@trueclone/cli 0.3.0 → 0.4.0

package/scripts/next.mjs

@@ -304,21 +304,26 @@ await fs.cp(path.join(cloneDir, 'assets'), path.join(out, 'public', 'assets'), {
 for (const f of ['DESIGN.md', 'design-tokens.json']) await fs.copyFile(path.join(root, f), path.join(out, f)).catch(() => {});
 await fs.writeFile(path.join(out, 'package.json'), JSON.stringify(PKG, null, 2) + '\n');
 // custom elements (<code-island>, <swiper-container>) have no JSX type: declared here, or `next build` fails
+// Types for what the page uses that React's typings don't know: custom elements (<code-island>), and HTML attributes
+// newer than the typings or outside them (command, commandfor, popovertarget, a framework's own): an HTML attribute
+// is valid markup whether React lists it or not, so every element accepts any attribute here.
 const custom = new Set();
 (function walk(n) { if (n.tagName && n.tagName.includes('-')) custom.add(n.tagName); for (const c of n.childNodes || []) walk(c); })(body);
-if (custom.size) {
-  await fs.writeFile(path.join(out, 'custom-elements.d.ts'), `// Generated by scripts/next.mjs: the page's custom elements, typed for JSX.
-import type { DetailedHTMLProps, HTMLAttributes } from 'react';
+await fs.rm(path.join(out, 'custom-elements.d.ts'), { force: true });
+await fs.writeFile(path.join(out, 'html-types.d.ts'), `// Generated by scripts/next.mjs: the page's markup, typed for JSX as the browser accepts it.
+import type { DetailedHTMLProps, HTMLAttributes as ReactHTMLAttributes } from 'react';
 
 declare module 'react' {
-  namespace JSX {
+  interface HTMLAttributes<T> {
+    [attribute: string]: unknown;
+  }
+${custom.size ? `  namespace JSX {
     interface IntrinsicElements {
-${[...custom].map((t) => `      ${JSON.stringify(t)}: DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement> & Record<string, unknown>;`).join('\n')}
+${[...custom].map((t) => `      ${JSON.stringify(t)}: DetailedHTMLProps<ReactHTMLAttributes<HTMLElement>, HTMLElement>;`).join('\n')}
     }
   }
-}
+` : ''}}
 `);
-} else await fs.rm(path.join(out, 'custom-elements.d.ts'), { force: true });
 await fs.writeFile(path.join(out, 'postcss.config.mjs'), "export default { plugins: { '@tailwindcss/postcss': {} } };\n");
 await fs.writeFile(path.join(out, 'next.config.mjs'), `import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -366,12 +371,31 @@ async function seededApp() {
   // follow the head's in document order
   const bodyStyles = [];
   (function walk(n) { for (const c of n.childNodes || []) { if (c.tagName === 'style' || c.tagName === 'link') bodyStyles.push(c); else walk(c); } })(body);
+  const layerOrder = []; // the site's own cascade layers, in the order its stylesheets first declare them
+  // a stylesheet's relative @import (patches/x.css importing ../tokens.css): the imported file comes along, renamed
+  // into styles/site/, and the @import points at it there
+  const carryImports = async (css, fromDir) => {
+    const out2 = [];
+    for (const m of css.matchAll(/@import\s+(?:url\()?\s*(['"])([^'"]+)\1\s*\)?/g)) {
+      const spec = m[2];
+      if (/^(https?:)?\/\//.test(spec) || spec.startsWith('data:') || !/\.css(\?|$)/i.test(spec)) continue;
+      const src = path.resolve(fromDir, spec.split('?')[0]);
+      const text = await fs.readFile(src, 'utf8').catch(() => null);
+      if (text === null) { console.warn(`WARNING @import ${spec} not found next to its stylesheet`); continue; }
+      const name = `imported-${path.basename(src)}`;
+      await fs.writeFile(path.join(out, 'styles', 'site', name), text.replace(/url\((['"]?)(?:\.\.\/)*assets\//g, (q0, q) => `url(${q}/assets/`));
+      out2.push([m[0], `@import "./${name}"`]);
+    }
+    for (const [a, b] of out2) css = css.split(a).join(b);
+    return css;
+  };
   for (const e of [...els(head), ...bodyStyles]) {
     const a = attrsOf(e);
-    let css = null, file = null;
+    let css = null, file = null, fromDir = cloneDir;
     if (e.tagName === 'link' && a.rel === 'stylesheet' && a.href && !/^(https?:)?\/\//.test(a.href)) {
       css = await fs.readFile(path.join(cloneDir, a.href), 'utf8').catch(() => null);
       file = path.basename(a.href);
+      fromDir = path.dirname(path.join(cloneDir, a.href));
     } else if (e.tagName === 'style') {
       css = (e.childNodes || []).map((c) => c.value || '').join('');
       file = `inline-${++inline}.css`;
@@ -379,6 +403,8 @@ async function seededApp() {
     if (css === null) continue;
     // stylesheets lived in clone/css/ (assets at ../assets/), inline blocks in the page (assets at assets/)
     css = css.replace(/url\((['"]?)(?:\.\.\/)?assets\//g, (m, q) => `url(${q}/assets/`);
+    css = await carryImports(css, fromDir);
+    for (const m of css.matchAll(/@layer\s+([\w-]+(?:\s*,\s*[\w-]+)*)\s*[;{]/g)) for (const l of m[1].split(',').map((x) => x.trim())) if (!layerOrder.includes(l)) layerOrder.push(l);
     usesTailwind ||= /--tw-|tailwindcss v\d/.test(css);
     await fs.writeFile(path.join(out, 'styles', 'site', file), css);
     imports.push(`import '../styles/site/${file}';`);
@@ -391,7 +417,11 @@ async function seededApp() {
   const tailwind = usesTailwind ? '@import "tailwindcss" source(none);'
     : '/* no preflight: the original was not built with Tailwind and relies on browser defaults */\n@layer theme, base, components, utilities;\n@import "tailwindcss/theme.css" layer(theme);\n@import "tailwindcss/utilities.css" layer(utilities) source(none);';
   const scoped = theme.replace('@import "tailwindcss";', `${tailwind}\n@source "../components/ui";`);
-  await fs.writeFile(path.join(out, 'app', 'globals.css'), scoped);
+  // Cascade layers are ordered by their first declaration anywhere in the page. globals.css loads first, so the site's
+  // own order goes at its very top: otherwise Tailwind's "base" is declared before the site's "reset", and the site's
+  // reset ends up overriding its own base.
+  const layerHead = layerOrder.length ? `/* the original's cascade layer order, declared first (see scripts/next.mjs) */\n@layer ${layerOrder.join(', ')};\n` : '';
+  await fs.writeFile(path.join(out, 'app', 'globals.css'), layerHead + scoped);
   const siteCssImports = imports;
 
   // markup
@@ -482,6 +512,30 @@ async function seededApp() {
     }
   };
   for (const a of scriptTags) if (a.src) await copyScript(a.src);
+  // the page's other head links (icons, font preloads, preconnects, a manifest), as in the HTML clone; local files are
+  // served from public/ at the same path
+  const headLinks = [];
+  for (const e of els(head)) {
+    // the seed's own small head scripts (tc-vw keeps --tc-vw at 1% of the layout width): they must run before paint
+    if (e.tagName === 'script' && /^tc-/.test(attrsOf(e).id || '') && !attrsOf(e).src) {
+      headLinks.push(`        <script id=${JSON.stringify(attrsOf(e).id)} dangerouslySetInnerHTML={{ __html: ${JSON.stringify((e.childNodes || []).map((c) => c.value || '').join(''))} }} />`);
+      continue;
+    }
+    if (e.tagName !== 'link') continue;
+    const a = attrsOf(e);
+    const rel = String(a.rel || '').toLowerCase();
+    if (!a.href || rel === 'stylesheet' || !/\b(icon|apple-touch-icon|mask-icon|preload|prefetch|preconnect|dns-prefetch|manifest)\b/.test(rel)) continue;
+    if (/\bpreload\b/.test(rel) && a.as === 'script') continue; // the scripts' own preloads are written below
+    let href = a.href;
+    if (!/^(https?:)?\/\//.test(href) && !href.startsWith('data:')) {
+      const clean = href.replace(/^\.\//, '').split(/[?#]/)[0];
+      const to = path.join(out, 'public', clean);
+      if (!clean.startsWith('assets/')) { await fs.mkdir(path.dirname(to), { recursive: true }); await fs.copyFile(path.join(cloneDir, clean), to).catch(() => {}); }
+      href = `/${clean}`;
+    }
+    const attrs = Object.entries({ ...a, href }).filter(([k]) => !/^on/.test(k)).map(([k, v]) => `${k === 'crossorigin' ? 'crossOrigin' : k === 'hreflang' ? 'hrefLang' : k === 'referrerpolicy' ? 'referrerPolicy' : k === 'fetchpriority' ? 'fetchPriority' : k}=${JSON.stringify(k === 'crossorigin' && v === '' ? 'anonymous' : v)}`);
+    headLinks.push(`        <link ${attrs.join(' ')} />`);
+  }
   const scriptList = scriptTags.map((a) => ({ ...(a.src ? { src: '/' + a.src.split(/[?#]/)[0].replace(/^\.\//, '') } : { code: a.code }), ...(a.type === 'module' ? { type: 'module' } : {}) }));
   await fs.writeFile(path.join(out, 'components', 'site', 'SiteScripts.tsx'), `'use client';
 // Generated by scripts/next.mjs: runs the clone's scripts (trueclone's players, inline scripts, script.js) in order,
@@ -533,6 +587,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
   return (
     <html${htmlAttrs} suppressHydrationWarning>
       <head>
+${headLinks.join('\n')}
         {/* the clone's scripts start downloading with the page; SiteScripts runs them the moment hydration is done */}
 ${scriptList.filter((s) => s.src).map((s) => `        <link rel="${s.type === 'module' ? 'modulepreload' : 'preload'}" href=${JSON.stringify(s.src)}${s.type === 'module' ? '' : ' as="script"'} />`).join('\n')}
       </head>
@@ -587,11 +642,21 @@ if (flags.verify) {
   for (let i = 0; i < 60; i++) { try { if ((await fetch(url)).ok) break; } catch { /* starting */ } await new Promise((r) => setTimeout(r, 1000)); }
   const lab = path.resolve('.');
   const score = (args) => run('node', args, { cwd: lab });
+  // The app is scored with the same checks, into compare-next/ and REPORT.next.md: the HTML clone's compare/ and
+  // REPORT.md are moved aside first and put back after, so its scores are never overwritten by the app's.
+  const exists = (p) => fs.stat(p).then(() => true, () => false);
+  const keep = [[path.join(root, 'compare'), path.join(root, '.compare-html')], [path.join(root, 'REPORT.md'), path.join(root, '.REPORT-html.md')]];
+  for (const [from, to] of keep) { await fs.rm(to, { recursive: true, force: true }); if (await exists(from)) await fs.rename(from, to); }
   try {
     // same scoring entry point as the HTML clone: time limit per step, summary at the end
     await score([path.join(path.dirname(toPath(import.meta.url)), 'score.mjs'), name, '--url', url, ...(flags.quick ? ['--quick'] : [])]);
   } finally {
     if (process.platform === 'win32') spawn('taskkill', ['/pid', String(server.pid), '/T', '/F']);
     else server.kill();
+    await fs.rm(path.join(root, 'compare-next'), { recursive: true, force: true });
+    if (await exists(path.join(root, 'compare'))) await fs.rename(path.join(root, 'compare'), path.join(root, 'compare-next'));
+    if (await exists(path.join(root, 'REPORT.md'))) await fs.rename(path.join(root, 'REPORT.md'), path.join(root, 'REPORT.next.md'));
+    for (const [from, to] of keep) if (await exists(to)) await fs.rename(to, from);
+    console.log(`Next.js app scores: ${path.relative(process.cwd(), path.join(root, 'REPORT.next.md'))} (details in compare-next/); the HTML clone's REPORT.md is unchanged`);
   }
 }

package/scripts/report.mjs

@@ -4,6 +4,7 @@
 //
 // usage: node scripts/report.mjs <name>
 import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
 import path from 'node:path';
 import { parseArgs } from './lib.mjs';
 
@@ -22,10 +23,14 @@ if (!meta) {
 }
 
 // Targets a clone has to meet (the same ones the skill gives the agent).
-const T = { layout: 98, statesGap: 5, motion: 95, detail: 95, hovers: 90, load: 95 };
+const T = { layout: 98, states: 95, canvas: 90, motion: 95, detail: 95, hovers: 90, load: 95 };
+// an accepted difference never covers a value below this, and needs evidence (a file it names that exists)
+const ACCEPT_FLOOR = 95;
 const mark = (ok, acceptedNote) => (ok === null ? '–' : ok ? 'pass' : acceptedNote ? `accepted (${acceptedNote})` : '**below target**');
 const pct = (v) => (v === undefined || v === null ? '–' : `${v}%`);
-const VPS = ['desktop', 'tablet', 'mobile'];
+// the seed sizes, then the held-out sizes (captured and scored, never used to build the clone)
+const VPS = ['desktop', 'tablet', 'mobile', 'laptop', 'wide'];
+const HELD = new Set(['laptop', 'wide']);
 
 const layout = await read('compare/report.mask.json');
 const visual = await read('compare/report.json');
@@ -46,8 +51,23 @@ const notesSection = (title) => {
   return m ? m[1].replace(/<!--[\s\S]*?-->/g, '').split('\n').map((l) => l.trim()).filter((l) => /^[-*]\s+\S/.test(l)).map((l) => l.replace(/^[-*]\s+/, '')) : [];
 };
 const accepted = notesSection('Accepted differences');
+// review: the frames trueclone review wrote, and the verdict the agent gave each in notes.md
+const reviewVerdicts = notesSection('Review');
+const reviewFrames = [];
+for (const size of ['wide', 'laptop', 'desktop', 'tablet', 'mobile']) {
+  const fr = await read(`compare/review/${size}/frames.json`);
+  for (const x of fr?.frames || []) {
+    const v = reviewVerdicts.find((l) => l.startsWith(`${x.id} ${size}:`) || l.startsWith(`${x.id} ${size} :`));
+    reviewFrames.push({ size, id: x.id, pct: x.pct, verdict: v ? v.slice(v.indexOf(':') + 1).trim() : null });
+  }
+}
+const reviewOpen = reviewFrames.filter((x) => !x.verdict || !/^same\b/i.test(x.verdict));
 const findings = notesSection('Findings');
-const acceptedFor = (check, vp) => accepted.filter((a) => new RegExp(`\\b${check}\\b`, 'i').test(a) && (!vp || new RegExp(`\\b${vp}\\b`, 'i').test(a) || !/\b(desktop|tablet|mobile)\b/i.test(a)));
+// an entry needs `evidence: <file>` naming a file in the site folder (a crop, a measurement): a reason without proof
+// is a gap, not a decision
+const hasEvidence = (a) => { const m = /evidence:\s*([^\s;,)]+)/i.exec(a); return Boolean(m && fsSync.existsSync(path.resolve(root, m[1]))); };
+const acceptedFor = (check, vp) => accepted.filter((a) => hasEvidence(a) && new RegExp(`\\b${check}\\b`, 'i').test(a) && (!vp || new RegExp(`\\b${vp}\\b`, 'i').test(a) || !/\b(desktop|tablet|mobile|laptop|wide)\b/i.test(a)));
+const unproven = accepted.filter((a) => !hasEvidence(a));
 
 const byVp = (rep, key = 'match') => Object.fromEntries((rep?.viewports || []).map((v) => [v.viewport, v[key] ?? v.score]));
 const L = byVp(layout), V = byVp(visual), S = byVp(states), D = byVp(detail, 'score');
@@ -60,7 +80,8 @@ const row = (check, values, test, note = '') => {
   // below target, but every failing width has an accepted entry in notes.md: the decision is recorded, not hidden
   const key = check.split(' ')[0].toLowerCase();
   const failing = typeof test === 'function' ? present(values).filter((v) => !test(values[v], v)) : ok === false ? present(values) : [];
-  const covered = failing.length && failing.every((v) => acceptedFor(key, v).length);
+  // never below the floor: an accepted difference explains the last few points, not a broken page
+  const covered = failing.length && failing.every((v) => (typeof values[v] !== 'number' || values[v] >= ACCEPT_FLOOR) && acceptedFor(key, v).length);
   const stale = drift?.stale && ['detail', 'hovers', 'motion', 'load', 'interactions'].includes(key) ? ' **stale capture**' : '';
   rows.push(`| ${check} | ${VPS.map((v) => pct(values[v])).join(' | ')} | ${mark(ok, covered ? acceptedFor(key)[0].slice(0, 60) : null)}${stale} | ${note} |`);
 };
@@ -68,17 +89,23 @@ const present = (vals) => VPS.filter((v) => vals[v] !== undefined && vals[v] !==
 const all = (vals, test) => (present(vals).length ? present(vals).every((v) => test(vals[v], v)) : null);
 row(`Layout (structure)`, L, (x) => x >= T.layout, `target ≥ ${T.layout}%; text and media masked`);
 if (meta.mode === 'exact') row('Layout (real pixels)', V, (x) => x >= T.layout, 'exact mode: same text and media');
-row('Scroll states', S, (x, v) => L[v] === undefined || x >= L[v] - T.statesGap, `within ${T.statesGap} points of layout`);
+row('Scroll states', S, (x) => x >= T.states, `target ≥ ${T.states}%`);
+const CV = byVp(states, 'canvas');
+if (present(CV).length) row('Canvases', CV, (x) => x >= T.canvas, `target ≥ ${T.canvas}%; what each scene draws, compared in the scroll-state frames (colours and coverage)`);
 row('Motion curves', C, (x) => x >= T.motion, present(C).length ? `target ≥ ${T.motion}%` : 'no motion map (no scroll or time animation to score)');
 row('Detail (styles)', D, (x) => x >= T.detail, `target ≥ ${T.detail}%; font, size, weight, line height, colour, boxes`);
 row('Hovers', { desktop: hovers?.score }, hovers ? hovers.score >= T.hovers : null, `target ≥ ${T.hovers}% of the reference hover effects`);
 const LD = byVp(load, 'score');
 const tts = (side) => VPS.map((v) => load?.viewports.find((x) => x.viewport === v)).filter(Boolean).map((x) => (x[side]?.settledAt === null ? '>4000' : x[side]?.settledAt)).filter((x) => x !== undefined);
 row('Load sequence', LD, (x) => x >= T.load, present(LD).length ? `target ≥ ${T.load}%; how settled each side is at 0.25 to 4 s, cold cache, same network (settled at: reference ${tts('ref').map((x) => `${x}ms`).join(' / ') || '–'}, clone ${tts('clone').map((x) => `${x}ms`).join(' / ') || '–'})` : 'not measured (trueclone load <name>)');
+if (reviewFrames.length) {
+  const sizes = [...new Set(reviewFrames.map((x) => x.size))];
+  rows.push(`| Review (by eye) | ${VPS.map((v) => (sizes.includes(v) ? `${reviewFrames.filter((x) => x.size === v && x.verdict && /^same\b/i.test(x.verdict)).length}/${reviewFrames.filter((x) => x.size === v).length}` : '–')).join(' | ')} | ${reviewOpen.length ? '**below target**' : 'pass'} | frames signed off "same" in notes.md (trueclone review) |`);
+} else rows.push(`| Review (by eye) | – | – | – | – | – | **below target** | not done: run trueclone review <name> and give every frame a verdict in notes.md |`);
 const scenarios = interact?.scenarios || [];
 const failed = scenarios.filter((s) => s.expect && !s.expect.pass);
 row('Interactions', { desktop: scenarios.length ? +(scenarios.reduce((n, s) => n + (s.score || 0), 0) / scenarios.length).toFixed(2) : undefined }, scenarios.length ? failed.length === 0 : null,
-  scenarios.length ? `${scenarios.length - failed.length}/${scenarios.length} scenarios change something on both sides` : 'no interactions.json');
+  scenarios.length ? `${scenarios.length - failed.length}/${scenarios.length} scenarios change on both sides and end in the reference's state (≥ 95)` : 'no interactions.json');
 
 const failing = rows.filter((r) => r.includes('below target')).length;
 const acceptedCount = rows.filter((r) => r.includes('| accepted (')).length;
@@ -88,7 +115,9 @@ const verdict = (failing ? `${failing} check(s) below target` : 'every scored ch
 const weak = [];
 for (const v of VPS) for (const s of (layout?.viewports.find((x) => x.viewport === v)?.worstSections || []).slice(0, 2)) if (s.match < 99) weak.push(`- Layout ${v}: section "${String(s.label).slice(0, 50)}" at y ${s.y} is ${s.match}%`);
 for (const v of VPS) for (const e of (curves[v]?.entries || []).filter((x) => x.score < 90).slice(0, 3)) weak.push(`- Motion ${v}: "${e.name}" ${e.score}%${e.note ? ` (${e.note})` : ''}`);
-for (const s of failed) weak.push(`- Interaction "${s.name}": the expected change happened on ${s.expect.ref ? 'the reference' : 'neither side'}${s.expect.clone ? '' : ', not on the clone'}`);
+for (const s of failed) weak.push(s.expect.ref !== null && !(s.expect.ref && s.expect.clone)
+  ? `- Interaction "${s.name}": the expected change happened on ${s.expect.ref ? 'the reference' : 'neither side'}${s.expect.clone ? '' : ', not on the clone'}`
+  : `- Interaction "${s.name}": the clone ends in a different state (${s.score}% like the reference's)`);
 for (const v of (load?.viewports || []).filter((x) => x.score < T.load)) {
   const worst = Object.entries(v.gap || {}).sort((a, b) => b[1] - a[1])[0];
   if (worst) weak.push(`- Load ${v.viewport}: at ${worst[0]}ms the clone is ${v.clone.curve[worst[0]]}% settled, the reference ${v.ref.curve[worst[0]]}% (settled at ${v.clone.settledAt ?? '>4000'}ms vs ${v.ref.settledAt ?? '>4000'}ms)`);
@@ -123,15 +152,18 @@ const md = `# trueclone report: ${name}
 | Scored | ${layout?.at || '–'}${layout?.clone && !/127\.0\.0\.1:\d+\/$/.test(layout.clone) ? ` against ${layout.clone}` : ''} |
 | Verdict | **${verdict}** |
 ${times ? `| Scoring time | ${times.totalMin} min (${times.kind}${times.only ? `, only ${times.only.join(',')}` : ''}): ${Object.entries(times.steps).filter(([, s]) => s.seconds).map(([k, s]) => `${k} ${s.seconds}s`).join(', ')}${Object.values(times.steps).some((s) => /kept/.test(s.status)) ? '; unchanged checks kept from their last run' : ''} |` : ''}
-${(detail?.viewports || []).some((v) => v.unstable) || hovers?.unstable || (load?.viewports || []).some((v) => v.unstable) ? `| Not scored | ${(detail?.viewports || []).filter((v) => v.unstable).map((v) => `${v.unstable} detail probe${v.unstable > 1 ? 's' : ''} (${v.viewport})`).concat(hovers?.unstable ? [`${hovers.unstable} hover${hovers.unstable > 1 ? 's' : ''}`] : [], (load?.viewports || []).filter((v) => v.unstable).map((v) => `load ${v.viewport} (±${v.noise} between two runs)`)).join(', ')}: unstable on the reference or the clone itself (random motion, timing), excluded from the scores above |` : ''}
+${(detail?.viewports || []).some((v) => v.unstable) || hovers?.unstable || (load?.viewports || []).some((v) => v.unstable) ? `| Not scored | ${(detail?.viewports || []).filter((v) => v.unstable).map((v) => `${v.unstable} detail probe${v.unstable > 1 ? 's' : ''} (${v.viewport})`).concat(hovers?.unstable ? [`${hovers.unstable} hover${hovers.unstable > 1 ? 's' : ''}`] : [], (load?.viewports || []).filter((v) => v.unstable).map((v) => `load ${v.viewport} (±${v.ref?.noise ?? v.noise} between two runs)`)).join(', ')}: unstable on the reference itself (random motion, timing), excluded from the scores above |` : ''}
+${(load?.viewports || []).some((v) => v.cloneUnstable) ? `| Clone loads inconsistently | ${load.viewports.filter((v) => v.cloneUnstable).map((v) => `${v.viewport} (±${v.clone.noise} between two runs)`).join(', ')}: the clone's own load differs from one run to the next; scored by its worse run, since a visitor can get either |` : ''}
 
 ## Scores
 
-| Check | Desktop | Tablet | Mobile | Status | Notes |
-|---|---|---|---|---|---|
+| Check | Desktop 1440 | Tablet 768 | Mobile 390 | Laptop 1280 ° | Wide 1920 ° | Status | Notes |
+|---|---|---|---|---|---|---|---|
 ${rows.join('\n')}
 
-${drift?.stale ? `## Stale capture\n\nThe live page differs from the capture of ${meta.capturedAt}: ${drift.viewports.filter((v) => v.stale).map((v) => `${v.viewport} ${v.livePageHeight}px tall vs ${v.capturedPageHeight}px captured, ${v.liveSections} vs ${v.capturedSections} sections`).join('; ')}. Layout and states score against the captured screenshots; detail, hovers, motion, interactions and load measure the live page and are marked stale above. Re-capture (\`trueclone capture\`, then \`states\`, \`reveals\`, \`seed --force\`) before reading them.\n\n` : ''}${accepted.length ? `## Accepted differences\n\nRecorded in notes.md with a reason; a check below target that is covered here is marked "accepted" in the table.\n\n${accepted.map((a) => `- ${a}`).join('\n')}\n\n` : ''}${weak.length ? `## Fix first\n\n${weak.join('\n')}\n` : '## Fix first\n\nNothing below 99% on layout, 90% on motion or failing.\n'}
+° held out: captured and scored, never used to build the clone. A clone right at the seed sizes and wrong here is fitted to those sizes, not a copy of the site.
+${unproven.length ? `\n${unproven.length} accepted difference(s) in notes.md name no evidence file and are not applied: ${unproven.map((a) => `"${a.slice(0, 50)}…"`).join('; ')}\n` : ''}
+${drift?.stale ? `## Stale capture\n\nThe live page differs from the capture of ${meta.capturedAt}: ${drift.viewports.filter((v) => v.stale).map((v) => `${v.viewport} ${v.livePageHeight}px tall vs ${v.capturedPageHeight}px captured, ${v.liveSections} vs ${v.capturedSections} sections`).join('; ')}. Layout and states score against the captured screenshots; detail, hovers, motion, interactions and load measure the live page and are marked stale above. Re-capture (\`trueclone capture\`, then \`states\`, \`reveals\`, \`seed --force\`) before reading them.\n\n` : ''}${accepted.length ? `## Accepted differences\n\nRecorded in notes.md with a reason; a check below target that is covered here is marked "accepted" in the table.\n\n${accepted.map((a) => `- ${a}`).join('\n')}\n\n` : ''}${reviewOpen.length ? `## Review: open frames\n\n${reviewOpen.slice(0, 40).map((x) => `- ${x.id} ${x.size}: ${x.verdict || 'no verdict yet'} (compare/review/${x.size}/${x.id}.png)`).join('\n')}\n\n` : ''}${weak.length ? `## Fix first\n\n${weak.join('\n')}\n` : '## Fix first\n\nNothing below 99% on layout, 90% on motion or failing.\n'}
 ${findings.length ? `## Findings (tool defects met on this site)\n\n${findings.map((f) => `- ${f}`).join('\n')}\n\n` : ''}## Motion found on the reference
 
 ${motionInv ? `Libraries: ${libs.length ? libs.join(', ') : 'none (no GSAP, Lenis, Swiper or similar)'}. ScrollTriggers: ${motionInv.triggers?.length ?? 0}. Tweens created while scrolling: ${motionInv.onScroll?.length ?? 0}. CSS animations: ${(motionInv.css || []).length}.` : 'Not inventoried yet (trueclone motion <name>).'}
@@ -142,5 +174,7 @@ ${motionInv ? `Libraries: ${libs.length ? libs.join(', ') : 'none (no GSAP, Leni
 - **Tracking, analytics and bot protection** are left out on purpose${tracking.length ? `: ${[...new Set(tracking.map((c) => { try { const u = new URL(c.url); return `${u.host}${u.pathname.split('/').slice(0, 3).join('/')}`; } catch { return host(c.url); } }))].join(', ')}` : ''}.
 ${data.length ? `- **Data and API calls** the reference makes (${uniq(data).length}), which the clone does not call; their captured responses are in reference/desktop.har:\n${uniq(data).slice(0, 15).map((c) => `  - \`${c.method} ${c.url.split('?')[0].slice(0, 110)}\` → ${c.status} ${c.type.split(';')[0]}`).join('\n')}` : '- **Data and API calls**: none seen during the capture (static content).'}
 `;
-await fs.writeFile(path.join(root, 'REPORT.md'), md);
+// rows left out of the summary table (an empty optional row) must not leave a blank line that splits it
+const [head, ...rest] = md.split('\n## Scores');
+await fs.writeFile(path.join(root, 'REPORT.md'), [head.replace(/(\|[^\n]*)\n(?:\n)+(?=\|)/g, '$1\n'), ...rest].join('\n## Scores'));
 console.log(`${verdict} -> ${path.relative(process.cwd(), path.join(root, 'REPORT.md'))}`);

package/scripts/reveals.mjs

@@ -205,6 +205,10 @@ async function record(vp) {
     await page.goto(meta.url, { waitUntil: 'load', timeout: 60000 });
     await page.mouse.move(5, vp.height - 5);
     await waitStill(page, { timeout: 15000, interval: 200 });
+    // Only what scrolling does: with pointer events off, whatever scrolls under the resting pointer is never hovered,
+    // so a card that opens on hover is not recorded as opened by the scroll. (Wheel input still reaches the page.)
+    await page.addStyleTag({ content: '*, *::before, *::after { pointer-events: none !important; }' });
+    await page.mouse.move(vp.width - 2, Math.round(vp.height / 2));
     const count = await page.evaluate(watchInPage);
     // Class changes caused by scrolling (a header that gets its backdrop, an "is-visible" toggle): watched with a
     // MutationObserver. Anything that changes while the page sits idle (timers, carousels) is ignored.

package/scripts/review.mjs

@@ -0,0 +1,149 @@
+// Review: the reference and the clone side by side, the way a person looks at a website, at a size the clone was never
+// built from (default: the held-out 1920x1080). Frames: the load at 0.3, 1.5 and 4.5 s, then every section (and every
+// screen of a tall one) after scrolling to it with the wheel, each also with the pointer resting on the control nearest
+// the middle of the screen. Each frame is one image, reference left, clone right, in compare/review/<size>/, listed in
+// compare/review/<size>/index.md with its pixel match.
+//
+// The agent looks at every frame and writes a verdict per frame in notes.md under "## Review":
+//   - 03-section-2 wide: same
+//   - 07-section-4-hover wide: differs: the panel opens on the wrong card
+// REPORT.md counts the frames signed off; "differs" and frames without a verdict are listed as open.
+//
+// usage: node scripts/review.mjs <name> [--size wide|laptop|desktop|tablet|mobile] [--url <clone url>]
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { SCORED, parseArgs, openBrowser, newPage, serve, matchPct, PNG } from './lib.mjs';
+
+const { pos, flags } = parseArgs(process.argv.slice(2));
+const [name] = pos;
+if (!name) {
+  console.error('usage: trueclone review <name> [--size wide] [--url <clone url>]');
+  process.exit(1);
+}
+const root = path.resolve('sites', name);
+const ref = path.join(root, 'reference');
+const meta = JSON.parse(await fs.readFile(path.join(ref, 'meta.json'), 'utf8'));
+const vp = SCORED.find((v) => v.name === (flags.size || 'wide'));
+if (!vp) { console.error(`unknown size ${flags.size}: ${SCORED.map((v) => v.name).join(', ')}`); process.exit(1); }
+const server = typeof flags.url === 'string' ? null : await serve(path.join(root, 'clone'));
+const cloneUrl = server ? `${server.url}index.html` : flags.url;
+const outDir = path.join(root, 'compare', 'review', vp.name);
+await fs.rm(outDir, { recursive: true, force: true });
+await fs.mkdir(outDir, { recursive: true });
+
+// the frame plan comes from the reference at this size: section tops, and a frame per screen in tall sections
+const sections = JSON.parse(await fs.readFile(path.join(ref, `${vp.name}.sections.json`), 'utf8').catch(() => 'null'));
+if (!sections) { console.error(`no capture at ${vp.name} (${vp.width}x${vp.height}): re-capture with trueclone 0.4+`); process.exit(1); }
+const plan = [];
+sections.forEach((s, i) => {
+  const top = Math.max(0, s.y);
+  const screens = Math.max(1, Math.min(4, Math.round((s.height || s.h || vp.height) / vp.height)));
+  for (let k = 0; k < screens; k++) plan.push({ label: `section-${i + 1}${screens > 1 ? `-${k + 1}` : ''}`, y: top + k * vp.height });
+});
+const frames = plan.slice(0, 30);
+
+// the control nearest the middle of the screen: links, buttons, pointer-cursor elements, cards with a hover listener
+function hoverPoint() {
+  let best = null;
+  for (const el of document.querySelectorAll('a, button, [role="button"], [role="tab"], summary, *')) {
+    const s = getComputedStyle(el);
+    if (s.cursor !== 'pointer' && !['A', 'BUTTON', 'SUMMARY'].includes(el.tagName)) continue;
+    const r = el.getBoundingClientRect();
+    if (r.width * r.height < 1500 || r.bottom < 60 || r.top > innerHeight - 20 || r.width > innerWidth * 0.9) continue;
+    const cx = r.left + r.width / 2, cy = Math.min(Math.max(r.top + r.height / 2, 70), innerHeight - 20);
+    const d = Math.hypot(cx - innerWidth / 2, cy - innerHeight / 2);
+    if (!best || d < best.d) best = { x: Math.round(cx), y: Math.round(cy), d };
+  }
+  return best;
+}
+
+async function shoot(url, side) {
+  const { context, page } = await newPage(await browserP, vp, { reducedMotion: 'no-preference' });
+  const shots = {};
+  try {
+    const t0 = Date.now();
+    const nav = page.goto(url, { waitUntil: 'load', timeout: 60000 }).catch(() => null);
+    for (const t of [300, 1500, 4500]) {
+      const wait = t0 + t - Date.now();
+      if (wait > 0) await page.waitForTimeout(wait);
+      shots[`load-${t}`] = await page.screenshot().catch(() => null);
+    }
+    await nav;
+    await page.waitForTimeout(1500);
+    const scrollTo = async (y) => {
+      // with the wheel, the way a visitor scrolls: scroll-linked scenes and smooth scrolling follow wheel input
+      await page.mouse.move(Math.round(vp.width * 0.98), Math.round(vp.height * 0.5));
+      const now = await page.evaluate(() => scrollY);
+      const n = Math.max(1, Math.ceil(Math.abs(y - now) / 400));
+      for (let i = 0; i < n; i++) { await page.mouse.wheel(0, (y - now) / n); await page.waitForTimeout(60); }
+      await page.waitForTimeout(1600);
+    };
+    for (const f of frames) {
+      await scrollTo(f.y);
+      shots[f.label] = await page.screenshot();
+      const at = side === 'ref' ? await page.evaluate(hoverPoint) : hoverPoints[f.label];
+      if (side === 'ref') hoverPoints[f.label] = at;
+      if (at) {
+        await page.mouse.move(at.x - 30, at.y, { steps: 4 });
+        await page.mouse.move(at.x, at.y, { steps: 6 });
+        await page.waitForTimeout(1100);
+        shots[`${f.label}-hover`] = await page.screenshot();
+        await page.mouse.move(Math.round(vp.width * 0.98), Math.round(vp.height * 0.5));
+      }
+    }
+  } finally {
+    await context.close();
+  }
+  return shots;
+}
+
+const hoverPoints = {};
+const browserP = openBrowser(flags.cdp);
+const browser = await browserP;
+let refShots, cloneShots;
+try {
+  refShots = await shoot(meta.url, 'ref');
+  cloneShots = await shoot(cloneUrl, 'clone');
+} finally {
+  if (!flags.cdp) await browser.close();
+  server?.close();
+}
+
+// one image per frame: reference | clone, half size, with the frame's pixel match
+const lines = [];
+let n = 0;
+for (const label of Object.keys(refShots)) {
+  const a = refShots[label] && PNG.sync.read(refShots[label]);
+  const b = cloneShots[label] && PNG.sync.read(cloneShots[label]);
+  if (!a || !b) continue;
+  const scale = 0.5, w = Math.round(vp.width * scale), h = Math.round(vp.height * scale);
+  const img = new PNG({ width: w * 2 + 12, height: h });
+  img.data.fill(255);
+  [a, b].forEach((src, k) => {
+    for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) {
+      const sx = Math.min(src.width - 1, Math.round(x / scale)), sy = Math.min(src.height - 1, Math.round(y / scale));
+      const si = (sy * src.width + sx) * 4, di = (y * img.width + x + k * (w + 12)) * 4;
+      img.data[di] = src.data[si]; img.data[di + 1] = src.data[si + 1]; img.data[di + 2] = src.data[si + 2]; img.data[di + 3] = 255;
+    }
+  });
+  const id = `${String(n++).padStart(2, '0')}-${label}`;
+  await fs.writeFile(path.join(outDir, `${id}.png`), PNG.sync.write(img));
+  const pct = matchPct(a, b).pct;
+  lines.push({ id, pct });
+}
+await fs.writeFile(path.join(outDir, 'index.md'), `# Review at ${vp.name} (${vp.width}x${vp.height}): reference left, clone right
+
+Look at every frame. In notes.md under "## Review", one line per frame: \`- <frame> ${vp.name}: same\` or
+\`- <frame> ${vp.name}: differs: <what you see>\`. Pixel match is a hint, not the verdict: a 99% frame can hide a wrong
+panel, and a 90% frame can be a random animation phase.
+
+| frame | pixel match |
+|---|---|
+${lines.map((l) => `| [${l.id}](${l.id}.png) | ${l.pct}% |`).join('\n')}
+`);
+// make sure notes.md has the section the verdicts go in
+const notesFile = path.join(root, 'notes.md');
+const notes = await fs.readFile(notesFile, 'utf8').catch(() => '');
+if (!/^## Review/m.test(notes)) await fs.appendFile(notesFile, `\n## Review\n\n<!-- one line per frame of compare/review/<size>/index.md: "- <frame> <size>: same" or "- <frame> <size>: differs: <what>". REPORT.md counts them. -->\n`);
+await fs.writeFile(path.join(outDir, 'frames.json'), JSON.stringify({ size: vp.name, at: new Date().toISOString(), frames: lines }, null, 2));
+console.log(`review (${vp.name} ${vp.width}x${vp.height}): ${lines.length} frames -> ${path.relative(process.cwd(), path.join(outDir, 'index.md'))}; lowest pixel match: ${[...lines].sort((x, y) => x.pct - y.pct).slice(0, 4).map((l) => `${l.id} ${l.pct}%`).join(', ')}`);

package/scripts/score.mjs

@@ -84,7 +84,10 @@ async function cloneHash() {
 const stampsFile = path.join(root, 'compare', '.stamps.json');
 const stamps = url ? {} : await fs.readFile(stampsFile, 'utf8').then(JSON.parse).catch(() => ({}));
 const inputs = url ? null : { hash: await cloneHash(), capturedAt, args: null };
-const stampKey = (step) => JSON.stringify({ hash: inputs?.hash, capturedAt, args: step.args });
+// the step's own code is an input too: a changed check must re-measure, never report its old number
+const codeHash = async (file) => crypto.createHash('sha1').update(await fs.readFile(path.join(HERE, path.basename(file)), 'utf8').catch(() => '')).update(await fs.readFile(path.join(HERE, 'lib.mjs'), 'utf8').catch(() => '')).digest('hex').slice(0, 12);
+const codeHashes = Object.fromEntries(await Promise.all(steps.map(async (st) => [st.label, await codeHash(st.args[0])])));
+const stampKey = (step) => JSON.stringify({ hash: inputs?.hash, capturedAt, args: step.args, code: codeHashes[step.label] });
 const reusable = (step) => !step.live && !url && !flags.fresh && !flags['refresh-ref'] && stamps[step.label]?.key === stampKey(step) && stamps[step.label].values !== undefined;
 
 const runStep = (step) => new Promise((resolve) => {

package/scripts/scripts-evidence.mjs

@@ -0,0 +1,116 @@
+// The reference's own code, as evidence for the agent (never copied into the clone): every script the page ran, saved
+// as shipped and as a readable copy, ranked by how much of it actually ran while the page loaded and was scrolled
+// through (V8 precise coverage), with every element's event listeners pointing at file:line:col. This is what lets an
+// agent port a scene's algorithm (a grid computed from the viewport, a spring, a scroll scene) instead of copying the
+// numbers it produced at one screen size. Read through Chrome's DevTools protocol; no extra tool needed.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const TRACKING = /google-analytics|googletagmanager|gtag|doubleclick|facebook\.(com|net)|fbevents|hotjar|segment\.(io|com)|plausible|cloudflareinsights|clarity\.ms|sentry|datadog|mixpanel|amplitude|posthog|intercom|hubspot|hs-scripts|linkedin|licdn|tiktok|twitter|ads-twitter|redditstatic|marketo|munchkin|challenges\.cloudflare|recaptcha|hcaptcha|turnstile|cdn-cgi\/rum|debugbear/i;
+
+// Before navigation: start collecting. Returns finish(), to call once the page has loaded and been scrolled through.
+export async function startScriptEvidence(page, pageUrl) {
+  const cdp = await page.context().newCDPSession(page);
+  const scripts = new Map(); // scriptId -> { url, inline }
+  cdp.on('Debugger.scriptParsed', (e) => {
+    if (!e.executionContextAuxData?.isDefault) return; // the page's own world, not tooling
+    if (!e.url) return; // eval'd code
+    scripts.set(e.scriptId, { url: e.url, inline: e.url.split('#')[0] === pageUrl.split('#')[0], start: e.startLine });
+  });
+  await cdp.send('Debugger.enable');
+  await cdp.send('Profiler.enable');
+  await cdp.send('Profiler.startPreciseCoverage', { callCount: true, detailed: false });
+
+  return async function finish(outDir) {
+    const { result: coverage } = await cdp.send('Profiler.takePreciseCoverage');
+    await cdp.send('Profiler.stopPreciseCoverage').catch(() => {});
+    // listeners anywhere in the document, with the element they sit on
+    let listeners = [];
+    try {
+      const { result } = await cdp.send('Runtime.evaluate', { expression: 'document', objectGroup: 'tc' });
+      ({ listeners } = await cdp.send('DOMDebugger.getEventListeners', { objectId: result.objectId, depth: -1, pierce: true }));
+    } catch { /* no listeners readable */ }
+    const labels = new Map();
+    const labelOf = async (backendNodeId) => {
+      if (!backendNodeId) return 'window';
+      if (labels.has(backendNodeId)) return labels.get(backendNodeId);
+      let label = '?';
+      try {
+        const { node } = await cdp.send('DOM.describeNode', { backendNodeId });
+        const attrs = {};
+        for (let i = 0; i < (node.attributes || []).length; i += 2) attrs[node.attributes[i]] = node.attributes[i + 1];
+        label = node.nodeName === '#document' ? 'document' : `${node.localName}${attrs.id ? `#${attrs.id}` : ''}${attrs.class ? `.${attrs.class.trim().split(/\s+/).slice(0, 2).join('.')}` : ''}`;
+      } catch { /* detached */ }
+      labels.set(backendNodeId, label);
+      return label;
+    };
+
+    await fs.rm(outDir, { recursive: true, force: true });
+    await fs.mkdir(outDir, { recursive: true });
+    const beautify = require('js-beautify').js;
+    const files = new Map(); // scriptId -> record
+    let n = 0;
+    for (const [scriptId, s] of scripts) {
+      let source = '';
+      try { ({ scriptSource: source } = await cdp.send('Debugger.getScriptSource', { scriptId })); } catch { continue; }
+      if (!source || source.length < 40) continue;
+      const base = s.inline ? `inline-${++n}` : `${String(++n).padStart(2, '0')}-${(new URL(s.url).pathname.split('/').pop() || 'script').replace(/[^a-z0-9._-]/gi, '_').replace(/\.m?js$/i, '').slice(-60)}`;
+      const file = `${base}.js`;
+      await fs.writeFile(path.join(outDir, file), source);
+      // a readable copy when the code is minified (long lines); line numbers in INDEX.md refer to the original
+      const lines = source.split('\n');
+      const minified = source.length / Math.max(1, lines.length) > 200;
+      let pretty = null;
+      if (minified && source.length < 3_000_000) {
+        try { pretty = `${base}.pretty.js`; await fs.writeFile(path.join(outDir, pretty), beautify(source, { indent_size: 2, max_preserve_newlines: 1 })); } catch { pretty = null; }
+      }
+      const cov = coverage.find((c) => c.scriptId === scriptId);
+      const fns = cov?.functions || [];
+      const ran = fns.filter((f) => f.ranges?.[0]?.count > 0);
+      files.set(scriptId, { file, pretty, url: s.inline ? `${s.url} (inline)` : s.url, bytes: source.length, functions: fns.length, functionsRan: ran.length, ranNames: [...new Set(ran.map((f) => f.functionName).filter(Boolean))].slice(0, 14), tracking: TRACKING.test(s.url) && !s.inline, source, start: s.start });
+    }
+
+    // listeners grouped by handler location
+    const groups = new Map();
+    for (const l of listeners) {
+      const f = files.get(l.scriptId);
+      const key = `${l.type}|${l.scriptId}|${l.lineNumber}|${l.columnNumber}`;
+      if (!groups.has(key)) groups.set(key, { type: l.type, file: f?.file || null, url: f?.url || null, line: l.lineNumber + 1, column: l.columnNumber, elements: [] });
+      const g = groups.get(key);
+      if (g.elements.length < 6) g.elements.push(await labelOf(l.backendNodeId));
+      else g.more = (g.more || 0) + 1;
+    }
+    const excerpt = (f, line, col) => {
+      const text = f?.source.split('\n')[line - 1 - (f.inline ? 0 : 0)] || '';
+      return text.length > 160 ? text.slice(Math.max(0, col - 40), col + 140) : text.trim();
+    };
+    const ranked = [...files.values()].sort((a, b) => b.functionsRan - a.functionsRan);
+    const listenerRows = [...groups.values()].filter((g) => g.file && !files.get([...files.entries()].find(([, v]) => v.file === g.file)?.[0])?.tracking)
+      .sort((a, b) => (a.file || '').localeCompare(b.file || '') || a.line - b.line);
+    const md = [
+      `# The reference's scripts (evidence, never copied)`,
+      '',
+      `Saved as the page shipped them (\`NN-name.js\`) and, when minified, as a readable copy (\`.pretty.js\`). Ranked by how much of each ran while the page loaded and was scrolled through. Read the algorithm, then write your own code: a value a script computes from the screen size must be computed again, not copied.`,
+      '',
+      '| file | ran | functions | size | from | names that ran |',
+      '|---|---|---|---|---|---|',
+      ...ranked.map((f) => `| [${f.file}](${f.file})${f.pretty ? ` ([readable](${f.pretty}))` : ''} | ${f.functionsRan} | ${f.functions} | ${Math.round(f.bytes / 1024)} KB | ${f.tracking ? 'tracking (never copy)' : f.url.slice(0, 90)} | ${f.ranNames.join(', ')} |`),
+      '',
+      '## Event listeners, by handler',
+      '',
+      'Line and column refer to the original file. Elements that share one handler are listed together; a handler on `document` or `window` usually serves every matching element below it (delegation).',
+      '',
+      '| event | handler | on | code at the handler |',
+      '|---|---|---|---|',
+      ...listenerRows.map((g) => { const f = [...files.values()].find((x) => x.file === g.file); return `| ${g.type} | ${g.file}:${g.line}:${g.column} | ${g.elements.join(', ')}${g.more ? ` +${g.more}` : ''} | \`${excerpt(f, g.line, g.column).replace(/\|/g, '\\|').replace(/`/g, "'")}\` |`; }),
+      '',
+    ].join('\n');
+    await fs.writeFile(path.join(outDir, 'INDEX.md'), md);
+    await fs.writeFile(path.join(outDir, 'scripts.json'), JSON.stringify({ scripts: ranked.map(({ source, ...r }) => r), listeners: listenerRows }, null, 2));
+    await cdp.send('Debugger.disable').catch(() => {});
+    await cdp.detach().catch(() => {});
+    return { scripts: ranked.length, ran: ranked.filter((f) => f.functionsRan).length, listeners: listenerRows.length };
+  };
+}