designlang 12.17.0 → 12.18.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [12.18.0] — 2026-06-12
+
+**`verify` closes the loop — designlang now *proves* its extraction with a fidelity score.**
+
+Every release so far *read* a design system and emitted artifacts. None proved
+the artifacts could rebuild the source. `verify` does exactly that.
+
+- **`designlang verify <url>`** — extracts the design, then for each detected
+  component (button + card in v1) rebuilds a clone styled **only** by the
+  extracted tokens (every visual property snapped to its nearest token; colours
+  matched in CIE-Lab ΔE space), renders it, and **pixel-diffs** it against the
+  live component. Emits a **0–100 fidelity score**, a per-token-family
+  attribution of where information was lost, and a `verify.html` triptych
+  (original │ rebuilt-from-tokens │ loss heatmap) per component, plus
+  `verify.json`. `--min <score>` exits non-zero for CI gating.
+
+  The score is honest by construction: a component not on the page is `n/a`
+  (excluded, never a silent 100), and a property with no matching token is
+  `unmapped` — counted as loss and surfaced in the attribution, so a weak
+  extractor *lowers* the score rather than hiding behind it. Size mismatches are
+  letterboxed, never stretched.
+
+  Adds `pixelmatch` + `pngjs` as dependencies. New modules under `src/verify/`
+  (`tokens`, `restyle`, `render`, `diff`, `index`) are isolated and unit-tested.
+
 ## [12.17.0] — 2026-06-12
 
 **motionlang adds two more emitters — GSAP and the framework-free Web Animations API.**

package/README.md

@@ -35,6 +35,7 @@ It also goes where extractors don't: **layout patterns**, **responsive behavior
 
 ```bash
 npx designlang https://stripe.com                      # extract everything
+npx designlang verify stripe.com                       # fidelity score: rebuild from tokens vs live ← v12.18
 npx designlang pair stripe.com linear.app              # fuse two designs (visuals A × voice B)    ← v12.8
 npx designlang brand stripe.com                        # full brand-guidelines book (13 chapters)  ← v12.7
 npx designlang theme-swap stripe.com --primary "#ff4800"  # recolour around your brand        ← v12.6

package/bin/design-extract.js

@@ -1920,6 +1920,51 @@ program
     }
   });
 
+// ── Verify — fidelity loop: rebuild from tokens, pixel-diff vs original ──
+program
+  .command('verify <url>')
+  .description('Rebuild components from the extracted tokens and pixel-diff them against the live page — a 0-100 fidelity score + loss heatmaps.')
+  .option('-o, --out <dir>', 'output directory', './design-extract-output')
+  .option('-c, --components <list>', 'comma-separated components to check (button,card,input,nav)', 'button,card')
+  .option('--min <score>', 'exit non-zero if site fidelity is below this (CI gate)', parseInt)
+  .option('--system-chrome', 'use the system Chrome install instead of bundled Chromium')
+  .action(async (url, opts) => {
+    if (!url.startsWith('http')) url = `https://${url}`;
+    validateUrl(url);
+    const spinner = ora('Extracting + rebuilding from tokens').start();
+    try {
+      const { verifyDesign } = await import('../src/verify/index.js');
+      const { formatVerifyHtml, formatVerifyJson } = await import('../src/formatters/verify.js');
+      const components = String(opts.components).split(',').map((s) => s.trim()).filter(Boolean);
+      const report = await verifyDesign(url, {
+        components,
+        out: resolve(opts.out),
+        channel: opts.systemChrome ? 'chrome' : undefined,
+      });
+      mkdirSync(resolve(opts.out), { recursive: true });
+      const htmlPath = join(resolve(opts.out), 'verify.html');
+      const jsonPath = join(resolve(opts.out), 'verify.json');
+      writeFileSync(htmlPath, formatVerifyHtml(report), 'utf8');
+      writeFileSync(jsonPath, formatVerifyJson(report), 'utf8');
+
+      const score = report.fidelity;
+      spinner.succeed(`Fidelity ${score == null ? 'n/a' : score + '/100'} → ${htmlPath}`);
+      for (const c of report.components) {
+        const line = c.status === 'ok'
+          ? `${chalk.bold(c.component.padEnd(8))} ${chalk.cyan(String(c.fidelity).padStart(3))}/100`
+          : `${chalk.bold(c.component.padEnd(8))} ${chalk.gray(c.status)} ${chalk.gray(c.reason || '')}`;
+        console.log('  ' + line);
+      }
+      if (opts.min != null && score != null && score < opts.min) {
+        console.error(chalk.red(`\n  Fidelity ${score} is below --min ${opts.min}\n`));
+        process.exit(1);
+      }
+    } catch (err) {
+      spinner.fail(err.message);
+      process.exit(1);
+    }
+  });
+
 // ── Chat — REPL over a live extraction (v12) ──────────────
 program
   .command('chat <target>')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "designlang",
-  "version": "12.17.0",
+  "version": "12.18.0",
   "description": "Extract the complete design language from any website and ship it — clone to a working Next.js starter, guard tokens with a CI drift bot, or browse everything in a local studio. Outputs W3C DTCG tokens, motion tokens, typed anatomy stubs, Tailwind config, and ready-to-paste v0 / Lovable / Cursor / Claude-Artifacts prompts.",
   "type": "module",
   "bin": {
@@ -24,7 +24,9 @@
     "commander": "^12.0.0",
     "ora": "^8.0.0",
     "pdf-lib": "^1.17.1",
-    "playwright": "^1.42.0"
+    "pixelmatch": "^7.2.0",
+    "playwright": "^1.42.0",
+    "pngjs": "^7.0.0"
   },
   "engines": {
     "node": ">=20"

package/src/formatters/verify.js

@@ -0,0 +1,77 @@
+// Render a verify report as JSON and a self-contained HTML triptych
+// (original │ rebuilt │ diff-heatmap per component) with the fidelity score.
+
+export function formatVerifyJson(report) {
+  // Drop the verbose per-property deltas from JSON; keep the attribution summary.
+  const slim = {
+    ...report,
+    components: report.components.map(({ deltas, ...c }) => c), // eslint-disable-line no-unused-vars
+  };
+  return JSON.stringify(slim, null, 2) + '\n';
+}
+
+function esc(s) {
+  return String(s ?? '').replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
+}
+
+function band(n) {
+  if (n == null) return '#888';
+  if (n >= 90) return '#16a34a';
+  if (n >= 75) return '#65a30d';
+  if (n >= 55) return '#d97706';
+  return '#dc2626';
+}
+
+export function formatVerifyHtml(report) {
+  const score = report.fidelity;
+  const cards = report.components.map((c) => {
+    if (c.status !== 'ok') {
+      return `<div class="comp na"><div class="comp-head"><span class="kind">${esc(c.component)}</span><span class="tag">${esc(c.status)}</span></div><p class="reason">${esc(c.reason || '')}</p></div>`;
+    }
+    const attr = (c.attribution || []).map((a) =>
+      `<li><b>${esc(a.family)}</b> — ${a.unmapped ? `${a.unmapped} unmapped` : ''}${a.unmapped && a.moves ? ', ' : ''}${a.moves ? `${a.moves} shifted` : ''}</li>`).join('');
+    return `<div class="comp">
+      <div class="comp-head"><span class="kind">${esc(c.component)}</span><span class="score" style="color:${band(c.fidelity)}">${c.fidelity}<small>/100</small></span></div>
+      <div class="trip">
+        <figure><img src="verify/original/${esc(c.component)}.png" alt="original"><figcaption>original</figcaption></figure>
+        <figure><img src="verify/rebuilt/${esc(c.component)}.png" alt="rebuilt from tokens"><figcaption>rebuilt from tokens</figcaption></figure>
+        <figure><img src="verify/diff/${esc(c.component)}.png" alt="diff"><figcaption>loss heatmap</figcaption></figure>
+      </div>
+      ${attr ? `<ul class="attr">${attr}</ul>` : '<p class="attr none">no significant token loss</p>'}
+    </div>`;
+  }).join('');
+
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>designlang · fidelity · ${esc(report.host)}</title>
+<style>
+  :root { --fg:#111; --mut:#666; --line:#e5e5e5; --bg:#fafafa; }
+  * { box-sizing: border-box; }
+  body { font: 15px/1.6 -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; color: var(--fg); background: var(--bg); margin: 0; padding: 40px 24px; }
+  .wrap { max-width: 1080px; margin: 0 auto; }
+  h1 { font-size: 28px; margin: 0 0 4px; }
+  .sub { color: var(--mut); font-size: 13px; margin: 0 0 28px; }
+  .big { display: flex; align-items: baseline; gap: 14px; margin: 0 0 32px; }
+  .big .n { font-size: 64px; font-weight: 800; line-height: 1; color: ${band(score)}; }
+  .big .l { color: var(--mut); font-size: 13px; text-transform: uppercase; letter-spacing: .08em; }
+  .comp { background: #fff; border: 1px solid var(--line); border-radius: 12px; padding: 18px; margin-bottom: 18px; }
+  .comp.na { opacity: .7; }
+  .comp-head { display: flex; justify-content: space-between; align-items: baseline; margin-bottom: 14px; }
+  .kind { font-weight: 700; text-transform: capitalize; }
+  .score { font-size: 26px; font-weight: 800; } .score small { font-size: 12px; color: var(--mut); font-weight: 500; }
+  .tag { font: 11px/1 ui-monospace, monospace; text-transform: uppercase; letter-spacing: .1em; color: var(--mut); border: 1px solid var(--line); padding: 4px 8px; border-radius: 6px; }
+  .trip { display: grid; grid-template-columns: repeat(3, 1fr); gap: 12px; }
+  figure { margin: 0; text-align: center; } figure img { max-width: 100%; border: 1px solid var(--line); border-radius: 8px; background: #fff; }
+  figcaption { color: var(--mut); font-size: 11px; margin-top: 6px; text-transform: uppercase; letter-spacing: .06em; }
+  .attr { margin: 14px 0 0; padding-left: 18px; color: var(--mut); font-size: 13px; } .attr.none { list-style: none; padding: 0; font-style: italic; }
+  .reason { color: var(--mut); font-size: 13px; margin: 0; }
+  footer { color: var(--mut); font-size: 12px; margin-top: 24px; }
+</style></head>
+<body><div class="wrap">
+  <h1>Fidelity report — ${esc(report.host)}</h1>
+  <p class="sub">How faithfully the extracted tokens reconstruct the live components. ${esc(report.generatedAt)}</p>
+  <div class="big"><span class="n">${score == null ? '—' : score}</span><span class="l">${score == null ? 'no components scored' : 'site fidelity / 100'}</span></div>
+  ${cards}
+  <footer>Rebuilt using only designlang's extracted tokens. Lower scores point to where tokenization lost information — see the heatmaps. Generated by <b>designlang verify</b>.</footer>
+</div></body></html>`;
+}

package/src/verify/diff.js

@@ -0,0 +1,52 @@
+// Pixel-diff two PNG buffers and return a differing-pixel ratio + a heatmap.
+//
+// Sizes rarely match (a snapped-down padding makes the rebuild smaller), so we
+// letterbox both onto a common canvas anchored top-left, padding with white.
+// We never STRETCH — a stretched compare would smear the score into fiction.
+// Padding asymmetry is real signal: if the rebuild is smaller, the uncovered
+// margin shows up as loss, which is correct.
+
+import pixelmatch from 'pixelmatch';
+import { PNG } from 'pngjs';
+
+function pad(png, width, height, fill = 255) {
+  if (png.width === width && png.height === height) return png;
+  const out = new PNG({ width, height });
+  out.data.fill(fill); // opaque white canvas
+  for (let i = 3; i < out.data.length; i += 4) out.data[i] = 255;
+  PNG.bitblt(png, out, 0, 0, Math.min(png.width, width), Math.min(png.height, height), 0, 0);
+  return out;
+}
+
+// aBuf/bBuf: PNG file buffers. Returns { ratio, width, height, diffPixels, heatmap }.
+export function diffPngBuffers(aBuf, bBuf, { threshold = 0.1 } = {}) {
+  const a = PNG.sync.read(aBuf);
+  const b = PNG.sync.read(bBuf);
+  const width = Math.max(a.width, b.width);
+  const height = Math.max(a.height, b.height);
+
+  const pa = pad(a, width, height);
+  const pb = pad(b, width, height);
+  const out = new PNG({ width, height });
+
+  const diffPixels = pixelmatch(pa.data, pb.data, out.data, width, height, {
+    threshold,
+    includeAA: false,
+    alpha: 0.25,
+    diffColor: [255, 0, 80],
+  });
+
+  const total = width * height;
+  return {
+    ratio: total ? diffPixels / total : 1,
+    width,
+    height,
+    diffPixels,
+    heatmap: PNG.sync.write(out),
+  };
+}
+
+// Convenience: ratio → 0–100 fidelity, rounded.
+export function ratioToFidelity(ratio) {
+  return Math.max(0, Math.min(100, Math.round((1 - ratio) * 100)));
+}

package/src/verify/index.js

@@ -0,0 +1,122 @@
+// `verifyDesign(url)` — the fidelity loop.
+//
+// extract → for each target component: capture the real crop + its computed
+// styles → re-style a clone using ONLY the extracted tokens → render → pixel-
+// diff against the real crop → fidelity %. Aggregate to a site score, with
+// per-token-family attribution so the number is explained, not asserted.
+
+import { chromium } from 'playwright';
+import { mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { extractDesignLanguage } from '../index.js';
+import { tokensFromDesign } from './tokens.js';
+import { restyleComponent } from './restyle.js';
+import { renderComponent } from './render.js';
+import { diffPngBuffers, ratioToFidelity } from './diff.js';
+
+const SELECTORS = {
+  button: 'button:not(:empty), a[role="button"]:not(:empty), [class*="btn"]:not(:empty)',
+  card: '[class*="card"]:not(:empty)',
+  input: 'input[type="text"], input[type="email"], input[type="search"], textarea',
+  nav: 'nav, [role="navigation"]',
+};
+
+// The computed-style slice restyle.js needs — read once, in-page. Passed as a
+// real function to Playwright's evaluate (no eval/string-compile).
+function captureInPage(el) {
+  const cs = getComputedStyle(el);
+  const r = el.getBoundingClientRect();
+  const pick = ['backgroundColor', 'color', 'borderTopColor', 'borderTopWidth', 'borderTopStyle', 'borderTopLeftRadius', 'paddingTop', 'paddingRight', 'paddingBottom', 'paddingLeft', 'fontFamily', 'fontSize', 'fontWeight', 'lineHeight', 'boxShadow'];
+  const computed = {};
+  for (const p of pick) computed[p] = cs[p];
+  return { computed, outerHTML: el.outerHTML.slice(0, 20000), box: { w: r.width, h: r.height } };
+}
+
+async function pickRepresentative(page, selector) {
+  const handles = await page.$$(selector);
+  for (const h of handles) {
+    const ok = await h.evaluate((el) => {
+      const r = el.getBoundingClientRect();
+      const cs = getComputedStyle(el);
+      return r.width >= 24 && r.height >= 12 && r.width <= window.innerWidth &&
+        cs.visibility !== 'hidden' && cs.display !== 'none' && parseFloat(cs.opacity) >= 0.5;
+    }).catch(() => false);
+    if (ok) return h;
+  }
+  return null;
+}
+
+function attribution(deltas) {
+  const byFamily = {};
+  for (const d of deltas) {
+    const f = (byFamily[d.family] ||= { family: d.family, moves: 0, unmapped: 0 });
+    if (d.mapped === false) f.unmapped += 1;
+    else if ((d.family === 'color' && d.distance > 6) || (d.distance || 0) > 2) f.moves += 1;
+  }
+  return Object.values(byFamily)
+    .filter((f) => f.moves || f.unmapped)
+    .sort((a, b) => (b.unmapped * 3 + b.moves) - (a.unmapped * 3 + a.moves));
+}
+
+export async function verifyDesign(url, opts = {}) {
+  const components = opts.components?.length ? opts.components : ['button', 'card'];
+  const width = opts.width || 1280;
+  const height = opts.height || 800;
+  const outDir = opts.out ? join(opts.out) : null;
+  if (outDir) for (const d of ['original', 'rebuilt', 'diff']) mkdirSync(join(outDir, 'verify', d), { recursive: true });
+
+  const design = opts.design || await extractDesignLanguage(url, opts.browserOpts || {});
+  const tokens = tokensFromDesign(design);
+
+  const browser = await chromium.launch({ headless: true, ...(opts.channel && { channel: opts.channel }) });
+  const results = [];
+  try {
+    const context = await browser.newContext({ viewport: { width, height }, deviceScaleFactor: 2, colorScheme: 'light' });
+    const page = await context.newPage();
+    await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 }).catch(() => {});
+    await page.waitForLoadState('networkidle').catch(() => {});
+    await page.evaluate(() => document.fonts.ready).catch(() => {});
+
+    for (const kind of components) {
+      const sel = SELECTORS[kind];
+      if (!sel) { results.push({ component: kind, status: 'n/a', reason: 'unknown component' }); continue; }
+      const handle = await pickRepresentative(page, sel);
+      if (!handle) { results.push({ component: kind, status: 'n/a', reason: 'not found on page' }); continue; }
+
+      try {
+        const originalBuf = await handle.screenshot({ type: 'png' });
+        const cap = await handle.evaluate(captureInPage);
+        const { styled, deltas } = restyleComponent(cap.computed, tokens);
+        const rebuiltBuf = await renderComponent(browser, { outerHTML: cap.outerHTML, box: cap.box, dpr: 2, styled }, tokens);
+        const { ratio, heatmap, diffPixels } = diffPngBuffers(originalBuf, rebuiltBuf);
+        const fidelity = ratioToFidelity(ratio);
+
+        if (outDir) {
+          writeFileSync(join(outDir, 'verify', 'original', `${kind}.png`), originalBuf);
+          writeFileSync(join(outDir, 'verify', 'rebuilt', `${kind}.png`), rebuiltBuf);
+          writeFileSync(join(outDir, 'verify', 'diff', `${kind}.png`), heatmap);
+        }
+        results.push({ component: kind, status: 'ok', fidelity, diffPixels, attribution: attribution(deltas), deltas });
+      } catch (err) {
+        results.push({ component: kind, status: 'error', reason: err?.message || 'render failed' });
+      }
+    }
+  } finally {
+    await browser.close();
+  }
+
+  const scored = results.filter((r) => r.status === 'ok');
+  const fidelity = scored.length ? Math.round(scored.reduce((s, r) => s + r.fidelity, 0) / scored.length) : null;
+
+  return {
+    url,
+    host: (() => { try { return new URL(url).hostname.replace(/^www\./, ''); } catch { return url; } })(),
+    generatedAt: new Date().toISOString(),
+    fidelity,
+    components: results,
+    tokenCounts: {
+      palette: tokens.palette.length, radii: tokens.radii.length, spacing: tokens.spacing.length,
+      fontSizes: tokens.fontSizes.length, shadows: tokens.shadows.length,
+    },
+  };
+}

package/src/verify/render.js

@@ -0,0 +1,45 @@
+// Render a re-styled component clone on a clean canvas and return its PNG.
+//
+// The clone keeps its DOM structure and text but loses the site's stylesheet
+// (we never load it). We pin the root to the captured box and apply ONLY the
+// token-snapped inline styles, so the screenshot is "this component as the
+// extracted token system would express it" — nothing more. Children inherit
+// the token body font/colour; author classes resolve to nothing, by design.
+
+import { styledToCss } from './restyle.js';
+
+// browser: a launched Playwright Browser. comp: { outerHTML, box:{w,h}, dpr, styled }.
+// tokens: used only for the page's inherited body font/colour defaults.
+export async function renderComponent(browser, comp, tokens = {}) {
+  const { outerHTML, box, dpr = 2, styled } = comp;
+  const w = Math.max(1, Math.ceil(box?.w || 1));
+  const h = Math.max(1, Math.ceil(box?.h || 1));
+  const css = styledToCss(styled);
+
+  const context = await browser.newContext({
+    viewport: { width: w + 8, height: h + 8 },
+    deviceScaleFactor: dpr,
+    colorScheme: 'light',
+  });
+  try {
+    const page = await context.newPage();
+    const html = `<!doctype html><html><head><meta charset="utf-8"><style>
+* { margin: 0; padding: 0; box-sizing: border-box; }
+html, body { background: ${tokens.bodyBg || '#ffffff'}; }
+body { font-family: ${tokens.bodyFamily || 'sans-serif'}; color: ${tokens.bodyColor || '#111'}; padding: 4px; }
+#dl-host > * { width: ${w}px; height: ${h}px; box-sizing: border-box; overflow: hidden; display: flex; align-items: center; justify-content: center; ${css}; }
+</style></head><body><div id="dl-host"></div></body></html>`;
+    await page.setContent(html, { waitUntil: 'domcontentloaded' });
+    await page.evaluate(({ outer, inline }) => {
+      const host = document.getElementById('dl-host');
+      host.innerHTML = outer;
+      const root = host.firstElementChild;
+      if (root) root.setAttribute('style', `${root.getAttribute('style') || ''};${inline}`);
+    }, { outer: outerHTML, inline: css });
+    await page.evaluate(() => document.fonts.ready).catch(() => {});
+    const root = page.locator('#dl-host > *').first();
+    return await root.screenshot({ type: 'png' });
+  } finally {
+    await context.close();
+  }
+}

package/src/verify/restyle.js

@@ -0,0 +1,155 @@
+// The re-style engine — the heart of `verify`.
+//
+// Pure function: given an element's *real* computed styles and the design's
+// token sets, produce the styles that element would have if it could only use
+// the extracted tokens. The gap between the two — rendered and pixel-diffed
+// elsewhere — IS the tokenization loss the fidelity score reports.
+//
+// No browser, no I/O. Every visual property that determines a static crop is
+// snapped to its nearest token; properties with no matching token family are
+// flagged `mapped: false` and rendered with a neutral default (radius 0,
+// shadow none) so the diff EXPOSES the missing extractor rather than hiding it.
+//
+// Motion/easing is deliberately excluded: it does not affect a static
+// screenshot, so snapping it would add noise without signal.
+
+// ── colour ──────────────────────────────────────────────────────
+export function parseColor(str) {
+  if (!str) return null;
+  const s = String(str).trim();
+  const m = s.match(/rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)\s*(?:[,/]\s*([\d.]+))?\s*\)/i);
+  if (m) return { r: +m[1], g: +m[2], b: +m[3], a: m[4] === undefined ? 1 : +m[4] };
+  const h = s.match(/^#([0-9a-f]{6})$/i);
+  if (h) return { r: parseInt(h[1].slice(0, 2), 16), g: parseInt(h[1].slice(2, 4), 16), b: parseInt(h[1].slice(4, 6), 16), a: 1 };
+  const h3 = s.match(/^#([0-9a-f]{3})$/i);
+  if (h3) return { r: parseInt(h3[1][0] + h3[1][0], 16), g: parseInt(h3[1][1] + h3[1][1], 16), b: parseInt(h3[1][2] + h3[1][2], 16), a: 1 };
+  return null;
+}
+
+function toHex({ r, g, b }) {
+  return '#' + [r, g, b].map((v) => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, '0')).join('');
+}
+
+// sRGB → CIE Lab, so colour distance tracks perception, not raw RGB.
+function rgbToLab({ r, g, b }) {
+  let [R, G, B] = [r, g, b].map((v) => {
+    v /= 255;
+    return v > 0.04045 ? ((v + 0.055) / 1.055) ** 2.4 : v / 12.92;
+  });
+  let x = (R * 0.4124 + G * 0.3576 + B * 0.1805) / 0.95047;
+  let y = (R * 0.2126 + G * 0.7152 + B * 0.0722) / 1.0;
+  let z = (R * 0.0193 + G * 0.1192 + B * 0.9505) / 1.08883;
+  [x, y, z] = [x, y, z].map((v) => (v > 0.008856 ? Math.cbrt(v) : 7.787 * v + 16 / 116));
+  return [116 * y - 16, 500 * (x - y), 200 * (y - z)];
+}
+
+export function deltaE(hexA, hexB) {
+  const a = parseColor(hexA);
+  const b = parseColor(hexB);
+  if (!a || !b) return Infinity;
+  const [l1, a1, b1] = rgbToLab(a);
+  const [l2, a2, b2] = rgbToLab(b);
+  return Math.hypot(l1 - l2, a1 - a2, b1 - b2);
+}
+
+export function nearestColor(value, palette) {
+  const col = parseColor(value);
+  if (!col || col.a < 0.05) return { value: 'transparent', mapped: true, transparent: true };
+  if (!palette?.length) return { value: toHex(col), mapped: false };
+  const here = toHex(col);
+  let best = palette[0];
+  let bestD = Infinity;
+  for (const p of palette) {
+    const d = deltaE(here, p);
+    if (d < bestD) { bestD = d; best = p; }
+  }
+  return { value: best, mapped: true, distance: bestD };
+}
+
+// ── numeric scales ──────────────────────────────────────────────
+export function px(v) {
+  const n = parseFloat(v);
+  return Number.isFinite(n) ? n : null;
+}
+
+export function nearestNumber(value, scale, { fallback = 0 } = {}) {
+  const n = px(value);
+  if (n === null) return { value: fallback, mapped: false };
+  if (!scale?.length) return { value: fallback, mapped: false, original: n };
+  let best = scale[0];
+  for (const s of scale) if (Math.abs(s - n) < Math.abs(best - n)) best = s;
+  return { value: best, mapped: true, distance: Math.abs(best - n) };
+}
+
+// ── shadow ──────────────────────────────────────────────────────
+function blurOf(shadow) {
+  const m = String(shadow).match(/(-?\d+(?:\.\d+)?)px\s+(-?\d+(?:\.\d+)?)px\s+(\d+(?:\.\d+)?)px/);
+  return m ? +m[3] : 0;
+}
+
+export function nearestShadow(value, shadows) {
+  const has = value && value !== 'none';
+  if (!has) return { value: 'none', mapped: true };
+  if (!shadows?.length) return { value: 'none', mapped: false };
+  const target = blurOf(value);
+  let best = shadows[0];
+  for (const s of shadows) if (Math.abs(blurOf(s) - target) < Math.abs(blurOf(best) - target)) best = s;
+  return { value: best, mapped: true };
+}
+
+// ── font family ─────────────────────────────────────────────────
+function primaryFamily(stack) {
+  return String(stack || '').split(',')[0].trim().replace(/^["']|["']$/g, '');
+}
+
+export function snapFamily(value, families, fallback) {
+  const want = primaryFamily(value).toLowerCase();
+  const hit = (families || []).find((f) => primaryFamily(f).toLowerCase() === want);
+  if (hit) return { value: hit, mapped: true };
+  return { value: fallback || families?.[0] || 'sans-serif', mapped: false };
+}
+
+// ── orchestration ───────────────────────────────────────────────
+// `computed` is a flat map of the raw values read from getComputedStyle.
+// Returns { styled, deltas } — styled is inline CSS to apply to the rebuild
+// root; deltas explains every move (for the attribution / heatmap legend).
+export function restyleComponent(computed = {}, tokens = {}) {
+  const styled = {};
+  const deltas = [];
+  const record = (prop, family, from, res) => {
+    styled[prop] = res.value;
+    deltas.push({ prop, family, from, to: res.value, mapped: res.mapped !== false, distance: res.distance });
+  };
+
+  record('background-color', 'color', computed.backgroundColor, nearestColor(computed.backgroundColor, tokens.palette));
+  record('color', 'color', computed.color, nearestColor(computed.color, tokens.palette));
+
+  const bw = px(computed.borderTopWidth) || 0;
+  if (bw > 0) {
+    record('border-style', 'border', computed.borderTopStyle, { value: computed.borderTopStyle || 'solid', mapped: true });
+    record('border-width', 'border', computed.borderTopWidth, nearestNumber(computed.borderTopWidth, tokens.borderWidths, { fallback: bw }));
+    record('border-color', 'color', computed.borderTopColor, nearestColor(computed.borderTopColor, tokens.palette));
+  }
+
+  record('border-radius', 'radius', computed.borderTopLeftRadius, nearestNumber(computed.borderTopLeftRadius, tokens.radii, { fallback: 0 }));
+
+  for (const [prop, key] of [['padding-top', 'paddingTop'], ['padding-right', 'paddingRight'], ['padding-bottom', 'paddingBottom'], ['padding-left', 'paddingLeft']]) {
+    record(prop, 'spacing', computed[key], nearestNumber(computed[key], tokens.spacing, { fallback: px(computed[key]) || 0 }));
+  }
+
+  record('font-family', 'type', computed.fontFamily, snapFamily(computed.fontFamily, tokens.fontFamilies, tokens.bodyFamily));
+  record('font-size', 'type', computed.fontSize, nearestNumber(computed.fontSize, tokens.fontSizes, { fallback: px(computed.fontSize) || 16 }));
+  record('font-weight', 'type', computed.fontWeight, nearestNumber(computed.fontWeight, tokens.fontWeights, { fallback: parseInt(computed.fontWeight, 10) || 400 }));
+  record('box-shadow', 'shadow', computed.boxShadow, nearestShadow(computed.boxShadow, tokens.shadows));
+
+  return { styled, deltas };
+}
+
+// Turn the `styled` map into an inline style string, appending px units to the
+// numeric props the snappers return as raw numbers.
+export function styledToCss(styled = {}) {
+  const PX = new Set(['border-width', 'border-radius', 'padding-top', 'padding-right', 'padding-bottom', 'padding-left', 'font-size']);
+  return Object.entries(styled)
+    .map(([k, v]) => `${k}: ${PX.has(k) && typeof v === 'number' ? `${v}px` : v}`)
+    .join('; ');
+}

package/src/verify/tokens.js

@@ -0,0 +1,45 @@
+// Normalise a `design` object into the flat token sets the re-style engine
+// snaps against. One job: turn the rich extraction into "here are the allowed
+// values per visual property", so restyle.js stays a pure function of
+// (computedStyle, tokens).
+
+function uniqNums(arr) {
+  return [...new Set((arr || []).map(Number).filter((n) => Number.isFinite(n)))].sort((a, b) => a - b);
+}
+
+function hex(s) {
+  return typeof s === 'string' && /^#[0-9a-f]{6}$/i.test(s) ? s.toLowerCase() : null;
+}
+
+export function tokensFromDesign(design = {}) {
+  const c = design.colors || {};
+  const palette = [...new Set([
+    c.primary?.hex,
+    c.secondary?.hex,
+    c.accent?.hex,
+    ...(c.neutrals || []).map((n) => n.hex),
+    ...(c.backgrounds || []),
+    ...(c.text || []),
+    ...(c.all || []).map((x) => x.hex),
+  ].map(hex).filter(Boolean))];
+
+  const ty = design.typography || {};
+  const fontFamilies = [...new Set((ty.families || []).map((f) => f.name).filter(Boolean))];
+  const fontSizes = uniqNums((ty.scale || []).map((s) => s.size));
+  const fontWeights = uniqNums((ty.scale || []).map((s) => parseInt(s.weight, 10)));
+
+  return {
+    palette,
+    radii: uniqNums(design.borders?.radii),
+    borderWidths: uniqNums(design.borders?.widths),
+    spacing: uniqNums(design.spacing?.scale),
+    fontFamilies,
+    fontSizes,
+    fontWeights,
+    shadows: (design.shadows?.values || []).filter((s) => typeof s === 'string' && s && s !== 'none'),
+    // sensible wrapper defaults so rebuilt text inherits the token system
+    bodyFamily: ty.body?.family || fontFamilies[0] || 'sans-serif',
+    bodyColor: hex(c.text?.[0]) || (c.primary?.hex ? hex(c.primary.hex) : null) || '#111111',
+    bodyBg: hex(c.backgrounds?.[0]) || '#ffffff',
+  };
+}