@bongos/core 1.19.993 → 1.19.995

package/scripts/gds/render-check.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+'use strict';
+// scripts/gds/render-check.js — render the pages a branch changed and report text wider than its box and
+// overlapping siblings, naming the element and the page (task 1004203, ADR 0329).
+//
+// Why: nothing else in the pipeline renders a page. The grader reads the diff, so a title clipped by character
+// count that still ran past its card (task 1003480) and a second grid child landing on the first (task 1003078)
+// both shipped looking correct in code and were found only by opening a browser.
+//
+// A SIGNAL, never a gate (ADR 0162): /ship-check shows it as an advisory row; ship.js and the grader never
+// read it. The measurement is the kit's `text-fit` + `sibling-overlap` floors (modules/ui-design/kit/lib.js);
+// this file only picks the pages, runs the kit's renderer at 1280 + 390, and keeps those two floors.
+//
+//   node scripts/gds/render-check.js                     the pages this branch changed against origin/main
+//   node scripts/gds/render-check.js --base <ref>        ... against another base
+//   node scripts/gds/render-check.js --files a,b         the pages these repo paths reach
+//
+// Exit 0 nothing found or nothing to render · 1 findings · 3 no system browser.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawn, spawnSync } = require('node:child_process');
+const { isUiSurfacePath } = require('../../modules/lifecycle/cascade');
+const kit = require('../../modules/ui-design/kit/lib');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const RENDER_JS = path.join(REPO_ROOT, 'modules', 'ui-design', 'kit', 'render.js');
+const HARNESS_JS = path.join(REPO_ROOT, 'scripts', 'hall-preview', 'server.js');
+const FIT_FLOORS = Object.freeze(['text-fit', 'sibling-overlap']);
+const SIZES = Object.freeze([1280, 390]);
+const MAX_STATES_FILES = 6; // a shared sheet reaches every page; past this the builder runs render.js by hand
+// The whole run fits inside ship-check's 15-minute cap on a slow step, so ship-check never has to kill it
+// (a killed parent cannot stop its harness and renderers). Files that would start past it are listed instead.
+const RUN_BUDGET_MS = 12 * 60 * 1000;
+const MIN_RENDER_MS = 60 * 1000;
+const HARNESS_BOOT_MS = 30 * 1000;
+const rel = (file) => path.relative(REPO_ROOT, file).split(path.sep).join('/');
+
+// statesFilesFor — the states files a list of changed repo paths reaches. A page, or a file named like one
+// (goal-map.js), reaches its own <page>.states.json; any other script, sheet or image reaches every page in
+// the same public dir whose HTML names it (text-fit.js → goal-map, goals). Own pages come first, so the
+// MAX_STATES_FILES cut never drops the page the builder changed for pages a shared sheet reaches.
+function statesFilesFor(paths, root = REPO_ROOT) {
+  const own = new Set(), reached = new Set();
+  for (const p of paths) {
+    if (!isUiSurfacePath(p)) continue;
+    const dir = p.slice(0, p.indexOf('/public/') + '/public'.length);
+    const file = p.slice(dir.length + 1);
+    const beside = path.join(root, dir, `${file.replace(/\.[^./]+$/, '')}.states.json`);
+    if (!file.includes('/') && fs.existsSync(beside)) { own.add(beside); continue; }
+    if (/\.html?$/i.test(file) || !fs.existsSync(path.join(root, dir))) continue;
+    const named = new RegExp(`(^|[/"'=\\s])${path.basename(file).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`);
+    for (const html of fs.readdirSync(path.join(root, dir)).filter((f) => f.endsWith('.html'))) {
+      const states = path.join(root, dir, html.replace(/\.html$/, '.states.json'));
+      if (fs.existsSync(states) && named.test(fs.readFileSync(path.join(root, dir, html), 'utf8'))) reached.add(states);
+    }
+  }
+  return [...[...own].sort(), ...[...reached].filter((f) => !own.has(f)).sort()];
+}
+
+// fitFindings — every element the two fit floors named in one render.js report.json, read from the
+// structured facts (auditFloors' problem line stops at five). One finding per element across all the
+// renders it appeared in, with its largest measure — a title past its card at 1280 and 390 is one finding.
+const MEASURE = / (\d+)px past its (?:box|card)$| (\d+)x(\d+)$/;
+function fitFindings(report) {
+  const byElement = new Map();
+  for (const [render, r] of Object.entries((report && report.renders) || {})) {
+    const facts = (r && r.facts) || {};
+    for (const [floor, items] of [['text-fit', facts.textFit], ['sibling-overlap', facts.overlaps]]) {
+      for (const item of items || []) {
+        const m = MEASURE.exec(item);
+        const key = `${floor}: ${m ? item.slice(0, m.index) : item}`;
+        const size = m ? (m[1] ? Number(m[1]) : Number(m[2]) * Number(m[3])) : 0;
+        if (!byElement.has(key)) byElement.set(key, { key, measure: '', size: -1, renders: [] });
+        const f = byElement.get(key);
+        f.renders.push(render);
+        if (size > f.size) { f.size = size; f.measure = m ? m[0].trim() : ''; }
+      }
+    }
+  }
+  return [...byElement.values()].map((f) => ({ page: report.page, problem: f.measure ? `${f.key} — ${f.measure}` : f.key, renders: f.renders }));
+}
+
+// Two pages of one name (hall-ui/index, public-landing/index) must never share a shots folder.
+function shotsDir(outRoot, file) {
+  return path.join(outRoot, rel(file).replace(/\.states\.json$/, '').replace(/[\\/]/g, '_'));
+}
+
+function changedFiles(base) {
+  const git = (...args) => spawnSync('git', args, { cwd: REPO_ROOT, encoding: 'utf8' });
+  const mergeBase = git('merge-base', base, 'HEAD').stdout.trim();
+  if (!mergeBase) return null;
+  const listed = `${git('diff', '--name-only', mergeBase).stdout}\n${git('ls-files', '--others', '--exclude-standard').stdout}`;
+  return [...new Set(listed.split(/\r?\n/).filter(Boolean))];
+}
+
+// Kill a child and everything it started (render.js starts two stubs and a browser).
+const DETACH = process.platform !== 'win32';
+function killTree(child) {
+  if (!child || child.exitCode !== null || child.signalCode !== null) return;
+  try {
+    if (process.platform === 'win32') spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
+    else process.kill(-child.pid, 'SIGKILL');
+  } catch { /* already gone */ }
+}
+
+// The hall's states files are written against the hall-preview harness (their notes say so): its fixtures
+// carry the populated pages, where the kit's own stub serves the hall its signed-out, empty reads. Its
+// output is read for the whole run, since a pipe left unread fills and stalls it mid-render.
+async function startHarness({ script = HARNESS_JS, bootMs = HARNESS_BOOT_MS } = {}) {
+  const port = await kit.freePort();
+  const proc = spawn(process.execPath, [script, '--port', String(port), '--fixture-me'], { cwd: REPO_ROOT, stdio: ['ignore', 'pipe', 'pipe'], detached: DETACH });
+  const stop = () => killTree(proc);
+  await new Promise((resolve, reject) => {
+    let said = '', ready = false;
+    const fail = (why) => { clearTimeout(timer); stop(); reject(new Error(`${why}: ${said.trim()}`)); };
+    const timer = setTimeout(() => fail(`the hall-preview harness did not start within ${bootMs / 1000}s`), bootMs);
+    const hear = (d) => {
+      if (ready) return;
+      said += d;
+      if (/hall-preview: http/.test(said)) { ready = true; clearTimeout(timer); resolve(); }
+    };
+    proc.stdout.on('data', hear);
+    proc.stderr.on('data', hear);
+    proc.on('exit', (code) => { if (!ready) fail(`the hall-preview harness exited ${code}`); });
+  });
+  return { base: `http://localhost:${port}`, pid: proc.pid, stop };
+}
+
+// Run a node script without blocking the event loop (the harness's pipes keep draining meanwhile);
+// past timeoutMs the script and everything it started are killed.
+function runNode(args, timeoutMs) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, args, { cwd: REPO_ROOT, stdio: ['ignore', 'ignore', 'pipe'], detached: DETACH });
+    let stderr = '';
+    child.stderr.on('data', (d) => { if (stderr.length < 4000) stderr += d; });
+    const timer = setTimeout(() => killTree(child), timeoutMs);
+    child.on('error', (e) => { clearTimeout(timer); resolve({ status: null, signal: null, stderr: e.message }); });
+    child.on('close', (status, signal) => { clearTimeout(timer); resolve({ status, signal, stderr }); });
+  });
+}
+
+// One states file through the kit's renderer: { findings, note?, noBrowser? }. ONE colour mode (the file's
+// first): the fit floors measure geometry, and the pack's two font stacks are the same in both modes. No
+// reduced-motion pass either — only the fit floors are read. render.js still runs everything when asked.
+async function renderStatesFile(file, { outRoot, harness, timeoutMs }) {
+  const json = kit.readJson(file);
+  const out = shotsDir(outRoot, file);
+  const mode = (json.modes || kit.MODES)[0];
+  const args = [RENDER_JS, '--states', file, '--sizes', SIZES.join(','), '--modes', mode, '--no-reduced-motion', '--out', out];
+  if (json.surface === 'hall-ui' && harness) args.push('--base-in', harness.base, '--base-out', harness.base);
+  const r = await runNode(args, timeoutMs);
+  if (r.status === kit.EXIT.NO_BROWSER) return { findings: [], noBrowser: true, note: String(r.stderr || '').trim().split('\n')[0] };
+  const reportFile = path.join(out, 'report.json');
+  if (r.status === kit.EXIT.USAGE || !fs.existsSync(reportFile)) {
+    const why = String(r.stderr || `exit ${r.status}${r.signal ? ` (${r.signal})` : ''}`).trim().split('\n').slice(0, 2).join(' ');
+    return { findings: [], note: `${rel(file)}: the renderer produced no report — ${why}` };
+  }
+  return { findings: fitFindings(kit.readJson(reportFile)), out };
+}
+
+async function main() {
+  const started = Date.now();
+  const args = process.argv.slice(2);
+  const explicit = kit.listArg(args, '--files', null);
+  const paths = explicit || changedFiles(kit.argOf(args, '--base', 'origin/main'));
+  if (!paths) { console.log('render-check: no merge base with origin/main — nothing to compare against, nothing rendered'); return 0; }
+  const all = statesFilesFor(paths);
+  const uiCount = paths.filter(isUiSurfacePath).length;
+  if (!all.length) {
+    console.log(uiCount
+      ? `render-check: ${uiCount} rendered-surface file(s) changed, but no <page>.states.json reaches them — nothing to measure (docs/recipes/ui-look-before-you-ship.md)`
+      : 'render-check: no rendered surface changed — nothing to render');
+    return 0;
+  }
+  const outRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'render-check-'));
+  console.log(`render-check — text past its box and overlapping siblings at ${SIZES.join(' + ')} (a signal, never a gate)`);
+  let harness = null;
+  const findings = [], notes = [], unrendered = all.slice(MAX_STATES_FILES).map((f) => [f, `past ${MAX_STATES_FILES}`]);
+  try {
+    const files = all.slice(0, MAX_STATES_FILES);
+    if (files.some((f) => kit.readJson(f).surface === 'hall-ui')) harness = await startHarness();
+    for (const [i, file] of files.entries()) {
+      const left = RUN_BUDGET_MS - (Date.now() - started);
+      if (left < MIN_RENDER_MS) { unrendered.unshift(...files.slice(i).map((f) => [f, 'out of time'])); break; }
+      const res = await renderStatesFile(file, { outRoot, harness, timeoutMs: left });
+      if (res.noBrowser) { console.log(`render-check: no system browser, nothing rendered — ${res.note}`); return kit.EXIT.NO_BROWSER; }
+      if (res.note) notes.push(res.note);
+      findings.push(...res.findings.map((x) => ({ ...x, shots: res.out })));
+      console.log(`  ${rel(file)}: ${res.findings.length ? `${res.findings.length} finding(s)` : res.note ? 'no report' : 'clean'}${res.out ? `  (shots: ${res.out})` : ''}`);
+    }
+  } finally {
+    if (harness) harness.stop();
+  }
+  for (const [f, why] of unrendered) console.log(`  not rendered (${why}): node modules/ui-design/kit/render.js --states ${rel(f)} --sizes 1280,390`);
+  for (const n of notes) console.log(`✗ ${n}`);
+  for (const f of findings) console.log(`✗ ${f.page} ${f.problem}  [${f.renders.join(', ')}]  shots: ${f.shots}`);
+  const unmeasured = notes.length ? `; ${notes.length} states file(s) not measured` : '';
+  console.log(findings.length || notes.length ? `${findings.length} finding(s)${unmeasured} — look at the shots, then fix the element or say in the ship notes why it is right` : 'nothing past its box, no overlapping siblings');
+  return findings.length || notes.length ? 1 : 0;
+}
+
+module.exports = { FIT_FLOORS, SIZES, statesFilesFor, fitFindings, shotsDir, startHarness };
+if (require.main === module) {
+  main().then((code) => { process.exitCode = code; }, (e) => { console.error(`render-check: ${e.stack || e.message}`); process.exitCode = 1; });
+}

package/scripts/gds/ship-check.js

@@ -10,7 +10,9 @@
 // call with one table. It CHANGES NOTHING: every step is a --check; the "fix" column is what to run.
 //
 // Usage:
-//   node scripts/gds/ship-check.js            checks only (fast; no tests)
+//   node scripts/gds/ship-check.js            checks only (fast; no tests) — plus, when the branch changed a
+//                                             page, an ADVISORY render of it (render-check.js; never flips the exit;
+//                                             minutes on a big page — --no-render skips it)
 //   node scripts/gds/ship-check.js --tests    also run the DB-free unit lane (npm test) and list failures
 //   node scripts/gds/ship-check.js --json
 // Exit 1 when any check is stale/failing, 0 when everything is fresh.
@@ -22,7 +24,9 @@ const path = require('node:path');
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
 
 // Each step: a label, the argv to run (node scripts run with THIS node), the command that heals it,
-// and how to read a non-zero exit. `optional` steps are skipped when their script is absent.
+// and how to read a non-zero exit. `optional` steps are skipped when their script is absent. An `advisory`
+// step is a signal, never a gate (ADR 0162): a non-zero exit reads `warn` (3 = no browser reads `skipped`).
+// `onlyWith` names the flag that adds a step; `skipWith` the flag that leaves one out.
 const STEPS = [
   { key: 'fitness', label: 'fitness.js (architecture + budgets + freshness gate)', argv: ['scripts/gds/fitness.js'], fix: 'read the ✗ lines above; each names its fix' },
   { key: 'repo-map', label: 'nested CLAUDE.md symbol blocks fresh', argv: ['scripts/gds/gen-repo-map.js', '--check-block'], fix: 'node scripts/gds/gen-repo-map.js' },
@@ -32,6 +36,7 @@ const STEPS = [
   { key: 'copy-registry', label: 'docs/copy-registry.json fresh', argv: ['scripts/gds/copy-inventory.js', '--check'], fix: 'node scripts/gds/copy-inventory.js', optional: true },
   { key: 'linkify', label: 'no bare #NNN task refs in committed markdown', argv: ['scripts/gds/linkify-refs.js', '--check'], fix: 'node scripts/gds/linkify-refs.js', optional: true },
   { key: 'skill-lint', label: 'SKILL.md frontmatter parses', argv: ['scripts/gds/skill-lint.js'], fix: 'fix the ✗ lines (description: >- block scalars)' },
+  { key: 'render-fit', label: 'rendered text fit + sibling overlap on the pages this branch changed (advisory)', argv: ['scripts/gds/render-check.js'], fix: 'look at the shots it names; fix the element, or say in the ship notes why it is right', advisory: true, optional: true, skipWith: '--no-render', slow: true },
   { key: 'tests', label: 'DB-free unit lane (npm test)', argv: ['scripts/gds/run-unit-tests.js'], fix: 'read the FAIL lines; compare against origin/main before calling any of them environmental', onlyWith: '--tests', slow: true },
 ];
 
@@ -42,18 +47,18 @@ function runStep(step, { cwd = REPO_ROOT } = {}) {
   const r = spawnSync(process.execPath, [script, ...step.argv.slice(1)], { cwd, encoding: 'utf8', timeout: step.slow ? 15 * 60 * 1000 : 5 * 60 * 1000, env: { ...process.env, GDS_QUIET: '1' } });
   const out = ((r.stdout || '') + (r.stderr || '')).trim().split(/\r?\n/);
   const failing = out.filter((l) => /^\s*(✗|FAIL|not ok|STALE|✘)/.test(l) || /STALE|is stale|would update|failed/i.test(l));
-  return { ...step, status: r.status === 0 ? 'ok' : 'fail', code: r.status, signal: r.signal, ms: Date.now() - t0, tail: (failing.length ? failing : out.slice(-4)).slice(0, 12).join('\n') };
+  return { ...step, status: r.status === 0 ? 'ok' : !step.advisory ? 'fail' : r.status === 3 ? 'skipped' : 'warn', code: r.status, signal: r.signal, ms: Date.now() - t0, tail: (failing.length ? failing : out.slice(-4)).slice(0, 12).join('\n') };
 }
 
 function summarize(results) {
   const stale = results.filter((r) => r.status === 'fail' || r.status === 'missing');
-  return { ok: stale.length === 0, stale: stale.map((r) => r.key), results };
+  return { ok: stale.length === 0, stale: stale.map((r) => r.key), warned: results.filter((r) => r.status === 'warn').map((r) => r.key), results };
 }
 
 function format(summary) {
   const lines = ['ship-check — what ship.js will trip on', ''];
   for (const r of summary.results) {
-    const mark = r.status === 'ok' ? '✓' : r.status === 'skipped' ? '·' : '✗';
+    const mark = r.status === 'ok' ? '✓' : r.status === 'skipped' ? '·' : r.status === 'warn' ? '!' : '✗';
     lines.push(`${mark} ${r.label}  (${r.ms} ms)`);
     if (r.status !== 'ok' && r.status !== 'skipped') {
       for (const t of String(r.tail).split('\n')) lines.push(`    ${t}`);
@@ -62,12 +67,13 @@ function format(summary) {
   }
   lines.push('');
   lines.push(summary.ok ? 'all fresh — ship.js preflight should pass; the grader and CI are the remaining gates.' : `${summary.stale.length} stale: ${summary.stale.join(', ')} — heal, commit, re-run.`);
+  if (summary.warned.length) lines.push(`advisory (a signal, never a gate): ${summary.warned.join(', ')}`);
   return lines.join('\n');
 }
 
 function main() {
   const argv = process.argv.slice(2);
-  const steps = STEPS.filter((s) => !s.onlyWith || argv.includes(s.onlyWith));
+  const steps = STEPS.filter((s) => (!s.onlyWith || argv.includes(s.onlyWith)) && !(s.skipWith && argv.includes(s.skipWith)));
   const results = steps.map((s) => runStep(s));
   const summary = summarize(results);
   console.log(argv.includes('--json') ? JSON.stringify(summary, null, 1) : format(summary));

package/scripts/gds/visual-review-nudge.js

@@ -31,6 +31,7 @@ function visualReviewNudge(task) {
     '🎨 This task changes a page people see.',
     '  Build it with /design, and check it in a real browser at desktop and phone width, light and dark.',
     '  Before you ship: open the before/after for your human (node scripts/gds/review-sheet.js) and wait for their OK.',
+    '  /ship-check renders the pages you changed and names any text past its box or overlapping siblings (a signal, not a gate).',
   ];
 }
 

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.993'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.995'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/render_check.mjs

@@ -0,0 +1,127 @@
+// tests/render_check.mjs — the rendered fit check (task 1004203, ADR 0329): which pages a changed path
+// reaches, which report rows it keeps, and that /ship-check shows it as a signal that never flips its exit
+// (ADR 0162). DB-free and browser-free; the in-page measurement is pinned in tests/ui_design_kit_fit.mjs.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { FIT_FLOORS, SIZES, statesFilesFor, fitFindings, shotsDir, startHarness } from '../scripts/gds/render-check.js';
+import { STEPS, runStep, summarize, format } from '../scripts/gds/ship-check.js';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const names = (paths) => statesFilesFor(paths, ROOT).map((f) => path.basename(f));
+
+test('a changed page or its own script reaches the states file beside it', () => {
+  assert.deepEqual(names(['modules/hall-ui/public/goal-map.js']), ['goal-map.states.json']);
+  assert.deepEqual(names(['modules/hall-ui/public/goal-map.html']), ['goal-map.states.json']);
+  assert.deepEqual(names(['modules/public-landing/public/projects.html']), ['projects.states.json']);
+});
+
+test('a shared asset reaches every page in its dir whose HTML names it', () => {
+  assert.deepEqual(names(['modules/hall-ui/public/text-fit.js']), ['goal-map.states.json', 'goals.states.json']);
+  assert.deepEqual(names(['modules/public-landing/public/assets/cosmos.css']), ['projects.states.json']);
+});
+
+test('the page a builder changed comes before the pages a shared file reaches, so the render cap never drops it', () => {
+  assert.deepEqual(names(['modules/hall-ui/public/text-fit.js', 'modules/hall-ui/public/work.js']), ['work.states.json', 'goal-map.states.json', 'goals.states.json']);
+  assert.deepEqual(names(['modules/hall-ui/public/text-fit.js', 'modules/hall-ui/public/goal-map.js']), ['goal-map.states.json', 'goals.states.json'], 'a page reached both ways is listed once, as its own');
+});
+
+test('a path that is not a rendered surface, or a page with no states file, reaches nothing', () => {
+  assert.deepEqual(names(['src/bongos/db.js', 'modules/hall-ui/public/goal-map.states.json', 'modules/hall-ui/routes/x.js']), []);
+  assert.deepEqual(names(['modules/hall-ui/public/deploy.html']), [], 'a page without a states file does not fall back to the pages that link to it');
+});
+
+test('fitFindings names every element from the structured facts, once per element across renders, with its largest measure', () => {
+  const title = (n, px) => `g.gm-nodes > g.gm-node:nth-of-type(${n}) > text.gm-name "Title ${n}…" ${px}px past its card`;
+  const report = {
+    page: '/builders/goal-map',
+    renders: {
+      // seven titles: more than auditFloors' five-item problem line names
+      'dark-1280-map': { facts: { textFit: [1, 2, 3, 4, 5, 6, 7].map((n) => title(n, 10)), overlaps: [] }, problems: ['controls-24px: a.x "Docs" 40x17'] },
+      'dark-390-map': { facts: { textFit: [title(1, 14)], overlaps: ['#mVisibility > div:nth-of-type(1) ∩ #mVisibility > div:nth-of-type(2) 640x48'] } },
+      'dark-390-out': { facts: {} },
+    },
+  };
+  const found = fitFindings(report);
+  assert.equal(found.filter((f) => f.problem.startsWith('text-fit: ')).length, 7, 'every element is named, not the first five');
+  assert.deepEqual(found[0], {
+    page: '/builders/goal-map',
+    problem: 'text-fit: g.gm-nodes > g.gm-node:nth-of-type(1) > text.gm-name "Title 1…" — 14px past its card',
+    renders: ['dark-1280-map', 'dark-390-map'],
+  }, 'one finding across widths, carrying the largest overflow');
+  assert.deepEqual(found.at(-1), {
+    page: '/builders/goal-map',
+    problem: 'sibling-overlap: #mVisibility > div:nth-of-type(1) ∩ #mVisibility > div:nth-of-type(2) — 640x48',
+    renders: ['dark-390-map'],
+  });
+  assert.deepEqual(fitFindings({ page: '/x', renders: {} }), []);
+  assert.deepEqual(fitFindings(null), []);
+  assert.deepEqual([...FIT_FLOORS], ['text-fit', 'sibling-overlap']);
+  assert.deepEqual([...SIZES], [1280, 390]);
+});
+
+test('two pages of one name never share a shots folder', () => {
+  const out = path.join(os.tmpdir(), 'rc');
+  const hall = shotsDir(out, path.join(ROOT, 'modules', 'hall-ui', 'public', 'index.states.json'));
+  const landing = shotsDir(out, path.join(ROOT, 'modules', 'public-landing', 'public', 'index.states.json'));
+  assert.notEqual(hall, landing);
+  assert.equal(path.basename(hall), 'modules_hall-ui_public_index');
+});
+
+const alive = (pid) => { try { process.kill(pid, 0); return true; } catch { return false; } };
+const waitDead = async (pid) => { for (let i = 0; i < 50 && alive(pid); i++) await new Promise((r) => setTimeout(r, 100)); return !alive(pid); };
+
+test('a harness that never says it is up is killed on the boot timeout, not left holding its port', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rc-harness-'));
+  const pidFile = path.join(dir, 'pid');
+  const script = path.join(dir, 'silent.js');
+  fs.writeFileSync(script, `require('fs').writeFileSync(${JSON.stringify(pidFile)}, String(process.pid)); setInterval(() => {}, 1000);`);
+  await assert.rejects(startHarness({ script, bootMs: 1500 }), /did not start within 1\.5s/);
+  assert.ok(await waitDead(Number(fs.readFileSync(pidFile, 'utf8'))), 'the silent harness was killed');
+});
+
+test('a harness that comes up is handed back with a stop that ends it', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rc-harness-'));
+  const script = path.join(dir, 'up.js');
+  fs.writeFileSync(script, `console.log('hall-preview: http://localhost:' + process.argv[3] + '/'); setInterval(() => {}, 1000);`);
+  const harness = await startHarness({ script, bootMs: 5000 });
+  assert.match(harness.base, /^http:\/\/localhost:\d+$/);
+  assert.ok(alive(harness.pid));
+  harness.stop();
+  assert.ok(await waitDead(harness.pid), 'stop() ended the harness');
+});
+
+test('the CLI renders nothing, and says why, when no page a states file describes changed', () => {
+  const cli = (files) => spawnSync(process.execPath, [path.join(ROOT, 'scripts', 'gds', 'render-check.js'), '--files', files], { cwd: ROOT, encoding: 'utf8' });
+  const none = cli('src/bongos/db.js');
+  assert.equal(none.status, 0);
+  assert.match(none.stdout, /no rendered surface changed/);
+  const noStates = cli('modules/hall-ui/public/deploy.html');
+  assert.equal(noStates.status, 0);
+  assert.match(noStates.stdout, /1 rendered-surface file\(s\) changed, but no <page>\.states\.json reaches them/);
+});
+
+test('ship-check runs the render check as an advisory row: findings warn, no browser skips, neither flips the exit', () => {
+  const step = STEPS.find((s) => s.key === 'render-fit');
+  assert.ok(step && step.advisory && step.argv[0] === 'scripts/gds/render-check.js');
+  assert.ok(step.optional, 'an absent script is skipped, never counted as stale');
+  assert.equal(step.skipWith, '--no-render');
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ship-check-advisory-'));
+  const script = (name, code) => { fs.writeFileSync(path.join(dir, name), `console.log('✗ a finding'); process.exit(${code});`); return name; };
+  const warn = runStep({ key: 'r', label: 'r', argv: [script('found.js', 1)], fix: 'f', advisory: true }, { cwd: dir });
+  const skip = runStep({ key: 's', label: 's', argv: [script('nobrowser.js', 3)], fix: 'f', advisory: true }, { cwd: dir });
+  const gate = runStep({ key: 'g', label: 'g', argv: [script('stale.js', 1)], fix: 'f' }, { cwd: dir });
+  assert.equal(warn.status, 'warn');
+  assert.match(warn.tail, /✗ a finding/);
+  assert.equal(skip.status, 'skipped');
+  assert.equal(gate.status, 'fail', 'a non-advisory step still fails');
+  const advisoryOnly = summarize([warn, skip]);
+  assert.equal(advisoryOnly.ok, true);
+  assert.deepEqual(advisoryOnly.warned, ['r']);
+  assert.match(format(advisoryOnly), /! r[\s\S]*advisory \(a signal, never a gate\): r/);
+  assert.equal(summarize([warn, gate]).ok, false);
+});

package/tests/ui_design_kit.mjs

@@ -27,9 +27,10 @@ const readJson = (rel) => JSON.parse(fs.readFileSync(path.join(ROOT, rel), 'utf8
 
 // ── the contract ──────────────────────────────────────────────────────────────
 test('the platform floors are a pinned list — a floor cannot vanish quietly', () => {
-  assert.deepEqual([...lib.FLOORS], ['console-errors', 'failed-requests', 'horizontal-overflow', 'one-header-main-h1', 'controls-24px', 'top-bar-80px', 'reduced-motion']);
+  assert.deepEqual([...lib.FLOORS], ['console-errors', 'failed-requests', 'horizontal-overflow', 'text-fit', 'sibling-overlap', 'one-header-main-h1', 'controls-24px', 'top-bar-80px', 'reduced-motion']);
   assert.deepEqual(lib.EXIT, { CLEAN: 0, PROBLEMS: 1, USAGE: 2, NO_BROWSER: 3 });
-  assert.deepEqual(Object.keys(lib.SIZES), ['320', '390', '1440']);
+  assert.deepEqual(Object.keys(lib.SIZES), ['320', '390', '1280', '1440']);
+  assert.deepEqual([...lib.DEFAULT_SIZES], [1440, 390, 320], 'render.js renders these unless --sizes names 1280');
 });
 
 test('the shipped states files validate and sit beside the page they name', () => {
@@ -95,6 +96,10 @@ test('auditFloors names each floor a render breaks, and says nothing about a cle
   assert.ok(p.some((x) => x.startsWith('top-bar-80px') && /96px/.test(x)));
   assert.ok(p.some((x) => /data-mode "light" under a dark scheme/.test(x)));
   assert.deepEqual(lib.auditFloors({ ...clean(), mode: null }, { mode: 'dark' }), [], 'a page that sets no data-mode is not held to one');
+  assert.deepEqual(lib.auditFloors({ ...clean(), textFit: [], overlaps: [] }, { width: 1440, mode: 'dark' }), []);
+  const fit = lib.auditFloors({ ...clean(), textFit: ['#t1 "Governance" 15px past its card', 'b', 'c', 'd', 'e', 'f', 'g'], overlaps: ['#mSec > div ∩ #mSec > div 640x48'] }, { width: 1280 });
+  assert.ok(fit.includes('text-fit: #t1 "Governance" 15px past its card | b | c | d | e (+2 more)'), fit.join(' / '));
+  assert.ok(fit.includes('sibling-overlap: #mSec > div ∩ #mSec > div 640x48'));
 });
 
 test('expectProblems compares every expectation the vocabulary allows', () => {

package/tests/ui_design_kit_fit.mjs

@@ -0,0 +1,75 @@
+// tests/ui_design_kit_fit.mjs — the kit's two fit floors measured in a real page (task 1004203, ADR 0329):
+// text past its box (HTML, and SVG text past its card) and overlapping text-bearing siblings, with the shapes
+// that clip or layer ON PURPOSE staying silent. Needs the system Edge or Chrome the kit drives; with neither,
+// the test skips — tests/ui_design_kit.mjs pins the pure audit without one.
+import assert from 'node:assert/strict';
+import { test, after } from 'node:test';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const lib = require(path.join(ROOT, 'modules', 'ui-design', 'kit', 'lib.js'));
+
+let browser = null;
+try { browser = await lib.launchBrowser(); } catch (e) { if (!(e instanceof lib.NoBrowserError)) throw e; }
+after(() => browser && browser.close());
+
+// Each shape the done-when names, beside the look-alikes that must NOT report: the .mSec one-cell grid with a
+// second child (task 1003078), a card title past its rect (task 1003480), ellipsis, a scroller, an absolute
+// overlay, a visually-hidden label, wrapped prose whose soft-wrap space hangs past the line, two wrapped
+// inline siblings (their boxes span lines), and a sticky head over rows scrolled under it.
+const PAGE = `<!doctype html><html><head><style>
+  body { margin: 0; font: 16px/1.4 monospace; }
+  .box { width: 120px; }
+  .nowrap { white-space: nowrap; }
+  .cell { display: grid; grid-template-columns: 100px 1fr; width: 400px; }
+  .cell > div { grid-column: 2; grid-row: 1; }
+  .vh { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; }
+</style></head><body><header></header><main><h1>fit</h1>
+  <p id="prose" class="box">a paragraph of ordinary words that wraps across several lines inside its box</p>
+  <div id="spills" class="box nowrap">averyveryverylongunbreakabletitle</div>
+  <div id="ellipsis" class="box nowrap" style="overflow: hidden; text-overflow: ellipsis">averyveryverylongunbreakabletitle</div>
+  <div id="scroller" class="box nowrap" style="overflow-x: auto">averyveryverylongunbreakabletitle</div>
+  <span class="vh">a visually hidden label far wider than one pixel</span>
+  <section id="mSec" class="cell"><h2>Head</h2><div>the first child's text</div><div>a second child's text</div></section>
+  <section id="alone" class="cell"><h2>Head</h2><div>the only child</div></section>
+  <p id="inline" class="box"><code>the first inline code run</code> then <code>a second inline code run</code></p>
+  <div id="rows" style="height: 60px; overflow: auto"><div style="position: sticky; top: 0">a sticky head</div><div>row one</div><div>row two</div><div>row three</div><div>row four</div></div>
+  <div id="layer" style="position: relative"><div>the base text</div><div style="position: absolute; top: 0">an overlay</div></div>
+  <svg width="400" height="100">
+    <g id="fits"><rect width="200" height="40"/><text x="10" y="25">fits</text></g>
+    <g id="over" transform="translate(0 50)"><rect width="60" height="40"/><text x="10" y="25">WWWWWWWWWWWW</text></g>
+  </svg>
+</main></body></html>`;
+
+test('the fit floors report the overflow and the overlap by element, and nothing that clips or layers on purpose', { skip: !browser && 'no system Edge or Chrome' }, async () => {
+  const ctx = await browser.newContext({ viewport: { width: 1280, height: 800 } });
+  const page = await ctx.newPage();
+  await page.setContent(PAGE);
+  await page.evaluate(() => { document.getElementById('rows').scrollTop = 30; });
+  const facts = await page.evaluate(lib.factsInPage, {});
+  await ctx.close();
+
+  assert.equal(facts.textFit.length, 2, facts.textFit.join('\n'));
+  assert.match(facts.textFit.find((f) => f.startsWith('#spills')) || '', /^#spills "averyvery.*" \d+px past its box$/);
+  assert.match(facts.textFit.find((f) => f.startsWith('#over')) || '', /^#over > text "WWWW.*" \d+px past its card$/);
+  assert.deepEqual(facts.overlaps.map((o) => o.replace(/ \d+x\d+$/, '')), ['#mSec > div:nth-of-type(1) ∩ #mSec > div:nth-of-type(2)']);
+
+  const problems = lib.auditFloors(facts, { width: 1280 });
+  assert.ok(problems.some((p) => p.startsWith('text-fit: ') && p.includes('#spills') && p.includes('#over > text')));
+  assert.ok(problems.some((p) => p.startsWith('sibling-overlap: #mSec > div:nth-of-type(1) ∩ #mSec > div:nth-of-type(2)')));
+});
+
+test('an overlap among <body>\'s own children is caught too — the one-cell grid one level up', { skip: !browser && 'no system Edge or Chrome' }, async () => {
+  const ctx = await browser.newContext({ viewport: { width: 1280, height: 800 } });
+  const page = await ctx.newPage();
+  await page.setContent(`<!doctype html><html><head><style>
+    body { margin: 0; display: grid; grid-template-columns: 1fr; }
+    body > div { grid-column: 1; grid-row: 1; }
+  </style></head><body><div id="first">the first child's text</div><div id="second">a second child's text</div></body></html>`);
+  const facts = await page.evaluate(lib.factsInPage, {});
+  await ctx.close();
+  assert.deepEqual(facts.overlaps.map((o) => o.replace(/ \d+x\d+$/, '')), ['#first ∩ #second']);
+});