@trueclone/cli 0.0.0-stage → 0.2.0

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/reveals.mjs

@@ -0,0 +1,191 @@
+// Record one-shot scroll reveals on the reference, frame by frame, so the clone can replay them exactly.
+// A fresh page is scrolled down like a visitor would; every element that sat below the fold in a hidden or offset
+// state (opacity ~0, a translate, a scale, a blur) is watched with requestAnimationFrame, and when it starts to
+// change its opacity, translate, scale and blur are sampled every frame until they settle. The result is the
+// reveal's real curve (delay, duration, easing, stagger included), whatever library drew it: Framer Motion, GSAP,
+// AOS, IntersectionObserver plus CSS transitions. `trueclone seed` marks these elements in the clone and adds a
+// small player that replays the curves with the Web Animations API when they scroll into view.
+//
+// Elements are identified by their path of element children, skipping script/style/meta-like tags, which is
+// the same in the live page and in the script-free mirror the clone is seeded from.
+//
+// usage: node scripts/reveals.mjs <name> [--viewport desktop]   -> sites/<name>/reference/reveals.<vp>.json
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { VIEWPORTS, parseArgs, openBrowser, newPage, waitStill, wheelTo } from './lib.mjs';
+
+const { pos, flags } = parseArgs(process.argv.slice(2));
+const [name] = pos;
+if (!name) {
+  console.error('usage: trueclone reveals <name> [--viewport desktop]');
+  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'));
+
+// Runs in the page before any scroll: picks the candidates and starts the frame sampler.
+function watchInPage() {
+  const SKIP = new Set(['SCRIPT', 'NOSCRIPT', 'TEMPLATE', 'STYLE', 'LINK', 'META']);
+  const pathOf = (el) => {
+    const parts = [];
+    for (let n = el; n && n !== document.body; n = n.parentElement) {
+      const sibs = [...n.parentElement.children].filter((c) => !SKIP.has(c.tagName));
+      parts.unshift(`${n.tagName.toLowerCase()}:${sibs.indexOf(n) + 1}`);
+    }
+    return parts.join('>');
+  };
+  const read = (el) => {
+    const s = getComputedStyle(el);
+    const m = new DOMMatrixReadOnly(s.transform === 'none' ? undefined : s.transform);
+    const blur = /blur\(([\d.]+)px\)/.exec(s.filter);
+    return { o: +(+s.opacity).toFixed(3), tx: +m.m41.toFixed(2), ty: +m.m42.toFixed(2), s: +Math.hypot(m.m11, m.m12).toFixed(4), blur: blur ? +blur[1] : 0 };
+  };
+  const hiddenish = (st) => st.o <= 0.05 || Math.hypot(st.tx, st.ty) >= 8 || Math.abs(st.s - 1) >= 0.04 || st.blur > 0;
+  const candidates = [];
+  for (const el of document.body.querySelectorAll('*')) {
+    if (SKIP.has(el.tagName) || el.closest('svg') && el.tagName !== 'svg') continue;
+    const r = el.getBoundingClientRect();
+    if (r.top < innerHeight || r.width < 8 || r.height < 8) continue;
+    const st = read(el);
+    if (!hiddenish(st)) continue;
+    // continuous motion (marquees, loops) is not a reveal: skip anything running an endless animation
+    const endless = (e) => e.getAnimations().some((a) => a.effect?.getTiming().iterations === Infinity);
+    if (endless(el) || (el.parentElement && endless(el.parentElement))) continue;
+    // keep the outermost element of a revealing group (a hidden card hides its children too)
+    if (candidates.some((c) => c.el.contains(el))) continue;
+    candidates.push({ el, path: pathOf(el), from: st, frames: null, start: null, topAtStart: null, last: JSON.stringify(st), still: 0, done: false });
+  }
+  window.__tcReveals = candidates;
+  const tick = (now) => {
+    for (const c of candidates) {
+      if (c.done) continue;
+      const st = read(c.el);
+      const key = JSON.stringify(st);
+      if (c.frames === null) {
+        if (key !== c.last) {
+          c.frames = [{ t: 0, ...c.from }, { t: 16, ...st }];
+          c.start = now - 16;
+          const r = c.el.getBoundingClientRect();
+          c.topAtStart = +(r.top / innerHeight).toFixed(3);
+          c.last = key;
+        }
+        continue;
+      }
+      c.frames.push({ t: Math.round(now - c.start), ...st });
+      c.still = key === c.last ? c.still + 1 : 0;
+      c.last = key;
+      if (c.still >= 8 || now - c.start > 6000) {
+        c.frames = c.frames.slice(0, c.frames.length - c.still + 1); // drop the trailing identical frames
+        c.done = true;
+      }
+    }
+    if (candidates.some((c) => !c.done)) requestAnimationFrame(tick);
+  };
+  requestAnimationFrame(tick);
+  return candidates.length;
+}
+
+// Records the first class change of each element while the page scrolls, with where it happened.
+function watchClassesInPage() {
+  const SKIP = new Set(['SCRIPT', 'NOSCRIPT', 'TEMPLATE', 'STYLE', 'LINK', 'META']);
+  const pathOf = (el) => {
+    const parts = [];
+    for (let n = el; n && n !== document.body; n = n.parentElement) {
+      const sibs = [...n.parentElement.children].filter((c) => !SKIP.has(c.tagName));
+      parts.unshift(`${n.tagName.toLowerCase()}:${sibs.indexOf(n) + 1}`);
+    }
+    return parts.join('>');
+  };
+  const pinned = (el) => { for (let n = el; n && n !== document.body; n = n.parentElement) { const p = getComputedStyle(n).position; if (p === 'fixed' || p === 'sticky') return true; } return false; };
+  window.__tcClasses = [];
+  window.__tcClassIdle = true;
+  const idleChanged = new Set();
+  const seen = new Set();
+  new MutationObserver((records) => {
+    for (const r of records) {
+      const el = r.target;
+      if (!(el instanceof Element) || !el.isConnected || el === document.body || el === document.documentElement) continue;
+      if (window.__tcClassIdle) { idleChanged.add(el); continue; }
+      if (idleChanged.has(el) || seen.has(el)) continue;
+      const now = el.getAttribute('class');
+      if (now === r.oldValue) continue;
+      seen.add(el);
+      const rect = el.getBoundingClientRect();
+      window.__tcClasses.push({ el, path: pathOf(el), from: r.oldValue, to: now, scrollY: Math.round(scrollY), ratio: +(rect.top / innerHeight).toFixed(3), sticky: pinned(el) });
+    }
+  }).observe(document.body, { subtree: true, attributes: true, attributeFilter: ['class'], attributeOldValue: true });
+}
+
+const browser = await openBrowser(flags.cdp);
+let result;
+try {
+  const { page } = await newPage(browser, vp, { reducedMotion: 'no-preference' });
+  await page.goto(meta.url, { waitUntil: 'load', timeout: 60000 });
+  await page.mouse.move(5, vp.height - 5);
+  await waitStill(page, { timeout: 15000, interval: 200 });
+  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.
+  await page.evaluate(watchClassesInPage);
+  await page.waitForTimeout(1500);
+  await page.evaluate(() => { window.__tcClassIdle = false; });
+  // scroll down a third of a window at a time and give each reveal time to play
+  const max = await page.evaluate(() => document.documentElement.scrollHeight - innerHeight);
+  for (let y = 0; y <= max; y += Math.round(vp.height / 3)) {
+    await wheelTo(page, y, vp);
+    await page.waitForTimeout(450);
+  }
+  await page.waitForTimeout(2500);
+  // back to the top: does each class change revert (scroll state) or stay (one-shot)?
+  await page.evaluate(() => window.scrollTo(0, 0));
+  await page.waitForTimeout(1200);
+  // class order changes when a site removes and re-adds classes: compare the sets
+  // It reverts when the classes the scroll removed are back; classes added once (a one-time animation) may stay, so the
+  // state after returning ('back') is recorded too and used by the clone after the first scroll.
+  await page.evaluate(() => {
+    const toks = (v) => String(v || '').split(/\s+/).filter(Boolean);
+    for (const c of window.__tcClasses) {
+      c.back = c.el.getAttribute('class');
+      const removed = toks(c.from).filter((t) => !toks(c.to).includes(t));
+      c.reverts = removed.length ? removed.every((t) => toks(c.back).includes(t)) : !toks(c.back).some((t) => toks(c.to).includes(t) && !toks(c.from).includes(t));
+      c.marks = toks(c.to).filter((t) => !toks(c.back).includes(t)); // classes that only exist while scrolled
+    }
+  });
+  // sticky/fixed elements switch at a scroll position: find it precisely by bisection
+  const stickyCount = await page.evaluate(() => window.__tcClasses.filter((c) => c.sticky && c.reverts).length);
+  for (let i = 0; i < stickyCount; i++) {
+    let lo = 0, hi = await page.evaluate((k) => window.__tcClasses.filter((c) => c.sticky && c.reverts)[k].scrollY, i);
+    while (hi - lo > 2) {
+      const mid = Math.round((lo + hi) / 2);
+      await page.evaluate((y) => window.scrollTo(0, y), mid);
+      await page.waitForTimeout(160);
+      const on = await page.evaluate((k) => { const c = window.__tcClasses.filter((x) => x.sticky && x.reverts)[k]; const now = String(c.el.getAttribute('class') || '').split(/\s+/); return c.marks.length > 0 && c.marks.every((t) => now.includes(t)); }, i);
+      if (on) hi = mid; else lo = mid;
+    }
+    await page.evaluate(([k, y]) => { window.__tcClasses.filter((c) => c.sticky && c.reverts)[k].threshold = y; }, [i, hi]);
+  }
+  const classes = await page.evaluate(() => window.__tcClasses.map((c) => ({ path: c.path, from: c.from, to: c.to, back: c.back, sticky: c.sticky, reverts: c.reverts, ...(c.sticky ? { threshold: c.threshold ?? c.scrollY } : { trigger: c.ratio }) })));
+  // a reveal settles; anything still moving at the 6s cap is continuous motion driven some other way
+  result = await page.evaluate(() => window.__tcReveals.filter((c) => c.frames && c.frames.length > 2 && c.frames[c.frames.length - 1].t < 5900).map((c) => {
+    const last = c.frames[c.frames.length - 1];
+    // keep at most ~60 keyframes: enough for any easing, small enough for the clone
+    const step = Math.max(1, Math.ceil(c.frames.length / 60));
+    const frames = c.frames.filter((f, i) => i % step === 0 || i === c.frames.length - 1);
+    return { path: c.path, cls: String(c.el.getAttribute('class') || '').split(/\s+/).slice(0, 2).join('.'), from: c.from, to: { o: last.o, tx: last.tx, ty: last.ty, s: last.s, blur: last.blur }, trigger: c.topAtStart, duration: last.t, frames };
+  }));
+  console.log(`${count} candidates below the fold, ${result.length} revealed while scrolling`);
+  result.classes = classes;
+  console.log(`${classes.length} class change(s) caused by scrolling: ${classes.filter((c) => c.sticky).length} at a scroll position (sticky/fixed), ${classes.filter((c) => !c.sticky).length} when in view; ${classes.filter((c) => c.reverts).length} revert on the way back up`);
+} finally {
+  if (!flags.cdp) await browser.close();
+}
+const out = path.join(root, 'reference', `reveals.${vp.name}.json`);
+await fs.writeFile(out, JSON.stringify({ url: meta.url, viewport: vp, at: new Date().toISOString(), reveals: result, classes: result.classes }, null, 2));
+const groups = new Map();
+for (const r of result) {
+  const k = `${JSON.stringify(r.from)} -> ${Math.round(r.duration / 50) * 50}ms`;
+  groups.set(k, (groups.get(k) || 0) + 1);
+}
+for (const [k, n] of [...groups].sort((a, b) => b[1] - a[1]).slice(0, 8)) console.log(`  ${String(n).padStart(3)}x  from ${k}`);
+console.log(`-> ${path.relative(process.cwd(), out)}`);

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());