@tangle-network/browser-agent-driver 0.33.2 → 0.34.0

package/dist/cli-design-audit.js

@@ -6,71 +6,17 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { execSync } from 'node:child_process';
 import chalk from 'chalk';
 import { chromium } from 'playwright';
 import { Brain } from './brain/index.js';
 import { PlaywrightDriver } from './drivers/playwright.js';
-import { resolveProviderApiKey, resolveProviderModelName } from './provider-defaults.js';
+import { resolveDefaultProvider, resolveProviderApiKey, resolveProviderModelName, isSupportedProvider, SUPPORTED_PROVIDERS } from './provider-defaults.js';
 import { loadLocalEnvFiles } from './env-loader.js';
 import { cliError } from './cli-ui.js';
 import { auditOnePage } from './design/audit/pipeline.js';
-/** Split "a, b , c" → ['a','b','c']. Returns undefined for empty input so the
- *  layered predicates can distinguish "operator did not say" from "[]". */
-function parseTagList(input) {
-    if (!input)
-        return undefined;
-    const tags = input.split(',').map(s => s.trim()).filter(Boolean);
-    return tags.length > 0 ? tags : undefined;
-}
-/** Pretty-print the ethics-violation report for a set of pages. Prints
- *  nothing when no page tripped a rule. Each rule is shown with severity,
- *  remediation, and citation so the operator can act without re-running. */
-function printEthicsViolations(pages) {
-    const offenders = pages.filter(p => (p.ethicsViolations?.length ?? 0) > 0);
-    if (offenders.length === 0)
-        return;
-    console.log('');
-    console.log(`  ${chalk.bgRed.white.bold(' ETHICS VIOLATIONS ')}`);
-    for (const page of offenders) {
-        console.log(`  ${chalk.dim('Page:')} ${page.url}`);
-        for (const v of page.ethicsViolations ?? []) {
-            const sevColor = v.severity === 'critical-floor' ? chalk.red : chalk.yellow;
-            console.log(`    ${sevColor('•')} ${chalk.bold(v.ruleId)} ${chalk.dim('—')} ${sevColor(v.severity)} ${chalk.dim(`(rollup capped at ${v.rollupCap})`)}`);
-            console.log(`      ${chalk.dim('fix:')} ${v.remediation}`);
-            if (v.citation)
-                console.log(`      ${chalk.dim('cite:')} ${v.citation}`);
-        }
-    }
-}
-/** Lowest rollup cap across all violated pages, or undefined if none fired. */
-function lowestRollupCap(pages) {
-    const caps = pages.flatMap(p => p.ethicsViolations ?? []).map(v => v.rollupCap);
-    return caps.length === 0 ? undefined : Math.min(...caps);
-}
-/**
- * Layer 1 — print the per-dimension breakdown for one page when an
- * `auditResult` is attached. Five dim lines + one rollup line; each shows
- * score, range, and confidence so an agent can reason about uncertainty.
- */
-function printScoreBreakdown(page) {
-    const result = page.auditResult;
-    if (!result || !result.scores || !result.rollup)
-        return;
-    const dimOrder = ['product_intent', 'visual_craft', 'trust_clarity', 'workflow', 'content_ia'];
-    for (const dim of dimOrder) {
-        const s = result.scores[dim];
-        if (!s)
-            continue;
-        const sevColor = s.score >= 8 ? chalk.green : s.score >= 5 ? chalk.yellow : chalk.red;
-        const confColor = s.confidence === 'high' ? chalk.green : s.confidence === 'medium' ? chalk.yellow : chalk.dim;
-        console.log(`      ${chalk.dim(dim.padEnd(15))} ${sevColor(`${s.score}/10`)} ${chalk.dim(`[${s.range[0]}-${s.range[1]}]`)} ${confColor(s.confidence)}`);
-    }
-    const r = result.rollup;
-    const rColor = r.score >= 8 ? chalk.green : r.score >= 5 ? chalk.yellow : chalk.red;
-    const confColor = r.confidence === 'high' ? chalk.green : r.confidence === 'medium' ? chalk.yellow : chalk.dim;
-    console.log(`      ${chalk.dim('rollup'.padEnd(15))} ${rColor(`${r.score.toFixed(1)}/10`)} ${chalk.dim(`[${r.range[0].toFixed(1)}-${r.range[1].toFixed(1)}]`)} ${confColor(r.confidence)}  ${chalk.dim(r.rule)}`);
-}
+import { extractDesignTokens, createZipBundle } from './design/audit/tokens/extract.js';
+import { runEvolveLoop, runAgentEvolveLoop, generateEvolveReport, buildApplyPrompt } from './design/audit/evolve/index.js';
+import { parseTagList, printEthicsViolations, lowestRollupCap, printScoreBreakdown, generateDesignReport, } from './design/audit/report.js';
 import { resolveAuditPasses } from './design/audit/evaluate.js';
 import { detectSystemicFindings, topByRoi } from './design/audit/roi.js';
 import { getTelemetry, setInvocation } from './telemetry/index.js';
@@ -122,122 +68,87 @@ async function discoverPages(page, startUrl, maxPages) {
     }
     return discovered;
 }
-// ---------------------------------------------------------------------------
-// Report generation
-// ---------------------------------------------------------------------------
-function generateReport(results, profile, topFixes = []) {
-    const lines = [];
-    const avgScore = results.length > 0
-        ? results.reduce((sum, r) => sum + r.score, 0) / results.length
-        : 0;
-    const allFindings = results.flatMap(r => r.findings);
-    const critical = allFindings.filter(f => f.severity === 'critical').length;
-    const major = allFindings.filter(f => f.severity === 'major').length;
-    const minor = allFindings.filter(f => f.severity === 'minor').length;
-    const totalTokens = results.reduce((sum, r) => sum + (r.tokensUsed ?? 0), 0);
-    lines.push('# Design Audit Report');
-    lines.push('');
-    if (profile) {
-        lines.push(`**Profile:** ${profile}`);
+/**
+ * Parse a `--judge-models` list (`"prov:model,prov:model"` or bare `"model"`)
+ * into `ModelRef[]`. Splits on `,` then the FIRST `:` (model names never contain
+ * one); a colon-less entry leaves `provider` unset so the wiring fills the
+ * ambient default. Blank entries are skipped; an empty/absent string ⇒ `[]`.
+ */
+export function parseModelRefs(spec) {
+    if (!spec)
+        return [];
+    const refs = [];
+    for (const raw of spec.split(',')) {
+        const entry = raw.trim();
+        if (!entry)
+            continue;
+        const colon = entry.indexOf(':');
+        if (colon < 0) {
+            refs.push({ model: entry });
+            continue;
+        }
+        const provider = entry.slice(0, colon).trim();
+        const model = entry.slice(colon + 1).trim();
+        if (!model)
+            continue;
+        refs.push(provider ? { provider: provider, model } : { model });
     }
-    // Surface per-page classification when present.
-    const classifications = results
-        .filter(r => r.classification)
-        .map(r => `${r.url}: ${r.classification.type}/${r.classification.domain} (${r.classification.maturity})`);
-    if (classifications.length > 0) {
-        lines.push(`**Auto-classified:**`);
-        for (const c of classifications)
-            lines.push(`- ${c}`);
+    return refs;
+}
+/**
+ * Default location for the reference corpus — mirrors
+ * `reference/config.ts` `DEFAULT_REFERENCE_CONFIG.corpusDir`. Checked with a
+ * plain fs read (no engine import) so reference-grounded can be the default
+ * without forcing the heavy engine to load on the v1 path.
+ */
+const DEFAULT_REFERENCE_CORPUS_DIR = 'bench/design/reference-corpus';
+/** True iff the default corpus dir holds at least one exemplar (`.json` other
+ *  than the tracked `sources.example.json`). Drives the corpus-aware default. */
+function hasPopulatedCorpus() {
+    try {
+        return fs
+            .readdirSync(path.resolve(DEFAULT_REFERENCE_CORPUS_DIR))
+            .some((f) => f.endsWith('.json') && f !== 'sources.example.json');
     }
-    lines.push(`**Pages audited:** ${results.length}`);
-    lines.push(`**Overall score:** ${avgScore.toFixed(1)}/10`);
-    lines.push(`**Findings:** ${allFindings.length} (${critical} critical, ${major} major, ${minor} minor)`);
-    if (totalTokens > 0)
-        lines.push(`**Tokens used:** ${totalTokens.toLocaleString()}`);
-    lines.push('');
-    // Score bar
-    const scoreBar = '█'.repeat(Math.round(avgScore)) + '░'.repeat(10 - Math.round(avgScore));
-    lines.push(`\`${scoreBar}\` ${avgScore.toFixed(1)}/10`);
-    lines.push('');
-    // ── Top Fixes (by ROI) — the headline section users actually read first ──
-    if (topFixes.length > 0) {
-        lines.push('## Top Fixes (by ROI)');
-        lines.push('');
-        lines.push('Fix these first — sorted by impact × blast / effort:');
-        lines.push('');
-        for (let i = 0; i < topFixes.length; i++) {
-            const f = topFixes[i];
-            const tags = [];
-            if (f.pageCount && f.pageCount >= 2)
-                tags.push(`appears on ${f.pageCount} pages`);
-            if (f.blast === 'system')
-                tags.push('SYSTEMIC');
-            const tagStr = tags.length > 0 ? ` _(${tags.join(', ')})_` : '';
-            const roiStr = f.roi !== undefined ? f.roi.toFixed(1) : '—';
-            lines.push(`### ${i + 1}. [${f.severity}] ${f.description}${tagStr}`);
-            lines.push('');
-            lines.push(`- **ROI:** ${roiStr}  ·  Impact ${f.impact ?? '—'}  ·  Effort ${f.effort ?? '—'}  ·  Blast ${f.blast ?? '—'}`);
-            lines.push(`- **Location:** ${f.location}`);
-            lines.push(`- **Fix:** ${f.suggestion}`);
-            if (f.cssSelector && f.cssFix) {
-                lines.push(`- **CSS:** \`${f.cssSelector} { ${f.cssFix} }\``);
-            }
-            lines.push('');
-        }
-        lines.push('---');
-        lines.push('');
+    catch {
+        return false;
     }
-    // Per-page results
-    for (const result of results) {
-        lines.push(`## ${result.url}`);
-        lines.push('');
-        const pageBar = '█'.repeat(Math.round(result.score)) + '░'.repeat(10 - Math.round(result.score));
-        lines.push(`**Score:** \`${pageBar}\` ${result.score}/10`);
-        if (result.summary)
-            lines.push(`**Summary:** ${result.summary}`);
-        if (result.error)
-            lines.push(`**Error:** ${result.error}`);
-        lines.push('');
-        if (result.strengths.length > 0) {
-            lines.push('**Strengths:**');
-            for (const s of result.strengths)
-                lines.push(`- ${s}`);
-            lines.push('');
-        }
-        if (result.designSystemScore) {
-            lines.push('**Design System Breakdown:**');
-            lines.push('');
-            const ds = result.designSystemScore;
-            // Universal dimensions in fixed order, then any custom dimensions (alpha)
-            const universal = ['layout', 'typography', 'color', 'spacing', 'components', 'interactions', 'accessibility', 'polish'];
-            const custom = Object.keys(ds).filter(k => !universal.includes(k)).sort();
-            for (const key of [...universal, ...custom]) {
-                if (typeof ds[key] === 'number') {
-                    const bar = '█'.repeat(Math.round(ds[key])) + '░'.repeat(10 - Math.round(ds[key]));
-                    lines.push(`- ${key}: \`${bar}\` ${ds[key]}/10`);
-                }
-            }
-            lines.push('');
-        }
-        if (result.findings.length > 0) {
-            lines.push('**Findings:**');
-            lines.push('');
-            lines.push('| Sev | Category | Description | Location | Fix | CSS |');
-            lines.push('|-----|----------|-------------|----------|-----|-----|');
-            for (const f of result.findings) {
-                const esc = (s) => s.replace(/\|/g, '\\|').replace(/\n/g, ' ').slice(0, 120);
-                const icon = f.severity === 'critical' ? '🔴' : f.severity === 'major' ? '🟡' : '⚪';
-                const cssFix = f.cssFix ? `\`${esc(f.cssFix)}\`` : '';
-                lines.push(`| ${icon} ${f.severity} | ${f.category} | ${esc(f.description)} | ${esc(f.location)} | ${esc(f.suggestion)} | ${cssFix} |`);
-            }
-            lines.push('');
-        }
-        else if (!result.error) {
-            lines.push('No issues found.');
-            lines.push('');
-        }
+}
+/**
+ * Acquire the reference-grounded eval bundle once: lazily load the engine,
+ * resolve the operator reference + corpus, and pick the taste judge. Reached
+ * only when reference-grounded mode is active, so the v1 path never loads the
+ * engine. Fails closed with a clear diagnostic (a module-load failure or an
+ * unresolvable reference) instead of an unhandled rejection.
+ */
+async function setupReferenceGrounded(opts, modelName, provider) {
+    try {
+        const { resolveReferenceConfig, createFileCorpusStore, resolveReferenceContext } = await import('./design/audit/reference/index.js');
+        const { createPageDnaExtractor } = await import('./design/audit/reference/dna/page-adapter.js');
+        // Vision judge: `--judge vision` selects it; `--judge-models` customises the
+        // ensemble (and implies vision when `--judge` is omitted). With vision on but
+        // no explicit models, default to the audit's OWN provider/model so the screenshot
+        // judge "just works" with whatever key the run already uses. Subjects without a
+        // screenshot (unrendered directions) fall back to the text judge inside the engine.
+        const visionRefs = parseModelRefs(opts.judgeModels);
+        const wantsVision = opts.judge === 'vision' || (!opts.judge && visionRefs.length > 0);
+        const referenceConfig = resolveReferenceConfig({
+            model: modelName,
+            ...(wantsVision ? { judge: 'vision' } : opts.judge === 'text' ? { judge: 'text' } : {}),
+            ...(wantsVision
+                ? { visionModels: visionRefs.length > 0 ? visionRefs : [{ provider, model: modelName }] }
+                : {}),
+        });
+        const reference = await resolveReferenceContext(opts.reference, { extractor: createPageDnaExtractor() }, { headless: opts.headless ?? true });
+        const corpus = await createFileCorpusStore(referenceConfig.corpusDir).load();
+        const refLabel = reference ? `, reference ${opts.reference ?? ''}` : '';
+        console.log(`  ${chalk.cyan('reference-grounded')} ${chalk.dim('—')} corpus ${chalk.bold(String(corpus.length))} exemplar${corpus.length !== 1 ? 's' : ''}${refLabel}`);
+        return { evalMode: 'reference-grounded', reference, corpus, referenceConfig };
+    }
+    catch (err) {
+        cliError(`reference-grounded setup failed: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
     }
-    return lines.join('\n');
 }
 export async function runDesignAudit(opts) {
     loadLocalEnvFiles(process.cwd());
@@ -250,7 +161,13 @@ export async function runDesignAudit(opts) {
     // selects a single type fragment instead of letting the classifier decide.
     const profile = opts.profile;
     const maxPages = opts.pages ?? 5;
-    const provider = (opts.provider ?? 'claude-code');
+    // Validate a user-supplied --provider before casting, so an unknown value
+    // fails fast with a clear message instead of surfacing deep in the pipeline.
+    if (opts.provider !== undefined && !isSupportedProvider(opts.provider)) {
+        cliError(`unknown --provider "${opts.provider}". Supported: ${SUPPORTED_PROVIDERS.join(', ')}`);
+        process.exit(1);
+    }
+    const provider = (opts.provider ?? resolveDefaultProvider());
     const modelName = resolveProviderModelName(provider, opts.model);
     const apiKey = opts.apiKey ?? resolveProviderApiKey(provider);
     const auditPasses = resolveAuditPasses(opts.auditPasses);
@@ -266,6 +183,23 @@ export async function runDesignAudit(opts) {
         audienceVulnerability: parseTagList(opts.audienceVulnerability),
         modality: parseTagList(opts.modality),
     };
+    // ── Reference-grounded eval — acquire-once. Default: reference-grounded WHEN a
+    // populated corpus is present (it needs exemplars to ground against), else v1.
+    // `--reference`/`--reference-grounded` force it on; `--v1` forces it off. The
+    // corpus check is a plain fs read (no engine import), so the v1 path stays
+    // lazy: evalMode 'v1' yields an empty bundle, `...referenceCommonOpts` adds only
+    // `evalMode:'v1'`, and the pipeline's stage-6 branch is never entered. When ON,
+    // resolve the operator reference and load the exemplar corpus a SINGLE time here
+    // — before the page/rep loops — so a multi-page/rep run never re-reads them
+    // (protects the ±0.5 reproducibility gate). The engine is imported lazily. ──
+    const evalMode = opts.v1
+        ? 'v1'
+        : opts.referenceGrounded || opts.reference || hasPopulatedCorpus()
+            ? 'reference-grounded'
+            : 'v1';
+    const referenceCommonOpts = evalMode === 'reference-grounded'
+        ? await setupReferenceGrounded(opts, modelName, provider)
+        : { evalMode };
     // Telemetry: every design-audit invocation gets a stable runId. Child
     // envelopes link back via parentRunId so fleet rollups can reconstruct
     // the run tree.
@@ -335,6 +269,7 @@ export async function runDesignAudit(opts) {
             provider,
             model: modelName,
             ...ethicsCommonOpts,
+            ...referenceCommonOpts,
         });
         const result = gen2;
         results.push(result);
@@ -356,8 +291,35 @@ export async function runDesignAudit(opts) {
         const deduped = detectSystemicFindings(perPage);
         topFixes = topByRoi(deduped, 5);
     }
+    // ── Reference-grounded: surface the rich redesign brief. Reference mode only —
+    // v1 results carry no `referenceArtifact`, so this block is skipped and both the
+    // report and the on-disk output are byte-identical to the legacy path. The
+    // render module is imported lazily (and is already module-cached in this mode),
+    // so a default audit never loads the reference engine. ──
+    let redesignSection;
+    if (evalMode === 'reference-grounded') {
+        const withArtifact = results.filter((r) => r.referenceArtifact);
+        if (withArtifact.length > 0) {
+            const { renderArtifactMarkdown, renderRedesignDirectionsSummary, renderRedesignTarget, artifactSlug } = await import('./design/audit/reference/index.js');
+            const sections = ['## Redesign directions', ''];
+            for (const r of withArtifact) {
+                const artifact = r.referenceArtifact;
+                const briefFile = `${artifactSlug(r.url)}.redesign.md`;
+                fs.writeFileSync(path.join(outputDir, briefFile), renderArtifactMarkdown(artifact));
+                sections.push(renderRedesignDirectionsSummary(artifact, briefFile));
+                console.log(`  ${chalk.dim('Redesign brief →')} ${path.join(outputDir, briefFile)}`);
+                // Default (non-spawning) apply path: emit the implementation prompt a
+                // coding agent reads and runs ITSELF to apply this grounded redesign in
+                // its project. Spawning a coding agent stays opt-in (`--evolve --agent`).
+                const applyFile = `${artifactSlug(r.url)}.apply-prompt.md`;
+                fs.writeFileSync(path.join(outputDir, applyFile), buildApplyPrompt([r], profile, renderRedesignTarget(artifact)));
+                console.log(`  ${chalk.dim('Apply prompt →')} ${path.join(outputDir, applyFile)}`);
+            }
+            redesignSection = sections.join('\n').trimEnd();
+        }
+    }
     // Generate report
-    const report = generateReport(results, profile, topFixes);
+    const report = generateDesignReport(results, profile, topFixes, redesignSection);
     const reportPath = path.join(outputDir, 'report.md');
     fs.writeFileSync(reportPath, report);
     const allFindings = results.flatMap(r => r.findings);
@@ -420,6 +382,7 @@ export async function runDesignAudit(opts) {
                     model: modelName,
                     parentRunId: runId,
                     ...ethicsCommonOpts,
+                    ...referenceCommonOpts,
                 });
                 repResults.push(gen2);
             }
@@ -453,11 +416,11 @@ export async function runDesignAudit(opts) {
         if (evolveMode !== 'css') {
             // Agent-dispatched evolve — a coding agent edits the actual source code
             const projectDir = opts.projectDir ?? process.cwd();
-            evolveResult = await runAgentEvolveLoop(brain, driver, page, pages, evolveProfile, results, outputDir, opts.evolveRounds ?? 3, evolveMode, projectDir, opts.debug, auditPasses, runId, provider, modelName);
+            evolveResult = await runAgentEvolveLoop(brain, driver, page, pages, evolveProfile, results, outputDir, opts.evolveRounds ?? 3, evolveMode, projectDir, opts.debug, auditPasses, runId, provider, modelName, referenceCommonOpts);
         }
         else {
             // CSS-injection evolve — ephemeral fixes injected into the browser page
-            evolveResult = await runEvolveLoop(brain, driver, page, pages, evolveProfile, results, outputDir, opts.evolveRounds ?? 3, auditPasses, runId, provider, modelName);
+            evolveResult = await runEvolveLoop(brain, driver, page, pages, evolveProfile, results, outputDir, opts.evolveRounds ?? 3, auditPasses, runId, provider, modelName, referenceCommonOpts);
         }
         // Write evolve report
         const evolvePath = path.join(outputDir, 'evolve-report.md');
@@ -528,1478 +491,6 @@ export async function runDesignAudit(opts) {
     });
     await browser.close();
 }
-async function runEvolveLoop(brain, driver, page, pages, profile, initialResults, outputDir, maxRounds, auditPasses, parentRunId, provider, model) {
-    const telemetry = parentRunId ? getTelemetry() : undefined;
-    const initialAvg = initialResults.reduce((s, r) => s + r.score, 0) / initialResults.length;
-    const scoreHistory = [initialAvg];
-    const appliedFixes = [];
-    const skippedFixes = [];
-    let cumulativeCSS = '';
-    let currentResults = initialResults;
-    let currentAvg = initialAvg;
-    console.log('');
-    console.log(`  ${chalk.bold('Design Evolve')} — ${maxRounds} rounds max`);
-    console.log(`  ${chalk.dim('Initial score:')} ${currentAvg.toFixed(1)}/10`);
-    console.log('');
-    for (let round = 1; round <= maxRounds; round++) {
-        console.log(`  ${chalk.dim(`Round ${round}/${maxRounds}`)}`);
-        // Collect all findings with CSS fixes across all pages
-        const fixableFixes = currentResults
-            .flatMap(r => r.findings)
-            .filter(f => f.cssSelector && f.cssFix);
-        if (fixableFixes.length === 0) {
-            console.log(`  ${chalk.dim('  No CSS-fixable findings — generating fixes via LLM…')}`);
-            // Ask the LLM to generate CSS fixes for the top findings
-            const topFindings = currentResults
-                .flatMap(r => r.findings)
-                .filter(f => f.severity === 'critical' || f.severity === 'major')
-                .slice(0, 10);
-            if (topFindings.length === 0) {
-                console.log(`  ${chalk.green('  No major/critical findings remaining')}`);
-                break;
-            }
-            const fixPrompt = buildFixGenerationPrompt(topFindings);
-            const fixResult = await brain.auditDesign(await driver.observe(), 'Generate CSS fixes for the design issues listed below', [], fixPrompt);
-            // Parse generated fixes
-            try {
-                let text = fixResult.raw.trim();
-                if (text.startsWith('```'))
-                    text = text.replace(/^```(?:json)?\n?/, '').replace(/\n?```$/, '');
-                const start = text.indexOf('{');
-                const end = text.lastIndexOf('}');
-                if (start >= 0 && end > start)
-                    text = text.slice(start, end + 1);
-                const parsed = JSON.parse(text);
-                if (Array.isArray(parsed.fixes)) {
-                    for (const fix of parsed.fixes) {
-                        if (fix.cssSelector && fix.cssFix) {
-                            fixableFixes.push({
-                                category: 'ux',
-                                severity: 'major',
-                                description: fix.description || '',
-                                location: fix.location || '',
-                                suggestion: fix.cssFix,
-                                cssSelector: fix.cssSelector,
-                                cssFix: fix.cssFix,
-                            });
-                        }
-                    }
-                }
-            }
-            catch { /* failed to parse fixes */ }
-        }
-        if (fixableFixes.length === 0) {
-            console.log(`  ${chalk.dim('  Could not generate fixable CSS — stopping')}`);
-            break;
-        }
-        // Build CSS override from all fixable findings
-        const roundCSS = fixableFixes
-            .map(f => `/* ${f.severity}: ${f.description?.slice(0, 80)} */\n${f.cssSelector} { ${f.cssFix} }`)
-            .join('\n\n');
-        cumulativeCSS += '\n' + roundCSS;
-        // Track applied fixes
-        for (const f of fixableFixes) {
-            appliedFixes.push({
-                cssSelector: f.cssSelector,
-                cssFix: f.cssFix,
-                finding: f.description,
-            });
-        }
-        console.log(`  ${chalk.dim(`  Applying ${fixableFixes.length} CSS fixes…`)}`);
-        // Re-audit each page with CSS injected
-        const roundResults = [];
-        for (const url of pages) {
-            try {
-                await page.goto(url, { waitUntil: 'networkidle', timeout: 20_000 }).catch(() => page.goto(url, { waitUntil: 'domcontentloaded', timeout: 15_000 }));
-                await page.waitForTimeout(1500);
-                // Inject cumulative CSS fixes
-                await page.addStyleTag({ content: cumulativeCSS });
-                await page.waitForTimeout(500);
-                // Take screenshot of fixed state
-                const screenshotDir = path.join(outputDir, `screenshots-round-${round}`);
-                fs.mkdirSync(screenshotDir, { recursive: true });
-                const result = (await auditOnePage({
-                    brain,
-                    driver,
-                    page,
-                    url,
-                    profileOverride: profile,
-                    screenshotDir,
-                    auditPasses,
-                    ...(parentRunId ? { runId: parentRunId, parentRunId } : {}),
-                    ...(provider ? { provider } : {}),
-                    ...(model ? { model } : {}),
-                }));
-                roundResults.push(result);
-            }
-            catch {
-                roundResults.push({
-                    url,
-                    score: currentAvg,
-                    summary: 'Re-audit failed',
-                    strengths: [],
-                    findings: [],
-                    error: 'Re-audit with CSS injection failed',
-                });
-            }
-        }
-        const roundAvg = roundResults.reduce((s, r) => s + r.score, 0) / roundResults.length;
-        scoreHistory.push(roundAvg);
-        const delta = roundAvg - currentAvg;
-        const deltaStr = delta >= 0 ? chalk.green(`+${delta.toFixed(1)}`) : chalk.red(delta.toFixed(1));
-        console.log(`  ${chalk.dim('  Score:')} ${roundAvg.toFixed(1)}/10 (${deltaStr})`);
-        if (telemetry && parentRunId) {
-            telemetry.emit({
-                kind: 'design-evolve-round',
-                runId: parentRunId,
-                parentRunId,
-                ok: true,
-                durationMs: 0, // round-level wall time would require a per-round timer; the parent run captures total duration
-                ...(provider && model ? { model: { provider, name: model } } : {}),
-                data: {
-                    mode: 'css',
-                    round,
-                    fixesApplied: fixableFixes.length,
-                },
-                metrics: {
-                    round,
-                    beforeScore: currentAvg,
-                    afterScore: roundAvg,
-                    delta,
-                    fixesApplied: fixableFixes.length,
-                },
-            });
-        }
-        currentResults = roundResults;
-        currentAvg = roundAvg;
-        // Check convergence — if no improvement, stop
-        if (delta <= 0.1 && round > 1) {
-            console.log(`  ${chalk.dim('  Converged — no further improvement')}`);
-            break;
-        }
-    }
-    const totalDelta = currentAvg - initialAvg;
-    const deltaColor = totalDelta >= 2 ? chalk.green : totalDelta > 0 ? chalk.yellow : chalk.red;
-    console.log('');
-    console.log(`  ${chalk.bold('Evolve complete')}`);
-    console.log(`  ${chalk.dim('Score:')} ${initialAvg.toFixed(1)} → ${currentAvg.toFixed(1)} (${deltaColor(`+${totalDelta.toFixed(1)}`)})`);
-    console.log(`  ${chalk.dim('Rounds:')} ${scoreHistory.length - 1}`);
-    console.log(`  ${chalk.dim('Fixes applied:')} ${appliedFixes.length}`);
-    console.log('');
-    return {
-        beforeScore: initialAvg,
-        afterScore: currentAvg,
-        delta: totalDelta,
-        rounds: scoreHistory.length - 1,
-        appliedFixes,
-        skippedFixes,
-        scoreHistory,
-        cssOverride: cumulativeCSS.trim(),
-    };
-}
-function buildFixGenerationPrompt(findings) {
-    const findingList = findings.map((f, i) => `${i + 1}. [${f.severity}/${f.category}] ${f.description}\n   Location: ${f.location}\n   Suggestion: ${f.suggestion}`).join('\n');
-    return `You are a CSS engineer fixing design issues. For each finding, generate a precise CSS fix.
-
-FINDINGS TO FIX:
-${findingList}
-
-RULES:
-- Use specific, targeted CSS selectors. Prefer class-based or semantic selectors.
-- Each fix should be a single CSS rule (selector + property:value pairs).
-- Fixes must not break other elements — be surgical.
-- For spacing: use consistent values (multiples of 4 or 8px).
-- For colors: ensure WCAG AA contrast (4.5:1 for text, 3:1 for large text).
-- For typography: use a limited scale (14px, 16px, 20px, 24px, 32px, 48px).
-
-RESPOND WITH ONLY a JSON object:
-{
-  "fixes": [
-    {
-      "cssSelector": "main > section:first-child",
-      "cssFix": "padding-bottom: 48px; margin-bottom: 0",
-      "description": "Standardize hero section bottom spacing",
-      "location": "Hero → features transition"
-    }
-  ]
-}`;
-}
-function generateEvolveReport(result) {
-    const lines = [];
-    lines.push('# Design Evolve Report');
-    lines.push('');
-    lines.push(`**Score:** ${result.beforeScore.toFixed(1)} → ${result.afterScore.toFixed(1)} (+${result.delta.toFixed(1)})`);
-    lines.push(`**Rounds:** ${result.rounds}`);
-    lines.push(`**Score progression:** ${result.scoreHistory.map(s => s.toFixed(1)).join(' → ')}`);
-    lines.push('');
-    if (result.appliedFixes.length > 0) {
-        lines.push('## Applied Fixes');
-        lines.push('');
-        for (const fix of result.appliedFixes) {
-            lines.push(`- \`${fix.cssSelector}\`: \`${fix.cssFix}\``);
-            if (fix.finding)
-                lines.push(`  - ${fix.finding}`);
-        }
-        lines.push('');
-    }
-    if (result.cssOverride) {
-        lines.push('## Generated CSS Override');
-        lines.push('');
-        lines.push('```css');
-        lines.push(result.cssOverride);
-        lines.push('```');
-        lines.push('');
-        lines.push('Apply this CSS to your app to fix the identified design issues:');
-        lines.push('```html');
-        lines.push('<link rel="stylesheet" href="design-fixes.css">');
-        lines.push('```');
-    }
-    return lines.join('\n');
-}
-// ---------------------------------------------------------------------------
-// Agent-dispatched evolve — sends findings to a coding agent that edits source
-// ---------------------------------------------------------------------------
-const AGENT_COMMANDS = {
-    'claude-code': (prompt, dir) => ['claude', '-p', prompt, '--dangerously-skip-permissions', '--add-dir', dir],
-    'codex': (prompt, dir) => ['codex', 'exec', prompt, '-c', `cwd="${dir}"`],
-    'opencode': (prompt, dir) => ['opencode', 'run', prompt],
-};
-function resolveAgentCommand(agent, prompt, projectDir) {
-    const builder = AGENT_COMMANDS[agent];
-    if (builder) {
-        const [cmd, ...args] = builder(prompt, projectDir);
-        return { cmd, args, cwd: projectDir };
-    }
-    // Custom command — treat the agent string as a command template
-    // e.g. "aider --message" becomes: aider --message "<prompt>"
-    const parts = agent.split(/\s+/);
-    return { cmd: parts[0], args: [...parts.slice(1), prompt], cwd: projectDir };
-}
-function buildAgentFixPrompt(results, profile, round) {
-    const allFindings = results.flatMap(r => r.findings);
-    const critical = allFindings.filter(f => f.severity === 'critical');
-    const major = allFindings.filter(f => f.severity === 'major');
-    const minor = allFindings.filter(f => f.severity === 'minor');
-    const findingsList = [...critical, ...major, ...minor.slice(0, 5)]
-        .map((f, i) => {
-        let entry = `${i + 1}. [${f.severity}/${f.category}] ${f.description}`;
-        entry += `\n   Location: ${f.location}`;
-        entry += `\n   Suggestion: ${f.suggestion}`;
-        if (f.cssSelector)
-            entry += `\n   CSS Selector: ${f.cssSelector}`;
-        if (f.cssFix)
-            entry += `\n   CSS Fix: ${f.cssFix}`;
-        return entry;
-    })
-        .join('\n\n');
-    const scoreBreakdowns = results
-        .filter(r => r.designSystemScore)
-        .map(r => {
-        const ds = r.designSystemScore;
-        return `  ${r.url}: ${Object.entries(ds).map(([k, v]) => `${k}=${v}`).join(', ')}`;
-    })
-        .join('\n');
-    return `You are fixing design issues found by an automated design audit.
-
-AUDIT PROFILE: ${profile}
-ROUND: ${round} (${round === 1 ? 'initial fixes' : 'fixing remaining issues from previous round'})
-CURRENT SCORES:
-  Overall: ${(results.reduce((s, r) => s + r.score, 0) / results.length).toFixed(1)}/10
-${scoreBreakdowns}
-
-FINDINGS TO FIX (${critical.length} critical, ${major.length} major, ${minor.length} minor):
-
-${findingsList}
-
-INSTRUCTIONS:
-1. Read the project's source files to understand the styling approach (Tailwind, CSS modules, plain CSS, styled-components, etc.)
-2. Fix the findings by editing the ACTUAL SOURCE FILES — not by creating new CSS override files
-3. Match the project's existing styling conventions
-4. Fix the design SYSTEM (shared components, tokens, globals) not individual instances
-5. Prioritize critical and major findings
-6. Only change visual/styling properties — never change business logic, state, or event handlers
-7. After making changes, verify the dev server is still running (no build errors)
-
-Do NOT:
-- Create new standalone CSS override files — edit the existing styles
-- Add comments explaining what you changed — just change it
-- Refactor unrelated code
-- Change component structure or HTML semantics unless a finding specifically requires it`;
-}
-async function runAgentEvolveLoop(brain, driver, page, pages, profile, initialResults, outputDir, maxRounds, agentName, projectDir, debug, auditPasses, parentRunId, provider, model) {
-    const telemetry = parentRunId ? getTelemetry() : undefined;
-    const initialAvg = initialResults.reduce((s, r) => s + r.score, 0) / initialResults.length;
-    const scoreHistory = [initialAvg];
-    const appliedFixes = [];
-    let currentResults = initialResults;
-    let currentAvg = initialAvg;
-    const resolvedProjectDir = path.resolve(projectDir);
-    if (!fs.existsSync(resolvedProjectDir)) {
-        cliError(`project directory not found: ${resolvedProjectDir}`);
-        process.exit(1);
-    }
-    console.log('');
-    console.log(`  ${chalk.bold('Design Evolve')} ${chalk.dim('via')} ${chalk.cyan(agentName)}`);
-    console.log(`  ${chalk.dim('Project:')} ${resolvedProjectDir}`);
-    console.log(`  ${chalk.dim('Initial score:')} ${currentAvg.toFixed(1)}/10`);
-    console.log(`  ${chalk.dim('Max rounds:')} ${maxRounds}`);
-    console.log('');
-    for (let round = 1; round <= maxRounds; round++) {
-        console.log(`  ${chalk.dim(`Round ${round}/${maxRounds}`)}`);
-        // Build the prompt for the agent
-        const prompt = buildAgentFixPrompt(currentResults, profile, round);
-        // Write the prompt to a file for debugging
-        const promptPath = path.join(outputDir, `agent-prompt-round-${round}.txt`);
-        fs.writeFileSync(promptPath, prompt);
-        // Also write the full report JSON so the agent could read it
-        const findingsPath = path.join(outputDir, `findings-round-${round}.json`);
-        fs.writeFileSync(findingsPath, JSON.stringify({
-            round,
-            score: currentAvg,
-            results: currentResults.map(r => ({
-                url: r.url,
-                score: r.score,
-                designSystemScore: r.designSystemScore,
-                findings: r.findings,
-            })),
-        }, null, 2));
-        // Dispatch to the coding agent
-        const { cmd, args, cwd } = resolveAgentCommand(agentName, prompt, resolvedProjectDir);
-        console.log(`  ${chalk.dim(`  Dispatching to ${agentName}…`)}`);
-        if (debug) {
-            console.log(`  ${chalk.dim(`  cmd: ${cmd} ${args.map(a => a.length > 80 ? a.slice(0, 80) + '…' : a).join(' ')}`)}`);
-        }
-        try {
-            const result = execSync(`${cmd} ${args.map(a => JSON.stringify(a)).join(' ')}`, {
-                cwd,
-                stdio: debug ? 'inherit' : 'pipe',
-                timeout: 300_000, // 5min max per agent round
-                env: { ...process.env },
-            });
-            if (!debug && result) {
-                const agentOutputPath = path.join(outputDir, `agent-output-round-${round}.txt`);
-                fs.writeFileSync(agentOutputPath, result.toString());
-            }
-            console.log(`  ${chalk.dim('  Agent completed')}`);
-        }
-        catch (err) {
-            const exitCode = err.status ?? 'unknown';
-            console.log(`  ${chalk.yellow(`  Agent exited with code ${exitCode} — continuing with re-audit`)}`);
-            // Write stderr if available
-            const stderr = err.stderr;
-            if (stderr) {
-                const errPath = path.join(outputDir, `agent-error-round-${round}.txt`);
-                fs.writeFileSync(errPath, stderr.toString());
-            }
-        }
-        // Wait for hot reload to settle
-        console.log(`  ${chalk.dim('  Waiting for hot reload…')}`);
-        await new Promise(resolve => setTimeout(resolve, 5000));
-        // Re-audit
-        console.log(`  ${chalk.dim('  Re-auditing…')}`);
-        const roundResults = [];
-        const roundScreenshotDir = path.join(outputDir, `screenshots-round-${round}`);
-        fs.mkdirSync(roundScreenshotDir, { recursive: true });
-        for (const url of pages) {
-            const result = (await auditOnePage({
-                brain,
-                driver,
-                page,
-                url,
-                profileOverride: profile,
-                screenshotDir: roundScreenshotDir,
-                auditPasses,
-                ...(parentRunId ? { runId: parentRunId, parentRunId } : {}),
-                ...(provider ? { provider } : {}),
-                ...(model ? { model } : {}),
-            }));
-            roundResults.push(result);
-        }
-        const roundAvg = roundResults.reduce((s, r) => s + r.score, 0) / roundResults.length;
-        scoreHistory.push(roundAvg);
-        const delta = roundAvg - currentAvg;
-        const deltaStr = delta >= 0 ? chalk.green(`+${delta.toFixed(1)}`) : chalk.red(delta.toFixed(1));
-        console.log(`  ${chalk.dim('  Score:')} ${roundAvg.toFixed(1)}/10 (${deltaStr})`);
-        // Track what changed
-        const prevFindingCount = currentResults.flatMap(r => r.findings).length;
-        const newFindingCount = roundResults.flatMap(r => r.findings).length;
-        const resolvedCount = Math.max(0, prevFindingCount - newFindingCount);
-        if (resolvedCount > 0) {
-            appliedFixes.push({
-                cssSelector: `round-${round}`,
-                cssFix: `${agentName} resolved ${resolvedCount} findings`,
-                finding: `Score: ${currentAvg.toFixed(1)} → ${roundAvg.toFixed(1)}`,
-            });
-        }
-        if (telemetry && parentRunId) {
-            telemetry.emit({
-                kind: 'design-evolve-round',
-                runId: parentRunId,
-                parentRunId,
-                ok: true,
-                durationMs: 0,
-                ...(provider && model ? { model: { provider, name: model } } : {}),
-                data: {
-                    mode: `agent:${agentName}`,
-                    round,
-                    resolvedCount,
-                },
-                metrics: {
-                    round,
-                    beforeScore: currentAvg,
-                    afterScore: roundAvg,
-                    delta,
-                    findingsResolved: resolvedCount,
-                },
-            });
-        }
-        currentResults = roundResults;
-        currentAvg = roundAvg;
-        // Check convergence
-        if (delta <= 0.1 && round > 1) {
-            console.log(`  ${chalk.dim('  Converged — no further improvement')}`);
-            break;
-        }
-    }
-    const totalDelta = currentAvg - initialAvg;
-    const deltaColor = totalDelta >= 2 ? chalk.green : totalDelta > 0 ? chalk.yellow : chalk.red;
-    console.log('');
-    console.log(`  ${chalk.bold('Evolve complete')} ${chalk.dim('via')} ${chalk.cyan(agentName)}`);
-    console.log(`  ${chalk.dim('Score:')} ${initialAvg.toFixed(1)} → ${currentAvg.toFixed(1)} (${deltaColor(totalDelta >= 0 ? `+${totalDelta.toFixed(1)}` : totalDelta.toFixed(1))})`);
-    console.log(`  ${chalk.dim('Rounds:')} ${scoreHistory.length - 1}`);
-    console.log('');
-    return {
-        beforeScore: initialAvg,
-        afterScore: currentAvg,
-        delta: totalDelta,
-        rounds: scoreHistory.length - 1,
-        appliedFixes,
-        skippedFixes: [],
-        scoreHistory,
-        cssOverride: '', // no CSS override in agent mode — agent edited source directly
-    };
-}
-// ---------------------------------------------------------------------------
-// Design Token Extraction — pure DOM, no LLM calls
-// ---------------------------------------------------------------------------
-const VIEWPORTS = [
-    { name: 'mobile', width: 375, height: 812 },
-    { name: 'tablet', width: 768, height: 1024 },
-    { name: 'desktop', width: 1440, height: 900 },
-];
-// The in-page extraction function — runs inside page.evaluate()
-function extractTokensFromDOM() {
-    const MAX_ELEMENTS = 50_000;
-    // --- CSS Custom Properties & Font Files ---
-    const customProperties = {};
-    const fontFiles = [];
-    const externalStylesheetUrls = [];
-    for (const sheet of document.styleSheets) {
-        if (sheet.href && (sheet.href.startsWith('http://') || sheet.href.startsWith('https://'))) {
-            externalStylesheetUrls.push(sheet.href);
-        }
-        try {
-            for (const rule of sheet.cssRules) {
-                if (rule instanceof CSSStyleRule &&
-                    (rule.selectorText === ':root' || rule.selectorText?.includes('html') || rule.selectorText?.includes('body'))) {
-                    for (let i = 0; i < rule.style.length; i++) {
-                        const prop = rule.style[i];
-                        if (prop.startsWith('--')) {
-                            customProperties[prop] = rule.style.getPropertyValue(prop).trim();
-                        }
-                    }
-                }
-                if (rule instanceof CSSFontFaceRule) {
-                    const family = rule.style.getPropertyValue('font-family').replace(/['"]/g, '').trim();
-                    const weight = rule.style.getPropertyValue('font-weight') || '400';
-                    const style = rule.style.getPropertyValue('font-style') || 'normal';
-                    const src = rule.style.getPropertyValue('src');
-                    const urlMatch = src.match(/url\(["']?([^"')]+)["']?\)/);
-                    const formatMatch = src.match(/format\(["']?([^"')]+)["']?\)/);
-                    if (urlMatch) {
-                        fontFiles.push({
-                            family,
-                            weight,
-                            style,
-                            src: urlMatch[1],
-                            format: formatMatch?.[1] || 'unknown',
-                        });
-                    }
-                }
-            }
-        }
-        catch { /* cross-origin stylesheet */ }
-    }
-    // Supplement with document.fonts API (catches cross-origin @font-face)
-    const seenFontSrcs = new Set(fontFiles.map(f => f.src));
-    try {
-        for (const face of document.fonts) {
-            if (face.status === 'loaded') {
-                // face.family is the CSS font-family, face.weight/style are strings
-                // Check if we already captured this via @font-face rules
-                const family = face.family.replace(/['"]/g, '').trim();
-                const weight = face.weight || '400';
-                const style = face.style || 'normal';
-                // document.fonts doesn't expose the URL, but we can match against loaded resources
-                if (!fontFiles.some(f => f.family === family && f.weight === weight && f.style === style)) {
-                    // Will be supplemented by Performance API below
-                }
-            }
-        }
-    }
-    catch { /* older browser */ }
-    // Use Performance API to find all loaded font resources (works cross-origin)
-    try {
-        const resources = performance.getEntriesByType('resource');
-        for (const r of resources) {
-            if (/\.(woff2?|ttf|otf|eot)(\?|$)/i.test(r.name) && !seenFontSrcs.has(r.name)) {
-                seenFontSrcs.add(r.name);
-                const formatMatch = r.name.match(/\.(woff2?|ttf|otf|eot)/i);
-                fontFiles.push({
-                    family: '', // can't determine from URL alone
-                    weight: '',
-                    style: '',
-                    src: r.name,
-                    format: formatMatch?.[1] || 'unknown',
-                });
-            }
-        }
-    }
-    catch { /* Performance API not available */ }
-    // --- Element traversal ---
-    const colorMap = new Map();
-    const spacingMap = new Map();
-    const borderRadiusMap = new Map();
-    const shadowMap = new Map();
-    const fontFamilyMap = new Map();
-    const typeScaleMap = new Map();
-    const animationMap = new Map();
-    const backgroundImageUrls = new Set();
-    function addColor(value, property) {
-        if (!value || value === 'transparent' || value === 'rgba(0, 0, 0, 0)' || value === 'inherit' || value === 'initial')
-            return;
-        const entry = colorMap.get(value);
-        if (entry) {
-            entry.count++;
-            entry.properties.add(property);
-        }
-        else {
-            colorMap.set(value, { count: 1, properties: new Set([property]) });
-        }
-    }
-    function addSpacing(value, property) {
-        if (!value || value === '0px' || value === 'auto' || value === 'normal')
-            return;
-        // Normalize multi-value shorthands — take individual values
-        const vals = value.split(/\s+/).filter(v => v !== '0px' && v !== 'auto');
-        for (const v of vals) {
-            if (!v.endsWith('px') && !v.endsWith('rem') && !v.endsWith('em'))
-                continue;
-            const entry = spacingMap.get(v);
-            if (entry) {
-                entry.count++;
-                entry.properties.add(property);
-            }
-            else {
-                spacingMap.set(v, { count: 1, properties: new Set([property]) });
-            }
-        }
-    }
-    function parseGradientColors(bg) {
-        const colorRegex = /(?:rgba?\([^)]+\)|hsla?\([^)]+\)|#[0-9a-fA-F]{3,8})/g;
-        const matches = bg.match(colorRegex) || [];
-        for (const c of matches)
-            addColor(c, 'gradient');
-    }
-    function parseShadowColors(shadow) {
-        if (shadow === 'none')
-            return;
-        const colorRegex = /(?:rgba?\([^)]+\)|hsla?\([^)]+\)|#[0-9a-fA-F]{3,8})/g;
-        const matches = shadow.match(colorRegex) || [];
-        for (const c of matches)
-            addColor(c, 'boxShadow');
-    }
-    const HEADING_TAGS = new Set(['H1', 'H2', 'H3', 'H4', 'H5', 'H6']);
-    const MONO_FAMILIES = /mono|consolas|courier|fira\s*code|jetbrains|source\s*code/i;
-    let elementCount = 0;
-    // Per-element extraction — shared between light DOM walker and shadow DOM walker
-    function processElement(el) {
-        const htmlEl = el;
-        if (htmlEl.offsetWidth === 0 && htmlEl.offsetHeight === 0)
-            return;
-        const cs = getComputedStyle(el);
-        // Colors
-        addColor(cs.color, 'color');
-        addColor(cs.backgroundColor, 'backgroundColor');
-        addColor(cs.borderTopColor, 'borderColor');
-        addColor(cs.borderRightColor, 'borderColor');
-        addColor(cs.borderBottomColor, 'borderColor');
-        addColor(cs.borderLeftColor, 'borderColor');
-        addColor(cs.outlineColor, 'outlineColor');
-        if (cs.backgroundImage.includes('gradient'))
-            parseGradientColors(cs.backgroundImage);
-        if (cs.backgroundImage.includes('url(')) {
-            const urlMatches = cs.backgroundImage.matchAll(/url\(["']?([^"')]+)["']?\)/g);
-            for (const m of urlMatches) {
-                const u = m[1];
-                if (u && !u.startsWith('data:') && !u.startsWith('blob:'))
-                    backgroundImageUrls.add(u);
-            }
-        }
-        if (cs.boxShadow !== 'none')
-            parseShadowColors(cs.boxShadow);
-        // Spacing
-        addSpacing(cs.paddingTop, 'padding');
-        addSpacing(cs.paddingRight, 'padding');
-        addSpacing(cs.paddingBottom, 'padding');
-        addSpacing(cs.paddingLeft, 'padding');
-        addSpacing(cs.marginTop, 'margin');
-        addSpacing(cs.marginRight, 'margin');
-        addSpacing(cs.marginBottom, 'margin');
-        addSpacing(cs.marginLeft, 'margin');
-        addSpacing(cs.gap, 'gap');
-        addSpacing(cs.rowGap, 'gap');
-        addSpacing(cs.columnGap, 'gap');
-        // Border radius
-        const br = cs.borderRadius;
-        if (br && br !== '0px') {
-            borderRadiusMap.set(br, (borderRadiusMap.get(br) ?? 0) + 1);
-        }
-        // Shadows
-        if (cs.boxShadow !== 'none') {
-            shadowMap.set(cs.boxShadow, (shadowMap.get(cs.boxShadow) ?? 0) + 1);
-        }
-        // Typography — only for elements with text content
-        if (el.childNodes.length > 0 && Array.from(el.childNodes).some(n => n.nodeType === Node.TEXT_NODE && n.textContent?.trim())) {
-            const family = cs.fontFamily;
-            const weight = parseInt(cs.fontWeight) || 400;
-            const isHeading = HEADING_TAGS.has(el.tagName);
-            const isMono = MONO_FAMILIES.test(family);
-            const fEntry = fontFamilyMap.get(family);
-            if (fEntry) {
-                fEntry.weights.add(weight);
-                if (isHeading)
-                    fEntry.headingUse = true;
-                if (isMono)
-                    fEntry.monoUse = true;
-            }
-            else {
-                fontFamilyMap.set(family, { weights: new Set([weight]), headingUse: isHeading, monoUse: isMono });
-            }
-            const scaleKey = `${cs.fontSize}|${cs.fontWeight}|${cs.lineHeight}|${cs.letterSpacing}|${family}`;
-            const scaleEntry = typeScaleMap.get(scaleKey);
-            if (scaleEntry) {
-                scaleEntry.count++;
-            }
-            else {
-                typeScaleMap.set(scaleKey, {
-                    fontSize: cs.fontSize,
-                    fontWeight: cs.fontWeight,
-                    lineHeight: cs.lineHeight,
-                    letterSpacing: cs.letterSpacing,
-                    fontFamily: family,
-                    tag: el.tagName.toLowerCase(),
-                    count: 1,
-                });
-            }
-        }
-        // Animations/transitions
-        if (cs.transition && cs.transition !== 'all 0s ease 0s' && cs.transition !== 'none') {
-            const key = cs.transition;
-            const aEntry = animationMap.get(key);
-            if (aEntry) {
-                aEntry.count++;
-            }
-            else {
-                animationMap.set(key, { property: 'transition', value: cs.transition, count: 1 });
-            }
-        }
-        if (cs.animationName && cs.animationName !== 'none') {
-            const key = `animation:${cs.animationName}`;
-            const aEntry = animationMap.get(key);
-            if (aEntry) {
-                aEntry.count++;
-            }
-            else {
-                animationMap.set(key, { property: 'animation', value: `${cs.animationName} ${cs.animationDuration} ${cs.animationTimingFunction}`, count: 1 });
-            }
-        }
-    }
-    // --- Light DOM walk ---
-    const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_ELEMENT);
-    let el = walker.currentNode;
-    while (el && elementCount < MAX_ELEMENTS) {
-        elementCount++;
-        processElement(el);
-        el = walker.nextNode();
-    }
-    // --- Shadow DOM walk ---
-    function walkShadowRoots(root) {
-        const shadowWalker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
-        // currentNode starts at root (ShadowRoot, not Element) — advance to first element
-        let shadowEl = shadowWalker.nextNode();
-        while (shadowEl && elementCount < MAX_ELEMENTS) {
-            elementCount++;
-            processElement(shadowEl);
-            if (shadowEl.shadowRoot) {
-                walkShadowRoots(shadowEl.shadowRoot);
-            }
-            shadowEl = shadowWalker.nextNode();
-        }
-    }
-    const allElements = document.body.querySelectorAll('*');
-    for (const bodyEl of allElements) {
-        if (bodyEl.shadowRoot && elementCount < MAX_ELEMENTS) {
-            walkShadowRoots(bodyEl.shadowRoot);
-        }
-    }
-    // --- Components: Buttons ---
-    const buttonStyles = [];
-    const btnFingerprints = new Map();
-    const BUTTON_STYLE_KEYS = ['backgroundColor', 'color', 'borderRadius', 'padding', 'fontSize', 'fontWeight', 'border', 'boxShadow', 'textTransform', 'letterSpacing'];
-    for (const btn of document.querySelectorAll('button, [role="button"], input[type="submit"], input[type="button"]')) {
-        const htmlBtn = btn;
-        if (htmlBtn.offsetWidth === 0 && htmlBtn.offsetHeight === 0)
-            continue;
-        const cs = getComputedStyle(btn);
-        const styles = {};
-        for (const k of BUTTON_STYLE_KEYS)
-            styles[k] = cs[k];
-        const fp = JSON.stringify(styles);
-        const existing = btnFingerprints.get(fp);
-        if (existing) {
-            existing.count++;
-        }
-        else {
-            const entry = { fingerprint: fp, count: 1, exampleText: htmlBtn.textContent?.trim().slice(0, 60) || '', styles };
-            btnFingerprints.set(fp, entry);
-        }
-    }
-    buttonStyles.push(...btnFingerprints.values());
-    // --- Components: Inputs ---
-    const inputStyles = [];
-    const inputFingerprints = new Map();
-    const INPUT_STYLE_KEYS = ['backgroundColor', 'color', 'borderRadius', 'padding', 'fontSize', 'border', 'boxShadow', 'outline'];
-    for (const inp of document.querySelectorAll('input[type="text"], input[type="email"], input[type="password"], input[type="search"], input[type="number"], input[type="tel"], input[type="url"], textarea, select, [role="textbox"], [role="combobox"]')) {
-        const htmlInp = inp;
-        if (htmlInp.offsetWidth === 0 && htmlInp.offsetHeight === 0)
-            continue;
-        const cs = getComputedStyle(inp);
-        const styles = {};
-        for (const k of INPUT_STYLE_KEYS)
-            styles[k] = cs[k];
-        const fp = JSON.stringify(styles);
-        const existing = inputFingerprints.get(fp);
-        if (existing) {
-            existing.count++;
-        }
-        else {
-            const entry = { fingerprint: fp, count: 1, exampleText: inp.placeholder?.slice(0, 60) || '', styles };
-            inputFingerprints.set(fp, entry);
-        }
-    }
-    inputStyles.push(...inputFingerprints.values());
-    // --- Components: Cards (elements with shadow or border-radius + multiple children) ---
-    const cardStyles = [];
-    const cardFingerprints = new Map();
-    const CARD_STYLE_KEYS = ['borderRadius', 'boxShadow', 'padding', 'backgroundColor', 'border'];
-    for (const el of document.querySelectorAll('div, section, article, li')) {
-        const htmlEl = el;
-        if (htmlEl.offsetWidth === 0 || htmlEl.children.length < 2)
-            continue;
-        const cs = getComputedStyle(el);
-        if (cs.boxShadow === 'none' && cs.borderRadius === '0px' && cs.border === '0px none rgb(0, 0, 0)')
-            continue;
-        const styles = {};
-        for (const k of CARD_STYLE_KEYS)
-            styles[k] = cs[k];
-        const fp = JSON.stringify(styles);
-        const existing = cardFingerprints.get(fp);
-        if (existing) {
-            existing.count++;
-        }
-        else {
-            const entry = { fingerprint: fp, count: 1, styles };
-            cardFingerprints.set(fp, entry);
-        }
-    }
-    // Only keep card patterns with 2+ instances (skip one-off containers)
-    for (const c of cardFingerprints.values()) {
-        if (c.count >= 2)
-            cardStyles.push(c);
-    }
-    // --- Components: Navigation ---
-    const navPatterns = [];
-    for (const nav of document.querySelectorAll('nav, [role="navigation"], header')) {
-        const cs = getComputedStyle(nav);
-        const links = nav.querySelectorAll('a');
-        if (links.length === 0)
-            continue;
-        const firstLinkCs = getComputedStyle(links[0]);
-        navPatterns.push({
-            selector: nav.tagName.toLowerCase() + (nav.className ? '.' + nav.className.split(/\s+/)[0] : ''),
-            layout: {
-                display: cs.display,
-                flexDirection: cs.flexDirection,
-                gap: cs.gap,
-                alignItems: cs.alignItems,
-                justifyContent: cs.justifyContent,
-                backgroundColor: cs.backgroundColor,
-                padding: cs.padding,
-            },
-            linkCount: links.length,
-            linkStyles: {
-                color: firstLinkCs.color,
-                fontSize: firstLinkCs.fontSize,
-                fontWeight: firstLinkCs.fontWeight,
-                textDecoration: firstLinkCs.textDecoration,
-            },
-        });
-    }
-    // --- Logos & Icons ---
-    const logos = [];
-    const icons = [];
-    // SVG logos (in header/nav or with logo-related attributes)
-    for (const svg of document.querySelectorAll('svg')) {
-        const parent = svg.closest('header, nav, [role="banner"]');
-        const classes = (svg.getAttribute('class') || '') + ' ' + (svg.parentElement?.getAttribute('class') || '');
-        const ariaLabel = svg.getAttribute('aria-label') || '';
-        const isLogo = parent !== null || /logo|brand|mark/i.test(classes) || /logo|brand/i.test(ariaLabel);
-        if (isLogo) {
-            const content = svg.outerHTML.slice(0, 4096);
-            logos.push({
-                type: 'svg',
-                width: svg.width?.baseVal?.value || undefined,
-                height: svg.height?.baseVal?.value || undefined,
-                svgContent: content,
-            });
-        }
-        else if (svg.outerHTML.length < 2048) {
-            // Collect as icon (small SVGs)
-            icons.push({
-                selector: svg.tagName + (svg.getAttribute('class') ? '.' + svg.getAttribute('class').split(/\s+/)[0] : ''),
-                viewBox: svg.getAttribute('viewBox') || undefined,
-                width: svg.width?.baseVal?.value || undefined,
-                height: svg.height?.baseVal?.value || undefined,
-                content: svg.outerHTML,
-            });
-        }
-    }
-    // IMG logos
-    for (const img of document.querySelectorAll('img')) {
-        const parent = img.closest('header, nav, [role="banner"]');
-        const src = img.src || '';
-        const alt = img.alt || '';
-        const classes = img.className || '';
-        if (parent !== null || /logo|brand|mark/i.test(src) || /logo|brand/i.test(alt) || /logo|brand/i.test(classes)) {
-            logos.push({
-                type: 'img',
-                src: img.src,
-                alt: img.alt || undefined,
-                width: img.naturalWidth || undefined,
-                height: img.naturalHeight || undefined,
-            });
-        }
-    }
-    // Limit icons to top 50 unique by viewBox
-    const seenViewBoxes = new Set();
-    const dedupedIcons = icons.filter(icon => {
-        const key = icon.viewBox || icon.content.slice(0, 100);
-        if (seenViewBoxes.has(key))
-            return false;
-        seenViewBoxes.add(key);
-        return true;
-    }).slice(0, 50);
-    // --- Brand Meta ---
-    const getMeta = (sel) => document.querySelector(sel)?.getAttribute('content') || undefined;
-    const getLink = (sel) => {
-        const el = document.querySelector(sel);
-        return el ? el.href || el.getAttribute('href') || undefined : undefined;
-    };
-    const brand = {
-        title: getMeta('meta[property="og:title"]') || document.title || undefined,
-        description: getMeta('meta[property="og:description"]') || getMeta('meta[name="description"]'),
-        themeColor: getMeta('meta[name="theme-color"]'),
-        favicon: getLink('link[rel="icon"]') || getLink('link[rel="shortcut icon"]'),
-        ogImage: getMeta('meta[property="og:image"]'),
-        appleTouchIcon: getLink('link[rel="apple-touch-icon"]'),
-        manifestUrl: getLink('link[rel="manifest"]'),
-    };
-    // --- All Image URLs ---
-    const imageUrls = new Set();
-    for (const img of document.querySelectorAll('img')) {
-        const src = img.src;
-        if (src && !src.startsWith('data:') && !src.startsWith('blob:'))
-            imageUrls.add(src);
-        const srcset = img.srcset;
-        if (srcset) {
-            for (const part of srcset.split(',')) {
-                const url = part.trim().split(/\s+/)[0];
-                if (url && !url.startsWith('data:') && !url.startsWith('blob:'))
-                    imageUrls.add(url);
-            }
-        }
-    }
-    // --- Video URLs ---
-    const videoUrls = new Set();
-    for (const video of document.querySelectorAll('video')) {
-        const src = video.src;
-        if (src && !src.startsWith('data:') && !src.startsWith('blob:'))
-            videoUrls.add(src);
-        const poster = video.poster;
-        if (poster && !poster.startsWith('data:') && !poster.startsWith('blob:'))
-            imageUrls.add(poster);
-        for (const source of video.querySelectorAll('source')) {
-            const ssrc = source.src;
-            if (ssrc && !ssrc.startsWith('data:') && !ssrc.startsWith('blob:'))
-                videoUrls.add(ssrc);
-        }
-    }
-    // Orphan <source> elements (audio, picture)
-    for (const source of document.querySelectorAll('source[src]')) {
-        const ssrc = source.src;
-        if (ssrc && /\.(mp4|webm|mov|ogg|avi|m3u8)/i.test(ssrc))
-            videoUrls.add(ssrc);
-    }
-    // <picture> <source> with srcset
-    for (const source of document.querySelectorAll('picture source[srcset]')) {
-        const srcset = source.srcset;
-        if (srcset) {
-            for (const part of srcset.split(',')) {
-                const url = part.trim().split(/\s+/)[0];
-                if (url && !url.startsWith('data:') && !url.startsWith('blob:'))
-                    imageUrls.add(url);
-            }
-        }
-    }
-    // --- Lazy-load data attributes ---
-    for (const el of document.querySelectorAll('[data-src], [data-bg], [data-background-image], [data-poster]')) {
-        for (const attr of ['data-src', 'data-bg', 'data-background-image', 'data-poster']) {
-            const val = el.getAttribute(attr);
-            if (!val || val.startsWith('data:') || val.startsWith('blob:'))
-                continue;
-            try {
-                const resolved = new URL(val, document.location.href).href;
-                if (/\.(mp4|webm|mov|ogg|avi|m3u8)/i.test(val))
-                    videoUrls.add(resolved);
-                else
-                    imageUrls.add(resolved);
-            }
-            catch { /* bad URL */ }
-        }
-    }
-    // --- Link Assets (favicons, icons, manifests) ---
-    const linkAssetUrls = [];
-    for (const link of document.querySelectorAll('link[href]')) {
-        const href = link.href;
-        const rel = link.rel || '';
-        if (href && !href.startsWith('data:') && !href.startsWith('blob:') &&
-            /^(icon|shortcut icon|apple-touch-icon|manifest|preload)$/i.test(rel)) {
-            linkAssetUrls.push({ url: href, rel });
-        }
-    }
-    // --- Inline script library detection ---
-    const detectedLibraries = [];
-    const seenLibs = new Set();
-    for (const script of document.querySelectorAll('script')) {
-        const src = script.src || '';
-        const text = script.textContent || '';
-        const content = src + ' ' + text.slice(0, 10_000);
-        const checks = [
-            [/gsap|ScrollTrigger|ScrollSmoother/i, 'gsap'],
-            [/new\s+p5\b|p5\.setup|p5\.draw|p5\.js/i, 'p5.js'],
-            [/THREE\.|new\s+THREE\.|from\s+['"]three/i, 'three.js'],
-            [/lottie|bodymovin/i, 'lottie'],
-            [/anime\s*\(|animejs/i, 'anime.js'],
-            [/framer-motion|motion\.div/i, 'framer-motion'],
-            [/webflow/i, 'webflow'],
-            [/swiper/i, 'swiper'],
-            [/locomotive.?scroll/i, 'locomotive-scroll'],
-            [/rive\.?app|@rive-app/i, 'rive'],
-            [/spline/i, 'spline'],
-        ];
-        for (const [regex, name] of checks) {
-            if (!seenLibs.has(name) && regex.test(content)) {
-                seenLibs.add(name);
-                detectedLibraries.push(name);
-            }
-        }
-    }
-    // --- Assemble result ---
-    return {
-        customProperties,
-        colors: Array.from(colorMap.entries())
-            .map(([value, data]) => ({ value, count: data.count, properties: Array.from(data.properties) }))
-            .sort((a, b) => b.count - a.count),
-        typography: {
-            families: Array.from(fontFamilyMap.entries()).map(([family, data]) => ({
-                family,
-                weights: Array.from(data.weights).sort((a, b) => a - b),
-                headingUse: data.headingUse,
-                monoUse: data.monoUse,
-            })),
-            scale: Array.from(typeScaleMap.values()).sort((a, b) => b.count - a.count),
-        },
-        brand,
-        logos,
-        icons: dedupedIcons,
-        spacing: Array.from(spacingMap.entries())
-            .map(([value, data]) => ({ value, count: data.count, properties: Array.from(data.properties) }))
-            .sort((a, b) => b.count - a.count),
-        borders: Array.from(borderRadiusMap.entries())
-            .map(([borderRadius, count]) => ({ borderRadius, count }))
-            .sort((a, b) => b.count - a.count),
-        shadows: Array.from(shadowMap.entries())
-            .map(([value, count]) => ({ value, count }))
-            .sort((a, b) => b.count - a.count),
-        components: {
-            buttons: buttonStyles.sort((a, b) => b.count - a.count),
-            inputs: inputStyles.sort((a, b) => b.count - a.count),
-            cards: cardStyles.sort((a, b) => b.count - a.count),
-            nav: navPatterns,
-        },
-        animations: Array.from(animationMap.values()).sort((a, b) => b.count - a.count),
-        fontFiles,
-        imageUrls: Array.from(imageUrls),
-        backgroundImageUrls: Array.from(backgroundImageUrls),
-        videoUrls: Array.from(videoUrls),
-        externalStylesheetUrls,
-        linkAssetUrls,
-        detectedLibraries,
-    };
-}
-// ---------------------------------------------------------------------------
-// Color clustering — assign semantic roles to extracted colors
-// ---------------------------------------------------------------------------
-function rgbaToHsl(rgba) {
-    const match = rgba.match(/rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)(?:\s*,\s*([\d.]+))?\s*\)/);
-    if (!match)
-        return null;
-    const r = parseFloat(match[1]) / 255;
-    const g = parseFloat(match[2]) / 255;
-    const b = parseFloat(match[3]) / 255;
-    const a = match[4] !== undefined ? parseFloat(match[4]) : 1;
-    const max = Math.max(r, g, b), min = Math.min(r, g, b);
-    const l = (max + min) / 2;
-    if (max === min)
-        return { h: 0, s: 0, l, a };
-    const d = max - min;
-    const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
-    let h = 0;
-    if (max === r)
-        h = ((g - b) / d + (g < b ? 6 : 0)) / 6;
-    else if (max === g)
-        h = ((b - r) / d + 2) / 6;
-    else
-        h = ((r - g) / d + 4) / 6;
-    return { h: h * 360, s: s * 100, l: l * 100, a };
-}
-function rgbaToHex(rgba) {
-    const match = rgba.match(/rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)(?:\s*,\s*([\d.]+))?\s*\)/);
-    if (!match)
-        return rgba;
-    const r = Math.round(parseFloat(match[1]));
-    const g = Math.round(parseFloat(match[2]));
-    const b = Math.round(parseFloat(match[3]));
-    const a = match[4] !== undefined ? parseFloat(match[4]) : 1;
-    const hex = `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b.toString(16).padStart(2, '0')}`;
-    if (a < 1)
-        return `${hex}${Math.round(a * 255).toString(16).padStart(2, '0')}`;
-    return hex;
-}
-function clusterColors(colors) {
-    const result = [];
-    let primaryHue = -1;
-    let secondaryHue = -1;
-    for (const c of colors) {
-        const hsl = rgbaToHsl(c.value);
-        const hex = rgbaToHex(c.value);
-        let cluster;
-        if (!hsl || hsl.s < 10) {
-            // Low saturation = neutral (grays, black, white)
-            if (hsl && hsl.l > 90)
-                cluster = 'background';
-            else
-                cluster = 'neutral';
-        }
-        else if (c.properties.includes('borderColor') && !c.properties.includes('color') && !c.properties.includes('backgroundColor')) {
-            cluster = 'border';
-        }
-        else if (primaryHue < 0) {
-            primaryHue = hsl.h;
-            cluster = 'primary';
-        }
-        else if (Math.abs(hsl.h - primaryHue) < 30 || Math.abs(hsl.h - primaryHue) > 330) {
-            cluster = 'primary';
-        }
-        else if (secondaryHue < 0) {
-            secondaryHue = hsl.h;
-            cluster = 'secondary';
-        }
-        else if (Math.abs(hsl.h - secondaryHue) < 30 || Math.abs(hsl.h - secondaryHue) > 330) {
-            cluster = 'secondary';
-        }
-        else {
-            cluster = 'accent';
-        }
-        result.push({ value: c.value, hex, count: c.count, properties: c.properties, cluster });
-    }
-    return result;
-}
-// ---------------------------------------------------------------------------
-// Grid base unit detection
-// ---------------------------------------------------------------------------
-function detectGridUnit(spacingValues) {
-    // Build frequency-weighted pairs
-    const pairs = spacingValues
-        .map(s => ({ px: parseFloat(s.value), count: s.count }))
-        .filter(p => p.px > 0 && p.px <= 200 && Number.isInteger(p.px));
-    if (pairs.length < 3)
-        return undefined;
-    // Score common grid units by how much of the total usage they explain
-    const CANDIDATES = [4, 5, 6, 8, 10];
-    let bestUnit = 0;
-    let bestScore = 0;
-    for (const unit of CANDIDATES) {
-        let aligned = 0;
-        let total = 0;
-        for (const p of pairs) {
-            total += p.count;
-            if (p.px % unit === 0)
-                aligned += p.count;
-        }
-        const score = aligned / total;
-        if (score > bestScore) {
-            bestScore = score;
-            bestUnit = unit;
-        }
-    }
-    // Require at least 60% of usage aligns with the grid
-    return bestScore >= 0.6 ? bestUnit : undefined;
-}
-// ---------------------------------------------------------------------------
-// Token extraction orchestrator
-// ---------------------------------------------------------------------------
-async function dismissCookieBanners(page) {
-    for (const sel of ['button:has-text("Accept all")', 'button:has-text("Accept")', 'button:has-text("Reject all")', 'button:has-text("Got it")', 'button:has-text("Close")']) {
-        const btn = page.locator(sel).first();
-        if (await btn.isVisible({ timeout: 500 }).catch(() => false)) {
-            await btn.click({ timeout: 2000 }).catch(() => null);
-            await page.waitForTimeout(500);
-            break;
-        }
-    }
-}
-/**
- * Extract design tokens from a URL at multiple viewports.
- * Pure DOM extraction — no LLM calls.
- *
- * ```typescript
- * import { extractDesignTokens } from '@tangle-network/browser-agent-driver'
- *
- * const { tokens } = await extractDesignTokens({ url: 'https://stripe.com' })
- * console.log(tokens.colors.filter(c => c.cluster === 'primary'))
- * console.log(tokens.typography.families)
- * console.log(tokens.brand)
- * ```
- */
-export async function extractDesignTokens(opts) {
-    const viewports = opts.viewports ?? [...VIEWPORTS];
-    const outputDir = opts.outputDir ?? `./audit-results/${new URL(opts.url).hostname}-tokens-${Date.now()}`;
-    fs.mkdirSync(outputDir, { recursive: true });
-    const screenshotDir = path.join(outputDir, 'screenshots');
-    fs.mkdirSync(screenshotDir, { recursive: true });
-    const browser = await chromium.launch({ headless: opts.headless ?? true });
-    const allCustomProps = {};
-    const allColors = new Map();
-    const allFamilies = new Map();
-    const allScaleEntries = [];
-    let brand = {};
-    const allLogos = [];
-    const allIcons = [];
-    const allFontFiles = new Map();
-    const allImageUrls = new Set();
-    const allBackgroundImageUrls = new Set();
-    const allVideoUrls = new Set();
-    const allExternalStylesheetUrls = new Set();
-    const allLinkAssetUrls = new Map(); // url -> rel
-    const allDetectedLibraries = new Set();
-    const responsiveTokens = {};
-    const screenshotPaths = {};
-    for (const vp of viewports) {
-        const context = await browser.newContext({ viewport: { width: vp.width, height: vp.height } });
-        const page = await context.newPage();
-        try {
-            await page.goto(opts.url, { waitUntil: 'networkidle', timeout: 20_000 }).catch(() => page.goto(opts.url, { waitUntil: 'domcontentloaded', timeout: 15_000 }));
-            await page.waitForTimeout(2000);
-            await dismissCookieBanners(page);
-            await page.waitForTimeout(500);
-            const screenshotPath = path.join(screenshotDir, `${vp.name}.png`);
-            await page.screenshot({ path: screenshotPath, fullPage: true }).catch(() => page.screenshot({ path: screenshotPath, fullPage: false }));
-            screenshotPaths[vp.name] = screenshotPath;
-            const raw = await page.evaluate(extractTokensFromDOM);
-            Object.assign(allCustomProps, raw.customProperties);
-            for (const c of raw.colors) {
-                const existing = allColors.get(c.value);
-                if (existing) {
-                    existing.count += c.count;
-                    for (const p of c.properties)
-                        existing.properties.add(p);
-                }
-                else {
-                    allColors.set(c.value, { count: c.count, properties: new Set(c.properties) });
-                }
-            }
-            for (const f of raw.typography.families) {
-                const existing = allFamilies.get(f.family);
-                if (existing) {
-                    for (const w of f.weights)
-                        existing.weights.add(w);
-                    if (f.headingUse)
-                        existing.headingUse = true;
-                    if (f.monoUse)
-                        existing.monoUse = true;
-                }
-                else {
-                    allFamilies.set(f.family, { weights: new Set(f.weights), headingUse: f.headingUse, monoUse: f.monoUse });
-                }
-            }
-            allScaleEntries.push(...raw.typography.scale);
-            if (vp.name === 'desktop' || !brand.title) {
-                brand = raw.brand;
-            }
-            for (const logo of raw.logos) {
-                if (!allLogos.some(l => l.src === logo.src && l.svgContent === logo.svgContent)) {
-                    allLogos.push(logo);
-                }
-            }
-            for (const icon of raw.icons) {
-                if (!allIcons.some(i => i.content === icon.content)) {
-                    allIcons.push(icon);
-                }
-            }
-            for (const ff of raw.fontFiles) {
-                if (!allFontFiles.has(ff.src)) {
-                    allFontFiles.set(ff.src, ff);
-                }
-            }
-            for (const u of raw.imageUrls)
-                allImageUrls.add(u);
-            for (const u of raw.backgroundImageUrls)
-                allBackgroundImageUrls.add(u);
-            for (const u of raw.videoUrls)
-                allVideoUrls.add(u);
-            for (const u of raw.externalStylesheetUrls)
-                allExternalStylesheetUrls.add(u);
-            for (const la of raw.linkAssetUrls)
-                allLinkAssetUrls.set(la.url, la.rel);
-            for (const lib of raw.detectedLibraries)
-                allDetectedLibraries.add(lib);
-            responsiveTokens[vp.name] = {
-                width: vp.width,
-                height: vp.height,
-                spacing: raw.spacing,
-                gridBaseUnit: detectGridUnit(raw.spacing),
-                borders: raw.borders,
-                shadows: raw.shadows,
-                components: raw.components,
-                animations: raw.animations,
-                screenshotPath,
-            };
-            opts.onProgress?.(vp.name, vp.width, vp.height, {
-                colors: raw.colors.length,
-                fonts: raw.typography.families.length,
-                buttons: raw.components.buttons.length,
-                inputs: raw.components.inputs.length,
-                cards: raw.components.cards.length,
-            });
-        }
-        finally {
-            await context.close();
-        }
-    }
-    await browser.close();
-    // Deduplicate type scale
-    const scaleMap = new Map();
-    for (const entry of allScaleEntries) {
-        const key = `${entry.fontSize}|${entry.fontWeight}|${entry.lineHeight}|${entry.fontFamily}`;
-        const existing = scaleMap.get(key);
-        if (existing) {
-            existing.count += entry.count;
-        }
-        else {
-            const isHeading = /^h[1-6]$/.test(entry.tag);
-            const fontSize = parseFloat(entry.fontSize);
-            let usage = 'body';
-            if (isHeading)
-                usage = 'heading';
-            else if (fontSize <= 12)
-                usage = 'caption';
-            else if (fontSize <= 14 && entry.fontWeight >= '500')
-                usage = 'label';
-            scaleMap.set(key, { fontSize: entry.fontSize, fontWeight: entry.fontWeight, lineHeight: entry.lineHeight, letterSpacing: entry.letterSpacing, fontFamily: entry.fontFamily, usage, tag: entry.tag, count: entry.count });
-        }
-    }
-    const mergedColors = Array.from(allColors.entries())
-        .map(([value, data]) => ({ value, count: data.count, properties: Array.from(data.properties) }))
-        .sort((a, b) => b.count - a.count);
-    const clusteredColors = clusterColors(mergedColors);
-    const families = Array.from(allFamilies.entries()).map(([family, data]) => ({
-        family,
-        weights: Array.from(data.weights).sort((a, b) => a - b),
-        classification: data.monoUse ? 'mono' :
-            (data.headingUse && allFamilies.size > 1) ? 'heading' :
-                data.headingUse ? 'display' : 'body',
-    }));
-    // Download font files
-    const downloadedFontFiles = [];
-    if (allFontFiles.size > 0) {
-        const fontDir = path.join(outputDir, 'fonts');
-        fs.mkdirSync(fontDir, { recursive: true });
-        for (const ff of allFontFiles.values()) {
-            try {
-                const res = await fetch(ff.src);
-                if (!res.ok)
-                    continue;
-                const buffer = Buffer.from(await res.arrayBuffer());
-                const urlPath = decodeURIComponent(new URL(ff.src).pathname);
-                const filename = path.basename(urlPath) || `${ff.family.replace(/\s+/g, '-')}-${ff.weight}-${ff.style}.${ff.format === 'unknown' ? 'bin' : ff.format}`;
-                const localPath = path.join(fontDir, filename);
-                fs.writeFileSync(localPath, buffer);
-                downloadedFontFiles.push({ ...ff, localPath });
-            }
-            catch {
-                downloadedFontFiles.push({ ...ff });
-            }
-        }
-    }
-    // Download images
-    const downloadedImages = [];
-    const allAssetUrls = new Map();
-    for (const u of allImageUrls)
-        allAssetUrls.set(u, 'img');
-    for (const u of allBackgroundImageUrls)
-        allAssetUrls.set(u, 'background');
-    // Brand assets
-    if (brand.favicon)
-        allAssetUrls.set(brand.favicon, 'favicon');
-    if (brand.ogImage)
-        allAssetUrls.set(brand.ogImage, 'og-image');
-    if (brand.appleTouchIcon)
-        allAssetUrls.set(brand.appleTouchIcon, 'icon');
-    for (const [url, rel] of allLinkAssetUrls) {
-        if (/icon/i.test(rel))
-            allAssetUrls.set(url, 'favicon');
-    }
-    if (allAssetUrls.size > 0) {
-        const imageDir = path.join(outputDir, 'images');
-        fs.mkdirSync(imageDir, { recursive: true });
-        for (const [url, type] of allAssetUrls) {
-            try {
-                const res = await fetch(url);
-                if (!res.ok) {
-                    downloadedImages.push({ url, type });
-                    continue;
-                }
-                const buffer = Buffer.from(await res.arrayBuffer());
-                const urlPath = decodeURIComponent(new URL(url).pathname);
-                const filename = path.basename(urlPath) || `asset-${downloadedImages.length}.bin`;
-                const localPath = path.join(imageDir, filename);
-                fs.writeFileSync(localPath, buffer);
-                downloadedImages.push({
-                    url, type, localPath,
-                    mimeType: res.headers.get('content-type') || undefined,
-                    sizeBytes: buffer.length,
-                });
-            }
-            catch {
-                downloadedImages.push({ url, type });
-            }
-        }
-    }
-    // Download external stylesheets
-    const downloadedStylesheets = [];
-    if (allExternalStylesheetUrls.size > 0) {
-        const cssDir = path.join(outputDir, 'stylesheets');
-        fs.mkdirSync(cssDir, { recursive: true });
-        for (const url of allExternalStylesheetUrls) {
-            try {
-                const res = await fetch(url);
-                if (!res.ok) {
-                    downloadedStylesheets.push({ url });
-                    continue;
-                }
-                const text = await res.text();
-                const urlPath = decodeURIComponent(new URL(url).pathname);
-                const filename = path.basename(urlPath) || `style-${downloadedStylesheets.length}.css`;
-                const localPath = path.join(cssDir, filename);
-                fs.writeFileSync(localPath, text);
-                downloadedStylesheets.push({ url, localPath });
-            }
-            catch {
-                downloadedStylesheets.push({ url });
-            }
-        }
-    }
-    // Download videos
-    const downloadedVideos = [];
-    if (allVideoUrls.size > 0) {
-        const videoDir = path.join(outputDir, 'videos');
-        fs.mkdirSync(videoDir, { recursive: true });
-        for (const url of allVideoUrls) {
-            try {
-                const res = await fetch(url);
-                if (!res.ok) {
-                    downloadedVideos.push({ url, type: 'video' });
-                    continue;
-                }
-                const buffer = Buffer.from(await res.arrayBuffer());
-                const urlPath = decodeURIComponent(new URL(url).pathname);
-                const filename = path.basename(urlPath) || `video-${downloadedVideos.length}.mp4`;
-                const localPath = path.join(videoDir, filename);
-                fs.writeFileSync(localPath, buffer);
-                downloadedVideos.push({
-                    url, type: 'video', localPath,
-                    mimeType: res.headers.get('content-type') || undefined,
-                    sizeBytes: buffer.length,
-                });
-            }
-            catch {
-                downloadedVideos.push({ url, type: 'video' });
-            }
-        }
-    }
-    const tokens = {
-        url: opts.url,
-        extractedAt: new Date().toISOString(),
-        viewportsAudited: viewports.map(v => v.name),
-        customProperties: allCustomProps,
-        colors: clusteredColors,
-        typography: { families, scale: Array.from(scaleMap.values()).sort((a, b) => b.count - a.count) },
-        brand,
-        logos: allLogos,
-        icons: allIcons.slice(0, 50),
-        fontFiles: downloadedFontFiles,
-        images: downloadedImages,
-        videos: downloadedVideos,
-        stylesheets: downloadedStylesheets,
-        responsive: responsiveTokens,
-        detectedLibraries: Array.from(allDetectedLibraries),
-    };
-    const tokenPath = path.join(outputDir, 'tokens.json');
-    fs.writeFileSync(tokenPath, JSON.stringify(tokens, null, 2));
-    return { tokens, outputDir, screenshotPaths };
-}
-// ---------------------------------------------------------------------------
-// Zip packaging
-// ---------------------------------------------------------------------------
-async function createZipBundle(outputDir, tokens) {
-    const { execSync } = await import('node:child_process');
-    const zipPath = `${outputDir}.zip`;
-    // Use system zip (available on macOS/Linux)
-    execSync(`cd "${path.dirname(outputDir)}" && zip -r "${path.basename(zipPath)}" "${path.basename(outputDir)}"`, { stdio: 'pipe' });
-    return zipPath;
-}
 // ---------------------------------------------------------------------------
 // CLI wrapper for token extraction
 // ---------------------------------------------------------------------------