@radicool/throughline 0.25.0 → 0.27.0

package/scripts/README.md

@@ -25,16 +25,20 @@ tested here; copied verbatim by `token-crosswalk-builder` into the user's
 | `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, the focus ring, and the focus ring's 3:1 contrast against the surfaces it's named to sit on, 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/figma-variables-read.figma.js` | Figma helpers that resolve a colour variable's value in each mode, through aliases. Inlined into both `references/figma-checks.md` and `references/figma-adherence.md`; never executed as a module. | plugin-internal (not installed) |
+| `lib/figma-variables-read.figma.js` | Figma helpers that resolve a colour variable's value in each mode, through aliases. Inlined into `references/figma-checks.md`, `references/figma-adherence.md` and `references/figma-compose.md`; never executed as a module. | plugin-internal (not installed) |
 | `lib/figma-adherence.mjs` | Pure checker for the Figma screen adherence gate: detached components, and raw colours, gaps, padding and radii that a variable has. A raw value no variable has is an advisory. Inlined into `references/figma-adherence.md`; unit-tested against `lib/fixtures/figma-adherence/`. | plugin-internal (not installed) |
-| `lib/figma-adherence-read.figma.js` | Figma reader that turns the screens on one page into the adherence checker's snapshot JSON, read-only. Inlined into `references/figma-adherence.md`; never executed as a module. | plugin-internal (not installed) |
+| `lib/figma-adherence-read.figma.js` | Figma reader that turns the screens on one page into the adherence checker's snapshot JSON, read-only, including content added to an instance's slots. Inlined into `references/figma-adherence.md`; never executed as a module. | plugin-internal (not installed) |
+| `lib/figma-compose.mjs` | Pure resolver for composing a Figma screen: checks a screen description against the file's component sets, variables and text styles, and returns every error or a plan of real keys and ids. Inlined into `references/figma-compose.md`; unit-tested against `lib/fixtures/figma-compose/`. `compose-code.mjs` imports its `nearestNames`. | run from the plugin (or `.throughline/scripts`) by `compose-code.mjs`; not copied into consumer repos |
+| `lib/figma-compose.figma.js` | Figma reader and writer for screen composition: reads the inventory, builds a `WIP:` screen from the resolver's plan with every value bound, and finalizes or discards it. Inlined into `references/figma-compose.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. Also inlined into `references/figma-checks.md` for the focus-ring contrast check. | copied alongside `verify-check.mjs`; also inlined into the generated Figma checks |
+| `doc-card-payload.mjs` | Assemble the complete `figma_execute` body that renders one doc card — record, canonical fingerprint, the nine `figma.docCardVariables` lookups, `Body/Default`, the generated snippet and the call — and print the `renderHash` the render must return, so a payload that changed on the way in is caught. Reads the snippet from `../references/doc-card-builder.md`. | run from the plugin (or `.throughline/scripts`); not copied into consumer repos |
+| `compose-code.mjs` | Composing a screen in code: `inventory` lists the system's components with their variant axes from `components.built` and the docs index, `check` resolves a screen's plan before any code is written and returns every gap with the nearest names, and `gate` runs the adherence gate on the one composed file plus three rules only a composed file is held to (`raw-value`, `scale-utility`, `off-plan`). Used by `/throughline:compose-code`. | run from the plugin (or `.throughline/scripts`); not copied into consumer repos |
 | `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`, `lib/contrast.mjs`, `lib/figma-checks.mjs` and `lib/figma-variables-read.figma.js` above the reader (`lib/figma-checks-read.figma.js`); and `references/figma-adherence.md`, the screen adherence gate, from `lib/figma-adherence.mjs`, `lib/figma-variables-read.figma.js` and `lib/figma-adherence-read.figma.js`. `--check` gates CI on both. | 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`, `lib/contrast.mjs`, `lib/figma-checks.mjs` and `lib/figma-variables-read.figma.js` above the reader (`lib/figma-checks-read.figma.js`); `references/figma-adherence.md`, the screen adherence gate, from `lib/figma-adherence.mjs`, `lib/figma-variables-read.figma.js` and `lib/figma-adherence-read.figma.js`; and `references/figma-compose.md`, screen composition, from `lib/figma-adherence.mjs`, `lib/figma-compose.mjs`, `lib/figma-variables-read.figma.js` and `lib/figma-compose.figma.js`. `--check` gates CI on all three. | 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) |
 
@@ -252,7 +256,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.25.0 init --target=cursor|codex|generic
+    npx @radicool/throughline@0.27.0 init --target=cursor|codex|generic
 
 See `scripts/install.mjs` (pure core + CLI + `install.test.mjs`).
 

package/scripts/build-doc-card-builder.mjs

@@ -29,6 +29,18 @@ const HEADER = [
   '',
   '## How to call it',
   '',
+  'Steps 1–4 are one command once `figma.docCardVariables` is recorded:',
+  '',
+  '```sh',
+  'node scripts/doc-card-payload.mjs design-system/docs/components/<Name>.doc.json <cardNodeId> --out <scratch>/payload.js',
+  '```',
+  '',
+  'It writes the complete `figma_execute` body — record, fingerprint, the nine',
+  'role lookups by recorded name, `Body/Default`, the snippet and the call — and',
+  'prints the `expectedRenderHash` to stderr. Pass the file\'s contents as the',
+  '`code` unchanged, then do steps 5–6. The steps below are what it does, and',
+  'what to do by hand when the mapping isn\'t recorded yet.',
+  '',
   '1. Load the record and compute its canonical fingerprint in Node',
   '   (`canonicalFingerprint` in `scripts/lib/doc-record.mjs`).',
   '2. Read `figma.docCardVariables` from `design-system.json`.',
@@ -97,6 +109,10 @@ const HEADER = [
   '   `cardWidth` — not from a screenshot, then stamp the manifest from it:',
   '   `surfaces.docCard = { src: summary.fingerprint, render: summary.renderHash,',
   '   renderer: summary.rendererVersion }`. Never re-read the card to stamp.',
+  '   With the payload script, first check `summary.renderHash` equals the',
+  '   `expectedRenderHash` it printed. A mismatch means the payload changed on',
+  '   the way in, or `Body/Default` isn\'t the size the script assumed — the',
+  '   summary\'s `bodyFontSize` says which; re-run with `--font-size`.',
   '',
   '## The snippet',
   '',

package/scripts/build-figma-checks.mjs

@@ -8,8 +8,11 @@
 //   references/figma-adherence.md — the screen adherence gate: the pure checker
 //     (lib/figma-adherence.mjs), then lib/figma-variables-read.figma.js and the
 //     screen reader (lib/figma-adherence-read.figma.js).
-// Mirrors build-doc-card-builder.mjs: run bare to write both, run with --check to
-// gate CI on both. Zero dependencies.
+//   references/figma-compose.md — screen composition: lib/figma-adherence.mjs (for
+//     dimensionBuckets), the pure resolver (lib/figma-compose.mjs),
+//     lib/figma-variables-read.figma.js, then the writer (lib/figma-compose.figma.js).
+// Mirrors build-doc-card-builder.mjs: run bare to write all three, run with --check
+// to gate CI on all three. Zero dependencies.
 import { readFileSync, writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -22,8 +25,11 @@ const READER = join(REPO_ROOT, 'scripts', 'lib', 'figma-checks-read.figma.js');
 const VARIABLES = join(REPO_ROOT, 'scripts', 'lib', 'figma-variables-read.figma.js');
 const ADHERENCE = join(REPO_ROOT, 'scripts', 'lib', 'figma-adherence.mjs');
 const ADHERENCE_READER = join(REPO_ROOT, 'scripts', 'lib', 'figma-adherence-read.figma.js');
+const COMPOSE = join(REPO_ROOT, 'scripts', 'lib', 'figma-compose.mjs');
+const COMPOSE_WRITER = join(REPO_ROOT, 'scripts', 'lib', 'figma-compose.figma.js');
 const OUT = join(REPO_ROOT, 'references', 'figma-checks.md');
 const ADHERENCE_OUT = join(REPO_ROOT, 'references', 'figma-adherence.md');
+const COMPOSE_OUT = join(REPO_ROOT, 'references', 'figma-compose.md');
 
 const BIND = 'const { checkSpec, checkBuilt, checkExisting } = withTable({ resolveArchetype, BASELINE_STATES, STATE_SYNONYMS, normalizeName, contrastRatio, composite, parseHex, AA_NON_TEXT });';
 
@@ -143,6 +149,73 @@ const ADHERENCE_HEADER = [
   '```js',
 ].join('\n');
 
+const COMPOSE_HEADER = [
+  '# Figma screen composition (GENERATED)',
+  '',
+  '> **GENERATED FILE — do not edit by hand.** Sources: `scripts/lib/figma-adherence.mjs`',
+  '> (for `dimensionBuckets`), `scripts/lib/figma-compose.mjs` (the pure resolver,',
+  '> unit-tested in Node), `scripts/lib/figma-variables-read.figma.js` +',
+  '> `scripts/lib/figma-compose.figma.js` (the reader and writer). Regenerate with',
+  '> `node scripts/build-figma-checks.mjs`; CI gates freshness with `--check`.',
+  '',
+  'The canonical `figma_execute` snippet that composes a screen from the file\'s own',
+  'component sets, variables and text styles. A screen is a short JSON description',
+  'written only in those names (its shape is the `DESCRIPTION` comment in the',
+  'snippet, at the top of the resolver).',
+  'The whole description is checked before anything is written: an unknown component,',
+  'property, option, variable or text style, a variable of the wrong kind, or a name',
+  'already held by a screen a person made, comes back as a list of errors and the file',
+  'is untouched. A component the file lacks is a `missing-component` error with the',
+  'nearest names: report it as a gap, never draw a lookalike. Every value the script',
+  'writes is bound to a variable. The script is the rule; do not re-write it by hand.',
+  '',
+  '## How to call it',
+  '',
+  '1. Paste the snippet below into `figma_execute` with `timeout: 30000`, and end it',
+  '   with `return await runCompose(MODE, SPEC);`, one mode per call:',
+  '   - `\'inventory\'`, `SPEC = { componentsPage, iconsPage }`: read-only. Returns',
+  '     `{ summary }`: each set\'s properties and options and whether it has auto',
+  '     layout, swap targets, variables by kind (colour, gap, radius), text styles and',
+  '     modes. Plan only from these names.',
+  '     `iconsPage` is optional; pass it when a swap property needs its targets.',
+  '   - `\'build\'`, `SPEC = { componentsPage, iconsPage, description, fileKey }`:',
+  '     returns `{ ok: false, errors }` with nothing written, or builds the screen into',
+  '     a top-level frame `WIP: <screen>` on the description\'s page (created if',
+  '     missing) and returns `{ ok: true, wipId, wipName, link, ms }`. A throw during',
+  '     the write removes the `WIP:` frame (and a page the build created) before it',
+  '     rethrows, so nothing is left half-built: report it as a composer bug.',
+  '   - `\'finalize\'`, `SPEC = { page, screen, fileKey }`: renames `WIP: <screen>` to',
+  '     `<screen>`, replacing a screen of that name only if throughline composed it.',
+  '     Returns `{ id, link, replaced }`.',
+  '   - `\'discard\'`, `SPEC = { page, screen }`: removes `WIP: <screen>`. Only when',
+  '     the user asks.',
+  '2. Between `build` and `finalize`, run the screen gate',
+  '   (`references/figma-adherence.md`) with `screens: [\'WIP: <screen>\']`. Finalize',
+  '   only a passing screen. A failure is a composer bug: report it and leave the',
+  '   `WIP:` frame.',
+  '3. Pages are found by exact name, or else the one page whose trimmed name matches.',
+  '   Only the named pages are loaded. Components and variables are the file\'s local',
+  '   ones.',
+  '',
+  '```js',
+  'const MODE = \'build\';',
+  'const SPEC = { componentsPage: \'Components\', iconsPage: \'Icons\', fileKey: \'<figma.fileKey>\', description: {',
+  '  screen: \'Sign in\', page: \'Screens\', width: 390, modes: { \'Color / Semantic\': \'Light\' },',
+  '  root: { layout: \'vertical\', gap: \'space/gap/md\', padding: \'space/inset/lg\', fill: \'color/bg/canvas\', children: [',
+  '    { text: \'Sign in\', style: \'Heading/L\', color: \'color/text/primary\' },',
+  '    { component: \'Input\', props: { placeholder: \'Email\' }, sizing: { horizontal: \'fill\' } },',
+  '    { component: \'Button\', props: { label: \'Sign in\', hasTrailing: true, trailingIcon: \'icon/arrow-right\' } },',
+  '  ] },',
+  '} };',
+  '// … the generated snippet …',
+  'return await runCompose(MODE, SPEC);',
+  '```',
+  '',
+  '## The snippet',
+  '',
+  '```js',
+].join('\n');
+
 const FOOTER = ['```', ''].join('\n');
 
 const stripExports = (src) =>
@@ -170,6 +243,13 @@ export function buildFigmaAdherence({ checkerSource, variablesSource, readerSour
   return `${ADHERENCE_HEADER}\n${checker}\n${variablesSource}\n${readerSource}${FOOTER}`;
 }
 
+export function buildFigmaCompose({ adherenceSource, composeSource, variablesSource, writerSource }) {
+  const adherence = stripExports(adherenceSource);
+  const compose = stripExports(composeSource);
+  assertInlinable([['figma-adherence.mjs', adherence], ['figma-compose.mjs', compose], ['figma-variables-read.figma.js', variablesSource], ['figma-compose.figma.js', writerSource]]);
+  return `${COMPOSE_HEADER}\n${adherence}\n${compose}\n${variablesSource}\n${writerSource}${FOOTER}`;
+}
+
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   const result = buildFigmaChecks({
     statesSource: readFileSync(STATES, 'utf8'),
@@ -183,9 +263,16 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
     variablesSource: readFileSync(VARIABLES, 'utf8'),
     readerSource: readFileSync(ADHERENCE_READER, 'utf8'),
   });
+  const compose = buildFigmaCompose({
+    adherenceSource: readFileSync(ADHERENCE, 'utf8'),
+    composeSource: readFileSync(COMPOSE, 'utf8'),
+    variablesSource: readFileSync(VARIABLES, 'utf8'),
+    writerSource: readFileSync(COMPOSE_WRITER, 'utf8'),
+  });
   const outputs = [
     [OUT, result, 'references/figma-checks.md', 'figma checks'],
     [ADHERENCE_OUT, adherence, 'references/figma-adherence.md', 'figma adherence'],
+    [COMPOSE_OUT, compose, 'references/figma-compose.md', 'figma compose'],
   ];
   if (process.argv.includes('--check')) {
     let stale = false;

package/scripts/compose-code.mjs

@@ -0,0 +1,271 @@
+// Composing a screen in code: the inventory a composer may use, a check of its
+// plan before any code is written, and the gate a composed file must pass. Run
+// by /throughline:compose-code from the plugin (or .throughline/scripts).
+//
+//   node scripts/compose-code.mjs inventory --system <dir> --package <spec>
+//   node scripts/compose-code.mjs check --system <dir> --package <spec> --plan <plan.json>
+//   node scripts/compose-code.mjs gate --system <dir> --package <spec> --plan <plan.json>
+//        --file <screen.tsx> --tokens <file> [--tokens <file>...]
+//
+// PLAN: { screen, file, components: [{ name, variants?: { [axis]: value } }] }
+//   `file` is resolved against the working directory. Sub-parts (CardHeader)
+//   come with their owner and need no entry. `gate` compares the file to the
+//   resolved plan, case-folded.
+//
+// Exit: 0 ok, 1 errors or failures, 2 usage or unreadable input.
+//
+// Spec: docs/specs/2026-10-13-compose-code-screen.md
+import { readFileSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { pathToFileURL } from 'node:url';
+import { normalizeName } from './lib/source-scan.mjs';
+import { nearestNames } from './lib/figma-compose.mjs';
+import {
+  extract, validate, formatReport, partOwner, blankComments,
+  buildTokenValues, skippedColourTokens, buildDimensionValues,
+} from './validate-adherence.mjs';
+
+export const COMPOSED_MARKER = (screen) => `// Composed by throughline: ${screen}.`;
+const MARKER_LINE = /^\/\/ Composed by throughline: (.*)\.$/;
+const DIRECTIVE = /^(['"])use [a-z]+\1;?$/;
+
+// The screen a file's marker names, '' for a file with no marker. The marker is
+// line 1, or line 2 after a directive ('use client').
+export function readMarker(text) {
+  const lines = String(text).split('\n').map((l) => l.trim());
+  const at = DIRECTIVE.test(lines[0] ?? '') ? 1 : 0;
+  return lines[at]?.match(MARKER_LINE)?.[1] ?? '';
+}
+
+export function codeInventory({ manifest, index, pkg }) {
+  const records = new Map((index?.components ?? []).map((c) => [normalizeName(c.name), c]));
+  const components = (manifest?.components?.built ?? []).map((name) => {
+    const r = records.get(normalizeName(name));
+    if (!r) return { name, documented: false, variants: {}, states: [] };
+    return {
+      name,
+      documented: true,
+      summary: r.summary,
+      whenToUse: r.whenToUse ?? [],
+      whenNotToUse: r.whenNotToUse ?? [],
+      variants: Object.fromEntries(Object.entries(r.variants ?? {}).map(([axis, values]) => [axis, Object.keys(values)])),
+      states: Object.keys(r.states ?? {}),
+    };
+  });
+  return { package: pkg, components };
+}
+
+const fold = (s) => normalizeName(s);
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+// existing: null (no file at plan.file) or the marker's screen name ('' unmarked).
+export function checkPlan(plan, inventory, { existing = null } = {}) {
+  const errors = [];
+  const err = (kind, path, asked, extra = {}) => errors.push({ kind, path, asked, ...extra });
+
+  if (!isObject(plan)) return { ok: false, errors: [{ kind: 'invalid', path: '', asked: plan }], plan: null };
+  for (const key of Object.keys(plan)) {
+    if (!['screen', 'file', 'components'].includes(key)) err('invalid', key, plan[key]);
+  }
+  if (typeof plan.screen !== 'string' || !plan.screen.trim()) err('invalid', 'screen', plan.screen);
+  if (typeof plan.file !== 'string' || !plan.file.trim()) err('invalid', 'file', plan.file);
+  if (!Array.isArray(plan.components)) err('invalid', 'components', plan.components);
+
+  if (existing !== null && existing !== plan.screen) err('name-taken', 'file', plan.file, { marked: existing || null });
+
+  const resolved = [];
+  for (const [i, c] of (Array.isArray(plan.components) ? plan.components : []).entries()) {
+    const path = `components[${i}]`;
+    if (!isObject(c) || typeof c.name !== 'string') { err('invalid', path, c); continue; }
+    for (const key of Object.keys(c)) if (!['name', 'variants'].includes(key)) err('invalid', `${path}.${key}`, c[key]);
+    const found = inventory.components.find((x) => fold(x.name) === fold(c.name));
+    // A sub-part (CardHeader) needs no entry, but one listed resolves to its owner.
+    const owner = found ? null : partOwner(c.name, inventory.components.map((x) => x.name));
+    if (owner) {
+      if (c.variants !== undefined) err('unknown-prop', `${path}.variants`, c.variants);
+      resolved.push({ name: c.name, partOf: owner, variants: {} });
+      continue;
+    }
+    if (!found) {
+      err('missing-component', `${path}.name`, c.name, { nearest: nearestNames(c.name, inventory.components.map((x) => x.name)) });
+      continue;
+    }
+    const variants = {};
+    if (c.variants !== undefined && !isObject(c.variants)) err('invalid', `${path}.variants`, c.variants);
+    for (const [axis, value] of Object.entries(isObject(c.variants) ? c.variants : {})) {
+      const realAxis = Object.keys(found.variants).find((a) => fold(a) === fold(axis));
+      if (!realAxis) { err('unknown-prop', `${path}.variants.${axis}`, axis); continue; }
+      const realValue = found.variants[realAxis].find((v) => fold(v) === fold(value));
+      if (!realValue) { err('unknown-option', `${path}.variants.${axis}`, value, { options: found.variants[realAxis] }); continue; }
+      variants[realAxis] = realValue;
+    }
+    resolved.push({ name: found.name, variants });
+  }
+
+  const ok = errors.length === 0;
+  return { ok, errors, plan: ok ? { screen: plan.screen, file: plan.file, components: resolved } : null };
+}
+
+// Default-scale Tailwind spacing, sizing, type-size and weight utilities, after
+// any variants (`md:`) and as negatives. Throughline's generated preset extends
+// only colours, radius and font family, so these are Tailwind's own values, not
+// tokens. Read anywhere in the file, so cn() and template strings count. Passes:
+// 0, fractions (`w-1/2`), keywords (`full`, `auto`, `screen`), preset names
+// (`text-primary`, `font-sans`) and `[var(--…)]`.
+const SCALE_UTILITY =
+  /(?<![\w-])(?:[\w-]+:)*-?(?:(?:p[xytrblse]?|m[xytrblse]?|gap(?:-[xy])?|space-[xy]|w|h|size|min-w|min-h|max-w|max-h|inset(?:-[xy])?|top|right|bottom|left|text|leading|tracking)-(?:0\.\d+|[1-9]\d*(?:\.\d+)?|px|xs|sm|base|lg|xl|[2-9]xl)|font-(?:thin|extralight|light|normal|medium|semibold|bold|extrabold|black))(?![\w/-])/g;
+// Sizing the gate doesn't read: an arbitrary size that isn't a variable, and a
+// width or height declaration with a raw length (percentages are layout).
+const RAW_SIZE = [
+  /(?<![\w-])(?:[\w-]+:)*(?:w|h|size|min-w|min-h|max-w|max-h)-\[(?!var\()(?!\d+(?:\.\d+)?(?:%|[dsl]?v[hw])\])[^\]\s]+\]/g,
+  /(?<![\w-])(?:min-?|max-?)?(?:[wW]idth|[hH]eight)\s*:\s*['"]?-?(?:\d+(?:\.\d+)?|\.\d+)(?:px|rem|em)?(?![\w%.])/g,
+];
+const NATIVE_CONTROL = /<(button|input|select|textarea)\b/g;
+// Every module reference: a static import (named, default, namespace,
+// type-only, side-effect), a re-export, a dynamic import() and a require().
+const ANY_IMPORT = [
+  /^\s*(?:import|export)\s+(?:[^'";]*?\s+from\s+)?['"]([^'"]+)['"]/gm,
+  /(?<![\w$.])(?:import|require)\s*\(\s*['"]([^'"]+)['"]/g,
+];
+const REACT = /^react(?:-dom)?(?:\/.*)?$/;
+
+const lineOf = (text, i) => text.slice(0, i).split('\n').length;
+
+export function gateFile({ file, text, plan, manifest, index, tokenDicts, pkg }) {
+  const marked = readMarker(text);
+  const extracted = extract(text, pkg, file);
+  const r = validate({
+    built: manifest?.components?.built ?? [],
+    index,
+    tokenValues: buildTokenValues(tokenDicts),
+    colourSkipped: skippedColourTokens(tokenDicts),
+    dimensionValues: buildDimensionValues(tokenDicts),
+    files: [{ path: file, ...extracted }],
+    walked: 1,
+  });
+
+  // On one file, known components that set no variant prop are normal; the plan
+  // check already validated every variant value against the same index.
+  const failures = r.failures.filter((f) => f.rule !== 'variant-rule-inert');
+  const advisories = [...r.advisories, ...r.failures.filter((f) => f.rule === 'variant-rule-inert')];
+
+  // Without the marker, the next run treats this file as a person's.
+  if (marked !== plan?.screen) failures.push({ rule: 'marker', written: marked || '(none)', expected: plan?.screen, file, line: 1 });
+
+  for (const l of extracted.literals) failures.push({ rule: 'raw-value', written: l.value, file, line: l.line });
+  for (const d of extracted.dimensions) failures.push({ rule: 'raw-value', written: d.written, file, line: d.line });
+
+  const code = blankComments(text, file);
+  for (const re of RAW_SIZE) for (const m of code.matchAll(re)) failures.push({ rule: 'raw-value', written: m[0], file, line: lineOf(code, m.index) });
+  for (const m of code.matchAll(SCALE_UTILITY)) failures.push({ rule: 'scale-utility', written: m[0], file, line: lineOf(code, m.index) });
+  for (const re of ANY_IMPORT) for (const m of code.matchAll(re)) {
+    const from = m[1];
+    if (from === pkg || from.startsWith(`${pkg}/`) || REACT.test(from)) continue;
+    failures.push({ rule: 'off-plan', written: `import from '${from}'`, file, line: lineOf(code, m.index + m[0].search(/\S/)) });
+  }
+  for (const m of code.matchAll(NATIVE_CONTROL)) failures.push({ rule: 'off-plan', written: `<${m[1]}>`, file, line: lineOf(code, m.index) });
+
+  const planned = (plan?.components ?? []).map((c) => c.partOf ?? c.name);
+  const plannedKeys = new Set(planned.map(fold));
+  for (const e of extracted.elements) {
+    if (plannedKeys.has(fold(e.component)) || partOwner(e.component, planned)) continue;
+    failures.push({ rule: 'off-plan', written: `<${e.component}>`, file, line: e.line });
+  }
+
+  return { ...r, ok: failures.length === 0, failures, advisories };
+}
+
+const COMPOSER_RULES = {
+  marker: (f) => `${f.file} is marked for ${f.written}, not "${f.expected}" — its first line (second after a directive) must be ${COMPOSED_MARKER(f.expected)}`,
+  'raw-value': (f) => `${f.written} at ${f.file}:${f.line} — write a token variable, not a raw value`,
+  'scale-utility': (f) => `${f.written} at ${f.file}:${f.line} — Tailwind's default scale, not a token; use a token variable (\`-[var(--…)]\`)`,
+  'off-plan': (f) => f.written.startsWith('import')
+    ? `${f.written} at ${f.file}:${f.line} — a composed screen imports only from the system's package and React; anything else is a gap to report`
+    : `${f.written} at ${f.file}:${f.line} — not a planned system component; use one from the plan, or check the plan again`,
+};
+
+export function formatGateReport(r) {
+  const own = r.failures.filter((f) => COMPOSER_RULES[f.rule]);
+  const lines = formatReport({ ...r, failures: r.failures.filter((f) => !COMPOSER_RULES[f.rule]) });
+  if (own.length) {
+    lines.push(`\n${own.length} composer failure(s):`);
+    for (const f of own) lines.push(`  - [${f.rule}] ${COMPOSER_RULES[f.rule](f)}`);
+  }
+  lines.push(r.ok ? '\ncompose-code gate: pass' : '\ncompose-code gate: FAIL');
+  return lines;
+}
+
+function main() {
+  const [mode, ...rest] = process.argv.slice(2);
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args: rest,
+      options: {
+        system: { type: 'string' },
+        package: { type: 'string' },
+        tokens: { type: 'string', multiple: true, default: [] },
+        plan: { type: 'string' },
+        file: { type: 'string' },
+      },
+    }));
+  } catch (e) {
+    console.error(e.message);
+    process.exit(2);
+  }
+  const usage = () => {
+    console.error('usage: compose-code.mjs inventory|check|gate --system <dir> --package <spec> [--plan <file>] [--tokens <file> --tokens <file>...] [--file <path>]');
+    process.exit(2);
+  };
+  if (!['inventory', 'check', 'gate'].includes(mode) || !values.system || !values.package) usage();
+  if (mode !== 'inventory' && !values.plan) usage();
+  if (mode === 'gate' && (!values.file || values.tokens.length === 0)) usage();
+
+  const read = (p, what, parse = true) => {
+    try {
+      const text = readFileSync(p, 'utf8');
+      return parse ? JSON.parse(text) : text;
+    } catch (e) {
+      console.error(`cannot read ${what} at ${p}: ${e.message}`);
+      process.exit(2);
+    }
+  };
+  const manifest = read(join(values.system, 'design-system.json'), 'the manifest');
+  const index = read(join(values.system, 'design-system/docs/index.json'), 'the docs index (run docs:digest first)');
+  const inventory = codeInventory({ manifest, index, pkg: values.package });
+
+  if (mode === 'inventory') {
+    console.log(JSON.stringify(inventory, null, 2));
+    return;
+  }
+
+  const plan = read(values.plan, 'the plan');
+  if (mode === 'check') {
+    const target = typeof plan?.file === 'string' ? resolve(plan.file) : null;
+    const existing = target && existsSync(target) ? readMarker(read(target, 'the target file', false)) : null;
+    const res = checkPlan(plan, inventory, { existing });
+    console.log(JSON.stringify(res, null, 2));
+    process.exit(res.ok ? 0 : 1);
+  }
+
+  // The gate holds a file to a plan check accepts, never to a rejected one.
+  const checked = checkPlan(plan, inventory);
+  if (!checked.ok) {
+    console.error(`the plan doesn't check: ${checked.errors.map((e) => `${e.kind} at ${e.path}`).join(', ')}. Run check and fix it first.`);
+    process.exit(2);
+  }
+  const r = gateFile({
+    file: values.file,
+    text: read(values.file, 'the screen file', false),
+    plan: checked.plan,
+    manifest,
+    index,
+    tokenDicts: values.tokens.map((f) => read(f, 'a token source')),
+    pkg: values.package,
+  });
+  for (const line of formatGateReport(r)) console.log(line);
+  process.exit(r.ok ? 0 : 1);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();

package/scripts/doc-card-payload.mjs

@@ -0,0 +1,115 @@
+// Assembles the complete figma_execute payload that renders one component doc
+// card — steps 1–4 of "How to call it" in references/doc-card-builder.md — so
+// the caller passes one file's contents instead of hand-splicing the record,
+// fingerprint, variable lookups and generated snippet. Also prints the
+// renderHash the render must return: the payload is pasted into the tool call,
+// and a matching hash proves it arrived intact.
+//
+//   node scripts/doc-card-payload.mjs <record.doc.json> <cardNodeId>
+//        [--manifest design-system.json] [--out payload.js] [--font-size 16]
+//
+// Zero dependencies. Reads the generated snippet from ../references, which sits
+// beside scripts/ both in the plugin and in an adapter install's .throughline/.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { canonicalFingerprint } from './lib/doc-record.mjs';
+import { planDocCard, fnv1a } from './lib/doc-card-plan.mjs';
+
+const BUILDER = join(dirname(fileURLToPath(import.meta.url)), '..', 'references', 'doc-card-builder.md');
+
+const ROLES = [
+  'textDefault', 'textMuted', 'tonePositive', 'toneNegative', 'border',
+  'spacePadding', 'spaceRowGap', 'spaceBlockGap', 'spaceItemGap',
+];
+
+// The text between "## The snippet"'s opening ```js fence and its closing fence.
+export function extractSnippet(builderMarkdown) {
+  const section = builderMarkdown.split('\n## The snippet\n')[1];
+  if (!section) throw new Error('doc-card-builder.md has no "## The snippet" section');
+  const start = section.indexOf('```js\n');
+  const end = section.lastIndexOf('\n```');
+  if (start === -1 || end <= start) throw new Error('doc-card-builder.md: snippet fence not found');
+  return section.slice(start + '```js\n'.length, end + 1);
+}
+
+export function buildPayload({ record, cardNodeId, manifest, builderMarkdown, fontSize = 16 }) {
+  if (!/^\d+:\d+$/.test(cardNodeId)) throw new Error(`cardNodeId must look like "24:773", got "${cardNodeId}"`);
+  const names = manifest && manifest.figma && manifest.figma.docCardVariables;
+  if (!names) {
+    throw new Error('design-system.json has no figma.docCardVariables — recover the nine roles from an existing card '
+      + '(step 2 of "How to call it" in references/doc-card-builder.md), write them back, then re-run');
+  }
+  const missing = ROLES.filter((r) => typeof names[r] !== 'string' || names[r] === '');
+  if (missing.length) throw new Error('figma.docCardVariables is missing role(s): ' + missing.join(', '));
+
+  const fingerprint = canonicalFingerprint(record);
+  const roleNames = Object.fromEntries(ROLES.map((r) => [r, names[r]]));
+  const code = [
+    `const RECORD = ${JSON.stringify(record)};`,
+    `const CANONICAL_FP = '${fingerprint}';`,
+    extractSnippet(builderMarkdown),
+    `const ROLE_NAMES = ${JSON.stringify(roleNames)};`,
+    'const allVars = await figma.variables.getLocalVariablesAsync();',
+    'const vars = {};',
+    'for (const [role, name] of Object.entries(ROLE_NAMES)) {',
+    '  const hits = allVars.filter((v) => v.name === name);',
+    "  if (hits.length !== 1) throw new Error('docCardVariables.' + role + ' \"' + name + '\" resolves to ' + hits.length + ' variables, not exactly one');",
+    '  vars[role] = await figma.variables.getVariableByIdAsync(hits[0].id);',
+    '}',
+    "const bodyTextStyle = (await figma.getLocalTextStylesAsync()).find((s) => s.name === 'Body/Default');",
+    `const card = await figma.getNodeByIdAsync('${cardNodeId}');`,
+    `if (!card) throw new Error('no node ${cardNodeId} in this file');`,
+    'const summary = await renderDocCard({ card, record: RECORD, vars, bodyTextStyle });',
+    'return { ...summary, bodyFontSize: bodyTextStyle.fontSize };',
+    '',
+  ].join('\n');
+
+  return {
+    code,
+    fingerprint,
+    fontSize,
+    expectedRenderHash: fnv1a(JSON.stringify(planDocCard(record, { fontSize }))),
+  };
+}
+
+function parseArgs(argv) {
+  const positional = [];
+  const opts = { manifest: 'design-system.json', out: null, fontSize: 16 };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--manifest') opts.manifest = argv[++i];
+    else if (a === '--out') opts.out = argv[++i];
+    else if (a === '--font-size') opts.fontSize = Number(argv[++i]);
+    else positional.push(a);
+  }
+  if (positional.length !== 2 || !Number.isFinite(opts.fontSize)) {
+    throw new Error('usage: node scripts/doc-card-payload.mjs <record.doc.json> <cardNodeId> [--manifest design-system.json] [--out payload.js] [--font-size 16]');
+  }
+  return { recordPath: positional[0], cardNodeId: positional[1], ...opts };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    const result = buildPayload({
+      record: JSON.parse(readFileSync(resolve(args.recordPath), 'utf8')),
+      cardNodeId: args.cardNodeId,
+      manifest: JSON.parse(readFileSync(resolve(args.manifest), 'utf8')),
+      builderMarkdown: readFileSync(BUILDER, 'utf8'),
+      fontSize: args.fontSize,
+    });
+    if (args.out) writeFileSync(resolve(args.out), result.code);
+    else process.stdout.write(result.code);
+    // Machine-readable trailer on stderr so stdout stays a clean payload.
+    console.error(JSON.stringify({
+      fingerprint: result.fingerprint,
+      expectedRenderHash: result.expectedRenderHash,
+      fontSize: result.fontSize,
+      out: args.out,
+    }));
+  } catch (err) {
+    console.error('✗ ' + err.message);
+    process.exit(1);
+  }
+}

package/scripts/install.mjs

@@ -102,9 +102,10 @@ function stagePayload(srcRoot, destRoot, skip) {
 // 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, references/figma-checks.md and
-// references/figma-adherence.md). Test fixtures
-// under lib/fixtures/ are dropped too.
+// references/doc-card-builder.md, references/figma-checks.md,
+// references/figma-adherence.md and references/figma-compose.md). Test fixtures
+// under lib/fixtures/ are dropped too. lib/figma-compose.mjs is inlined the same
+// way but stays: compose-code.mjs imports nearestNames from it.
 const PLUGIN_INTERNAL = new Set([
   'install.mjs',
   'build-doc-card-builder.mjs',
@@ -116,6 +117,7 @@ const PLUGIN_INTERNAL = new Set([
   'lib/figma-variables-read.figma.js',
   'lib/figma-adherence.mjs',
   'lib/figma-adherence-read.figma.js',
+  'lib/figma-compose.figma.js',
 ]);
 
 export const skipScript = (relPosix) =>