@uiresponse/renderer-react 0.1.0

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@uiresponse/renderer-react",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "OBL's first-party React renderer. Consumes OBL page JSON directly; no Lang step, nothing lossy.",
+  "license": "MIT",
+  "author": "Orthen",
+  "homepage": "https://github.com/dnljl/uir/tree/main/uir/renderer/web#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dnljl/uir.git",
+    "directory": "renderer/web"
+  },
+  "bugs": {
+    "url": "https://github.com/dnljl/uir/issues"
+  },
+  "keywords": ["uir", "generative-ui", "orthen", "react", "renderer"],
+  "sideEffects": ["*.css"],
+  "main": "./dist/uir-renderer-web.js",
+  "module": "./dist/uir-renderer-web.js",
+  "style": "./dist/uir-renderer-web.css",
+  "exports": {
+    ".": {
+      "import": "./dist/uir-renderer-web.js",
+      "default": "./dist/uir-renderer-web.js"
+    },
+    "./styles.css": "./dist/uir-renderer-web.css",
+    "./src": "./src/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "ATTRIBUTION.md"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "prepack": "npm run build",
+    "test": "node tests.mjs",
+    "preview:dev": "vite --config preview/vite.config.js",
+    "preview:build": "vite build --config preview/vite.config.js"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "dependencies": {
+    "@openuidev/react-ui": "^0.12.1"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.3.4",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "vite": "^6.0.0"
+  },
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/UIResponsePage.jsx

@@ -0,0 +1,576 @@
+/**
+ * <UIResponsePage> — OBL's first-party React renderer.
+ *
+ * Consumes an OBL page document DIRECTLY. There is no Lang step and nothing lossy: the block tree in
+ * the JSON is the component tree on the screen, and every semantic the document carries — `format`,
+ * `empty`, `emphasis`, `density`, `intent.priority`, `visible_when` — reaches a pixel (DECISIONS X4).
+ *
+ *   <UIResponsePage page={pageDoc} resolve={resolveFn} theme={tokens} />
+ *
+ * `resolve` is the ONE data surface. The renderer never sees a connector, a query, or a credential:
+ * it asks for `{page, dataset, params}` and receives `{rows}`. Principle 4, enforced by the props.
+ */
+import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { UIResponseContext } from "./blocks/context.js";
+import { usePageData, overlayParams, blockSettled } from "./core/store.js";
+import { visibility } from "./core/condition.js";
+import { resolveValue, collectDatasets } from "./core/value.js";
+import { formatValue } from "./core/format.js";
+import { hidesBlock } from "./core/empty.js";
+import { pageHeadlineIsInDocument } from "./core/record.js";
+import { defaultTheme, makeTheme, themeToCssVars } from "./theme/tokens.js";
+import { Skeleton, BlockError, ConfirmDialog, ValidationTick } from "./blocks/primitives.jsx";
+import { SectionBlock, CardBlock, TabsBlock } from "./blocks/containers.jsx";
+import { TableBlock, ListBlock, DetailBlock, TimelineBlock, CalendarBlock } from "./blocks/data.jsx";
+import { ChartBlock, MetricBlock, ProgressBlock, BadgeBlock, StageChecklistBlock } from "./blocks/viz.jsx";
+import { TextBlock, MediaBlock, InputBlock, ButtonBlock } from "./blocks/content.jsx";
+
+const LEAVES = {
+  table: TableBlock, list: ListBlock, detail: DetailBlock, timeline: TimelineBlock, calendar: CalendarBlock,
+  chart: ChartBlock, metric: MetricBlock, progress: ProgressBlock, badge: BadgeBlock,
+  stage_checklist: StageChecklistBlock,
+  text: TextBlock, media: MediaBlock, input: InputBlock, button: ButtonBlock,
+};
+const CONTAINERS = new Set(["section", "card", "tabs"]);
+
+/**
+ * Which blocks are TILES: self-contained objects placed on the host's canvas.
+ *
+ * The renderer used to draw a bounded paper sheet and lay blocks inside it — a page within a page.
+ * That reads as a document. It is not what a generated surface is. A generated answer is a handful of
+ * elements put ON the surface, and the surface belongs to the host: a workroom canvas, a chat
+ * thread, a home screen.
+ *
+ * So `metric`, `chart`, `table`, `list`, `detail`, `timeline`, `calendar`, `progress` and `media`
+ * each become a discrete rounded tile. `text`, `badge`, `stage_checklist`, `input` and `button` do
+ * not: prose, a status word, an ordered run of statuses, a field and a verb are elements, not
+ * objects, and boxing them would be chrome for chrome's sake.
+ */
+const TILES = new Set(["metric", "chart", "table", "list", "detail", "timeline", "calendar", "progress", "media"]);
+
+/** The skeleton shape a block wears while its datasets are in flight. */
+const SKELETON_VARIANT = { metric: "metric", progress: "value", badge: "value", text: "value", stage_checklist: "value" };
+
+const prefersReducedMotion = () =>
+  typeof window !== "undefined" && typeof window.matchMedia === "function"
+    ? window.matchMedia("(prefers-reduced-motion: reduce)").matches
+    : false;
+
+/** Leaves only. A page of one or two elements gets a label, not a masthead. */
+function countLeaves(blocks, n = 0) {
+  for (const b of blocks ?? []) {
+    n = CONTAINERS.has(b.type) ? countLeaves(b.children, n) : n + 1;
+  }
+  return n;
+}
+
+export function UIResponsePage({
+  page,
+  resolve,
+  theme: themeProp,
+  params: suppliedParams,
+  onOpenRecord,
+  onNotice,
+  confirm,
+  now,
+  concurrency = 2,
+  datasetTimeoutMs,
+  /** Inline chat context: same artifact and data semantics, without title/shell chrome. */
+  inline = false,
+  className,
+  /**
+   * The minimum time a data-bearing block wears its skeleton before its content is allowed to
+   * paint (design behavior B4: "skeleton-before-content, always"). Instant data is real — but a
+   * tile that skips its skeleton reads as a pop, not an arrival, so the host may ask for a floor.
+   * 0 (the default) keeps today's paint-when-ready behavior; `prefers-reduced-motion` forces 0.
+   */
+  revealDwellMs = 0,
+  /**
+   * The host says the page passed Phase 2. Only then does a block draw the design's validation tick:
+   * the renderer does not validate, so a tick it drew unbidden would assert a check nobody ran.
+   */
+  validated = false,
+  /**
+   * `(pageId) => pageDoc | Promise<pageDoc>`. What makes `navigate.mode: "overlay"` executable
+   * (DECISIONS A13): the renderer can PRESENT a page over the one it is drawing, but it cannot
+   * invent the document. Without this, an overlay navigate draws disabled, wearing its reason.
+   *
+   * The host must return a page it has VALIDATED. The overlay renders it exactly as `<UIResponsePage>`
+   * renders anything, and this renderer trusts its input.
+   */
+  resolvePage,
+  /**
+   * THE COMMENTARY TRACK. Generation-time narration lines — `[{ after, text, slots }]` — spoken
+   * over the page as it fills in: "The soonest is {title}, {date}." The model PHRASES a line and
+   * POINTS at values with slots (ordinary OBL bindings); it never states one, because it has
+   * never seen a row. Each line paints after the block it narrates, once every slot's dataset is
+   * ready, with the slots resolved and formatted by the same machinery as every block. A slot
+   * that cannot resolve withholds its line — narration understates, never invents. Not part of
+   * the page document: a saved view keeps its data live and its commentary in the past.
+   */
+  narration = null,
+  /**
+   * `(settled: boolean) => void` — called with `true` each time the page reaches the state where
+   * every data-bearing block on screen has revealed its content (or settled terminally into an
+   * error), and with `false` when new unrevealed content appears (a streamed document growing,
+   * a refresh). Reported after commit, on transitions only; the mount state is always reported.
+   *
+   * THE SEAM, and why it is this and not dataset events: "revealed" is not "resolved". The dwell
+   * gate holds a tile's content on its skeleton after its rows are already in memory, page-wide,
+   * one per beat — timing only this component knows. A host deriving readiness from its own
+   * `resolve` calls would re-implement that private choreography and drift the first time it
+   * changed. So the renderer reports the FACT (what a viewer can see) and keeps the mechanism;
+   * the host composes rhythm — outros, CTAs, composer re-enable — on top of the fact.
+   */
+  onAllRevealed,
+  /** Internal. An overlay does not open an overlay — see the comment on `openOverlay`. */
+  __inOverlay = false,
+}) {
+  const theme = useMemo(() => (themeProp ? makeTheme(themeProp) : defaultTheme), [themeProp]);
+  const cssVars = useMemo(() => themeToCssVars(theme), [theme]);
+  const clock = useMemo(() => now ?? new Date(), [now]);
+  const [notice, setNotice] = useState(null);
+  const [confirmation, setConfirmation] = useState(null);
+  const confirmationResolve = useRef(null);
+
+  const defaultConfirm = useCallback((prompt) => new Promise((resolve) => {
+    confirmationResolve.current?.(false);
+    confirmationResolve.current = resolve;
+    setConfirmation(prompt);
+  }), []);
+  const settleConfirmation = useCallback((accepted) => {
+    const resolvePending = confirmationResolve.current;
+    confirmationResolve.current = null;
+    setConfirmation(null);
+    resolvePending?.(accepted);
+  }, []);
+  useEffect(() => () => confirmationResolve.current?.(false), []);
+  const effectiveConfirm = confirm ?? defaultConfirm;
+
+  const { datasets, dataset, params, setParam, refresh, blockReady, blockError, blockStale } =
+    usePageData(page, resolve, { params: suppliedParams, concurrency, timeoutMs: datasetTimeoutMs });
+
+  // The masthead states what the page is doing, in the page's own terms. An internal block id or a
+  // spec version would be engineering talking to itself; "2 of 3 datasets" is the thing a person
+  // watching a page fill in actually wants to know.
+  const status = useMemo(() => {
+    const all = Object.values(datasets);
+    if (!all.length) return null;
+    const ready = all.filter((d) => d.status === "ready").length;
+    const failed = all.filter((d) => d.status === "error").length;
+    if (failed) return `${failed} of ${all.length} datasets failed`;
+    if (ready < all.length) return `Resolving · ${ready} of ${all.length} datasets`;
+    return `${all.length} ${all.length === 1 ? "dataset" : "datasets"} · live`;
+  }, [datasets]);
+
+  const notify = useCallback((msg) => {
+    onNotice?.(msg);
+    setNotice(msg);
+  }, [onNotice]);
+
+  /**
+   * `navigate.mode: "overlay"` — present a page without leaving this one (DECISIONS A13).
+   *
+   * The overlay is NOT a stack. An overlay may not open an overlay: two drawers deep is chrome
+   * managing chrome, and OBL's claim is only "the user has not left". The nested page therefore
+   * receives no `resolvePage`, so its own overlay navigations draw disabled and say why — which is a
+   * far better outcome than a drawer sliding out from under a drawer.
+   *
+   * `openOverlay` is absent from `actionCtx` when the host gave us no `resolvePage`, and `verbReason`
+   * reads exactly that absence to decide whether the verb can run. One source of truth.
+   */
+  const [overlay, setOverlay] = useState(null);
+  // The element that opened the drawer, so focus can go back to it. Captured when the ACTION fires,
+  // not when the panel mounts: by mount time the row may already have lost focus, and `document.body`
+  // is where focus lands when nobody remembers.
+  const overlayTrigger = useRef(null);
+
+  const openOverlay = useCallback(async ({ pageId, params }) => {
+    overlayTrigger.current = typeof document !== "undefined" ? document.activeElement : null;
+    setOverlay({ pageId, params, doc: null, error: null });
+    try {
+      const doc = await resolvePage(pageId);
+      if (!doc) throw new Error(`the host has no page \`${pageId}\``);
+      setOverlay({ pageId, params, doc, error: null });
+    } catch (e) {
+      setOverlay({ pageId, params, doc: null, error: e.message });
+    }
+  }, [resolvePage]);
+  const closeOverlay = useCallback(() => setOverlay(null), []);
+
+  const actionCtx = useMemo(() => ({
+    setParam, refresh, onOpenRecord, onNotice: notify, confirm: effectiveConfirm, resolveValue,
+    ...(resolvePage && !__inOverlay ? { openOverlay } : null),
+  }), [setParam, refresh, onOpenRecord, notify, effectiveConfirm, resolvePage, __inOverlay, openOverlay]);
+
+  const uir = useMemo(() => ({
+    // `pageId` is here for continuity across closes and reopens — the count-up seeds its climb
+    // from the value this page last showed, and a value is only "the same one" per page per block.
+    dataset, params, now: clock, theme, actionCtx, row: undefined, pageId: page.id,
+  }), [dataset, params, clock, theme, actionCtx, page.id]);
+
+  const scope = useMemo(() => ({ dataset, params, now: clock }), [dataset, params, clock]);
+
+  /**
+   * THE SKELETON DWELL — and the CONTENT BEAT. Two floors, one knob:
+   *
+   *   · Each data-bearing block wears its skeleton for at least `revealDwellMs` from its first
+   *     paint, even if its rows are already here ("skeleton-before-content, always").
+   *   · Contents flip in no faster than one per `revealDwellMs`, page-wide. Two blocks bound to
+   *     the SAME dataset become ready in the same instant — without a shared floor they pop in the
+   *     same frame, which is precisely the "load, not composition" the beat exists to prevent.
+   *     Blocks claim their slot in document order, because that is the order render walks them.
+   *
+   * A revealed block STAYS revealed — the gate is for arrival, not for life. A timer per held
+   * block re-renders at its slot — nothing polls. Ids are the keys, so a block that re-enters
+   * after a failed round dwells again (its content IS arriving again).
+   */
+  const dwellMs = revealDwellMs > 0 && !prefersReducedMotion() ? revealDwellMs : 0;
+  const firstPaintAt = useRef(new Map());
+  const revealedIds = useRef(new Set());
+  const lastRevealAt = useRef(-Infinity);
+  const dwellTimers = useRef(new Map());
+  const [, bumpDwell] = useState(0);
+  useEffect(() => {
+    const timers = dwellTimers.current;
+    return () => { for (const t of timers.values()) clearTimeout(t); };
+  }, []);
+
+  const dwelling = useCallback((id, ready) => {
+    if (!dwellMs) return false;
+    if (revealedIds.current.has(id)) return false;
+    const nowMs = Date.now();
+    let seen = firstPaintAt.current.get(id);
+    if (seen === undefined) {
+      seen = nowMs;
+      firstPaintAt.current.set(id, seen);
+    }
+    if (!ready) return false; // the natural skeleton is already showing; the clock started at first paint
+    const allowedAt = Math.max(seen + dwellMs, lastRevealAt.current + dwellMs);
+    if (nowMs >= allowedAt) {
+      revealedIds.current.add(id);
+      lastRevealAt.current = nowMs;
+      return false;
+    }
+    if (!dwellTimers.current.has(id)) {
+      dwellTimers.current.set(
+        id,
+        setTimeout(() => {
+          dwellTimers.current.delete(id);
+          bumpDwell((n) => n + 1);
+        }, allowedAt - nowMs + 15),
+      );
+    }
+    return true;
+  }, [dwellMs]);
+
+  /**
+   * SETTLEMENT — the ledger behind `onAllRevealed`. Reset at the top of every render pass and
+   * repopulated by `renderBlock` as it walks (children render after this function returns, still
+   * before the commit's effects — so the effect below always reads a complete pass). A partial
+   * re-render (a tab switching) only overwrites its own entries, and every state change that can
+   * move a block's settledness (datasets, the dwell timers) re-renders this component, so the
+   * ledger is never stale when it is read.
+   */
+  const settlement = useRef(new Map());
+  const reportedAllRevealed = useRef(undefined);
+  settlement.current = new Map();
+
+  useEffect(() => {
+    if (!onAllRevealed) return;
+    let all = true;
+    for (const settled of settlement.current.values()) {
+      if (!settled) { all = false; break; }
+    }
+    if (all !== reportedAllRevealed.current) {
+      reportedAllRevealed.current = all;
+      onAllRevealed(all);
+    }
+  });
+
+  /** One or two elements is an answer, not a document. It gets a label. */
+  const minimal = useMemo(() => countLeaves(page.blocks) <= 2, [page.blocks]);
+
+  /**
+   * …and an answer that already OPENS with a headline gets nothing at all. A browse page is a single
+   * editorial section, so the shell's title and the section's headline were printing the same thing
+   * twice — the first as a 12px grey label (see `minimal`), the second as a 30px headline directly
+   * beneath it. The document's headline wins, because it is the one the author wrote in the document.
+   */
+  const headlineInDocument = useMemo(() => pageHeadlineIsInDocument(page), [page]);
+
+  /**
+   * Whether the shell prints `page.title` at all. It does not when the document opens with its own
+   * headline, and it does not inside an overlay — the drawer's head is already showing this exact
+   * string, four pixels above where the header would print it again.
+   */
+  const showTitle = !headlineInDocument && !__inOverlay;
+
+  /**
+   * One block. This function is where the document's promises are kept:
+   *
+   *   - a block whose datasets have not landed paints its FRAME and a skeleton, never a blank;
+   *   - a block whose dataset FAILED says what failed, never an empty table (R9);
+   *   - `visible_when` is evaluated only once the data it reads exists, because "still loading" and
+   *     "deliberately absent" are different claims and must never look the same;
+   *   - `empty.show: "hide"` removes the block, and only that policy does.
+   */
+  const renderBlock = useCallback(function render(block, key, opts = {}) {
+    const emphasis = block.emphasis ?? "normal";
+    const needsData = collectDatasets(block).size > 0;
+    const dataReady = !needsData || blockReady(block);
+    const error = blockError(block);
+    const stale = blockStale(block);
+    // The dwell delays PAINT, never truth: visibility and errors read the real readiness, and only
+    // a block that would otherwise show content is held on its skeleton.
+    const held = needsData && !error && dwelling(block.id ?? key, dataReady);
+    const ready = dataReady && !held;
+
+    // The settlement ledger entry for this block (see `settlement` above). Recorded on every exit
+    // path: a hidden block owes nothing, an errored one has settled into its error, and the rest
+    // follow `blockSettled` — data ready and the dwell released.
+    const note = (settled, node) => {
+      settlement.current.set(String(block.id ?? key), settled);
+      return node;
+    };
+    const settledNow = blockSettled({ needsData, error, dataReady, held });
+
+    const vis = visibility(block, scope, dataReady);
+    if (vis === "hidden") return note(true, null);
+    // A conditional block whose condition has not resolved draws nothing: we do not yet know that it
+    // belongs on this page, and a skeleton is a promise. See core/condition.js.
+    if (vis === "pending") return note(settledNow, null);
+
+    const isTile = TILES.has(block.type);
+
+    const wrap = (children, state) => (
+      <div
+        key={key}
+        className="uir-block"
+        data-block={block.id}
+        data-type={block.type}
+        data-emphasis={emphasis}
+        data-state={state}
+        data-stale={stale || undefined}
+        data-tile={isTile || undefined}
+        // STREAMING ARRIVAL: the tile's frame was already on screen; its content just landed, so it
+        // folds in. A block that never waited for data has nothing to arrive and does not animate.
+        data-arrived={(isTile && state === "ready" && needsData) || undefined}
+      >
+        {validated && isTile && state === "ready" && <ValidationTick />}
+        {children}
+      </div>
+    );
+
+    // Containers paint immediately: their structure is knowable from the document alone, and their
+    // children each decide for themselves whether they are ready. That is what "top-down" means.
+    if (CONTAINERS.has(block.type)) {
+      const childOf = (child, i) => render(child, child.id ?? i, { hideTitle: block.type === "tabs" });
+      if (block.type === "section") return note(true, wrap(<SectionBlock block={block} renderChild={childOf} hideTitle={opts.hideTitle} />, "ready"));
+      if (block.type === "card") {
+        if (!ready && needsData) return note(settledNow, wrap(<Skeleton block={block} />, "pending"));
+        return note(settledNow, wrap(<CardBlock block={block} renderChild={childOf} emphasis={emphasis} />, "ready"));
+      }
+      if (block.type === "tabs") return note(true, wrap(<TabsBlock block={block} renderChild={childOf} />, "ready"));
+    }
+
+    const Leaf = LEAVES[block.type];
+    if (!Leaf) {
+      // A block from the future. Skip it, keep its siblings, and say so once — never render a
+      // partial block, never fail the page (VERSIONING §3.2). It settled as this notice.
+      return note(true, wrap(<BlockError message={`This renderer does not know the block type "${block.type}". It needs a newer renderer.`} />, "ready"));
+    }
+
+    if (error) {
+      // A dataset that failed can be asked again. `refresh` is already a first-class verb, so the
+      // design's Retry costs nothing but the wiring.
+      const retry = () => refresh([...collectDatasets(block)]);
+      return note(true, wrap(<BlockError message={error} onRetry={retry} />, "error"));
+    }
+    if (!ready) {
+      return note(settledNow, wrap(<Skeleton variant={SKELETON_VARIANT[block.type] ?? "bars"} block={block} />, "pending"));
+    }
+
+    // `empty.show: "hide"` is the one policy that removes a block entirely.
+    if (block.value?.$bind?.empty && hidesBlock(block.value.$bind.empty)) {
+      const v = resolveValue(block.value, scope);
+      if (v === null || v === undefined) return note(true, null);
+    }
+
+    try {
+      return note(settledNow, wrap(<Leaf block={block} emphasis={emphasis} />, "ready"));
+    } catch (e) {
+      // An `only` assertion that fired, a binding that could not resolve. Loud, local, and it does
+      // not take the page down with it.
+      return note(true, wrap(<BlockError message={e.message} />, "error"));
+    }
+  }, [blockReady, blockError, blockStale, scope, refresh, validated, dwelling]);
+
+  /** Narration lines grouped by their anchor block; unanchored lines follow the last block. */
+  const narrationAfter = useMemo(() => {
+    const by = new Map();
+    for (const n of narration ?? []) {
+      if (!n || typeof n.text !== "string") continue;
+      const key = typeof n.after === "string" ? n.after : "__end__";
+      if (!by.has(key)) by.set(key, []);
+      by.get(key).push(n);
+    }
+    return by;
+  }, [narration]);
+
+  const narrationFor = useCallback((blockId) => {
+    const lines = narrationAfter.get(blockId);
+    if (!lines?.length) return null;
+    return lines.map((n, i) => {
+      const slotNames = Object.keys(n.slots ?? {});
+      // Every slot's dataset must be READY — a commentary line about data that has not landed
+      // would be a promise, and half-resolved prose is worse than none.
+      const pending = slotNames.some((name) => {
+        const ds = n.slots[name]?.$bind?.dataset ?? n.slots[name]?.dataset;
+        return ds && datasets[ds]?.status !== "ready";
+      });
+      if (pending) return null;
+      let line = n.text;
+      try {
+        for (const name of slotNames) {
+          const slot = n.slots[name];
+          const bind = slot?.$bind ?? slot;
+          const value = resolveValue({ $bind: bind }, scope);
+          if (value === null || value === undefined || value === "") throw new Error("empty slot");
+          const column = (page.data ?? []).find((d) => d.name === bind.dataset)?.columns?.find((c) => c.name === bind.field);
+          line = line.split(`{${name}}`).join(formatValue(value, bind.format, { column, now: clock }));
+        }
+      } catch {
+        return null; // a slot that cannot resolve withholds the line — understate, never invent
+      }
+      return (
+        <p key={`narr-${blockId}-${i}`} className="uir-narration">
+          {line}
+        </p>
+      );
+    });
+  }, [narrationAfter, datasets, scope, page, clock]);
+
+  return (
+    <UIResponseContext.Provider value={uir}>
+      <div
+        className={["uir-page", inline ? "uir-page--inline" : null, className].filter(Boolean).join(" ")}
+        style={cssVars}
+        aria-label={inline ? page.title : undefined}
+      >
+        <div className="uir-shell">
+          {/* Chrome scales to content. A dashboard earns a header line; a generated page of one chart
+              earns a label and nothing else. A masthead over a single tile is a poster, not a page. */}
+          {!inline && (
+            <header className="uir-header" data-minimal={minimal || undefined}>
+              <div className="uir-header__line">
+                {/* The title is chrome; the editorial headline below is the page. When the document
+                    carries its own, the shell says nothing and keeps only its dataset status. */}
+                {showTitle && <h1 className="uir-header__title">{page.title}</h1>}
+                {status && (
+                  <span className="uir-header__status" data-settled={status.endsWith("live") || undefined}>
+                    {status}
+                  </span>
+                )}
+              </div>
+              {page.subtitle && !minimal && showTitle && <p className="uir-header__subtitle">{page.subtitle}</p>}
+            </header>
+          )}
+
+          {page.blocks.map((block, i) => (
+            <React.Fragment key={`f-${block.id ?? i}`}>
+              {renderBlock(block, block.id ?? i)}
+              {narrationFor(block.id)}
+            </React.Fragment>
+          ))}
+          {narrationFor("__end__")}
+
+          {notice && (
+            <div className="uir-notice" role="status">
+              <button type="button" className="uir-notice__close" onClick={() => setNotice(null)} aria-label="Dismiss">×</button>
+              {notice}
+            </div>
+          )}
+        </div>
+
+        {overlay && (
+          <OverlayDrawer overlay={overlay} onClose={closeOverlay} returnFocusTo={overlayTrigger}>
+            {overlay.doc && (
+              <UIResponsePage
+                page={overlay.doc}
+                resolve={resolve}
+                theme={themeProp}
+                params={overlayParams(suppliedParams, overlay.params)}
+                onOpenRecord={onOpenRecord}
+                onNotice={onNotice}
+                confirm={confirm}
+                now={now}
+                validated={validated}
+                revealDwellMs={revealDwellMs}
+                className="uir-page--nested"
+                __inOverlay
+              />
+            )}
+          </OverlayDrawer>
+        )}
+        {confirmation && <ConfirmDialog prompt={confirmation} onResolve={settleConfirmation} />}
+      </div>
+    </UIResponseContext.Provider>
+  );
+}
+
+/**
+ * The overlay presentation of a page (DECISIONS A13, design sheet `2a · Chat to page prototype`).
+ *
+ * Geometry and motion are EXTRACTED from the sheet, not chosen: a 372px right drawer, a 1px left
+ * border, a `-16px 0 40px rgba(0,0,0,0.1)` shadow, `obSlideIn 0.32s` on the panel and `obFade 0.25s`
+ * on an `rgba(9,9,11,0.18)` scrim. They live in `theme/tokens.js` with everything else.
+ *
+ * Nothing about a drawer is in the schema. `mode: "overlay"` says only *the user has not left*; this
+ * is one medium's answer to that claim, and a voice renderer's answer is the word "aside".
+ *
+ * Escape closes it, the scrim closes it, and focus moves into the panel on open and back to whatever
+ * had it on close. A drawer you cannot leave with the keyboard is a trap, and the page underneath is
+ * still there — which is the whole point of the mode.
+ */
+function OverlayDrawer({ overlay, onClose, returnFocusTo, children }) {
+  const panelRef = useRef(null);
+
+  useEffect(() => {
+    panelRef.current?.focus();
+    const onKey = (e) => { if (e.key === "Escape") { e.stopPropagation(); onClose(); } };
+    document.addEventListener("keydown", onKey);
+    return () => {
+      document.removeEventListener("keydown", onKey);
+      // The element may have gone with the row that opened the drawer, and `body` is not a place to
+      // put focus — it is where focus goes when nobody put it anywhere.
+      const trigger = returnFocusTo?.current;
+      if (trigger && trigger !== document.body && trigger.isConnected) trigger.focus();
+    };
+  }, [onClose]);
+
+  return (
+    <div className="uir-overlay" role="dialog" aria-modal="true" aria-label={overlay.doc?.title ?? "Loading"}>
+      <div className="uir-overlay__scrim" onClick={onClose} />
+      <div className="uir-overlay__panel" ref={panelRef} tabIndex={-1}>
+        <div className="uir-overlay__head">
+          <span className="uir-overlay__title">{overlay.doc?.title ?? overlay.pageId}</span>
+          <button type="button" className="uir-overlay__close" onClick={onClose} aria-label="Close">
+            <svg width="9" height="9" viewBox="0 0 9 9" aria-hidden="true">
+              <line x1="1" y1="1" x2="8" y2="8" /><line x1="8" y1="1" x2="1" y2="8" />
+            </svg>
+          </button>
+        </div>
+        <div className="uir-overlay__body">
+          {overlay.error
+            ? <BlockError message={`Could not present \`${overlay.pageId}\`: ${overlay.error}`} />
+            : overlay.doc
+              ? children
+              : <Skeleton />}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default UIResponsePage;