@unitninety/site-kit 0.0.0-stage → 1.6.1

package/src/bridge/preview.ts

@@ -0,0 +1,179 @@
+import type { PreviewInstruction } from './protocol'
+
+/** A path inside an attribute selector: the two characters a selector string can be broken by. */
+const q = (path: string) => path.replace(/["\\]/g, '\\$&')
+
+/** The element a preview addresses: the block or the field marked with that path. */
+const nodeAt = (doc: Document, path: string): HTMLElement | null =>
+  doc.querySelector<HTMLElement>(`[data-u90-block="${q(path)}"], [data-u90-field="${q(path)}"]`)
+
+/**
+ * The element holding the siblings at `path`'s level, found through any one of them rather than
+ * through a marker of its own: `page:4f2/blocks/b3`'s container is the parent of whatever matches
+ * `page:4f2/blocks/` directly. A block nested inside one of those carries the same prefix, so a match
+ * with a further `/` after it is skipped. A zone with no blocks in it yet has nothing to find, so an
+ * append into an empty zone is a no-op and the refresh shows it instead.
+ */
+const containerFor = (doc: Document, path: string): HTMLElement | null => {
+  const cut = path.lastIndexOf('/')
+  if (cut < 0) return null
+  const prefix = path.slice(0, cut + 1)
+  for (const el of doc.querySelectorAll<HTMLElement>(`[data-u90-block^="${q(prefix)}"]`)) {
+    const own = el.getAttribute('data-u90-block') ?? ''
+    // A direct sibling only: a block nested inside one of these also matches the prefix.
+    if (!own.slice(prefix.length).includes('/')) return el.parentElement
+  }
+  return null
+}
+
+/** The first element of a fragment of markup, or null if it holds none. */
+const parse = (doc: Document, html: string): Element | null => {
+  const template = doc.createElement('template')
+  template.innerHTML = html
+  return template.content.firstElementChild
+}
+
+/** Puts the page back as it was before one preview. */
+export type Undo = () => void
+
+/**
+ * Applies one DOM-shaped instruction to markup the page has already rendered, so a Canvas edit
+ * shows before the server re-renders it, and returns how to take it back (null if it did nothing).
+ *
+ * **Why every preview can be undone.** The page is React's, and React writes only what changed in
+ * *its* model of the page. A preview changes the document and not that model, so left in place it
+ * leaves the two disagreeing, and the refresh that follows the save is no longer authoritative: a
+ * node we detached makes React throw when it removes it, a refused move is never put back, and a
+ * moved node can be left where neither the preview nor the server put it. So the frame undoes every
+ * preview, newest first, immediately before it asks for the refresh (`createBridge`'s journal), and
+ * React then reconciles a document that is exactly its own model. Two rules follow: a preview never
+ * detaches or replaces a node React owns without keeping it to put back (a remove hides, it does not
+ * detach; a text edit keeps the original child nodes, because React updates *those* nodes), and an
+ * undo reads state captured *before* the preview mutated.
+ *
+ * Every branch is a no-op when what it addresses is missing. That is the contract, not defensive
+ * coding: `u90:refresh` is what makes the frame correct, and a preview only makes it correct
+ * sooner, so a preview that cannot be applied costs the wait it was trying to save and nothing
+ * else.
+ *
+ * `html` arrives over `postMessage` from the platform origin, which `createBridge`'s `onMessage`
+ * has already checked — the same trust as every other command the Canvas sends.
+ */
+export const applyPreview = (doc: Document, instruction: PreviewInstruction): Undo | null => {
+  if (instruction.kind === 'insert') {
+    const before = instruction.before ? nodeAt(doc, instruction.before) : null
+    // A `before` that was named but is not here means this preview cannot be placed correctly.
+    // Showing it in the wrong position is worse than not showing it: the refresh is close behind.
+    if (instruction.before && !before) return null
+    const parent = before?.parentElement ?? containerFor(doc, instruction.path)
+    const node = parse(doc, instruction.html)
+    if (!parent || !node) return null
+    parent.insertBefore(node, before)
+    return () => node.remove()
+  }
+
+  if (instruction.kind === 'link-label') {
+    // A responsive header can render the same button twice. Update every label, but keep its
+    // anchor and decorations intact and never overwrite a label the person is still typing in.
+    const originals: { el: HTMLElement; children: ChildNode[] }[] = []
+    for (const el of doc.querySelectorAll<HTMLElement>(`[data-u90-field="${q(instruction.path)}"][data-u90-edit="link-label"]`)) {
+      // Capture every copy even when it is actively edited. A later inspector preview may touch
+      // that copy too; previews coalesce by path, so the first undo must cover it from the start.
+      originals.push({ el, children: [...el.childNodes] })
+      if (el.hasAttribute('contenteditable') || el.hasAttribute('data-u90-editing')) continue
+      el.textContent = instruction.value
+    }
+    return originals.length ? () => originals.forEach(({ el, children }) => el.replaceChildren(...children)) : null
+  }
+
+  const el = nodeAt(doc, instruction.path)
+  if (!el) return null
+
+  if (instruction.kind === 'move') {
+    const before = instruction.before ? nodeAt(doc, instruction.before) : null
+    // As for `insert`: a named but missing `before` is a no-op, not an append.
+    if (instruction.before && !before) return null
+    const parent = before?.parentElement ?? el.parentElement
+    if (!parent) return null
+    const home = el.parentNode
+    const next = el.nextSibling
+    parent.insertBefore(el, before)
+    return () => {
+      // The tree this node belonged to may have been replaced by something other than our own
+      // refresh: a site calling router.push, or fast refresh in dev. Re-attaching it then would
+      // graft a node from the old tree into the live document, and nothing would ever remove it.
+      if (!el.isConnected) return
+      // Restored newest first, so `next` is back where it was; if it is not a child of `home` the
+      // journal is stale (a frame that reloaded), and appending is the least wrong place.
+      home?.insertBefore(el, next && next.parentNode === home ? next : null)
+    }
+  }
+  if (instruction.kind === 'remove') {
+    // Hidden, not detached: React still owns this node, and will remove it itself when the server's
+    // render no longer lists it. Detaching it made that removal throw and took the page down.
+    const style = (el as HTMLElement).style
+    if (!style) return null
+    // The whole attribute is kept, not just `display`, so the undo leaves the markup byte for byte as React wrote it.
+    const written = el.getAttribute('style')
+    style.display = 'none'
+    // The attribute carries what to put back, so the frame's last-resort sweep can restore it too
+    // without the journal (`createBridge`'s `undoPreviews`): the renderer writes `display:contents`
+    // on every block wrapper, and losing that would give the block a layout box.
+    el.setAttribute('data-u90-removed', JSON.stringify(written))
+    return () => {
+      if (written === null) el.removeAttribute('style')
+      else el.setAttribute('style', written)
+      el.removeAttribute('data-u90-removed')
+    }
+  }
+  if (instruction.kind === 'text' || instruction.kind === 'rich') {
+    // The user's own keystrokes are the newest truth in a field they are typing in; an echo of an
+    // older value would move their caret to the end of it. v1 marks the field it is editing with
+    // `contenteditable` (`createBridge.ts`'s `beginEditing`); `data-u90-editing` is what legacy
+    // marked it with, and is kept so a legacy frame is covered too.
+    if (el.hasAttribute('data-u90-editing') || el.hasAttribute('contenteditable')) return null
+    // Only a field whose stored value IS its rendered text. A string set does not say that: a choice
+    // stores its value and renders its label, a date stores an ISO string and renders a formatted one,
+    // and writing the stored string into either shows something the page never will. `editable()`
+    // sets `data-u90-edit="text"` only for a value that carries text, so that attribute is the test.
+    if (el.getAttribute('data-u90-edit') !== instruction.kind) return null
+    // The child nodes themselves are kept, not their text: React holds those very nodes and updates
+    // them, so an undo that made new ones would leave React writing to nodes no longer on the page.
+    const children = [...el.childNodes]
+    if (instruction.kind === 'text') el.textContent = instruction.value
+    else el.replaceChildren(...instruction.paragraphs.map((text) => {
+      const paragraph = doc.createElement('p')
+      paragraph.textContent = text
+      return paragraph
+    }))
+    return () => el.replaceChildren(...children)
+  }
+  if (instruction.kind === 'media') {
+    // `tagName`, not `instanceof HTMLImageElement`: the tests build a bare Document with no
+    // defaultView, so there is no window to take the constructor from.
+    const img = el.tagName === 'IMG' ? (el as HTMLImageElement) : el.querySelector('img')
+    if (!img) return null
+    const src = img.getAttribute('src')
+    const srcset = img.getAttribute('srcset')
+    // A srcset left in place outranks the src and would keep showing the old image.
+    img.removeAttribute('srcset')
+    img.setAttribute('src', instruction.src)
+    return () => {
+      for (const [name, value] of [['src', src], ['srcset', srcset]] as const) {
+        if (value === null) img.removeAttribute(name)
+        else img.setAttribute(name, value)
+      }
+    }
+  }
+  if (instruction.kind === 'replace') {
+    const node = parse(doc, instruction.html)
+    if (!node) return null
+    el.replaceWith(node)
+    return () => {
+      // `node` is gone if a later undo (an insert's) already removed it; then `el` has nowhere to go
+      // and the page is as it was before either.
+      if (node.parentNode) node.replaceWith(el)
+    }
+  }
+  return null
+}

package/src/bridge/protocol.ts

@@ -0,0 +1,271 @@
+import { isDocumentId } from '../elements/ids'
+import { LinkTo } from '../elements/leaves/link'
+
+/**
+ * Bridge v4: the message protocol between a server-rendered draft page (the site) and the
+ * Canvas (the platform). See `docs/content-contracts/bridge-v4.md` and spec §6.
+ *
+ * The model: the page is server-rendered from draft content. Typing edits the DOM in place and
+ * is sent as `edit`; the Canvas saves; after any structural save the Canvas sends `refresh` and
+ * the site calls `router.refresh()`. No content push, no client-side merge, no `fields` message.
+ */
+export const BRIDGE_VERSION = 4 as const
+
+/** The `u90:caret`'s `block`: the nearest block element the caret sits in, if any. */
+type CaretBlock = 'paragraph' | 'h2' | 'h3' | 'h4' | 'list' | 'quote'
+const CARET_BLOCKS = new Set<CaretBlock>(['paragraph', 'h2', 'h3', 'h4', 'list', 'quote'])
+
+/** A `{ top, left, width, height }` rect shape, used both for the caret's own rect and `field`. */
+const isRect = (v: unknown): v is { top: number; left: number; width: number; height: number } =>
+  Boolean(
+    v &&
+      typeof v === 'object' &&
+      typeof (v as Record<string, unknown>).top === 'number' &&
+      typeof (v as Record<string, unknown>).left === 'number' &&
+      typeof (v as Record<string, unknown>).width === 'number' &&
+      typeof (v as Record<string, unknown>).height === 'number',
+  )
+
+/**
+ * A `to` the bridge accepts from the Canvas: `LinkTo`-shaped, and — since the Canvas only ever
+ * sends document ids, never a seed's key, per this plan's global constraint that a stored link
+ * target uses document ids — a page or entry target's id must itself be a document id.
+ * `LinkTo`'s own `Id` is wider (a positive integer or any non-empty string) because it is shared
+ * with legacy and seed data; the bridge has no reason to accept either here.
+ */
+const isBridgeLinkTarget = (to: unknown): to is LinkTo => {
+  const parsed = LinkTo.safeParse(to)
+  if (!parsed.success) return false
+  const value = parsed.data
+  if ('page' in value) return isDocumentId(value.page)
+  if ('entry' in value) return isDocumentId(value.entry.id)
+  return true
+}
+
+/**
+ * A DOM-shaped instruction the Canvas asks a frame to apply to markup it has already rendered, so
+ * an edit shows before the server has re-rendered the page.
+ *
+ * Deliberately presentational. It carries no fields, no sections and no content tree, which is what
+ * keeps it from growing back into the client-side merge v4 removed: there is nothing here to merge.
+ * Every preview is transient. React owns draft block order and settles it from the next server render.
+ * For other previews the frame records an undo and takes them back, newest
+ * first, just before it asks for the `u90:refresh` that follows the save (`createBridge`'s journal), so
+ * the server's render lands on a page that is exactly as React last rendered it. Being wrong costs a
+ * visible settle, never wrong content.
+ *
+ * `before` names the sibling to insert in front of; `null` appends.
+ */
+export type PreviewInstruction =
+  | { kind: 'move'; path: string; before: string | null }
+  | { kind: 'remove'; path: string }
+  | { kind: 'media'; path: string; src: string }
+  | { kind: 'text'; path: string; value: string }
+  /** The words inside a link; never replace its decorations or destination. */
+  | { kind: 'link-label'; path: string; value: string }
+  /** Plain paragraph edits from the inspector; formatted/resolved trees still come from the server. */
+  | { kind: 'rich'; path: string; paragraphs: string[] }
+  | { kind: 'insert'; path: string; before: string | null; html: string }
+  | { kind: 'replace'; path: string; html: string }
+  /**
+   * Asks the frame to fetch the rendered `block` from its own site's fragment page and put it where
+   * `path` is marked. The frame does the fetching because only it is same-origin with the site: the
+   * Canvas could not read that response, and the frame already carries the draft cookie. It is not
+   * applied by `applyPreview`; `createBridge` handles it.
+   */
+  | { kind: 'fragment'; path: string; block: string }
+
+const PREVIEW_KINDS = new Set(['move', 'remove', 'media', 'text', 'link-label', 'rich', 'insert', 'replace', 'fragment'])
+const isBefore = (v: unknown): boolean => v === null || typeof v === 'string'
+
+/** Whether a `u90:preview`'s instruction has a known kind and a well-formed payload. */
+const isPreviewInstruction = (value: unknown): value is PreviewInstruction => {
+  if (!(value && typeof value === 'object')) return false
+  const r = value as Record<string, unknown>
+  if (typeof r.kind !== 'string' || !PREVIEW_KINDS.has(r.kind) || typeof r.path !== 'string') return false
+  if (r.kind === 'media') return typeof r.src === 'string'
+  if (r.kind === 'text' || r.kind === 'link-label') return typeof r.value === 'string'
+  if (r.kind === 'rich') return Array.isArray(r.paragraphs) && r.paragraphs.every((paragraph) => typeof paragraph === 'string')
+  if (r.kind === 'replace') return typeof r.html === 'string'
+  if (r.kind === 'fragment') return typeof r.block === 'string'
+  if (r.kind === 'insert') return typeof r.html === 'string' && isBefore(r.before)
+  if (r.kind === 'move') return isBefore(r.before)
+  return true
+}
+
+/**
+ * Which page of which screen a message belongs to: the screen's frame key, the language it was
+ * loaded in (null for the original) and the count of its address changes. The Canvas sends one on
+ * `u90:hello` only when it shows languages, and the site then puts it on every message it sends, so
+ * the Canvas can drop what a screen's earlier page said. A message without one is a site on a kit
+ * before 1.3.0, or a Canvas that asked for none.
+ */
+export type BridgeStamp = { frame: string; locale: string | null; revision: number }
+
+/** Every message's own fields: the version, and a stamp, which validates as the three together or none of them. */
+type Base = { version: 4; frame?: string; locale?: string | null; revision?: number }
+
+/** Whether a message carries no stamp, a well formed one, or something else in its place. */
+const stampState = (record: Record<string, unknown>): 'none' | 'stamped' | 'malformed' => {
+  const { frame, locale, revision } = record
+  if (frame === undefined && locale === undefined && revision === undefined) return 'none'
+  const wellFormed =
+    typeof frame === 'string' &&
+    frame !== '' &&
+    (locale === null || typeof locale === 'string') &&
+    typeof revision === 'number' &&
+    Number.isSafeInteger(revision) &&
+    revision >= 0
+  return wellFormed ? 'stamped' : 'malformed'
+}
+
+/** Site → Canvas. */
+export type SiteMessage = Base &
+  (
+    | { type: 'u90:ready'; path: string }
+    | { type: 'u90:path'; path: string }
+    | { type: 'u90:select'; path: string | null }
+    | { type: 'u90:hover'; path: string | null }
+    | { type: 'u90:edit'; path: string; kind: 'text' | 'rich' | 'link-label'; value: unknown }
+    | {
+        type: 'u90:caret'
+        path: string
+        top: number
+        left: number
+        width: number
+        height: number
+        marks?: string[]
+        block?: CaretBlock
+        field?: { top: number; left: number; width: number; height: number }
+      }
+    | { type: 'u90:flushed'; requestId: string }
+    | { type: 'u90:height'; height: number }
+    | { type: 'u90:scrolled'; top: number; max: number }
+    | { type: 'u90:navigate'; path: string }
+    | { type: 'u90:zoom'; deltaY: number; x: number; y: number }
+    | { type: 'u90:wheel'; deltaX: number; deltaY: number }
+    | { type: 'u90:grab'; screenX: number; screenY: number }
+    | { type: 'u90:drag'; screenX: number; screenY: number }
+    | { type: 'u90:drop' }
+    | { type: 'u90:key'; code: string; down: boolean }
+    /** Draft, right-to-left pages only: how far the page overflows the screen, and the fields that reach past its edges (spec §8, 09-11 §5). */
+    | { type: 'u90:direction'; dir: 'rtl'; overflow: number; offenders: string[] }
+  )
+
+/** Canvas → Site. */
+export type CanvasMessage = Base &
+  (
+    | { type: 'u90:refresh' }
+    | { type: 'u90:select'; path: string | null }
+    | { type: 'u90:flush'; requestId: string }
+    | { type: 'u90:format'; action: string; url?: string; to?: LinkTo; newTab?: boolean }
+    | { type: 'u90:scroll'; to: 'top' | 'fraction'; fraction?: number }
+    | { type: 'u90:viewport'; height: number | null }
+    | { type: 'u90:navigation'; enabled: boolean }
+    /**
+     * Whether this screen is the one the Canvas has selected.
+     *
+     * Restores the single thing v3's `isActive` was load-bearing for and v4's first table left
+     * out. The wheel is the case: an active screen's page scrolls, an inactive one's wheel pans
+     * the Canvas instead, and only the site can stop its own page scrolling — `preventDefault`
+     * inside the frame is not something the Canvas can do for it. Without this message the site
+     * cannot tell the two apart, so it forwarded every wheel AND let the page scroll, and one
+     * gesture moved both.
+     *
+     * Sent to every frame whenever the selection changes, so each knows its own state and no
+     * frame is told about the others. A site that does not know it ignores it, as it does any
+     * message it does not parse — such a site keeps the behaviour it has today.
+     */
+    | { type: 'u90:active'; active: boolean }
+    /**
+     * Asks the page to say it is ready again: answered with `u90:ready` and the path it is on now.
+     * The Canvas sends it when it registers a frame whose page had already loaded, since a
+     * `u90:ready` sent before the Canvas was listening is lost. A site that does not know it ignores
+     * it, as it does any message it does not parse.
+     */
+    | { type: 'u90:hello' }
+    | { type: 'u90:preview'; instruction: PreviewInstruction }
+  )
+
+const CANVAS_TYPES = new Set([
+  'u90:hello',
+  'u90:preview',
+  'u90:refresh',
+  'u90:select',
+  'u90:flush',
+  'u90:format',
+  'u90:scroll',
+  'u90:viewport',
+  'u90:navigation',
+  'u90:active',
+])
+
+/** Whether a `u90:format` payload's optional `to`/`newTab` are each either absent or well formed. */
+const isValidFormat = (data: Record<string, unknown>): boolean => {
+  if ('to' in data && data.to !== undefined && !isBridgeLinkTarget(data.to)) return false
+  if ('newTab' in data && data.newTab !== undefined && typeof data.newTab !== 'boolean') return false
+  return true
+}
+
+/** A message from the Canvas, accepted only at the current version and a known type. */
+export const parseCanvasMessage = (data: unknown): CanvasMessage | null => {
+  if (!(data && typeof data === 'object' && (data as { version?: unknown }).version === 4)) return null
+  const record = data as Record<string, unknown>
+  if (!CANVAS_TYPES.has(String(record.type))) return null
+  if (stampState(record) === 'malformed') return null
+  if (record.type === 'u90:format' && !isValidFormat(record)) return null
+  if (record.type === 'u90:preview' && !isPreviewInstruction(record.instruction)) return null
+  return data as CanvasMessage
+}
+
+const SITE_TYPES = new Set([
+  'u90:ready',
+  'u90:path',
+  'u90:select',
+  'u90:hover',
+  'u90:edit',
+  'u90:caret',
+  'u90:flushed',
+  'u90:height',
+  'u90:scrolled',
+  'u90:navigate',
+  'u90:zoom',
+  'u90:wheel',
+  'u90:grab',
+  'u90:drag',
+  'u90:drop',
+  'u90:key',
+  'u90:direction',
+])
+
+/** Whether a `u90:caret` payload's optional `marks`/`block`/`field` are each either absent or well formed. */
+const isValidCaret = (data: Record<string, unknown>): boolean => {
+  if ('marks' in data && data.marks !== undefined && !(Array.isArray(data.marks) && data.marks.every((m) => typeof m === 'string'))) return false
+  if ('block' in data && data.block !== undefined && !CARET_BLOCKS.has(data.block as CaretBlock)) return false
+  if ('field' in data && data.field !== undefined && !isRect(data.field)) return false
+  return true
+}
+
+/** The most fields a right-to-left check names, and the longest field path it may carry. */
+export const MAX_OFFENDERS = 20
+export const MAX_OFFENDER_LENGTH = 512
+/** Whether a `u90:direction` is a right-to-left page's finite, non-negative overflow and at most 20 field paths of at most 512 characters. */
+const isValidDirection = (data: Record<string, unknown>): boolean =>
+  data.dir === 'rtl' &&
+  typeof data.overflow === 'number' &&
+  Number.isFinite(data.overflow) &&
+  data.overflow >= 0 &&
+  Array.isArray(data.offenders) &&
+  data.offenders.length <= MAX_OFFENDERS &&
+  data.offenders.every((o) => typeof o === 'string' && o.length <= MAX_OFFENDER_LENGTH)
+
+/** A message from a site frame, accepted only at the current version and a known type. */
+export const isSiteMessage = (data: unknown): data is SiteMessage => {
+  if (!(data && typeof data === 'object' && (data as { version?: unknown }).version === 4)) return false
+  const record = data as Record<string, unknown>
+  if (!SITE_TYPES.has(String(record.type))) return false
+  if (stampState(record) === 'malformed') return false
+  if (record.type === 'u90:caret' && !isValidCaret(record)) return false
+  if (record.type === 'u90:direction' && !isValidDirection(record)) return false
+  return true
+}

package/src/bridge/registry.ts

@@ -0,0 +1,27 @@
+import type { Bridge } from './createBridge'
+
+/**
+ * The one shared, module-level handle onto the live bridge instance and its reveal listeners.
+ *
+ * No React, no Next — this file exists purely so `useReveal` (in `hooks.tsx`) can register a
+ * listener without statically importing `./client` or `./createBridge`. Those two pull in
+ * `next/navigation` and the whole DOM-level bridge respectively; `EditingProvider` already keeps
+ * that chunk out of a production bundle by fetching it with `lazy(() => import('./client'))`
+ * (see `hooks.tsx`), and only when `editing`. A site component that calls `useReveal` (Task 8's
+ * header, for one) sits beside that provider in the same client bundle, so if `useReveal` itself
+ * imported `./client` or `./createBridge` eagerly, using the hook at all would pull the bridge
+ * chunk back in on every render, draft or not — this indirection is what keeps `useReveal` cheap.
+ *
+ * `current` is set by `createBridge(...).start()` and cleared by `.stop()`. `reveals` is the
+ * live set `createBridge`'s `u90:select` handler walks — `useReveal` adds and removes its own
+ * `{ prefix, fn }` entry directly, so revealing works whether or not a bridge is mounted yet.
+ */
+export const registry: {
+  current: Bridge | null
+  reveals: Set<{ prefix: string; fn: () => void }>
+  blockOrders: Set<{ document: Document; beforeRefresh(): void; needsReload(): boolean; move(path: string, before: string | null): boolean }>
+} = {
+  current: null,
+  reveals: new Set(),
+  blockOrders: new Set(),
+}

package/src/bridge/styles.ts

@@ -0,0 +1,137 @@
+import { EDITABLE_LEAF_SELECTOR, MEDIA, MEDIA_SELECTOR } from './caret'
+
+/**
+ * The editing affordances injected into a draft page: pointer/I-beam cursors, hover outlines,
+ * the selected-element outline, the navigation-mode link/button treatment, and the "no sections
+ * yet" placeholder.
+ *
+ * Extracted from `legacy/bridge.tsx`'s `EditingStyles` (the `<style>` it rendered, from around
+ * line 1779 of that file). That component took `selected` and `navigation` as React props and
+ * rebuilt the stylesheet string on every render; `createBridge` instead appends this once, as a
+ * static stylesheet, and toggles attributes on the elements themselves:
+ *
+ *  - the dynamic `[${FIELD_ATTR}="${escaped}"]` rule (the selected element) and the digit-keyed
+ *    `[${SECTION_ATTR}="${sectionKey}"]` rule (a selected section) both collapse into one pair of
+ *    static `[data-u90-selected]` rules — `createBridge`'s `markSelected` sets that attribute on
+ *    the selected element (field or block) directly, so the stylesheet no longer needs to know
+ *    which path is selected. The heavier `3px solid` / `8px`-offset treatment legacy gave a
+ *    selected *section* survives as the more specific `[data-u90-block][data-u90-selected]` rule,
+ *    below the plain `2px` / `5px` one every other selected element gets.
+ *  - `[data-u90-hover]` is a highlight driven by attribute rather than by the `:hover`
+ *    pseudo-class — `createBridge`'s `onPointerOver`/`onPointerOut` set and clear it as the
+ *    pointer moves across `[data-u90-field]`/`[data-u90-block]` elements, which is also what
+ *    sends `u90:hover`. The plain mouse-hover affordance below (the dashed outline) is a
+ *    *separate*, unconditional `:hover` pseudo-class rule, exactly as legacy had it — the two
+ *    can be visually distinguished (solid highlight vs. dashed hover) because nothing requires
+ *    them to look the same.
+ *  - legacy's `navigation` prop — links and buttons either behave like plain links (navigation
+ *    on) or are outlined as selectable controls with an I-beam over their editable text
+ *    (navigation off) — cannot be reproduced by a *value* the way legacy's component took it,
+ *    since `EDITING_CSS` is a static string with no per-render prop to read. Both branches are
+ *    still here, keyed on `html[data-u90-navigation]` / `html:not([data-u90-navigation])`;
+ *    `createBridge`'s `u90:navigation` handler sets or removes that attribute on
+ *    `document.documentElement`, so the CSS switches branch exactly when legacy's component
+ *    would have re-rendered with a new `navigation` value. Off (`html:not([data-u90-navigation])`)
+ *    is the state with no `<html>` attribute at all, matching legacy's own `navigation = false`
+ *    default and its fallback for a site on an older kit that never sends the message.
+ *  - `[data-u90-rich]`/`[data-u90-section]` selectors become `[data-u90-edit="rich"]`/
+ *    `[data-u90-block]` throughout, matching the same rename in `caret.ts`.
+ *
+ * The "no sections yet" placeholder (`main:not(:has(*))`) is copied unchanged.
+ */
+export const EDITING_CSS = `
+[data-u90-field] { cursor: pointer; }
+[data-u90-field]:hover {
+  outline: 1px dashed #FF5D2E;
+  outline-offset: 4px;
+}
+
+/* a Single inside editable copy: one chip the caret skips, saved back as its {key} (R38) */
+[data-u90-field] [data-single-key] {
+  border-radius: 4px;
+  padding: 0 2px;
+  background: rgba(255, 93, 46, 0.12);
+}
+
+${MEDIA_SELECTOR} { cursor: pointer; }
+${MEDIA_SELECTOR}:hover {
+  outline: 2px dashed #FF5D2E;
+  outline-offset: -2px;
+}
+
+[data-u90-block]:hover {
+  outline: 2px dashed #FF5D2E;
+  outline-offset: 8px;
+}
+
+/* navigation on: links and buttons with no marker of their own behave like plain links */
+html[data-u90-navigation] a[href]:not([data-u90-field]),
+html[data-u90-navigation] button:not([data-u90-field]) {
+  cursor: pointer;
+}
+
+/* navigation off (default): the whole control is outlined, and an editable leaf takes an I-beam */
+html:not([data-u90-navigation]) a[href],
+html:not([data-u90-navigation]) button {
+  cursor: pointer;
+}
+html:not([data-u90-navigation]) a[href]:not(:has([data-u90-field])):hover,
+html:not([data-u90-navigation]) button:not(:has([data-u90-field])):hover {
+  outline: 1px dashed #FF5D2E;
+  outline-offset: 3px;
+}
+html:not([data-u90-navigation]) a[href]:has([data-u90-field]):hover {
+  outline: 1px dashed #FF5D2E;
+  outline-offset: 3px;
+}
+html:not([data-u90-navigation]) ${EDITABLE_LEAF_SELECTOR} {
+  cursor: text;
+}
+
+[data-u90-selected] {
+  outline: 2px solid #FF5D2E !important;
+  outline-offset: 5px;
+}
+[data-u90-selected]:is(${MEDIA}) {
+  outline: 3px solid #FF5D2E !important;
+  outline-offset: -3px;
+}
+[data-u90-block][data-u90-selected] {
+  outline: 3px solid #FF5D2E !important;
+  outline-offset: 8px;
+}
+
+[data-u90-hover] {
+  outline: 1px dashed #FF5D2E;
+  outline-offset: 4px;
+}
+
+[data-u90-field][data-u90-editing] {
+  cursor: text;
+  outline: 2px solid #FF5D2E !important;
+  outline-offset: 5px;
+}
+[data-u90-field][data-u90-editing]:focus,
+[data-u90-field][data-u90-editing]:focus-visible {
+  outline: 2px solid #FF5D2E !important;
+}
+
+main:not(:has(*)) {
+  min-height: 50vh;
+  display: grid;
+  place-items: center;
+  padding: 48px 24px;
+  box-sizing: border-box;
+}
+main:not(:has(*))::after {
+  content: 'This page has no sections yet. Add one from the Page panel.';
+  display: block;
+  max-width: 32ch;
+  padding: 28px 32px;
+  border: 1px dashed #FF5D2E;
+  font: 500 14px/1.5 ui-sans-serif, system-ui, sans-serif;
+  letter-spacing: 0.01em;
+  text-align: center;
+  color: #FF5D2E;
+}
+`

package/src/components/DateText.tsx

@@ -0,0 +1,9 @@
+import { createElement, type ElementType } from 'react'
+import type { DateRead } from '../elements'
+import { draftAttrs } from './draft'
+export function DateText<T extends ElementType = 'time'>({ value, as, locale, format, ...rest }: { value: DateRead | null | undefined; as?: T; locale?: string; format?: Intl.DateTimeFormatOptions } & Record<string, unknown>) {
+  if (!value) return null
+  const text = new Intl.DateTimeFormat(locale, { timeZone: 'UTC', ...(format ?? { dateStyle: 'medium' }) }).format(new Date(`${value.iso}T00:00:00Z`))
+  const attrs = draftAttrs(value)
+  return as ? createElement(as, { ...rest, ...attrs }, text) : value.$path ? createElement('span', attrs, text) : text
+}

package/src/components/File.tsx

@@ -0,0 +1,9 @@
+import { createElement, Fragment } from 'react'
+import type { FileRead } from '../elements'
+import { draftAttrs } from './draft'
+export function File({ value, ...rest }: { value: FileRead | null | undefined } & Record<string, unknown>) {
+  if (!value || !value.asset) return null
+  return createElement(Fragment, null,
+    createElement('a', { ...rest, ...draftAttrs(value), href: value.asset.url, ...(value.downloadName ? { download: value.downloadName } : { download: true }) }, value.label || value.asset.filename),
+    value.description ? createElement('span', { className: 'u90-file-description' }, value.description) : null)
+}

package/src/components/Image.tsx

@@ -0,0 +1,30 @@
+import NextImage, { getImageProps } from 'next/image'
+import { createElement } from 'react'
+import type { ImageRead } from '../elements'
+import { draftAttrs } from './draft'
+import { imageProps, isGrantPath, pictureSources, type ImageProps } from './imageProps'
+/**
+ * One declared variant's `<source>`, built with `next/image`'s own `getImageProps` so its `srcSet`
+ * carries the candidates a plain `<Image>` would. `getImageProps` refuses `fill` together with a
+ * `width` or `height` — it throws outside production, so under `next dev`, which the Canvas preview
+ * runs — so a fill image's sources take no size of their own.
+ */
+export const sourceProps = (props: ImageProps, s: ReturnType<typeof pictureSources>[number]) => {
+  const size = props.fill ? {} : { width: s.width ?? props.width, height: s.height ?? props.height }
+  // The variant's own URL decides, in both directions: a grant path is never optimised, whatever the main image is.
+  const unoptimized = isGrantPath(s.srcSet)
+  const { props: p } = getImageProps({ ...props, src: s.srcSet, ...size, unoptimized, alt: props.alt })
+  // An unoptimised image has no generated srcSet, so the raw path is the candidate.
+  return { key: s.name, media: s.media, srcSet: p.srcSet ?? p.src, sizes: p.sizes }
+}
+export function Image({ value, sizes, fill, priority, className, figureClassName, variants }: { value: ImageRead | null | undefined; sizes?: string; fill?: boolean; priority?: boolean; className?: string; figureClassName?: string; variants?: Record<string, { media: string }> }) {
+  if (!value) return null
+  const attrs = draftAttrs(value)
+  const props = imageProps(value, { sizes, fill, priority })
+  if (!props) return value.$path ? createElement('div', { ...attrs, className, 'data-u90-missing': 'image' }, 'Image missing') : null
+  const sources = pictureSources(value, variants)
+  const img = sources.length
+    ? createElement('picture', null, ...sources.map((s) => createElement('source', sourceProps(props, s))), createElement(NextImage, { ...props, className, ...attrs }))
+    : createElement(NextImage, { ...props, className, ...attrs })
+  return value.caption ? createElement('figure', { className: figureClassName }, img, createElement('figcaption', null, value.caption)) : img
+}