@trueclone/cli 0.0.0-stage → 0.2.0

package/scripts/lib.mjs

@@ -0,0 +1,423 @@
+// Shared capture settings so the reference and the clone are rendered identically.
+import fs from 'node:fs/promises';
+import crypto from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { chromium } from 'playwright';
+import { PNG } from 'pngjs';
+import pixelmatch from 'pixelmatch';
+
+export { PNG };
+
+export const VIEWPORTS = [
+  { name: 'mobile', width: 390, height: 844 },
+  { name: 'tablet', width: 768, height: 1024 },
+  { name: 'desktop', width: 1440, height: 900 },
+];
+
+// 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;
+transition:none!important;caret-color:transparent!important;scroll-behavior:auto!important}`;
+
+const MAX_SCROLL = 30000; // stop infinite-scroll pages from running forever
+
+export function parseArgs(argv) {
+  const pos = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith('--')) { flags[key] = next; i++; } else flags[key] = true;
+    } else pos.push(a);
+  }
+  return { pos, flags };
+}
+
+export function siteName(url) {
+  return new URL(url).hostname.replace(/^www\./, '').replace(/[^a-z0-9]+/gi, '-').toLowerCase();
+}
+
+// --cdp attaches to the lab Chrome (npm run chrome) for sites that refuse headless browsers.
+// Installed Google Chrome by default: Playwright's bundled Chromium has no H.264/AAC, so sites that wait
+// for an HLS/MP4 video (intros, loaders) never finish loading in it. LAB_BROWSER=chromium forces the bundled one.
+export async function openBrowser(cdp) {
+  if (cdp) return chromium.connectOverCDP(cdp === true ? 'http://127.0.0.1:9222' : cdp);
+  if (process.env.LAB_BROWSER !== 'chromium') {
+    try { return await chromium.launch({ channel: 'chrome' }); } catch { /* Chrome not installed: fall back */ }
+  }
+  return chromium.launch();
+}
+
+export async function newPage(browser, vp, extra = {}) {
+  const context = await browser.newContext({
+    viewport: { width: vp.width, height: vp.height },
+    deviceScaleFactor: 1,
+    reducedMotion: 'reduce',
+    ...extra,
+  });
+  const page = await context.newPage();
+  // Hard limits on Playwright actions: a stuck click or navigation fails loudly instead of hanging for hours.
+  page.setDefaultTimeout(30000);
+  page.setDefaultNavigationTimeout(60000);
+  // Surface script errors immediately: one uncaught error can stop a clone's whole motion layer and
+  // turn every score into noise, which is much harder to diagnose from the numbers alone.
+  page.on('pageerror', (e) => console.warn(`PAGE ERROR (${page.url()}): ${e.message}`));
+  return { context, page };
+}
+
+// page.evaluate has no timeout in Playwright; anything that loops over evaluate goes through this.
+export function withTimeout(promise, ms, label) {
+  let timer;
+  const guard = new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`timeout after ${ms}ms: ${label}`)), ms); });
+  return Promise.race([promise.finally(() => clearTimeout(timer)), guard]);
+}
+
+// Reference results don't change between clone iterations: measure once, reuse until the next capture.
+// The key includes the capture time, so `npm run capture` invalidates everything automatically.
+async function cacheFile(siteRoot, keyObj) {
+  const meta = JSON.parse(await fs.readFile(path.join(siteRoot, 'reference', 'meta.json'), 'utf8'));
+  const key = crypto.createHash('sha1').update(JSON.stringify({ capturedAt: meta.capturedAt, ...keyObj })).digest('hex').slice(0, 16);
+  return path.join(siteRoot, 'reference', 'cache', `${key}.json`);
+}
+
+// Read-only lookup: the cached value, or null (never writes).
+export async function readCache(siteRoot, keyObj) {
+  try { return JSON.parse(await fs.readFile(await cacheFile(siteRoot, keyObj), 'utf8')); } catch { return null; }
+}
+
+export async function cached(siteRoot, keyObj, compute, refresh = false) {
+  const file = await cacheFile(siteRoot, keyObj);
+  if (!refresh) {
+    try { return JSON.parse(await fs.readFile(file, 'utf8')); } catch { /* not cached yet */ }
+  }
+  const value = await compute();
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await fs.writeFile(file, JSON.stringify(value));
+  return value;
+}
+
+export async function settle(page, hide = []) {
+  const hideCss = hide.length ? `${hide.join(',')}{display:none!important}` : '';
+  const tag = await page.addStyleTag({ content: FREEZE_CSS + hideCss });
+  await tag.evaluate((el) => el.setAttribute('data-lab-freeze', ''));
+  // Scroll the whole page once so lazy images and in-view reveals load.
+  await page.evaluate(async (max) => {
+    const step = Math.max(200, window.innerHeight * 0.8);
+    for (let y = 0; y < Math.min(document.documentElement.scrollHeight, max); y += step) {
+      window.scrollTo(0, y);
+      await new Promise((r) => setTimeout(r, 150));
+    }
+    window.scrollTo(0, 0);
+  }, MAX_SCROLL);
+  await page.waitForLoadState('networkidle', { timeout: 15000 }).catch(() => {});
+  await page.evaluate(() => document.fonts.ready);
+  await page.waitForTimeout(500);
+}
+
+// Structure mode: hide glyphs and turn every image/video/svg/background photo into a flat grey box,
+// so a clone with placeholder content can be scored on layout alone. Applied to both sides.
+const MASK_CSS = `*,*::before,*::after{color:transparent!important;text-shadow:none!important;
+-webkit-text-stroke-color:transparent!important;text-decoration-color:transparent!important}
+::placeholder{color:transparent!important}
+img,video{object-position:-99999px -99999px!important;background:#888!important}
+svg{background:#888!important} svg *{visibility:hidden!important} iframe{visibility:hidden!important}
+canvas{background:#888!important;filter:contrast(0) brightness(1.066)!important}
+[data-lab-cliptext]{background:none!important;-webkit-text-fill-color:transparent!important}
+[data-lab-bgb]::before,[data-lab-bga]::after{background-image:none!important;background-color:#888!important}`; // canvas = media (WebGL heroes, 3D models): flat grey box like images
+
+// What CSS alone can't select: 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. Marked with attributes
+// the mask CSS targets; `off` removes them.
+function maskExtrasInPage(enable) {
+  const marks = ['data-lab-cliptext', 'data-lab-bgb', 'data-lab-bga'];
+  if (!enable) {
+    for (const m of marks) for (const el of document.querySelectorAll(`[${m}]`)) el.removeAttribute(m);
+    return;
+  }
+  for (const el of document.querySelectorAll('*')) {
+    const s = getComputedStyle(el);
+    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', '');
+  }
+}
+
+export async function mask(page) {
+  const tag = await page.addStyleTag({ content: MASK_CSS });
+  await tag.evaluate((el) => el.setAttribute('data-lab-freeze', ''));
+  await page.evaluate(() => {
+    for (const el of document.querySelectorAll('*')) {
+      if (getComputedStyle(el).backgroundImage.includes('url(')) {
+        el.style.setProperty('background-image', 'none', 'important');
+        el.style.setProperty('background-color', '#888', 'important');
+      }
+    }
+  });
+  await page.evaluate(maskExtrasInPage, true);
+  await page.waitForTimeout(200);
+}
+
+// Endless animations (marquees, rotating borders, pulsing glows) sit at whatever phase the page's clock happens to
+// be at, so two screenshots of the same page differ. Before a still comparison, every infinite animation is put on
+// its first frame and paused, on both sides. Continuous motion is scored by the motion checks, not by stills.
+export async function freezeLoops(page) {
+  await page.evaluate(() => {
+    for (const a of document.getAnimations()) {
+      if (a.effect?.getTiming().iterations !== Infinity) continue;
+      a.currentTime = 0;
+      a.pause();
+    }
+  }).catch(() => {});
+}
+
+// Reversible version of mask() for live pages: on() masks, off() restores every inline style it touched.
+export async function maskToggle(page, on) {
+  await page.evaluate(([css, enable]) => {
+    if (enable) {
+      const tag = document.createElement('style');
+      tag.id = 'lab-mask';
+      tag.setAttribute('data-lab-freeze', '');
+      tag.textContent = css;
+      document.head.appendChild(tag);
+      for (const el of document.querySelectorAll('*')) {
+        if (getComputedStyle(el).backgroundImage.includes('url(')) {
+          el.setAttribute('data-lab-bg', el.style.cssText);
+          el.style.setProperty('background-image', 'none', 'important');
+          el.style.setProperty('background-color', '#888', 'important');
+        }
+      }
+    } else {
+      document.getElementById('lab-mask')?.remove();
+      for (const el of document.querySelectorAll('[data-lab-bg]')) {
+        el.style.cssText = el.getAttribute('data-lab-bg');
+        el.removeAttribute('data-lab-bg');
+      }
+    }
+  }, [MASK_CSS, on]);
+  await page.evaluate(maskExtrasInPage, on);
+  await page.waitForTimeout(on ? 150 : 50);
+}
+
+// Top-level visual sections: unwrap single-child wrappers (#__next, #root...), then list the blocks.
+export async function sectionsOf(page) {
+  return page.evaluate(() => {
+    const visible = (el) => {
+      const s = getComputedStyle(el);
+      const r = el.getBoundingClientRect();
+      return s.display !== 'none' && s.visibility !== 'hidden' && r.height > 0 && r.width > 0
+        && !['SCRIPT', 'STYLE', 'NOSCRIPT', 'LINK', 'META'].includes(el.tagName);
+    };
+    let node = document.body;
+    for (let kids = [...node.children].filter(visible); kids.length === 1; kids = [...node.children].filter(visible)) {
+      node = kids[0];
+    }
+    let blocks = [...node.children].filter(visible);
+    blocks = blocks.flatMap((el) => (el.tagName === 'MAIN' && el.children.length > 1 ? [...el.children].filter(visible) : [el]));
+    return blocks.map((el, index) => {
+      const r = el.getBoundingClientRect();
+      const heading = el.querySelector('h1,h2,h3');
+      return {
+        index,
+        tag: el.tagName.toLowerCase(),
+        id: el.id || undefined,
+        classes: [...el.classList].slice(0, 3).join(' ') || undefined,
+        heading: heading ? heading.textContent.trim().replace(/\s+/g, ' ').slice(0, 60) : undefined,
+        y: Math.round(r.top + window.scrollY),
+        height: Math.round(r.height),
+      };
+    });
+  });
+}
+
+// ---------- Static server for clones (diff + states) ----------
+const MIME = {
+  '.html': 'text/html', '.css': 'text/css', '.js': 'text/javascript', '.mjs': 'text/javascript', '.json': 'application/json',
+  '.svg': 'image/svg+xml', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif',
+  '.webp': 'image/webp', '.avif': 'image/avif', '.ico': 'image/x-icon', '.woff': 'font/woff', '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf', '.otf': 'font/otf', '.mp4': 'video/mp4', '.webm': 'video/webm', '.glb': 'model/gltf-binary',
+  '.gltf': 'model/gltf+json', '.m3u8': 'application/vnd.apple.mpegurl', '.ts': 'video/mp2t',
+};
+
+// Port 0 = a free port picked by the OS, so several scoring tools can run side by side; use server.url.
+export function serve(dir, port = 0) {
+  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; }
+      try {
+        await fs.access(file);
+        res.writeHead(200, { 'content-type': MIME[path.extname(file).toLowerCase()] || 'application/octet-stream' });
+        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); });
+  });
+}
+
+// ---------- Image comparison ----------
+// White-pad so images of different sizes can be compared; the gap counts as mismatch.
+export function pad(png, width, height) {
+  if (png.width === width && png.height === height) return png;
+  const out = new PNG({ width, height });
+  out.data.fill(255);
+  PNG.bitblt(png, out, 0, 0, png.width, png.height, 0, 0);
+  return out;
+}
+
+export function crop(png, y, h) {
+  const out = new PNG({ width: png.width, height: h });
+  PNG.bitblt(png, out, 0, y, png.width, h, 0, 0);
+  return out;
+}
+
+export const match = (a, b, diff) => pixelmatch(a.data, b.data, diff ? diff.data : null, a.width, a.height, { threshold: 0.1, includeAA: false });
+
+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);
+  const diff = withDiff ? new PNG({ width: w, height: h }) : null;
+  const bad = match(a, b, diff);
+  return { pct: +(100 - (bad / (w * h)) * 100).toFixed(2), diff };
+}
+
+// ---------- Live-state sampling (animations running, nothing frozen) ----------
+// Loads lazy content without freezing anything: scroll once top to bottom, then back to the top.
+export async function warmUp(page) {
+  await page.evaluate(async (max) => {
+    const step = Math.max(200, window.innerHeight * 0.8);
+    for (let y = 0; y < Math.min(document.documentElement.scrollHeight, max); y += step) {
+      window.scrollTo(0, y);
+      await new Promise((r) => setTimeout(r, 120));
+    }
+    window.scrollTo(0, 0);
+  }, MAX_SCROLL);
+  await page.waitForLoadState('networkidle', { timeout: 15000 }).catch(() => {});
+  await page.evaluate(() => document.fonts.ready);
+}
+
+// Motion-relevant state of every element, keyed by a stable DOM path. Elements at opacity 0 or
+// visibility:hidden are kept on purpose: "hidden until scrolled into view" is what we need to see.
+export function statesInPage() {
+  const SKIP = new Set(['SCRIPT', 'STYLE', 'NOSCRIPT', 'LINK', 'META', 'BR', 'PATH', 'G', 'DEFS', 'USE', 'RECT', 'CIRCLE', 'LINE', 'POLYGON', 'TSPAN', 'STOP', 'CLIPPATH']);
+  const pathOf = (el) => {
+    const parts = [];
+    for (let n = el; n && n !== document.body; n = n.parentElement) {
+      parts.unshift(`${n.tagName.toLowerCase()}:${[...n.parentElement.children].indexOf(n) + 1}`);
+    }
+    return parts.join('>');
+  };
+  const out = {};
+  for (const el of document.body.querySelectorAll('*')) {
+    if (SKIP.has(el.tagName.toUpperCase())) continue;
+    const s = getComputedStyle(el);
+    if (s.display === 'none') continue;
+    const r = el.getBoundingClientRect();
+    if (r.width < 8 || r.height < 8) continue;
+    const tag = el.tagName.toLowerCase();
+    out[pathOf(el)] = {
+      cls: String(el.getAttribute('class') || '').split(/\s+/).filter(Boolean).slice(0, 2).join('.'),
+      box: [Math.round(r.left), Math.round(r.top), Math.round(r.width), Math.round(r.height)], // viewport-relative
+      o: +(+s.opacity).toFixed(2),
+      v: s.visibility === 'hidden' ? 0 : 1,
+      t: s.transform === 'none' ? '' : s.transform,
+      c: s.clipPath === 'none' ? '' : s.clipPath,
+      f: s.filter === 'none' ? '' : s.filter,
+      pos: s.position === 'fixed' || s.position === 'sticky' ? s.position : undefined,
+      media: ['img', 'video', 'canvas', 'svg', 'iframe'].includes(tag) ? tag : undefined,
+    };
+  }
+  return out;
+}
+
+// Wait until nothing moves: layout + opacity + transform unchanged for 3 polls (video/canvas ignored).
+// Endless loops (a floating helmet, a marquee) would never settle, so an element that changed on at least
+// 90% of polls after the first second counts as "continuous" and is ignored from then on.
+export async function waitStill(page, { timeout = 4000, interval = 80 } = {}) {
+  const changed = () => withTimeout(page.evaluate(() => {
+    const prev = window.__labSig || new Map();
+    const next = new Map();
+    const out = [];
+    let i = 0;
+    const H = innerHeight;
+    for (const el of document.body.querySelectorAll('*')) {
+      i++;
+      if (['VIDEO', 'CANVAS', 'SCRIPT', 'STYLE'].includes(el.tagName)) continue;
+      // Only what is on (or just around) the screen can matter for a screenshot; reading styles for the
+      // whole document on every poll was the main cost of scoring (thousands of elements, every 80-120ms).
+      const r = el.getBoundingClientRect();
+      if (r.bottom < -200 || r.top > H + 200 || (r.width === 0 && r.height === 0)) continue;
+      const s = getComputedStyle(el);
+      if (s.display === 'none') continue;
+      const str = `${Math.round(r.top)}|${Math.round(r.left)}|${s.opacity}|${s.transform}`;
+      next.set(i, str);
+      if (prev.size && prev.get(i) !== str) out.push(i);
+    }
+    window.__labSig = next;
+    return { out, y: Math.round(scrollY) };
+  }), 15000, 'waitStill poll');
+  await withTimeout(page.evaluate(() => { window.__labSig = undefined; }), 15000, 'waitStill reset');
+  await changed();
+  const start = Date.now();
+  const counts = new Map();
+  let polls = 0, quiet = 0, lastY = null;
+  while (Date.now() - start < timeout) {
+    await page.waitForTimeout(interval);
+    const { out, y } = await changed();
+    polls++;
+    out.forEach((k) => counts.set(k, (counts.get(k) || 0) + 1));
+    const continuous = (k) => polls >= 8 && counts.get(k) >= polls * 0.9;
+    const real = out.filter((k) => !continuous(k));
+    quiet = real.length === 0 && y === lastY ? quiet + 1 : 0;
+    lastY = y;
+    if (quiet >= 2) return { settled: true, ms: Date.now() - start, continuous: [...counts].filter(([k]) => continuous(k)).length };
+  }
+  return { settled: false, ms: Date.now() - start };
+}
+
+// Wait only for the scroll position to stop moving (smooth-scroll easing): cheap, usually 100-600ms.
+async function scrollSettled(page, maxMs = 1500) {
+  const start = Date.now();
+  let last = null, same = 0;
+  while (Date.now() - start < maxMs) {
+    const y = await withTimeout(page.evaluate(() => scrollY), 10000, 'scrollY');
+    same = y === last ? same + 1 : 0;
+    last = y;
+    if (same >= 2) break;
+    await page.waitForTimeout(50);
+  }
+  return last;
+}
+// Smooth-scroll libraries scale wheel input (Lenis wheelMultiplier 0.7 moves 315px for a 450px wheel). Retrying
+// with the remainder took 5-6 glides of ~0.9s each per step, which was most of every scoring run. The page's
+// scroll-per-wheel-pixel is learned from the first unclamped move and used to size the next wheels, so a step
+// is one glide.
+const wheelGain = new WeakMap();
+export async function wheelTo(page, y, vp, { settle = false } = {}) {
+  await page.mouse.move(Math.round(vp.width * 0.02), Math.round(vp.height * 0.98)); // away from hover effects
+  const max = await withTimeout(page.evaluate(() => document.documentElement.scrollHeight - innerHeight), 10000, 'scrollMax');
+  let at = await scrollSettled(page);
+  for (let i = 0; i < 4 && Math.abs(y - at) >= 2; i++) {
+    const gain = wheelGain.get(page) || 1;
+    const want = y - at;
+    await withTimeout(page.mouse.wheel(0, want / gain), 10000, 'wheel');
+    const now = await scrollSettled(page);
+    const moved = now - at;
+    const clamped = now <= 1 || now >= max - 1;
+    if (!clamped && Math.abs(want) > 20 && Math.abs(moved) > 5 && Math.sign(moved) === Math.sign(want)) {
+      const learned = (gain * moved) / want;
+      if (learned > 0.1 && learned < 10) wheelGain.set(page, learned);
+    }
+    at = now;
+  }
+  if (Math.abs(at - y) >= 2) { // pages that swallow wheel events
+    await withTimeout(page.evaluate((yy) => window.scrollTo(0, yy), y), 10000, 'scrollTo');
+    await scrollSettled(page);
+  }
+  if (settle) await waitStill(page, { timeout: 2000 });
+  return withTimeout(page.evaluate(() => scrollY), 10000, 'scrollY');
+}

package/scripts/motion.mjs

@@ -0,0 +1,239 @@
+// Motion inventory from the live runtime: what moves, what drives it, with what parameters.
+// Reads library state after the intro finishes, so the numbers are the site's real settings, not guesses:
+//   - GSAP: every ScrollTrigger (trigger, start/end, scrub, pin, toggleActions) with its full timeline,
+//     pointer-driven tweens (gsap.quickTo), endless loops, other standalone tweens
+//   - Lenis options (constructor intercepted), Swiper params, CSS animations/transitions
+//   - a pointer probe: which elements move or change when the cursor moves
+// Records parameters only (targets, ranges, durations, easing); the site's code itself is never saved.
+//
+// usage: node scripts/motion.mjs <name> [--viewport desktop|tablet|mobile]
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { VIEWPORTS, parseArgs, openBrowser, newPage, waitStill, statesInPage } from './lib.mjs';
+
+const { pos, flags } = parseArgs(process.argv.slice(2));
+const [name] = pos;
+if (!name) {
+  console.error('usage: npm run motion -- <name> [--viewport desktop]');
+  process.exit(1);
+}
+const ref = path.resolve('sites', name, 'reference');
+const meta = JSON.parse(await fs.readFile(path.join(ref, 'meta.json'), 'utf8'));
+const vp = VIEWPORTS.find((v) => v.name === (flags.viewport || 'desktop'));
+
+// Runs before any page script: intercept constructors whose options are not reachable afterwards.
+const INIT = () => {
+  const wrap = (globalName, store) => {
+    let value;
+    Object.defineProperty(window, globalName, {
+      configurable: true,
+      get() { return value; },
+      set(v) {
+        value = typeof v !== 'function' ? v : new Proxy(v, {
+          construct(target, args) {
+            const safe = JSON.parse(JSON.stringify(args[0] || {}, (k, x) => (typeof x === 'function' ? `[function ${x.name || 'anonymous'}]` : x instanceof Element ? `[element ${x.tagName.toLowerCase()}.${x.className}]` : x)));
+            (window[store] = window[store] || []).push(safe);
+            return Reflect.construct(target, args);
+          },
+        });
+      },
+    });
+  };
+  wrap('Lenis', '__labLenis');
+};
+
+function inventory() {
+  const pathOf = (el) => {
+    const parts = [];
+    for (let n = el; n && n !== document.body && n.parentElement; n = n.parentElement) parts.unshift(`${n.tagName.toLowerCase()}:${[...n.parentElement.children].indexOf(n) + 1}`);
+    return parts.join('>');
+  };
+  const sel = (el) => (el instanceof Element ? `${el.tagName.toLowerCase()}${String(el.getAttribute('class') || '').split(/\s+/).filter(Boolean).slice(0, 3).map((c) => '.' + c).join('')}` : null);
+  const section = (el) => {
+    if (!(el instanceof Element)) return null;
+    let n = el;
+    while (n.parentElement && n.parentElement !== document.body && !['MAIN'].includes(n.parentElement.tagName) && n.parentElement.children.length === 1) n = n.parentElement;
+    for (let p = el; p && p !== document.body; p = p.parentElement) {
+      if (/section|footer|header/i.test(p.tagName) || /(^|\s)section[_-]/.test(String(p.getAttribute('class') || ''))) return sel(p);
+    }
+    return null;
+  };
+  const target = (el) => (el instanceof Element ? { sel: sel(el), path: pathOf(el), section: section(el) } : { kind: typeof el });
+  const easeName = (e) => (typeof e === 'string' ? e : typeof e === 'function' ? (e.custom ? 'CustomEase' : e.name || 'function') : e);
+  const clean = (vars) => {
+    const out = {};
+    for (const [k, v] of Object.entries(vars || {})) {
+      if (['scrollTrigger', 'onComplete', 'onUpdate', 'onStart', 'callbackScope', 'data', 'id', 'parent'].includes(k)) continue;
+      if (k === 'ease') { out.ease = easeName(v); continue; }
+      if (k === 'startAt') { out.startAt = clean(v); continue; }
+      if (k === 'stagger' && v && typeof v === 'object') { out.stagger = clean(v); continue; }
+      if (typeof v === 'function') { out[k] = '[function]'; continue; }
+      if (v && typeof v === 'object') continue;
+      out[k] = v;
+    }
+    return out;
+  };
+  const describe = (a, depth = 0) => {
+    if (!a || depth > 6) return null;
+    if (a.getChildren) {
+      return {
+        type: 'timeline', duration: +a.duration().toFixed(3), repeat: a.repeat(), vars: clean(a.vars), labels: a.labels,
+        children: a.getChildren(false, true, true).map((c) => ({ start: +c.startTime().toFixed(3), ...describe(c, depth + 1) })),
+      };
+    }
+    const targets = a.targets();
+    const els = targets.filter((t) => t instanceof Element);
+    return {
+      type: 'tween', duration: +a.duration().toFixed(3), delay: a.delay(), repeat: a.repeat(), yoyo: a.yoyo(),
+      from: Boolean(a.vars.runBackwards), vars: clean(a.vars),
+      targets: els.slice(0, 6).map(target), targetCount: targets.length,
+      split: els.some((e) => /(^|\s)(line|word|char|split)/i.test(String(e.getAttribute('class') || '')) || e.parentElement?.hasAttribute('aria-label')),
+    };
+  };
+
+  const triggers = (window.ScrollTrigger ? ScrollTrigger.getAll() : []).map((st, i) => ({
+    i,
+    trigger: target(st.trigger),
+    start: st.vars.start ?? 'top bottom', end: st.vars.end ?? 'bottom top',
+    startPx: Math.round(st.start), endPx: Math.round(st.end),
+    scrub: st.vars.scrub ?? false,
+    pin: st.pin ? target(st.pin) : null, pinSpacing: st.vars.pinSpacing,
+    toggleActions: st.vars.toggleActions, once: st.vars.once,
+    snap: st.vars.snap ? JSON.stringify(st.vars.snap) : undefined,
+    callbacks: Object.keys(st.vars).filter((k) => k.startsWith('on')),
+    animation: st.animation ? describe(st.animation) : null,
+  }));
+
+  const standalone = window.gsap ? gsap.globalTimeline.getChildren(false, true, true).filter((a) => !a.scrollTrigger) : [];
+  const isElTween = (a) => !a.getChildren && a.targets().some((t) => t instanceof Element);
+  const quickTo = (a) => isElTween(a) && a.paused() && Object.values(a.vars).some((v) => v === '+=0.1');
+  const pointer = standalone.filter(quickTo).map((a) => ({ target: target(a.targets()[0]), prop: Object.keys(a.vars).find((k) => a.vars[k] === '+=0.1'), duration: a.duration(), ease: easeName(a.vars.ease) }));
+  const loops = standalone.filter((a) => a.repeat && a.repeat() === -1).map((a) => describe(a));
+  const other = standalone.filter((a) => !quickTo(a) && !(a.repeat && a.repeat() === -1) && (a.getChildren || isElTween(a))).map((a) => describe(a));
+
+  const swipers = [...document.querySelectorAll('*')].filter((e) => e.swiper).map((e) => {
+    const p = e.swiper.params;
+    const pick = (o, keys) => Object.fromEntries(keys.filter((k) => o[k] !== undefined).map((k) => [k, typeof o[k] === 'object' ? JSON.parse(JSON.stringify(o[k], (kk, v) => (v instanceof Element ? sel(v) : typeof v === 'function' ? '[function]' : v))) : o[k]]));
+    return { el: target(e), slides: e.swiper.slides.length, params: pick(p, ['slidesPerView', 'spaceBetween', 'speed', 'loop', 'grabCursor', 'centeredSlides', 'freeMode', 'effect', 'direction', 'autoplay', 'breakpoints', 'navigation', 'pagination', 'simulateTouch', 'allowTouchMove', 'mousewheel', 'keyboard']) };
+  });
+
+  const css = document.getAnimations().map((a) => ({
+    type: a.constructor.name, name: a.animationName || a.transitionProperty || null,
+    target: a.effect?.target ? target(a.effect.target) : null,
+    duration: a.effect?.getTiming().duration, iterations: a.effect?.getTiming().iterations, easing: a.effect?.getTiming().easing,
+    keyframes: a.constructor.name === 'CSSAnimation' ? a.effect.getKeyframes().slice(0, 6) : undefined,
+  }));
+  const cssGrouped = Object.values(css.reduce((m, a) => { const k = `${a.type}|${a.name}|${a.target?.sel}`; (m[k] = m[k] || { ...a, count: 0 }).count++; return m; }, {}));
+
+  window.__lab = { describe, target };
+  return {
+    libs: {
+      gsap: window.gsap?.version, ScrollTrigger: Boolean(window.ScrollTrigger), SplitText: Boolean(window.SplitText), CustomEase: Boolean(window.CustomEase),
+      Lenis: Boolean(window.Lenis), Swiper: Boolean(window.Swiper), three: window.THREE?.REVISION, jquery: window.jQuery?.fn?.jquery,
+      webflow: Boolean(window.Webflow), hls: Boolean(window.Hls), lottie: Boolean(window.lottie),
+    },
+    lenis: window.__labLenis || [],
+    triggers, pointer, loops, other, swipers, css: cssGrouped,
+  };
+}
+
+const browser = await openBrowser(flags.cdp);
+let result;
+try {
+  const { context, page } = await newPage(browser, vp, { reducedMotion: 'no-preference' });
+  await page.addInitScript(INIT);
+  const t0 = Date.now();
+  await page.goto(meta.url, { waitUntil: 'load', timeout: 60000 });
+  await page.mouse.move(5, vp.height - 5);
+  const intro = await waitStill(page, { timeout: 15000, interval: 200 });
+  const introMs = Date.now() - t0;
+  result = await page.evaluate(inventory);
+
+  // Pointer probe at the top of the page: which elements react when the cursor moves?
+  const probe = async (x, y) => { await page.mouse.move(x, y, { steps: 12 }); await page.waitForTimeout(1600); return page.evaluate(statesInPage); };
+  const a = await probe(Math.round(vp.width * 0.3), Math.round(vp.height * 0.35));
+  const b = await probe(Math.round(vp.width * 0.7), Math.round(vp.height * 0.65));
+  const reactive = Object.keys(b).filter((k) => a[k] && (a[k].t !== b[k].t || a[k].o !== b[k].o || a[k].c !== b[k].c || a[k].f !== b[k].f || a[k].box.join() !== b[k].box.join()))
+    .map((k) => ({ path: k, cls: b[k].cls, media: b[k].media, from: { t: a[k].t, o: a[k].o, c: a[k].c, f: a[k].f, box: a[k].box }, to: { t: b[k].t, o: b[k].o, c: b[k].c, f: b[k].f, box: b[k].box } }));
+  reactive.sort((x, y) => x.path.length - y.path.length);
+  const pruned = [];
+  for (const r of reactive) if (!pruned.some((p) => r.path.startsWith(p.path + '>') && p.cls === r.cls)) pruned.push(r);
+  // Scroll pass: callback-driven animations (onEnter reveals, SplitText) only exist once their trigger fires.
+  // Record every tween/timeline that appears while scrolling, with the scroll position it appeared at.
+  await page.mouse.move(5, vp.height - 5);
+  await page.evaluate(() => {
+    window.__labSeen = new WeakSet();
+    if (window.gsap) gsap.globalTimeline.getChildren(true, true, true).forEach((a) => window.__labSeen.add(a));
+  });
+  const scan = () => page.evaluate(() => {
+    if (!window.gsap) return [];
+    const out = [];
+    for (const a of gsap.globalTimeline.getChildren(true, true, true)) {
+      if (window.__labSeen.has(a)) continue;
+      window.__labSeen.add(a);
+      if (a.scrollTrigger || (a.parent && a.parent !== gsap.globalTimeline)) continue; // children are described with their parent
+      const d = window.__lab.describe(a);
+      const hasEls = d && (d.type === 'timeline' ? JSON.stringify(d).includes('"sel"') : d.targets.length);
+      if (hasEls) out.push({ y: Math.round(scrollY), ...d });
+    }
+    return out;
+  });
+  const created = [];
+  const maxY = await page.evaluate(() => document.documentElement.scrollHeight - innerHeight);
+  for (let y = 0; y <= maxY + vp.height / 4; y += Math.round(vp.height / 4)) {
+    await page.mouse.wheel(0, Math.round(vp.height / 4));
+    for (let k = 0; k < 6; k++) { await page.waitForTimeout(100); created.push(...await scan()); }
+  }
+  // Collapse repeats (same targets + same vars) into one entry with every scroll position it fired at.
+  const groups = new Map();
+  for (const c of created) {
+    const key = JSON.stringify({ ...c, y: 0 });
+    const g = groups.get(key) || { ...c, firedAt: [] };
+    g.firedAt.push(c.y);
+    groups.set(key, g);
+  }
+  const onScroll = [...groups.values()].map(({ y, ...rest }) => rest);
+  result = { url: meta.url, viewport: vp, capturedAt: new Date().toISOString(), intro: { ms: introMs, settled: intro.settled, continuousElements: intro.continuous || 0 }, ...result, pointerReactive: pruned.slice(0, 40), onScroll };
+  await context.close();
+} finally {
+  if (!flags.cdp) await browser.close();
+}
+
+const out = path.join(ref, `motion.${vp.name}.json`);
+await fs.writeFile(out, JSON.stringify(result, null, 2));
+
+// Human-readable digest, grouped by section, for building the clone.
+const lines = [`# Motion inventory: ${meta.url} (${vp.name} ${vp.width}x${vp.height})`, '',
+  `Libraries: ${Object.entries(result.libs).filter(([, v]) => v).map(([k, v]) => (v === true ? k : `${k} ${v}`)).join(', ')}`,
+  `Intro: settled after ${(result.intro.ms / 1000).toFixed(1)} s${result.intro.settled ? '' : ' (did not fully settle)'}; ${result.intro.continuousElements} continuously animating elements.`,
+  `Lenis: ${result.lenis.length ? JSON.stringify(result.lenis) : 'not constructed through the global'}`, ''];
+const tweenLine = (t, indent = '') => {
+  if (!t) return [];
+  if (t.type === 'timeline') return [`${indent}timeline ${t.duration}s${t.repeat ? ` repeat ${t.repeat}` : ''}`, ...t.children.flatMap((c) => tweenLine({ ...c }, indent + '  ').map((l, i) => (i === 0 ? l.replace(/^(\s*)/, `$1@${c.start}s `) : l)))];
+  const props = Object.entries(t.vars).filter(([k]) => !['duration', 'ease', 'delay', 'overwrite', 'immediateRender', 'lazy', 'inherit', 'paused', 'stagger', 'startAt', 'repeat', 'yoyo'].includes(k)).map(([k, v]) => `${k}:${v}`).join(' ');
+  const start = t.vars.startAt ? ` from {${Object.entries(t.vars.startAt).map(([k, v]) => `${k}:${v}`).join(' ')}}` : '';
+  return [`${indent}${t.from ? 'from' : 'to'} [${t.targets.map((x) => x.sel).join(', ')}${t.targetCount > t.targets.length ? ` +${t.targetCount - t.targets.length}` : ''}]${t.split ? ' (split text)' : ''} ${props}${start} | ${t.duration}s ${t.vars.ease || ''}${t.vars.stagger !== undefined ? ` stagger ${JSON.stringify(t.vars.stagger)}` : ''}${t.repeat ? ` repeat ${t.repeat}${t.yoyo ? ' yoyo' : ''}` : ''}`];
+};
+const bySection = {};
+for (const st of result.triggers) (bySection[st.trigger.section || st.trigger.sel || '(no element)'] ||= []).push(st);
+lines.push(`## Scroll-driven (${result.triggers.length} ScrollTriggers)`, '');
+for (const [sec, list] of Object.entries(bySection)) {
+  lines.push(`### ${sec}`, '');
+  for (const st of list) {
+    lines.push(`- trigger \`${st.trigger.sel}\` start "${st.start}" end "${st.end}"${st.scrub !== false ? ` scrub ${st.scrub}` : ''}${st.pin ? ` pin \`${st.pin.sel}\`` : ''}${st.toggleActions ? ` toggleActions "${st.toggleActions}"` : ''}${st.once ? ' once' : ''}${st.callbacks.length ? ` callbacks ${st.callbacks.join(',')}` : ''}`);
+    tweenLine(st.animation, '    ').forEach((l) => lines.push(l));
+  }
+  lines.push('');
+}
+lines.push(`## Created while scrolling (callback-driven: reveals, SplitText, toggles) - ${result.onScroll.length} distinct`, '',
+  ...result.onScroll.flatMap((t) => [`- first at scrollY ${t.firedAt[0]}${t.firedAt.length > 1 ? ` (x${t.firedAt.length})` : ''}`, ...tweenLine(t, '    ')]), '');
+lines.push(`## Pointer-driven (gsap.quickTo)`, '', ...result.pointer.map((p) => `- \`${p.target.sel}\` ${p.prop} ${p.duration}s ${p.ease}`), '');
+lines.push(`## Elements that react to the cursor (probe)`, '', ...result.pointerReactive.map((r) => `- \`${r.cls || r.path}\`${r.media ? ` (${r.media})` : ''}: ${['t', 'o', 'c', 'f'].filter((k) => r.from[k] !== r.to[k]).map((k) => ({ t: 'transform', o: 'opacity', c: 'clip-path', f: 'filter' })[k]).join(', ') || 'position'}`), '');
+lines.push(`## Endless loops`, '', ...result.loops.flatMap((t) => tweenLine(t, '- ')), '');
+lines.push(`## Other standalone tweens/timelines`, '', ...result.other.flatMap((t) => tweenLine(t, '- ')), '');
+lines.push(`## Sliders (Swiper)`, '', ...result.swipers.map((s) => `- \`${s.el.sel}\` ${s.slides} slides ${JSON.stringify(s.params)}`), '');
+lines.push(`## CSS animations / transitions`, '', ...result.css.map((c) => `- ${c.type} ${c.name} on \`${c.target?.sel}\` x${c.count} ${c.duration}ms ${c.easing}${c.iterations === Infinity ? ' infinite' : ''}`), '');
+await fs.writeFile(path.join(ref, `motion.${vp.name}.md`), lines.join('\n'));
+console.log(`libs: ${JSON.stringify(result.libs)}`);
+console.log(`intro ${result.intro.ms}ms settled=${result.intro.settled} | triggers ${result.triggers.length} | created-on-scroll ${result.onScroll.length} | pointer ${result.pointer.length} | cursor-reactive ${result.pointerReactive.length} | loops ${result.loops.length} | other ${result.other.length} | swipers ${result.swipers.length} | css ${result.css.length} | lenis ${result.lenis.length}`);
+console.log(`-> ${path.relative(process.cwd(), out)} and motion.${vp.name}.md`);