@exponential-at/ui 0.0.0-stage → 0.1.0

package/conformance/parity.ts

@@ -0,0 +1,412 @@
+// FEED-128: the deterministic WEB PARITY check. Two web renderers that claim
+// the same DOM + stylesheet contract (`@exponential-at/ui-react` is the
+// REFERENCE; `@exponential-at/ui-solid` the first candidate) are loaded side
+// by side in ONE headless Chromium — same viewport, device scale 1, the
+// conformance font set, reduced motion, animations and transitions off — and
+// every case is compared four ways, all EXACT:
+//   dom    the `.xui-surface` subtrees serialised (tag, attributes by name,
+//          text; adjacent text nodes MERGED, as the jsdom helper does: the
+//          HTML parser of Playwright's pinned Chromium splits an innerHTML
+//          text past 65 536 chars, React's `<style>`, where `textContent`
+//          keeps one node), generated ids normalised (parity-compare.ts);
+//   style  every `[data-xui-id]` element's (and every overlay part's) full
+//          computed style;
+//   (FEED-131: a PRIMITIVE case's page wears `data-xui-parity-root` on
+//   <body>: the dom is the whole body incl. its attributes, and EVERY
+//   element under it is compared, keyed by its path `body/div[0]/button[1]`);
+//   frame  the same elements' getBoundingClientRect, 0 px tolerance;
+//   pixels full-page screenshots through pixelmatch (threshold 0, AA
+//          excluded): 0 differing pixels.
+// Not a manifest suite (the natives' reports keep the manifest's list): a
+// web-only gate with its own report (parity-report.schema.json), checked by
+// `bun run --filter @exponential-at/ui parity:check <report.json>`.
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import pixelmatch from "pixelmatch"
+import sharp from "sharp"
+import type { Browser, BrowserContext, Page } from "playwright"
+import { allCases, caseInput, fontFaceCss, fontFiles, MANIFEST_PATH, type ConformanceManifest, type FontManifest } from "./dump"
+import { launchChromium, pageUrl, type Query, type RunningHarness, type WebHarness } from "./browser-page"
+import { caseSlug, firstDomDiff, firstFrameDiff, firstStyleDiff, normalizeIds, PARITY_FORMAT, type DomNode, type ParityCaseResult, type ParityReport, type StyleTable } from "./parity-compare"
+
+export * from "./parity-compare"
+
+const repoRoot = join(import.meta.dirname, `..`, `..`, `..`)
+const fixturesDir = join(import.meta.dirname, `..`, `fixtures`)
+
+/** The forced states every control specimen is re-dumped in (`data-xs` on
+ *  every `[data-xui-part]`; the recipe sheet honours `[data-xs~=state]`). */
+export const FORCED_STATES = [`hover`, `focus`, `pressed`, `checked`, `open`, `disabled`, `invalid`] as const
+
+/** The specimens whose component is a CONTROL (control-geometry.json's
+ *  interactive set): they get the forced-state cases. */
+export const CONTROL_COMPONENTS = [`Button`, `Toggle`, `Segmented`, `Input`, `Textarea`, `Select`, `DatePicker`, `Checkbox`, `Radio`, `Switch`, `Slider`, `Tabs`, `NumberField`, `ChipInput`, `TimePicker`, `DateRangePicker`]
+
+export interface ParityCase {
+  /** `matrix:<conformance key>`, `specimen:<id>`, `state:<id>:<state>`,
+   *  `overlay:<n>`, `primitive:<id>:<theme>-<mode>[:<interact>]`. */
+  id: string
+  group: `matrix` | `specimen` | `state` | `overlay` | `primitive`
+  query: Query
+  viewport: { width: number; height: number }
+  /** A forced state written onto every part before the dump. */
+  state?: string
+  /** An overlay case: wait for `window.__xuiOverlay()` to place it. */
+  overlay?: boolean
+  /** A primitive specimen that opens an overlay on mount: wait for
+   *  `window.__xuiOverlay?.()` (when the page defines it), then two frames. */
+  open?: boolean
+  /** Hover / focus the FIRST `[data-xui-target]` inside the specimen
+   *  before the dump (primitive cases). */
+  interact?: `hover` | `focus`
+}
+
+/** One `primitive-specimens.json` row (FEED-131). */
+export interface PrimitiveSpecimen {
+  /** `<primitive>/<variant>`. */
+  id: string
+  /** The harness module owning it (`harness/primitives/<primitive>.tsx`). */
+  primitive: string
+  viewport: { width: number; height: number }
+  open: boolean
+  interact: `hover` | `focus` | null
+}
+
+/** The theme × mode pairs every primitive specimen runs in. */
+export const PRIMITIVE_THEMES: readonly { theme: string; mode: `light` | `dark` }[] = [
+  { theme: `exponential`, mode: `light` },
+  { theme: `orange`, mode: `dark` },
+]
+
+/** The primitive cases alone (group `primitive`): every specimen × PRIMITIVE_THEMES,
+ *  plus its `interact` variant when the row names one. */
+export function primitiveCases(specimens: readonly PrimitiveSpecimen[] = fixture<{ specimens: PrimitiveSpecimen[] }>(`primitive-specimens.json`).specimens): ParityCase[] {
+  const out: ParityCase[] = []
+  for (const s of specimens)
+    for (const { theme, mode } of PRIMITIVE_THEMES) {
+      const base: ParityCase = { id: `primitive:${s.id}:${theme}-${mode}`, group: `primitive`, query: { view: `primitives`, id: s.id, theme, mode, width: s.viewport.width }, viewport: s.viewport }
+      if (s.open) base.open = true
+      out.push(base)
+      if (s.interact) out.push({ ...base, id: `${base.id}:${s.interact}`, interact: s.interact })
+    }
+  return out
+}
+
+
+
+export interface ParityOptions {
+  reference: WebHarness
+  candidate: WebHarness
+  /** Report names (default `reference` / `candidate`). */
+  names?: { reference?: string; candidate?: string }
+  /** Default: `parityCases()`. */
+  cases?: ParityCase[]
+  /** Extra Chromium flags (always PARITY_CHROMIUM_ARGS) and an
+   *  executable (default `EXPONENTIAL_UI_CHROME`, else Playwright's). */
+  chrome?: { args?: string[]; executablePath?: string }
+  /** Where differing screenshots land (default <repo>/.conformance/parity). */
+  outDir?: string
+  /** Cases compared at once (default 4). */
+  concurrency?: number
+  log?: (line: string) => void
+}
+
+/** Chromium for exact pixels: unhinted fractional glyph advances, and
+ *  DETERMINISTIC raster (software, whole-tile, sRGB, grayscale AA): without
+ *  `--disable-partial-raster` + `--disable-gpu` a composited layer's
+ *  anti-aliased rounded corners (a carousel scroller, an open drawer) come
+ *  out ±1 level between two loads of the SAME page now and then. */
+export const PARITY_CHROMIUM_ARGS = [`--font-render-hinting=none`, `--disable-gpu`, `--disable-partial-raster`, `--force-color-profile=srgb`, `--disable-lcd-text`]
+
+const fixture = <T>(name: string) => JSON.parse(readFileSync(join(fixturesDir, name), `utf8`)) as T
+const repoJson = async (path: string) => JSON.parse(readFileSync(join(repoRoot, path), `utf8`)) as unknown
+
+/** Every parity case: the conformance matrix (fixtures × themes × modes ×
+ *  widths × directions, each through the harness's `?view=tree` with the
+ *  case's tree + data exactly as the conformance page builds them), every
+ *  specimen at `specimenWidth`, the control specimens in each forced state,
+ *  every overlay-geometry case with its overlay open, and the primitive
+ *  specimens (`primitiveCases`). */
+export async function parityCases(opts: { specimenWidth?: number; states?: readonly string[]; controls?: readonly string[] } = {}): Promise<ParityCase[]> {
+  const out: ParityCase[] = []
+  const manifest = (await repoJson(MANIFEST_PATH)) as ConformanceManifest
+  const inputs = new Map<string, { tree: string; data: string }>()
+  for (const c of allCases(manifest)) {
+    // The tree + data depend on the fixture and the direction only.
+    const k = `${c.fixture}/${c.direction}`
+    if (!inputs.has(k)) {
+      const { tree, data } = await caseInput(manifest, c, repoJson)
+      inputs.set(k, { tree: JSON.stringify(tree), data: JSON.stringify(data) })
+    }
+    const input = inputs.get(k)!
+    out.push({ id: `matrix:${c.key}`, group: `matrix`, query: { view: `tree`, tree: input.tree, data: input.data, theme: c.theme, mode: c.mode, width: c.width, dir: c.direction, locale: manifest.locale }, viewport: { width: c.width, height: 900 } })
+  }
+  const width = opts.specimenWidth ?? 900
+  const specimens = fixture<{ specimens: { id: string; component?: string }[] }>(`specimens.json`).specimens
+  const query = (id: string): Query => ({ view: `specimen`, id, theme: `exponential`, mode: `light`, width })
+  for (const s of specimens) out.push({ id: `specimen:${s.id}`, group: `specimen`, query: query(s.id), viewport: { width, height: 900 } })
+  const controls = new Set(opts.controls ?? CONTROL_COMPONENTS)
+  for (const s of specimens.filter((s) => s.component && controls.has(s.component)))
+    for (const state of opts.states ?? FORCED_STATES) out.push({ id: `state:${s.id}:${state}`, group: `state`, query: query(s.id), viewport: { width, height: 900 }, state })
+  const overlays = fixture<{ cases: { name: string; viewport: { width: number; height: number } }[] }>(`overlay-geometry.json`).cases
+  for (const [i, c] of overlays.entries()) out.push({ id: `overlay:${i}`, group: `overlay`, query: { view: `overlay`, case: i }, viewport: c.viewport, overlay: true })
+  out.push(...primitiveCases())
+  return out
+}
+
+/** The in-page probe (a string, so no transpiler helper leaks into it):
+ *  `window.__xuiParity` = { dom, table, values, force }. */
+const PROBE = `(() => {
+  const rooted = () => !!document.body && document.body.hasAttribute('data-xui-parity-root');
+  const skipped = (el) => el.tagName === 'SCRIPT' || (el.tagName === 'STYLE' && el.hasAttribute('data-xui-parity'));
+  const surfaces = () => rooted() ? [document.body] : Array.from(document.querySelectorAll('.xui-surface')).filter((s) => !s.parentElement || !s.parentElement.closest('.xui-surface'));
+  const ser = (n) => {
+    if (n.nodeType === 3) return n.data.length ? { x: n.data } : null;
+    if (n.nodeType !== 1) return null;
+    if (rooted() && skipped(n)) return null;
+    const a = Array.from(n.attributes).map((x) => [x.name, x.value]).sort((p, q) => (p[0] < q[0] ? -1 : p[0] > q[0] ? 1 : 0));
+    const c = [];
+    for (const k of Array.from(n.childNodes)) {
+      const s = ser(k);
+      if (!s) continue;
+      const last = c[c.length - 1];
+      if (s.x !== undefined && last && last.x !== undefined) last.x += s.x;
+      else c.push(s);
+    }
+    return { t: n.tagName.toLowerCase(), a, c };
+  };
+  const compared = () => {
+    const out = [];
+    if (rooted()) {
+      const walk = (el, key) => {
+        out.push([key, el]);
+        let i = 0;
+        for (const k of Array.from(el.children)) if (!skipped(k)) walk(k, key + '/' + k.tagName.toLowerCase() + '[' + i++ + ']');
+      };
+      walk(document.body, 'body');
+      return out;
+    }
+    for (const s of surfaces()) for (const el of [s, ...Array.from(s.querySelectorAll('*'))]) {
+      const id = el.getAttribute('data-xui-id');
+      if (id !== null) { out.push([id, el]); continue; }
+      const part = el.getAttribute('data-xui-part');
+      if (part !== null && el.closest('[data-xui-layer]')) {
+        const owner = el.parentElement && el.parentElement.closest('[data-xui-id]');
+        out.push([(owner ? owner.getAttribute('data-xui-id') : '') + '/' + part, el]);
+      }
+    }
+    return out;
+  };
+  // Sorted on a primitive page: its :root carries custom properties, which
+  // Chromium enumerates in a per-document order (the hash is order-bound).
+  const properties = () => { const p = Array.from(getComputedStyle(document.documentElement)); return rooted() ? p.sort() : p; };
+  const hash = (str) => {
+    let h1 = 0xdeadbeef, h2 = 0x41c6ce57;
+    for (let i = 0; i < str.length; i++) { const ch = str.charCodeAt(i); h1 = Math.imul(h1 ^ ch, 2654435761); h2 = Math.imul(h2 ^ ch, 1597334677); }
+    h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+    h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+    return (h2 >>> 0).toString(16) + (h1 >>> 0).toString(16);
+  };
+  const valuesOf = (el, props) => { const cs = getComputedStyle(el); return props.map((p) => cs.getPropertyValue(p)); };
+  window.__xuiParity = {
+    dom: () => surfaces().map(ser),
+    table: () => {
+      const props = properties();
+      return { properties: ['(hash)'], count: props.length, elements: compared().map(([key, el]) => {
+        const r = el.getBoundingClientRect();
+        return { key, values: [hash(valuesOf(el, props).join('\\u0001'))], frame: { x: r.x, y: r.y, w: r.width, h: r.height } };
+      }) };
+    },
+    values: (i) => { const props = properties(); const e = compared()[i]; return { properties: props, elements: e ? [{ key: e[0], values: valuesOf(e[1], props), frame: { x: 0, y: 0, w: 0, h: 0 } }] : [] }; },
+    force: (state) => {
+      for (const s of surfaces()) for (const el of Array.from(s.querySelectorAll('[data-xui-part]'))) {
+        const prev = el.getAttribute('data-xs');
+        el.setAttribute('data-xs', prev ? prev + ' ' + state : state);
+      }
+    },
+  };
+})()`
+
+/** Motion off, applied identically to both pages AFTER the surface's own
+ *  sheets (and `!important`, so no rule of theirs wins). */
+const STILL_CSS = `*,*::before,*::after{animation:none!important;transition:none!important;caret-color:transparent!important}`
+
+const frames = (page: Page, n = 2) => page.evaluate(`new Promise((r) => { const step = (k) => (k <= 0 ? r(null) : requestAnimationFrame(() => step(k - 1))); step(${n}) })`)
+
+interface Side {
+  page: Page
+  context: BrowserContext
+  errors: string[]
+}
+
+async function openSide(browser: Browser, baseUrl: string, c: ParityCase, fontCss: string, fontAllow: Set<string>): Promise<Side> {
+  const context = await browser.newContext({ viewport: c.viewport, deviceScaleFactor: 1, locale: `en-US`, reducedMotion: `reduce`, timezoneId: `UTC` })
+  // Offline: the harness answers, the font set is served off disk, the
+  // fixtures' example.com media fail the same way on both sides.
+  await context.route(`**/*`, async (route) => {
+    const url = new URL(route.request().url())
+    if (url.pathname.startsWith(`/__xui-parity/fonts/`)) {
+      const rel = decodeURIComponent(url.pathname.slice(`/__xui-parity/fonts/`.length))
+      if (!fontAllow.has(rel)) return route.abort()
+      return route.fulfill({ status: 200, contentType: `font/ttf`, body: readFileSync(join(repoRoot, rel)) })
+    }
+    if (!route.request().url().startsWith(baseUrl)) return route.abort()
+    // The page request goes out WITHOUT its query (a tree in the URL is far
+    // longer than a server's request line): the harness serves one page for
+    // every query and the page still reads its own `location.search`.
+    if (route.request().isNavigationRequest() && url.search) return route.continue({ url: `${baseUrl}${url.pathname}` })
+    return route.continue()
+  })
+  // The font set, before the bundle runs (documentElement may not exist yet).
+  await context.addInitScript({
+    content: `(() => { const add = () => { if (!document.documentElement) return false; const s = document.createElement('style'); s.setAttribute('data-xui-parity', 'fonts'); s.textContent = ${JSON.stringify(fontCss)}; document.documentElement.appendChild(s); return true; }; if (!add()) { const mo = new MutationObserver(() => { if (add()) mo.disconnect(); }); mo.observe(document, { childList: true }); } })()`,
+  })
+  const page = await context.newPage()
+  const errors: string[] = []
+  page.on(`pageerror`, (e) => errors.push(String(e)))
+  page.on(`console`, (m) => {
+    if (m.type() === `error` && !m.text().startsWith(`Failed to load resource`)) errors.push(m.text())
+  })
+  await page.goto(pageUrl(baseUrl, c.query))
+  const primitive = c.group === `primitive`
+  await page.waitForSelector(primitive ? `body[data-xui-parity-root] [data-xui-specimen]` : `.xui-surface [data-xui-id]`, { state: `attached`, timeout: 30_000 })
+  await page.evaluate(`(() => { const s = document.createElement('style'); s.setAttribute('data-xui-parity', 'still'); s.textContent = ${JSON.stringify(STILL_CSS)}; document.body.appendChild(s); })()`)
+  await page.evaluate(`Promise.all(Array.from(document.fonts).map((f) => f.load().catch(() => undefined))).then(() => document.fonts.ready)`)
+  if (c.overlay) await page.waitForFunction(`typeof window.__xuiOverlay === 'function' && window.__xuiOverlay() !== null`, undefined, { timeout: 30_000 })
+  if (c.open) await page.waitForFunction(`typeof window.__xuiOverlay !== 'function' || window.__xuiOverlay() !== null`, undefined, { timeout: 30_000 })
+  await frames(page, 2)
+  await page.evaluate(PROBE)
+  if (c.state) {
+    await page.evaluate(`window.__xuiParity.force(${JSON.stringify(c.state)})`)
+    await frames(page, 2)
+  }
+  if (c.interact) {
+    const target = page.locator(`[data-xui-specimen] [data-xui-target]`).first()
+    await (c.interact === `hover` ? target.hover({ force: true }) : target.focus())
+    await frames(page, 2)
+  }
+  return { page, context, errors }
+}
+
+async function raster(png: Buffer): Promise<{ width: number; height: number; data: Uint8Array }> {
+  const { data, info } = await sharp(png).ensureAlpha().raw().toBuffer({ resolveWithObject: true })
+  return { width: info.width, height: info.height, data: new Uint8Array(data.buffer, data.byteOffset, data.length) }
+}
+
+async function compareCase(browser: Browser, ref: RunningHarness, cand: RunningHarness, c: ParityCase, fontCss: string, fontAllow: Set<string>, outDir: string): Promise<ParityCaseResult> {
+  const started = Date.now()
+  const result: ParityCaseResult = { case: c.id, ok: false, elapsedMs: 0 }
+  const sides: Side[] = []
+  try {
+    const [a, b] = await Promise.all([openSide(browser, ref.baseUrl, c, fontCss, fontAllow), openSide(browser, cand.baseUrl, c, fontCss, fontAllow)])
+    sides.push(a, b)
+    const errs = [...a.errors.map((e) => `reference: ${e}`), ...b.errors.map((e) => `candidate: ${e}`)]
+    if (errs.length) throw new Error(`page errors:\n${errs.join(`\n`)}`)
+    const [domA, domB] = (await Promise.all([a.page.evaluate(`window.__xuiParity.dom()`), b.page.evaluate(`window.__xuiParity.dom()`)])) as [DomNode[], DomNode[]]
+    result.dom = firstDomDiff(normalizeIds(domA), normalizeIds(domB))
+    const [tA, tB] = (await Promise.all([a.page.evaluate(`window.__xuiParity.table()`), b.page.evaluate(`window.__xuiParity.table()`)])) as [StyleTable, StyleTable]
+    const hashDiff = firstStyleDiff(tA, tB)
+    if (hashDiff && hashDiff.property === `(hash)`) {
+      // The first element whose computed style differs: its full values.
+      const i = tA.elements.findIndex((e, k) => e.values[0] !== tB.elements[k]?.values[0])
+      const [vA, vB] = (await Promise.all([a.page.evaluate(`window.__xuiParity.values(${i})`), b.page.evaluate(`window.__xuiParity.values(${i})`)])) as [StyleTable, StyleTable]
+      result.style = firstStyleDiff(vA, vB) ?? hashDiff
+    } else if (hashDiff) result.style = hashDiff
+    result.frame = firstFrameDiff(tA, tB)
+    // Native <video>/<audio> boxes are MASKED (same colour on both sides):
+    // the browser's own media controls run a loading spinner in the UA
+    // shadow root no author CSS stops; their DOM, style and frames are still
+    // compared above.
+    const shot = (p: Page) => p.screenshot({ fullPage: true, animations: `disabled`, caret: `hide`, mask: [p.locator(`.xui-surface video, .xui-surface audio, [data-xui-specimen] video, [data-xui-specimen] audio`)], maskColor: `#ff00ff` })
+    const [pA, pB] = await Promise.all([shot(a.page), shot(b.page)])
+    const [rA, rB] = await Promise.all([raster(pA), raster(pB)])
+    const size = `${rA.width}x${rA.height}`
+    let differing: number
+    let diff: Uint8Array | undefined
+    if (rA.width !== rB.width || rA.height !== rB.height) differing = Math.max(rA.width * rA.height, rB.width * rB.height)
+    else if (Buffer.from(rA.data).equals(Buffer.from(rB.data))) differing = 0
+    else {
+      diff = new Uint8Array(rA.data.length)
+      differing = pixelmatch(rA.data, rB.data, diff, rA.width, rA.height, { threshold: 0, includeAA: false })
+    }
+    result.pixels = { differing, size: rA.width === rB.width && rA.height === rB.height ? size : `${size} vs ${rB.width}x${rB.height}` }
+    if (differing > 0) {
+      mkdirSync(outDir, { recursive: true })
+      const base = join(outDir, caseSlug(c.id))
+      writeFileSync(`${base}.ref.png`, pA)
+      writeFileSync(`${base}.cand.png`, pB)
+      result.pixels.referencePng = `${base}.ref.png`
+      result.pixels.candidatePng = `${base}.cand.png`
+      if (diff) {
+        await sharp(Buffer.from(diff), { raw: { width: rA.width, height: rA.height, channels: 4 } }).png().toFile(`${base}.diff.png`)
+        result.pixels.diffPng = `${base}.diff.png`
+      }
+    }
+    result.ok = !result.dom && !result.style && !result.frame && differing === 0
+  } catch (e) {
+    result.error = e instanceof Error ? e.message : String(e)
+  } finally {
+    await Promise.all(sides.map((s) => s.context.close().catch(() => undefined)))
+    result.elapsedMs = Date.now() - started
+  }
+  for (const k of [`dom`, `style`, `frame`] as const) if (result[k] === undefined) delete result[k]
+  return result
+}
+
+export async function runParity(options: ParityOptions): Promise<ParityReport> {
+  const started = Date.now()
+  const cases = options.cases ?? (await parityCases())
+  const manifest = (await repoJson(MANIFEST_PATH)) as ConformanceManifest
+  const fonts = (await repoJson(manifest.fonts)) as FontManifest
+  const fontAllow = new Set(fontFiles(fonts))
+  const fontCss = fontFaceCss(fonts, (file) => `/__xui-parity/fonts/${file}`)
+  const outDir = options.outDir ?? join(repoRoot, `.conformance`, `parity`)
+  const [ref, cand] = await Promise.all([options.reference.start(), options.candidate.start()])
+  let browser: Browser | undefined
+  let chromium = `?`
+  const results: ParityCaseResult[] = new Array(cases.length)
+  try {
+    const args = [...PARITY_CHROMIUM_ARGS, ...(options.chrome?.args ?? [])]
+    browser = await launchChromium(args, options.chrome?.executablePath)
+    chromium = browser.version()
+    const b = browser
+    let next = 0
+    let done = 0
+    const worker = async () => {
+      for (let i = next++; i < cases.length; i = next++) {
+        results[i] = await compareCase(b, ref, cand, cases[i]!, fontCss, fontAllow, outDir)
+        // A harness that went away mid-case (respawned by bunHarness): once more.
+        if (results[i]!.error?.includes(`ERR_CONNECTION_REFUSED`)) {
+          await new Promise((r) => setTimeout(r, 3000))
+          results[i] = await compareCase(b, ref, cand, cases[i]!, fontCss, fontAllow, outDir)
+        }
+        done += 1
+        const r = results[i]!
+        if (!r.ok || done % 25 === 0) options.log?.(`${done}/${cases.length} ${r.ok ? `ok  ` : `FAIL`} ${r.case} (${r.elapsedMs} ms)${r.ok ? `` : ` ${JSON.stringify({ error: r.error, dom: r.dom, style: r.style, frame: r.frame, pixels: r.pixels }).slice(0, 600)}`}`)
+      }
+    }
+    await Promise.all(Array.from({ length: Math.max(1, options.concurrency ?? 4) }, worker))
+  } finally {
+    await browser?.close()
+    await Promise.all([ref.stop(), cand.stop()])
+  }
+  const byGroup: Record<string, { cases: number; passed: number }> = {}
+  for (const [i, r] of results.entries()) {
+    const g = (byGroup[cases[i]!.group] ??= { cases: 0, passed: 0 })
+    g.cases += 1
+    if (r.ok) g.passed += 1
+  }
+  const passed = results.filter((r) => r.ok).length
+  return {
+    format: PARITY_FORMAT,
+    reference: options.names?.reference ?? `reference`,
+    candidate: options.names?.candidate ?? `candidate`,
+    chromium: `Chromium ${chromium} headless, ${PARITY_CHROMIUM_ARGS.join(` `)}, deviceScaleFactor 1, reduced motion`,
+    startedAt: new Date(started).toISOString(),
+    elapsedMs: Date.now() - started,
+    summary: { cases: results.length, passed, failed: results.length - passed, byGroup },
+    cases: results,
+  }
+}
+

package/conformance/pixel.ts

@@ -0,0 +1,177 @@
+// The PERCEPTUAL step of the conformance harness (reported, never gating):
+// per case, the web surface as Chromium paints it (the conformance page,
+// Playwright element screenshot, deviceScaleFactor 1) next to the gpui
+// painter in a REAL window under Xvfb (`conformance_dump --window`, wgpu on
+// the machine's Vulkan — lavapipe works — and a FONTCONFIG_FILE that lists
+// only the conformance fonts), compared over their common top-left area:
+// the share of pixels pixelmatch calls different (threshold 0.1) and a mean
+// SSIM over 8×8 luminance blocks. Files land in `<out>/pixels/`; nothing is
+// written under shots/ (the committed store shots stay with
+// packages/exponential-ui-react/scripts/shots.ts).
+
+import { spawnSync } from "node:child_process"
+import { existsSync, mkdirSync, readFileSync, symlinkSync, writeFileSync, rmSync } from "node:fs"
+import { basename, join } from "node:path"
+import pixelmatch from "pixelmatch"
+import sharp from "sharp"
+import { fontFiles, MANIFEST_PATH, type ConformanceManifest, type Dump, type FontManifest } from "./dump"
+
+export interface PixelRow {
+  key: string
+  diffRatio?: number
+  ssim?: number
+  size?: string
+  files?: string
+  note?: string
+}
+
+export interface Raster {
+  width: number
+  height: number
+  data: Uint8Array
+}
+
+async function load(path: string): Promise<Raster> {
+  const { data, info } = await sharp(path).ensureAlpha().raw().toBuffer({ resolveWithObject: true })
+  return { width: info.width, height: info.height, data: new Uint8Array(data.buffer, data.byteOffset, data.length) }
+}
+
+/** The top-left `w × h` of a raster. */
+export function crop(r: Raster, w: number, h: number): Raster {
+  const out = new Uint8Array(w * h * 4)
+  for (let y = 0; y < h; y++) out.set(r.data.subarray(y * r.width * 4, y * r.width * 4 + w * 4), y * w * 4)
+  return { width: w, height: h, data: out }
+}
+
+const luma = (d: Uint8Array, i: number) => 0.299 * d[i] + 0.587 * d[i + 1] + 0.114 * d[i + 2]
+
+/** Mean SSIM over non-overlapping 8×8 luminance blocks (same size inputs). */
+export function ssim(a: Raster, b: Raster, block = 8): number {
+  const c1 = (0.01 * 255) ** 2
+  const c2 = (0.03 * 255) ** 2
+  let sum = 0
+  let n = 0
+  for (let by = 0; by + block <= a.height; by += block)
+    for (let bx = 0; bx + block <= a.width; bx += block) {
+      let ma = 0
+      let mb = 0
+      for (let y = by; y < by + block; y++)
+        for (let x = bx; x < bx + block; x++) {
+          const i = (y * a.width + x) * 4
+          ma += luma(a.data, i)
+          mb += luma(b.data, i)
+        }
+      const k = block * block
+      ma /= k
+      mb /= k
+      let va = 0
+      let vb = 0
+      let cov = 0
+      for (let y = by; y < by + block; y++)
+        for (let x = bx; x < bx + block; x++) {
+          const i = (y * a.width + x) * 4
+          const da = luma(a.data, i) - ma
+          const db = luma(b.data, i) - mb
+          va += da * da
+          vb += db * db
+          cov += da * db
+        }
+      va /= k - 1
+      vb /= k - 1
+      cov /= k - 1
+      sum += ((2 * ma * mb + c1) * (2 * cov + c2)) / ((ma * ma + mb * mb + c1) * (va + vb + c2))
+      n++
+    }
+  return n ? sum / n : 1
+}
+
+/** Compare two PNGs over their common area; writes the pixelmatch diff. */
+export async function comparePngs(webPng: string, desktopPng: string, diffPng: string): Promise<{ diffRatio: number; ssim: number; size: string }> {
+  const a = await load(webPng)
+  const b = await load(desktopPng)
+  const w = Math.min(a.width, b.width)
+  const h = Math.min(a.height, b.height)
+  const ca = crop(a, w, h)
+  const cb = crop(b, w, h)
+  const diff = new Uint8Array(w * h * 4)
+  const changed = pixelmatch(ca.data, cb.data, diff, w, h, { threshold: 0.1 })
+  await sharp(Buffer.from(diff), { raw: { width: w, height: h, channels: 4 } })
+    .png()
+    .toFile(diffPng)
+  return { diffRatio: changed / (w * h), ssim: ssim(ca, cb), size: `web ${a.width}×${a.height} · gpui ${b.width}×${b.height} · compared ${w}×${h}` }
+}
+
+const has = (cmd: string) => spawnSync(`sh`, [`-c`, `command -v ${cmd}`]).status === 0
+
+/** A fontconfig root holding ONLY the conformance font files (+ the last resort). */
+function fontconfigDir(repoRoot: string, dir: string): string {
+  const manifest = JSON.parse(readFileSync(join(repoRoot, MANIFEST_PATH), `utf8`)) as ConformanceManifest
+  const fonts = JSON.parse(readFileSync(join(repoRoot, manifest.fonts), `utf8`)) as FontManifest
+  rmSync(dir, { recursive: true, force: true })
+  mkdirSync(join(dir, `fonts`), { recursive: true })
+  const files = fontFiles(fonts).map((f) => join(repoRoot, f))
+  for (const family of fonts.lastResort?.families ?? []) {
+    const r = spawnSync(`fc-match`, [`-f`, `%{family}\n%{file}`, family], { encoding: `utf8` })
+    const [found, file] = (r.stdout ?? ``).split(`\n`)
+    if (file && found?.split(`,`).some((f) => f.trim() === family)) {
+      files.push(file.trim())
+      break
+    }
+  }
+  for (const f of files) symlinkSync(f, join(dir, `fonts`, basename(f)))
+  const conf = join(dir, `fonts.conf`)
+  writeFileSync(conf, `<?xml version="1.0"?>\n<!DOCTYPE fontconfig SYSTEM "fonts.dtd">\n<fontconfig><dir>${join(dir, `fonts`)}</dir><cachedir>${join(dir, `cache`)}</cachedir></fontconfig>\n`)
+  return conf
+}
+
+export async function pixelStep(repoRoot: string, outDir: string, keys: string[]): Promise<PixelRow[]> {
+  const dir = join(outDir, `pixels`)
+  mkdirSync(dir, { recursive: true })
+  if (!keys.length) return []
+  // Web: the conformance page, one element screenshot per case.
+  const web = spawnSync(`bun`, [`scripts/conformance-web.ts`, `--keys`, keys.join(`,`), `--shots`, dir, `--out`, join(dir, `web-shots.json`)], { cwd: join(repoRoot, `packages/exponential-ui-react`), stdio: [`ignore`, `inherit`, `inherit`] })
+  const desktopDump = join(outDir, `desktop.json`)
+  const heights = existsSync(desktopDump) ? (JSON.parse(readFileSync(desktopDump, `utf8`)) as Dump).cases : {}
+  const missing = [`xvfb-run`, `xdotool`, `import`].filter((c) => !has(c))
+  const canDesktop = (process.platform === `linux` || process.platform === `freebsd`) && missing.length === 0
+  let built = false
+  if (canDesktop) built = spawnSync(`cargo`, [`build`, `-q`, `-p`, `exponential-ui-gpui`, `--example`, `conformance_dump`], { cwd: join(repoRoot, `apps/desktop`), stdio: [`ignore`, `inherit`, `inherit`] }).status === 0
+  const conf = canDesktop ? fontconfigDir(repoRoot, join(dir, `fontconfig`)) : ``
+  const rows: PixelRow[] = []
+  for (const key of keys) {
+    const slug = key.replaceAll(`/`, `_`)
+    const webPng = join(dir, `${slug}.web.png`)
+    if (web.status !== 0 || !existsSync(webPng)) {
+      rows.push({ key, note: `web screenshot failed` })
+      continue
+    }
+    if (!canDesktop) {
+      rows.push({ key, note: `desktop capture unavailable here (${missing.length ? `missing ${missing.join(`, `)}` : process.platform}); web shot ${webPng}` })
+      continue
+    }
+    if (!built) {
+      rows.push({ key, note: `the conformance_dump example did not build` })
+      continue
+    }
+    const width = Number(key.split(`/`)[3])
+    const height = Math.min(8000, Math.ceil(heights[key]?.height ?? 2000))
+    const deskPng = join(dir, `${slug}.desktop.png`)
+    rmSync(deskPng, { force: true })
+    // The window presents its first frame on input: move the pointer once.
+    const script = [
+      `cargo run -q -p exponential-ui-gpui --example conformance_dump -- --window '${key}' --height ${height} & P=$!`,
+      `for i in $(seq 1 240); do W=$(xdotool search --name '^xui-conformance$' 2>/dev/null | head -1); [ -n "$W" ] && break; sleep 0.5; done`,
+      `sleep 3; xdotool mousemove ${width + 5} 5; sleep 1; xdotool mousemove ${width + 6} 6; sleep 2`,
+      `[ -n "$W" ] && import -window "$W" '${deskPng}'`,
+      `kill $P`,
+    ].join(`\n`)
+    const r = spawnSync(`xvfb-run`, [`-a`, `-s`, `-screen 0 ${width + 16}x${height + 16}x24 +extension RENDER +extension Composite`, `sh`, `-c`, script], { cwd: join(repoRoot, `apps/desktop`), env: { ...process.env, FONTCONFIG_FILE: conf }, encoding: `utf8`, timeout: 300_000 })
+    if (!existsSync(deskPng)) {
+      rows.push({ key, note: `desktop capture failed (xvfb-run exit ${r.status}): ${(r.stderr ?? ``).split(`\n`).filter((l) => l && !l.includes(`libEGL`)).slice(-3).join(` | `)}` })
+      continue
+    }
+    const m = await comparePngs(webPng, deskPng, join(dir, `${slug}.diff.png`))
+    rows.push({ key, ...m, files: `${slug}.{web,desktop,diff}.png` })
+  }
+  return rows
+}

package/conformance/primitives-page.ts

@@ -0,0 +1,49 @@
+// FEED-131: the framework-neutral half of both harnesses' `?view=primitives`
+// page (packages/exponential-ui-{react,solid}/harness/primitives/mount.tsx):
+//   ?view=primitives&id=<specimen>&theme=<id>&mode=light|dark&width=<px>
+// The <head> gets the unscoped shadcn variable block (`globalsCss`, `:root`
+// + `.dark`), the package's OWN compiled stylesheet (served by its
+// serve.ts at PRIMITIVES_SHEET_URL) and the page rules; `<html>` wears
+// `class="dark"` in dark mode; `<body>` wears `data-xui-parity-root` (the
+// web-parity probe then compares the WHOLE body) + `data-xui-mode`. The
+// caller renders `<div data-xui-specimen="<id>" style="padding:16px">` into
+// the returned container. Body inline style stays EMPTY (Radix writes it).
+
+import { builtinTheme } from "../src/themes"
+import { globalsCss } from "../src/web/theme-css"
+
+/** Where each harness's serve.ts answers with its package's dist stylesheet. */
+export const PRIMITIVES_SHEET_URL = `/dist/primitives.css`
+
+/** The page's own rules (no preflight in the sheet): body chrome only. */
+export const PRIMITIVES_PAGE_CSS = `body{margin:0;background:var(--background);color:var(--foreground);font-family:var(--font-sans)}`
+
+export interface PrimitivesPage {
+  id: string
+  mode: `light` | `dark`
+  container: HTMLElement
+}
+
+const style = (name: string, css: string) => {
+  const s = document.createElement(`style`)
+  s.setAttribute(`data-xui-primitives`, name)
+  s.textContent = css
+  document.head.appendChild(s)
+}
+
+/** Head styles + root attributes, then the stylesheet fetched and applied:
+ *  resolves once the page is ready to render the specimen. */
+export async function preparePrimitivesPage(params = new URLSearchParams(location.search)): Promise<PrimitivesPage> {
+  const id = params.get(`id`) ?? ``
+  const mode = params.get(`mode`) === `dark` ? `dark` : `light`
+  const theme = builtinTheme(params.get(`theme`) ?? `exponential`)
+  if (mode === `dark`) document.documentElement.classList.add(`dark`)
+  document.body.setAttribute(`data-xui-parity-root`, ``)
+  document.body.setAttribute(`data-xui-mode`, mode)
+  style(`globals`, globalsCss(theme))
+  const r = await fetch(PRIMITIVES_SHEET_URL)
+  if (!r.ok) throw new Error(`primitives: ${PRIMITIVES_SHEET_URL} answered ${r.status}`)
+  style(`sheet`, await r.text())
+  style(`page`, PRIMITIVES_PAGE_CSS)
+  return { id, mode, container: document.getElementById(`app`)! }
+}