@bongos/core 1.19.395 → 1.19.397

package/modules/ui-design/kit/render.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+'use strict';
+// render.js — render a page's states and audit every render against the platform
+// floors (task 1003320, ADR 0197). The states live in a JSON file BESIDE the
+// surface (<dir>/<page>.states.json: name → url + actions + expectations); each
+// is rendered in dark + light at 1440x900 / 390x844 / 320x700 through two stubs
+// this file starts itself (signed out, signed in), then a reduced-motion pass per
+// mode. Writes the shots + a JSON report; exits non-zero on any problem.
+//
+//   node modules/ui-design/kit/render.js --page /projects              (public-landing/projects.states.json)
+//   node modules/ui-design/kit/render.js --page /builders/ranks --surface hall-ui
+//   node modules/ui-design/kit/render.js --states <file>               (explicit file)
+//     --modes dark,light  --sizes 1440,390,320  --only a,b  --out <dir>
+//     --base-out <url> --base-in <url>   use running stubs instead of starting two
+//
+// Exit 0 ALL CLEAN · 1 problems · 2 usage/contract · 3 no browser.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const lib = require('./lib.js');
+
+function usage(msg) {
+  process.stderr.write(`render: ${msg}\n  node modules/ui-design/kit/render.js --page /projects [--surface <dir|key>] [--states <file>] [--modes dark,light] [--sizes 1440,390,320] [--only a,b] [--out <dir>] [--base-out <url> --base-in <url>]\n`);
+  process.exit(lib.EXIT.USAGE);
+}
+
+// Resolve the states file + surface from the argv (pure over the filesystem; the
+// test drives the failure paths through the CLI's exit code).
+function locate(args) {
+  const explicit = lib.argOf(args, '--states', null);
+  let file = explicit && path.resolve(explicit);
+  let json;
+  if (file) {
+    if (!fs.existsSync(file)) usage(`states file not found: ${file}`);
+    try { json = lib.readJson(file); } catch (e) { usage(`states file is not JSON: ${e.message}`); }
+  } else {
+    const page = lib.normalizePageArg(lib.argOf(args, '--page', null));
+    if (!page) usage('--page </path> or --states <file> is required');
+    const surfaceKey = lib.argOf(args, '--surface', 'public-landing');
+    const dir = lib.resolveSurfaceDir(surfaceKey);
+    if (!dir) usage(`--surface "${surfaceKey}" is neither a checkout dir nor a module key with a webSurfaces dir`);
+    file = lib.sidecarPath(dir, page, 'states');
+    if (!fs.existsSync(file)) usage(`no states file beside the surface: ${file} — write one (see docs/recipes/ui-look-before-you-ship.md)`);
+    try { json = lib.readJson(file); } catch (e) { usage(`states file is not JSON: ${e.message}`); }
+  }
+  const v = lib.validateStatesFile(json);
+  if (!v.ok) usage(`${path.relative(lib.REPO_ROOT, file)} breaks the states contract:\n  - ${v.errors.join('\n  - ')}`);
+  const surface = json.surface || lib.argOf(args, '--surface', null) || path.relative(lib.REPO_ROOT, path.dirname(file)).split(path.sep).join('/');
+  return { file, json, surface };
+}
+
+// Runs IN THE PAGE after the reduced-motion context loads + acts: what still moves?
+async function reducedMotionFacts(page) {
+  return page.evaluate(async () => {
+    const running = document.getAnimations().filter((a) => a.playState === 'running').map((a) => a.animationName || a.constructor.name);
+    const orig = window.requestAnimationFrame; let frames = 0;
+    window.requestAnimationFrame = function (cb) { frames += 1; return orig.call(window, cb); };
+    await new Promise((r) => setTimeout(r, 800));
+    window.requestAnimationFrame = orig;
+    return { running, frames };
+  });
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (lib.hasFlag(args, '--help')) usage('');
+  const { file, json, surface } = locate(args);
+  const modes = lib.listArg(args, '--modes', [...lib.MODES]).filter((m) => lib.MODES.includes(m));
+  const sizes = lib.listArg(args, '--sizes', Object.keys(lib.SIZES)).map(Number).filter((w) => lib.SIZES[w]);
+  const only = lib.listArg(args, '--only', null);
+  const names = Object.keys(json.states).filter((n) => !only || only.includes(n));
+  if (!names.length) usage(`--only names no state of ${path.basename(file)}`);
+  const out = path.resolve(lib.argOf(args, '--out', path.join(os.tmpdir(), 'ui-design-kit', surface.replace(/[\\/]/g, '_'), lib.pageName(json.page))));
+  fs.mkdirSync(out, { recursive: true });
+
+  const stubs = [];
+  let baseOut = lib.argOf(args, '--base-out', null), baseIn = lib.argOf(args, '--base-in', null);
+  const stubOpts = { surface, prefix: json.stub && json.stub.prefix, child: json.stub && json.stub.child };
+  if (!baseOut) { const s = await lib.startStub({ ...stubOpts, auth: false }); stubs.push(s); baseOut = s.base; }
+  if (!baseIn) { const s = await lib.startStub({ ...stubOpts, auth: true }); stubs.push(s); baseIn = s.base; }
+  const stop = () => stubs.forEach((s) => s.stop());
+
+  let browser;
+  try { browser = await lib.launchBrowser(); }
+  catch (e) { stop(); process.stderr.write(`render: ${e.message}\n`); process.exit(e instanceof lib.NoBrowserError ? lib.EXIT.NO_BROWSER : lib.EXIT.USAGE); }
+
+  const report = { page: json.page, surface, out, renders: {}, reducedMotion: {} };
+  const problems = [];
+  const collectorOpts = { ignoreRequests: json.ignoreRequests, ignoreConsole: json.ignoreConsole };
+  try {
+    for (const mode of modes) for (const w of sizes) for (const name of names) {
+      const st = json.states[name];
+      const [W, H] = lib.SIZES[w];
+      const ctx = await browser.newContext({ viewport: { width: W, height: H }, deviceScaleFactor: 1, colorScheme: mode });
+      const page = await ctx.newPage();
+      const logs = lib.attachCollectors(page, collectorOpts);
+      const base = st.auth ? baseIn : baseOut;
+      await page.goto(base + lib.withMode(st.url || json.page, mode, json.modeQuery), { waitUntil: 'load' });
+      await page.evaluate(() => document.fonts.ready);
+      await page.waitForTimeout(lib.SETTLE_MS);
+      let actionFailed = null;
+      try { await lib.runActions(page, st.actions); } catch (e) { actionFailed = String(e.message).split('\n')[0]; logs.push('action failed: ' + actionFailed); }
+      const facts = await page.evaluate(lib.factsInPage, { expect: st.expect, ignoreControls: json.ignoreControls });
+      const found = [...logs, ...lib.auditFloors(facts, { width: W, mode }), ...lib.expectProblems(facts, st.expect)];
+      const key = `${mode}-${w}-${name}`;
+      await page.screenshot({ path: path.join(out, key + '.png') });
+      report.renders[key] = { facts, problems: found };
+      process.stdout.write(`${mode} ${w} ${name}: ${found.length ? 'PROBLEMS' : 'clean'}  bar ${facts.bar ? facts.bar.h : '-'} expanded [${facts.expanded.join('|')}] anims ${facts.running} focus ${facts.activeId || facts.activeText || '-'}\n`);
+      for (const f of found) { process.stdout.write(`   ${f}\n`); problems.push(`${key}: ${f}`); }
+      await ctx.close();
+    }
+    // reduced motion: the kill switch, exercised with the file's own interaction
+    const rm = json.reducedMotion || {};
+    for (const mode of modes) {
+      const ctx = await browser.newContext({ viewport: { width: 1440, height: 900 }, colorScheme: mode, reducedMotion: 'reduce' });
+      const page = await ctx.newPage();
+      await page.goto((rm.auth === false ? baseOut : baseIn) + lib.withMode(rm.url || json.page, mode, json.modeQuery), { waitUntil: 'load' });
+      await page.waitForTimeout(lib.SETTLE_MS);
+      try { await lib.runActions(page, rm.actions); } catch (e) { problems.push(`${mode} reduced-motion: action failed: ${String(e.message).split('\n')[0]}`); }
+      const facts = await reducedMotionFacts(page);
+      const found = lib.reducedMotionProblems(facts);
+      report.reducedMotion[mode] = { ...facts, problems: found };
+      process.stdout.write(`${mode} reduced-motion: ${found.length ? 'ALIVE' : 'dead'}  running ${facts.running.length} rAF ${facts.frames}\n`);
+      for (const f of found) { process.stdout.write(`   ${f}\n`); problems.push(`${mode}: ${f}`); }
+      await ctx.close();
+    }
+  } finally {
+    await browser.close();
+    stop();
+  }
+  report.problems = problems;
+  fs.writeFileSync(path.join(out, 'report.json'), JSON.stringify(report, null, 1));
+  process.stdout.write(`\nshots + report.json → ${out}\n${problems.length ? `${problems.length} PROBLEM(S)` : 'ALL CLEAN'}\n`);
+  process.exit(problems.length ? lib.EXIT.PROBLEMS : lib.EXIT.CLEAN);
+}
+
+main().catch((e) => { process.stderr.write(`render: ${e.stack || e.message}\n`); process.exit(lib.EXIT.USAGE); });

package/modules/ui-design/kit/serve.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+'use strict';
+// serve.js — the look-before-you-ship stub (task 1003320, ADR 0197): serves ANY
+// surface directory of the checkout through the instance's REAL serving
+// transforms — the apex-only strip, the brand-token stamp and the pack's theme
+// injection, run by scripts/gds/ui-kit-transform.js (a core-side command: a
+// module may not require core and the doorway may not import the serving domain,
+// so the real code path is reached as a child process) — plus the content-hash
+// ?v= stamp, with the instance's own branding pack. Answers the public feeds from
+// fixtures/ so a page boots with real-shaped data and no database. Serves docs/
+// raw so a mock under docs/design/mocks/ renders with its relative links.
+//
+//   node modules/ui-design/kit/serve.js                  -> http://127.0.0.1:3412/  (public-landing)
+//   SURFACE=<dir or module key>   a checkout dir ("public-landing", "modules/hall-ui/public") or a
+//                                 module key whose manifest declares a webSurfaces dir
+//   PREFIX=/builders/             the URL prefix the surface's pages + assets are served under
+//   STUB_REPO=<checkout>          the checkout to serve (default: the one this file sits in)
+//   STUB_PORT=<n>                 default 3412 (0 = any free port; the port is printed)
+//   AUTH=1                        /api/<ns>/me answers the fixture builder — { builder }, the real
+//                                 route's shape; my-projects + provisioning answer too
+//   CHILD=1                       the child-instance shape: apex-only regions stripped
+//   LIVE=1 | LIVE=<origin>        proxy the public feeds to the pack's public origin (or the named one)
+//   FAIL=<feed,feed>              those feeds answer 500 (the names in FEEDS below)
+//
+// Exit 2 on a surface that does not resolve. Prints ONE line when listening
+// ("stub on http://…") — render.js and probe.js wait for it.
+const http = require('node:http');
+const https = require('node:https');
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { spawnSync } = require('node:child_process');
+const lib = require('./lib.js');
+
+const ROOT = process.env.STUB_REPO ? path.resolve(process.env.STUB_REPO) : lib.REPO_ROOT;
+const SURFACE = process.env.SURFACE || 'public-landing';
+const PREFIX = process.env.PREFIX || '/';
+const PORT = process.env.STUB_PORT === undefined ? 3412 : Number(process.env.STUB_PORT);
+const AUTH = process.env.AUTH === '1';
+const CHILD = process.env.CHILD === '1';
+const LIVE = process.env.LIVE || '';
+const FAIL = new Set(String(process.env.FAIL || '').split(',').map((s) => s.trim()).filter(Boolean));
+const FIXTURES = path.join(__dirname, 'fixtures');
+const DOCS = path.join(ROOT, 'docs');
+const TRANSFORM = path.join(ROOT, 'scripts', 'gds', 'ui-kit-transform.js');
+
+const DIR = lib.resolveSurfaceDir(SURFACE, ROOT);
+if (!DIR) { process.stderr.write(`serve: SURFACE "${SURFACE}" is neither a directory of ${ROOT} nor a module key with a webSurfaces dir\n`); process.exit(lib.EXIT.USAGE); }
+if (!PREFIX.startsWith('/') || !PREFIX.endsWith('/')) { process.stderr.write('serve: PREFIX must start and end with "/"\n'); process.exit(lib.EXIT.USAGE); }
+if (!fs.existsSync(TRANSFORM)) { process.stderr.write(`serve: the transform command is missing: ${TRANSFORM}\n`); process.exit(lib.EXIT.USAGE); }
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8', '.css': 'text/css; charset=utf-8', '.js': 'application/javascript', '.mjs': 'application/javascript',
+  '.json': 'application/json', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp',
+  '.gif': 'image/gif', '.svg': 'image/svg+xml', '.ico': 'image/x-icon', '.woff': 'font/woff', '.woff2': 'font/woff2',
+  '.txt': 'text/plain; charset=utf-8', '.md': 'text/markdown; charset=utf-8', '.mmd': 'text/plain; charset=utf-8',
+};
+
+// The real transforms, as the instance runs them (see ui-kit-transform.js).
+function transform(file) {
+  const r = spawnSync(process.execPath, [TRANSFORM, path.join(DIR, file), ...(CHILD ? ['--child'] : []), '--json'], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  if (r.status !== 0) throw new Error(`ui-kit-transform exited ${r.status}: ${(r.stderr || r.stdout || '').trim().slice(0, 600)}`);
+  return JSON.parse(r.stdout);
+}
+let liveOrigin = LIVE;
+// The content-hash ?v= stamp, by RESOLUTION (a URL is an asset if it names a file
+// under the surface dir) — the shape platform-server.js and asset-version.js stamp
+// with; the stub knows the dir + prefix, so it stamps here, LAST (their order).
+const LOCAL_ASSET = /(href|src)="(\/[A-Za-z0-9._~/-]+\.[A-Za-z0-9]+)"/g;
+function stampAssets(html) {
+  return String(html).replace(LOCAL_ASSET, (m, attr, url) => {
+    const rel = url.startsWith(PREFIX) ? url.slice(PREFIX.length) : url.replace(/^\//, '');
+    const abs = path.resolve(DIR, rel);
+    if (!abs.startsWith(DIR + path.sep)) return m;
+    try { return `${attr}="${url}?v=${crypto.createHash('sha256').update(fs.readFileSync(abs)).digest('hex').slice(0, 8)}"`; }
+    catch { return m; }
+  });
+}
+const pages = new Map();
+function page(file) {
+  if (!pages.has(file)) {
+    const t = transform(file);
+    if (LIVE === '1' && !liveOrigin.startsWith('http')) liveOrigin = t.publicOrigin || '';
+    pages.set(file, { html: stampAssets(t.html), brand: t.brand });
+  }
+  return pages.get(file);
+}
+
+// The feeds a surface may read on boot → the fixture that answers. Both API
+// namespaces the instance mounts resolve to the same fixture.
+const FEEDS = {
+  '/public/progress': 'progress',
+  '/public/cost-summary': 'cost-summary',
+  '/public/recent-shipped': 'recent-shipped',
+  '/public/leaderboard': 'leaderboard',
+  '/projects/featured': 'featured',
+};
+const AUTHED = { '/my-projects': 'my-projects' };
+const UNAUTH = { error: { code: 'unauthenticated', message: 'unauthenticated' } };
+
+function json(res, status, body) { res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store' }); res.end(JSON.stringify(body)); }
+function fixture(name, res) {
+  if (FAIL.has(name)) return json(res, 500, { error: { code: 'stub_failure', message: `FAIL=${name}` } });
+  const file = path.join(FIXTURES, name + '.json');
+  if (!fs.existsSync(file)) return json(res, 404, { error: { code: 'no_fixture', message: name } });
+  res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+  res.end(fs.readFileSync(file));
+}
+function proxy(req, res) {
+  const origin = (liveOrigin === '1' ? '' : liveOrigin).replace(/\/$/, '');
+  if (!origin) return json(res, 502, { error: { code: 'no_live_origin', message: 'LIVE=1 needs a pack with domains.publicOrigin; or LIVE=<origin>' } });
+  const target = origin + req.url;
+  (target.startsWith('https:') ? https : http).get(target, { headers: { accept: 'application/json' } }, (up) => {
+    res.writeHead(up.statusCode, { 'content-type': up.headers['content-type'] || 'application/json' });
+    up.pipe(res);
+  }).on('error', (e) => json(res, 502, { error: { code: 'proxy_failed', message: e.message } }));
+}
+function sendFile(abs, res) {
+  res.writeHead(200, { 'content-type': MIME[path.extname(abs).toLowerCase()] || 'application/octet-stream', 'cache-control': 'no-store' });
+  fs.createReadStream(abs).pipe(res);
+}
+function fileUnder(base, rel) {
+  const abs = path.resolve(base, '.' + '/' + rel.replace(/^\/+/, ''));
+  return abs.startsWith(base + path.sep) && fs.existsSync(abs) && fs.statSync(abs).isFile() ? abs : null;
+}
+// The fixture builder's avatar is served by this stub (a page accepts only an
+// http(s) avatar and sizes its chip by the image), so a root-relative avatar_url
+// is absolutised to this origin per request.
+const AVATAR_SVG = '<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64"><circle cx="32" cy="32" r="32" fill="#888"/><circle cx="32" cy="26" r="11" fill="#ddd"/><path d="M12 56c3-12 11-17 20-17s17 5 20 17" fill="#ddd"/></svg>';
+function me(origin) {
+  const m = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'me.json'), 'utf8'));
+  if (m.builder && typeof m.builder.avatar_url === 'string' && m.builder.avatar_url.startsWith('/')) m.builder.avatar_url = origin + m.builder.avatar_url;
+  return m;
+}
+
+const server = http.createServer((req, res) => {
+  const u = new URL(req.url, 'http://x');
+  const p = u.pathname;
+  const origin = `http://127.0.0.1:${server.address().port}`;
+  if (p === '/__kit/avatar.svg') { res.writeHead(200, { 'content-type': MIME['.svg'], 'cache-control': 'no-store' }); return res.end(AVATAR_SVG); }
+  // ── the API: /api/gds/* and /api/bongos/* are one surface on the instance ──
+  const apiMatch = p.match(/^\/api\/(gds|bongos)(\/.*)$/);
+  if (apiMatch) {
+    const rest = apiMatch[2];
+    if (FEEDS[rest]) return LIVE ? proxy(req, res) : fixture(FEEDS[rest], res);
+    if (rest === '/me') return AUTH ? json(res, 200, me(origin)) : json(res, 401, UNAUTH);
+    if (AUTHED[rest]) return AUTH ? fixture(AUTHED[rest], res) : json(res, 401, UNAUTH);
+    if (rest === '/provisioning/instances') return AUTH ? json(res, 200, { instances: [] }) : json(res, 401, UNAUTH);
+    if (rest === '/auth/logout') return json(res, 200, { ok: true });
+    if (rest.startsWith('/auth/web/start')) { res.writeHead(302, { location: PREFIX }); return res.end(); }
+    if (rest === '/instance') { const b = pages.size ? pages.values().next().value.brand : {}; return json(res, 200, { brand: { productName: (b && b.productName) || '', project: {} }, modules: {} }); }
+    return json(res, 404, { error: { code: 'not_found', message: p } });
+  }
+  // the generated client every internal page loads (the real bundle when present)
+  if (/\/lib\/bongos-client\.js$/.test(p)) {
+    const bundle = fileUnder(ROOT, 'clients/bongos-client/bongos-client.global.js');
+    res.writeHead(200, { 'content-type': MIME['.js'], 'cache-control': 'no-store' });
+    return res.end(bundle ? fs.readFileSync(bundle, 'utf8') : '/* stub: no client bundle in this checkout */');
+  }
+  // docs/ raw (a mock's relative links resolve) and the surface dir by its checkout path
+  if (p.startsWith('/docs/')) { const abs = fileUnder(DOCS, p.slice('/docs/'.length)); if (abs) return sendFile(abs, res); }
+  const relSurface = path.relative(ROOT, DIR).split(path.sep).join('/');
+  if (p.startsWith('/' + relSurface + '/')) { const abs = fileUnder(DIR, p.slice(relSurface.length + 2)); if (abs) return sendFile(abs, res); }
+  // ── the surface: pages by name under PREFIX (and at the root), assets by path ──
+  const under = p.startsWith(PREFIX) ? p.slice(PREFIX.length) : (PREFIX !== '/' && (p === PREFIX.slice(0, -1)) ? '' : p.replace(/^\//, ''));
+  const asset = fileUnder(DIR, under);
+  if (asset && !asset.endsWith('.html')) return sendFile(asset, res);
+  const name = under === '' ? 'index' : under.replace(/\/$/, '').replace(/\.html$/, '');
+  if (!name.includes('/') && fs.existsSync(path.join(DIR, name + '.html'))) {
+    try { res.writeHead(200, { 'content-type': MIME['.html'], 'cache-control': 'no-store' }); return res.end(page(name + '.html').html); }
+    catch (e) { res.writeHead(500, { 'content-type': 'text/plain' }); return res.end('render failed: ' + e.stack); }
+  }
+  res.writeHead(404, { 'content-type': 'text/plain' }); res.end('404 ' + p);
+});
+server.listen(PORT, '127.0.0.1', () => {
+  const port = server.address().port;
+  process.stdout.write(`stub on http://127.0.0.1:${port}${PREFIX}  surface=${path.relative(ROOT, DIR) || '.'} auth=${AUTH} child=${CHILD} live=${LIVE || '-'} fail=${[...FAIL].join(',') || '-'}\n`);
+});

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.395",
+  "version": "1.19.397",
   "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/public-landing/index.probes.json

@@ -0,0 +1,37 @@
+{
+  "_": "The landing's interaction contract for modules/ui-design/kit/probe.js (task 1003320): the same disclosure component as the hub, on the front page.",
+  "page": "/",
+  "surface": "public-landing",
+  "probes": [
+    { "name": "landing: Enter opens Projects on the first item", "auth": true, "width": 1440,
+      "steps": [["focus", "#projTrig"], ["press", "Enter"], ["wait", 150]],
+      "expect": { "open": "#menuProjects", "activeText": "Sky" } },
+    { "name": "landing: arrows walk the visible items (Your projects shows signed in)", "continue": true,
+      "steps": [["press", "ArrowDown"], ["press", "ArrowDown"]],
+      "expect": { "activeText": "Your projects" } },
+    { "name": "landing: Escape closes and returns focus", "continue": true,
+      "steps": [["press", "Escape"], ["wait", 100]],
+      "expect": { "closed": "#menuProjects", "activeId": "projTrig" } },
+    { "name": "landing: the profile band closes the Projects band", "continue": true,
+      "steps": [["click", "#projTrig"], ["wait", 120], ["click", "#who .trig"], ["wait", 120]],
+      "expect": { "open": "#menuProfile", "closed": "#menuProjects" } },
+    { "name": "landing: the profile band names the person; sign out keeps the honest href", "continue": true,
+      "steps": [],
+      "expect": { "href": [["#menuProfile a.signout", "/api/bongos/auth/logout"]], "text": [["#bandWho", "builder"]], "count": [["#bandWho img", 1]] } },
+    { "name": "landing: a click outside closes", "continue": true,
+      "steps": [["clickAt", 700, 700], ["wait", 120]],
+      "expect": { "closed": "#menuProfile", "expanded": false } },
+    { "name": "landing: the band deep-links the hub views + About + Docs", "continue": true,
+      "steps": [["click", "#projTrig"], ["wait", 120]],
+      "expect": { "count": [["#menuProjects a", 6]], "href": [["#menuProjects .bandCell:nth-child(1) a", "/projects?view=map"], ["#menuProjects .bandCell:nth-child(2) a", "/projects?view=map&sub=table"], ["#menuProjects a[href=\"#about\"]", "#about"], ["#menuProjects a[href=\"/docs\"]", "/docs"]] } },
+    { "name": "landing: #about exists", "continue": true,
+      "steps": [["press", "Escape"]],
+      "expect": { "count": [["#about", 1]] } },
+    { "name": "landing signed out: the door, no chip, no Your-projects cell", "auth": false, "width": 1440,
+      "steps": [],
+      "expect": { "visible": ["#who a.signin"], "count": [["#who .trig", 0]], "hidden": ["#mineCell"] } },
+    { "name": "landing signed out: nothing throws", "continue": true,
+      "steps": [["click", "#projTrig"], ["wait", 100], ["press", "Escape"], ["wait", 100]],
+      "expect": { "closed": "#menuProjects" } }
+  ]
+}

package/public-landing/index.states.json

@@ -0,0 +1,16 @@
+{
+  "_": "The landing's states for modules/ui-design/kit/render.js (task 1003320): the bar and its two bands, signed out and in.",
+  "page": "/",
+  "surface": "public-landing",
+  "modeQuery": "mode",
+  "ignoreRequests": ["/api/(gds|bongos)/me$", "/my-projects", "/provisioning/"],
+  "ignoreConsole": ["/api/(gds|bongos)/me", "\\b401\\b", "Unauthorized"],
+  "ignoreControls": [".skip", ".vh"],
+  "states": {
+    "out": { "auth": false, "expect": { "expanded": false, "visible": ["#who a.signin"], "hidden": ["#mineCell"] } },
+    "in": { "auth": true, "expect": { "expanded": false, "visible": ["#who .trig"] } },
+    "out-projects": { "auth": false, "actions": [["click", "#projTrig"], ["wait", 350]], "expect": { "expanded": true, "open": "#menuProjects", "count": [["#menuProjects [aria-current]", 0]] } },
+    "in-profile": { "auth": true, "actions": [["click", "#who .trig"], ["wait", 350]], "expect": { "expanded": true, "open": "#menuProfile" } }
+  },
+  "reducedMotion": { "auth": true, "actions": [["click", "#projTrig"], ["wait", 100]] }
+}

package/public-landing/projects.probes.json

@@ -0,0 +1,79 @@
+{
+  "_": "The hub's interaction contract for modules/ui-design/kit/probe.js (task 1003320): the disclosure bands, the views, the card, the fold under 480, signed out. A probe with `continue` keeps the previous page — the contract is a sequence.",
+  "page": "/projects",
+  "surface": "public-landing",
+  "probes": [
+    { "name": "Enter opens Projects and lands on the first item", "auth": true, "width": 1440,
+      "steps": [["focus", "#projTrig"], ["press", "Enter"], ["wait", 150]],
+      "expect": { "open": "#menuProjects", "activeText": "Sky" } },
+    { "name": "ArrowDown walks to Table", "continue": true,
+      "steps": [["press", "ArrowDown"]],
+      "expect": { "activeText": "Table" } },
+    { "name": "ArrowUp wraps to the last item (Docs, the About/Docs row)", "continue": true,
+      "steps": [["press", "ArrowUp"], ["press", "ArrowUp"]],
+      "expect": { "activeText": "Docs" } },
+    { "name": "Escape closes and returns focus to the trigger", "continue": true,
+      "steps": [["press", "Escape"], ["wait", 100]],
+      "expect": { "closed": "#menuProjects", "activeId": "projTrig", "expanded": false } },
+    { "name": "opening the profile band closes the Projects band", "continue": true,
+      "steps": [["click", "#projTrig"], ["wait", 120], ["click", "#who"], ["wait", 120]],
+      "expect": { "open": "#menuProfile", "closed": "#menuProjects", "expandedIds": ["who"] } },
+    { "name": "a click outside closes", "continue": true,
+      "steps": [["clickAt", 700, 600], ["wait", 120]],
+      "expect": { "closed": "#menuProfile", "expanded": false } },
+    { "name": "Tab out of the band closes it", "continue": true,
+      "steps": [["click", "#projTrig"], ["wait", 120], ["focus", "#menuProjects a[href=\"/docs\"]"], ["press", "Tab"], ["wait", 120]],
+      "expect": { "closed": "#menuProjects" } },
+    { "name": "Table from the band: the table on stage, Table current, band closed", "continue": true,
+      "steps": [["click", "#projTrig"], ["wait", 120], ["click", "a[data-sub=\"table\"]"], ["wait", 300]],
+      "expect": { "visible": ["#sub-table-body"], "closed": "#menuProjects", "text": [["[aria-current=\"page\"]", "Table"]] } },
+    { "name": "Sky from the band: the sky back on stage, Sky current", "continue": true,
+      "steps": [["click", "#projTrig"], ["wait", 120], ["click", "a[data-sub=\"sky\"]"], ["wait", 300]],
+      "expect": { "hidden": ["#sub-table-body"], "text": [["[aria-current=\"page\"]", "Sky"]] } },
+    { "name": "Your projects: the search hides, the URL says mine", "continue": true,
+      "steps": [["fill", "#mapQ", "demo"], ["wait", 200], ["click", "#projTrig"], ["wait", 120], ["click", "a[data-nav=\"mine\"]"], ["wait", 300]],
+      "expect": { "hidden": ["#qWrap", "#qToggle"], "param": { "view": "mine" } } },
+    { "name": "Back to the map restores the typed filter", "continue": true,
+      "steps": [["back"], ["wait", 400]],
+      "expect": { "visible": ["#qWrap"], "value": [["#mapQ", "demo"]] } },
+    { "name": "the profile band names the person and keeps the honest sign-out href", "continue": true,
+      "steps": [["fill", "#mapQ", ""], ["wait", 200], ["click", "#who"], ["wait", 120]],
+      "expect": { "href": [["#menuProfile a.signout", "/api/bongos/auth/logout"]], "text": [["#bandWho", "builder"]], "count": [["#bandWho img", 1]] } },
+    { "name": "My projects (profile band) switches the view and closes the band", "continue": true,
+      "steps": [["click", "#menuProfile a[data-nav-to=\"mine\"]"], ["wait", 300]],
+      "expect": { "param": { "view": "mine" }, "closed": "#menuProfile", "text": [["[aria-current=\"page\"]", "Your projects"]] } },
+    { "name": "an orb opens the card", "continue": true,
+      "steps": [["back"], ["wait", 400], ["dispatchClick", "#orbField a.worldOrb:not(#selfOrb)"], ["wait", 400]],
+      "expect": { "dialog": true } },
+    { "name": "Escape closes the card when no band is open", "continue": true,
+      "steps": [["press", "Escape"], ["wait", 150]],
+      "expect": { "dialog": false } },
+    { "name": "a solo Shift tap focuses the search on the map", "continue": true,
+      "steps": [["clickAt", 700, 600], ["press", "Shift"], ["wait", 100]],
+      "expect": { "activeId": "mapQ" } },
+    { "name": "the mode toggle: the label says what the press does, and the press does it", "continue": true,
+      "steps": [["clickAt", 700, 600], ["click", "#modeToggle"], ["wait", 100]],
+      "expect": { "attr": [["#modeToggle", "aria-label", "Switch to light mode"], ["html", "data-mode", "dark"]] } },
+    { "name": "signed out: no chip, the door shows, no switch, the search stays", "auth": false, "width": 1440,
+      "steps": [],
+      "expect": { "hidden": ["#who", ".switch"], "visible": ["#signinTop", "#qWrap"] } },
+    { "name": "signed out the Projects band is Sky / Table / New project + About / Docs (no Your projects)", "continue": true,
+      "steps": [["click", "#projTrig"], ["wait", 120]],
+      "expect": { "count": [["#menuProjects .bandCell:not([hidden])", 5]], "hidden": ["#menuProjects [data-nav=\"mine\"]"] } },
+    { "name": "signed out: the card still closes on Escape (nothing throws with no session)", "continue": true,
+      "steps": [["press", "Escape"], ["wait", 100], ["dispatchClick", "#orbField a.worldOrb:not(#selfOrb)"], ["wait", 400], ["press", "Escape"], ["wait", 150]],
+      "expect": { "dialog": false, "closed": "#menuProjects" } },
+    { "name": "390: the magnifier opens the row and focuses the field", "auth": true, "width": 390,
+      "steps": [["click", "#qToggle"], ["wait", 150]],
+      "expect": { "activeId": "mapQ", "hasClass": [["#qWrap", "is-open"]] } },
+    { "name": "390: Escape folds the row and returns focus to the magnifier", "continue": true,
+      "steps": [["press", "Escape"], ["wait", 100]],
+      "expect": { "activeId": "qToggle", "hasClass": [["#qWrap", "is-open", false]] } },
+    { "name": "390: an opening band folds the search", "continue": true,
+      "steps": [["click", "#qToggle"], ["wait", 100], ["click", "#projTrig"], ["wait", 150]],
+      "expect": { "hasClass": [["#qWrap", "is-open", false]], "open": "#menuProjects" } },
+    { "name": "390: a solo Shift tap opens the fold and focuses the field, without overflow", "continue": true,
+      "steps": [["press", "Escape"], ["wait", 100], ["press", "Shift"], ["wait", 150]],
+      "expect": { "hasClass": [["#qWrap", "is-open", true]], "activeId": "mapQ", "noOverflow": true } }
+  ]
+}

package/public-landing/projects.states.json

@@ -0,0 +1,25 @@
+{
+  "_": "The hub's states for modules/ui-design/kit/render.js (task 1003320): name → url + actions + expectations. `auth` picks the signed-in stub. Rendered dark + light at 1440/390/320 and audited against the platform floors.",
+  "page": "/projects",
+  "surface": "public-landing",
+  "modeQuery": "mode",
+  "ignoreRequests": ["/api/(gds|bongos)/me$", "/my-projects", "/provisioning/"],
+  "ignoreConsole": ["/api/(gds|bongos)/me", "\\b401\\b", "Unauthorized"],
+  "ignoreControls": [".skip", ".vh"],
+  "states": {
+    "out-map": { "auth": false, "expect": { "expanded": false } },
+    "in-map": { "auth": true, "expect": { "expanded": false } },
+    "in-map-projects": { "auth": true, "actions": [["click", "#projTrig"], ["wait", 350]], "expect": { "expanded": true, "open": "#menuProjects" } },
+    "in-map-profile": { "auth": true, "actions": [["click", "#who"], ["wait", 350]], "expect": { "expanded": true, "open": "#menuProfile" } },
+    "in-map-kbd": { "auth": true, "actions": [["focus", "#projTrig"], ["press", "Enter"], ["wait", 350], ["press", "ArrowDown"], ["wait", 120]], "expect": { "expanded": true, "activeText": "Table" } },
+    "in-map-search": { "auth": true, "actions": [["clickIfVisible", "#qToggle"], ["wait", 200], ["fill", "#mapQ", "emer"], ["wait", 300]], "expect": { "value": [["#mapQ", "emer"]] } },
+    "in-map-mine-on": { "auth": true, "actions": [["check", "#onlyMine"], ["wait", 300]], "expect": { "checked": "#onlyMine" } },
+    "in-table": { "auth": true, "actions": [["click", "#projTrig"], ["wait", 250], ["click", "a[data-sub=\"table\"]"], ["wait", 400]], "expect": { "visible": ["#sub-table-body"], "closed": "#menuProjects" } },
+    "in-mine": { "auth": true, "url": "/projects?view=mine", "expect": { "hidden": ["#qWrap"] } },
+    "in-new": { "auth": true, "url": "/projects?view=new", "expect": { "hidden": ["#qWrap"] } },
+    "out-new": { "auth": false, "url": "/projects?view=new", "expect": { "hidden": ["#qWrap"] } },
+    "out-map-projects": { "auth": false, "actions": [["click", "#projTrig"], ["wait", 350]], "expect": { "expanded": true, "hidden": ["#menuProjects [data-nav=\"mine\"]"] } },
+    "card": { "auth": true, "actions": [["dispatchClick", "#orbField a.worldOrb:not(#selfOrb)"], ["wait", 600]], "expect": { "dialog": true } }
+  },
+  "reducedMotion": { "auth": true, "actions": [["click", "#projTrig"], ["wait", 100]] }
+}

package/scripts/gds/ui-kit-transform.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+'use strict';
+// ui-kit-transform.js — the instance's serving transforms as a command (task
+// 1003320, ADR 0197). Reads one surface page and prints it transformed exactly as
+// serve-internal.js / platform-server.js serve it: the apex-only strip, the
+// brand-token stamp, the pack's theme injection — with the instance's own
+// branding pack.
+//
+// WHY a script: the ui-design kit's stub (modules/ui-design/kit/serve.js) must
+// serve a page through the REAL code path, and a module may not require core
+// (ADR 0083), while the doorway may not import the serving domain (fitness Check
+// 12, ADR 0091 §1). A command under scripts/gds/ is outside both walls — the
+// memory / ideas / sessions precedent: a command travels with its domain but
+// stays under scripts/. The stub spawns this per page and memoises the answer.
+//
+//   node scripts/gds/ui-kit-transform.js <page.html> [--child] [--json]
+//     --child   the child-instance shape (apex-only regions removed)
+//     --json    { html, brand, publicOrigin, hallOrigin } instead of the bare HTML
+//
+// Exit 2 on usage; the transformed page on stdout, nothing else.
+const fs = require('node:fs');
+const path = require('node:path');
+
+const args = process.argv.slice(2);
+const file = args.find((a) => !a.startsWith('--'));
+if (!file) { process.stderr.write('usage: node scripts/gds/ui-kit-transform.js <page.html> [--child] [--json]\n'); process.exit(2); }
+const child = args.includes('--child');
+
+const { injectBrandingGlobal, applyBrandTokens } = require('../../src/bongos/serve-internal');
+const { stripApexOnly } = require('../../src/platform-server');
+const branding = require('../../src/branding');
+
+const brand = branding.clientBranding();
+let domains = {};
+try { domains = (typeof branding.branding === 'function' ? branding.branding() : {}).domains || {}; } catch { domains = {}; }
+const publicOrigin = domains.publicOrigin || '';
+const hallOrigin = child ? '' : (domains.buildersOrigin || '');
+
+const raw = fs.readFileSync(path.resolve(file), 'utf8');
+// platform-server's order for the landing: strip, then inject; the token stamp is
+// what the hall/status surfaces get on the way through serve-internal.
+const html = injectBrandingGlobal(applyBrandTokens(stripApexOnly(raw, !child), brand, publicOrigin, hallOrigin, '', ''), brand);
+process.stdout.write(args.includes('--json') ? JSON.stringify({ html, brand, publicOrigin, hallOrigin }) : html);

package/src/bongos/module-scope-map.js

@@ -223,6 +223,7 @@ const MODULE_GLOBS = {
   'ui-design': [
     'modules/ui-design/',
     'scripts/gds/design-sync.js', 'scripts/gds/figma-design-sync.js', 'scripts/gds/validate-design.js',
+    'scripts/gds/ui-kit-transform.js', // the kit's stub reaches the real serving transforms through this command (task 1003320)
     '.claude/skills/design/', '.claude/skills/design-sync/', '.claude/skills/figma-design-sync/',
     'docs/recipes/claude-design-loop.md', 'docs/recipes/figma-design-loop.md',
   ],

package/src/module-api.js

@@ -1230,8 +1230,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.393 with no explicit bump. run 33182535783. (task 1002620)
 //   1.19.395 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.394 with no explicit bump. run 33188021384. (task 1002620)
+//   1.19.396 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.395 with no explicit bump. run 33188525568. (task 1002620)
+//   1.19.397 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.396 with no explicit bump. run 33193365480. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.395'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.397'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');