@amityco/social-plus-vise 0.8.1 → 0.12.2

package/dist/tools/design.js

@@ -0,0 +1,1496 @@
+import { createHash } from "node:crypto";
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+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";
+/** 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"]);
+// ---------------------------------------------------------------------------
+// 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).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            prototypePath: { type: "string", description: "Path to an HTML/CSS prototype file or a directory of them. Omit when fromProject is true." },
+            fromProject: { type: "boolean", description: "Derive the contract from the host project's own detected design system (no external prototype). Uses repoPath as the project root." },
+            repoPath: { type: "string", description: "Project root: the sp-vise/ sidecar to write, and (with fromProject) the design system to read. Defaults to the current directory." },
+            write: { type: "boolean", description: "Write sp-vise/design-contract.json (default true). When false, only returns the contract." },
+        },
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        const fromProject = args.fromProject === true;
+        const repoPath = optionalStringField(args, "repoPath") ?? ".";
+        const write = args.write !== false;
+        const contract = fromProject ? await extractDesignContractFromProject(repoPath) : await extractDesignContract(stringField(args, "prototypePath"));
+        let written;
+        if (write) {
+            written = await writeDesignContract(repoPath, contract);
+        }
+        const empty = contract.source.file_count === 0;
+        return textResult({
+            status: empty ? "no-input" : "extracted",
+            source: contract.source.kind,
+            written,
+            digest: contract.digest,
+            strength: contract.stats.strength,
+            stats: contract.stats,
+            sources: contract.source.inputs,
+            tokenSummary: summarizeTokens(contract.tokens),
+            breakpoints: contract.breakpoints.map((bp) => bp.raw),
+            components: contract.components.map((component) => component.name),
+            guidance: empty
+                ? fromProject
+                    ? "No design system detected in this project (no theme/token module, tailwind config with concrete values, or CSS custom properties). Ask the customer for a prototype, or point to their design source."
+                    : "No HTML/CSS found at the prototype path. Pass a path to a prototype file or a directory containing one."
+                : contract.stats.strength === "weak"
+                    ? "Weak contract: few named tokens were found. Generated UI can use the inferred tokens as advisory guidance; confirm brand values with the customer."
+                    : `${fromProject ? "Derived from the host project's own design system. " : ""}Build the feed using the declared tokens, fall back to inferred tokens as advisory, and record the contract digest at attestation time.`,
+            where: written ? `Design contract written to ${written}.` : "Contract not written (write=false).",
+        });
+    },
+};
+export async function extractDesignContract(prototypePath) {
+    const resolved = path.resolve(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);
+    const css = [];
+    const moduleTokens = [];
+    const inputs = [];
+    for (const abs of files) {
+        const ext = path.extname(abs).toLowerCase();
+        const rel = path.relative(root, abs);
+        let content;
+        try {
+            const info = await stat(abs);
+            if (info.size > MAX_FILE_BYTES) {
+                continue;
+            }
+            content = await readFile(abs, "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (ext === ".css" || ext === ".scss") {
+            css.push(content);
+            inputs.push(rel);
+        }
+        else if (MODULE_EXTS.has(ext)) {
+            const tokens = extractTokensFromModule(content);
+            if (tokens.length > 0) {
+                moduleTokens.push(...tokens);
+                inputs.push(rel);
+            }
+        }
+        else if (ext === ".xml") {
+            const tokens = extractTokensFromAndroidXml(content);
+            if (tokens.length > 0) {
+                moduleTokens.push(...tokens);
+                inputs.push(rel);
+            }
+        }
+        else if (ext === ".dart") {
+            const tokens = extractTokensFromDart(content);
+            if (tokens.length > 0) {
+                moduleTokens.push(...tokens);
+                inputs.push(rel);
+            }
+        }
+        else if (ext === ".json") {
+            const name = path.basename(path.dirname(abs)).replace(/\.colorset$/i, "");
+            const tokens = extractTokensFromColorset(content, name);
+            if (tokens.length > 0) {
+                moduleTokens.push(...tokens);
+                inputs.push(rel);
+            }
+        }
+        else if (ext === ".swift") {
+            const tokens = extractTokensFromSwift(content);
+            if (tokens.length > 0) {
+                moduleTokens.push(...tokens);
+                inputs.push(rel);
+            }
+        }
+    }
+    inputs.sort();
+    return buildDesignContract({ css, html: [], inputs }, { kind: "host-project", inputs, file_count: inputs.length }, moduleTokens);
+}
+export async function writeDesignContract(repoPath, contract) {
+    const sidecarDir = path.join(path.resolve(repoPath), "sp-vise");
+    await mkdir(sidecarDir, { recursive: true });
+    const target = path.join(sidecarDir, DESIGN_CONTRACT_FILENAME);
+    await writeFile(target, `${JSON.stringify(contract, null, 2)}\n`, "utf8");
+    return target;
+}
+export async function readDesignContract(repoPath) {
+    const target = path.join(path.resolve(repoPath), "sp-vise", DESIGN_CONTRACT_FILENAME);
+    try {
+        const raw = await readFile(target, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object" && Array.isArray(parsed.tokens)) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// 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.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repoPath: { type: "string", description: "Project root containing sp-vise/design-contract.json. Defaults to the current directory." },
+            reference: { type: "string", description: "Optional path to the HTML/CSS prototype to embed for side-by-side visual comparison." },
+            write: { type: "boolean", description: "Write sp-vise/design-preview.html (default true)." },
+        },
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        const repoPath = optionalStringField(args, "repoPath") ?? ".";
+        const referencePath = optionalStringField(args, "reference");
+        const write = args.write !== false;
+        const contract = await readDesignContract(repoPath);
+        if (!contract) {
+            return textResult({
+                status: "no-contract",
+                message: "No sp-vise/design-contract.json found. Run `vise design extract` (or `--from-project`) first.",
+            });
+        }
+        const check = await runDesignCheck(repoPath).catch(() => null);
+        const reference = referencePath ? await readReferenceHtml(referencePath) : null;
+        const html = renderDesignPreview(contract, check && check.status === "advisory" ? check : null, reference);
+        let written;
+        if (write) {
+            const target = path.join(path.resolve(repoPath), "sp-vise", "design-preview.html");
+            await mkdir(path.dirname(target), { recursive: true });
+            await writeFile(target, html, "utf8");
+            written = target;
+        }
+        return textResult({
+            status: "rendered",
+            written,
+            digest: contract.digest,
+            strength: contract.stats.strength,
+            referenceEmbedded: Boolean(reference),
+            conformance: check && check.status === "advisory" ? { coverage: `${check.tokenCoverage?.referenced}/${check.tokenCoverage?.declared_total}`, off_contract: check.colorLiterals?.off_contract } : "no UI code scanned",
+            note: "Open the HTML to visually compare the contract (and embedded reference, if HTML) against your app. A human or VLM judges the visual match — this is not an automated pixel diff.",
+            where: written ? `Open ${written} in a browser.` : "Not written (write=false).",
+        });
+    },
+};
+/** 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;
+    try {
+        const info = await stat(resolved);
+        if (info.isDirectory()) {
+            const files = await collectFiles(resolved, 200);
+            htmlFile = files.find((f) => /\.html?$/i.test(f)) ?? null;
+        }
+        else if (/\.html?$/i.test(resolved)) {
+            htmlFile = resolved;
+        }
+    }
+    catch {
+        return null;
+    }
+    if (!htmlFile) {
+        return null;
+    }
+    let html;
+    try {
+        const info = await stat(htmlFile);
+        if (info.size > MAX_FILE_BYTES) {
+            return null;
+        }
+        html = await readFile(htmlFile, "utf8");
+    }
+    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)
+        }
+        try {
+            const cssPath = path.join(dir, href);
+            const css = await readFile(cssPath, "utf8");
+            html = html.replace(link[0], `<style>\n${css}\n</style>`);
+        }
+        catch {
+            // leave the link; missing CSS just won't apply
+        }
+    }
+    return html;
+}
+export function renderDesignPreview(contract, check, referenceHtml) {
+    const byCat = (category) => contract.tokens.filter((t) => t.category === category);
+    const tokenRow = (t, sample) => `<div class="tok">${sample}<div class="meta"><code>${esc(t.name ?? "—")}</code><code class="val">${esc(t.value)}</code>${t.provenance === "inferred" ? '<span class="inf">inferred</span>' : ""}</div></div>`;
+    const colors = byCat("color").map((t) => tokenRow(t, `<span class="sw" style="background:${safeCss(t.value)}"></span>`)).join("");
+    const spaces = byCat("space").map((t) => tokenRow(t, `<span class="bar" style="width:${safeCss(t.value)}"></span>`)).join("");
+    const radii = byCat("radius").map((t) => tokenRow(t, `<span class="box" style="border-radius:${safeCss(t.value)}"></span>`)).join("");
+    const shadows = byCat("shadow").map((t) => tokenRow(t, `<span class="box" style="box-shadow:${safeCss(t.value)}"></span>`)).join("");
+    const fonts = byCat("fontFamily").map((t) => tokenRow(t, `<span class="type" style="font-family:${safeCss(t.value)}">Ag</span>`)).join("");
+    const sizes = byCat("fontSize").map((t) => tokenRow(t, `<span class="type" style="font-size:${safeCss(t.value)}">Ag</span>`)).join("");
+    const motions = byCat("motion").map((t) => tokenRow(t, `<span class="mo">${esc(t.value)}</span>`)).join("");
+    const group = (title, body) => (body ? `<h2>${esc(title)}</h2><div class="grid">${body}</div>` : "");
+    const reference = referenceHtml
+        ? `<iframe class="ref" sandbox="allow-same-origin" srcdoc="${escAttr(referenceHtml)}" title="reference prototype"></iframe>`
+        : `<p class="muted">No renderable HTML reference. (Host-project / native sources — Android XML, Flutter, iOS — can't be rendered dependency-free; review the swatches against your app by eye.)</p>`;
+    let conformance = `<p class="muted">No UI code scanned against the contract (run in a project that has both the contract and source).</p>`;
+    if (check) {
+        const cov = check.tokenCoverage;
+        const cl = check.colorLiterals;
+        const off = (cl?.sample ?? []).map((s) => `<li><code>${esc(s.value)}</code> <span class="muted">${esc(s.file)}</span></li>`).join("");
+        const undef = (check.undefinedTokenRefs?.sample ?? []).map((s) => `<li><code>${esc(s.token)}</code> <span class="muted">${esc(s.file)}</span></li>`).join("");
+        conformance =
+            `<p><b>${cov?.referenced}/${cov?.declared_total}</b> declared tokens referenced &middot; <b>${cl?.off_contract}</b> of ${cl?.total} color literals off-contract${(check.undefinedTokenRefs?.count ?? 0) > 0 ? ` &middot; <b>${check.undefinedTokenRefs?.count}</b> undefined token refs` : ""}.</p>` +
+                (cov?.unreferenced_tokens.length ? `<p class="muted">Unreferenced: ${cov.unreferenced_tokens.map((t) => `<code>${esc(t)}</code>`).join(" ")}</p>` : "") +
+                (off ? `<p>Off-contract color literals (review — one-offs like scrims are fine):</p><ul>${off}</ul>` : "") +
+                (undef ? `<p>Undefined token references (likely broken styles):</p><ul>${undef}</ul>` : "");
+    }
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Vise design preview — ${esc(contract.digest.slice(0, 16))}</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { font: 14px/1.5 -apple-system, system-ui, sans-serif; margin: 0; padding: 24px; max-width: 1100px; margin: 0 auto; }
+  header { border-bottom: 1px solid #8884; padding-bottom: 12px; margin-bottom: 20px; }
+  h1 { font-size: 20px; margin: 0 0 4px; } h2 { font-size: 15px; margin: 24px 0 8px; text-transform: uppercase; letter-spacing: .04em; opacity: .7; }
+  .badge { display: inline-block; padding: 2px 8px; border-radius: 999px; background: #8882; font-size: 12px; margin-right: 6px; }
+  .advisory { background: #f5a62333; padding: 8px 12px; border-radius: 8px; font-size: 13px; margin: 12px 0; }
+  .grid { display: flex; flex-wrap: wrap; gap: 12px; }
+  .tok { display: flex; flex-direction: column; gap: 6px; min-width: 90px; }
+  .meta { display: flex; flex-direction: column; gap: 1px; } .meta code { font-size: 11px; } .val { opacity: .7; } .inf { font-size: 10px; opacity: .6; }
+  .sw { width: 64px; height: 48px; border-radius: 6px; border: 1px solid #8883; display: block; }
+  .bar { height: 16px; background: #6a9; display: block; max-width: 200px; border-radius: 3px; }
+  .box { width: 64px; height: 48px; background: #fff; border: 1px solid #8883; display: block; }
+  .type { font-size: 28px; display: block; } .mo { font-family: monospace; }
+  iframe.ref { width: 100%; height: 520px; border: 1px solid #8884; border-radius: 8px; background: #fff; }
+  .cols { display: grid; grid-template-columns: 1fr 1fr; gap: 20px; align-items: start; }
+  @media (max-width: 800px) { .cols { grid-template-columns: 1fr; } }
+  .muted { opacity: .6; } code { background: #8881; padding: 1px 4px; border-radius: 3px; }
+  ul { margin: 4px 0; padding-left: 18px; }
+</style></head>
+<body>
+<header>
+  <h1>Design preview &amp; conformance</h1>
+  <div><span class="badge">${esc(contract.source.kind)}</span><span class="badge">strength: ${esc(contract.stats.strength)}</span><span class="badge">${contract.stats.declared_tokens} declared + ${contract.stats.inferred_tokens} inferred</span><code>${esc(contract.digest)}</code></div>
+  <div class="advisory">Advisory artifact. Vise renders the contract; <b>a human or VLM judges the visual match</b> against the reference and your app. This is not an automated pixel diff.</div>
+</header>
+<div class="cols">
+  <div><h2>Reference prototype</h2>${reference}</div>
+  <div><h2>Conformance (design check)</h2>${conformance}</div>
+</div>
+${group("Colors", colors)}
+${group("Spacing", spaces)}
+${group("Radius", radii)}
+${group("Shadow", shadows)}
+${group("Type — families", fonts)}
+${group("Type — sizes", sizes)}
+${group("Motion", motions)}
+</body></html>`;
+}
+function esc(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+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);
+}
+const ADVISORY_NOTE = "Advisory only — non-blocking and NOT part of `vise check`. One-off literals (overlays, scrims, pure #fff/#000, gradients) are expected and fine; off-contract literals are review hints, not violations.";
+export const designCheckTool = {
+    name: "design_check",
+    description: "Advisory (non-blocking) report on how closely the project's UI code matches the extracted design contract. Never fails a build; not a `vise check` gate.",
+    inputSchema: {
+        type: "object",
+        properties: { repoPath: { type: "string", description: "Project root containing sp-vise/design-contract.json. Defaults to the current directory." } },
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        return textResult(await runDesignCheck(optionalStringField(args, "repoPath") ?? "."));
+    },
+};
+export async function runDesignCheck(repoPath) {
+    const repoRoot = path.resolve(repoPath);
+    const contract = await readDesignContract(repoRoot);
+    if (!contract) {
+        return {
+            status: "no-contract",
+            message: "No sp-vise/design-contract.json found. Run `vise design extract <prototype>` first, or rely on the host project's own design system (`vise inspect` lists detected design signals).",
+            note: ADVISORY_NOTE,
+        };
+    }
+    const files = (await collectFiles(repoRoot, MAX_SCAN_FILES)).filter((file) => SCAN_EXTS.has(path.extname(file).toLowerCase()));
+    if (files.length === 0) {
+        return { status: "no-sources", message: "No UI source files found to check against the contract.", contract: contractSummary(contract), note: ADVISORY_NOTE };
+    }
+    const declaredTokens = contract.tokens.filter((token) => token.provenance === "declared");
+    const contractColorValues = new Set(contract.tokens.filter((token) => token.category === "color").map((token) => token.value));
+    const referenced = new Set();
+    const colorSample = [];
+    const definedVars = new Set();
+    const varRefs = [];
+    let totalColors = 0;
+    let onContract = 0;
+    let scanned = 0;
+    for (const file of files) {
+        let content;
+        try {
+            const info = await stat(file);
+            if (info.size > MAX_FILE_BYTES) {
+                continue;
+            }
+            content = await readFile(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        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)) {
+                continue;
+            }
+            if ((token.name && content.includes(token.name)) || content.includes(token.value)) {
+                referenced.add(key);
+            }
+        }
+        // Raw color literals: counted, then classified on/off contract.
+        for (const value of scanColorLiterals(content)) {
+            totalColors += 1;
+            if (contractColorValues.has(value)) {
+                onContract += 1;
+            }
+            else if (colorSample.length < OFF_CONTRACT_SAMPLE) {
+                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 });
+        }
+        if (isCss) {
+            for (const name of scanVarDefinitions(content)) {
+                definedVars.add(name);
+            }
+        }
+    }
+    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 {
+        status: "advisory",
+        message: `Checked ${scanned} source file(s) against design contract ${contract.digest}. ` +
+            `${referencedTokens.length}/${declaredTokens.length} declared tokens referenced; ${totalColors - onContract} of ${totalColors} color literal(s) are off-contract (review hints)` +
+            (undefinedRefs.length > 0 ? `; ${undefinedRefs.length} undefined token reference(s) (likely broken styles)` : "") +
+            ".",
+        contract: contractSummary(contract),
+        tokenCoverage: {
+            declared_total: declaredTokens.length,
+            referenced: referencedTokens.length,
+            referenced_tokens: referencedTokens,
+            unreferenced_tokens: unreferencedTokens,
+        },
+        colorLiterals: {
+            scanned_files: scanned,
+            total: totalColors,
+            on_contract: onContract,
+            off_contract: totalColors - onContract,
+            sample: colorSample,
+        },
+        undefinedTokenRefs: {
+            count: undefinedRefs.length,
+            sample: undefinedRefs.slice(0, OFF_CONTRACT_SAMPLE),
+        },
+        note: ADVISORY_NOTE,
+    };
+}
+function dedupeByToken(refs) {
+    const seen = new Set();
+    const out = [];
+    for (const ref of refs) {
+        if (!seen.has(ref.token)) {
+            seen.add(ref.token);
+            out.push(ref);
+        }
+    }
+    return out.sort((a, b) => a.token.localeCompare(b.token));
+}
+function scanVarReferences(content) {
+    const out = [];
+    const pattern = /var\(\s*(--[\w-]+)/g;
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+        out.push(match[1]);
+    }
+    return out;
+}
+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) {
+        out.push(match[1]);
+    }
+    return out;
+}
+function contractSummary(contract) {
+    return {
+        digest: contract.digest,
+        strength: contract.stats.strength,
+        declared_tokens: contract.stats.declared_tokens,
+        inferred_tokens: contract.stats.inferred_tokens,
+    };
+}
+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]);
+        const g = parseColorComponent(match[2]);
+        const b = parseColorComponent(match[3]);
+        if (r !== null && g !== null && b !== null) {
+            out.push(`#${toHex2(r)}${toHex2(g)}${toHex2(b)}`);
+        }
+    }
+    return out;
+}
+async function readPrototypeSources(resolved) {
+    const css = [];
+    const html = [];
+    const inputs = [];
+    let isDir = false;
+    try {
+        isDir = (await stat(resolved)).isDirectory();
+    }
+    catch {
+        return { css, html, inputs };
+    }
+    const files = isDir ? await collectFiles(resolved) : [resolved];
+    for (const file of files) {
+        const ext = path.extname(file).toLowerCase();
+        if (ext !== ".css" && ext !== ".scss" && ext !== ".html" && ext !== ".htm") {
+            continue;
+        }
+        let content;
+        try {
+            const info = await stat(file);
+            if (info.size > MAX_FILE_BYTES) {
+                continue;
+            }
+            content = await readFile(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        inputs.push(isDir ? path.relative(resolved, file) : path.basename(file));
+        if (ext === ".css" || ext === ".scss") {
+            css.push(content);
+        }
+        else {
+            html.push(content);
+        }
+    }
+    inputs.sort();
+    return { css, html, inputs };
+}
+async function collectFiles(root, max = MAX_PROTOTYPE_FILES) {
+    const out = [];
+    const stack = [root];
+    while (stack.length > 0 && out.length < max) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (out.length >= max) {
+                break;
+            }
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith(".")) {
+                    stack.push(full);
+                }
+            }
+            else if (entry.isFile()) {
+                out.push(full);
+            }
+        }
+    }
+    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];
+    let visited = 0;
+    while (stack.length > 0 && out.length < MAX_DESIGN_FILES && visited < MAX_SCAN_DIRS) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            visited += 1;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!DESIGN_FILE_SKIP.has(entry.name) && !entry.name.startsWith(".")) {
+                    stack.push(full);
+                }
+            }
+            else if (entry.isFile() && isDesignFile(full)) {
+                out.push(full);
+            }
+        }
+    }
+    return out.sort();
+}
+function isDesignFile(full) {
+    const lower = full.replace(/\\/g, "/").toLowerCase();
+    const base = path.basename(lower);
+    const ext = path.extname(lower);
+    if (ext === ".xml") {
+        return /\/values(-[a-z0-9-]+)?\//.test(lower) && /^(colors|themes|dimens|styles)\.xml$/.test(base);
+    }
+    if (ext === ".dart") {
+        return /\/lib\//.test(lower) && /(theme|color|token|palette)/.test(base);
+    }
+    if (ext === ".css" || ext === ".scss") {
+        return base === "globals.css" || /(theme|token|design)/.test(base);
+    }
+    if (ext === ".json") {
+        return /\.colorset\//.test(lower) && base === "contents.json"; // iOS asset-catalog color
+    }
+    if (ext === ".swift") {
+        return /(theme|color|palette|style|appearance|design)/.test(base); // iOS design-named Swift
+    }
+    if (MODULE_EXTS.has(ext)) {
+        if (/^tailwind\.config\.(js|ts|cjs|mjs)$/.test(base)) {
+            return true;
+        }
+        if (/^(theme|tokens|design-tokens|colors|palette)\.(ts|tsx|js|jsx|mjs|cjs)$/.test(base)) {
+            return true;
+        }
+        return /\/(theme|tokens)\/index\.(ts|tsx|js|jsx)$/.test(lower);
+    }
+    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) {
+        if (!decl.prop.startsWith("--")) {
+            continue;
+        }
+        const category = categorizeDeclaredVar(decl.prop, decl.value);
+        if (!category) {
+            continue;
+        }
+        const value = normalizeValue(category, decl.value);
+        if (!value) {
+            continue;
+        }
+        declaredValues.add(value);
+        declaredTokens.push({
+            category,
+            name: decl.prop,
+            value,
+            provenance: "declared",
+            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}`;
+        const existing = declaredByName.get(key);
+        if (!existing || token.uses > existing.uses) {
+            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
+        }
+        for (const observed of observeLiterals(decl.prop, decl.value)) {
+            const key = `${observed.category}::${observed.value}`;
+            const existing = observations.get(key);
+            if (existing) {
+                existing.uses += 1;
+            }
+            else {
+                observations.set(key, { ...observed, uses: 1 });
+            }
+        }
+    }
+    const inferredTokens = [];
+    for (const obs of observations.values()) {
+        if (obs.uses < INFERRED_MIN_USES) {
+            continue; // one-off literal, not a token
+        }
+        if (declaredValues.has(obs.value)) {
+            continue; // already represented as a declared token
+        }
+        inferredTokens.push({ category: obs.category, name: null, value: obs.value, provenance: "inferred", uses: obs.uses });
+    }
+    const tokens = sortTokens([...declaredByName.values(), ...inferredTokens]);
+    const breakpoints = parseBreakpoints(strippedCss);
+    const components = inferComponents(sources.html, strippedCss);
+    const declaredCount = tokens.filter((token) => token.provenance === "declared").length;
+    const inferredCount = tokens.filter((token) => token.provenance === "inferred").length;
+    const contract = {
+        schema_version: DESIGN_CONTRACT_SCHEMA_VERSION,
+        foundry_version: packageVersion,
+        source: sourceMeta,
+        digest: "",
+        tokens,
+        breakpoints,
+        components,
+        stats: {
+            declared_tokens: declaredCount,
+            inferred_tokens: inferredCount,
+            advisory_components: components.length,
+            strength: gradeStrength(declaredCount, inferredCount),
+        },
+    };
+    contract.digest = digestContract(contract);
+    return contract;
+}
+function gradeStrength(declared, inferred) {
+    if (declared >= 6) {
+        return "strong";
+    }
+    if (declared >= 1 || inferred >= 4) {
+        return "partial";
+    }
+    return "weak";
+}
+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;
+    let match;
+    while ((match = bodyPattern.exec(css)) !== null) {
+        out.push(...splitDeclarations(match[1] ?? ""));
+    }
+    return out;
+}
+function splitDeclarations(body) {
+    const out = [];
+    for (const chunk of body.split(";")) {
+        const idx = chunk.indexOf(":");
+        if (idx <= 0) {
+            continue;
+        }
+        const prop = chunk.slice(0, idx).trim().toLowerCase();
+        const value = chunk.slice(idx + 1).trim();
+        if (!prop || !value || /[{}]/.test(prop)) {
+            continue;
+        }
+        out.push({ prop, value });
+    }
+    return out;
+}
+function countVarReferences(css) {
+    const counts = new Map();
+    const pattern = /var\(\s*(--[\w-]+)/g;
+    let match;
+    while ((match = pattern.exec(css)) !== null) {
+        const name = match[1];
+        counts.set(name, (counts.get(name) ?? 0) + 1);
+    }
+    return counts;
+}
+export function extractStyleBlocks(html) {
+    const out = [];
+    const pattern = /<style[^>]*>([\s\S]*?)<\/style>/gi;
+    let match;
+    while ((match = pattern.exec(html)) !== null) {
+        out.push(match[1] ?? "");
+    }
+    return out;
+}
+export function extractInlineStyles(html) {
+    const out = [];
+    const pattern = /style\s*=\s*("([^"]*)"|'([^']*)')/gi;
+    let match;
+    while ((match = pattern.exec(html)) !== null) {
+        const body = match[2] ?? match[3] ?? "";
+        out.push(...splitDeclarations(body));
+    }
+    return out;
+}
+export function parseBreakpoints(css) {
+    const seen = new Map();
+    const pattern = /\(\s*(min|max)-width\s*:\s*([\d.]+)(px|em|rem)\s*\)/gi;
+    let match;
+    while ((match = pattern.exec(css)) !== null) {
+        const edge = match[1].toLowerCase();
+        const num = Number(match[2]);
+        const unit = match[3].toLowerCase();
+        if (!Number.isFinite(num)) {
+            continue;
+        }
+        const px = unit === "px" ? num : num * 16;
+        const raw = `(${edge}-width: ${match[2]}${unit})`;
+        seen.set(`${edge}:${px}`, { edge, px, raw });
+    }
+    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;
+const TIME = /\b\d*\.?\d+m?s\b/i;
+const NAMED_COLORS = new Set([
+    "black", "white", "red", "green", "blue", "yellow", "orange", "purple", "pink", "gray", "grey",
+    "transparent", "currentcolor", "silver", "maroon", "navy", "teal", "olive", "lime", "aqua", "fuchsia",
+    "indigo", "violet", "gold", "coral", "salmon", "crimson", "tomato", "slategray", "slategrey",
+]);
+const SPACING_PROPS = /^(padding|margin|gap|row-gap|column-gap|inset|top|right|bottom|left)(-|$)/;
+function isColor(value) {
+    const trimmed = value.trim();
+    return HEX_COLOR.test(trimmed) || COLOR_FUNCTION.test(trimmed) || NAMED_COLORS.has(trimmed.toLowerCase());
+}
+function categorizeDeclaredVar(name, value) {
+    const n = name.toLowerCase();
+    const v = value.trim();
+    if (/shadow|elevation/.test(n)) {
+        return "shadow";
+    }
+    if (/radius|radii|corner|\bround/.test(n)) {
+        return "radius";
+    }
+    if (/(color|colour|bg|background|fg|foreground|surface|border|brand|primary|secondary|accent|fill|stroke|ink|text-color)/.test(n) || isColor(v)) {
+        return "color";
+    }
+    if (/(font-family|fontfamily|typeface|family)/.test(n) && /[a-z]/i.test(v) && !LENGTH.test(v) && !isColor(v)) {
+        return "fontFamily";
+    }
+    if (/(font-size|fontsize|text-size|leading|line-height)/.test(n) || /\btext-(xs|sm|base|md|lg|xl|\dxl|\d)\b/.test(n)) {
+        return "fontSize"; // incl. the Tailwind text-scale convention (--text-sm/base/lg)
+    }
+    // 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";
+    }
+    if (/(space|spacing|gap|size|gutter|inset|pad|margin)/.test(n) && LENGTH.test(v)) {
+        return "space";
+    }
+    if (isColor(v)) {
+        return "color";
+    }
+    if (LENGTH.test(v)) {
+        return "space";
+    }
+    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);
+            if (time) {
+                return [{ category: "motion", value: time[0].toLowerCase() }];
+            }
+        }
+        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 });
+        }
+    }
+    else if (SPACING_PROPS.test(prop)) {
+        for (const len of extractLengths(v)) {
+            out.push({ category: "space", value: len });
+        }
+    }
+    return out;
+}
+function extractColorLiterals(value) {
+    const out = [];
+    const hexPattern = /#[0-9a-f]{3,8}\b/gi;
+    let match;
+    while ((match = hexPattern.exec(value)) !== null) {
+        out.push(normalizeHex(match[0]));
+    }
+    const funcPattern = /\b(rgb|rgba|hsl|hsla|hwb|oklch|oklab|lab|lch)\(([^)]*)\)/gi;
+    while ((match = funcPattern.exec(value)) !== null) {
+        out.push(`${match[1].toLowerCase()}(${collapseSpaces(match[2] ?? "").replace(/\s*,\s*/g, ",")})`);
+    }
+    return out;
+}
+function extractLengths(value) {
+    const out = [];
+    const pattern = /-?\d*\.?\d+(px|rem|em)\b/gi;
+    let match;
+    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
+        }
+        out.push(token);
+    }
+    return out;
+}
+function normalizeValue(category, value) {
+    const v = value.trim();
+    if (category === "color") {
+        if (HEX_COLOR.test(v)) {
+            return normalizeHex(v);
+        }
+        const fn = v.match(/^(rgb|rgba|hsl|hsla|hwb|oklch|oklab|lab|lch)\(([^)]*)\)/i);
+        if (fn) {
+            return `${fn[1].toLowerCase()}(${collapseSpaces(fn[2] ?? "").replace(/\s*,\s*/g, ",")})`;
+        }
+        return v.toLowerCase();
+    }
+    if (category === "fontFamily" || category === "shadow") {
+        return collapseSpaces(v);
+    }
+    return v.toLowerCase();
+}
+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) {
+        h = `#${h[1]}${h[1]}${h[2]}${h[2]}${h[3]}${h[3]}${h[4]}${h[4]}`;
+    }
+    return h;
+}
+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) {
+    if (htmlSources.length === 0) {
+        return [];
+    }
+    const classUses = new Map();
+    const classPattern = /class\s*=\s*("([^"]*)"|'([^']*)')/gi;
+    for (const html of htmlSources) {
+        let match;
+        while ((match = classPattern.exec(html)) !== null) {
+            const classes = (match[2] ?? match[3] ?? "").split(/\s+/).filter(Boolean);
+            for (const cls of classes) {
+                classUses.set(cls, (classUses.get(cls) ?? 0) + 1);
+            }
+        }
+    }
+    const ruleStyles = collectClassRuleStyles(css);
+    const candidates = [];
+    for (const [cls, uses] of classUses) {
+        const looksLikeComponent = COMPONENT_NAME_HINTS.test(cls.toLowerCase());
+        if (!looksLikeComponent && uses < COMPONENT_MIN_USES) {
+            continue;
+        }
+        candidates.push({
+            name: friendlyComponentName(cls),
+            selector: `.${cls}`,
+            uses,
+            confidence: "low",
+            styles: ruleStyles.get(cls) ?? {},
+        });
+    }
+    candidates.sort((a, b) => b.uses - a.uses || a.name.localeCompare(b.name));
+    return candidates.slice(0, 24);
+}
+function collectClassRuleStyles(css) {
+    const out = new Map();
+    const rulePattern = /([^{}]+)\{([^{}]*)\}/g;
+    let match;
+    while ((match = rulePattern.exec(css)) !== null) {
+        const selector = (match[1] ?? "").trim();
+        const simple = selector.match(/^\.([\w-]+)$/);
+        if (!simple) {
+            continue;
+        }
+        const cls = simple[1];
+        const styles = {};
+        for (const decl of splitDeclarations(match[2] ?? "")) {
+            if (!decl.prop.startsWith("--")) {
+                styles[decl.prop] = decl.value;
+            }
+        }
+        if (Object.keys(styles).length > 0) {
+            out.set(cls, styles);
+        }
+    }
+    return out;
+}
+function friendlyComponentName(cls) {
+    const lower = cls.toLowerCase();
+    const hint = lower.match(COMPONENT_NAME_HINTS);
+    return hint ? hint[0] : cls;
+}
+// ---------------------------------------------------------------------------
+// Sorting, summarizing, digest
+// ---------------------------------------------------------------------------
+const CATEGORY_ORDER = ["color", "space", "radius", "shadow", "fontFamily", "fontSize", "motion"];
+function sortTokens(tokens) {
+    return [...tokens].sort((a, b) => {
+        const cat = CATEGORY_ORDER.indexOf(a.category) - CATEGORY_ORDER.indexOf(b.category);
+        if (cat !== 0) {
+            return cat;
+        }
+        if (a.provenance !== b.provenance) {
+            return a.provenance === "declared" ? -1 : 1;
+        }
+        return a.value.localeCompare(b.value) || (a.name ?? "").localeCompare(b.name ?? "");
+    });
+}
+function summarizeTokens(tokens) {
+    const summary = {};
+    for (const token of tokens) {
+        const key = `${token.category}:${token.provenance}`;
+        summary[key] = (summary[key] ?? 0) + 1;
+    }
+    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,
+        tokens: contract.tokens,
+        breakpoints: contract.breakpoints.map((bp) => ({ edge: bp.edge, px: bp.px })),
+        components: contract.components.map((component) => ({ selector: component.selector, styles: component.styles })),
+    };
+    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 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) {
+        return [];
+    }
+    const pairs = [];
+    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);
+        }
+        for (let i = 0; i < node.namedChildCount; i += 1) {
+            const child = node.namedChild(i);
+            if (child) {
+                stack.push(child);
+            }
+        }
+    }
+    const tokens = [];
+    const seen = new Set();
+    for (const { keyPath, value } of pairs) {
+        const categorized = categorizeTokenModuleValue(keyPath, value);
+        if (!categorized) {
+            continue;
+        }
+        const dedupeKey = `${categorized.category}::${keyPath}::${categorized.value}`;
+        if (seen.has(dedupeKey)) {
+            continue;
+        }
+        seen.add(dedupeKey);
+        tokens.push({ category: categorized.category, name: keyPath, value: categorized.value, provenance: "declared", uses: 0 });
+    }
+    return tokens;
+}
+function seedKeyPath(objectNode) {
+    const parent = objectNode.parent;
+    if (!parent) {
+        return [];
+    }
+    if (parent.type === "variable_declarator") {
+        const name = parent.childForFieldName("name");
+        if (name) {
+            return [name.text];
+        }
+    }
+    if (parent.type === "assignment_expression") {
+        const left = parent.childForFieldName("left");
+        if (left) {
+            return [left.text];
+        }
+    }
+    return [];
+}
+function collectObjectStringPairs(node, keyPath, out) {
+    for (let i = 0; i < node.namedChildCount; i += 1) {
+        const pair = node.namedChild(i);
+        if (!pair || pair.type !== "pair") {
+            continue;
+        }
+        const keyNode = pair.childForFieldName("key");
+        const valueNode = pair.childForFieldName("value");
+        if (!keyNode || !valueNode) {
+            continue;
+        }
+        const key = stripQuotes(keyNode.text);
+        if (valueNode.type === "object") {
+            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 });
+            }
+        }
+    }
+}
+function stripQuotes(text) {
+    if ((text.startsWith('"') && text.endsWith('"')) ||
+        (text.startsWith("'") && text.endsWith("'")) ||
+        (text.startsWith("`") && text.endsWith("`"))) {
+        return text.slice(1, -1);
+    }
+    return text;
+}
+function firstArrayStringLiteral(arrayNode) {
+    for (let i = 0; i < arrayNode.namedChildCount; i += 1) {
+        const child = arrayNode.namedChild(i);
+        if (child) {
+            const literal = moduleStringLiteral(child);
+            if (literal !== undefined) {
+                return literal;
+            }
+        }
+    }
+    return undefined;
+}
+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 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();
+    const push = (category, name, value) => {
+        const key = `${category}::${name}::${value}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            tokens.push({ category, name, value, provenance: "declared", uses: 0 });
+        }
+    };
+    const colorPattern = /<color\s+name\s*=\s*"([^"]+)"\s*>\s*(#[0-9a-fA-F]{3,8})\s*<\/color>/g;
+    let match;
+    while ((match = colorPattern.exec(content)) !== null) {
+        push("color", match[1], normalizeAndroidHex(match[2]));
+    }
+    const dimenPattern = /<dimen\s+name\s*=\s*"([^"]+)"\s*>\s*(-?\d*\.?\d+)(dp|sp|px)\s*<\/dimen>/g;
+    while ((match = dimenPattern.exec(content)) !== null) {
+        const name = match[1];
+        const value = `${match[2]}px`;
+        const key = name.toLowerCase();
+        if (/radius|radii|corner|\bround/.test(key)) {
+            push("radius", name, value);
+        }
+        else if (/(space|spacing|gap|gutter|inset|pad|margin)/.test(key)) {
+            push("space", name, value);
+        }
+        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)
+    }
+    if (h.length === 5) {
+        return normalizeHex(`#${h.slice(2)}`); // #ARGB -> #RGB -> expand
+    }
+    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();
+    const pattern = /(\w+)\s*[:=]\s*(?:const\s+)?Color\(\s*0x([0-9a-fA-F]{8})\s*\)/g;
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+        const name = match[1];
+        const value = `#${match[2].slice(2).toLowerCase()}`; // 0xAARRGGBB -> #rrggbb
+        const key = `color::${name}::${value}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            tokens.push({ category: "color", name, value, provenance: "declared", uses: 0 });
+        }
+    }
+    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 {
+        parsed = JSON.parse(contentsJson);
+    }
+    catch {
+        return [];
+    }
+    const colors = parsed?.colors;
+    if (!Array.isArray(colors)) {
+        return [];
+    }
+    const withComponents = colors.filter((entry) => entry?.color?.components);
+    const chosen = withComponents.find((entry) => !hasDarkAppearance(entry)) ?? withComponents[0];
+    if (!chosen) {
+        return [];
+    }
+    const components = chosen.color.components;
+    const r = parseColorComponent(String(components.red));
+    const g = parseColorComponent(String(components.green));
+    const b = parseColorComponent(String(components.blue));
+    if (r === null || g === null || b === null) {
+        return [];
+    }
+    return [{ category: "color", name, value: `#${toHex2(r)}${toHex2(g)}${toHex2(b)}`, provenance: "declared", uses: 0 }];
+}
+function hasDarkAppearance(entry) {
+    const appearances = entry.appearances;
+    return Array.isArray(appearances) && appearances.some((a) => a.value === "dark");
+}
+function parseColorComponent(raw) {
+    const v = raw.trim();
+    if (/^0x[0-9a-f]{1,2}$/i.test(v)) {
+        return clampByte(parseInt(v, 16));
+    }
+    if (v.includes("/")) {
+        const [a, b] = v.split("/").map(Number);
+        return b ? clampByte(Math.round((a / b) * 255)) : null;
+    }
+    const num = Number(v);
+    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) {
+    return Math.max(0, Math.min(255, 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();
+    const push = (name, hex) => {
+        const value = normalizeHex(`#${hex.replace(/^#/, "").slice(0, 6).toLowerCase()}`);
+        const key = `${name}::${value}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            tokens.push({ category: "color", name, value, provenance: "declared", uses: 0 });
+        }
+    };
+    const hexPattern = /(\w+)\s*[:=]\s*(?:[\w.]+\.)?Color\(\s*hex:\s*"#?([0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?)"/g;
+    let match;
+    while ((match = hexPattern.exec(content)) !== null) {
+        push(match[1], match[2]);
+    }
+    const rgbPattern = /(\w+)\s*[:=]\s*(?:UI)?Color\(\s*red:\s*([\d./]+)\s*,\s*green:\s*([\d./]+)\s*,\s*blue:\s*([\d./]+)/g;
+    while ((match = rgbPattern.exec(content)) !== null) {
+        const r = parseColorComponent(match[2]);
+        const g = parseColorComponent(match[3]);
+        const b = parseColorComponent(match[4]);
+        if (r !== null && g !== null && b !== null) {
+            push(match[1], `${toHex2(r)}${toHex2(g)}${toHex2(b)}`);
+        }
+    }
+    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
+    }
+    const key = keyPath.toLowerCase();
+    if (/screen|breakpoint|media|z-?index|opacity|weight/.test(key)) {
+        return null; // not a design token we model (or handled as breakpoints elsewhere)
+    }
+    // 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() };
+        }
+        if (/(space|spacing|gap|gutter|inset|pad|margin)/.test(key)) {
+            return { category: "space", value: v.toLowerCase() };
+        }
+        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 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) };
+    }
+    if (/(duration|motion|transition|delay)/.test(key)) {
+        const time = v.match(/-?\d*\.?\d+m?s/i);
+        if (time) {
+            return { category: "motion", value: time[0].toLowerCase() };
+        }
+    }
+    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) };
+    }
+    return null;
+}
+function stableStringify(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(",")}]`;
+    }
+    if (value && typeof value === "object") {
+        const entries = Object.entries(value)
+            .filter(([, entryValue]) => entryValue !== undefined)
+            .sort(([a], [b]) => a.localeCompare(b));
+        return `{${entries.map(([key, entryValue]) => `${JSON.stringify(key)}:${stableStringify(entryValue)}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+}