@trueclone/cli 0.2.0 → 0.3.0

package/scripts/understand.mjs

@@ -0,0 +1,231 @@
+// Code-level evidence about the reference, with REA (Reverse Engineer Anything, bundled) doing the reading and
+// trueclone owning the browser: which scripts actually run while a visitor scrolls and hovers (V8 coverage), which
+// handler each interactive element has and where its code is (CDP listeners, with the source around it), which
+// endpoints exist in the code (fired during the capture or not), original sources when the site publishes source
+// maps. Written to reference/code.md (for the agent) and reference/code.json. The capture already knows what the
+// page looks like and does; this says which code does it, so script.js copies rules instead of guessing them.
+//
+// usage: node scripts/understand.mjs <name> [--elements 40] [--observe-ms 20000]
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import net from 'node:net';
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { chromium } from 'playwright';
+import { VIEWPORTS, parseArgs, newPage, settle, wheelTo, withTimeout } from './lib.mjs';
+
+const { pos, flags } = parseArgs(process.argv.slice(2));
+const [name] = pos;
+if (!name) {
+  console.error('usage: trueclone understand <name> [--elements 40] [--observe-ms 20000]');
+  process.exit(1);
+}
+const root = path.resolve('sites', name);
+const ref = path.join(root, 'reference');
+const meta = JSON.parse(await fs.readFile(path.join(ref, 'meta.json'), 'utf8'));
+const MAX_ELEMENTS = Number(flags.elements || 40);
+const OBSERVE_MS = Number(flags['observe-ms'] || 20000);
+const vp = VIEWPORTS.find((v) => v.name === 'desktop');
+const require = createRequire(import.meta.url);
+const REA = path.join(path.dirname(require.resolve('rea-agents/package.json')), 'scripts', 'rea.mjs');
+const reaVersion = JSON.parse(await fs.readFile(require.resolve('rea-agents/package.json'), 'utf8')).version;
+
+// REA attaches to a loopback CDP endpoint it does not own: trueclone launches Chrome with a debugging port
+const freePort = () => new Promise((resolve) => { const s = net.createServer(); s.listen(0, '127.0.0.1', () => { const p = s.address().port; s.close(() => resolve(p)); }); });
+const port = await freePort();
+const endpoint = `http://127.0.0.1:${port}`;
+const launch = async () => {
+  const args = [`--remote-debugging-port=${port}`];
+  if (process.env.LAB_BROWSER !== 'chromium') { try { return await chromium.launch({ channel: 'chrome', args }); } catch { /* no Chrome */ } }
+  return chromium.launch({ args });
+};
+const rea = (args, { timeout = 90000, onProgress } = {}) => new Promise((resolve) => {
+  const child = spawn(process.execPath, [REA, ...args, '--format', 'json'], { stdio: ['ignore', 'pipe', 'pipe'] });
+  let out = '', err = '';
+  child.stdout.on('data', (d) => { out += d; });
+  child.stderr.on('data', (d) => { err += d; if (onProgress) for (const line of String(d).split('\n')) if (line.includes('rea_progress')) onProgress(line); });
+  const timer = setTimeout(() => { try { child.kill(); } catch { /* gone */ } }, timeout);
+  child.on('close', (code) => {
+    clearTimeout(timer);
+    let json = null;
+    try { json = JSON.parse(out); } catch { /* not JSON: an error */ }
+    const errText = err.split('\n').filter((l) => l && !l.includes('rea_progress')).join('\n').slice(0, 600);
+    resolve({ code, json, result: json?.normalized_result || null, err: errText || (json ? '' : `exit ${code}: ${out.slice(0, 400)}`) });
+  });
+});
+
+// origins whose scripts count: the page's own and every origin that served a script during the capture
+const har = await fs.readFile(path.join(ref, 'desktop.har'), 'utf8').then(JSON.parse).catch(() => null);
+const harEntries = har?.log?.entries || [];
+const origins = new Set([new URL(meta.url).origin]);
+for (const e of harEntries) if (e._resourceType === 'script') { try { origins.add(new URL(e.request.url).origin); } catch { /* data: */ } }
+const originArgs = [...origins].flatMap((o) => ['--allowed-origins', o]); // one flag per origin
+const fired = new Set(harEntries.map((e) => e.request.url.split('?')[0]));
+
+const browser = await launch();
+const out = { name, url: meta.url, at: new Date().toISOString(), rea: reaVersion, scripts: [], handlers: [], endpoints: [], sourceMaps: [], unknowns: [], notes: [] };
+try {
+  const { page } = await newPage(browser, vp, { reducedMotion: 'no-preference' });
+  await page.goto(meta.url, { waitUntil: 'load', timeout: 60000 });
+  await settle(page, meta.hide || []);
+  await page.evaluate(() => window.scrollTo(0, 0));
+  await page.waitForTimeout(500);
+
+  const targets = await rea(['list-browser-targets', endpoint, ...originArgs]);
+  const target = (targets.result?.targets || []).find((t) => (t.url || '').startsWith(meta.url.replace(/\/$/, ''))) || (targets.result?.targets || [])[0];
+  if (!target) throw new Error(`REA found no page target at ${endpoint}: ${targets.err || 'no output'}`);
+  const tid = target.target_id;
+
+  // 1. the bundle: scripts, chunk edges, endpoints and routes in the code, source maps when published
+  const bundle = await rea(['analyze-web-bundle', endpoint, tid, '--fetch-source-maps', '--observation-ms', '1500', ...originArgs], { timeout: 180000 });
+  const obs = bundle.result?.observations || {};
+  const nodes = obs.chunks?.nodes || [];
+  const byKey = new Map(nodes.map((n) => [n.script_key, n]));
+  // an endpoint is a URL or a path; a `.get("EXT_blend_minmax")` on a WebGL context is not one
+  const TRACKING = /google-analytics|googletagmanager|doubleclick|facebook\.(com|net)|hotjar|segment\.(io|com)|plausible|cloudflareinsights|clarity\.ms|sentry|datadog|mixpanel|amplitude|posthog|intercom|hubspot|challenges\.cloudflare|recaptcha|hcaptcha|turnstile/i;
+  const urlish = (v) => /^(https?:)?\/\/[^\s]+$/.test(v) || /^\.{0,2}\/[\w./-]+/.test(v) || /^wss?:\/\//.test(v);
+  out.endpoints = (obs.endpoints || []).filter((e) => typeof e.value === 'string' && urlish(e.value.trim()) && !/^(call:.*\.get|call:.*\.request)$/.test(e.mechanism || '') || /fetch|xhr|websocket|axios|beacon/i.test(e.mechanism || '') && urlish(String(e.value)))
+    .map((e) => ({ value: e.value, mechanism: e.mechanism, script: byKey.get(e.location?.script_key)?.url || e.location?.script_key, line: e.location?.line, fired: fired.has(String(e.value).split('?')[0]), tracking: TRACKING.test(e.value) }));
+  out.routes = (obs.routes || []).map((r) => r.value || r.path || JSON.stringify(r)).slice(0, 40);
+  out.sourceMaps = (obs.source_maps?.items || []).map((m) => ({ script: byKey.get(m.script_key)?.url || m.script_key, status: m.status, sources: (m.sources || m.original_sources || []).slice(0, 20) }));
+  out.unknowns.push(...(bundle.result?.unknowns || []).map((u) => `${u.dimension}: ${u.reason}`));
+  if (!bundle.result) out.notes.push(`analyze-web-bundle gave no result: ${bundle.err}`);
+
+  // 2. what ran: coverage while trueclone scrolls through the page and hovers what a visitor hovers
+  const interactive = await page.evaluate((max) => {
+    const SEL = 'a[href], button, [role="button"], [role="tab"], summary, input, select, textarea, [tabindex]:not([tabindex="-1"])';
+    const uniq = (el) => {
+      if (el.id && document.querySelectorAll(`#${CSS.escape(el.id)}`).length === 1) return `#${CSS.escape(el.id)}`;
+      const parts = [];
+      for (let n = el; n && n !== document.body; n = n.parentElement) {
+        const i = [...n.parentElement.children].indexOf(n) + 1;
+        parts.unshift(`${n.tagName.toLowerCase()}:nth-child(${i})`);
+      }
+      return `body > ${parts.join(' > ')}`;
+    };
+    const seen = new Set();
+    const list = [];
+    // a plain link navigates; it only has behaviour when it is wired to something (a hash, no real href, aria/data hooks)
+    const behaves = (el) => el.tagName !== 'A' || /^(#|javascript:|$)/.test((el.getAttribute('href') || '').trim()) || [...el.attributes].some((a) => /^(data-|aria-controls|aria-expanded|role)/.test(a.name));
+    for (const el of document.querySelectorAll(SEL)) {
+      const r = el.getBoundingClientRect();
+      if (r.width < 4 || r.height < 4 || r.top + scrollY < 0 || !el.checkVisibility?.() || !behaves(el)) continue;
+      const sig = `${el.tagName}.${el.className}`;
+      if (seen.has(sig) && list.length > max / 2) continue; // repeated rows share handlers: a few of each is enough
+      seen.add(sig);
+      list.push({ selector: uniq(el), label: `${el.tagName.toLowerCase()}${el.className ? `.${String(el.className).trim().split(/\s+/).slice(0, 2).join('.')}` : ''}`, text: (el.textContent || '').trim().slice(0, 40), x: Math.round(r.left + r.width / 2), y: Math.round(r.top + scrollY + r.height / 2) });
+      if (list.length >= max) break;
+    }
+    // delegated handlers live on the roots: a click on any row is handled here
+    for (const sel of ['body', 'html']) list.push({ selector: sel, label: sel, text: '', x: 2, y: 2, root: true });
+    return list;
+  }, MAX_ELEMENTS);
+
+  let armed = false;
+  const observing = rea(['observe-web-execution', endpoint, tid, '--observation-ms', String(OBSERVE_MS), ...originArgs], { timeout: OBSERVE_MS + 60000, onProgress: (l) => { if (l.includes('armed')) armed = true; } });
+  for (let i = 0; i < 50 && !armed; i++) await page.waitForTimeout(100);
+  const t0 = Date.now();
+  const max = await page.evaluate(() => document.documentElement.scrollHeight - innerHeight);
+  const step = Math.round(vp.height / 2);
+  for (let y = step; y <= max && Date.now() - t0 < OBSERVE_MS * 0.6; y += step) { await wheelTo(page, y, vp); await page.waitForTimeout(150); }
+  for (const el of interactive.filter((e) => !e.root).slice(0, 12)) {
+    if (Date.now() - t0 > OBSERVE_MS * 0.9) break;
+    await page.evaluate((y) => window.scrollTo(0, Math.max(0, y - innerHeight / 2)), el.y);
+    await page.waitForTimeout(120);
+    const vy = el.y - (await page.evaluate(() => scrollY));
+    await page.mouse.move(el.x, vy, { steps: 4 }).catch(() => {});
+    await page.waitForTimeout(250);
+  }
+  await page.evaluate(() => window.scrollTo(0, 0));
+  const exec = await observing;
+  const cov = exec.result?.coverage || {};
+  const sourceText = new Map();
+  for (const s of exec.result?.sources || []) if (s.source?.text) sourceText.set(String(s.script_id), { url: s.url, text: s.source.text });
+  // scripts without a URL are the page's inline <script> blocks, or the automation's own helpers: only the former count
+  const rendered = await fs.readFile(path.join(ref, 'rendered.html'), 'utf8').catch(() => '');
+  const inlineIndex = new Map();
+  const labelOf = (s) => {
+    if (s.reported_url) return s.reported_url;
+    const text = sourceText.get(String(s.script_id))?.text || '';
+    const head = text.trim().slice(0, 80);
+    if (!head || !rendered.includes(head)) return null;
+    if (!inlineIndex.has(head)) inlineIndex.set(head, inlineIndex.size + 1);
+    return `inline <script> #${inlineIndex.get(head)} ("${head.slice(0, 40).replace(/\s+/g, ' ')}…")`;
+  };
+  out.scripts = (cov.scripts || []).map((s) => {
+    const url = labelOf(s);
+    if (!url) return null;
+    const fns = s.functions || [];
+    const ran = fns.filter((f) => f.ranges?.some((r) => r.count > 0)).map((f) => f.name).filter(Boolean);
+    return { url, functionsRan: ran.length, functions: fns.length, bytes: sourceText.get(String(s.script_id))?.text.length || null, ranNames: ran.slice(0, 12) };
+  }).filter(Boolean).sort((a, b) => b.functionsRan - a.functionsRan);
+  if (!exec.result) out.notes.push(`observe-web-execution gave no result: ${exec.err}`);
+
+  // 3. handlers: the listener on each interactive element and the code around it
+  // readable source: lines around the handler; in a minified one-line bundle, a window of characters around the column
+  const excerpt = (text, line, column = 0, before = 3, after = 22) => {
+    const lines = text.split('\n');
+    const at = lines[line] || '';
+    if (at.length > 400) {
+      const from = Math.max(0, column - 500), to = Math.min(at.length, column + 900);
+      return `${line + 1}:${column}  (minified, ${at.length} chars on this line; ${from}-${to} shown)\n${at.slice(from, to).replace(/;/g, ';\n')}`;
+    }
+    const from = Math.max(0, line - before);
+    return lines.slice(from, Math.min(lines.length, line + after)).map((l, i) => `${String(from + i + 1).padStart(5)}  ${l.length > 160 ? `${l.slice(0, 160)}…` : l}`).join('\n');
+  };
+  const seenLoc = new Map();
+  for (const el of interactive) {
+    const r = await rea(['inspect-web-event-listeners', endpoint, tid, el.selector, ...originArgs], { timeout: 60000 });
+    const listeners = r.result?.listeners || [];
+    for (const s of r.result?.sources || []) if (s.source?.text && !sourceText.has(String(s.script_id))) sourceText.set(String(s.script_id), { url: s.url, text: s.source.text });
+    const entry = { selector: el.selector, label: el.label, text: el.text, y: el.y, listeners: [] };
+    for (const l of listeners) {
+      const loc = l.location || {};
+      const key = `${loc.url}:${loc.line_number}:${loc.column_number}`;
+      const src = sourceText.get(String(loc.script_id));
+      const listener = { type: l.type, url: loc.url, line: (loc.line_number ?? 0) + 1, column: loc.column_number, fn: loc.function_name || null, sharedWith: seenLoc.get(key) || null, code: !seenLoc.has(key) && src ? excerpt(src.text, loc.line_number ?? 0, loc.column_number ?? 0) : null };
+      if (!seenLoc.has(key)) seenLoc.set(key, el.label);
+      entry.listeners.push(listener);
+    }
+    if (!listeners.length && r.result?.selected_node?.match === 'found') entry.note = 'no direct listener: delegated (an ancestor, a framework root) or CSS-only';
+    if (!r.result) entry.note = `not inspected: ${r.err.split('\n')[0] || 'no output'}`;
+    out.handlers.push(entry);
+  }
+} finally {
+  await browser.close();
+}
+
+// code.md
+const md = [];
+md.push(`# ${name}: code evidence`, '', `Reference ${meta.url}, read ${out.at} with REA ${out.rea} through \`trueclone understand\` (trueclone owned the browser; REA observed, never clicked or evaluated). Observed facts only; what REA could not see is under Unknowns.`, '');
+md.push('## Scripts, by how much of them ran while scrolling the page and hovering its controls', '', '| script | functions that ran | of | names |', '|---|---|---|---|');
+for (const s of out.scripts) md.push(`| ${s.url} | ${s.functionsRan} | ${s.functions} | ${s.ranNames.join(', ')} |`);
+if (!out.scripts.length) md.push('| (no coverage captured) | | | |');
+md.push('', 'A script with nothing that ran is not needed for what the page does on a scroll-through; start from the ones at the top.', '');
+md.push('## Handlers on interactive elements', '', 'What `script.js` has to reproduce, with the original code around each handler (read the rule, write your own). Elements that share one handler are listed once.', '');
+for (const h of out.handlers) {
+  const direct = h.listeners.filter((l) => !l.sharedWith);
+  const shared = h.listeners.filter((l) => l.sharedWith);
+  if (!h.listeners.length && !h.note) continue;
+  md.push(`### \`${h.label}\`${h.text ? ` "${h.text}"` : ''} at y ${h.y}`, '', `selector: \`${h.selector}\``);
+  if (h.note) md.push(`- ${h.note}`);
+  for (const l of shared) md.push(`- ${l.type} → ${l.url}:${l.line} (same handler as \`${l.sharedWith}\`)`);
+  for (const l of direct) {
+    md.push(`- ${l.type} → ${l.url}:${l.line}${l.fn ? ` (${l.fn})` : ''}`);
+    if (l.code) md.push('', '```js', l.code, '```');
+  }
+  md.push('');
+}
+md.push('## Endpoints in the code', '', '| endpoint | how | where | fired during the capture |', '|---|---|---|---|');
+for (const e of out.endpoints) md.push(`| ${e.value} | ${e.mechanism}${e.tracking ? ' (tracking: never copied)' : ''} | ${e.script}:${e.line ?? '?'} | ${e.fired ? 'yes (response in desktop.har)' : 'no: a form, a later state or a condition the capture did not reach'} |`);
+if (!out.endpoints.length) md.push('| (none found in the scripts) | | | |');
+if (out.routes?.length) md.push('', `Routes in the code: ${out.routes.join(', ')}`);
+md.push('', '## Source maps', '');
+md.push(out.sourceMaps.length ? out.sourceMaps.map((m) => `- ${m.script}: ${m.status}${m.sources.length ? `; originals: ${m.sources.join(', ')}` : ''}`).join('\n') : '- none published: the scripts are read as shipped (minified where minified)');
+md.push('', '## Unknowns', '');
+md.push([...out.unknowns, ...out.notes].length ? [...out.unknowns, ...out.notes].map((u) => `- ${u}`).join('\n') : '- none reported');
+md.push('', 'Deeper, by hand: `npx trueclone rea <command>` (REA\'s own CLI; `npx trueclone rea --help`).', '');
+await fs.writeFile(path.join(ref, 'code.md'), md.join('\n'));
+await fs.writeFile(path.join(ref, 'code.json'), JSON.stringify(out, null, 2));
+console.log(`understand: ${out.scripts.length} script(s) with coverage (${out.scripts.filter((s) => s.functionsRan).length} ran), ${out.handlers.filter((h) => h.listeners.length).length}/${out.handlers.length} elements with a direct handler, ${out.endpoints.length} endpoint(s) in code (${out.endpoints.filter((e) => e.fired).length} fired), ${out.sourceMaps.length} source map(s)`);
+console.log(`-> ${path.relative(process.cwd(), path.join(ref, 'code.md'))}`);

package/skill/SKILL.md

@@ -10,7 +10,7 @@ Everything for a site lives in `sites/<name>/` (gitignored, stays local):
 - `next/`: the same site as a Next.js + Tailwind v4 + shadcn app, generated from `clone/`.
 - `design-tokens.json`: the **one canonical source** of the design system, rendered to `DESIGN.md` (Google design.md format, linted), `globals.css` (shadcn theme) and `clone/tokens.css`.
 - `REPORT.md`: every score against its target, what to fix first, what was not copied. This is the deliverable.
-- `notes.md`: your notes: stack, motion inventory, decisions, known gaps.
+- `notes.md`: your record, written by the seed with fixed sections; `REPORT.md` reads Findings and Accepted differences from it (see 2).
 
 Run every step as `npx trueclone <step> <name>` from the project folder (`npx trueclone help` lists them).
 
@@ -30,8 +30,11 @@ npx trueclone capture <url> [name] [--hide "<cookie banner / popup selectors>"]
 npx trueclone states <name>      # live scroll states + motion inventory (animations running)
 npx trueclone motion <name>      # animation runtime: ScrollTriggers, timelines, reveals, cursor tweens, loops, Lenis/Swiper, CSS
 npx trueclone spec <name>        # measured boxes and styles per viewport
+npx trueclone understand <name>  # code evidence with REA: which scripts ran, each control's handler with its source -> code.md
 ```
 
+`states`, `motion`, `spec` and `understand` only read the reference: run them together in the background while you read the capture.
+
 `npx trueclone <url> [name]` is a shortcut for capture + design-system draft.
 
 `reference/` then holds:
@@ -46,14 +49,25 @@ Read the motion inventory before building. Each entry is a behaviour the clone m
 
 If the page is blank or blocked, capture through your own Chrome over CDP (`chrome --remote-debugging-port=9222 --user-data-dir=.chrome-profile`, then `--cdp`). Never try to get past bot checks, logins or paywalls.
 
-## 2. Understand it with REA
+## 2. Understand it
+
+```powershell
+npx trueclone understand <name>   # code evidence with REA -> reference/code.md (2-4 min; run it with states/motion/spec)
+```
+
+The capture says what the page looks like and does; `code.md` says **which code does it**. trueclone owns the browser and drives REA (Reverse Engineer Anything, bundled) for you; you never call REA directly for this. `code.md` has:
+- the scripts ranked by how much of them ran while scrolling the page and hovering its controls: a script with nothing that ran is not needed for what you are rebuilding;
+- every interactive element's handler, with the original code around it (`click → engine.js:412` and the twenty lines there), plus the delegated handlers on `body`/`html`: **read the rule, write your own**. When `code.md` has the handler, copy the rule (its constants, its conditions), never guess it from recorded effects;
+- the endpoints that exist in the code, fired during the capture or not (a form's POST, a filter's fetch): they go into the report's "Not copied";
+- original sources when the site publishes source maps (most don't);
+- what REA could not see (delegated handlers through a framework, minified names) under Unknowns.
 
-trueclone bundles REA (Reverse Engineer Anything). `npx @trueclone/cli init` registers it as an MCP server; without MCP, run `npx trueclone rea <command>`. With the page open in your CDP Chrome:
-- `inspect_web_page`: DOM, scripts, resources.
-- `analyze_web_bundle` with source maps: framework, vendors (GSAP, ScrollTrigger, Lenis, Swiper, Webflow IX2, three.js), routes and API endpoints.
-- `inspect_web_event_listeners`: hover, drag, wheel and click logic.
+For the part no capture or listener reaches (a bundled physics rule, a shader, a module's data flow), REA's own CLI is one command away: `npx trueclone rea --help`. Record what you learn in `notes.md` under Behaviours and Unknowns.
 
-Use REA when the capture can't tell you how something works: a behaviour's exact rule, bundled shader or physics code, the API a component calls. Write `notes.md`: stack, breakpoints, and the motion inventory turned into a list of behaviours (trigger, property, range).
+**`notes.md` is a contract**, not a diary. The seed writes it with six sections, and `REPORT.md` reads two of them back:
+- Stack, Behaviours (one line per motion entry and interaction: element, trigger, property, range, timing), Own-code map (file → behaviours → where each parameter came from), Unknowns;
+- **Findings**: defects in the tool you met (symptom, cause, workaround). They appear in `REPORT.md` and are how the tool gets fixed;
+- **Accepted differences**: what cannot or should not match, one per line with the why (`detail desktop hero chips: random walk on both sides`). A check below target that is covered by an entry naming it (and its width) is marked "accepted" in `REPORT.md` instead of "below target". Every entry needs a reason that would convince the site's owner; an entry without one is a gap you are hiding.
 
 ## 3. Design system
 
@@ -69,20 +83,26 @@ Review the draft: role names, the `notes` prose (overview, do's and don'ts), any
 **Start every clone from the mirror** (both modes):
 
 ```powershell
-npx trueclone reveals <name>   # records scroll reveals frame by frame + class changes caused by scrolling (any library)
+npx trueclone reveals <name>   # records, at all three widths: scroll reveals frame by frame, scroll-linked curves (parallax), pins, class changes
 npx trueclone widgets <name>   # clicks every tab and menu and records each state (they often aren't in the page until clicked)
 npx trueclone seed <name>      # clone/ from the script-free mirror; replays what reveals and widgets recorded
 ```
 
-- **Exact mode:** the site's own markup, text, stylesheets and media at local paths.
+- **Exact mode:** the site's own markup, text, stylesheets and media at local paths. The mirror fetches media the capture never saw (lazy images, hover and state images, fonts behind `@import`), so nothing points at the site.
 - **Template mode:** the same markup and stylesheets, but every text becomes lorem words of the same laid-out width (lines break where the reference's break), every image, video, large SVG and iframe a same-size placeholder, CSS backgrounds a transparent one, every link `#`, brand metadata and tracking hints dropped. No text or media of the site ends up in `clone/`; fonts stay for local study (swap licensed fonts before reusing the result).
-- **Recorded behaviour comes with it:** one-shot scroll reveals replay their measured curve (delay, duration, easing, spring overshoot) with the Web Animations API, and scroll class changes (a header that gets its backdrop past 12px) toggle the same classes at the same point. Both live in `clone/trueclone-reveals.js`; don't rewrite them by hand.
+- **Recorded behaviour comes with it:** one-shot scroll reveals replay their measured curve (delay, duration, easing, spring overshoot) with the Web Animations API; scroll-linked curves (parallax, a scrubbed fade) follow the scroll position through the recorded samples; scroll class changes (a header that gets its backdrop past 12px) toggle the same classes at the same point. Every record exists per width, and the player uses the visitor's width, so phone offsets are never desktop pixels. All of it lives in `clone/trueclone-reveals.js`; don't rewrite it by hand. When your own script must drive an element the player also drives (a hero scene you rebuild whole), hand it over: `el.removeAttribute('data-tc-reveal')` / `'data-tc-scrub'` / `'data-tc-class'` at the start of `script.js`; the player leaves it alone and its recorded starting state (a stylesheet rule on the mark) goes with the mark. Never let both run on one element.
+- **Runtime artefacts are cleaned:** the mirror is a snapshot taken after the site's scripts ran. The seed turns every GSAP pin into its CSS equivalent, a `position: sticky; top: 0` element inside a spacer whose padding is the pin distance (`[data-tc-pin-spacer]` around `[data-tc-runtime="pin"][data-tc-pin="<px>"]`), so layout and scroll states hold with no script. Animate inside it as it is; if you must recreate the pin with ScrollTrigger (`pin: true`), unwrap the spacer and clear the sticky style first, or the page gets both. `reveals` lists transform-driven pins with their start and end positions. Every `<canvas>` is marked `data-tc-runtime="canvas"` (its buffer size is dropped when CSS sizes it; your scene sets it). Regions a script builds at runtime (a grid a hero script assembles) are captured in their built state: your script owns them, so rebuild them from the captured markup rather than beside it.
+- **Per-width values come with it:** the capture reads every inline style at all three widths. What a script set differently per width (a container's computed height, a card's offset, a custom property, a pin distance) becomes a media-query rule on `[data-tc-w]` elements (`<style id="tc-width-styles">`), and a pin whose distance changes per width carries `data-tc-pin-desktop/tablet/mobile`. Open shadow roots (web components, a Webflow code island) are carried as declarative shadow DOM (`<template shadowrootmode="open">` inside the host), so they render with no script.
 - **Recorded widgets come with it too** (template mode): every tab set and expandable menu, with each state the original showed after a click, placeholdered like the page. `clone/trueclone-widgets.js` swaps the region on click (menus in a header or nav also on hover). Popovers rendered in a portal (comboboxes, tooltips) are listed as not replayed: build those in `script.js`. In interaction scenarios, `selector@n` picks the n-th match in `at`, `click` and `expectChange`; mind hidden duplicates (a mobile menu button is often the first match).
 
+**Never edit `clone/index.html` by hand.** It is seed output and every re-seed rewrites it. Anything a clone needs on top of the seed goes in `clone/patches/`, applied by the seed in name order: `head-*.html` before `</head>`, `*.css` linked before `</head>` (after the site's stylesheets), `body-*.html` before the clone's own `<script src="script.js">` (vendored libraries, a hand-over prelude), `*.js` as a deferred script before `script.js`. A fix that needs the generated markup to change is a missing seed feature: report it in `notes.md` under Findings.
+
 Then write `clone/script.js`: every remaining interaction in your own code, using the parameters you read from the reference (timings, physics constants, offsets, breakpoints). Never copy the site's scripts. JS-set initial states, such as a `<details>` closed on phones, are part of the layout, so check every viewport. Data the page fetches live (a star count, a feed) stays as captured; no requests to third parties.
 
 A seed is where layout ends up at 99%+ with zero hand-written CSS; your work is behaviour. Build by hand (below) only what the mirror can't carry.
 
+After each build round, `npx trueclone owned <name>` lists the sections your script rebuilds at boot (the clone loaded with scripts blocked vs running). Those are yours: hand their marks over to `script.js` and hide them until boot if the original hides them too. Everything else stays with the seed's players.
+
 **Building parts by hand:**
 
 - `styles.css` starts with `@import url("tokens.css");` and uses its variables. Never hard-code a token value.
@@ -105,6 +125,8 @@ A seed is where layout ends up at 99%+ with zero hand-written CSS; your work is
 ```powershell
 npx trueclone score <name> --quick   # layout, desktop states, interactions: the loop while building (about a minute)
 npx trueclone score <name>           # everything, in parallel groups, then REPORT.md
+npx trueclone score <name> --only detail,load --viewport desktop   # after a fix: just the checks it can move, at that width
+npx trueclone explain <name> <y>     # one place on the page: what every check saw there + a reference|clone|diff crop
 ```
 
 The steps, if you need one alone:
@@ -118,13 +140,20 @@ npx trueclone interact <name> --draft              # interactions.draft.json: fi
 npx trueclone interact <name>                      # interactions: click/hover/drag/key scenarios + expectChange (geometry, text, state attributes, canvas pixels)
 npx trueclone detail <name> --viewport all         # styles at matching points: font, size, weight, line height, colour, boxes
 npx trueclone hovers <name>                        # hover effects present on the reference but missing on the clone
+npx trueclone load <name>                          # load sequence: how settled each side is 0.25-4 s after navigation (cold cache, same network)
 ```
 
 Reference measurements are cached until the next capture, so only the clone is re-measured. Sites without scroll/time motion or without interactions simply skip those steps.
 
-Fix in this order: page height drift, the worst layout section, the worst state step, the lowest motion curve, any interaction marked FAIL, then detail and hovers. `REPORT.md` lists them under "Fix first". For a drift, compare the element's ancestor boxes on both sides until one differs, then `rules` that ancestor: the cause is usually one declaration. Fix the cause; never tune numbers to the score.
+**Spend scoring time only on what changed.** The first run is a full `score`. After a fix, re-run only the checks it can move, at the width it concerns: `npx trueclone score <name> --only layout,detail --viewport tablet`. A check whose inputs (the clone's files, the capture) have not changed since its last run is reported from that run and not re-measured (`--fresh` forces it). `REPORT.md` shows where the scoring time went. To understand one gap, run `npx trueclone explain <name> <y or "section label"> --viewport <vp>`: it prints what layout, states, detail and hovers saw there and writes a reference | clone | diff crop, so you read the tool's data instead of re-measuring with a browser.
+
+**Unstable probes are not your gaps.** Detail probes and hover effects are read twice on the reference; what does not agree with itself (random motion, a hover that lands by timing, a rotating word) is listed as unstable and excluded from the score. The load check reports its own noise (±). Do not chase a number inside the noise: a gap of 0.3 on a check with ±1 noise is not a gap.
+
+Fix in this order: page height drift, the worst layout section, the worst state step, the lowest motion curve, any interaction marked FAIL, the load sequence, then detail and hovers. `REPORT.md` lists them under "Fix first". For a drift, compare the element's ancestor boxes on both sides until one differs, then `rules` that ancestor: the cause is usually one declaration. Fix the cause; never tune numbers to the score.
+
+**Done when:** layout ≥ 98% at every viewport, states within 5 points of layout, motion ≥ 95%, detail ≥ 95%, hovers ≥ 90%, load ≥ 95%, and every interaction passes. Otherwise stop after 8 passes and report what's left and why.
 
-**Done when:** layout ≥ 98% at every viewport, states within 5 points of layout, motion ≥ 95%, detail ≥ 95%, hovers ≥ 90%, and every interaction passes. Otherwise stop after 8 passes and report what's left and why.
+**The load sequence is scored too.** A visitor's first impression is the load, so both pages are photographed 0.25 to 4 s after navigation and compared with their own settled frame. A clone that paints a captured, pre-script state (a hero grid a script builds, a card layout a script places) until its scripts run shows a gap here that no other check sees. The seed's boot contract handles it: `<html class="tc-boot">` from the first byte until the clone's scripts have run and every hold is released; elements marked `data-tc-boot-hide` stay invisible meanwhile (3 s failsafe). Pass the regions your script builds at boot to the seed: `npx trueclone seed <name> --hide-until-boot "<selectors>"`. If your script needs more than "has run" (an intro that waits for its image), call `tcBoot.hold()` at the top of `script.js` and `tcBoot.release()` when the first frame is ready. Hide only what the original also does not show before its scripts run (its first frames are in `reference/load/`); hiding more than the original hides is a gap of its own.
 
 How detail measures, so you can trust it:
 - motion on (many originals ignore `prefers-reduced-motion`, and a clone that honours it lays out differently);
@@ -137,7 +166,7 @@ How layout and states measure:
 - content that a component mounts only while in view (marked `data-tc-viewmount` by capture) can't appear in a full-page still on either side: layout paints its box the same on both and reports the count; the scroll-state check, with a real viewport, scores it;
 - endless animations (marquees, rotating borders) are frozen on their first frame on both sides before every state screenshot: their phase depends on load time, not on the clone.
 
-The live site can change after capture (a redeploy changes its CSS bundle name). When live-site tools (detail, rules) and screenshot scores (layout, states) disagree about a section, re-capture (`capture`, then `states <name>`); that also resets the cached reference measurements.
+The live site can change after capture (a redeploy, a new nav item, a rotating headline). Every full score starts with `drift`: the live page's height and sections against the capture's. When it reports a change, `REPORT.md` marks detail, hovers, motion, interactions and load **stale capture**: they now measure a page the clone was never a copy of. Re-capture (`capture`, then `states`, `reveals`, `seed --force`) before reading them; never fix the clone against a stale reference.
 
 ## 6. Next.js (after the HTML clone passes)