@exponential-at/ui 0.0.0-stage → 0.1.0

package/catalog/tokens.json

@@ -0,0 +1,47 @@
+{
+  "$comment": "VAPP-85: the token NAMES the core catalog's macros and Box styles reference as `$<group>.<name>` (e.g. `$color.primary`, `$spacing.md`). VALUES come from a theme (VAPP-92); this file only fixes the vocabulary. `color` = the shadcn semantic set plus success/warning/info and the eight chart hues (round 1 added chart6..8); `spacing`/`radius`/`type` mirror packages/design-tokens' scales by NAME (xl2 because 2xl is not an identifier in Swift/Kotlin/Rust); `control` = the per-kind control heights the VAPP-4 spike asked for instead of px (round 1 adds `appBar`, `tabBar`, `toast`); `shadow` = the boxShadow presets, ALSO the elevation scale (none < sm < md < lg < xl: flat, card, popover, dialog, toast; paint order inside a layer stays tree order, overlays stack by layer, never by zIndex); `opacity` = the text-emphasis ladder; VAPP-92 adds `border` (the border-width ladder, px) and `motion` (durations, ms). Round 1 (docs/round-1-contract.md) adds `breakpoint` (px, the ONLY tokens a style CONDITION may reference: `\"@media (min-width: $breakpoint.md)\"`; resolved against the theme before matching), `ease` (cubic-bezier control points [x1, y1, x2, y2], referenced by `transitionEasing`) and `density` (multipliers over `control` and `spacing` for the surface density `compact`/`comfortable`; `default` = 1, never a token). Round 2 (docs/round-2-contract.md §2) adds `blur` (px radii, the ONLY values `backdropBlur` takes). EXP-1259 (EXP-1243, packages/design-tokens motion.scale) adds `scale` (unitless multipliers the PAINTERS read, never a style value): `press` = what a pressed button scales to, `popoverFrom` = what a popover or menu scales FROM while it fades in (never from 0); reduce motion = no scale. Every group is append-only: a theme is validated against these names.",
+  "color": [
+    "background", "foreground",
+    "card", "cardForeground",
+    "popover", "popoverForeground",
+    "primary", "primaryForeground",
+    "secondary", "secondaryForeground",
+    "muted", "mutedForeground",
+    "accent", "accentForeground",
+    "destructive", "destructiveForeground",
+    "success", "successForeground",
+    "warning", "warningForeground",
+    "info", "infoForeground",
+    "border", "input", "ring",
+    "chart1", "chart2", "chart3", "chart4", "chart5", "chart6", "chart7", "chart8"
+  ],
+  "spacing": ["none", "xxs", "xs", "sm", "md", "lg", "xl", "xl2", "xl3"],
+  "radius": ["none", "sm", "md", "lg", "xl", "xl2", "xl3", "full"],
+  "type": {
+    "size": ["xs", "sm", "base", "lg", "xl", "xl2", "xl3"],
+    "lineHeight": ["xs", "sm", "base", "lg", "xl", "xl2", "xl3"],
+    "weight": ["regular", "medium", "semibold", "bold"],
+    "family": ["sans", "mono"]
+  },
+  "control": [
+    "buttonSm", "buttonMd", "buttonLg", "buttonIcon",
+    "input", "textarea",
+    "row", "rowCompact",
+    "pill", "badge", "chip",
+    "toggle", "switch", "checkbox", "slider",
+    "progress", "meter",
+    "avatarSm", "avatarMd", "avatarLg",
+    "iconSm", "iconMd", "iconLg",
+    "hairline",
+    "appBar", "tabBar", "toast"
+  ],
+  "shadow": ["none", "sm", "md", "lg", "xl"],
+  "opacity": ["primary", "secondary", "tertiary", "quaternary", "disabled"],
+  "border": ["none", "hairline", "thick"],
+  "motion": ["fast", "standard", "slow"],
+  "breakpoint": ["sm", "md", "lg", "xl"],
+  "ease": ["standard", "decelerate", "accelerate"],
+  "density": ["compact", "comfortable"],
+  "blur": ["sm", "md", "lg", "xl"],
+  "scale": ["press", "popoverFrom"]
+}

package/conformance/README.md

@@ -0,0 +1,217 @@
+# Exponential UI conformance
+
+A renderer is **Exponential UI conformant** when its runner replays every
+suite of [`manifest.json`](manifest.json) (GENERATED from the fixtures,
+drift-gated) and the report passes:
+
+```bash
+bun run --filter @exponential-at/ui conformance:check path/to/report.json
+# CONFORMANT  my-renderer (flutter 0.3.0): <n> cases passed in <m> suites
+```
+
+Every suite present, every case run (the manifest's `cases` count), nothing
+failed or skipped. The fixtures under `../fixtures/` are the contract; the
+TS reference (`../src/`) generated their `expected` values and the Rust core
+replays them byte for byte.
+
+## The suites
+
+| suite | fixture | a runner does, per case |
+|---|---|---|
+| `catalog` | `catalog-components.json` | reduce the nested node (no issues), PAINT it: no crash, no `Unknown` |
+| `macros` | `catalog-macros.json` | expand: the tree equals `expanded` |
+| `basic-map` | `catalog-basic-map.json` | reduce the A2UI basic surface: tree + issues equal |
+| `extension` | `catalog-extension.json` | register the extension, reduce: tree + issues equal |
+| `theme-resolved` | `theme-resolved.json` | load each built-in theme: equal |
+| `theme-recipes` | `theme-recipes.json` | resolve the part recipe per theme × mode × state: equal |
+| `theme-extends` | `theme-extends.json` | load over the parents: chain + probes equal |
+| `theme-invalid` | `theme-invalid.json` | validate: the same issues, never a crash |
+| `control-geometry` | `control-geometry.json` | measure YOUR painted control: every fixed key within 0.5 (with `minHeight`, height is only a floor) |
+| `layout` | `layout-geometry.json` | lay out with the fixed measure: frames exact (a CSS renderer: within 1 px) |
+| `overlay` | `overlay-geometry.json` | place the overlay: side, flip, position within `tolerancePx` |
+| `replay` | `kitchen-sink.json` | paint the sink per built-in theme × mode: the expanded tree, no `Unknown`, paint/a11y order = pre-order |
+| `host-transport` | `host-transport.json` | JSONL / SSE chunks through ONE decoder, the MCP carrier: messages + issues equal |
+| `host-policy` | `host-policy.json` | the function gate, combine, URL policy, media request, source URIs, catalog negotiation |
+| `host-router` | `host-router.json` | package validation; message flows → the ops, in order |
+| `bind` | `bind-time.json` | expand, run the bind pass per dataset: bound tree, `set` presses, per-row slot cells |
+| `style-conditions` | `style-conditions.json` | flatten the style per context |
+| `code-tokens` | `code-tokens.json` | tokenize: the lines of tokens |
+| `format` | `format.json` | format calls through the English fallback (`zoned`: at `offsetMinutes`), exact; display values. A platform Formatter may run too (U+202F, U+00A0 → space) |
+| `template-items` | `template-items.json` | item and row keys, template instances + escaped suffixes, reduce with templates lifted (cycles reported, kept in place) |
+| `text-direction` | `text-direction.json` | every node's direction and physical text alignment |
+| `resizable` | `resizable.json` | panel sizes (normalize, drag, keys, extents, px → percent) within 1e-6 |
+| `virtual-list` | `virtual-list.json` | the window, scrollToIndex (sectioned: data index → row), sections, the sticky header |
+| `animations` | `animations.json` | timing + frames per theme within 1e-3; painted opacity = own × frame |
+
+`manifest.json` says how each count is derived (`unit`). A renderer built on
+the Rust core (the facade, `exponential-ui-ffi`) gets the pure suites through
+its bindings; one on the TS package gets them from `@exponential-at/ui`;
+anything else implements `catalog/host.json` and the reducer itself.
+
+## The report
+
+[`report.schema.json`](report.schema.json):
+`{renderer, platform, version, conformanceVersion, suites: {<id>: {cases,
+passed, failed: [names], skipped?}}}`. Our runners write it to
+`$EXPONENTIAL_UI_CONFORMANCE_REPORT` (default `<repo>/.conformance/<name>.json`):
+
+| renderer | runner | command |
+|---|---|---|
+| `exponential-ui` (Rust core) | `apps/desktop/crates/exponential-ui/tests/conformance.rs` | `cargo test -p exponential-ui --test conformance` |
+| `@exponential-at/ui-react` | `packages/exponential-ui-react/browser/suites.test.ts` | `bun run --filter @exponential-at/ui-react test:conformance` (headless Chromium) |
+| `@exponential-at/ui-solid` | `packages/exponential-ui-solid/browser/suites.test.ts` | `bun run --filter @exponential-at/ui-solid test:conformance` (headless Chromium) |
+| `@exponential-at/ui-element` | `packages/exponential-ui-element/browser/suites.test.ts` | `bun run --filter @exponential-at/ui-element test:conformance` (headless Chromium) |
+| `exponential-ui-gpui` | `apps/desktop/crates/exponential-ui-gpui/tests/suites.rs` | `cargo test -p exponential-ui-gpui --test suites` |
+| `ExponentialUI` (SwiftUI) | `packages/exponential-ui-swift/Tests/ExponentialUITests/ConformanceTests.swift` | `swift test` |
+| `at.exponential:ui-compose` | `packages/exponential-ui-compose/ui-compose/src/test/…/ConformanceTest.kt` | `./gradlew :ui-compose:testDebugUnitTest` |
+
+CI (`.github/workflows/exponential-ui.yml`) runs all six renderers plus the
+core on every SDK pull request and fails unless every report is conformant;
+the two non-React web renderers (Solid, the web component) must also pass
+the web-parity gate against React (below).
+
+Version 2 (round 2, `docs/round-2-contract.md` §8) added the last nine
+suites: round 1's bind/style/code fixtures every runner already replayed,
+and the round-2 contract fixtures.
+
+## With the real-font harness (VAPP-98, round 1)
+
+Round 1 (#VAPP-98) adds the other half to this directory: `run.ts` dumps the
+cases of `fixtures/conformance-cases.json` from the web and desktop renderers
+with the conformance fonts and compares them with
+`fixtures/conformance-baseline.json` (geometry with real text, plus a reported
+pixel step). The two halves do not overlap: this manifest locks the CONTRACT
+every renderer replays case by case (no fonts involved), the harness locks
+what real text does to it. Once both are on master, the harness's comparison
+becomes suite `real-font` here (cases = its matrix, a renderer passes when its
+dump has no divergence beyond `conformance-known.json`), so
+`conformance:check` stays the one verdict. Runner files are named `suites`
+(`browser/suites.test.ts`, gpui `tests/suites.rs`) beside the harness's own
+`conformance` ones.
+
+### The matrix
+
+Every renderer runs the FULL cross product of `conformance-cases.json`
+(`allCases` in `dump.ts`; the Rust, Swift and Kotlin runners build the same
+keys `<fixture>/<theme>/<mode>/<width>/<direction>`), so adding a fixture, a
+theme, a mode or a width there widens every runner at once:
+
+| axis | values |
+|---|---|
+| fixtures | `kitchen-sink` (every component), `responsive` (the kitchen sink's responsive section, `layout-geometry-round1.json`), `dashboard` (`dashboard.json` + `dashboard.data.json`: an agent project dashboard, VAPP-103) |
+| themes | the built-ins: `exponential`, `neutral`, `playful`, `orange` |
+| modes | `dark`, `light` (a mode changes colours only by contract; the light cases lock that no theme mode or recipe moves a box) |
+| widths | 390, 600, 900, 1280 |
+| directions | `ltr`, `rtl` |
+
+The web dump of the whole matrix takes well under a minute; the Swift and
+Compose ratchets a few seconds each, so the matrix is not sampled.
+
+### Recording
+
+| what | where | command |
+|---|---|---|
+| the web baseline | any machine with Chromium | `bun run --filter @exponential-at/ui conformance -- --write-baseline --skip-desktop` (whole matrix only) |
+| the SwiftUI ratchet | macOS | `EXPONENTIAL_UI_WRITE_FIXTURES=1 swift test --filter RealFont` (`packages/exponential-ui-swift`) |
+| the Compose ratchet | ubuntu (CI verifies there) | `.github/workflows/record-compose-fixtures.yml`, artifact `compose-fixtures` (`EXP_UI_WRITE_FIXTURES=1 ./gradlew :ui-compose:testDebugUnitTest --tests '*RealFontConformanceTest'`) |
+| the gpui ratchet | Linux only (`tests/conformance.rs` builds there) | the same workflow's `gpui` job, artifact `gpui-ratchet` (`EXP_UI_WRITE_FIXTURES=1 cargo test -p exponential-ui-gpui --test conformance`) |
+
+A new case without a budget fails every ratchet, so a matrix change re-records
+all four in the same change.
+
+Round 2: the dump measures LAYOUT boxes (transforms and animations off,
+`LAYOUT_ONLY_CSS`), skips inactive carousel pages (`data-xui-inactive`),
+and every painted part carries `data-xui-id="<node id>.<part>[.<index or
+row key>]"` + `data-xui-part` (catalog/recipes.json lists the parts), so the
+web and gpui dumps cover the same nodes. Nunito and Fira Code are real
+faces (`fonts/`, SIL OFL 1.1). `conformance-known.json` carries the
+divergence decisions (`causes`, `rules`) beside the ratchet's counts.
+
+## Shared browser runner
+
+Every WEB renderer runs the manifest through ONE runner,
+[`browser-suites.ts`](browser-suites.ts) `runBrowserSuites(options)`: the
+pure suites through the core and the shared web layer
+(`@exponential-at/ui/web`), the painted ones in headless Chromium against the
+renderer's harness ([`browser-page.ts`](browser-page.ts): `bunHarness`,
+`openPage`, `EXPONENTIAL_UI_CHROME` = an explicit Chromium executable). A
+renderer plugs in with:
+
+- **a harness**: a `serve.ts` that honours `PORT` and answers `/` with a page
+  speaking the React harness's protocol (`?view=` kitchen-sink, geometry,
+  overlay, catalog, conditions, tree, controls, specimen, mount, bench,
+  round2; `theme`/`mode`/`rtl`/`width`/`echo`; the `window.__xui*` probes);
+- **its logic**: `templateItems`, `itemInstance`, `runNodeAction` (the rest
+  is shared).
+
+The function returns `{report, failures}` (no vitest in the core); the
+renderer's `browser/suites.test.ts` writes the report and asserts
+`checkReport`, as React's does in about 30 lines.
+
+## Web parity
+
+A separate, web-only gate (not a manifest suite: the natives keep the
+manifest's list): [`parity.ts`](parity.ts) `runParity({reference,
+candidate})` loads two web renderers side by side in one headless Chromium
+(software raster, `--font-render-hinting=none`, the conformance fonts,
+device scale 1, reduced motion, animations and transitions off) and compares
+every case EXACTLY:
+
+| check | what |
+|---|---|
+| dom | the `.xui-surface` subtrees (tag, attributes by name, text); generated ids (`useId`, Radix, Solid `cl-N`) in id attributes → `#id-N` in first-seen order |
+| style | the full computed style of every `[data-xui-id]` element (and every overlay part) |
+| frame | their `getBoundingClientRect`, 0 px tolerance |
+| pixels | full-page screenshots, pixelmatch threshold 0 (AA excluded): 0 differing pixels; native `<video>`/`<audio>` boxes masked (the browser's own spinner) |
+
+Cases (390): the matrix through `?view=tree` (192), every specimen at 900 px
+(75), the control specimens with `data-xs` forced to hover, focus, pressed,
+checked, open, disabled, invalid on every part (112), the overlay cases open
+(11). The report ([`parity-report.schema.json`](parity-report.schema.json))
+keeps the FIRST difference of each kind per case; differing screenshots land
+in `.conformance/parity/`.
+
+```bash
+bun run --filter @exponential-at/ui conformance:parity              # React vs React, the self-check (~3 min)
+bun run --filter @exponential-at/ui conformance:parity -- --candidate packages/exponential-ui-solid/harness/serve.ts
+bun run --filter @exponential-at/ui conformance:parity -- --candidate packages/exponential-ui-element/harness/serve.ts
+bun run --filter @exponential-at/ui parity:check .conformance/exponential-ui-parity-react-react.json
+bun run --filter @exponential-at/ui-solid test:parity               # Solid's gate calls runParity
+bun run --filter @exponential-at/ui-element test:parity             # the web component's gate, the same call
+```
+
+**Primitive cases (FEED-131, group `primitive`).** The same gate also
+compares the PRIMITIVE sets: `@exponential-at/ui-react/primitives` (Radix +
+`dist/exponential-ui-react.css`) against `@exponential-at/ui-solid/primitives`
+(+ `dist/exponential-ui-solid.css`, compiled from the SAME `tailwind.css`,
+byte-identical: `src/primitives/styles.test.ts`). Every row of
+[`primitive-specimens.json`](../fixtures/primitive-specimens.json) runs ×
+[`exponential` light, `orange` dark] (`primitive:<id>:<theme>-<mode>`, plus
+`…:<hover|focus>` when the row names an `interact`: the first
+`[data-xui-target]` is hovered / focused on both sides) through both
+harnesses' `?view=primitives&id=&theme=&mode=&width=`
+([`primitives-page.ts`](primitives-page.ts): `globalsCss` + the package's
+own sheet in `<head>`, `class="dark"` on `<html>`, `data-xui-parity-root` +
+`data-xui-mode` on `<body>`, the specimen in `<div data-xui-specimen
+style="padding: 16px;">`). On such a page the probe compares the WHOLE
+`<body>` (its attributes too: Radix's scroll lock writes them; `<script>`
+and the gate's own styles skipped) and EVERY element under it, keyed by its
+path (`body/div[0]/button[1]`). Specimens live in one module per lane,
+`harness/primitives/{smoke,plain,controls,overlays,data,calendar}.tsx` in
+BOTH packages (`SPECIMENS: Record<id, component>`); the jsdom twin is
+`expectElementParity` (ui-solid `src/test/parity.ts`).
+
+```bash
+bun run --filter @exponential-at/ui-solid test:parity:primitives    # the primitive group alone (seconds)
+EXPONENTIAL_UI_PARITY_GROUP=matrix,overlay bun run --filter @exponential-at/ui-solid test:parity
+```
+
+## Listing
+
+Once two platforms pass, the A2UI ecosystem's renderers page gets an entry
+(a pull request to google/A2UI, a person's call: it is outward-facing):
+
+> **Exponential UI** (React, SwiftUI, Jetpack Compose, gpui): native renderers
+> of the A2UI v0.9 basic catalog plus an 81-component core catalog, runtime
+> themes, extension catalogs and a host API (transports, functions, bindings,
+> policy). Apache-2.0. https://ui.exponential.at

package/conformance/baseline.ts

@@ -0,0 +1,101 @@
+// The committed web BASELINE (fixtures/conformance-baseline.json): the React
+// renderer's frame dump of the whole matrix, stored compactly — per fixture
+// ONE node table (the union of every case's nodes: id, component, part,
+// parent, text) and per case one frame row per placed node
+// `[node, x, y, w, h, lines?, lh?]`, one row per line so a layout change
+// diffs as the rows it moved. `decodeBaseline` gives the plain dump back;
+// the Rust gate (tests/conformance.rs) decodes the same shape.
+
+import { BASELINE_PATH, type CaseDump, type Dump, type DumpNode } from "./dump"
+
+export const BASELINE_FILE = BASELINE_PATH
+export const BASELINE_FORMAT = `xui-conformance-baseline/1`
+
+type NodeRow = [id: string, component: string, part: string | null, parent: string | null, text: string | null]
+type FrameRow = [node: number, x: number, y: number, w: number, h: number, lines?: number, lh?: number]
+
+export interface Baseline {
+  $comment: string
+  format: string
+  renderer: string
+  fonts: string
+  /** How the baseline was produced (browser version, launch flags). */
+  producer: string
+  fixtures: Record<string, { nodes: NodeRow[] }>
+  cases: Record<string, { width: number; height: number; frames: FrameRow[] }>
+}
+
+const fixtureOf = (key: string) => key.split(`/`)[0]
+
+export function toBaseline(dump: Dump, producer: string): Baseline {
+  const fixtures: Baseline[`fixtures`] = {}
+  const index = new Map<string, Map<string, number>>()
+  const cases: Baseline[`cases`] = {}
+  for (const [key, c] of Object.entries(dump.cases)) {
+    const fx = fixtureOf(key)
+    fixtures[fx] ??= { nodes: [] }
+    const ids = index.get(fx) ?? new Map<string, number>()
+    index.set(fx, ids)
+    const frames: FrameRow[] = []
+    for (const n of c.nodes) {
+      const sig = JSON.stringify([n.id, n.component, n.part ?? null, n.parent ?? null, n.text ?? null])
+      let i = ids.get(sig)
+      if (i === undefined) {
+        i = fixtures[fx].nodes.length
+        fixtures[fx].nodes.push(JSON.parse(sig) as NodeRow)
+        ids.set(sig, i)
+      }
+      const row: FrameRow = [i, n.x, n.y, n.w, n.h]
+      if (n.lines !== undefined) row.push(n.lines, n.lh ?? 0)
+      frames.push(row)
+    }
+    cases[key] = { width: c.width, height: c.height, frames }
+  }
+  return {
+    $comment: `GENERATED by \`bun run --filter @exponential-at/ui conformance -- --write-baseline\` (packages/exponential-ui/conformance): the React renderer's frame dump of fixtures/conformance-cases.json in headless Chromium with the conformance font set. Decoded by conformance/baseline.ts and the Rust gate. Never hand-edit.`,
+    format: BASELINE_FORMAT,
+    renderer: dump.renderer,
+    fonts: dump.fonts,
+    producer,
+    fixtures,
+    cases,
+  }
+}
+
+export function decodeBaseline(b: Baseline): Dump {
+  if (b.format !== BASELINE_FORMAT) throw new Error(`baseline format ${b.format} ≠ ${BASELINE_FORMAT}`)
+  const cases: Record<string, CaseDump> = {}
+  for (const [key, c] of Object.entries(b.cases)) {
+    const table = b.fixtures[fixtureOf(key)].nodes
+    cases[key] = {
+      width: c.width,
+      height: c.height,
+      nodes: c.frames.map(([i, x, y, w, h, lines, lh]) => {
+        const [id, component, part, parent, text] = table[i]
+        const n: DumpNode = { id, component, x, y, w, h }
+        if (part !== null) n.part = part
+        if (parent !== null) n.parent = parent
+        if (text !== null) n.text = text
+        if (lines !== undefined) {
+          n.lines = lines
+          n.lh = lh
+        }
+        return n
+      }),
+    }
+  }
+  return { format: `xui-frame-dump/1`, renderer: b.renderer, fonts: b.fonts, cases }
+}
+
+/** The baseline as committed: the envelope pretty, one node row / frame row per line. */
+export function encodeBaseline(dump: Dump, producer: string): string {
+  const b = toBaseline(dump, producer)
+  const rows = (items: unknown[], indent: string) => (items.length ? `[\n${items.map((r) => `${indent}  ${JSON.stringify(r)}`).join(`,\n`)}\n${indent}]` : `[]`)
+  const fixtures = Object.entries(b.fixtures)
+    .map(([k, f]) => `    ${JSON.stringify(k)}: { "nodes": ${rows(f.nodes, `    `)} }`)
+    .join(`,\n`)
+  const cases = Object.entries(b.cases)
+    .map(([k, c]) => `    ${JSON.stringify(k)}: { "width": ${c.width}, "height": ${c.height}, "frames": ${rows(c.frames, `    `)} }`)
+    .join(`,\n`)
+  return `{\n  "$comment": ${JSON.stringify(b.$comment)},\n  "format": ${JSON.stringify(b.format)},\n  "renderer": ${JSON.stringify(b.renderer)},\n  "fonts": ${JSON.stringify(b.fonts)},\n  "producer": ${JSON.stringify(b.producer)},\n  "fixtures": {\n${fixtures}\n  },\n  "cases": {\n${cases}\n  }\n}\n`
+}

package/conformance/browser-page.ts

@@ -0,0 +1,146 @@
+// FEED-128: the Playwright side of the shared WEB conformance tooling — one
+// headless Chromium (`EXPONENTIAL_UI_CHROME` = an explicit executable, for a
+// machine whose Playwright build is not installed), a renderer HARNESS served
+// on a loopback port, and the page opener every painted suite uses. Node-safe
+// (vitest runs the runners under Node): a harness is a `bun <serve.ts>`
+// child process, never an in-process `Bun.build`.
+//
+// The harness protocol (packages/exponential-ui-react/harness/main.tsx is
+// the reference): `<serve.ts>` honours `PORT`, answers `/` with a page whose
+// module script is the bundle, and that page reads `?view=…` (kitchen-sink,
+// geometry, overlay, catalog, conditions, tree, controls, specimen, mount,
+// bench, round2, primitives = FEED-131's primitives-page.ts) plus
+// theme/mode/rtl/width/echo and exposes the `window.__xui*` probes.
+
+import { chromium, type Browser, type BrowserContext, type Page } from "playwright"
+import { spawn, type ChildProcess } from "node:child_process"
+import { createServer } from "node:net"
+
+export type Query = Record<string, string | number | undefined>
+
+/** A renderer's harness: `start()` serves its bundle on a loopback port. */
+export interface WebHarness {
+  start(): Promise<RunningHarness>
+}
+
+export interface RunningHarness {
+  baseUrl: string
+  stop(): void | Promise<void>
+}
+
+/** The Chromium executable override (`EXPONENTIAL_UI_CHROME`), else
+ *  Playwright's own build. */
+export const chromeExecutable = (): string | undefined => process.env.EXPONENTIAL_UI_CHROME || undefined
+
+export async function launchChromium(args: string[] = [], executablePath = chromeExecutable()): Promise<Browser> {
+  return chromium.launch({ executablePath, args })
+}
+
+/** `${baseUrl}/?<query>` (undefined values dropped). */
+export function pageUrl(baseUrl: string, query: Query): string {
+  const q = new URLSearchParams()
+  for (const [k, v] of Object.entries(query)) if (v !== undefined) q.set(k, String(v))
+  return `${baseUrl}/?${q.toString()}`
+}
+
+/** A free loopback TCP port. */
+export function freePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const srv = createServer()
+    srv.unref()
+    srv.on(`error`, reject)
+    srv.listen(0, `127.0.0.1`, () => {
+      const addr = srv.address()
+      const port = typeof addr === `object` && addr ? addr.port : 0
+      srv.close(() => resolve(port))
+    })
+  })
+}
+
+/** The harness of a `serve.ts` that honours `PORT`: spawned with `bun`,
+ *  ready once `/` answers and the module script it names bundles (a 500 =
+ *  the bundler's error, thrown). A child that dies before `stop()` (killed
+ *  from outside on a busy machine) is respawned on the same port. */
+export function bunHarness(serveScript: string, opts: { timeoutMs?: number } = {}): WebHarness {
+  return {
+    async start() {
+      const port = await freePort()
+      const baseUrl = `http://127.0.0.1:${port}`
+      let stderr = ``
+      let stopping = false
+      let proc: ChildProcess
+      const spawnChild = () => {
+        proc = spawn(`bun`, [serveScript], { env: { ...process.env, PORT: String(port) }, stdio: [`ignore`, `pipe`, `pipe`] })
+        proc.stderr?.on(`data`, (d) => (stderr += String(d)))
+        proc.on(`exit`, (code, signal) => {
+          if (stopping) return
+          stderr += `${serveScript} exited (${code ?? signal}); respawned\n`
+          spawnChild()
+        })
+      }
+      spawnChild()
+      const deadline = Date.now() + (opts.timeoutMs ?? 60_000)
+      for (;;) {
+        let ready = false
+        try {
+          const page = await fetch(`${baseUrl}/`)
+          if (page.ok) {
+            const src = /<script[^>]*src="([^"]+)"/.exec(await page.text())?.[1] ?? `/dist/main.js`
+            const r = await fetch(new URL(src, baseUrl))
+            if (r.status === 500) {
+              stopping = true
+              proc!.kill()
+              throw new Error(`${serveScript}: bundle failed: ${await r.text()}`)
+            }
+            ready = r.ok
+          }
+        } catch (e) {
+          if (String(e).includes(`bundle failed`)) throw e
+        }
+        if (ready) break
+        if (Date.now() > deadline) {
+          stopping = true
+          proc!.kill()
+          throw new Error(`${serveScript} did not start on ${baseUrl}: ${stderr}`)
+        }
+        await new Promise((r) => setTimeout(r, 150))
+      }
+      return {
+        baseUrl,
+        stop: () => {
+          stopping = true
+          proc.kill()
+          if (stderr.trim()) console.error(stderr)
+        },
+      }
+    },
+  }
+}
+
+export interface OpenPageOptions {
+  viewport?: { width: number; height: number }
+  /** Wait for a `.xui-surface` (default true). */
+  waitForSurface?: boolean
+  /** Extra settle time after the surface attached, ms (default 250). */
+  settleMs?: number
+  context?: Parameters<Browser[`newContext`]>[0]
+}
+
+/** A fresh context + page on the harness at `query`; throws on page errors. */
+export async function openPage(browser: Browser, baseUrl: string, query: Query, viewport = { width: 1200, height: 900 }, opts: Omit<OpenPageOptions, `viewport`> = {}): Promise<Page> {
+  const context: BrowserContext = await browser.newContext({ viewport, deviceScaleFactor: 1, ...opts.context })
+  const page = await context.newPage()
+  const errors: string[] = []
+  page.on(`pageerror`, (e) => errors.push(String(e)))
+  page.on(`console`, (m) => {
+    if (m.type() === `error`) errors.push(m.text())
+  })
+  await page.goto(pageUrl(baseUrl, query))
+  if (opts.waitForSurface !== false) await page.waitForSelector(`.xui-surface`, { timeout: 30_000, state: `attached` })
+  await page.waitForTimeout(opts.settleMs ?? 250)
+  if (errors.length) {
+    await context.close()
+    throw new Error(`page errors: ${errors.join(`\n`)}`)
+  }
+  return page
+}