prism-design 2.13.0

package/scripts/compare-vs-gd.ts

@@ -0,0 +1,269 @@
+/**
+ * Prism vs GetDesign — Comparison Framework
+ *
+ * Pour chaque brand qui existe à la fois dans extractions/ (CA) et compare-gd/ (GD),
+ * compute des métriques side-by-side et output un JSON structuré + Markdown report.
+ *
+ * Usage: npx tsx scripts/compare-vs-gd.ts [brands...]
+ *        npx tsx scripts/compare-vs-gd.ts --all
+ */
+
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+
+interface BrandMetrics {
+  domain: string;
+  hasCA: boolean;
+  hasGD: boolean;
+  ca?: {
+    designMdLines: number;
+    sectionsCount: number;
+    colorsCount: number;
+    fontFamiliesCount: number;
+    hasScreenshots: boolean;
+    hasTokensJson: boolean;
+    completenessScore: number;
+    sizeKb: number;
+    dark: boolean;
+    extractedAt: string;
+  };
+  gd?: {
+    designMdLines: number;
+    sectionsCount: number;
+    colorsNamed: number;
+    fontFamiliesCount: number;
+    hasFrontmatter: boolean;
+    sizeKb: number;
+  };
+  winner?: {
+    volume: 'CA' | 'GD' | 'tie';
+    colorRichness: 'CA' | 'GD' | 'tie';
+    verifiability: 'CA' | 'GD';
+    narrative: 'CA' | 'GD';
+  };
+}
+
+const ROOT = process.cwd();
+
+const GD_DOMAIN_MAP: Record<string, string> = {
+  'airbnb': 'airbnb.com', 'cal': 'cal.com', 'clickhouse': 'clickhouse.com',
+  'cursor': 'cursor.com', 'figma': 'figma.com', 'framer': 'framer.com',
+  'github': 'github.com', 'linear': 'linear.app', 'loom': 'loom.com',
+  'lovable': 'lovable.dev', 'minimax': 'minimax.io', 'mintlify': 'mintlify.com',
+  'miro': 'miro.com', 'mistral.ai': 'mistral.ai', 'mongodb': 'mongodb.com',
+  'nike': 'nike.com', 'notion': 'notion.so', 'nvidia': 'nvidia.com',
+  'ollama': 'ollama.com', 'opencode.ai': 'opencode.ai', 'posthog': 'posthog.com',
+  'revolut': 'revolut.com', 'starbucks': 'starbucks.com', 'stripe': 'stripe.com',
+  'theverge': 'theverge.com', 'together.ai': 'together.ai', 'vercel': 'vercel.com',
+  'vodafone': 'vodafone.com',
+};
+
+const DOMAIN_TO_GD: Record<string, string> = Object.fromEntries(
+  Object.entries(GD_DOMAIN_MAP).map(([gd, dom]) => [dom, gd])
+);
+
+function countSections(content: string): number {
+  // Count lines starting with "## " (H2 markdown headers)
+  const lines = content.split('\n');
+  return lines.filter(l => l.match(/^##\s+\d?\.?\s*[A-Z]/)).length;
+}
+
+function countColorsInDesignMd(content: string): number {
+  // Count hex codes referenced
+  const hexes = content.match(/#[0-9a-fA-F]{6}\b/g) || [];
+  const rgbs = content.match(/rgb\([^)]+\)/g) || [];
+  return new Set([...hexes, ...rgbs]).size;
+}
+
+function countFontFamilies(content: string): number {
+  const matches = content.match(/font[-_]family[^:\n]*:[^\n]+/gi) || [];
+  return matches.length;
+}
+
+function analyzeCABrand(domain: string): BrandMetrics['ca'] | undefined {
+  const extractDir = join(ROOT, 'extractions', domain);
+  const designMdPath = join(extractDir, 'DESIGN.md');
+  const tokensPath = join(extractDir, 'tokens.json');
+  const screenshotsPath = join(extractDir, 'screenshots');
+  const summaryPath = join(extractDir, 'extraction-summary.json');
+
+  if (!existsSync(designMdPath)) return undefined;
+
+  const content = readFileSync(designMdPath, 'utf-8');
+  const lines = content.split('\n').length;
+  const sectionsCount = countSections(content);
+  const colorsCount = countColorsInDesignMd(content);
+  const fontFamiliesCount = countFontFamilies(content);
+  const sizeKb = Math.round(Buffer.byteLength(content, 'utf-8') / 1024);
+
+  // Read catalog for completeness score
+  const catalogPath = join(ROOT, 'catalog', 'index.json');
+  const catalog = JSON.parse(readFileSync(catalogPath, 'utf-8'));
+  const brandEntry = catalog.brands.find((b: any) => b.domain === domain);
+
+  return {
+    designMdLines: lines,
+    sectionsCount,
+    colorsCount,
+    fontFamiliesCount,
+    hasScreenshots: existsSync(screenshotsPath),
+    hasTokensJson: existsSync(tokensPath),
+    completenessScore: brandEntry?.completeness || 0,
+    sizeKb,
+    dark: brandEntry?.dark || false,
+    extractedAt: brandEntry?.extractedAt || '?',
+  };
+}
+
+function analyzeGDBrand(domain: string): BrandMetrics['gd'] | undefined {
+  const gdSlug = DOMAIN_TO_GD[domain];
+  if (!gdSlug) return undefined;
+
+  const gdPath = join(ROOT, 'compare-gd', gdSlug, 'GD-DESIGN.md');
+  if (!existsSync(gdPath)) return undefined;
+
+  const content = readFileSync(gdPath, 'utf-8');
+  const lines = content.split('\n').length;
+  const sectionsCount = countSections(content);
+  const colorsNamed = countColorsInDesignMd(content);
+  const fontFamiliesCount = countFontFamilies(content);
+  const hasFrontmatter = content.startsWith('---\n') || content.startsWith('---\r\n');
+  const sizeKb = Math.round(Buffer.byteLength(content, 'utf-8') / 1024);
+
+  return { designMdLines: lines, sectionsCount, colorsNamed, fontFamiliesCount, hasFrontmatter, sizeKb };
+}
+
+function determineWinner(ca: BrandMetrics['ca'], gd: BrandMetrics['gd']): BrandMetrics['winner'] {
+  if (!ca || !gd) return undefined;
+  return {
+    volume: ca.designMdLines > gd.designMdLines * 1.1 ? 'CA'
+      : gd.designMdLines > ca.designMdLines * 1.1 ? 'GD' : 'tie',
+    colorRichness: ca.colorsCount > gd.colorsNamed * 1.1 ? 'CA'
+      : gd.colorsNamed > ca.colorsCount * 1.1 ? 'GD' : 'tie',
+    verifiability: ca.hasScreenshots && ca.hasTokensJson ? 'CA' : 'GD',
+    narrative: gd.hasFrontmatter ? 'GD' : 'CA', // GD has YAML frontmatter narrative
+  };
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const allMode = args.includes('--all');
+
+  // Build the list of domains to compare
+  let domains: string[];
+  if (allMode) {
+    domains = Object.values(GD_DOMAIN_MAP);
+  } else if (args.length > 0) {
+    domains = args.filter(a => !a.startsWith('--'));
+  } else {
+    domains = Object.values(GD_DOMAIN_MAP);
+  }
+
+  console.log(`🔬 Prism vs GetDesign — comparison of ${domains.length} brands\n`);
+
+  const results: BrandMetrics[] = [];
+  let caWins = { volume: 0, color: 0, verif: 0, narrative: 0 };
+  let gdWins = { volume: 0, color: 0, verif: 0, narrative: 0 };
+
+  for (const domain of domains) {
+    const ca = analyzeCABrand(domain);
+    const gd = analyzeGDBrand(domain);
+
+    const metrics: BrandMetrics = {
+      domain,
+      hasCA: !!ca,
+      hasGD: !!gd,
+      ca,
+      gd,
+      winner: ca && gd ? determineWinner(ca, gd) : undefined,
+    };
+
+    if (metrics.winner) {
+      if (metrics.winner.volume === 'CA') caWins.volume++;
+      else if (metrics.winner.volume === 'GD') gdWins.volume++;
+      if (metrics.winner.colorRichness === 'CA') caWins.color++;
+      else if (metrics.winner.colorRichness === 'GD') gdWins.color++;
+      if (metrics.winner.verifiability === 'CA') caWins.verif++;
+      else gdWins.verif++;
+      if (metrics.winner.narrative === 'CA') caWins.narrative++;
+      else gdWins.narrative++;
+    }
+
+    results.push(metrics);
+
+    const statusCA = ca ? `✅ ${ca.designMdLines}L ${ca.colorsCount}c ${ca.completenessScore}/100` : '❌';
+    const statusGD = gd ? `✅ ${gd.designMdLines}L ${gd.colorsNamed}c` : '❌';
+    console.log(`${domain.padEnd(20)} CA: ${statusCA.padEnd(30)} GD: ${statusGD}`);
+  }
+
+  // Aggregate stats
+  const compared = results.filter(r => r.hasCA && r.hasGD);
+  const avgCALines = compared.reduce((s, r) => s + (r.ca?.designMdLines || 0), 0) / compared.length;
+  const avgGDLines = compared.reduce((s, r) => s + (r.gd?.designMdLines || 0), 0) / compared.length;
+  const avgCAColors = compared.reduce((s, r) => s + (r.ca?.colorsCount || 0), 0) / compared.length;
+  const avgGDColors = compared.reduce((s, r) => s + (r.gd?.colorsNamed || 0), 0) / compared.length;
+  const avgCAScore = compared.reduce((s, r) => s + (r.ca?.completenessScore || 0), 0) / compared.length;
+
+  console.log('\n══════════════════════════════════════════════════');
+  console.log('📊 AGGREGATE METRICS');
+  console.log('══════════════════════════════════════════════════');
+  console.log(`Compared brands     : ${compared.length} / ${domains.length}`);
+  console.log(`Avg lines           : CA ${avgCALines.toFixed(0)} vs GD ${avgGDLines.toFixed(0)} (CA ${(avgCALines/avgGDLines).toFixed(1)}x)`);
+  console.log(`Avg colors          : CA ${avgCAColors.toFixed(1)} vs GD ${avgGDColors.toFixed(1)} (GD ${(avgGDColors/avgCAColors).toFixed(1)}x)`);
+  console.log(`Avg completeness CA : ${avgCAScore.toFixed(0)}/100`);
+  console.log('');
+  console.log('🏆 WINS PER DIMENSION');
+  console.log(`Volume         : CA ${caWins.volume} | GD ${gdWins.volume}`);
+  console.log(`Color richness : CA ${caWins.color} | GD ${gdWins.color}`);
+  console.log(`Verifiability  : CA ${caWins.verif} | GD ${gdWins.verif}`);
+  console.log(`Narrative      : CA ${caWins.narrative} | GD ${gdWins.narrative}`);
+
+  // Save outputs
+  const outDir = join(ROOT, 'docs', 'comparison');
+  mkdirSync(outDir, { recursive: true });
+
+  const jsonPath = join(outDir, 'ca-vs-gd-metrics.json');
+  writeFileSync(jsonPath, JSON.stringify({
+    generatedAt: new Date().toISOString(),
+    totalBrands: domains.length,
+    comparedCount: compared.length,
+    avg: { caLines: avgCALines, gdLines: avgGDLines, caColors: avgCAColors, gdColors: avgGDColors, caScore: avgCAScore },
+    wins: { ca: caWins, gd: gdWins },
+    brands: results,
+  }, null, 2));
+  console.log(`\n💾 JSON output → ${jsonPath}`);
+
+  // Markdown report
+  const mdPath = join(outDir, 'ca-vs-gd-report.md');
+  let md = `# Prism vs getdesign.md — Comparison Report\n\n`;
+  md += `Generated: ${new Date().toISOString()}\n\n`;
+  md += `## Aggregate Metrics\n\n`;
+  md += `| Metric | Prism | getdesign.md | Ratio |\n`;
+  md += `|---|---|---|---|\n`;
+  md += `| Brands compared | ${compared.length} / ${domains.length} | — | — |\n`;
+  md += `| Avg DESIGN.md lines | ${avgCALines.toFixed(0)} | ${avgGDLines.toFixed(0)} | CA ${(avgCALines/avgGDLines).toFixed(1)}× |\n`;
+  md += `| Avg colors referenced | ${avgCAColors.toFixed(1)} | ${avgGDColors.toFixed(1)} | GD ${(avgGDColors/avgCAColors).toFixed(1)}× |\n`;
+  md += `| Avg CA completeness | ${avgCAScore.toFixed(0)}/100 | — | — |\n`;
+  md += `\n## Wins per Dimension\n\n`;
+  md += `| Dimension | CA wins | GD wins |\n`;
+  md += `|---|---|---|\n`;
+  md += `| Volume (lines) | ${caWins.volume} | ${gdWins.volume} |\n`;
+  md += `| Color richness | ${caWins.color} | ${gdWins.color} |\n`;
+  md += `| Verifiability (screenshots+tokens) | ${caWins.verif} | ${gdWins.verif} |\n`;
+  md += `| Narrative editorial | ${caWins.narrative} | ${gdWins.narrative} |\n`;
+  md += `\n## Per-Brand Details\n\n`;
+  md += `| Brand | CA lines | GD lines | CA colors | GD colors | CA score | Winner volume | Winner color |\n`;
+  md += `|---|---|---|---|---|---|---|---|\n`;
+  for (const r of results) {
+    if (!r.hasCA || !r.hasGD) {
+      md += `| ${r.domain} | ${r.hasCA ? '✅' : '❌'} | ${r.hasGD ? '✅' : '❌'} | — | — | — | — | — |\n`;
+    } else {
+      md += `| ${r.domain} | ${r.ca?.designMdLines} | ${r.gd?.designMdLines} | ${r.ca?.colorsCount} | ${r.gd?.colorsNamed} | ${r.ca?.completenessScore} | ${r.winner?.volume} | ${r.winner?.colorRichness} |\n`;
+    }
+  }
+
+  writeFileSync(mdPath, md);
+  console.log(`📄 Markdown report → ${mdPath}`);
+}
+
+main().catch(err => { console.error(err); process.exit(1); });

package/scripts/compare.ts

@@ -0,0 +1,405 @@
+/**
+ * Prism — Visual Comparison (pixel-level)
+ *
+ * Compare le screenshot original avec le code genere via pixelmatch.
+ * Produit un diff image (pixels rouges = differences) et un score de similarite.
+ */
+
+import { chromium } from 'playwright';
+import { readFile, writeFile, mkdir, readdir, stat } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { PNG } from 'pngjs';
+import pixelmatch from 'pixelmatch';
+
+interface ComparisonResult {
+  domain: string;
+  timestamp: string;
+  originalScreenshot: string;
+  generatedScreenshot: string;
+  diffImage: string;
+  viewport: string;
+  differences: string[];
+  score: number;
+  ssim: number;
+  verdict: 'PASS' | 'NEEDS-REVISION' | 'FAIL';
+  pixelStats: {
+    totalPixels: number;
+    diffPixels: number;
+    matchPercent: number;
+  };
+}
+
+/**
+ * Parse a PNG file buffer into a PNG object.
+ */
+function decodePNG(buffer: Buffer): PNG {
+  return PNG.sync.read(buffer);
+}
+
+// ── Structural similarity (SSIM) ──────────────────────────────────────────────
+// v2.13 — pixelmatch is dominated by large flat fills (background), so it can't tell a
+// structural clone from a token re-skin (both get the background right). SSIM compares LOCAL
+// luminance/contrast/structure in windows, so it actually rewards reproducing the layout
+// (hero position, heading mass, banding). We report BOTH: pixelmatch = flat-area match,
+// SSIM = structural match. The honest "fidelity" headline is the structure-aware one.
+
+/** Downsample an RGBA PNG to grayscale at a target width (box filter). */
+function toGray(png: PNG, targetW: number): { w: number; h: number; data: Float64Array } {
+  const w = Math.max(1, Math.min(targetW, png.width));
+  const h = Math.max(1, Math.round(png.height * (w / png.width)));
+  const data = new Float64Array(w * h);
+  const sx = png.width / w, sy = png.height / h;
+  for (let y = 0; y < h; y++) {
+    const y0 = Math.floor(y * sy), y1 = Math.max(y0 + 1, Math.floor((y + 1) * sy));
+    for (let x = 0; x < w; x++) {
+      const x0 = Math.floor(x * sx), x1 = Math.max(x0 + 1, Math.floor((x + 1) * sx));
+      let sum = 0, n = 0;
+      for (let yy = y0; yy < Math.min(y1, png.height); yy++) {
+        for (let xx = x0; xx < Math.min(x1, png.width); xx++) {
+          const i = (yy * png.width + xx) * 4;
+          sum += 0.2126 * png.data[i] + 0.7152 * png.data[i + 1] + 0.0722 * png.data[i + 2];
+          n++;
+        }
+      }
+      data[y * w + x] = n ? sum / n : 0;
+    }
+  }
+  return { w, h, data };
+}
+
+/** Mean SSIM over non-overlapping 8×8 blocks → 0..1. */
+function meanSSIM(a: { w: number; h: number; data: Float64Array }, b: { w: number; h: number; data: Float64Array }): number {
+  const w = Math.min(a.w, b.w), h = Math.min(a.h, b.h);
+  const C1 = 6.5025, C2 = 58.5225, B = 8, N = B * B;
+  let total = 0, blocks = 0;
+  for (let by = 0; by + B <= h; by += B) {
+    for (let bx = 0; bx + B <= w; bx += B) {
+      let ma = 0, mb = 0;
+      for (let y = 0; y < B; y++) for (let x = 0; x < B; x++) {
+        ma += a.data[(by + y) * a.w + bx + x];
+        mb += b.data[(by + y) * b.w + bx + x];
+      }
+      ma /= N; mb /= N;
+      let va = 0, vb = 0, cov = 0;
+      for (let y = 0; y < B; y++) for (let x = 0; x < B; x++) {
+        const da = a.data[(by + y) * a.w + bx + x] - ma;
+        const db = b.data[(by + y) * b.w + bx + x] - mb;
+        va += da * da; vb += db * db; cov += da * db;
+      }
+      va /= N - 1; vb /= N - 1; cov /= N - 1;
+      total += ((2 * ma * mb + C1) * (2 * cov + C2)) / ((ma * ma + mb * mb + C1) * (va + vb + C2));
+      blocks++;
+    }
+  }
+  return blocks ? total / blocks : 0;
+}
+
+/** Structure-aware similarity 0..100 between two same-sized PNGs (downsampled to 512px wide). */
+function structuralSimilarity(png1: PNG, png2: PNG): number {
+  const s = meanSSIM(toGray(png1, 512), toGray(png2, 512));
+  return Math.round(Math.max(0, Math.min(1, s)) * 100);
+}
+
+/**
+ * Resize a PNG to target dimensions by cropping (top-left) or padding (transparent).
+ * Returns a new PNG with exactly targetWidth x targetHeight.
+ */
+function resizePNG(src: PNG, targetWidth: number, targetHeight: number): PNG {
+  const dst = new PNG({ width: targetWidth, height: targetHeight, fill: true });
+  // fill with transparent black
+  dst.data.fill(0);
+
+  const copyW = Math.min(src.width, targetWidth);
+  const copyH = Math.min(src.height, targetHeight);
+
+  for (let y = 0; y < copyH; y++) {
+    const srcOffset = y * src.width * 4;
+    const dstOffset = y * targetWidth * 4;
+    src.data.copy(dst.data, dstOffset, srcOffset, srcOffset + copyW * 4);
+  }
+
+  return dst;
+}
+
+async function screenshotGenerated(
+  htmlPath: string,
+  outputPath: string,
+  viewport: { width: number; height: number },
+): Promise<void> {
+  const browser = await chromium.launch({ headless: true, args: ['--no-sandbox'] });
+  // v2.12 — match the originals' 2× device scale so we compare like-for-like (originals are
+  //   captured at deviceScaleFactor 2 → 2880px wide). Comparing a 1× render against a 2× original
+  //   silently inflated/distorted scores via the crop-to-common-area fallback.
+  const context = await browser.newContext({ viewport, deviceScaleFactor: 2 });
+  const page = await context.newPage();
+
+  await page.goto(`file://${htmlPath}`, { waitUntil: 'networkidle' });
+  await page.waitForTimeout(1000);
+  await page.screenshot({ path: outputPath, fullPage: true });
+
+  await browser.close();
+}
+
+/**
+ * Pixel-level comparison using pixelmatch.
+ * Generates a diff image and returns a similarity score.
+ */
+async function comparePixels(
+  img1Path: string,
+  img2Path: string,
+  diffOutputPath: string,
+): Promise<{ score: number; ssim: number; differences: string[]; pixelStats: { totalPixels: number; diffPixels: number; matchPercent: number } }> {
+  const differences: string[] = [];
+
+  // Read both images
+  let buf1: Buffer;
+  let buf2: Buffer;
+  try {
+    buf1 = await readFile(img1Path);
+  } catch {
+    return {
+      score: 0,
+      differences: [`Original image not found: ${img1Path}`],
+      ssim: 0,
+      pixelStats: { totalPixels: 0, diffPixels: 0, matchPercent: 0 },
+    };
+  }
+  try {
+    buf2 = await readFile(img2Path);
+  } catch {
+    return {
+      score: 0,
+      differences: [`Generated image not found: ${img2Path}`],
+      ssim: 0,
+      pixelStats: { totalPixels: 0, diffPixels: 0, matchPercent: 0 },
+    };
+  }
+
+  // Decode PNGs
+  let png1: PNG;
+  let png2: PNG;
+  try {
+    png1 = decodePNG(buf1);
+    png2 = decodePNG(buf2);
+  } catch (err) {
+    return {
+      score: 0,
+      differences: [`Failed to decode PNG: ${err}`],
+      ssim: 0,
+      pixelStats: { totalPixels: 0, diffPixels: 0, matchPercent: 0 },
+    };
+  }
+
+  // Log original dimensions
+  if (png1.width !== png2.width || png1.height !== png2.height) {
+    differences.push(
+      `Size mismatch: original ${png1.width}x${png1.height} vs generated ${png2.width}x${png2.height} — cropped to common area`,
+    );
+  }
+
+  // Use the smaller dimensions so we compare the common area
+  const width = Math.min(png1.width, png2.width);
+  const height = Math.min(png1.height, png2.height);
+
+  // Resize both to the common dimensions
+  const resized1 = resizePNG(png1, width, height);
+  const resized2 = resizePNG(png2, width, height);
+
+  // Create diff output image
+  const diff = new PNG({ width, height });
+
+  // Run pixelmatch
+  const diffPixels = pixelmatch(
+    resized1.data,
+    resized2.data,
+    diff.data,
+    width,
+    height,
+    {
+      threshold: 0.1,
+      includeAA: false,
+      alpha: 0.1,
+    },
+  );
+
+  // Write diff image
+  const diffBuffer = PNG.sync.write(diff);
+  await writeFile(diffOutputPath, diffBuffer);
+
+  const totalPixels = width * height;
+  const matchPercent = totalPixels > 0 ? ((1 - diffPixels / totalPixels) * 100) : 0;
+  const score = Math.round(matchPercent);
+  const ssim = structuralSimilarity(resized1, resized2);
+
+  // Add diagnostic differences
+  if (diffPixels > 0) {
+    const diffPercent = ((diffPixels / totalPixels) * 100).toFixed(2);
+    differences.push(`${diffPixels.toLocaleString()} pixels differ (${diffPercent}% of ${totalPixels.toLocaleString()} total)`);
+  }
+
+  if (score < 60) {
+    differences.push('Major structural differences detected — layout likely diverges significantly');
+  } else if (score < 85) {
+    differences.push('Moderate differences — colors, spacing, or minor layout issues');
+  }
+
+  if (score >= 60 && ssim < 45) {
+    differences.push(`Structure diverges (SSIM ${ssim}/100) despite ${score}% flat-area match — background matches, layout does not`);
+  }
+
+  return {
+    score,
+    ssim,
+    differences,
+    pixelStats: { totalPixels, diffPixels, matchPercent: Math.round(matchPercent * 100) / 100 },
+  };
+}
+
+async function compare(domain: string): Promise<void> {
+  const baseDir = join(process.cwd(), 'extractions', domain);
+  const comparisonDir = join(baseDir, 'comparison');
+  const screenshotDir = join(baseDir, 'screenshots');
+  const outputDir = join(baseDir, 'output');
+
+  await mkdir(comparisonDir, { recursive: true });
+
+  console.log(`\n🔍 Comparing results for ${domain}...`);
+
+  // Check if output exists
+  try {
+    await readdir(outputDir);
+  } catch {
+    console.error(`No output directory found at ${outputDir}`);
+    console.error('Generate code first, then run compare.');
+    process.exit(1);
+  }
+
+  // Find HTML files in output
+  const outputFiles = await readdir(outputDir);
+  const htmlFiles = outputFiles.filter((f) => f.endsWith('.html'));
+
+  if (htmlFiles.length === 0) {
+    console.error('No HTML files found in output directory');
+    process.exit(1);
+  }
+
+  const results: ComparisonResult[] = [];
+
+  for (const htmlFile of htmlFiles) {
+    const htmlPath = join(outputDir, htmlFile);
+
+    for (const [vpName, vpSize] of Object.entries({
+      desktop: { width: 1440, height: 900 },
+      mobile: { width: 390, height: 844 },
+    })) {
+      const baseName = htmlFile.replace('.html', '');
+      const generatedScreenshot = join(comparisonDir, `generated-${vpName}-${baseName}.png`);
+      // v2.12 — prefer the ABOVE-FOLD original for a fair, region-matched score. Comparing a
+      //   token reconstruction against the FULL scrolled page (often 7000px+) was apples-to-oranges
+      //   and the crop fallback flattered dark-background sites. Fold-to-fold is the honest measure.
+      const aboveFold = join(screenshotDir, `above-fold-${vpName}.png`);
+      const originalScreenshot = existsSync(aboveFold) ? aboveFold : join(screenshotDir, `full-page-${vpName}.png`);
+      const diffImage = join(comparisonDir, `diff-${vpName}.png`);
+
+      console.log(`  📸 Screenshotting ${htmlFile} (${vpName})...`);
+      await screenshotGenerated(htmlPath, generatedScreenshot, vpSize);
+
+      // Check if original exists
+      try {
+        await stat(originalScreenshot);
+      } catch {
+        console.log(`  ⚠️  No original screenshot for ${vpName}, skipping comparison`);
+        continue;
+      }
+
+      console.log(`  🔍 Comparing ${vpName} (pixel-level)...`);
+      const { score, ssim, differences, pixelStats } = await comparePixels(
+        originalScreenshot,
+        generatedScreenshot,
+        diffImage,
+      );
+
+      const verdict: ComparisonResult['verdict'] =
+        score >= 85 ? 'PASS' : score >= 60 ? 'NEEDS-REVISION' : 'FAIL';
+
+      results.push({
+        domain,
+        timestamp: new Date().toISOString(),
+        originalScreenshot,
+        generatedScreenshot,
+        diffImage,
+        viewport: vpName,
+        differences,
+        score,
+        ssim,
+        verdict,
+        pixelStats,
+      });
+
+      const icon = verdict === 'PASS' ? '✅' : verdict === 'NEEDS-REVISION' ? '⚠️' : '❌';
+      console.log(`  ${icon} ${vpName}: ${score}/100 flat · ${ssim}/100 structure — ${verdict}`);
+      if (pixelStats.totalPixels > 0) {
+        console.log(`     ${pixelStats.diffPixels.toLocaleString()} differing pixels / ${pixelStats.totalPixels.toLocaleString()} total`);
+      }
+      if (differences.length > 0) {
+        differences.forEach((d) => console.log(`     → ${d}`));
+      }
+      console.log(`     Diff image: ${diffImage}`);
+    }
+  }
+
+  // Save report
+  const overallScore = Math.round(
+    results.reduce((sum, r) => sum + r.score, 0) / Math.max(results.length, 1),
+  );
+  const overallSsim = Math.round(
+    results.reduce((sum, r) => sum + r.ssim, 0) / Math.max(results.length, 1),
+  );
+  const overallVerdict: ComparisonResult['verdict'] = results.every((r) => r.verdict === 'PASS')
+    ? 'PASS'
+    : results.some((r) => r.verdict === 'FAIL')
+      ? 'FAIL'
+      : 'NEEDS-REVISION';
+
+  // Read the rebuild mode (structural vs token re-skin) so the score is self-describing
+  let rebuildMode = 'unknown';
+  try { rebuildMode = JSON.parse(await readFile(join(outputDir, 'rebuild-meta.json'), 'utf-8')).mode || 'unknown'; } catch { /* optional */ }
+
+  const report = {
+    domain,
+    comparedAt: new Date().toISOString(),
+    rebuildMode,
+    results,
+    overallScore,
+    overallSsim,
+    overallVerdict,
+  };
+
+  await writeFile(join(comparisonDir, 'comparison-report.json'), JSON.stringify(report, null, 2));
+  // v2.12 — compact score.json the catalog scorer + DESIGN.md injector can read
+  // v2.13 — report SSIM (structure-aware) alongside pixelmatch (flat-area). SSIM is the honest
+  //   fidelity headline; pixelmatch alone is background-dominated and can't see layout.
+  await writeFile(join(comparisonDir, 'score.json'), JSON.stringify({
+    domain, score: overallScore, ssim: overallSsim, verdict: overallVerdict,
+    rebuildMode,
+    region: 'above-fold',
+    method: 'pixelmatch (flat-area) + SSIM (structure) @ 2× device scale, fold-to-fold',
+    comparedAt: report.comparedAt,
+  }, null, 2));
+
+  console.log(`\n📊 Overall: ${overallScore}/100 flat-area · ${overallSsim}/100 structure — ${overallVerdict} (above-fold, 2× matched, ${rebuildMode})`);
+  console.log(`📁 Report: ${comparisonDir}/comparison-report.json`);
+}
+
+// ── CLI ──
+const domain = process.argv[2];
+if (!domain) {
+  console.error('Usage: npm run compare -- <domain>');
+  process.exit(1);
+}
+
+compare(domain).catch((err) => {
+  console.error('Error:', err);
+  process.exit(1);
+});