@radicool/throughline 0.14.0 → 0.16.0

package/references/sync-adapters.md

@@ -35,16 +35,54 @@ user names one of these, use the vetted preset — high confidence, no guessing.
 | `tailwind` | tailwind theme config | `dark:` variant / class strategy | preserved (via CSS vars) | `colors.background` |
 | `mui` | JS theme object | `createTheme` palettes | preserved (object refs) | `palette.primary.main` |
 | `vanilla-css` | one CSS file | `:root` + `[data-theme]` | preserved | `--color-bg-default` |
-| `ios-swift` | Swift enum / asset catalog | light/dark asset variants | flattened | `Color.backgroundPrimary` |
-
-These five were chosen for coverage of this plugin's web-first, design-led
-audience: three React framework adapters (shadcn — the dominant new-project
-choice; standalone Tailwind — for the large Tailwind-without-shadcn population;
-MUI — the enterprise/Material standard), the universal `vanilla-css` escape
-hatch (plain CSS custom properties, no framework), and one native slot
-(`ios-swift`, the more standardized native pattern). Everything else —
-Ant Design, Chakra, HeroUI, Android/Kotlin, Flutter, React Native, etc. — is
-fully supported via Tier 2.
+| `ios-swift` | Swift enum constants (`Tokens.swift`) | one build per mode, one output directory per mode | flattened | `Tokens.textSm` |
+
+Four of the five cover this plugin's web-first, design-led audience: three React
+framework adapters (shadcn — the dominant new-project choice; standalone
+Tailwind — for the large Tailwind-without-shadcn population; MUI — the
+enterprise/Material standard), plus the universal `vanilla-css` escape hatch
+(plain CSS custom properties, no framework). `ios-swift` is the one native
+member, and it is curated because its configuration ships as tested code rather
+than as advice — see `${CLAUDE_PLUGIN_ROOT}/references/native-adapter-config.md`.
+Everything else — Ant Design, Chakra, HeroUI, Android/Kotlin, Flutter, React
+Native, etc. — is fully supported via Tier 2.
+
+**`ios-swift` was demoted, and has been restored.** Run against a real DTCG
+source under the *stock* transform group it emitted px-authored dimensions at
+×16 their authored value (valid, compiling Swift), leaked `color-mix()`
+expressions, and left dual-node aliases as bare `px` literals. The tier badge
+claimed a confidence the stock configuration had not earned, so it came off.
+
+The cause was the transform group, not the adapter concept. That configuration
+now ships as tested code at
+`${CLAUDE_PLUGIN_ROOT}/scripts/lib/sd-native.mjs`, is installed into the
+consumer's repo, and is verified end to end against a real source (195 emitted
+symbols matched, zero rule failures under the shipping ruleset, on both light
+and dark builds). The badge is back on that basis.
+
+**What the badge does not cover: nothing is compiled.** Every emitted value is
+checked to be a well-formed Swift or Kotlin *literal* — `tokens:validate-output`'s
+`invalid-literal` rule parses each one and fails on anything that is not
+(#53) — but no `swiftc` or `kotlinc` runs, so a type mismatch or a call to an
+undefined symbol would still pass. String-valued tokens (`fontFamily`, `string`,
+keyword `fontWeight`) are quoted by the module's own transforms, and a value with
+no native form at all — a CSS `linear-gradient(...)` — is filtered out of native
+output rather than emitted broken. That drop is reported as an unemitted token,
+not hidden.
+
+`android-kotlin` uses the same module and stays Tier 2: its remaining unknowns
+are on the consumption side — Compose `dp`/`sp` behaviour against a real Compose
+app, resource-qualifier conventions, package layout — which building tokens does
+not exercise. The `dp`/`sp` split itself is no longer among them: font sizes and
+line heights whose role a DTCG source states — the `fontSize`, `letterSpacing`
+and `lineHeight` member names of §9.8's typography composite — now emit as
+`sp`. What remains is narrower and documented in
+`${CLAUDE_PLUGIN_ROOT}/references/native-adapter-config.md`: a bare scale
+primitive carries no role and stays `dp`, and an `em` letterSpacing is
+filtered out rather than emitted as `.em`.
+`tokens:validate-output` remains what decides whether any adapter can be
+trusted, and re-promotion is available to any adapter that passes it against a
+real source.
 
 `shadcn` vs `tailwind`: shadcn emits CSS vars *plus* the specific var names
 shadcn components expect; `tailwind` targets Tailwind used on its own, mapping
@@ -99,8 +137,52 @@ emit as references to primitive vars rather than flattened literals.
 - **Native adapters** (`ios-swift`, and generated native targets like
   Android/Kotlin): `outputReferences: false` — references resolve to literal
   values at build time, because the target language has no runtime var
-  indirection. Modes map to the platform's native mechanism (asset catalog
-  variants, resource qualifiers).
+  indirection. Modes map to **one build per mode, one output directory per
+  mode** — each build passing only that mode's sources, through `nativeSources`.
+  Asset-catalog variants and resource qualifiers are *not* implemented: nothing
+  here emits an `.xcassets` catalog or a `values-night/` resource tree.
+
+## What the stock configuration gets wrong
+
+These are all legal in a real DTCG source, and a **stock** Style Dictionary
+transform group mishandles every one of them silently — emitting output that
+compiles and is wrong, which is why `tokens:validate-output` exists.
+
+**None of these are Style Dictionary limitations.** All four are fixed by
+roughly 80 lines of preprocessor and transform code, which ships as a tested
+module at `${CLAUDE_PLUGIN_ROOT}/scripts/lib/sd-native.mjs` and is documented in
+`${CLAUDE_PLUGIN_ROOT}/references/native-adapter-config.md`. Against a real
+322-token source it emitted 195 symbols that all map to a source token, 107 of
+them with their numeric magnitude additionally verified, with zero rule failures
+— colour and string values are matched by name only and are checked by no rule.
+**Import that module** rather than configuring a native adapter from a stock
+`transformGroup` or transcribing the reference doc.
+
+- **CSS expressions in a value** — `color-mix(in srgb, {color.brand.500} 12%,
+  transparent)` is a runtime CSS construct. Style Dictionary does no colour
+  math, so it resolves only the inner reference and leaves the function wrapper
+  in the output. *Fix: a transform that computes the blend to a literal.*
+- **Dual-node tokens** — a node carrying both a `$value` and children (`text.sm`
+  with `$value: "14px"` plus a `text.sm.lineHeight` child). Style Dictionary's
+  resolver will not traverse into one, so every alias to the child fails to
+  resolve and emits as a bare literal; its collector also stops there, so the
+  child is never emitted at all. *Fix: a preprocessor that resolves aliases and
+  hoists the children.*
+- **`%` and `em` dimensions** — parent-relative or container-relative, so there
+  genuinely is no build-time native magnitude. This one is a real limit rather
+  than a configuration gap. *Handling: filter them out of native builds — on the
+  authored value, since a `100%` token may be typed `string`, not `dimension`.*
+- **A third mode axis** — this reference models theme (`.dark` /
+  `[data-theme]`) and brand (`[data-brand]`). A viewport axis carrying its own
+  spacing and type scales is common and has no mapping here; on native it is
+  size classes and resource qualifiers, resolved by a different mechanism
+  entirely.
+
+**Native dimension transforms must read the authored unit.** The stock
+`ios-swift` and `compose` transform groups assume `rem` input and multiply by
+16. Against a `px`-authored source that silently produces output at sixteen
+times scale which compiles and ships. Emit 1:1 for `px` and unitless ratios;
+×16 only for `rem`.
 
 ## Brownfield value transforms
 

package/scripts/README.md

@@ -10,10 +10,38 @@ tested here; copied verbatim by `token-crosswalk-builder` into the user's
 | `validate-crosswalk.mjs` | Resolve every `newToken` against the DTCG token source; assert resolved value == `newValue`, N/N. The CI gate. | `tokens:validate` |
 | `build-reverse-index.mjs` | Emit a `codeToken -> newToken` map from the crosswalk to semi-automate SCSS/Tailwind swaps. | `tokens:reverse-index` |
 | `guard-token-removal.mjs` | Grep `.ts/.tsx` (minus generated + tests) for about-to-be-deleted symbols; blocks cleanup until zero references remain. | run during the cleanup phase |
+| `validate-token-output.mjs` | Assert generated native token output matches its DTCG source: authored-unit fidelity, no leaked CSS syntax, no bare unit literals, no mode collisions. Fails when no emitted symbol matches a source token, and reports match rate, unparsed lines, and unemitted tokens on every run. | `tokens:validate-output` |
 | `lib/crosswalk.mjs` | Shared loader + structural validation for `crosswalk.json` (used by the validator and reverse-index). | copied alongside |
+| `lib/dtcg.mjs` | Shared DTCG flatten + `{alias}` resolution. Dual-node aware: a node carrying both a `$value` and children yields its own value **and** is descended into. Used by `validate-crosswalk.mjs` and `validate-token-output.mjs`. | copied alongside both |
+| `lib/sd-native.mjs` | The Style Dictionary native configuration as code: unit-aware dimension transforms, `color-mix` computation, dual-node preprocessing, platform assembly, and a per-mode source guard. Style Dictionary is a parameter, never an import. | copied alongside `validate-token-output.mjs` |
+| `lib/native-literal.mjs` | Shared grammar for "is this a well-formed Swift or Kotlin literal": parses rather than pattern-matches, so an unquoted string, a raw CSS function, or any other unanticipated case fails the same way. Used by `sd-native.mjs`'s output filter and by `validate-token-output.mjs`'s invalid-literal rule. | copied alongside `validate-token-output.mjs` and `lib/sd-native.mjs` |
 | `crosswalk.schema.json` | The finalized JSON Schema for `crosswalk.json` (contract + editor support). | copied beside `crosswalk.json` |
 | `build-docs-digest.mjs` | Aggregate every `design-system/docs/components/*.doc.json` into `design-system/docs/index.json` + `llms.txt` for AI/human consumers. | `docs:digest` |
 | `docs-check.mjs` | Drift gate — verifies each component's doc surfaces still match its canonical record (via `lib/doc-record.mjs` fingerprints). Exits 1 on drift. | `docs:check` |
+| `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/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 |
+| `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-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
+registering them leaves a repo with a script on disk and no entry point, which
+is how a stale `docs:check` went unnoticed for a full release. Both
+`storybook-chromatic-builder` (first-time setup) and `/document-component`
+(freshness refresh) install the same five files and register the same three
+scripts:
+
+| File | npm script |
+| --- | --- |
+| `build-docs-digest.mjs` | `"docs:digest": "node scripts/build-docs-digest.mjs"` |
+| `docs-check.mjs` | `"docs:check": "node scripts/docs-check.mjs"` |
+| `docs-lint.mjs` | `"docs:lint": "node scripts/docs-lint.mjs"` |
+| `lib/doc-record.mjs` | — (imported by the above) |
+| `lib/doc-card-plan.mjs` | — (imported by the above) |
+
+A refresh that adds a file must also add its npm script; check `package.json`
+for all three every time, not just the file that changed.
 
 The crosswalk contract is documented in
 `${CLAUDE_PLUGIN_ROOT}/references/crosswalk-schema.md`.
@@ -31,9 +59,9 @@ conflict, or remaining reference), `2` bad CLI arguments.
 
 ## How the skill installs these
 
-`token-crosswalk-builder` copies `lib/crosswalk.mjs`, `validate-crosswalk.mjs`,
-`build-reverse-index.mjs`, `guard-token-removal.mjs`, and `crosswalk.schema.json`
-into the user's `packages/tokens/scripts/` (schema beside `crosswalk.json`), then
+`token-crosswalk-builder` copies `lib/crosswalk.mjs`, `lib/dtcg.mjs`,
+`validate-crosswalk.mjs`, `build-reverse-index.mjs`, `guard-token-removal.mjs`, and
+`crosswalk.schema.json` into the user's `packages/tokens/scripts/` (schema beside `crosswalk.json`), then
 wires `packages/tokens/package.json`:
 
 ```jsonc
@@ -43,6 +71,12 @@ wires `packages/tokens/package.json`:
 }
 ```
 
+`token-sync-layer` copies `validate-token-output.mjs`, `lib/dtcg.mjs`,
+`lib/native-literal.mjs`, **and** `lib/sd-native.mjs`, and wires
+`"tokens:validate-output"`. All four travel together: `sd-native.mjs` and the
+validator both import `lib/dtcg.mjs` and `lib/native-literal.mjs`, so
+installing any one of them alone breaks at import time.
+
 The scripts version with the user's repo so their CI runs them locally — a path
 inside the plugin install would not be reachable from the user's CI.
 

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

@@ -0,0 +1,143 @@
+// Generates references/doc-card-builder.md — the canonical figma_execute
+// snippet that renders a doc card's Usage band — by inlining the pure planner
+// (lib/doc-card-plan.mjs) above the Figma renderer template
+// (lib/doc-card-render.figma.js). Mirrors the adapters generate.mjs idiom:
+// 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 PLANNER = join(REPO_ROOT, 'scripts', 'lib', 'doc-card-plan.mjs');
+const RENDERER = join(REPO_ROOT, 'scripts', 'lib', 'doc-card-render.figma.js');
+const OUT = join(REPO_ROOT, 'references', 'doc-card-builder.md');
+
+const HEADER = [
+  '# Doc-card Usage-band builder (GENERATED)',
+  '',
+  '> **GENERATED FILE — do not edit by hand.** Sources: `scripts/lib/doc-card-plan.mjs`',
+  '> (the pure planner, unit-tested in Node) + `scripts/lib/doc-card-render.figma.js`',
+  '> (the Figma renderer). Regenerate with `node scripts/build-doc-card-builder.mjs`;',
+  '> CI gates freshness with `--check`.',
+  '',
+  'The canonical `figma_execute` snippet that renders a component doc card\'s',
+  '`Usage` band from its `.doc.json` record. Every card is identical by',
+  'construction — never hand-build the usage body. The builder owns the `Usage`',
+  'band and the header\'s record-derived content (its short description and date);',
+  'it reads the specimen and never writes it. The status chip keeps its own owner',
+  '— the finalize write-back in `references/figma-component-standards.md`.',
+  '',
+  '## How to call it',
+  '',
+  '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`.',
+  '   - If present, resolve each of the nine roles to a Variable object **by',
+  '     the recorded name** — do not re-derive, do not substitute a similar',
+  '     name. Look each name up via `figma_get_variables`, then in the script',
+  '     fetch it as a Variable object with',
+  '     `figma.variables.getVariableByIdAsync(id)`. If a recorded name no',
+  '     longer resolves to exactly one variable in the file, **throw** rather',
+  '     than guess — the token was renamed or removed, and silently picking a',
+  '     neighbour is how cards drift apart.',
+  '   - If the field is absent (a project\'s first doc-card render, or any',
+  '     render after the field is cleared), do not resolve fresh by judgement',
+  '     yet — first check whether a doc card already exists in the file. If',
+  '     one does, recover all nine roles from it by resolving each bound',
+  '     variable id back to its name (`figma.variables.getVariableByIdAsync(id)`):',
+  '     - `spacePadding` ← the `Usage` frame\'s `paddingLeft`.',
+  '     - `spaceRowGap` ← the `Usage` frame\'s `itemSpacing`.',
+  '     - `spaceBlockGap` ← a `Usage Row *` frame\'s `itemSpacing`.',
+  '     - `spaceItemGap` ← a `Block: *` frame\'s `itemSpacing` (blocks are the',
+  '       children of a `Usage Row *`).',
+  '     - `border` ← a `Row Divider` frame\'s',
+  '       `fills[0].boundVariables.color`.',
+  '     - `tonePositive` ← the first TEXT child of the `Block: Do` frame\'s',
+  '       `fills[0].boundVariables.color`.',
+  '     - `toneNegative` ← the first TEXT child of the `Block: Don\'t` frame,',
+  '       same property.',
+  '     - `textMuted` ← the first TEXT child of any block other than',
+  '       `Block: Do` / `Block: Don\'t`, same property (tone blocks colour',
+  '       their eyebrow differently, so exclude them here).',
+  '     - `textDefault` ← the second child of that same block when it is a',
+  '       TEXT node — `Block: Overview` is reliable; definition blocks nest',
+  '       frames there instead, so skip those. Same property.',
+  '     A single-row card has no `Row Divider` (no `border`); a card without',
+  '     `Block: Do` / `Block: Don\'t` yields no `tonePositive` / `toneNegative`.',
+  '     Read another rendered card for the roles that specific card can\'t',
+  '     yield, or fall back to judgement for just those. Only when no',
+  '     rendered card exists at all does the caller choose every role by',
+  '     judgement — establishing the project\'s rhythm, not guessing at one.',
+  '   Either way, resolve the nine roles once, **write the mapping back to',
+  '   `design-system.json`** as `figma.docCardVariables`, then render. Every',
+  '   later render reads it.',
+  '   The nine roles: `textDefault`, `textMuted` (text colors), `tonePositive`,',
+  '   `toneNegative` (Do/Don\'t eyebrow colors — success/danger roles), `border`',
+  '   (row dividers), `spacePadding`, `spaceRowGap`, `spaceBlockGap`,',
+  '   `spaceItemGap` (spacing roles: band padding, row gap, block gutter,',
+  '   within-block gap).',
+  '3. Find the body text style: `(await figma.getLocalTextStylesAsync())',
+  '   .find((s) => s.name === \'Body/Default\')`. Missing variables or style =',
+  '   the builder throws (bind-or-throw — the gap is in the token set; fix it',
+  '   there, never hardcode around it).',
+  '4. Prepend the two slots, then the snippet below, then the call:',
+  '',
+  '```js',
+  'const RECORD = /* the parsed .doc.json object */;',
+  'const CANONICAL_FP = \'/* canonicalFingerprint(RECORD), 16 hex chars */\';',
+  '// … the generated snippet …',
+  'const card = await figma.getNodeByIdAsync(cardNodeId);',
+  'const summary = await renderDocCard({ card, record: RECORD, vars, bodyTextStyle });',
+  '```',
+  '',
+  '5. Pass an explicit `timeout` (30000 is right for one card; the ~30s',
+  '   `figma_execute` ceiling fits a single card comfortably — render cards one',
+  '   call at a time, never batched).',
+  '6. Verify from the returned summary — `rowsRendered`, `blocksCreated`,',
+  '   `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.',
+  '',
+  '## The snippet',
+  '',
+  '```js',
+].join('\n');
+
+const FOOTER = [
+  '```',
+  '',
+  'Layout contract and rationale:',
+  '`docs/superpowers/specs/2026-08-09-doc-card-layout-and-voice-design.md`.',
+  '',
+].join('\n');
+
+export function buildDocCardBuilder({ plannerSource, rendererSource }) {
+  const inlined = plannerSource
+    .replace(/^export const /gm, 'const ')
+    .replace(/^export function /gm, 'function ');
+  for (const [name, src] of [['doc-card-plan.mjs', inlined], ['doc-card-render.figma.js', rendererSource]]) {
+    if (/^\s*(import|export)\b/m.test(src)) {
+      throw new Error(`${name} must stay import-free (only top-level \`export const\`/\`export function\` allowed in the planner) — it is inlined into the Figma snippet where no module system exists`);
+    }
+  }
+  return `${HEADER}\n${inlined}\n${rendererSource}${FOOTER}`;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const result = buildDocCardBuilder({
+    plannerSource: readFileSync(PLANNER, 'utf8'),
+    rendererSource: readFileSync(RENDERER, 'utf8'),
+  });
+  if (process.argv.includes('--check')) {
+    let onDisk = null;
+    try { onDisk = readFileSync(OUT, 'utf8'); } catch (e) { /* missing counts as drift */ }
+    if (onDisk !== result) {
+      console.error('✗ references/doc-card-builder.md out of date; run: node scripts/build-doc-card-builder.mjs');
+      process.exit(1);
+    }
+    console.log('✓ doc-card builder in sync');
+  } else {
+    writeFileSync(OUT, result);
+    console.log('✓ wrote references/doc-card-builder.md');
+  }
+}

package/scripts/build-native-adapter-config.mjs

@@ -0,0 +1,280 @@
+// Generates references/native-adapter-config.md from scripts/lib/sd-native.mjs.
+// The prose lives here, keyed by section id; the code is sliced out of the
+// module's real source between @doc-section markers and interleaved beneath its
+// prose. Mirrors build-doc-card-builder.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';
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+export const SOURCE = join(REPO_ROOT, 'scripts', 'lib', 'sd-native.mjs');
+export const OUT = join(REPO_ROOT, 'references', 'native-adapter-config.md');
+
+const OPEN = /^\s*\/\/\s*@doc-section\s+(\S+)\s*$/;
+const CLOSE = /^\s*\/\/\s*@doc-section-end\s+(\S+)\s*$/;
+
+export function sliceSections(source) {
+  const sections = new Map();
+  let open = null;
+  let buffer = [];
+  for (const line of source.split('\n')) {
+    const closeMatch = line.match(CLOSE);
+    if (closeMatch) {
+      if (!open) throw new Error(`@doc-section-end ${closeMatch[1]} with no open section`);
+      if (closeMatch[1] !== open) {
+        throw new Error(`@doc-section-end ${closeMatch[1]} does not close ${open}`);
+      }
+      sections.set(open, buffer.join('\n').trim());
+      open = null;
+      buffer = [];
+      continue;
+    }
+    const openMatch = line.match(OPEN);
+    if (openMatch) {
+      if (open) throw new Error(`unclosed @doc-section ${open}`);
+      if (sections.has(openMatch[1])) throw new Error(`duplicate @doc-section ${openMatch[1]}`);
+      open = openMatch[1];
+      continue;
+    }
+    if (open) buffer.push(line);
+  }
+  if (open) throw new Error(`unclosed @doc-section ${open}`);
+  return sections;
+}
+
+// Every line of module source must live inside some @doc-section pair, so that
+// adding a piece to the module without documenting it breaks CI rather than
+// silently shipping a doc whose code does not run. Legitimately outside: blank
+// lines, `//` comment lines (the file's leading banner), and the markers
+// themselves. Anything else — any line with executable code on it — is a gap.
+export function assertCovered(source) {
+  const uncovered = [];
+  let open = false;
+  source.split('\n').forEach((line, i) => {
+    if (CLOSE.test(line)) {
+      open = false;
+      return;
+    }
+    if (OPEN.test(line)) {
+      open = true;
+      return;
+    }
+    if (open) return;
+    const trimmed = line.trim();
+    if (trimmed === '' || trimmed.startsWith('//')) return;
+    uncovered.push(`  ${i + 1}: ${line}`);
+  });
+  if (uncovered.length === 0) return;
+  throw new Error(
+    `${uncovered.length} line(s) of ${SOURCE} fall outside every @doc-section pair.\n` +
+      'Only blank lines and // comments may sit outside a section; code must be\n' +
+      'inside one, or the generated doc shows code that cannot run.\n' +
+      uncovered.join('\n'),
+  );
+}
+
+// Section id -> the prose that introduces it. Order here is the doc's order.
+const PROSE = [
+  ['imports', `## Imports
+
+\`node:fs\` plus the siblings \`lib/dtcg.mjs\` and \`lib/native-literal.mjs\` this
+plugin already installs — nothing else. Style Dictionary is passed in as a
+parameter, never imported, which is what keeps this module installable into a
+consumer's repo.`],
+  ['unit-aware', `## 1. Read the authored unit
+
+**This replaces \`size/swift/remToCGFloat\` and the \`size/compose/*\` transforms,
+and it is the single most important piece.** Those assume every dimension is
+authored in \`rem\` and multiply by 16. Against a \`px\`-authored source that
+silently produces output at sixteen times scale which compiles and ships.`],
+  ['color-mix', `## 2. Compute \`color-mix()\` to a literal
+
+A CSS expression has no native equivalent, and Style Dictionary does no colour
+math. Native adapters resolve to literals; for a \`color-mix\` that means
+actually computing the blend. Register this **before** the platform's colour
+transform, so the colour transform receives a valid hex8 rather than a CSS
+function.`],
+  ['preprocess', `## 3. Resolve aliases and hoist dual-node children
+
+Style Dictionary's resolver will not traverse into a node that carries both a
+\`$value\` and children, and its collector stops there too. The dual-node pattern
+is invalid DTCG — the Design Tokens Format Module's 30 July 2026 draft, §6.1,
+requires tools to report it as an error, and §6.2's \`$root\` is the sanctioned
+way to pair a value with children. Figma-derived sources emit it anyway:
+\`text.sm\` holds \`$value: "14px"\` *and* a \`text.sm.lineHeight\` child. So every
+alias to such a child fails to resolve, and the child is never emitted at all.
+
+Both are fixed before Style Dictionary sees the tree.`],
+  ['platform', `## 4. Assemble the platform from the stock list
+
+Build the transform list from Style Dictionary's **stock group**, replacing only
+the rem-assuming size transforms. A hand-picked list silently drops whatever it
+forgets — three real defects arose exactly that way.
+
+**The \`dp\`/\`sp\` split is fixed here; two narrower Android-only limits remain.**
+Style Dictionary's Compose transforms select on \`$type\`, and DTCG's type set
+does not line up with what they expect — there is no \`fontSize\` type, because
+DTCG types font sizes as \`dimension\`. So the role is taken instead from the
+member names DTCG §9.8 fixes for the typography composite, stamped onto
+\`$extensions\` during preprocessing, and the two Compose transforms partition on
+that stamp. Measured against a real source: 39 declarations that emitted \`dp\`
+now emit \`sp\`, with the Swift output byte-identical.
+
+What remains:
+
+- **A bare scale primitive emits as \`dp\`.** \`text.base: "16px"\` is a font size
+  only to a human — no nominal or structural signal marks it — so it is not
+  stamped. The semantic tokens that reference it are, and those are what a
+  consumer should reach for.
+- **An \`em\` letter spacing reaches Compose but not Swift.** \`size/unit-aware/compose-em\`
+  emits it as a real \`.em\` TextUnit, parenthesised — \`(-0.03).em\` — because
+  \`-0.03.em\` parses as \`-(0.03.em)\` and needs an \`unaryMinus\` operator, while
+  the parenthesised form compiles regardless. iOS is excluded deliberately, not
+  pending: letter spacing there is an \`NSAttributedString\` kern in points,
+  which needs the font size the token does not carry, so no constant Swift
+  could emit would be right at every font size.
+
+The first is Android-only. \`size/unit-aware/swift\` filters
+\`dimension || fontSize\` and emits \`CGFloat\`, which carries no unit to be wrong
+about; iOS handles Dynamic Type at the use site via \`UIFontMetrics\`.
+\`tokens:validate-output\` passes in both cases: it checks magnitude, not unit.
+
+**A unitless value is no longer one of them.** DTCG §8.2.1 requires a dimension
+to carry a unit, §8.7's \`number\` is the type for a ratio, and §9.8 types
+\`lineHeight\` as one — so \`leading.normal: "1.5"\` typed \`dimension\` is malformed
+input. No size transform claims it: it emits bare on both platforms, which is
+byte-for-byte what a correctly typed \`number\` already produced, so correcting
+the source's \`$type\` changes no output. \`tokens:validate-output\` reports it as
+a \`unitless-dimension\` advisory, which does not gate — the emitted value is
+right under the ratio reading, and only the author can say whether a ratio is
+what was meant.
+
+**The stock list is accounted for, not transcribed.** \`PLATFORMS\` records the
+stock group each platform mirrors, and \`auditStockGroups\` checks at
+registration that every transform in that live group is either run here or
+declined in writing, with a reason. A stock transform this config has never
+decided about warns; it is never silently dropped. The check warns and never
+throws — a new stock transform is usually harmless, and the fatal direction, a
+transform we run being removed, already makes Style Dictionary throw on an
+unknown name. It runs in your build because that is the only place the
+installed Style Dictionary version is knowable: ThroughLine declares no
+dependency on it.`],
+  ['sources', `## 5. Guard the per-mode source list
+
+Style Dictionary deduplicates by dot-path, so one build over both a light and a
+dark definition of the same token keeps whichever file sorts last and drops the
+other mode with no diagnostic. Pass every build's sources through
+\`nativeSources\`, which returns them, so the check cannot be skipped by
+forgetting it.`],
+  ['register', `## 6. Register with Style Dictionary
+
+One call. Style Dictionary is a parameter, never an import, which is what lets
+this module install into a consumer's \`packages/tokens/scripts/lib/\`.`],
+];
+
+const HEADER = `# Native adapter configuration (GENERATED)
+
+> **GENERATED FILE — do not edit by hand.** Source: \`scripts/lib/sd-native.mjs\`,
+> which is unit-tested in Node and installed into the consumer's repo.
+> Regenerate with \`node scripts/build-native-adapter-config.mjs\`; CI gates
+> freshness with \`--check\`.
+
+The Style Dictionary configuration a native adapter (\`ios-swift\`,
+\`android-kotlin\`, or any generated native target) needs in order to emit
+**correct** output from a real DTCG token source.
+
+**Why this exists.** The stock \`ios-swift\` and \`compose\` transform groups
+produce output that compiles and is wrong. Run against a real source, the stock
+configuration emitted every \`px\`-authored dimension at ×16 its authored value,
+leaked \`color-mix()\` expressions into Swift, and left dual-node aliases as bare
+\`px\` literals — all at exit \`0\`. None of that is a Style Dictionary limitation.
+All of it is configuration.
+
+**You do not need to copy any of this.** It ships as
+\`\${CLAUDE_PLUGIN_ROOT}/scripts/lib/sd-native.mjs\`. Install it beside
+\`lib/dtcg.mjs\` and \`lib/native-literal.mjs\` and call it:
+
+\`\`\`js
+import StyleDictionary from 'style-dictionary';
+import { registerNativeTransforms, nativePlatform, nativeSources }
+  from './scripts/lib/sd-native.mjs';
+
+registerNativeTransforms(StyleDictionary);
+
+for (const mode of ['light', 'dark']) {
+  const sd = new StyleDictionary({
+    source: nativeSources(sourcesFor(mode)),
+    preprocessors: ['dtcg/resolve-dual-node'],
+    platforms: {
+      ios: nativePlatform({ platform: 'ios-swift', buildPath: \`out/\${mode}/\` }),
+    },
+  });
+  await sd.buildAllPlatforms();
+}
+\`\`\`
+
+The sections below are the module's own source, inlined so the configuration
+stays reviewable. Pair this with \`\${CLAUDE_PLUGIN_ROOT}/references/sync-adapters.md\`,
+which covers the adapter contract itself.
+`;
+
+const FOOTER = `## Verify, always
+
+Configuration this specific is exactly what regresses unnoticed, because every
+failure mode above produces output that compiles. Run \`tokens:validate-output\`
+against each generated file with the same source list that file's build used,
+and treat it as a gate rather than a spot check:
+
+\`\`\`
+node scripts/validate-token-output.mjs \\
+  --source tokens/color-primitives.json --source tokens/text-primitives.json \\
+  --output out/light/Tokens.swift --platform ios-swift --min-match 1
+\`\`\`
+
+A clean run reports 100% of emitted symbols matched with zero rule failures.
+Anything less means the configuration drifted — so **pass \`--min-match 1\`**.
+The flag's default is \`0.5\`, which is a floor against wholly unparseable output
+rather than the gate this doc describes; without it a 60% match rate exits \`0\`.
+See \`\${CLAUDE_PLUGIN_ROOT}/scripts/README.md\`.
+
+"Matched" means an emitted symbol's name resolved to a source token. Numeric
+magnitudes are additionally compared; colour and string values are matched by
+name only, and no rule checks that the output compiles.
+`;
+
+export function render(sections) {
+  const declared = PROSE.map(([id]) => id);
+  for (const id of declared) {
+    if (!sections.has(id)) throw new Error(`@doc-section ${id} is declared in PROSE but missing from ${SOURCE}`);
+  }
+  for (const id of sections.keys()) {
+    if (!declared.includes(id)) throw new Error(`@doc-section ${id} exists in ${SOURCE} but has no prose entry`);
+  }
+  const body = PROSE.map(([id, prose]) => `${prose}\n\n\`\`\`js\n${sections.get(id)}\n\`\`\`\n`).join('\n');
+  return `${HEADER}\n${body}\n${FOOTER}`;
+}
+
+function main() {
+  const check = process.argv.includes('--check');
+  const source = readFileSync(SOURCE, 'utf8');
+  assertCovered(source);
+  const rendered = render(sliceSections(source));
+  if (!check) {
+    writeFileSync(OUT, rendered);
+    console.log(`wrote ${OUT}`);
+    return;
+  }
+  const current = readFileSync(OUT, 'utf8');
+  if (current === rendered) {
+    console.log('references/native-adapter-config.md is up to date');
+    return;
+  }
+  console.error(
+    'references/native-adapter-config.md is stale.\n' +
+      'Run: node scripts/build-native-adapter-config.mjs',
+  );
+  process.exit(1);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();