@trueclone/cli 0.3.0 → 0.4.0-rc.1

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,27 +102,67 @@ 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, pageHeight };
+  return { list, out, pageHeight, listened };
 }
 
 const browser = await openBrowser(flags.cdp);
@@ -96,30 +170,48 @@ let ref, cl;
 try {
   // 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: 3 }, async () => {
-    const first = await hoverAll(browser, meta.url, null);
+  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);
-    return { ...first, unstable: first.out.map((a, i) => a.sel !== again.out[i]?.sel || a.kinds.join() !== (again.out[i]?.kinds || []).join()) };
+    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);
+  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 = ref.unstable?.[i] ? 'unstable' : !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 !== '-' && r.status !== 'unstable');
+  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 = 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), unstable, rows };
+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${unstable ? `, ${unstable} unstable on the reference itself, not scored` : ''})`);
-console.table(rows.filter((r) => r.status !== 'static' && r.status !== 'ok' && r.status !== 'unstable').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)}`);

package/scripts/interact.mjs

@@ -11,6 +11,10 @@
 //    "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".
+// Points are [x, y] fractions of the viewport (0-1); move and hover also take an element: "selector@n" or { ref, clone }.
+// "selector@n" in at/click/expectChange picks the n-th match, counting from 0 (mind hidden duplicates: a mobile menu
+// button is often the first match). A scenario passes when the change happens on both sides and the shots after it
+// match the reference's (≥ 95).
 // 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';
@@ -19,7 +23,7 @@ import { VIEWPORTS, parseArgs, openBrowser, newPage, serve, warmUp, waitStill, w
 const { pos, flags } = parseArgs(process.argv.slice(2));
 const [name] = pos;
 if (!name) {
-  console.error('usage: npm run interact -- <name> [--only text] | --draft');
+  console.error('usage: trueclone interact <name> [--only "<scenario text>"] | trueclone interact <name> --draft   (scenario format: the comment at the top of scripts/interact.mjs, and SKILL.md)');
   process.exit(1);
 }
 const root = path.resolve('sites', name);
@@ -94,6 +98,14 @@ async function runSide(url, side, list) {
         await wheelTo(page, sc.at?.offset || 0, vp);
       }
       await waitStill(page, { timeout: 3000 });
+      // the first frame only once the screen itself has stopped changing (a slow intro fade outlasts the page-level
+      // wait, and a "before" caught halfway through it is compared against forever): two shots in a row the same
+      for (let t0 = Date.now(), last = null; Date.now() - t0 < 6000;) {
+        const buf = await page.screenshot();
+        if (last && (buf.equals(last) || matchPct(PNG.sync.read(last), PNG.sync.read(buf)).pct >= 99.8)) break;
+        last = buf;
+        await page.waitForTimeout(250);
+      }
       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;
@@ -109,7 +121,18 @@ async function runSide(url, side, list) {
       };
       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 });
+        if (st.move || st.hover) {
+          // a point [x, y], or an element to put the pointer on: "selector@n" or { ref, clone }
+          const t = st.move || st.hover;
+          const sel = Array.isArray(t) ? null : typeof t === 'string' ? t : t[side];
+          if (!sel) await page.mouse.move(...px(t), { steps: 15 });
+          else {
+            const [s, idx] = sel.split('@');
+            const box = await page.locator(s).nth(Number(idx || 0)).boundingBox().catch(() => null);
+            if (box) await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2, { steps: 15 });
+            else results.push({ name: sc.name, error: `hover ${sel}: no such element on the ${side === 'ref' ? 'reference' : 'clone'}` });
+          }
+        }
         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 });
@@ -146,7 +169,7 @@ const server = typeof flags.url === 'string' ? null : await serve(path.join(root
 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 refKey = (sc) => ({ tool: 'interact', v: 2, 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) {
@@ -164,6 +187,7 @@ const cloneRes = await runSide(cloneUrl, 'clone', scenarios);
 server?.close();
 
 const report = { name, at: new Date().toISOString(), scenarios: [] };
+const END_STATE_MIN = 95; // the shots after the action must match this well
 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);
@@ -174,7 +198,12 @@ for (const sc of scenarios) {
   }
   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;
+  // a scenario passes when the change happens on both sides AND the clone ends up where the reference does: a wrong
+  // panel opening is a change too
+  const endOk = score !== null && score >= END_STATE_MIN;
+  const expect = sc.expectChange
+    ? { ref: a?.changed, clone: b?.changed, endState: score, pass: a?.changed === true && b?.changed === true && endOk }
+    : { ref: null, clone: null, endState: score, pass: endOk };
   report.scenarios.push({ name: sc.name, score, shots, expect, errors });
 }
 await fs.writeFile(path.join(outDir, 'report.json'), JSON.stringify(report, null, 2));
@@ -182,7 +211,8 @@ 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'}` : '-',
+  'changes (ref/clone)': s.expect.ref === null ? '-' : `${s.expect.ref ? 'yes' : 'NO'} / ${s.expect.clone ? 'yes' : 'NO'}`,
+  'end state': `${s.score ?? '-'}${s.expect.pass ? '' : '  FAIL'}`,
   errors: s.errors.join('; ') || '',
 })));
 console.log(`-> ${path.relative(process.cwd(), path.join(outDir, 'report.json'))}`);

package/scripts/lib.mjs

@@ -3,6 +3,7 @@ import fs from 'node:fs/promises';
 import crypto from 'node:crypto';
 import { createReadStream } from 'node:fs';
 import http from 'node:http';
+import zlib from 'node:zlib';
 import path from 'node:path';
 import { chromium } from 'playwright';
 import { PNG } from 'pngjs';
@@ -10,11 +11,19 @@ import pixelmatch from 'pixelmatch';
 
 export { PNG };
 
+// The seed sizes: the clone is built from what the reference shows at these.
 export const VIEWPORTS = [
   { name: 'mobile', width: 390, height: 844 },
   { name: 'tablet', width: 768, height: 1024 },
   { name: 'desktop', width: 1440, height: 900 },
 ];
+// Held-out sizes: captured and scored, never read by anything that builds the clone. A clone that is right at the seed
+// sizes and wrong here is fitted to the sizes it was built from, not a copy of the site.
+export const HELD_OUT = [
+  { name: 'laptop', width: 1280, height: 720, heldOut: true },
+  { name: 'wide', width: 1920, height: 1080, heldOut: true },
+];
+export const SCORED = [...VIEWPORTS, ...HELD_OUT];
 
 // Jump every animation/transition to its end state so screenshots are deterministic.
 const FREEZE_CSS = `*,*::before,*::after{animation-duration:0s!important;animation-delay:0s!important;
@@ -133,19 +142,38 @@ canvas{background:#888!important;filter:contrast(0) brightness(1.066)!important}
 // would undo an inline override, so the mask is a stylesheet rule on a marker attribute, which inline styles lose
 // to), gradient text (background-clip: text paints the glyphs with its background, so a transparent colour still
 // shows the letters) and photo backgrounds on ::before/::after. `off` removes the markers.
+// A script that rebuilds or restyles media after the mask went on (a resize during a full-page shot rebuilds a grid)
+// would leave the new elements unmasked on one side only; an observer marks them as they appear, on both sides.
 function maskExtrasInPage(enable) {
   const marks = ['data-lab-bgi', 'data-lab-cliptext', 'data-lab-bgb', 'data-lab-bga'];
   if (!enable) {
+    window.__labMaskObserver?.disconnect();
+    window.__labMaskObserver = null;
     for (const m of marks) for (const el of document.querySelectorAll(`[${m}]`)) el.removeAttribute(m);
     return;
   }
-  for (const el of document.querySelectorAll('*')) {
+  const markOne = (el) => {
     const s = getComputedStyle(el);
     if (s.backgroundImage.includes('url(')) el.setAttribute('data-lab-bgi', '');
     if (s.backgroundClip === 'text' || s.webkitBackgroundClip === 'text') el.setAttribute('data-lab-cliptext', '');
     if (getComputedStyle(el, '::before').backgroundImage.includes('url(')) el.setAttribute('data-lab-bgb', '');
     if (getComputedStyle(el, '::after').backgroundImage.includes('url(')) el.setAttribute('data-lab-bga', '');
-  }
+  };
+  for (const el of document.querySelectorAll('*')) markOne(el);
+  window.__labMaskObserver?.disconnect();
+  window.__labMaskObserver = new MutationObserver((records) => {
+    for (const r of records) {
+      if (r.type === 'attributes') {
+        if (!(r.target instanceof Element) || marks.includes(r.attributeName)) continue;
+        markOne(r.target);
+        // a custom property or url() set on an ancestor (--hero-img) reaches its descendants' backgrounds
+        if (/url\(|--/.test(r.target.getAttribute('style') || '')) for (const el of r.target.querySelectorAll('*')) markOne(el);
+        continue;
+      }
+      for (const n of r.addedNodes) if (n instanceof Element) { markOne(n); for (const el of n.querySelectorAll('*')) markOne(el); }
+    }
+  });
+  window.__labMaskObserver.observe(document.documentElement, { subtree: true, childList: true, attributes: true, attributeFilter: ['style', 'class'] });
 }
 
 export async function mask(page) {
@@ -226,17 +254,29 @@ const MIME = {
 };
 
 // Port 0 = a free port picked by the OS, so several scoring tools can run side by side; use server.url.
+// Serves a clone the way a host would: text compressed (brotli or gzip, as the browser asks), so the load check
+// compares the clone with a CDN-served original on equal terms.
+const COMPRESSIBLE = /\.(html?|css|m?js|json|svg|txt|xml|map)$/i;
 export function serve(dir, port = 0) {
+  dir = path.resolve(dir); // forward or back slashes, relative or not: one form, so the containment check holds
   return new Promise((resolve) => {
     const server = http.createServer(async (req, res) => {
       let p = decodeURIComponent(new URL(req.url, 'http://x').pathname);
       if (p.endsWith('/')) p += 'index.html';
       const file = path.join(dir, p);
-      if (!file.startsWith(dir)) { res.writeHead(403).end(); return; }
+      if (file !== dir && !file.startsWith(dir + path.sep)) { res.writeHead(403).end(); return; }
       try {
         await fs.access(file);
-        res.writeHead(200, { 'content-type': MIME[path.extname(file).toLowerCase()] || 'application/octet-stream' });
-        createReadStream(file).pipe(res);
+        const headers = { 'content-type': MIME[path.extname(file).toLowerCase()] || 'application/octet-stream' };
+        const accept = String(req.headers['accept-encoding'] || '');
+        const enc = COMPRESSIBLE.test(file) ? (/\bbr\b/.test(accept) ? 'br' : /\bgzip\b/.test(accept) ? 'gzip' : null) : null;
+        if (enc) {
+          res.writeHead(200, { ...headers, 'content-encoding': enc, vary: 'accept-encoding' });
+          createReadStream(file).pipe(enc === 'br' ? zlib.createBrotliCompress({ params: { [zlib.constants.BROTLI_PARAM_QUALITY]: 5 } }) : zlib.createGzip({ level: 6 })).pipe(res);
+        } else {
+          res.writeHead(200, headers);
+          createReadStream(file).pipe(res);
+        }
       } catch { res.writeHead(404).end(); }
     });
     server.listen(port, '127.0.0.1', () => { server.url = `http://127.0.0.1:${server.address().port}/`; resolve(server); });
@@ -261,6 +301,30 @@ export function crop(png, y, h) {
 
 export const match = (a, b, diff) => pixelmatch(a.data, b.data, diff ? diff.data : null, a.width, a.height, { threshold: 0.1, includeAA: false });
 
+// How alike two canvas regions look, 0-100: what a scene draws rarely matches pixel for pixel (time, physics, random
+// seeds), so it is compared by what is drawn rather than where: the colour distribution (64 bins) and how much of the
+// region is covered by drawing at all (pixels away from the region's dominant colour). An empty or wrong canvas scores
+// low; the same scene a frame apart scores high.
+export function canvasSimilarity(a, b) {
+  const stats = (img) => {
+    const hist = new Float64Array(64);
+    const n = img.width * img.height;
+    for (let i = 0; i < n; i++) hist[((img.data[i * 4] >> 6) << 4) | ((img.data[i * 4 + 1] >> 6) << 2) | (img.data[i * 4 + 2] >> 6)]++;
+    let mode = 0;
+    for (let k = 1; k < 64; k++) if (hist[k] > hist[mode]) mode = k;
+    const [mr, mg, mb] = [(mode >> 4) * 64 + 32, ((mode >> 2) & 3) * 64 + 32, (mode & 3) * 64 + 32];
+    let ink = 0;
+    for (let i = 0; i < n; i++) if (Math.abs(img.data[i * 4] - mr) + Math.abs(img.data[i * 4 + 1] - mg) + Math.abs(img.data[i * 4 + 2] - mb) > 96) ink++;
+    for (let k = 0; k < 64; k++) hist[k] /= n || 1;
+    return { hist, ink: ink / (n || 1) };
+  };
+  const A = stats(a), B = stats(b);
+  let inter = 0;
+  for (let k = 0; k < 64; k++) inter += Math.min(A.hist[k], B.hist[k]);
+  const cover = 1 - Math.abs(A.ink - B.ink) / Math.max(A.ink, B.ink, 0.05);
+  return +(100 * (0.5 * inter + 0.5 * cover)).toFixed(2);
+}
+
 export function matchPct(pngA, pngB, withDiff = false) {
   const w = Math.max(pngA.width, pngB.width), h = Math.max(pngA.height, pngB.height);
   const a = pad(pngA, w, h), b = pad(pngB, w, h);

package/scripts/load.mjs

@@ -9,7 +9,7 @@
 //   -> sites/<name>/compare/load.json, frames in compare/load/ and reference/load/
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { VIEWPORTS, parseArgs, openBrowser, newPage, serve, matchPct, cached, PNG, withTimeout } from './lib.mjs';
+import { SCORED as VIEWPORTS, parseArgs, openBrowser, newPage, serve, matchPct, cached, PNG, withTimeout } from './lib.mjs';
 
 const { pos, flags } = parseArgs(process.argv.slice(2));
 const [name] = pos;
@@ -81,14 +81,18 @@ try {
     const clone = await twice(cloneUrl || `${server.url}index.html`, path.join(root, 'compare', 'load'), vp);
     const gap = Object.fromEntries(TIMES.map((t) => [t, +Math.abs(ref.curve[t] - clone.curve[t]).toFixed(2)]));
     const noise = +Math.max(ref.noise, clone.noise).toFixed(2);
-    // a side that does not agree with itself (an intro that starts a second later in one run) cannot be scored
-    // against anything: the width is reported as unstable, like a probe, instead of as a number
-    const unstable = noise > NOISE_LIMIT;
-    const score = unstable ? null : +(100 - TIMES.reduce((s, t) => s + gap[t], 0) / TIMES.length).toFixed(2);
-    viewports.push({ viewport: vp.name, score, unstable, noise, gap, ref, clone });
+    const match = (curve) => +(100 - TIMES.reduce((s, t) => s + Math.abs(ref.curve[t] - curve[t]), 0) / TIMES.length).toFixed(2);
+    // Only the reference not agreeing with itself (an intro that starts a second later in one run) leaves nothing to
+    // score against: that width is reported as unstable, like a probe. A clone that loads differently from one run to
+    // the next is a defect, not noise: it is scored by its worse run (a visitor may get that one).
+    const unstable = ref.noise > NOISE_LIMIT;
+    const cloneUnstable = !unstable && clone.noise > NOISE_LIMIT;
+    const score = unstable ? null : cloneUnstable ? Math.min(...clone.runs.map((r) => match(r.curve))) : match(clone.curve);
+    viewports.push({ viewport: vp.name, score, unstable, cloneUnstable, noise, gap, ref, clone });
+    const curves = `curves ref ${TIMES.map((t) => ref.curve[t]).join('/')} clone ${clone.runs.map((r) => TIMES.map((t) => r.curve[t]).join('/')).join(' | ')}`;
     console.log(unstable
-      ? `${vp.name}: load unstable (noise ±${noise} between two runs of the ${ref.noise > clone.noise ? 'reference' : 'clone'} itself; not scored; curves ref ${TIMES.map((t) => ref.curve[t]).join('/')} clone ${TIMES.map((t) => clone.curve[t]).join('/')})`
-      : `${vp.name}: load match ${score}% (noise ±${noise}; settled: reference ${ref.settledAt ?? '>4000'}ms, clone ${clone.settledAt ?? '>4000'}ms; curves ref ${TIMES.map((t) => ref.curve[t]).join('/')} clone ${TIMES.map((t) => clone.curve[t]).join('/')})`);
+      ? `${vp.name}: load unstable (the reference differs by ±${ref.noise} between two runs of itself; not scored; ${curves})`
+      : `${vp.name}: load match ${score}%${cloneUnstable ? ` (the clone loads differently each time, ±${clone.noise}: scored by its worse run)` : ` (noise ±${noise})`}; settled: reference ${ref.settledAt ?? '>4000'}ms, clone ${clone.settledAt ?? '>4000'}ms; ${curves}`);
   }
 } finally {
   if (!flags.cdp) await browser.close();