@trueclone/cli 0.0.0-stage → 0.1.0

package/scripts/detail.mjs

@@ -0,0 +1,225 @@
+// Detail diff: style-level comparison by page position, no mapping needed. Once the layout matches (diff ≥ 97%),
+// the element at a given page coordinate on the reference corresponds to the element at the same coordinate on
+// the clone. For every reference text element and every styled box (background, border, radius) this probes the
+// clone at the same point and compares computed styles: font family, size, weight, line height, letter spacing,
+// transform, colour, background, radius, padding. Only style values are compared, never content.
+//
+// usage: node scripts/detail.mjs <name> [--viewport desktop|tablet|mobile|all] [--url <clone url>] [--max 400]
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { VIEWPORTS, parseArgs, openBrowser, newPage, settle, serve, cached, waitStill } from './lib.mjs';
+
+const { pos, flags } = parseArgs(process.argv.slice(2));
+const [name] = pos;
+if (!name) {
+  console.error('usage: npm run detail -- <name> [--viewport desktop|all] [--url <clone url>]');
+  process.exit(1);
+}
+const root = path.resolve('sites', name);
+const meta = JSON.parse(await fs.readFile(path.join(root, 'reference', 'meta.json'), 'utf8'));
+const wanted = !flags.viewport || flags.viewport === 'all' ? VIEWPORTS.map((v) => v.name) : String(flags.viewport).split(',');
+const MAX = Number(flags.max || 400);
+const server = typeof flags.url === 'string' ? null : await serve(path.join(root, 'clone'));
+const cloneUrl = server ? server.url : flags.url;
+
+// Styles that define "detail". Colours are compared as rgba with alpha.
+function styleOf(el) {
+  const s = getComputedStyle(el);
+  return {
+    family: s.fontFamily.split(',')[0].replace(/["']/g, '').trim().toLowerCase(),
+    size: parseFloat(s.fontSize), weight: Number(s.fontWeight), lh: s.lineHeight === 'normal' ? parseFloat(s.fontSize) * 1.2 : parseFloat(s.lineHeight),
+    ls: s.letterSpacing === 'normal' ? 0 : parseFloat(s.letterSpacing), tt: s.textTransform,
+    color: s.color, bg: s.backgroundColor, radius: parseFloat(s.borderTopLeftRadius) || 0,
+    pad: [s.paddingTop, s.paddingRight, s.paddingBottom, s.paddingLeft].map(parseFloat),
+    opacity: Number(s.opacity),
+  };
+}
+
+// Reference probes: text elements and styled boxes in the current viewport, as page coordinates plus the scroll
+// position they were seen at. The clone is probed at that same scroll position, so sticky and pinned content
+// (which moves with the scroll) is compared where it actually sits on screen.
+function collectProbes(max) {
+  const own = (el) => [...el.childNodes].some((n) => n.nodeType === 3 && n.textContent.trim());
+  const out = [];
+  const scroll = Math.round(scrollY);
+  for (const el of document.body.querySelectorAll('*')) {
+    if (el.__labProbed) continue;
+    if (['SCRIPT', 'STYLE', 'NOSCRIPT', 'SVG', 'PATH', 'IMG', 'VIDEO', 'CANVAS', 'HTML', 'BODY', 'MAIN', 'SECTION', 'FOOTER', 'HEADER'].includes(el.tagName.toUpperCase())) continue;
+    const s = getComputedStyle(el);
+    if (s.display === 'none' || s.visibility === 'hidden' || +s.opacity === 0) continue;
+    // content of a closed <details> (and other content-visibility: hidden subtrees) still reports a box but is
+    // never painted: checkVisibility() is the browser's own answer
+    if (el.checkVisibility && !el.checkVisibility({ contentVisibilityAuto: true, visibilityProperty: true, opacityProperty: true })) continue;
+    const r = el.getBoundingClientRect();
+    const midY = r.top + r.height / 2;
+    if (r.width < 6 || r.height < 6 || midY < 0 || midY >= innerHeight) continue;
+    // Only what a visitor can actually see: not clipped away by an overflow ancestor, not inside a fixed
+    // overlay (menus, cursors), not under a hidden or fully transparent ancestor.
+    let hidden = false;
+    const cx = r.left + r.width / 2, cy = r.top + r.height / 2;
+    for (let p = el.parentElement; p && p !== document.body; p = p.parentElement) {
+      const ps = getComputedStyle(p);
+      if (ps.position === 'fixed' || ps.visibility === 'hidden' || +ps.opacity === 0) { hidden = true; break; }
+      if (ps.overflow !== 'visible' || ps.overflowX !== 'visible' || ps.overflowY !== 'visible') {
+        const pr = p.getBoundingClientRect();
+        if (cx < pr.left || cx > pr.right || cy < pr.top || cy > pr.bottom) { hidden = true; break; }
+      }
+    }
+    if (hidden) continue;
+    // Split text (one span per character or word, for hover/reveal animations): probe the container once,
+    // not every letter; otherwise one button label becomes 20 probes aimed at characters.
+    const sib = el.parentElement ? [...el.parentElement.children].filter((c) => c.tagName === el.tagName) : [];
+    if (own(el) && el.textContent.trim().length <= 2 && sib.length >= 3) {
+      const parent = el.parentElement;
+      if (!parent.__labSplit) {
+        parent.__labSplit = true;
+        const pr = parent.getBoundingClientRect();
+        out.push({ kind: 'text', x: Math.round(pr.left + pr.width / 2), xs: [pr.left + pr.width / 2, pr.left + Math.min(8, pr.width / 2), pr.right - Math.min(8, pr.width / 2)].map(Math.round), y: Math.round(pr.top + scrollY + Math.min(pr.height / 2, 12)), w: Math.round(pr.width), h: Math.round(pr.height), sel: `${parent.tagName.toLowerCase()}.${String(parent.getAttribute('class') || '').split(/\s+/).slice(0, 2).join('.')} (split)`, scroll, style: window.__styleOf(el) });
+      }
+      continue;
+    }
+    const text = own(el);
+    const alpha = (c) => { const m = c.match(/[\d.]+/g) || []; return m.length > 3 ? +m[3] : m.length ? 1 : 0; };
+    // a box only counts if it is visible: a background with some alpha, or a border
+    const box = !text && (alpha(s.backgroundColor) > 0.02 || parseFloat(s.borderTopWidth) > 0) && r.width < innerWidth * 0.95;
+    if (!text && !box) continue;
+    // The reference's style is read from the element itself; the clone is probed at three points for text
+    // (left, centre, right: covers left/right/centre-aligned text of different lengths), the centre for boxes.
+    const xs = text ? [r.left + r.width / 2, r.left + Math.min(8, r.width / 2), r.right - Math.min(8, r.width / 2)] : [r.left + r.width / 2];
+    out.push({ kind: text ? 'text' : 'box', x: Math.round(r.left + r.width / 2), xs: xs.map(Math.round), y: Math.round(r.top + scrollY + Math.min(r.height / 2, 12)), w: Math.round(r.width), h: Math.round(r.height), sel: `${el.tagName.toLowerCase()}.${String(el.getAttribute('class') || '').split(/\s+/).slice(0, 2).join('.')}`, scroll, style: window.__styleOf(el) });
+    el.__labProbed = true;
+    if (out.length >= max) break;
+  }
+  return out;
+}
+
+// At a page point, the element of the requested kind (deepest first).
+function probeAt([xs, py, kind, W, H]) {
+  const vy = py - scrollY;
+  if (vy < 0 || vy >= innerHeight) return { offscreen: true };
+  const own = (el) => [...el.childNodes].some((n) => n.nodeType === 3 && n.textContent.trim());
+  const styled = (e) => { const s = getComputedStyle(e); return s.backgroundColor !== 'rgba(0, 0, 0, 0)' || parseFloat(s.borderTopLeftRadius) > 0 || parseFloat(s.borderTopWidth) > 0; };
+  const gap = (e) => { const r = e.getBoundingClientRect(); return Math.abs(r.width - W) + Math.abs(r.height - H); };
+  let el = null, stack = [];
+  // text boxes are cap-trimmed (often ~10px tall), so allow a few px of vertical drift
+  const dys = kind === 'text' ? [0, -3, 3, -6, 6] : [0];
+  outer: for (const dy of dys) {
+    for (const px of xs) {
+      if (vy + dy < 0 || vy + dy >= innerHeight) continue;
+      stack = document.elementsFromPoint(px, vy + dy);
+      // boxes: of the styled elements under the point, the one closest in size to the reference element
+      el = kind === 'text' ? stack.find(own) : stack.filter((e) => !['HTML', 'BODY'].includes(e.tagName) && styled(e)).sort((a, b) => gap(a) - gap(b))[0];
+      if (!el && kind === 'text') {
+        // split text (a span per character, e.g. a typing prompt): the point can fall between characters, so take
+        // the split container under it and read the style of its first character
+        const split = stack.find((e) => e.children.length >= 3 && [...e.children].filter(own).length >= 3 && [...e.children].every((c) => c.textContent.trim().length <= 2));
+        if (split) el = [...split.children].find(own);
+      }
+      if (el) break outer;
+    }
+  }
+  if (!el) return { none: true, top: stack[0] ? `${stack[0].tagName.toLowerCase()}.${String(stack[0].getAttribute('class') || '').split(' ')[0]}` : null };
+  const r = el.getBoundingClientRect();
+  return { sel: `${el.tagName.toLowerCase()}.${String(el.getAttribute('class') || '').split(/\s+/).slice(0, 2).join('.')}`, w: Math.round(r.width), h: Math.round(r.height), style: window.__styleOf(el) };
+}
+
+async function sample(browser, url, vp, probes) {
+  // Motion on, as visitors see it: many originals ignore prefers-reduced-motion, while a clone that honours it
+  // shows a different (unpinned, unrevealed) layout. CSS transitions are frozen so states snap.
+  const { context, page } = await newPage(browser, vp, { reducedMotion: 'no-preference' });
+  await page.goto(url, { waitUntil: 'load', timeout: 60000 });
+  await page.mouse.move(5, vp.height - 5);
+  await waitStill(page, { timeout: 15000, interval: 200 }); // intros and loaders first
+  await settle(page);
+  // hit tests (elementsFromPoint) skip pointer-events:none layers, and text overlays often are
+  await page.addStyleTag({ content: '*{pointer-events:auto!important}' });
+  await page.evaluate(`window.__styleOf = ${styleOf.toString()}`);
+  const go = async (y) => {
+    await page.evaluate((yy) => window.scrollTo(0, yy), y);
+    await waitStill(page, { timeout: 3000 }); // scroll-triggered reveals and pins finish
+    return page.evaluate(() => Math.round(scrollY));
+  };
+  if (!probes) {
+    // reference: walk the page a viewport at a time (with overlap), collecting what is on screen
+    // Each point is then measured exactly as the clone will be (hit-tested at the same scroll), so both sides are
+    // read the same way: an inline <strong> under the point is the <strong> on both pages, a point between split
+    // characters misses on both, and an identical page scores 100% by construction.
+    const list = [];
+    const results = [];
+    const max = await page.evaluate(() => document.documentElement.scrollHeight - innerHeight);
+    for (let y = 0; list.length < MAX; y += vp.height - 80) {
+      await go(Math.min(y, max));
+      const found = await page.evaluate(collectProbes, MAX - list.length);
+      for (const p of found) results.push(await page.evaluate(probeAt, [p.xs || [p.x], p.y, p.kind, p.w, p.h]));
+      list.push(...found);
+      if (y >= max) break;
+    }
+    await context.close();
+    return { list, results };
+  }
+  const list = probes;
+  const results = new Array(list.length);
+  let at = null;
+  for (const [p, i] of list.map((q, k) => [q, k]).sort((x, y) => x[0].scroll - y[0].scroll)) {
+    if (at === null || Math.abs(at - p.scroll) > 1) at = await go(p.scroll);
+    results[i] = await page.evaluate(probeAt, [p.xs || [p.x], p.y, p.kind, p.w, p.h]);
+  }
+  await context.close();
+  return { list, results };
+}
+
+const near = (a, b, tol) => Math.abs(a - b) <= tol;
+const rgba = (c) => (c.match(/[\d.]+/g) || []).map(Number).concat([1]).slice(0, 4);
+const colorDist = (a, b) => { const x = rgba(a), y = rgba(b); return Math.abs(x[0] - y[0]) + Math.abs(x[1] - y[1]) + Math.abs(x[2] - y[2]) + Math.abs(x[3] - y[3]) * 255; };
+
+const browser = await openBrowser(flags.cdp);
+const report = { name, at: new Date().toISOString(), viewports: [] };
+try {
+  for (const vpName of wanted) {
+    const vp = VIEWPORTS.find((v) => v.name === vpName);
+    // reference probes are cached until the next capture (--refresh-ref to re-measure)
+    const ref = await cached(root, { tool: 'detail', vp: vpName, max: MAX, v: 8 }, () => sample(browser, meta.url, vp, null), Boolean(flags['refresh-ref']));
+    const cl = await sample(browser, cloneUrl, vp, ref.list.map(({ x, xs, y, kind, w, h, scroll }) => ({ x, xs, y, kind, w, h, scroll })));
+    const issues = [];
+    let clean = 0, missing = 0;
+    ref.list.forEach((p, i) => {
+      const a = ref.results[i], b = cl.results[i];
+      if (!a?.style) return;
+      if (!b?.style) { missing++; issues.push({ y: p.y, kind: p.kind, ref: a.sel, clone: b?.top || '(nothing)', props: [`no ${p.kind} element at this point on the clone`] }); return; }
+      const A = a.style, B = b.style, props = [];
+      if (p.kind === 'text') {
+        if (A.family !== B.family) props.push(`font ${A.family} vs ${B.family}`);
+        if (!near(A.size, B.size, 0.6)) props.push(`size ${A.size} vs ${B.size}px`);
+        if (A.weight !== B.weight) props.push(`weight ${A.weight} vs ${B.weight}`);
+        if (!near(A.lh, B.lh, 1)) props.push(`line-height ${A.lh.toFixed(1)} vs ${B.lh.toFixed(1)}px`);
+        if (!near(A.ls, B.ls, 0.2)) props.push(`letter-spacing ${A.ls} vs ${B.ls}px`);
+        if (A.tt !== B.tt) props.push(`transform ${A.tt} vs ${B.tt}`);
+        if (colorDist(A.color, B.color) > 24) props.push(`color ${A.color} vs ${B.color}`);
+      } else {
+        if (colorDist(A.bg, B.bg) > 24) props.push(`background ${A.bg} vs ${B.bg}`);
+        if (!near(A.radius, B.radius, 1)) props.push(`radius ${A.radius} vs ${B.radius}px`);
+        if (!near(a.w, b.w, 3) || !near(a.h, b.h, 3)) props.push(`size ${a.w}x${a.h} vs ${b.w}x${b.h}`);
+      }
+      if (props.length) issues.push({ y: p.y, kind: p.kind, ref: a.sel, clone: b.sel, props });
+      else clean++;
+    });
+    const total = ref.list.filter((p, i) => ref.results[i]?.style).length;
+    const byProp = {};
+    issues.forEach((it) => it.props.forEach((pr) => { const k = pr.split(' ')[0] === 'no' ? 'missing element' : pr.split(' ')[0]; byProp[k] = (byProp[k] || 0) + 1; }));
+    report.viewports.push({ viewport: vpName, probes: total, clean, missing, score: +(100 * clean / Math.max(1, total)).toFixed(1), byProp, issues });
+  }
+} finally {
+  if (!flags.cdp) await browser.close();
+  server?.close();
+}
+const out = path.join(root, 'compare', 'detail.json');
+await fs.mkdir(path.dirname(out), { recursive: true });
+await fs.writeFile(out, JSON.stringify(report, null, 2));
+for (const v of report.viewports) {
+  console.log(`\n${v.viewport}: detail match ${v.score}% (${v.clean}/${v.probes} probes clean, ${v.missing} with no counterpart)  by property: ${JSON.stringify(v.byProp)}`);
+  // group identical issues so one root cause prints once with a count
+  const groups = new Map();
+  for (const it of v.issues) { const k = `${it.ref} -> ${it.clone}: ${it.props.join('; ')}`; const g = groups.get(k) || { ...it, n: 0 }; g.n++; groups.set(k, g); }
+  [...groups.values()].sort((a, b) => b.n - a.n).slice(0, 18).forEach((g) => console.log(`  x${String(g.n).padEnd(3)} y${String(g.y).padEnd(6)} ${g.ref} -> ${g.clone}: ${g.props.join('; ')}`));
+}
+console.log(`-> ${path.relative(process.cwd(), out)}`);

package/scripts/diff.mjs

@@ -0,0 +1,72 @@
+// Render the clone exactly like the reference and score it: whole-page and per-section pixel match.
+// usage: node scripts/diff.mjs <name> [--structure] [--url http://localhost:5173/] [--cdp]
+// Without --url it serves sites/<name>/clone/ itself on a free local port.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { VIEWPORTS, parseArgs, openBrowser, newPage, settle, mask, serve, pad, crop, match, PNG } from './lib.mjs';
+
+const { pos, flags } = parseArgs(process.argv.slice(2));
+const [name] = pos;
+if (!name) {
+  console.error('usage: npm run diff -- <name> [--url <dev server url>]');
+  process.exit(1);
+}
+const root = path.resolve('sites', name);
+const ref = path.join(root, 'reference');
+const out = path.join(root, 'compare');
+const meta = JSON.parse(await fs.readFile(path.join(ref, 'meta.json'), 'utf8'));
+await fs.mkdir(out, { recursive: true });
+
+// --structure: compare layout only (text and media masked on both sides), for placeholder-content clones.
+const structure = Boolean(flags.structure);
+const suffix = structure ? '.mask' : '';
+const server = flags.url ? null : await serve(path.join(root, 'clone'));
+const target = typeof flags.url === 'string' ? flags.url : server.url;
+const browser = await openBrowser(flags.cdp);
+const report = { name, mode: structure ? 'structure' : 'visual', source: meta.url, clone: target, at: new Date().toISOString(), viewports: [] };
+try {
+  for (const vp of VIEWPORTS) {
+    const { context, page } = await newPage(browser, vp);
+    await page.goto(target, { waitUntil: 'load', timeout: 60000 });
+    await settle(page);
+    if (structure) await mask(page);
+    const clonePath = path.join(out, `${vp.name}${suffix}.clone.png`);
+    await page.screenshot({ path: clonePath, fullPage: true });
+    await context.close();
+
+    const a0 = PNG.sync.read(await fs.readFile(path.join(ref, `${vp.name}${suffix}.png`)));
+    const b0 = PNG.sync.read(await fs.readFile(clonePath));
+    const w = Math.max(a0.width, b0.width), h = Math.max(a0.height, b0.height);
+    const a = pad(a0, w, h), b = pad(b0, w, h);
+    const diff = new PNG({ width: w, height: h });
+    const bad = match(a, b, diff);
+    await fs.writeFile(path.join(out, `${vp.name}${suffix}.diff.png`), PNG.sync.write(diff));
+
+    const sections = JSON.parse(await fs.readFile(path.join(ref, `${vp.name}.sections.json`), 'utf8'));
+    const perSection = sections
+      // sections can start above the page (a skip link parked at y -80) or run past it: score the visible part
+      .filter((s) => s.height > 0 && s.y < h && s.y + s.height > 0)
+      .map((s) => {
+        const y0 = Math.max(0, s.y);
+        const sh = Math.min(s.y + s.height, h) - y0;
+        const miss = match(crop(a, y0, sh), crop(b, y0, sh));
+        return { index: s.index, label: s.heading || s.id || s.classes || s.tag, y: s.y, height: s.height, match: +(100 - (miss / (w * sh)) * 100).toFixed(2) };
+      });
+    report.viewports.push({
+      viewport: vp.name,
+      match: +(100 - (bad / (w * h)) * 100).toFixed(2),
+      heightRef: a0.height,
+      heightClone: b0.height,
+      worstSections: [...perSection].sort((x, y) => x.match - y.match).slice(0, 5),
+      sections: perSection,
+    });
+  }
+} finally {
+  if (!flags.cdp) await browser.close();
+  server?.close();
+}
+
+await fs.writeFile(path.join(out, `report${suffix}.json`), JSON.stringify(report, null, 2));
+console.log(`mode: ${report.mode}`);
+console.table(report.viewports.map((v) => ({ viewport: v.viewport, 'match %': v.match, 'ref h': v.heightRef, 'clone h': v.heightClone, worst: v.worstSections[0] ? `${v.worstSections[0].label} (${v.worstSections[0].match}%)` : '-' })));
+console.log(`Diff images + report: ${path.relative(process.cwd(), out)}`);

package/scripts/hovers.mjs

@@ -0,0 +1,116 @@
+// Hover inventory + comparison by position. Hovers every interactive element on the reference (links, buttons,
+// anything with cursor:pointer), records which visual properties change on it and its first descendants, then
+// hovers the same page point on the clone and checks it reacts the same way. Catches missing hover states,
+// which screenshots at rest never show.
+//
+// usage: node scripts/hovers.mjs <name> [--viewport desktop] [--url <clone url>] [--max 40]
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { VIEWPORTS, parseArgs, openBrowser, newPage, settle, serve, cached } from './lib.mjs';
+
+const { pos, flags } = parseArgs(process.argv.slice(2));
+const [name] = pos;
+if (!name) {
+  console.error('usage: npm run hovers -- <name> [--viewport desktop] [--url <clone url>]');
+  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 MAX = Number(flags.max || 40);
+const server = typeof flags.url === 'string' ? null : await serve(path.join(root, 'clone'));
+const cloneUrl = server ? server.url : flags.url;
+
+function targets(max) {
+  const seen = new Set();
+  const out = [];
+  for (const el of document.querySelectorAll('a, button, [role="button"], *')) {
+    const s = getComputedStyle(el);
+    if (s.cursor !== 'pointer' && !['A', 'BUTTON'].includes(el.tagName)) continue;
+    if (s.display === 'none' || s.visibility === 'hidden') continue;
+    const r = el.getBoundingClientRect();
+    if (r.width < 10 || r.height < 10 || r.width > innerWidth * 0.9) continue;
+    // one target per interactive root: skip descendants of an already listed element
+    let p = el.parentElement, nested = false;
+    while (p) { if (seen.has(p)) { nested = true; break; } p = p.parentElement; }
+    if (nested) continue;
+    seen.add(el);
+    out.push({ x: Math.round(r.left + r.width / 2), y: Math.round(r.top + scrollY + r.height / 2), sel: `${el.tagName.toLowerCase()}.${String(el.getAttribute('class') || '').split(/\s+/).slice(0, 2).join('.')}` });
+    if (out.length >= max) break;
+  }
+  return out;
+}
+
+// Signature of the interactive root under a point and its first descendants.
+function signature([px, vy]) {
+  let el = document.elementFromPoint(px, vy);
+  // cursor:pointer is inherited, so prefer the nearest real control (a/button/[role=button]); otherwise the
+  // outermost ancestor that still has a pointer cursor
+  const control = el?.closest('a, button, [role="button"]');
+  if (control) el = control;
+  else {
+    let top = null;
+    for (let n = el; n && n !== document.body; n = n.parentElement) if (getComputedStyle(n).cursor === 'pointer') top = n;
+    el = top;
+  }
+  if (!el) return null;
+  const nodes = [el, ...[...el.querySelectorAll('*')].slice(0, 12)];
+  const props = {};
+  nodes.forEach((n, i) => {
+    const s = getComputedStyle(n);
+    props[i] = { color: s.color, background: s.backgroundColor, transform: s.transform, opacity: s.opacity, shadow: s.boxShadow, decoration: s.textDecorationLine, border: s.borderColor, filter: s.filter, scale: s.scale };
+  });
+  return { sel: `${el.tagName.toLowerCase()}.${String(el.getAttribute('class') || '').split(/\s+/).slice(0, 2).join('.')}`, props };
+}
+const changedKinds = (a, b) => {
+  const kinds = new Set();
+  for (const i of Object.keys(a.props)) for (const k of Object.keys(a.props[i])) if (b.props[i] && a.props[i][k] !== b.props[i][k]) kinds.add(k === 'scale' ? 'transform' : k);
+  return [...kinds].sort();
+};
+
+async function hoverAll(browser, url, list) {
+  const { context, page } = await newPage(browser, vp, { reducedMotion: 'no-preference' });
+  await page.goto(url, { waitUntil: 'load', timeout: 60000 });
+  await settle(page);
+  if (!list) list = await page.evaluate(targets, MAX);
+  const out = [];
+  for (const t of list) {
+    const top = Math.max(0, t.y - Math.round(vp.height / 2));
+    await page.evaluate((y) => window.scrollTo(0, y), top);
+    await page.mouse.move(2, 2);
+    await page.waitForTimeout(400);
+    const vy = t.y - (await page.evaluate(() => scrollY));
+    const before = await page.evaluate(signature, [t.x, vy]);
+    await page.mouse.move(t.x, vy, { steps: 6 });
+    await page.waitForTimeout(800);
+    const after = await page.evaluate(signature, [t.x, vy]);
+    out.push({ sel: before?.sel || null, kinds: before && after && before.sel === after.sel ? changedKinds(before, after) : [] });
+  }
+  await context.close();
+  return { list, out };
+}
+
+const browser = await openBrowser(flags.cdp);
+let ref, cl;
+try {
+  // reference hovers are cached until the next capture (--refresh-ref to re-measure)
+  ref = await cached(root, { tool: 'hovers', vp: vp.name, max: MAX, v: 2 }, () => hoverAll(browser, meta.url, null), Boolean(flags['refresh-ref']));
+  cl = await hoverAll(browser, cloneUrl, ref.list);
+} finally {
+  if (!flags.cdp) await browser.close();
+  server?.close();
+}
+const rows = ref.list.map((t, i) => {
+  const a = ref.out[i], b = cl.out[i];
+  const status = !a.kinds.length ? (b.kinds.length ? 'extra' : 'static') : !b.sel ? 'no element' : !b.kinds.length ? 'MISSING' : a.kinds.some((k) => b.kinds.includes(k)) ? 'ok' : 'different';
+  return { y: t.y, ref: a.sel || t.sel, refChanges: a.kinds.join(',') || '-', clone: b.sel || '-', cloneChanges: b.kinds.join(',') || '-', status };
+});
+const withHover = rows.filter((r) => r.refChanges !== '-');
+const ok = withHover.filter((r) => r.status === 'ok').length;
+const report = { name, viewport: vp.name, at: new Date().toISOString(), score: +(100 * ok / Math.max(1, withHover.length)).toFixed(1), rows };
+const out = path.join(root, 'compare', `hovers.${vp.name}.json`);
+await fs.mkdir(path.dirname(out), { recursive: true });
+await fs.writeFile(out, JSON.stringify(report, null, 2));
+console.log(`hover match (${vp.name}): ${report.score}% of ${withHover.length} reference hover effects reproduced (${rows.length} interactive elements probed)`);
+console.table(rows.filter((r) => r.status !== 'static' && r.status !== 'ok').slice(0, 25));
+console.log(`-> ${path.relative(process.cwd(), out)}`);

package/scripts/interact.mjs

@@ -0,0 +1,184 @@
+// Interaction tests: run the same scripted scenario on the reference and the clone (hover, cursor paths,
+// drag, click, keys, waits), screenshot named moments, and compare them. Each scenario can also assert that
+// an element actually changed (moved, faded, resized, new text, state attribute or canvas pixels) on both sides, so "the button exists but does nothing"
+// fails even when screenshots happen to look alike.
+//
+// sites/<name>/interactions.json:
+// [{ "name": "media slider drags", "viewport": "desktop",
+//    "at": { "ref": "div.section_media", "clone": ".media", "offset": 0 },        // scroll this element to the top first
+//    "steps": [ { "drag": { "from": [0.7, 0.62], "to": [0.25, 0.62] } }, { "wait": 1500 }, { "shot": "after-drag" } ],
+//    "expectChange": { "ref": "div.swiper-wrapper", "clone": ".media-track" },
+//    "compare": "structure" }]                                                     // or "visual"
+// Step kinds: move [x,y] (fractions of the viewport), hover [x,y], path [[x,y],...], drag {from,to}, down/up [x,y],
+// click {ref,clone} selector or [x,y], key "Escape", wait ms, shot "label".
+// usage: node scripts/interact.mjs <name> [--only "<text>"]   |   node scripts/interact.mjs <name> --draft
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { VIEWPORTS, parseArgs, openBrowser, newPage, serve, warmUp, waitStill, wheelTo, maskToggle, matchPct, PNG, cached, readCache } from './lib.mjs';
+
+const { pos, flags } = parseArgs(process.argv.slice(2));
+const [name] = pos;
+if (!name) {
+  console.error('usage: npm run interact -- <name> [--only text] | --draft');
+  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'));
+
+// ---------- Draft scenarios from the motion inventory ----------
+if (flags.draft) {
+  const motion = JSON.parse(await fs.readFile(path.join(ref, 'motion.desktop.json'), 'utf8'));
+  const drafts = [];
+  for (const s of motion.swipers) {
+    drafts.push({ name: `slider drag ${s.el.sel}`, viewport: 'desktop', at: { ref: s.el.section || s.el.sel, clone: 'TODO', offset: 0 },
+      steps: [{ drag: { from: [0.7, 0.6], to: [0.25, 0.6] } }, { wait: 1500 }, { shot: 'after-drag' }], expectChange: { ref: `${s.el.sel} .swiper-wrapper`, clone: 'TODO' }, compare: 'structure' });
+  }
+  const pointerTargets = [...new Set(motion.pointer.map((p) => p.target.sel))];
+  for (const sel of pointerTargets) {
+    drafts.push({ name: `cursor follow ${sel}`, viewport: 'desktop', at: { ref: 'body', clone: 'body', offset: 0 },
+      steps: [{ move: [0.3, 0.4] }, { wait: 1500 }, { shot: 'left' }, { path: [[0.3, 0.4], [0.5, 0.5], [0.7, 0.6]] }, { wait: 1500 }, { shot: 'right' }], expectChange: { ref: sel, clone: 'TODO' }, compare: 'structure' });
+  }
+  drafts.push({ name: 'menu opens', viewport: 'desktop', at: { ref: 'body', clone: 'body', offset: 0 }, steps: [{ click: { ref: 'TODO', clone: 'TODO' } }, { wait: 1200 }, { shot: 'open' }, { key: 'Escape' }, { wait: 1200 }], compare: 'structure' });
+  const out = path.join(root, 'interactions.draft.json');
+  await fs.writeFile(out, JSON.stringify(drafts, null, 2));
+  console.log(`${drafts.length} scenarios -> ${path.relative(process.cwd(), out)}. Fill in the TODOs, then save as interactions.json.`);
+  process.exit(0);
+}
+
+const scenarioText = await fs.readFile(path.join(root, 'interactions.json'), 'utf8').catch(() => null);
+if (scenarioText === null) {
+  console.log('interactions: skipped, no interactions.json (run --draft, or write the scenarios by hand)');
+  process.exit(0);
+}
+let scenarios = JSON.parse(scenarioText);
+if (typeof flags.only === 'string') scenarios = scenarios.filter((s) => s.name.includes(flags.only));
+const outDir = path.join(root, 'compare', 'interact');
+await fs.mkdir(outDir, { recursive: true });
+
+const stateOf = (page, selector) => page.evaluate((sel) => {
+  const [s, idx] = sel.split('@');
+  const el = document.querySelectorAll(s)[Number(idx || 0)];
+  if (!el) return null;
+  const cs = getComputedStyle(el);
+  const r = el.getBoundingClientRect();
+  // Besides geometry and visibility: text, state attributes and canvas pixels, so a button that changes its label,
+  // a tab that flips aria-pressed or a game that redraws its canvas counts as a change too.
+  const attrs = ['class', 'aria-pressed', 'aria-current', 'aria-expanded', 'open', 'hidden', 'disabled']
+    .map((a) => (el.hasAttribute(a) ? `${a}=${el.getAttribute(a)}` : '')).join(',') // boolean attributes are "" + (el.value !== undefined ? `,${el.value}` : '');
+  const text = el.textContent.replace(/\s+/g, ' ').trim().slice(0, 200);
+  let pixels = '';
+  if (el.tagName === 'CANVAS') {
+    try { const d = el.toDataURL(); let h = 0; for (let i = 0; i < d.length; i += 7) h = (h * 31 + d.charCodeAt(i)) | 0; pixels = String(h); } catch { /* tainted canvas */ }
+  }
+  return `${Math.round(r.left)},${Math.round(r.top)},${Math.round(r.width)},${Math.round(r.height)}|${cs.transform}|${cs.opacity}|${cs.visibility}|${cs.clipPath}|${attrs}|${text}|${pixels}`;
+}, selector);
+
+async function runSide(url, side, list) {
+  if (!list.length) return [];
+  const browser = await openBrowser(flags.cdp);
+  const results = [];
+  try {
+    for (const sc of list) {
+      const vp = VIEWPORTS.find((v) => v.name === (sc.viewport || 'desktop'));
+      const { context, page } = await newPage(browser, vp, { reducedMotion: 'no-preference' });
+      await page.goto(url, { waitUntil: 'load', timeout: 60000 });
+      await page.mouse.move(5, vp.height - 5);
+      await waitStill(page, { timeout: 15000, interval: 200 });
+      await warmUp(page);
+      const atSel = sc.at?.[side];
+      if (atSel && atSel !== 'body') {
+        const y = await page.evaluate((s) => { const el = document.querySelector(s); return el ? el.getBoundingClientRect().top + scrollY : 0; }, atSel);
+        await wheelTo(page, Math.max(0, Math.round(y + (sc.at.offset || 0))), vp);
+      } else {
+        await wheelTo(page, sc.at?.offset || 0, vp);
+      }
+      await waitStill(page, { timeout: 3000 });
+      const px = ([x, y]) => [Math.round(x * vp.width), Math.round(y * vp.height)];
+      const expectSel = sc.expectChange?.[side];
+      const before = expectSel ? await stateOf(page, expectSel) : null;
+      const shots = {};
+      const states = [];
+      const shot = async (label) => {
+        if (expectSel) states.push(await stateOf(page, expectSel));
+        const file = path.join(outDir, `${sc.name.replace(/[^a-z0-9]+/gi, '-')}.${label}.${side}${sc.compare === 'structure' ? '.mask' : ''}.png`);
+        if (sc.compare === 'structure') await maskToggle(page, true);
+        await page.screenshot({ path: file });
+        if (sc.compare === 'structure') await maskToggle(page, false);
+        shots[label] = file;
+      };
+      await shot('before');
+      for (const st of sc.steps) {
+        if (st.move || st.hover) await page.mouse.move(...px(st.move || st.hover), { steps: 15 });
+        else if (st.path) for (const p of st.path) await page.mouse.move(...px(p), { steps: 20 });
+        else if (st.drag) {
+          await page.mouse.move(...px(st.drag.from), { steps: 5 });
+          await page.mouse.down();
+          await page.mouse.move(...px(st.drag.to), { steps: 25 });
+          await page.mouse.up();
+        } else if (st.down) { await page.mouse.move(...px(st.down)); await page.mouse.down(); }
+        else if (st.up) { await page.mouse.move(...px(st.up), { steps: 20 }); await page.mouse.up(); }
+        else if (st.click) {
+          const target = Array.isArray(st.click) ? st.click : st.click[side];
+          if (Array.isArray(target)) await page.mouse.click(...px(target));
+          else await page.click(target, { timeout: 5000 }).catch((e) => results.push({ name: sc.name, error: `click ${target}: ${e.message.split('\n')[0]}` }));
+        } else if (st.key) await page.keyboard.press(st.key);
+        else if (st.wait) await page.waitForTimeout(st.wait);
+        else if (st.shot) await shot(st.shot);
+      }
+      const after = expectSel ? await stateOf(page, expectSel) : null;
+      const changed = expectSel ? before !== null && [...states, after].some((s) => s !== null && s !== before) : null;
+      results.push({ name: sc.name, shots, changed, before, after });
+      await context.close();
+    }
+  } finally {
+    if (!flags.cdp) await browser.close();
+  }
+  return results;
+}
+
+// --url scores another build of the clone (e.g. the Next.js app) instead of serving clone/
+const server = typeof flags.url === 'string' ? null : await serve(path.join(root, 'clone'));
+const cloneUrl = server ? server.url : flags.url;
+// Reference results are cached per scenario (reference side + viewport + capture time) as long as the shot
+// files still exist; only new or edited scenarios touch the live site. --refresh-ref re-measures all.
+const refKey = (sc) => ({ tool: 'interact', name: sc.name, viewport: sc.viewport, at: sc.at, steps: sc.steps, expect: sc.expectChange?.ref, compare: sc.compare, click: JSON.stringify(sc.steps) });
+const refRes = [];
+const missing = [];
+for (const sc of scenarios) {
+  const hit = flags['refresh-ref'] ? null : await readCache(root, refKey(sc));
+  const filesOk = hit && (await Promise.all(Object.values(hit.shots || {}).map((f) => fs.access(f).then(() => true, () => false)))).every(Boolean);
+  if (hit && filesOk) refRes.push(hit); else missing.push(sc);
+}
+if (missing.length) console.log(`measuring ${missing.length} reference scenario(s) (${scenarios.length - missing.length} cached)`);
+for (const r of await runSide(meta.url, 'ref', missing)) {
+  refRes.push(r);
+  const sc = missing.find((m) => m.name === r.name);
+  if (sc && r.shots) await cached(root, refKey(sc), async () => r, true);
+}
+const cloneRes = await runSide(cloneUrl, 'clone', scenarios);
+server?.close();
+
+const report = { name, at: new Date().toISOString(), scenarios: [] };
+for (const sc of scenarios) {
+  const a = refRes.find((r) => r.name === sc.name && r.shots), b = cloneRes.find((r) => r.name === sc.name && r.shots);
+  const errors = [...refRes, ...cloneRes].filter((r) => r.name === sc.name && r.error).map((r) => r.error);
+  const shots = {};
+  for (const label of Object.keys(a?.shots || {})) {
+    if (!b?.shots[label]) continue;
+    shots[label] = matchPct(PNG.sync.read(await fs.readFile(a.shots[label])), PNG.sync.read(await fs.readFile(b.shots[label]))).pct;
+  }
+  const labels = Object.keys(shots).filter((l) => l !== 'before');
+  const score = labels.length ? +(labels.reduce((n, l) => n + shots[l], 0) / labels.length).toFixed(2) : null;
+  const expect = sc.expectChange ? { ref: a?.changed, clone: b?.changed, pass: a?.changed === true && b?.changed === true } : null;
+  report.scenarios.push({ name: sc.name, score, shots, expect, errors });
+}
+await fs.writeFile(path.join(outDir, 'report.json'), JSON.stringify(report, null, 2));
+console.table(report.scenarios.map((s) => ({
+  scenario: s.name,
+  'match %': s.score,
+  shots: Object.entries(s.shots).map(([k, v]) => `${k} ${v}`).join('  '),
+  'changes (ref/clone)': s.expect ? `${s.expect.ref ? 'yes' : 'NO'} / ${s.expect.clone ? 'yes' : 'NO'}${s.expect.pass ? '' : '  FAIL'}` : '-',
+  errors: s.errors.join('; ') || '',
+})));
+console.log(`-> ${path.relative(process.cwd(), path.join(outDir, 'report.json'))}`);