@amityco/social-plus-vise 1.0.0 → 1.1.0

package/dist/tools/design.js

@@ -4,33 +4,15 @@ import path from "node:path";
 import { objectInput, optionalStringField, stringField, textResult } from "../types.js";
 import { packageVersion } from "../version.js";
 import { tryParse } from "./ast.js";
-/**
- * Design-contract extractor.
- *
- * Ingests an HTML/CSS prototype and produces a *graded* design contract:
- * declared CSS custom properties are recorded as EXACT tokens; repeated literal
- * values are recorded as INFERRED tokens; component shapes from the DOM are
- * recorded as ADVISORY observations. Provenance is first-class so downstream
- * consumers never treat an inferred value as authoritative.
- *
- * Design principle (mirrors `tryParse` degrading to regex): a messy prototype
- * yields a *weaker* contract, never a *wrong* one. Less signal -> fewer tokens,
- * never fabricated ones.
- */
 export const DESIGN_CONTRACT_SCHEMA_VERSION = 1;
 export const DESIGN_CONTRACT_FILENAME = "design-contract.json";
 export const DESIGN_PREVIEW_FILENAME = "design-preview.html";
 export const DESIGN_CONTRACT_CONFIRMATION_ANSWER_ID = "design_contract_confirmation";
-/** A literal value must appear at least this many times to become an inferred token. Single-use literals are one-offs (a scrim, one accent), not design tokens. */
 export const INFERRED_MIN_USES = 2;
-/** Bound the prototype walk so a large input directory cannot stall extraction. */
 const MAX_PROTOTYPE_FILES = 300;
-/** Bound the source scan for the advisory `design check`. */
 const MAX_SCAN_FILES = 2000;
-/** Cap the off-contract sample so the advisory report stays readable. */
 const OFF_CONTRACT_SAMPLE = 20;
 const SCAN_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".dart", ".kt", ".java", ".swift", ".css", ".scss", ".vue", ".xml"]);
-/** Extensions whose design tokens are extracted by parsing object literals (TS/JS token modules, tailwind config). */
 const MODULE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
 const MAX_FILE_BYTES = 2_000_000;
 const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", ".next", "out", "coverage", "vendor", ".turbo", ".cache"]);
@@ -55,9 +37,6 @@ export function designContractConfirmationFromAnswers(answers) {
 export function designPreviewPath(repoPath) {
     return path.join(path.resolve(repoPath), "sp-vise", DESIGN_PREVIEW_FILENAME);
 }
-// ---------------------------------------------------------------------------
-// Public entry points
-// ---------------------------------------------------------------------------
 export const designExtractTool = {
     name: "design_extract",
     description: "Extract a graded design contract (declared/inferred tokens + advisory components) for design-conformant social.plus UI. Source is an HTML/CSS prototype, or — with fromProject — the host project's own design system (CSS vars, token modules, tailwind config).",
@@ -116,15 +95,6 @@ export async function extractDesignContract(prototypePath) {
     const sources = await readPrototypeSources(resolved);
     return buildDesignContract(sources, { kind: "html-css-prototype", inputs: sources.inputs, file_count: sources.inputs.length });
 }
-/**
- * Derive a design contract from the *host project's own* design system, for when
- * the customer gives no external prototype. Scopes to the design-source files
- * Vise detects (theme/token modules, tailwind config, global CSS) — never the
- * whole repo — and extracts: CSS custom properties (incl. shadcn `:root` and
- * Tailwind v4 `@theme`), plus concrete tokens from TS/JS token modules and
- * inline tailwind configs. References (`var()`/`theme()`/`calc()`) are rejected,
- * so a var-mapped config contributes nothing rather than wrong tokens.
- */
 export async function extractDesignContractFromProject(repoPath) {
     const root = path.resolve(repoPath);
     const files = await findProjectDesignFiles(root);
@@ -187,14 +157,13 @@ export async function extractDesignContractFromProject(repoPath) {
         }
     }
     inputs.sort();
-    // Hash each source file so design check can detect staleness without re-extracting.
     const input_digests = {};
     for (const rel of inputs) {
         try {
             const content = await readFile(path.join(root, rel), "utf8");
             input_digests[rel] = `sha256:${createHash("sha256").update(content).digest("hex")}`;
         }
-        catch { /* file read already succeeded above; defensive only */ }
+        catch { }
     }
     return buildDesignContract({ css, html: [], inputs }, { kind: "host-project", inputs, input_digests, file_count: inputs.length }, moduleTokens);
 }
@@ -228,17 +197,6 @@ export async function writeDesignPreview(repoPath, contract, referencePath) {
     await writeFile(target, html, "utf8");
     return target;
 }
-// ---------------------------------------------------------------------------
-// Visual contract review + conformance report (advisory, dependency-free)
-// ---------------------------------------------------------------------------
-//
-// Vise produces the visual artifact; a human (or a VLM) judges whether the
-// generated UI matches. This is NOT an automated pixel/render diff — that would
-// need a headless browser (non-deterministic, heavy dep) and does not belong in
-// Vise's deterministic, dependency-free core. The honest comparison data is:
-// (1) the contract's tokens rendered as visual swatches, (2) the actual HTML
-// reference embedded beside them when renderable, and (3) the `design check`
-// conformance numbers (coverage + on/off-contract) as the textual diff.
 export const designPreviewTool = {
     name: "design_preview",
     description: "Generate a self-contained HTML visual review of the design contract (token swatches + embedded HTML reference + conformance report) for human/VLM judgment. Advisory, non-blocking; not an automated pixel diff.",
@@ -281,7 +239,6 @@ export const designPreviewTool = {
         });
     },
 };
-/** Read an HTML prototype into a self-contained string (inlining linked stylesheets) for embedding. Returns null if there's no renderable HTML. */
 export async function readReferenceHtml(referencePath) {
     const resolved = path.resolve(referencePath);
     let htmlFile = null;
@@ -312,14 +269,13 @@ export async function readReferenceHtml(referencePath) {
     catch {
         return null;
     }
-    // Inline <link rel="stylesheet" href="..."> so the embed is self-contained.
     const dir = path.dirname(htmlFile);
     const linkPattern = /<link[^>]*rel\s*=\s*["']stylesheet["'][^>]*href\s*=\s*["']([^"']+)["'][^>]*>/gi;
     const links = [...html.matchAll(linkPattern)];
     for (const link of links) {
         const href = link[1];
         if (/^https?:|^\/\//i.test(href)) {
-            continue; // external — leave as-is (won't load in sandboxed iframe, that's fine)
+            continue;
         }
         try {
             const cssPath = path.join(dir, href);
@@ -327,7 +283,6 @@ export async function readReferenceHtml(referencePath) {
             html = html.replace(link[0], `<style>\n${css}\n</style>`);
         }
         catch {
-            // leave the link; missing CSS just won't apply
         }
     }
     return html;
@@ -420,29 +375,10 @@ function esc(s) {
 function escAttr(s) {
     return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
 }
-/** Sanitize a contract value before use inside an inline CSS `style` attribute (values come from the user's own files, but keep the preview from breaking out of the attribute). */
 function safeCss(value) {
     return value.replace(/[<>"]/g, "").slice(0, 200);
 }
-// ---------------------------------------------------------------------------
-// Social-plus token scaffold (vise design init-tokens)
-// ---------------------------------------------------------------------------
-//
-// Creates a dedicated `src/styles/social-plus-tokens.css` in the customer's
-// project — the single editable source for social.plus feature styling.
-// The contract always points at this file; customers edit it freely without
-// needing an AI agent. Design check detects changes and prompts re-extract.
-//
-// Two cases:
-//   Greenfield (no existing design system): scaffold Option-B neutral defaults.
-//   Brownfield (existing tokens found):     seed from their concrete values.
-//   Already exists: leave it untouched (idempotent — never clobbers edits).
-/** Relative path within the customer's project where sp tokens live. */
 export const SP_TOKENS_PATH = "src/styles/social-plus-tokens.css";
-/** Option-B neutral default — a clean, adaptive light-mode system using system
- *  fonts. All token names use `--sp-` prefix to avoid collision with the
- *  customer's own design system. Will be replaced with the official social.plus
- *  palette (Option A) once that palette is finalised. */
 export const NEUTRAL_SP_TOKENS_DEFAULT = `/* social-plus-tokens.css — social.plus feature design system.
  * This file controls the look of all social.plus features in your app.
  * Edit freely. Run: vise design extract --from-project . to refresh the contract.
@@ -577,7 +513,6 @@ export const designInitTokensTool = {
 export async function initSpTokens(repoPath, force = false) {
     const root = path.resolve(repoPath);
     const target = path.join(root, SP_TOKENS_PATH);
-    // Idempotent: don't overwrite unless forced.
     try {
         await stat(target);
         if (!force) {
@@ -588,14 +523,12 @@ export async function initSpTokens(repoPath, force = false) {
             };
         }
     }
-    catch { /* file doesn't exist — proceed to scaffold */ }
-    // Try brownfield seeding: extract concrete token values from the existing project.
+    catch { }
     const existingContract = await extractDesignContractFromProject(root);
     const hasBrownfieldTokens = existingContract.tokens.length > 0;
     let css;
     let seededFrom;
     if (hasBrownfieldTokens) {
-        // Seed from their existing concrete values, namespaced as --sp-*.
         const lines = [
             `/* social-plus-tokens.css — social.plus feature design system.`,
             ` * Seeded from your existing design tokens on ${new Date().toISOString().slice(0, 10)}.`,
@@ -619,7 +552,6 @@ export async function initSpTokens(repoPath, force = false) {
         seededFrom = existingContract.source.inputs;
     }
     else {
-        // Greenfield: neutral Option-B defaults.
         css = NEUTRAL_SP_TOKENS_DEFAULT;
     }
     await mkdir(path.dirname(target), { recursive: true });
@@ -633,16 +565,6 @@ export async function initSpTokens(repoPath, force = false) {
             : `Scaffolded ${SP_TOKENS_PATH} with neutral defaults. Fill in your colors, then run vise design extract --from-project .`,
     };
 }
-// ---------------------------------------------------------------------------
-// Design-system reference document (human/VLM-readable, advisory)
-// ---------------------------------------------------------------------------
-//
-// Pairs with design-contract.json (machine-readable): this is the "v1.0" visual
-// spec a human or VLM can read, share, or diff. It reads the source CSS so that
-// var(--x) resolves live in the browser; for non-CSS projects (Android, Flutter,
-// iOS, TS module) it falls back to rendering directly from the contract tokens.
-//
-// NOT a gate — advisory documentation only.
 export const designReferenceTool = {
     name: "design_reference",
     description: "Generate a self-contained HTML design-system reference (token swatches, type samples, component demos, growth-layer summary) from the Vise design contract. Human/VLM-readable; advisory, not an enforcement gate.",
@@ -685,11 +607,6 @@ export const designReferenceTool = {
         });
     },
 };
-/**
- * Generate a self-contained HTML design-system reference from the contract.
- * Reads source CSS files for full var() resolution; falls back to contract tokens
- * for non-CSS projects (Android XML, Flutter Dart, iOS, TS module sources).
- */
 export async function generateDesignReference(repoPath, contract, title) {
     const root = path.resolve(repoPath);
     const cssTexts = await Promise.all((contract.source?.inputs ?? []).map(async (rel) => {
@@ -704,10 +621,6 @@ export async function generateDesignReference(repoPath, contract, title) {
         }
     }));
     const tokenCss = cssTexts.join("\n");
-    // `ref` = how this token is referenced in a CSS style attribute.
-    // CSS projects: `var(--name)` so the token resolves live via the inlined :root.
-    // Non-CSS projects (Android/Flutter/iOS/TS module): use the concrete value directly
-    // since there is no :root to resolve from.
     const hasCssInputs = (contract.source?.inputs ?? []).some((rel) => /\.(css|scss)$/i.test(rel));
     let allTokens;
     if (hasCssInputs && tokenCss.trim()) {
@@ -720,7 +633,6 @@ export async function generateDesignReference(repoPath, contract, title) {
         }));
     }
     else {
-        // Non-CSS project: render from contract tokens directly, using concrete values.
         allTokens = contract.tokens
             .filter((t) => t.name !== null)
             .map((t) => ({ name: t.name, value: t.value, ref: safeCss(t.value), inContract: true, category: t.category }));
@@ -744,8 +656,6 @@ export async function generateDesignReference(repoPath, contract, title) {
         { id: "bp", label: "Breakpoints", kind: "chip", match: (n) => n.startsWith("--bp-") },
         { id: "z", label: "Z-index", kind: "chip", match: (n) => n.startsWith("--z-") },
     ];
-    // Maps contract category → rendering kind; used as fallback for non-CSS tokens
-    // whose names don't carry the --prefix conventions above.
     const CATEGORY_TO_KIND = {
         color: "color", space: "space", radius: "radius", shadow: "shadow",
         fontFamily: "family", fontSize: "fontsize", motion: "chip", opacity: "opacity",
@@ -760,8 +670,6 @@ export async function generateDesignReference(repoPath, contract, title) {
         items.forEach((t) => used.add(t.name));
         return { id: g.id, label: g.label, kind: g.kind, items };
     }).filter((g) => g.items.length > 0);
-    // For non-CSS tokens not matched by name-prefix above, fall back to grouping by
-    // the contract category field so native projects produce a properly-sectioned doc.
     const unmatchedByName = allTokens.filter((t) => !used.has(t.name));
     const catBuckets = new Map();
     const trueUngrouped = [];
@@ -804,14 +712,12 @@ export async function generateDesignReference(repoPath, contract, title) {
     function renderTokenRow(t) {
         return `<div class="ds-token-row"><code class="ds-token-name">${esc(t.name)}${provTag(t)}</code><code class="ds-token-pill">${esc(t.value)}</code></div>`;
     }
-    // Super-group assignment for nav + section tags.
     const GROUP_SUPER = {
         brand: "COLOR", bg: "COLOR", text: "COLOR", line: "COLOR",
         font: "TYPOGRAPHY", fs: "TYPOGRAPHY", fw: "TYPOGRAPHY", lh: "TYPOGRAPHY",
         space: "LAYOUT", size: "LAYOUT", bp: "LAYOUT",
         radius: "SURFACE", border: "SURFACE", shadow: "SURFACE",
         opacity: "EFFECTS", motion: "EFFECTS", z: "EFFECTS",
-        // category-based (native projects)
         color: "COLOR", fontFamily: "TYPOGRAPHY", fontSize: "TYPOGRAPHY",
         other: "OTHER",
     };
@@ -1180,8 +1086,6 @@ export async function runDesignCheck(repoPath) {
             note: ADVISORY_NOTE,
         };
     }
-    // Freshness check: compare source file content hashes to those recorded at extract time.
-    // Advisory only — never blocks, just surfaces a nudge to re-extract.
     const staleContract = await checkContractFreshness(repoRoot, contract);
     const files = (await collectFiles(repoRoot, MAX_SCAN_FILES)).filter((file) => SCAN_EXTS.has(path.extname(file).toLowerCase()));
     if (files.length === 0) {
@@ -1211,7 +1115,6 @@ export async function runDesignCheck(repoPath) {
         scanned += 1;
         const rel = path.relative(repoRoot, file);
         const isCss = file.toLowerCase().endsWith(".css") || file.toLowerCase().endsWith(".scss");
-        // Token coverage: a declared token is "referenced" if its var name OR its value appears in the code.
         for (const token of declaredTokens) {
             const key = tokenKey(token);
             if (referenced.has(key)) {
@@ -1221,7 +1124,6 @@ export async function runDesignCheck(repoPath) {
                 referenced.add(key);
             }
         }
-        // Raw color literals: counted, then classified on/off contract.
         for (const value of scanColorLiterals(content)) {
             totalColors += 1;
             if (contractColorValues.has(value)) {
@@ -1231,7 +1133,6 @@ export async function runDesignCheck(repoPath) {
                 colorSample.push({ value, file: rel, on_contract: false });
             }
         }
-        // Token hygiene: collect var(--x) references (any file) and --x: definitions (CSS files).
         for (const name of scanVarReferences(content)) {
             varRefs.push({ token: name, file: rel });
         }
@@ -1243,11 +1144,6 @@ export async function runDesignCheck(repoPath) {
     }
     const referencedTokens = declaredTokens.filter((token) => referenced.has(tokenKey(token))).map((token) => token.name ?? token.value);
     const unreferencedTokens = declaredTokens.filter((token) => !referenced.has(tokenKey(token))).map((token) => token.name ?? token.value);
-    // A var(--x) referenced but defined in no scanned CSS file AND not a known
-    // contract token resolves to nothing at runtime — a typo or hallucinated
-    // token. Contract token names are excluded: they are legitimate design tokens
-    // that may be supplied by an imported/external design-system stylesheet, so
-    // flagging them would risk a false positive (Vise's cardinal sin).
     const contractTokenNames = new Set(contract.tokens.map((token) => token.name).filter((name) => Boolean(name)));
     const undefinedRefs = dedupeByToken(varRefs.filter((ref) => !definedVars.has(ref.token) && !contractTokenNames.has(ref.token)));
     return {
@@ -1278,8 +1174,6 @@ export async function runDesignCheck(repoPath) {
         note: ADVISORY_NOTE,
     };
 }
-/** Compare source.inputs file content against hashes recorded at extract time.
- *  Returns null if the contract is fresh or has no recorded digests. */
 async function checkContractFreshness(repoRoot, contract) {
     const recorded = contract.source?.input_digests;
     if (!recorded || Object.keys(recorded).length === 0)
@@ -1293,7 +1187,7 @@ async function checkContractFreshness(repoRoot, contract) {
                 changed.push(rel);
         }
         catch {
-            changed.push(rel); // file deleted or unreadable — also stale
+            changed.push(rel);
         }
     }
     if (changed.length === 0)
@@ -1325,7 +1219,6 @@ function scanVarReferences(content) {
 }
 function scanVarDefinitions(content) {
     const out = [];
-    // Match `--x:` declarations, but not `var(--x)` references (no colon after the name there).
     const pattern = /(--[\w-]+)\s*:/g;
     let match;
     while ((match = pattern.exec(content)) !== null) {
@@ -1344,26 +1237,21 @@ function contractSummary(contract) {
 function tokenKey(token) {
     return `${token.category}::${token.name ?? token.value}`;
 }
-/** Extract comparable hex color values from a source file: web `#hex`, Flutter/Android `Color(0xAARRGGBB)`. */
 function scanColorLiterals(content) {
     const out = [];
     let match;
-    // Web/Android/XML hex (`#RRGGBB`, incl. `<color>#RRGGBB</color>`).
     const hexPattern = /#[0-9a-fA-F]{3,8}\b/g;
     while ((match = hexPattern.exec(content)) !== null) {
         out.push(normalizeHex(match[0]));
     }
-    // Flutter/Android ARGB `0xAARRGGBB` -> #rrggbb (drop alpha).
     const argbPattern = /0x([0-9a-fA-F]{8})\b/g;
     while ((match = argbPattern.exec(content)) !== null) {
         out.push(normalizeHex(`#${match[1].slice(2)}`));
     }
-    // iOS Swift `Color(hex: "RRGGBB")`.
     const swiftHex = /Color\(\s*hex:\s*"#?([0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?)"/g;
     while ((match = swiftHex.exec(content)) !== null) {
         out.push(normalizeHex(`#${match[1].slice(0, 6)}`));
     }
-    // iOS Swift `Color(red: r, green: g, blue: b)` (floats or n/255).
     const swiftRgb = /(?:UI)?Color\(\s*red:\s*([\d./]+)\s*,\s*green:\s*([\d./]+)\s*,\s*blue:\s*([\d./]+)/g;
     while ((match = swiftRgb.exec(content)) !== null) {
         const r = parseColorComponent(match[1]);
@@ -1443,26 +1331,14 @@ async function collectFiles(root, max = MAX_PROTOTYPE_FILES) {
     }
     return out;
 }
-// ---------------------------------------------------------------------------
-// Host-project design-file discovery
-// ---------------------------------------------------------------------------
 const DESIGN_FILE_SKIP = new Set([
     ...SKIP_DIRS,
     "test", "tests", "__tests__", "__mocks__", "example", "examples", "sample", "samples",
     "pods", ".dart_tool", "coverage", "fastlane", "generated", "gen", "snapshots",
-    // Platform-runner dirs (Flutter/React Native) — design lives in lib/ or src/,
-    // not these. Skipping them keeps the walk from exhausting its budget before
-    // reaching the real design files in large native repos.
     "macos", "windows", "linux", "gradle",
 ]);
 const MAX_SCAN_DIRS = 60000;
 const MAX_DESIGN_FILES = 60;
-/**
- * Recursively find a project's design-source files by HIGH-SIGNAL name (not every
- * stylesheet — that would inflate noise). Real apps put these at non-standard
- * paths (e.g. `lib/v4/core/theme.dart`, `common/src/main/res/values/colors.xml`),
- * so a fixed root-relative candidate list misses them.
- */
 async function findProjectDesignFiles(root) {
     const out = [];
     const stack = [root];
@@ -1508,10 +1384,10 @@ async function isDesignFile(full) {
         return cssFileDeclaresDesignTokens(full);
     }
     if (ext === ".json") {
-        return /\.colorset\//.test(lower) && base === "contents.json"; // iOS asset-catalog color
+        return /\.colorset\//.test(lower) && base === "contents.json";
     }
     if (ext === ".swift") {
-        return /(theme|color|palette|style|appearance|design)/.test(base); // iOS design-named Swift
+        return /(theme|color|palette|style|appearance|design)/.test(base);
     }
     if (MODULE_EXTS.has(ext)) {
         if (/^tailwind\.config\.(js|ts|cjs|mjs)$/.test(base)) {
@@ -1537,18 +1413,13 @@ async function cssFileDeclaresDesignTokens(full) {
         return false;
     }
 }
-// ---------------------------------------------------------------------------
-// Contract construction
-// ---------------------------------------------------------------------------
 export function buildDesignContract(sources, sourceMeta, extraDeclaredTokens = []) {
-    // CSS bodies come from .css files plus <style> blocks inside HTML.
     const cssText = [...sources.css, ...sources.html.flatMap(extractStyleBlocks)].join("\n");
     const strippedCss = stripCssComments(cssText);
     const declarations = parseDeclarations(strippedCss);
     const inlineDeclarations = sources.html.flatMap(extractInlineStyles);
     const allDeclarations = [...declarations, ...inlineDeclarations];
     const varReferenceCounts = countVarReferences(strippedCss);
-    // --- Declared (exact) tokens: every CSS custom property. ---
     const declaredTokens = [];
     const declaredValues = new Set();
     for (const decl of declarations) {
@@ -1572,13 +1443,9 @@ export function buildDesignContract(sources, sourceMeta, extraDeclaredTokens = [
             uses: varReferenceCounts.get(decl.prop) ?? 0,
         });
     }
-    // Declared tokens from non-CSS sources (TS/JS token modules, tailwind config)
-    // are exact too. Record their values so inferred clustering won't duplicate them.
     for (const token of extraDeclaredTokens) {
         declaredValues.add(token.value);
     }
-    // Collapse duplicate declarations (CSS custom properties + module tokens),
-    // keying on category+name, keeping the highest use count.
     const declaredByName = new Map();
     for (const token of [...declaredTokens, ...extraDeclaredTokens]) {
         const key = `${token.category}::${token.name}`;
@@ -1587,11 +1454,10 @@ export function buildDesignContract(sources, sourceMeta, extraDeclaredTokens = [
             declaredByName.set(key, token);
         }
     }
-    // --- Inferred tokens: literal values observed >= INFERRED_MIN_USES times. ---
     const observations = new Map();
     for (const decl of allDeclarations) {
         if (decl.prop.startsWith("--")) {
-            continue; // declared tokens are exact, handled above
+            continue;
         }
         for (const observed of observeLiterals(decl.prop, decl.value)) {
             const key = `${observed.category}::${observed.value}`;
@@ -1607,10 +1473,10 @@ export function buildDesignContract(sources, sourceMeta, extraDeclaredTokens = [
     const inferredTokens = [];
     for (const obs of observations.values()) {
         if (obs.uses < INFERRED_MIN_USES) {
-            continue; // one-off literal, not a token
+            continue;
         }
         if (declaredValues.has(obs.value)) {
-            continue; // already represented as a declared token
+            continue;
         }
         inferredTokens.push({ category: obs.category, name: null, value: obs.value, provenance: "inferred", uses: obs.uses });
     }
@@ -1650,7 +1516,6 @@ function gradeStrength(declared, inferred) {
 export function stripCssComments(css) {
     return css.replace(/\/\*[\s\S]*?\*\//g, " ");
 }
-/** Parse declarations inside the innermost `{ ... }` rule bodies. */
 export function parseDeclarations(css) {
     const out = [];
     const bodyPattern = /\{([^{}]*)\}/g;
@@ -1722,9 +1587,6 @@ export function parseBreakpoints(css) {
     }
     return [...seen.values()].sort((a, b) => a.px - b.px || a.edge.localeCompare(b.edge));
 }
-// ---------------------------------------------------------------------------
-// Value classification
-// ---------------------------------------------------------------------------
 const COLOR_FUNCTION = /^(rgb|rgba|hsl|hsla|hwb|lab|lch|oklab|oklch|color)\(/i;
 const HEX_COLOR = /^#[0-9a-f]{3,8}$/i;
 const LENGTH = /^-?\d*\.?\d+(px|rem|em|vh|vw|%)$/i;
@@ -1748,8 +1610,6 @@ function categorizeDeclaredVar(name, value) {
     if (/radius|radii|corner|\bround/.test(n)) {
         return "radius";
     }
-    // borderWidth: name-and-value gated, MUST come before the color branch because
-    // the color regex matches /border/ — `--border-width-thin: 1px` is a length, not a color.
     if (/border-?width|stroke-?width|outline-?width/.test(n) && LENGTH.test(v)) {
         return "borderWidth";
     }
@@ -1759,46 +1619,30 @@ function categorizeDeclaredVar(name, value) {
     if (/(font-family|fontfamily|typeface|family)/.test(n) && /[a-z]/i.test(v) && !LENGTH.test(v) && !isColor(v)) {
         return "fontFamily";
     }
-    // fontSize: broaden to include the common --fs-* naming convention (e.g. --fs-sm: 14px).
-    // 'leading' and 'line-height' are moved to lineHeight below.
     if (/(font-size|fontsize|text-size)/.test(n) || /\btext-(xs|sm|base|md|lg|xl|\dxl|\d)\b/.test(n) || /^--fs-\w/.test(n)) {
-        return "fontSize"; // incl. the Tailwind text-scale convention (--text-sm/base/lg) and --fs-* shorthand
+        return "fontSize";
     }
-    // Motion is value-gated: only time/easing values become motion tokens. This
-    // stops substring matches like "increase"/"decrease" (which contain "ease")
-    // from turning a px length into a nonsensical motion token.
     if (TIME.test(v) || /cubic-bezier|steps\(/i.test(v)) {
         return "motion";
     }
     if (/(duration|easing|transition|motion|animation|\bease)/.test(n) && !LENGTH.test(v) && !isColor(v)) {
         return "motion";
     }
-    // Generic font/type hint, but only for an actual family value (not a length —
-    // e.g. "prototype" contains "type" but `--prototype-flag: 10px` is not a font).
     if (/(font|type)/.test(n) && /[a-z]/i.test(v) && !LENGTH.test(v) && !isColor(v) && !TIME.test(v)) {
         return "fontFamily";
     }
-    // fontWeight: name-gated (bare integers collide with z-index). Value must be a
-    // 3-digit integer in the valid CSS font-weight range 100–950.
     if (/\bfw\b|font-?weight|\bweight\b/.test(n)) {
         const num = Number(v);
         if (/^\d{3}$/.test(v) && num >= 100 && num <= 950) {
             return "fontWeight";
         }
     }
-    // lineHeight: name-gated + unitless value (1.1, 1.4, 1.6 etc.). Captures both
-    // 'lh-*' shorthand and 'leading-*'/'line-height-*' naming conventions.
     if (/\blh\b|leading|line-?height|lineheight/.test(n) && /^-?[0-9]*\.?[0-9]+$/.test(v) && !LENGTH.test(v)) {
         return "lineHeight";
     }
-    // letterSpacing: name-gated + any CSS length. Must come before the generic
-    // LENGTH→space fallback so --ls-* tokens aren't misfiled as spacing.
     if (/\bls\b|letter-?spacing|letterspacing|\btracking\b/.test(n) && LENGTH.test(v)) {
         return "letterSpacing";
     }
-    // breakpoint: name-gated + length. Must precede the LENGTH fallback. The
-    // contract already captures @media breakpoints in contract.breakpoints[]; this
-    // catches explicit --bp-* / --breakpoint-* custom-property tokens.
     if (/\bbp\b|break-?point|viewport-?width|screen-?size/.test(n) && LENGTH.test(v)) {
         return "breakpoint";
     }
@@ -1811,29 +1655,22 @@ function categorizeDeclaredVar(name, value) {
     if (LENGTH.test(v)) {
         return "space";
     }
-    // Opacity: declared-only (a bare 0.4 in code could be line-height/scale/anything — never infer).
     if (/opacity/.test(n) && /^(0(\.\d+)?|\.\d+|1(\.0*)?)$/.test(v)) {
         return "opacity";
     }
-    // zIndex: name-gated strictly; integers collide with fontWeight so the name is
-    // the only reliable signal. Use z-index / z-idx or the common --z-* prefix.
-    // Note: bare `/z/` would catch --zoom, --size, etc. — do NOT relax this guard.
     if ((/z-?index|z-?idx/.test(n) || /^--z-\w/.test(n)) && /^-?\d+$/.test(v)) {
         return "zIndex";
     }
     return null;
 }
-/** Emit zero or more (category, normalizedValue) observations from one literal declaration. */
 function observeLiterals(prop, value) {
     const v = value.trim();
     if (!v || v.startsWith("var(") || v === "inherit" || v === "initial" || v === "unset" || v === "none" || v === "auto") {
         return [];
     }
-    // Shadows: keep the whole declaration as one token; don't dissect inner colors/lengths.
     if (/shadow/.test(prop)) {
         return [{ category: "shadow", value: collapseSpaces(v) }];
     }
-    // Motion: durations/easing.
     if (/^(transition|animation)(-|$)/.test(prop) || TIME.test(v)) {
         if (TIME.test(v)) {
             const time = v.match(/\b\d*\.?\d+m?s\b/i);
@@ -1843,20 +1680,16 @@ function observeLiterals(prop, value) {
         }
         return [];
     }
-    // Font family.
     if (prop === "font-family") {
         return [{ category: "fontFamily", value: collapseSpaces(v) }];
     }
-    // Font size.
     if (prop === "font-size" && LENGTH.test(v)) {
         return [{ category: "fontSize", value: v.toLowerCase() }];
     }
     const out = [];
-    // Colors anywhere in the value.
     for (const color of extractColorLiterals(v)) {
         out.push({ category: "color", value: color });
     }
-    // Lengths — only meaningful as spacing/radius tokens on the relevant props.
     if (/radius/.test(prop)) {
         for (const len of extractLengths(v)) {
             out.push({ category: "radius", value: len });
@@ -1889,7 +1722,7 @@ function extractLengths(value) {
     while ((match = pattern.exec(value)) !== null) {
         const token = match[0].toLowerCase();
         if (token.startsWith("0") && (token === "0px" || token === "0rem" || token === "0em")) {
-            continue; // zero is not a spacing token
+            continue;
         }
         out.push(token);
     }
@@ -1915,7 +1748,6 @@ function normalizeValue(category, value) {
 function normalizeHex(hex) {
     let h = hex.toLowerCase();
     if (h.length === 4) {
-        // #abc -> #aabbcc
         h = `#${h[1]}${h[1]}${h[2]}${h[2]}${h[3]}${h[3]}`;
     }
     else if (h.length === 5) {
@@ -1926,9 +1758,6 @@ function normalizeHex(hex) {
 function collapseSpaces(value) {
     return value.replace(/\s+/g, " ").trim();
 }
-// ---------------------------------------------------------------------------
-// Component inference (advisory only)
-// ---------------------------------------------------------------------------
 const COMPONENT_NAME_HINTS = /(card|btn|button|avatar|badge|chip|header|footer|nav|navbar|modal|dialog|sheet|list|item|row|tile|tag|pill|toolbar|toast|banner|input|field|composer|message|bubble|post|feed|comment|reaction)/;
 const COMPONENT_MIN_USES = 3;
 function inferComponents(htmlSources, css) {
@@ -1992,9 +1821,6 @@ function friendlyComponentName(cls) {
     const hint = lower.match(COMPONENT_NAME_HINTS);
     return hint ? hint[0] : cls;
 }
-// ---------------------------------------------------------------------------
-// Sorting, summarizing, digest
-// ---------------------------------------------------------------------------
 const CATEGORY_ORDER = ["color", "space", "radius", "shadow", "fontFamily", "fontSize", "fontWeight", "lineHeight", "letterSpacing", "borderWidth", "breakpoint", "motion", "opacity", "zIndex"];
 function sortTokens(tokens) {
     return [...tokens].sort((a, b) => {
@@ -2016,7 +1842,6 @@ function summarizeTokens(tokens) {
     }
     return summary;
 }
-/** Digest over design facts only — excludes timestamps, version, and input paths so the same prototype always yields the same digest. */
 export function digestContract(contract) {
     const facts = {
         kind: contract.source.kind,
@@ -2026,17 +1851,8 @@ export function digestContract(contract) {
     };
     return `sha256:${createHash("sha256").update(stableStringify(facts)).digest("hex")}`;
 }
-// ---------------------------------------------------------------------------
-// Token-module / tailwind-config extraction (TS/JS object literals)
-// ---------------------------------------------------------------------------
-const REFERENCE_VALUE = /var\(|theme\(|calc\(|env\(/i; // references / computed — not concrete tokens
+const REFERENCE_VALUE = /var\(|theme\(|calc\(|env\(/i;
 const MODULE_LENGTH = /^-?\d*\.?\d+(px|rem|em|vh|vw|%)$/i;
-/**
- * Extract concrete declared tokens from the object literals in a TS/JS token
- * module or tailwind config. Only emits a token when the value is a concrete
- * literal we can confidently categorize — references and un-placeable values are
- * skipped (weaker, never wrong).
- */
 export function extractTokensFromModule(source) {
     const tree = tryParse("tsx", source) ?? tryParse("typescript", source);
     if (!tree) {
@@ -2046,10 +1862,6 @@ export function extractTokensFromModule(source) {
     const stack = [tree.rootNode];
     while (stack.length > 0) {
         const node = stack.pop();
-        // Kick off collection at standalone object literals (an object that is a
-        // pair's value is already captured by the parent's recursion). Seed the key
-        // path with the declared variable name so `export const spacing = {...}`
-        // carries the "spacing" category hint down to its leaf values.
         if (node.type === "object" && node.parent?.type !== "pair") {
             collectObjectStringPairs(node, seedKeyPath(node), pairs);
         }
@@ -2111,9 +1923,6 @@ function collectObjectStringPairs(node, keyPath, out) {
             collectObjectStringPairs(valueNode, [...keyPath, key], out);
         }
         else {
-            // Arrays (e.g. Tailwind fontSize: ['14px', { lineHeight }]) — take the
-            // first string-literal element (the size); numeric/unitless arrays yield
-            // nothing.
             const valueText = valueNode.type === "array" ? firstArrayStringLiteral(valueNode) : moduleStringLiteral(valueNode);
             if (valueText !== undefined) {
                 out.push({ keyPath: [...keyPath, key].join("."), value: valueText });
@@ -2145,17 +1954,12 @@ function moduleStringLiteral(node) {
     if (node.type === "string" || node.type === "template_string") {
         const text = node.text;
         if (text.includes("${")) {
-            return undefined; // interpolated — not a concrete literal
+            return undefined;
         }
         return stripQuotes(text);
     }
     return undefined;
 }
-/**
- * Android resources: `<color name="x">#hex</color>` (concrete) and
- * `<dimen name="x">16dp</dimen>`. `<item>@color/x</item>` references are
- * ignored (they aren't concrete values).
- */
 export function extractTokensFromAndroidXml(content) {
     const tokens = [];
     const seen = new Set();
@@ -2185,25 +1989,19 @@ export function extractTokensFromAndroidXml(content) {
         else if (/(text|font)/.test(key)) {
             push("fontSize", name, value);
         }
-        // unplaceable dimens are skipped (never guessed)
     }
     return tokens;
 }
 function normalizeAndroidHex(hex) {
     const h = hex.toLowerCase();
     if (h.length === 9) {
-        return `#${h.slice(3)}`; // #AARRGGBB -> #rrggbb (drop alpha)
+        return `#${h.slice(3)}`;
     }
     if (h.length === 5) {
-        return normalizeHex(`#${h.slice(2)}`); // #ARGB -> #RGB -> expand
+        return normalizeHex(`#${h.slice(2)}`);
     }
     return normalizeHex(h);
 }
-/**
- * Flutter color tokens: both `kPrimary = Color(0xAARRGGBB)` (const declarations)
- * and `primaryColor: const Color(0xAARRGGBB)` (named-parameter theme construction,
- * the common real pattern). Named `Colors.*` are not extractable.
- */
 export function extractTokensFromDart(content) {
     const tokens = [];
     const seen = new Set();
@@ -2211,7 +2009,7 @@ export function extractTokensFromDart(content) {
     let match;
     while ((match = pattern.exec(content)) !== null) {
         const name = match[1];
-        const value = `#${match[2].slice(2).toLowerCase()}`; // 0xAARRGGBB -> #rrggbb
+        const value = `#${match[2].slice(2).toLowerCase()}`;
         const key = `color::${name}::${value}`;
         if (!seen.has(key)) {
             seen.add(key);
@@ -2220,11 +2018,6 @@ export function extractTokensFromDart(content) {
     }
     return tokens;
 }
-/**
- * iOS asset catalog: `*.colorset/Contents.json` (sRGB/display-p3 components as
- * 0–255 integers, 0–1 floats, or 0xNN hex). The colorset directory name is the
- * token name. Dark-appearance variants are skipped in favor of the base color.
- */
 export function extractTokensFromColorset(contentsJson, name) {
     let parsed;
     try {
@@ -2268,7 +2061,6 @@ function parseColorComponent(raw) {
     if (!Number.isFinite(num)) {
         return null;
     }
-    // A decimal point means a 0–1 float component; a bare integer is 0–255.
     return v.includes(".") ? clampByte(Math.round(num * 255)) : clampByte(Math.round(num));
 }
 function clampByte(n) {
@@ -2277,7 +2069,6 @@ function clampByte(n) {
 function toHex2(n) {
     return n.toString(16).padStart(2, "0");
 }
-/** Swift color constants: `Color(hex: "RRGGBB")` and `Color(red: r, green: g, blue: b)` (floats or n/255). */
 export function extractTokensFromSwift(content) {
     const tokens = [];
     const seen = new Set();
@@ -2305,28 +2096,21 @@ export function extractTokensFromSwift(content) {
     }
     return tokens;
 }
-/** Conservative, FP-safe categorization for a token-module/config value. */
 function categorizeTokenModuleValue(keyPath, value) {
     const v = value.trim();
     if (!v || REFERENCE_VALUE.test(v)) {
-        return null; // reference / computed — not a concrete token
+        return null;
     }
     const key = keyPath.toLowerCase();
-    // These categories are CSS-only (declared custom properties): the name-gating
-    // that makes them safe against false positives only works in CSS. Module/native
-    // extraction skips them rather than risk inventing wrong tokens.
     if (/screen|breakpoint|media|z-?index|opacity|weight|\blh\b|leading|line-?height|letter-?spacing/.test(key)) {
         return null;
     }
-    // Colors: unambiguous from the value alone.
     if (isColor(v)) {
         return { category: "color", value: normalizeValue("color", v) };
     }
-    // Shadows: key-hinted, value carries length(s).
     if (/shadow|elevation/.test(key) && /\d/.test(v)) {
         return { category: "shadow", value: collapseSpaces(v) };
     }
-    // Lengths: only categorize when the key places them — otherwise skip (never guess).
     if (MODULE_LENGTH.test(v)) {
         if (/radius|radii|corner|\bround/.test(key)) {
             return { category: "radius", value: v.toLowerCase() };
@@ -2337,13 +2121,10 @@ function categorizeTokenModuleValue(keyPath, value) {
         if (/(font-?size|text-?size|leading|line-?height)/.test(key) ||
             /\btext-(xs|sm|base|md|lg|xl|\dxl|\d)\b/.test(key) ||
             (/(typography|font|text)/.test(key) && /(^|\.)sizes?(\.|$)/.test(key))) {
-            return { category: "fontSize", value: v.toLowerCase() }; // incl. text-scale + typography.size.* conventions
+            return { category: "fontSize", value: v.toLowerCase() };
         }
         return null;
     }
-    // Motion: cubic-bezier/steps is unambiguously an easing token (value-based,
-    // like colors) — catches keys like "smooth"/"standard" that lack an ease/-
-    // duration hint.
     if (/cubic-bezier|steps\(/i.test(v)) {
         return { category: "motion", value: collapseSpaces(v) };
     }
@@ -2356,7 +2137,6 @@ function categorizeTokenModuleValue(keyPath, value) {
     if (/(ease|easing|bezier)/.test(key) && /cubic-bezier|ease/i.test(v)) {
         return { category: "motion", value: collapseSpaces(v) };
     }
-    // Font family: key-hinted, value is a family list.
     if (/(font-?family|fontfamily|typeface|family)/.test(key) && /[a-z]/i.test(v) && !MODULE_LENGTH.test(v)) {
         return { category: "fontFamily", value: collapseSpaces(v) };
     }
@@ -2374,26 +2154,13 @@ function stableStringify(value) {
     }
     return JSON.stringify(value);
 }
-/**
- * Structural grounding helper: builds a BriefLine and throws a TypeError at
- * construction time if groundedIn is empty. This makes the grounding invariant
- * structural — an ungrounded line is impossible rather than a runtime surprise.
- */
 function line(text, groundedIn, confidence = "high") {
     if (groundedIn.length === 0) {
         throw new TypeError(`BriefLine created with empty groundedIn: "${text}"`);
     }
     return { text, groundedIn, confidence };
 }
-/**
- * Per-role keyword rules in spec-defined order.
- * Each entry: [pattern, role, confidence].
- * Rules are applied with first-match-wins semantics.
- * Compound rules (muted+text, muted+bg/surface) must precede their plain
- * counterparts so "--color-text-muted" resolves to textSecondary, not textPrimary.
- */
 const ROLE_RULES = [
-    // Compound rules — must precede their plain counterparts
     {
         test: (n) => /muted/.test(n) && /\btext\b|foreground|fg/.test(n),
         role: "textSecondary",
@@ -2406,11 +2173,6 @@ const ROLE_RULES = [
         confidence: "medium",
         reason: "name contains 'muted' and 'bg'/'surface'/'background'",
     },
-    // Noun-first compounds — in real design systems the NOUN keyword (text/surface/
-    // bg/border) sets the role family and primary/secondary act as modifiers within
-    // it: "--text-primary" is the primary BODY-TEXT color, not the action color.
-    // These must precede the plain primary/secondary rules below, or first-match-wins
-    // would misbind some of the most common token names in the wild.
     {
         test: (n) => /\btext\b|foreground|\bfg\b/.test(n) && /\bprimary\b/.test(n),
         role: "textPrimary",
@@ -2441,12 +2203,6 @@ const ROLE_RULES = [
         confidence: "medium",
         reason: "name contains a border keyword with a primary/secondary modifier — the noun keyword sets the role family",
     },
-    // Primary: plain "primary" → high; "brand"/"accent" → medium
-    // EXCLUSION: action roles bind interactive-family names only.
-    // A token whose name contains a text-family noun (text/foreground/fg) MUST
-    // NEVER bind primaryAction or secondaryAction — it represents a text colour,
-    // not an interactive accent (e.g. --text-bright-accent is a text accent, while
-    // --essential-bright-accent is the real interactive accent).
     {
         test: (n) => /\bprimary\b/.test(n) && !/brand|accent/.test(n) && !/\btext\b|foreground|\bfg\b/.test(n),
         role: "primaryAction",
@@ -2508,7 +2264,6 @@ const ROLE_RULES = [
         reason: "name contains 'avatar'",
     },
 ];
-/** Infer a (role, confidence, reason) from a token name, or null if no rule matches. */
 function inferRole(tokenName) {
     const n = tokenName.toLowerCase();
     for (const rule of ROLE_RULES) {
@@ -2518,11 +2273,6 @@ function inferRole(tokenName) {
     }
     return null;
 }
-/**
- * Among multiple candidates for the same role, prefer:
- * 1. high confidence over medium
- * 2. shorter name (e.g. "--color-primary" beats "--color-primary-hover")
- */
 function bestCandidate(a, b) {
     if (a.confidence === "high" && b.confidence !== "high")
         return a;
@@ -2530,22 +2280,8 @@ function bestCandidate(a, b) {
         return b;
     return a.token.length <= b.token.length ? a : b;
 }
-/**
- * Build a DesignBuildBrief from a DesignContract.
- *
- * - Pure: no I/O, no side effects.
- * - Never persisted or digested.
- * - Every BriefLine has non-empty groundedIn citing actual contract tokens/roles.
- * - Roles inferred from NAME only (never from value).
- * - Inferred tokens (name: null) are never cited by name; they may be cited only
- *   as a count for do/avoid prose, but only if the contract has declared color
- *   tokens with recognizable names to ground the line instead.
- */
 export function buildDesignBrief(contract) {
     const strength = contract.stats.strength;
-    // ── Role inference ──────────────────────────────────────────────────────────
-    // Walk only declared color tokens (provenance=declared, category=color, name != null).
-    // Inferred tokens always have name: null; value-only matching is forbidden.
     const colorTokens = contract.tokens.filter((t) => t.category === "color" && t.name !== null);
     const roleMap = new Map();
     for (const token of colorTokens) {
@@ -2564,26 +2300,12 @@ export function buildDesignBrief(contract) {
         roleMap.set(inferred.role, existing ? bestCandidate(existing, candidate) : candidate);
     }
     const roles = [...roleMap.values()];
-    // Helper: is a role name in this brief?
     const roleNames = new Set(roles.map((r) => r.role));
-    // String-typed version for use in contexts where we compare arbitrary strings against role names.
     const roleNameStrings = new Set(roles.map((r) => r.role));
-    // ── Component hints ─────────────────────────────────────────────────────────
-    // Reference ONLY tokens that actually exist in the contract.
-    /**
-     * Representative token selector: among a category's declared tokens, prefer
-     * (in order) a name containing "base", then "default", then "md"/"medium",
-     * then the SHORTEST name, then first-in-order.
-     *
-     * Using first-in-contract-order (old behaviour) selected unrepresentative tokens
-     * like --encore-corner-radius-smaller over --encore-corner-radius-base, causing
-     * agents to anchor on non-base variants and miss the authoritative base token.
-     */
     function representativeToken(cat) {
         const candidates = contract.tokens.filter((t) => t.category === cat && t.name !== null && t.provenance === "declared");
         if (candidates.length === 0)
             return undefined;
-        // Scoring: lower is better. 0 = base, 1 = default, 2 = md/medium, 3 = shortest, 4 = first.
         const score = (name) => {
             const n = name.toLowerCase();
             if (/\bbase\b/.test(n))
@@ -2601,18 +2323,14 @@ export function buildDesignBrief(contract) {
                 return t;
             if (ts > bs)
                 return best;
-            // Same bucket: prefer shorter name, then first-in-order (best wins ties).
             return t.name.length < best.name.length ? t : best;
         });
     }
     const radiusToken = representativeToken("radius");
     const spaceToken = representativeToken("space");
-    // Border colour: sourced from the inferred border role (a color token named *border*/*outline*/*divider*).
-    // There is no "border" TokenCategory — border colours live in the "color" category.
     const borderRoleColor = roleMap.get("border");
     const shadowToken = representativeToken("shadow");
     const primaryRole = roleMap.get("primaryAction");
-    // card hint
     const cardGuidanceLines = [];
     if (radiusToken) {
         cardGuidanceLines.push(line(`Use ${radiusToken.name} (${radiusToken.value}) for card corner radius.`, [radiusToken.name]));
@@ -2629,7 +2347,6 @@ export function buildDesignBrief(contract) {
     const cardHint = cardGuidanceLines.length > 0
         ? { kind: "card", guidance: cardGuidanceLines, confidence: radiusToken && spaceToken ? "high" : "medium" }
         : { kind: "card", absent: true, note: "No card pattern confidently identified — reuse the host app's existing card styles." };
-    // button hint
     const buttonGuidanceLines = [];
     if (primaryRole) {
         buttonGuidanceLines.push(line(`Use ${primaryRole.token} (${primaryRole.value}) as the primary button background.`, [primaryRole.role]));
@@ -2643,7 +2360,6 @@ export function buildDesignBrief(contract) {
     const buttonHint = buttonGuidanceLines.length > 0
         ? { kind: "button", guidance: buttonGuidanceLines, confidence: primaryRole ? "high" : "medium" }
         : { kind: "button", absent: true, note: "No button pattern confidently identified — reuse the host app's existing button styles." };
-    // input hint
     const inputGuidanceLines = [];
     if (borderRoleColor) {
         inputGuidanceLines.push(line(`Use ${borderRoleColor.token} for input border colour.`, [borderRoleColor.role]));
@@ -2658,60 +2374,38 @@ export function buildDesignBrief(contract) {
         ? { kind: "input", guidance: inputGuidanceLines, confidence: borderRoleColor ? "high" : "medium" }
         : { kind: "input", absent: true, note: "No input pattern confidently identified — reuse the host app's existing input styles." };
     const componentHints = [cardHint, buttonHint, inputHint];
-    // ── Do/Avoid lines ──────────────────────────────────────────────────────────
-    // Every line MUST be grounded in tokens/roles that actually exist in this brief.
     const doLines = [];
     const avoidLines = [];
-    // Only emit do/avoid lines that are grounded in actually-present tokens.
     const declaredColorTokens = colorTokens.filter((t) => t.provenance === "declared");
     const declaredSpaceTokens = contract.tokens.filter((t) => t.category === "space" && t.name !== null && t.provenance === "declared");
     const declaredRadiusTokens = contract.tokens.filter((t) => t.category === "radius" && t.name !== null && t.provenance === "declared");
-    // Do: use declared color tokens
     if (declaredColorTokens.length > 0) {
         const tokenNames = declaredColorTokens.slice(0, 3).map((t) => t.name);
         doLines.push(line(`Reference declared color tokens (e.g. ${tokenNames.join(", ")}) — never introduce new hex literals.`, tokenNames));
     }
-    // Do: use declared space tokens
     if (declaredSpaceTokens.length > 0) {
         const tokenNames = declaredSpaceTokens.slice(0, 3).map((t) => t.name);
         doLines.push(line(`Reference declared spacing tokens (e.g. ${tokenNames.join(", ")}) for margins, padding, and gaps.`, tokenNames));
     }
-    // Do: use declared radius tokens
     if (declaredRadiusTokens.length > 0) {
         const tokenNames = declaredRadiusTokens.slice(0, 2).map((t) => t.name);
         doLines.push(line(`Use declared radius tokens (e.g. ${tokenNames.join(", ")}) for corner rounding.`, tokenNames));
     }
-    // Do: use primary-role token for interactive elements
     if (primaryRole) {
         doLines.push(line(`Use the primary colour token (${primaryRole.token}) for primary interactive elements (buttons, CTAs).`, [primaryRole.role]));
     }
-    // Avoid: hex literals (grounded in declared color tokens)
     if (declaredColorTokens.length > 0) {
         const tokenNames = declaredColorTokens.slice(0, 3).map((t) => t.name);
         avoidLines.push(line(`Do not introduce new hex or colour literals — use the ${declaredColorTokens.length} declared colour token(s) (e.g. ${tokenNames.join(", ")}).`, tokenNames));
     }
-    // Avoid: raw spacing literals (grounded in declared space tokens)
     if (declaredSpaceTokens.length > 0) {
         const tokenNames = declaredSpaceTokens.slice(0, 2).map((t) => t.name);
         avoidLines.push(line(`Do not hardcode raw spacing values — use declared spacing tokens (e.g. ${tokenNames.join(", ")}).`, tokenNames));
     }
-    // Avoid: overriding the primary colour token on interactive elements
     if (primaryRole) {
         avoidLines.push(line(`Do not override the primary colour token (${primaryRole.token}) with ad-hoc colours on interactive elements.`, [primaryRole.role]));
     }
-    // ── Breadth instruction (Fix 3 — anti-anchoring) ─────────────────────────────
-    //
-    // The roles and hints above are a starting lens — a minimal named anchor set.
-    // Without an explicit instruction, agents anchor on the named tokens and stop
-    // reading the full token file. This breadth line counters that by directing the
-    // agent to the FULL declared token set, grounded in one representative token
-    // per category so the grounding itself spans the system's breadth.
-    //
-    // Grounding rule: up to one representative declared token per category present,
-    // using the representativeToken() selector (Fix 2). Only emitted when ≥1
-    // declared token exists — weak/empty contracts do NOT get an invented breadth line.
     const ALL_TOKEN_CATEGORIES = ["color", "space", "radius", "shadow", "fontFamily", "fontSize", "fontWeight", "lineHeight", "letterSpacing", "borderWidth", "breakpoint", "motion", "opacity", "zIndex"];
-    // Collect one representative declared token per category that has any declared tokens.
     const breadthGroundingTokens = [];
     for (const cat of ALL_TOKEN_CATEGORIES) {
         const rep = representativeToken(cat);
@@ -2720,11 +2414,9 @@ export function buildDesignBrief(contract) {
     }
     const totalDeclaredTokens = contract.tokens.filter((t) => t.provenance === "declared" && t.name !== null).length;
     if (breadthGroundingTokens.length > 0) {
-        // Build the grounding set (names of the representative tokens).
         const breadthGrounding = breadthGroundingTokens.map((t) => t.name);
         doLines.push(line(`The roles and hints above are a starting lens, not the full design system — reference the FULL declared token set (${totalDeclaredTokens} declared tokens) and prefer an existing token over any new value.`, breadthGrounding));
     }
-    // ── Review notes ─────────────────────────────────────────────────────────────
     const reviewNotes = [];
     if (strength === "weak") {
         reviewNotes.push("Contract is weak — very few named tokens were found. Guidance above is minimal. Run `vise design extract --from-project` to derive a richer contract from the host project's design system, or provide a prototype.");
@@ -2732,8 +2424,6 @@ export function buildDesignBrief(contract) {
     if (roles.length === 0) {
         reviewNotes.push("No colour roles could be inferred from token names. Role-based guidance is unavailable. Ensure tokens use recognisable names (e.g. --color-primary, --color-surface) and run `vise design extract --from-project` again.");
     }
-    // Suggest missing roles using name examples, not camelCase role identifiers
-    // (camelCase role names must not appear in prose to keep the weak/neutral brief JSON clean).
     if (!roleNames.has("primaryAction") && contract.stats.declared_tokens > 0) {
         reviewNotes.push("No primary action colour found — consider naming a token --color-primary (or --color-brand / --color-accent) for primary interactive elements.");
     }
@@ -2743,19 +2433,12 @@ export function buildDesignBrief(contract) {
     if (!roleNames.has("border") && contract.stats.declared_tokens > 0) {
         reviewNotes.push("No border colour found — consider naming a token --color-border or --color-outline.");
     }
-    // Conservative-inference reviewNote (Fix 3):
-    // When roles bind fewer than half the declared COLOR tokens, the role inference
-    // was conservative on this vocabulary (e.g. Encore's essential-/decorative-
-    // prefixed names are correct restraint but result in thin role coverage).
-    // Alert the agent that it MUST read the full token file rather than relying on roles alone.
     const declaredColorCount = declaredColorTokens.length;
     const colorTokensBoundToRoles = roles.filter((r) => declaredColorTokens.some((t) => t.name === r.token)).length;
     if (declaredColorCount > 0 && colorTokensBoundToRoles < declaredColorCount / 2) {
         reviewNotes.push(`Role inference was conservative on this vocabulary — only ${colorTokensBoundToRoles} of ${declaredColorCount} declared colour token(s) are bound to roles. The full token file must be read to discover the complete colour system.`);
     }
-    // ── Summary ──────────────────────────────────────────────────────────────────
     const tokenCount = contract.tokens.filter((t) => t.name !== null).length;
-    // Count how many distinct declared token names are referenced by roles + hints.
     const briefReferencedTokenNames = new Set();
     for (const r of roles)
         briefReferencedTokenNames.add(r.token);
@@ -2763,7 +2446,6 @@ export function buildDesignBrief(contract) {
         if (!("absent" in h)) {
             for (const l of h.guidance) {
                 for (const g of l.groundedIn) {
-                    // Only add entries that are actual declared token names (not role names).
                     if (!roleNameStrings.has(g))
                         briefReferencedTokenNames.add(g);
                 }
@@ -2786,26 +2468,14 @@ export function buildDesignBrief(contract) {
         reviewNotes,
     };
 }
-/**
- * Build outcome-specific design recipe items grounded in an existing brief.
- *
- * HARD INVARIANT: every item is grounded ONLY in roles/tokens already in the brief.
- * Items for absent roles are silently omitted. Returns `undefined` when zero items
- * can be grounded (e.g. empty brief).
- *
- * Pure — no I/O, no side effects. Generated at plan time; never persisted.
- */
 export function buildOutcomeDesignRecipe(brief, outcome) {
     const roleMap = new Map(brief.roles.map((r) => [r.role, r]));
-    // Collect groundedIn entries from a given component hint (absent hints contribute nothing).
     const hintGrounding = (kind) => {
         const hint = brief.componentHints.find((h) => h.kind === kind);
         if (!hint || "absent" in hint)
             return [];
         return hint.guidance.flatMap((l) => l.groundedIn);
     };
-    // Collect radius-specific grounding from the card hint by looking for guidance
-    // lines that mention "corner radius" — avoids mis-citing a space token as radius.
     const cardRadiusGrounding = () => {
         const hint = brief.componentHints.find((h) => h.kind === "card");
         if (!hint || "absent" in hint)
@@ -2816,30 +2486,24 @@ export function buildOutcomeDesignRecipe(brief, outcome) {
     };
     const items = [];
     if (outcome === "add-feed") {
-        // Composer / action button — only when primaryAction exists.
         const primaryAction = roleMap.get("primaryAction");
         if (primaryAction) {
             items.push(line(`The post composer action button uses the primary action colour token (${primaryAction.token}).`, ["primaryAction"]));
         }
-        // Post cards — only when the card hint has grounding tokens.
         const cardGrounding = hintGrounding("card");
         if (cardGrounding.length > 0) {
             items.push(line("Post cards follow the card component hint: apply the card hint tokens for corner radius, padding, and border/shadow.", cardGrounding));
         }
-        // Post metadata and timestamps.
         const textSecondary = roleMap.get("textSecondary");
         if (textSecondary) {
             items.push(line(`Post metadata and timestamps use the secondary text colour token (${textSecondary.token}).`, ["textSecondary"]));
         }
-        // Report / delete affordances.
         const danger = roleMap.get("danger");
         if (danger) {
             items.push(line(`Report and delete affordances use the danger colour token (${danger.token}).`, ["danger"]));
         }
     }
     else {
-        // add-chat
-        // Message bubbles use surface.
         const surface = roleMap.get("surface");
         if (surface) {
             const radiusGrounding = cardRadiusGrounding();
@@ -2850,33 +2514,23 @@ export function buildOutcomeDesignRecipe(brief, outcome) {
                 items.push(line(`Message bubbles use the surface colour token (${surface.token}).`, ["surface"]));
             }
         }
-        // Own-message vs other-message contrast — ONLY when BOTH primaryAction AND surface exist.
         const primaryAction = roleMap.get("primaryAction");
         if (primaryAction && surface) {
             items.push(line(`Own messages use the primary action colour (${primaryAction.token}) as background; other messages use the surface colour (${surface.token}).`, ["primaryAction", "surface"]));
         }
-        // Timestamps.
         const textSecondary = roleMap.get("textSecondary");
         if (textSecondary) {
             items.push(line(`Message timestamps use the secondary text colour token (${textSecondary.token}).`, ["textSecondary"]));
         }
-        // Composer follows the input hint tokens.
         const inputGrounding = hintGrounding("input");
         if (inputGrounding.length > 0) {
             items.push(line("The message composer follows the input component hint: apply the input hint tokens for border colour, corner radius, and padding.", inputGrounding));
         }
-        // Moderation actions.
         const danger = roleMap.get("danger");
         if (danger) {
             items.push(line(`Moderation actions (report, block, mute) use the danger colour token (${danger.token}).`, ["danger"]));
         }
     }
-    // Breadth audit item (Fix 3 — anti-anchoring):
-    // Append a final item instructing the agent to audit against the FULL token set.
-    // Grounded the same way as the brief's breadth do-line: reuse the groundedIn of
-    // the "starting lens" do-line if it exists in the brief (spans the breadth of
-    // the system's categories). Only emitted when the brief has declared tokens
-    // (the breadth do-line only exists when there are declared tokens).
     const breadthDoLine = brief.do.find((l) => l.text.includes("starting lens"));
     if (breadthDoLine) {
         items.push(line("Before finishing, audit the UI against the full declared token set and replace any near-miss values with the matching token.", breadthDoLine.groundedIn));