create-pmos 0.52.0 → 0.53.1

package/workspace/design-parity.js

@@ -1,673 +0,0 @@
-#!/usr/bin/env node
-/* design-parity — decides whether the workspace matches the design the PM handed over.
- *
- * The PM's bar for this surface was one word: IDENTICAL. That is not a thing anyone can hold in
- * their head across four panels, two themes and ten interaction states, so it is decided here
- * mechanically instead. This renders the PM's own prototype and the built app side by side at the
- * same viewport with the same font files, and diffs them on four axes:
- *
- *   text      the ordered list of rendered text nodes — a reworded label is a failure
- *   style     computed styles on structurally-matched elements
- *   geometry  bounding boxes, to a 2px tolerance
- *   pixels    a screenshot diff, failing above 0.5% of the viewport
- *
- * WHY THE APP IS RENDERED IN FIXTURE MODE. A diff needs like-for-like content, and the app's real
- * content is this repository. `?fixture=proto` loads the prototype's own seed data through the app's
- * real renderer — so what is being compared is the rendering, which is the thing under test, and not
- * the data, which is not. The same fixture doubles as the offline demo path: it proves the UI draws
- * with no repository readable at all. What it deliberately does NOT prove is that the app is wired to
- * anything; that is dimension 2 of the rubric and it is asserted in ui-test.js against real state.
- *
- * OFFLINE BY CONSTRUCTION. The prototype's runtime fetches React from unpkg. Both files are vendored
- * under planning/design/four-panel/vendor/ and injected through the runtime's own `window.__resources`
- * override, and the Google Fonts link is rewritten to the workspace's own vendored woff2 — the same
- * byte-identical faces the app serves, so a font-fallback difference can never be mistaken for a
- * design difference. Babel is not vendored because the prototype does not need it (verified: the
- * render is node-for-node identical without it).
- *
- *   node design-parity.js --board=WsA      the cockpit mockup's Option A board (planning/design/cockpit-mockup/), dark, 1600x900,
- *                                          against `?fixture=cockpit`. This is `npm run test:parity` and the BLOCKING CI step.
- *   node design-parity.js                  the four-panel prototype (the layout workspace-cockpit-nav replaced), both themes,
- *                                          against `?fixture=proto`. `npm run test:parity:four-panel`; no longer in CI.
- *   node design-parity.js --theme=light    one theme
- *   node design-parity.js --states         also walk the interaction states (see STATES below)
- *   node design-parity.js --state=<id>     one named state
- *   node design-parity.js --keep           keep the rendered PNGs for inspection
- *
- * THE STATE WALK. `--states` was advertised in this header for two review rounds while doing
- * nothing — the flag was never read, so "identical across the captured interaction states" (PRD
- * success criterion 1, and the rubric's test_method) was decided on the opening screen alone. It is
- * implemented now: each state is a list of LABELS to click, applied to the prototype and to the app
- * from a fresh load, and the same four axes are diffed at the end of the sequence. The steps are
- * text, not selectors, deliberately — a selector would encode one page's DOM and quietly stop
- * matching on the other, which is the shape a check takes when it goes decorative. A step that
- * cannot find its label on EITHER page is a hard failure: "could not drive the app there" must
- * never be recorded as "the app matched there".
- *
- * Exit 0 only when every axis is clean. Exit 3 means it could not run (no browser, no server) —
- * which is a skip, and is reported as one rather than as a pass.
- */
-'use strict';
-const fs = require('fs');
-const path = require('path');
-const http = require('http');
-const os = require('os');
-
-const ROOT = path.resolve(__dirname, '..');
-const DESIGN = path.join(ROOT, 'planning', 'design', 'four-panel');
-const COCKPIT = path.join(ROOT, 'planning', 'design', 'cockpit-mockup');
-const FONTS = path.join(__dirname, 'public', 'vendor');
-const APP_URL = process.env.PMOS_PARITY_APP || 'http://127.0.0.1:7433';
-const REF_PORT = +(process.env.PMOS_PARITY_PORT || 8899);
-const OUT = process.env.PMOS_PARITY_OUT || path.join(os.tmpdir(), 'pmos-design-parity');
-
-const argv = process.argv.slice(2);
-/* `--board=<Name>` points the check at a board of the cockpit mockup instead of the four-panel prototype. The boards are static, drawn
- * at 1600x900 in the dark theme only, so a board run is one theme, one state, at that size. */
-const BOARD = (argv.find((a) => a.startsWith('--board=')) || '').split('=')[1] || null;
-const themes = BOARD ? ['dark'] : argv.some((a) => a.startsWith('--theme=')) ? [argv.find((a) => a.startsWith('--theme=')).split('=')[1]] : ['dark', 'light'];
-const KEEP = argv.includes('--keep');
-const W = 1600, H = BOARD ? 900 : 1000;
-
-/* THE CAPTURED INTERACTION STATES.
- *
- * Each entry is a state the PM can put the surface into, expressed as the labels a person would
- * click to get there — read as the element's OWN text, so "add repository" means the span holding
- * exactly that, in either page's markup. `default` is the opening screen and always runs.
- *
- * Chosen because each one changes a DIFFERENT part of the layout, so the set covers the interaction
- * model the handoff brief calls final rather than repeating one kind of change: a drawer over panel
- * 1, a collapsed group in panel 2, an expanded task tree and an opened tab in panels 3 and 4, a
- * collapsed column, and the panel-3 inline expansion. A state whose divergence is a DECISION rather
- * than a defect does not belong here — it belongs in the PRD — so if one is ever excluded, the
- * reason goes in `why` and gets printed, not left as an absence nobody can see.
- */
-const STATES = [
-  { id: 'default', steps: [] },
-  { id: 'settings-drawer', steps: ['settings & tools'] },
-  { id: 'group-collapsed', steps: ['health:tech'] },
-  { id: 'phase-collapsed', steps: ['intake'] },
-  { id: 'task-tab-open', steps: ['produce the build output'] },
-  { id: 'column-collapsed', steps: ['⟨'] },
-  { id: 'add-repository', steps: ['add repository'] },
-];
-const stateArg = argv.find((a) => a.startsWith('--state='));
-const states = BOARD ? STATES.filter((s) => s.id === 'default') : stateArg
-  ? STATES.filter((s) => s.id === stateArg.split('=')[1])
-  : (argv.includes('--states') ? STATES : STATES.filter((s) => s.id === 'default'));
-if (!states.length) {
-  console.error(`no such state: ${stateArg.split('=')[1]} — known: ${STATES.map((s) => s.id).join(', ')}`);
-  process.exit(2);
-}
-
-const PROPS = [
-  'display', 'gridTemplateColumns', 'gridTemplateRows', 'flexDirection', 'alignItems',
-  'justifyContent', 'gap', 'minHeight', 'padding', 'backgroundColor', 'color',
-  'borderTopWidth', 'borderRightWidth', 'borderBottomWidth', 'borderLeftWidth',
-  'borderLeftColor', 'borderBottomColor', 'borderRadius', 'fontFamily', 'fontSize', 'fontWeight',
-  'lineHeight', 'letterSpacing', 'textTransform', 'writingMode', 'overflowX', 'overflowY',
-];
-
-/* ── THE EXCLUSIONS: differences that are DECISIONS, named one by one ──────────────────────────────────────────────────────────
- *
- * A board run compares the app against a picture the PM drew before some later decisions were taken. Where the app differs from the
- * picture BECAUSE OF A DECISION (a PRD requirement, a PM answer, a feature a later run added on purpose), the difference is listed
- * here, by name, with the decision that makes it one. Nothing else is excluded, and no tolerance is loosened: the four axes, the 2px
- * geometry bound and the 0.5% pixel bound are the same for every run.
- *
- * What an exclusion does, and only for the element or phrase it names:
- *   text      the named element's text (or the named phrase) is left out of that page's word stream
- *   style     the named element and everything inside it are not paired or measured
- *   pixels    the named element's box, on the page where it is found, is painted identically on both screenshots before the diff
- *
- * A NARROW exclusion (`only`) leaves the element in every axis and skips just the listed comparisons on it — a list of computed-style
- * properties, or `box` for its geometry. Its text is compared, the rest of its style is compared, and its pixels are diffed.
- *
- * Each side is located the way a person would point at it. The app side uses the app's own stable hooks (`sel`). The board has no
- * hooks, so its side is anchored on visible text: `own` is the element whose own text is exactly that string, `up` climbs to an
- * ancestor, `child` steps down to one of its children (an element with no text of its own, such as a dot), and `phrase` is a run of
- * characters inside one text node. A side that is `null` means the element exists on the other
- * page only.
- *
- * A STALE EXCLUSION FAILS THE RUN. If a named side matches nothing, the run fails and says which: an exclusion that no longer
- * matches would otherwise be a silent hole that a future difference could hide in. Masked area is printed per exclusion, so how
- * much of the screen is NOT compared is always on the report, never only in this file.
- *
- * No exclusion is a reworded label. A label the app says differently from the board is a defect and is fixed in the app.
- */
-const EXCLUSIONS = {
-  WsA: [
-    {
-      name: 'terminal content',
-      why: 'The body of a terminal tab is the session\'s own output: the agent CLI and the cockpit mod draw it (the "Blocked" band and '
-        + 'the acceptance band are pmos-cockpit-mod M8 and M10), not the workspace. The workspace-cockpit-nav PRD puts "the terminal '
-        + 'mod and its boards" out of scope. The tab strip above it is compared.',
-      design: { own: 'accepted. merge PR 41 and publish the kit', up: 1 },
-      app: { sel: '[data-tabs="panes"]' },
-    },
-    {
-      name: 'scratchpad bar',
-      why: 'The session scratchpad\'s handle under the panes (Run 3, PRD R10, drawn from ViewFilesPad.dc.html). WsA predates it and '
-        + 'the PRD keeps it (R12, nothing is lost). On the board that strip is terminal body, which the exclusion above leaves out.',
-      design: null,
-      app: { sel: '[data-tabs="bottom"]' },
-    },
-    {
-      name: 'breadcrumb: last crumb',
-      why: 'PRD R8 makes the breadcrumb "repository, initiative, step, active tab", so the last crumb is the active tab\'s title '
-        + '("claude · merge PR 41"). The board ends it with the highlighted task. The first three crumbs are compared.',
-      design: { own: 'Run independent review', nth: 0 },
-      app: { sel: '[data-top="crumb"] > [data-crumb="tab"]' },
-      follows: [{
-        what: 'the trail\'s width, and its clipping of a long name',
-        only: ['box', 'overflowX', 'overflowY'],
-        design: { own: 'microsites', up: 1 },
-        app: { sel: '[data-top="crumb"]' },
-      }],
-    },
-    {
-      name: 'grants: the Grant button and the grants count',
-      why: 'PRD Q3, answered by the PM on 2026-10-04: Grant buttons and the grants count are hidden until the grants ledger behind '
-        + 'them exists (R5\'s rule: what has no backing is hidden, not greyed). The blocker card keeps the button\'s height, so '
-        + 'nothing moves when it comes; the rest of the status bar is compared.',
-      design: { own: 'Grant' },
-      app: null,
-      also: [{ design: { phrase: 'grants 0 active · ' }, app: null }],
-      follows: [{
-        what: 'the width of the status bar\'s right-hand text',
-        only: ['box'],
-        design: { phrase: '⌘K jump · Esc closes tab', parent: true },
-        app: { sel: '[data-shell="status"] > span:last-child' },
-      }],
-    },
-    {
-      name: 'Done: the third row',
-      why: 'The board labels the group "Done · 3" and draws two rows. The seed has three done initiatives (the count is the board\'s '
-        + 'own), and the app draws every row its count names. The label and the first two rows are compared.',
-      design: null,
-      app: { sel: '[data-row="shortlink-redirects"]' },
-      follows: [{ what: 'the height of the rows\' container', only: ['box'], design: { own: 'Needs you · 2', up: 1 }, app: { sel: '#pm-list [data-list="rows"]' } }],
-    },
-    {
-      name: 'artifact: the sync claim, and the link and sync controls',
-      why: 'The board\'s artifact row ends in "⇄ in sync". The app never says "in sync": it has never compared the repository file '
-        + 'with the linked document, and the external-linking work decided it shows only states a row on disk records '
-        + '(panel-detail.js, SYNC_NOT_A_SYNC). The artifact\'s link and sync controls (D53) sit under the row instead (R12). The '
-        + 'row\'s role badge and path are compared.',
-      design: { own: '⇄ in sync' },
-      app: { sel: '[data-art-links]' },
-      follows: [
-        { what: 'the path\'s width (it fills the row)', only: ['box'], design: { own: 'planning/prd/ooh-weather…-prd.md' }, app: { sel: '[data-art-path]' } },
-        { what: 'the height of the artifacts section', only: ['box'], design: { own: 'Artifacts', up: 1 }, app: { sel: '[data-cockpit="artifacts"]' } },
-      ],
-    },
-    {
-      name: 'column fold controls',
-      why: 'The PM could not fold the list and the detail away (2026-10-05, "i cannot minimize column 2 and 3"). Each column has a '
-        + '"⟨" control that folds it to the 36px strip, which opens it again. The board draws no fold control. Both float over the '
-        + 'column (the list\'s over the right end of "New initiative", the detail\'s at its top right), so nothing in the column moves.',
-      design: null,
-      app: { sel: '[data-fold]' },
-    },
-    {
-      name: 'tab: second line',
-      why: 'A tab names its initiative and session under its title ("<initiative> · session <id>"): after a reload the PM could not '
-        + 'tell which session a reopened tab was on (a PM-reported defect; ui-test AC6). The board\'s tabs have one line. The second '
-        + 'line sits in the tab\'s own lower padding, so the title stays where the board puts it.',
-      design: null,
-      app: { sel: '[data-tab-sub]' },
-    },
-    {
-      name: 'tab: close control on a tab not in front',
-      why: 'The board draws × on the tab in front only. The app keeps it on every tab, so a tab can be closed without first being '
-        + 'brought forward (a control shown only on hover is the trap this surface\'s earlier reviews named). It sits in the tab\'s '
-        + 'right padding, so no tab moves. The × of the tab in front is compared.',
-      design: null,
-      app: { sel: '[data-tab-active="0"] > [data-tab-close]' },
-    },
-    {
-      name: 'tab strip: options and split',
-      why: '"⋯ options" is the pre-flight composer an accepted PRD (workspace-repo-first) kept reachable; "⫽ split" shows two tabs side '
-        + 'by side. Both are live controls the board does not draw (R12). They sit left of "+ session", which is compared where the '
-        + 'board puts it.',
-      design: null,
-      app: { sel: '#pm-tabs [data-tabs="bar"] > button:not([data-tab]):not(:last-child)' },
-    },
-    {
-      name: 'tab: a view\'s dot colour',
-      why: 'PRD R4: a view tab has its own dot colour. The board paints "tool · memory" in the purple the app gives task tabs. Only the '
-        + 'dot\'s colour is skipped; its box and its pixels are compared.',
-      only: ['backgroundColor', 'color', 'borderLeftColor', 'borderBottomColor'],
-      design: { own: 'tool · memory', child: 0 },
-      app: { sel: '[data-tab-dot="view"]' },
-    },
-    {
-      name: 'the tabs column\'s fill',
-      why: 'The tabs column is painted --term-bg so a terminal stays dark in the light theme. The board is drawn dark only, where '
-        + '--term-bg and the page are the same colour, so the board leaves the column unpainted. Only that property is skipped.',
-      only: ['backgroundColor'],
-      design: { own: '+ session', up: 2 },
-      app: { sel: '#pm-tabs' },
-    },
-    {
-      name: 'the body: a grid with a scroll chain',
-      why: 'The board lays its four columns out as a flex row; the app\'s body is a grid, so Focus and the legacy shell re-place the '
-        + 'same four hosts without moving a terminal (R12), and each host down to the scrolling one has a zero minimum and clips '
-        + '(app.js: one tall document once scrolled the whole page). The list\'s rows, the detail and the tab strip scroll, because a '
-        + 'real repository has more than one screen of each; the board is a still picture. Only the layout mechanism, overflow and '
-        + 'minimum height of those containers are skipped; every column\'s box, and everything inside, is compared.',
-      only: ['display', 'gridTemplateColumns', 'gridTemplateRows', 'overflowX', 'overflowY', 'minHeight'],
-      design: null,
-      app: { sel: '[data-shell="body"]' },
-      follows: [{
-        what: 'the overflow and minimum height of the four columns and of the three containers that scroll',
-        only: ['overflowX', 'overflowY', 'minHeight'],
-        design: null,
-        app: { sel: '#pm-rail, #pm-list, #pm-detail, #pm-tabs, #pm-list [data-list="rows"], #pm-tabs [data-tabs="bar"]' },
-      }],
-    },
-  ],
-};
-/* The run's list: each exclusion and its sides, then each of its consequences (`follows`), which is always narrow (`only`) and is
- * printed under the decision it follows from. */
-const exclusions = (BOARD ? (EXCLUSIONS[BOARD] || []) : []).flatMap((x) => [
-  x,
-  ...(x.also || []).map((y) => ({ ...y, name: x.name, why: x.why, also: true })),
-  ...(x.follows || []).map((f) => ({ ...f, name: x.name + ' → ' + f.what, why: 'follows from "' + x.name + '"', follows: true })),
-]);
-
-function skip(why) { console.log(`⏭  design-parity SKIPPED — ${why}`); process.exit(3); }
-
-function requireOptional(name) { try { return require(name); } catch { return null; } }
-
-// ── a cockpit board as a static reference page ──────────────────────────────────────────────────
-/* A board is a `*.dc.html` file: a <helmet> holding the board's own CSS (and a Google Fonts link), then the board markup inside
- * <x-dc>. The boards render statically without the design canvas runtime, so the page is built here: the helmet's <style> goes in the
- * head, the Google Fonts link is replaced by the workspace's own vendored faces, and the markup sits inside a `data-pm-theme="dark"`
- * root so the comparer's walk starts at the same place on both pages. Nothing is fetched from the network. */
-function boardHtml(name) {
-  const file = path.join(COCKPIT, name + '.dc.html');
-  if (!fs.existsSync(file)) throw new Error('no such board: ' + file);
-  const src = fs.readFileSync(file, 'utf8');
-  const style = (/<helmet>[\s\S]*?<style>([\s\S]*?)<\/style>[\s\S]*?<\/helmet>/.exec(src) || [])[1];
-  const body = (/<\/helmet>([\s\S]*?)<\/x-dc>/.exec(src) || [])[1];
-  if (!style || !body) throw new Error('board ' + name + ' has no <helmet><style> or no <x-dc> body — it cannot be rendered statically');
-  // The board's own root element carries `data-pm-theme`, so the walk starts at the board itself and not at a wrapper of this script's.
-  const rooted = body.replace(/<div\b/, '<div data-pm-theme="dark"');
-  return '<!doctype html><html><head><meta charset="utf-8"><link rel="stylesheet" href="./fonts.css"><style>' + style + '</style></head><body>' + rooted + '</body></html>';
-}
-
-// ── the reference page, patched offline in memory ───────────────────────────────────────────────
-function referenceHtml() {
-  if (BOARD) return boardHtml(BOARD);
-  const src = fs.readFileSync(path.join(DESIGN, 'prototype-original.html'), 'utf8');
-  const map = JSON.stringify({
-    'https://unpkg.com/react@18.3.1/umd/react.production.min.js': './vendor/react.production.min.js',
-    'https://unpkg.com/react-dom@18.3.1/umd/react-dom.production.min.js': './vendor/react-dom.production.min.js',
-  });
-  let h = src.replace('<script src="./support.js"></script>',
-    `<script>window.__resources=${map};</script>\n<script src="./support.js"></script>`);
-  h = h.replace(/<link rel="preconnect"[^>]*>\s*/g, '');
-  h = h.replace(/<link href="https:\/\/fonts\.googleapis\.com[^>]*>/, '<link rel="stylesheet" href="./fonts.css">');
-  if (/fonts\.googleapis|unpkg\.com/.test(h.replace(map, ''))) {
-    throw new Error('reference page still carries a remote asset after patching — refusing to compare against a page that would need the network');
-  }
-  return h;
-}
-
-const FONTS_CSS = `
-@font-face{font-family:"Space Grotesk";src:url("./fonts/space-grotesk-var.woff2") format("woff2-variations");font-weight:300 700;font-style:normal;font-display:block}
-@font-face{font-family:"IBM Plex Mono";src:url("./fonts/ibm-plex-mono-400.woff2") format("woff2");font-weight:400;font-style:normal;font-display:block}
-@font-face{font-family:"IBM Plex Mono";src:url("./fonts/ibm-plex-mono-500.woff2") format("woff2");font-weight:500;font-style:normal;font-display:block}
-@font-face{font-family:"IBM Plex Mono";src:url("./fonts/ibm-plex-mono-700.woff2") format("woff2");font-weight:700;font-style:normal;font-display:block}
-`;
-
-function serveReference() {
-  const html = referenceHtml();
-  const types = { '.js': 'text/javascript', '.css': 'text/css', '.woff2': 'font/woff2', '.html': 'text/html' };
-  const server = http.createServer((req, res) => {
-    const p = decodeURIComponent(req.url.split('?')[0]);
-    if (p === '/' || p === '/index.html') { res.writeHead(200, { 'content-type': 'text/html' }); return res.end(html); }
-    if (p === '/fonts.css') { res.writeHead(200, { 'content-type': 'text/css' }); return res.end(FONTS_CSS); }
-    let file = null;
-    if (p.startsWith('/fonts/')) file = path.join(FONTS, path.basename(p));
-    else if (p === '/support.js' || p.startsWith('/vendor/')) file = path.join(DESIGN, p.replace(/^\//, ''));
-    if (file && fs.existsSync(file)) {
-      res.writeHead(200, { 'content-type': types[path.extname(file)] || 'application/octet-stream' });
-      return res.end(fs.readFileSync(file));
-    }
-    res.writeHead(404).end('not found');
-  });
-  return new Promise((resolve, reject) => {
-    server.on('error', reject);
-    server.listen(REF_PORT, '127.0.0.1', () => resolve(server));
-  });
-}
-
-/* Click the element whose OWN text is `label`, on whichever page it is given. Returns false when
- * nothing visible carries that text — the caller turns that into a failure rather than skipping the
- * state, because a state that could not be reached is not a state that matched. `closest('button')`
- * is what actually gets clicked: the prototype's runtime wraps each interpolated label in a span, so
- * the text node and the control are usually different elements. */
-async function drive(page, steps) {
-  const applied = [];
-  for (const label of steps) {
-    const hit = await page.evaluate((lab) => {
-      const own = (e) => [...e.childNodes].filter((n) => n.nodeType === 3)
-        .map((n) => n.textContent.replace(/\s+/g, ' ').trim()).join(' ').trim();
-      const visible = (e) => {
-        const cs = getComputedStyle(e);
-        if (cs.display === 'none' || cs.visibility === 'hidden' || cs.opacity === '0') return false;
-        const r = e.getBoundingClientRect();
-        return r.width > 0 && r.height > 0;
-      };
-      const target = [...document.querySelectorAll('*')].find((e) => own(e) === lab && visible(e));
-      if (!target) return false;
-      (target.closest('button,[role="button"]') || target).click();
-      return true;
-    }, label);
-    applied.push({ label, hit });
-    await page.waitForTimeout(600);
-  }
-  return applied;
-}
-
-async function snap(browser, url, theme, tag, steps = [], side = null) {
-  const page = await browser.newPage({ viewport: { width: W, height: H }, deviceScaleFactor: 1 });
-  const errors = [];
-  page.on('pageerror', (e) => errors.push(String(e.message)));
-  page.on('console', (m) => { if (m.type() === 'error') errors.push(m.text()); });
-  await page.goto(url, { waitUntil: 'networkidle', timeout: 60000 });
-  await page.waitForTimeout(1200);
-  if (theme === 'light') {
-    await page.evaluate(() => {
-      const b = [...document.querySelectorAll('button')].find((x) => /theme/i.test(x.textContent || ''));
-      if (b) b.click();
-    });
-    await page.waitForTimeout(500);
-  }
-  // The interaction steps are applied AFTER the theme is settled, so a state is diffed in the theme
-  // it was reached in rather than in whatever theme the toggle left behind.
-  const applied = await drive(page, steps);
-  await page.waitForFunction(() => document.fonts.status === 'loaded', null, { timeout: 15000 }).catch(() => {});
-  const png = path.join(OUT, `${tag}.png`);
-  await page.screenshot({ path: png });
-  // this page's side of each exclusion (see EXCLUSIONS); null when the excluded thing exists on the other page only
-  const xs = side ? exclusions.map((x) => ({ name: x.name, loc: x[side] || null, only: x.only || null })) : [];
-  const data = await page.evaluate(([props, xs, frame, tokenNames]) => {
-    const own = (e) => [...e.childNodes].filter((n) => n.nodeType === 3)
-      .map((n) => n.textContent.replace(/\s+/g, ' ').trim()).filter(Boolean).join(' ');
-    const shown = (e) => { const cs = getComputedStyle(e); const r = e.getBoundingClientRect(); return cs.display !== 'none' && r.width > 0 && r.height > 0; };
-    // ── mark the excluded elements and phrases, and keep their boxes for the pixel mask ──
-    const masks = [], phrases = [];
-    for (const x of xs) {
-      if (!x.loc) continue;
-      const m = { name: x.name, found: 0, boxes: [] };
-      masks.push(m);
-      if (x.loc.phrase) {
-        const tw = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
-        for (let n = tw.nextNode(); n; n = tw.nextNode()) {
-          const at = n.textContent.indexOf(x.loc.phrase);
-          if (at < 0) continue;
-          if (x.loc.parent) {      // the element that holds the phrase, for a narrow exclusion
-            if (x.only) { n.parentElement.setAttribute('data-parity-only', x.only.join(',')); m.found++; }
-            continue;
-          }
-          const rg = document.createRange(); rg.setStart(n, at); rg.setEnd(n, at + x.loc.phrase.length);
-          const r = rg.getBoundingClientRect();
-          m.found++; m.boxes.push([r.x, r.y, r.width, r.height]); phrases.push({ node: n, phrase: x.loc.phrase });
-        }
-        continue;
-      }
-      let hits = x.loc.sel ? [...document.querySelectorAll(x.loc.sel)]
-        : [...document.querySelectorAll('body *')].filter((e) => own(e) === x.loc.own && shown(e));
-      if (typeof x.loc.nth === 'number') hits = hits.slice(x.loc.nth, x.loc.nth + 1);
-      for (let e of hits) {
-        for (let i = 0; i < (x.loc.up || 0) && e.parentElement; i++) e = e.parentElement;
-        if (typeof x.loc.child === 'number') e = e.children[x.loc.child];
-        if (!e) continue;
-        if (!shown(e)) continue;
-        if (x.only) { e.setAttribute('data-parity-only', x.only.join(',')); m.found++; continue; }
-        e.setAttribute('data-parity-excluded', x.name);
-        const r = e.getBoundingClientRect();
-        m.found++; m.boxes.push([r.x, r.y, r.width, r.height]);
-      }
-    }
-    const cut = (n) => { let t = n.textContent; for (const p of phrases) if (p.node === n) t = t.split(p.phrase).join(' '); return t; };
-    const excluded = (e) => e.hasAttribute('data-parity-excluded');
-    // an element's whole visible text, leaving out what is excluded inside it
-    const fullText = (e) => {
-      let t = '';
-      for (const c of e.childNodes) {
-        if (c.nodeType === 3) t += cut(c);
-        else if (c.nodeType === 1 && !excluded(c)) t += ' ' + fullText(c) + ' ';
-      }
-      return t;
-    };
-    const root = document.querySelector('[data-pm-theme]') || document.body;
-    const nodes = [], texts = [];
-    const walk = (e) => {
-      if (excluded(e)) return;
-      const cs = getComputedStyle(e);
-      if (cs.display === 'none') return;
-      // On a board run the walk's root is a FRAME on both pages and is not itself a compared node: the board's root is a flex column and
-      // the app's is a grid (the phone's stylesheet places its rows), two ways of drawing the same three bands. Its geometry is the
-      // viewport on both, its fill is diffed by the pixel axis, and everything inside it is compared.
-      if (frame && e === root) { for (const c of e.childNodes) { if (c.nodeType === 3) { const s0 = cut(c).replace(/\s+/g, ' ').trim(); if (s0) texts.push(s0); } else if (c.nodeType === 1) walk(c); } return; }
-      const r = e.getBoundingClientRect();
-      const ownT = [...e.childNodes].filter((n) => n.nodeType === 3)
-        .map((n) => cut(n).replace(/\s+/g, ' ').trim()).filter(Boolean).join(' ');
-      const st = {}; for (const p of props) st[p] = cs[p];
-      // `full` is the element's WHOLE visible text, used to anchor style comparison; `own` is only
-      // its own text nodes. They differ because the prototype's runtime wraps each interpolation in
-      // a span, so its label sits one element deeper than the app's.
-      nodes.push({ text: ownT.slice(0, 60), full: fullText(e).replace(/\s+/g, ' ').trim().slice(0, 80),
-        box: [r.x, r.y, r.width, r.height].map(Math.round), st, only: (e.getAttribute('data-parity-only') || '').split(',').filter(Boolean) });
-      // Walk childNodes IN ORDER, emitting text where it actually sits rather than hoisting all of an
-      // element's own text ahead of its children. The status bar is the case that forced this: the
-      // design writes "local · persistent server · ", then a <span> holding the count, then
-      // " sessions running", so hoisting produced "…server · sessions running 3" and reported a text
-      // difference on a bar that is pixel-identical. Reading order is what the PM sees; it is what
-      // the stream has to be.
-      for (const c of e.childNodes) {
-        if (c.nodeType === 3) {
-          const s = cut(c).replace(/\s+/g, ' ').trim();
-          if (s) texts.push(s);
-        } else if (c.nodeType === 1) walk(c);
-      }
-    };
-    walk(root);
-    // what each design token resolves to on this page (see TOKENS)
-    const tokens = {};
-    for (const t of tokenNames) {
-      const probe = document.createElement('div');
-      probe.style.color = 'var(--' + t + ')';
-      root.appendChild(probe);
-      tokens[t] = getComputedStyle(probe).color;
-      probe.remove();
-    }
-    return { nodes, texts, masks, tokens };
-  }, [PROPS, xs, !!BOARD, BOARD ? TOKENS : []]);
-  await page.close();
-  return { ...data, errors, png, applied };
-}
-
-/* THE TOKEN MAPPING (PRD R12). A board declares its own token values at its :root, and four of them are not the token system's:
- * --card, --sidebar, --accent and --brand-wash are drawn a shade or two off the D38 values the app uses. R12 decided it: "the
- * mockup's --brand, --success and similar values map to the token system, not to new hex values". So on a board run a computed
- * colour that is exactly what a board token resolves to is read as that token, and matches when the app's element has the SAME
- * token's value. It is a mapping by token name, never a tolerance: a colour the board wrote out by hand, or a different token, still
- * differs. The tokens whose values differ are printed with each run. */
-const TOKENS = ['background', 'foreground', 'card', 'sidebar', 'secondary', 'accent', 'muted-foreground', 'border', 'input', 'brand',
-  'brand-wash', 'success', 'warning', 'info', 'destructive'];
-let tokenMap = new Map();      // design-resolved value -> app-resolved value, for the tokens whose values differ
-
-/* On a board run `font-family` is compared by its FIRST family only. The mockup's fallback tail (`system-ui, sans-serif`) and the token
- * system's (`ui-sans-serif, system-ui, sans-serif, …`) differ by design (PRD R12: the mockup's values map to the tokens, they do not
- * replace them), and a fallback is never drawn while the first family loads — the fonts are vendored, so the check would be measuring
- * a stack nobody sees. Every other property is compared exactly. */
-const sameValue = (p, a, b) => (BOARD && p === 'fontFamily') ? String(a).split(',')[0] === String(b).split(',')[0]
-  : a === b || (BOARD && tokenMap.has(a) && tokenMap.get(a) === b);
-
-function diff(A, B, theme) {
-  const problems = [];
-  if (B.errors.length) problems.push(`console errors in the app (${B.errors.length}): ${B.errors.slice(0, 5).join(' | ')}`);
-  // Compare the CONCATENATED stream, not the node list. Node boundaries are an artefact of the
-  // prototype's interpolation wrappers: its template runtime wraps every {{ }} in a <span>, so the
-  // status bar's session count is three text nodes there and one in the app. The handoff brief calls
-  // that runtime an implementation detail, so reproducing its wrapper elements would be copying the
-  // scaffolding rather than the design. What the PM reads is the sequence of words on screen, and
-  // that is what has to match — in content and in order.
-  const streamA = A.texts.join(' ').replace(/\s+/g, ' ').trim();
-  const streamB = B.texts.join(' ').replace(/\s+/g, ' ').trim();
-  let missing = [], extra = [];
-  if (streamA !== streamB) {
-    const wa = streamA.split(' '), wb = streamB.split(' ');
-    let i = 0;
-    while (i < wa.length && i < wb.length && wa[i] === wb[i]) i++;
-    missing = wa.slice(i, i + 20); extra = wb.slice(i, i + 20);
-    problems.push('the rendered text differs — first divergence at word ' + i + ':\n    design: …' +
-      wa.slice(Math.max(0, i - 6), i + 14).join(' ') + '\n    app:    …' +
-      wb.slice(Math.max(0, i - 6), i + 14).join(' '));
-  }
-
-  // Anchor on FULL text, keeping the OUTERMOST match. The walk is pre-order, so a parent is seen
-  // before its children and first-wins yields the outermost element carrying that text — pairing the
-  // design's <button> with the app's <button>, rather than pairing the design's interpolation <span>
-  // against the app's button and reporting the button's own padding and border as differences.
-  const index = (ns) => { const m = new Map(); for (const n of ns) if (n.full && !m.has(n.full)) m.set(n.full, n); return m; };
-  const ia = index(A.nodes), ib = index(B.nodes);
-  const sd = [];
-  for (const [t, na] of ia) {
-    const nb = ib.get(t); if (!nb) continue;
-    const skipped = new Set([...(na.only || []), ...(nb.only || [])]);   // a narrow exclusion's listed comparisons (see EXCLUSIONS)
-    for (const p of PROPS) if (!skipped.has(p) && !sameValue(p, na.st[p], nb.st[p])) sd.push(`    [${JSON.stringify(t.slice(0, 30))}] ${p}: design=${na.st[p]} app=${nb.st[p]}`);
-    const off = na.box.map((v, i) => Math.abs(v - nb.box[i]));
-    if (!skipped.has('box') && Math.max(...off) > 2) sd.push(`    [${JSON.stringify(t.slice(0, 30))}] box: design=${na.box} app=${nb.box}`);
-  }
-  if (sd.length) {
-    problems.push(`${sd.length} computed-style / geometry difference(s)${sd.length > 40 ? ' (the first 40; all of them are in ' + path.join(OUT, 'differences-' + theme + '.txt') + ')' : ''}:\n` + sd.slice(0, 40).join('\n'));
-    try { fs.writeFileSync(path.join(OUT, 'differences-' + theme + '.txt'), sd.join('\n') + '\n'); } catch { /* the report is still printed */ }
-  }
-  return { problems, missing, extra, styleDiffs: sd, theme };
-}
-
-(async () => {
-  const pw = requireOptional('playwright-core');
-  if (!pw) skip('playwright-core is not installed (npm install in workspace/)');
-  // Discovery is lib/find-browser.js's, not a third private candidate list. This file used to hunt
-  // only under /opt/pw-browsers, so on a runner whose browser is /usr/bin/chromium-browser it found
-  // nothing and reported a SKIP — from a machine that had a browser the whole time.
-  const exe = require('./lib/find-browser').findBrowser();
-  if (!exe) skip('no Chrome/Chromium found (set PMOS_CHROME, or install one)');
-  if (!BOARD && !fs.existsSync(path.join(DESIGN, 'prototype-original.html'))) skip(`the design reference is missing at ${DESIGN}`);
-
-  const alive = await new Promise((r) => {
-    const req = http.get(APP_URL, (res) => { res.resume(); r(true); });
-    req.on('error', () => r(false)); req.setTimeout(3000, () => { req.destroy(); r(false); });
-  });
-  if (!alive) skip(`the workspace is not running at ${APP_URL} (node server.js)`);
-
-  fs.mkdirSync(OUT, { recursive: true });
-  const server = await serveReference();
-  const browser = await pw.chromium.launch({ executablePath: exe, args: ['--no-sandbox', '--font-render-hinting=none'] });
-
-  let failed = 0, compared = 0;
-  const report = {};
-  for (const theme of themes) for (const st of states) {
-    const key = `${theme}/${st.id}`;
-    const A = await snap(browser, `http://127.0.0.1:${REF_PORT}/index.html`, theme, `design-${theme}-${st.id}`, st.steps, 'design');
-    const B = await snap(browser, `${APP_URL}/?fixture=${BOARD ? 'cockpit' : 'proto'}`, theme, `app-${theme}-${st.id}`, st.steps, 'app');
-    tokenMap = new Map();
-    const mapped = [];
-    for (const t of TOKENS) {
-      const dv = A.tokens && A.tokens[t], av = B.tokens && B.tokens[t];
-      if (dv && av && dv !== av && !tokenMap.has(dv)) { tokenMap.set(dv, av); mapped.push(`--${t}: ${dv} → ${av}`); }
-    }
-    if (mapped.length) console.log(`\ntoken mapping (PRD R12), by name: ${mapped.join(' · ')}`);
-    const d = diff(A, B, theme);
-
-    // COULD THE STATE BE REACHED AT ALL? Asserted before anything is compared, and on BOTH pages: a
-    // step that found no label leaves the page in the previous state, where a clean diff would say
-    // only that two unchanged screens still match. Reported as a failure with the step named.
-    const missedD = A.applied.filter((s) => !s.hit).map((s) => s.label);
-    const missedA = B.applied.filter((s) => !s.hit).map((s) => s.label);
-    if (missedD.length || missedA.length) {
-      d.problems.push(`the state could not be reached — ` +
-        (missedD.length ? `no visible "${missedD.join('", "')}" in the DESIGN; ` : '') +
-        (missedA.length ? `no visible "${missedA.join('", "')}" in the APP; ` : '') +
-        `nothing below this line is a comparison of ${st.id}`);
-    }
-
-    // A STALE EXCLUSION FAILS: every side an exclusion names must still match something on that page.
-    const stale = [];
-    for (const [who, P] of [['design', A], ['app', B]]) for (const m of P.masks) if (!m.found) stale.push(`"${m.name}" matches nothing in the ${who.toUpperCase()}`);
-    if (stale.length) d.problems.push('stale exclusion(s) — remove or repair them in EXCLUSIONS:\n    ' + stale.join('\n    '));
-    const maskBoxes = [...A.masks, ...B.masks].flatMap((m) => m.boxes.map((b) => ({ name: m.name, b })));
-
-    let pixels = null, maskedPct = 0;
-    const pixelmatch = requireOptional('pixelmatch'); const pngjs = requireOptional('pngjs');
-    if (pixelmatch && pngjs) {
-      const pm = pixelmatch.default || pixelmatch;
-      const a = pngjs.PNG.sync.read(fs.readFileSync(A.png)), b = pngjs.PNG.sync.read(fs.readFileSync(B.png));
-      if (a.width === b.width && a.height === b.height) {
-        // Paint each excluded box identically on both screenshots (the design's pixels are copied into the app's), so only what is
-        // compared can differ. The masked area is counted and reported, not hidden.
-        const masked = new Uint8Array(a.width * a.height);
-        for (const { b: [x0, y0, w0, h0] } of maskBoxes) {
-          const x1 = Math.max(0, Math.floor(x0)), y1 = Math.max(0, Math.floor(y0));
-          const x2 = Math.min(a.width, Math.ceil(x0 + w0)), y2 = Math.min(a.height, Math.ceil(y0 + h0));
-          for (let y = y1; y < y2; y++) for (let x = x1; x < x2; x++) {
-            const i = y * a.width + x; masked[i] = 1;
-            for (let k = 0; k < 4; k++) b.data[i * 4 + k] = a.data[i * 4 + k];
-          }
-        }
-        let nMasked = 0; for (const v of masked) nMasked += v;
-        maskedPct = +(100 * nMasked / (a.width * a.height)).toFixed(2);
-        const out = new pngjs.PNG({ width: a.width, height: a.height });
-        const n = pm(a.data, b.data, out.data, a.width, a.height, { threshold: 0.12 });
-        fs.writeFileSync(path.join(OUT, `diff-${theme}-${st.id}.png`), pngjs.PNG.sync.write(out));
-        pixels = n / (a.width * a.height);
-        if (pixels > 0.005) d.problems.push(`pixel diff ${(pixels * 100).toFixed(2)}% of the viewport — ${path.join(OUT, `diff-${theme}-${st.id}.png`)}`);
-      } else d.problems.push(`screenshot sizes differ: design ${a.width}x${a.height}, app ${b.width}x${b.height}`);
-    }
-
-    report[key] = {
-      steps: st.steps,
-      designNodes: A.nodes.length, appNodes: B.nodes.length,
-      textMissing: d.missing.length, textExtra: d.extra.length,
-      styleDiffs: d.styleDiffs.length,
-      exclusions: (EXCLUSIONS[BOARD] || []).map((x) => x.name),
-      maskedPct,
-      pixelPct: pixels === null ? 'not measured (pixelmatch/pngjs absent)' : +(pixels * 100).toFixed(3),
-      clean: d.problems.length === 0,
-    };
-    compared++;
-    console.log(`\n── ${key} ──`);
-    console.log(JSON.stringify(report[key], null, 1));
-    if (d.problems.length) { failed++; console.log('\n' + d.problems.join('\n\n')); }
-  }
-
-  await browser.close();
-  server.close();
-  fs.writeFileSync(path.join(OUT, 'report.json'), JSON.stringify(report, null, 1));
-  if (!KEEP && !failed) for (const f of fs.readdirSync(OUT)) if (f.endsWith('.png')) fs.unlinkSync(path.join(OUT, f));
-
-  if (exclusions.length) {
-    const top = EXCLUSIONS[BOARD] || [];
-    console.log(`\n${top.length} named exclusion(s) on board ${BOARD} — each a decision, not a defect:`);
-    for (const x of top) {
-      console.log(`  · ${x.name}${x.only ? ' (only: ' + x.only.join(', ') + ')' : ''} — ${x.why}`);
-      for (const f of x.follows || []) console.log(`      ↳ follows: ${f.what} (only: ${f.only.join(', ')})`);
-    }
-  }
-  const scope = `${themes.join(' and ')} × ${states.length} state(s) [${states.map((s) => s.id).join(', ')}]`;
-  if (failed) {
-    console.log(`\n❌ design parity FAILED in ${failed}/${compared} comparison(s). Renders kept in ${OUT}.`);
-    process.exit(1);
-  }
-  console.log(`\n✅ design parity — the app is identical to ${BOARD ? 'the cockpit board ' + BOARD : "the PM's prototype"} across ${scope} — ${compared} comparison(s).`);
-  if (states.length === 1 && states[0].id === 'default') {
-    console.log('   (default state only. `--states` walks all ' + STATES.length + ', which is what the PRD asks for.)');
-  }
-})().catch((e) => { console.error('design-parity ERROR:', e.stack); process.exit(2); });