@bongos/core 1.21.175 → 1.21.177

package/scripts/bongos/page-reader.js

@@ -0,0 +1,722 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/bongos/page-reader.js — the PAGE READER: every string a rendered page
+// shows, in page order, grouped by section, each placed against the copy
+// registry (BV2.TW04, task 1004315; ADR 0341 D3; goal 1000095, the Tweak Mode
+// chain — docs/specs/bongos-v2-tweak-mode.md).
+//
+// WHY. The copy registry (docs/copy-registry.json) is keyed by FILE: it lists
+// comment text nobody sees, and misses anything a script builds at run time or a
+// server sends. Tweak Mode's unit is the PAGE (ADR 0341 D1), so an artist needs
+// the other view — "what does this page actually show". This reader renders each
+// page of docs/page-inventory.json in each of its states, lists every visible
+// string, and says for each line where it lives: PLACED (a registry row: file,
+// line, string_id), SHARED (shell text — the top bar, sidebar and footer every
+// page of a surface carries, the planning session's "same UI element") or
+// UNPLACED (a string the registry cannot place; ADR 0341 D4 turns a rewrite of
+// one into its own engineer task). An unplaced string is LISTED, never dropped.
+//
+// THE OUTPUT CONTRACT (ADR 0341 D3). docs/page-readings.json, generated and
+// committed: one entry per inventory page, its lines in page order. Each line has
+//   key        L0001, L0002, … in page order — stable only within one reading;
+//   section    the heading the line sits under (or the shell region for shared);
+//   text       the string, with {…} holes where the registry row has a hole or a
+//              run-time value (data from the page's own reads) was filled in;
+//   placement  placed | shared | unplaced, with file, line and string_id
+//              whenever the registry places the string (shared lines too, so a
+//              shared edit can travel in a batch like a placed one, D4).
+// Each page carries reading_hash (over its NON-shared lines' key, section and
+// text — so a shell change does not move every page's hash) and files_hash (over
+// the contents of its inventory `files`, line endings normalised).
+//
+// FRESHNESS WITHOUT A BROWSER. --check compares files_hash only — pure fs, no
+// browser, no network — and names the command that re-reads the stale pages.
+// ship-check runs it; nothing inside ship-check or fitness launches a browser
+// (D3). The browser runs only when a person or session runs this reader.
+//
+// HOW IT RENDERS. The hall through the hall-preview harness
+// (scripts/hall-preview/server.js --fixture-me: the real pages, the checked-in
+// fixtures, one pinned account), landing and status through the ui-design kit's
+// stub (modules/ui-design/kit/serve.js: the real serving transforms, the kit's
+// public feeds), the browser through the kit's launchBrowser (system Edge or
+// Chrome via playwright-core; nothing is downloaded). Each state is rendered at
+// 1280x800, light (or the page's one pinned mode), with the clock pinned so a
+// relative date reads the same on every run, then its states-file actions run.
+// Four renders run at once. Measured on the owner's Windows box (2026-09-27): the
+// whole inventory, 37 pages and 156 renders, in 128 seconds; one page in 5-40
+// seconds (--page). Two back-to-back full runs wrote byte-identical files.
+//
+// Run:  node scripts/bongos/page-reader.js                 (re-read every page, write the readings)
+//       node scripts/bongos/page-reader.js --stale         (re-read only the pages --check calls stale)
+//       node scripts/bongos/page-reader.js --page builders:studio,landing:index
+//       node scripts/bongos/page-reader.js --check         (no browser: exit 1 naming each stale page)
+//       node scripts/bongos/page-reader.js --page <id> --print   (read one page, print it, write nothing)
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { spawn, spawnSync } = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const INVENTORY_REL = 'docs/page-inventory.json';
+const REGISTRY_REL = 'docs/copy-registry.json';
+const READINGS_REL = 'docs/page-readings.json';
+const REREAD_COMMAND = 'node scripts/bongos/page-reader.js --stale';
+const PLACEMENTS = Object.freeze(['placed', 'shared', 'unplaced']);
+const HOLE = '{…}';
+const VIEWPORT = Object.freeze({ width: 1280, height: 800 });
+// A fixed instant for every render, so "3 days ago" is the same on every run. Only
+// Date is pinned; timers keep running, so the pages still boot.
+const PINNED_CLOCK = '2026-09-27T12:00:00Z';
+const CONCURRENCY = 4;
+const EXTRA_SETTLE_MS = 600; // on top of the kit's SETTLE_MS: late fetches, the harness's SSE nudge
+const ACTION_TIMEOUT_MS = 6000;
+const RENDER_CEILING_MS = 30000;
+
+// Locale-independent order (see copy-inventory.js: localeCompare depends on ICU).
+function cmp(a, b) {
+  if (a === b) return 0;
+  return a < b ? -1 : 1;
+}
+
+function sha(s) { return crypto.createHash('sha256').update(s).digest('hex'); }
+
+// ── the hashes ────────────────────────────────────────────────────────────────
+
+// files_hash — over the contents of a page's inventory files, CRLF folded to LF
+// (a Windows checkout and CI must agree). A missing file hashes as absent, so
+// deleting one moves the hash too.
+function filesHash(files, { root = REPO_ROOT, fsImpl = fs } = {}) {
+  const h = crypto.createHash('sha256');
+  for (const f of files) {
+    let body;
+    try { body = fsImpl.readFileSync(path.join(root, f), 'utf8').replace(/\r\n/g, '\n'); } catch { body = '\u0000absent'; }
+    h.update(`${f}\n${body.length}\n${body}\n`);
+  }
+  return h.digest('hex').slice(0, 16);
+}
+
+// reading_hash — over the non-shared lines only (ADR 0341 D3). The keys are in it,
+// so a shell line added above the page's own text (which renumbers them) still
+// moves the hash, and a draft keyed on the old numbering is refused, not misread.
+function readingHash(lines) {
+  const own = lines.filter((l) => l.placement !== 'shared').map((l) => [l.key, l.section, l.text]);
+  return sha(JSON.stringify(own)).slice(0, 16);
+}
+
+// ── the registry matcher (pure) ──────────────────────────────────────────────
+
+function decodeEntities(s) {
+  return String(s)
+    .replace(/&nbsp;/g, ' ').replace(/&mdash;/g, '—').replace(/&ndash;/g, '–').replace(/&hellip;/g, '…')
+    .replace(/&rsquo;/g, '’').replace(/&lsquo;/g, '‘').replace(/&rdquo;/g, '”').replace(/&ldquo;/g, '“')
+    .replace(/&middot;/g, '·').replace(/&times;/g, '×').replace(/&rarr;/g, '→').replace(/&larr;/g, '←')
+    .replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+    .replace(/&#(\d+);/g, (m, n) => String.fromCodePoint(Number(n)))
+    .replace(/&amp;/g, '&');
+}
+function norm(s) { return String(s == null ? '' : s).replace(/\s+/g, ' ').trim(); }
+const HAS_LETTER = /\p{L}/u;
+// The registry's holes: ${…} (a template expression), {…} (the same, written
+// plain) and {{token}} (a branding placeholder the server fills).
+const REGISTRY_HOLE = /\$\{…\}|\{\{[A-Za-z0-9_.]+\}\}|\{…\}/g;
+function escapeRe(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+// The reading's own text for a registry row: ${…} written as the registry's plain
+// {…}; a {{token}} is kept by name (it is a brand value, and says which).
+function registryText(text) { return norm(decodeEntities(text)).replace(/\$\{…\}/g, HOLE); }
+
+// buildMatcher — index the registry once: exact texts, holed patterns, and the
+// literal segments between holes (a hole filled with markup splits one row into
+// several text nodes, each a segment of it).
+function buildMatcher(registry) {
+  const entries = (registry && registry.entries) || [];
+  const exact = new Map();
+  const segments = new Map();
+  const patterns = [];
+  const push = (map, k, v) => { if (!map.has(k)) map.set(k, []); map.get(k).push(v); };
+  entries.forEach((e, order) => {
+    const text = norm(decodeEntities(e.text));
+    if (!text || !HAS_LETTER.test(text)) return;
+    const row = { id: e.id, file: e.file, line: e.line, text: registryText(e.text), order };
+    const parts = text.split(REGISTRY_HOLE);
+    if (parts.length === 1) { push(exact, text, row); return; }
+    const literal = parts.join('');
+    if ((literal.match(/\p{L}/gu) || []).length < 2) return; // a row that is all holes places nothing
+    patterns.push({ row, re: new RegExp(`^${parts.map((p) => escapeRe(p)).join('(.*?)')}$`, 'su') });
+    for (const p of parts) { const seg = norm(p); if (seg.length >= 2 && HAS_LETTER.test(seg)) push(segments, seg, row); }
+  });
+  return { exact, segments, patterns, size: entries.length };
+}
+
+// placeText — the registry row that renders this string on this page, or null.
+// Tiers in order: the exact text, a holed row whose pattern matches it whole, a
+// literal segment of a holed row. Within a tier, a row in one of the page's own
+// files wins (in the page's file order: its html first), then the lowest line; a
+// row in a script or sheet elsewhere on the same surface is the fallback (one the
+// page loads late, which the inventory's script tags cannot see). Anything else is
+// unplaced — the caller lists it, it is never dropped.
+function placeText(text, matcher, { files = [], surfaceDir = null } = {}) {
+  const t = norm(text);
+  if (!t) return null;
+  const rank = new Map(files.map((f, i) => [f, i]));
+  const pick = (rows) => {
+    if (!rows || !rows.length) return null;
+    const own = rows.filter((r) => rank.has(r.file)).sort((a, b) => rank.get(a.file) - rank.get(b.file) || a.line - b.line || a.order - b.order);
+    if (own.length) return own[0];
+    // Never another page's html: a page file renders only itself, so a row there
+    // is the same words on a different page, and an applier would edit the wrong one.
+    const near = surfaceDir ? rows.filter((r) => r.file.startsWith(`${surfaceDir}/`) && !/\.html?$/i.test(r.file)).sort((a, b) => cmp(a.file, b.file) || a.line - b.line) : [];
+    return near[0] || null;
+  };
+  const tiers = [
+    () => ({ row: pick(matcher.exact.get(t)), how: 'exact' }),
+    () => ({ row: pick(matcher.patterns.filter((p) => p.re.test(t)).map((p) => p.row)), how: 'pattern' }),
+    () => ({ row: pick(matcher.segments.get(t)), how: 'segment' }),
+  ];
+  for (const tier of tiers) {
+    const { row, how } = tier();
+    if (row) return { file: row.file, line: row.line, string_id: row.id, text: how === 'pattern' ? row.text : t, how };
+  }
+  return null;
+}
+
+// ── data values: what the page READ, not what it SAYS ─────────────────────────
+
+// A page shows its data too — task titles, names, counts from its own API reads.
+// Those are not copy: an artist cannot rewrite a fixture's task title. A string
+// the registry cannot place is compared against the values the page actually
+// received: every such value in it becomes a {…} hole, and a string that is
+// nothing BUT data once holed (no letter left) is data, counted and not listed.
+// The registry is always asked first, so a placed string is never taken for data.
+function collectStrings(value, out = new Set()) {
+  if (typeof value === 'string') { const s = norm(value); if (s.length >= 2 && s.length <= 400 && HAS_LETTER.test(s)) out.add(s); }
+  else if (Array.isArray(value)) for (const v of value) collectStrings(v, out);
+  else if (value && typeof value === 'object') for (const v of Object.values(value)) collectStrings(v, out);
+  return out;
+}
+const TIME_RE = /\b\d{1,2}:\d{2}(?::\d{2})?(?:\s?[AaPp]\.?[Mm]\.?)?(?![\p{L}\p{N}])/gu;
+const DATE_RE = /\b(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Sept|Oct|Nov|Dec)[a-z]*\.? \d{1,2}(?:, \d{4})?\b|\b\d{4}-\d{2}-\d{2}(?:[T ][\d:.]+Z?)?\b/g;
+function holeData(text, dataValues) {
+  const t = norm(text);
+  if (dataValues.has(t)) return { text: HOLE, data: true };
+  let out = t;
+  const vals = [...dataValues].filter((v) => v.length >= 4 && out.includes(v)).sort((a, b) => b.length - a.length || cmp(a, b));
+  for (const v of vals) {
+    const re = new RegExp(`(^|[^\\p{L}\\p{N}])${escapeRe(v)}(?=$|[^\\p{L}\\p{N}])`, 'gu');
+    out = out.replace(re, (m, pre) => `${pre}${HOLE}`);
+  }
+  // Clock times and calendar dates are run-time values too, and a stub may stamp
+  // its fixtures relative to its own clock, which the page's pinned Date cannot
+  // reach — holed, so a re-read of an unchanged page reads the same.
+  out = out.replace(TIME_RE, HOLE).replace(DATE_RE, HOLE);
+  const residue = out.split(HOLE).join('');
+  return { text: out, data: !HAS_LETTER.test(residue) };
+}
+
+// ── assembling one page's reading (pure) ─────────────────────────────────────
+
+// mergeStates — the default state's strings in page order, then each other
+// state's strings not already there, inserted after the last string the two
+// share, so a panel a state opens reads where it sits on the page.
+function mergeStates(captures) {
+  const merged = [];
+  const id = (s) => `${s.shared || ''}\u0000${s.section}\u0000${s.text}`;
+  captures.forEach(({ state, strings }, si) => {
+    let at = 0;
+    const seen = new Map();
+    for (const s of strings) {
+      const k = id(s);
+      const n = (seen.get(k) || 0) + 1;
+      seen.set(k, n);
+      // the nth occurrence of this identity in the merged list, at or after `at`
+      let hit = -1, count = 0;
+      for (let i = 0; i < merged.length; i += 1) {
+        if (id(merged[i]) !== k) continue;
+        count += 1;
+        if (count === n) { hit = i; break; }
+      }
+      if (hit >= 0) { at = Math.max(at, hit + 1); continue; }
+      merged.splice(at, 0, { ...s, state: si === 0 ? null : state });
+      at += 1;
+    }
+  });
+  return merged;
+}
+
+// assembleReading — one page's strings (per state, as captured) into its reading.
+function assembleReading(page, captures, matcher, { dataValues = new Set(), surfaceDir = null, root = REPO_ROOT, fsImpl = fs } = {}) {
+  const files = page.files || [];
+  const placeCache = new Map();
+  const place = (t) => {
+    if (!placeCache.has(t)) placeCache.set(t, placeText(t, matcher, { files, surfaceDir }));
+    return placeCache.get(t);
+  };
+  const sectionName = (raw, shared) => {
+    if (shared) return shared;
+    const t = norm(raw);
+    if (!t) return 'page top';
+    const hit = place(t);
+    const text = hit ? hit.text : holeData(t, dataValues).text;
+    return text.length > 80 ? `${text.slice(0, 79)}…` : text;
+  };
+  const merged = mergeStates(captures.map((c) => ({ state: c.state, strings: c.strings.map((s) => ({ ...s, text: norm(s.text), section: norm(s.section) })) })));
+  const lines = [];
+  const index = new Map();
+  let omittedData = 0;
+  for (const s of merged) {
+    if (!s.text || !HAS_LETTER.test(s.text)) continue; // a number, a glyph, punctuation: nothing to reword
+    const section = sectionName(s.section, s.shared);
+    const hit = place(s.text);
+    let line;
+    if (hit) {
+      line = { section, text: hit.text, placement: s.shared ? 'shared' : 'placed', file: hit.file, line: hit.line, string_id: hit.string_id };
+    } else {
+      const held = holeData(s.text, dataValues);
+      if (held.data) { omittedData += 1; continue; }
+      line = { section, text: held.text, placement: s.shared ? 'shared' : 'unplaced' };
+    }
+    if (s.attr) line.attr = s.attr;
+    if (s.state) line.state = s.state;
+    const k = `${line.section}\u0000${line.text}\u0000${line.placement}\u0000${line.string_id || ''}\u0000${line.attr || ''}`;
+    if (index.has(k)) { const first = index.get(k); first.occurrences = (first.occurrences || 1) + 1; continue; }
+    index.set(k, line);
+    lines.push(line);
+  }
+  const keyed = lines.map((l, i) => ({ key: `L${String(i + 1).padStart(4, '0')}`, ...l }));
+  const counts = { lines: keyed.length };
+  for (const p of PLACEMENTS) counts[p] = keyed.filter((l) => l.placement === p).length;
+  return {
+    id: page.id,
+    surface: page.surface,
+    title: page.title,
+    states_read: captures.map((c) => c.state),
+    files_hash: filesHash(files, { root, fsImpl }),
+    reading_hash: readingHash(keyed),
+    counts,
+    omitted: { data: omittedData },
+    notes: [...new Set(captures.flatMap((c) => c.notes || []))],
+    lines: keyed,
+  };
+}
+
+// ── the artifact ─────────────────────────────────────────────────────────────
+
+const HOW = [
+  'Generated by node scripts/bongos/page-reader.js (BV2.TW04, task 1004315; ADR 0341 D3). Do not hand-edit.',
+  'One entry per page of docs/page-inventory.json. Lines are in page order: the default state first, and a line only another state shows sits where that state shows it, with its state named.',
+  'placement: placed = a docs/copy-registry.json row renders it (file, line, string_id); shared = shell text every page of the surface carries (top bar, sidebar, footer), with its row when the registry has one; unplaced = the registry cannot place it (a rewrite becomes an engineer task, ADR 0341 D4).',
+  'text keeps {…} where the registry row has a hole, or where a value the page read from its API was filled in. A string that is only such data is counted under omitted.data, not listed.',
+  'reading_hash is over the non-shared lines (key, section, text); files_hash is over the page\'s inventory files. --check compares files_hash only and never opens a browser.',
+  'Rendered through the hall-preview harness (hall) and the ui-design kit stub (landing, status), at 1280x800 with the clock pinned, so a reading is the fixture world\'s page.',
+];
+
+function summaryCounts(pages) {
+  const c = { pages: pages.length, lines: 0, placed: 0, shared: 0, unplaced: 0, omitted_data: 0 };
+  for (const p of pages) {
+    c.lines += p.counts.lines;
+    for (const k of PLACEMENTS) c[k] += p.counts[k];
+    c.omitted_data += p.omitted.data;
+  }
+  return c;
+}
+
+// One line per reading line, so a re-read of one page is a diff of that page's
+// block, and two branches re-reading different pages merge cleanly.
+function serialize(doc) {
+  const out = [];
+  out.push('{');
+  for (const k of ['schema', 'generator', 'task', 'adr', 'reread', 'how', 'counts']) out.push(`  ${JSON.stringify(k)}: ${JSON.stringify(doc[k])},`);
+  out.push('  "pages": [');
+  doc.pages.forEach((p, pi) => {
+    out.push('    {');
+    for (const k of ['id', 'surface', 'title', 'states_read', 'files_hash', 'reading_hash', 'counts', 'omitted', 'notes']) out.push(`      ${JSON.stringify(k)}: ${JSON.stringify(p[k])},`);
+    out.push('      "lines": [');
+    p.lines.forEach((l, li) => out.push(`        ${JSON.stringify(l)}${li < p.lines.length - 1 ? ',' : ''}`));
+    out.push('      ]');
+    out.push(`    }${pi < doc.pages.length - 1 ? ',' : ''}`);
+  });
+  out.push('  ]');
+  out.push('}');
+  return `${out.join('\n')}\n`;
+}
+
+function buildDoc(pages) {
+  return {
+    schema: 1,
+    generator: 'scripts/bongos/page-reader.js',
+    task: 1004315,
+    adr: '0341 D3',
+    reread: REREAD_COMMAND,
+    how: HOW,
+    counts: summaryCounts(pages),
+    pages,
+  };
+}
+
+function readJsonFile(rel, root = REPO_ROOT) {
+  return JSON.parse(fs.readFileSync(path.join(root, rel), 'utf8'));
+}
+
+// checkReadings — the browser-free freshness check (ADR 0341 D3): a page is stale
+// when it has no reading, or its files_hash no longer matches its files. A reading
+// for a page the inventory no longer lists is stale too (an extra).
+function checkReadings(inventory, readings, { root = REPO_ROOT, fsImpl = fs } = {}) {
+  const byId = new Map(((readings && readings.pages) || []).map((p) => [p.id, p]));
+  const stale = [];
+  for (const page of inventory.pages) {
+    const r = byId.get(page.id);
+    if (!r) { stale.push({ id: page.id, why: 'no reading' }); continue; }
+    if (r.files_hash !== filesHash(page.files, { root, fsImpl })) stale.push({ id: page.id, why: 'its files changed' });
+  }
+  const listed = new Set(inventory.pages.map((p) => p.id));
+  for (const id of byId.keys()) if (!listed.has(id)) stale.push({ id, why: 'not in the inventory' });
+  return stale;
+}
+
+// ── rendering (the browser half; never reached by --check) ───────────────────
+
+// Runs IN THE PAGE: every visible string in document order, each with the heading
+// it sits under and, when it is shell text, the shell region. Self-contained (it is
+// serialised into the page).
+function captureInPage() {
+  const clean = (s) => String(s || '').replace(/\s+/g, ' ').trim();
+  const main = document.querySelector('main');
+  const SHELL = [['#app-topbar', 'top bar'], ['#app-sidebar', 'sidebar'], ['#app-foot', 'footer'], ['a.skip', 'skip link']];
+  const sharedOf = (el) => {
+    for (const [sel, name] of SHELL) if (el.closest(sel)) return name;
+    if (main && main.contains(el)) return null;
+    const lm = el.closest('header, footer, nav, [role="banner"], [role="contentinfo"], [role="navigation"]');
+    if (!lm || (main && lm.contains(main))) return null;
+    const tag = lm.tagName.toLowerCase(), role = lm.getAttribute('role');
+    if (tag === 'footer' || role === 'contentinfo') return 'footer';
+    if (tag === 'nav' || role === 'navigation') return 'navigation';
+    return 'top bar';
+  };
+  const shown = (el) => {
+    if (!el || !el.isConnected) return false;
+    if (typeof el.checkVisibility === 'function' && !el.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true, opacityProperty: true, visibilityProperty: true })) return false;
+    const r = el.getBoundingClientRect();
+    return r.width > 1 && r.height > 1; // a 1px box is screen-reader-only text
+  };
+  const textShown = (node) => {
+    const el = node.parentElement;
+    const select = el && el.closest('select');
+    if (select) return shown(select);
+    if (!shown(el)) return false;
+    const range = document.createRange();
+    range.selectNodeContents(node);
+    return [...range.getClientRects()].some((r) => r.width > 1 && r.height > 1);
+  };
+  const out = [];
+  let section = '';
+  const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT, {
+    acceptNode(n) {
+      if (n.nodeType === 1 && /^(SCRIPT|STYLE|NOSCRIPT|TEMPLATE)$/.test(n.tagName)) return NodeFilter.FILTER_REJECT;
+      return NodeFilter.FILTER_ACCEPT;
+    },
+  });
+  for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+    if (n.nodeType === 1) {
+      if (/^H[1-3]$/.test(n.tagName) && shown(n) && !sharedOf(n)) section = clean(n.textContent);
+      if ((n.tagName === 'INPUT' || n.tagName === 'TEXTAREA') && shown(n)) {
+        const ph = clean(n.getAttribute('placeholder'));
+        if (ph) out.push({ text: ph, section, shared: sharedOf(n), attr: 'placeholder' });
+        if (n.tagName === 'INPUT' && /^(submit|button|reset)$/i.test(n.type) && clean(n.value)) out.push({ text: clean(n.value), section, shared: sharedOf(n), attr: 'value' });
+      }
+      continue;
+    }
+    const t = clean(n.nodeValue);
+    if (!t || !textShown(n)) continue;
+    out.push({ text: t, section, shared: sharedOf(n.parentElement) });
+  }
+  let branding = null;
+  try { branding = window.__BRANDING__ || null; } catch { branding = null; }
+  return { strings: out, branding };
+}
+
+// Every render the reader makes for one page: the states of its states files, in
+// file order, or one "default" render at its own path when it has none.
+function planRenders(page, { root = REPO_ROOT } = {}) {
+  if (!page.states_files || !page.states_files.length) {
+    return [{ page: page.id, state: 'default', url: page.path, auth: page.surface !== 'landing', actions: [], stub: {}, mode: 'light', modeQuery: false }];
+  }
+  const plans = [];
+  const seen = new Set();
+  for (const rel of page.states_files) {
+    const json = JSON.parse(fs.readFileSync(path.join(root, rel), 'utf8'));
+    const mode = (json.modes && json.modes.includes('light')) || !json.modes ? 'light' : json.modes[0];
+    for (const [name, st] of Object.entries(json.states || {})) {
+      const state = seen.has(name) ? `${path.basename(rel, '.states.json')}:${name}` : name;
+      seen.add(name);
+      plans.push({
+        page: page.id, state, url: st.url || json.page, auth: !!st.auth, actions: st.actions || [],
+        stub: json.stub || {}, mode, modeQuery: json.modeQuery, ignore: json.ignoreRequests || [],
+      });
+    }
+  }
+  return plans;
+}
+
+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-preview harness, with the pinned fixture account (--fixture-me), so
+// two runs on two machines read the same hall.
+async function startHarness(kit) {
+  const port = await kit.freePort();
+  const proc = spawn(process.execPath, [path.join(REPO_ROOT, 'scripts', 'hall-preview', 'server.js'), '--port', String(port), '--fixture-me'], { cwd: REPO_ROOT, stdio: ['ignore', 'pipe', 'pipe'], detached: DETACH });
+  await new Promise((resolve, reject) => {
+    let said = '', ready = false;
+    const timer = setTimeout(() => { killTree(proc); reject(new Error(`the hall-preview harness did not start within 30s: ${said.trim()}`)); }, 30000);
+    const hear = (d) => { if (ready) return; said += d; if (/hall-preview: http/.test(said)) { ready = true; clearTimeout(timer); resolve(); } };
+    proc.stdout.on('data', hear); // read for the whole run: an unread pipe fills and stalls the harness
+    proc.stderr.on('data', hear);
+    proc.on('exit', (code) => { if (!ready) { clearTimeout(timer); reject(new Error(`the hall-preview harness exited ${code}: ${said.trim()}`)); } });
+  });
+  return { base: `http://localhost:${port}`, stop: () => killTree(proc) };
+}
+
+const SURFACE_MODULE = { landing: 'public-landing', status: 'status-ui' };
+
+async function renderOne(browser, kit, plan, base) {
+  const ctx = await browser.newContext({ viewport: VIEWPORT, deviceScaleFactor: 1, colorScheme: plan.mode });
+  const notes = [];
+  const data = new Set();
+  const pending = [];
+  try {
+    if (ctx.clock && typeof ctx.clock.setFixedTime === 'function') await ctx.clock.setFixedTime(new Date(PINNED_CLOCK));
+    const page = await ctx.newPage();
+    // A states file's click on an element this fixture world never draws would
+    // otherwise wait out Playwright's 30s default; the reading notes it and moves on.
+    page.setDefaultTimeout(ACTION_TIMEOUT_MS);
+    // A native confirm()/alert() a state's click opens would hold the page; the
+    // reading is of the page, so the dialog is dismissed.
+    page.on('dialog', (d) => { d.dismiss().catch(() => {}); });
+    page.on('response', (r) => {
+      if (!/\/api\//.test(r.url())) return;
+      if (!/json/i.test(r.headers()['content-type'] || '')) return;
+      pending.push(r.json().then((j) => collectStrings(j, data)).catch(() => {}));
+    });
+    const url = kit.withMode(plan.url, plan.mode, plan.modeQuery);
+    await page.goto(base + url, { waitUntil: 'load', timeout: 45000 });
+    await page.evaluate(() => document.fonts.ready).catch(() => {});
+    await page.waitForTimeout(kit.SETTLE_MS + EXTRA_SETTLE_MS);
+    try { await kit.runActions(page, plan.actions); } catch (e) { notes.push(`${plan.state}: an action failed (${String(e.message).split('\n')[0].slice(0, 120)}); read as it stood`); }
+    // A body read on a response from a page that has since navigated away never
+    // settles, so the wait for the data is bounded.
+    await Promise.race([Promise.all(pending), new Promise((r) => setTimeout(r, 2000))]);
+    const got = await page.evaluate(captureInPage);
+    if (got.branding) collectStrings(got.branding, data);
+    return { state: plan.state, strings: got.strings, notes, data };
+  } catch (e) {
+    notes.push(`${plan.state}: not rendered (${String(e.message).split('\n')[0].slice(0, 160)})`);
+    return { state: plan.state, strings: [], notes, data };
+  } finally {
+    await ctx.close().catch(() => {});
+  }
+}
+
+async function readPages(inventory, ids, { log = console.log, progress = true } = {}) {
+  const kit = require('../../modules/ui-design/kit/lib');
+  const registry = readJsonFile(REGISTRY_REL);
+  const matcher = buildMatcher(registry);
+  const pages = inventory.pages.filter((p) => ids.includes(p.id));
+  const surfaceDir = new Map(inventory.surfaces.map((s) => [s.id, s.at]));
+  const jobs = pages.flatMap((p) => planRenders(p).map((plan, i) => ({ ...plan, order: i })));
+  const stubs = new Map();
+  const stoppers = [];
+  let harness = null;
+  let browser;
+  try {
+    browser = await kit.launchBrowser();
+  } catch (e) {
+    const err = new Error(`page-reader: ${e.message}`);
+    err.noBrowser = e instanceof kit.NoBrowserError;
+    throw err;
+  }
+  const baseFor = async (plan, surface) => {
+    if (surface === 'builders') {
+      if (!harness) { harness = await startHarness(kit); stoppers.push(harness.stop); }
+      return harness.base;
+    }
+    const opts = { surface: SURFACE_MODULE[surface] || surface, auth: plan.auth, prefix: plan.stub.prefix, child: plan.stub.child, fixtures: plan.stub.fixtures };
+    const k = JSON.stringify(opts);
+    if (!stubs.has(k)) stubs.set(k, kit.startStub(opts).then((s) => { stoppers.push(s.stop); return s; }));
+    return (await stubs.get(k)).base;
+  };
+  const results = new Map();
+  const byId = new Map(pages.map((p) => [p.id, p]));
+  try {
+    let next = 0, done = 0;
+    const worker = async () => {
+      while (next < jobs.length) {
+        const job = jobs[next];
+        next += 1;
+        const page = byId.get(job.page);
+        const base = await baseFor(job, page.surface);
+        const t0 = Date.now();
+        // A hard ceiling per render: a page that never settles is a note on its
+        // reading, never a run that hangs.
+        let timer;
+        const r = await Promise.race([
+          renderOne(browser, kit, job, base),
+          new Promise((resolve) => { timer = setTimeout(() => resolve({ state: job.state, strings: [], notes: [`${job.state}: not rendered (no answer within ${RENDER_CEILING_MS / 1000}s)`], data: new Set() }), RENDER_CEILING_MS); }),
+        ]);
+        clearTimeout(timer);
+        done += 1;
+        if (progress) log(`  [${done}/${jobs.length}] ${job.page} ${job.state} (${((Date.now() - t0) / 1000).toFixed(1)}s)${r.notes.length ? '  !' : ''}`);
+        if (!results.has(job.page)) results.set(job.page, []);
+        results.get(job.page).push({ ...r, order: job.order });
+      }
+    };
+    await Promise.all(Array.from({ length: Math.min(CONCURRENCY, jobs.length) }, worker));
+  } finally {
+    await browser.close().catch(() => {});
+    for (const stop of stoppers) stop();
+  }
+  const out = [];
+  for (const page of pages) {
+    const caps = (results.get(page.id) || []).sort((a, b) => a.order - b.order);
+    const data = new Set(caps.flatMap((c) => [...c.data]));
+    const reading = assembleReading(page, caps, matcher, { dataValues: data, surfaceDir: surfaceDir.get(page.surface) });
+    log(`  ${page.id}: ${reading.counts.lines} lines (${reading.counts.placed} placed, ${reading.counts.shared} shared, ${reading.counts.unplaced} unplaced) from ${caps.length} state(s)${reading.notes.length ? `  ! ${reading.notes.length} note(s)` : ''}`);
+    out.push(reading);
+  }
+  return out;
+}
+
+// Merge fresh readings into the committed ones, in inventory order; a page the
+// inventory no longer lists drops out.
+function mergeReadings(inventory, previous, fresh) {
+  const byId = new Map(((previous && previous.pages) || []).map((p) => [p.id, p]));
+  for (const r of fresh) byId.set(r.id, r);
+  return inventory.pages.map((p) => byId.get(p.id)).filter(Boolean);
+}
+
+// mergeReadingDocs({ base, ours, theirs }) -> { ok, content, conflicted }
+//
+// The merge rule for docs/page-readings.json (task 1004775). Two approved page
+// tweak rounds branched from the same main each re-read THEIR page, and both
+// rewrite the top `counts` line — so git conflicts on every pair, and the second
+// round stranded as unresolvable_conflict until a person merged it by hand. A
+// re-read needs a browser, which a merge never has, but it does not need one: the
+// file is one entry per page, so the merge is per page. A page only one side
+// changed takes that side's reading; a page both changed the same way takes it; a
+// page both changed DIFFERENTLY is a real conflict (two rounds re-read one page —
+// their source files conflict too) and is named, never guessed. The summary counts
+// are recomputed from the merged pages and the whole file re-serialized, so the
+// result is byte-for-byte what the reader itself would write for those pages.
+// Pages keep ours' order; a page only theirs has goes where theirs had it.
+function mergeReadingDocs({ base, ours, theirs }) {
+  const parse = (s) => { try { return s && String(s).trim() ? JSON.parse(s) : { pages: [] }; } catch { return null; } };
+  const b = parse(base), o = parse(ours), t = parse(theirs);
+  if (!b || !o || !t) return { ok: false, content: null, conflicted: ['(unreadable json)'] };
+  const map = (d) => new Map((d.pages || []).map((p) => [p.id, p]));
+  const B = map(b), O = map(o), T = map(t);
+  const same = (x, y) => JSON.stringify(x === undefined ? null : x) === JSON.stringify(y === undefined ? null : y);
+  const order = [...O.keys()];
+  for (const id of T.keys()) {
+    if (order.includes(id)) continue;
+    const at = (t.pages || []).findIndex((p) => p.id === id);
+    const prev = at > 0 ? t.pages[at - 1].id : null;
+    const i = prev ? order.indexOf(prev) : -1;
+    order.splice(i + 1, 0, id);
+  }
+  const pages = [];
+  const conflicted = [];
+  for (const id of order) {
+    const bv = B.get(id), ov = O.get(id), tv = T.get(id);
+    let pick;
+    if (same(ov, tv)) pick = ov;
+    else if (same(ov, bv)) pick = tv;
+    else if (same(tv, bv)) pick = ov;
+    else { conflicted.push(id); continue; }
+    if (pick) pages.push(pick);
+  }
+  if (conflicted.length) return { ok: false, content: null, conflicted };
+  return { ok: true, content: serialize(buildDoc(pages)), conflicted: [] };
+}
+
+function loadPrevious() {
+  try { return readJsonFile(READINGS_REL); } catch { return null; }
+}
+
+async function main(args) {
+  const inventory = readJsonFile(INVENTORY_REL);
+  if (args.includes('--check')) {
+    const stale = checkReadings(inventory, loadPrevious());
+    if (stale.length) {
+      console.error(`page-reader: STALE — ${stale.length} page reading(s) do not match the tree:`);
+      for (const s of stale) console.error(`  ✗ ${s.id} (${s.why})`);
+      console.error(`Re-read them (opens a browser): ${REREAD_COMMAND}`);
+      return 1;
+    }
+    console.log(`page-reader: all ${inventory.pages.length} page readings match their files.`);
+    return 0;
+  }
+  const i = args.indexOf('--page');
+  let ids;
+  if (i > -1) {
+    ids = String(args[i + 1] || '').split(',').map((s) => s.trim()).filter(Boolean);
+    const unknown = ids.filter((id) => !inventory.pages.some((p) => p.id === id));
+    if (!ids.length || unknown.length) { console.error(`page-reader: --page needs inventory page ids${unknown.length ? ` (unknown: ${unknown.join(', ')})` : ''}`); return 2; }
+  } else if (args.includes('--stale')) {
+    ids = [...new Set(checkReadings(inventory, loadPrevious()).map((s) => s.id))].filter((id) => inventory.pages.some((p) => p.id === id));
+    if (!ids.length) {
+      const prev = loadPrevious();
+      const merged = mergeReadings(inventory, prev, []);
+      if (prev && merged.length !== ((prev.pages || []).length)) fs.writeFileSync(path.join(REPO_ROOT, READINGS_REL), serialize(buildDoc(merged)));
+      console.log('page-reader: nothing stale — no page re-read.');
+      return 0;
+    }
+  } else {
+    ids = inventory.pages.map((p) => p.id);
+  }
+  const started = Date.now();
+  console.log(`page-reader: reading ${ids.length} page(s)…`);
+  let fresh;
+  try { fresh = await readPages(inventory, ids); } catch (e) {
+    console.error(e.message);
+    return e.noBrowser ? 3 : 1;
+  }
+  const secs = Math.round((Date.now() - started) / 1000);
+  if (args.includes('--print')) {
+    for (const r of fresh) {
+      console.log(`\n# ${r.id} — ${r.title}  (reading ${r.reading_hash}, files ${r.files_hash})`);
+      let sec = null;
+      for (const l of r.lines) {
+        if (l.section !== sec) { sec = l.section; console.log(`## ${sec}`); }
+        console.log(`  ${l.key} [${l.placement}${l.file ? ` ${l.file}:${l.line}` : ''}${l.state ? ` @${l.state}` : ''}] ${l.text}`);
+      }
+      for (const n of r.notes) console.log(`  ! ${n}`);
+    }
+    console.log(`\npage-reader: read in ${secs}s; --print writes nothing.`);
+    return 0;
+  }
+  const merged = mergeReadings(inventory, loadPrevious(), fresh);
+  fs.writeFileSync(path.join(REPO_ROOT, READINGS_REL), serialize(buildDoc(merged)));
+  console.log(`page-reader: ${fresh.length} page(s) read in ${secs}s -> wrote ${READINGS_REL} (${merged.length} readings)`);
+  return 0;
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2)).then((code) => { process.exitCode = code; }, (e) => { console.error(`page-reader: ${e.stack || e.message}`); process.exitCode = 1; });
+}
+
+module.exports = {
+  INVENTORY_REL, REGISTRY_REL, READINGS_REL, REREAD_COMMAND, PLACEMENTS, HOLE,
+  filesHash, readingHash, buildMatcher, placeText, collectStrings, holeData,
+  mergeStates, assembleReading, serialize, buildDoc, checkReadings, planRenders,
+  captureInPage, mergeReadings,
+  // task 1004775: the merge driver's per-page rule for docs/page-readings.json.
+  mergeReadingDocs,
+  // task 1004322: /tweak renders the page the reader reads, through the same harness.
+  startHarness, SURFACE_MODULE, PINNED_CLOCK,
+};