@exponential-at/ui 0.0.0-stage → 0.1.0

package/conformance/manifest.json

@@ -0,0 +1,224 @@
+{
+  "$comment": "GENERATED by `bun run --filter @exponential-at/ui generate` (VAPP-91). The Exponential UI conformance suite: a renderer is \"Exponential UI conformant\" when its runner reports every suite below with `cases` run and none failed (`bun run --filter @exponential-at/ui conformance:check <report.json>`). conformance/README.md says how to write a runner for a new platform.",
+  "version": 2,
+  "hostContractVersion": 2,
+  "suites": [
+    {
+      "id": "catalog",
+      "files": [
+        "fixtures/catalog-components.json"
+      ],
+      "unit": "case",
+      "cases": 528,
+      "check": "Reduce the case's nested node with the core catalog: no issues. Paint it under the default theme: no crash, no Unknown placeholder, every visible node painted."
+    },
+    {
+      "id": "macros",
+      "files": [
+        "fixtures/catalog-macros.json"
+      ],
+      "unit": "case",
+      "cases": 265,
+      "check": "Expand the case: the tree equals `expanded` (JSON-equal, recipes included)."
+    },
+    {
+      "id": "basic-map",
+      "files": [
+        "fixtures/catalog-basic-map.json"
+      ],
+      "unit": "case",
+      "cases": 13,
+      "check": "Reduce the A2UI basic surface: the tree and the issues equal the expected ones."
+    },
+    {
+      "id": "extension",
+      "files": [
+        "fixtures/catalog-extension.json"
+      ],
+      "unit": "case",
+      "cases": 4,
+      "check": "Register the extension; reduce each case: tree + issues equal; its natives reach the extension painter (an `Extension` leaf of that kind)."
+    },
+    {
+      "id": "theme-resolved",
+      "files": [
+        "fixtures/theme-resolved.json"
+      ],
+      "unit": "theme",
+      "cases": 4,
+      "check": "Load each built-in theme: the resolved theme equals the fixture."
+    },
+    {
+      "id": "theme-recipes",
+      "files": [
+        "fixtures/theme-recipes.json"
+      ],
+      "unit": "case",
+      "cases": 409,
+      "check": "Resolve the part's recipe for the case's theme, props, mode and states: the visual equals the fixture."
+    },
+    {
+      "id": "theme-extends",
+      "files": [
+        "fixtures/theme-extends.json"
+      ],
+      "unit": "case",
+      "cases": 3,
+      "check": "Load the theme over its parents: the chain and the probed styles equal the fixture."
+    },
+    {
+      "id": "theme-invalid",
+      "files": [
+        "fixtures/theme-invalid.json"
+      ],
+      "unit": "case",
+      "cases": 26,
+      "check": "Validate the bad theme: the same issue paths, never a crash."
+    },
+    {
+      "id": "control-geometry",
+      "files": [
+        "fixtures/control-geometry.json"
+      ],
+      "unit": "theme × control × case",
+      "cases": 324,
+      "check": "Measure the control under the theme: the box (height, padding, gap, border, radius) equals the fixture."
+    },
+    {
+      "id": "layout",
+      "files": [
+        "fixtures/layout-geometry.json"
+      ],
+      "unit": "width × direction",
+      "cases": 4,
+      "check": "Lay the surface out with the fixture's fixed measure: every node's frame equals the fixture (exact for the Rust core and native painters, within 1 px for a CSS renderer)."
+    },
+    {
+      "id": "overlay",
+      "files": [
+        "fixtures/overlay-geometry.json"
+      ],
+      "unit": "case",
+      "cases": 11,
+      "check": "Place the overlay: side, flip and frame equal the fixture within `tolerancePx`."
+    },
+    {
+      "id": "replay",
+      "files": [
+        "fixtures/kitchen-sink.json",
+        "fixtures/kitchen-sink.expanded.json"
+      ],
+      "unit": "theme × mode",
+      "cases": 8,
+      "check": "Paint the kitchen sink under each built-in theme and mode: the reduced tree equals kitchen-sink.expanded.json, no Unknown, the accessibility order is the pre-order of the painted nodes."
+    },
+    {
+      "id": "host-transport",
+      "files": [
+        "fixtures/host-transport.json"
+      ],
+      "unit": "case",
+      "cases": 20,
+      "check": "Feed the chunks through ONE decoder (JSONL / SSE), or decode the MCP result, or build the MCP action call: messages + issues equal `expected`."
+    },
+    {
+      "id": "host-policy",
+      "files": [
+        "fixtures/host-policy.json"
+      ],
+      "unit": "case",
+      "cases": 103,
+      "check": "Decide the function / combine / url, build the media request, parse the source, negotiate the catalog ids: each equals `expected`."
+    },
+    {
+      "id": "host-router",
+      "files": [
+        "fixtures/host-router.json"
+      ],
+      "unit": "package or flow",
+      "cases": 11,
+      "check": "Validate each package; for each flow build ONE router with `extensionIds`, install `packages` (issues = `installIssues`), route every step: the ops equal `expected`."
+    },
+    {
+      "id": "bind",
+      "files": [
+        "fixtures/bind-time.json"
+      ],
+      "unit": "case",
+      "cases": 53,
+      "check": "Expand the input; for every dataset run the bind pass: the bound tree, every `set` press and the per-row slot cells equal the fixture (reducer `issues` too for `extra`)."
+    },
+    {
+      "id": "style-conditions",
+      "files": [
+        "fixtures/style-conditions.json"
+      ],
+      "unit": "case",
+      "cases": 7,
+      "check": "Flatten the style for every context: equal to `expected` (key order irrelevant)."
+    },
+    {
+      "id": "code-tokens",
+      "files": [
+        "fixtures/code-tokens.json"
+      ],
+      "unit": "case",
+      "cases": 23,
+      "check": "Tokenize the code: the lines of tokens equal `expected`."
+    },
+    {
+      "id": "format",
+      "files": [
+        "fixtures/format.json"
+      ],
+      "unit": "call or value",
+      "cases": 86,
+      "check": "Resolve each format call through the English fallback (`zoned`: at the case's `offsetMinutes`): the string equals `expected` exactly; display each value in a text prop: equals `expected`. A platform Formatter may run too, at en-US / UTC (`zoned`: `timeZone`), comparing after U+202F and U+00A0 → space."
+    },
+    {
+      "id": "template-items",
+      "files": [
+        "fixtures/template-items.json"
+      ],
+      "unit": "case",
+      "cases": 26,
+      "check": "Key the items / rows, list the template instances (path, key, accumulated suffix), reduce the surfaces (templates lifted): equal to `expected`."
+    },
+    {
+      "id": "text-direction",
+      "files": [
+        "fixtures/text-direction.json"
+      ],
+      "unit": "surface direction",
+      "cases": 2,
+      "check": "Reduce the tree; every node's resolved direction and physical text alignment equal `expected`."
+    },
+    {
+      "id": "resizable",
+      "files": [
+        "fixtures/resizable.json"
+      ],
+      "unit": "case",
+      "cases": 38,
+      "check": "Normalize / resize / key / measure / convert: the numbers equal `expected` within 1e-6."
+    },
+    {
+      "id": "virtual-list",
+      "files": [
+        "fixtures/virtual-list.json"
+      ],
+      "unit": "case",
+      "cases": 26,
+      "check": "Window the extents, compute the scrollToIndex offset (sectioned: data index → row), group the sections, pin the sticky header: equal to `expected`."
+    },
+    {
+      "id": "animations",
+      "files": [
+        "fixtures/animations.json"
+      ],
+      "unit": "theme × animation",
+      "cases": 38,
+      "check": "Time each animation under the theme and sample its frames (and the reduced-motion frame): equal to `expected` within 1e-3; `opacity`: the painted opacity = the node's own × the frame's, within 1e-3."
+    }
+  ]
+}

package/conformance/parity-compare.ts

@@ -0,0 +1,191 @@
+// FEED-128: the PURE half of the web parity check (parity.ts drives the
+// browser): the serialised DOM shape, generated-id normalisation, and the
+// first-difference finders for DOM, computed style and frames. No browser,
+// no I/O: parity.test.ts locks them on hand-written inputs.
+
+/** One serialised DOM node: an element (`t` tag, `a` attributes sorted by
+ *  name, `c` children) or a text node (`x`). Comments are dropped. */
+export type DomNode = { t: string; a: [string, string][]; c: DomNode[] } | { x: string }
+
+/** The attributes whose values are element ids (space-separated lists for
+ *  the ARIA relations). Only these are normalised. */
+export const ID_ATTRIBUTES = new Set([`id`, `for`, `name`, `aria-controls`, `aria-labelledby`, `aria-describedby`, `aria-owns`, `aria-activedescendant`, `aria-errormessage`, `aria-details`, `aria-flowto`, `list`, `form`])
+
+/** A GENERATED id token: React `useId` (`:r1:`, `«r1»`, `_r_1_`), anything
+ *  Radix derives (`radix-…`), Solid / Kobalte `createUniqueId` (`cl-12…`). */
+export const GENERATED_ID_PATTERNS: readonly RegExp[] = [/radix-/, /:r[0-9a-z]+:/, /«r[0-9a-z]+»/, /(^|[^0-9A-Za-z])_r_[0-9a-z]+_/, /(^|[^0-9A-Za-z])cl-\d+/]
+
+export const isGeneratedId = (token: string): boolean => GENERATED_ID_PATTERNS.some((re) => re.test(token))
+
+/** A copy of the tree with every generated id token in an id attribute
+ *  replaced by `#id-N`, N = first-seen order (document order, attributes by
+ *  name): the same token always maps to the same N, so a relation still
+ *  points at its target after normalisation. */
+export function normalizeIds(roots: DomNode[]): DomNode[] {
+  const seen = new Map<string, string>()
+  const map = (token: string) => {
+    if (!isGeneratedId(token)) return token
+    let out = seen.get(token)
+    if (!out) seen.set(token, (out = `#id-${seen.size + 1}`))
+    return out
+  }
+  const walk = (n: DomNode): DomNode => {
+    if (`x` in n) return n
+    return { t: n.t, a: n.a.map(([k, v]) => [k, ID_ATTRIBUTES.has(k) ? v.split(/(\s+)/).map((p) => (p.trim() ? map(p) : p)).join(``) : v]), c: n.c.map(walk) }
+  }
+  return roots.map(walk)
+}
+
+export interface DomDiff {
+  /** `0/div[0]/span[2]` (surface index, then element children by tag +
+   *  index among ALL children), `@attr` / `#text` for the differing part. */
+  path: string
+  reference: string
+  candidate: string
+}
+
+const describe = (n: DomNode | undefined): string => (n === undefined ? `(nothing)` : `x` in n ? `#text ${JSON.stringify(n.x)}` : `<${n.t}>`)
+
+/** The FIRST difference between two serialised trees in document order. */
+export function firstDomDiff(reference: DomNode[], candidate: DomNode[]): DomDiff | undefined {
+  const visit = (a: DomNode | undefined, b: DomNode | undefined, path: string): DomDiff | undefined => {
+    if (a === undefined || b === undefined || `x` in a !== `x` in b) return { path, reference: describe(a), candidate: describe(b) }
+    if (`x` in a && `x` in b) return a.x === b.x ? undefined : { path: `${path}#text`, reference: a.x, candidate: b.x }
+    const ea = a as Extract<DomNode, { t: string }>
+    const eb = b as Extract<DomNode, { t: string }>
+    if (ea.t !== eb.t) return { path, reference: describe(ea), candidate: describe(eb) }
+    const names = [...new Set([...ea.a.map(([k]) => k), ...eb.a.map(([k]) => k)])].sort()
+    const av = new Map(ea.a)
+    const bv = new Map(eb.a)
+    for (const k of names) if (av.get(k) !== bv.get(k)) return { path: `${path}@${k}`, reference: av.has(k) ? av.get(k)! : `(absent)`, candidate: bv.has(k) ? bv.get(k)! : `(absent)` }
+    for (let i = 0; i < Math.max(ea.c.length, eb.c.length); i++) {
+      const child = ea.c[i] ?? eb.c[i]!
+      const d = visit(ea.c[i], eb.c[i], `${path}/${`x` in child ? `#text` : child.t}[${i}]`)
+      if (d) return d
+    }
+    return undefined
+  }
+  for (let i = 0; i < Math.max(reference.length, candidate.length); i++) {
+    const d = visit(reference[i], candidate[i], String(i))
+    if (d) return d
+  }
+  return undefined
+}
+
+/** One compared element: its key (`data-xui-id`, or `<owner id>/<part>` for
+ *  an overlay part without its own id), the computed-style values in
+ *  `StyleTable.properties` order, and its frame. */
+export interface ElementProbe {
+  key: string
+  values: string[]
+  frame: { x: number; y: number; w: number; h: number }
+}
+
+export interface StyleTable {
+  properties: string[]
+  elements: ElementProbe[]
+}
+
+export interface StyleDiff {
+  id: string
+  property: string
+  reference: string
+  candidate: string
+}
+
+export interface FrameDiff {
+  id: string
+  key: `x` | `y` | `w` | `h` | `element`
+  reference: number | string
+  candidate: number | string
+}
+
+/** The element lists must line up key for key; the first mismatch is the
+ *  difference (`property: "(element)"`). */
+function elementMismatch(a: StyleTable, b: StyleTable): { index: number; reference: string; candidate: string } | undefined {
+  for (let i = 0; i < Math.max(a.elements.length, b.elements.length); i++) {
+    const ka = a.elements[i]?.key
+    const kb = b.elements[i]?.key
+    if (ka !== kb) return { index: i, reference: ka ?? `(nothing)`, candidate: kb ?? `(nothing)` }
+  }
+  return undefined
+}
+
+/** The FIRST computed-style difference (element order, then property order). */
+export function firstStyleDiff(a: StyleTable, b: StyleTable): StyleDiff | undefined {
+  const props = [...new Set([...a.properties, ...b.properties])]
+  const ia = new Map(a.properties.map((p, i) => [p, i]))
+  const ib = new Map(b.properties.map((p, i) => [p, i]))
+  const n = Math.min(a.elements.length, b.elements.length)
+  const mismatch = elementMismatch(a, b)
+  const upto = mismatch ? mismatch.index : n
+  for (let i = 0; i < upto; i++) {
+    const ea = a.elements[i]!
+    const eb = b.elements[i]!
+    for (const p of props) {
+      const va = ia.has(p) ? (ea.values[ia.get(p)!] ?? `(absent)`) : `(absent)`
+      const vb = ib.has(p) ? (eb.values[ib.get(p)!] ?? `(absent)`) : `(absent)`
+      if (va !== vb) return { id: ea.key, property: p, reference: va, candidate: vb }
+    }
+  }
+  if (mismatch) return { id: `#${mismatch.index}`, property: `(element)`, reference: mismatch.reference, candidate: mismatch.candidate }
+  return undefined
+}
+
+/** The FIRST frame difference, exact (0 px tolerance). */
+export function firstFrameDiff(a: StyleTable, b: StyleTable): FrameDiff | undefined {
+  const mismatch = elementMismatch(a, b)
+  const upto = mismatch ? mismatch.index : Math.min(a.elements.length, b.elements.length)
+  for (let i = 0; i < upto; i++) {
+    const fa = a.elements[i]!.frame
+    const fb = b.elements[i]!.frame
+    for (const k of [`x`, `y`, `w`, `h`] as const) if (fa[k] !== fb[k]) return { id: a.elements[i]!.key, key: k, reference: fa[k], candidate: fb[k] }
+  }
+  if (mismatch) return { id: `#${mismatch.index}`, key: `element`, reference: mismatch.reference, candidate: mismatch.candidate }
+  return undefined
+}
+
+/** A case id → a file-name-safe slug. */
+export const caseSlug = (id: string): string => id.replace(/[^A-Za-z0-9._-]+/g, `_`)
+
+// ---------------------------------------------------------------------------
+// The report (parity-report.schema.json)
+// ---------------------------------------------------------------------------
+
+export const PARITY_FORMAT = `xui-web-parity/1`
+
+export interface ParityCaseResult {
+  case: string
+  ok: boolean
+  elapsedMs: number
+  /** A page error, a timeout: the case could not be compared. */
+  error?: string
+  dom?: DomDiff
+  style?: StyleDiff
+  frame?: FrameDiff
+  pixels?: { differing: number; size: string; referencePng?: string; candidatePng?: string; diffPng?: string }
+}
+
+export interface ParityReport {
+  format: typeof PARITY_FORMAT
+  reference: string
+  candidate: string
+  chromium: string
+  startedAt: string
+  elapsedMs: number
+  summary: { cases: number; passed: number; failed: number; byGroup: Record<string, { cases: number; passed: number }> }
+  cases: ParityCaseResult[]
+}
+
+/** Every problem of a parity report (empty = parity). */
+export function checkParityReport(report: ParityReport): string[] {
+  const problems: string[] = []
+  if (report.format !== PARITY_FORMAT) problems.push(`format ${String(report.format)}, want ${PARITY_FORMAT}`)
+  if (!Array.isArray(report.cases) || report.cases.length === 0) problems.push(`no cases`)
+  for (const c of report.cases ?? []) {
+    if (c.ok) continue
+    const what = c.error ? `error ${c.error.split(`\n`)[0]}` : [c.dom && `dom ${c.dom.path}`, c.style && `style ${c.style.id} ${c.style.property}`, c.frame && `frame ${c.frame.id}.${c.frame.key}`, c.pixels?.differing && `${c.pixels.differing} px`].filter(Boolean).join(`, `)
+    problems.push(`${c.case}: ${what}`)
+  }
+  return problems
+}

package/conformance/parity-report.schema.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ui.exponential.at/conformance/parity-report.schema.json",
+  "title": "Exponential UI web parity report",
+  "description": "FEED-128: what conformance/parity.ts runParity() writes: a candidate web renderer against the reference (React) in one headless Chromium, every case compared exactly on DOM (generated ids normalised), computed style, frames and pixels. parity:check passes only when every case is ok. A web-only gate, not a manifest suite.",
+  "type": "object",
+  "required": ["format", "reference", "candidate", "chromium", "startedAt", "elapsedMs", "summary", "cases"],
+  "properties": {
+    "format": { "const": "xui-web-parity/1" },
+    "reference": { "type": "string", "description": "The reference renderer's name (react)." },
+    "candidate": { "type": "string", "description": "The candidate renderer's name (solid; react for the self-check)." },
+    "chromium": { "type": "string", "description": "The browser build and its settings." },
+    "startedAt": { "type": "string", "description": "ISO 8601." },
+    "elapsedMs": { "type": "number" },
+    "summary": {
+      "type": "object",
+      "required": ["cases", "passed", "failed", "byGroup"],
+      "properties": {
+        "cases": { "type": "integer" },
+        "passed": { "type": "integer" },
+        "failed": { "type": "integer" },
+        "byGroup": {
+          "type": "object",
+          "description": "matrix | specimen | state | overlay | primitive",
+          "additionalProperties": { "type": "object", "required": ["cases", "passed"], "properties": { "cases": { "type": "integer" }, "passed": { "type": "integer" } } }
+        }
+      }
+    },
+    "cases": { "type": "array", "items": { "$ref": "#/$defs/case" } }
+  },
+  "$defs": {
+    "case": {
+      "type": "object",
+      "required": ["case", "ok", "elapsedMs"],
+      "properties": {
+        "case": { "type": "string", "description": "matrix:<conformance key> | specimen:<id> | state:<id>:<state> | overlay:<n> | primitive:<id>:<theme>-<mode>[:hover|focus]" },
+        "ok": { "type": "boolean" },
+        "elapsedMs": { "type": "number", "description": "Both pages opened, settled, compared." },
+        "error": { "type": "string", "description": "The case could not be compared (page error, timeout)." },
+        "dom": {
+          "type": "object",
+          "description": "The FIRST DOM difference: path = surface index / tag[child index]…, @attr or #text for the differing part.",
+          "required": ["path", "reference", "candidate"],
+          "properties": { "path": { "type": "string" }, "reference": { "type": "string" }, "candidate": { "type": "string" } }
+        },
+        "style": {
+          "type": "object",
+          "description": "The FIRST computed-style difference: id = data-xui-id (or <owner>/<part> in an overlay, #<index> + property (element) when the element lists do not line up).",
+          "required": ["id", "property", "reference", "candidate"],
+          "properties": { "id": { "type": "string" }, "property": { "type": "string" }, "reference": { "type": "string" }, "candidate": { "type": "string" } }
+        },
+        "frame": {
+          "type": "object",
+          "description": "The FIRST getBoundingClientRect difference (0 px tolerance).",
+          "required": ["id", "key", "reference", "candidate"],
+          "properties": { "id": { "type": "string" }, "key": { "enum": ["x", "y", "w", "h", "element"] }, "reference": { "type": ["number", "string"] }, "candidate": { "type": ["number", "string"] } }
+        },
+        "pixels": {
+          "type": "object",
+          "description": "Full-page screenshots through pixelmatch (threshold 0, AA excluded); a size mismatch counts the larger area. The PNGs are written only when pixels differ.",
+          "required": ["differing", "size"],
+          "properties": {
+            "differing": { "type": "integer" },
+            "size": { "type": "string" },
+            "referencePng": { "type": "string" },
+            "candidatePng": { "type": "string" },
+            "diffPng": { "type": "string" }
+          }
+        }
+      }
+    }
+  }
+}