designlang 12.16.0 → 12.18.0

package/src/classifiers/smart.js

@@ -1,7 +1,8 @@
 // Optional LLM fallback for low-confidence classifications. No SDK deps — we
-// hit the OpenAI or Anthropic REST API directly via global fetch. Runs only
-// when the user passes --smart AND an API key is available in env. Silently
-// no-ops otherwise so the core extractor stays zero-config.
+// hit the Anthropic REST API or an OpenAI-compatible chat endpoint directly via
+// global fetch. Runs only when the user passes --smart AND an API key is
+// available in env. Silently no-ops otherwise so the core extractor stays
+// zero-config.
 //
 // Consumers call `refineWithSmart({ pageIntent, sectionRoles, materialLanguage,
 // componentLibrary }, digest)` — we only hit the network for fields where
@@ -19,9 +20,38 @@ const TASKS = {
   },
 };
 
-function detectProvider() {
-  if (process.env.ANTHROPIC_API_KEY) return 'anthropic';
-  if (process.env.OPENAI_API_KEY) return 'openai';
+function trimTrailingSlash(url) {
+  return url ? url.replace(/\/+$/, '') : url;
+}
+
+export function resolveSmartProviderConfig(env = process.env) {
+  if (env.ANTHROPIC_API_KEY) {
+    return {
+      provider: 'anthropic',
+      apiKey: env.ANTHROPIC_API_KEY,
+      model: env.DESIGNLANG_MODEL || 'claude-haiku-4-5-20251001',
+    };
+  }
+
+  const atlasApiKey = env.ATLASCLOUD_API_KEY || env.ATLAS_CLOUD_API_KEY;
+  if (atlasApiKey) {
+    return {
+      provider: 'atlascloud',
+      apiKey: atlasApiKey,
+      baseUrl: trimTrailingSlash(env.ATLASCLOUD_API_BASE || env.ATLAS_CLOUD_API_BASE || 'https://api.atlascloud.ai/v1'),
+      model: env.DESIGNLANG_MODEL || env.ATLASCLOUD_MODEL || env.ATLAS_CLOUD_MODEL || 'deepseek-ai/deepseek-v4-pro',
+    };
+  }
+
+  if (env.OPENAI_API_KEY) {
+    return {
+      provider: 'openai',
+      apiKey: env.OPENAI_API_KEY,
+      baseUrl: trimTrailingSlash(env.OPENAI_API_BASE || env.OPENAI_BASE_URL || 'https://api.openai.com/v1'),
+      model: env.DESIGNLANG_MODEL || 'gpt-4o-mini',
+    };
+  }
+
   return null;
 }
 
@@ -44,16 +74,16 @@ function buildDigest({ rawData, design, pageIntent }) {
   ].join('\n\n');
 }
 
-async function callAnthropic(system, user) {
+async function callAnthropic(config, system, user) {
   const res = await fetch('https://api.anthropic.com/v1/messages', {
     method: 'POST',
     headers: {
-      'x-api-key': process.env.ANTHROPIC_API_KEY,
+      'x-api-key': config.apiKey,
       'anthropic-version': '2023-06-01',
       'content-type': 'application/json',
     },
     body: JSON.stringify({
-      model: process.env.DESIGNLANG_MODEL || 'claude-haiku-4-5-20251001',
+      model: config.model,
       max_tokens: 200,
       system,
       messages: [{ role: 'user', content: user }],
@@ -65,15 +95,15 @@ async function callAnthropic(system, user) {
   return text;
 }
 
-async function callOpenAI(system, user) {
-  const res = await fetch('https://api.openai.com/v1/chat/completions', {
+async function callOpenAICompatible(config, system, user) {
+  const res = await fetch(`${config.baseUrl}/chat/completions`, {
     method: 'POST',
     headers: {
-      'authorization': `Bearer ${process.env.OPENAI_API_KEY}`,
+      'authorization': `Bearer ${config.apiKey}`,
       'content-type': 'application/json',
     },
     body: JSON.stringify({
-      model: process.env.DESIGNLANG_MODEL || 'gpt-4o-mini',
+      model: config.model,
       messages: [
         { role: 'system', content: system },
         { role: 'user', content: user },
@@ -82,14 +112,14 @@ async function callOpenAI(system, user) {
       response_format: { type: 'json_object' },
     }),
   });
-  if (!res.ok) throw new Error(`openai ${res.status}`);
+  if (!res.ok) throw new Error(`${config.provider} ${res.status}`);
   const json = await res.json();
   return json.choices?.[0]?.message?.content || '';
 }
 
-async function callLLM(provider, system, user) {
-  if (provider === 'anthropic') return callAnthropic(system, user);
-  return callOpenAI(system, user);
+async function callLLM(config, system, user) {
+  if (config.provider === 'anthropic') return callAnthropic(config, system, user);
+  return callOpenAICompatible(config, system, user);
 }
 
 function parseJsonLoose(text) {
@@ -101,8 +131,10 @@ function parseJsonLoose(text) {
 
 export async function refineWithSmart({ enabled, rawData, design, pageIntent, sectionRoles, materialLanguage, componentLibrary }) {
   if (!enabled) return { applied: false, reason: 'disabled' };
-  const provider = detectProvider();
-  if (!provider) return { applied: false, reason: 'no API key (set OPENAI_API_KEY or ANTHROPIC_API_KEY)' };
+  const providerConfig = resolveSmartProviderConfig();
+  if (!providerConfig) {
+    return { applied: false, reason: 'no API key (set OPENAI_API_KEY, ATLASCLOUD_API_KEY, or ANTHROPIC_API_KEY)' };
+  }
 
   const digest = buildDigest({ rawData, design, pageIntent });
   const updates = {};
@@ -118,13 +150,13 @@ export async function refineWithSmart({ enabled, rawData, design, pageIntent, se
     if (!spec) continue;
     const user = `Digest:\n${digest}\n\nCurrent heuristic result:\n${JSON.stringify(current)}\n\nRespond with the requested JSON.`;
     try {
-      const raw = await callLLM(provider, spec.system, user);
+      const raw = await callLLM(providerConfig, spec.system, user);
       const parsed = parseJsonLoose(raw);
-      if (parsed) updates[task] = { ...parsed, smart: true, provider };
+      if (parsed) updates[task] = { ...parsed, smart: true, provider: providerConfig.provider };
     } catch (e) {
       errors.push(`${task}: ${e.message}`);
     }
   }
 
-  return { applied: true, provider, updates, errors };
+  return { applied: true, provider: providerConfig.provider, updates, errors };
 }

package/src/formatters/motion-gsap.js

@@ -0,0 +1,131 @@
+// GSAP emitter — `<host>-motion.gsap.js`.
+//
+// Targets GreenSock (gsap). The extracted cubic-bezier curves are registered
+// as named `CustomEase`s (so the site's exact feel is reproducible), durations
+// come through as seconds, and we emit `gsap.from()` reveal helpers plus a
+// ScrollTrigger reveal when the page actually uses scroll-/view-timeline.
+//
+// We emit:
+//   • `eases`       — CustomEase SVG-path strings keyed by family
+//   • `durations`   — extracted timings in seconds
+//   • `registerEases(gsap)` — registers every ease as a named CustomEase
+//   • `reveals`     — gsap.from() helpers (fadeIn / slideUp / scaleIn / pop)
+//   • `revealOnScroll()` — ScrollTrigger batch reveal (only when scroll-linked)
+
+function bezierPts(raw) {
+  if (!raw) return null;
+  const m = String(raw).match(/cubic-bezier\(\s*([-\d.]+)\s*,\s*([-\d.]+)\s*,\s*([-\d.]+)\s*,\s*([-\d.]+)\s*\)/i);
+  if (m) return [parseFloat(m[1]), parseFloat(m[2]), parseFloat(m[3]), parseFloat(m[4])];
+  const named = {
+    linear: [0, 0, 1, 1], ease: [0.25, 0.1, 0.25, 1],
+    'ease-in': [0.42, 0, 1, 1], 'ease-out': [0, 0, 0.58, 1], 'ease-in-out': [0.42, 0, 0.58, 1],
+  };
+  return named[String(raw).trim()] || null;
+}
+
+function camel(s) {
+  return String(s || '').replace(/[^a-zA-Z0-9]+(.)/g, (_, c) => c.toUpperCase()).replace(/^[0-9]/, '_$&');
+}
+
+// GSAP CustomEase accepts SVG cubic-path data; a bezier from (0,0)→(1,1) with
+// the two extracted control points maps directly to one cubic segment.
+function customEasePath([x1, y1, x2, y2]) {
+  return `M0,0 C${x1},${y1} ${x2},${y2} 1,1`;
+}
+
+export function formatMotionGsap(design) {
+  const host = (() => { try { return new URL(design?.meta?.url).hostname.replace(/^www\./, ''); } catch { return 'site'; } })();
+  const durations = Array.isArray(design?.motion?.durations) ? design.motion.durations : [];
+  const easings   = Array.isArray(design?.motion?.easings)   ? design.motion.easings   : [];
+  const springs   = Array.isArray(design?.motion?.springs)   ? design.motion.springs   : [];
+  const scroll    = design?.motion?.scrollLinked || { present: false, signals: [] };
+
+  const durSec = (d) => ((d.ms || parseInt(d.css || d.value || d, 10) || 300) / 1000);
+  const defaultDur = durations.length ? durSec(durations[Math.min(2, durations.length - 1)]) : 0.3;
+
+  // Eases: dedupe by family, most-used first, fall back to a standard curve.
+  const sortedEase = [...easings].sort((a, b) => (b.count || 0) - (a.count || 0));
+  const easeEntries = [];
+  sortedEase.forEach((e, i) => {
+    const pts = bezierPts(e.raw);
+    if (!pts) return;
+    const key = e.family && e.family !== 'custom' ? camel(e.family) : `custom${i + 1}`;
+    if (easeEntries.find((x) => x.key === key)) return;
+    easeEntries.push({ key, path: customEasePath(pts), count: e.count });
+  });
+  springs.forEach((s) => {
+    const pts = bezierPts(s.raw);
+    if (pts && !easeEntries.find((x) => x.key === 'spring')) {
+      easeEntries.push({ key: 'spring', path: customEasePath(pts), count: s.count });
+    }
+  });
+  if (easeEntries.length === 0) {
+    easeEntries.push({ key: 'standard', path: customEasePath([0.25, 0.1, 0.25, 1]), count: 0 });
+  }
+  const primaryEaseKey = easeEntries[0].key;
+
+  const lines = [
+    '// GSAP presets — generated by designlang (motionlang)',
+    `// Source: ${design?.meta?.url || host}`,
+    `// ${new Date().toISOString()}`,
+    '//',
+    "//   import gsap from 'gsap';",
+    `//   import { registerEases, reveals } from './${host}-motion.gsap.js';`,
+    '//   registerEases(gsap);            // one-time: registers CustomEases',
+    "//   reveals.slideUp('.card');",
+    '',
+    '/** CustomEase path data extracted from the live page, keyed by family. */',
+    'export const eases = {',
+  ];
+  for (const { key, path, count } of easeEntries) {
+    lines.push(`  ${key}: '${path}',${count ? ` // ${count}× on page` : ''}`);
+  }
+  lines.push('};', '');
+
+  lines.push('/** Duration presets (seconds), extracted from the live page. */');
+  lines.push('export const durations = {');
+  if (durations.length) {
+    for (const d of durations) lines.push(`  ${camel(d.name || `ms${d.ms}`)}: ${durSec(d)},`);
+  } else {
+    lines.push('  fast: 0.15,', '  base: 0.3,', '  slow: 0.5,');
+  }
+  lines.push('};', '');
+
+  lines.push('/** Register every extracted curve as a named GSAP CustomEase. Call once. */');
+  lines.push('export function registerEases(gsap) {');
+  lines.push('  const CustomEase = gsap.plugins?.CustomEase || (typeof window !== \'undefined\' && window.CustomEase);');
+  lines.push('  if (!CustomEase) {');
+  lines.push("    console.warn('[motion.gsap] CustomEase plugin not registered — call gsap.registerPlugin(CustomEase) first.');");
+  lines.push('    return;');
+  lines.push('  }');
+  lines.push('  for (const [name, path] of Object.entries(eases)) CustomEase.create(name, path);');
+  lines.push('}');
+  lines.push('');
+
+  lines.push('/** gsap.from() reveal helpers. Pass any GSAP target + optional vars override. */');
+  lines.push('export const reveals = {');
+  lines.push(`  fadeIn: (target, vars = {}) => gsap.from(target, { opacity: 0, duration: ${defaultDur}, ease: '${primaryEaseKey}', ...vars }),`);
+  lines.push(`  slideUp: (target, vars = {}) => gsap.from(target, { opacity: 0, y: 24, duration: ${defaultDur}, ease: '${primaryEaseKey}', ...vars }),`);
+  lines.push(`  slideDown: (target, vars = {}) => gsap.from(target, { opacity: 0, y: -24, duration: ${defaultDur}, ease: '${primaryEaseKey}', ...vars }),`);
+  lines.push(`  scaleIn: (target, vars = {}) => gsap.from(target, { opacity: 0, scale: 0.96, duration: ${defaultDur}, ease: '${primaryEaseKey}', ...vars }),`);
+  lines.push(`  pop: (target, vars = {}) => gsap.from(target, { scale: 0.9, duration: ${defaultDur}, ease: '${easeEntries.find((e) => e.key === 'spring') ? 'spring' : primaryEaseKey}', ...vars }),`);
+  lines.push('};', '');
+
+  if (scroll.present) {
+    lines.push('/** Site uses scroll-/view-timeline. Batch-reveals elements as they enter. */');
+    lines.push('/** Requires: gsap.registerPlugin(ScrollTrigger). */');
+    lines.push('export function revealOnScroll(targets, vars = {}) {');
+    lines.push('  return gsap.utils.toArray(targets).map((el) =>');
+    lines.push('    gsap.from(el, {');
+    lines.push(`      opacity: 0, y: 24, duration: ${defaultDur}, ease: '${primaryEaseKey}', ...vars,`);
+    lines.push("      scrollTrigger: { trigger: el, start: 'top 85%', toggleActions: 'play none none reverse' },");
+    lines.push('    }));');
+    lines.push('}');
+    lines.push('');
+  }
+
+  lines.push('export default { eases, durations, registerEases, reveals };');
+  lines.push('');
+
+  return lines.join('\n');
+}

package/src/formatters/motion-waapi.js

@@ -0,0 +1,140 @@
+// Web Animations API emitter — `<host>-motion.waapi.js`.
+//
+// The zero-dependency sibling of the Motion One / Framer emitters. Everything
+// here runs on the browser-native `Element.animate()` — no runtime, no bundle
+// cost. WAAPI accepts cubic-bezier easing strings verbatim, so the extracted
+// curves are reproduced *exactly* (no spring approximation, unlike the
+// library targets).
+//
+// We emit:
+//   • `easings`   — the page's cubic-bezier strings, keyed by family
+//   • `durations` — extracted timings in milliseconds
+//   • `keyframes` — keyframe arrays reconstructed from on-page @keyframes,
+//                   ready to hand straight to `el.animate(frames, timing)`
+//   • `animations`— fadeIn / slideUp / scaleIn … helpers returning the live
+//                   Animation object so callers can await `.finished`
+//   • a `prefersReducedMotion()` guard the helpers honour automatically.
+
+function bezier(raw) {
+  if (!raw) return null;
+  const m = String(raw).match(/cubic-bezier\(\s*([-\d.]+)\s*,\s*([-\d.]+)\s*,\s*([-\d.]+)\s*,\s*([-\d.]+)\s*\)/i);
+  if (m) return `cubic-bezier(${m[1]}, ${m[2]}, ${m[3]}, ${m[4]})`;
+  const named = new Set(['linear', 'ease', 'ease-in', 'ease-out', 'ease-in-out']);
+  return named.has(String(raw).trim()) ? String(raw).trim() : null;
+}
+
+function camel(s) {
+  return String(s || '').replace(/[^a-zA-Z0-9]+(.)/g, (_, c) => c.toUpperCase()).replace(/^[0-9]/, '_$&');
+}
+
+export function formatMotionWaapi(design) {
+  const host = (() => { try { return new URL(design?.meta?.url).hostname.replace(/^www\./, ''); } catch { return 'site'; } })();
+  const durations = Array.isArray(design?.motion?.durations) ? design.motion.durations : [];
+  const easings   = Array.isArray(design?.motion?.easings)   ? design.motion.easings   : [];
+  const springs   = Array.isArray(design?.motion?.springs)   ? design.motion.springs   : [];
+  const keyframes = Array.isArray(design?.motion?.keyframes) ? design.motion.keyframes : [];
+
+  const ms = (d) => (d.ms || parseInt(d.css || d.value || d, 10) || 300);
+  const defaultDur = durations.length ? ms(durations[Math.min(2, durations.length - 1)]) : 300;
+
+  // Easings: dedupe by family, keep the most-used first, fall back to a
+  // standard curve when the page exposed nothing parseable.
+  const sortedEase = [...easings].sort((a, b) => (b.count || 0) - (a.count || 0));
+  const easeEntries = [];
+  sortedEase.forEach((e, i) => {
+    const css = bezier(e.raw);
+    if (!css) return;
+    const key = e.family && e.family !== 'custom' ? camel(e.family) : `custom${i + 1}`;
+    if (easeEntries.find((x) => x.key === key)) return;
+    easeEntries.push({ key, css, count: e.count });
+  });
+  // Detected overshoot beziers ride along as a `spring` easing (WAAPI honours
+  // the overshoot natively — the curve simply leaves the [0,1] band).
+  springs.forEach((s) => {
+    const css = bezier(s.raw);
+    if (css && !easeEntries.find((x) => x.key === 'spring')) easeEntries.push({ key: 'spring', css, count: s.count });
+  });
+  if (easeEntries.length === 0) {
+    easeEntries.push({ key: 'standard', css: 'cubic-bezier(0.25, 0.1, 0.25, 1)', count: 0 });
+  }
+  const primaryEaseKey = easeEntries[0].key;
+
+  const lines = [
+    '// Web Animations API presets — generated by designlang (motionlang)',
+    `// Source: ${design?.meta?.url || host}`,
+    `// ${new Date().toISOString()}`,
+    '//',
+    '// Zero-dependency. Runs on the browser-native Element.animate().',
+    `//   import { animations } from './${host}-motion.waapi.js';`,
+    "//   animations.fadeIn(document.querySelector('#hero'));",
+    "//   await animations.slideUp(card, { delay: 80 }).finished;",
+    '',
+    '/** Easing curves extracted from the live page, as WAAPI easing strings. */',
+    'export const easings = {',
+  ];
+  for (const { key, css, count } of easeEntries) {
+    lines.push(`  ${key}: '${css}',${count ? ` // ${count}× on page` : ''}`);
+  }
+  lines.push('};', '');
+
+  lines.push('/** Duration presets (milliseconds), extracted from the live page. */');
+  lines.push('export const durations = {');
+  if (durations.length) {
+    for (const d of durations) lines.push(`  ${camel(d.name || `ms${d.ms}`)}: ${ms(d)},`);
+  } else {
+    lines.push('  fast: 150,', '  base: 300,', '  slow: 500,');
+  }
+  lines.push('};', '');
+
+  // Reconstructed keyframes — WAAPI takes an array of frame objects, so each
+  // step's `prop: value` pairs become one frame.
+  const usedKeyframes = keyframes.filter((k) => k.used && k.steps && k.steps.length);
+  if (usedKeyframes.length) {
+    lines.push('/** @keyframes blocks reconstructed as WAAPI keyframe arrays. */');
+    lines.push('export const keyframes = {');
+    for (const kf of usedKeyframes.slice(0, 16)) {
+      const frames = [];
+      for (const step of kf.steps) {
+        const frame = {};
+        for (const part of (step.style || '').split(';')) {
+          const [p, v] = part.split(':').map((x) => (x || '').trim());
+          if (p && v) frame[camel(p)] = v;
+        }
+        const offset = parseFloat(String(step.offset)) / 100;
+        if (Number.isFinite(offset)) frame.offset = offset;
+        if (Object.keys(frame).length) frames.push(frame);
+      }
+      if (frames.length >= 2) lines.push(`  ${camel(kf.name)}: ${JSON.stringify(frames)},`);
+    }
+    lines.push('};', '');
+  } else {
+    lines.push('/** No on-page @keyframes were attached to elements; emit empty for shape parity. */');
+    lines.push('export const keyframes = {};', '');
+  }
+
+  lines.push('/** Honours the user\'s reduced-motion preference. */');
+  lines.push('export const prefersReducedMotion = () =>');
+  lines.push("  typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;");
+  lines.push('');
+  lines.push(`const _timing = { duration: ${defaultDur}, easing: easings.${primaryEaseKey}, fill: 'both' };`);
+  lines.push('');
+  lines.push('function _animate(el, frames, opts = {}) {');
+  lines.push('  const timing = { ..._timing, ...opts };');
+  lines.push('  if (prefersReducedMotion()) timing.duration = 0;');
+  lines.push('  return el.animate(frames, timing);');
+  lines.push('}');
+  lines.push('');
+  lines.push('/** Animate-on-call helpers. Each returns the live Animation (await `.finished`). */');
+  lines.push('export const animations = {');
+  lines.push('  fadeIn: (el, opts = {}) => _animate(el, [{ opacity: 0 }, { opacity: 1 }], opts),');
+  lines.push('  fadeOut: (el, opts = {}) => _animate(el, [{ opacity: 1 }, { opacity: 0 }], opts),');
+  lines.push("  slideUp: (el, opts = {}) => _animate(el, [{ opacity: 0, transform: 'translateY(16px)' }, { opacity: 1, transform: 'translateY(0)' }], opts),");
+  lines.push("  slideDown: (el, opts = {}) => _animate(el, [{ opacity: 0, transform: 'translateY(-16px)' }, { opacity: 1, transform: 'translateY(0)' }], opts),");
+  lines.push("  scaleIn: (el, opts = {}) => _animate(el, [{ opacity: 0, transform: 'scale(0.96)' }, { opacity: 1, transform: 'scale(1)' }], opts),");
+  lines.push('};', '');
+
+  lines.push('export default { easings, durations, keyframes, animations, prefersReducedMotion };');
+  lines.push('');
+
+  return lines.join('\n');
+}

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)));
+}