designlang 12.16.0 → 12.18.0

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',
+  };
+}