@bongos/core 1.19.1056 → 1.19.1057

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.1056",
-  "core_contract": "1.19.1056",
-  "source_commit": "069ec293a36320e7bb8a9546282a2ef92bed10e4",
+  "core_version": "1.19.1057",
+  "core_contract": "1.19.1057",
+  "source_commit": "d501e49e33ddb2b6779e8bd556710c012c3d0cdb",
   "source_ref": "HEAD",
-  "built_at": "2026-09-28T05:31:55.050Z",
+  "built_at": "2026-09-28T06:35:05.692Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 543,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2511,
+    "functional_verbatim": 2513,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3081,
-  "tree_sha256": "8984ba3615dc3744fe218ef870fafffbf77518b4db628e054010ca8cb40ed041",
+  "file_count": 3083,
+  "tree_sha256": "fea44093e4742e41db41f9cc9c3a345b7f205059ca4cbe3f82b5eb02566df7b7",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2732,7 +2732,7 @@
     {
       "path": "docs/file-map.md",
       "mode": "0000644",
-      "sha256": "fe02a043a43ec6c062efea669b07722ae08e5ef93555ca80e489504dbc0180ad"
+      "sha256": "771b9fdbe001c3e10068a7a3eca13e270e4f017345f851ffac2bc94464bdee22"
     },
     {
       "path": "docs/handoff-template.md",
@@ -2742,7 +2742,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "8c3a8c0069cd15d3b2ade2c2cc7c87a346c733cadd37ffc7c52a1f1ec22e3f6f"
+      "sha256": "f2b7d0470a3301710a06171c98e6fe5e512f234e566317116039b0d684d6dc92"
     },
     {
       "path": "docs/modules-contract.md",
@@ -8467,12 +8467,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "edc67014a2cb1e4b1b5d6e59d3da8cacb2b22c51c959bc28fc33e598b400e1c5"
+      "sha256": "9df4cf4a5ad66ced9b1f6868540c91d6fa25a89405926352c63d6469398b2ec9"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "7bf05c3c167f553ab3f5aa7f68adb070625e336e0ab8444d5f5ccd3609eff206"
+      "sha256": "3fca2502e59fa31b4575a0bfa09712cceea4114940af579d38f2852feb1aaaf4"
     },
     {
       "path": "public-docs/index.html",
@@ -8492,7 +8492,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "cf9eeae40e20a710b6342a6af31c2f29cd0044df79f221408a8f98c3531f1252"
+      "sha256": "7929f537dc60f10bad4ca1a0929bdec87bb6f5508997f82fa25c9b788777b3fb"
     },
     {
       "path": "scripts/bongos-mcp.js",
@@ -9394,6 +9394,11 @@
       "mode": "0000644",
       "sha256": "f4b676c3949015733bc3f1bcaf369c2ab1225583b0200f862c25a6f0f18d3873"
     },
+    {
+      "path": "scripts/gds/page-reader.js",
+      "mode": "0000644",
+      "sha256": "aae55494f204111e5511729bf10bab6fade4ba2b9727c4155ab76b2b7b80054b"
+    },
     {
       "path": "scripts/gds/paste-token.js",
       "mode": "0000644",
@@ -9852,7 +9857,7 @@
     {
       "path": "scripts/gds/ship-check.js",
       "mode": "0000644",
-      "sha256": "3ca2e32eaea17ef03a91606b3815551a8cfdd3987b6e182c08017c84c7947ee3"
+      "sha256": "7a51c161729e549e42f3258695e91c6500c147fd56b4b571f7599bcd4f83e97b"
     },
     {
       "path": "scripts/gds/ship-deploy-target.js",
@@ -10572,7 +10577,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "8419fdb2f19beaccf903a5f9d341ba6b0bf76b75d6f8e14c574e65e341f6a83e"
+      "sha256": "359179dcb9b13435adf5c0f8e55fe24d1f1edea46756f13cfd1d02c8d343abaf"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -13644,6 +13649,11 @@
       "mode": "0000644",
       "sha256": "363855afde70c909be7b6392d36663848c823afed0131a8785286b7b93ca321b"
     },
+    {
+      "path": "tests/page_reader.mjs",
+      "mode": "0000644",
+      "sha256": "2d86f24827327f8015feec80de6fb1089d7f5d5589847a1c0cf4fad59412d307"
+    },
     {
       "path": "tests/parallel-load.mjs",
       "mode": "0000644",

package/docs/file-map.md

@@ -50,6 +50,7 @@
 │   ├── copy-inventory.md       ← GENERATED twin of copy-registry.json: the human-readable copy report, including the "what this cannot see" section (server-side messages, skill prose, Discord copy, runtime-composed strings, and the src/ui-vs-reality surface mismatch)
 │   ├── page-inventory.json     ← GENERATED (scripts/gds/page-inventory.js, BV2.TW02 task 1004314): every page of every enabled web surface (builders hall, landing, status) with its stable id <surface>:<page>, title, portable url, the files that render it and its .states.json states. Tweak Mode keys page status, claims and pay on these ids; regenerate + commit, never hand-edit
 │   ├── page-inventory.md       ← GENERATED twin of page-inventory.json: the id rule, then one table per surface
+│   ├── page-readings.json      ← GENERATED (scripts/gds/page-reader.js, BV2.TW04 task 1004315, ADR 0341 D3): every inventory page rendered in each state, its visible strings in page order by section, each placed (registry row), shared (shell text) or unplaced; reading_hash + files_hash per page. Re-read with page-reader.js --stale, never hand-edit
 │   ├── handoff-template.md      ← session-end template + Definition of Done
 │   ├── module-api-changelog.md  ← the `CORE_VERSION` release ledger for the published doorway (ADR 0203, task 1003335). MOVED here out of src/module-api.js: the ADR 0161 CI carrier appends an entry on every release and pushes straight to main, which grew that .js file past the 1500-line oversized-file ratchet and turned `unit` red for main and every open PR. Markdown is exempt from the .js line budget. Written by scripts/gds/bump-version.js (entries oldest-first, each inserted above the closing divider); the CORE_VERSION literal itself stays in src/module-api.js
 │   ├── google-chat-broadcast.md ← team-chat integration plan
@@ -202,6 +203,7 @@
 │       ├── doc-comment-coverage.js ← ADR 0095 / task 1001654: the ADVISORY doc-comment nudge (fitness Check 28) — reports source files under src/·scripts/·modules/ that open with no module header. Never hard-fails: a doc-comment gate that blocks a ship buys filler prose, and making it blocking needs owner sign-off + its own ADR. CRLF-safe (unlike docs-entropy.js); an empty enumeration throws as a scan defect
 │       ├── copy-inventory.js  ← R01 of goal 1000074 (the artist's loop): the COPY REGISTRY — every user-facing string across the hall / status / landing surfaces, each row naming the render path that shows it (html-text · html-attr · js-markup · js-notice · js-text-assign) + a stable id that survives a move. Writes docs/copy-registry.json + docs/copy-inventory.md; `--check` fails on drift. Precision over recall: a JS literal with no render path is not listed
 │       ├── page-inventory.js  ← BV2.TW02 (task 1004314): the PAGE INVENTORY — surfaces from the loader's moduleWebSurfaces() over the ENABLED modules (no hardcoded list), pages from each surface's *.html, ids <surface>:<page> (page = body[data-page] else the file name). Writes docs/page-inventory.json + .md; `--check` (run by fitness.js + ship-check.js) fails on drift, a duplicate id or an empty surface
+│       ├── page-reader.js     ← BV2.TW04 (task 1004315, ADR 0341 D3): the PAGE READER — renders every page of docs/page-inventory.json in each state (hall-preview harness + ui-design kit stub, one browser, about two minutes for all 37) and writes docs/page-readings.json; `--check` (ship-check only, no browser) compares files_hash; `--stale` re-reads the stale pages
 │       ├── copy-apply.js     ← R03 of goal 1000074 (ADR 0233): lands a copy proposal as a REAL DIFF under a claim — the design half’s adapter.export() applied to text. Reads the fenced copy-proposal patch off a task (--task N; --dry-run, --patch-file), RE-DERIVES the string’s position by re-running copy-inventory’s own extractor over the working tree (the registry commits no offsets — they go stale, the id does not), re-injects the source’s own ${expr} into the proposal’s {…} holes, writes, regenerates the registry and verifies its own edit. Refuses BY NAME on target_gone / ambiguous_target / no_exact_span / placeholder_mismatch / path_outside_surface. The ONLY writer in the copy feature, and deliberately a command rather than a route
 │       ├── gen-role-responsibilities.js ← writes each role pack's written-responsibility block from src/role-responsibilities.js (task 1003732, ADR 0275). Targets come from the role registry, not a hardcoded list, so a renamed pack or a fourth craft needs no edit here; the block takes the pack's own line ending (the packs are CRLF on Windows, LF in CI). `--check` is the CI gate, run by role-pack-guard.js — never hand-edit a block
 │       ├── role-pack-guard.js   ← the fitness check over the role packs (task 1002990, ADR 0274): every registry entry resolves to a real pack, every pack fits its char budget, three crafts carry one, and each pack's responsibility block is current. HARD-fails because claim.js reads the registry fail-open, so a broken pack path is silent at runtime

package/docs/module-api-changelog.md

@@ -2599,5 +2599,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.1054 with no explicit bump. run 36380323033. (task 1002620)
   1.19.1056 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.1055 with no explicit bump. run 36382270561. (task 1002620)
+  1.19.1057 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.1056 with no explicit bump. run 36387147130. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1056",
+  "version": "1.19.1057",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.1056",
+      "version": "1.19.1057",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1056",
+  "version": "1.19.1057",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -7637,5 +7637,11 @@
       "id": "1004332",
       "text": "Tweak Mode now has one written plan that every later step builds on. It says how a page is taken, where the artist's words rest while they write, how a page shows as tweaked or changed since, how the Word download and upload w"
     }
+  ],
+  "1.19.1057": [
+    {
+      "id": "1004315",
+      "text": "Every page of the project now has a written reading: all the words it actually shows, in order, grouped under its headings. Each line says where the words live. Some come from a known place in the code, some are shared by ever"
+    }
   ]
 }

package/scripts/gds/page-reader.js

@@ -0,0 +1,674 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/gds/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/gds/page-reader.js                 (re-read every page, write the readings)
+//       node scripts/gds/page-reader.js --stale         (re-read only the pages --check calls stale)
+//       node scripts/gds/page-reader.js --page builders:studio,landing:index
+//       node scripts/gds/page-reader.js --check         (no browser: exit 1 naming each stale page)
+//       node scripts/gds/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/gds/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/gds/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/gds/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);
+}
+
+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,
+};

package/scripts/gds/ship-check.js

@@ -35,6 +35,8 @@ const STEPS = [
   { key: 'api-docs', label: 'docs/api/openapi.json + api-reference fresh', argv: ['scripts/gds/gen-api-docs.js', '--check'], fix: 'node scripts/gds/gen-api-docs.js' },
   { 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: 'page-inventory', label: 'docs/page-inventory.json fresh (every page + its stable id)', argv: ['scripts/gds/page-inventory.js', '--check'], fix: 'node scripts/gds/page-inventory.js', optional: true },
+  // The page readings (task 1004315, ADR 0341 D3): files_hash only, no browser; the fix is the reader's own re-read.
+  { key: 'page-readings', label: 'docs/page-readings.json fresh (every page\'s reading matches its files)', argv: ['scripts/gds/page-reader.js', '--check'], fix: 'node scripts/gds/page-reader.js --stale', 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 },

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.1056'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1057'; // 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/page_reader.mjs

@@ -0,0 +1,200 @@
+// tests/page_reader.mjs — the page reader (BV2.TW04, task 1004315; ADR 0341 D3;
+// the Tweak Mode chain, goal 1000095).
+//
+// What these tests defend:
+//   1. NOTHING IS DROPPED. A visible string the copy registry cannot place is
+//      LISTED as unplaced, with a key and a section — the task's own done-when.
+//      Only a string that is nothing but the page's own data is left out, and
+//      the registry is always asked first, so a placed string is never mistaken
+//      for data.
+//   2. PLACEMENT. Exact text, a holed row's pattern, a segment of a holed row —
+//      a row in the page's own files first, never another page's html.
+//   3. SHARED. Shell text is marked shared, keeps its registry row when it has
+//      one, and is outside reading_hash.
+//   4. THE CONTRACT. docs/page-readings.json covers every inventory page, each
+//      line carries key/section/text/placement, keys run L0001.. in order, and
+//      both hashes are what the generator computes.
+//   5. FRESHNESS WITHOUT A BROWSER. --check compares files_hash, names the re-read
+//      command, and never loads the browser driver.
+//
+// DB-free, network-free, browser-free.
+// Run:  node --test tests/page_reader.mjs
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+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 reader = require(path.join(ROOT, 'scripts', 'gds', 'page-reader.js'));
+const shipCheck = require(path.join(ROOT, 'scripts', 'gds', 'ship-check.js'));
+
+const REGISTRY = {
+  entries: [
+    { id: 'aaa000000001', text: 'Welcome back', file: 'mods/pub/home.html', line: 10 },
+    { id: 'aaa000000002', text: '${…} of ${…} shipped this week', file: 'mods/pub/home.js', line: 40 },
+    { id: 'aaa000000003', text: 'Signed in as ${…}. Sign out', file: 'mods/pub/shell.js', line: 7 },
+    { id: 'aaa000000004', text: 'Welcome back', file: 'mods/pub/other.html', line: 3 },
+    { id: 'aaa000000005', text: 'Only on the other page', file: 'mods/pub/other.html', line: 5 },
+    { id: 'aaa000000006', text: 'Loaded late', file: 'mods/pub/late.js', line: 2 },
+    { id: 'aaa000000007', text: 'Studio — {{worldName}}', file: 'mods/pub/home.html', line: 1 },
+  ],
+};
+const PAGE = { id: 'builders:home', surface: 'builders', title: 'Home', files: ['mods/pub/home.html', 'mods/pub/shell.js', 'mods/pub/home.js'] };
+const matcher = reader.buildMatcher(REGISTRY);
+const place = (t) => reader.placeText(t, matcher, { files: PAGE.files, surfaceDir: 'mods/pub' });
+const fakeFs = { readFileSync: () => 'x' };
+const assemble = (captures, opts = {}) => reader.assembleReading(PAGE, captures, matcher, { surfaceDir: 'mods/pub', fsImpl: fakeFs, ...opts });
+
+test('an unplaced string is listed, not dropped', () => {
+  const r = assemble([{ state: 'default', strings: [
+    { text: 'Welcome back', section: 'Home', shared: null },
+    { text: 'A sentence no file in the registry holds', section: 'Home', shared: null },
+    { text: 'Welcome back', section: 'Later', shared: null },
+  ] }]);
+  const line = r.lines.find((l) => l.text === 'A sentence no file in the registry holds');
+  assert.ok(line, 'the unplaceable string is in the reading');
+  assert.equal(line.placement, 'unplaced');
+  assert.equal(line.section, 'Home');
+  assert.match(line.key, /^L\d{4}$/);
+  assert.equal(line.file, undefined, 'an unplaced line names no file');
+  assert.equal(r.counts.unplaced, 1);
+  assert.deepEqual(r.lines.map((l) => l.key), ['L0001', 'L0002', 'L0003'], 'keys run in page order');
+});
+
+test('an unplaced string that CONTAINS data keeps its words, with the data holed', () => {
+  const data = new Set(['Ada Lovelace', 'ready']);
+  const r = assemble([{ state: 'default', strings: [
+    { text: 'Good morning, Ada Lovelace', section: '', shared: null },
+    { text: 'Ada Lovelace', section: '', shared: null },
+    { text: '42', section: '', shared: null },
+  ] }], { dataValues: data });
+  assert.deepEqual(r.lines.map((l) => [l.text, l.placement]), [['Good morning, {…}', 'unplaced']]);
+  assert.equal(r.omitted.data, 1, 'the pure-data string is counted, and the number is not copy');
+});
+
+test('clock times and dates in an unplaced string are holed, so a re-read reads the same', () => {
+  assert.equal(reader.holeData('· since 10:43 PM', new Set()).text, '· since {…}');
+  assert.equal(reader.holeData('Filed Sep 10, 2026 · Blocking 2 tasks:', new Set()).text, 'Filed {…} · Blocking 2 tasks:');
+  assert.equal(reader.holeData('Jul 20, 2026', new Set()).data, true, 'a bare date is data');
+  assert.equal(reader.holeData('Licensed AGPL-3.0', new Set()).text, 'Licensed AGPL-3.0', 'a version number is left alone');
+});
+
+test('the registry is asked before the data: a placed string is never taken for data', () => {
+  const r = assemble([{ state: 'default', strings: [{ text: 'Welcome back', section: '', shared: null }] }], { dataValues: new Set(['Welcome back']) });
+  assert.equal(r.lines.length, 1);
+  assert.equal(r.lines[0].placement, 'placed');
+});
+
+test('placement: exact, pattern and segment; the page\'s own file wins; never another page\'s html', () => {
+  assert.deepEqual(place('Welcome back'), { file: 'mods/pub/home.html', line: 10, string_id: 'aaa000000001', text: 'Welcome back', how: 'exact' });
+  const pat = place('3 of 9 shipped this week');
+  assert.equal(pat.string_id, 'aaa000000002');
+  assert.equal(pat.text, '{…} of {…} shipped this week', 'a pattern-placed line reads as its row, with the registry\'s {…} holes');
+  assert.equal(place('shipped this week').string_id, 'aaa000000002', 'a literal segment of a holed row places');
+  assert.equal(place('Only on the other page'), null, 'a row in ANOTHER page\'s html does not place a string on this one');
+  assert.equal(place('Loaded late').file, 'mods/pub/late.js', 'a script elsewhere on the surface is the fallback');
+  assert.equal(place('Studio — Cloud Bongos').text, 'Studio — {{worldName}}', 'entities decode and a {{token}} is a hole');
+});
+
+test('shared text is marked shared, keeps its row, and stays out of reading_hash', () => {
+  const own = { text: 'Welcome back', section: 'Home', shared: null };
+  const a = assemble([{ state: 'default', strings: [{ text: 'Signed in as Ada. Sign out', section: '', shared: 'top bar' }, own] }]);
+  const top = a.lines[0];
+  assert.equal(top.placement, 'shared');
+  assert.equal(top.section, 'top bar');
+  assert.equal(top.string_id, 'aaa000000003');
+  const b = assemble([{ state: 'default', strings: [{ text: 'Something else entirely', section: '', shared: 'top bar' }, own] }]);
+  assert.equal(b.lines[0].placement, 'shared', 'an unplaceable shell string is still shared');
+  assert.equal(a.reading_hash, b.reading_hash, 'a changed shell line does not move the page\'s own hash');
+  const c = assemble([{ state: 'default', strings: [{ text: 'Welcome back', section: 'Elsewhere', shared: null }] }]);
+  assert.notEqual(a.reading_hash, c.reading_hash, 'a changed own line does');
+});
+
+test('other states add their lines where they sit, named, after the default state\'s', () => {
+  const r = assemble([
+    { state: 'closed', strings: [{ text: 'Welcome back', section: 'Home', shared: null }, { text: 'Loaded late', section: 'Home', shared: null }] },
+    { state: 'open', strings: [{ text: 'Welcome back', section: 'Home', shared: null }, { text: 'A panel only open shows', section: 'Home', shared: null }, { text: 'Loaded late', section: 'Home', shared: null }] },
+  ]);
+  assert.deepEqual(r.lines.map((l) => [l.text, l.state || null]), [['Welcome back', null], ['A panel only open shows', 'open'], ['Loaded late', null]]);
+  assert.deepEqual(r.states_read, ['closed', 'open']);
+});
+
+test('a string repeated in one section is one line with its occurrences', () => {
+  const r = assemble([{ state: 'default', strings: [1, 2, 3].map(() => ({ text: 'Welcome back', section: 'List', shared: null })) }]);
+  assert.equal(r.lines.length, 1);
+  assert.equal(r.lines[0].occurrences, 3);
+});
+
+test('files_hash folds CRLF, and moves when a file changes or disappears', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'page-reader-'));
+  fs.writeFileSync(path.join(dir, 'a.html'), 'one\ntwo\n');
+  const lf = reader.filesHash(['a.html'], { root: dir });
+  fs.writeFileSync(path.join(dir, 'a.html'), 'one\r\ntwo\r\n');
+  assert.equal(reader.filesHash(['a.html'], { root: dir }), lf, 'a Windows checkout agrees with CI');
+  fs.writeFileSync(path.join(dir, 'a.html'), 'one\ntwo!\n');
+  assert.notEqual(reader.filesHash(['a.html'], { root: dir }), lf);
+  fs.rmSync(path.join(dir, 'a.html'));
+  assert.notEqual(reader.filesHash(['a.html'], { root: dir }), lf);
+});
+
+test('checkReadings names a missing reading, a changed page and an extra one', () => {
+  const inv = { pages: [{ id: 's:a', files: ['x'] }, { id: 's:b', files: ['y'] }] };
+  const f = { readFileSync: (p) => (p.endsWith('x') ? 'X' : 'Y') };
+  const good = reader.filesHash(['x'], { fsImpl: f });
+  const stale = reader.checkReadings(inv, { pages: [{ id: 's:a', files_hash: good }, { id: 's:gone', files_hash: 'z' }] }, { fsImpl: f });
+  assert.deepEqual(stale, [{ id: 's:b', why: 'no reading' }, { id: 's:gone', why: 'not in the inventory' }]);
+  assert.deepEqual(reader.checkReadings(inv, { pages: [{ id: 's:a', files_hash: 'old' }, { id: 's:b', files_hash: reader.filesHash(['y'], { fsImpl: f }) }] }, { fsImpl: f }), [{ id: 's:a', why: 'its files changed' }]);
+});
+
+test('the committed readings cover every inventory page, in the D3 shape', () => {
+  const inv = JSON.parse(fs.readFileSync(path.join(ROOT, reader.INVENTORY_REL), 'utf8'));
+  const doc = JSON.parse(fs.readFileSync(path.join(ROOT, reader.READINGS_REL), 'utf8'));
+  assert.deepEqual(doc.pages.map((p) => p.id), inv.pages.map((p) => p.id), 'one reading per inventory page, in inventory order');
+  let unplaced = 0;
+  for (const p of doc.pages) {
+    assert.ok(p.lines.length > 0, `${p.id} has lines`);
+    p.lines.forEach((l, i) => {
+      assert.equal(l.key, `L${String(i + 1).padStart(4, '0')}`, `${p.id} keys run in order`);
+      assert.ok(typeof l.section === 'string' && l.section, `${p.id} ${l.key} has a section`);
+      assert.ok(typeof l.text === 'string' && l.text, `${p.id} ${l.key} has text`);
+      assert.ok(reader.PLACEMENTS.includes(l.placement), `${p.id} ${l.key} placement`);
+      if (l.placement === 'placed') assert.ok(l.file && Number.isInteger(l.line) && /^[0-9a-f]{12}$/.test(l.string_id), `${p.id} ${l.key} names its registry row`);
+      if (l.placement === 'unplaced') { unplaced += 1; assert.equal(l.string_id, undefined); }
+    });
+    assert.equal(p.reading_hash, reader.readingHash(p.lines), `${p.id} reading_hash is over its lines`);
+    assert.equal(p.counts.lines, p.lines.length);
+  }
+  assert.ok(unplaced > 0, 'the real pages carry unplaced strings, and they are listed');
+  assert.deepEqual(reader.checkReadings(inv, doc), [], 'the committed readings match this tree (re-read: node scripts/gds/page-reader.js --stale)');
+});
+
+test('--check needs no browser and names the re-read command', () => {
+  // A preload that makes the browser driver unloadable: if --check ever reached
+  // for it, this run would fail.
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'page-reader-nobrowser-'));
+  const pre = path.join(dir, 'no-browser.cjs');
+  fs.writeFileSync(pre, "const M=require('module');const o=M._load;M._load=function(r,...a){if(/playwright|ui-design[\\\\/]kit/.test(r))throw new Error('browser reached: '+r);return o.call(this,r,...a);};\n");
+  const r = spawnSync(process.execPath, ['--require', pre, path.join(ROOT, 'scripts', 'gds', 'page-reader.js'), '--check'], { cwd: ROOT, encoding: 'utf8' });
+  assert.equal(r.status, 0, r.stderr || r.stdout);
+  assert.match(reader.REREAD_COMMAND, /page-reader\.js --stale/);
+  const src = fs.readFileSync(path.join(ROOT, 'scripts', 'gds', 'page-reader.js'), 'utf8');
+  assert.match(src, /Re-read them \(opens a browser\): \$\{REREAD_COMMAND\}/, 'a stale --check names the command');
+});
+
+test('ship-check runs the browser-free --check, and fitness does not render', () => {
+  const step = shipCheck.STEPS.find((s) => s.key === 'page-readings');
+  assert.ok(step, 'ship-check has a page-readings row');
+  assert.deepEqual(step.argv, ['scripts/gds/page-reader.js', '--check']);
+  assert.equal(step.fix, reader.REREAD_COMMAND);
+  const fitness = fs.readFileSync(path.join(ROOT, 'scripts', 'gds', 'fitness.js'), 'utf8');
+  assert.doesNotMatch(fitness, /page-reader/, 'fitness never runs the reader (a render is the builder\'s own command)');
+});
+
+test('a hall page with no states file is read once, at its own path', () => {
+  assert.deepEqual(reader.planRenders({ id: 'builders:x', surface: 'builders', path: '/x', states_files: [] }).map((p) => [p.state, p.url]), [['default', '/x']]);
+});