@radicool/throughline 0.21.4 → 0.23.0

package/scripts/README.md

@@ -23,12 +23,16 @@ tested here; copied verbatim by `token-crosswalk-builder` into the user's
 | `docs-lint.mjs` | Copy lint for .doc.json records — warnings only, always exits 0 on a parseable record; the mechanical subset of `references/doc-writing-standard.md`. | `docs:lint` |
 | `lib/doc-record.mjs` | Canonical record load + `canonicalFingerprint` (sha256 over the record minus `provenance`). The fingerprint every surface is stamped with. | copied alongside docs-check.mjs |
 | `lib/doc-card-render.figma.js` | Figma renderer template for the doc card's `Usage` band and header. Inlined into `references/doc-card-builder.md`; never executed as a module. | plugin-internal (not installed) |
+| `lib/figma-checks.mjs` | Pure checker for the Figma stop conditions: the COMPONENT_SET assertion against the full matrix, the state matrix, and the focus ring, plus the focus-framework rules. Inlined into `references/figma-checks.md`; unit-tested against `lib/fixtures/figma-checks/`. | plugin-internal (not installed) |
+| `lib/figma-checks-read.figma.js` | Figma reader that turns the live COMPONENT_SET into the checker's snapshot JSON. Inlined into `references/figma-checks.md`; never executed as a module. | plugin-internal (not installed) |
 | `lib/doc-card-plan.mjs` | Pure layout planner for the doc card's `Usage` band + `DOC_CARD_RENDERER_VERSION` (single source of the layout version). Inlined into `references/doc-card-builder.md`; imported by `docs-check.mjs`. | copied alongside docs-check.mjs; also inlined into the generated builder |
 | `verify-check.mjs` | The verification proof bundle: records each stage's entry, and re-derives what it can rather than trusting the record. Fails on an orphaned token, a component documented without its archetype's baseline interaction states, a name that drifts between the manifest, its record and its code surface, or a recorded result the rerun contradicts. | `verify:check` |
 | `lib/proof.mjs` | The proof store's vocabulary and mechanics: the stage list, entry validation, latest-wins merge, and the fingerprint the manifest pointer carries. | copied alongside `verify-check.mjs` |
 | `lib/component-states.mjs` | The archetype table and resolver behind `state-incomplete` — which baseline interaction states each kind of component owes, and when to abstain. `validate-adherence.mjs` also uses it to find Badges. | copied alongside `verify-check.mjs` and `validate-adherence.mjs` |
 | `lib/contrast.mjs` | The WCAG contrast maths and the semantic colour pairs behind `color-contrast` — which text role must clear which surface, in every mode, and where the rule deliberately abstains. | copied alongside `verify-check.mjs` |
 | `build-doc-card-builder.mjs` | Generate `references/doc-card-builder.md` from the planner + the Figma renderer template (`lib/doc-card-render.figma.js`). `--check` gates CI. | plugin-internal (not installed) |
+| `build-figma-checks.mjs` | Generate `references/figma-checks.md`, the `figma_execute` snippet for the Figma stop conditions, by inlining `lib/component-states.mjs` and `lib/figma-checks.mjs` above the reader (`lib/figma-checks-read.figma.js`). `--check` gates CI. | plugin-internal (not installed) |
+| `build-state-baseline.mjs` | Generate `references/state-baseline.md`, the table of which components owe which interaction states, from `lib/component-states.mjs`. The Figma executor reads the table; `verify:check` reads the module. `--check` gates CI. | plugin-internal (not installed) |
 | `build-native-adapter-config.mjs` | Generate `references/native-adapter-config.md` by slicing `lib/sd-native.mjs` on its `@doc-section` markers and interleaving each fragment under its prose. Fails when module code falls outside every section, so the doc cannot silently ship incomplete. `--check` gates CI. | plugin-internal (not installed) |
 
 **Documentation scripts — install as a set.** Copying these files without
@@ -245,7 +249,7 @@ the committed `adapters/<target>/` tree plus the runtime payload
 (`references/` + `scripts/`, minus `scripts/adapters/`) into `.throughline/`,
 rewriting `${CLAUDE_PLUGIN_ROOT}` → `.throughline`:
 
-    npx @radicool/throughline@0.21.4 init --target=cursor|codex|generic
+    npx @radicool/throughline@0.23.0 init --target=cursor|codex|generic
 
 See `scripts/install.mjs` (pure core + CLI + `install.test.mjs`).
 

package/scripts/build-figma-checks.mjs

@@ -0,0 +1,98 @@
+// Generates references/figma-checks.md — the canonical figma_execute snippet
+// that runs the Figma stop conditions (COMPONENT_SET assertion, state matrix,
+// focus ring) — by inlining the state table (lib/component-states.mjs) and the
+// pure checker (lib/figma-checks.mjs) above the Figma reader
+// (lib/figma-checks-read.figma.js). Mirrors build-doc-card-builder.mjs: run
+// bare to write, run with --check to gate CI. Zero dependencies.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const STATES = join(REPO_ROOT, 'scripts', 'lib', 'component-states.mjs');
+const CHECKER = join(REPO_ROOT, 'scripts', 'lib', 'figma-checks.mjs');
+const READER = join(REPO_ROOT, 'scripts', 'lib', 'figma-checks-read.figma.js');
+const OUT = join(REPO_ROOT, 'references', 'figma-checks.md');
+
+const BIND = 'const { checkSpec, checkBuilt } = withTable({ resolveArchetype, BASELINE_STATES, STATE_SYNONYMS, normalizeName });';
+
+const HEADER = [
+  '# Figma stop-condition checks (GENERATED)',
+  '',
+  '> **GENERATED FILE — do not edit by hand.** Sources: `scripts/lib/component-states.mjs`',
+  '> (the state table), `scripts/lib/figma-checks.mjs` (the pure checker, unit-tested in',
+  '> Node) + `scripts/lib/figma-checks-read.figma.js` (the Figma reader). Regenerate with',
+  '> `node scripts/build-figma-checks.mjs`; CI gates freshness with `--check`.',
+  '',
+  'The canonical `figma_execute` snippet for the checks that can stop a component',
+  'build: the COMPONENT_SET assertion against the full variant matrix, the state',
+  'matrix, and the focus ring. The script is the rule; do not re-write these checks',
+  'by hand.',
+  '',
+  '## How to call it',
+  '',
+  '1. Paste the snippet below into `figma_execute`, with the two slots filled above it:',
+  '   - `const EXPECT = { name, matrix, uiFramework, controlLayer }` — `name` is the',
+  '     component\'s real name; `matrix` is `{ axis: [values] }` for every axis of the',
+  '     set; `uiFramework` is `project.uiFramework` from `design-system.json`;',
+  '     `controlLayer` is the layer that is the actual control in a wrapped control,',
+  '     copied from the architect\'s spec when it gives one (omit it otherwise).',
+  '   - `const MODE = \'spec\'` or `\'built\'`.',
+  '2. End the script with `return await runFigmaChecks(EXPECT, MODE);` and pass',
+  '   `timeout: 30000`.',
+  '3. Read the result, `{ pass, checks: [{ name, result, detail }] }`. `result` is',
+  '   `pass`, `fail` or `skip`; `pass` ignores skips. On `fail`, fix what each failing',
+  '   check\'s `detail` names and run it again, within the ~3-pass budget; after that,',
+  '   `BLOCKED` naming the failing checks\' `detail`.',
+  '4. `\'spec\'` reads no node and runs before the first write. `\'built\'` reads the',
+  '   COMPONENT_SET inside the frame named `WIP: <name>` on the current page and runs',
+  '   in the self-verify loop. It throws only if that frame is missing; a frame with',
+  '   no set, or a set Figma reports as conflicting, fails the structural check.',
+  '',
+  '```js',
+  'const EXPECT = { name: \'Chip\', matrix: { state: [\'default\', \'hover\'] }, uiFramework: \'shadcn\' };',
+  'const MODE = \'spec\';',
+  '// … the generated snippet …',
+  'return await runFigmaChecks(EXPECT, MODE);',
+  '```',
+  '',
+  '## The snippet',
+  '',
+  '```js',
+].join('\n');
+
+const FOOTER = ['```', ''].join('\n');
+
+const stripExports = (src) =>
+  src.replace(/^export const /gm, 'const ').replace(/^export function /gm, 'function ');
+
+export function buildFigmaChecks({ statesSource, checkerSource, readerSource }) {
+  const states = stripExports(statesSource);
+  const checker = stripExports(checkerSource);
+  for (const [name, src] of [['component-states.mjs', states], ['figma-checks.mjs', checker], ['figma-checks-read.figma.js', readerSource]]) {
+    if (/^\s*(import|export)\b/m.test(src)) {
+      throw new Error(`${name} must stay import-free (only top-level \`export const\`/\`export function\` allowed) — it is inlined into the Figma snippet where no module system exists`);
+    }
+  }
+  return `${HEADER}\n${states}\n${checker}\n${BIND}\n\n${readerSource}${FOOTER}`;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const result = buildFigmaChecks({
+    statesSource: readFileSync(STATES, 'utf8'),
+    checkerSource: readFileSync(CHECKER, 'utf8'),
+    readerSource: readFileSync(READER, 'utf8'),
+  });
+  if (process.argv.includes('--check')) {
+    let onDisk = null;
+    try { onDisk = readFileSync(OUT, 'utf8'); } catch { /* missing counts as drift */ }
+    if (onDisk !== result) {
+      console.error('✗ references/figma-checks.md out of date; run: node scripts/build-figma-checks.mjs');
+      process.exit(1);
+    }
+    console.log('✓ figma checks in sync');
+  } else {
+    writeFileSync(OUT, result);
+    console.log('✓ wrote references/figma-checks.md');
+  }
+}

package/scripts/build-state-baseline.mjs

@@ -0,0 +1,71 @@
+// Generates references/state-baseline.md from scripts/lib/component-states.mjs.
+// The table is the one list of which components owe which interaction states:
+// `verify:check` reads the module, and `figma-executor` (which cannot import
+// JavaScript) reads this rendering. Mirrors build-native-adapter-config.mjs:
+// run bare to write, --check to gate CI. Zero dependencies.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { ARCHETYPES, BASELINE_STATES, NAME_SYNONYMS, STATE_SYNONYMS } from './lib/component-states.mjs';
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+export const OUT = join(REPO_ROOT, 'references', 'state-baseline.md');
+
+export function render(states = BASELINE_STATES, synonyms = NAME_SYNONYMS, archetypes = ARCHETYPES, stateSynonyms = STATE_SYNONYMS) {
+  const aliases = Object.keys(stateSynonyms).map((s) => `\`${s}\` counts as \`${stateSynonyms[s]}\``).join(', and ');
+  const owing = archetypes.filter((a) => (states[a] ?? []).length > 0);
+  const rows = owing.map((a) => {
+    const names = Object.keys(synonyms).filter((n) => synonyms[n] === a);
+    return `| ${a} | ${names.map((n) => `\`${n}\``).join(', ')} | ${states[a].map((s) => `\`${s}\``).join(', ')} |`;
+  });
+  const exempt = archetypes.filter((a) => !owing.includes(a) && a !== 'other');
+  const exemptNames = exempt.flatMap((a) => Object.keys(synonyms).filter((n) => synonyms[n] === a));
+  return `<!-- GENERATED by scripts/build-state-baseline.mjs from scripts/lib/component-states.mjs. Do not edit; run: node scripts/build-state-baseline.mjs -->
+# State baseline
+
+Which interaction states a component owes. This is the one list both checks read:
+\`verify:check\` (\`state-incomplete\`) reads it from \`scripts/lib/component-states.mjs\`,
+and the Figma checks script (\`references/figma-checks.md\`) inlines the same module,
+so this table is the human-readable view of both. CI fails when it is stale.
+
+A component name matches a row when it folds (lowercase, punctuation and spaces
+stripped) to exactly one of that row's names. \`Text Field\` folds to \`textfield\`.
+Matching is exact on purpose: \`IconButton\` matches nothing, and a component that
+matches nothing owes no states.
+
+| Archetype | Names | States owed |
+|---|---|---|
+${rows.join('\n')}
+
+Every state in the table must be a value on the component's \`state\` axis, with one
+exception in Figma: a choice control may carry \`selected\` on its own axis named
+\`selected\`, \`checked\` or \`on\`. On the
+Figma side the matrix also carries \`default\` as the resting state; the CLI does not
+count it. ${aliases}, since that is what shadcn and Radix call it. Conditional states (\`loading\`, \`error\`, \`success\`) are not in the table:
+whether one applies is a design judgment.
+
+Names that fold to ${exemptNames.map((n) => `\`${n}\``).join(', ')} owe none, so neither check asserts states on them.
+`;
+}
+
+function main() {
+  const check = process.argv.includes('--check');
+  const rendered = render();
+  if (!check) {
+    writeFileSync(OUT, rendered);
+    console.log(`wrote ${OUT}`);
+    return;
+  }
+  const current = readFileSync(OUT, 'utf8');
+  if (current === rendered) {
+    console.log('references/state-baseline.md is up to date');
+    return;
+  }
+  console.error(
+    'references/state-baseline.md is stale.\n' +
+      'Run: node scripts/build-state-baseline.mjs',
+  );
+  process.exit(1);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();

package/scripts/install.mjs

@@ -99,18 +99,23 @@ function stagePayload(srcRoot, destRoot, skip) {
   return written;
 }
 
-// Scripts that never run from a consuming repo: the installer itself, the two
-// reference-doc generators, and the renderer template one of them inlines (the
-// renderer reaches Figma pre-inlined inside references/doc-card-builder.md).
+// Scripts that never run from a consuming repo: the installer itself, the
+// reference-doc generators, and the Figma sources they inline (the doc-card
+// renderer and the Figma checks reach Figma pre-inlined inside
+// references/doc-card-builder.md and references/figma-checks.md). Test fixtures
+// under lib/fixtures/ are dropped too.
 const PLUGIN_INTERNAL = new Set([
   'install.mjs',
   'build-doc-card-builder.mjs',
   'build-native-adapter-config.mjs',
   'lib/doc-card-render.figma.js',
+  'build-figma-checks.mjs',
+  'lib/figma-checks-read.figma.js',
+  'lib/figma-checks.mjs',
 ]);
 
 export const skipScript = (relPosix) =>
-  relPosix.startsWith('adapters/') || relPosix.endsWith('.test.mjs') || PLUGIN_INTERNAL.has(relPosix);
+  relPosix.startsWith('adapters/') || relPosix.startsWith('lib/fixtures/') || relPosix.endsWith('.test.mjs') || PLUGIN_INTERNAL.has(relPosix);
 
 export function install({ target, dir, pkgRoot = PKG_ROOT }) {
   if (!TARGETS.includes(target)) {

package/scripts/lib/component-states.mjs

@@ -1,22 +1,30 @@
 // The archetype baseline for `state-incomplete` (`docs/specs/2026-09-12-verification-proof-bundle.md`,
-// step 3). Source of truth for the prose is `references/figma-component-standards.md:126-138`.
+// step 3). The prose in `references/figma-component-standards.md` (State handling) points at
+// `references/state-baseline.md`, which is generated from this file.
 //
 // `default` is deliberately excluded from every baseline below: documenting the
 // resting state is not documentation, and the Figma matrix requirement for it is
 // the executor's, not this table's. Conditional states (`loading`, `error`,
-// `success`, `selected`) are deliberately excluded too — whether one applies to a
-// given component is a design judgment, not something a baseline can assert.
+// `success`) are deliberately excluded too — whether one applies to a given
+// component is a design judgment, not something a baseline can assert. `selected`
+// is not conditional for a choice control: a checkbox, radio, toggle, switch or
+// chip that cannot be selected is not one.
 //
-// MAINTENANCE: a change to the prose baseline must change this table.
+// This table is the single source for both checks. `scripts/build-state-baseline.mjs`
+// renders it into `references/state-baseline.md`, which the Figma executor reads;
+// CI fails when that file is stale. MAINTENANCE: change this table, then run it.
 
-import { normalizeName } from './source-scan.mjs';
+// Defined here rather than imported from source-scan.mjs so this module has no
+// imports and can be inlined into the Figma checks script. A test keeps the two
+// copies in step.
+const normalizeName = (s) => String(s).toLowerCase().replace(/[^a-z0-9]/g, '');
 
 export const ARCHETYPES = ['button', 'input', 'choice', 'card', 'modal', 'badge', 'other'];
 
 export const BASELINE_STATES = {
   button: ['hover', 'focus', 'active', 'disabled'],
   input: ['hover', 'focus', 'disabled'],
-  choice: ['hover', 'focus', 'active', 'disabled'],
+  choice: ['hover', 'focus', 'active', 'selected', 'disabled'],
   card: [],
   modal: [],
   badge: [],
@@ -40,6 +48,14 @@ export const NAME_SYNONYMS = {
   tag: 'badge',
 };
 
+// Other names a recorded state goes by. shadcn and Radix call a checked checkbox
+// `checked` and a pressed-in toggle `on`; both are `selected` here. `pressed` is
+// not one: the standards use it for `active`.
+export const STATE_SYNONYMS = {
+  checked: 'selected',
+  on: 'selected',
+};
+
 export function resolveArchetype(record) {
   if (ARCHETYPES.includes(record.archetype)) return record.archetype;
   const bySynonym = NAME_SYNONYMS[normalizeName(record.name)];
@@ -51,6 +67,11 @@ export function missingStates(record) {
   if (archetype === null) return [];
   const baseline = BASELINE_STATES[archetype];
   if (baseline.length === 0) return [];
-  const recordedKeys = new Set(Object.keys(record.states ?? {}).map(normalizeName));
+  const recordedKeys = new Set(
+    Object.keys(record.states ?? {}).map((key) => {
+      const name = normalizeName(key);
+      return STATE_SYNONYMS[name] ?? name;
+    }),
+  );
   return baseline.filter((state) => !recordedKeys.has(normalizeName(state)));
 }

package/scripts/lib/figma-checks-read.figma.js

@@ -0,0 +1,120 @@
+// Figma plugin-API reader for the stop-condition checks. This file is NOT a
+// Node module — build-figma-checks.mjs concatenates it after the inlined
+// component-states.mjs and figma-checks.mjs into references/figma-checks.md, and
+// the result runs inside figma_execute (dynamic-page mode). Constraints honored
+// here (see references/figma-scripting.md): async getters only, variable names
+// resolved with getVariableByIdAsync and only for focus variants and their
+// controlLayer. Untested in Node, like the doc-card renderer; the pure checker
+// it feeds is unit-tested.
+//
+// In-scope globals when assembled: normalizeName (inlined
+// component-states.mjs), checkSpec, checkBuilt (bound from withTable) and the
+// caller-filled slots EXPECT and MODE (passed to runFigmaChecks). The snapshot
+// shape is documented at the top of scripts/lib/figma-checks.mjs.
+
+async function variableName(alias) {
+  if (!alias || !alias.id) return null;
+  const variable = await figma.variables.getVariableByIdAsync(alias.id);
+  return variable ? variable.name : null;
+}
+
+// The fields the focus check reads from a variant, a control layer or a direct child.
+async function readFocusNode(node, { withEffects }) {
+  const strokes = (node.boundVariables && node.boundVariables.strokes) || [];
+  const strokeVariables = [];
+  for (const alias of strokes) {
+    const name = await variableName(alias);
+    if (name !== null) strokeVariables.push(name);
+  }
+  const bound = node.boundVariables || {};
+  const out = {
+    strokeAlign: node.strokeAlign,
+    strokeVariables,
+    strokeWeightBound: Boolean(
+      bound.strokeWeight || bound.strokeTopWeight || bound.strokeRightWeight || bound.strokeBottomWeight || bound.strokeLeftWeight,
+    ),
+  };
+  if (withEffects) {
+    out.effects = [];
+    for (const effect of node.effects || []) {
+      const colorAlias = effect.boundVariables && effect.boundVariables.color;
+      out.effects.push({
+        type: effect.type,
+        visible: effect.visible,
+        spread: effect.spread,
+        colorVariable: await variableName(colorAlias),
+      });
+    }
+  } else {
+    out.layoutPositioning = node.layoutPositioning;
+  }
+  return out;
+}
+
+async function readFocusTree(node) {
+  const focus = await readFocusNode(node, { withEffects: true });
+  focus.children = [];
+  for (const child of node.children || []) {
+    focus.children.push(await readFocusNode(child, { withEffects: false }));
+  }
+  return focus;
+}
+
+// The getter throws when Figma flags the set as conflicting (duplicate variant
+// combinations). Fall back to the axes the children declare, so the structural
+// check names the duplicates instead of the read throwing.
+function groupProperties(set) {
+  try {
+    return set.variantGroupProperties;
+  } catch {
+    const axes = {};
+    for (const child of set.children) {
+      for (const axis of Object.keys(child.variantProperties || {})) axes[axis] = { values: [] };
+    }
+    return axes;
+  }
+}
+
+async function readComponentSet(expect) {
+  await figma.currentPage.loadAsync();
+  const frameName = `WIP: ${expect.name}`;
+  const frame = figma.currentPage.findOne((n) => n.name === frameName);
+  if (!frame) throw new Error(`no node named "${frameName}" on the current page`);
+  const set = frame.type === 'COMPONENT_SET' ? frame : (frame.children || []).find((c) => c.type === 'COMPONENT_SET');
+  // A frame holding plain FRAMEs where the set should be is a failed assertion,
+  // not a missing target: report what is there so the structural check names it.
+  if (!set) {
+    const first = (frame.children || [])[0];
+    return { type: first ? first.type : 'NONE', variantGroupProperties: {}, children: [] };
+  }
+
+  const isFocusState = (props) =>
+    Object.entries(props || {}).some(([k, v]) => {
+      const state = normalizeName(v);
+      return normalizeName(k) === 'state' && state === 'focus';
+    });
+
+  const children = [];
+  for (const child of set.children) {
+    const read = { type: child.type, variantProperties: child.variantProperties };
+    if (child.type === 'COMPONENT' && isFocusState(child.variantProperties)) {
+      Object.assign(read, await readFocusTree(child));
+      if (expect.controlLayer !== undefined && expect.controlLayer !== null) {
+        const layer = child.findOne((n) => n.name === expect.controlLayer);
+        read.controlLayer = layer ? await readFocusTree(layer) : null;
+      }
+    }
+    children.push(read);
+  }
+  return {
+    type: set.type,
+    variantGroupProperties: groupProperties(set),
+    children,
+  };
+}
+
+async function runFigmaChecks(EXPECT, MODE) {
+  if (MODE === 'spec') return checkSpec(EXPECT);
+  if (MODE === 'built') return checkBuilt(await readComponentSet(EXPECT), EXPECT);
+  throw new Error(`MODE must be 'spec' or 'built', got ${JSON.stringify(MODE)}`);
+}

package/scripts/lib/figma-checks.mjs

@@ -0,0 +1,240 @@
+// The Figma stop conditions as a pure checker: the COMPONENT_SET assertion against
+// the full variant matrix, the state matrix, and the focus ring. ZERO imports,
+// `export const`/`export function` only. This module is inlined, with
+// component-states.mjs above it, into the generated Figma script
+// (references/figma-checks.md) by build-figma-checks.mjs, so it must run in both
+// Node and the Figma plugin sandbox.
+//
+// The state table is not imported. `withTable({ resolveArchetype, BASELINE_STATES,
+// STATE_SYNONYMS, normalizeName })` takes it, and the fold, from the caller and
+// returns { checkSpec, checkBuilt }. In the generated script the caller passes the
+// inlined component-states.mjs names; in tests it passes the module's own exports.
+//
+// Spec: docs/specs/2026-10-07-figma-checks-as-scripts.md
+// Rules: references/figma-component-standards.md (State handling; audit items 8, 9)
+//
+// EXPECT: { name, matrix: { axis: [values] }, uiFramework, controlLayer? }
+//
+// SNAPSHOT (what the reader returns for the COMPONENT_SET in `WIP: <name>`):
+//   {
+//     type,                               // the set's node type, 'COMPONENT_SET'
+//     variantGroupProperties: { Axis: { values: [...] }, ... },   // only the keys are read
+//     children: [ VARIANT, ... ]
+//   }
+//   VARIANT (every child):  { type, variantProperties: { Axis: 'Value' } }
+//   A VARIANT whose state value folds to `focus` also carries FOCUS NODE fields
+//   (below), plus `controlLayer` when EXPECT names one.
+//   FOCUS NODE (the variant itself, and the controlLayer subtree):
+//     {
+//       effects: [{ type, visible, spread, colorVariable }],   // colorVariable: bound colour variable name or null
+//       strokeAlign,                                           // 'INSIDE' | 'OUTSIDE' | 'CENTER'
+//       strokeVariables: [name, ...],                          // names of variables bound to stroke colours
+//       strokeWeightBound,                                     // boundVariables.strokeWeight is present
+//       children: [{ layoutPositioning, strokeAlign, strokeVariables, strokeWeightBound }]   // direct children only
+//     }
+//   VARIANT.controlLayer: a FOCUS NODE, or null when EXPECT names a layer the variant does not have.
+//   Variable names are resolved by the reader and only for focus variants and their controlLayer.
+//
+// RESULT: { pass, checks: [{ name, result: 'pass' | 'fail' | 'skip', detail }] }
+//   `pass` ignores skips. A failed assertion is data; nothing here throws.
+
+// The in-scope `uiFramework` values and the focus recipe each one uses. An absent or
+// null `uiFramework` uses the `ring` recipe. Any other value is out of scope.
+//   ring    - DROP_SHADOW effect with a focus-bound colour and spread > 0, or an
+//             ABSOLUTE ring child with an OUTSIDE stroke bound to a focus variable
+//   mui     - an input: the control's own stroke and its weight are bound; any other
+//             component uses the ring recipe
+//   outline - the control or a direct child carries an OUTSIDE stroke bound to a
+//             focus variable
+export const FRAMEWORKS = {
+  shadcn: { recipe: 'ring' },
+  tailwind: { recipe: 'ring' },
+  mui: { recipe: 'mui' },
+  'vanilla-css': { recipe: 'outline' },
+  vanilla: { recipe: 'outline' },
+};
+
+function frameworkRecipe(uiFramework) {
+  if (uiFramework === undefined || uiFramework === null) return 'ring';
+  return Object.prototype.hasOwnProperty.call(FRAMEWORKS, uiFramework)
+    ? FRAMEWORKS[uiFramework].recipe
+    : null;
+}
+
+// A focus variable is any variable whose name has a `focus` segment:
+// `border/focus`, `color/border/focus` and `color/focus/ring` count; `focusRing` and
+// a raw colour (null) do not.
+function isFocusVariable(name) {
+  return typeof name === 'string' && name.split('/').some((seg) => seg.trim().toLowerCase() === 'focus');
+}
+
+// A choice control may carry selection on its own axis instead of as a `selected`
+// value on the state axis: the sample's Checkbox has `checked: false | true |
+// indeterminate`. An axis with one of these names satisfies `selected`.
+const SELECTION_AXES = ['selected', 'checked', 'on'];
+
+const hasFocusStroke = (node) => (node.strokeVariables ?? []).some(isFocusVariable);
+
+function lacksRing(target, recipe, isInput) {
+  const children = target.children ?? [];
+  if (recipe === 'mui' && isInput) {
+    const lacks = [];
+    if (!hasFocusStroke(target)) lacks.push('a stroke bound to a focus variable');
+    if (!target.strokeWeightBound) lacks.push('a stroke weight bound to a variable');
+    return lacks;
+  }
+  if (recipe === 'outline') {
+    const outside = (n) => n.strokeAlign === 'OUTSIDE' && hasFocusStroke(n);
+    return outside(target) || children.some(outside)
+      ? []
+      : ['an OUTSIDE stroke bound to a focus variable on the control or a direct child'];
+  }
+  const shadow = (target.effects ?? []).some(
+    (e) => e.type === 'DROP_SHADOW' && e.visible !== false && e.spread > 0 && isFocusVariable(e.colorVariable),
+  );
+  const ringChild = children.some(
+    (c) => c.layoutPositioning === 'ABSOLUTE' && c.strokeAlign === 'OUTSIDE' && hasFocusStroke(c),
+  );
+  return shadow || ringChild
+    ? []
+    : [
+        'a DROP_SHADOW with spread > 0 and a colour bound to a focus variable, or an ABSOLUTE ring child with an OUTSIDE stroke bound to a focus variable',
+      ];
+}
+
+export function withTable({ resolveArchetype, BASELINE_STATES, STATE_SYNONYMS, normalizeName }) {
+  const fold = normalizeName;
+  const foldState = (value) => {
+    const name = fold(value);
+    return STATE_SYNONYMS[name] ?? name;
+  };
+  const result = (checks) => ({ pass: checks.every((c) => c.result !== 'fail'), checks });
+  const label = (props) =>
+    Object.entries(props ?? {})
+      .map(([k, v]) => `${k}=${v}`)
+      .join(', ');
+
+  // Combinations as comparable strings, axes sorted by folded name.
+  const comboKey = (props) =>
+    Object.entries(props ?? {})
+      .map(([k, v]) => [fold(k), fold(v)])
+      .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+      .map(([k, v]) => `${k}=${v}`)
+      .join(', ');
+
+  function crossProduct(matrix) {
+    let combos = [{}];
+    for (const [axis, values] of Object.entries(matrix ?? {})) {
+      combos = combos.flatMap((combo) => values.map((value) => ({ ...combo, [axis]: value })));
+    }
+    return combos;
+  }
+
+  function structural(snapshot, expect) {
+    const name = 'structural-read-back';
+    const problems = [];
+    if (snapshot.type !== 'COMPONENT_SET') problems.push(`the node is ${snapshot.type}, not a COMPONENT_SET`);
+    const children = snapshot.children ?? [];
+    const notComponents = children.filter((c) => c.type !== 'COMPONENT');
+    if (notComponents.length > 0) {
+      problems.push(`${notComponents.length} of ${children.length} children are not COMPONENTs (${[...new Set(notComponents.map((c) => c.type))].join(', ')})`);
+    }
+
+    const builtAxes = Object.keys(snapshot.variantGroupProperties ?? {}).map(fold).sort();
+    const wantAxes = Object.keys(expect.matrix ?? {}).map(fold).sort();
+    const missingAxes = wantAxes.filter((a) => !builtAxes.includes(a));
+    const extraAxes = builtAxes.filter((a) => !wantAxes.includes(a));
+    if (missingAxes.length) problems.push(`missing axes: ${missingAxes.join(', ')}`);
+    if (extraAxes.length) problems.push(`extra axes: ${extraAxes.join(', ')}`);
+
+    const want = new Map(crossProduct(expect.matrix).map((combo) => [comboKey(combo), label(combo)]));
+    const seen = new Map();
+    const duplicates = [];
+    for (const child of children) {
+      const key = comboKey(child.variantProperties);
+      if (seen.has(key)) duplicates.push(label(child.variantProperties));
+      else seen.set(key, label(child.variantProperties));
+    }
+    const missing = [...want].filter(([key]) => !seen.has(key)).map(([, text]) => text);
+    const extra = [...seen].filter(([key]) => !want.has(key)).map(([, text]) => text);
+    if (missing.length) problems.push(`missing combinations: ${missing.join(' | ')}`);
+    if (extra.length) problems.push(`extra combinations: ${extra.join(' | ')}`);
+    if (duplicates.length) problems.push(`duplicate combinations: ${duplicates.join(' | ')}`);
+
+    return problems.length
+      ? { name, result: 'fail', detail: problems.join('; ') }
+      : { name, result: 'pass', detail: `COMPONENT_SET with ${children.length} COMPONENT variants matching the matrix` };
+  }
+
+  // `entries` are [axisName, value] pairs; only the `state` axis is read.
+  function stateBaseline(expect, entries) {
+    const name = 'state-baseline';
+    const archetype = resolveArchetype({ name: expect.name });
+    if (archetype === null) {
+      return { name, result: 'skip', detail: `"${expect.name}" is not a name in the state table` };
+    }
+    const baseline = BASELINE_STATES[archetype];
+    if (baseline.length === 0) {
+      return { name, result: 'skip', detail: `"${expect.name}" is a ${archetype}, which owes no states beyond default` };
+    }
+    const present = new Set(entries.filter(([axis]) => fold(axis) === 'state').map(([, value]) => foldState(value)));
+    if (entries.some(([axis]) => SELECTION_AXES.includes(fold(axis)))) present.add('selected');
+    const required = ['default', ...baseline];
+    const missing = required.filter((s) => !present.has(foldState(s)));
+    return missing.length
+      ? { name, result: 'fail', detail: `the state axis is missing: ${missing.join(', ')}` }
+      : { name, result: 'pass', detail: `the state axis has default and every ${archetype} state` };
+  }
+
+  function focusIndicator(snapshot, expect) {
+    const name = 'focus-indicator';
+    const archetype = resolveArchetype({ name: expect.name });
+    if (archetype === null) {
+      return { name, result: 'skip', detail: `"${expect.name}" is not a name in the state table` };
+    }
+    if (BASELINE_STATES[archetype].length === 0) {
+      return { name, result: 'skip', detail: `"${expect.name}" is a ${archetype}, which owes no states, so no focus ring is checked` };
+    }
+    const recipe = frameworkRecipe(expect.uiFramework);
+    if (recipe === null) {
+      return { name, result: 'skip', detail: `uiFramework "${expect.uiFramework}" is out of scope for the focus check` };
+    }
+    const isFocusVariant = (child) =>
+      child.type === 'COMPONENT' &&
+      Object.entries(child.variantProperties ?? {}).some(([k, v]) => fold(k) === 'state' && fold(v) === 'focus');
+    const variants = (snapshot.children ?? []).filter(isFocusVariant);
+    if (variants.length === 0) {
+      return { name, result: 'fail', detail: 'no COMPONENT variant has a state of focus, so no ring can be read; the state check stops on this' };
+    }
+    const misses = [];
+    for (const variant of variants) {
+      let target = variant;
+      if (expect.controlLayer !== undefined && expect.controlLayer !== null) {
+        target = variant.controlLayer;
+        if (!target) {
+          misses.push(`${label(variant.variantProperties)}: no layer named "${expect.controlLayer}"`);
+          continue;
+        }
+      }
+      const lacks = lacksRing(target, recipe, archetype === 'input');
+      if (lacks.length) misses.push(`${label(variant.variantProperties)}: lacks ${lacks.join(' and ')}`);
+    }
+    return misses.length
+      ? { name, result: 'fail', detail: misses.join('; ') }
+      : { name, result: 'pass', detail: `all ${variants.length} focus variants carry a ${recipe}-recipe focus indicator` };
+  }
+
+  // Before anything is written: the matrix the spec asks for against the state table.
+  function checkSpec(expect) {
+    const entries = Object.entries(expect.matrix ?? {}).flatMap(([axis, values]) => values.map((v) => [axis, v]));
+    return result([stateBaseline(expect, entries)]);
+  }
+
+  // After the build: the node as read.
+  function checkBuilt(snapshot, expect) {
+    const entries = (snapshot.children ?? []).flatMap((c) => Object.entries(c.variantProperties ?? {}));
+    return result([structural(snapshot, expect), stateBaseline(expect, entries), focusIndicator(snapshot, expect)]);
+  }
+
+  return { checkSpec, checkBuilt };
+}