@bongos/core 1.19.395 → 1.19.397

package/modules/ui-design/kit/lib.js

@@ -0,0 +1,389 @@
+'use strict';
+// lib.js — the ui-design kit's shared floor (task 1003320, ADR 0197): the repo
+// root, the browser launch on the SYSTEM channel, the platform FLOORS every
+// render is audited against, the states-file and probes-file contracts, the
+// action + expectation vocabularies a JSON file may use, the WCAG maths, and the
+// stub spawner. Pure wherever it can be — tests/ui_design_kit.mjs pins the pure
+// parts without a browser. Instance-agnostic: nothing here names a page, a
+// module or a host; a surface describes itself in a JSON file beside it.
+//
+// Exit codes shared by every kit CLI: 0 clean · 1 problems/FAILs · 2 usage or a
+// contract error (a bad file, a missing page) · 3 no browser / no playwright-core.
+const fs = require('node:fs');
+const path = require('node:path');
+const net = require('node:net');
+const { spawn } = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+const KIT_DIR = __dirname;
+const EXIT = Object.freeze({ CLEAN: 0, PROBLEMS: 1, USAGE: 2, NO_BROWSER: 3 });
+
+// The floors (modules/ui-design/CLAUDE.md "The platform's floors"). The names are
+// the contract the test pins; render.js reports a problem under one of them.
+const FLOORS = Object.freeze([
+  'console-errors',       // no console.error and no uncaught page error
+  'failed-requests',      // no 4xx/5xx response the states file did not declare expected
+  'horizontal-overflow',  // documentElement.scrollWidth fits the viewport
+  'one-header-main-h1',   // exactly one <header>, one <main>, one <h1>
+  'controls-24px',        // every visible control clears 24px on both sides
+  'top-bar-80px',         // the page's <header> is at most 80px tall
+  'reduced-motion',       // under prefers-reduced-motion nothing runs and no rAF loop
+]);
+
+const SIZES = Object.freeze({ 1440: [1440, 900], 390: [390, 844], 320: [320, 700] });
+const MODES = Object.freeze(['dark', 'light']);
+const CHANNELS = Object.freeze(['msedge', 'chrome']);
+const SETTLE_MS = 900; // fonts + the pages' own boot fetches; the scratchpad value that never flaked
+
+// ── argv ──────────────────────────────────────────────────────────────────────
+function argOf(args, flag, dflt) { const i = args.indexOf(flag); return i > -1 && i + 1 < args.length ? args[i + 1] : dflt; }
+function hasFlag(args, flag) { return args.includes(flag); }
+function listArg(args, flag, dflt) { const v = argOf(args, flag, null); return v == null ? dflt : v.split(',').map((s) => s.trim()).filter(Boolean); }
+
+// ── pages + surfaces ─────────────────────────────────────────────────────────
+// '/' → index · '/projects' → projects · '/builders/ranks' → ranks · 'x.html' → x
+function pageName(urlPath) {
+  const last = String(urlPath || '/').split('?')[0].replace(/\/+$/, '').split('/').pop();
+  return (last || 'index').replace(/\.html$/, '');
+}
+// A `--page /` typed in Git Bash on Windows arrives as the MSYS root
+// ("C:/Program Files/Git/") — the shell's path conversion, not the user. Read it
+// back as the root; `MSYS_NO_PATHCONV=1` is the shell-side cure the recipe names.
+function normalizePageArg(page) {
+  if (typeof page === 'string' && /^[A-Za-z]:[\\/]/.test(page) && /[\\/]$/.test(page)) return '/';
+  return page;
+}
+// A surface is a directory of the checkout: 'public-landing', 'modules/<key>/public',
+// or a module KEY whose manifest declares a webSurfaces dir. Nothing is hardcoded.
+function resolveSurfaceDir(surface, root = REPO_ROOT) {
+  if (!surface) return null;
+  const direct = path.resolve(root, surface);
+  if (fs.existsSync(direct) && fs.statSync(direct).isDirectory()) return direct;
+  const manifest = path.join(root, 'modules', surface, 'module.json');
+  if (fs.existsSync(manifest)) {
+    try {
+      const m = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+      const ws = (m.contributes && m.contributes.webSurfaces || [])[0];
+      const dir = path.join(root, 'modules', surface, (ws && ws.dir) || 'public');
+      if (fs.existsSync(dir)) return dir;
+    } catch { /* fall through */ }
+  }
+  return null;
+}
+// The states/probes file for a page lives BESIDE the surface: <dir>/<page>.states.json.
+function sidecarPath(surfaceDir, urlPath, kind) { return path.join(surfaceDir, `${pageName(urlPath)}.${kind}.json`); }
+function readJson(file) { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+
+// ── the action vocabulary (states + probes) ───────────────────────────────────
+const ACTIONS = Object.freeze(['click', 'focus', 'press', 'fill', 'wait', 'clickAt', 'clickIfVisible', 'dispatchClick', 'check', 'back', 'forward']);
+function validateActions(actions, at) {
+  if (actions === undefined) return [];
+  if (!Array.isArray(actions)) return [`${at}: an array of [op, ...args]`];
+  const errors = [];
+  actions.forEach((step, i) => {
+    const arr = Array.isArray(step) ? step : [step];
+    const [op, a, b] = arr;
+    if (!ACTIONS.includes(op)) { errors.push(`${at}[${i}]: unknown action "${op}" (one of ${ACTIONS.join(', ')})`); return; }
+    if (['click', 'focus', 'fill', 'clickIfVisible', 'dispatchClick', 'check'].includes(op) && typeof a !== 'string') errors.push(`${at}[${i}]: ${op} needs a selector`);
+    if (op === 'press' && typeof a !== 'string') errors.push(`${at}[${i}]: press needs a key`);
+    if (op === 'wait' && !(Number(a) >= 0)) errors.push(`${at}[${i}]: wait needs milliseconds`);
+    if (op === 'clickAt' && !(Number(a) >= 0 && Number(b) >= 0)) errors.push(`${at}[${i}]: clickAt needs x y`);
+  });
+  return errors;
+}
+async function runActions(page, actions = []) {
+  for (const step of actions) {
+    const [op, a, b] = Array.isArray(step) ? step : [step];
+    switch (op) {
+      case 'click': await page.click(a); break;
+      case 'focus': await page.focus(a); break;
+      case 'press': await page.keyboard.press(a); break;
+      case 'fill': await page.fill(a, b == null ? '' : String(b)); break;
+      case 'wait': await page.waitForTimeout(Number(a) || 0); break;
+      case 'clickAt': await page.mouse.click(Number(a), Number(b)); break;
+      case 'clickIfVisible': {
+        const vis = await page.evaluate((s) => { const el = document.querySelector(s); return !!el && getComputedStyle(el).display !== 'none' && !el.closest('[hidden]'); }, a);
+        if (vis) await page.click(a);
+        break;
+      }
+      case 'dispatchClick':
+        await page.evaluate((s) => { const el = document.querySelector(s); if (!el) throw new Error('dispatchClick: nothing matches ' + s); el.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true })); }, a);
+        break;
+      case 'check':
+        await page.evaluate(([s, on]) => { const el = document.querySelector(s); if (!el) throw new Error('check: nothing matches ' + s); el.checked = on !== false; el.dispatchEvent(new Event('change', { bubbles: true })); }, [a, b]);
+        break;
+      case 'back': await page.goBack(); break;
+      case 'forward': await page.goForward(); break;
+      default: throw new Error(`unknown action "${op}"`);
+    }
+  }
+}
+
+// ── the expectation vocabulary ────────────────────────────────────────────────
+// A state may EXPECT (render.js) and a probe must EXPECT (probe.js). Selectors are
+// evaluated in the page; scalars compared here. `open`/`visible` = present and not
+// hidden; `closed`/`hidden` = absent or hidden.
+const EXPECT_KEYS = Object.freeze(['expanded', 'dialog', 'visible', 'hidden', 'open', 'closed', 'activeId', 'activeText', 'expandedIds', 'param', 'attr', 'text', 'href', 'count', 'checked', 'value', 'hasClass', 'noOverflow']);
+function validateExpect(expect, at) {
+  if (expect === undefined) return [];
+  if (!expect || typeof expect !== 'object' || Array.isArray(expect)) return [`${at}: an object`];
+  const errors = [];
+  for (const k of Object.keys(expect)) if (!EXPECT_KEYS.includes(k)) errors.push(`${at}.${k}: unknown expectation (one of ${EXPECT_KEYS.join(', ')})`);
+  for (const k of ['visible', 'hidden']) if (expect[k] !== undefined && !(Array.isArray(expect[k]) && expect[k].every((s) => typeof s === 'string'))) errors.push(`${at}.${k}: an array of selectors`);
+  for (const k of ['open', 'closed', 'activeId', 'activeText', 'checked']) if (expect[k] !== undefined && typeof expect[k] !== 'string') errors.push(`${at}.${k}: a string`);
+  for (const k of ['expanded', 'dialog', 'noOverflow']) if (expect[k] !== undefined && typeof expect[k] !== 'boolean') errors.push(`${at}.${k}: a boolean`);
+  if (expect.expandedIds !== undefined && !Array.isArray(expect.expandedIds)) errors.push(`${at}.expandedIds: an array of ids`);
+  if (expect.param !== undefined && (typeof expect.param !== 'object' || Array.isArray(expect.param))) errors.push(`${at}.param: an object of name → value (null = absent)`);
+  for (const k of ['attr', 'text', 'href', 'count', 'value', 'hasClass']) if (expect[k] !== undefined && !(Array.isArray(expect[k]) && expect[k].every(Array.isArray))) errors.push(`${at}.${k}: an array of [selector, ...]`);
+  return errors;
+}
+// Runs IN THE PAGE: collects the facts the expectations compare against, plus the
+// floor facts every render needs. Self-contained (page.evaluate serialises it).
+function factsInPage(spec) {
+  const describe = (el) => el.id ? '#' + el.id : el.tagName.toLowerCase() + (el.className && typeof el.className === 'string' ? '.' + el.className.split(' ')[0] : '');
+  const shown = (el) => {
+    if (!el || el.hidden || el.closest('[hidden]')) return false;
+    let a = el;
+    while (a && a !== document.body) { const s = getComputedStyle(a); if (s.display === 'none' || s.visibility === 'hidden' || +s.opacity === 0) return false; a = a.parentElement; }
+    return true;
+  };
+  const q = (s) => { try { return document.querySelector(s); } catch { return null; } };
+  const qa = (s) => { try { return [...document.querySelectorAll(s)]; } catch { return []; } };
+  const de = document.documentElement;
+  const out = { scrollWidth: de.scrollWidth, clientWidth: de.clientWidth, mode: de.getAttribute('data-mode') };
+  // RENDERED landmarks: a page that keeps one <h1> per view and shows one view at a
+  // time has one h1 on stage, which is what the floor means.
+  const shownCount = (s) => qa(s).filter(shown).length;
+  out.headers = shownCount('header'); out.mains = shownCount('main'); out.h1s = shownCount('h1');
+  const bar = document.querySelector('header');
+  out.bar = bar ? { h: Math.round(bar.getBoundingClientRect().height), top: Math.round(bar.getBoundingClientRect().top) } : null;
+  const ignore = spec.ignoreControls || [];
+  const small = [];
+  document.querySelectorAll('a[href], button, [role="button"], input, select, textarea, summary').forEach((el) => {
+    if (ignore.some((s) => { try { return el.matches(s) || !!el.closest(s); } catch { return false; } })) return;
+    const r = el.getBoundingClientRect();
+    if ((r.width === 0 && r.height === 0) || !shown(el)) return;
+    if (el.tagName === 'INPUT' && (el.type === 'checkbox' || el.type === 'radio') && el.closest('label')) return; // the label is the target
+    if (r.width < 24 || r.height < 24) small.push(`${describe(el)} "${(el.textContent || el.getAttribute('aria-label') || '').trim().slice(0, 28)}" ${Math.round(r.width)}x${Math.round(r.height)}`);
+  });
+  out.smallControls = small;
+  out.expanded = [...document.querySelectorAll('[aria-expanded="true"]')].map((el) => el.id || describe(el));
+  out.dialog = qa('[role="dialog"], dialog[open]').some(shown);
+  out.running = document.getAnimations().filter((a) => a.playState === 'running').length;
+  const ae = document.activeElement;
+  out.activeId = ae ? ae.id || '' : ''; out.activeText = ae ? (ae.textContent || '').replace(/\s+/g, ' ').trim().slice(0, 40) : '';
+  const e = spec.expect || {};
+  out.sel = {};
+  for (const s of [...(e.visible || []), ...(e.hidden || []), ...(e.open ? [e.open] : []), ...(e.closed ? [e.closed] : [])]) out.sel[s] = shown(q(s));
+  if (e.param) { const u = new URLSearchParams(location.search); out.param = {}; for (const k of Object.keys(e.param)) out.param[k] = u.get(k); }
+  if (e.attr) out.attr = e.attr.map(([s, n]) => { const el = q(s); return el ? el.getAttribute(n) : null; });
+  if (e.text) out.text = e.text.map(([s]) => { const el = q(s); return el ? (el.textContent || '').trim() : null; });
+  if (e.href) out.href = e.href.map(([s]) => { const el = q(s); return el ? el.getAttribute('href') : null; });
+  if (e.count) out.count = e.count.map(([s]) => qa(s).length);
+  if (e.checked) { const el = q(e.checked); out.checked = el ? !!el.checked : null; }
+  if (e.value) out.value = e.value.map(([s]) => { const el = q(s); return el ? el.value : null; });
+  if (e.hasClass) out.hasClass = e.hasClass.map(([s, c]) => { const el = q(s); return el ? el.classList.contains(c) : null; });
+  return out;
+}
+// Pure: compare collected facts against an expectation. Returns problem strings.
+function expectProblems(facts, expect = {}) {
+  const p = [];
+  const eq = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+  if (expect.expanded === true && !facts.expanded.length) p.push('expected an [aria-expanded="true"] trigger');
+  if (expect.expanded === false && facts.expanded.length) p.push(`expected no expanded trigger, found ${facts.expanded.join(', ')}`);
+  if (expect.dialog === true && !facts.dialog) p.push('expected a visible dialog');
+  if (expect.dialog === false && facts.dialog) p.push('expected no visible dialog');
+  for (const s of expect.visible || []) if (!facts.sel[s]) p.push(`expected visible: ${s}`);
+  for (const s of expect.hidden || []) if (facts.sel[s]) p.push(`expected hidden: ${s}`);
+  if (expect.open && !facts.sel[expect.open]) p.push(`expected open: ${expect.open}`);
+  if (expect.closed && facts.sel[expect.closed]) p.push(`expected closed: ${expect.closed}`);
+  if (expect.activeId !== undefined && facts.activeId !== expect.activeId) p.push(`active element #${facts.activeId || '(none)'}, expected #${expect.activeId}`);
+  if (expect.activeText !== undefined && facts.activeText !== expect.activeText) p.push(`active text "${facts.activeText}", expected "${expect.activeText}"`);
+  if (expect.expandedIds && !eq([...facts.expanded].sort(), [...expect.expandedIds].sort())) p.push(`expanded [${facts.expanded.join(',')}], expected [${expect.expandedIds.join(',')}]`);
+  if (expect.param) for (const [k, v] of Object.entries(expect.param)) if ((facts.param || {})[k] !== v) p.push(`?${k}=${(facts.param || {})[k]}, expected ${v}`);
+  (expect.attr || []).forEach(([s, n, v], i) => { if (facts.attr[i] !== v) p.push(`${s}[${n}]="${facts.attr[i]}", expected "${v}"`); });
+  (expect.text || []).forEach(([s, v], i) => { if (facts.text[i] !== v) p.push(`${s} text "${facts.text[i]}", expected "${v}"`); });
+  (expect.href || []).forEach(([s, v], i) => { if (facts.href[i] !== v) p.push(`${s} href "${facts.href[i]}", expected "${v}"`); });
+  (expect.count || []).forEach(([s, n], i) => { if (facts.count[i] !== n) p.push(`${facts.count[i]} × ${s}, expected ${n}`); });
+  if (expect.checked !== undefined && facts.checked !== true) p.push(`${expect.checked} is not checked`);
+  (expect.value || []).forEach(([s, v], i) => { if (facts.value[i] !== v) p.push(`${s} value "${facts.value[i]}", expected "${v}"`); });
+  (expect.hasClass || []).forEach(([s, c, want = true], i) => { if (facts.hasClass[i] !== want) p.push(`${s} ${want ? 'lacks' : 'still has'} class "${c}"`); });
+  if (expect.noOverflow && facts.scrollWidth > facts.clientWidth + 1) p.push(`horizontal overflow ${facts.scrollWidth} > ${facts.clientWidth}`);
+  return p;
+}
+// Pure: the floor problems in one render. `mode` is the requested colour scheme;
+// a page that carries data-mode must agree with it.
+function auditFloors(facts, { width, mode } = {}) {
+  const p = [];
+  if (facts.scrollWidth > facts.clientWidth + 1) p.push(`horizontal-overflow: scrollWidth ${facts.scrollWidth} > ${width || facts.clientWidth}`);
+  if (facts.headers !== 1 || facts.mains !== 1 || facts.h1s !== 1) p.push(`one-header-main-h1: header ${facts.headers} main ${facts.mains} h1 ${facts.h1s}`);
+  if (facts.smallControls && facts.smallControls.length) p.push(`controls-24px: ${facts.smallControls.join(' | ')}`);
+  if (facts.bar && facts.bar.h > 80) p.push(`top-bar-80px: header is ${facts.bar.h}px`);
+  if (mode && facts.mode && facts.mode !== mode) p.push(`data-mode "${facts.mode}" under a ${mode} scheme`);
+  return p;
+}
+function reducedMotionProblems({ running = [], frames = 0 } = {}) {
+  const p = [];
+  if (running.length) p.push(`reduced-motion: ${running.length} animation(s) still running (${running.slice(0, 5).join(', ')})`);
+  if (frames > 2) p.push(`reduced-motion: a requestAnimationFrame loop (${frames} frames in 800ms)`);
+  return p;
+}
+
+// ── the states file ───────────────────────────────────────────────────────────
+// { "page": "/projects", "surface"?: "public-landing", "stub"?: { prefix?, child? },
+//   "modeQuery"?: "mode" | false, "ignoreRequests"?: [regex strings], "ignoreConsole"?: [...],
+//   "ignoreControls"?: [selectors], "states": { name: { url?, auth?, actions?, expect? } },
+//   "reducedMotion"?: { auth?, url?, actions? } }
+function validateStatesFile(json) {
+  if (!json || typeof json !== 'object' || Array.isArray(json)) return { ok: false, errors: ['a states file is a JSON object'] };
+  const errors = [];
+  if (typeof json.page !== 'string' || !json.page.startsWith('/')) errors.push('page: required — the root-relative path the states render (e.g. "/projects")');
+  if (json.surface !== undefined && typeof json.surface !== 'string') errors.push('surface: a string (a checkout dir or a module key)');
+  errors.push(...validateStub(json.stub, 'stub'));
+  if (json.modeQuery !== undefined && json.modeQuery !== false && typeof json.modeQuery !== 'string') errors.push('modeQuery: the query param the page reads for its colour mode (default "mode"), or false');
+  for (const k of ['ignoreRequests', 'ignoreConsole', 'ignoreControls']) if (json[k] !== undefined && !(Array.isArray(json[k]) && json[k].every((s) => typeof s === 'string'))) errors.push(`${k}: an array of strings`);
+  const states = json.states;
+  if (!states || typeof states !== 'object' || Array.isArray(states) || !Object.keys(states).length) errors.push('states: required — a non-empty object of name → { url?, auth?, actions?, expect? }');
+  else {
+    for (const [name, s] of Object.entries(states)) {
+      if (!/^[a-z0-9][a-z0-9-]*$/.test(name)) errors.push(`states.${name}: names are lowercase kebab-case (they name the screenshots)`);
+      if (!s || typeof s !== 'object' || Array.isArray(s)) { errors.push(`states.${name}: an object`); continue; }
+      if (s.url !== undefined && (typeof s.url !== 'string' || !s.url.startsWith('/'))) errors.push(`states.${name}.url: a root-relative path`);
+      if (s.auth !== undefined && typeof s.auth !== 'boolean') errors.push(`states.${name}.auth: true (signed-in stub) or false`);
+      errors.push(...validateActions(s.actions, `states.${name}.actions`));
+      errors.push(...validateExpect(s.expect, `states.${name}.expect`));
+    }
+  }
+  if (json.reducedMotion !== undefined) {
+    const r = json.reducedMotion;
+    if (!r || typeof r !== 'object' || Array.isArray(r)) errors.push('reducedMotion: an object { auth?, url?, actions? }');
+    else { if (r.auth !== undefined && typeof r.auth !== 'boolean') errors.push('reducedMotion.auth: boolean'); errors.push(...validateActions(r.actions, 'reducedMotion.actions')); }
+  }
+  return { ok: !errors.length, errors };
+}
+function validateStub(stub, at) {
+  if (stub === undefined) return [];
+  if (!stub || typeof stub !== 'object' || Array.isArray(stub)) return [`${at}: an object { prefix?, child? }`];
+  const errors = [];
+  if (stub.prefix !== undefined && (typeof stub.prefix !== 'string' || !stub.prefix.startsWith('/') || !stub.prefix.endsWith('/'))) errors.push(`${at}.prefix: a URL prefix like "/builders/"`);
+  if (stub.child !== undefined && typeof stub.child !== 'boolean') errors.push(`${at}.child: boolean (serve the child-instance shape)`);
+  return errors;
+}
+
+// ── the probes file ───────────────────────────────────────────────────────────
+// { "page": "/projects", "surface"?, "stub"?, "probes": [ { "name", "auth"?, "width"?,
+//   "url"?, "continue"?: true, "steps": [...], "expect": {...} } ] }
+function validateProbesFile(json) {
+  if (!json || typeof json !== 'object' || Array.isArray(json)) return { ok: false, errors: ['a probes file is a JSON object'] };
+  const errors = [];
+  if (typeof json.page !== 'string' || !json.page.startsWith('/')) errors.push('page: required — the root-relative path the probes open');
+  errors.push(...validateStub(json.stub, 'stub'));
+  if (!Array.isArray(json.probes) || !json.probes.length) errors.push('probes: required — a non-empty array');
+  else json.probes.forEach((pr, i) => {
+    const at = `probes[${i}]`;
+    if (!pr || typeof pr !== 'object') { errors.push(`${at}: an object`); return; }
+    if (typeof pr.name !== 'string' || !pr.name) errors.push(`${at}.name: required`);
+    if (pr.auth !== undefined && typeof pr.auth !== 'boolean') errors.push(`${at}.auth: boolean`);
+    if (pr.width !== undefined && !SIZES[pr.width]) errors.push(`${at}.width: one of ${Object.keys(SIZES).join(', ')}`);
+    if (pr.url !== undefined && (typeof pr.url !== 'string' || !pr.url.startsWith('/'))) errors.push(`${at}.url: a root-relative path`);
+    if (pr.continue !== undefined && typeof pr.continue !== 'boolean') errors.push(`${at}.continue: boolean (reuse the previous probe's page)`);
+    if (pr.continue && i === 0) errors.push(`${at}.continue: the first probe has nothing to continue`);
+    errors.push(...validateActions(pr.steps, `${at}.steps`));
+    if (!pr.expect || typeof pr.expect !== 'object' || !Object.keys(pr.expect).length) errors.push(`${at}.expect: required — a probe with nothing to expect proves nothing`);
+    else errors.push(...validateExpect(pr.expect, `${at}.expect`));
+  });
+  return { ok: !errors.length, errors };
+}
+
+// ── browser ───────────────────────────────────────────────────────────────────
+class NoBrowserError extends Error {}
+async function launchBrowser() {
+  let pw;
+  try { pw = require('playwright-core'); }
+  catch { throw new NoBrowserError('playwright-core is not installed — run `npm install` (a devDependency; the kit never downloads a browser, it drives the system Edge or Chrome).'); }
+  const tried = [];
+  for (const channel of CHANNELS) {
+    try { return await pw.chromium.launch({ channel, headless: true }); }
+    catch (e) { tried.push(`${channel}: ${String(e.message).split('\n')[0]}`); }
+  }
+  throw new NoBrowserError(`no system browser: neither Microsoft Edge nor Google Chrome launched. Install one; the kit does not download browsers. (${tried.join(' | ')})`);
+}
+// Wire the listeners a render needs: console errors, uncaught errors, failed
+// responses — each filtered by the file's ignore lists (regex sources).
+function attachCollectors(page, { ignoreRequests = [], ignoreConsole = [] } = {}) {
+  const logs = [];
+  const req = ignoreRequests.map((s) => new RegExp(s));
+  const con = ignoreConsole.map((s) => new RegExp(s));
+  page.on('console', (m) => { if (m.type() === 'error' && !con.some((r) => r.test(m.text()))) logs.push('console-errors: ' + m.text().slice(0, 200)); });
+  page.on('pageerror', (e) => logs.push('console-errors: uncaught ' + String(e.message).split('\n')[0]));
+  page.on('response', (r) => { if (r.status() >= 400 && !req.some((x) => x.test(r.url()))) logs.push(`failed-requests: ${r.status()} ${r.url()}`); });
+  return logs;
+}
+function withMode(url, mode, modeQuery) {
+  if (modeQuery === false) return url;
+  const q = modeQuery || 'mode';
+  return `${url}${url.includes('?') ? '&' : '?'}${q}=${mode}`;
+}
+
+// ── the stub spawner ──────────────────────────────────────────────────────────
+function freePort() {
+  return new Promise((resolve, reject) => {
+    const s = net.createServer();
+    s.on('error', reject);
+    s.listen(0, '127.0.0.1', () => { const p = s.address().port; s.close(() => resolve(p)); });
+  });
+}
+async function startStub({ surface, auth = false, port, prefix, child = false } = {}) {
+  const p = port || await freePort();
+  const env = { ...process.env, STUB_PORT: String(p), AUTH: auth ? '1' : '0', CHILD: child ? '1' : '0' };
+  if (surface) env.SURFACE = surface;
+  if (prefix) env.PREFIX = prefix;
+  const proc = spawn(process.execPath, [path.join(KIT_DIR, 'serve.js')], { env, stdio: ['ignore', 'pipe', 'pipe'] });
+  await new Promise((resolve, reject) => {
+    let out = '';
+    const timer = setTimeout(() => reject(new Error('the stub did not start within 15s: ' + out.trim())), 15000);
+    proc.stdout.on('data', (d) => { out += d; if (/stub on http/.test(out)) { clearTimeout(timer); resolve(); } });
+    proc.stderr.on('data', (d) => { out += d; });
+    proc.on('exit', (code) => { clearTimeout(timer); reject(new Error(`the stub exited ${code}: ${out.trim()}`)); });
+  });
+  return { base: `http://127.0.0.1:${p}`, port: p, stop: () => { try { proc.kill(); } catch { /* gone */ } } };
+}
+
+// ── WCAG maths (pure) ─────────────────────────────────────────────────────────
+function parseColor(str) {
+  const s = String(str || '').trim();
+  let m = s.match(/^rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*(?:,\s*([\d.]+))?\s*\)$/i) || s.match(/^rgba?\(\s*([\d.]+)\s+([\d.]+)\s+([\d.]+)\s*(?:\/\s*([\d.%]+))?\s*\)$/i);
+  if (m) return [+m[1], +m[2], +m[3], m[4] === undefined ? 1 : (String(m[4]).endsWith('%') ? parseFloat(m[4]) / 100 : +m[4])];
+  m = s.match(/^#([0-9a-f]{3,8})$/i);
+  if (!m) return null;
+  let h = m[1];
+  if (h.length === 3 || h.length === 4) h = [...h].map((c) => c + c).join('');
+  if (h.length !== 6 && h.length !== 8) return null;
+  return [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16), h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1];
+}
+function composite(fg, bg) { const a = fg[3] == null ? 1 : fg[3]; return [fg[0] * a + bg[0] * (1 - a), fg[1] * a + bg[1] * (1 - a), fg[2] * a + bg[2] * (1 - a), 1]; }
+function luminance(c) { const f = (v) => { v /= 255; return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4); }; return 0.2126 * f(c[0]) + 0.7152 * f(c[1]) + 0.0722 * f(c[2]); }
+function contrastRatio(a, b) { const l1 = luminance(a), l2 = luminance(b); const [hi, lo] = l1 > l2 ? [l1, l2] : [l2, l1]; return (hi + 0.05) / (lo + 0.05); }
+
+// The instance's resolved branding pack through the doorway — the only core
+// reach the kit makes (task 1003320). Loaded lazily: the pure helpers above never
+// touch it, so the test pins them without booting the doorway.
+function instancePack() {
+  const api = require(path.join(REPO_ROOT, 'src', 'module-api.js'));
+  return api.clientBranding();
+}
+// The fifteen's colours off a pack in either shape: the FILE shape (theme.ui.colors,
+// config/branding*.json) or the CLIENT shape clientBranding() serves (theme.colors —
+// the ui block flattened onto theme). Same values; the resolver flattens.
+function packColors(pack) {
+  const theme = (pack && pack.theme) || {};
+  return (theme.ui && theme.ui.colors) || theme.colors || (pack && pack.colors) || {};
+}
+
+module.exports = {
+  REPO_ROOT, KIT_DIR, EXIT, FLOORS, SIZES, MODES, CHANNELS, SETTLE_MS, ACTIONS, EXPECT_KEYS,
+  argOf, hasFlag, listArg, pageName, normalizePageArg, resolveSurfaceDir, sidecarPath, readJson,
+  validateActions, runActions, validateExpect, factsInPage, expectProblems, auditFloors, reducedMotionProblems,
+  validateStatesFile, validateProbesFile, NoBrowserError, launchBrowser, attachCollectors, withMode,
+  freePort, startStub, parseColor, composite, luminance, contrastRatio, instancePack, packColors,
+};

package/modules/ui-design/kit/png.js

@@ -0,0 +1,51 @@
+'use strict';
+// png.js — a minimal PNG decoder (8-bit grey/RGB/RGBA, non-interlaced) → { w, h,
+// data: RGBA Buffer }, so the kit can read the pixels of a screenshot without a
+// dependency. Ported from the apex review pass's glyph probe (task 1003320).
+const zlib = require('node:zlib');
+
+function decode(buf) {
+  if (buf.readUInt32BE(0) !== 0x89504e47) throw new Error('not a PNG');
+  let off = 8, w = 0, h = 0, bitDepth = 0, colorType = 0, interlace = 0;
+  const idat = [];
+  while (off < buf.length) {
+    const len = buf.readUInt32BE(off);
+    const type = buf.toString('ascii', off + 4, off + 8);
+    const data = buf.subarray(off + 8, off + 8 + len);
+    if (type === 'IHDR') { w = data.readUInt32BE(0); h = data.readUInt32BE(4); bitDepth = data[8]; colorType = data[9]; interlace = data[12]; }
+    else if (type === 'IDAT') idat.push(data);
+    else if (type === 'IEND') break;
+    off += 12 + len;
+  }
+  if (bitDepth !== 8 || interlace !== 0) throw new Error(`unsupported PNG (bit depth ${bitDepth}, interlace ${interlace})`);
+  const ch = colorType === 6 ? 4 : colorType === 2 ? 3 : colorType === 0 ? 1 : -1;
+  if (ch < 0) throw new Error(`unsupported PNG colour type ${colorType}`);
+  const raw = zlib.inflateSync(Buffer.concat(idat));
+  const stride = w * ch;
+  const out = Buffer.alloc(w * h * 4);
+  let prev = Buffer.alloc(stride);
+  let p = 0;
+  for (let y = 0; y < h; y++) {
+    const ft = raw[p++];
+    const line = Buffer.from(raw.subarray(p, p + stride)); p += stride;
+    for (let i = 0; i < stride; i++) {
+      const a = i >= ch ? line[i - ch] : 0, b = prev[i], c = i >= ch ? prev[i - ch] : 0;
+      let v = line[i];
+      if (ft === 1) v = (v + a) & 255;
+      else if (ft === 2) v = (v + b) & 255;
+      else if (ft === 3) v = (v + ((a + b) >> 1)) & 255;
+      else if (ft === 4) { const pp = a + b - c, pa = Math.abs(pp - a), pb = Math.abs(pp - b), pc = Math.abs(pp - c); v = (v + (pa <= pb && pa <= pc ? a : pb <= pc ? b : c)) & 255; }
+      line[i] = v;
+    }
+    for (let x = 0; x < w; x++) {
+      const s = x * ch, d = (y * w + x) * 4;
+      if (ch === 1) { out[d] = out[d + 1] = out[d + 2] = line[s]; out[d + 3] = 255; }
+      else { out[d] = line[s]; out[d + 1] = line[s + 1]; out[d + 2] = line[s + 2]; out[d + 3] = ch === 4 ? line[s + 3] : 255; }
+    }
+    prev = line;
+  }
+  return { w, h, data: out };
+}
+const px = (img, x, y) => { const d = (y * img.w + x) * 4; return [img.data[d], img.data[d + 1], img.data[d + 2]]; };
+
+module.exports = { decode, px };

package/modules/ui-design/kit/probe.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+'use strict';
+// probe.js — interaction contracts as PASS/FAIL lines (task 1003320, ADR 0197).
+// A probes file beside the surface (<dir>/<page>.probes.json) lists probes: each
+// opens the page (signed in or out, at a width), drives steps from the shared
+// action vocabulary, then states what must be true (the expectation vocabulary
+// in lib.js). The disclosure contract ships as the first: Enter opens on the
+// first item, arrows cycle and skip hidden cells, Escape returns focus, Tab out
+// closes, a click outside closes, one closes the other; the fold under 480; a
+// dialog yields Escape; signed out nothing throws.
+//
+//   node modules/ui-design/kit/probe.js --page /projects [--surface <dir|key>] [--probes <file>] [--only <substring>]
+//     --base-out <url> --base-in <url>   use running stubs instead of starting two
+//
+// A probe with `continue: true` keeps the previous probe's page (a contract is a
+// sequence). An uncaught page error during a probe fails it. Exit 0 ALL PASS ·
+// 1 FAIL(s) · 2 usage/contract · 3 no browser.
+const fs = require('node:fs');
+const path = require('node:path');
+const lib = require('./lib.js');
+
+function usage(msg) {
+  process.stderr.write(`probe: ${msg}\n  node modules/ui-design/kit/probe.js --page /projects [--surface <dir|key>] [--probes <file>] [--only <substring>] [--base-out <url> --base-in <url>]\n`);
+  process.exit(lib.EXIT.USAGE);
+}
+function locate(args) {
+  const explicit = lib.argOf(args, '--probes', null);
+  let file = explicit && path.resolve(explicit);
+  if (!file) {
+    const page = lib.normalizePageArg(lib.argOf(args, '--page', null));
+    if (!page) usage('--page </path> or --probes <file> is required');
+    const dir = lib.resolveSurfaceDir(lib.argOf(args, '--surface', 'public-landing'));
+    if (!dir) usage(`--surface does not resolve to a directory`);
+    file = lib.sidecarPath(dir, page, 'probes');
+  }
+  if (!fs.existsSync(file)) usage(`probes file not found: ${file}`);
+  let json;
+  try { json = lib.readJson(file); } catch (e) { usage(`probes file is not JSON: ${e.message}`); }
+  const v = lib.validateProbesFile(json);
+  if (!v.ok) usage(`${path.relative(lib.REPO_ROOT, file)} breaks the probes contract:\n  - ${v.errors.join('\n  - ')}`);
+  const surface = json.surface || lib.argOf(args, '--surface', null) || path.relative(lib.REPO_ROOT, path.dirname(file)).split(path.sep).join('/');
+  return { file, json, surface };
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (lib.hasFlag(args, '--help')) usage('');
+  const { json, surface } = locate(args);
+  const only = lib.argOf(args, '--only', null);
+  const probes = json.probes.filter((p) => !only || p.name.includes(only));
+  if (!probes.length) usage('--only matches no probe');
+
+  const stubs = [];
+  let baseOut = lib.argOf(args, '--base-out', null), baseIn = lib.argOf(args, '--base-in', null);
+  const stubOpts = { surface, prefix: json.stub && json.stub.prefix, child: json.stub && json.stub.child };
+  if (!baseOut) { const s = await lib.startStub({ ...stubOpts, auth: false }); stubs.push(s); baseOut = s.base; }
+  if (!baseIn) { const s = await lib.startStub({ ...stubOpts, auth: true }); stubs.push(s); baseIn = s.base; }
+  const stop = () => stubs.forEach((s) => s.stop());
+  let browser;
+  try { browser = await lib.launchBrowser(); }
+  catch (e) { stop(); process.stderr.write(`probe: ${e.message}\n`); process.exit(e instanceof lib.NoBrowserError ? lib.EXIT.NO_BROWSER : lib.EXIT.USAGE); }
+
+  const results = [];
+  const check = (name, problems) => { results.push([name, !problems.length]); process.stdout.write(`${problems.length ? 'FAIL' : 'PASS'}  ${name}${problems.length ? '  (' + problems.join('; ') + ')' : ''}\n`); };
+  let ctx = null, page = null, errors = [];
+  try {
+    for (const pr of probes) {
+      if (!(pr.continue && page)) {
+        if (ctx) await ctx.close();
+        const [W, H] = lib.SIZES[pr.width || 1440];
+        ctx = await browser.newContext({ viewport: { width: W, height: H }, deviceScaleFactor: 1 });
+        page = await ctx.newPage();
+        errors = [];
+        page.on('pageerror', (e) => errors.push(String(e.message).split('\n')[0]));
+        await page.goto((pr.auth ? baseIn : baseOut) + (pr.url || json.page), { waitUntil: 'load' });
+        await page.evaluate(() => document.fonts.ready);
+        await page.waitForTimeout(lib.SETTLE_MS);
+      } else {
+        errors.length = 0;
+      }
+      const problems = [];
+      try { await lib.runActions(page, pr.steps); } catch (e) { problems.push('step failed: ' + String(e.message).split('\n')[0]); }
+      await page.waitForTimeout(120);
+      let facts = null;
+      try { facts = await page.evaluate(lib.factsInPage, { expect: pr.expect }); } catch (e) { problems.push('facts failed: ' + String(e.message).split('\n')[0]); }
+      if (facts) problems.push(...lib.expectProblems(facts, pr.expect));
+      if (errors.length) problems.push('page error: ' + errors.join(' | '));
+      check(pr.name, problems);
+    }
+  } finally {
+    if (ctx) await ctx.close();
+    await browser.close();
+    stop();
+  }
+  const fails = results.filter((r) => !r[1]).length;
+  process.stdout.write(`\n${results.length} probe(s): ${fails ? `${fails} FAIL(S)` : 'ALL PASS'}\n`);
+  process.exit(fails ? lib.EXIT.PROBLEMS : lib.EXIT.CLEAN);
+}
+
+main().catch((e) => { process.stderr.write(`probe: ${e.stack || e.message}\n`); process.exit(lib.EXIT.USAGE); });