diff --git a/CLAUDE.md b/CLAUDE.md
index 1e6729f9..788e6efd 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -51,9 +51,21 @@ requires a rebuild+redeploy, not just a file edit.
 | `npm run version-sync` | Sync all version references to root `package.json` |
 | `npm run check:version` | Verify all version references match (CI gate — run before every commit that touches versions) |
 | `npm run check:llm-guide` | Verify `docs/llm-guide.md` only references live tokens (CI gate) |
+| `npm run check:macros` | Verify `.sf-*` macro classes match `docs/macros.md` (not currently wired into CI — run manually before committing macro changes) |
+| `npm run check:registry` | Verify `token-registry.json` is in sync with source (CI gate) |
+| `npm run audit:check` | Verify `docs/registry.json` matches source without writing (CI gate) |
+| `npm run lint:css` | Lint all CSS source with stylelint (CI gate) |
+| `npm run lint:css:fix` | Lint CSS source and auto-fix violations |
 | `npm run docs` | Regenerate docs and sync configurator API index |
+| `npm run docs:tokens` | Regenerate `docs/tokens.md` only |
+| `npm run docs:index` | Regenerate `docs/token-index.md` + `.json` only |
+| `npm run docs:api` | Regenerate `docs/api-index.md` + `.json` only |
+| `npm run docs:classes` | Regenerate `docs/classes.md` only |
+| `npm run gen:registry` | Regenerate `token-registry.json` (stable id assignments) |
 | `npm run configurator:sync` | Push `docs/api-index.json` → `configurator/src/data/api-index.generated.json` |
-| `npm run audit` | Audit CSS tokens for consistency |
+| `npm run audit` | Audit CSS tokens for consistency, writing `docs/registry.json` |
+| `npm run watch` | Rebuild CSS bundles on file change (dev watch mode) |
+| `npm run test:unit` | Run the Node `--test` unit suite only, without the Playwright e2e build. Some tests read from `badges/` — run `npm run build` first on a clean checkout (CI instead downloads the `badges` artifact from the `build` job before this step) |
 | `npm test` | Full suite: build → unit → Playwright e2e |
 
 ## Release process
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ca714b40..10190440 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -46,7 +46,7 @@ and `badges/` must be rebuilt and committed.
 ## Tests & demo coverage
 
 - Any new `.sf-*` or `.is-*` class in `core/*.css` must appear in `docs/demo.html`
-  (`tests/coverage.spec.js`).
+  (`tests/coverage.test.js`).
 - Any new token must resolve in both themes (`tests/tokens.spec.js`); tokens whose
   value is `inherit` go in that file's `EXPECTED_EMPTY` allowlist.
 - Add a focused assertion when you fix a bug.
diff --git a/README.md b/README.md
index 82916404..c62dbbf7 100644
--- a/README.md
+++ b/README.md
@@ -33,7 +33,9 @@ Use a pre-built bundle (see [Releases](https://github.com/codeslash-dev/SLASHED/
 ```
 
 À la carte is also supported. When wiring up individual files, `core/layers.css`
-must load **first**. `optional/legacy.css` is not bundled by default — add it
+must load **first** — it declares the `@layer` order once, and that order (not
+`<link>` order) controls the cascade, so the snippet below simply mirrors it
+for readability. `optional/legacy.css` is not bundled by default — add it
 explicitly if you need back-compat shims and load it **last**:
 
 ```html
@@ -44,10 +46,10 @@ explicitly if you need back-compat shims and load it **last**:
 <link rel="stylesheet" href="core/tokens.macros.css">
 <link rel="stylesheet" href="core/reset.css">
 <link rel="stylesheet" href="core/base.css">
-<link rel="stylesheet" href="core/themes.css">
 <link rel="stylesheet" href="core/layout.css">
 <link rel="stylesheet" href="core/macros.css">
 <link rel="stylesheet" href="core/states.css">
+<link rel="stylesheet" href="core/themes.css">
 <link rel="stylesheet" href="core/motion.css">
 <link rel="stylesheet" href="core/accessibility.css">
 <link rel="stylesheet" href="core/print.css">
diff --git a/configurator/package-lock.json b/configurator/package-lock.json
index 74b5030a..ed74bc86 100644
--- a/configurator/package-lock.json
+++ b/configurator/package-lock.json
@@ -8,9 +8,8 @@
       "name": "slashed-configurator",
       "version": "0.6.33",
       "dependencies": {
-        "fflate": "^0.8.3",
-        "lucide-svelte": "^0.468.0",
-        "motion": "^12.23.24"
+        "@lucide/svelte": "^1.23.0",
+        "fflate": "^0.8.3"
       },
       "devDependencies": {
         "@playwright/test": "^1.60.0",
@@ -686,6 +685,15 @@
         "@jridgewell/sourcemap-codec": "^1.4.14"
       }
     },
+    "node_modules/@lucide/svelte": {
+      "version": "1.23.0",
+      "resolved": "https://registry.npmjs.org/@lucide/svelte/-/svelte-1.23.0.tgz",
+      "integrity": "sha512-3LQbKXx9vId6Nx4E2Nu2qwgJfdmr5+CVeVJbxe5cy+HcnCRd9QVVtZXqvgBYAV1OJrPmQAf9/3gJWLCpASC/Ng==",
+      "license": "ISC",
+      "peerDependencies": {
+        "svelte": "^5"
+      }
+    },
     "node_modules/@playwright/test": {
       "version": "1.61.1",
       "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.61.1.tgz",
@@ -2165,33 +2173,6 @@
         "node": ">= 6"
       }
     },
-    "node_modules/framer-motion": {
-      "version": "12.42.0",
-      "resolved": "https://registry.npmjs.org/framer-motion/-/framer-motion-12.42.0.tgz",
-      "integrity": "sha512-wp7EJnfWaaEScVygKv3e20udoRz+LbtxScsuTkakAxfXmt+ReC6WyPW2nINRAGvd+hG9odwcjBLyOTPjH5pBRA==",
-      "license": "MIT",
-      "dependencies": {
-        "motion-dom": "^12.42.0",
-        "motion-utils": "^12.39.0",
-        "tslib": "^2.4.0"
-      },
-      "peerDependencies": {
-        "@emotion/is-prop-valid": "*",
-        "react": "^18.0.0 || ^19.0.0",
-        "react-dom": "^18.0.0 || ^19.0.0"
-      },
-      "peerDependenciesMeta": {
-        "@emotion/is-prop-valid": {
-          "optional": true
-        },
-        "react": {
-          "optional": true
-        },
-        "react-dom": {
-          "optional": true
-        }
-      }
-    },
     "node_modules/fsevents": {
       "version": "2.3.3",
       "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
@@ -2747,16 +2728,6 @@
       "dev": true,
       "license": "ISC"
     },
-    "node_modules/lucide-svelte": {
-      "version": "0.468.0",
-      "resolved": "https://registry.npmjs.org/lucide-svelte/-/lucide-svelte-0.468.0.tgz",
-      "integrity": "sha512-n0ecAFtCY5LEeL+PJ1Xj4n3c2gzj8tMpak0KMGnvoSJEjCsCnRB0mekBtJZAo7beyynW9Qj5Um1KfMBAeTNplw==",
-      "deprecated": "Package deprecated. Please use @lucide/svelte instead.",
-      "license": "ISC",
-      "peerDependencies": {
-        "svelte": "^3 || ^4 || ^5.0.0-next.42"
-      }
-    },
     "node_modules/lz-string": {
       "version": "1.5.0",
       "resolved": "https://registry.npmjs.org/lz-string/-/lz-string-1.5.0.tgz",
@@ -2819,47 +2790,6 @@
         "node": ">=4"
       }
     },
-    "node_modules/motion": {
-      "version": "12.42.0",
-      "resolved": "https://registry.npmjs.org/motion/-/motion-12.42.0.tgz",
-      "integrity": "sha512-Qhwvu9sVl5/URSq5CNzwMCpSKK8Uhnrwb6VO977kZyj/wOCS7mWebJUnBoHx5cZU1Zv8a9BD5CSICWKAlrLJgA==",
-      "license": "MIT",
-      "dependencies": {
-        "framer-motion": "^12.42.0",
-        "tslib": "^2.4.0"
-      },
-      "peerDependencies": {
-        "@emotion/is-prop-valid": "*",
-        "react": "^18.0.0 || ^19.0.0",
-        "react-dom": "^18.0.0 || ^19.0.0"
-      },
-      "peerDependenciesMeta": {
-        "@emotion/is-prop-valid": {
-          "optional": true
-        },
-        "react": {
-          "optional": true
-        },
-        "react-dom": {
-          "optional": true
-        }
-      }
-    },
-    "node_modules/motion-dom": {
-      "version": "12.42.0",
-      "resolved": "https://registry.npmjs.org/motion-dom/-/motion-dom-12.42.0.tgz",
-      "integrity": "sha512-M63h4n8R+quJdNhBwuLlgxM+OLYa9+I/T2pzDRboB9fLXRdbou+Gw7Zury+SkpaCyACP1JHSjHgZ1EgTkBr30w==",
-      "license": "MIT",
-      "dependencies": {
-        "motion-utils": "^12.39.0"
-      }
-    },
-    "node_modules/motion-utils": {
-      "version": "12.39.0",
-      "resolved": "https://registry.npmjs.org/motion-utils/-/motion-utils-12.39.0.tgz",
-      "integrity": "sha512-8nadJAJjTtqRkmRF36FoJTrywK9nnFmnPwnSMyxaOCU7GDjN9RTMJIxx9De8ErM+vpPhMccr/6fo5WciyQLnMQ==",
-      "license": "MIT"
-    },
     "node_modules/mri": {
       "version": "1.2.0",
       "resolved": "https://registry.npmjs.org/mri/-/mri-1.2.0.tgz",
@@ -3429,7 +3359,9 @@
       "version": "2.8.1",
       "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
       "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
-      "license": "0BSD"
+      "dev": true,
+      "license": "0BSD",
+      "optional": true
     },
     "node_modules/typescript": {
       "version": "5.8.3",
diff --git a/configurator/package.json b/configurator/package.json
index 45e312e8..ac9ba6b8 100644
--- a/configurator/package.json
+++ b/configurator/package.json
@@ -21,9 +21,8 @@
     "test:e2e": "playwright test"
   },
   "dependencies": {
-    "fflate": "^0.8.3",
-    "lucide-svelte": "^0.468.0",
-    "motion": "^12.23.24"
+    "@lucide/svelte": "^1.23.0",
+    "fflate": "^0.8.3"
   },
   "devDependencies": {
     "@playwright/test": "^1.60.0",
diff --git a/configurator/src/App.svelte b/configurator/src/App.svelte
index 6b5d3b7d..9a256f18 100644
--- a/configurator/src/App.svelte
+++ b/configurator/src/App.svelte
@@ -1,19 +1,19 @@
 <script lang="ts">
   import { onMount, untrack } from 'svelte';
-  import { SlidersHorizontal, Eye, RotateCcw } from 'lucide-svelte';
-  import type { PreviewTemplate, SlashedToken } from './types';
+  import { SlidersHorizontal, Eye, RotateCcw } from '@lucide/svelte';
+  import type { PreviewTemplate, SlashedToken, ApiIndex } from './types';
   import StudioHeader from './components/shell/StudioHeader.svelte';
   import SidebarNav from './components/shell/SidebarNav.svelte';
   import StatusBar from './components/shell/StatusBar.svelte';
   import PreviewPanel from './components/shell/PreviewPanel.svelte';
   import DomainPanel from './components/DomainPanel.svelte';
-  import { fa } from './lib/codec';
+  import { generateCSS } from './lib/codec';
   import { loadInitialOverrides, injectLivePreview, saveOverrides, hasWpBoot } from './lib/persistence';
   import { domainOf } from './lib/domains';
   import tokensRaw from './data/api-index.generated.json';
   import CommandPalette from './components/CommandPalette.svelte';
 
-  const ALL_TOKENS = ((tokensRaw as any).tokens ?? tokensRaw) as SlashedToken[];
+  const ALL_TOKENS = ((tokensRaw as ApiIndex).tokens ?? tokensRaw) as SlashedToken[];
 
   const DOMAIN_LABELS: Record<string, string> = {
     home: "Home", colors: "Colors", typography: "Typography", spacing: "Spacing",
@@ -79,7 +79,7 @@
 
   // Save state — hasPendingChanges is derived so undo/redo update it automatically.
   let lastSavedOverrides = $state<Record<string, string>>(untrack(() => ({ ...overrides })));
-  let saveState = $state<'idle' | 'saving' | 'saved'>('idle');
+  let saveState = $state<'idle' | 'saving' | 'saved' | 'error'>('idle');
   let hasPendingChanges = $derived(!shallowEq(overrides, lastSavedOverrides));
   let saveStateTimer: ReturnType<typeof setTimeout> | null = null;
 
@@ -92,7 +92,7 @@
     if (!shallowEq(prev, next)) {
       past = [...past.slice(-49), prev];
       future = [];
-      if (saveState === 'saved') saveState = 'idle';
+      if (saveState === 'saved' || saveState === 'error') saveState = 'idle';
     }
     overrides = next;
   }
@@ -117,7 +117,7 @@
       }
     } catch (err) {
       console.warn('slashed: save failed', err);
-      saveState = 'idle';
+      saveState = 'error';
     }
   }
 
@@ -219,7 +219,7 @@
   }
 
   function handleExport() {
-    const css = fa(overrides, { mode: "layer", banner: true });
+    const css = generateCSS(overrides, { mode: "layer", banner: true });
     const blob = new Blob([css], { type: "text/css" });
     const url = URL.createObjectURL(blob);
     const a = document.createElement("a");
diff --git a/configurator/src/components/DomainPanel.svelte b/configurator/src/components/DomainPanel.svelte
index 8df3e773..2f9d6d3a 100644
--- a/configurator/src/components/DomainPanel.svelte
+++ b/configurator/src/components/DomainPanel.svelte
@@ -1,5 +1,5 @@
 <script lang="ts">
-  import { SlidersHorizontal, List } from 'lucide-svelte';
+  import { SlidersHorizontal, List } from '@lucide/svelte';
   import type { SlashedToken } from '../types';
   import { DOMAIN_PATTERNS, domainOf } from '../lib/domains';
   import HomePanel from './panels/HomePanel.svelte';
diff --git a/configurator/src/components/panels/CheatsheetPanel.svelte b/configurator/src/components/panels/CheatsheetPanel.svelte
index 3b83f4c1..bff6fee3 100644
--- a/configurator/src/components/panels/CheatsheetPanel.svelte
+++ b/configurator/src/components/panels/CheatsheetPanel.svelte
@@ -5,10 +5,11 @@
 <script lang="ts">
   import classesData from '../../data/classes.generated.json';
   import tokensData from '../../data/api-index.generated.json';
-  import { Copy, Check } from 'lucide-svelte';
+  import { Copy, Check } from '@lucide/svelte';
+  import type { SlashedClass } from '../../types';
 
   const classes = classesData.classes;
-  const tokens = tokensData.tokens.filter((t: any) => t.tier === 'PUBLIC' || t.tier === 'PUBLIC-ADVANCED');
+  const tokens = tokensData.tokens.filter((t) => t.tier === 'PUBLIC' || t.tier === 'PUBLIC-ADVANCED');
 
   let query = $state('');
   let tab = $state<'classes' | 'tokens'>('classes');
@@ -17,7 +18,7 @@
   let filteredClasses = $derived(() => {
     const q = query.trim().toLowerCase();
     if (!q) return classes;
-    return classes.filter((c: any) =>
+    return classes.filter((c: SlashedClass) =>
       c.name.toLowerCase().includes(q) ||
       c.selector?.toLowerCase().includes(q) ||
       c.description?.toLowerCase().includes(q) ||
@@ -28,7 +29,7 @@
   let filteredTokens = $derived(() => {
     const q = query.trim().toLowerCase();
     if (!q) return tokens;
-    return tokens.filter((t: any) =>
+    return tokens.filter((t) =>
       t.name.toLowerCase().includes(q) ||
       t.description?.toLowerCase().includes(q) ||
       t.group?.toLowerCase().includes(q) ||
diff --git a/configurator/src/components/panels/ExportPanel.svelte b/configurator/src/components/panels/ExportPanel.svelte
index 46d8d1dd..c25ef76a 100644
--- a/configurator/src/components/panels/ExportPanel.svelte
+++ b/configurator/src/components/panels/ExportPanel.svelte
@@ -1,6 +1,6 @@
 <script lang="ts">
-  import { Check, Copy, Download, Link } from 'lucide-svelte';
-  import { fa, qa } from '../../lib/codec';
+  import { Check, Copy, Download, Link } from '@lucide/svelte';
+  import { generateCSS, buildShareUrl } from '../../lib/codec';
 
   let { overrides }: {
     overrides: Record<string, string>;
@@ -10,7 +10,7 @@
   let copied = $state(false);
   let copiedLink = $state(false);
 
-  let css = $derived(fa(overrides, { mode: outputMode, banner: true }));
+  let css = $derived(generateCSS(overrides, { mode: outputMode, banner: true }));
   let count = $derived(Object.keys(overrides).length);
 
   async function handleCopy() {
@@ -23,7 +23,7 @@
 
   async function handleCopyLink() {
     try {
-      const url = qa(overrides);
+      const url = buildShareUrl(overrides);
       await navigator.clipboard.writeText(url);
       copiedLink = true;
       setTimeout(() => { copiedLink = false; }, 2000);
diff --git a/configurator/src/components/panels/HomePanel.svelte b/configurator/src/components/panels/HomePanel.svelte
index 60eda01e..3a695283 100644
--- a/configurator/src/components/panels/HomePanel.svelte
+++ b/configurator/src/components/panels/HomePanel.svelte
@@ -2,7 +2,7 @@
   import {
     Sparkles, Palette, Type, Ruler, Layout, Square, Layers, Zap,
     Puzzle, Blocks, SwatchBook, ShieldCheck, Package, BookOpen, Save,
-  } from 'lucide-svelte';
+  } from '@lucide/svelte';
   import type { SavedSlot } from '../../types';
   import { listSavedThemes, saveTheme } from '../../lib/savedThemes';
 
diff --git a/configurator/src/components/panels/ThemesPanel.svelte b/configurator/src/components/panels/ThemesPanel.svelte
index f972e078..5c95a3aa 100644
--- a/configurator/src/components/panels/ThemesPanel.svelte
+++ b/configurator/src/components/panels/ThemesPanel.svelte
@@ -1,5 +1,5 @@
 <script lang="ts">
-  import { Save, Trash2, Check } from 'lucide-svelte';
+  import { Save, Trash2, Check } from '@lucide/svelte';
   import type { SavedSlot } from '../../types';
   import { listSavedThemes, saveTheme, deleteTheme } from '../../lib/savedThemes';
 
diff --git a/configurator/src/components/shell/PreviewPanel.svelte b/configurator/src/components/shell/PreviewPanel.svelte
index 0539f5aa..52645254 100644
--- a/configurator/src/components/shell/PreviewPanel.svelte
+++ b/configurator/src/components/shell/PreviewPanel.svelte
@@ -1,7 +1,7 @@
 <script lang="ts">
-  import { Sun, Moon, Smartphone, Tablet, Monitor, RefreshCw, ExternalLink, Columns2 } from 'lucide-svelte';
+  import { Sun, Moon, Smartphone, Tablet, Monitor, RefreshCw, ExternalLink, Columns2 } from '@lucide/svelte';
   import type { PreviewTemplate } from '../../types';
-  import { fa } from '../../lib/codec';
+  import { generateCSS } from '../../lib/codec';
   import { computeDerivedOverrides } from '../../lib/persistence';
   import { registerPreviewDoc, bumpPreviewVersion } from '../../lib/previewResolver.svelte';
   import { lumlockerPreview } from '../../lib/lumlockerPreview.svelte';
@@ -429,7 +429,7 @@
     template: PreviewTemplate,
     frameworkCSS: string,
   ): string {
-    const css = fa(withDerivedOverrides(ov), { mode: "root", banner: false });
+    const css = generateCSS(withDerivedOverrides(ov), { mode: "root", banner: false });
     const motionCSS =
       motion === "slow"
         ? "*, *::before, *::after { transition-duration: 200% !important; animation-duration: 200% !important; }"
@@ -481,70 +481,108 @@ ${BODIES[template]}
   let htmlLight = $derived(buildIframeHTML({}, "light", previewMotion, previewTemplate, frameworkCSSStatic));
   let htmlDark = $derived(buildIframeHTML({}, "dark", previewMotion, previewTemplate, frameworkCSSStatic));
 
+  // SL-020: the DOM writes below (style/attribute mutation on the iframe
+  // document, plus bumpPreviewVersion()'s resolveCache.clear()) are cheap
+  // individually but these effects re-run on every override tick — e.g. every
+  // input event while dragging a slider, many times per animation frame.
+  // rAF-coalescing collapses a burst of same-frame reruns into a single
+  // apply using the latest captured values ("coalesce to latest"), since only
+  // the frame actually painted to the user matters. The effect body above
+  // this comment still runs synchronously on every change (so Svelte's
+  // dependency tracking is unaffected) — only the DOM-writing work below is
+  // deferred. The `return () => cancelAnimationFrame(rafId)` cleanup fires
+  // before Svelte re-runs this effect (or on unmount), so a still-pending
+  // frame from a superseded run is cancelled before scheduling the next one.
   $effect(() => {
     const _ov = overrides;
     const _theme = previewTheme;
     const _count = loadCount;
     const _lock = lumlockerPreview.value;
 
-    const iframe = iframeEl;
-    if (_count === 0 || !iframe) return;
-    const doc = iframe.contentDocument;
-    if (!doc) return;
+    const rafId = requestAnimationFrame(() => {
+      const iframe = iframeEl;
+      if (_count === 0 || !iframe) return;
+      const doc = iframe.contentDocument;
+      if (!doc) return;
 
-    const styleEl = doc.getElementById("slashed-overrides");
-    if (styleEl) {
-      styleEl.textContent = fa(withDerivedOverrides(_ov), { mode: "root", banner: false });
-    }
+      const styleEl = doc.getElementById("slashed-overrides");
+      if (styleEl) {
+        styleEl.textContent = generateCSS(withDerivedOverrides(_ov), { mode: "root", banner: false });
+      }
+
+      injectFontsIntoDoc(doc, _ov);
 
-    injectFontsIntoDoc(doc, _ov);
+      // Framework activates dark mode via [data-theme="dark"] (color-scheme +
+      // light-dark()), NOT a class — keep this in sync with buildIframeHTML.
+      doc.documentElement.setAttribute("data-theme", _theme);
 
-    // Framework activates dark mode via [data-theme="dark"] (color-scheme +
-    // light-dark()), NOT a class — keep this in sync with buildIframeHTML.
-    doc.documentElement.setAttribute("data-theme", _theme);
+      // Luminance lock preview — mirrors :root[data-lumlocker] in core/themes.css.
+      if (_lock) doc.documentElement.setAttribute("data-lumlocker", "");
+      else doc.documentElement.removeAttribute("data-lumlocker");
 
-    // Luminance lock preview — mirrors :root[data-lumlocker] in core/themes.css.
-    if (_lock) doc.documentElement.setAttribute("data-lumlocker", "");
-    else doc.documentElement.removeAttribute("data-lumlocker");
+      // This single-mode iframe is the canonical resolver source.
+      // registerPreviewDoc() always bumps internally (both its
+      // activeDoc-unchanged early-return and its replace-doc path do), so an
+      // explicit bumpPreviewVersion() here would double-bump/double-clear
+      // resolveCache for no reason.
+      registerPreviewDoc(doc);
+    });
 
-    // This single-mode iframe is the canonical resolver source.
-    registerPreviewDoc(doc);
-    bumpPreviewVersion();
+    return () => cancelAnimationFrame(rafId);
   });
 
   $effect(() => {
+    const _splitMode = splitMode;
     const _ov = overrides;
     const _lightCount = splitLightLoadCount;
     const _darkCount = splitDarkLoadCount;
     const _lock = lumlockerPreview.value;
-    const css = fa(withDerivedOverrides(_ov), { mode: "root", banner: false });
 
-    const applyLock = (doc: Document) => {
-      if (_lock) doc.documentElement.setAttribute("data-lumlocker", "");
-      else doc.documentElement.removeAttribute("data-lumlocker");
-    };
-
-    if (splitLightEl && _lightCount > 0) {
-      const doc = splitLightEl.contentDocument;
-      if (doc) {
-        const styleEl = doc.getElementById("slashed-overrides");
-        if (styleEl) styleEl.textContent = css;
-        injectFontsIntoDoc(doc, _ov);
-        applyLock(doc);
-        // In split mode the light pane is the canonical resolver source.
-        registerPreviewDoc(doc);
+    // Split iframes only exist in the DOM under {#if splitMode} below — skip
+    // scheduling entirely rather than doing per-frame no-op work while the
+    // single-iframe effect above is the one actually driving the preview.
+    if (!_splitMode) return;
+
+    const rafId = requestAnimationFrame(() => {
+      const css = generateCSS(withDerivedOverrides(_ov), { mode: "root", banner: false });
+
+      const applyLock = (doc: Document) => {
+        if (_lock) doc.documentElement.setAttribute("data-lumlocker", "");
+        else doc.documentElement.removeAttribute("data-lumlocker");
+      };
+
+      // registerPreviewDoc() (light pane) already bumps internally; only
+      // bump explicitly when the dark pane was the sole one updated this
+      // frame, so consumers still get notified without double-bumping.
+      let lightApplied = false;
+      let darkApplied = false;
+
+      if (splitLightEl && _lightCount > 0) {
+        const doc = splitLightEl.contentDocument;
+        if (doc) {
+          const styleEl = doc.getElementById("slashed-overrides");
+          if (styleEl) styleEl.textContent = css;
+          injectFontsIntoDoc(doc, _ov);
+          applyLock(doc);
+          // In split mode the light pane is the canonical resolver source.
+          registerPreviewDoc(doc);
+          lightApplied = true;
+        }
       }
-    }
-    if (splitDarkEl && _darkCount > 0) {
-      const doc = splitDarkEl.contentDocument;
-      if (doc) {
-        const styleEl = doc.getElementById("slashed-overrides");
-        if (styleEl) styleEl.textContent = css;
-        injectFontsIntoDoc(doc, _ov);
-        applyLock(doc);
+      if (splitDarkEl && _darkCount > 0) {
+        const doc = splitDarkEl.contentDocument;
+        if (doc) {
+          const styleEl = doc.getElementById("slashed-overrides");
+          if (styleEl) styleEl.textContent = css;
+          injectFontsIntoDoc(doc, _ov);
+          applyLock(doc);
+          darkApplied = true;
+        }
       }
-    }
-    bumpPreviewVersion();
+      if (darkApplied && !lightApplied) bumpPreviewVersion();
+    });
+
+    return () => cancelAnimationFrame(rafId);
   });
 
   let isConstrained = $derived(previewWidth !== "fluid");
diff --git a/configurator/src/components/shell/SidebarNav.svelte b/configurator/src/components/shell/SidebarNav.svelte
index 2cea2cb1..d8a0d872 100644
--- a/configurator/src/components/shell/SidebarNav.svelte
+++ b/configurator/src/components/shell/SidebarNav.svelte
@@ -2,7 +2,7 @@
   import {
     Home, Palette, Type, Ruler, Layout, Square, Layers, Zap, Sparkles, Puzzle,
     Blocks, SwatchBook, ShieldCheck, Package, BookOpen,
-  } from 'lucide-svelte';
+  } from '@lucide/svelte';
 
   let { activeId, onSelect, overridesByDomain = {} }: {
     activeId: string;
diff --git a/configurator/src/components/shell/StudioHeader.svelte b/configurator/src/components/shell/StudioHeader.svelte
index 58b70ac3..8e4ed757 100644
--- a/configurator/src/components/shell/StudioHeader.svelte
+++ b/configurator/src/components/shell/StudioHeader.svelte
@@ -1,6 +1,6 @@
 <script lang="ts">
   import { tick } from 'svelte';
-  import { Undo2, Redo2, Trash2, Share2, FolderOpen, Check, Save, Loader2 } from 'lucide-svelte';
+  import { Undo2, Redo2, Trash2, Share2, FolderOpen, Check, Save, Loader2, AlertTriangle } from '@lucide/svelte';
 
   const version = typeof __SLASHED_VERSION__ !== "undefined" ? __SLASHED_VERSION__ : "";
 
@@ -9,7 +9,7 @@
     canUndo: boolean;
     canRedo: boolean;
     hasPendingChanges: boolean;
-    saveState: 'idle' | 'saving' | 'saved';
+    saveState: 'idle' | 'saving' | 'saved' | 'error';
     onUndo: () => void;
     onRedo: () => void;
     onResetAll: () => void;
@@ -86,10 +86,12 @@
     <button
       onclick={onSave}
       disabled={!hasPendingChanges || saveState === 'saving'}
-      title={hasPendingChanges ? "Save changes (Ctrl+S)" : "No unsaved changes"}
+      title={saveState === 'error' ? "Save failed — click to retry" : hasPendingChanges ? "Save changes (Ctrl+S)" : "No unsaved changes"}
       class={[
         "flex items-center gap-1.5 px-3 py-1.5 rounded-lg text-[11px] font-bold transition-colors cursor-pointer",
-        saveState === 'saved'
+        saveState === 'error'
+          ? "bg-red-900/40 border border-red-500/30 text-red-300"
+          : saveState === 'saved'
           ? "bg-emerald-900/40 border border-emerald-500/30 text-emerald-300"
           : hasPendingChanges
             ? "bg-emerald-600 hover:bg-emerald-500 text-white shadow-sm shadow-emerald-600/30"
@@ -102,6 +104,9 @@
       {:else if saveState === 'saved'}
         <Check class="w-3.5 h-3.5" />
         Saved
+      {:else if saveState === 'error'}
+        <AlertTriangle class="w-3.5 h-3.5" />
+        Save failed
       {:else}
         <Save class="w-3.5 h-3.5" />
         Save
diff --git a/configurator/src/lib/codec.ts b/configurator/src/lib/codec.ts
index 02bfc29e..7b08c06e 100644
--- a/configurator/src/lib/codec.ts
+++ b/configurator/src/lib/codec.ts
@@ -5,100 +5,108 @@
 
 import { deflateSync, inflateSync } from "fflate";
 import tokensData from "../data/token-registry.generated.json";
+import type { TokenRegistry, DecodeOptions, ShareOptions } from "../types";
 
 declare const __SLASHED_VERSION__: string;
 
-const Wa = tokensData; // The token id registry — append-only map of name → numeric id
-const Ki: string = typeof __SLASHED_VERSION__ !== "undefined" ? __SLASHED_VERSION__ : "0.0.0";
+const frameworkVersion: string = typeof __SLASHED_VERSION__ !== "undefined" ? __SLASHED_VERSION__ : "0.0.0";
 
-const Na = 65535;
-const Pa = new TextEncoder();
-const Fa = new TextDecoder("utf-8", { fatal: false });
-const Ia = 65535;
+export const CODEC_VERSION = 2;
+export const SHARE_PARAM = "c";
+
+// SL-026: MAX_VALUE_BYTES and MAX_ID happen to share the same value (both
+// bounded by the 2-byte length-prefix / id field in the wire format — see
+// encode()'s payload layout below) but are independent limits for unrelated
+// things (a value's encoded byte length vs. a token's registry id). Don't
+// assume changing one should change the other.
+const MAX_VALUE_BYTES = 65535;
+const MAX_ID = 65535;
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder("utf-8", { fatal: false });
 const MAX_COMPRESSED_BYTES = 32 * 1024;
 const MAX_DECOMPRESSED_BYTES = 256 * 1024;
 
-function La(e: number): boolean {
-  return Number.isInteger(e) && e >= 0 && e <= Ia;
+function isValidId(id: number): boolean {
+  return Number.isInteger(id) && id >= 0 && id <= MAX_ID;
 }
 
-function Ra(e: any): Map<string, number> {
-  const t = new Map<string, number>();
-  for (const n of e?.tokens ?? []) {
-    if (n && !n.removed && typeof n.name === "string" && La(n.id)) {
-      t.set(n.name, n.id);
+function buildNameToIdMap(registry: TokenRegistry): Map<string, number> {
+  const nameToId = new Map<string, number>();
+  for (const entry of registry?.tokens ?? []) {
+    if (entry && !entry.removed && typeof entry.name === "string" && isValidId(entry.id)) {
+      nameToId.set(entry.name, entry.id);
     }
   }
-  return t;
+  return nameToId;
 }
 
-function za(e: any): Map<number, string> {
-  const t = new Map<number, string>();
-  for (const n of e?.tokens ?? []) {
-    if (n && typeof n.name === "string" && Number.isInteger(n.id)) {
-      t.set(n.id, n.name);
+function buildIdToNameMap(registry: TokenRegistry): Map<number, string> {
+  const idToName = new Map<number, string>();
+  for (const entry of registry?.tokens ?? []) {
+    if (entry && typeof entry.name === "string" && Number.isInteger(entry.id)) {
+      idToName.set(entry.id, entry.name);
     }
   }
-  return t;
+  return idToName;
 }
 
-function Ba(e: Uint8Array): string {
-  let t = "";
-  for (let n = 0; n < e.length; n++) {
-    t += String.fromCharCode(e[n]);
+function bytesToBase64Url(bytes: Uint8Array): string {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
   }
-  return btoa(t)
+  return btoa(binary)
     .replace(/\+/g, "-")
     .replace(/\//g, "_")
     .replace(/=+$/, "");
 }
 
-function Va(e: string): Uint8Array | null {
+function base64UrlToBytes(value: string): Uint8Array | null {
   try {
-    let t = e.replace(/-/g, "+").replace(/_/g, "/");
-    while (t.length % 4) {
-      t += "=";
+    let base64 = value.replace(/-/g, "+").replace(/_/g, "/");
+    while (base64.length % 4) {
+      base64 += "=";
     }
-    const decoded = atob(t);
-    const n = new Uint8Array(decoded.length);
-    for (let t = 0; t < decoded.length; t++) {
-      n[t] = decoded.charCodeAt(t);
+    const decoded = atob(base64);
+    const bytes = new Uint8Array(decoded.length);
+    for (let j = 0; j < decoded.length; j++) {
+      bytes[j] = decoded.charCodeAt(j);
     }
-    return n;
+    return bytes;
   } catch {
     return null;
   }
 }
 
-export function Ha(e: Record<string, string>, t: any = Wa): string {
-  if (!e || typeof e !== "object") return "";
-  const n = Ra(t);
-  const r: { id: number; valueBytes: Uint8Array }[] = [];
+export function encode(overrides: Record<string, string>, registry: TokenRegistry = tokensData): string {
+  if (!overrides || typeof overrides !== "object") return "";
+  const nameToId = buildNameToIdMap(registry);
+  const entries: { id: number; valueBytes: Uint8Array }[] = [];
 
-  for (const [key, val] of Object.entries(e)) {
+  for (const [key, val] of Object.entries(overrides)) {
     if (typeof key !== "string" || typeof val !== "string" || val === "") continue;
-    const id = n.get(key);
+    const id = nameToId.get(key);
     if (id === undefined) continue;
-    const valueBytes = Pa.encode(val);
-    if (valueBytes.length > Na) continue;
-    r.push({ id, valueBytes });
+    const valueBytes = textEncoder.encode(val);
+    if (valueBytes.length > MAX_VALUE_BYTES) continue;
+    entries.push({ id, valueBytes });
   }
 
-  if (r.length === 0) return "";
-  r.sort((a, b) => a.id - b.id);
+  if (entries.length === 0) return "";
+  entries.sort((a, b) => a.id - b.id);
 
   let payloadLen = 0;
-  for (const item of r) payloadLen += 4 + item.valueBytes.length;
+  for (const item of entries) payloadLen += 4 + item.valueBytes.length;
 
   const payload = new Uint8Array(payloadLen);
-  let o = 0;
-  for (const { id, valueBytes } of r) {
-    payload[o++] = (id >> 8) & 255;
-    payload[o++] = id & 255;
-    payload[o++] = (valueBytes.length >> 8) & 255;
-    payload[o++] = valueBytes.length & 255;
-    payload.set(valueBytes, o);
-    o += valueBytes.length;
+  let offset = 0;
+  for (const { id, valueBytes } of entries) {
+    payload[offset++] = (id >> 8) & 255;
+    payload[offset++] = id & 255;
+    payload[offset++] = (valueBytes.length >> 8) & 255;
+    payload[offset++] = valueBytes.length & 255;
+    payload.set(valueBytes, offset);
+    offset += valueBytes.length;
   }
 
   const compressed = deflateSync(payload);
@@ -107,19 +115,19 @@ export function Ha(e: Record<string, string>, t: any = Wa): string {
     return "";
   }
   const out = new Uint8Array(1 + compressed.length);
-  out[0] = 2;
+  out[0] = CODEC_VERSION;
   out.set(compressed, 1);
-  return Ba(out);
+  return bytesToBase64Url(out);
 }
 
-export function Ua(e: string, t: any = Wa, n: any = {}): Record<string, string> {
-  const r = String(e ?? "").trim();
-  if (r === "") return {};
-  const rawBytes = Va(r);
+export function decode(code: string, registry: TokenRegistry = tokensData, options: DecodeOptions = {}): Record<string, string> {
+  const trimmed = String(code ?? "").trim();
+  if (trimmed === "") return {};
+  const rawBytes = base64UrlToBytes(trimmed);
   if (!rawBytes || rawBytes.length === 0) return {};
 
-  if (rawBytes[0] !== 2) {
-    console.warn(`[codec] unknown config-code version ${rawBytes[0]} (expected 2); ignoring.`);
+  if (rawBytes[0] !== CODEC_VERSION) {
+    console.warn(`[codec] unknown config-code version ${rawBytes[0]} (expected ${CODEC_VERSION}); ignoring.`);
     return {};
   }
 
@@ -129,54 +137,54 @@ export function Ua(e: string, t: any = Wa, n: any = {}): Record<string, string>
     return {};
   }
 
-  let i: Uint8Array;
+  let decompressed: Uint8Array;
   try {
-    i = inflateSync(rawBytes.subarray(1));
+    decompressed = inflateSync(rawBytes.subarray(1));
   } catch {
     console.warn("[codec] failed to decompress config; ignoring.");
     return {};
   }
-  if (!i || i.length === 0) return {};
-  if (i.length > MAX_DECOMPRESSED_BYTES) {
-    console.warn(`[codec] decompressed payload too large (${i.length} B > ${MAX_DECOMPRESSED_BYTES} B); ignoring.`);
+  if (!decompressed || decompressed.length === 0) return {};
+  if (decompressed.length > MAX_DECOMPRESSED_BYTES) {
+    console.warn(`[codec] decompressed payload too large (${decompressed.length} B > ${MAX_DECOMPRESSED_BYTES} B); ignoring.`);
     return {};
   }
 
-  const a = za(t);
-  const sanitize = typeof n.sanitize === "function" ? n.sanitize : (val: string) => val;
-  const isKnown = typeof n.isKnown === "function" ? n.isKnown : () => true;
-  const c: Record<string, string> = {};
-  let l = 0;
-  
+  const idToName = buildIdToNameMap(registry);
+  const sanitize = typeof options.sanitize === "function" ? options.sanitize : (val: string) => val;
+  const isKnown = typeof options.isKnown === "function" ? options.isKnown : () => true;
+  const result: Record<string, string> = {};
+  let offset = 0;
+
   try {
-    while (l < i.length) {
-      if (l + 4 > i.length) throw new Error("truncated entry header");
-      const id = (i[l] << 8) | i[l + 1];
-      const valLen = (i[l + 2] << 8) | i[l + 3];
-      l += 4;
-      if (l + valLen > i.length) throw new Error("truncated value");
-      const decodedVal = Fa.decode(i.subarray(l, l + valLen));
-      l += valLen;
-      
-      const tokenName = a.get(id);
+    while (offset < decompressed.length) {
+      if (offset + 4 > decompressed.length) throw new Error("truncated entry header");
+      const id = (decompressed[offset] << 8) | decompressed[offset + 1];
+      const valLen = (decompressed[offset + 2] << 8) | decompressed[offset + 3];
+      offset += 4;
+      if (offset + valLen > decompressed.length) throw new Error("truncated value");
+      const decodedVal = textDecoder.decode(decompressed.subarray(offset, offset + valLen));
+      offset += valLen;
+
+      const tokenName = idToName.get(id);
       if (tokenName === undefined || !isKnown(tokenName)) continue;
       const sanitizedVal = sanitize(decodedVal);
       if (sanitizedVal !== "") {
-        c[tokenName] = sanitizedVal;
+        result[tokenName] = sanitizedVal;
       }
     }
   } catch (err: any) {
     console.warn(`[codec] malformed config code; ignoring (${err.message}).`);
     return {};
   }
-  
-  return c;
+
+  return result;
 }
 
-export function da(e: string | null | undefined): string {
-  return e == null
+export function sanitizeValue(value: string | null | undefined): string {
+  return value == null
     ? ""
-    : String(e)
+    : String(value)
         .replace(/\/\*[\s\S]*?\*\//g, " ")
         .replace(/[;{}]/g, " ")
         .replace(/[/*]{2,}/g, " ")
@@ -184,48 +192,48 @@ export function da(e: string | null | undefined): string {
         .trim();
 }
 
-export function fa(e: Record<string, string>, t: { mode?: "layer" | "root"; banner?: boolean } = {}): string {
-  const { mode = "layer", banner = true } = t;
+export function generateCSS(overrides: Record<string, string>, options: { mode?: "layer" | "root"; banner?: boolean } = {}): string {
+  const { mode = "layer", banner = true } = options;
   // Keys land here from several untrusted-ish entry points (imported JSON,
   // shared URL hash, localStorage, WP hydration) — unlike values, they were
   // never sanitized before being interpolated into the emitted CSS, so a
   // crafted key could break out of its declaration. Every real token name
   // (source or derived) is --sf-<word-chars/hyphens>; anything else is dropped.
-  const i = Object.keys(e).filter((key) => /^--sf-[\w-]+$/.test(key)).sort((a, b) => a.localeCompare(b));
-  if (i.length === 0) return "";
-  
-  const a = i.map((key) => `${key}: ${da(e[key])};`);
-  const o = mode === "layer" ? "\t\t" : "\t";
-  const s = a.map((val) => `${o}${val}`).join("\n");
-  let c = "";
-  
+  const keys = Object.keys(overrides).filter((key) => /^--sf-[\w-]+$/.test(key)).sort((a, b) => a.localeCompare(b));
+  if (keys.length === 0) return "";
+
+  const lines = keys.map((key) => `${key}: ${sanitizeValue(overrides[key])};`);
+  const indent = mode === "layer" ? "\t\t" : "\t";
+  const body = lines.map((val) => `${indent}${val}`).join("\n");
+  let output = "";
+
   if (banner) {
-    c += `/* SLASHED override tokens v${Ki} — generated by the SLASHED configurator.\n   Load this AFTER the SLASHED stylesheet. ${i.length} token${i.length === 1 ? "" : "s"} customised. */\n`;
+    output += `/* SLASHED override tokens v${frameworkVersion} — generated by the SLASHED configurator.\n   Load this AFTER the SLASHED stylesheet. ${keys.length} token${keys.length === 1 ? "" : "s"} customised. */\n`;
   }
-  
+
   return mode === "layer"
-    ? `${c}@layer slashed.overrides {\n\t:root {\n${s}\n\t}\n}\n`
-    : `${c}:root {\n${s}\n}\n`;
+    ? `${output}@layer slashed.overrides {\n\t:root {\n${body}\n\t}\n}\n`
+    : `${output}:root {\n${body}\n}\n`;
 }
 
-export function pa(e: string): Record<string, string> {
-  const t: Record<string, string> = {};
-  if (!e) return t;
-  const n = e.replace(/\/\*[\s\S]*?\*\//g, "");
-  const r = /(--sf-[\w-]+)\s*:/g;
-  let i;
-  
-  while ((i = r.exec(n)) !== null) {
-    const key = i[1];
-    let index = i.index + i[0].length;
+export function parseCSS(css: string): Record<string, string> {
+  const result: Record<string, string> = {};
+  if (!css) return result;
+  const stripped = css.replace(/\/\*[\s\S]*?\*\//g, "");
+  const declarationRe = /(--sf-[\w-]+)\s*:/g;
+  let match;
+
+  while ((match = declarationRe.exec(stripped)) !== null) {
+    const key = match[1];
+    let index = match.index + match[0].length;
     let parenCount = 0;
     let quoteChar = "";
     let accumulatedValue = "";
-    
-    for (; index < n.length; index++) {
-      const char = n[index];
+
+    for (; index < stripped.length; index++) {
+      const char = stripped[index];
       if (quoteChar) {
-        if (char === quoteChar && n[index - 1] !== "\\") {
+        if (char === quoteChar && stripped[index - 1] !== "\\") {
           quoteChar = "";
         }
       } else if (char === '"' || char === "'") {
@@ -239,54 +247,44 @@ export function pa(e: string): Record<string, string> {
       }
       accumulatedValue += char;
     }
-    
+
     const trimmedVal = accumulatedValue.replace(/\s+/g, " ").trim();
     if (trimmedVal !== "") {
-      t[key] = trimmedVal;
+      result[key] = trimmedVal;
     }
-    r.lastIndex = index;
+    declarationRe.lastIndex = index;
   }
-  
-  return t;
+
+  return result;
 }
 
-export function Ga(e: Record<string, string>): string {
-  return Ha(e, Wa);
+export function encodeOverrides(overrides: Record<string, string>): string {
+  return encode(overrides, tokensData);
 }
 
-export function Ka(e: string, t: any = {}): Record<string, string> {
-  const knownTokensSet = new Set(Wa.tokens.map((tok: any) => tok.name));
-  const isKnown = t.isKnown ?? ((name: string) => knownTokensSet.has(name));
-  let r = String(e ?? "").trim();
-  const i = r.match(/[#&]?c=([^&]+)/);
-  if (i) {
-    r = i[1];
+const SHARE_PARAM_RE = new RegExp(`[#&]?${SHARE_PARAM}=([^&]+)`);
+
+export function readShareFromHash(hashOrParam: string, options: ShareOptions = {}): Record<string, string> {
+  const knownTokensSet = new Set(tokensData.tokens.map((tok) => tok.name));
+  const isKnown = options.isKnown ?? ((name: string) => knownTokensSet.has(name));
+  let trimmed = String(hashOrParam ?? "").trim();
+  const match = trimmed.match(SHARE_PARAM_RE);
+  if (match) {
+    trimmed = match[1];
   }
-  return Ua(r, Wa, { sanitize: da, isKnown });
+  return decode(trimmed, tokensData, { sanitize: sanitizeValue, isKnown });
 }
 
-export function qa(e: Record<string, string>, t?: string): string {
+export function buildShareUrl(overrides: Record<string, string>, baseUrlOverride?: string): string {
   const fallbackUrl = typeof window !== "undefined" ? window.location.href : "https://example.com/";
-  const baseUrl = t ?? fallbackUrl;
-  const r = new URL(baseUrl);
-  const code = Ga(e);
-  r.hash = code ? `c=${code}` : "";
-  return r.toString();
+  const baseUrl = baseUrlOverride ?? fallbackUrl;
+  const url = new URL(baseUrl);
+  const code = encodeOverrides(overrides);
+  url.hash = code ? `${SHARE_PARAM}=${code}` : "";
+  return url.toString();
 }
 
-export function Ja(e: string, t: any = {}): Record<string, string> {
-  const n = String(e ?? "");
-  return n.includes("c=") ? Ka(n, t) : {};
+export function readShareFromHashIfPresent(hash: string, options: ShareOptions = {}): Record<string, string> {
+  const value = String(hash ?? "");
+  return value.includes(`${SHARE_PARAM}=`) ? readShareFromHash(value, options) : {};
 }
-
-// Named aliases for tests and external consumers
-export const encode = Ha;
-export const decode = Ua;
-export const sanitizeValue = da;
-export const generateCSS = fa;
-export const parseCSS = pa;
-export const encodeOverrides = Ga;
-export const buildShareUrl = qa;
-export const readShareFromHash = Ka;
-export const CODEC_VERSION = 2;
-export const SHARE_PARAM = "c";
diff --git a/configurator/src/lib/persistence.ts b/configurator/src/lib/persistence.ts
index ea5e2c16..3e2fd72b 100644
--- a/configurator/src/lib/persistence.ts
+++ b/configurator/src/lib/persistence.ts
@@ -13,7 +13,8 @@
  * In every mode a live `<style id="sf-parent-overrides">` is injected so the
  * chrome + preview reflect the current overrides immediately.
  */
-import { Ja, Ga, fa } from "./codec";
+import { readShareFromHashIfPresent, encodeOverrides, generateCSS } from "./codec";
+import { isStringRecord } from "./savedThemes";
 
 const LS_KEY = "slashed-studio/overrides/v2";
 
@@ -212,11 +213,14 @@ export function loadInitialOverrides(): Record<string, string> {
   // Standalone: URL hash (shareable config) takes priority over localStorage.
   const hash = window.location.hash;
   if (hash?.includes("c=")) {
-    try { return Ja(hash); } catch { /* fall through */ }
+    try { return readShareFromHashIfPresent(hash); } catch { /* fall through */ }
   }
   const local = localStorage.getItem(LS_KEY);
   if (local) {
-    try { return JSON.parse(local); } catch { /* fall through */ }
+    try {
+      const parsed: unknown = JSON.parse(local);
+      if (isStringRecord(parsed)) return parsed;
+    } catch { /* fall through */ }
   }
   return {};
 }
@@ -235,7 +239,7 @@ export function injectLivePreview(ov: Record<string, string>): void {
   const reduceMotion = typeof window !== "undefined" && window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
   const derived = computeDerivedOverrides(ov, { reduceMotion });
   const preview = Object.keys(derived).length > 0 ? { ...derived, ...ov } : ov;
-  styleEl.textContent = fa(preview, { mode: "root", banner: false });
+  styleEl.textContent = generateCSS(preview, { mode: "root", banner: false });
 }
 
 async function wpSave(rest: { url?: string; nonce?: string }, ov: Record<string, string>): Promise<void> {
@@ -259,7 +263,7 @@ async function wpSave(rest: { url?: string; nonce?: string }, ov: Record<string,
 
 function saveStandalone(ov: Record<string, string>): void {
   try { localStorage.setItem(LS_KEY, JSON.stringify(ov)); } catch { /* quota */ }
-  const code = Ga(ov);
+  const code = encodeOverrides(ov);
   const nextHash = code ? `c=${code}` : "";
   if (window.location.hash.replace("#", "") !== nextHash) {
     window.location.hash = nextHash;
diff --git a/configurator/src/lib/previewResolver.svelte.ts b/configurator/src/lib/previewResolver.svelte.ts
index 819eb0ec..c55066c7 100644
--- a/configurator/src/lib/previewResolver.svelte.ts
+++ b/configurator/src/lib/previewResolver.svelte.ts
@@ -34,6 +34,14 @@ let probeDarkEl: HTMLElement | null = null;
 // function is a pure write with no reactive read, so clearing here can't cause loops.
 const resolveCache = new Map<string, string>();
 
+// SL-025: deliberately module-level (not created inside a component/store
+// factory). Every panel across the whole tree resolves colors against the
+// *same* single preview iframe registered via registerPreviewDoc(), so there
+// is exactly one meaningful "preview version" for the app to share — scoping
+// this to a component would just mean re-deriving/passing it down everywhere
+// for no benefit. Wrapped in an object (`.value`) because `$state` on a bare
+// module-level primitive isn't itself reactive outside a component context;
+// consumers read `previewVersion.value`, never reassign `previewVersion`.
 /** Reactive version counter — Svelte runes pick this up via `.value`. */
 export const previewVersion = $state({ value: 0 });
 
diff --git a/configurator/src/lib/savedThemes.ts b/configurator/src/lib/savedThemes.ts
index 364f8026..cb765ef3 100644
--- a/configurator/src/lib/savedThemes.ts
+++ b/configurator/src/lib/savedThemes.ts
@@ -10,7 +10,7 @@ import type { SavedSlot } from "../types";
 
 const LS_KEY = "slashed-studio/themes/v1";
 
-function isStringRecord(value: unknown): value is Record<string, string> {
+export function isStringRecord(value: unknown): value is Record<string, string> {
   return !!value
     && typeof value === "object"
     && !Array.isArray(value)
diff --git a/configurator/src/types.ts b/configurator/src/types.ts
index 7d18d08c..8f576474 100644
--- a/configurator/src/types.ts
+++ b/configurator/src/types.ts
@@ -19,6 +19,68 @@ export interface SlashedToken {
   syntax?: string | null;
 }
 
+// SL-017/024: types for the two consumed-generated-JSON shapes and codec.ts's
+// options objects, replacing `any` at their 7 call sites.
+
+/** A token entry as it appears in data/api-index.generated.json's `tokens` array. */
+export interface ApiIndexToken extends SlashedToken {
+  fallbackOnly?: boolean;
+  optional?: boolean;
+  layer?: string | null;
+  bundles?: string[];
+}
+
+/** Shape of data/api-index.generated.json (configurator/scripts/sync-api.mjs's output). */
+export interface ApiIndex {
+  _sync?: Record<string, unknown>;
+  tokens: ApiIndexToken[];
+}
+
+/** A class entry as it appears in data/classes.generated.json's `classes` array. */
+export interface SlashedClass {
+  name: string;
+  selector: string;
+  kind: string;
+  category: string;
+  group?: string;
+  description?: string;
+  optional?: boolean;
+  layer?: string | null;
+}
+
+/** Shape of data/classes.generated.json (configurator/scripts/sync-api.mjs's output). */
+export interface ClassIndex {
+  _sync?: Record<string, unknown>;
+  classes: SlashedClass[];
+}
+
+/** A registry entry as it appears in data/token-registry.generated.json's `tokens` array. */
+export interface TokenRegistryEntry {
+  id: number;
+  name: string;
+  removed?: boolean;
+}
+
+/** Shape of data/token-registry.generated.json, consumed by codec.ts's encode/decode. */
+export interface TokenRegistry {
+  _meta?: Record<string, unknown>;
+  tokens: TokenRegistryEntry[];
+}
+
+/** Options accepted by codec.ts's decode(). */
+export interface DecodeOptions {
+  sanitize?: (value: string) => string;
+  isKnown?: (tokenName: string) => boolean;
+}
+
+/**
+ * Options accepted by codec.ts's readShareFromHash() / readShareFromHashIfPresent().
+ * Deliberately omits `sanitize` (unlike DecodeOptions): these are the public
+ * share-link entry points and always force sanitizeValue as a CSS-injection
+ * safeguard, so a caller-supplied sanitize is never honoured.
+ */
+export type ShareOptions = Pick<DecodeOptions, "isKnown">;
+
 export interface SlashedCategory {
   id: string;
   label: string;
diff --git a/configurator/tests-components/header.test.js b/configurator/tests-components/header.test.js
index 15c940ed..e34bf67f 100644
--- a/configurator/tests-components/header.test.js
+++ b/configurator/tests-components/header.test.js
@@ -2,7 +2,7 @@
  * Component smoke test for StudioHeader.
  * Verifies that the header renders the branding text and responds to props.
  */
-import { describe, test, expect } from 'vitest';
+import { describe, test, expect, vi } from 'vitest';
 import { render, screen } from '@testing-library/svelte';
 import StudioHeader from '../src/components/shell/StudioHeader.svelte';
 
@@ -10,11 +10,14 @@ const baseProps = {
   overridesCount: 0,
   canUndo: false,
   canRedo: false,
+  hasPendingChanges: false,
+  saveState: 'idle',
   onUndo: () => {},
   onRedo: () => {},
   onResetAll: () => {},
   onImport: () => {},
   onExport: () => {},
+  onSave: () => {},
 };
 
 describe('StudioHeader', () => {
@@ -44,4 +47,50 @@ describe('StudioHeader', () => {
     render(StudioHeader, { props: { ...baseProps, overridesCount: 0 } });
     expect(screen.queryByText('customised · Export →')).toBeNull();
   });
+
+  // SL-018: a failed save must be visibly distinguishable from "never
+  // attempted" (idle) or "in progress" (saving), and must stay retryable.
+  describe('save state', () => {
+    test('idle: save button is disabled and reads "Save" when there are no pending changes', () => {
+      render(StudioHeader, { props: { ...baseProps, hasPendingChanges: false, saveState: 'idle' } });
+      const btn = screen.getByTitle('No unsaved changes');
+      expect(btn).toBeDisabled();
+      expect(btn).toHaveTextContent('Save');
+    });
+
+    test('idle: save button is enabled when there are pending changes', () => {
+      render(StudioHeader, { props: { ...baseProps, hasPendingChanges: true, saveState: 'idle' } });
+      expect(screen.getByTitle('Save changes (Ctrl+S)')).not.toBeDisabled();
+    });
+
+    test('saving: button is disabled and reads "Saving…" regardless of pending changes', () => {
+      render(StudioHeader, { props: { ...baseProps, hasPendingChanges: true, saveState: 'saving' } });
+      const btn = screen.getByTitle('Save changes (Ctrl+S)');
+      expect(btn).toBeDisabled();
+      expect(btn).toHaveTextContent('Saving…');
+    });
+
+    test('saved: button reads "Saved" with a distinct title from a fresh, unattempted save', () => {
+      render(StudioHeader, { props: { ...baseProps, hasPendingChanges: false, saveState: 'saved' } });
+      const btn = screen.getByTitle('No unsaved changes');
+      expect(btn).toHaveTextContent('Saved');
+    });
+
+    test('error: button surfaces a distinct "Save failed" title and label, and stays clickable to retry', async () => {
+      const onSave = vi.fn();
+      render(StudioHeader, { props: { ...baseProps, hasPendingChanges: true, saveState: 'error', onSave } });
+      const btn = screen.getByTitle('Save failed — click to retry');
+      expect(btn).toHaveTextContent('Save failed');
+      expect(btn).not.toBeDisabled();
+      await btn.click();
+      expect(onSave).toHaveBeenCalledOnce();
+    });
+
+    test('error: a subsequent save is still blocked while actually saving', () => {
+      // Mirrors App.svelte's handleSave guard (saveState === 'saving' disables
+      // retry) even though the button was left enabled after a prior error.
+      render(StudioHeader, { props: { ...baseProps, hasPendingChanges: true, saveState: 'saving' } });
+      expect(screen.getByTitle('Save changes (Ctrl+S)')).toBeDisabled();
+    });
+  });
 });
diff --git a/configurator/tests-components/token-editing.test.js b/configurator/tests-components/token-editing.test.js
new file mode 100644
index 00000000..a8b0862c
--- /dev/null
+++ b/configurator/tests-components/token-editing.test.js
@@ -0,0 +1,150 @@
+/**
+ * Component tests for the two token-editing primitives every panel is built
+ * from: SliderRow (numeric/raw-CSS knob) and TokenRow (generic bind → set →
+ * reset row). Covers bind (initial render reflects value/override state),
+ * override-set (interacting with the control calls onChange/onSet), and
+ * reset (the reset affordance calls onReset).
+ */
+import { describe, test, expect, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/svelte';
+import SliderRow from '../src/components/inputs/SliderRow.svelte';
+import TokenRow from '../src/components/inputs/TokenRow.svelte';
+
+describe('SliderRow', () => {
+  const baseProps = {
+    label: 'Base size',
+    value: 16,
+    min: 8,
+    max: 32,
+    step: 1,
+    unit: 'px',
+    overridden: false,
+    onChange: () => {},
+    onReset: () => {},
+  };
+
+  test('bind: renders the label and reflects the current value in the number field', () => {
+    render(SliderRow, { props: baseProps });
+    expect(screen.getByText('Base size')).toBeTruthy();
+    expect(screen.getByRole('spinbutton')).toHaveValue(16);
+    expect(screen.getByRole('slider')).toHaveValue('16');
+  });
+
+  test('override-set: dragging the range input fires onChange with a clamped number', async () => {
+    const onChange = vi.fn();
+    render(SliderRow, { props: { ...baseProps, onChange } });
+    const range = screen.getByRole('slider');
+    await fireEvent.input(range, { target: { value: '24' } });
+    expect(onChange).toHaveBeenCalledWith(24);
+  });
+
+  test('override-set: editing the number field fires onChange, clamped to [min, max]', async () => {
+    const onChange = vi.fn();
+    render(SliderRow, { props: { ...baseProps, onChange } });
+    const spinbutton = screen.getByRole('spinbutton');
+    await fireEvent.change(spinbutton, { target: { value: '999' } });
+    expect(onChange).toHaveBeenCalledWith(32); // clamped to max
+  });
+
+  test('reset: reset affordance is absent when not overridden', () => {
+    render(SliderRow, { props: baseProps });
+    expect(screen.queryByText('reset')).toBeNull();
+  });
+
+  test('reset: clicking reset fires onReset when overridden', async () => {
+    const onReset = vi.fn();
+    render(SliderRow, { props: { ...baseProps, overridden: true, onReset } });
+    await fireEvent.click(screen.getByText('reset'));
+    expect(onReset).toHaveBeenCalledOnce();
+  });
+
+  test('raw mode: typing a raw CSS value fires onRawSet', async () => {
+    const onRawSet = vi.fn();
+    render(SliderRow, {
+      props: {
+        ...baseProps,
+        rawDefault: '1rem',
+        currentRaw: 'var(--sf-text-base)', // matches the raw-CSS-expression auto-detect
+        onRawSet,
+      },
+    });
+    const rawInput = screen.getByPlaceholderText('1rem');
+    await fireEvent.input(rawInput, { target: { value: 'clamp(1rem, 2vw, 2rem)' } });
+    expect(onRawSet).toHaveBeenCalledWith('clamp(1rem, 2vw, 2rem)');
+  });
+
+  test('raw mode: clearing the raw field and blurring fires onReset', async () => {
+    const onReset = vi.fn();
+    render(SliderRow, {
+      props: {
+        ...baseProps,
+        overridden: true,
+        rawDefault: '1rem',
+        currentRaw: 'var(--sf-text-base)',
+        onRawSet: () => {},
+        onReset,
+      },
+    });
+    const rawInput = screen.getByPlaceholderText('1rem');
+    await fireEvent.input(rawInput, { target: { value: '' } });
+    await fireEvent.blur(rawInput);
+    expect(onReset).toHaveBeenCalledOnce();
+  });
+});
+
+describe('TokenRow', () => {
+  const token = {
+    name: '--sf-space-m',
+    value: '1rem',
+    tier: 'public',
+    role: 'knob',
+  };
+
+  test('bind: renders the short name and the default value when not overridden', () => {
+    render(TokenRow, { props: { token, onSet: () => {}, onReset: () => {} } });
+    expect(screen.getByText('space-m')).toBeTruthy();
+    expect(screen.getByText('1rem')).toBeTruthy();
+    expect(screen.queryByText('✕')).toBeNull();
+  });
+
+  test('bind: renders the override value and reset affordance when overridden', () => {
+    render(TokenRow, { props: { token, overrideValue: '2rem', onSet: () => {}, onReset: () => {} } });
+    expect(screen.getByText('2rem')).toBeTruthy();
+    expect(screen.getByText('✕')).toBeTruthy();
+  });
+
+  test('override-set: editing the value and blurring with a new value calls onSet', async () => {
+    const onSet = vi.fn();
+    const onReset = vi.fn();
+    render(TokenRow, { props: { token, onSet, onReset } });
+
+    await fireEvent.click(screen.getByTitle('1rem'));
+    const input = screen.getByDisplayValue('1rem');
+    await fireEvent.input(input, { target: { value: '1.5rem' } });
+    await fireEvent.blur(input);
+
+    expect(onSet).toHaveBeenCalledWith('1.5rem');
+    expect(onReset).not.toHaveBeenCalled();
+  });
+
+  test('reset: blurring with the value unchanged from the default calls onReset, not onSet', async () => {
+    const onSet = vi.fn();
+    const onReset = vi.fn();
+    render(TokenRow, { props: { token, overrideValue: '2rem', onSet, onReset } });
+
+    await fireEvent.click(screen.getByTitle('2rem'));
+    const input = screen.getByDisplayValue('2rem');
+    await fireEvent.input(input, { target: { value: '1rem' } }); // back to token.value
+    await fireEvent.blur(input);
+
+    expect(onReset).toHaveBeenCalledOnce();
+    expect(onSet).not.toHaveBeenCalled();
+  });
+
+  test('reset: clicking the ✕ button calls onReset directly', async () => {
+    const onReset = vi.fn();
+    render(TokenRow, { props: { token, overrideValue: '2rem', onSet: () => {}, onReset } });
+    await fireEvent.click(screen.getByText('✕'));
+    expect(onReset).toHaveBeenCalledOnce();
+  });
+});
diff --git a/configurator/tests/persistence.test.js b/configurator/tests/persistence.test.js
new file mode 100644
index 00000000..896839d0
--- /dev/null
+++ b/configurator/tests/persistence.test.js
@@ -0,0 +1,173 @@
+/**
+ * Tests for the persistence seam (src/lib/persistence.ts).
+ *
+ * Contract: standalone mode reads/writes localStorage + URL hash; WP-embedded
+ * mode (window.slashedApp present) reads PHP-hydrated overrides and writes via
+ * REST. Covers both branches of loadInitialOverrides/saveOverrides, including
+ * the malformed-localStorage edge cases fixed by SL-019 (shape-guarded via
+ * savedThemes.ts's isStringRecord()).
+ */
+import { describe, test, expect, beforeEach, afterEach, vi } from 'vitest';
+import registry from '../src/data/token-registry.generated.json';
+import { encodeOverrides } from '../src/lib/codec';
+import { loadInitialOverrides, saveOverrides, isEmbedded, hasWpBoot } from '../src/lib/persistence';
+
+const LS_KEY = 'slashed-studio/overrides/v2';
+const active = registry.tokens.filter((t) => !t.removed);
+const t0 = active[0].name;
+const t1 = active[1].name;
+
+function resetEnv() {
+  localStorage.clear();
+  window.location.hash = '';
+  delete window.slashedApp;
+  vi.unstubAllGlobals();
+}
+
+beforeEach(resetEnv);
+afterEach(resetEnv);
+
+describe('loadInitialOverrides — WP-embedded mode', () => {
+  test('returns a copy of window.slashedApp.overrides when present', () => {
+    const boot = { overrides: { [t0]: '1rem' } };
+    window.slashedApp = boot;
+    const result = loadInitialOverrides();
+    expect(result).toEqual({ [t0]: '1rem' });
+    expect(result).not.toBe(boot.overrides); // copy, not the same reference
+  });
+
+  test('returns {} when slashedApp is present but overrides is missing', () => {
+    window.slashedApp = { rest: { url: '/wp-json/slashed/v1' } };
+    expect(loadInitialOverrides()).toEqual({});
+  });
+
+  test('returns {} (not the stale array) when overrides is an array, ignoring any hash/localStorage', () => {
+    localStorage.setItem(LS_KEY, JSON.stringify({ [t0]: 'should-not-be-used' }));
+    window.slashedApp = { overrides: [] };
+    expect(loadInitialOverrides()).toEqual({});
+  });
+
+  test('does not fall through to localStorage when embedded, even with no overrides', () => {
+    localStorage.setItem(LS_KEY, JSON.stringify({ [t0]: 'should-not-be-used' }));
+    window.slashedApp = {};
+    expect(loadInitialOverrides()).toEqual({});
+  });
+});
+
+describe('loadInitialOverrides — standalone mode', () => {
+  test('reads a shareable config from the URL hash, taking priority over localStorage', () => {
+    localStorage.setItem(LS_KEY, JSON.stringify({ [t1]: 'from-local-storage' }));
+    const code = encodeOverrides({ [t0]: '2rem' });
+    window.location.hash = `c=${code}`;
+    expect(loadInitialOverrides()).toEqual({ [t0]: '2rem' });
+  });
+
+  test('falls back to localStorage when the hash has no c= param', () => {
+    localStorage.setItem(LS_KEY, JSON.stringify({ [t1]: '3rem' }));
+    window.location.hash = '';
+    expect(loadInitialOverrides()).toEqual({ [t1]: '3rem' });
+  });
+
+  test('an undecodable hash wins over localStorage and resolves to {} (codec never throws)', () => {
+    // readShareFromHashIfPresent/decode swallow malformed input internally and
+    // return {} rather than throwing (see share.test.js), so the try/catch in
+    // loadInitialOverrides never actually triggers its localStorage fallback
+    // for a garbage — as opposed to absent — c= param.
+    localStorage.setItem(LS_KEY, JSON.stringify({ [t1]: '4rem' }));
+    window.location.hash = 'c=!!!not-valid-base64!!!';
+    expect(loadInitialOverrides()).toEqual({});
+  });
+
+  test('returns {} when there is neither a hash nor localStorage data', () => {
+    expect(loadInitialOverrides()).toEqual({});
+  });
+
+  test('returns {} when localStorage holds malformed JSON', () => {
+    localStorage.setItem(LS_KEY, '{not json');
+    expect(loadInitialOverrides()).toEqual({});
+  });
+
+  // SL-019: loadInitialOverrides' standalone/localStorage path now reuses
+  // savedThemes.ts's isStringRecord() shape guard, matching that module's
+  // equivalent read path, instead of trusting JSON.parse's result outright.
+  test('SL-019: returns {} for non-object JSON instead of passing it through', () => {
+    localStorage.setItem(LS_KEY, JSON.stringify(['not', 'an', 'object']));
+    expect(loadInitialOverrides()).toEqual({});
+  });
+
+  test('SL-019: returns {} when a value in the stored record is not a string', () => {
+    localStorage.setItem(LS_KEY, JSON.stringify({ [t0]: '5rem', [t1]: 42 }));
+    expect(loadInitialOverrides()).toEqual({});
+  });
+});
+
+describe('saveOverrides — standalone mode', () => {
+  test('writes overrides to localStorage and encodes them into the URL hash', () => {
+    const ov = { [t0]: '5rem' };
+    return saveOverrides(ov).then(() => {
+      expect(JSON.parse(localStorage.getItem(LS_KEY))).toEqual(ov);
+      expect(window.location.hash).toBe(`#c=${encodeOverrides(ov)}`);
+    });
+  });
+
+  test('clears the hash when saving an empty overrides map', async () => {
+    window.location.hash = `c=${encodeOverrides({ [t0]: '1rem' })}`;
+    await saveOverrides({});
+    expect(window.location.hash).toBe('');
+  });
+});
+
+describe('saveOverrides — WP-embedded (REST) mode', () => {
+  test('POSTs to <rest.url>/tokens/overrides with the nonce header and overrides body', async () => {
+    window.slashedApp = { rest: { url: `${window.location.origin}/wp-json/slashed/v1`, nonce: 'abc123' } };
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 200, statusText: 'OK' });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const ov = { [t0]: '6rem' };
+    await saveOverrides(ov);
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(url).toBe(`${window.location.origin}/wp-json/slashed/v1/tokens/overrides`);
+    expect(init.method).toBe('POST');
+    expect(init.headers['X-WP-Nonce']).toBe('abc123');
+    expect(JSON.parse(init.body)).toEqual({ overrides: ov });
+    // REST save must never touch localStorage/hash — that's the standalone path only.
+    expect(localStorage.getItem(LS_KEY)).toBeNull();
+  });
+
+  test('rejects when the REST response is not ok', async () => {
+    window.slashedApp = { rest: { url: `${window.location.origin}/wp-json/slashed/v1`, nonce: 'abc123' } };
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: false, status: 500, statusText: 'Internal Server Error' }));
+
+    await expect(saveOverrides({ [t0]: '7rem' })).rejects.toThrow(/save failed 500/);
+  });
+
+  test('rejects before fetching when the REST URL is cross-origin', async () => {
+    window.slashedApp = { rest: { url: 'https://evil.example.com/wp-json/slashed/v1', nonce: 'abc123' } };
+    const fetchMock = vi.fn();
+    vi.stubGlobal('fetch', fetchMock);
+
+    await expect(saveOverrides({ [t0]: '8rem' })).rejects.toThrow(/same-origin/);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});
+
+describe('isEmbedded / hasWpBoot', () => {
+  test('both false in standalone mode', () => {
+    expect(isEmbedded()).toBe(false);
+    expect(hasWpBoot()).toBe(false);
+  });
+
+  test('hasWpBoot is true but isEmbedded is false when slashedApp has no rest.url', () => {
+    window.slashedApp = { overrides: {} };
+    expect(hasWpBoot()).toBe(true);
+    expect(isEmbedded()).toBe(false);
+  });
+
+  test('both true when slashedApp has a rest.url', () => {
+    window.slashedApp = { rest: { url: '/wp-json/slashed/v1' } };
+    expect(hasWpBoot()).toBe(true);
+    expect(isEmbedded()).toBe(true);
+  });
+});
diff --git a/configurator/tests/previewResolver.test.js b/configurator/tests/previewResolver.test.js
new file mode 100644
index 00000000..49c068af
--- /dev/null
+++ b/configurator/tests/previewResolver.test.js
@@ -0,0 +1,205 @@
+/**
+ * Tests for previewResolver.svelte.ts — resolves real, browser-computed
+ * colors from the live preview iframe, with a per-version cache cleared on
+ * every bumpPreviewVersion() call (see PreviewPanel.svelte's SL-020
+ * rAF-coalesced effects, which are the production callers of that clear).
+ *
+ * Uses a real <iframe> rather than document.implementation.createHTMLDocument():
+ * jsdom's getComputedStyle only resolves colors on documents that have a
+ * defaultView, which a detached document lacks but an iframe's contentDocument
+ * has — matching how PreviewPanel.svelte registers a real iframe in production.
+ *
+ * jsdom doesn't implement CSS custom-property substitution or color functions
+ * (var()/oklch()/color-mix()), so fixtures use plain, jsdom-resolvable values
+ * (keyword/hex colors) — these tests exercise the resolver's caching/
+ * invalidation/theme-scoping logic, not real CSS cascade computation (the
+ * browser's job, already trusted).
+ */
+import { describe, test, expect, vi, afterEach } from 'vitest';
+import {
+  previewVersion,
+  registerPreviewDoc,
+  getActiveTheme,
+  bumpPreviewVersion,
+  resolveColor,
+  resolveColorForTheme,
+  resolveRgb,
+  resolveBackground,
+} from '../src/lib/previewResolver.svelte';
+
+// Tracks every <iframe> created by makePreviewDoc() so afterEach can remove
+// them — registerPreviewDoc() only tears down the resolver's own internal
+// probe elements, not the fixtures this file appends to document.body.
+let createdIframes = [];
+
+function makePreviewDoc(theme = 'light') {
+  const iframe = document.createElement('iframe');
+  document.body.appendChild(iframe);
+  createdIframes.push(iframe);
+  const doc = iframe.contentDocument;
+  doc.documentElement.setAttribute('data-theme', theme);
+  return doc;
+}
+
+afterEach(() => {
+  registerPreviewDoc(null);
+  createdIframes.forEach((iframe) => iframe.remove());
+  createdIframes = [];
+});
+
+describe('registerPreviewDoc / getActiveTheme', () => {
+  test('bumps previewVersion when registering a new document', () => {
+    const before = previewVersion.value;
+    registerPreviewDoc(makePreviewDoc());
+    expect(previewVersion.value).toBeGreaterThan(before);
+  });
+
+  test('bumps previewVersion again when re-registering the same document', () => {
+    const doc = makePreviewDoc();
+    registerPreviewDoc(doc);
+    const before = previewVersion.value;
+    registerPreviewDoc(doc);
+    expect(previewVersion.value).toBeGreaterThan(before);
+  });
+
+  test('getActiveTheme reflects the registered document\'s data-theme attribute', () => {
+    registerPreviewDoc(makePreviewDoc('dark'));
+    expect(getActiveTheme()).toBe('dark');
+    registerPreviewDoc(makePreviewDoc('light'));
+    expect(getActiveTheme()).toBe('light');
+  });
+
+  test('getActiveTheme defaults to light when data-theme is absent', () => {
+    const doc = makePreviewDoc();
+    doc.documentElement.removeAttribute('data-theme');
+    registerPreviewDoc(doc);
+    expect(getActiveTheme()).toBe('light');
+  });
+});
+
+describe('resolveColor', () => {
+  test('returns "" when no preview document is registered', () => {
+    registerPreviewDoc(null);
+    expect(resolveColor('red')).toBe('');
+  });
+
+  test('resolves a CSS color as painted by the preview document', () => {
+    registerPreviewDoc(makePreviewDoc());
+    expect(resolveColor('red')).toBe('rgb(255, 0, 0)');
+  });
+
+  test('caches resolved values — a repeated call does not recompute getComputedStyle', () => {
+    const doc = makePreviewDoc();
+    registerPreviewDoc(doc);
+    const spy = vi.spyOn(doc.defaultView, 'getComputedStyle');
+    const first = resolveColor('#00ff00');
+    const callsAfterFirst = spy.mock.calls.length;
+    const second = resolveColor('#00ff00');
+    expect(second).toBe(first);
+    expect(spy.mock.calls.length).toBe(callsAfterFirst);
+    spy.mockRestore();
+  });
+
+  // Closes the loop on SL-020: PreviewPanel.svelte's rAF-coalesced effects
+  // rely on bumpPreviewVersion() reliably invalidating the cache every time
+  // it runs, however rarely (once per frame) it now gets called.
+  test('bumpPreviewVersion() invalidates the cache — a cached expression is recomputed after bumping', () => {
+    const doc = makePreviewDoc();
+    registerPreviewDoc(doc);
+    const spy = vi.spyOn(doc.defaultView, 'getComputedStyle');
+    resolveColor('blue');
+    const callsBeforeBump = spy.mock.calls.length;
+    bumpPreviewVersion();
+    resolveColor('blue');
+    expect(spy.mock.calls.length).toBeGreaterThan(callsBeforeBump);
+    spy.mockRestore();
+  });
+
+  test('bumpPreviewVersion can be called repeatedly without throwing (pure counter, no reactive loop)', () => {
+    registerPreviewDoc(makePreviewDoc());
+    const before = previewVersion.value;
+    expect(() => {
+      for (let i = 0; i < 50; i++) bumpPreviewVersion();
+    }).not.toThrow();
+    expect(previewVersion.value).toBe(before + 50);
+  });
+});
+
+describe('resolveColorForTheme', () => {
+  test('resolves via an independent probe per theme, scoped under a [data-theme] wrapper', () => {
+    registerPreviewDoc(makePreviewDoc());
+    expect(resolveColorForTheme('red', 'light')).toBe('rgb(255, 0, 0)');
+    expect(resolveColorForTheme('blue', 'dark')).toBe('rgb(0, 0, 255)');
+  });
+
+  test('returns "" when no preview document is registered', () => {
+    registerPreviewDoc(null);
+    expect(resolveColorForTheme('red', 'light')).toBe('');
+  });
+
+  test('caches per theme+expression key independently of resolveColor\'s cache', () => {
+    const doc = makePreviewDoc();
+    registerPreviewDoc(doc);
+    const spy = vi.spyOn(doc.defaultView, 'getComputedStyle');
+    resolveColorForTheme('green', 'dark');
+    const callsAfterFirst = spy.mock.calls.length;
+    resolveColorForTheme('green', 'dark');
+    expect(spy.mock.calls.length).toBe(callsAfterFirst);
+    // A different theme with the same expression is a different cache key —
+    // expect at least one more getComputedStyle call, not a cache hit.
+    resolveColorForTheme('green', 'light');
+    expect(spy.mock.calls.length).toBeGreaterThan(callsAfterFirst);
+    spy.mockRestore();
+  });
+});
+
+describe('resolveRgb', () => {
+  test('returns null when no preview document is registered', () => {
+    registerPreviewDoc(null);
+    expect(resolveRgb('red')).toBeNull();
+  });
+
+  // Explicitly stubbing getContext('2d') to return null (rather than relying
+  // on this sandbox's jsdom having no `canvas` npm package installed) so this
+  // test asserts resolveRgb's documented contract, not an environment detail
+  // that would silently start failing if a canvas backend became available.
+  //
+  // Spies on the preview *iframe's own* HTMLCanvasElement, not the top-level
+  // test file's global one — each iframe is a separate jsdom realm with its
+  // own constructors, so a canvas created via activeDoc.createElement('canvas')
+  // is an instance of doc.defaultView.HTMLCanvasElement, not window.HTMLCanvasElement.
+  test('degrades to null (not a throw) when no 2D canvas context is available', () => {
+    const doc = makePreviewDoc();
+    registerPreviewDoc(doc);
+    const spy = vi.spyOn(doc.defaultView.HTMLCanvasElement.prototype, 'getContext').mockReturnValue(null);
+    expect(() => resolveRgb('red')).not.toThrow();
+    expect(resolveRgb('red')).toBeNull();
+    spy.mockRestore();
+  });
+
+  test('converts a resolved color to an [r,g,b] triple when a 2D context is available', () => {
+    const doc = makePreviewDoc();
+    registerPreviewDoc(doc);
+    const fakeCtx = {
+      clearRect: vi.fn(),
+      fillRect: vi.fn(),
+      fillStyle: '',
+      getImageData: vi.fn(() => ({ data: new Uint8ClampedArray([255, 0, 0, 255]) })),
+    };
+    const spy = vi.spyOn(doc.defaultView.HTMLCanvasElement.prototype, 'getContext').mockReturnValue(fakeCtx);
+    expect(resolveRgb('red')).toEqual([255, 0, 0]);
+    spy.mockRestore();
+  });
+});
+
+describe('resolveBackground', () => {
+  test('returns "" when no preview document is registered', () => {
+    registerPreviewDoc(null);
+    expect(resolveBackground('linear-gradient(red, blue)')).toBe('');
+  });
+
+  test('returns the resolved background-image as painted by the preview', () => {
+    registerPreviewDoc(makePreviewDoc());
+    expect(resolveBackground('linear-gradient(red, blue)')).toContain('gradient');
+  });
+});
diff --git a/core/accessibility.css b/core/accessibility.css
index 8bb09193..bc822562 100644
--- a/core/accessibility.css
+++ b/core/accessibility.css
@@ -157,6 +157,11 @@
   }
 
   /* Clickable-parent */
+  /* Perf note (SL-002): the two selector groups below each combine multiple
+     :has()-bearing branches, forcing subtree re-evaluation on DOM mutation
+     inside .sf-clickable-parent. Fine for typical card/list-item usage; avoid
+     applying this class to large (100+ node) grids or lists without profiling
+     first. */
   .sf-clickable-parent {
     --sf-clickable-overlay-z: 1;
     position: relative;
diff --git a/core/layout.css b/core/layout.css
index ef3bbefa..c482b527 100644
--- a/core/layout.css
+++ b/core/layout.css
@@ -1,11 +1,15 @@
 /* SLASHED — core/layout.css
    @layer slashed.layout
    Layout primitives: section, container, stack, cluster, grid, sidebar, switcher, frame.
-   Prefix: .sf-*; local rhythm via --sf-*-gap / sizing tokens. */
+   Prefix: .sf-*; local rhythm via --sf-*-gap / sizing tokens.
+   SL-005: every @container query in this file hardcodes its breakpoint
+   instead of referencing a --sf-* token — var() is not allowed inside an
+   @container condition per the CSS spec. This applies framework-wide to
+   every @container site below; not re-explained at each one. */
 
 @layer slashed.layout {
 
-  
+  /* Section */
   .sf-section     { padding-block: var(--sf-section-pad); }
   .sf-section--xs { --sf-section-pad: var(--sf-section-pad--xs); }
   .sf-section--s  { --sf-section-pad: var(--sf-section-pad--s); }
@@ -52,6 +56,7 @@
   }
 
   
+  /* Container */
   .sf-container {
     container:      sf-layout / inline-size;
     width:          100%;
@@ -71,6 +76,7 @@
   }
 
   
+  /* Stack & gap */
   .sf-stack {
     display:        flex;
     flex-direction: column;
@@ -96,12 +102,14 @@
   .sf-gap--2xl { gap: var(--sf-space-2xl); }
 
   
+  /* Box */
   .sf-box {
     padding: var(--sf-box-padding);
     outline: var(--sf-box-border-width) solid var(--sf-box-border-color);
   }
 
   
+  /* Center */
   .sf-center {
     box-sizing:      content-box;
     width:           auto;
@@ -117,6 +125,7 @@
   }
 
   
+  /* Cluster */
   .sf-cluster {
     display:         flex;
     flex-wrap:       wrap;
@@ -137,6 +146,7 @@
   .sf-cluster--between  { justify-content: space-between; }
 
   
+  /* Sidebar */
   .sf-sidebar {
     display:   flex;
     flex-wrap: wrap;
@@ -169,6 +179,7 @@
   .sf-sidebar--wide   { --sf-sidebar-width: 26rem; }
 
   
+  /* Switcher */
   .sf-switcher {
     display:   flex;
     flex-wrap: wrap;
@@ -184,6 +195,7 @@
   .sf-switcher--vertical { flex-direction: column; }
 
   
+  /* Grid & icon */
   .sf-grid {
     display:               grid;
     grid-template-columns: repeat(auto-fill, minmax(min(var(--sf-grid-min), 100%), 1fr));
@@ -229,6 +241,7 @@
   }
 
   
+  /* Cover */
   .sf-cover {
     display:        flex;
     flex-direction: column;
@@ -247,6 +260,7 @@
   .sf-cover--padding-l { padding-block: var(--sf-space-4xl); }
 
   
+  /* Frame */
   .sf-frame {
     aspect-ratio:    var(--sf-frame-ratio);
     overflow:        hidden;
@@ -395,7 +409,6 @@
     container: sf-grid / inline-size;
   }
 
-  /* Cannot use var() inside @container per CSS spec — breakpoints hardcoded. */
   @container (min-width: 30em) {
     .sf-grid-cols-4 { grid-template-columns: repeat(2, 1fr); }
     .sf-grid-cols-6 { grid-template-columns: repeat(3, 1fr); }
diff --git a/core/themes.css b/core/themes.css
index a0bb707f..8f501eba 100644
--- a/core/themes.css
+++ b/core/themes.css
@@ -58,7 +58,12 @@
 
   /* SECTION-LEVEL THEMING */
   /* light-dark() bakes at :root declaration time; re-declarations on [data-theme]
-     elements are required for section-level theming to work. */
+     elements are required for section-level theming to work.
+     SL-001: the clamp() derivation formula below is the same one used inside
+     tokens.css's "Resolved color tokens — auto-switch via light-dark()"
+     block (search core/tokens.css for that comment) — duplicated here, not
+     shared, because this file needs flat values outside light-dark().
+     Keep both copies in sync if the formula ever changes. */
   @supports (color: oklch(from red l c h)) {
 
         :root {
diff --git a/core/tokens.css b/core/tokens.css
index 4bc09994..35613a14 100644
--- a/core/tokens.css
+++ b/core/tokens.css
@@ -101,14 +101,20 @@
     --sf-color-danger:    var(--sf-color-danger-source-light);
   }
 
-  /* Mode flag — drives formula direction for non-color dark overrides.
-     Set by themes.css via [data-theme="dark"] and the prefers-color-scheme
-     media query. Do not set directly. */
+  /* Mode flag — INTERNAL, not a public hook (SL-003: same "--sf-is-*" naming
+     pattern as the public flags below, opposite contract — read here, don't
+     set). Drives formula direction for non-color dark overrides. Set only by
+     themes.css via [data-theme="dark"] and the prefers-color-scheme media
+     query; every other read site (core/tokens.css, the configurator's power
+     knobs) only reads it inside calc() expressions. Setting it directly
+     desyncs it from color-scheme/[data-theme] and produces an inconsistent
+     theme. */
   @property --sf-is-dark { syntax: "<integer>"; inherits: true; initial-value: 0; }
 
   /* @property — INTERACTION STATE FLAGS */
-  /* Public hooks for Style Queries. Allow components to react to states
-     toggled on ancestors via .is-* classes. */
+  /* PUBLIC hooks for Style Queries — safe to set from consumer code, unlike
+     --sf-is-dark above. Allow components to react to states toggled on
+     ancestors via .is-* classes. */
   @property --sf-is-active  { syntax: "<integer>"; inherits: true; initial-value: 0; }
   @property --sf-is-current { syntax: "<integer>"; inherits: true; initial-value: 0; }
   @property --sf-is-pressed { syntax: "<integer>"; inherits: true; initial-value: 0; }
@@ -366,7 +372,11 @@
          Dark auto-derivation formula (brand + status):
          clamp(0.65, 0.95 - l*0.5, 0.88) lightens dark-mode value relative to the light source.
          Surface inverts: clamp(0.16, 1.18 - l, 0.24) — near-white flips to near-dark.
-         Override any --sf-color-X-dark to take full per-mode control. */
+         Override any --sf-color-X-dark to take full per-mode control.
+         SL-001: this same clamp() formula is re-declared flat in themes.css
+         (SECTION-LEVEL THEMING) so [data-theme] overrides on non-:root elements
+         still resolve correctly — light-dark() only bakes at :root. Keep both
+         copies in sync if the formula ever changes. */
       --sf-color-primary:   light-dark(var(--sf-color-primary-source-light),   var(--sf-color-primary-source-dark,   oklch(from var(--sf-color-primary-source-light)   clamp(0.65, calc(0.95 - l * 0.5), 0.88) calc(c * 0.9) h)));
       --sf-color-secondary: light-dark(var(--sf-color-secondary-source-light), var(--sf-color-secondary-source-dark, oklch(from var(--sf-color-secondary-source-light) clamp(0.65, calc(0.95 - l * 0.5), 0.88) calc(c * 0.9) h)));
       --sf-color-tertiary:  light-dark(var(--sf-color-tertiary-source-light),  var(--sf-color-tertiary-source-dark,  oklch(from var(--sf-color-tertiary-source-light)  clamp(0.65, calc(0.95 - l * 0.5), 0.88) calc(c * 0.9) h)));
diff --git a/docs/llm-guide.md b/docs/llm-guide.md
index ad933873..d7fc4793 100644
--- a/docs/llm-guide.md
+++ b/docs/llm-guide.md
@@ -60,7 +60,7 @@ slashed/
 └── optional/
     ├── tokens.components.css # Component tokens (field, button…)
     ├── forms.css             # Form styles
-    ├── utilities.css         # Utility classes
+    ├── utilities.css         # Utility classes (staged — commented out, not yet active)
     ├── components.css        # Optional components
     └── overrides-example.css / theme-example.css / config-example.css
 ```
diff --git a/docs/migration.md b/docs/migration.md
index ecfbcb98..a2dff8fe 100644
--- a/docs/migration.md
+++ b/docs/migration.md
@@ -3,7 +3,7 @@
 Mapping concepts from popular CSS frameworks to SLASHED, plus intra-project
 upgrade notes.
 
-## SLASHED 0.6.25 → next
+## SLASHED 0.6.25 → 0.6.26
 
 ### `base` relative shade aliases removed
 
diff --git a/docs/token-annotations.json b/docs/token-annotations.json
index 21de16de..2b323ccf 100644
--- a/docs/token-annotations.json
+++ b/docs/token-annotations.json
@@ -802,6 +802,7 @@
   },
   "classes": {
     "no-motion": "Suppresses all animations and transitions within the subtree. Apply to a container to create a reduced-motion zone without relying on the system preference.",
+    "sf-section--guttered": "Adds horizontal page gutters directly to a section — use when you want to skip a separate .sf-container wrapper (gutterless layout inside section). Neutralises container gutter to prevent double padding.",
     "sf-clickable-parent": "Makes the entire card or list-item clickable via an absolutely-positioned child overlay link. Apply to the container; place sf-clickable-parent__overlay on the <a>.",
     "sf-clickable-parent__overlay": "The full-bleed overlay link inside an sf-clickable-parent. Stretches to cover the parent and uses pointer-events to let interactive children keep their own clicks.",
     "sf-focus-parent": "Forwards focus-visible styling to this container when any descendant is keyboard-focused. Useful for custom controls that wrap a visually-hidden <input>.",
diff --git a/package.json b/package.json
index 663fa835..d7bef8ea 100644
--- a/package.json
+++ b/package.json
@@ -51,9 +51,9 @@
     "check:version": "node scripts/check-version-sync.js",
     "lint:css": "stylelint \"**/*.css\"",
     "lint:css:fix": "stylelint \"**/*.css\" --fix",
-    "pretest": "npm run build && node --test tests/tier1-p2-coverage.test.js tests/tier1-p7-oldengine.test.js tests/tier1-p10-contrast.test.js tests/api-index-sync.test.js tests/color-docs.test.js tests/docs-artifacts-sync.test.js tests/check-version-sync.test.js",
+    "pretest": "npm run build && node --test tests/tier1-p2-coverage.test.js tests/tier1-p7-oldengine.test.js tests/tier1-p10-contrast.test.js tests/api-index-sync.test.js tests/color-docs.test.js tests/docs-artifacts-sync.test.js tests/check-version-sync.test.js tests/coverage.test.js tests/parse-lib.test.js",
     "test": "playwright test",
-    "test:unit": "node --test tests/tier1-p2-coverage.test.js tests/tier1-p7-oldengine.test.js tests/tier1-p10-contrast.test.js tests/api-index-sync.test.js tests/color-docs.test.js tests/docs-artifacts-sync.test.js tests/check-version-sync.test.js",
+    "test:unit": "node --test tests/tier1-p2-coverage.test.js tests/tier1-p7-oldengine.test.js tests/tier1-p10-contrast.test.js tests/api-index-sync.test.js tests/color-docs.test.js tests/docs-artifacts-sync.test.js tests/check-version-sync.test.js tests/coverage.test.js tests/parse-lib.test.js",
     "test:install": "playwright install --with-deps chromium firefox webkit",
     "release": "release-it",
     "release:minor": "release-it --increment minor",
diff --git a/scripts/README.md b/scripts/README.md
new file mode 100644
index 00000000..53596e18
--- /dev/null
+++ b/scripts/README.md
@@ -0,0 +1,45 @@
+# scripts/ conventions
+
+## Error handling (SL-008)
+
+No single convention is enforced — each script picks whichever fits its
+failure mode, and that's intentional at the current script count (each is a
+single, independently-invoked CI-gate job, not a shared library):
+
+- **`throw new Error(...)`** — for conditions the caller (another script's
+  `import`, or `npm run docs`'s pipeline) should be able to catch, or that
+  indicate a genuinely broken invariant (`bundle.js`'s unbalanced `@layer`
+  block, `version-sync.js`'s pattern-not-found).
+- **`console.error(...)` + `process.exit(1)`** — the CI-gate scripts
+  (`check-*.js`, `audit.js --check`), where the failure is meant to print a
+  human-readable diagnosis and stop the pipeline, not be caught.
+- **Bare `catch { ... }`** (no rethrow) — best-effort operations where
+  failure is an expected, non-fatal branch (e.g. "file doesn't exist yet,
+  fall back to a default").
+
+Revisit this if the script count grows enough that the inconsistency itself
+becomes confusing; not worth enforcing for ~17 independent scripts.
+
+## CLI flag parsing (SL-009)
+
+Every script hand-rolls `process.argv.includes('--flag')` checks; there's no
+shared arg-parsing helper or `--help` output. Fine at the current ~1-2
+flags per script — revisit if any script's flag count grows past that.
+
+## Environment variables (SL-011)
+
+| Var | Read by | Purpose |
+|---|---|---|
+| `SLASHED_ROOT` | `check-version-sync.js` | Override the repo root (test-only — lets the version-sync test suite point at a fixture tree instead of the real repo). |
+| `GITHUB_REF`, `GITHUB_REF_NAME` | `bundle.js` | CI-only — used to detect whether the current run is on a release tag, for badge-stamping. |
+| `GITHUB_BASE_REF` | `check-token-registry.js` | CI-only — the PR's target branch, used to diff the registry against the base ref instead of just the working tree. |
+
+## `execSync(cmd, { shell: true })` (SL-013)
+
+`check-artifacts.js`'s `run()` helper and `changelog-release.js` both shell
+out with a command string. In both cases `cmd` is either a hardcoded git
+command or sourced from `scripts/artifacts.json`, a repo-committed config
+file — not attacker-controlled input today. The pattern does grant full
+shell execution to whatever string ends up in `artifacts.json`'s
+`buildCmd` field, though, so treat new entries there with the same care as
+any other code change, not as inert config.
diff --git a/scripts/audit.js b/scripts/audit.js
index 9584810c..b22ecc9c 100644
--- a/scripts/audit.js
+++ b/scripts/audit.js
@@ -27,6 +27,7 @@
 import fs   from 'node:fs';
 import path from 'node:path';
 import { TOKEN_FILES, CLASS_FILES } from './registry-sources.js';
+import { stripComments, stripStrings, requireFile } from './lib/parse.js';
 
 const ROOT = path.resolve(import.meta.dirname, '..');
 
@@ -39,21 +40,8 @@ const ALL_SOURCE_FILES = [
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
-function stripComments(css) {
-  return css.replace(/\/\*[\s\S]*?\*\//g, '');
-}
-
-function stripStrings(css) {
-  // Prevent matching class names that appear inside CSS string values
-  return css.replace(/"[^"]*"|'[^']*'/g, '""');
-}
-
 function readFile(rel) {
-  const abs = path.join(ROOT, rel);
-  if (!fs.existsSync(abs)) {
-    throw new Error(`[audit] Missing canonical source file: ${rel}`);
-  }
-  return fs.readFileSync(abs, 'utf8');
+  return requireFile(rel, ROOT, `[audit] Missing canonical source file: ${rel}`);
 }
 
 // ── Token extraction ─────────────────────────────────────────────────────────
diff --git a/scripts/check-macro-catalog.js b/scripts/check-macro-catalog.js
index 64e87744..e2c13ae9 100644
--- a/scripts/check-macro-catalog.js
+++ b/scripts/check-macro-catalog.js
@@ -14,6 +14,7 @@
 
 import fs   from 'node:fs';
 import path from 'node:path';
+import { stripComments, stripStrings } from './lib/parse.js';
 
 const ROOT = path.resolve(import.meta.dirname, '..');
 
@@ -40,14 +41,6 @@ const SKIP_IN_DOCS = new Set([
   '.sf-frame', '.sf-reel',
 ]);
 
-function stripComments(css) {
-  return css.replace(/\/\*[\s\S]*?\*\//g, '');
-}
-
-function stripStrings(css) {
-  return css.replace(/"[^"]*"|'[^']*'/g, '""');
-}
-
 // ── 1. Collect classes from CSS ───────────────────────────────────────────────
 
 const cssClasses = new Set();
diff --git a/scripts/gen-api-index.js b/scripts/gen-api-index.js
index 4fb12b1f..3ee18c1d 100644
--- a/scripts/gen-api-index.js
+++ b/scripts/gen-api-index.js
@@ -26,746 +26,42 @@
  * Descriptions and groups prefer curated docs metadata, then fall back to the
  * previous generated API index, and finally to concise source section banners.
  * This keeps source CSS comments terse without erasing public API docs.
+ *
+ * SL-006: extraction (reading source/annotations/the previous index and
+ * assembling entries) lives in scripts/lib/api-index/extract.js; rendering
+ * the Markdown companion lives in scripts/lib/api-index/render.js. This file
+ * is now just the path constants, the write-time regression guard, and the
+ * orchestration in main().
  */
 
 import fs   from 'node:fs';
 import path from 'node:path';
 import { TOKEN_FILES, CLASS_FILES } from './registry-sources.js';
-import { tierOf, roleOf } from './token-tiers.js';
+import {
+  readAnnotations, readExistingApiIndex, buildBundleMap,
+  buildTokenEntries, buildClassEntries, finalizeEntry, tally,
+} from './lib/api-index/extract.js';
+import { buildMarkdown } from './lib/api-index/render.js';
 
 const ROOT = path.resolve(import.meta.dirname, '..');
 const OUT    = path.join(ROOT, 'docs', 'api-index.json');
 const OUT_MD = path.join(ROOT, 'docs', 'api-index.md');
 
-const BUNDLE_CONFIG      = 'bundle.config.json';
-const ANNOTATIONS_FILE   = path.join(ROOT, 'docs', 'token-annotations.json');
-
-/**
- * Read docs/token-annotations.json — the curated overlay for per-token notes
- * and per-class descriptions. Returns a shape with `tokens` and `classes`
- * objects; both default to {} when the file is absent or unreadable.
- * @returns {{ tokens: Record<string,string>, classes: Record<string,string> }}
- */
-function readAnnotations() {
-  if (!fs.existsSync(ANNOTATIONS_FILE)) return { tokens: {}, classes: {} };
-  try {
-    const parsed = JSON.parse(fs.readFileSync(ANNOTATIONS_FILE, 'utf8'));
-    return {
-      tokens:  parsed.tokens  ?? {},
-      classes: parsed.classes ?? {},
-    };
-  } catch (err) {
-    console.warn(`[docs] Failed to parse ${ANNOTATIONS_FILE}:`, err.message);
-    return { tokens: {}, classes: {} };
-  }
-}
-
-/**
- * Read the previously generated API index as a compatibility overlay. This
- * preserves curated groups/descriptions when source comments are intentionally
- * reduced to terse category markers.
- * @returns {{ tokens: Map<string, object>, classes: Map<string, object> }}
- */
-function readExistingApiIndex() {
-  const empty = { tokens: new Map(), classes: new Map() };
-  if (!fs.existsSync(OUT)) return empty;
-  try {
-    const parsed = JSON.parse(fs.readFileSync(OUT, 'utf8'));
-    const tokens = new Map();
-    const classes = new Map();
-    for (const entry of parsed.entries ?? []) {
-      if (entry.type === 'token') tokens.set(entry.name, entry);
-      if (entry.type === 'class') classes.set(entry.name, entry);
-    }
-    return { tokens, classes };
-  } catch (err) {
-    console.warn(`[docs] Failed to parse existing ${OUT}:`, err.message);
-    return empty;
-  }
-}
-
-function isUsefulDescription(description) {
-  return Boolean(description && !/^SLASHED\s+[—-]/.test(description));
-}
-
-// ── Per-file metadata ─────────────────────────────────────────────────────────
-// `category` is the high-level, human-facing area. `area` is a short machine
-// slug. `kind` is the element family produced by the file.
-const FILE_META = {
-  // Token files
-  'core/tokens.css':                    { category: 'Core tokens',              area: 'core',     kind: 'token' },
-  'core/tokens.layout.css':             { category: 'Layout tokens',            area: 'layout',   kind: 'token' },
-  'core/tokens.macros.css':             { category: 'Macro tokens',             area: 'macros',   kind: 'token' },
-  'optional/tokens.components.css':     { category: 'Component tokens',         area: 'components', kind: 'token' },
-  // Class files
-  'core/layout.css':            { category: 'Layout primitives',     area: 'layout',        kind: 'layout'        },
-  'core/macros.css':            { category: 'Macro classes',         area: 'macros',        kind: 'macro'         },
-  'core/states.css':            { category: 'State classes',         area: 'states',        kind: 'state'         },
-  'core/accessibility.css':     { category: 'Accessibility',         area: 'accessibility', kind: 'accessibility' },
-  'core/motion.css':            { category: 'Motion / animation',    area: 'motion',        kind: 'motion'        },
-  'core/print.css':             { category: 'Print',                 area: 'print',         kind: 'print'         },
-  'core/themes.css':            { category: 'Theme utilities',        area: 'theme',         kind: 'theme'         },
-  'optional/forms.css':         { category: 'Forms (classless)',     area: 'forms',         kind: 'form'          },
-  'optional/components.css':    { category: 'Components',             area: 'components',    kind: 'component'     },
-  'optional/theme-example.css': { category: 'Theme example',         area: 'theme',         kind: 'theme'         },
-};
-
-// ── Source masking (length-preserving) ─────────────────────────────────────────
-// Replacing comment/string bodies with spaces (NOT removing them) keeps every
-// character index stable, so a token/class match found in the masked text can
-// be looked up against section banners parsed from the original text.
-
-/**
- * Mask block-comment bodies with spaces (length-preserving) so character
- * offsets stay stable for later banner/section lookups.
- * @param {string} css source CSS
- * @returns {string} CSS with comment bodies blanked
- */
-function maskComments(css) {
-  return css.replace(/\/\*[\s\S]*?\*\//g, m => m.replace(/[^\n]/g, ' '));
-}
-/**
- * Mask string-literal bodies with spaces (length-preserving) so quoted class
- * names inside `content:"…"` aren't mistaken for selectors.
- * @param {string} css source CSS
- * @returns {string} CSS with string bodies blanked
- */
-function maskStrings(css) {
-  return css.replace(/"[^"]*"|'[^']*'/g, m => m.replace(/[^\n]/g, ' '));
-}
-
-/**
- * Read a workspace-relative source file, throwing a clear error if missing.
- * @param {string} rel path relative to repo root
- * @returns {string} file contents
- */
-function readFile(rel) {
-  const abs = path.join(ROOT, rel);
-  if (!fs.existsSync(abs)) {
-    throw new Error(`[docs:api] Missing source file: ${rel}`);
-  }
-  return fs.readFileSync(abs, 'utf8');
-}
-
-// ── Section-banner parsing ──────────────────────────────────────────────────
-// A "banner" is a block comment that contains a long divider run (>=10 of '='
-// or '-'). The file-header comment (starts with "SLASHED —" at offset 0) is
-// recognised separately and never used as an element's group — regardless of
-// whether it contains a divider run. Plain NOTE comments (no divider) are not
-// treated as section banners.
-
-const DIVIDER_RUN = /[-=─═]{10,}/;
-
-/**
- * True when a comment line is purely a divider rule (ASCII or box-drawing).
- * @param {string} line trimmed comment line
- * @returns {boolean}
- */
-function lineIsDivider(line) {
-  const compact = line.replace(/\s/g, '');
-  return compact.length >= 4 && /^[-=─═]+$/.test(compact);
-}
-
-/**
- * Parse a section-banner comment into a `{ title, description }` pair, stripping
- * divider fences and promoting an inline `Title — lead` description.
- * @param {string} raw the raw block comment (including delimiters)
- * @returns {{title: string, description: string}}
- */
-function parseBanner(raw) {
-  const inner = raw.replace(/^\/\*+/, '').replace(/\*+\/$/, '');
-  const rawLines = inner.split('\n')
-    .map(l => l.replace(/^\s*\*?\s?/, '').trimEnd())
-    .map(l => l.trim());
-
-  const lines = [];
-  for (let line of rawLines) {
-    if (!line) continue;
-    // "-- Title --------" form (ASCII or box-drawing fences): strip the fences.
-    const fenced = /^[-─]{2,}\s*(.*?)\s*[-─]{2,}$/.exec(line);
-    if (fenced) { if (fenced[1]) lines.push(fenced[1]); continue; }
-    if (lineIsDivider(line)) continue;
-    lines.push(line);
-  }
-  if (!lines.length) return { title: '', description: '' };
-
-  let title = lines[0];
-  let rest  = lines.slice(1);
-
-  // A title like "Flow — distance between flow children" carries an inline
-  // description after an em/en dash (or " - "). Split it off as lead text.
-  const dash = /^(.+?)\s+[—–]\s+(.+)$/.exec(title) || /^(.+?)\s+-\s+(.+)$/.exec(title);
-  let lead = '';
-  if (dash) { title = dash[1].trim(); lead = dash[2].trim(); }
-
-  // Section banners in tokens.css are prefixed with the at-rule they document
-  // (e.g. "@property — BRAND COLORS …"). The keyword is noise as a group name —
-  // promote the part after the dash to be the title instead.
-  if (/^@[\w-]+$/.test(title) && lead) {
-    title = lead;
-    lead = '';
-  }
-
-  const description = [lead, ...rest]
-    .filter(Boolean)
-    .join(' ')
-    .replace(/\s+/g, ' ')
-    .trim();
-
-  return { title, description };
-}
-
-/**
- * Collect every block comment with its position and classification
- * (file header vs. section banner vs. plain note) for context lookups.
- * @param {string} css source CSS (comments intact)
- * @returns {Array<object>} ordered comment records
- */
-function collectComments(css) {
-  const comments = [];
-  for (const m of css.matchAll(/\/\*[\s\S]*?\*\//g)) {
-    const raw    = m[0];
-    const start  = m.index;
-    const end    = m.index + raw.length;
-    const isHeader = /SLASHED\s+[—-]/.test(raw) && start < 4;
-    // A banner is either a divider-fenced comment, a "/* -- Title -- */" form,
-    // or a single-line at-rule sub-header ("/* @property — STATUS COLORS */").
-    const singleLineSubHeader = !/\n/.test(raw.trim()) && /^\/\*\s*@[\w-]+\s+[—–-]\s+\S/.test(raw);
-    const isBanner = DIVIDER_RUN.test(raw) || /^\/\*\s*--\s+\S/.test(raw) || singleLineSubHeader;
-    const parsed = (isBanner || isHeader) ? parseBanner(raw) : parseNote(raw);
-    comments.push({ start, end, raw, isHeader, isBanner, ...parsed });
-  }
-  return comments;
-}
-
-/**
- * Collapse a non-banner note comment into a single descriptive string.
- * @param {string} raw the raw block comment
- * @returns {{title: string, description: string}} title is always empty
- */
-function parseNote(raw) {
-  const inner = raw.replace(/^\/\*+/, '').replace(/\*+\/$/, '');
-  const text = inner.split('\n')
-    .map(l => l.replace(/^\s*\*?\s?/, '').trim())
-    .filter(Boolean)
-    .filter(l => !lineIsDivider(l))
-    .join(' ')
-    .replace(/\s+/g, ' ')
-    .trim();
-  return { title: '', description: text };
-}
-
-/**
- * Find the comment context governing the element at character `idx`: the
- * nearest preceding section banner and the nearest preceding comment of any
- * kind (the latter may attach a more specific description).
- * @param {Array<object>} comments records from collectComments
- * @param {number} idx character offset of the element
- * @returns {{banner: ?object, nearest: ?object}}
- */
-function contextAt(comments, idx) {
-  let banner = null;
-  let nearest = null;
-  for (const c of comments) {
-    if (c.end > idx) break;
-    if (c.isHeader) continue;
-    nearest = c;
-    if (c.isBanner) banner = c;
-  }
-  return { banner, nearest };
-}
-
-/**
- * Derive a `{ group, description }` for the element at `idx` from its comment
- * context, preferring an attached note over the governing banner's prose.
- * @param {Array<object>} comments records from collectComments
- * @param {number} idx character offset of the element
- * @returns {{group: string, description: string}}
- */
-function describe(comments, idx) {
-  const { banner, nearest } = contextAt(comments, idx);
-  const group = banner ? banner.title : '';
-  // Prefer a specific note attached directly above the element; otherwise fall
-  // back to the governing banner's own description (or its title).
-  let description = '';
-  if (nearest && nearest !== banner && nearest.description) {
-    description = nearest.description;
-  } else if (banner) {
-    description = banner.description || banner.title;
-  } else if (nearest) {
-    description = nearest.description;
-  }
-  return { group, description: truncate(description) };
-}
-
-/**
- * Trim a description to a documentation-hint length, breaking on a word
- * boundary and appending an ellipsis when truncated.
- * @param {string} str input text
- * @param {number} [max=280] maximum length
- * @returns {string}
- */
-function truncate(str, max = 280) {
-  if (!str) return '';
-  const clean = str.replace(/\s+/g, ' ').trim();
-  if (clean.length <= max) return clean;
-  return clean.slice(0, max - 1).replace(/\s+\S*$/, '') + '…';
-}
-
-/**
- * Read a custom-property value starting at its `:` offset, honouring nested
- * parentheses so light-dark()/oklch()/clamp() values stay intact. (Identical
- * contract to gen-token-index.js / gen-token-reference.js.)
- * @param {string} css source (comment-masked)
- * @param {number} colonIdx offset of the `:` after the property name
- * @returns {string} the normalised value text
- */
-function readValue(css, colonIdx) {
-  let depth = 0;
-  let out = '';
-  for (let i = colonIdx + 1; i < css.length; i++) {
-    const ch = css[i];
-    if (ch === '(') depth++;
-    else if (ch === ')') depth--;
-    else if (ch === ';' && depth === 0) break;
-    out += ch;
-  }
-  return out.replace(/\s+/g, ' ').trim();
-}
-
-/**
- * Find the first `@layer` a file declares (e.g. "slashed.layout").
- * @param {string} maskedCss comment-masked CSS
- * @returns {?string} the layer name, or null
- */
-function layerOf(maskedCss) {
-  const m = /@layer\s+(slashed(?:\.[\w-]+)?)/.exec(maskedCss);
-  return m ? m[1] : null;
-}
-
-// ── Bundle membership ───────────────────────────────────────────────────────
-// Map each source file to the set of bundle tiers that ship it. Layered and
-// flat variants of the same tier collapse to one name (e.g. "essential").
-/**
- * Build the file → bundle-tiers map from bundle.config.json (layered and flat
- * variants of a tier collapse to one name) plus a `bundlesFor(file)` resolver.
- * @returns {{bundlesFor: (file: string) => string[], allBundles: string[]}}
- */
-function buildBundleMap() {
-  const cfg = JSON.parse(readFile(BUNDLE_CONFIG));
-  const fileToBundles = new Map();
-  const allBundles = new Set();
-  for (const bundle of cfg.bundles || []) {
-    const tier = path.basename(bundle.output)
-      .replace(/^slashed\./, '')
-      .replace(/\.flat/, '')
-      .replace(/\.css$/, '');
-    allBundles.add(tier);
-    for (const file of bundle.files || []) {
-      if (!fileToBundles.has(file)) fileToBundles.set(file, new Set());
-      fileToBundles.get(file).add(tier);
-    }
-  }
-  // Stable bundle ordering: by ascending breadth (how many files each ships),
-  // so smaller tiers list first.
-  const order = [...allBundles].sort((a, b) => a.localeCompare(b));
-  const rank = new Map(order.map((b, i) => [b, i]));
-  const bundlesFor = file => {
-    const set = fileToBundles.get(file);
-    if (!set) return [];
-    return [...set].sort((a, b) => rank.get(a) - rank.get(b));
-  };
-  return { bundlesFor, allBundles: order };
-}
-
-// ── Token name → namespace ──────────────────────────────────────────────────
-// The second path segment of a token name is a useful machine-filterable
-// facet, e.g. --sf-color-primary → "color", --sf-space-m → "space".
-/**
- * Extract a token's namespace facet — the second name segment, e.g.
- * `--sf-color-primary` → "color", `--sf-space-m` → "space".
- * @param {string} name token custom-property name
- * @returns {?string}
- */
-function namespaceOf(name) {
-  const m = /^--sf-([a-z0-9]+)/.exec(name);
-  return m ? m[1] : null;
-}
-
-/**
- * Return the alias target when a value is exactly one `var(--sf-x)` reference.
- * @param {string} value declared value
- * @returns {?string} the referenced token name, or null
- */
-function aliasTarget(value) {
-  const m = /^var\(\s*(--sf-[\w-]+)\s*\)$/.exec(value || '');
-  return m ? m[1] : null;
-}
-
-// ── Token extraction ──────────────────────────────────────────────────────────
-
-/**
- * Extract every token from one source file with its value, @property metadata
- * and derived group/description. Last declaration wins per file for the value.
- * @param {string} rel source file path
- * @returns {Map<string, object>} name → partial token data
- */
-function extractTokensFromFile(rel) {
-  const original = readFile(rel);
-  const masked   = maskComments(original);
-  const comments = collectComments(original);
-  const layer    = layerOf(masked);
-  const rows = new Map(); // name -> partial entry data
-
-  // @property registrations: tier-precise syntax / inherits / initial-value.
-  for (const m of masked.matchAll(/@property\s+(--sf-[\w-]+)\s*\{([^}]*)\}/g)) {
-    const name = m[1];
-    const body = m[2];
-    const syntax   = /syntax\s*:\s*("(?:[^"]*)"|'(?:[^']*)')/.exec(body);
-    const inherits = /inherits\s*:\s*(true|false)/.exec(body);
-    const initial  = /initial-value\s*:\s*([^;]+);/.exec(body);
-    const { group, description } = describe(comments, m.index);
-    rows.set(name, {
-      registered: true,
-      syntax:   syntax ? syntax[1].replace(/^['"]|['"]$/g, '') : null,
-      inherits: inherits ? inherits[1] === 'true' : null,
-      value:    initial ? initial[1].trim() : (rows.get(name)?.value ?? null),
-      group, description, layer,
-    });
-  }
-
-  // Custom-property declarations (last declaration wins per file for value).
-  const re = /(--sf-[\w-]+)\s*:/g;
-  let m;
-  while ((m = re.exec(masked)) !== null) {
-    const name  = m[1];
-    const colon = m.index + m[0].length - 1;
-    const value = readValue(masked, colon);
-    const prev  = rows.get(name) || {};
-    const ctx   = describe(comments, m.index);
-    rows.set(name, {
-      registered: prev.registered || false,
-      syntax:   prev.syntax ?? null,
-      inherits: prev.inherits ?? null,
-      value,
-      // Keep the first encountered group/description (definition site); fall
-      // back to declaration context if @property didn't supply one.
-      group:       prev.group || ctx.group,
-      description: prev.description || ctx.description,
-      layer:       prev.layer || layer,
-    });
-  }
-
-  return rows;
-}
-
-/**
- * Merge tokens across all TOKEN_FILES into finished entries (tier, namespace,
- * value, alias, bundle membership, …). Redeclarations: last value wins, sources
- * unioned.
- * @param {(file: string) => string[]} bundlesFor bundle resolver
- * @returns {Map<string, object>} name → token entry
- */
-// ── Class extraction ──────────────────────────────────────────────────────────
-
-/**
- * Extract prefixed (.sf-/.is-) and unprefixed framework classes from one file,
- * with selector, kind, BEM-variant info and derived group/description.
- * @param {string} rel source file path
- * @returns {Map<string, object>} name → class entry
- */
-function extractClassesFromFile(rel) {
-  const original = readFile(rel);
-  const masked   = maskStrings(maskComments(original));
-  const comments = collectComments(original);
-  const layer    = layerOf(masked);
-  const meta     = FILE_META[rel];
-  const rows = new Map(); // name -> entry
-
-  // Prefixed classes: .sf-* and .is-*
-  for (const m of masked.matchAll(/\.((?:sf|is)-[\w-]+)/g)) {
-    addClass(rows, m[1], m.index);
-  }
-  // Unprefixed framework classes (a11y helpers, print utilities, theme helper).
-  // Skip dotted @layer names by neutralising @layer declarations first.
-  const noLayer = masked.replace(/@layer\s+[^{;]+[{;]/g, mm => mm.replace(/[^\n]/g, ' '));
-  for (const m of noLayer.matchAll(/\.([a-z][\w-]*)/g)) {
-    const name = m[1];
-    if (name.startsWith('sf-') || name.startsWith('is-')) continue;
-    addClass(rows, name, m.index);
-  }
-
-  /**
-   * Record a class on first occurrence (which defines its comment context).
-   * @param {Map<string, object>} map accumulator
-   * @param {string} name class name (no leading dot)
-   * @param {number} idx character offset of the match
-   */
-  function addClass(map, name, idx) {
-    if (map.has(name)) return; // first occurrence defines its context
-    const prefix = name.startsWith('sf-') ? 'sf' : name.startsWith('is-') ? 'is' : '';
-    const variantSplit = name.indexOf('--');
-    const ctx = describe(comments, idx);
-    map.set(name, {
-      name,
-      type: 'class',
-      tier: 'PUBLIC',
-      selector: `.${name}`,
-      prefix,
-      kind: meta.kind,
-      category: meta.category,
-      area: meta.area,
-      group: ctx.group || '',
-      description: ctx.description || '',
-      isVariant: variantSplit > 0,
-      baseClass: variantSplit > 0 ? name.slice(0, variantSplit) : null,
-      optional: rel.startsWith('optional/'),
-      layer: layer || null,
-      sourceFiles: [rel],
-      bundles: bundlesFor_(rel),
-    });
-  }
-
-  return rows;
-}
-
-/**
- * Hoisted bundle resolver so addClass (a closure) can reach it; assigned in
- * buildClassEntries before extraction runs.
- * @type {(file: string) => string[]}
- */
-let bundlesFor_ = () => [];
-
-/**
- * Merge tokens across all TOKEN_FILES with curated per-token annotations.
- * @param {(file: string) => string[]} bundlesFor bundle resolver
- * @param {Record<string,string>} tokenAnnotations token name → curated description
- * @returns {Map<string, object>} name → token entry
- */
-function buildTokenEntries(bundlesFor, tokenAnnotations = {}, existingTokens = new Map()) {
-  const merged = new Map(); // name -> entry
-
-  for (const rel of TOKEN_FILES) {
-    const rows = extractTokensFromFile(rel);
-    const meta = FILE_META[rel];
-    for (const [name, data] of rows) {
-      const existing = merged.get(name);
-      if (!existing) {
-        merged.set(name, {
-          name,
-          type: 'token',
-          tier: tierOf(name),
-          role: roleOf(data.value, name),
-          namespace: namespaceOf(name),
-          category: meta.category,
-          area: meta.area,
-          group: data.group || '',
-          description: data.description || '',
-          value: data.value ?? null,
-          aliasOf: aliasTarget(data.value),
-          registered: !!data.registered,
-          animatable: !!data.registered,
-          syntax: data.syntax ?? null,
-          inherits: data.inherits ?? null,
-          optional: rel.startsWith('optional/'),
-          layer: data.layer || null,
-          sourceFiles: [rel],
-          bundles: new Set(bundlesFor(rel)),
-        });
-      } else {
-        // Token redeclared in a later file — last value wins, union sources.
-        existing.value = data.value ?? existing.value;
-        existing.aliasOf = aliasTarget(existing.value);
-        existing.role = roleOf(existing.value, name);
-        existing.registered = existing.registered || !!data.registered;
-        existing.animatable = existing.registered;
-        existing.syntax = existing.syntax ?? data.syntax ?? null;
-        existing.inherits = existing.inherits ?? data.inherits ?? null;
-        if (!existing.group && data.group) existing.group = data.group;
-        if (!existing.description && data.description) existing.description = data.description;
-        if (!existing.sourceFiles.includes(rel)) existing.sourceFiles.push(rel);
-        for (const b of bundlesFor(rel)) existing.bundles.add(b);
-      }
-    }
-  }
-  // Overlay curated per-token descriptions from token-annotations.json.
-  for (const [name, entry] of merged) {
-    const previous = existingTokens.get(name);
-    if (previous) {
-      if (!entry.group && previous.group) entry.group = previous.group;
-      if (!isUsefulDescription(entry.description) && previous.description) entry.description = previous.description;
-    }
-    if (tokenAnnotations[name]) entry.description = tokenAnnotations[name];
-  }
-  return merged;
-}
-
-/**
- * Merge classes across all CLASS_FILES into finished entries, unioning source
- * files and bundle membership for classes declared in more than one file.
- * Per-class descriptions from docs/token-annotations.json["classes"] override
- * the auto-derived banner-comment description when present.
- * @param {(file: string) => string[]} bundlesFor bundle resolver
- * @param {Record<string,string>} classAnnotations class name → curated description
- * @returns {Map<string, object>} name → class entry
- */
-function buildClassEntries(bundlesFor, classAnnotations = {}, existingClasses = new Map()) {
-  bundlesFor_ = bundlesFor;
-  const merged = new Map(); // name -> entry (union of files)
-  for (const rel of CLASS_FILES) {
-    const rows = extractClassesFromFile(rel);
-    for (const [name, entry] of rows) {
-      const existing = merged.get(name);
-      if (!existing) {
-        merged.set(name, { ...entry, bundles: new Set(entry.bundles) });
-      } else {
-        if (!existing.sourceFiles.includes(rel)) existing.sourceFiles.push(rel);
-        for (const b of entry.bundles) existing.bundles.add(b);
-        if (!existing.group && entry.group) existing.group = entry.group;
-        if (!existing.description && entry.description) existing.description = entry.description;
-      }
-    }
-  }
-  // Overlay curated per-class descriptions from token-annotations.json.
-  // The annotation wins unconditionally so the curated text always appears.
-  for (const [name, entry] of merged) {
-    const previous = existingClasses.get(name);
-    if (previous) {
-      if (!entry.group && previous.group) entry.group = previous.group;
-      if (!isUsefulDescription(entry.description) && previous.description) entry.description = previous.description;
-    }
-    if (classAnnotations[name]) entry.description = classAnnotations[name];
-  }
-  return merged;
-}
-
-// ── Assemble ────────────────────────────────────────────────────────────────
-
-/**
- * Finalise an entry for output: convert its `bundles` Set into a stably ordered
- * array.
- * @param {object} entry in-progress entry (bundles is a Set)
- * @param {(b: string) => number} bundleOrderRank ordering key
- * @returns {object} output-ready entry
- */
-function finalizeEntry(entry, bundleOrderRank) {
-  const out = { ...entry };
-  out.bundles = [...entry.bundles].sort((a, b) => bundleOrderRank(a) - bundleOrderRank(b));
-  return out;
-}
-
-/**
- * Count entries grouped by the value of one key, returned as a key-sorted
- * object (used for the `_meta.counts` breakdowns).
- * @param {Array<object>} entries rows
- * @param {string} key field to group by
- * @returns {Object<string, number>}
- */
-function tally(entries, key) {
-  const counts = {};
-  for (const e of entries) {
-    const k = e[key];
-    if (k == null) continue;
-    counts[k] = (counts[k] || 0) + 1;
-  }
-  return Object.fromEntries(Object.entries(counts).sort((a, b) => a[0].localeCompare(b[0])));
-}
-
-// ── Markdown view ─────────────────────────────────────────────────────────────
-// A browseable companion to the JSON, generated from the SAME data so the two
-// can never drift. Tokens and classes are split (different columns), each
-// grouped by category and alphabetised within a group.
-
-/**
- * Escape a value for a Markdown table cell: backslash first (so we don't
- * re-escape our own escapes), then the pipe column-separator.
- * @param {*} v cell value
- * @returns {string} escaped text
- */
-const escCell = v => String(v ?? '').replace(/\\/g, '\\\\').replace(/\|/g, '\\|');
-
-/**
- * Group entries by their `category` field, returned as category-sorted
- * `[category, entries]` pairs for the Markdown tables.
- * @param {Array<object>} entries rows
- * @returns {Array<[string, object[]]>}
- */
-function groupByCategory(entries) {
-  const map = new Map();
-  for (const e of entries) {
-    if (!map.has(e.category)) map.set(e.category, []);
-    map.get(e.category).push(e);
-  }
-  return [...map.entries()].sort((a, b) => a[0].localeCompare(b[0]));
-}
-
-/**
- * Render the human-readable Markdown companion from the same assembled data as
- * the JSON, so the two views can never drift.
- * @param {object} data assembled entries + count breakdowns
- * @returns {string} Markdown document
- */
-function buildMarkdown({ entries, tokenEntries, classEntries, tierCounts, typeCounts }) {
-  let md = `# API index
-
-> **Generated** from source by \`scripts/gen-api-index.js\` —
-> run \`npm run docs:api\` to refresh. Do not edit by hand.
-
-A single browseable catalogue of every public SLASHED element — design
-**tokens** and **classes** — with stability tier, category, bundle membership
-and a short description. The machine-readable companion (with all columns) is
-[api-index.json](api-index.json); for the flat name list see
-[registry.json](registry.json); for the tier contract see
-[architecture.md](architecture.md).
-
-**${entries.length} elements** — ${typeCounts.token || 0} tokens, ${typeCounts.class || 0} classes.
-
-| Tier | Count | Meaning |
-|---|---|---|
-| PUBLIC | ${tierCounts.PUBLIC || 0} | Everyday surface. SemVer-stable. |
-| PUBLIC-ADVANCED | ${tierCounts['PUBLIC-ADVANCED'] || 0} | Same SemVer guarantee; niche/powerful. |
-| INTERNAL | ${tierCounts.INTERNAL || 0} | Implementation detail; may change without a major bump. |
-
-`;
-
-  // Tokens
-  md += `## Tokens (${tokenEntries.length})\n\n`;
-  for (const [category, list] of groupByCategory(tokenEntries)) {
-    md += `### ${category} (${list.length})\n\n`;
-    md += '| Token | Tier | Role | Namespace | Default | Description |\n|---|---|---|---|---|---|\n';
-    for (const e of list) {
-      md += `| \`${e.name}\` | ${e.tier} | ${e.role || '—'} | ${e.namespace || '—'} | \`${escCell(e.value)}\` | ${escCell(e.description)} |\n`;
-    }
-    md += '\n';
-  }
-
-  // Classes
-  md += `## Classes (${classEntries.length})\n\n`;
-  for (const [category, list] of groupByCategory(classEntries)) {
-    md += `### ${category} (${list.length})\n\n`;
-    md += '| Class | Tier | Kind | Group | Description |\n|---|---|---|---|---|\n';
-    for (const e of list) {
-      md += `| \`${e.selector}\` | ${e.tier} | ${e.kind} | ${escCell(e.group) || '—'} | ${escCell(e.description)} |\n`;
-    }
-    md += '\n';
-  }
-
-  return md;
-}
+const ANNOTATIONS_FILE = path.join(ROOT, 'docs', 'token-annotations.json');
 
 /**
  * Entry point: assemble token + class entries, build counts and the column
  * schema, and write docs/api-index.json and docs/api-index.md.
  */
 function main() {
-  const { bundlesFor, allBundles } = buildBundleMap();
+  const { bundlesFor, allBundles } = buildBundleMap(ROOT);
   const rank = new Map(allBundles.map((b, i) => [b, i]));
   const bundleOrderRank = b => (rank.has(b) ? rank.get(b) : Number.MAX_SAFE_INTEGER);
 
-  const annotations = readAnnotations();
-  const existing = readExistingApiIndex();
-  const tokenMap   = buildTokenEntries(bundlesFor, annotations.tokens, existing.tokens);
-  const classMap   = buildClassEntries(bundlesFor, annotations.classes, existing.classes);
+  const annotations = readAnnotations(ANNOTATIONS_FILE);
+  const existing = readExistingApiIndex(OUT);
+  const tokenMap   = buildTokenEntries(ROOT, bundlesFor, annotations.tokens, existing.tokens);
+  const classMap   = buildClassEntries(ROOT, bundlesFor, annotations.classes, existing.classes);
 
   const tokenEntries = [...tokenMap.values()]
     .map(e => finalizeEntry(e, bundleOrderRank))
@@ -843,6 +139,19 @@ function main() {
     entries,
   };
 
+  // Regression guard (SL-010/SL-012): a bad regex change in one of the
+  // extraction passes should fail loudly, not silently truncate the index
+  // every consumer (gen-token-registry.js, check:llm-guide, the
+  // configurator sync) trusts. `existing` was already read above for the
+  // description/group compat overlay, so this is free.
+  const previousTotal = existing.tokens.size + existing.classes.size;
+  if (previousTotal > 0 && entries.length < previousTotal * 0.8) {
+    throw new Error(
+      `[docs:api] refusing to write ${OUT}: entry count dropped from ` +
+        `${previousTotal} to ${entries.length} (>20% shrink) — looks like a parsing regression, not an intentional change.`
+    );
+  }
+
   fs.mkdirSync(path.dirname(OUT), { recursive: true });
   fs.writeFileSync(OUT, JSON.stringify(output, null, 2) + '\n', 'utf8');
 
diff --git a/scripts/gen-token-index.js b/scripts/gen-token-index.js
index 3a98ed76..341368cf 100644
--- a/scripts/gen-token-index.js
+++ b/scripts/gen-token-index.js
@@ -21,6 +21,7 @@ import fs   from 'node:fs';
 import path from 'node:path';
 import { TOKEN_FILES } from './registry-sources.js';
 import { INTERNAL, ADVANCED, tierOf, roleOf } from './token-tiers.js';
+import { stripComments, readValue, requireFile } from './lib/parse.js';
 
 const ROOT = path.resolve(import.meta.dirname, '..');
 
@@ -39,31 +40,8 @@ export { INTERNAL, ADVANCED, tierOf, roleOf };
 
 // ── Parsing (matches scripts/gen-token-reference.js contract) ─────────────────
 
-function stripComments(css) {
-  return css.replace(/\/\*[\s\S]*?\*\//g, '');
-}
-
-// Read a custom-property value starting at its `:` index, honouring nested
-// parentheses so light-dark()/oklch()/clamp() values stay intact.
-function readValue(css, colonIdx) {
-  let depth = 0;
-  let out = '';
-  for (let i = colonIdx + 1; i < css.length; i++) {
-    const ch = css[i];
-    if (ch === '(') depth++;
-    else if (ch === ')') depth--;
-    else if (ch === ';' && depth === 0) break;
-    out += ch;
-  }
-  return out.replace(/\s+/g, ' ').trim();
-}
-
 function readSource(rel) {
-  const abs = path.join(ROOT, rel);
-  if (!fs.existsSync(abs)) {
-    throw new Error(`[docs:index] Missing token source file: ${rel}`);
-  }
-  return stripComments(fs.readFileSync(abs, 'utf8'));
+  return stripComments(requireFile(rel, ROOT, `[docs:index] Missing token source file: ${rel}`));
 }
 
 // Extract ordered [name, value] pairs (last declaration wins per file).
@@ -132,11 +110,31 @@ const jsonOut = {
   ),
 };
 
-fs.writeFileSync(
-  path.join(ROOT, 'docs', 'token-index.json'),
-  JSON.stringify(jsonOut, null, 2) + '\n',
-  'utf8'
-);
+// Regression guard (SL-010/SL-012): a bad regex/tier-set change should fail
+// loudly, not silently truncate the index every consumer (check:llm-guide,
+// the configurator) trusts. A real token removal is legitimate but rare and
+// small in number; a >20% drop is far more likely a parsing bug.
+const TOKEN_INDEX_JSON = path.join(ROOT, 'docs', 'token-index.json');
+if (fs.existsSync(TOKEN_INDEX_JSON)) {
+  try {
+    const previous = JSON.parse(fs.readFileSync(TOKEN_INDEX_JSON, 'utf8'));
+    const previousCount = Object.keys(previous.tokens ?? {}).length;
+    if (previousCount > 0 && names.length < previousCount * 0.8) {
+      throw new Error(
+        `[docs:index] refusing to write ${TOKEN_INDEX_JSON}: token count dropped from ` +
+          `${previousCount} to ${names.length} (>20% shrink) — looks like a parsing regression, not an intentional change.`
+      );
+    }
+  } catch (err) {
+    if (err instanceof SyntaxError) {
+      console.warn(`[docs:index] Failed to parse existing ${TOKEN_INDEX_JSON} for the regression check:`, err.message);
+    } else {
+      throw err;
+    }
+  }
+}
+
+fs.writeFileSync(TOKEN_INDEX_JSON, JSON.stringify(jsonOut, null, 2) + '\n', 'utf8');
 
 // ── Emit Markdown ─────────────────────────────────────────────────────────────
 
diff --git a/scripts/gen-token-reference.js b/scripts/gen-token-reference.js
index f49f225e..9aeac806 100644
--- a/scripts/gen-token-reference.js
+++ b/scripts/gen-token-reference.js
@@ -5,6 +5,7 @@
 import fs   from 'node:fs';
 import path from 'node:path';
 import { TOKEN_FILES } from './registry-sources.js';
+import { stripComments, readValue, requireFile } from './lib/parse.js';
 
 const ROOT = path.resolve(import.meta.dirname, '..');
 
@@ -17,27 +18,9 @@ const FILE_TITLES = {
 
 const SOURCES = TOKEN_FILES.map(f => ({ file: f, title: `${FILE_TITLES[f]} (\`${f}\`)` }));
 
-// Read the value of a custom-property declaration starting at `:` index,
-// honouring nested parentheses so light-dark()/oklch() values stay intact.
-function readValue(css, colonIdx) {
-  let depth = 0;
-  let out = '';
-  for (let i = colonIdx + 1; i < css.length; i++) {
-    const ch = css[i];
-    if (ch === '(') depth++;
-    else if (ch === ')') depth--;
-    else if (ch === ';' && depth === 0) break;
-    out += ch;
-  }
-  return out.replace(/\s+/g, ' ').trim();
-}
-
 function extract(file) {
   const abs = path.join(ROOT, file);
-  if (!fs.existsSync(abs)) {
-    throw new Error(`[docs:tokens] Missing canonical token source file: ${abs}`);
-  }
-  const css = fs.readFileSync(abs, 'utf8').replace(/\/\*[\s\S]*?\*\//g, ''); // strip comments first
+  const css = stripComments(requireFile(file, ROOT, `[docs:tokens] Missing canonical token source file: ${abs}`));
   const rows = new Map(); // name -> value (last declaration wins)
 
   // @property registrations: initial-value — scanned AFTER comment stripping
diff --git a/scripts/gen-token-registry.js b/scripts/gen-token-registry.js
index 8a3f791c..02363cda 100644
--- a/scripts/gen-token-registry.js
+++ b/scripts/gen-token-registry.js
@@ -89,6 +89,7 @@ function readCatalogueTokens() {
 
 function main() {
   const registry = readRegistry();
+  const previousCount = registry.tokens.length;
   const catalogue = readCatalogueTokens();
   const known = new Map(registry.tokens.map((t) => [t.name, t]));
 
@@ -130,6 +131,18 @@ function main() {
   // Stable on-disk order: by id (= creation order). nextId stays monotonic.
   registry.tokens.sort((a, b) => a.id - b.id);
 
+  // Regression guard (SL-010/SL-012): this file's own contract (see header
+  // comment) is append-only — entries are flagged `removed`, never deleted.
+  // A shrink here can only mean a bug (e.g. a bad catalogue read truncating
+  // `registry.tokens` before the merge), never a legitimate edit.
+  if (registry.tokens.length < previousCount) {
+    throw new Error(
+      `[docs:registry] refusing to write ${OUT}: entry count shrank from ` +
+        `${previousCount} to ${registry.tokens.length}. This registry is append-only ` +
+        `(tokens are flagged removed, never deleted) — a shrink means a bug upstream, not an intentional edit.`
+    );
+  }
+
   fs.writeFileSync(OUT, JSON.stringify(registry, null, 2) + '\n', 'utf8');
 
   console.log(
diff --git a/scripts/lib/api-index/extract.js b/scripts/lib/api-index/extract.js
new file mode 100644
index 00000000..3b28465c
--- /dev/null
+++ b/scripts/lib/api-index/extract.js
@@ -0,0 +1,602 @@
+/**
+ * Extraction half of scripts/gen-api-index.js (SL-006): everything that reads
+ * source CSS / annotations / the previous generated index and turns it into
+ * assembled token/class entries. The Markdown rendering half lives in
+ * ./render.js — see that file's header for why the split runs there and not
+ * elsewhere. This module has no behavior of its own beyond what
+ * gen-api-index.js already did; it's a relocation, not a rewrite.
+ */
+import fs   from 'node:fs';
+import path from 'node:path';
+import { TOKEN_FILES, CLASS_FILES } from '../../registry-sources.js';
+import { tierOf, roleOf } from '../../token-tiers.js';
+import { maskComments, maskStrings, readValue, requireFile } from '../parse.js';
+
+/**
+ * Read docs/token-annotations.json — the curated overlay for per-token notes
+ * and per-class descriptions. Returns a shape with `tokens` and `classes`
+ * objects; both default to {} when the file is absent or unreadable.
+ * @param {string} annotationsFile absolute path to token-annotations.json
+ * @returns {{ tokens: Record<string,string>, classes: Record<string,string> }}
+ */
+export function readAnnotations(annotationsFile) {
+  if (!fs.existsSync(annotationsFile)) return { tokens: {}, classes: {} };
+  try {
+    const parsed = JSON.parse(fs.readFileSync(annotationsFile, 'utf8'));
+    return {
+      tokens:  parsed.tokens  ?? {},
+      classes: parsed.classes ?? {},
+    };
+  } catch (err) {
+    console.warn(`[docs] Failed to parse ${annotationsFile}:`, err.message);
+    return { tokens: {}, classes: {} };
+  }
+}
+
+/**
+ * Read the previously generated API index as a compatibility overlay. This
+ * preserves curated groups/descriptions when source comments are intentionally
+ * reduced to terse category markers.
+ * @param {string} outFile absolute path to the existing docs/api-index.json
+ * @returns {{ tokens: Map<string, object>, classes: Map<string, object> }}
+ */
+export function readExistingApiIndex(outFile) {
+  const empty = { tokens: new Map(), classes: new Map() };
+  if (!fs.existsSync(outFile)) return empty;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(outFile, 'utf8'));
+    const tokens = new Map();
+    const classes = new Map();
+    for (const entry of parsed.entries ?? []) {
+      if (entry.type === 'token') tokens.set(entry.name, entry);
+      if (entry.type === 'class') classes.set(entry.name, entry);
+    }
+    return { tokens, classes };
+  } catch (err) {
+    console.warn(`[docs] Failed to parse existing ${outFile}:`, err.message);
+    return empty;
+  }
+}
+
+export function isUsefulDescription(description) {
+  return Boolean(description && !/^SLASHED\s+[—-]/.test(description));
+}
+
+// ── Per-file metadata ─────────────────────────────────────────────────────────
+// `category` is the high-level, human-facing area. `area` is a short machine
+// slug. `kind` is the element family produced by the file.
+export const FILE_META = {
+  // Token files
+  'core/tokens.css':                    { category: 'Core tokens',              area: 'core',     kind: 'token' },
+  'core/tokens.layout.css':             { category: 'Layout tokens',            area: 'layout',   kind: 'token' },
+  'core/tokens.macros.css':             { category: 'Macro tokens',             area: 'macros',   kind: 'token' },
+  'optional/tokens.components.css':     { category: 'Component tokens',         area: 'components', kind: 'token' },
+  // Class files
+  'core/layout.css':            { category: 'Layout primitives',     area: 'layout',        kind: 'layout'        },
+  'core/macros.css':            { category: 'Macro classes',         area: 'macros',        kind: 'macro'         },
+  'core/states.css':            { category: 'State classes',         area: 'states',        kind: 'state'         },
+  'core/accessibility.css':     { category: 'Accessibility',         area: 'accessibility', kind: 'accessibility' },
+  'core/motion.css':            { category: 'Motion / animation',    area: 'motion',        kind: 'motion'        },
+  'core/print.css':             { category: 'Print',                 area: 'print',         kind: 'print'         },
+  'core/themes.css':            { category: 'Theme utilities',        area: 'theme',         kind: 'theme'         },
+  'optional/forms.css':         { category: 'Forms (classless)',     area: 'forms',         kind: 'form'          },
+  'optional/components.css':    { category: 'Components',             area: 'components',    kind: 'component'     },
+  'optional/theme-example.css': { category: 'Theme example',         area: 'theme',         kind: 'theme'         },
+};
+
+// ── Source masking (length-preserving) ─────────────────────────────────────────
+// Replacing comment/string bodies with spaces (NOT removing them) keeps every
+// character index stable, so a token/class match found in the masked text can
+// be looked up against section banners parsed from the original text.
+// maskComments/maskStrings (offset-preserving) come from scripts/lib/parse.js —
+// NOT the same contract as that module's stripComments/stripStrings.
+
+/**
+ * Read a workspace-relative source file, throwing a clear error if missing.
+ * @param {string} rel path relative to `root`
+ * @param {string} root absolute repo root
+ * @returns {string} file contents
+ */
+function readSourceFile(rel, root) {
+  return requireFile(rel, root, `[docs:api] Missing source file: ${rel}`);
+}
+
+// ── Section-banner parsing ──────────────────────────────────────────────────
+// A "banner" is a block comment that contains a long divider run (>=10 of '='
+// or '-'). The file-header comment (starts with "SLASHED —" at offset 0) is
+// recognised separately and never used as an element's group — regardless of
+// whether it contains a divider run. Plain NOTE comments (no divider) are not
+// treated as section banners.
+
+export const DIVIDER_RUN = /[-=─═]{10,}/;
+
+/**
+ * True when a comment line is purely a divider rule (ASCII or box-drawing).
+ * @param {string} line trimmed comment line
+ * @returns {boolean}
+ */
+export function lineIsDivider(line) {
+  const compact = line.replace(/\s/g, '');
+  return compact.length >= 4 && /^[-=─═]+$/.test(compact);
+}
+
+/**
+ * Parse a section-banner comment into a `{ title, description }` pair, stripping
+ * divider fences and promoting an inline `Title — lead` description.
+ * @param {string} raw the raw block comment (including delimiters)
+ * @returns {{title: string, description: string}}
+ */
+export function parseBanner(raw) {
+  const inner = raw.replace(/^\/\*+/, '').replace(/\*+\/$/, '');
+  const rawLines = inner.split('\n')
+    .map(l => l.replace(/^\s*\*?\s?/, '').trimEnd())
+    .map(l => l.trim());
+
+  const lines = [];
+  for (let line of rawLines) {
+    if (!line) continue;
+    // "-- Title --------" form (ASCII or box-drawing fences): strip the fences.
+    const fenced = /^[-─]{2,}\s*(.*?)\s*[-─]{2,}$/.exec(line);
+    if (fenced) { if (fenced[1]) lines.push(fenced[1]); continue; }
+    if (lineIsDivider(line)) continue;
+    lines.push(line);
+  }
+  if (!lines.length) return { title: '', description: '' };
+
+  let title = lines[0];
+  let rest  = lines.slice(1);
+
+  // A title like "Flow — distance between flow children" carries an inline
+  // description after an em/en dash (or " - "). Split it off as lead text.
+  const dash = /^(.+?)\s+[—–]\s+(.+)$/.exec(title) || /^(.+?)\s+-\s+(.+)$/.exec(title);
+  let lead = '';
+  if (dash) { title = dash[1].trim(); lead = dash[2].trim(); }
+
+  // Section banners in tokens.css are prefixed with the at-rule they document
+  // (e.g. "@property — BRAND COLORS …"). The keyword is noise as a group name —
+  // promote the part after the dash to be the title instead.
+  if (/^@[\w-]+$/.test(title) && lead) {
+    title = lead;
+    lead = '';
+  }
+
+  const description = [lead, ...rest]
+    .filter(Boolean)
+    .join(' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  return { title, description };
+}
+
+/**
+ * Collapse a non-banner note comment into a single descriptive string.
+ * @param {string} raw the raw block comment
+ * @returns {{title: string, description: string}} title is always empty
+ */
+export function parseNote(raw) {
+  const inner = raw.replace(/^\/\*+/, '').replace(/\*+\/$/, '');
+  const text = inner.split('\n')
+    .map(l => l.replace(/^\s*\*?\s?/, '').trim())
+    .filter(Boolean)
+    .filter(l => !lineIsDivider(l))
+    .join(' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return { title: '', description: text };
+}
+
+/**
+ * Collect every block comment with its position and classification
+ * (file header vs. section banner vs. plain note) for context lookups.
+ * @param {string} css source CSS (comments intact)
+ * @returns {Array<object>} ordered comment records
+ */
+export function collectComments(css) {
+  const comments = [];
+  for (const m of css.matchAll(/\/\*[\s\S]*?\*\//g)) {
+    const raw    = m[0];
+    const start  = m.index;
+    const end    = m.index + raw.length;
+    const isHeader = /SLASHED\s+[—-]/.test(raw) && start < 4;
+    // A banner is either a divider-fenced comment, a "/* -- Title -- */" form,
+    // or a single-line at-rule sub-header ("/* @property — STATUS COLORS */").
+    const singleLineSubHeader = !/\n/.test(raw.trim()) && /^\/\*\s*@[\w-]+\s+[—–-]\s+\S/.test(raw);
+    const isBanner = DIVIDER_RUN.test(raw) || /^\/\*\s*--\s+\S/.test(raw) || singleLineSubHeader;
+    const parsed = (isBanner || isHeader) ? parseBanner(raw) : parseNote(raw);
+    comments.push({ start, end, raw, isHeader, isBanner, ...parsed });
+  }
+  return comments;
+}
+
+/**
+ * Find the comment context governing the element at character `idx`: the
+ * nearest preceding section banner and the nearest preceding comment of any
+ * kind (the latter may attach a more specific description).
+ * @param {Array<object>} comments records from collectComments
+ * @param {number} idx character offset of the element
+ * @returns {{banner: ?object, nearest: ?object}}
+ */
+export function contextAt(comments, idx) {
+  let banner = null;
+  let nearest = null;
+  for (const c of comments) {
+    if (c.end > idx) break;
+    if (c.isHeader) continue;
+    nearest = c;
+    if (c.isBanner) banner = c;
+  }
+  return { banner, nearest };
+}
+
+/**
+ * Trim a description to a documentation-hint length, breaking on a word
+ * boundary and appending an ellipsis when truncated.
+ * @param {string} str input text
+ * @param {number} [max=280] maximum length
+ * @returns {string}
+ */
+export function truncate(str, max = 280) {
+  if (!str) return '';
+  const clean = str.replace(/\s+/g, ' ').trim();
+  if (clean.length <= max) return clean;
+  return clean.slice(0, max - 1).replace(/\s+\S*$/, '') + '…';
+}
+
+/**
+ * Derive a `{ group, description }` for the element at `idx` from its comment
+ * context, preferring an attached note over the governing banner's prose.
+ * @param {Array<object>} comments records from collectComments
+ * @param {number} idx character offset of the element
+ * @returns {{group: string, description: string}}
+ */
+export function describe(comments, idx) {
+  const { banner, nearest } = contextAt(comments, idx);
+  const group = banner ? banner.title : '';
+  // Prefer a specific note attached directly above the element; otherwise fall
+  // back to the governing banner's own description (or its title).
+  let description = '';
+  if (nearest && nearest !== banner && nearest.description) {
+    description = nearest.description;
+  } else if (banner) {
+    description = banner.description || banner.title;
+  } else if (nearest) {
+    description = nearest.description;
+  }
+  return { group, description: truncate(description) };
+}
+
+// readValue (comment-masked-safe, identical contract to gen-token-index.js /
+// gen-token-reference.js) comes from scripts/lib/parse.js.
+
+/**
+ * Find the first `@layer` a file declares (e.g. "slashed.layout").
+ * @param {string} maskedCss comment-masked CSS
+ * @returns {?string} the layer name, or null
+ */
+export function layerOf(maskedCss) {
+  const m = /@layer\s+(slashed(?:\.[\w-]+)?)/.exec(maskedCss);
+  return m ? m[1] : null;
+}
+
+// ── Bundle membership ───────────────────────────────────────────────────────
+// Map each source file to the set of bundle tiers that ship it. Layered and
+// flat variants of the same tier collapse to one name (e.g. "essential").
+/**
+ * Build the file → bundle-tiers map from bundle.config.json (layered and flat
+ * variants of a tier collapse to one name) plus a `bundlesFor(file)` resolver.
+ * @param {string} root absolute repo root
+ * @param {string} bundleConfigRel path to bundle.config.json, relative to root
+ * @returns {{bundlesFor: (file: string) => string[], allBundles: string[]}}
+ */
+export function buildBundleMap(root, bundleConfigRel = 'bundle.config.json') {
+  const cfg = JSON.parse(readSourceFile(bundleConfigRel, root));
+  const fileToBundles = new Map();
+  const allBundles = new Set();
+  for (const bundle of cfg.bundles || []) {
+    const tier = path.basename(bundle.output)
+      .replace(/^slashed\./, '')
+      .replace(/\.flat/, '')
+      .replace(/\.css$/, '');
+    allBundles.add(tier);
+    for (const file of bundle.files || []) {
+      if (!fileToBundles.has(file)) fileToBundles.set(file, new Set());
+      fileToBundles.get(file).add(tier);
+    }
+  }
+  // Stable bundle ordering: by ascending breadth (how many files each ships),
+  // so smaller tiers list first.
+  const order = [...allBundles].sort((a, b) => a.localeCompare(b));
+  const rank = new Map(order.map((b, i) => [b, i]));
+  const bundlesFor = file => {
+    const set = fileToBundles.get(file);
+    if (!set) return [];
+    return [...set].sort((a, b) => rank.get(a) - rank.get(b));
+  };
+  return { bundlesFor, allBundles: order };
+}
+
+// ── Token name → namespace ──────────────────────────────────────────────────
+// The second path segment of a token name is a useful machine-filterable
+// facet, e.g. --sf-color-primary → "color", --sf-space-m → "space".
+/**
+ * Extract a token's namespace facet — the second name segment, e.g.
+ * `--sf-color-primary` → "color", `--sf-space-m` → "space".
+ * @param {string} name token custom-property name
+ * @returns {?string}
+ */
+export function namespaceOf(name) {
+  const m = /^--sf-([a-z0-9]+)/.exec(name);
+  return m ? m[1] : null;
+}
+
+/**
+ * Return the alias target when a value is exactly one `var(--sf-x)` reference.
+ * @param {string} value declared value
+ * @returns {?string} the referenced token name, or null
+ */
+export function aliasTarget(value) {
+  const m = /^var\(\s*(--sf-[\w-]+)\s*\)$/.exec(value || '');
+  return m ? m[1] : null;
+}
+
+// ── Token extraction ──────────────────────────────────────────────────────────
+
+/**
+ * Extract every token from one source file with its value, @property metadata
+ * and derived group/description. Last declaration wins per file for the value.
+ * @param {string} rel source file path
+ * @param {string} root absolute repo root
+ * @returns {Map<string, object>} name → partial token data
+ */
+export function extractTokensFromFile(rel, root) {
+  const original = readSourceFile(rel, root);
+  const masked   = maskComments(original);
+  const comments = collectComments(original);
+  const layer    = layerOf(masked);
+  const rows = new Map(); // name -> partial entry data
+
+  // @property registrations: tier-precise syntax / inherits / initial-value.
+  for (const m of masked.matchAll(/@property\s+(--sf-[\w-]+)\s*\{([^}]*)\}/g)) {
+    const name = m[1];
+    const body = m[2];
+    const syntax   = /syntax\s*:\s*("(?:[^"]*)"|'(?:[^']*)')/.exec(body);
+    const inherits = /inherits\s*:\s*(true|false)/.exec(body);
+    const initial  = /initial-value\s*:\s*([^;]+);/.exec(body);
+    const { group, description } = describe(comments, m.index);
+    rows.set(name, {
+      registered: true,
+      syntax:   syntax ? syntax[1].replace(/^['"]|['"]$/g, '') : null,
+      inherits: inherits ? inherits[1] === 'true' : null,
+      value:    initial ? initial[1].trim() : (rows.get(name)?.value ?? null),
+      group, description, layer,
+    });
+  }
+
+  // Custom-property declarations (last declaration wins per file for value).
+  const re = /(--sf-[\w-]+)\s*:/g;
+  let m;
+  while ((m = re.exec(masked)) !== null) {
+    const name  = m[1];
+    const colon = m.index + m[0].length - 1;
+    const value = readValue(masked, colon);
+    const prev  = rows.get(name) || {};
+    const ctx   = describe(comments, m.index);
+    rows.set(name, {
+      registered: prev.registered || false,
+      syntax:   prev.syntax ?? null,
+      inherits: prev.inherits ?? null,
+      value,
+      // Keep the first encountered group/description (definition site); fall
+      // back to declaration context if @property didn't supply one.
+      group:       prev.group || ctx.group,
+      description: prev.description || ctx.description,
+      layer:       prev.layer || layer,
+    });
+  }
+
+  return rows;
+}
+
+// ── Class extraction ──────────────────────────────────────────────────────────
+
+/**
+ * Extract prefixed (.sf-/.is-) and unprefixed framework classes from one file,
+ * with selector, kind, BEM-variant info and derived group/description.
+ * @param {string} rel source file path
+ * @param {string} root absolute repo root
+ * @param {(file: string) => string[]} bundlesFor bundle resolver
+ * @returns {Map<string, object>} name → class entry
+ */
+export function extractClassesFromFile(rel, root, bundlesFor) {
+  const original = readSourceFile(rel, root);
+  const masked   = maskStrings(maskComments(original));
+  const comments = collectComments(original);
+  const layer    = layerOf(masked);
+  const meta     = FILE_META[rel];
+  const rows = new Map(); // name -> entry
+
+  /**
+   * Record a class on first occurrence (which defines its comment context).
+   * @param {Map<string, object>} map accumulator
+   * @param {string} name class name (no leading dot)
+   * @param {number} idx character offset of the match
+   */
+  function addClass(map, name, idx) {
+    if (map.has(name)) return; // first occurrence defines its context
+    const prefix = name.startsWith('sf-') ? 'sf' : name.startsWith('is-') ? 'is' : '';
+    const variantSplit = name.indexOf('--');
+    const ctx = describe(comments, idx);
+    map.set(name, {
+      name,
+      type: 'class',
+      tier: 'PUBLIC',
+      selector: `.${name}`,
+      prefix,
+      kind: meta.kind,
+      category: meta.category,
+      area: meta.area,
+      group: ctx.group || '',
+      description: ctx.description || '',
+      isVariant: variantSplit > 0,
+      baseClass: variantSplit > 0 ? name.slice(0, variantSplit) : null,
+      optional: rel.startsWith('optional/'),
+      layer: layer || null,
+      sourceFiles: [rel],
+      bundles: bundlesFor(rel),
+    });
+  }
+
+  // Prefixed classes: .sf-* and .is-*
+  for (const m of masked.matchAll(/\.((?:sf|is)-[\w-]+)/g)) {
+    addClass(rows, m[1], m.index);
+  }
+  // Unprefixed framework classes (a11y helpers, print utilities, theme helper).
+  // Skip dotted @layer names by neutralising @layer declarations first.
+  const noLayer = masked.replace(/@layer\s+[^{;]+[{;]/g, mm => mm.replace(/[^\n]/g, ' '));
+  for (const m of noLayer.matchAll(/\.([a-z][\w-]*)/g)) {
+    const name = m[1];
+    if (name.startsWith('sf-') || name.startsWith('is-')) continue;
+    addClass(rows, name, m.index);
+  }
+
+  return rows;
+}
+
+/**
+ * Merge tokens across all TOKEN_FILES with curated per-token annotations.
+ * @param {string} root absolute repo root
+ * @param {(file: string) => string[]} bundlesFor bundle resolver
+ * @param {Record<string,string>} tokenAnnotations token name → curated description
+ * @param {Map<string,object>} existingTokens previous generated index, for the compat overlay
+ * @returns {Map<string, object>} name → token entry
+ */
+export function buildTokenEntries(root, bundlesFor, tokenAnnotations = {}, existingTokens = new Map()) {
+  const merged = new Map(); // name -> entry
+
+  for (const rel of TOKEN_FILES) {
+    const rows = extractTokensFromFile(rel, root);
+    const meta = FILE_META[rel];
+    for (const [name, data] of rows) {
+      const existing = merged.get(name);
+      if (!existing) {
+        merged.set(name, {
+          name,
+          type: 'token',
+          tier: tierOf(name),
+          role: roleOf(data.value, name),
+          namespace: namespaceOf(name),
+          category: meta.category,
+          area: meta.area,
+          group: data.group || '',
+          description: data.description || '',
+          value: data.value ?? null,
+          aliasOf: aliasTarget(data.value),
+          registered: !!data.registered,
+          animatable: !!data.registered,
+          syntax: data.syntax ?? null,
+          inherits: data.inherits ?? null,
+          optional: rel.startsWith('optional/'),
+          layer: data.layer || null,
+          sourceFiles: [rel],
+          bundles: new Set(bundlesFor(rel)),
+        });
+      } else {
+        // Token redeclared in a later file — last value wins, union sources.
+        existing.value = data.value ?? existing.value;
+        existing.aliasOf = aliasTarget(existing.value);
+        existing.role = roleOf(existing.value, name);
+        existing.registered = existing.registered || !!data.registered;
+        existing.animatable = existing.registered;
+        existing.syntax = existing.syntax ?? data.syntax ?? null;
+        existing.inherits = existing.inherits ?? data.inherits ?? null;
+        if (!existing.group && data.group) existing.group = data.group;
+        if (!existing.description && data.description) existing.description = data.description;
+        if (!existing.sourceFiles.includes(rel)) existing.sourceFiles.push(rel);
+        for (const b of bundlesFor(rel)) existing.bundles.add(b);
+      }
+    }
+  }
+  // Overlay curated per-token descriptions from token-annotations.json.
+  for (const [name, entry] of merged) {
+    const previous = existingTokens.get(name);
+    if (previous) {
+      if (!entry.group && previous.group) entry.group = previous.group;
+      if (!isUsefulDescription(entry.description) && previous.description) entry.description = previous.description;
+    }
+    if (tokenAnnotations[name]) entry.description = tokenAnnotations[name];
+  }
+  return merged;
+}
+
+/**
+ * Merge classes across all CLASS_FILES into finished entries, unioning source
+ * files and bundle membership for classes declared in more than one file.
+ * Per-class descriptions from docs/token-annotations.json["classes"] override
+ * the auto-derived banner-comment description when present.
+ * @param {string} root absolute repo root
+ * @param {(file: string) => string[]} bundlesFor bundle resolver
+ * @param {Record<string,string>} classAnnotations class name → curated description
+ * @param {Map<string,object>} existingClasses previous generated index, for the compat overlay
+ * @returns {Map<string, object>} name → class entry
+ */
+export function buildClassEntries(root, bundlesFor, classAnnotations = {}, existingClasses = new Map()) {
+  const merged = new Map(); // name -> entry (union of files)
+  for (const rel of CLASS_FILES) {
+    const rows = extractClassesFromFile(rel, root, bundlesFor);
+    for (const [name, entry] of rows) {
+      const existing = merged.get(name);
+      if (!existing) {
+        merged.set(name, { ...entry, bundles: new Set(entry.bundles) });
+      } else {
+        if (!existing.sourceFiles.includes(rel)) existing.sourceFiles.push(rel);
+        for (const b of entry.bundles) existing.bundles.add(b);
+        if (!existing.group && entry.group) existing.group = entry.group;
+        if (!existing.description && entry.description) existing.description = entry.description;
+      }
+    }
+  }
+  // Overlay curated per-class descriptions from token-annotations.json.
+  // The annotation wins unconditionally so the curated text always appears.
+  for (const [name, entry] of merged) {
+    const previous = existingClasses.get(name);
+    if (previous) {
+      if (!entry.group && previous.group) entry.group = previous.group;
+      if (!isUsefulDescription(entry.description) && previous.description) entry.description = previous.description;
+    }
+    if (classAnnotations[name]) entry.description = classAnnotations[name];
+  }
+  return merged;
+}
+
+// ── Assemble ────────────────────────────────────────────────────────────────
+
+/**
+ * Finalise an entry for output: convert its `bundles` Set into a stably ordered
+ * array.
+ * @param {object} entry in-progress entry (bundles is a Set)
+ * @param {(b: string) => number} bundleOrderRank ordering key
+ * @returns {object} output-ready entry
+ */
+export function finalizeEntry(entry, bundleOrderRank) {
+  const out = { ...entry };
+  out.bundles = [...entry.bundles].sort((a, b) => bundleOrderRank(a) - bundleOrderRank(b));
+  return out;
+}
+
+/**
+ * Count entries grouped by the value of one key, returned as a key-sorted
+ * object (used for the `_meta.counts` breakdowns).
+ * @param {Array<object>} entries rows
+ * @param {string} key field to group by
+ * @returns {Object<string, number>}
+ */
+export function tally(entries, key) {
+  const counts = {};
+  for (const e of entries) {
+    const k = e[key];
+    if (k == null) continue;
+    counts[k] = (counts[k] || 0) + 1;
+  }
+  return Object.fromEntries(Object.entries(counts).sort((a, b) => a[0].localeCompare(b[0])));
+}
diff --git a/scripts/lib/api-index/render.js b/scripts/lib/api-index/render.js
new file mode 100644
index 00000000..a347244b
--- /dev/null
+++ b/scripts/lib/api-index/render.js
@@ -0,0 +1,83 @@
+/**
+ * Rendering half of scripts/gen-api-index.js (SL-006): builds the Markdown
+ * companion from the SAME assembled data ./extract.js produces, so the two
+ * views (docs/api-index.json and docs/api-index.md) can never drift. This is
+ * a relocation, not a rewrite — no logic changed from the original file.
+ */
+
+/**
+ * Escape a value for a Markdown table cell: backslash first (so we don't
+ * re-escape our own escapes), then the pipe column-separator.
+ * @param {*} v cell value
+ * @returns {string} escaped text
+ */
+export const escCell = v => String(v ?? '').replace(/\\/g, '\\\\').replace(/\|/g, '\\|');
+
+/**
+ * Group entries by their `category` field, returned as category-sorted
+ * `[category, entries]` pairs for the Markdown tables.
+ * @param {Array<object>} entries rows
+ * @returns {Array<[string, object[]]>}
+ */
+export function groupByCategory(entries) {
+  const map = new Map();
+  for (const e of entries) {
+    if (!map.has(e.category)) map.set(e.category, []);
+    map.get(e.category).push(e);
+  }
+  return [...map.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+}
+
+/**
+ * Render the human-readable Markdown companion from the same assembled data as
+ * the JSON, so the two views can never drift.
+ * @param {object} data assembled entries + count breakdowns
+ * @returns {string} Markdown document
+ */
+export function buildMarkdown({ entries, tokenEntries, classEntries, tierCounts, typeCounts }) {
+  let md = `# API index
+
+> **Generated** from source by \`scripts/gen-api-index.js\` —
+> run \`npm run docs:api\` to refresh. Do not edit by hand.
+
+A single browseable catalogue of every public SLASHED element — design
+**tokens** and **classes** — with stability tier, category, bundle membership
+and a short description. The machine-readable companion (with all columns) is
+[api-index.json](api-index.json); for the flat name list see
+[registry.json](registry.json); for the tier contract see
+[architecture.md](architecture.md).
+
+**${entries.length} elements** — ${typeCounts.token || 0} tokens, ${typeCounts.class || 0} classes.
+
+| Tier | Count | Meaning |
+|---|---|---|
+| PUBLIC | ${tierCounts.PUBLIC || 0} | Everyday surface. SemVer-stable. |
+| PUBLIC-ADVANCED | ${tierCounts['PUBLIC-ADVANCED'] || 0} | Same SemVer guarantee; niche/powerful. |
+| INTERNAL | ${tierCounts.INTERNAL || 0} | Implementation detail; may change without a major bump. |
+
+`;
+
+  // Tokens
+  md += `## Tokens (${tokenEntries.length})\n\n`;
+  for (const [category, list] of groupByCategory(tokenEntries)) {
+    md += `### ${category} (${list.length})\n\n`;
+    md += '| Token | Tier | Role | Namespace | Default | Description |\n|---|---|---|---|---|---|\n';
+    for (const e of list) {
+      md += `| \`${e.name}\` | ${e.tier} | ${e.role || '—'} | ${e.namespace || '—'} | \`${escCell(e.value)}\` | ${escCell(e.description)} |\n`;
+    }
+    md += '\n';
+  }
+
+  // Classes
+  md += `## Classes (${classEntries.length})\n\n`;
+  for (const [category, list] of groupByCategory(classEntries)) {
+    md += `### ${category} (${list.length})\n\n`;
+    md += '| Class | Tier | Kind | Group | Description |\n|---|---|---|---|---|\n';
+    for (const e of list) {
+      md += `| \`${e.selector}\` | ${e.tier} | ${e.kind} | ${escCell(e.group) || '—'} | ${escCell(e.description)} |\n`;
+    }
+    md += '\n';
+  }
+
+  return md;
+}
diff --git a/scripts/lib/parse.js b/scripts/lib/parse.js
new file mode 100644
index 00000000..ba429977
--- /dev/null
+++ b/scripts/lib/parse.js
@@ -0,0 +1,95 @@
+/**
+ * Shared CSS/file-reading helpers for the scripts/*.js generators and checks.
+ *
+ * Before this module, `stripComments`/`maskComments`, `readValue`, and
+ * `readFile` were each reimplemented independently across 4+ scripts — see
+ * docs/technical-debt-audit.md SL-007. `stripComments` and `maskComments`
+ * are NOT interchangeable and must stay separate exports:
+ *   - stripComments REMOVES comment bodies, shortening the string. Fine for
+ *     scripts that only count/extract values and don't need offsets to line
+ *     up with the original source.
+ *   - maskComments REPLACES comment bodies with same-length whitespace,
+ *     preserving every character's offset. Required by gen-api-index.js,
+ *     which looks up section banners by offset in the original text after
+ *     matching against the masked text.
+ * The same distinction applies to stripStrings vs maskStrings.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Remove block comments, shortening the string. Not offset-safe. */
+export function stripComments(css) {
+  return css.replace(/\/\*[\s\S]*?\*\//g, '');
+}
+
+/** Remove quoted string literals, shortening the string. Not offset-safe. */
+export function stripStrings(css) {
+  return css.replace(/"[^"]*"|'[^']*'/g, '""');
+}
+
+/**
+ * Mask block-comment bodies with spaces (length-preserving) so character
+ * offsets stay stable for later banner/section lookups.
+ * @param {string} css source CSS
+ * @returns {string} CSS with comment bodies blanked
+ */
+export function maskComments(css) {
+  return css.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '));
+}
+
+/**
+ * Mask string-literal bodies with spaces (length-preserving) so quoted class
+ * names inside `content:"…"` aren't mistaken for selectors.
+ * @param {string} css source CSS
+ * @returns {string} CSS with string bodies blanked
+ */
+export function maskStrings(css) {
+  return css.replace(/"[^"]*"|'[^']*'/g, (m) => m.replace(/[^\n]/g, ' '));
+}
+
+/**
+ * Read a custom-property value starting at its `:` offset, honouring nested
+ * parentheses so light-dark()/oklch()/clamp() values stay intact.
+ * @param {string} css source (comment-stripped or -masked)
+ * @param {number} colonIdx offset of the `:` after the property name
+ * @returns {string} the normalised value text
+ */
+export function readValue(css, colonIdx) {
+  let depth = 0;
+  let out = '';
+  for (let i = colonIdx + 1; i < css.length; i++) {
+    const ch = css[i];
+    if (ch === '(') depth++;
+    else if (ch === ')') depth--;
+    else if (ch === ';' && depth === 0) break;
+    out += ch;
+  }
+  return out.replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Read a workspace-relative file. No existence check — mirrors
+ * version-sync.js's original bare `fs.readFileSync`, which lets a missing
+ * file surface Node's own ENOENT rather than a custom message.
+ * @param {string} rel path relative to `root`
+ * @param {string} root absolute repo root
+ * @returns {string} file contents
+ */
+export function readFile(rel, root) {
+  return fs.readFileSync(path.join(root, rel), 'utf8');
+}
+
+/**
+ * Read a workspace-relative file, throwing `message` if it doesn't exist.
+ * @param {string} rel path relative to `root`
+ * @param {string} root absolute repo root
+ * @param {string} message error message to throw when the file is missing
+ * @returns {string} file contents
+ */
+export function requireFile(rel, root, message) {
+  const abs = path.join(root, rel);
+  if (!fs.existsSync(abs)) {
+    throw new Error(message);
+  }
+  return fs.readFileSync(abs, 'utf8');
+}
diff --git a/scripts/version-sync.js b/scripts/version-sync.js
index 3d28ef80..ff885c43 100644
--- a/scripts/version-sync.js
+++ b/scripts/version-sync.js
@@ -13,11 +13,12 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { readFile as readFileLib } from './lib/parse.js';
 
 const ROOT = path.resolve(import.meta.dirname, '..');
 
 function readFile(rel) {
-  return fs.readFileSync(path.join(ROOT, rel), 'utf8');
+  return readFileLib(rel, ROOT);
 }
 
 function writeFile(rel, content) {
diff --git a/tests/README.md b/tests/README.md
new file mode 100644
index 00000000..6ffd799d
--- /dev/null
+++ b/tests/README.md
@@ -0,0 +1,28 @@
+# Test conventions
+
+Two runners, split by whether a test needs a real browser:
+
+- **`*.spec.js`** — Playwright (`npm test`). Runs across chromium/firefox/webkit.
+  Use for anything that renders CSS and reads computed styles, layout geometry,
+  or visual output — imports `test`/`expect` from `@playwright/test`.
+- **`*.test.js`** — Node's built-in test runner (`npm run test:unit`), single
+  process, no browser. Use for pure fs/regex/data-shape checks that never touch
+  a DOM — imports `test`/`describe` from `node:test` and `assert` from
+  `node:assert/strict`. Wire new files into `pretest`/`test:unit` in
+  `package.json`.
+
+If a test doesn't call `page.*` or read a computed style, it almost certainly
+belongs in `*.test.js`, not `*.spec.js` — see SL-027 (`coverage.test.js` used
+to be Playwright-discovered despite never touching a browser, tripling its CI
+cost for no reason).
+
+## `tier1-p*` numbering (SL-032)
+
+`tier1-p2-coverage`, `tier1-p7-oldengine`, `tier1-p8-modern`, and
+`tier1-p10-contrast` number their properties P2/P7/P8/P10 with no P1,
+P3-P6, or P9 anywhere in the repo. These numbers come from the
+tier-1-color-fallback feature's original property enumeration (see each
+file's own `Property N:` header comment) — only a subset of the enumerated
+properties warranted a dedicated automated test; the rest were covered by
+other existing tests, manual review, or judged unnecessary to automate. The
+gaps are not dead history — don't renumber these files sequentially.
diff --git a/tests/a11y-patterns.spec.js b/tests/a11y-patterns.spec.js
index ecaba27e..2c30d363 100644
--- a/tests/a11y-patterns.spec.js
+++ b/tests/a11y-patterns.spec.js
@@ -4,16 +4,11 @@
 //   .sf-focus-parent, .sf-clickable-parent,
 //   touch-target token, forced-colors, disabled cursor.
 import { test, expect } from '@playwright/test';
-import path from 'node:path';
-
-const BUNDLE = path.join(process.cwd(), 'badges', 'slashed.optimal.css');
+import { renderWithBundle, NO_TRANSITIONS_STYLE } from './render-helpers.js';
 
 async function setup(page, html) {
-  await page.setViewportSize({ width: 800, height: 600 });
-  await page.setContent(`<!doctype html><html><body style="margin:0">${html}</body></html>`);
-  await page.addStyleTag({ path: BUNDLE });
   // Disable transitions so computed property reads are stable (no mid-animation values).
-  await page.addStyleTag({ content: '*, *::before, *::after { transition: none !important; animation-duration: 0s !important; }' });
+  await renderWithBundle(page, html, { width: 800, height: 600, extraStyle: NO_TRANSITIONS_STYLE });
 }
 
 // ── .sr-only ────────────────────────────────────────────────────
diff --git a/tests/container-queries.spec.js b/tests/container-queries.spec.js
index c7e50853..e6236de3 100644
--- a/tests/container-queries.spec.js
+++ b/tests/container-queries.spec.js
@@ -5,9 +5,7 @@
 // setupInContainer pins font-size to 16px so em-based CQ thresholds are stable
 // across browsers (WebKit 26+ resolves em against inherited font-size, not 16px).
 import { test, expect } from '@playwright/test';
-import path from 'node:path';
-
-const BUNDLE = path.join(process.cwd(), 'badges', 'slashed.optimal.css');
+import { BUNDLE } from './render-helpers.js';
 
 // Wraps grid HTML in a container of a known inline-size so anonymous
 // @container queries fire against that width, not the viewport.
diff --git a/tests/coverage.spec.js b/tests/coverage.test.js
similarity index 85%
rename from tests/coverage.spec.js
rename to tests/coverage.test.js
index 64af3582..5321cf7a 100644
--- a/tests/coverage.spec.js
+++ b/tests/coverage.test.js
@@ -1,8 +1,3 @@
-// @ts-check
-import { test, expect } from '@playwright/test';
-import fs from 'node:fs';
-import path from 'node:path';
-
 /**
  * Selector inventory coverage test.
  *
@@ -15,11 +10,20 @@ import path from 'node:path';
  *   an example in comments, .sf-nav .is-current — component-layer refs)
  * - BEM children (.sf-cover__center) — checked by their parent
  * - Selectors that only exist in comments
+ *
+ * Run: node --test tests/coverage.test.js
  */
-test.describe('Selector coverage', () => {
-  test('every .sf-* and .is-* class from core/*.css appears in docs/demo.html', async () => {
-    const coreDir = path.resolve(process.cwd(), 'core');
-    const demoPath = path.resolve(process.cwd(), 'docs', 'demo.html');
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const ROOT = path.resolve(import.meta.dirname, '..');
+
+describe('Selector coverage', () => {
+  test('every .sf-* and .is-* class from core/*.css appears in docs/demo.html', () => {
+    const coreDir = path.join(ROOT, 'core');
+    const demoPath = path.join(ROOT, 'docs', 'demo.html');
 
     // Read all core CSS files
     const cssFiles = fs.readdirSync(coreDir).filter(f => f.endsWith('.css'));
@@ -62,6 +66,6 @@ test.describe('Selector coverage', () => {
     if (missing.length > 0) {
       console.log('Missing from demo.html:', missing.sort().join(', '));
     }
-    expect(missing).toEqual([]);
+    assert.deepEqual(missing, []);
   });
 });
diff --git a/tests/layers.spec.js b/tests/layers.spec.js
index 96989c17..6d84e33e 100644
--- a/tests/layers.spec.js
+++ b/tests/layers.spec.js
@@ -1,6 +1,6 @@
 // @ts-check
 import { test, expect } from '@playwright/test';
-import path from 'node:path';
+import { BUNDLE } from './render-helpers.js';
 
 /**
  * Layer ordering invariant test.
@@ -26,7 +26,7 @@ test.describe('Layer ordering', () => {
       </style>
       <div class="layer-check">test</div>
     `);
-    await page.addStyleTag({ path: path.join(process.cwd(), 'badges', 'slashed.optimal.css') });
+    await page.addStyleTag({ path: BUNDLE });
 
     const color = await page.locator('.layer-check').evaluate(el =>
       getComputedStyle(el).color
@@ -42,7 +42,7 @@ test.describe('Layer ordering', () => {
       </style>
       <div class="layer-check-2">test</div>
     `);
-    await page.addStyleTag({ path: path.join(process.cwd(), 'badges', 'slashed.optimal.css') });
+    await page.addStyleTag({ path: BUNDLE });
 
     const opacity = await page.locator('.layer-check-2').evaluate(el =>
       getComputedStyle(el).opacity
@@ -58,7 +58,7 @@ test.describe('Layer ordering', () => {
       </style>
       <div class="layer-check-3">test</div>
     `);
-    await page.addStyleTag({ path: path.join(process.cwd(), 'badges', 'slashed.optimal.css') });
+    await page.addStyleTag({ path: BUNDLE });
 
     const opacity = await page.locator('.layer-check-3').evaluate(el =>
       getComputedStyle(el).opacity
@@ -76,7 +76,7 @@ test.describe('Layer ordering', () => {
       </style>
       <div class="layer-check-4">test</div>
     `);
-    await page.addStyleTag({ path: path.join(process.cwd(), 'badges', 'slashed.optimal.css') });
+    await page.addStyleTag({ path: BUNDLE });
 
     const color = await page.locator('.layer-check-4').evaluate(el =>
       getComputedStyle(el).color
@@ -94,7 +94,7 @@ test.describe('Layer ordering', () => {
       </style>
       <div class="layer-check-5">test</div>
     `);
-    await page.addStyleTag({ path: path.join(process.cwd(), 'badges', 'slashed.optimal.css') });
+    await page.addStyleTag({ path: BUNDLE });
 
     const opacity = await page.locator('.layer-check-5').evaluate(el =>
       getComputedStyle(el).opacity
@@ -113,7 +113,7 @@ test.describe('Layer ordering', () => {
       </style>
       <div class="layer-check-6">test</div>
     `);
-    await page.addStyleTag({ path: path.join(process.cwd(), 'badges', 'slashed.optimal.css') });
+    await page.addStyleTag({ path: BUNDLE });
 
     const opacity = await page.locator('.layer-check-6').evaluate(el =>
       getComputedStyle(el).opacity
diff --git a/tests/layout.spec.js b/tests/layout.spec.js
index 5650571a..3f14087b 100644
--- a/tests/layout.spec.js
+++ b/tests/layout.spec.js
@@ -1,14 +1,10 @@
 // @ts-check
 // Behavioural tests for core/layout.css — every layout primitive.
 import { test, expect } from '@playwright/test';
-import path from 'node:path';
-
-const BUNDLE = path.join(process.cwd(), 'badges', 'slashed.optimal.css');
+import { renderWithBundle } from './render-helpers.js';
 
 async function setup(page, html) {
-  await page.setViewportSize({ width: 1200, height: 900 });
-  await page.setContent(`<!doctype html><html><body style="margin:0">${html}</body></html>`);
-  await page.addStyleTag({ path: BUNDLE });
+  await renderWithBundle(page, html, { width: 1200, height: 900 });
 }
 
 // ── .sf-section ────────────────────────────────────────────────
diff --git a/tests/macros.spec.js b/tests/macros.spec.js
index 9e7f98a0..b3dcce06 100644
--- a/tests/macros.spec.js
+++ b/tests/macros.spec.js
@@ -3,14 +3,12 @@
 // Each macro is exercised against a synthetic fixture and its
 // observable effect verified via getComputedStyle / layout reads.
 import { test, expect } from '@playwright/test';
-import path from 'node:path';
-
-const BUNDLE = path.join(process.cwd(), 'badges', 'slashed.optimal.css');
+import { renderWithBundle } from './render-helpers.js';
 
 async function setup(page, html) {
-  await page.setViewportSize({ width: 800, height: 600 });
-  await page.setContent(`<!doctype html><html><body>${html}</body></html>`);
-  await page.addStyleTag({ path: BUNDLE });
+  // Unlike the other spec files' setup(), body has no margin:0 here —
+  // preserved as-is (bodyMargin: null omits the style attribute entirely).
+  await renderWithBundle(page, html, { width: 800, height: 600, bodyMargin: null });
 }
 
 test.describe('macro: .sf-flow', () => {
diff --git a/tests/parse-lib.test.js b/tests/parse-lib.test.js
new file mode 100644
index 00000000..12acbec5
--- /dev/null
+++ b/tests/parse-lib.test.js
@@ -0,0 +1,115 @@
+/**
+ * Tests for scripts/lib/parse.js — the shared CSS/file-reading helpers
+ * consolidated from 6 generator/audit scripts (SL-007). The PR that
+ * introduced this module relies on "generated docs output is byte-identical"
+ * as its correctness signal; these tests guard the shared surface itself so
+ * a future regex/logic change fails fast here instead of only showing up as
+ * a silent docs diff.
+ *
+ * Run: node --test tests/parse-lib.test.js
+ */
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  stripComments, stripStrings, maskComments, maskStrings,
+  readValue, readFile, requireFile,
+} from '../scripts/lib/parse.js';
+
+describe('stripComments vs maskComments', () => {
+  const css = '.a { color: red; } /* comment */ .b { color: blue; }';
+
+  test('stripComments removes the comment body, shortening the string', () => {
+    const result = stripComments(css);
+    assert.equal(result.includes('comment'), false);
+    assert.ok(result.length < css.length);
+  });
+
+  test('maskComments preserves the original length and every non-comment character offset', () => {
+    const result = maskComments(css);
+    assert.equal(result.length, css.length);
+    // Everything outside the comment is untouched, so a match found in the
+    // masked text lands on the same offset in the original.
+    const bIndex = css.indexOf('.b');
+    assert.equal(result.indexOf('.b'), bIndex);
+    assert.equal(result.includes('comment'), false); // body is blanked
+  });
+
+  test('maskComments preserves embedded newlines (offset math stays line-accurate)', () => {
+    const multiline = '.a {}\n/* line1\nline2 */\n.b {}';
+    const masked = maskComments(multiline);
+    assert.equal(masked.length, multiline.length);
+    assert.equal(masked.split('\n').length, multiline.split('\n').length);
+  });
+});
+
+describe('stripStrings vs maskStrings', () => {
+  const css = '.a::before { content: "hello"; } .b { color: red; }';
+
+  test('stripStrings collapses the string literal, shortening the string', () => {
+    const result = stripStrings(css);
+    assert.equal(result.includes('hello'), false);
+    assert.ok(result.length < css.length);
+  });
+
+  test('maskStrings preserves length and offsets outside the string', () => {
+    const result = maskStrings(css);
+    assert.equal(result.length, css.length);
+    const bIndex = css.indexOf('.b');
+    assert.equal(result.indexOf('.b'), bIndex);
+  });
+});
+
+describe('readValue', () => {
+  test('reads a simple declaration up to the terminating semicolon', () => {
+    const css = '--sf-space-m: 1rem;';
+    assert.equal(readValue(css, css.indexOf(':')), '1rem');
+  });
+
+  test('does not terminate on a semicolon nested inside parentheses', () => {
+    // clamp()/light-dark() style values can't contain a literal ';' in real
+    // CSS, but the depth counter must still ignore ')' vs top-level ';'
+    // correctly for nested function calls generally.
+    const css = '--sf-x: clamp(1rem, calc(1rem + 2vw), 3rem);';
+    assert.equal(readValue(css, css.indexOf(':')), 'clamp(1rem, calc(1rem + 2vw), 3rem)');
+  });
+
+  test('handles deeply nested parentheses without losing the outer close', () => {
+    const css = '--sf-y: oklch(from var(--sf-color-base) clamp(0.1, calc(l - 0.04), 0.9) c h);';
+    const value = readValue(css, css.indexOf(':'));
+    assert.equal(value, 'oklch(from var(--sf-color-base) clamp(0.1, calc(l - 0.04), 0.9) c h)');
+  });
+
+  test('collapses internal whitespace and trims the result', () => {
+    const css = '--sf-z:   1   2   ;';
+    assert.equal(readValue(css, css.indexOf(':')), '1 2');
+  });
+});
+
+describe('readFile vs requireFile — missing-file behavior', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'parse-lib-test-'));
+  const existingRel = 'present.css';
+  fs.writeFileSync(path.join(root, existingRel), '.a {}', 'utf8');
+  const missingRel = 'does-not-exist.css';
+
+  test('readFile returns contents for a file that exists', () => {
+    assert.equal(readFile(existingRel, root), '.a {}');
+  });
+
+  test('readFile has no existence check — a missing file throws Node\'s own ENOENT', () => {
+    assert.throws(() => readFile(missingRel, root), /ENOENT/);
+  });
+
+  test('requireFile returns contents for a file that exists', () => {
+    assert.equal(requireFile(existingRel, root, 'should not be thrown'), '.a {}');
+  });
+
+  test('requireFile throws the supplied custom message for a missing file, not ENOENT', () => {
+    assert.throws(
+      () => requireFile(missingRel, root, '[test] custom missing-file message'),
+      (err) => err.message === '[test] custom missing-file message',
+    );
+  });
+});
diff --git a/tests/print.spec.js b/tests/print.spec.js
index 04c2b782..11676bcc 100644
--- a/tests/print.spec.js
+++ b/tests/print.spec.js
@@ -1,6 +1,6 @@
 // @ts-check
 import { test, expect } from '@playwright/test';
-import path from 'node:path';
+import { BUNDLE } from './render-helpers.js';
 
 /**
  * Print color preservation smoke test.
@@ -12,7 +12,7 @@ test.describe('Print styles', () => {
   test('<mark> retains non-transparent background in print', async ({ page }) => {
     await page.emulateMedia({ media: 'print' });
     await page.setContent(`<p><mark>Highlighted text</mark></p>`);
-    await page.addStyleTag({ path: path.join(process.cwd(), 'badges', 'slashed.optimal.css') });
+    await page.addStyleTag({ path: BUNDLE });
 
     const bg = await page.locator('mark').evaluate(el =>
       getComputedStyle(el).backgroundColor
@@ -29,7 +29,7 @@ test.describe('Print styles', () => {
       <div class="no-print" id="hidden-el">Should be hidden</div>
       <div id="visible-el">Should be visible</div>
     `);
-    await page.addStyleTag({ path: path.join(process.cwd(), 'badges', 'slashed.optimal.css') });
+    await page.addStyleTag({ path: BUNDLE });
     await page.emulateMedia({ media: 'print' });
 
     const hiddenDisplay = await page.locator('#hidden-el').evaluate(el =>
@@ -47,7 +47,7 @@ test.describe('Print styles', () => {
     await page.setContent(`
       <div class="print-color-exact" style="background: rgb(100, 150, 200);">Coloured</div>
     `);
-    await page.addStyleTag({ path: path.join(process.cwd(), 'badges', 'slashed.optimal.css') });
+    await page.addStyleTag({ path: BUNDLE });
     await page.emulateMedia({ media: 'print' });
 
     const pca = await page.locator('.print-color-exact').evaluate(el =>
diff --git a/tests/render-helpers.js b/tests/render-helpers.js
new file mode 100644
index 00000000..af5b9234
--- /dev/null
+++ b/tests/render-helpers.js
@@ -0,0 +1,40 @@
+// Shared Playwright test-fixture helpers (SL-033). The optimal bundle path
+// and the viewport/doctype/addStyleTag boilerplate were duplicated across
+// a11y-patterns.spec.js, layout.spec.js, macros.spec.js, states-full.spec.js,
+// and typography.spec.js with near-identical setup() functions. The three
+// real differences between them (viewport size, whether <body> gets
+// style="margin:0", and whether transitions are disabled) are now the
+// options renderWithBundle() takes — see each call site for its values.
+//
+// container-queries.spec.js's setupInContainer() wraps content in a sized
+// container div and pins font-size for @container em thresholds; that shape
+// is genuinely different from the flat case here, so it keeps its own local
+// function, but imports BUNDLE from here instead of redefining it.
+//
+// layers.spec.js and print.spec.js inline page.setContent per-test (each
+// test stages different competing rules in its own <style> block) — only
+// their repeated BUNDLE path.join() is shared here.
+import path from 'node:path';
+
+export const BUNDLE = path.join(process.cwd(), 'badges', 'slashed.optimal.css');
+
+export const NO_TRANSITIONS_STYLE =
+  '*, *::before, *::after { transition: none !important; animation-duration: 0s !important; }';
+
+/**
+ * Load the optimal bundle and set page content inside a minimal
+ * <!doctype html><html><body> wrapper.
+ * @param {import('@playwright/test').Page} page
+ * @param {string} html
+ * @param {{ width?: number, height?: number, bodyMargin?: string | null, extraStyle?: string, bundle?: string }} [options]
+ */
+export async function renderWithBundle(page, html, options = {}) {
+  const { width = 1200, height = 900, bodyMargin = '0', extraStyle, bundle = BUNDLE } = options;
+  await page.setViewportSize({ width, height });
+  const bodyAttr = bodyMargin != null ? ` style="margin:${bodyMargin}"` : '';
+  await page.setContent(`<!doctype html><html><body${bodyAttr}>${html}</body></html>`);
+  await page.addStyleTag({ path: bundle });
+  if (extraStyle) {
+    await page.addStyleTag({ content: extraStyle });
+  }
+}
diff --git a/tests/states-full.spec.js b/tests/states-full.spec.js
index 7eafaed1..2f54f57b 100644
--- a/tests/states-full.spec.js
+++ b/tests/states-full.spec.js
@@ -1,16 +1,11 @@
 // @ts-check
 // Full coverage of every .is-* class in core/states.css.
 import { test, expect } from '@playwright/test';
-import path from 'node:path';
-
-const BUNDLE = path.join(process.cwd(), 'badges', 'slashed.optimal.css');
+import { renderWithBundle, NO_TRANSITIONS_STYLE } from './render-helpers.js';
 
 async function setup(page, html) {
-  await page.setViewportSize({ width: 800, height: 600 });
-  await page.setContent(`<!doctype html><html><body style="margin:0">${html}</body></html>`);
-  await page.addStyleTag({ path: BUNDLE });
   // Disable transitions so computed property reads are stable (no mid-animation values).
-  await page.addStyleTag({ content: '*, *::before, *::after { transition: none !important; animation-duration: 0s !important; }' });
+  await renderWithBundle(page, html, { width: 800, height: 600, extraStyle: NO_TRANSITIONS_STYLE });
 }
 
 // ── Visibility ──────────────────────────────────────────────────
diff --git a/tests/tier1-p10-contrast.test.js b/tests/tier1-p10-contrast.test.js
index 55afc269..ce3dc561 100644
--- a/tests/tier1-p10-contrast.test.js
+++ b/tests/tier1-p10-contrast.test.js
@@ -4,6 +4,9 @@
  * Verifies the mathematical invariant: dark text on a light background
  * always meets 4.5:1 across the ranges used by the framework's defaults.
  *
+ * The P2/P7/P8/P10 numbering gaps (no P1, P3-P6, P9 test files) are
+ * explained in tests/README.md — not dead history, don't renumber.
+ *
  * Run: node --test tests/tier1-p10-contrast.test.js
  */
 import { test, describe } from 'node:test';
diff --git a/tests/tier1-p2-coverage.test.js b/tests/tier1-p2-coverage.test.js
index 7eb61606..7754227f 100644
--- a/tests/tier1-p2-coverage.test.js
+++ b/tests/tier1-p2-coverage.test.js
@@ -2,6 +2,9 @@
  * Property 2: tokens.css uses @supports gating — no bare light-dark() or
  *             oklch(from…)/color-mix() declarations outside a @supports block.
  *
+ * The P2/P7/P8/P10 numbering gaps (no P1, P3-P6, P9 test files) are
+ * explained in tests/README.md — not dead history, don't renumber.
+ *
  * Run: node --test tests/tier1-p2-coverage.test.js
  */
 import { test, describe } from 'node:test';
diff --git a/tests/tier1-p7-oldengine.test.js b/tests/tier1-p7-oldengine.test.js
index 34d6ac67..94320b28 100644
--- a/tests/tier1-p7-oldengine.test.js
+++ b/tests/tier1-p7-oldengine.test.js
@@ -6,6 +6,9 @@
  * checks the same invariant at source level). P7 verifies the invariant
  * holds in the final built artifact after bundling and minification.
  *
+ * The P2/P7/P8/P10 numbering gaps (no P1, P3-P6, P9 test files) are
+ * explained in tests/README.md — not dead history, don't renumber.
+ *
  * Run: node --test tests/tier1-p7-oldengine.test.js
  */
 import { test, describe } from 'node:test';
diff --git a/tests/tier1-p8-modern.spec.js b/tests/tier1-p8-modern.spec.js
index ee0c1d39..705dd90e 100644
--- a/tests/tier1-p8-modern.spec.js
+++ b/tests/tier1-p8-modern.spec.js
@@ -6,6 +6,9 @@
  *             This proves that adding core/tokens.color-fallbacks.css before
  *             core/tokens.css did NOT change any resolved value on modern browsers.
  *
+ * The P2/P7/P8/P10 numbering gaps (no P1, P3-P6, P9 test files) are
+ * explained in tests/README.md — not dead history, don't renumber.
+ *
  * Regenerate baseline: BASELINE_CAPTURE=1 npx playwright test tests/tier1-p8-modern.spec.js --project=chromium
  * Run: npx playwright test tests/tier1-p8-modern.spec.js --project=chromium
  */
diff --git a/tests/typography.spec.js b/tests/typography.spec.js
index 8ea90c1b..4feb6792 100644
--- a/tests/typography.spec.js
+++ b/tests/typography.spec.js
@@ -5,14 +5,12 @@
 import { test, expect } from '@playwright/test';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { renderWithBundle } from './render-helpers.js';
 
 const FIXTURE = pathToFileURL(path.join(import.meta.dirname, 'fixture.html')).href;
-const BUNDLE  = path.join(process.cwd(), 'badges', 'slashed.optimal.css');
 
 async function setup(page, html) {
-  await page.setViewportSize({ width: 1200, height: 900 });
-  await page.setContent(`<!doctype html><html><body style="margin:0">${html}</body></html>`);
-  await page.addStyleTag({ path: BUNDLE });
+  await renderWithBundle(page, html, { width: 1200, height: 900 });
 }
 
 // ── Heading size scale ───────────────────────────────────────────