@bongos/core 1.19.396 → 1.19.398

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/modules/ui-design/skills/PREAMBLE.md

@@ -0,0 +1,13 @@
+<!-- BEGIN PLATFORM PREAMBLE · ui-design module · one block, byte-identical in every vendored skill so an upstream refresh is a three-way merge; the source is modules/ui-design/skills/PREAMBLE.md and tests/ui_design_skills.mjs fails on drift -->
+> **Platform preamble — read before any rule below.** This skill is vendored by the `ui-design` module and runs INSIDE an instance's world, which it reads first and never overrides.
+>
+> 1. **Load the world before any taste rule.** `config/branding.json` over `config/branding.neutral.json` (`theme.ui` is the fifteen tokens: <redacted> colours and two font stacks), `config/design-tokens.json` over `config/design-tokens.neutral.json`, and `DESIGN.md` at the repo root: the instance's palette and derived tiers, faces, materials, motion grammar, components, and its Do's and Don'ts. Where an instance has no `DESIGN.md`, the neutral pack is the world and the platform floors in item 6 are the whole rulebook; say so and build to them. Never invent a palette.
+> 2. **The fifteen-token contract is the only colour source.** Every colour is a `var()` or a `color-mix()` of the fifteen; the only legal literal is pure black or white with alpha as a scrim, mask or halo. No page `:root` (page tokens live on `body`), and every dark rule is written twice: `:root[data-mode="dark"]` and its `prefers-color-scheme` twin.
+> 3. **A style skill produces variants INSIDE that world, never a second world.** The look this skill carries (its palette, faces, materials, mood boards) is a reference for composition and craft; the instance's tokens and faces replace it. Changing the world is the owner's decision and an ADR, not a session's taste.
+> 4. **Images are for hero plates and hero objects only.** UI is built from templates and the instance's world, not painted; any image-generation step below applies to text-free plates and hero objects, never to controls, cards, text, or a screenshot of a screen.
+> 5. **The instance's taste bans apply and win.** Read them from its `DESIGN.md`. Cloud Bongos's own (no em dash or en dash in visible copy, no emoji, no gradient text, no three-equal-card row, no fake screenshot built from divs) are that instance's, not the module's; where this skill's rules conflict with an instance's bans, the instance wins.
+> 6. **The platform floors hold on every instance** and a `DESIGN.md` may tighten them, never loosen them: every control clears 24px on both sides (primary pills 46–48px); AA in both modes (4.5:1 body text, 3:1 large text and non-text) measured from the real stylesheet; and the Kill Switch, `@media (prefers-reduced-motion: reduce)` at the foot of the token layer killing every animation and transition, no motion authored in JavaScript, and a rest frame that is a complete composition on its own.
+> 7. **Look before you ship.** Render the real surface through the module's kit before and after (`/design` Step 2 and `docs/recipes/ui-look-before-you-ship.md`: every state at 1440 / 390 / 320 in dark and light, audited against the floors); a page with no states file gets one first, and new interactive code ships with a pin in the page's own test file.
+>
+> The rules below are the upstream skill's, unchanged. `PROVENANCE.md` beside this file names the origin, the pinned commit, the licence and the scan verdict it was vendored under.
+<!-- END PLATFORM PREAMBLE -->

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

@@ -1,3 +1,37 @@
-# `modules/ui-design/skills/` — reserved home for the vetted UI skills
+# `modules/ui-design/skills/` — the vetted UI skills: the policy, the roster, and why the roster is what it is
 
-Lands with [task 1003321](https://cloudbongos.com/builders#/task/1003321): the vendored design skills (impeccable, the style/taste skills, image-to-code, imagegen, brandkit), each scanned with `/scan-before-install`, carrying a PROVENANCE sidecar and a licence on the allowlist, and prefixed with the PLATFORM PREAMBLE that reads the instance's branding pack and `DESIGN.md` before any taste rule applies. The vendoring policy is that task's ADR; [ADR 0197](../../../docs/adr/<redacted>.md) only points at it.
+The home for third-party design skills the `ui-design` module ships to every builder on every instance where the module is on ([task 1003321](https://cloudbongos.com/builders#/task/1003321), [ADR 0198](../../../docs/adr/<redacted>.md)). A skill that lands here is **materialised** into a builder's `.claude/skills/<name>/` by `scripts/gds/claude-materialize.js` (step 1b) on `bongos init` / `bongos upgrade`, exactly like a core skill, and withdrawn when the instance disables the module.
+
+## The policy (enforced by `tests/ui_design_skills.mjs`, declared in [`policy.json`](policy.json))
+
+A third-party skill lands here **only** as a copy of a pinned commit that:
+
+1. was scanned with `/scan-before-install` at the `default` tier or higher and reduced to **`clean` or `caution`** — a `dangerous` verdict never lands a copy, not for a skill already installed on a builder's machine, not for one that "ran the last round"; the arithmetic is the scanner's, not a session's;
+2. carries a licence on the allowlist — `Apache-2.0`, `MIT`, `BSD-2-Clause`, `BSD-3-Clause`, `CC-BY-4.0` — with the upstream `LICENSE` text beside the copy; anything else or unlicensed becomes a rebuild spec, not a copy;
+3. carries a `PROVENANCE.md` sidecar (YAML frontmatter with the fields [`policy.json`](policy.json) names: `name`, `origin`, `sourcePath`, `commit`, `licence`, `scanVerdict`, `scanTier`, `scanReport`, `scannedOn`, `vendoredOn`, then prose) — and the materialiser reads it **at copy time** (`vendoredSkillGate` in `scripts/gds/claude-materialize.js`): a vendored dir with no sidecar, an off-list licence or a verdict that may not land is refused and logged, whatever the CI test says;
+4. opens its `SKILL.md` body with the **PLATFORM PREAMBLE** — [`PREAMBLE.md`](PREAMBLE.md), one fenced block, byte-identical in every copy so an upstream refresh is a three-way merge — which reads the instance's world (its branding pack, its design tokens, its `DESIGN.md`) before any taste rule, keeps the fifteen-token contract the only colour source, makes a style skill produce variants *inside* that world, confines image generation to hero plates and hero objects, applies the instance's taste bans, restates the platform floors and the kill switch, and points at the look-before-you-ship loop;
+5. is declared in `module.json` `contributes.skills` (the manifest stays the single declaration; an undeclared dir is not a skill) and lives under **`vendor/<name>/`** — the `vendor/` segment is the one `scripts/gds/fitness-ratchets.js` exempts from the first-party line and duplication budgets, so a 150-file upstream tree does not count as our debt. A skill the module *authors* lives at `<name>/` and is counted.
+
+No auto-update: a refresh is a task that re-scans the new commit and re-applies the preamble. An instance may disable the module (`config/modules.json`), which withdraws every skill here; it may add its own skills under its own `.claude/skills/` — never by editing a vendored copy.
+
+## The roster (2026-08-28)
+
+Two origins were scanned for the set scoped with the owner (impeccable; the eleven taste skills). **Both reduced to `dangerous` at the deterministic floor, so neither landed as a copy** — the reports are in the scanning builder's `~/.config/otb/scan-reports/`, the rows in `security_scans`, the verdicts recorded in ADR 0198.
+
+| Skill (in-house name) | Upstream | Licence | Verdict | Landing |
+|---|---|---|---|---|
+| `impeccable` | `pbakaus/impeccable` @ `<redacted>` (skill v4.1.x) | Apache-2.0 | **dangerous** — floor: 3 critical (a `bypassPermissions` marker in the skill's own live copy-edit agent; an instruction-override phrase in a test fixture; a same-file credential-store + http-client co-occurrence in a test), 19 high (shipped PostToolUse + Stop hooks, credential-store references), 107 medium, 147 low; panel: hooks written into five harness configs (globally on a global install), a child agent spawned with permissions bypassed from a loopback HTTP route, an autonomy directive that tells the agent to disregard its system prompt, a live-server token embedded in page source, an unverified remote bundle download | rebuild spec → GDS task |
+| `design-taste-frontend`, `design-taste-frontend-v1`, `high-end-visual-design`, `minimalist-ui`, `industrial-brutalist-ui`, `redesign-existing-projects`, `gpt-taste`, `stitch-design-taste`, `image-to-code`, `imagegen-frontend-web`, `imagegen-frontend-mobile`, `brandkit` | `Leonxlnx/taste-skill` @ `<redacted>` | MIT | **dangerous** — floor: 1 critical (an injection-phrase hit at `skills/taste-skill/SKILL.md:892`, which the panel identifies as a filename placeholder; the floor is untouchable by design); panel: caution (1 medium: the only documented install path runs an unpinned third-party `npx` CLI; 21 low: mandated invocation of any available image-generation tool, unbounded image counts, remote assets and scripts in generated pages, an auto-loaded cross-agent instruction file) | rebuild spec → GDS task |
+
+The eleven taste skills are single-file prose; the floor's one critical is a false positive in the human sense and a true positive in the scanner's — and the rule that makes the scanner worth having is that a session does not get to tell the difference. Vendoring any of them anyway is an **owner override recorded in an ADR**, not a judgement a task makes.
+
+**The playwright plugin** (`claude-plugins-official`, an MCP plugin) is the LIVE browser-driving loop, where the kit is the headless one. It is a prerequisite, documented — `claude plugin install playwright@claude-plugins-official` — never vendored.
+
+## How to land one (when a scan says it may)
+
+1. `/scan-before-install <origin url>` at `default` or higher; keep the report; record the row.
+2. `git init <tmp> && git -C <tmp> fetch --depth 1 <url> <sha> && git -C <tmp> checkout --detach FETCH_HEAD` — the pinned commit only, never a branch.
+3. Copy the skill's directory to `vendor/<name>/`; add the upstream `LICENSE`; write `PROVENANCE.md` from `policy.json`'s `sidecarRequiredFields`.
+4. Insert the contents of `PREAMBLE.md` as the first thing after the SKILL.md frontmatter.
+5. Add `<name>` to `module.json` `contributes.skills`; add its line to `/design` (`.claude/skills/design/SKILL.md`) and to the roster above.
+6. `node tests/ui_design_skills.mjs` — it refuses a missing sidecar, an off-list licence, a dangerous verdict, a drifted preamble, an undeclared dir.

package/modules/ui-design/skills/policy.json

@@ -0,0 +1,12 @@
+{
+  "_doc": "The vendoring policy for third-party UI skills in the ui-design module (task 1003321, ADR 0198). tests/ui_design_skills.mjs enforces it; modules/ui-design/skills/README.md explains it. A skill lands under skills/vendor/<name>/ only with a PROVENANCE.md sidecar, a licence on the allowlist, a /scan-before-install verdict that is not dangerous, and the PLATFORM PREAMBLE block (PREAMBLE.md, byte-identical) at the top of its SKILL.md body. A dangerous verdict or a licence off the allowlist lands a rebuild spec, never a copy.",
+  "licenceAllowlist": ["Apache-2.0", "MIT", "BSD-2-Clause", "BSD-3-Clause", "CC-BY-4.0"],
+  "verdictsThatMayLand": ["clean", "caution"],
+  "sidecar": "PROVENANCE.md",
+  "preamble": {
+    "source": "PREAMBLE.md",
+    "begin": "<!-- BEGIN PLATFORM PREAMBLE",
+    "end": "<!-- END PLATFORM PREAMBLE -->"
+  },
+  "sidecarRequiredFields": ["name", "origin", "sourcePath", "commit", "licence", "scanVerdict", "scanTier", "scanReport", "scannedOn", "vendoredOn"]
+}

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.396",
+  "version": "1.19.398",
   "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]] }
+}