@trueclone/cli 0.2.0 → 0.3.0

package/scripts/reveals.mjs

@@ -1,14 +1,20 @@
-// Record one-shot scroll reveals on the reference, frame by frame, so the clone can replay them exactly.
-// A fresh page is scrolled down like a visitor would; every element that sat below the fold in a hidden or offset
-// state (opacity ~0, a translate, a scale, a blur) is watched with requestAnimationFrame, and when it starts to
-// change its opacity, translate, scale and blur are sampled every frame until they settle. The result is the
-// reveal's real curve (delay, duration, easing, stagger included), whatever library drew it: Framer Motion, GSAP,
-// AOS, IntersectionObserver plus CSS transitions. `trueclone seed` marks these elements in the clone and adds a
-// small player that replays the curves with the Web Animations API when they scroll into view.
+// Record what scrolling does to the reference, so the clone can replay it exactly:
+// - one-shot scroll reveals, frame by frame: every element that sat below the fold in a hidden or offset state
+//   (opacity ~0, a translate, a scale, a blur) is watched with requestAnimationFrame, and when it starts to change
+//   its opacity, translate, scale and blur are sampled every frame until they settle. The result is the reveal's
+//   real curve (delay, duration, easing, stagger included), whatever library drew it: Framer Motion, GSAP, AOS,
+//   IntersectionObserver plus CSS transitions;
+// - scroll-linked curves (parallax, a scrubbed fade or scale): every element is sampled at each settled scroll
+//   position; what follows the scroll position, and comes back to its start when the page returns to the top, is a
+//   curve keyed by scroll position. A translate that follows the scroll one to one is a pin and is listed, not
+//   replayed (the clone's script recreates pins);
+// - class changes caused by scrolling (a header that gets its backdrop past 12px, an "is-visible" toggle).
+// `trueclone seed` marks these elements in the clone and adds a small player that replays them.
 //
 // Elements are identified by their path of element children, skipping script/style/meta-like tags, which is
 // the same in the live page and in the script-free mirror the clone is seeded from.
 //
+// Runs at every width by default (offsets differ per width): one file each, recorded in parallel.
 // usage: node scripts/reveals.mjs <name> [--viewport desktop]   -> sites/<name>/reference/reveals.<vp>.json
 import fs from 'node:fs/promises';
 import path from 'node:path';
@@ -17,14 +23,19 @@ import { VIEWPORTS, parseArgs, openBrowser, newPage, waitStill, wheelTo } from '
 const { pos, flags } = parseArgs(process.argv.slice(2));
 const [name] = pos;
 if (!name) {
-  console.error('usage: trueclone reveals <name> [--viewport desktop]');
+  console.error('usage: trueclone reveals <name> [--viewport desktop|tablet|mobile]');
   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 vps = flags.viewport ? [VIEWPORTS.find((v) => v.name === flags.viewport)] : VIEWPORTS;
+if (vps.some((v) => !v)) {
+  console.error(`unknown viewport ${flags.viewport}: desktop, tablet or mobile`);
+  process.exit(1);
+}
 
-// Runs in the page before any scroll: picks the candidates and starts the frame sampler.
+// Runs in the page before any scroll: picks the reveal candidates, starts the frame sampler, and prepares the
+// per-position sampler for every element.
 function watchInPage() {
   const SKIP = new Set(['SCRIPT', 'NOSCRIPT', 'TEMPLATE', 'STYLE', 'LINK', 'META']);
   const pathOf = (el) => {
@@ -35,6 +46,7 @@ function watchInPage() {
     }
     return parts.join('>');
   };
+  const clsOf = (el) => String(el.getAttribute('class') || '').split(/\s+/).slice(0, 2).join('.');
   const read = (el) => {
     const s = getComputedStyle(el);
     const m = new DOMMatrixReadOnly(s.transform === 'none' ? undefined : s.transform);
@@ -43,8 +55,10 @@ function watchInPage() {
   };
   const hiddenish = (st) => st.o <= 0.05 || Math.hypot(st.tx, st.ty) >= 8 || Math.abs(st.s - 1) >= 0.04 || st.blur > 0;
   const candidates = [];
+  const tracked = [];
   for (const el of document.body.querySelectorAll('*')) {
     if (SKIP.has(el.tagName) || el.closest('svg') && el.tagName !== 'svg') continue;
+    tracked.push({ el, samples: [], last: null, back: null });
     const r = el.getBoundingClientRect();
     if (r.top < innerHeight || r.width < 8 || r.height < 8) continue;
     const st = read(el);
@@ -54,9 +68,67 @@ function watchInPage() {
     if (endless(el) || (el.parentElement && endless(el.parentElement))) continue;
     // keep the outermost element of a revealing group (a hidden card hides its children too)
     if (candidates.some((c) => c.el.contains(el))) continue;
-    candidates.push({ el, path: pathOf(el), from: st, frames: null, start: null, topAtStart: null, last: JSON.stringify(st), still: 0, done: false });
+    candidates.push({ el, path: pathOf(el), from: st, frames: null, start: null, topAtStart: null, last: JSON.stringify(st), still: 0, done: false, doneAtY: null, movedStill: 0, lastY: Math.round(scrollY) });
   }
   window.__tcReveals = candidates;
+  // one sample per element per settled scroll position, kept only when the state changed
+  window.__tcSample = () => {
+    const y = Math.round(scrollY);
+    for (const t of tracked) {
+      if (!t.el.isConnected) continue;
+      const r = t.el.getBoundingClientRect();
+      if (r.width < 8 || r.height < 8) continue;
+      const st = read(t.el);
+      const key = JSON.stringify(st);
+      if (key === t.last) continue;
+      t.last = key;
+      // v: where the element's layout box sits in the viewport (its translate taken out), the way ScrollTrigger sees it
+      t.samples.push({ y, v: Math.round(r.top - st.ty), ...st });
+    }
+  };
+  window.__tcSampleBack = () => { for (const t of tracked) if (t.el.isConnected) { const st = read(t.el); t.back = { y: Math.round(scrollY), v: Math.round(t.el.getBoundingClientRect().top - st.ty), ...st }; } };
+  // called twice while the page stands still: what changed in between moves on its own (a loop, a timer), not with the scroll
+  window.__tcSampleIdle = () => { for (const t of tracked) { if (!t.el.isConnected) continue; const key = JSON.stringify(read(t.el)); if (t.idleKey !== undefined && key !== t.idleKey) t.idleMoved = true; t.idleKey = key; } };
+  // after the scroll-through: which sampled elements follow the scroll position
+  window.__tcClassify = (classPathList) => {
+    const classPaths = new Set(classPathList);
+    const revealOf = new Map(candidates.filter((c) => c.done && c.movedStill >= 2).map((c) => [c.el, c]));
+    const scrubs = [], pins = [];
+    for (const t of tracked) {
+      if (!t.el.isConnected || t.samples.length < 2 || t.idleMoved) continue;
+      const p = pathOf(t.el);
+      if (classPaths.has(p)) continue; // a class change the class player replays
+      const rev = revealOf.get(t.el);
+      let samples = t.samples;
+      if (rev) {
+        // after its one-shot reveal: the state back at the top (revealed, scroll position 0), then from where the
+        // reveal ended; between the two the curve is interpolated (a parallax is linear in the scroll position)
+        const last = rev.frames[rev.frames.length - 1];
+        const after = samples.filter((s) => s.y > rev.doneAtY);
+        samples = [...(t.back && t.back.y < rev.doneAtY ? [t.back] : []), { y: rev.doneAtY, v: after[0] ? after[0].v + (after[0].y - rev.doneAtY) : undefined, o: last.o, tx: last.tx, ty: last.ty, s: last.s, blur: last.blur }, ...after];
+      }
+      if (samples.length < 3) continue; // two states is a toggle, not a curve
+      // a pin: translateY follows the scroll one to one between two positions, nothing else changes
+      const slopes = [];
+      for (let i = 1; i < samples.length; i++) slopes.push((samples[i].ty - samples[i - 1].ty) / ((samples[i].y - samples[i - 1].y) || 1));
+      const isPin = (k) => Math.abs(k - 1) < 0.05, isFlat = (k) => Math.abs(k) < 0.02;
+      if (slopes.filter(isPin).length >= 2 && slopes.every((k) => isPin(k) || isFlat(k)) && samples.every((s) => Math.abs(s.tx - samples[0].tx) < 2 && Math.abs(s.o - samples[0].o) < 0.03 && Math.abs(s.s - samples[0].s) < 0.01)) {
+        const first = slopes.findIndex(isPin);
+        let lastI = slopes.length - 1;
+        while (lastI > first && !isPin(slopes[lastI])) lastI--;
+        pins.push({ path: p, cls: clsOf(t.el), start: samples[first].y, end: samples[lastI + 1].y });
+        continue;
+      }
+      const step = Math.max(1, Math.ceil(samples.length / 40));
+      // keyed by the element's viewport position when it moves with the page (a card's parallax: the same curve in
+      // any viewport height, as a ScrollTrigger on the element would give), by scroll position when it doesn't (a
+      // line inside a pinned stage: its box stays put while the page scrolls)
+      const a = samples[0], b = samples[samples.length - 1];
+      const key = b.y !== a.y && a.v !== undefined && Math.abs((b.v - a.v) / (b.y - a.y) + 1) < 0.15 ? 'v' : 'y';
+      scrubs.push({ path: p, cls: clsOf(t.el), key, samples: samples.filter((s, i) => i % step === 0 || i === samples.length - 1) });
+    }
+    return { scrubs, pins };
+  };
   const tick = (now) => {
     for (const c of candidates) {
       if (c.done) continue;
@@ -73,11 +145,16 @@ function watchInPage() {
         continue;
       }
       c.frames.push({ t: Math.round(now - c.start), ...st });
+      // motion while the page stands still is a one-shot animation; motion only while scrolling is scroll-linked
+      const y = Math.round(scrollY);
+      if (key !== c.last && y === c.lastY) c.movedStill++;
+      c.lastY = y;
       c.still = key === c.last ? c.still + 1 : 0;
       c.last = key;
       if (c.still >= 8 || now - c.start > 6000) {
         c.frames = c.frames.slice(0, c.frames.length - c.still + 1); // drop the trailing identical frames
         c.done = true;
+        c.doneAtY = Math.round(scrollY);
       }
     }
     if (candidates.some((c) => !c.done)) requestAnimationFrame(tick);
@@ -111,81 +188,98 @@ function watchClassesInPage() {
       const now = el.getAttribute('class');
       if (now === r.oldValue) continue;
       seen.add(el);
-      const rect = el.getBoundingClientRect();
+      // an element without a box (display: contents, an empty wrapper) is placed by its first descendant that has one
+      let boxEl = el;
+      if (!boxEl.getBoundingClientRect().height) boxEl = [...el.querySelectorAll('*')].find((d) => d.getBoundingClientRect().height) || el;
+      const rect = boxEl.getBoundingClientRect();
       window.__tcClasses.push({ el, path: pathOf(el), from: r.oldValue, to: now, scrollY: Math.round(scrollY), ratio: +(rect.top / innerHeight).toFixed(3), sticky: pinned(el) });
     }
   }).observe(document.body, { subtree: true, attributes: true, attributeFilter: ['class'], attributeOldValue: true });
 }
 
-const browser = await openBrowser(flags.cdp);
-let result;
-try {
-  const { page } = await newPage(browser, vp, { reducedMotion: 'no-preference' });
-  await page.goto(meta.url, { waitUntil: 'load', timeout: 60000 });
-  await page.mouse.move(5, vp.height - 5);
-  await waitStill(page, { timeout: 15000, interval: 200 });
-  const count = await page.evaluate(watchInPage);
-  // Class changes caused by scrolling (a header that gets its backdrop, an "is-visible" toggle): watched with a
-  // MutationObserver. Anything that changes while the page sits idle (timers, carousels) is ignored.
-  await page.evaluate(watchClassesInPage);
-  await page.waitForTimeout(1500);
-  await page.evaluate(() => { window.__tcClassIdle = false; });
-  // scroll down a third of a window at a time and give each reveal time to play
-  const max = await page.evaluate(() => document.documentElement.scrollHeight - innerHeight);
-  for (let y = 0; y <= max; y += Math.round(vp.height / 3)) {
-    await wheelTo(page, y, vp);
-    await page.waitForTimeout(450);
-  }
-  await page.waitForTimeout(2500);
-  // back to the top: does each class change revert (scroll state) or stay (one-shot)?
-  await page.evaluate(() => window.scrollTo(0, 0));
-  await page.waitForTimeout(1200);
-  // class order changes when a site removes and re-adds classes: compare the sets
-  // It reverts when the classes the scroll removed are back; classes added once (a one-time animation) may stay, so the
-  // state after returning ('back') is recorded too and used by the clone after the first scroll.
-  await page.evaluate(() => {
-    const toks = (v) => String(v || '').split(/\s+/).filter(Boolean);
-    for (const c of window.__tcClasses) {
-      c.back = c.el.getAttribute('class');
-      const removed = toks(c.from).filter((t) => !toks(c.to).includes(t));
-      c.reverts = removed.length ? removed.every((t) => toks(c.back).includes(t)) : !toks(c.back).some((t) => toks(c.to).includes(t) && !toks(c.from).includes(t));
-      c.marks = toks(c.to).filter((t) => !toks(c.back).includes(t)); // classes that only exist while scrolled
+async function record(vp) {
+  const browser = await openBrowser(flags.cdp);
+  let result, scrubs, pins;
+  try {
+    const { page } = await newPage(browser, vp, { reducedMotion: 'no-preference' });
+    await page.goto(meta.url, { waitUntil: 'load', timeout: 60000 });
+    await page.mouse.move(5, vp.height - 5);
+    await waitStill(page, { timeout: 15000, interval: 200 });
+    const count = await page.evaluate(watchInPage);
+    // Class changes caused by scrolling (a header that gets its backdrop, an "is-visible" toggle): watched with a
+    // MutationObserver. Anything that changes while the page sits idle (timers, carousels) is ignored.
+    await page.evaluate(watchClassesInPage);
+    await page.waitForTimeout(1500);
+    await page.evaluate(() => { window.__tcClassIdle = false; });
+    await page.evaluate(() => window.__tcSample()); // every element's state at the top
+    // scroll down a third of a window at a time, give each reveal time to play, sample every element where it settled
+    const max = await page.evaluate(() => document.documentElement.scrollHeight - innerHeight);
+    for (let y = 0; y <= max; y += Math.round(vp.height / 3)) {
+      await wheelTo(page, y, vp, { settle: true });
+      await page.waitForTimeout(450);
+      await page.evaluate(() => window.__tcSample());
     }
-  });
-  // sticky/fixed elements switch at a scroll position: find it precisely by bisection
-  const stickyCount = await page.evaluate(() => window.__tcClasses.filter((c) => c.sticky && c.reverts).length);
-  for (let i = 0; i < stickyCount; i++) {
-    let lo = 0, hi = await page.evaluate((k) => window.__tcClasses.filter((c) => c.sticky && c.reverts)[k].scrollY, i);
-    while (hi - lo > 2) {
-      const mid = Math.round((lo + hi) / 2);
-      await page.evaluate((y) => window.scrollTo(0, y), mid);
-      await page.waitForTimeout(160);
-      const on = await page.evaluate((k) => { const c = window.__tcClasses.filter((x) => x.sticky && x.reverts)[k]; const now = String(c.el.getAttribute('class') || '').split(/\s+/); return c.marks.length > 0 && c.marks.every((t) => now.includes(t)); }, i);
-      if (on) hi = mid; else lo = mid;
+    await page.waitForTimeout(1300);
+    await page.evaluate(() => { window.__tcSample(); window.__tcSampleIdle(); });
+    await page.waitForTimeout(1200);
+    await page.evaluate(() => window.__tcSampleIdle());
+    // back to the top: does each class change revert (scroll state) or stay (one-shot)? does each moved element
+    // return to its starting state (scroll-linked) or not (one-shot, time-driven)?
+    await page.evaluate(() => window.scrollTo(0, 0));
+    await page.waitForTimeout(1200);
+    await page.evaluate(() => window.__tcSampleBack());
+    // class order changes when a site removes and re-adds classes: compare the sets
+    // It reverts when the classes the scroll removed are back; classes added once (a one-time animation) may stay, so the
+    // state after returning ('back') is recorded too and used by the clone after the first scroll.
+    await page.evaluate(() => {
+      const toks = (v) => String(v || '').split(/\s+/).filter(Boolean);
+      for (const c of window.__tcClasses) {
+        c.back = c.el.getAttribute('class');
+        const removed = toks(c.from).filter((t) => !toks(c.to).includes(t));
+        c.reverts = removed.length ? removed.every((t) => toks(c.back).includes(t)) : !toks(c.back).some((t) => toks(c.to).includes(t) && !toks(c.from).includes(t));
+        c.marks = toks(c.to).filter((t) => !toks(c.back).includes(t)); // classes that only exist while scrolled
+      }
+    });
+    // sticky/fixed elements switch at a scroll position: find it precisely by bisection
+    const stickyCount = await page.evaluate(() => window.__tcClasses.filter((c) => c.sticky && c.reverts).length);
+    for (let i = 0; i < stickyCount; i++) {
+      let lo = 0, hi = await page.evaluate((k) => window.__tcClasses.filter((c) => c.sticky && c.reverts)[k].scrollY, i);
+      while (hi - lo > 2) {
+        const mid = Math.round((lo + hi) / 2);
+        await page.evaluate((y) => window.scrollTo(0, y), mid);
+        await page.waitForTimeout(160);
+        const on = await page.evaluate((k) => { const c = window.__tcClasses.filter((x) => x.sticky && x.reverts)[k]; const now = String(c.el.getAttribute('class') || '').split(/\s+/); return c.marks.length > 0 && c.marks.every((t) => now.includes(t)); }, i);
+        if (on) hi = mid; else lo = mid;
+      }
+      await page.evaluate(([k, y]) => { window.__tcClasses.filter((c) => c.sticky && c.reverts)[k].threshold = y; }, [i, hi]);
     }
-    await page.evaluate(([k, y]) => { window.__tcClasses.filter((c) => c.sticky && c.reverts)[k].threshold = y; }, [i, hi]);
+    const classes = await page.evaluate(() => window.__tcClasses.map((c) => ({ path: c.path, from: c.from, to: c.to, back: c.back, sticky: c.sticky, reverts: c.reverts, ...(c.sticky ? { threshold: c.threshold ?? c.scrollY } : { trigger: c.ratio }) })));
+    // a reveal settles; anything still moving at the 6s cap is continuous motion driven some other way
+    // a reveal settles, and moves while the page stands still; anything still moving at the 6s cap is continuous
+    // motion driven some other way, and a change seen only during scroll steps is scroll-linked (a curve, below)
+    result = await page.evaluate(() => window.__tcReveals.filter((c) => c.frames && c.frames.length > 2 && c.movedStill >= 2 && c.frames[c.frames.length - 1].t < 5900).map((c) => {
+      const last = c.frames[c.frames.length - 1];
+      // keep at most ~60 keyframes: enough for any easing, small enough for the clone
+      const step = Math.max(1, Math.ceil(c.frames.length / 60));
+      const frames = c.frames.filter((f, i) => i % step === 0 || i === c.frames.length - 1);
+      return { path: c.path, cls: String(c.el.getAttribute('class') || '').split(/\s+/).slice(0, 2).join('.'), from: c.from, to: { o: last.o, tx: last.tx, ty: last.ty, s: last.s, blur: last.blur }, trigger: c.topAtStart, duration: last.t, frames };
+    }));
+    ({ scrubs, pins } = await page.evaluate((cp) => window.__tcClassify(cp), classes.map((c) => c.path)));
+    console.log(`${vp.name}: ${count} candidates below the fold, ${result.length} revealed while scrolling; ${scrubs.length} scroll-linked curve(s), ${pins.length} pin(s)${pins.length ? ` (${pins.map((p) => `${p.cls || p.path.split('>').pop()} ${p.start}-${p.end}px`).join(', ')})` : ''}`);
+    result.classes = classes;
+    console.log(`${vp.name}: ${classes.length} class change(s) caused by scrolling: ${classes.filter((c) => c.sticky).length} at a scroll position (sticky/fixed), ${classes.filter((c) => !c.sticky).length} when in view; ${classes.filter((c) => c.reverts).length} revert on the way back up`);
+  } finally {
+    if (!flags.cdp) await browser.close();
   }
-  const classes = await page.evaluate(() => window.__tcClasses.map((c) => ({ path: c.path, from: c.from, to: c.to, back: c.back, sticky: c.sticky, reverts: c.reverts, ...(c.sticky ? { threshold: c.threshold ?? c.scrollY } : { trigger: c.ratio }) })));
-  // a reveal settles; anything still moving at the 6s cap is continuous motion driven some other way
-  result = await page.evaluate(() => window.__tcReveals.filter((c) => c.frames && c.frames.length > 2 && c.frames[c.frames.length - 1].t < 5900).map((c) => {
-    const last = c.frames[c.frames.length - 1];
-    // keep at most ~60 keyframes: enough for any easing, small enough for the clone
-    const step = Math.max(1, Math.ceil(c.frames.length / 60));
-    const frames = c.frames.filter((f, i) => i % step === 0 || i === c.frames.length - 1);
-    return { path: c.path, cls: String(c.el.getAttribute('class') || '').split(/\s+/).slice(0, 2).join('.'), from: c.from, to: { o: last.o, tx: last.tx, ty: last.ty, s: last.s, blur: last.blur }, trigger: c.topAtStart, duration: last.t, frames };
-  }));
-  console.log(`${count} candidates below the fold, ${result.length} revealed while scrolling`);
-  result.classes = classes;
-  console.log(`${classes.length} class change(s) caused by scrolling: ${classes.filter((c) => c.sticky).length} at a scroll position (sticky/fixed), ${classes.filter((c) => !c.sticky).length} when in view; ${classes.filter((c) => c.reverts).length} revert on the way back up`);
-} finally {
-  if (!flags.cdp) await browser.close();
-}
-const out = path.join(root, 'reference', `reveals.${vp.name}.json`);
-await fs.writeFile(out, JSON.stringify({ url: meta.url, viewport: vp, at: new Date().toISOString(), reveals: result, classes: result.classes }, null, 2));
-const groups = new Map();
-for (const r of result) {
-  const k = `${JSON.stringify(r.from)} -> ${Math.round(r.duration / 50) * 50}ms`;
-  groups.set(k, (groups.get(k) || 0) + 1);
+  const out = path.join(root, 'reference', `reveals.${vp.name}.json`);
+  await fs.writeFile(out, JSON.stringify({ url: meta.url, viewport: vp, at: new Date().toISOString(), reveals: result, scrubs, pins, classes: result.classes }, null, 2));
+  const groups = new Map();
+  for (const r of result) {
+    const k = `${JSON.stringify(r.from)} -> ${Math.round(r.duration / 50) * 50}ms`;
+    groups.set(k, (groups.get(k) || 0) + 1);
+  }
+  for (const [k, n] of [...groups].sort((a, b) => b[1] - a[1]).slice(0, 8)) console.log(`  ${vp.name} ${String(n).padStart(3)}x  from ${k}`);
+  console.log(`-> ${path.relative(process.cwd(), out)}`);
 }
-for (const [k, n] of [...groups].sort((a, b) => b[1] - a[1]).slice(0, 8)) console.log(`  ${String(n).padStart(3)}x  from ${k}`);
-console.log(`-> ${path.relative(process.cwd(), out)}`);
+
+await Promise.all(vps.map(record));

package/scripts/score.mjs

@@ -7,9 +7,14 @@
 // tool mostly waits on smooth scroll and settling, so running them side by side costs little. --serial runs
 // one at a time (for debugging a flaky score).
 //
-// usage: node scripts/score.mjs <name> [--quick] [--url <clone url>] [--refresh-ref] [--step-minutes 20] [--serial]
+// A check whose inputs are unchanged since its last run is reported from its last result instead of re-measured
+// (--fresh re-measures). --only detail,load runs those checks alone; --viewport tablet narrows every check to one width.
+//
+// usage: node scripts/score.mjs <name> [--quick] [--only <checks>] [--viewport <vp>] [--fresh] [--url <clone url>] [--refresh-ref] [--step-minutes 20] [--serial]
 import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
 import path from 'node:path';
+import crypto from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from './lib.mjs';
 
@@ -27,16 +32,60 @@ const refresh = flags['refresh-ref'] ? ['--refresh-ref'] : [];
 const limitMs = Number(flags['step-minutes'] || 20) * 60 * 1000;
 const withUrl = (args) => (url ? [...args, '--url', url] : args);
 
-const steps = [
+// --viewport desktop narrows every check that can run per width; --only detail,load runs those checks alone
+const vpOnly = typeof flags.viewport === 'string' ? flags.viewport : null;
+const vpList = vpOnly ? [vpOnly] : ['desktop', 'tablet', 'mobile'];
+const only = typeof flags.only === 'string' ? flags.only.split(',').map((s) => s.trim()).filter(Boolean) : null;
+const allSteps = [
+  // first and alone: has the live page changed since the capture? (the live-measured checks are then marked stale)
+  ...(flags.quick ? [] : [{ group: 0, label: 'drift', args: ['scripts/drift.mjs', name, ...(vpOnly ? ['--viewport', vpOnly] : [])], pick: /(\w+): live (\d+)px/g, unit: 'live px', live: true }]),
   { group: 1, label: 'layout', args: withUrl(['scripts/diff.mjs', name, '--structure']), pick: /│ \d+\s+│ '(\w+)'\s+│ ([\d.]+)/g, unit: 'layout %' },
-  { group: 1, label: 'states', args: ['scripts/states.mjs', name, '--clone', ...(url ? [url] : []), '--structure', ...(flags.quick ? ['--viewports', 'desktop'] : [])], pick: /│ \d+\s+│ '(\w+)'\s+│ ([\d.]+)/g, unit: 'states %' },
-  ...(flags.quick ? [] : ['desktop', 'tablet', 'mobile'].map((v) => ({ group: 2, label: `curves ${v}`, args: withUrl(['scripts/curves.mjs', name, '--viewport', v, ...refresh]), pick: /motion score \((\w+)\): ([\d.]+)%/g, unit: 'motion %' }))),
+  { group: 1, label: 'states', args: ['scripts/states.mjs', name, '--clone', ...(url ? [url] : []), '--structure', ...(flags.quick || vpOnly ? ['--viewports', vpOnly || 'desktop'] : [])], pick: /│ \d+\s+│ '(\w+)'\s+│ ([\d.]+)/g, unit: 'states %' },
+  ...(flags.quick ? [] : vpList.map((v) => ({ group: 2, label: `curves ${v}`, args: withUrl(['scripts/curves.mjs', name, '--viewport', v, ...refresh]), pick: /motion score \((\w+)\): ([\d.]+)%/g, unit: 'motion %' }))),
   { group: 3, label: 'interact', args: withUrl(['scripts/interact.mjs', name, ...refresh]), pick: /│ \d+\s+│ '([^']+)'\s+│ ([\d.]+)/g, unit: 'interaction %', fail: /FAIL/g },
   ...(flags.quick ? [] : [
     { group: 3, label: 'hovers', args: withUrl(['scripts/hovers.mjs', name, ...refresh]), pick: /hover match \((\w+)\): ([\d.]+)%/g, unit: 'hover %' },
-    { group: 3, label: 'detail', args: withUrl(['scripts/detail.mjs', name, '--viewport', 'all', ...refresh]), pick: /(\w+): detail match ([\d.]+)%/g, unit: 'detail %' },
+    { group: 3, label: 'detail', args: withUrl(['scripts/detail.mjs', name, '--viewport', vpOnly || 'all', ...refresh]), pick: /(\w+): detail match ([\d.]+)%/g, unit: 'detail %' },
+    // alone, last: the load sequence is a timing measurement, and the other checks must not be starved by it either
+    { group: 4, label: 'load', args: withUrl(['scripts/load.mjs', name, ...(vpOnly ? ['--viewport', vpOnly] : []), ...refresh]), pick: /(\w+): load match ([\d.]+)%/g, unit: 'load %' },
   ]),
 ];
+const steps = only ? allSteps.filter((st) => only.some((o) => st.label === o || st.label.startsWith(`${o} `))) : allSteps;
+if (!steps.length) {
+  console.error(`--only matched no check; checks: ${[...new Set(allSteps.map((st) => st.label.split(' ')[0]))].join(', ')}`);
+  process.exit(1);
+}
+
+// Incremental: a check whose inputs have not changed since its last run (the clone's files, the capture, the
+// options) is not re-measured; its last result is reported again. --fresh re-measures everything. Scoring another
+// build (--url) is always measured, since its files are not the clone's.
+const root = path.resolve('sites', name);
+const capturedAt = await fs.readFile(path.join(root, 'reference', 'meta.json'), 'utf8').then((s) => JSON.parse(s).capturedAt).catch(() => null);
+async function cloneHash() {
+  const h = crypto.createHash('sha1');
+  const walk = async (dir) => {
+    for (const e of (await fs.readdir(dir, { withFileTypes: true }).catch(() => [])).sort((a, b) => a.name.localeCompare(b.name))) {
+      const p = path.join(dir, e.name);
+      if (e.isDirectory()) { if (e.name !== 'node_modules') await walk(p); continue; }
+      const st = await fs.stat(p);
+      h.update(`${path.relative(root, p)}:${st.size}:${Math.round(st.mtimeMs)}\n`);
+    }
+  };
+  await walk(path.join(root, 'clone'));
+  for (const f of ['interactions.json', 'motion-map.json']) h.update(`${f}:${await fs.readFile(path.join(root, f), 'utf8').catch(() => '')}\n`);
+  // reference measurements other steps produce (live scroll states, reveals, motion, cached probe reads) are inputs too
+  for (const e of (await fs.readdir(path.join(root, 'reference'), { withFileTypes: true }).catch(() => [])).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (['assets', 'mirror', 'load', 'tiles'].includes(e.name)) continue;
+    const p = path.join(root, 'reference', e.name);
+    if (e.isDirectory()) await walk(p); else { const st = await fs.stat(p); h.update(`reference/${e.name}:${st.size}:${Math.round(st.mtimeMs)}\n`); }
+  }
+  return h.digest('hex');
+}
+const stampsFile = path.join(root, 'compare', '.stamps.json');
+const stamps = url ? {} : await fs.readFile(stampsFile, 'utf8').then(JSON.parse).catch(() => ({}));
+const inputs = url ? null : { hash: await cloneHash(), capturedAt, args: null };
+const stampKey = (step) => JSON.stringify({ hash: inputs?.hash, capturedAt, args: step.args });
+const reusable = (step) => !step.live && !url && !flags.fresh && !flags['refresh-ref'] && stamps[step.label]?.key === stampKey(step) && stamps[step.label].values !== undefined;
 
 const runStep = (step) => new Promise((resolve) => {
   const started = Date.now();
@@ -66,17 +115,30 @@ const finish = (step, { code, out, ms }) => {
   if (code !== 0 && !timedOut) console.log(out.split('\n').filter(Boolean).slice(-4).map((l) => `    ${l}`).join('\n'));
   [...errors, ...warnings].forEach((l) => console.log(`    ${l}`));
   summary.push({ step: step.label, status, seconds: Math.round(ms / 1000), [step.unit]: values.join('  ') || '-' });
+  if (!url && (status === 'ok' || status.endsWith('FAIL'))) stamps[step.label] = { key: stampKey(step), status, values: values.join('  '), seconds: Math.round(ms / 1000), at: new Date().toISOString() };
 };
 const groups = flags.serial
   ? steps.map((st) => [st])
   : [...new Set(steps.map((st) => st.group))].map((g) => steps.filter((st) => st.group === g));
 for (const group of groups) {
-  console.log(`running: ${group.map((st) => st.label).join(', ')}`);
-  await Promise.all(group.map(async (step) => finish(step, await runStep(step))));
+  const todo = group.filter((st) => !reusable(st));
+  for (const st of group.filter(reusable)) {
+    const s = stamps[st.label];
+    console.log(`  ${st.label.padEnd(16)} ${s.status} (unchanged since ${s.at.slice(0, 16).replace('T', ' ')}, not re-measured; --fresh to re-run)   ${s.values}`);
+    summary.push({ step: st.label, status: `${s.status} (kept)`, seconds: 0, [st.unit]: s.values || '-' });
+  }
+  if (!todo.length) continue;
+  console.log(`running: ${todo.map((st) => st.label).join(', ')}`);
+  await Promise.all(todo.map(async (step) => finish(step, await runStep(step))));
 }
 summary.sort((x, y) => steps.findIndex((st) => st.label === x.step) - steps.findIndex((st) => st.label === y.step));
-console.log(`\n${flags.quick ? 'quick' : 'full'} score for ${name}${url ? ` (${url})` : ''} in ${((Date.now() - t0) / 60000).toFixed(1)} min`);
-console.table(summary.map((s) => ({ step: s.step, status: s.status, 's': s.seconds, result: Object.entries(s).find(([k]) => k.endsWith('%'))?.[1] })));
+const totalMin = +((Date.now() - t0) / 60000).toFixed(1);
+console.log(`\n${flags.quick ? 'quick' : 'full'} score for ${name}${url ? ` (${url})` : ''} in ${totalMin} min`);
+console.table(summary.map((s) => ({ step: s.step, status: s.status, 's': s.seconds, result: Object.entries(s).find(([k]) => k.endsWith('%') || k.endsWith('px'))?.[1] })));
+await fs.mkdir(path.join(root, 'compare'), { recursive: true });
+if (!url) await fs.writeFile(stampsFile, JSON.stringify(stamps, null, 2));
+// where the time went, for REPORT.md and for choosing what to re-run
+await fs.writeFile(path.join(root, 'compare', 'score-times.json'), JSON.stringify({ at: new Date().toISOString(), kind: flags.quick ? 'quick' : 'full', only, viewport: vpOnly, url, totalMin, steps: Object.fromEntries(summary.map((s) => [s.step, { status: s.status, seconds: s.seconds }])) }, null, 2));
 // REPORT.md: every score against its target, what to fix first, and what was not copied
 const report = await runStep({ args: ['report.mjs', name] });
 console.log(report.out.trim());