# brc333ui-v2 – local install of the next UI module

Status: **staged locally** – the project is currently running on
`brc333ui-v2.js`, the next version of the project's UI module, shipped as
a local file (`<script src="brc333ui-v2.js"></script>`) before the
on-chain `UI` sat is reinscribed to carry this body.

This doc collects the open authoring questions for the actual reinscription
of the UI sat to match the locally-installed v2.

## What ships in v2

A coherent set of meta-layer-context UI helpers, layered on top of (and
compatible with) the canonical UI module surface (`window.UI`).

| Helper | Purpose |
|---|---|
| `BRC333UI.classify({ contentType, url, bodyText })` | Precedence ladder image → html → json → markdown → text, with markdown content-sniffing for `text/plain` bodies (ordinals.com's default). |
| `BRC333UI.renderInto({ container, kind, mime, contentUrl, contentText })` | Renders any medium into a DOM container with consistent dark-theme styling. |
| `BRC333UI.fetchAndRender({ metaUrl, contentUrl, container })` | One-shot helper that fetches, classifies, and renders in a single call. |
| `BRC333UI.parseMarkdown(src)` | Dependency-free GFM-flavored parser (headings, paragraphs, lists, blockquotes, fenced code, GFM tables, hr, inline code, bold/italic/strike, links, images, ordinals.com/.net autolinks, hard breaks). Input is escaped before any inline rule; output never leaks raw HTML. |
| `BRC333UI.fetchJson(url)` / `BRC333UI.fetchText(url)` | `fetch` with a 15-min `localStorage` cache, in-flight deduplication, and TTL-bypass on miss-then-revalidate. |
| `BRC333UI.invalidate(url)` / `BRC333UI.invalidateAll()` | Manually drop cache entries (useful for "force refresh" buttons). |
| `BRC333UI.formatSatNumber(sat)` | `<a href="https://ordinals.com/sat/<n>">#<n></a>` – uniform sat-reference renderer for the whole meta-layer. |
| `BRC333UI.linkToInscription(id, label?, opts?)` | Always-correct inscription anchor (http/https only). |
| `BRC333UI.truncateInscriptionId(id)` | `abc123…i0`-style display. |
| `BRC333UI.formatProvenance(meta, id?)` | Provenance bar (block / sat / date / owner / content type / length) as a DOM node. |
| `BRC333UI.loadPreview(id, opts?)` | Programmatically open the preview overlay. |
| `BRC333UI.closePreview()` | Close the overlay (also fires on Esc and click-outside). |
| `BRC333UI.bindInscriptionPreview(rootEl?, opts?)` | One-call install of the dwell + travel-cancel + slow-fade hover behavior on every `ordinals.com/inscription/<id>` anchor under `rootEl`. Configurable via `opts.dwellMs` (360), `opts.travelPx` (60), `opts.fadeMs` (720). |

Canonical UI shims remain exposed at the same `window.UI` namespace, so
pages that swap this file in for the on-chain UI module keep working
without rewiring. The shims are deliberately minimal – pages that need the
full UX should import the on-chain module alongside this one for
stylistic reasons.

## Why this file (and not a one-off helper)

The bit at the start (`brc333-inscription-renderer.js`) was a perfectly
good single-responsibility helper, but as a one-off script it can't be
reused by other satplications without them knowing to look for it. The
right move is to roll the helper into the next version of the existing
`UI` module, ship that v2 locally so the project can exercise every
helper without waiting for a reinscription, and let `brc333ui-v2.js`
demonstrate the "a module is just a sat you can reinscribe" pattern on
itself.

Net effects:

1. Every satplication that imports `UI` gets the renderer, cache layer,
   and uniform helpers for free on the next reinscription.
2. The local file is the *exact* body that goes into the new UI sat
   payload, minus the satellite-specific config (no need to edit it
   manually when reinscribing – just lift the file and inscribe).
3. Pages can be developed against `window.BRC333UI` now, switching to
   the chain version when it lands, with no API churn.

## Open questions for the reinscription authoring pass

1. **Namespace shape** – keep `window.UI` / `window.BRC333UI` dual-binding,
   or move fully to `window.BRC333UI`? Recommend dual-bind for backward
   compatibility; mark `window.UI` as the canonical name in docs.
2. **Auto-binding hover previews** – should `bindInscriptionPreview`
   attach automatically on `loadStyles()` / a `BRC333UI.init(rootEl)`
   call, or stay opt-in? Recommend opt-in via
   `BRC333UI.init(document.body)` so consumers control where the
   dwell-cancel logic applies (e.g., disable on the sat-graph view).
3. **Markdown parser** – keep the inlined dependency-free parser, or
   pull `marked` / `markdown-it`? Recommend inlined for size and
   auditability; matches the rest of the project's zero-build,
   single-file-sat philosophy.
4. **Cache TTL default** – current is 15 min. Should it be config-driven
   (`window.brc333uiCacheTtlMs` or a config-sat field)? Recommend
   config-driven with a 15-min default.
5. **Version bump** – the UI module should bump its declared
   `schemaVersion` (e.g., `2`) and document the new exports in its own
   config-sat, so other satplications can opt in.

## Once the UI module is reinscribed

The reinscription itself is the deliverable. The satplication loader
resolves `source.src` (the sat number, e.g. `1055369955956989`) to the
**latest** inscription on that sat via
`getInscriptionsForSat(sat, last=true, backup)` in `logic.htm`. So
**no edits to `config-sat.json` are required** for the new version to
take effect – the sat already points to its current inscription, and
the loader follows it automatically on every page load. The `backup`
field stays as a fallback for the case when the sat has zero
discoverable inscriptions; it does not need to be updated for a normal
reinscription either.

This is the whole point of the "a module is just a sat you can
reinscribe" mechanic – the `src` is a sat, not a specific inscription,
so consumers don't have to be told when the body changes.

After the reinscription:

- **Nothing in `config-sat.json`** – the sat field already resolves
  to its latest inscription; only the `backup` field would ever want
  touching, and only if you want a different fallback path.
- **Nothing in `logic.htm`** – the new API is available under the same
  `BRC333UI` namespace.
- Replace `<script src="brc333ui-v2.js"></script>` with a chain import
  (keep the local file as a fallback for `--localFiles` development).
- Delete this doc and the standalone `brc333-inscription-renderer.js`,
  flip the "v2 UI installed locally" milestone to completed.