@bongos/core 1.19.396 → 1.19.397

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.396",
-  "core_contract": "1.19.396",
-  "source_commit": "b4632d6e8d92e8096e958762a36e810fc24c9c35",
+  "core_version": "1.19.397",
+  "core_contract": "1.19.397",
+  "source_commit": "1474f9835d0443e4986671261eda1c4fbdc42f77",
   "source_ref": "HEAD",
-  "built_at": "2026-08-28T16:08:46.136Z",
+  "built_at": "2026-08-28T17:09:55.951Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 345,
+    "docs_redacted": 346,
     "agent_docs_stubbed": 23,
-    "functional_verbatim": 1635,
+    "functional_verbatim": 1656,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2003,
-  "tree_sha256": "950c8c43ac98c0e161e25a1c17cd699ad9582392105dcd0abadc8efc090a95c8",
+  "file_count": 2025,
+  "tree_sha256": "0f6d8ffa405c75bbf9238495bd46ce02aab1724213fee1856d77e34c261f7e34",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -127,7 +127,7 @@
     {
       "path": ".claude/skills/design/SKILL.md",
       "mode": "0000644",
-      "sha256": "83f2d423421bc08e7f460847616bc0cfba636cb24563566724776b2c7c1a1662"
+      "sha256": "3fff5beddcb4dc4b2091b27f70fe56a9117db25be3e1201c145ded8123762c16"
     },
     {
       "path": ".claude/skills/dev/SKILL.md",
@@ -1822,7 +1822,7 @@
     {
       "path": "docs/file-map.md",
       "mode": "0000644",
-      "sha256": "3789594e075f2501de76ac637a3adcb383e3bc611f84f985ed9e385e5d5c8169"
+      "sha256": "da6550986b40181599b2b8e3a4bf0fa02ac82ded0b75b65ec69d8ac6deb1606e"
     },
     {
       "path": "docs/handoff-template.md",
@@ -2054,6 +2054,11 @@
       "mode": "0000644",
       "sha256": "02ae31810440b86f7c896b7014c75549497cab47345079986d54c9785cf5cc4a"
     },
+    {
+      "path": "docs/recipes/ui-look-before-you-ship.md",
+      "mode": "0000644",
+      "sha256": "cd8272b75c5fe26f165cf95a45656109266c8ef1942a47705ab10f5f5affcdd5"
+    },
     {
       "path": "docs/recipes/upgrading-the-core.md",
       "mode": "0000644",
@@ -3999,6 +4004,11 @@
       "mode": "0000644",
       "sha256": "99f9338383c4940f199f8ad66d2140779b0262b628c135646c00778973a5b292"
     },
+    {
+      "path": "modules/hall-ui/public/ranks.states.json",
+      "mode": "0000644",
+      "sha256": "3a2e1d649c217473b3706f9295b796c50a20327b78b2856daf85bf01a1e34b27"
+    },
     {
       "path": "modules/hall-ui/public/roadmap.css",
       "mode": "0000644",
@@ -5177,7 +5187,77 @@
     {
       "path": "modules/ui-design/kit/README.md",
       "mode": "0000644",
-      "sha256": "70f65052951335b63def03590ee971e2f482d6db08365484b532e4bc3c676495"
+      "sha256": "850e72f762d80951ed0ad6ca392a5c0619f26c10a58edd0a1d467038b74bbcfa"
+    },
+    {
+      "path": "modules/ui-design/kit/check-mock.js",
+      "mode": "0000644",
+      "sha256": "9f38941d23b498feeac12f6f32a64d5f3c7749e1b6e01db7bf83dedd3cc2e549"
+    },
+    {
+      "path": "modules/ui-design/kit/contrast.js",
+      "mode": "0000644",
+      "sha256": "239cc33a7896dbbe0bab25098904b2be8298ff5c440b7e2a44594e131d21ed9c"
+    },
+    {
+      "path": "modules/ui-design/kit/fixtures/cost-summary.json",
+      "mode": "0000644",
+      "sha256": "057391fcbba1985a234cf1d4f56db36a89a79d1ee44a80b5cd30f51ed7175cdb"
+    },
+    {
+      "path": "modules/ui-design/kit/fixtures/featured.json",
+      "mode": "0000644",
+      "sha256": "a5e075d343bc7d29e69896ba90de2fc96e2aeb5765f09e193cb26926b4ae697d"
+    },
+    {
+      "path": "modules/ui-design/kit/fixtures/leaderboard.json",
+      "mode": "0000644",
+      "sha256": "53f4fbe364bee2295133ea55082b79069451b0deaf3e99e42d0963c63ee1da87"
+    },
+    {
+      "path": "modules/ui-design/kit/fixtures/me.json",
+      "mode": "0000644",
+      "sha256": "71e560cd3ffcc86287f0ec9c0e527de5ce568a1a9c5c8a6cefea7efe2459d070"
+    },
+    {
+      "path": "modules/ui-design/kit/fixtures/my-projects.json",
+      "mode": "0000644",
+      "sha256": "ff0195be4b19616f30fccde0dc980a47329587124bfac08158b1e8741386fc1b"
+    },
+    {
+      "path": "modules/ui-design/kit/fixtures/progress.json",
+      "mode": "0000644",
+      "sha256": "bbc16593ef50e966647f54559834a956778ac59937ef3fc27794d98d1e12a67e"
+    },
+    {
+      "path": "modules/ui-design/kit/fixtures/recent-shipped.json",
+      "mode": "0000644",
+      "sha256": "5c50e901d4e2e123b2c94f17b42e68cdb5dd9702edff840802777f0796e8f976"
+    },
+    {
+      "path": "modules/ui-design/kit/lib.js",
+      "mode": "0000644",
+      "sha256": "9b0b5eb21711fd7f5c0857a89066270ac8c0911cec19d0b8f21ed369a1dde8e5"
+    },
+    {
+      "path": "modules/ui-design/kit/png.js",
+      "mode": "0000644",
+      "sha256": "d4a7f9c791dec3857452642a1f87dac716c2f098a36d6f7b5a0655da9a110b4e"
+    },
+    {
+      "path": "modules/ui-design/kit/probe.js",
+      "mode": "0000644",
+      "sha256": "d38d6168c3bd701a368726fbf53bfb9209711bd2cb68b7df79a3d2505edf2efe"
+    },
+    {
+      "path": "modules/ui-design/kit/render.js",
+      "mode": "0000644",
+      "sha256": "15931b862ff62824b9916172d75df677bea186e1be23eefb99bbd4541932acfd"
+    },
+    {
+      "path": "modules/ui-design/kit/serve.js",
+      "mode": "0000644",
+      "sha256": "f1d349f681525b78abb47df98bf26a1f7470a72b00b8d5696d5453bb936647c8"
     },
     {
       "path": "modules/ui-design/module.json",
@@ -5212,12 +5292,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "7dd6552859e62daf201d9fdd1c17f95ea4a97bac3e5dc95d175ed0c8bbac88c7"
+      "sha256": "261eccb023c862c7b005d3078f269afdee0db925ebb0834145cb8080a30137f9"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "292bfaf5419d894c03339b6363173872ba73e896a9dceec60ff625568fe9ed60"
+      "sha256": "cd144d5c3d9102a17d79445708230c929987ac1d102ca82c3aa69493b8fdc242"
     },
     {
       "path": "public-docs/index.html",
@@ -5549,6 +5629,16 @@
       "mode": "0000644",
       "sha256": "1e7ceb571c899be95c7a945a8bd4337bb000af2b90d6f8de5b4dfcef3a5e8891"
     },
+    {
+      "path": "public-landing/index.probes.json",
+      "mode": "0000644",
+      "sha256": "eb90141b2ef676e06b3140d2e8caa61481991a748b36491502592987ed9c0880"
+    },
+    {
+      "path": "public-landing/index.states.json",
+      "mode": "0000644",
+      "sha256": "8d5955085ab5059a15195d5c475262d114061d616dd9c82335a91a5992cc5602"
+    },
     {
       "path": "public-landing/privacy.html",
       "mode": "0000644",
@@ -5559,6 +5649,16 @@
       "mode": "0000644",
       "sha256": "1e1867918ec2a8fe489d9d21aa2e50fada9950b220c865c57f23c703a6c29f24"
     },
+    {
+      "path": "public-landing/projects.probes.json",
+      "mode": "0000644",
+      "sha256": "e5594cda5b6c30569aaca6181dc39eb28d20e716cdebbca7ad618748bbb8ccb5"
+    },
+    {
+      "path": "public-landing/projects.states.json",
+      "mode": "0000644",
+      "sha256": "26a1473a42005d89b4a15b3538b3e9fe9d1982633f1ec556524d83e114df5240"
+    },
     {
       "path": "public-landing/terms.html",
       "mode": "0000644",
@@ -6789,6 +6889,11 @@
       "mode": "0000644",
       "sha256": "cc6e8640376ada7ceff6a896007b3257c8ea4d943a900eae28433cd41bdd139d"
     },
+    {
+      "path": "scripts/gds/ui-kit-transform.js",
+      "mode": "0000644",
+      "sha256": "8735394cfc5bcdd85b7addb78c3de302f4ba0fee37c25a595f5dcb46240ec529"
+    },
     {
       "path": "scripts/gds/update-channel.js",
       "mode": "0000644",
@@ -7032,7 +7137,7 @@
     {
       "path": "src/bongos/module-scope-map.js",
       "mode": "0000644",
-      "sha256": "77dd62d640862624066bfcd2845c6ed2801091ce49ed676a809da3cce5077761"
+      "sha256": "9705e8a5176cfd1136c1b432b1d4ff71351d9f4654c636345597a4d96763e500"
     },
     {
       "path": "src/bongos/module-submissions.js",
@@ -7207,7 +7312,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "711a3add8803459721523364c9c993e30908475bebdf65eb83789f5520e91104"
+      "sha256": "dc2d98c7ece67a2c881914a1a9cf000736e7634161f774d09c5c66a7bef2c1a9"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9954,6 +10059,11 @@
       "mode": "0000644",
       "sha256": "74798ce81280d4fcfa5844b575c3c64db582308f7a0726fc420317fe83eadd96"
     },
+    {
+      "path": "tests/ui_design_kit.mjs",
+      "mode": "0000644",
+      "sha256": "2d3c4f767a3de04beddf22d6d0acf8ca57b7a85dc0f132930466eb4f33aa8c13"
+    },
     {
       "path": "tests/update_channel.mjs",
       "mode": "0000644",

package/.claude/skills/design/SKILL.md

@@ -25,7 +25,7 @@ Read, in this order, and quote nothing from memory:
 
 Render the real surface before and after — never reason about layout from source alone:
 
-- Stage it (`/builder-stage` on a box; a local stub + Playwright on a laptop — the kit under `modules/ui-design/kit/` ports the apex probes once [task 1003320](https://cloudbongos.com/builders#/task/1003320) lands) and screenshot **three widths (≥1280 / ~900 / ≤480) × two modes (light / dark)** at minimum.
+- Run the kit — `node modules/ui-design/kit/render.js --page <path>` renders every state of the page's states file at **1440 / 390 / 320 × dark / light** through a stub that serves the surface the way the instance does, audits each render against the floors below, and writes the shots; `node modules/ui-design/kit/probe.js --page <path>` runs the page's interaction contract as PASS/FAIL lines. The loop, the file shapes and the failure table: [`docs/recipes/ui-look-before-you-ship.md`](../../../docs/recipes/ui-look-before-you-ship.md). A page with no states file yet gets one first (copy the hub's). `/builder-stage` on a box shows the same change on a live preview.
 - Show the screens, then caption them in one line. The person you're working with judges the picture.
 - Grep the receiving page for class collisions before porting a component across pages (the landing's content sections are `.band`; the menu is `.menuBand`).
 

package/docs/file-map.md

@@ -129,7 +129,7 @@
 │   ├── hall-ui/                ← CORE-DOMAIN WEB-SURFACE carve (BV1.R85, default-on): the authenticated builders' hall at builders.<apex>, moved from public-builders/ (~13k LOC, the largest). NO routes/db/port — declares contributes.webSurfaces:[{host:"builders.",dir:"public"}] for discovery, but UNLIKE status-ui keeps its DEDICATED serving block in serve-internal (the /builders shim + canonical redirects + citizen/Archon page gates + asset-stamping + hall-widget injection), partitioned out of the generic web-surface loop and served from BUILDERS_DIR. CLAUDE.md, module.json, public/{index.html,builders.js,style.css,work,watch,harbor,gate,pair,settings,ranks,sessions,primer,diagrams,atlas,...}.{html,js},cursors/,chime.wav.
 │   ├── lifecycle/               ← CORE-DOMAIN carve (BV1.R86, default-on): the build state machine — tasks · claims · versions · done-when · goals · dependencies · claim→ship→grade→credit · github-push + merge-lock + conflict-resolve + publish-reconciler. The LAST, most-coupled carve; registers the `lifecycle` kernel port (createTask, classifyTaskKind, tallyPeerVotes, work-tracking reads). CLAUDE.md, module.json, routes/{tasks,claims,versions,done-when,goals,dependencies,gate-approvals,analytics}.js, lifecycle.js, github-push.js, merge-lock.js, conflict-resolve.js, publish-reconciler.js, task-visuals.js + task-visual-db.js + routes/visuals.js (the optional ship-time visual, task 1003109 — the route file is NOT named task-*.js on purpose; see the module CLAUDE.md).
 │   ├── copy-desk/               ← CORE-DOMAIN module (task 1003113 / R02 of goal 1000074, default-on): the COPY half of the design contract — ADR 0081 gave design TOKENS a repo-owned source of truth, text had none. Owns the FLAG (anyone in any role marks a string or a whole surface as needing an artist's attention, with a reason required in BOTH the route and a CHECK constraint) and the QUEUE an artist reads it from. READS R01's committed registry (docs/copy-registry.json, generated by scripts/gds/copy-inventory.js) and never writes it. NO LIVE CMS is the hard non-goal: no column here could hold replacement text, and copy_no_cms.mjs pins that. Key is `copy-desk`, not `copy` — the branding contract already owns a `copy` block, so the bare word reds the "core carries no module code" fitness check. CLAUDE.md, module.json, registry.js, flags.js, routes/copy-desk.js, migrations/copy_desk_001_flags.sql, tests/{copy_flags,copy_queue,copy_no_cms}.mjs. Its hall surface lives with hall-ui (public/copy-desk.{html,js,css}), per the one-key-per-web-surface precedent.
-│   ├── ui-design/               ← CORE-DOMAIN module (task 1003324 / ADR 0197, default-on): the design capability every builder on every instance gets — ships METHOD, never a world. Absorbs ADR 0081's layer: adapters/{claude-design,figma}/index.js (moved from src/ui/adapters/), scripts/{design-sync,figma-design-sync,validate-design}.js (moved from scripts/gds/, which keeps thin shims), docs/design-contract.md (moved from docs/). Declaration-only: contributes.skills design (the /design playbook, new) + design-sync + figma-design-sync; no routes/port/migrations, so disabling it touches no served surface. CLAUDE.md separates the platform FLOORS (the Fifteen Rule, the dark twins, no page :root, the 24px floor, AA in both modes, the kill switch) from the instance's WORLD (its packs + DESIGN.md). Reserved homes kit/ (task 1003320), skills/ (1003321), styles/ (1003323), each with a README. config/design-tokens.* + design-sources.json STAY in config/ as the host boundary; public-landing keeps its own key (first customer, not owner).
+│   ├── ui-design/               ← CORE-DOMAIN module (task 1003324 / ADR 0197, default-on): the design capability every builder on every instance gets — ships METHOD, never a world. Absorbs ADR 0081's layer: adapters/{claude-design,figma}/index.js (moved from src/ui/adapters/), scripts/{design-sync,figma-design-sync,validate-design}.js (moved from scripts/gds/, which keeps thin shims), docs/design-contract.md (moved from docs/). Declaration-only: contributes.skills design (the /design playbook, new) + design-sync + figma-design-sync; no routes/port/migrations, so disabling it touches no served surface. CLAUDE.md separates the platform FLOORS (the Fifteen Rule, the dark twins, no page :root, the 24px floor, AA in both modes, the kill switch) from the instance's WORLD (its packs + DESIGN.md). kit/ (task 1003320) is the look-before-you-ship kit: lib.js (the floors, the states/probes contracts, the action + expectation vocabularies, the WCAG maths, the stub spawner), serve.js (any surface through the doorway's real transforms + fixtures/), render.js (states × 1440/390/320 × dark/light, audited), probe.js (PASS/FAIL contracts), check-mock.js (platform rules + the instance's DESIGN.md taste bans), contrast.js + png.js; a page's <page>.states.json / <page>.probes.json sit BESIDE the surface (public-landing/, modules/hall-ui/public/). Recipe: docs/recipes/ui-look-before-you-ship.md. Reserved homes skills/ (1003321), styles/ (1003323), each with a README. config/design-tokens.* + design-sources.json STAY in config/ as the host boundary; public-landing keeps its own key (first customer, not owner).
 │   ├── character-anim/          ← consistent-character generative animation (ADR 0088) — graded painterly frame sets + manifest, the otb-character-review skill. CLAUDE.md, module.json.
 │   ├── provisioning/            ← stands up + operates a Cloud Bongos instance's own infra (server/DB/domain/DNS/TLS) via the API (ADR 0111); web-tier request+state only, no cloud tokens — a separate control-plane runner drains the intents. Distinct from the `hosting` module (ADR 0092), which brokers compute workloads. CLAUDE.md, module.json.
 │   └── demo/                    ← BV1.R52 acceptance-proof module: one rank-gated write route + one namespaced migration proving the loader mounts a scaffolded module with zero core edits. CLAUDE.md, module.json.

package/docs/recipes/ui-look-before-you-ship.md

@@ -0,0 +1,113 @@
+# Look before you ship — the ui-design kit
+
+> The `ui-design` module's kit (`modules/ui-design/kit/`, [task 1003320](https://cloudbongos.com/builders#/task/1003320), [ADR 0197](../adr/<redacted>.md)): a stub, a renderer/auditor, the interaction probes, the mock checker and the contrast probe any builder points at any surface of any instance. Plain Node; the browser is the system Edge or Chrome (nothing is downloaded). The `/design` playbook sends you here.
+
+The loop is five commands and one habit: **stub → render → probe → read the shots → fix in one batch → re-run once.** A surface describes itself in two small JSON files beside it; the kit never hardcodes a page.
+
+## 0. Once per machine
+
+```
+npm install                       # playwright-core is a devDependency; no browser download
+```
+
+Edge or Chrome must be installed. If neither launches, every kit command prints one line saying so and exits 3.
+
+## 1. Stub — serve the surface the way the instance would
+
+```
+node modules/ui-design/kit/serve.js                          # public-landing at http://127.0.0.1:3412/
+AUTH=1 STUB_PORT=3413 node modules/ui-design/kit/serve.js    # the same, signed in (/me answers { builder })
+SURFACE=hall-ui PREFIX=/builders/ node modules/ui-design/kit/serve.js
+CHILD=1 node modules/ui-design/kit/serve.js                  # the child-instance shape (apex-only regions stripped)
+LIVE=1 node modules/ui-design/kit/serve.js                   # public feeds proxied to the pack's public origin
+FAIL=featured,progress node modules/ui-design/kit/serve.js   # those feeds answer 500
+```
+
+The stub runs the page through the **instance's real transforms** — the apex-only strip, the brand-token stamp, the pack's theme injection, run by the core-side command `scripts/gds/ui-kit-transform.js` (a module may not require core, so the stub spawns the command and memoises the page) — then the content-hash `?v=` stamp, with the instance's own branding pack, and answers the public feeds from `kit/fixtures/`. It also serves `docs/` raw, so a mock under `docs/design/mocks/` renders with its relative links: `http://127.0.0.1:3412/docs/design/mocks/hub/v2.html`.
+
+`SURFACE` is a checkout directory (`public-landing`, `modules/hall-ui/public`) or a module key whose manifest declares a `webSurfaces` dir. `PREFIX` is the URL prefix the surface's pages and assets live under (the hall's is `/builders/`).
+
+## 2. Render — every state, every width, both modes, audited
+
+```
+node modules/ui-design/kit/render.js --page /projects
+node modules/ui-design/kit/render.js --page /                       # MSYS_NO_PATHCONV=1 in Git Bash, or the kit reads the mangled root back
+node modules/ui-design/kit/render.js --page /builders/ranks --surface hall-ui
+node modules/ui-design/kit/render.js --page /projects --only in-map,card --modes dark --sizes 390
+```
+
+`render.js` starts its own two stubs (signed out, signed in), renders each state of the page's **states file** in dark + light at 1440×900 / 390×844 / 320×700, drives the state's actions, and audits every render against the **platform floors**:
+
+| Floor | What fails it |
+|---|---|
+| `console-errors` | a `console.error` or an uncaught page error (the file's `ignoreConsole` regexes excepted) |
+| `failed-requests` | a 4xx/5xx response the file did not declare in `ignoreRequests` |
+| `horizontal-overflow` | `scrollWidth` wider than the viewport |
+| `one-header-main-h1` | not exactly one *rendered* `<header>`, `<main>` and `<h1>` |
+| `controls-24px` | a visible control under 24px on either side (`ignoreControls` for the skip link and the like) |
+| `top-bar-80px` | a `<header>` taller than 80px |
+| `reduced-motion` | under `prefers-reduced-motion` an animation still runs or a `requestAnimationFrame` loop ticks |
+
+Then a state's own `expect` (a band open, a dialog present, a field's value, a class, a query param). Shots and `report.json` land in `%TMP%/ui-design-kit/<surface>/<page>/` (or `--out`). Exit 0 is `ALL CLEAN`; 1 lists the problems; 2 is a broken states file, named line by line.
+
+### The states file — `<surface>/<page>.states.json`
+
+```json
+{
+  "page": "/projects",
+  "surface": "public-landing",
+  "modeQuery": "mode",
+  "ignoreRequests": ["/api/(gds|bongos)/me$", "/my-projects"],
+  "ignoreConsole": ["\\b401\\b"],
+  "ignoreControls": [".skip", ".vh"],
+  "states": {
+    "out-map": { "auth": false, "expect": { "expanded": false } },
+    "in-map-projects": { "auth": true, "actions": [["click", "#projTrig"], ["wait", 350]], "expect": { "expanded": true, "open": "#menuProjects" } },
+    "card": { "auth": true, "actions": [["dispatchClick", "#orbField a.worldOrb:not(#selfOrb)"], ["wait", 600]], "expect": { "dialog": true } }
+  },
+  "reducedMotion": { "auth": true, "actions": [["click", "#projTrig"], ["wait", 100]] }
+}
+```
+
+Actions: `click`, `focus`, `press`, `fill`, `wait`, `clickAt x y`, `clickIfVisible`, `dispatchClick`, `check`, `back`, `forward`. Expectations: `expanded`, `dialog`, `visible[]`, `hidden[]`, `open`, `closed`, `activeId`, `activeText`, `expandedIds[]`, `param{}`, `attr[[sel,name,value]]`, `text[[sel,value]]`, `href[[sel,value]]`, `count[[sel,n]]`, `value[[sel,v]]`, `hasClass[[sel,class,bool]]`, `checked`, `noOverflow`. The kit validates the file before it opens a browser and names every problem.
+
+The worked examples: `public-landing/projects.states.json` (the hub's thirteen), `public-landing/index.states.json` (the landing's four), `modules/hall-ui/public/ranks.states.json` (a second surface under its own prefix — it renders **red**, deliberately: the hall predates the 24px floor and Ranks has no `<h1>`, and the states file declares the shell's un-fixtured feeds rather than hiding the findings; idea 1000863 carries them).
+
+## 3. Probe — the interaction contract, as PASS/FAIL lines
+
+```
+node modules/ui-design/kit/probe.js --page /projects
+node modules/ui-design/kit/probe.js --page / --only "Escape"
+```
+
+A **probes file** (`<surface>/<page>.probes.json`) is a sequence: each probe opens the page (or continues the previous probe's page with `"continue": true`), drives steps from the same action vocabulary, and states what must be true with the same expectations. An uncaught page error during a probe fails it. The disclosure contract ships first — `public-landing/projects.probes.json` (24 probes: Enter opens on the first item, arrows cycle and skip hidden cells, Escape returns focus, Tab out closes, a click outside closes, one band closes the other, the views, the card yields Escape, the fold under 480, signed out nothing throws) and `index.probes.json` (10, the landing).
+
+## 4. Read the shots, fix in one batch, re-run once
+
+Open the shots directory. Look at the 390 and 320 renders first (the fold, the bar, the bands), then dark, then the states you touched. Fix everything you see in **one** batch — a render pass costs a minute, a change-render-change loop costs the afternoon — then re-run `render.js` and `probe.js` once. Ship the tests with the change: a new interactive behaviour gets a pin in the page's own test file in the same diff.
+
+## 5. Two more probes, for a mock and for colour
+
+```
+node modules/ui-design/kit/check-mock.js --file docs/design/mocks/hub/v2.html [--states out-map,card] [--keys THESIS,BAR]
+node modules/ui-design/kit/contrast.js --pack
+node modules/ui-design/kit/contrast.js --url http://127.0.0.1:3412/projects --glyphs "#projTrig,.foot a"
+```
+
+`check-mock.js` runs the mechanical rules over a self-contained mock before anyone looks at it: the **platform's** (no page-local `:root`, page tokens on `body`, every dark rule written twice byte-identical, no literal colour beyond black/white with alpha, no pack colour pinned, the `?state=` contract, a head comment after `<body>`, one header/main/h1 + a skip link, apex-only sentinels balanced, no `innerHTML`, no motion in JavaScript, transitions ≤ 400ms) and the **instance's taste bans**, read from its `DESIGN.md` "Don't" section (an em/en dash, emoji, gradient text, a coloured glow, a box shadow). The em dash ban is Cloud Bongos's, not the platform's: an instance whose `DESIGN.md` never mentions it is not held to it.
+
+`contrast.js --pack` measures the instance's own pack — every ink on every ground, light values — with no browser. `--url`/`--file` walks every visible text element in both modes and computes the real WCAG ratio against its *composited* background; `--glyphs` screenshots named elements and reads the glyph pixels against the local ground's median, for text over a moving or textured ground where the stylesheet cannot say what is under it.
+
+## When it goes wrong
+
+| Symptom | Cause | Do |
+|---|---|---|
+| `no states file beside the surface: …/Git.states.json` | Git Bash turned `--page /` into the MSYS root | the kit reads it back as `/`; or `MSYS_NO_PATHCONV=1 node …` |
+| `no system browser` (exit 3) | neither Edge nor Chrome is installed | install one; the kit never downloads a browser |
+| `failed-requests: 404 …/api/bongos/goals` on a hall page | the shell polls feeds the stub does not fixture | declare them in the states file's `ignoreRequests` (the hall's does) — or add a fixture under `kit/fixtures/` and the route in `serve.js` |
+| `controls-24px: button.trig "builder" 13x44` | the chip sized itself by a missing avatar | the fixture builder's avatar is served by the stub (`/__kit/avatar.svg`); a page that rejects non-http avatars gets it absolutised |
+| a probe times out on `click` | an earlier probe in the chain left the page in another state | fix the earlier FAIL first; chains are sequences |
+
+## What the kit is not
+
+Not CI: `tests/ui_design_kit.mjs` pins the contract (the floors, the file shapes, the audit, the mock rules, the pack, the exit codes, the stub) without a browser; the renders are yours to run and look at. Not a screenshot-diff tool: it audits against floors and expectations, not against a golden image. Not an instance's taste: everything <redacted> lives in the states/probes files beside Cloud Bongos's pages and in its `DESIGN.md`.

package/modules/hall-ui/public/ranks.states.json

@@ -0,0 +1,15 @@
+{
+  "_": "The hall's Ranks page as the SECOND surface through modules/ui-design/kit/render.js (task 1003320): the hall serves under /builders/, signed out and in.",
+  "page": "/builders/ranks",
+  "surface": "hall-ui",
+  "stub": { "prefix": "/builders/" },
+  "modeQuery": false,
+  "_feeds": "The hall's shell polls goals + inbox + profile feeds on every page; the stub fixtures only the public feeds, so those 404s are declared here, not hidden by the kit. The 24px-floor and h1 findings the render reports are REAL (the hall predates the floor) and are deliberately not ignored.",
+  "ignoreRequests": ["/api/(gds|bongos)/me$", "/api/(gds|bongos)/goals", "/api/(gds|bongos)/inbox/", "/api/(gds|bongos)/me/"],
+  "ignoreConsole": ["/api/(gds|bongos)/me", "\\b401\\b", "Unauthorized", "404 \\(Not Found\\)", "goals load failed"],
+  "states": {
+    "out": { "auth": false },
+    "in": { "auth": true }
+  },
+  "reducedMotion": { "auth": true }
+}

package/modules/ui-design/kit/README.md

@@ -1,3 +1,13 @@
-# `modules/ui-design/kit/` — reserved home for the look-before-you-ship kit
+# `modules/ui-design/kit/` — look before you ship
 
-Lands with [task 1003320](https://cloudbongos.com/builders#/task/1003320): an instance-agnostic stub server, a renderer/auditor (every state × width × mode, with the contrast audit), the interaction probes and the mock checker any builder points at any surface. Until it lands, the apex probes live in session scratchpads (see the [module CLAUDE.md](../CLAUDE.md)).
+The stub, the renderer/auditor, the interaction probes, the mock checker and the contrast probe any builder points at any surface of any instance ([task 1003320](https://cloudbongos.com/builders#/task/1003320), [ADR 0197](../../../docs/adr/<redacted>.md)). Plain Node; the browser is the system Edge or Chrome via `playwright-core` (a devDependency — nothing is downloaded).
+
+```
+node modules/ui-design/kit/serve.js                     # the stub (SURFACE, PREFIX, AUTH=1, CHILD=1, LIVE=…, FAIL=…, STUB_PORT)
+node modules/ui-design/kit/render.js --page /projects   # every state × 1440/390/320 × dark/light, audited against the floors
+node modules/ui-design/kit/probe.js  --page /projects   # the interaction contract as PASS/FAIL lines
+node modules/ui-design/kit/check-mock.js --file docs/design/mocks/hub/v2.html
+node modules/ui-design/kit/contrast.js --pack | --url <url> [--glyphs sel,sel]
+```
+
+A surface describes itself in two JSON files beside it — `<page>.states.json` and `<page>.probes.json` — in the vocabularies `lib.js` defines and validates. The full loop, the file shapes and the failure table: [`docs/recipes/ui-look-before-you-ship.md`](../../../docs/recipes/ui-look-before-you-ship.md). Exit codes everywhere: 0 clean · 1 problems · 2 a broken file or usage · 3 no browser.

package/modules/ui-design/kit/check-mock.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+'use strict';
+// check-mock.js — the mechanical rule set for a MOCK (a self-contained HTML page
+// under docs/design/mocks/) before anyone looks at it (task 1003320, ADR 0197).
+// Two kinds of rule, kept apart on purpose:
+//   • the PLATFORM's — token discipline (no page-local :root, page tokens on
+//     body, every dark rule written twice byte-identical, no literal colour
+//     beyond black/white with alpha, no pack colour pinned as a literal), the
+//     state contract (the mock reads ?state=), the head comment after <body>,
+//     one <header>/<main>/<h1> + a skip link, apex-only sentinels balanced, no
+//     innerHTML, no motion in JavaScript, state transitions ≤ 400ms;
+//   • the INSTANCE's taste bans — read from its DESIGN.md "Don't" section (an
+//     em/en dash in copy, emoji, gradient text, a coloured text glow, a box
+//     shadow). The em dash ban is Cloud Bongos's, not the platform's: an instance
+//     whose DESIGN.md never mentions it is not held to it.
+//
+//   node modules/ui-design/kit/check-mock.js --file <mock.html> [--states a,b] [--keys THESIS,BAR] [--design <DESIGN.md>] [--no-taste]
+//
+// Prints PASS/FAIL/WARN per rule; exit 1 on any FAIL, 2 on usage.
+const fs = require('node:fs');
+const path = require('node:path');
+const lib = require('./lib.js');
+
+// The taste bans an instance's DESIGN.md may switch on, by the words its "Don't"
+// section uses. Pure: text in, a Set of ban keys out.
+const TASTE_BANS = Object.freeze({
+  'em-dash': /em dash|en dash|em-dash|en-dash/i,
+  'emoji': /\bemoji\b/i,
+  'gradient-text': /gradient text/i,
+  'text-glow': /\bglow\b/i,
+  'box-shadow': /box[- ]shadow|\bshadow\b/i,
+});
+function readDesignBans(mdText) {
+  const bans = new Set();
+  const m = String(mdText || '').match(/^###\s*Don'?ts?\b[\s\S]*?(?=^##\s|^###\s|(?![\s\S]))/mi);
+  const section = m ? m[0] : '';
+  for (const [key, re] of Object.entries(TASTE_BANS)) if (re.test(section)) bans.add(key);
+  return bans;
+}
+
+function stripToText(html) {
+  return html.replace(/<!--[\s\S]*?-->/g, '').replace(/<script[\s\S]*?<\/script>/gi, '').replace(/<style[\s\S]*?<\/style>/gi, '').replace(/<[^>]+>/g, ' ');
+}
+// Top-level (or nested, when `selectorRe` names an @media) blocks of a stylesheet.
+function cssBlocks(css, selectorRe) {
+  const out = [];
+  let i = 0;
+  while (i < css.length) {
+    const open = css.indexOf('{', i);
+    if (open < 0) break;
+    const selStart = Math.max(css.lastIndexOf('}', open), css.lastIndexOf(';', open)) + 1;
+    const sel = css.slice(selStart, open).trim();
+    let depth = 1, j = open + 1;
+    while (j < css.length && depth > 0) { if (css[j] === '{') depth++; else if (css[j] === '}') depth--; j++; }
+    const inner = css.slice(open + 1, j - 1);
+    if (selectorRe.test(sel)) out.push({ sel, inner });
+    i = /^@(media|supports)/.test(sel) ? open + 1 : j;
+  }
+  return out;
+}
+const norm = (s) => s.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\s+/g, ' ').replace(/\s*([{}:;,])\s*/g, '$1').trim();
+const BLACK_OR_WHITE = /^(000|000000|fff|ffffff|0{8}|f{8}|000000[0-9a-f]{2}|ffffff[0-9a-f]{2})$/;
+
+// Pure: the rules over a mock's source. `packColors` = the instance's fifteen
+// (name → value) so a literal equal to a pack colour is caught; `bans` = the
+// instance's taste bans; `states`/`keys` = names the mock must carry.
+function checkMock(html, { bans = new Set(), packColors = {}, states = [], keys = [] } = {}) {
+  const raw = String(html).replace(/\r\n/g, '\n');
+  const results = [];
+  const ok = (rule, pass, detail) => results.push([pass ? 'PASS' : 'FAIL', rule, detail || '']);
+  const warn = (rule, detail) => results.push(['WARN', rule, detail || '']);
+  const text = stripToText(raw);
+  const styles = [...raw.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/gi)].map((m) => m[1]).join('\n');
+  const scripts = [...raw.matchAll(/<script[^>]*>([\s\S]*?)<\/script>/gi)].map((m) => m[1]).join('\n');
+  const css = styles.replace(/\/\*[\s\S]*?\*\//g, '').replace(/url\([^)]*\)/g, 'url()');
+
+  // ── token discipline (platform) ──
+  const rootBlocks = css.replace(/:root\[data-mode="dark"\]\s+body/g, 'X').replace(/:root:not\(\[data-mode="light"\]\)\s+body/g, 'X');
+  ok('no page-local :root block (the pack\'s :root is spliced at the end of <head>)', !/(^|[}\s;]):root\s*(\[[^\]]*\]\s*)?(:not\([^)]*\)\s*)?\{/m.test(rootBlocks.replace(/:root\[data-mode="dark"\]\s*\{/g, 'D{').replace(/:root:not\(\[data-mode="light"\]\)\s*\{/g, 'D{')));
+  const bodyBlocks = cssBlocks(styles, /^body$/);
+  ok('page tokens declared on body', bodyBlocks.some((b) => /--[\w-]+\s*:/.test(b.inner)), `${bodyBlocks.length} body block(s)`);
+  const darkAttr = cssBlocks(styles, /^:root\[data-mode="dark"\]/);
+  const darkMedia = cssBlocks(styles, /^@media[^{]*prefers-color-scheme:\s*dark/).map((b) => cssBlocks(b.inner, /^:root:not\(\[data-mode="light"\]\)/)).flat();
+  const a = darkAttr.map((b) => norm(b.sel.replace(/^:root\[data-mode="dark"\]/, '') + '{' + b.inner + '}')).sort();
+  const m = darkMedia.map((b) => norm(b.sel.replace(/^:root:not\(\[data-mode="light"\]\)/, '') + '{' + b.inner + '}')).sort();
+  if (!a.length && !m.length) warn('dark twins: the mock declares no dark rules at all', 'fine for a light-only fragment; a page needs both');
+  else ok('every dark rule written twice, byte-identical (attribute block == prefers-color-scheme twin)', a.length > 0 && JSON.stringify(a) === JSON.stringify(m), `${a.length} attribute block(s), ${m.length} media twin(s)`);
+  const hexes = [...css.matchAll(/#([0-9a-fA-F]{3,8})\b/g)].map((x) => x[1].toLowerCase()).filter((h) => !BLACK_OR_WHITE.test(h));
+  ok('no literal hex colour (the fifteen via var()/color-mix(); black or white with alpha only)', hexes.length === 0, hexes.length ? [...new Set(hexes)].slice(0, 12).join(',') : '');
+  const rgbLit = [...css.matchAll(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/g)].filter((x) => !((x[1] === '0' && x[2] === '0' && x[3] === '0') || (x[1] === '255' && x[2] === '255' && x[3] === '255')));
+  ok('rgb() literals only as black or white with alpha', rgbLit.length === 0, rgbLit.length ? `${rgbLit.length} found` : '');
+  const pinned = Object.entries(packColors).filter(([, v]) => typeof v === 'string' && /^#[0-9a-f]{6}$/i.test(v) && new RegExp(v.replace('#', '#'), 'i').test(css)).map(([k]) => k);
+  ok('no pack colour pinned as a literal (a var() of the contract token instead)', pinned.length === 0, pinned.join(','));
+
+  // ── the taste bans the instance declared ──
+  if (bans.has('em-dash')) { const n = (text.match(/[–—]/g) || []).length; ok('taste: no em/en dash in visible copy', n === 0, n ? `${n} found` : ''); }
+  if (bans.has('emoji')) { const n = (text.match(/[\u{1F300}-\u{1FAFF}\u{2600}-\u{27BF}\u{2B50}\u{FE0F}]/gu) || []).length; ok('taste: no emoji in visible copy', n === 0, n ? `${n} found` : ''); }
+  if (bans.has('gradient-text')) ok('taste: no gradient text', !/background-clip\s*:\s*text/i.test(css));
+  if (bans.has('text-glow')) { const glow = [...css.matchAll(/text-shadow\s*:\s*([^;]+);/g)].map((x) => x[1]).filter((v) => !/^(var\(|none)/.test(v.trim()) && /rgba?\((?!0,\s*0,\s*0)|#(?!000)/.test(v)); ok('taste: no coloured text glow', glow.length === 0, glow.join(' | ')); }
+  if (bans.has('box-shadow')) { const sh = [...css.matchAll(/box-shadow\s*:\s*([^;]+);/g)].map((x) => x[1].trim()).filter((v) => !/^(var\(|none|inset|0 0 0 \d+px var\()/.test(v) && !/^0 0 0 0/.test(v)); ok('taste: no box shadow (hairlines only; a 0-spread halo for focus is the exception)', sh.length === 0, sh.join(' | ')); }
+
+  // ── structure + the state contract (platform) ──
+  ok('one <header>', (raw.match(/<header\b/g) || []).length === 1);
+  ok('one <main>', (raw.match(/<main\b/g) || []).length === 1);
+  ok('one <h1>', (raw.match(/<h1\b/g) || []).length === 1);
+  ok('a skip link', /class="[^"]*\bskip\b[^"]*"/.test(raw));
+  ok('state contract: the mock reads ?state=', /(searchParams|location\.search)/.test(scripts) && /['"]state['"]/.test(scripts));
+  if (states.length) { const missing = states.filter((s) => !new RegExp(`['"\`]${s}['"\`]`).test(scripts) && !new RegExp(`data-state="${s}"`).test(raw)); ok('every state of the contract is named in the script or markup', missing.length === 0, missing.join(', ')); }
+  const headComment = (raw.match(/<body[^>]*>\s*<!--([\s\S]*?)-->/) || [])[1];
+  ok('a head comment right after <body> (what the mock claims, for the reviewer)', !!headComment && headComment.trim().length > 40);
+  if (keys.length && headComment) { const missing = keys.filter((k) => !headComment.includes(k)); ok('the head comment names every required section', missing.length === 0, missing.join(', ')); }
+  const sentStart = (raw.match(/<!--apex-only:start-->/g) || []).length, sentEnd = (raw.match(/<!--apex-only:end-->/g) || []).length;
+  ok('apex-only sentinels balanced', sentStart === sentEnd, `${sentStart} start / ${sentEnd} end`);
+  ok('apex-only sentinels never nested', !/<!--apex-only:start-->(?:(?!<!--apex-only:end-->)[\s\S])*<!--apex-only:start-->/.test(raw));
+  const menus = (raw.match(/<button[^>]*aria-expanded="(true|false)"[^>]*aria-controls="[^"]+"|<button[^>]*aria-controls="[^"]+"[^>]*aria-expanded="(true|false)"/g) || []).length;
+  if (/aria-expanded/.test(raw)) ok('menus use the disclosure pattern (button aria-expanded + aria-controls)', menus >= 1);
+
+  // ── motion hygiene (platform: the kill switch rule) ──
+  ok('no motion in JavaScript (no requestAnimationFrame, no .animate()', !/requestAnimationFrame|\.animate\(/.test(scripts));
+  ok('no innerHTML', !/innerHTML/.test(scripts));
+  const durs = [...css.matchAll(/transition\s*:[^;]*?(\d+)ms/g)].map((x) => +x[1]).filter((d) => d > 400);
+  ok('state transitions at most 400ms', durs.length === 0, durs.join(','));
+  return results;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const file = lib.argOf(args, '--file', null);
+  if (!file || lib.hasFlag(args, '--help')) { process.stderr.write('usage: node modules/ui-design/kit/check-mock.js --file <mock.html> [--states a,b] [--keys A,B] [--design <DESIGN.md>] [--no-taste]\n'); process.exit(lib.EXIT.USAGE); }
+  if (!fs.existsSync(file)) { process.stderr.write(`check-mock: not found: ${file}\n`); process.exit(lib.EXIT.USAGE); }
+  const designPath = lib.argOf(args, '--design', path.join(lib.REPO_ROOT, 'DESIGN.md'));
+  let bans = new Set();
+  if (!lib.hasFlag(args, '--no-taste')) {
+    if (fs.existsSync(designPath)) bans = readDesignBans(fs.readFileSync(designPath, 'utf8'));
+    else process.stdout.write(`WARN taste bans off: no DESIGN.md at ${designPath} (the platform rules still apply)\n`);
+  }
+  let packColors = {};
+  try { packColors = lib.packColors(lib.instancePack()); } catch { packColors = {}; }
+  const results = checkMock(fs.readFileSync(file, 'utf8'), { bans, packColors, states: lib.listArg(args, '--states', []), keys: lib.listArg(args, '--keys', []) });
+  for (const [s, rule, detail] of results) process.stdout.write(`${s.padEnd(4)} ${rule}${detail ? '  (' + detail + ')' : ''}\n`);
+  const fails = results.filter((r) => r[0] === 'FAIL').length;
+  process.stdout.write(`\n${fails ? `${fails} RULE(S) FAIL` : 'ALL RULES PASS'}  (taste bans: ${[...bans].join(', ') || 'none declared'})\n`);
+  process.exit(fails ? lib.EXIT.PROBLEMS : lib.EXIT.CLEAN);
+}
+
+if (require.main === module) main();
+module.exports = { checkMock, readDesignBans, TASTE_BANS, cssBlocks };