From 744a9ebbf631d09a33b064cdcc0d6c6db5d72435 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 2 Jul 2026 03:47:14 +0000
Subject: [PATCH 01/20] refactor(configurator): de-obfuscate codec.ts internal
 names (SL-016)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Rename cryptic 1-2 letter symbols in the persistence/encode/CSS-export
module (Wa, Ra, za, Ha, fa, Ga, qa...) to their existing readable
export-alias names, and update the four call sites that imported the
obfuscated names directly (persistence.ts, App.svelte,
PreviewPanel.svelte, ExportPanel.svelte). No behavior change — public
export surface (encode/decode/generateCSS/etc.) is unchanged, verified
by tsc, svelte-check, and the full codec/css/share unit test suite.
---
 configurator/src/App.svelte                   |   4 +-
 .../src/components/panels/ExportPanel.svelte  |   6 +-
 .../src/components/shell/PreviewPanel.svelte  |   8 +-
 configurator/src/lib/codec.ts                 | 284 +++++++++---------
 configurator/src/lib/persistence.ts           |   8 +-
 5 files changed, 150 insertions(+), 160 deletions(-)

diff --git a/configurator/src/App.svelte b/configurator/src/App.svelte
index 6b5d3b7d..3c960c70 100644
--- a/configurator/src/App.svelte
+++ b/configurator/src/App.svelte
@@ -7,7 +7,7 @@
   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';
@@ -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/panels/ExportPanel.svelte b/configurator/src/components/panels/ExportPanel.svelte
index 46d8d1dd..ac1a6d39 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 { 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/shell/PreviewPanel.svelte b/configurator/src/components/shell/PreviewPanel.svelte
index 0539f5aa..06d61482 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 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; }"
@@ -494,7 +494,7 @@ ${BODIES[template]}
 
     const styleEl = doc.getElementById("slashed-overrides");
     if (styleEl) {
-      styleEl.textContent = fa(withDerivedOverrides(_ov), { mode: "root", banner: false });
+      styleEl.textContent = generateCSS(withDerivedOverrides(_ov), { mode: "root", banner: false });
     }
 
     injectFontsIntoDoc(doc, _ov);
@@ -517,7 +517,7 @@ ${BODIES[template]}
     const _lightCount = splitLightLoadCount;
     const _darkCount = splitDarkLoadCount;
     const _lock = lumlockerPreview.value;
-    const css = fa(withDerivedOverrides(_ov), { mode: "root", banner: false });
+    const css = generateCSS(withDerivedOverrides(_ov), { mode: "root", banner: false });
 
     const applyLock = (doc: Document) => {
       if (_lock) doc.documentElement.setAttribute("data-lumlocker", "");
diff --git a/configurator/src/lib/codec.ts b/configurator/src/lib/codec.ts
index 02bfc29e..ad1861f9 100644
--- a/configurator/src/lib/codec.ts
+++ b/configurator/src/lib/codec.ts
@@ -8,97 +8,96 @@ import tokensData from "../data/token-registry.generated.json";
 
 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;
+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: any): 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: any): 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: any = 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);
@@ -109,13 +108,13 @@ export function Ha(e: Record<string, string>, t: any = Wa): string {
   const out = new Uint8Array(1 + compressed.length);
   out[0] = 2;
   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: any = tokensData, options: any = {}): 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) {
@@ -129,54 +128,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 +183,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 +238,45 @@ 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];
+export function readShareFromHash(hashOrParam: string, options: any = {}): Record<string, string> {
+  const knownTokensSet = new Set(tokensData.tokens.map((tok: any) => tok.name));
+  const isKnown = options.isKnown ?? ((name: string) => knownTokensSet.has(name));
+  let trimmed = String(hashOrParam ?? "").trim();
+  const match = trimmed.match(/[#&]?c=([^&]+)/);
+  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 ? `c=${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: any = {}): Record<string, string> {
+  const value = String(hash ?? "");
+  return value.includes("c=") ? 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..7b365f8a 100644
--- a/configurator/src/lib/persistence.ts
+++ b/configurator/src/lib/persistence.ts
@@ -13,7 +13,7 @@
  * 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";
 
 const LS_KEY = "slashed-studio/overrides/v2";
 
@@ -212,7 +212,7 @@ 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) {
@@ -235,7 +235,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 +259,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;

From c0505f90247e071b7bbfe4fe6d1677a21451ed6b Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 2 Jul 2026 03:53:46 +0000
Subject: [PATCH 02/20] fix(configurator): surface save failures instead of
 silently reverting (SL-018)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add an 'error' state to the saveState union so a failed REST/network
save is distinguishable from "never attempted" — previously handleSave's
catch block reset straight back to 'idle'. StudioHeader now renders a
red "Save failed" state with a retry-hint tooltip; a further edit clears
it back to 'idle' the same way 'saved' already did.

Verified live: booted the configurator against a window.slashedApp REST
target that 404s, confirmed the button renders "Save failed" after a
failed save and clears to "Save" on the next edit. Also tsc,
svelte-check, and the full unit suite pass unchanged.
---
 configurator/src/App.svelte                         |  6 +++---
 .../src/components/shell/StudioHeader.svelte        | 13 +++++++++----
 2 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/configurator/src/App.svelte b/configurator/src/App.svelte
index 3c960c70..fb436fa0 100644
--- a/configurator/src/App.svelte
+++ b/configurator/src/App.svelte
@@ -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';
     }
   }
 
diff --git a/configurator/src/components/shell/StudioHeader.svelte b/configurator/src/components/shell/StudioHeader.svelte
index 58b70ac3..cf18f2cb 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

From eb88ede8ca36799def67cd1fc5ffe3ecf7de4754 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 2 Jul 2026 03:57:20 +0000
Subject: [PATCH 03/20] test(configurator): start closing the interactive-layer
 coverage gap (SL-023)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The audit's top finding: persistence.ts (save/load/error paths,
WP-vs-standalone branching) and every panel's token-editing interaction
had zero test coverage — only pure codec/data logic was tested.

Add tests/persistence.test.js: loadInitialOverrides and saveOverrides
across both the standalone (localStorage + URL hash) and WP-embedded
(REST) branches, including the malformed-localStorage edge case from
SL-019 — pinned to today's real (unguarded) behavior since SL-019's fix
itself is out of scope here.

Add tests-components/token-editing.test.js: SliderRow and TokenRow,
covering bind (initial render), override-set (interacting calls
onChange/onSet), and reset (reset affordance calls onReset), plus
SliderRow's raw-CSS-value editing mode.

89 unit + component tests pass; tsc/svelte-check remain clean.
---
 .../tests-components/token-editing.test.js    | 150 ++++++++++++++++
 configurator/tests/persistence.test.js        | 169 ++++++++++++++++++
 2 files changed, 319 insertions(+)
 create mode 100644 configurator/tests-components/token-editing.test.js
 create mode 100644 configurator/tests/persistence.test.js

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..cfe12c97
--- /dev/null
+++ b/configurator/tests/persistence.test.js
@@ -0,0 +1,169 @@
+/**
+ * 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 case flagged by SL-019 (not fixed in this
+ * pass — the assertions below document the current, unguarded behavior).
+ */
+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 (not fixed here): loadInitialOverrides' standalone/localStorage path
+  // trusts JSON.parse's result as Record<string,string> with no shape guard,
+  // unlike savedThemes.ts's equivalent read path. This test pins today's real
+  // (unguarded) behavior so a future SL-019 fix has a test to update.
+  test('SL-019: currently returns non-object JSON as-is instead of {} (documented gap)', () => {
+    localStorage.setItem(LS_KEY, JSON.stringify(['not', 'an', 'object']));
+    expect(loadInitialOverrides()).toEqual(['not', 'an', 'object']);
+  });
+});
+
+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);
+  });
+});

From 6004c90be82b9636350573ab436ce959dd23b6f9 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 2 Jul 2026 04:09:08 +0000
Subject: [PATCH 04/20] refactor(scripts): dedupe generator parsing helpers
 into scripts/lib/parse.js (SL-007)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

stripComments/maskComments, readValue, and readFile were each
reimplemented 3-4 times across audit.js, check-macro-catalog.js,
gen-token-index.js, gen-api-index.js, gen-token-reference.js, and
version-sync.js, with no shared module despite gen-api-index.js's header
claiming a "canonical parsing contract."

Extract byte-identical stripComments/stripStrings/readValue into
scripts/lib/parse.js. gen-api-index.js's maskComments/maskStrings are
NOT the same contract (they blank comment/string bodies in place to
preserve character offsets for banner lookups, rather than removing
them) — kept as distinct exports per the audit's explicit warning not
to merge them. readFile is split into a bare readFile(rel, root) (no
existence check, matching version-sync.js's original behavior exactly)
and requireFile(rel, root, message) for the four call sites that throw
a custom "missing file" error; each site's original error message text
is preserved unchanged.

No behavior change: npm run docs output (docs/api-index.json,
docs/token-index.json, docs/tokens.md, docs/registry.json,
token-registry.json) is byte-identical before/after, verified by diffing
a pre-refactor snapshot against a post-refactor regeneration. check:macros,
check:registry, check:llm-guide, audit:check, check:version, and the
root node --test unit suite all pass.

Also:
- SL-030: annotate docs/llm-guide.md's optional/utilities.css entry as
  staged/commented-out, matching the file's own header and README's
  existing wording — the guide previously listed it as if live.
- SL-029: reorder README's a-la-carte <link> example to match
  core/layers.css's real @layer order (themes.css was listed right
  after base.css; the real order puts it after states.css), and note
  that @layer order, not <link> order, controls the cascade.
---
 README.md                      |  6 ++-
 docs/llm-guide.md              |  2 +-
 scripts/audit.js               | 16 +-----
 scripts/check-macro-catalog.js |  9 +---
 scripts/gen-api-index.js       | 55 +++-----------------
 scripts/gen-token-index.js     | 26 +---------
 scripts/gen-token-reference.js | 21 +-------
 scripts/lib/parse.js           | 95 ++++++++++++++++++++++++++++++++++
 scripts/version-sync.js        |  3 +-
 9 files changed, 115 insertions(+), 118 deletions(-)
 create mode 100644 scripts/lib/parse.js

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/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/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..9efa3f84 100644
--- a/scripts/gen-api-index.js
+++ b/scripts/gen-api-index.js
@@ -32,6 +32,7 @@ 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 './lib/parse.js';
 
 const ROOT = path.resolve(import.meta.dirname, '..');
 const OUT    = path.join(ROOT, 'docs', 'api-index.json');
@@ -114,37 +115,11 @@ const FILE_META = {
 // 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.
 
-/**
- * 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');
+  return requireFile(rel, ROOT, `[docs:api] Missing source file: ${rel}`);
 }
 
 // ── Section-banner parsing ──────────────────────────────────────────────────
@@ -312,26 +287,8 @@ function truncate(str, max = 280) {
   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();
-}
+// 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").
diff --git a/scripts/gen-token-index.js b/scripts/gen-token-index.js
index 3a98ed76..d7018e19 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).
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/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) {

From 12fa7fbd2b0511a3a1b41be4e28f197f78e63111 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 2 Jul 2026 04:10:46 +0000
Subject: [PATCH 05/20] test: move selector-coverage check off Playwright onto
 node:test (SL-027)

tests/coverage.spec.js never touched a browser (pure fs/regex work
comparing core/*.css selectors against docs/demo.html) but was
Playwright-discovered, so it ran redundantly 3x across
chromium/firefox/webkit. Rename to coverage.test.js, port from
@playwright/test's test/expect to node:test/node:assert to match the
tier1-p*.test.js convention, and wire it into pretest/test:unit.
Confirmed Playwright's test list no longer includes it and node --test
runs it once. Update CONTRIBUTING.md's reference to the new filename.
---
 CONTRIBUTING.md                              |  2 +-
 package.json                                 |  4 ++--
 tests/{coverage.spec.js => coverage.test.js} | 24 ++++++++++++--------
 3 files changed, 17 insertions(+), 13 deletions(-)
 rename tests/{coverage.spec.js => coverage.test.js} (85%)

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/package.json b/package.json
index 663fa835..ed5dc081 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",
     "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",
     "test:install": "playwright install --with-deps chromium firefox webkit",
     "release": "release-it",
     "release:minor": "release-it --increment minor",
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, []);
   });
 });

From c839ae99c42962552c6066d9e8bd16d83a1bf2ed Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 2 Jul 2026 04:12:32 +0000
Subject: [PATCH 06/20] chore(configurator): remove unused motion dependency
 (SL-021)

motion (^12.23.24) had zero imports anywhere in configurator/src.
Verified via grep before removing. npm install updates the lockfile;
version-sync/check:version confirm nothing drifted. tsc, svelte-check,
unit + component tests, and vite build all pass unchanged.
---
 configurator/package-lock.json | 75 ++--------------------------------
 configurator/package.json      |  3 +-
 2 files changed, 5 insertions(+), 73 deletions(-)

diff --git a/configurator/package-lock.json b/configurator/package-lock.json
index 74b5030a..bfe4c941 100644
--- a/configurator/package-lock.json
+++ b/configurator/package-lock.json
@@ -9,8 +9,7 @@
       "version": "0.6.33",
       "dependencies": {
         "fflate": "^0.8.3",
-        "lucide-svelte": "^0.468.0",
-        "motion": "^12.23.24"
+        "lucide-svelte": "^0.468.0"
       },
       "devDependencies": {
         "@playwright/test": "^1.60.0",
@@ -2165,33 +2164,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",
@@ -2819,47 +2791,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 +3360,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..34500122 100644
--- a/configurator/package.json
+++ b/configurator/package.json
@@ -22,8 +22,7 @@
   },
   "dependencies": {
     "fflate": "^0.8.3",
-    "lucide-svelte": "^0.468.0",
-    "motion": "^12.23.24"
+    "lucide-svelte": "^0.468.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.60.0",

From 902a1612743c942871e5402f340e69d3c558a676 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 2 Jul 2026 06:04:51 +0000
Subject: [PATCH 07/20] docs(core): clean up core css comments (SL-001..005)

Comment-only changes across core/*.css, no selector/property/value diffs
(verified: npm run build's badge-optimal.json is byte-identical).

- SL-001: cross-link the duplicated dark/light OKLCH clamp() derivation
  formula between core/tokens.css:364-373 (inside light-dark()) and
  core/themes.css's SECTION-LEVEL THEMING block (flat re-declaration for
  [data-theme] overrides on non-:root elements). Left unmerged per the
  audit's open question - themes.css genuinely needs flat values outside
  light-dark(), so this may be intentional; deferred to the maintainer.
- SL-002: doc-comment above .sf-clickable-parent warning against applying
  it to large (100+ node) grids, since its selectors combine multiple
  :has() branches.
- SL-003: strengthen --sf-is-dark's "internal, don't set directly"
  comment to be unmistakable against the immediately-following
  --sf-is-active/-current/-pressed/-open block's "public hooks" comment -
  same --sf-is-* naming pattern, opposite contract. Grepped every
  var(--sf-is-dark) read site first to confirm nothing external sets it.
- SL-004: add short section labels to core/layout.css's 11 previously
  unlabeled blank-line section dividers, matching sibling files' style.
- SL-005: consolidate the "var() not allowed inside @container" note
  (previously stated at only 1 of 4 @container sites) into one comment
  near the top of core/layout.css.

Adding SL-004's /* Section */ label directly above .sf-section shadowed
gen-api-index.js's fallback-to-previous-description logic for the
uncommented .sf-section--guttered sitting in the same section (its
description regenerated as the literal string "Section" instead of its
existing curated text). Fixed by promoting that description into
docs/token-annotations.json's classes overlay - the durable, intended
mechanism for exactly this - rather than removing the section label.

Verified: lint:css, build, test:unit, check:llm-guide, audit:check all
pass; docs/api-index.json, docs/api-index.md, and the configurator's
generated data files are byte-identical to base after the fix.
---
 core/accessibility.css      |  5 +++++
 core/layout.css             | 19 ++++++++++++++++---
 core/themes.css             |  6 +++++-
 core/tokens.css             | 22 ++++++++++++++++------
 docs/token-annotations.json |  1 +
 5 files changed, 43 insertions(+), 10 deletions(-)

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..0cddf3dd 100644
--- a/core/themes.css
+++ b/core/themes.css
@@ -58,7 +58,11 @@
 
   /* 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 light-dark() block (core/tokens.css:364-373) — 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/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>.",

From 161f6266badfdab788c6ba1e24e83652b3489895 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 2 Jul 2026 06:12:25 +0000
Subject: [PATCH 08/20] fix(configurator,scripts): address CodeRabbit review on
 PR 474

- codec.ts: encode/decode now reference CODEC_VERSION instead of a
  hardcoded 2, and readShareFromHash/buildShareUrl/readShareFromHashIfPresent
  reference SHARE_PARAM instead of a hardcoded "c=" - previously the
  exported constants existed but every call site hardcoded the literal,
  so bumping either constant would have silently desynced encode/decode
  or share-link parsing. Moved both consts above their first use.
- scripts/lib/parse.js: add tests/parse-lib.test.js covering
  stripComments/maskComments offset preservation, readValue's
  paren-depth handling (including nested clamp()/oklch() shapes), and
  the readFile-vs-requireFile missing-file divergence - the shared
  surface backing 6 generator scripts previously had no direct test,
  only the "docs output is byte-identical" verification a manual diff
  could miss.

Verified: tsc, svelte-check, configurator unit suite (72 tests) unchanged,
root unit suite now 44 tests (was 31), lint:css/build/check:llm-guide/
check:version all pass.
---
 configurator/src/lib/codec.ts |  20 +++---
 package.json                  |   4 +-
 tests/parse-lib.test.js       | 115 ++++++++++++++++++++++++++++++++++
 3 files changed, 128 insertions(+), 11 deletions(-)
 create mode 100644 tests/parse-lib.test.js

diff --git a/configurator/src/lib/codec.ts b/configurator/src/lib/codec.ts
index ad1861f9..f18f048f 100644
--- a/configurator/src/lib/codec.ts
+++ b/configurator/src/lib/codec.ts
@@ -10,6 +10,9 @@ declare const __SLASHED_VERSION__: string;
 
 const frameworkVersion: string = typeof __SLASHED_VERSION__ !== "undefined" ? __SLASHED_VERSION__ : "0.0.0";
 
+export const CODEC_VERSION = 2;
+export const SHARE_PARAM = "c";
+
 const MAX_VALUE_BYTES = 65535;
 const MAX_ID = 65535;
 const textEncoder = new TextEncoder();
@@ -106,7 +109,7 @@ export function encode(overrides: Record<string, string>, registry: any = tokens
     return "";
   }
   const out = new Uint8Array(1 + compressed.length);
-  out[0] = 2;
+  out[0] = CODEC_VERSION;
   out.set(compressed, 1);
   return bytesToBase64Url(out);
 }
@@ -117,8 +120,8 @@ export function decode(code: string, registry: any = tokensData, options: any =
   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 {};
   }
 
@@ -253,11 +256,13 @@ export function encodeOverrides(overrides: Record<string, string>): string {
   return encode(overrides, tokensData);
 }
 
+const SHARE_PARAM_RE = new RegExp(`[#&]?${SHARE_PARAM}=([^&]+)`);
+
 export function readShareFromHash(hashOrParam: string, options: any = {}): Record<string, string> {
   const knownTokensSet = new Set(tokensData.tokens.map((tok: any) => tok.name));
   const isKnown = options.isKnown ?? ((name: string) => knownTokensSet.has(name));
   let trimmed = String(hashOrParam ?? "").trim();
-  const match = trimmed.match(/[#&]?c=([^&]+)/);
+  const match = trimmed.match(SHARE_PARAM_RE);
   if (match) {
     trimmed = match[1];
   }
@@ -269,14 +274,11 @@ export function buildShareUrl(overrides: Record<string, string>, baseUrlOverride
   const baseUrl = baseUrlOverride ?? fallbackUrl;
   const url = new URL(baseUrl);
   const code = encodeOverrides(overrides);
-  url.hash = code ? `c=${code}` : "";
+  url.hash = code ? `${SHARE_PARAM}=${code}` : "";
   return url.toString();
 }
 
 export function readShareFromHashIfPresent(hash: string, options: any = {}): Record<string, string> {
   const value = String(hash ?? "");
-  return value.includes("c=") ? readShareFromHash(value, options) : {};
+  return value.includes(`${SHARE_PARAM}=`) ? readShareFromHash(value, options) : {};
 }
-
-export const CODEC_VERSION = 2;
-export const SHARE_PARAM = "c";
diff --git a/package.json b/package.json
index ed5dc081..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 tests/coverage.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 tests/coverage.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/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',
+    );
+  });
+});

From c6cdb3d79322f693a73791ba797c4c40d5406348 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 2 Jul 2026 06:13:22 +0000
Subject: [PATCH 09/20] docs(core): replace hardcoded line-number citation in
 SL-001 comment

core/themes.css's cross-link to core/tokens.css cited a specific line
range (364-373) that will drift as either file is edited independently.
Replaced with a stable text anchor (the section's own comment text) to
search for instead, matching how the tokens.css side already referenced
themes.css by section name (SECTION-LEVEL THEMING) rather than by line
number. Caught by Qodo's review on PR 475.
---
 badges/badge-optimal.json | 7 -------
 core/themes.css           | 5 +++--
 2 files changed, 3 insertions(+), 9 deletions(-)
 delete mode 100644 badges/badge-optimal.json

diff --git a/badges/badge-optimal.json b/badges/badge-optimal.json
deleted file mode 100644
index 1536a71b..00000000
--- a/badges/badge-optimal.json
+++ /dev/null
@@ -1,7 +0,0 @@
-{
-  "schemaVersion": 1,
-  "label": "optimal",
-  "message": "17.5 kB gzip",
-  "color": "brightgreen",
-  "namedLogo": "css3"
-}
diff --git a/core/themes.css b/core/themes.css
index 0cddf3dd..8f501eba 100644
--- a/core/themes.css
+++ b/core/themes.css
@@ -60,8 +60,9 @@
   /* light-dark() bakes at :root declaration time; re-declarations on [data-theme]
      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 light-dark() block (core/tokens.css:364-373) — duplicated
-     here, not shared, because this file needs flat values outside light-dark().
+     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)) {
 

From 0b402677e240bb9f3f876dc13100d6cf5d8a2250 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 2 Jul 2026 06:13:58 +0000
Subject: [PATCH 10/20] chore: restore badges/badge-optimal.json accidentally
 deleted by prior commit

A stray 'rm -rf badges' before rebuilding removed the tracked
badge-optimal.json along with the gitignored bundle files, and the
subsequent commit picked up the deletion. Restoring it unchanged - no
content difference, it was regenerated identically by npm run build.
---
 badges/badge-optimal.json | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 badges/badge-optimal.json

diff --git a/badges/badge-optimal.json b/badges/badge-optimal.json
new file mode 100644
index 00000000..1536a71b
--- /dev/null
+++ b/badges/badge-optimal.json
@@ -0,0 +1,7 @@
+{
+  "schemaVersion": 1,
+  "label": "optimal",
+  "message": "17.5 kB gzip",
+  "color": "brightgreen",
+  "namedLogo": "css3"
+}

From 5f1c4aefe97d4f1b337ea1f99269f0c009b52fce Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 2 Jul 2026 06:21:02 +0000
Subject: [PATCH 11/20] docs(tests): docs and test hygiene remainder (SL-014,
 028, 031, 032, 033)

- SL-014: add the 12 previously-undocumented npm scripts to CLAUDE.md's
  Key scripts table, prioritizing the CI-gate scripts (check:macros,
  check:registry, audit:check, lint:css).
- SL-028: add tests/README.md documenting the *.spec.js (Playwright) vs
  *.test.js (node:test) convention, referencing SL-027 as the motivating
  example of what happens when it's unenforced.
- SL-031: retitle docs/migration.md's stale "0.6.25 -> next" header to
  "0.6.25 -> 0.6.26" (traced via CHANGELOG.md to the release that
  actually shipped the base-alias removal it documents), matching the
  versioned-header style used elsewhere in the same file.
- SL-032: document the tier1-p2/p7/p8/p10 numbering gaps (no P1, P3-P6,
  P9 files) in tests/README.md plus a one-line pointer in each of the 4
  files - they trace back to the tier-1-color-fallback feature's
  original property enumeration; not renumbered.
- SL-033: extract tests/render-helpers.js (BUNDLE path + renderWithBundle
  helper) after diffing all 8 page.setContent call sites individually -
  5 files (a11y-patterns, layout, macros, states-full, typography) had
  near-identical setup() functions differing only in viewport/margin/
  extra-stylesheet, now parameterized through one shared function;
  layers.spec.js/print.spec.js/container-queries.spec.js only shared the
  BUNDLE path constant (their setContent bodies are genuinely per-test or
  differently-shaped) and were left otherwise untouched, per the plan's
  explicit caution not to force uniformity where the originals differ.

Verified with real browser execution (not just --list): all 5 refactored
setup()-using spec files plus layers/print/container-queries ran under a
temporary local executablePath override (this sandbox's pinned Playwright
browser build isn't pre-installed) - 150/150 tests pass unchanged.
lint:css, build, test:unit (31/31), check:llm-guide, check:version all
pass; the temporary config was not committed.
---
 CLAUDE.md                        | 14 ++++++++++-
 docs/migration.md                |  2 +-
 tests/README.md                  | 28 ++++++++++++++++++++++
 tests/a11y-patterns.spec.js      |  9 ++-----
 tests/container-queries.spec.js  |  4 +---
 tests/layers.spec.js             | 14 +++++------
 tests/layout.spec.js             |  8 ++-----
 tests/macros.spec.js             | 10 ++++----
 tests/print.spec.js              |  8 +++----
 tests/render-helpers.js          | 40 ++++++++++++++++++++++++++++++++
 tests/states-full.spec.js        |  9 ++-----
 tests/tier1-p10-contrast.test.js |  3 +++
 tests/tier1-p2-coverage.test.js  |  3 +++
 tests/tier1-p7-oldengine.test.js |  3 +++
 tests/tier1-p8-modern.spec.js    |  3 +++
 tests/typography.spec.js         |  6 ++---
 16 files changed, 118 insertions(+), 46 deletions(-)
 create mode 100644 tests/README.md
 create mode 100644 tests/render-helpers.js

diff --git a/CLAUDE.md b/CLAUDE.md
index 1e6729f9..925472aa 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` (CI gate) |
+| `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 |
 | `npm test` | Full suite: build → unit → Playwright e2e |
 
 ## Release process
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/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/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/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 ───────────────────────────────────────────

From c19b0140b1f9d0c4e595d7843d64e67b599cb42a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 2 Jul 2026 06:29:54 +0000
Subject: [PATCH 12/20] refactor(scripts): build script hardening (SL-006, 008,
 009, 010, 011, 012, 013)

- SL-006 (highest-risk item in this wave): split gen-api-index.js's 829
  lines along its existing section-comment boundaries into
  scripts/lib/api-index/extract.js (annotations, previous-index reading,
  banner/comment parsing, bundle mapping, token/class extraction and
  merging) and render.js (the Markdown companion). gen-api-index.js is
  now just path constants, the write-time regression guard, and
  orchestration in main(). One small behavior-neutral cleanup along the
  way: replaced the hoisted-closure `bundlesFor_` mutable-variable hack
  with a normal parameter, since extractClassesFromFile now takes
  bundlesFor directly. No logic changed otherwise - verified by diffing
  docs/api-index.json, docs/api-index.md, docs/token-index.json, and
  token-registry.json byte-for-byte against a pre-refactor snapshot
  (empty diff on all four, both from a single `node
  scripts/gen-api-index.js` run and from the full `npm run docs`
  pipeline).
- SL-010 + SL-012: add regression guards before the three
  fs.writeFileSync sites that downstream tooling trusts
  (gen-api-index.js, gen-token-registry.js, gen-token-index.js) - a
  >20% entry-count drop (or, for the append-only token-registry.json,
  any drop at all) now throws instead of silently writing a truncated
  artifact. No new dependency; hand-rolled against each file's existing
  "read the previous version" logic.
- SL-008/009/011/013: new scripts/README.md documenting the
  intentionally-unenforced error-handling convention, the hand-rolled
  CLI flag parsing, the 3 environment variables the scripts read
  (SLASHED_ROOT, GITHUB_REF/GITHUB_REF_NAME, GITHUB_BASE_REF), and the
  execSync(shell:true) pattern in check-artifacts.js/changelog-release.js
  (config-sourced today, not attacker input, but worth flagging for
  future artifacts.json entries).

Verified: npm run docs before/after diff empty on every generated
artifact; check:macros, check:registry, check:llm-guide, audit:check,
lint:css, build, test:unit (44/44) all pass.
---
 scripts/README.md                |  45 ++
 scripts/gen-api-index.js         | 708 ++-----------------------------
 scripts/gen-token-index.js       |  30 +-
 scripts/gen-token-registry.js    |  13 +
 scripts/lib/api-index/extract.js | 602 ++++++++++++++++++++++++++
 scripts/lib/api-index/render.js  |  83 ++++
 6 files changed, 798 insertions(+), 683 deletions(-)
 create mode 100644 scripts/README.md
 create mode 100644 scripts/lib/api-index/extract.js
 create mode 100644 scripts/lib/api-index/render.js

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/gen-api-index.js b/scripts/gen-api-index.js
index 9efa3f84..3ee18c1d 100644
--- a/scripts/gen-api-index.js
+++ b/scripts/gen-api-index.js
@@ -26,703 +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 { maskComments, maskStrings, readValue, requireFile } from './lib/parse.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.
-// maskComments/maskStrings (offset-preserving) come from scripts/lib/parse.js —
-// NOT the same contract as that module's stripComments/stripStrings.
-
-function readFile(rel) {
-  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.
-
-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*$/, '') + '…';
-}
-
-// 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
- */
-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))
@@ -800,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 d7018e19..341368cf 100644
--- a/scripts/gen-token-index.js
+++ b/scripts/gen-token-index.js
@@ -110,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-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;
+}

From d4768000f16e983fd06093492b47b2c30b4072a5 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 2 Jul 2026 06:31:09 +0000
Subject: [PATCH 13/20] docs: fix two CLAUDE.md inaccuracies flagged by Qodo
 review on PR 476
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- check:macros was labeled a CI gate; verified against
  .github/workflows/ci.yml directly and it isn't wired into any job
  (the audit's own SL-014 finding had asserted it was — that
  assumption was wrong). Corrected the label rather than adding it to
  CI, since wiring in a new gate is a separate decision with its own
  blast radius.
- test:unit's new row didn't mention it needs badges/ built first;
  hit this myself moments earlier while verifying PR3 (5 spurious test
  failures from a stale badges/ dir). CI works around it by downloading
  the badges artifact from the build job before this step; a clean
  local checkout needs npm run build first.
---
 CLAUDE.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 925472aa..788e6efd 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -51,7 +51,7 @@ 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` (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) |
@@ -65,7 +65,7 @@ requires a rebuild+redeploy, not just a file edit.
 | `npm run configurator:sync` | Push `docs/api-index.json` → `configurator/src/data/api-index.generated.json` |
 | `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 |
+| `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

From 62067e2258b539742eedfb9270ce6de78fa755eb Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 2 Jul 2026 06:40:11 +0000
Subject: [PATCH 14/20] refactor(configurator): type codec.ts and its call
 sites, document shared limit constants

SL-017/024: replace `any` at codec.ts's 7 registry/options parameters and
its two consumers (App.svelte, CheatsheetPanel.svelte) with new TokenRegistry,
ApiIndex, SlashedClass and DecodeOptions interfaces in types.ts, so malformed
JSON or option shapes are caught at compile time instead of silently
no-op'ing at runtime.

SL-026: document why MAX_VALUE_BYTES and MAX_ID share the same numeric
value (65535) despite being independent limits, so a future edit doesn't
assume they're the same constant in disguise.
---
 configurator/src/App.svelte                   |  4 +-
 .../components/panels/CheatsheetPanel.svelte  |  7 +--
 configurator/src/lib/codec.ts                 | 20 ++++---
 configurator/src/types.ts                     | 54 +++++++++++++++++++
 4 files changed, 73 insertions(+), 12 deletions(-)

diff --git a/configurator/src/App.svelte b/configurator/src/App.svelte
index fb436fa0..937b0704 100644
--- a/configurator/src/App.svelte
+++ b/configurator/src/App.svelte
@@ -1,7 +1,7 @@
 <script lang="ts">
   import { onMount, untrack } from 'svelte';
   import { SlidersHorizontal, Eye, RotateCcw } from 'lucide-svelte';
-  import type { PreviewTemplate, SlashedToken } from './types';
+  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';
@@ -13,7 +13,7 @@
   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",
diff --git a/configurator/src/components/panels/CheatsheetPanel.svelte b/configurator/src/components/panels/CheatsheetPanel.svelte
index 3b83f4c1..1fe7edbc 100644
--- a/configurator/src/components/panels/CheatsheetPanel.svelte
+++ b/configurator/src/components/panels/CheatsheetPanel.svelte
@@ -6,9 +6,10 @@
   import classesData from '../../data/classes.generated.json';
   import tokensData from '../../data/api-index.generated.json';
   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/lib/codec.ts b/configurator/src/lib/codec.ts
index f18f048f..75118271 100644
--- a/configurator/src/lib/codec.ts
+++ b/configurator/src/lib/codec.ts
@@ -5,6 +5,7 @@
 
 import { deflateSync, inflateSync } from "fflate";
 import tokensData from "../data/token-registry.generated.json";
+import type { TokenRegistry, DecodeOptions } from "../types";
 
 declare const __SLASHED_VERSION__: string;
 
@@ -13,6 +14,11 @@ const frameworkVersion: string = typeof __SLASHED_VERSION__ !== "undefined" ? __
 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();
@@ -24,7 +30,7 @@ function isValidId(id: number): boolean {
   return Number.isInteger(id) && id >= 0 && id <= MAX_ID;
 }
 
-function buildNameToIdMap(registry: any): Map<string, number> {
+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)) {
@@ -34,7 +40,7 @@ function buildNameToIdMap(registry: any): Map<string, number> {
   return nameToId;
 }
 
-function buildIdToNameMap(registry: any): Map<number, string> {
+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)) {
@@ -72,7 +78,7 @@ function base64UrlToBytes(value: string): Uint8Array | null {
   }
 }
 
-export function encode(overrides: Record<string, string>, registry: any = tokensData): string {
+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 }[] = [];
@@ -114,7 +120,7 @@ export function encode(overrides: Record<string, string>, registry: any = tokens
   return bytesToBase64Url(out);
 }
 
-export function decode(code: string, registry: any = tokensData, options: any = {}): Record<string, string> {
+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);
@@ -258,8 +264,8 @@ export function encodeOverrides(overrides: Record<string, string>): string {
 
 const SHARE_PARAM_RE = new RegExp(`[#&]?${SHARE_PARAM}=([^&]+)`);
 
-export function readShareFromHash(hashOrParam: string, options: any = {}): Record<string, string> {
-  const knownTokensSet = new Set(tokensData.tokens.map((tok: any) => tok.name));
+export function readShareFromHash(hashOrParam: string, options: DecodeOptions = {}): 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);
@@ -278,7 +284,7 @@ export function buildShareUrl(overrides: Record<string, string>, baseUrlOverride
   return url.toString();
 }
 
-export function readShareFromHashIfPresent(hash: string, options: any = {}): Record<string, string> {
+export function readShareFromHashIfPresent(hash: string, options: DecodeOptions = {}): Record<string, string> {
   const value = String(hash ?? "");
   return value.includes(`${SHARE_PARAM}=`) ? readShareFromHash(value, options) : {};
 }
diff --git a/configurator/src/types.ts b/configurator/src/types.ts
index 7d18d08c..e82f857f 100644
--- a/configurator/src/types.ts
+++ b/configurator/src/types.ts
@@ -19,6 +19,60 @@ 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() / readShareFromHash() / readShareFromHashIfPresent(). */
+export interface DecodeOptions {
+  sanitize?: (value: string) => string;
+  isKnown?: (tokenName: string) => boolean;
+}
+
 export interface SlashedCategory {
   id: string;
   label: string;

From 2af608fcb23b93630e8e172bb16de3abd150eda8 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 2 Jul 2026 06:47:01 +0000
Subject: [PATCH 15/20] fix(configurator): stop advertising an ignored sanitize
 option on share-link readers

readShareFromHash()/readShareFromHashIfPresent() were typed to accept
DecodeOptions.sanitize but always forced sanitizeValue internally (a
CSS-injection safeguard that must not be caller-overridable) and silently
discarded any options.sanitize passed in. Narrow their accepted options to
a new ShareOptions type (isKnown only) so the signature matches actual
behavior instead of advertising a knob that does nothing.
---
 configurator/src/lib/codec.ts |  6 +++---
 configurator/src/types.ts     | 10 +++++++++-
 2 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/configurator/src/lib/codec.ts b/configurator/src/lib/codec.ts
index 75118271..7b08c06e 100644
--- a/configurator/src/lib/codec.ts
+++ b/configurator/src/lib/codec.ts
@@ -5,7 +5,7 @@
 
 import { deflateSync, inflateSync } from "fflate";
 import tokensData from "../data/token-registry.generated.json";
-import type { TokenRegistry, DecodeOptions } from "../types";
+import type { TokenRegistry, DecodeOptions, ShareOptions } from "../types";
 
 declare const __SLASHED_VERSION__: string;
 
@@ -264,7 +264,7 @@ export function encodeOverrides(overrides: Record<string, string>): string {
 
 const SHARE_PARAM_RE = new RegExp(`[#&]?${SHARE_PARAM}=([^&]+)`);
 
-export function readShareFromHash(hashOrParam: string, options: DecodeOptions = {}): Record<string, string> {
+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();
@@ -284,7 +284,7 @@ export function buildShareUrl(overrides: Record<string, string>, baseUrlOverride
   return url.toString();
 }
 
-export function readShareFromHashIfPresent(hash: string, options: DecodeOptions = {}): Record<string, string> {
+export function readShareFromHashIfPresent(hash: string, options: ShareOptions = {}): Record<string, string> {
   const value = String(hash ?? "");
   return value.includes(`${SHARE_PARAM}=`) ? readShareFromHash(value, options) : {};
 }
diff --git a/configurator/src/types.ts b/configurator/src/types.ts
index e82f857f..8f576474 100644
--- a/configurator/src/types.ts
+++ b/configurator/src/types.ts
@@ -67,12 +67,20 @@ export interface TokenRegistry {
   tokens: TokenRegistryEntry[];
 }
 
-/** Options accepted by codec.ts's decode() / readShareFromHash() / readShareFromHashIfPresent(). */
+/** 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;

From 23c53270f6ff733478b4c5a70bf045af95560cbd Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 2 Jul 2026 07:14:00 +0000
Subject: [PATCH 16/20] refactor(configurator): shape-guard localStorage reads,
 migrate lucide-svelte, document preview singleton
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

SL-019: reuse savedThemes.ts's isStringRecord() shape guard in
persistence.ts's loadInitialOverrides() instead of trusting
JSON.parse(local) as Record<string,string> unchecked — malformed or
wrong-shaped localStorage now falls back to {} instead of passing through.

SL-021: verified already resolved (no motion dependency or imports remain).

SL-022: migrate lucide-svelte -> @lucide/svelte across all 9 importing
files (import-source only, no icon renames needed — verified via tsc/
svelte-check/build after the full migration).

SL-025: document why previewResolver.svelte.ts's previewVersion is a
deliberate module-level singleton rather than component-scoped state.

SL-018 and SL-015 were investigated but required no changes: SL-018's
'error' saveState and its StudioHeader render branch were already fully
implemented in an earlier batch; SL-015's premise (two competing
`overrides` membership idioms to unify) doesn't hold in this codebase —
only the `in` idiom is used, consistently, across ~120 call sites in ~15
files, well beyond the ~15-site estimate in the remediation plan.
---
 configurator/package-lock.json                | 23 +++++++++----------
 configurator/package.json                     |  4 ++--
 configurator/src/App.svelte                   |  2 +-
 .../src/components/DomainPanel.svelte         |  2 +-
 .../components/panels/CheatsheetPanel.svelte  |  2 +-
 .../src/components/panels/ExportPanel.svelte  |  2 +-
 .../src/components/panels/HomePanel.svelte    |  2 +-
 .../src/components/panels/ThemesPanel.svelte  |  2 +-
 .../src/components/shell/PreviewPanel.svelte  |  2 +-
 .../src/components/shell/SidebarNav.svelte    |  2 +-
 .../src/components/shell/StudioHeader.svelte  |  2 +-
 configurator/src/lib/persistence.ts           |  6 ++++-
 .../src/lib/previewResolver.svelte.ts         |  8 +++++++
 configurator/src/lib/savedThemes.ts           |  2 +-
 configurator/tests/persistence.test.js        | 20 +++++++++-------
 15 files changed, 48 insertions(+), 33 deletions(-)

diff --git a/configurator/package-lock.json b/configurator/package-lock.json
index bfe4c941..ed74bc86 100644
--- a/configurator/package-lock.json
+++ b/configurator/package-lock.json
@@ -8,8 +8,8 @@
       "name": "slashed-configurator",
       "version": "0.6.33",
       "dependencies": {
-        "fflate": "^0.8.3",
-        "lucide-svelte": "^0.468.0"
+        "@lucide/svelte": "^1.23.0",
+        "fflate": "^0.8.3"
       },
       "devDependencies": {
         "@playwright/test": "^1.60.0",
@@ -685,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",
@@ -2719,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",
diff --git a/configurator/package.json b/configurator/package.json
index 34500122..ac9ba6b8 100644
--- a/configurator/package.json
+++ b/configurator/package.json
@@ -21,8 +21,8 @@
     "test:e2e": "playwright test"
   },
   "dependencies": {
-    "fflate": "^0.8.3",
-    "lucide-svelte": "^0.468.0"
+    "@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 fb436fa0..b6d65bf8 100644
--- a/configurator/src/App.svelte
+++ b/configurator/src/App.svelte
@@ -1,6 +1,6 @@
 <script lang="ts">
   import { onMount, untrack } from 'svelte';
-  import { SlidersHorizontal, Eye, RotateCcw } from 'lucide-svelte';
+  import { SlidersHorizontal, Eye, RotateCcw } from '@lucide/svelte';
   import type { PreviewTemplate, SlashedToken } from './types';
   import StudioHeader from './components/shell/StudioHeader.svelte';
   import SidebarNav from './components/shell/SidebarNav.svelte';
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..5c791c1c 100644
--- a/configurator/src/components/panels/CheatsheetPanel.svelte
+++ b/configurator/src/components/panels/CheatsheetPanel.svelte
@@ -5,7 +5,7 @@
 <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';
 
   const classes = classesData.classes;
   const tokens = tokensData.tokens.filter((t: any) => t.tier === 'PUBLIC' || t.tier === 'PUBLIC-ADVANCED');
diff --git a/configurator/src/components/panels/ExportPanel.svelte b/configurator/src/components/panels/ExportPanel.svelte
index ac1a6d39..c25ef76a 100644
--- a/configurator/src/components/panels/ExportPanel.svelte
+++ b/configurator/src/components/panels/ExportPanel.svelte
@@ -1,5 +1,5 @@
 <script lang="ts">
-  import { Check, Copy, Download, Link } from 'lucide-svelte';
+  import { Check, Copy, Download, Link } from '@lucide/svelte';
   import { generateCSS, buildShareUrl } from '../../lib/codec';
 
   let { overrides }: {
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 06d61482..4beb7898 100644
--- a/configurator/src/components/shell/PreviewPanel.svelte
+++ b/configurator/src/components/shell/PreviewPanel.svelte
@@ -1,5 +1,5 @@
 <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 { generateCSS } from '../../lib/codec';
   import { computeDerivedOverrides } from '../../lib/persistence';
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 cf18f2cb..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, AlertTriangle } from 'lucide-svelte';
+  import { Undo2, Redo2, Trash2, Share2, FolderOpen, Check, Save, Loader2, AlertTriangle } from '@lucide/svelte';
 
   const version = typeof __SLASHED_VERSION__ !== "undefined" ? __SLASHED_VERSION__ : "";
 
diff --git a/configurator/src/lib/persistence.ts b/configurator/src/lib/persistence.ts
index 7b365f8a..3e2fd72b 100644
--- a/configurator/src/lib/persistence.ts
+++ b/configurator/src/lib/persistence.ts
@@ -14,6 +14,7 @@
  * chrome + preview reflect the current overrides immediately.
  */
 import { readShareFromHashIfPresent, encodeOverrides, generateCSS } from "./codec";
+import { isStringRecord } from "./savedThemes";
 
 const LS_KEY = "slashed-studio/overrides/v2";
 
@@ -216,7 +217,10 @@ export function loadInitialOverrides(): Record<string, string> {
   }
   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 {};
 }
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/tests/persistence.test.js b/configurator/tests/persistence.test.js
index cfe12c97..896839d0 100644
--- a/configurator/tests/persistence.test.js
+++ b/configurator/tests/persistence.test.js
@@ -4,8 +4,8 @@
  * 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 case flagged by SL-019 (not fixed in this
- * pass — the assertions below document the current, unguarded behavior).
+ * 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';
@@ -87,13 +87,17 @@ describe('loadInitialOverrides — standalone mode', () => {
     expect(loadInitialOverrides()).toEqual({});
   });
 
-  // SL-019 (not fixed here): loadInitialOverrides' standalone/localStorage path
-  // trusts JSON.parse's result as Record<string,string> with no shape guard,
-  // unlike savedThemes.ts's equivalent read path. This test pins today's real
-  // (unguarded) behavior so a future SL-019 fix has a test to update.
-  test('SL-019: currently returns non-object JSON as-is instead of {} (documented gap)', () => {
+  // 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(['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({});
   });
 });
 

From 04ab9968427f9363f6a773172a2eba00ac044b74 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 2 Jul 2026 10:04:23 +0000
Subject: [PATCH 17/20] perf(configurator): rAF-coalesce preview iframe writes
 during rapid override changes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

SL-020: PreviewPanel.svelte's two $effects that write to the preview
iframe(s) and call bumpPreviewVersion() re-run on every overrides tick —
e.g. every input event while dragging a slider, often several times per
animation frame. Deferred the DOM-writing work (style/attribute mutation,
font injection, resolver cache invalidation) inside each effect to a
requestAnimationFrame callback that captures the latest values, cancelling
any not-yet-fired frame from a superseded run via the effect's cleanup.
This collapses a same-frame burst down to one apply using the last state,
instead of one apply per keystroke.

Reactive dependency tracking is unaffected — overrides/previewTheme/
loadCount/etc. are still read synchronously at the top of each effect, so
Svelte's re-run triggering is unchanged; only the actual DOM writes are
deferred. previewResolver.svelte.ts's bumpPreviewVersion() itself is
untouched, preserving its existing "pure write, no reactive read"
invariant.

Verified via a manual rapid-drag simulation against a real built preview
server (40 input events fired faster than one per frame): zero console/
page errors (no effect_update_depth loop), and the preview iframe's
applied CSS exactly matched the last dragged value with no dropped
trailing frame.
---
 .../src/components/shell/PreviewPanel.svelte  | 107 +++++++++++-------
 1 file changed, 64 insertions(+), 43 deletions(-)

diff --git a/configurator/src/components/shell/PreviewPanel.svelte b/configurator/src/components/shell/PreviewPanel.svelte
index 06d61482..5f76d003 100644
--- a/configurator/src/components/shell/PreviewPanel.svelte
+++ b/configurator/src/components/shell/PreviewPanel.svelte
@@ -481,35 +481,51 @@ ${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 = generateCSS(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(doc);
+      bumpPreviewVersion();
+    });
 
-    // This single-mode iframe is the canonical resolver source.
-    registerPreviewDoc(doc);
-    bumpPreviewVersion();
+    return () => cancelAnimationFrame(rafId);
   });
 
   $effect(() => {
@@ -517,34 +533,39 @@ ${BODIES[template]}
     const _lightCount = splitLightLoadCount;
     const _darkCount = splitDarkLoadCount;
     const _lock = lumlockerPreview.value;
-    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");
-    };
-
-    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);
+    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");
+      };
+
+      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);
+        }
       }
-    }
-    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);
+        }
       }
-    }
-    bumpPreviewVersion();
+      bumpPreviewVersion();
+    });
+
+    return () => cancelAnimationFrame(rafId);
   });
 
   let isConstrained = $derived(previewWidth !== "fluid");

From 0515efa864050e24096a37014ef6b9035fea31a9 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 2 Jul 2026 10:14:37 +0000
Subject: [PATCH 18/20] fix(configurator): remove redundant previewVersion
 bumps and skip split-mode effect when inactive
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Qodo review on PR6 flagged two real, pre-existing (not introduced by the
rAF-coalescing itself) inefficiencies in the two effects this PR touches:

1. The single-iframe effect called bumpPreviewVersion() explicitly right
   after registerPreviewDoc(doc), but registerPreviewDoc() already bumps
   internally on every path (both its activeDoc-unchanged early-return and
   its replace-doc branch) — the explicit call double-bumped
   previewVersion and double-cleared resolveCache on every apply.

2. The split-mode effect unconditionally scheduled an rAF, computed CSS,
   and bumped previewVersion even when splitMode is false and no split
   iframes exist in the DOM (they're gated behind {#if splitMode}),
   making every apply pure overhead outside split mode.

Fixed both: dropped the explicit bump in the single-iframe effect, added
an early return on !splitMode in the split effect, and made its trailing
bump conditional (only fires when the dark pane updated without the light
pane also updating, since registerPreviewDoc's internal bump already
covers the light-pane case) so consumers are still notified exactly once
whenever a split pane actually changed.

Re-verified via the same rapid-drag simulation as the original PR6
commit, now covering both single- and split-preview modes: zero console/
page errors, and both modes' applied CSS exactly matched the last
dragged value.
---
 .../src/components/shell/PreviewPanel.svelte  | 21 +++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/configurator/src/components/shell/PreviewPanel.svelte b/configurator/src/components/shell/PreviewPanel.svelte
index 5f76d003..fee78000 100644
--- a/configurator/src/components/shell/PreviewPanel.svelte
+++ b/configurator/src/components/shell/PreviewPanel.svelte
@@ -521,19 +521,28 @@ ${BODIES[template]}
       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);
-      bumpPreviewVersion();
     });
 
     return () => cancelAnimationFrame(rafId);
   });
 
   $effect(() => {
+    const _splitMode = splitMode;
     const _ov = overrides;
     const _lightCount = splitLightLoadCount;
     const _darkCount = splitDarkLoadCount;
     const _lock = lumlockerPreview.value;
 
+    // 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 });
 
@@ -542,6 +551,12 @@ ${BODIES[template]}
         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) {
@@ -551,6 +566,7 @@ ${BODIES[template]}
           applyLock(doc);
           // In split mode the light pane is the canonical resolver source.
           registerPreviewDoc(doc);
+          lightApplied = true;
         }
       }
       if (splitDarkEl && _darkCount > 0) {
@@ -560,9 +576,10 @@ ${BODIES[template]}
           if (styleEl) styleEl.textContent = css;
           injectFontsIntoDoc(doc, _ov);
           applyLock(doc);
+          darkApplied = true;
         }
       }
-      bumpPreviewVersion();
+      if (darkApplied && !lightApplied) bumpPreviewVersion();
     });
 
     return () => cancelAnimationFrame(rafId);

From 5b14839ae12c514035842d0edfd4921aee6ffe3a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 2 Jul 2026 12:20:17 +0000
Subject: [PATCH 19/20] test(configurator): cover previewResolver.svelte.ts and
 StudioHeader's save-error state
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

SL-023 continuation, the last item in the remediation plan's PR7. Two
real gaps remained after PR4/PR5/PR6 merged and the earlier batch's
persistence.ts/SliderRow/TokenRow coverage:

- previewResolver.svelte.ts had zero test coverage. Added tests/previewResolver.test.js
  covering registerPreviewDoc/getActiveTheme, resolveColor/resolveColorForTheme's
  per-expression and per-theme caching, resolveRgb/resolveBackground's
  no-preview-doc fallbacks, and — closing the loop on PR6's SL-020
  rAF-coalescing — that bumpPreviewVersion() reliably invalidates the
  cache and is safe to call repeatedly (a pure counter, no reactive
  loop). Uses a real <iframe>'s contentDocument rather than a detached
  document, since jsdom's getComputedStyle only resolves colors on
  documents with a defaultView — matching how PreviewPanel.svelte
  registers a real iframe in production.

- StudioHeader's 'error' saveState (added by SL-018 in an earlier
  batch) had no test coverage of its own. Added a save-state describe
  block to tests-components/header.test.js covering all four states
  (idle/saving/saved/error), specifically that a failed save surfaces
  a distinct title/label from a fresh save and stays clickable to
  retry, while an in-progress retry is still correctly disabled.
  Corrected the file's baseProps fixture, which was missing
  hasPendingChanges/saveState/onSave (present since SL-018 but never
  added to this test file).

Verified: npm run test:unit (89/89), npm run test:components (23/23),
npm run test (112/112 combined), npx tsc --noEmit, npx svelte-check
(0 errors/warnings), npm run build, and a real-browser e2e smoke pass
against a built preview server (5/6 — the 1 failure is the same
pre-existing /favicon.ico 404 noted in PR5/PR6, unrelated).
---
 configurator/tests-components/header.test.js |  51 +++++-
 configurator/tests/previewResolver.test.js   | 174 +++++++++++++++++++
 2 files changed, 224 insertions(+), 1 deletion(-)
 create mode 100644 configurator/tests/previewResolver.test.js

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/previewResolver.test.js b/configurator/tests/previewResolver.test.js
new file mode 100644
index 00000000..a8a9eef7
--- /dev/null
+++ b/configurator/tests/previewResolver.test.js
@@ -0,0 +1,174 @@
+/**
+ * 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 } from 'vitest';
+import {
+  previewVersion,
+  registerPreviewDoc,
+  getActiveTheme,
+  bumpPreviewVersion,
+  resolveColor,
+  resolveColorForTheme,
+  resolveRgb,
+  resolveBackground,
+} from '../src/lib/previewResolver.svelte';
+
+function makePreviewDoc(theme = 'light') {
+  const iframe = document.createElement('iframe');
+  document.body.appendChild(iframe);
+  const doc = iframe.contentDocument;
+  doc.documentElement.setAttribute('data-theme', theme);
+  return doc;
+}
+
+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();
+  });
+
+  // This sandbox has no `canvas` npm package installed, so jsdom's
+  // HTMLCanvasElement.getContext('2d') is unimplemented and logs (but does
+  // not throw) a "not implemented" error — resolveRgb must degrade to null
+  // rather than propagating that. Silencing the expected console.error here
+  // to keep test output clean; the assertion is what matters.
+  test('degrades to null (not a throw) when no 2D canvas context is available', () => {
+    registerPreviewDoc(makePreviewDoc());
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    expect(() => resolveRgb('red')).not.toThrow();
+    expect(resolveRgb('red')).toBeNull();
+    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');
+  });
+});

From 156e4214abd0d6e781d56f0b1956113656c710ee Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 2 Jul 2026 12:27:46 +0000
Subject: [PATCH 20/20] fix(configurator): clean up leaked test iframes and
 decouple canvas test from environment
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Qodo review on PR7 flagged two real issues in tests/previewResolver.test.js:

1. makePreviewDoc() appended a new <iframe> to document.body on every
   call with no teardown — registerPreviewDoc() only cleans up the
   resolver's internal probe elements, not the test-created iframes
   themselves, so they accumulated across the file's 16+ calls. Added
   an afterEach that removes every iframe makePreviewDoc() created and
   unregisters the preview doc.

2. The canvas-degrades-to-null test asserted resolveRgb('red') returns
   null based on this sandbox's jsdom lacking the optional `canvas` npm
   package, rather than the documented contract — if canvas support
   ever became available the test would start failing for an unrelated
   reason. Replaced with an explicit getContext('2d') stub, plus a new
   companion test asserting the positive path (a real 2D context
   available) returns an [r,g,b] triple.

   Fixing this surfaced a real subtlety Qodo's own suggested fix would
   have missed: each iframe is a separate jsdom realm with its own
   HTMLCanvasElement constructor, so a canvas created via
   activeDoc.createElement('canvas') is an instance of
   doc.defaultView.HTMLCanvasElement, not the top-level test file's
   global HTMLCanvasElement — spying on the wrong one is a silent no-op
   (verified: the positive-path test failed until the spy target was
   corrected to the iframe's own realm).

Verified: npm run test:unit (90/90, up from 89 with the new positive-
path test), npx tsc --noEmit, npx svelte-check (0 errors/warnings), and
a standalone check confirming zero leftover <iframe> elements in
document.body after the full previewResolver suite runs.
---
 configurator/tests/previewResolver.test.js | 47 ++++++++++++++++++----
 1 file changed, 39 insertions(+), 8 deletions(-)

diff --git a/configurator/tests/previewResolver.test.js b/configurator/tests/previewResolver.test.js
index a8a9eef7..49c068af 100644
--- a/configurator/tests/previewResolver.test.js
+++ b/configurator/tests/previewResolver.test.js
@@ -15,7 +15,7 @@
  * invalidation/theme-scoping logic, not real CSS cascade computation (the
  * browser's job, already trusted).
  */
-import { describe, test, expect, vi } from 'vitest';
+import { describe, test, expect, vi, afterEach } from 'vitest';
 import {
   previewVersion,
   registerPreviewDoc,
@@ -27,14 +27,26 @@ import {
   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;
@@ -147,18 +159,37 @@ describe('resolveRgb', () => {
     expect(resolveRgb('red')).toBeNull();
   });
 
-  // This sandbox has no `canvas` npm package installed, so jsdom's
-  // HTMLCanvasElement.getContext('2d') is unimplemented and logs (but does
-  // not throw) a "not implemented" error — resolveRgb must degrade to null
-  // rather than propagating that. Silencing the expected console.error here
-  // to keep test output clean; the assertion is what matters.
+  // 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', () => {
-    registerPreviewDoc(makePreviewDoc());
-    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    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', () => {