@bongos/core 1.19.395 → 1.19.397

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/my-projects.css

@@ -37,4 +37,26 @@
   background: var(--surface);
   color: var(--ink);
 }
+/* The application's optional note (task 1002330). Sits under the one-click join
+   row so the click stays the primary act and the note is plainly skippable. */
+.join-note-label {
+  display: block;
+  margin: 10px 0 4px;
+  color: var(--ink-soft);
+  font-size: 12px;
+}
+.join-note {
+  display: block;
+  width: 100%;
+  box-sizing: border-box;
+  font: inherit;
+  font-size: 13px;
+  line-height: 1.4;
+  padding: 6px 10px;
+  resize: vertical;
+  border: 1px solid var(--border-strong);
+  border-radius: var(--radius-sm);
+  background: var(--surface);
+  color: var(--ink);
+}
 .note { margin: 10px 0 0; color: var(--ink-soft); font-size: 13px; min-height: 1.2em; }

package/modules/hall-ui/public/my-projects.html

@@ -46,7 +46,13 @@
             <input id="join-origin" type="url" placeholder="https://project.cloudbongos.com" autocomplete="off">
             <button id="join-btn" type="button" class="btn-ghost">Request to join</button>
           </div>
-          <p id="join-note" class="note"></p>
+          <!-- An application is one click; the note is the applicant's own words,
+               and it is optional on purpose (task 1002330 — lightweight, never an
+               owner-defined form). It reaches the project owner's queue. -->
+          <label class="join-note-label" for="join-note">Add a note (optional)</label>
+          <textarea id="join-note" class="join-note" rows="2" maxlength="400"
+                    placeholder="Anything the project's owner should know — what you'd like to work on, who you are."></textarea>
+          <p id="join-status" class="note"></p>
         </section>
       </main>
 

package/modules/hall-ui/public/my-projects.js

@@ -1,6 +1,7 @@
 // my-projects.js — the signed-in builder's cross-project view (ADR 0141 §3, task
 // #1002112). Fetches /api/gds/my-projects (session cookie, same-origin) and renders
-// owned + building-on lists with self-service leave, plus a join-by-origin form.
+// owned + building-on lists with self-service leave, plus a join-by-origin form
+// whose application is one click plus an optional note (task 1002330).
 // All network values are rendered via textContent — never innerHTML.
 (function () {
   'use strict';
@@ -8,7 +9,8 @@
   var buildingEl = document.getElementById('building');
   var joinBtn = document.getElementById('join-btn');
   var joinInput = document.getElementById('join-origin');
-  var joinNote = document.getElementById('join-note');
+  var joinNoteInput = document.getElementById('join-note');   // the applicant's own words (optional)
+  var joinStatus = document.getElementById('join-status');    // what the project answered
 
   function el(tag, cls) { var e = document.createElement(tag); if (cls) e.className = cls; return e; }
 
@@ -119,27 +121,31 @@
 
   joinBtn.addEventListener('click', function () {
     var origin = (joinInput.value || '').trim();
-    if (!origin) { joinNote.textContent = 'Enter a project URL.'; return; }
+    if (!origin) { joinStatus.textContent = 'Enter a project URL.'; return; }
+    var note = (joinNoteInput.value || '').trim();
     joinBtn.disabled = true;
-    joinNote.textContent = 'Requesting…';
+    joinStatus.textContent = 'Requesting…';
     fetch('/api/gds/my-projects/join', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ origin: origin }),
+      /* note is omitted entirely when blank — an application with nothing written
+         is still an application (task 1002330). */
+      body: JSON.stringify(note ? { origin: origin, note: note } : { origin: origin }),
     })
       .then(function (r) { return r.json().then(function (b) { return { ok: r.ok, body: b }; }); })
       .then(function (res) {
         joinBtn.disabled = false;
         if (res.ok && res.body && res.body.message) {
-          joinNote.textContent = res.body.message;
-          /* a door refusal rides a 200 (task 1003044): keep the address, and don't repaint as if a request went out */
+          joinStatus.textContent = res.body.message;
+          /* a door refusal rides a 200 (task 1003044): keep the address AND the
+             note the applicant wrote, and don't repaint as if a request went out */
           var refused = res.body.status === 'invite_only' || res.body.status === 'open_enrollment' || res.body.status === 'members_only';
-          if (!refused) { joinInput.value = ''; load(); }
+          if (!refused) { joinInput.value = ''; joinNoteInput.value = ''; load(); }
         }
-        else if (res.body && res.body.error && res.body.error.code === 'unknown_project') { joinNote.textContent = 'That project isn’t on the platform.'; }
-        else { joinNote.textContent = 'Could not request access right now.'; }
+        else if (res.body && res.body.error && res.body.error.code === 'unknown_project') { joinStatus.textContent = 'That project isn’t on the platform.'; }
+        else { joinStatus.textContent = 'Could not request access right now.'; }
       })
-      .catch(function () { joinBtn.disabled = false; joinNote.textContent = 'Could not request access right now.'; });
+      .catch(function () { joinBtn.disabled = false; joinStatus.textContent = 'Could not request access right now.'; });
   });
 
   load();

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/platform-identity/routes/my-projects.js

@@ -2,7 +2,9 @@
 // project "My Projects" view + self-service join / leave (ADR 0141 §3, task #1002112).
 //
 //   GET  /my-projects              — projects this account builds on, owned grouped apart
-//   POST /my-projects/join         — request to join a project (executed by the project)
+//   POST /my-projects/join         — apply to a project: one click plus an optional
+//                                    note in the applicant's own words (task 1002330).
+//                                    Relayed; the project executes and decides.
 //   POST /my-projects/:clientId/leave — self-service offboard (reflected to the hub)
 //
 // All gated on a live HUB session (requireBuilder). Authority stays LOCAL: JOIN only
@@ -44,6 +46,40 @@ function joinRelayOutcome(status, body) {
   return { status: outcome, message: RELAY_SENTENCE[outcome] };
 }
 
+// The provenance line the project's owner reads when an application arrives
+// through the platform rather than off their own landing page. It is the HUB's
+// sentence, not the applicant's — see relayApplicationNote.
+const RELAY_PROVENANCE = 'via platform My Projects';
+
+// What an applicant may write, and what the project will store. The project's
+// public POST /access-requests caps `note` at 500 chars and `display_name` at
+// 100, and refuses anything longer with a 400 — which joinRelayOutcome cannot
+// read, so the hub would tell the applicant the project "could not be reached".
+// A lie about someone else's door because our own field was too long is the bug
+// these two caps exist to prevent: the hub asks for less than the project takes,
+// and clamps anyway.
+const APPLICANT_NOTE_MAX = 400;
+const APPLICANT_NAME_MAX = 100;
+
+// relayApplicationNote — the note that reaches the project's queue: the
+// applicant's own words plus where the request came from (task 1002330). An
+// application with nothing written is still an application, so an absent note
+// relays the provenance line alone — exactly what this route sent before the
+// applicant could write anything. Pure; clamped so the composed string always
+// fits the project's 500-char column.
+function relayApplicationNote(note) {
+  const written = String(note == null ? '' : note).trim().slice(0, APPLICANT_NOTE_MAX);
+  return written ? `${written} (${RELAY_PROVENANCE})` : RELAY_PROVENANCE;
+}
+
+// relayApplicantName — the applicant's display name as the project should show
+// it, or null when they have none (the queue then reads as the bare @login it
+// always did). Clamped to the project's column.
+function relayApplicantName(displayName) {
+  const name = String(displayName == null ? '' : displayName).trim().slice(0, APPLICANT_NAME_MAX);
+  return name || null;
+}
+
 module.exports = function myProjectsRoutes() {
   const router = express.Router();
 
@@ -75,7 +111,10 @@ module.exports = function myProjectsRoutes() {
   // stays local). SSRF guard: only relay to an origin that is a REGISTERED, active
   // client — never an arbitrary builder-supplied URL.
   router.post('/my-projects/join', requireBuilder, async (req, res) => {
-    if (validateOrRespond(req, res, { origin: { required: true, type: 'string', maxLength: 512 } })) return;
+    if (validateOrRespond(req, res, {
+      origin: { required: true, type: 'string', maxLength: 512 },
+      note: { type: 'string', maxLength: APPLICANT_NOTE_MAX },
+    })) return;
     try {
       const client = await pi.getClientByOrigin(req.body.origin, { pool });
       if (!client || client.status !== 'active' || !client.origin) {
@@ -89,7 +128,11 @@ module.exports = function myProjectsRoutes() {
         const r = await fetch(`${client.origin}/api/gds/access-requests`, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'User-Agent': userAgent() },
-          body: JSON.stringify({ github_login: req.builder.github_login, note: 'via platform My Projects' }),
+          body: JSON.stringify({
+            github_login: req.builder.github_login,
+            display_name: relayApplicantName(req.builder.display_name),
+            note: relayApplicationNote(req.body.note),
+          }),
         });
         const body = await r.json().catch(() => null);
         outcome = joinRelayOutcome(r.status, body);
@@ -164,3 +207,7 @@ module.exports = function myProjectsRoutes() {
   return router;
 };
 module.exports.joinRelayOutcome = joinRelayOutcome;
+module.exports.relayApplicationNote = relayApplicationNote;
+module.exports.relayApplicantName = relayApplicantName;
+module.exports.APPLICANT_NOTE_MAX = APPLICANT_NOTE_MAX;
+

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 };