@radicool/throughline 0.25.0 → 0.26.0

package/scripts/README.md

@@ -25,16 +25,19 @@ 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/`. | plugin-internal (not installed) |
+| `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 |
 | `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 +255,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.26.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/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,8 +102,8 @@ 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
+// 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.
 const PLUGIN_INTERNAL = new Set([
   'install.mjs',
@@ -116,6 +116,8 @@ const PLUGIN_INTERNAL = new Set([
   'lib/figma-variables-read.figma.js',
   'lib/figma-adherence.mjs',
   'lib/figma-adherence-read.figma.js',
+  'lib/figma-compose.mjs',
+  'lib/figma-compose.figma.js',
 ]);
 
 export const skipScript = (relPosix) =>

package/scripts/lib/doc-card-plan.mjs

@@ -99,3 +99,40 @@ export function planDocCard(record, bodyTextStyle) {
     rows,
   };
 }
+
+// 32-bit FNV-1a — the render hash: fnv1a(JSON.stringify(plan)). Only ever
+// compared against itself (the manifest's surfaces.docCard.render), so it does
+// not need to match the sha256-based canonical fingerprint, which cannot run in
+// the Figma sandbox. Lives here, not in the renderer, so Node can compute the
+// hash a render should return (doc-card-payload.mjs) with the same code.
+export function fnv1a(str) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h.toString(16).padStart(8, '0');
+}
+
+// When a header's title row has no node named `Status Pill`/`Status`, name the
+// node that most likely IS the chip so the error can say what to rename. Never
+// used to pick a node to write — the renderer still refuses to guess. A
+// candidate is a FRAME below the title row whose only child is a TEXT node
+// (the chip shape: a pill frame around its label). Exactly one candidate or
+// no hint. Reads only type/name/id/characters/children, so it runs on Figma
+// nodes and on plain test objects alike.
+export function statusChipHint(titleRow) {
+  if (!titleRow || titleRow.type !== 'FRAME') return null;
+  const found = [];
+  const walk = (node) => {
+    for (const child of node.children || []) {
+      if (child.type === 'FRAME' && child.children && child.children.length === 1
+        && child.children[0].type === 'TEXT') {
+        found.push({ id: child.id, name: child.name, label: child.children[0].characters });
+      }
+      walk(child);
+    }
+  };
+  walk(titleRow);
+  return found.length === 1 ? found[0] : null;
+}

package/scripts/lib/doc-card-render.figma.js

@@ -6,20 +6,8 @@
 // BEFORE .characters, fonts loaded up front, resize() sizing modes re-asserted,
 // bound paints seeded light-gray (never pure black).
 //
-// In-scope globals when assembled: planDocCard, DOC_CARD_RENDERER_VERSION
-// (inlined planner) and the caller-filled slots RECORD, CANONICAL_FP.
-
-// 32-bit FNV-1a — the render hash. Only ever compared against itself (the
-// manifest's surfaces.docCard.render), so it does not need to match the
-// sha256-based canonical fingerprint, which cannot run in the Figma sandbox.
-function fnv1a(str) {
-  let h = 0x811c9dc5;
-  for (let i = 0; i < str.length; i++) {
-    h ^= str.charCodeAt(i);
-    h = Math.imul(h, 0x01000193) >>> 0;
-  }
-  return h.toString(16).padStart(8, '0');
-}
+// In-scope globals when assembled: planDocCard, DOC_CARD_RENDERER_VERSION,
+// fnv1a, statusChipHint (inlined planner) and the caller-filled slots RECORD, CANONICAL_FP.
 
 const REQUIRED_VARS = [
   'textDefault', 'textMuted', 'tonePositive', 'toneNegative', 'border',
@@ -151,7 +139,13 @@ async function renderDocCard({ card, record, vars, bodyTextStyle }) {
   const descAmbiguous = !named && descCandidates.length > 1;
 
   const missingAnchors = [];
-  if (!hasStatusAnchor) missingAnchors.push('status (title row must contain a descendant named "Status Pill" or "Status")');
+  if (!hasStatusAnchor) {
+    const hint = statusChipHint(titleRow);
+    missingAnchors.push('status (title row must contain a descendant named "Status Pill" or "Status"'
+      + (hint ? ' — frame ' + hint.id + ' "' + hint.name + '" holding "' + hint.label
+        + '" looks like the status chip; rename it "Status Pill" and re-run' : '')
+      + ')');
+  }
   if (!headerDescCandidate) {
     missingAnchors.push(descAmbiguous
       ? 'description (found ' + descCandidates.length + ' candidate TEXT children, cannot tell which is the description — name the right one "Header Description" by hand and re-run)'

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

@@ -111,6 +111,19 @@ function overriddenRecords(instance, path, underDetached) {
   return records;
 }
 
+// The SLOT nodes on this instance's own surface: its slots, and the slots of
+// instances nested in its component, reached only through component sublayers
+// (ids 'I…'). A slot inside content added to a slot is left out here; the walk
+// reaches it through that content.
+function slotsOf(instance) {
+  return instance.findAll((n) => n.type === 'SLOT').filter((slot) => {
+    for (let node = slot.parent; node && node !== instance; node = node.parent) {
+      if (!String(node.id).startsWith('I')) return false;
+    }
+    return true;
+  });
+}
+
 function screensOn(page, names) {
   const all = [];
   for (const top of page.children) {
@@ -171,6 +184,14 @@ async function readScreens(target) {
     if (node.visible === false) return;
     if (node.type === 'INSTANCE') {
       nodes.push(...overriddenRecords(node, path, insideDetached));
+      // Content added to a slot is the screen's own, and isn't listed in
+      // instance.overrides. A slot's placeholder children keep instance-sublayer
+      // ids ('I…;…') and stay part of the component.
+      for (const slot of slotsOf(node)) {
+        for (const child of slot.children) {
+          if (!String(child.id).startsWith('I')) walk(child, `${path} / ${slot.name} / ${child.name}`, false, insideDetached);
+        }
+      }
       return;
     }
     const mixedPaints = node.fills === figma.mixed;