@trueclone/cli 0.2.0 → 0.4.0-rc.1

package/scripts/curves.mjs

@@ -7,7 +7,7 @@
 //   { "name": "quote reveal", "ref": ".is-quote .reveal-line", "clone": ".is-quote .split-line",
 //     "props": ["ty"], "time": { "before": 0, "at": 700, "ms": 1400, "every": 100 } }
 //
-// selector@n picks the n-th match (default 0). Props: opacity, tx, ty, sx, sy, rot, top, left, width, height, saturate.
+// selector@n picks the n-th match (default 0); path:<recorded path> picks an element the reveals recorder saw. Props: opacity, tx, ty, sx, sy, rot, top, left, width, height, saturate.
 // Viewport-independent ranges: "scroll": { "of": { "ref": "...", "clone": "..." }, "start": "top bottom", "end": "bottom top", "steps": 10 }
 // resolve each side's own scroll positions, so one map scores desktop, tablet and mobile (--viewport tablet).
 // usage: node scripts/curves.mjs <name> [--viewport desktop] [--only "<name substring>"]
@@ -29,7 +29,7 @@ const vp = VIEWPORTS.find((v) => v.name === (flags.viewport || 'desktop'));
 
 // ---------- Draft a map from the motion inventory ----------
 if (flags.draft) {
-  const motion = JSON.parse(await fs.readFile(path.join(ref, `motion.${vp.name}.json`), 'utf8'));
+  const motion = JSON.parse(await fs.readFile(path.join(ref, `motion.${vp.name}.json`), 'utf8').catch(() => '{"triggers":[],"onScroll":[]}'));
   const propsFor = (vars) => {
     const out = new Set();
     for (const k of Object.keys(vars || {})) {
@@ -69,9 +69,27 @@ if (flags.draft) {
     const y = tw.firedAt[0];
     entries.push({ name: `reveal ${sel}`, ref: sel, clone: 'TODO', props: propsFor({ ...leaf.vars, ...(leaf.vars.startAt || {}) }), time: { before: Math.max(0, y - vp.height), at: y, ms: Math.ceil((tw.duration + 0.4) * 10) * 100, every: 100 } });
   }
+  // Scroll-linked curves the recorder sampled (any library, or none the inventory can read): one entry per element,
+  // over the scroll range it was seen moving at this size
+  const recorded = JSON.parse(await fs.readFile(path.join(ref, `reveals.${vp.name}.json`), 'utf8').catch(() => '{}')).scrubs || [];
+  let fromScrubs = 0;
+  for (const s of recorded) {
+    const samples = (s.samples || []).filter((x) => x && Number.isFinite(x.y));
+    if (samples.length < 2 || seen.has(`path:${s.path}`)) continue;
+    const moved = (k) => Math.max(...samples.map((x) => x[k] ?? 0)) - Math.min(...samples.map((x) => x[k] ?? 0));
+    const props = [];
+    if (moved('o') > 0.02) props.push('opacity');
+    if (moved('tx') > 1) props.push('tx');
+    if (moved('ty') > 1) props.push('ty');
+    if (moved('s') > 0.01) props.push('sx', 'sy');
+    if (!props.length) continue;
+    seen.add(`path:${s.path}`);
+    fromScrubs++;
+    entries.push({ name: `scrub ${s.cls || s.path}`, ref: `path:${s.path}`, clone: 'TODO', props, viewports: [vp.name], scroll: { from: samples[0].y, to: samples.at(-1).y, steps: Math.min(12, Math.max(4, samples.length - 1)) } });
+  }
   const out = path.join(root, 'motion-map.draft.json');
   await fs.writeFile(out, JSON.stringify(entries, null, 2));
-  console.log(`${entries.length} entries -> ${path.relative(process.cwd(), out)}. Fill in the clone selectors, then save as motion-map.json.`);
+  console.log(`${entries.length} entries (${fromScrubs} from recorded scroll curves) -> ${path.relative(process.cwd(), out)}. Fill in the clone selectors, then save as motion-map.json.`);
   process.exit(0);
 }
 
@@ -86,9 +104,28 @@ let map = JSON.parse(mapText);
 if (typeof flags.only === 'string') map = map.filter((e) => e.name.includes(flags.only));
 map = map.filter((e) => e.clone && e.clone !== 'TODO' && (!e.viewports || e.viewports.includes(vp.name)));
 
+// `path:section:3>div:2` is a recorded element path (from trueclone reveals: tag:position among the children that
+// are not script/style/meta, 1-based, from <body>); anything else is a CSS selector with an optional @n.
+// Installed on every page as window.__tcFind.
+function installFind() {
+  window.__tcFind = (selector) => {
+    if (selector.startsWith('path:')) {
+      const SKIP = new Set(['SCRIPT', 'NOSCRIPT', 'TEMPLATE', 'STYLE', 'LINK', 'META']);
+      let n = document.body;
+      for (const part of selector.slice(5).split('>')) {
+        const [tag, i] = part.split(':');
+        n = n && [...n.children].filter((c) => !SKIP.has(c.tagName))[Number(i) - 1];
+        if (!n || n.tagName.toLowerCase() !== tag) return null;
+      }
+      return n;
+    }
+    const [sel, idx] = selector.split('@');
+    return document.querySelectorAll(sel)[Number(idx || 0)] || null;
+  };
+}
+
 function sampleInPage([selector, props]) {
-  const [sel, idx] = selector.split('@');
-  const el = document.querySelectorAll(sel)[Number(idx || 0)];
+  const el = window.__tcFind(selector);
   if (!el) return null;
   const s = getComputedStyle(el);
   const m = new DOMMatrixReadOnly(s.transform === 'none' ? undefined : s.transform);
@@ -132,6 +169,7 @@ async function run(url, side, entries, onEntry) {
   };
   try {
     const { context, page } = await newPage(browser, vp, { reducedMotion: 'no-preference' });
+    await page.addInitScript(installFind);
     await page.goto(url, { waitUntil: 'load', timeout: 60000 });
     await page.mouse.move(5, vp.height - 5);
     await waitStill(page, { timeout: 15000, interval: 200 });
@@ -139,8 +177,7 @@ async function run(url, side, entries, onEntry) {
     // Scroll entries: resolve every range first (at the top, before anything is pinned), then visit all sample
     // positions of all curves in one downward pass, so the page glides short distances and never rewinds.
     const resolve = (of, spec) => page.evaluate(([sel, s]) => {
-      const [selector, idx] = sel.split('@');
-      const el = document.querySelectorAll(selector)[Number(idx || 0)];
+      const el = window.__tcFind(sel);
       if (!el) return 0;
       const r = el.getBoundingClientRect();
       const top = r.top + scrollY;

package/scripts/detail.mjs

@@ -155,7 +155,7 @@ async function sample(browser, url, vp, probes) {
       if (y >= max) break;
     }
     await context.close();
-    return { list, results };
+    return { list, results, pageHeight: max + vp.height };
   }
   const list = probes;
   const results = new Array(list.length);
@@ -177,14 +177,27 @@ 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']));
+    // reference probes are cached until the next capture (--refresh-ref to re-measure). The reference is read twice:
+    // a probe that does not agree with itself (random motion, a hover that lands by timing, a rotating word) can
+    // never be matched by any clone and is set aside as unstable instead of being handed over as a gap.
+    const ref = await cached(root, { tool: 'detail', vp: vpName, max: MAX, v: 9 }, async () => {
+      const first = await sample(browser, meta.url, vp, null);
+      // a live site changes: a reference read against today's page scores a clone of yesterday's capture against the
+      // wrong thing. The page height is a cheap tell; the fix is a new capture, not a new clone.
+      const captured = meta.viewports?.find((v) => v.viewport === vpName)?.pageHeight;
+      if (captured && first.pageHeight && Math.abs(first.pageHeight - captured) > Math.max(40, captured * 0.01)) console.warn(`WARNING reference drift (${vpName}): the live page is ${first.pageHeight}px tall, the capture was ${captured}px (${meta.capturedAt}); re-capture before trusting this score`);
+      const again = await sample(browser, meta.url, vp, first.list.map(({ x, xs, y, kind, w, h, scroll }) => ({ x, xs, y, kind, w, h, scroll })));
+      const unstable = first.list.map((p, i) => JSON.stringify(first.results[i]?.style) !== JSON.stringify(again.results[i]?.style) || first.results[i]?.sel !== again.results[i]?.sel);
+      return { ...first, unstable };
+    }, 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 = [];
+    const unstableList = [];
     let clean = 0, missing = 0;
     ref.list.forEach((p, i) => {
       const a = ref.results[i], b = cl.results[i];
       if (!a?.style) return;
+      if (ref.unstable?.[i]) { unstableList.push({ y: p.y, kind: p.kind, ref: a.sel }); 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') {
@@ -203,10 +216,10 @@ try {
       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 total = ref.list.filter((p, i) => ref.results[i]?.style && !ref.unstable?.[i]).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 });
+    report.viewports.push({ viewport: vpName, probes: total, clean, missing, unstable: unstableList.length, score: +(100 * clean / Math.max(1, total)).toFixed(1), byProp, issues, unstableProbes: unstableList });
   }
 } finally {
   if (!flags.cdp) await browser.close();
@@ -216,7 +229,7 @@ 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)}`);
+  console.log(`\n${v.viewport}: detail match ${v.score}% (${v.clean}/${v.probes} probes clean, ${v.missing} with no counterpart${v.unstable ? `; ${v.unstable} unstable on the reference itself, not scored: ${[...new Set(v.unstableProbes.map((u) => u.ref))].slice(0, 4).join(', ')}` : ''})  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); }

package/scripts/diff.mjs

@@ -3,7 +3,7 @@
 // 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';
+import { SCORED, parseArgs, openBrowser, newPage, settle, mask, serve, pad, crop, match, PNG } from './lib.mjs';
 
 const { pos, flags } = parseArgs(process.argv.slice(2));
 const [name] = pos;
@@ -25,7 +25,9 @@ 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) {
+  for (const vp of SCORED) {
+    // a capture made before held-out sizes existed has no reference for them: skipped, not failed
+    if (!(await fs.stat(path.join(ref, `${vp.name}${suffix}.png`)).then(() => true, () => false))) { console.log(`${vp.name}: no reference capture at ${vp.width}x${vp.height} (re-capture to score it)`); continue; }
     const { context, page } = await newPage(browser, vp);
     await page.goto(target, { waitUntil: 'load', timeout: 60000 });
     await settle(page);

package/scripts/drift.mjs

@@ -0,0 +1,55 @@
+// Has the live page changed since the capture? Layout and scroll states score against the captured screenshots, but
+// detail, hovers, motion curves, interactions and the load sequence measure the live page: when the site changed in
+// between, those checks compare the clone with something it was never a copy of. One page load per width: the page
+// height and the number of top-level sections against meta.json. Written to compare/drift.json; REPORT.md marks the
+// live-measured checks "stale capture" and the advice is to re-capture, not to touch the clone.
+// usage: node scripts/drift.mjs <name> [--viewport desktop|all]
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { SCORED as VIEWPORTS, parseArgs, openBrowser, newPage, settle, sectionsOf } from './lib.mjs';
+
+const { pos, flags } = parseArgs(process.argv.slice(2));
+const [name] = pos;
+if (!name) {
+  console.error('usage: trueclone drift <name> [--viewport desktop|all]');
+  process.exit(1);
+}
+const root = path.resolve('sites', name);
+const meta = JSON.parse(await fs.readFile(path.join(root, 'reference', 'meta.json'), 'utf8'));
+const vps = !flags.viewport || flags.viewport === 'all' ? VIEWPORTS : [VIEWPORTS.find((v) => v.name === flags.viewport)].filter(Boolean);
+
+const browser = await openBrowser(flags.cdp);
+const viewports = [];
+try {
+  for (const vp of vps) {
+    const captured = meta.viewports?.find((v) => v.viewport === vp.name);
+    if (!captured) continue;
+    const sample = async () => {
+      const { context, page } = await newPage(browser, vp);
+      try {
+        await page.goto(meta.url, { waitUntil: 'load', timeout: 60000 });
+        await settle(page, meta.hide || []);
+        return { h: await page.evaluate(() => document.documentElement.scrollHeight), n: (await sectionsOf(page)).length };
+      } finally {
+        await context.close();
+      }
+    };
+    // 1% (at least 40px) absorbs font hinting and a rotating line of text; a new section or a block that moved is above that
+    const differs = (s) => Math.abs(s.h - captured.pageHeight) > Math.max(40, captured.pageHeight * 0.01) || s.n !== captured.sections;
+    // a page that renders differently from one load to the next (a random block, a late embed) is not a changed site:
+    // a difference counts only when a second load shows it too
+    let s = await sample();
+    let confirmed = false;
+    if (differs(s)) { const again = await sample(); confirmed = differs(again); if (!confirmed) s = again; }
+    const stale = confirmed;
+    viewports.push({ viewport: vp.name, livePageHeight: s.h, capturedPageHeight: captured.pageHeight, liveSections: s.n, capturedSections: captured.sections, stale });
+    console.log(`${vp.name}: live ${s.h}px / ${s.n} sections, captured ${captured.pageHeight}px / ${captured.sections} sections${stale ? '  <- changed since the capture (seen on two loads)' : '  (same)'}`);
+  }
+} finally {
+  if (!flags.cdp) await browser.close();
+}
+const stale = viewports.some((v) => v.stale);
+await fs.mkdir(path.join(root, 'compare'), { recursive: true });
+await fs.writeFile(path.join(root, 'compare', 'drift.json'), JSON.stringify({ at: new Date().toISOString(), capturedAt: meta.capturedAt, stale, viewports }, null, 2));
+if (stale) console.warn(`WARNING reference drift: the live page has changed since the capture of ${meta.capturedAt}; detail, hovers, curves, interactions and load now measure a page the clone was never a copy of. Re-capture (trueclone capture, then states, reveals, seed --force) before trusting them.`);
+else console.log(`drift: none since ${meta.capturedAt}`);

package/scripts/explain.mjs

@@ -0,0 +1,87 @@
+// One look at one place on the page: what every check saw there, so a gap is read from the tool's own data instead of
+// re-measured by hand. Given a page y (or a section label) at one width, it prints the layout section's score, the
+// scroll states near it, the detail probes that differ, the hover rows that differ, and writes a side-by-side crop
+// (reference | clone | diff, masked) around that y.
+// usage: node scripts/explain.mjs <name> <y | "section label"> [--viewport desktop] [--range 800]
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { PNG, parseArgs, crop } from './lib.mjs';
+
+const { pos, flags } = parseArgs(process.argv.slice(2));
+const [name, where] = pos;
+if (!name || where === undefined) {
+  console.error('usage: trueclone explain <name> <y | "section label"> [--viewport desktop] [--range 800]');
+  process.exit(1);
+}
+const vp = flags.viewport || 'desktop';
+const range = Number(flags.range || 800);
+const root = path.resolve('sites', name);
+const read = async (rel) => fs.readFile(path.join(root, rel), 'utf8').then(JSON.parse).catch(() => null);
+
+const layout = await read('compare/report.mask.json');
+const lv = layout?.viewports.find((v) => v.viewport === vp);
+if (!lv) {
+  console.error(`no layout score for ${vp} yet: run trueclone score ${name} first`);
+  process.exit(1);
+}
+const section = /^\d+$/.test(where)
+  ? lv.sections.find((s) => Number(where) >= s.y && Number(where) < s.y + s.height) || null
+  : lv.sections.find((s) => String(s.label).toLowerCase().includes(where.toLowerCase())) || null;
+const y = /^\d+$/.test(where) ? Number(where) : section?.y;
+if (y === undefined) {
+  console.error(`no section labelled like "${where}" at ${vp}; sections: ${lv.sections.map((s) => `${s.y} ${String(s.label).slice(0, 24)}`).join(' | ')}`);
+  process.exit(1);
+}
+const lo = Math.max(0, y - range / 2), hi = y + range / 2;
+const within = (v) => v >= lo && v <= hi;
+
+console.log(`${name} @ ${vp} y ${y} (±${range / 2}px)`);
+console.log(`\nLayout: page ${lv.heightRef}px vs clone ${lv.heightClone}px (${lv.match}% overall)`);
+if (section) console.log(`  section "${String(section.label).slice(0, 60)}" y ${section.y} h ${section.height}: ${section.match}%`);
+for (const s of lv.sections.filter((s) => s !== section && (within(s.y) || within(s.y + s.height)))) console.log(`  nearby "${String(s.label).slice(0, 40)}" y ${s.y}: ${s.match}%`);
+
+const states = await read('compare/states/report.mask.json');
+const sv = states?.viewports?.find((v) => v.viewport === vp);
+const steps = (sv?.steps || sv?.states || []).filter((st) => within(st.scrollY ?? st.y ?? st.scroll ?? -1));
+if (steps.length) console.log(`\nScroll states scrolled to here: ${steps.map((st) => `${st.scrollY ?? st.y ?? st.scroll}px ${st.match ?? st.score}%`).join(', ')}`);
+
+const detail = await read('compare/detail.json');
+const dv = detail?.viewports?.find((v) => v.viewport === vp);
+if (dv) {
+  const here = dv.issues.filter((it) => within(it.y));
+  const unstable = (dv.unstableProbes || []).filter((it) => within(it.y));
+  console.log(`\nDetail: ${here.length} differing probe(s) here${unstable.length ? `, ${unstable.length} unstable on the reference (not scored)` : ''}`);
+  const groups = new Map();
+  for (const it of here) { 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, 12).forEach((g) => console.log(`  x${String(g.n).padEnd(3)} y${String(g.y).padEnd(6)} ${g.ref} -> ${g.clone}: ${g.props.join('; ')}`));
+}
+
+const hovers = await read(`compare/hovers.${vp}.json`);
+if (hovers) {
+  const rows = hovers.rows.filter((r) => within(r.y) && !['static', 'ok', 'unstable'].includes(r.status));
+  if (rows.length) { console.log(`\nHovers differing here:`); rows.slice(0, 10).forEach((r) => console.log(`  y${r.y} ${r.ref}: reference changes ${r.refChanges}, clone ${r.cloneChanges} (${r.status})`)); }
+}
+
+// the crop: reference | clone | diff, masked, half size
+try {
+  const imgs = await Promise.all([`reference/${vp}.mask.png`, `compare/${vp}.mask.clone.png`, `compare/${vp}.mask.diff.png`].map(async (f) => PNG.sync.read(await fs.readFile(path.join(root, f)))));
+  const top = Math.max(0, Math.round(lo)), h = Math.min(Math.round(hi) - top, Math.min(...imgs.map((i) => i.height)) - top);
+  const parts = imgs.map((img) => crop(img, top, h));
+  const scale = 0.5, w = Math.round(parts[0].width * scale), hh = Math.round(h * scale);
+  const out = new PNG({ width: w * 3 + 20, height: hh });
+  out.data.fill(255);
+  parts.forEach((p, k) => {
+    for (let yy = 0; yy < hh; yy++) for (let x = 0; x < w; x++) {
+      const sx = Math.min(p.width - 1, Math.round(x / scale)), sy = Math.min(p.height - 1, Math.round(yy / scale));
+      const si = (sy * p.width + sx) * 4, di = (yy * out.width + x + k * (w + 10)) * 4;
+      out.data[di] = p.data[si]; out.data[di + 1] = p.data[si + 1]; out.data[di + 2] = p.data[si + 2]; out.data[di + 3] = 255;
+    }
+  });
+  const file = path.join(root, 'compare', 'explain', `${vp}-${y}.png`);
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await fs.writeFile(file, PNG.sync.write(out));
+  console.log(`\nCrop (reference | clone | diff, y ${top}-${top + h}): ${path.relative(process.cwd(), file)}`);
+} catch (e) {
+  console.log(`\n(no crop: ${e.message.split('\n')[0]})`);
+}
+console.log(`\nNext: npx trueclone rules ${name} "<selector>" --viewport ${vp} (the reference's CSS) and --clone (the clone's), or npx trueclone score ${name} --only layout,detail --viewport ${vp} after a fix.`);

package/scripts/hovers.mjs

@@ -1,52 +1,86 @@
-// 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.
+// Hovers: does hovering do the same thing on the clone as on the reference? Every element a visitor can hover is
+// found two ways: interactive elements (links, buttons, anything with cursor:pointer) and every element that has a
+// mouse or pointer enter/over/move listener (read through the DevTools protocol, so a card that opens a panel from
+// script is found even without a pointer cursor). Each one is hovered on the reference; the same page point is
+// hovered on the clone. Two things are compared:
+// - which visual properties change on the element and its first descendants (colour, background, transform…);
+// - the outcome: the region around the element after the hover, as pixels, reference vs clone (text and media masked
+//   in template mode). A clone that opens a different panel, or opens nothing, fails even if "something changed".
 //
-// usage: node scripts/hovers.mjs <name> [--viewport desktop] [--url <clone url>] [--max 40]
+// usage: node scripts/hovers.mjs <name> [--viewport desktop] [--url <clone url>] [--max 60] [--refresh-ref]
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { VIEWPORTS, parseArgs, openBrowser, newPage, settle, serve, cached } from './lib.mjs';
+import { SCORED, parseArgs, openBrowser, newPage, settle, serve, cached, maskToggle, matchPct, PNG } 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>]');
+  console.error('usage: trueclone hovers <name> [--viewport desktop] [--url <clone url>] [--max 60]');
   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 vp = SCORED.find((v) => v.name === (flags.viewport || 'desktop'));
+const MAX = Number(flags.max || 60);
+const template = meta.mode !== 'exact';
+// the hovered region must match this well (exact mode renders the same text, so it can be stricter)
+const OUTCOME_MIN = template ? 95 : 97;
+const REACTS_BELOW = 99.5; // the region before vs after the hover: below this, the hover changed something visible
 const server = typeof flags.url === 'string' ? null : await serve(path.join(root, 'clone'));
 const cloneUrl = server ? server.url : flags.url;
 
+// Elements with a hover-type listener, marked data-lab-hover through CDP (one call for the whole document).
+async function markListened(page) {
+  const cdp = await page.context().newCDPSession(page);
+  try {
+    const { result } = await cdp.send('Runtime.evaluate', { expression: 'document', objectGroup: 'lab' });
+    const { listeners } = await cdp.send('DOMDebugger.getEventListeners', { objectId: result.objectId, depth: -1, pierce: false });
+    const HOVER = new Set(['mouseenter', 'mouseover', 'pointerenter', 'pointerover', 'mousemove', 'pointermove']);
+    const nodes = [...new Set(listeners.filter((l) => HOVER.has(l.type) && l.backendNodeId).map((l) => l.backendNodeId))];
+    let marked = 0;
+    for (const backendNodeId of nodes.slice(0, 400)) {
+      try {
+        const { object } = await cdp.send('DOM.resolveNode', { backendNodeId, objectGroup: 'lab' });
+        await cdp.send('Runtime.callFunctionOn', { objectId: object.objectId, functionDeclaration: 'function(){ if (this.setAttribute && this !== document.documentElement && this !== document.body) this.setAttribute("data-lab-hover", ""); }' });
+        marked++;
+      } catch { /* detached */ }
+    }
+    return marked;
+  } catch { return 0; } finally { await cdp.detach().catch(() => {}); }
+}
+
 function targets(max) {
   const seen = new Set();
   const out = [];
-  for (const el of document.querySelectorAll('a, button, [role="button"], *')) {
+  const sel = (el) => `${el.tagName.toLowerCase()}.${String(el.getAttribute('class') || '').split(/\s+/).slice(0, 2).join('.')}`;
+  const consider = (el, why) => {
     const s = getComputedStyle(el);
-    if (s.cursor !== 'pointer' && !['A', 'BUTTON'].includes(el.tagName)) continue;
-    if (s.display === 'none' || s.visibility === 'hidden') continue;
+    if (s.display === 'none' || s.visibility === 'hidden') return;
     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;
+    if (r.width < 10 || r.height < 10 || r.width > innerWidth * 0.95) return;
+    // one target per interactive root: never the same element twice (found by its listener and by its cursor), nor
+    // one inside or around an element already listed (the same region, counted twice)
+    if (seen.has(el)) return;
+    for (let p = el.parentElement; p; p = p.parentElement) if (seen.has(p)) return;
+    for (const s of seen) if (el.contains(s)) return;
     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('.')}` });
+    out.push({ x: Math.round(r.left + r.width / 2), y: Math.round(r.top + scrollY + r.height / 2), w: Math.round(r.width), h: Math.round(r.height), sel: sel(el), why });
+  };
+  // listened elements first: they are the ones a visual check at rest never sees
+  for (const el of document.querySelectorAll('[data-lab-hover]')) { if (out.length >= max) break; consider(el, 'listener'); }
+  for (const el of document.querySelectorAll('a, button, [role="button"], *')) {
     if (out.length >= max) break;
+    const s = getComputedStyle(el);
+    if (s.cursor !== 'pointer' && !['A', 'BUTTON'].includes(el.tagName)) continue;
+    consider(el, 'pointer');
   }
-  return out;
+  return out.sort((a, b) => a.y - b.y);
 }
 
-// Signature of the interactive root under a point and its first descendants.
+// Signature of the hover 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"]');
+  const control = el?.closest('[data-lab-hover], a, button, [role="button"]');
   if (control) el = control;
   else {
     let top = null;
@@ -58,7 +92,7 @@ function signature([px, vy]) {
   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 };
+    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, visibility: s.visibility };
   });
   return { sel: `${el.tagName.toLowerCase()}.${String(el.getAttribute('class') || '').split(/\s+/).slice(0, 2).join('.')}`, props };
 }
@@ -68,49 +102,116 @@ const changedKinds = (a, b) => {
   return [...kinds].sort();
 };
 
-async function hoverAll(browser, url, list) {
+// the region a hover can change: the element and half its size around it (a panel opening next to a card), in view
+const regionOf = (t, vy) => {
+  const x = Math.max(0, Math.round(t.x - t.w)), y = Math.max(0, Math.round(vy - t.h));
+  return { x, y, width: Math.min(vp.width - x, Math.round(t.w * 2)), height: Math.min(vp.height - y, Math.round(t.h * 2)) };
+};
+
+async function hoverAll(browser, url, list, shotDir) {
   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);
+  let listened = 0;
+  if (!list) { listened = await markListened(page); list = await page.evaluate(targets, MAX); }
+  else await markListened(page);
+  await fs.mkdir(shotDir, { recursive: true });
   const out = [];
-  for (const t of list) {
+  for (const [i, t] of list.entries()) {
     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 clip = regionOf(t, vy);
+    const ok = clip.width > 4 && clip.height > 4;
+    // the region shot until two shots in a row agree (a transition has ended), at most 1.5 s: as long as a slow
+    // hover needs, no longer than a quick one does. A region that is never still (a loop, a video) gets the fixed
+    // 0.9 s wait instead: stillness will not come.
+    let still = true;
+    const grab = async (file, min = 0, max = 1500) => { // min: a transition-delay must have passed before "still" means done
+      if (!ok) { await page.waitForTimeout(Math.max(300, min)); return null; }
+      if (template) await maskToggle(page, true);
+      let last = null, buf = null;
+      const t0 = Date.now();
+      try {
+        for (;;) {
+          await page.waitForTimeout(last ? 120 : 80);
+          buf = await page.screenshot({ clip });
+          // still = no visible change: a shimmering background or grain never repeats byte for byte
+          if (last && (buf.equals(last) || matchPct(PNG.sync.read(last), PNG.sync.read(buf)).pct >= 99.8) && Date.now() - t0 >= min) break;
+          if (Date.now() - t0 > max) { still = false; break; }
+          last = buf;
+        }
+      } catch { buf = null; }
+      if (template) await maskToggle(page, false);
+      if (!buf) return null;
+      const p = path.join(shotDir, file);
+      await fs.writeFile(p, buf);
+      return p;
+    };
+    const shotBefore = await grab(`${String(i).padStart(2, '0')}-before.png`, 0, 600);
     const before = await page.evaluate(signature, [t.x, vy]);
     await page.mouse.move(t.x, vy, { steps: 6 });
-    await page.waitForTimeout(800);
+    const shot = await grab(`${String(i).padStart(2, '0')}.png`, 450, still ? 1500 : 900);
     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) : [] });
+    // what the hover changed on screen: deep descendants, a panel next to the card, a class-driven state
+    const visible = shotBefore && shot ? matchPct(PNG.sync.read(await fs.readFile(shotBefore)), PNG.sync.read(await fs.readFile(shot))).pct : 100;
+    const kinds = before && after && before.sel === after.sel ? changedKinds(before, after) : [];
+    if (visible < REACTS_BELOW && !kinds.length) kinds.push('pixels');
+    out.push({ sel: before?.sel || null, kinds, shot, visible });
   }
+  const pageHeight = await page.evaluate(() => document.documentElement.scrollHeight).catch(() => null);
   await context.close();
-  return { list, out };
+  return { list, out, pageHeight, listened };
 }
 
 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);
+  // reference hovers are cached until the next capture (--refresh-ref to re-measure); read twice, so a hover effect
+  // that comes and goes by timing on the reference itself is set aside as unstable rather than demanded of the clone
+  ref = await cached(root, { tool: 'hovers', vp: vp.name, max: MAX, v: 8 }, async () => {
+    const dir = path.join(root, 'reference', 'cache', `hovers-${vp.name}`);
+    const first = await hoverAll(browser, meta.url, null, path.join(dir, 'a'));
+    const captured = meta.viewports?.find((v) => v.viewport === vp.name)?.pageHeight;
+    if (captured && first.pageHeight && Math.abs(first.pageHeight - captured) > Math.max(40, captured * 0.01)) console.warn(`WARNING reference drift (${vp.name}): the live page is ${first.pageHeight}px tall, the capture was ${captured}px (${meta.capturedAt}); re-capture before trusting this score`);
+    const again = await hoverAll(browser, meta.url, first.list, path.join(dir, 'b'));
+    const unstable = await Promise.all(first.out.map(async (a, i) => {
+      const b = again.out[i];
+      if (a.sel !== b?.sel || a.kinds.join() !== (b?.kinds || []).join()) return true;
+      if (a.shot && b?.shot) return matchPct(PNG.sync.read(await fs.readFile(a.shot)), PNG.sync.read(await fs.readFile(b.shot))).pct < 97;
+      return false;
+    }));
+    return { ...first, unstable };
+  }, Boolean(flags['refresh-ref']));
+  cl = await hoverAll(browser, cloneUrl, ref.list, path.join(root, 'compare', `hovers-${vp.name}`));
 } finally {
   if (!flags.cdp) await browser.close();
   server?.close();
 }
-const rows = ref.list.map((t, i) => {
+const rows = [];
+for (const [i, t] of ref.list.entries()) {
   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 outcome = a.shot && b.shot ? matchPct(PNG.sync.read(await fs.readFile(a.shot)), PNG.sync.read(await fs.readFile(b.shot))).pct : null;
+  const reacts = a.kinds.length > 0;
+  let status;
+  if (ref.unstable?.[i]) status = 'unstable';
+  else if (!reacts && !b.kinds.length) status = 'static';
+  else if (!reacts) status = outcome !== null && outcome < OUTCOME_MIN ? 'EXTRA' : 'static'; // the clone reacts where the reference doesn't
+  else if (!b.sel) status = 'no element';
+  else if (!b.kinds.length) status = 'MISSING';
+  else if (!a.kinds.some((k) => b.kinds.includes(k))) status = 'different';
+  else if (outcome !== null && outcome < OUTCOME_MIN) status = 'WRONG OUTCOME';
+  else status = 'ok';
+  rows.push({ y: t.y, found: t.why || 'pointer', ref: a.sel || t.sel, refChanges: a.kinds.join(',') || '-', clone: b.sel || '-', cloneChanges: b.kinds.join(',') || '-', outcome, status });
+}
+const scored = rows.filter((r) => r.status !== 'static' && r.status !== 'unstable');
+const unstable = rows.filter((r) => r.status === 'unstable').length;
+const ok = scored.filter((r) => r.status === 'ok').length;
+const report = { name, viewport: vp.name, at: new Date().toISOString(), score: +(100 * ok / Math.max(1, scored.length)).toFixed(1), unstable, listened: ref.listened ?? null, 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(`hover match (${vp.name}): ${report.score}% of ${scored.length} hover effects reproduced with the same outcome (${rows.length} elements probed, ${rows.filter((r) => r.found === 'listener').length} found by their mouse listeners${unstable ? `, ${unstable} unstable on the reference itself, not scored` : ''})`);
+console.table(rows.filter((r) => !['static', 'ok', 'unstable'].includes(r.status)).slice(0, 25));
 console.log(`-> ${path.relative(process.cwd(), out)}`);