@bongos/core 1.19.444 → 1.19.446

package/tests/hall_tokens.mjs

@@ -0,0 +1,371 @@
+// tests/hall_tokens.mjs — the builders' hall's token tier (task 1003303, goal 1000081).
+//
+// The hall was rebuilt into the chrome world DESIGN.md records, taking the tier
+// the composition round authored and verified (docs/design/mocks/hall/_tokens.css,
+// task 1003302; the pick and its steers are docs/design/hall-direction-v2.md §6).
+// This file is to modules/hall-ui/public/style.css what tests/world_tokens.mjs is
+// to world.css, and the method is the same: the TOKENS are the only input — it
+// parses style.css and resolves var() / color-mix() itself, so it measures what
+// the hall actually paints. Restating the hex values here would prove nothing.
+// The resolver is COPIED rather than imported because world_tokens.mjs is a test
+// file, not a module, and exporting from it would make one file's failure
+// silence the other's.
+//
+// What it locks, all of it silent in a browser:
+//   * DRIFT — the contract tier is a dead default (serve-internal.js's
+//     themeMarkup re-declares the thirteen from the pack AFTER this sheet, so
+//     the pack always wins); a value can rot here and nobody sees the colour
+//     they audited, and the sheet only reads correctly standalone while the two
+//     agree;
+//   * LOCKSTEP — dark is written twice (the hall's own [data-theme] switch and
+//     the prefers-color-scheme twin that covers first paint before shell.js
+//     runs); a change to one only works for half of users;
+//   * RE-THEMEABILITY — the dark blocks outrank the pack's :root, so a literal
+//     --accent inside one would defeat every instance's palette forever;
+//   * THE STATUS VOCABULARY — the hall renders VERIFICATION state, so DESIGN.md
+//     §Reuse licenses it a fixed green/amber/red instead of the world's warm
+//     accent-derived states. Three of the four values had to MOVE for the
+//     world's darker paper, which is a measurement: this is what re-measures it,
+//     on both grounds in both modes. Hand-tuning one without re-running this is
+//     how the shipped values came to fail in the first place;
+//   * THE SKELETON — --bg-deep is the obvious loading tone and it is invisible
+//     in dark, where DESIGN.md collapses deep back to black;
+//   * THE COMPAT ALIASES — ~20 page sheets still derive from --surface /
+//     --border / --accent-text; dropping one silently breaks colours across
+//     pages this task did not re-skin, rather than erroring;
+//   * THE KILL SWITCH — present, and LAST in the token layer, because a later
+//     rule re-declaring animation would outrank it on source order.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const HALL = path.join(ROOT, 'modules', 'hall-ui', 'public');
+const src = fs.readFileSync(path.join(HALL, 'style.css'), 'utf8');
+
+// ── parse ────────────────────────────────────────────────────────────────────
+const declarations = (body) => {
+  const out = {};
+  for (const m of body.replace(/\/\*[\s\S]*?\*\//g, '').matchAll(/(--[\w-]+)\s*:\s*([^;]+);/g)) {
+    out[m[1]] = m[2].replace(/\s+/g, ' ').trim();
+  }
+  return out;
+};
+
+const bodyAt = (open) => {
+  let depth = 0;
+  for (let i = open; i < src.length; i++) {
+    if (src[i] === '{') depth++;
+    else if (src[i] === '}' && --depth === 0) return src.slice(open + 1, i);
+  }
+  throw new Error(`unbalanced braces at offset ${open}`);
+};
+
+const blockAfter = (marker) => {
+  const at = src.indexOf(marker);
+  assert.notEqual(at, -1, `style.css no longer contains ${marker} — update this test`);
+  return bodyAt(src.indexOf('{', at));
+};
+
+// The one top-level bare :root: the contract tier, the derived tier and the
+// compat aliases in a single block. tests/hall_audit.mjs pins ten of its names
+// by reading the FIRST ':root {', so a second bare one appearing above it would
+// quietly move that check to the wrong block.
+const bareRoots = [...src.matchAll(/\n:root\s*\{/g)];
+assert.equal(bareRoots.length, 1, 'expected exactly one top-level :root block in style.css');
+const contractTier = declarations(bodyAt(src.indexOf('{', bareRoots[0].index)));
+
+const darkExplicit = declarations(blockAfter('html[data-theme="dark"] {'));
+const darkMedia = declarations(blockAfter('html:not([data-theme]) {'));
+
+// THE CASCADE THAT ACTUALLY SHIPS. injectBrandingInto splices the pack's theme
+// <style> at the END of <head> — after style.css's <link> — as a plain :root.
+// Equal specificity, later in document order, so for the tokens the pack emits
+// the PACK wins and style.css's own value never renders. html[data-theme="dark"]
+// is (0,1,1) and wins back.
+const packUi = JSON.parse(
+  fs.readFileSync(path.join(ROOT, 'config', 'branding.neutral.json'), 'utf8'),
+).theme.ui;
+
+// mirrors COLOR_VARS in src/bongos/serve-internal.js
+const camelToVar = (k) => '--' + k.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase());
+const PACK = Object.fromEntries(
+  Object.entries(packUi.colors).map(([k, v]) => [camelToVar(k), v]),
+);
+
+const RAW = {
+  light: { ...contractTier, ...PACK },
+  dark: { ...contractTier, ...PACK, ...darkExplicit },
+};
+
+// ── color resolution ─────────────────────────────────────────────────────────
+const clamp = (v) => Math.min(255, Math.max(0, v));
+
+function resolve(expr, mode, seen = new Set()) {
+  const e = String(expr).trim();
+
+  if (e === 'transparent') return [0, 0, 0, 0];
+
+  let m = e.match(/^#([0-9a-f]{6})$/i);
+  if (m) { const n = parseInt(m[1], 16); return [(n >> 16) & 255, (n >> 8) & 255, n & 255, 1]; }
+
+  m = e.match(/^#([0-9a-f]{3})$/i);
+  if (m) return [...m[1]].map((c) => parseInt(c + c, 16)).concat(1);
+
+  m = e.match(/^rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*(?:,\s*([\d.]+)\s*)?\)$/);
+  if (m) return [+m[1], +m[2], +m[3], m[4] === undefined ? 1 : +m[4]];
+
+  m = e.match(/^var\(\s*(--[\w-]+)\s*(?:,([\s\S]+))?\)$/);
+  if (m) {
+    const name = m[1];
+    assert.ok(!seen.has(name), `cyclic var reference at ${name}`);
+    const next = RAW[mode][name] ?? m[2];
+    assert.ok(next !== undefined, `${name} is not defined for ${mode} mode`);
+    return resolve(next, mode, new Set([...seen, name]));
+  }
+
+  m = e.match(/^color-mix\(\s*in\s+srgb\s*,\s*([\s\S]+?)\s+([\d.]+)%\s*,\s*([\s\S]+?)\s*\)$/);
+  if (m) {
+    const p = +m[2] / 100;
+    const a = resolve(m[1], mode, seen);
+    const b = resolve(m[3], mode, seen);
+    const alpha = a[3] * p + b[3] * (1 - p);
+    if (alpha === 0) return [0, 0, 0, 0];
+    return [0, 1, 2]
+      .map((i) => (a[i] * a[3] * p + b[i] * b[3] * (1 - p)) / alpha)
+      .concat(alpha);
+  }
+
+  throw new Error(`cannot resolve color expression: ${e}`);
+}
+
+// flatten a possibly-translucent color onto an opaque backdrop
+const over = (fg, bg) =>
+  fg[3] === 1 ? fg : [0, 1, 2].map((i) => clamp(fg[i] * fg[3] + bg[i] * (1 - fg[3]))).concat(1);
+
+const lin = (c) => { c /= 255; return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4; };
+const lum = ([r, g, b]) => 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+const contrast = (fg, bg) => {
+  const [hi, lo] = [lum(fg), lum(bg)].sort((a, b) => b - a);
+  return (hi + 0.05) / (lo + 0.05);
+};
+
+const paint = (name, mode) => resolve(RAW[mode][name] ?? name, mode);
+const ratio = (fgName, bgName, mode) => {
+  const bg = paint(bgName, mode);
+  return contrast(over(paint(fgName, mode), bg), bg);
+};
+
+// ── (a) the contract tier is the pack ────────────────────────────────────────
+
+test('style.css defaults do not drift from the branding pack', () => {
+  // For the pack-owned tokens style.css's :root is a DEAD DEFAULT — the pack
+  // always overrides it. That makes silent drift easy and dangerous: anyone
+  // auditing the sheet alone would measure colours no builder ever sees.
+  const drift = [];
+  for (const [name, value] of Object.entries(PACK)) {
+    if (contractTier[name] !== value) drift.push(`${name}: sheet ${contractTier[name]} vs pack ${value}`);
+  }
+  for (const [key, cssVar] of [['display', '--font-display'], ['body', '--font-body']]) {
+    if (contractTier[cssVar] !== packUi.fonts[key]) {
+      drift.push(`${cssVar}: sheet ${contractTier[cssVar]} vs pack ${packUi.fonts[key]}`);
+    }
+  }
+  assert.deepEqual(drift, [], 'the contract tier must equal config/branding.neutral.json theme.ui');
+});
+
+test('the pack still carries the web-font links the hall relies on', () => {
+  // The hall's 27 heads used to hardcode an Inter <link>; task 1003303 deleted
+  // all 27 and let themeMarkup() inject the pack's instead, which is what makes
+  // the faces host-overridable and reachable from a mirror. If the pack ever
+  // stops carrying them the hall silently falls back to the system stack.
+  assert.ok(Array.isArray(packUi.fonts.links) && packUi.fonts.links.length,
+    'branding.neutral.json theme.ui.fonts.links must carry the face stylesheet(s)');
+  const pages = fs.readdirSync(HALL).filter((f) => f.endsWith('.html'));
+  const hardcoded = pages.filter((f) => /fonts\.googleapis\.com\/css2/.test(fs.readFileSync(path.join(HALL, f), 'utf8')));
+  assert.deepEqual(hardcoded, [], 'no hall page may hardcode a web-font stylesheet — the pack injects it');
+});
+
+// ── (b) the dark twins are in lockstep ───────────────────────────────────────
+
+test('the two dark blocks are byte-identical', () => {
+  // html[data-theme="dark"] is the switch shell.js writes; the media block covers
+  // first paint for OS-dark users before the script runs. A value that lands in
+  // one and not the other works for half the audience and nobody can see which.
+  assert.deepEqual(darkMedia, darkExplicit,
+    'html[data-theme="dark"] and the prefers-color-scheme twin must declare the same tokens');
+  assert.ok(Object.keys(darkExplicit).length >= 20, 'sanity: the dark tier is substantial');
+});
+
+test('no dark block pins an accent literal (the Unpinned Accent Rule)', () => {
+  // The dark blocks are (0,1,1) and the pack's injected :root is (0,1,0), so a
+  // literal here outranks every instance's palette forever and a re-themed
+  // instance could not reach dark.
+  for (const name of ['--accent', '--sea', '--terracotta']) {
+    assert.equal(darkExplicit[name], undefined, `${name} must not be re-declared in dark`);
+  }
+});
+
+// ── (c) contrast, in both modes ──────────────────────────────────────────────
+
+// The ink-on-ground pairs the hall actually paints. --ink-faint on --bg is the
+// thinnest pair in the world and DESIGN.md says not to thin it further.
+const INK_PAIRS = [
+  ['--ink', '--bg'], ['--ink', '--bg-card'], ['--ink', '--bg-frame'], ['--ink', '--surface-2'],
+  ['--ink-soft', '--bg'], ['--ink-soft', '--bg-card'], ['--ink-soft', '--surface-2'],
+  ['--ink-faint', '--bg'], ['--ink-faint', '--bg-card'],
+  ['--accent-ink', '--bg'], ['--accent-ink', '--bg-card'],
+];
+
+test('every ink-on-ground pair clears AA in both modes', () => {
+  const fails = [];
+  for (const mode of ['light', 'dark']) {
+    for (const [fg, bg] of INK_PAIRS) {
+      const r = ratio(fg, bg, mode);
+      if (r < 4.5) fails.push(`${mode} ${fg} on ${bg} = ${r.toFixed(2)}:1`);
+    }
+  }
+  assert.deepEqual(fails, [], 'body text needs 4.5:1');
+});
+
+test('accent-on is readable on the accent fill, and white would not be', () => {
+  // DESIGN.md bans white on this salmon; --accent-on is the dark ink that goes
+  // on an accent fill. The second half of this is what stops a future edit from
+  // "simplifying" it back to #fff.
+  for (const mode of ['light', 'dark']) {
+    const r = ratio('--accent-on', '--accent', mode);
+    assert.ok(r >= 4.5, `${mode}: --accent-on on --accent = ${r.toFixed(2)}:1`);
+    const white = contrast([255, 255, 255], paint('--accent', mode));
+    assert.ok(white < 4.5, `${mode}: white on --accent measures ${white.toFixed(2)}:1 — it must stay banned`);
+  }
+});
+
+test('the status vocabulary clears AA on both grounds in both modes', () => {
+  // The round's finding: the shipped values were tuned against the hall's
+  // retired ground (--bg #f5f6f8) and FAIL against the world's darker paper
+  // (--bg #edecee) — ok 4.27, warn 4.13, info 3.85 and 4.36, and 4.19 on the
+  // dark card. These are the re-solved values; this is what keeps them solved.
+  const fails = [];
+  for (const mode of ['light', 'dark']) {
+    for (const state of ['--ok', '--warn', '--danger', '--info']) {
+      for (const ground of ['--bg', '--bg-card']) {
+        const r = ratio(state, ground, mode);
+        if (r < 4.5) fails.push(`${mode} ${state} on ${ground} = ${r.toFixed(2)}:1`);
+      }
+    }
+  }
+  assert.deepEqual(fails, [], 'a verification state must be legible on both grounds');
+});
+
+test('each state reads against its own weak fill', () => {
+  const fails = [];
+  for (const mode of ['light', 'dark']) {
+    for (const state of ['--ok', '--warn', '--danger', '--info']) {
+      const r = ratio(state, state + '-weak', mode);
+      if (r < 4.5) fails.push(`${mode} ${state} on ${state}-weak = ${r.toFixed(2)}:1`);
+    }
+  }
+  assert.deepEqual(fails, [], 'a status chip paints its own colour on its own weak fill');
+});
+
+test('the contrast probe would CATCH the values that failed', () => {
+  // The shipped-before values, measured against the world's paper. If this ever
+  // passes, the probe has stopped measuring what it claims to.
+  const bg = paint('--bg', 'light');
+  for (const [name, hex] of [['ok', '#1a7f4b'], ['warn', '#9a6700']]) {
+    const r = contrast(resolve(hex, 'light'), bg);
+    assert.ok(r < 4.5, `the retired ${name} ${hex} must still measure under AA here (got ${r.toFixed(2)}:1)`);
+  }
+});
+
+// ── (d) the derived tier's own hazards ───────────────────────────────────────
+
+test('--skeleton reads on the card in both modes, where --bg-deep cannot', () => {
+  // DESIGN.md collapses deep back to black in dark, so --bg-deep and --bg are
+  // the same value and a skeleton painted with it is invisible. Every hall page
+  // has loading states; the landing has none, which is why it never noticed.
+  for (const mode of ['light', 'dark']) {
+    const r = ratio('--skeleton', '--bg-card', mode);
+    assert.ok(r >= 1.1, `${mode}: --skeleton on --bg-card = ${r.toFixed(3)}:1 — a skeleton must be visible`);
+  }
+  const deep = paint('--bg-deep', 'dark');
+  const bg = paint('--bg', 'dark');
+  assert.deepEqual(deep.slice(0, 3), bg.slice(0, 3),
+    'in dark --bg-deep IS --bg — this is why it cannot be the skeleton tone');
+});
+
+test('--line is a width, not a colour', () => {
+  // DESIGN.md warns about this exact name: --line is a 1px WIDTH here and a
+  // hairline COLOUR in the hub's sheet. Page sheets that treated it as a colour
+  // were repointed at --rule / --rule-soft in task 1003303.
+  assert.match(contractTier['--line'], /^\d+px$/, '--line must resolve to a length');
+  const sheets = fs.readdirSync(HALL).filter((f) => f.endsWith('.css'));
+  const misuse = sheets.filter((f) => /var\(--line\s*,/.test(fs.readFileSync(path.join(HALL, f), 'utf8')));
+  assert.deepEqual(misuse, [], 'a colour fallback on --line means the sheet thinks it is a colour');
+});
+
+test('the plate seam is declared and resolves to none in both modes', () => {
+  // The owner deferred the hall's ground ("decide after the shell lands"), so
+  // the shell must be a complete composition with no plate — and adding one
+  // later must be a token change, not a re-layout.
+  for (const name of ['--plate', '--plate-blend', '--plate-veil']) {
+    assert.ok(contractTier[name], `${name} must stay declared as the seam`);
+  }
+  assert.equal(contractTier['--plate'], 'none', 'no plate ships with the shell');
+  assert.equal(contractTier['--plate-veil'], 'none', 'light never veils');
+  assert.equal(darkExplicit['--plate'], undefined, 'dark must not smuggle a plate in');
+});
+
+// ── (e) the compat aliases the un-reskinned pages still consume ──────────────
+
+test('every token a hall stylesheet references is defined', () => {
+  // ~20 page sheets derive from the aliases (--surface, --border, --accent-text,
+  // …). A page this task did not re-skin must degrade into the new palette, not
+  // break; dropping a name it uses fails silently in a browser.
+  const sheets = fs.readdirSync(HALL).filter((f) => f.endsWith('.css'));
+  const defined = new Set([
+    ...Object.keys(contractTier), ...Object.keys(darkExplicit), ...Object.keys(PACK),
+  ]);
+  // A sheet may define its own private tokens (atlas.css's --ab-* family), and
+  // a page script may set one inline on the element (roadmap.js writes
+  // style="--p:…;--rc:…" on the progress ring). Both are legitimate, so both
+  // count as defined — and the collector must not anchor to line start, because
+  // atlas.css declares two per line.
+  for (const f of [...sheets, ...fs.readdirSync(HALL).filter((x) => x.endsWith('.js'))]) {
+    for (const m of fs.readFileSync(path.join(HALL, f), 'utf8').matchAll(/(--[\w-]+)\s*:/g)) defined.add(m[1]);
+  }
+  const missing = new Map();
+  for (const f of sheets) {
+    const css = fs.readFileSync(path.join(HALL, f), 'utf8').replace(/\/\*[\s\S]*?\*\//g, '');
+    for (const m of css.matchAll(/var\(\s*(--[\w-]+)\s*([,)])/g)) {
+      // a var() WITH a fallback is a deliberate optional; one without must resolve
+      if (m[2] === ',') continue;
+      if (!defined.has(m[1])) {
+        if (!missing.has(m[1])) missing.set(m[1], []);
+        missing.get(m[1]).push(f);
+      }
+    }
+  }
+  assert.deepEqual([...missing.keys()], [], `undefined tokens: ${[...missing].map(([k, v]) => `${k} (${[...new Set(v)].join(', ')})`).join('; ')}`);
+});
+
+// ── (f) the kill switch ──────────────────────────────────────────────────────
+
+test('the reduced-motion kill switch is present and closes the token layer', () => {
+  const at = src.indexOf('@media (prefers-reduced-motion: reduce)');
+  assert.ok(at > 0, 'the kill switch must exist');
+  const body = bodyAt(src.indexOf('{', at));
+  assert.match(body, /animation:\s*none\s*!important/, 'animation must be killed with !important');
+  assert.match(body, /transition:\s*none\s*!important/, 'transition must be killed with !important');
+  assert.match(body, /\*,\s*\*::before,\s*\*::after/, 'nothing may escape it');
+  // It must sit AFTER the dark blocks: a later rule re-declaring animation would
+  // outrank it on source order, so this is where it can still win.
+  assert.ok(at > src.indexOf('html:not([data-theme]) {'),
+    'the kill switch closes the token layer, after the dark twins');
+  // and it must be the only one, or a second copy can drift from the first
+  assert.equal(src.split('@media (prefers-reduced-motion: reduce)').length - 1, 1,
+    'exactly one kill switch — a second copy is a place for the rule to rot');
+});