@trueclone/cli 0.0.0-stage → 0.1.0

package/scripts/next.mjs

@@ -0,0 +1,316 @@
+// Next.js mode: turn a verified HTML clone into a Next.js (App Router) + Tailwind v4 + shadcn-ready project.
+//   sites/<name>/next/
+//     app/globals.css      the generated shadcn theme (from design-tokens.json) + the clone's tokens.css + site.css
+//     app/layout.tsx       fonts, metadata (noindex), early `js` class
+//     app/page.tsx         composes one component per section
+//     components/site/*    each section converted from the clone's HTML to JSX
+//     components/site/SiteMotion.tsx   client component: npm GSAP/ScrollTrigger/SplitText, Lenis, Swiper, three.js
+//     lib/site-script.js   the clone's motion/interaction script, unchanged logic, exported as initSite()
+//     components.json + lib/utils.ts   so `npx shadcn add <component>` works out of the box
+// The HTML clone stays the source of truth: regenerate after every change, then verify the build with the same
+// four scores (`npm run next -- <name> --verify`).
+//
+// usage: node scripts/next.mjs <name> [--install] [--build] [--verify [--quick]] [--port 3100]
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import net from 'node:net';
+import { parse } from 'parse5';
+import { fileURLToPath as toPath } from 'node:url';
+import { parseArgs } from './lib.mjs';
+
+const { pos, flags } = parseArgs(process.argv.slice(2));
+const [name] = pos;
+if (!name) {
+  console.error('usage: npm run next -- <name> [--install] [--build] [--verify] [--port 3100]');
+  process.exit(1);
+}
+const root = path.resolve('sites', name);
+const cloneDir = path.join(root, 'clone');
+const out = path.join(root, 'next');
+const port = Number(flags.port || 3100);
+
+// Versions: motion libraries pinned to what the verified HTML clone loads, so behaviour is identical.
+const PKG = {
+  name: `${name}-next`, private: true, version: '0.1.0',
+  scripts: { dev: 'next dev', build: 'next build', start: `next start -p ${port}` },
+  dependencies: {
+    next: '16.4.0', react: '19.3.0', 'react-dom': '19.3.0',
+    gsap: '3.13.0', lenis: '1.1.18', swiper: '11.2.6', three: '0.128.0',
+    clsx: '2.1.1', 'tailwind-merge': '3.7.0',
+  },
+  devDependencies: {
+    tailwindcss: '4.3.3', '@tailwindcss/postcss': '4.3.3', 'tw-animate-css': '1.4.0',
+    typescript: '5.9.3', '@types/react': '19.3.0', '@types/node': '22.18.0',
+  },
+};
+
+// ---------------- HTML -> JSX ----------------
+const VOID = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'source', 'track', 'wbr']);
+const RENAME = {
+  class: 'className', for: 'htmlFor', tabindex: 'tabIndex', readonly: 'readOnly', maxlength: 'maxLength', minlength: 'minLength',
+  crossorigin: 'crossOrigin', autoplay: 'autoPlay', playsinline: 'playsInline', srcset: 'srcSet', autocomplete: 'autoComplete',
+  enctype: 'encType', colspan: 'colSpan', rowspan: 'rowSpan', contenteditable: 'contentEditable', spellcheck: 'spellCheck',
+  novalidate: 'noValidate', allowfullscreen: 'allowFullScreen', frameborder: 'frameBorder', inputmode: 'inputMode', datetime: 'dateTime',
+};
+const BOOL = new Set(['muted', 'loop', 'playsinline', 'autoplay', 'controls', 'disabled', 'checked', 'required', 'hidden', 'novalidate', 'readonly', 'multiple', 'selected', 'allowfullscreen']);
+const camel = (s) => s.replace(/[-:]([a-z])/g, (m, c) => c.toUpperCase());
+const styleObject = (css) => {
+  const o = {};
+  for (const decl of css.split(';')) {
+    const i = decl.indexOf(':');
+    if (i < 0) continue;
+    const k = decl.slice(0, i).trim();
+    if (k) o[k.startsWith('--') ? k : camel(k)] = decl.slice(i + 1).trim();
+  }
+  return o;
+};
+const fixUrl = (v) => (v.startsWith('assets/') ? '/' + v : v);
+const attrString = (n, v) => (/["\\]/.test(v) ? `${n}={${JSON.stringify(v)}}` : `${n}="${v}"`);
+
+let usesStyle = false; // set while converting a component whose style objects need the CSSProperties type (custom properties like --i)
+function jsxAttrs(node, inSvg) {
+  const parts = [];
+  for (const a of node.attrs || []) {
+    if (/^on[a-z]+$/.test(a.name)) continue; // inline handlers are strings; the motion script owns behaviour
+    if (a.name === 'style') { usesStyle = true; parts.push(`style={${JSON.stringify(styleObject(a.value))} as CSSProperties}`); continue; }
+    if (BOOL.has(a.name) && (a.value === '' || a.value === a.name)) { parts.push(RENAME[a.name] || a.name); continue; }
+    let n = RENAME[a.name] || a.name;
+    if (!RENAME[a.name] && inSvg && !n.startsWith('data-') && !n.startsWith('aria-')) n = camel(n);
+    if (n === 'xmlns:xlink') continue;
+    const v = ['src', 'href', 'poster', 'srcSet'].includes(n) ? fixUrl(a.value) : a.value;
+    parts.push(attrString(n, v));
+  }
+  return parts.length ? ' ' + parts.join(' ') : '';
+}
+
+function toJsx(node, depth, inSvg = false) {
+  const pad = '  '.repeat(depth);
+  if (node.nodeName === '#comment') return '';
+  if (node.nodeName === '#text') {
+    if (!node.value.trim()) return node.value.includes('\n') ? '' : ' ';
+    const text = node.value.replace(/\s+/g, ' ');
+    return /[{}<>&"']/.test(text) ? `{${JSON.stringify(text)}}` : text;
+  }
+  if (['script', 'noscript', 'style'].includes(node.nodeName)) return '';
+  const tag = node.tagName;
+  const svg = inSvg || tag === 'svg';
+  const attrs = jsxAttrs(node, svg);
+  const kids = (node.childNodes || []).map((c) => toJsx(c, depth + 1, svg)).filter((s) => s !== '');
+  if (VOID.has(tag) || !kids.length) return `${pad}<${tag}${attrs} />`;
+  const inline = kids.every((k) => !k.startsWith('  ')) && kids.join('').length < 120;
+  if (inline) return `${pad}<${tag}${attrs}>${kids.map((k) => k.trim() || ' ').join('')}</${tag}>`;
+  return `${pad}<${tag}${attrs}>\n${kids.map((k) => (k.startsWith(' ') && k.trim() ? k : pad + '  ' + k.trim())).join('\n')}\n${pad}</${tag}>`;
+}
+
+const pascal = (s) => s.split(/[^a-z0-9]+/i).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join('');
+const els = (n) => (n.childNodes || []).filter((c) => c.tagName);
+const find = (n, tag) => els(n).find((c) => c.tagName === tag);
+
+// ---------------- Generate ----------------
+const html = await fs.readFile(path.join(cloneDir, 'index.html'), 'utf8');
+const doc = parse(html);
+const htmlEl = find(doc, 'html');
+const head = find(htmlEl, 'head');
+const body = find(htmlEl, 'body');
+const title = (els(head).find((e) => e.tagName === 'title')?.childNodes[0]?.value || name).trim();
+const fontLinks = els(head).filter((e) => e.tagName === 'link').map((e) => Object.fromEntries(e.attrs.map((a) => [a.name, a.value])))
+  .filter((l) => /fonts\.(googleapis|gstatic)\.com/.test(l.href || ''));
+
+await fs.rm(path.join(out, 'app'), { recursive: true, force: true });
+await fs.rm(path.join(out, 'components', 'site'), { recursive: true, force: true });
+for (const d of ['app', 'components/site', 'lib', 'styles', 'public']) await fs.mkdir(path.join(out, d), { recursive: true });
+
+// Sections: everything before <main> is "chrome" (nav, menu, intro, cursor); each child of <main> is a section.
+const mainEl = find(body, 'main');
+const chrome = els(body).filter((e) => e !== mainEl && e.tagName !== 'script');
+const sections = mainEl ? els(mainEl) : [];
+const used = new Set();
+const components = [];
+const writeComponent = async (compName, nodes, depth = 2) => {
+  usesStyle = false;
+  const jsx = nodes.map((n) => toJsx(n, depth)).filter(Boolean).join('\n');
+  const typeImport = usesStyle ? "import type { CSSProperties } from 'react';\n\n" : '';
+  const file = `// Generated from clone/index.html by scripts/next.mjs. Edit the HTML clone and regenerate.\n${typeImport}export default function ${compName}() {\n  return (\n    <>\n${jsx}\n    </>\n  );\n}\n`;
+  await fs.writeFile(path.join(out, 'components', 'site', `${compName}.tsx`), file);
+};
+await writeComponent('SiteChrome', chrome, 3);
+for (const s of sections) {
+  const id = s.attrs.find((a) => a.name === 'id')?.value;
+  const cls = (s.attrs.find((a) => a.name === 'class')?.value || s.tagName).split(/\s+/)[0];
+  let compName = pascal(id || cls) || 'Section';
+  if (/^\d/.test(compName)) compName = 'S' + compName;
+  while (used.has(compName)) compName += 'X';
+  used.add(compName);
+  components.push(compName);
+  await writeComponent(compName, [s], 3);
+}
+
+// Motion: the clone's script, wrapped as initSite(); libraries come from npm instead of CDN script tags.
+let script = await fs.readFile(path.join(cloneDir, 'script.js'), 'utf8');
+const startIdx = script.indexOf('(() => {');
+const endIdx = script.lastIndexOf('})();');
+if (startIdx < 0 || endIdx < 0) throw new Error('clone/script.js must be a single (() => { ... })(); IIFE');
+script = script.slice(0, startIdx) + 'export default function initSite() {' + script.slice(startIdx + '(() => {'.length, endIdx) + '}\n';
+script = script.replace(/(['"`])assets\//g, (m, q) => `${q}/assets/`);
+await fs.writeFile(path.join(out, 'lib', 'site-script.js'), `// Generated from clone/script.js by scripts/next.mjs. Edit the HTML clone and regenerate.\n${script}`);
+await fs.writeFile(path.join(out, 'components', 'site', 'SiteMotion.tsx'), `'use client';
+// Generated by scripts/next.mjs: loads the motion libraries from npm (same versions the HTML clone uses),
+// exposes them the way the clone's script expects, then runs it once after hydration.
+import { useEffect } from 'react';
+
+export default function SiteMotion() {
+  useEffect(() => {
+    const w = window as unknown as Record<string, unknown>;
+    if (w.__siteInit) return; // React strict mode runs effects twice in dev
+    w.__siteInit = true;
+    (async () => {
+      const [{ gsap }, { ScrollTrigger }, { SplitText }, lenis, swiper, three] = await Promise.all([
+        import('gsap'), import('gsap/ScrollTrigger'), import('gsap/SplitText'), import('lenis'), import('swiper/bundle'), import('three'),
+      ]);
+      Object.assign(w, { gsap, ScrollTrigger, SplitText, Lenis: lenis.default, Swiper: swiper.default, THREE: three });
+      const { default: initSite } = await import('@/lib/site-script.js');
+      initSite();
+    })();
+  }, []);
+  return null;
+}
+`);
+
+// Styles: shadcn theme first (Tailwind + tokens as utilities), then the clone's own tokens and stylesheet.
+const globals = await fs.readFile(path.join(root, 'globals.css'), 'utf8');
+const siteCss = (await fs.readFile(path.join(cloneDir, 'styles.css'), 'utf8')).replace(/@import url\(["']?tokens\.css["']?\);\s*/, '').replace(/url\((['"]?)assets\//g, (m, q) => `url(${q}/assets/`);
+await fs.writeFile(path.join(out, 'styles', 'site.css'), siteCss);
+await fs.copyFile(path.join(cloneDir, 'tokens.css'), path.join(out, 'styles', 'tokens.css'));
+// Library stylesheets the HTML loads from an npm CDN become package imports, placed BEFORE the site
+// stylesheet exactly like in the HTML <head>: same cascade order, same winners (e.g. .media-card vs .swiper-slide).
+const libCss = els(head).filter((e) => e.tagName === 'link').map((e) => Object.fromEntries(e.attrs.map((a) => [a.name, a.value])))
+  .filter((l) => l.rel === 'stylesheet' && /cdn\.jsdelivr\.net\/npm\/|unpkg\.com\//.test(l.href || ''))
+  .map((l) => {
+    const m = /\/npm\/((?:@[^/]+\/)?[^@/]+)@[^/]+\/(.+)$/.exec(l.href) || /unpkg\.com\/((?:@[^/]+\/)?[^@/]+)@[^/]+\/(.+)$/.exec(l.href);
+    if (!m) return null;
+    const [, pkgName, file] = m;
+    if (pkgName === 'swiper') return 'swiper/css/bundle'; // swiper's package exports expose its CSS under css/
+    return `${pkgName}/${file}`;
+  }).filter(Boolean);
+const importLines = libCss.map((p) => `@import "${p}";\n`).join('') + '@import "../styles/tokens.css";\n@import "../styles/site.css";\n';
+// Preflight parity: Tailwind's reset gives media elements display:block, vertical-align:middle and
+// (img/video) max-width:100% + height:auto. The HTML clone was verified without that reset, so restore the
+// browser defaults where they differ; the site stylesheet (unlayered) still wins wherever it sets a value.
+const parity = `
+/* Preflight parity (scripts/next.mjs): render media like the verified HTML clone */
+@layer base {
+  svg, video, canvas, audio, iframe, embed, object { display: revert; vertical-align: revert; }
+  video { max-width: revert; height: revert; }
+}
+`;
+const globalsOut = globals.includes('@import "tw-animate-css";')
+  ? globals.replace('@import "tw-animate-css";', () => '@import "tw-animate-css";\n' + importLines)
+  : importLines + globals;
+await fs.writeFile(path.join(out, 'app', 'globals.css'), globalsOut + parity);
+
+// App shell
+await fs.writeFile(path.join(out, 'app', 'layout.tsx'), `// Generated by scripts/next.mjs
+import type { Metadata } from 'next';
+import './globals.css';
+
+export const metadata: Metadata = {
+  title: ${JSON.stringify(title)},
+  robots: { index: false, follow: false },
+};
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        {/* the clone hides reveal targets and shows its intro only when JS runs: flag it before first paint */}
+        <script dangerouslySetInnerHTML={{ __html: "document.documentElement.classList.add('js')" }} />
+${fontLinks.map((l) => `        <link ${Object.entries(l).map(([k, v]) => (k === 'crossorigin' ? 'crossOrigin=""' : `${k}="${v}"`)).join(' ')} />`).join('\n')}
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+`);
+await fs.writeFile(path.join(out, 'app', 'page.tsx'), `// Generated by scripts/next.mjs: one component per section of the verified HTML clone.
+import SiteChrome from '@/components/site/SiteChrome';
+${components.map((c) => `import ${c} from '@/components/site/${c}';`).join('\n')}
+import SiteMotion from '@/components/site/SiteMotion';
+
+export default function Page() {
+  return (
+    <>
+      <SiteChrome />
+      <main>
+${components.map((c) => `        <${c} />`).join('\n')}
+      </main>
+      <SiteMotion />
+    </>
+  );
+}
+`);
+
+// Assets, design system docs, config
+await fs.rm(path.join(out, 'public', 'assets'), { recursive: true, force: true });
+await fs.cp(path.join(cloneDir, 'assets'), path.join(out, 'public', 'assets'), { recursive: true });
+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');
+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';
+
+const root = path.dirname(fileURLToPath(import.meta.url));
+// Pin the project root: the lab folder above has its own lockfile.
+export default { reactStrictMode: true, turbopack: { root }, outputFileTracingRoot: root };
+`);
+await fs.writeFile(path.join(out, 'tsconfig.json'), JSON.stringify({
+  compilerOptions: {
+    target: 'ES2017', lib: ['dom', 'dom.iterable', 'esnext'], allowJs: true, skipLibCheck: true, strict: false, noEmit: true,
+    esModuleInterop: true, module: 'esnext', moduleResolution: 'bundler', resolveJsonModule: true, isolatedModules: true,
+    jsx: 'react-jsx', incremental: true, plugins: [{ name: 'next' }], paths: { '@/*': ['./*'] },
+  },
+  include: ['next-env.d.ts', '**/*.ts', '**/*.tsx', '**/*.js', '.next/types/**/*.ts', '.next/dev/types/**/*.ts'],
+  exclude: ['node_modules'],
+}, null, 2) + '\n');
+await fs.writeFile(path.join(out, 'components.json'), JSON.stringify({
+  $schema: 'https://ui.shadcn.com/schema.json', style: 'new-york', rsc: true, tsx: true,
+  tailwind: { config: '', css: 'app/globals.css', baseColor: 'neutral', cssVariables: true, prefix: '' },
+  aliases: { components: '@/components', utils: '@/lib/utils', ui: '@/components/ui', lib: '@/lib', hooks: '@/hooks' },
+  iconLibrary: 'lucide',
+}, null, 2) + '\n');
+await fs.writeFile(path.join(out, 'lib', 'utils.ts'), "import { clsx, type ClassValue } from 'clsx';\nimport { twMerge } from 'tailwind-merge';\n\nexport function cn(...inputs: ClassValue[]) {\n  return twMerge(clsx(inputs));\n}\n");
+await fs.writeFile(path.join(out, '.gitignore'), 'node_modules/\n.next/\nnext-env.d.ts\n*.tsbuildinfo\n');
+console.log(`generated ${path.relative(process.cwd(), out)}: ${components.length} section components + SiteChrome + SiteMotion`);
+
+// ---------------- Install / build / verify ----------------
+const run = (cmd, args, opts = {}) => new Promise((resolve, reject) => {
+  const p = spawn(cmd, args, { cwd: out, stdio: 'inherit', shell: process.platform === 'win32', ...opts });
+  p.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`${cmd} ${args.join(' ')} exited ${code}`))));
+});
+if (flags.install || flags.build || flags.verify) await run('npm', ['install', '--no-audit', '--no-fund']);
+if (flags.build || flags.verify) await run('npx', ['next', 'build']);
+// A server left running on the port would keep serving the OLD build (or a half-deleted one after a rebuild)
+// and the scores would describe the wrong thing. Always verify on a port that is actually free.
+const freePort = async (start) => {
+  for (let p = start; p < start + 50; p++) {
+    const ok = await new Promise((resolve) => { const t = net.createServer().once('error', () => resolve(false)).once('listening', () => t.close(() => resolve(true))).listen(p, '127.0.0.1'); });
+    if (ok) return p;
+  }
+  throw new Error('no free port');
+};
+if (flags.verify) {
+  const verifyPort = await freePort(port);
+  if (verifyPort !== port) console.warn(`port ${port} is busy (another server?) - verifying on ${verifyPort}`);
+  const server = spawn('npx', ['next', 'start', '-p', String(verifyPort)], { cwd: out, shell: process.platform === 'win32', stdio: 'ignore' });
+  const url = `http://127.0.0.1:${verifyPort}/`;
+  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 });
+  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();
+  }
+}

package/scripts/report.mjs

@@ -0,0 +1,114 @@
+// REPORT.md for a clone: every score against its target, the weakest spots, and what was not (or cannot be)
+// copied. Reads the latest score files under sites/<name>/compare and the capture under sites/<name>/reference;
+// `trueclone score` writes it at the end of every run.
+//
+// usage: node scripts/report.mjs <name>
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { parseArgs } from './lib.mjs';
+
+const { pos } = parseArgs(process.argv.slice(2));
+const [name] = pos;
+if (!name) {
+  console.error('usage: trueclone report <name>');
+  process.exit(1);
+}
+const root = path.resolve('sites', name);
+const read = (rel) => fs.readFile(path.join(root, rel), 'utf8').then(JSON.parse, () => null);
+const meta = await read('reference/meta.json');
+if (!meta) {
+  console.error(`no capture for ${name}: run trueclone capture <url> ${name} first`);
+  process.exit(1);
+}
+
+// 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 };
+const mark = (ok) => (ok === null ? '–' : ok ? 'pass' : '**below target**');
+const pct = (v) => (v === undefined || v === null ? '–' : `${v}%`);
+const VPS = ['desktop', 'tablet', 'mobile'];
+
+const layout = await read('compare/report.mask.json');
+const visual = await read('compare/report.json');
+const states = await read('compare/states/report.mask.json');
+const curves = Object.fromEntries(await Promise.all(VPS.map(async (v) => [v, await read(`compare/curves.${v}.json`)])));
+const interact = await read('compare/interact/report.json');
+const hovers = await read('compare/hovers.desktop.json');
+const detail = await read('compare/detail.json');
+const motionInv = await read('reference/motion.desktop.json');
+
+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');
+const C = Object.fromEntries(VPS.map((v) => [v, curves[v]?.score]));
+
+const rows = [];
+const row = (check, values, ok, note = '') => rows.push(`| ${check} | ${VPS.map((v) => pct(values[v])).join(' | ')} | ${mark(ok)} | ${note} |`);
+const present = (vals) => VPS.filter((v) => vals[v] !== undefined && vals[v] !== null);
+const all = (vals, test) => (present(vals).length ? present(vals).every((v) => test(vals[v], v)) : null);
+row(`Layout (structure)`, L, all(L, (x) => x >= T.layout), `target ≥ ${T.layout}%; text and media masked`);
+if (meta.mode === 'exact') row('Layout (real pixels)', V, all(V, (x) => x >= T.layout), 'exact mode: same text and media');
+row('Scroll states', S, all(S, (x, v) => L[v] === undefined || x >= L[v] - T.statesGap), `within ${T.statesGap} points of layout`);
+row('Motion curves', C, all(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, all(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 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');
+
+const failing = rows.filter((r) => r.includes('below target')).length;
+const verdict = failing ? `${failing} check(s) below target` : 'every scored check meets its target';
+
+// Weakest spots, to fix first.
+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 v of detail?.viewports || []) {
+  const groups = new Map();
+  for (const it of v.issues || []) { const k = it.props[0].split(' ').slice(0, 1)[0]; groups.set(k, (groups.get(k) || 0) + 1); }
+  const top = [...groups].sort((a, b) => b[1] - a[1]).slice(0, 3);
+  if (top.length) weak.push(`- Detail ${v.viewport}: ${top.map(([k, n]) => `${n}× ${k === 'no' ? 'missing element' : k}`).join(', ')}`);
+}
+
+// What the clone does not copy: server-side behaviour, tracking, and the original's data/API calls.
+let calls = [];
+try {
+  const har = JSON.parse(await fs.readFile(path.join(root, 'reference', 'desktop.har'), 'utf8'));
+  calls = har.log.entries.filter((e) => ['xhr', 'fetch'].includes(e._resourceType)).map((e) => ({ method: e.request.method, url: e.request.url, status: e.response.status, type: e.response.content.mimeType || '' }));
+} catch { /* no HAR */ }
+const TRACKING = /google-analytics|googletagmanager|doubleclick|facebook\.(com|net)|hotjar|segment\.(io|com)|plausible|cloudflareinsights|clarity\.ms|sentry|datadog|mixpanel|amplitude|posthog|intercom|hubspot|linkedin\.com\/px|tiktok|challenges\.cloudflare|cdn-cgi\/rum|recaptcha|hcaptcha|turnstile/i;
+const tracking = calls.filter((c) => TRACKING.test(c.url));
+const data = calls.filter((c) => !TRACKING.test(c.url));
+const host = (u) => { try { return new URL(u).host; } catch { return u; } };
+const uniq = (list) => [...new Map(list.map((c) => [`${c.method} ${c.url.split('?')[0]}`, c])).values()];
+
+const libs = motionInv ? Object.entries(motionInv.libs || {}).filter(([, v]) => v).map(([k]) => k) : [];
+const md = `# trueclone report: ${name}
+
+| | |
+|---|---|
+| Reference | ${meta.url} |
+| Mode | ${meta.mode === 'exact' ? `exact (the site's own text and media). Permission: ${meta.permission}` : 'template (structure, motion and behaviour; placeholder text and media)'} |
+| Captured | ${meta.capturedAt} |
+| Scored | ${layout?.at || '–'}${layout?.clone && !/127\.0\.0\.1:\d+\/$/.test(layout.clone) ? ` against ${layout.clone}` : ''} |
+| Verdict | **${verdict}** |
+
+## Scores
+
+| Check | Desktop | Tablet | Mobile | Status | Notes |
+|---|---|---|---|---|---|
+${rows.join('\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'}
+## 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>).'}
+
+## Not copied
+
+- **Server-side behaviour** is never visible from the outside: databases, accounts, payments, search indexes. The clone reproduces the client.
+- **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);
+console.log(`${verdict} -> ${path.relative(process.cwd(), path.join(root, 'REPORT.md'))}`);

package/scripts/rules.mjs

@@ -0,0 +1,109 @@
+// CSS rules for one element, like the DevTools Styles pane: every rule that matches the element and its
+// ::before / ::after, in source order, with the @media / @supports / @layer it sits in and where it came from.
+// Build from the original's real CSS instead of approximating what the computed values look like
+// (e.g. a "capsize" ::before/::after text trim is not the same as text-box-trim inside flex and grid).
+// Cross-origin stylesheets (CDNs) are fetched outside the page and parsed, so they are included too.
+//
+// usage: node scripts/rules.mjs <name> "<selector>[@n]" [--viewport desktop] [--clone] [--url <page>]
+//        node scripts/rules.mjs <name> --text "Car number"     (the element whose own text starts with this)
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { VIEWPORTS, parseArgs, openBrowser, newPage, settle, serve, waitStill } from './lib.mjs';
+
+const { pos, flags } = parseArgs(process.argv.slice(2));
+const [name, target] = pos;
+if (!name || (!target && typeof flags.text !== 'string')) {
+  console.error('usage: npm run rules -- <name> "<selector>[@n]" [--viewport desktop] [--clone] | <name> --text "label"');
+  process.exit(1);
+}
+const root = path.resolve('sites', name);
+const meta = JSON.parse(await fs.readFile(path.join(root, 'reference', 'meta.json'), 'utf8'));
+const vp = VIEWPORTS.find((v) => v.name === (flags.viewport || 'desktop'));
+const server = flags.clone && typeof flags.url !== 'string' ? await serve(path.join(root, 'clone')) : null;
+const url = typeof flags.url === 'string' ? flags.url : server ? server.url : meta.url;
+
+const browser = await openBrowser(flags.cdp);
+try {
+  const { page } = await newPage(browser, vp, { reducedMotion: 'no-preference' });
+  await page.goto(url, { waitUntil: 'load', timeout: 60000 });
+  await waitStill(page, { timeout: 15000, interval: 200 });
+  await settle(page);
+
+  // Sheets the page cannot read (cross-origin without CORS): fetch them here, parse them in the page.
+  const blocked = await page.evaluate(() => [...document.styleSheets].map((s, i) => {
+    try { void s.cssRules; return null; } catch { return { i, href: s.href, media: s.media.mediaText }; }
+  }).filter(Boolean));
+  for (const b of blocked) {
+    const text = await page.context().request.get(b.href).then((r) => r.text()).catch(() => '');
+    await page.evaluate(([b, text]) => {
+      const sheet = new CSSStyleSheet({ media: b.media || undefined });
+      sheet.replaceSync(text.replace(/@import[^;]+;/g, ''));
+      (window.__labSheets ||= []).push({ i: b.i, href: b.href, sheet });
+    }, [b, text]);
+  }
+
+  const result = await page.evaluate(([target, text]) => {
+    let el;
+    if (text) {
+      el = [...document.body.querySelectorAll('*')].find((e) => [...e.childNodes].some((n) => n.nodeType === 3 && n.textContent.trim().startsWith(text)));
+    } else {
+      const [sel, idx] = target.split('@');
+      el = document.querySelectorAll(sel)[Number(idx || 0)];
+    }
+    if (!el) return null;
+    // split a selector list on top-level commas only (":is(a, b)" stays whole)
+    const split = (s) => { const out = []; let depth = 0, cur = ''; for (const ch of s) { if (ch === '(' || ch === '[') depth++; if (ch === ')' || ch === ']') depth--; if (ch === ',' && !depth) { out.push(cur.trim()); cur = ''; } else cur += ch; } if (cur.trim()) out.push(cur.trim()); return out; };
+    const PSEUDO = /::?(before|after)\b/;
+    const found = { element: [], before: [], after: [] };
+    const sheets = [...document.styleSheets].map((s, i) => {
+      if (s.ownerNode?.hasAttribute?.('data-lab-freeze')) return { rules: [], source: 'lab' }; // the lab's own freeze styles
+      const own = (() => { try { return s.cssRules; } catch { return null; } })();
+      const parsed = (window.__labSheets || []).find((x) => x.i === i);
+      return { rules: own || parsed?.sheet.cssRules || [], source: s.href ? s.href.split('/').pop().split('?')[0] : `inline <style> #${i}` };
+    });
+    const walk = (rules, source, ctx) => {
+      for (const r of rules) {
+        if (r instanceof CSSMediaRule) { if (matchMedia(r.conditionText).matches) walk(r.cssRules, source, [...ctx, `@media ${r.conditionText}`]); continue; }
+        if (r instanceof CSSSupportsRule) { if (CSS.supports(r.conditionText)) walk(r.cssRules, source, [...ctx, `@supports ${r.conditionText}`]); continue; }
+        if (window.CSSLayerBlockRule && r instanceof CSSLayerBlockRule) { walk(r.cssRules, source, [...ctx, `@layer ${r.name}`]); continue; }
+        if (!(r instanceof CSSStyleRule)) continue;
+        for (const part of split(r.selectorText)) {
+          const m = part.match(PSEUDO);
+          if (!m && /::?(marker|placeholder|selection|first-line|first-letter|-webkit-|-moz-)/.test(part)) continue; // other pseudo-elements
+          const base = part.replace(/::?(before|after|marker|placeholder|selection|first-line|first-letter)\b/g, '').trim() || '*';
+          let hit = false;
+          try { hit = el.matches(base); } catch { /* selector the engine does not support */ }
+          if (!hit) continue;
+          (found[m ? m[1] : 'element']).push({ selector: part, where: [source, ...ctx].join('  '), css: r.style.cssText });
+          break;
+        }
+      }
+    };
+    sheets.forEach((s) => walk(s.rules, s.source, []));
+    const inline = el.getAttribute('style');
+    if (inline) found.element.push({ selector: 'style=""', where: 'inline attribute', css: inline });
+    const pick = (s) => ({ display: s.display, size: `${s.width} x ${s.height}`, margin: s.margin, padding: s.padding, font: `${s.fontWeight} ${s.fontSize}/${s.lineHeight} ${s.fontFamily.split(',')[0]}`, color: s.color, background: s.backgroundColor, transform: s.transform, content: s.content });
+    const r = el.getBoundingClientRect();
+    return {
+      el: `${el.tagName.toLowerCase()}.${String(el.getAttribute('class') || '').split(/\s+/).join('.')}`,
+      box: `${Math.round(r.width)} x ${Math.round(r.height)} at page y ${Math.round(r.top + scrollY)}`,
+      computed: { element: pick(getComputedStyle(el)), before: pick(getComputedStyle(el, '::before')), after: pick(getComputedStyle(el, '::after')) },
+      found,
+    };
+  }, [target || null, typeof flags.text === 'string' ? flags.text : null]);
+
+  if (!result) { console.error(`nothing matched ${target || flags.text} on ${url}`); process.exitCode = 1; }
+  else {
+    console.log(`${result.el}  (${result.box})  on ${flags.clone ? 'the clone' : url}, ${vp.name}`);
+    for (const part of ['element', 'before', 'after']) {
+      const rules = result.found[part];
+      const c = result.computed[part];
+      if (part !== 'element' && !rules.length && c.content === 'none') continue;
+      console.log(`\n${part === 'element' ? 'element' : `::${part}`}  computed: ${Object.entries(c).filter(([k, v]) => v && v !== 'none' && v !== 'normal' && !(k === 'content' && part === 'element')).map(([k, v]) => `${k} ${v}`).join(' | ')}`);
+      for (const r of rules) console.log(`  ${r.selector}  { ${r.css} }\n      ${r.where}`);
+    }
+  }
+} finally {
+  if (!flags.cdp) await browser.close();
+  server?.close();
+}

package/scripts/score.mjs

@@ -0,0 +1,82 @@
+// One command for all scores, with a time limit per step and a summary at the end.
+//   --quick   layout (all viewports) + live states (desktop) + interactions: the fast loop while building
+//   (full)    layout + states (all) + motion curves (desktop/tablet/mobile) + interactions + hovers + detail
+//   --url <clone url>  score another build (e.g. the Next.js app); --refresh-ref re-measures the reference
+// A step that runs past its limit is killed and reported as TIMEOUT; the rest still run.
+// Steps run in three parallel groups (layout+states, the three curve viewports, interact+hovers+detail): each
+// tool mostly waits on smooth scroll and settling, so running them side by side costs little. --serial runs
+// one at a time (for debugging a flaky score).
+//
+// usage: node scripts/score.mjs <name> [--quick] [--url <clone url>] [--refresh-ref] [--step-minutes 20] [--serial]
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from './lib.mjs';
+
+// steps are the sibling scripts of this file, wherever the package is installed; sites/ is in the current folder
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+const { pos, flags } = parseArgs(process.argv.slice(2));
+const [name] = pos;
+if (!name) {
+  console.error('usage: npm run score -- <name> [--quick] [--url <clone url>] [--refresh-ref] [--serial]');
+  process.exit(1);
+}
+const url = typeof flags.url === 'string' ? flags.url : null;
+const refresh = flags['refresh-ref'] ? ['--refresh-ref'] : [];
+const limitMs = Number(flags['step-minutes'] || 20) * 60 * 1000;
+const withUrl = (args) => (url ? [...args, '--url', url] : args);
+
+const steps = [
+  { group: 1, label: 'layout', args: withUrl(['scripts/diff.mjs', name, '--structure']), pick: /│ \d+\s+│ '(\w+)'\s+│ ([\d.]+)/g, unit: 'layout %' },
+  { group: 1, label: 'states', args: ['scripts/states.mjs', name, '--clone', ...(url ? [url] : []), '--structure', ...(flags.quick ? ['--viewports', 'desktop'] : [])], pick: /│ \d+\s+│ '(\w+)'\s+│ ([\d.]+)/g, unit: 'states %' },
+  ...(flags.quick ? [] : ['desktop', 'tablet', 'mobile'].map((v) => ({ group: 2, label: `curves ${v}`, args: withUrl(['scripts/curves.mjs', name, '--viewport', v, ...refresh]), pick: /motion score \((\w+)\): ([\d.]+)%/g, unit: 'motion %' }))),
+  { group: 3, label: 'interact', args: withUrl(['scripts/interact.mjs', name, ...refresh]), pick: /│ \d+\s+│ '([^']+)'\s+│ ([\d.]+)/g, unit: 'interaction %', fail: /FAIL/g },
+  ...(flags.quick ? [] : [
+    { group: 3, label: 'hovers', args: withUrl(['scripts/hovers.mjs', name, ...refresh]), pick: /hover match \((\w+)\): ([\d.]+)%/g, unit: 'hover %' },
+    { group: 3, label: 'detail', args: withUrl(['scripts/detail.mjs', name, '--viewport', 'all', ...refresh]), pick: /(\w+): detail match ([\d.]+)%/g, unit: 'detail %' },
+  ]),
+];
+
+const runStep = (step) => new Promise((resolve) => {
+  const started = Date.now();
+  const [file, ...args] = step.args;
+  const child = spawn(process.execPath, [path.join(HERE, path.basename(file)), ...args], { cwd: process.cwd() });
+  let out = '';
+  child.stdout.on('data', (d) => { out += d; });
+  child.stderr.on('data', (d) => { out += d; });
+  const timer = setTimeout(() => {
+    out += '\nTIMEOUT';
+    if (process.platform === 'win32') spawn('taskkill', ['/pid', String(child.pid), '/T', '/F']);
+    else child.kill('SIGKILL');
+  }, limitMs);
+  child.on('close', (code) => { clearTimeout(timer); resolve({ code, out, ms: Date.now() - started }); });
+});
+
+const summary = [];
+const t0 = Date.now();
+const finish = (step, { code, out, ms }) => {
+  const values = [...out.matchAll(step.pick)].map((m) => `${m[1]} ${m[2]}`);
+  const fails = step.fail ? (out.match(step.fail) || []).length : 0;
+  const timedOut = out.includes('\nTIMEOUT');
+  const errors = (out.match(/PAGE ERROR[^\n]*/g) || []).slice(0, 2);
+  const warnings = (out.match(/WARNING[^\n]*/g) || []).slice(0, 2);
+  const status = timedOut ? 'TIMEOUT' : code !== 0 ? `EXIT ${code}` : fails ? `${fails} FAIL` : 'ok';
+  console.log(`  ${step.label.padEnd(16)} ${status} in ${(ms / 1000).toFixed(0)}s   ${values.join('  ')}`);
+  if (code !== 0 && !timedOut) console.log(out.split('\n').filter(Boolean).slice(-4).map((l) => `    ${l}`).join('\n'));
+  [...errors, ...warnings].forEach((l) => console.log(`    ${l}`));
+  summary.push({ step: step.label, status, seconds: Math.round(ms / 1000), [step.unit]: values.join('  ') || '-' });
+};
+const groups = flags.serial
+  ? steps.map((st) => [st])
+  : [...new Set(steps.map((st) => st.group))].map((g) => steps.filter((st) => st.group === g));
+for (const group of groups) {
+  console.log(`running: ${group.map((st) => st.label).join(', ')}`);
+  await Promise.all(group.map(async (step) => finish(step, await runStep(step))));
+}
+summary.sort((x, y) => steps.findIndex((st) => st.label === x.step) - steps.findIndex((st) => st.label === y.step));
+console.log(`\n${flags.quick ? 'quick' : 'full'} score for ${name}${url ? ` (${url})` : ''} in ${((Date.now() - t0) / 60000).toFixed(1)} min`);
+console.table(summary.map((s) => ({ step: s.step, status: s.status, 's': s.seconds, result: Object.entries(s).find(([k]) => k.endsWith('%'))?.[1] })));
+// REPORT.md: every score against its target, what to fix first, and what was not copied
+const report = await runStep({ args: ['report.mjs', name] });
+console.log(report.out.trim());