@trueclone/cli 0.2.0 → 0.4.0-rc.1

package/scripts/states.mjs

@@ -7,7 +7,7 @@
 //        node scripts/states.mjs <name> --clone [url] [--structure]
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { VIEWPORTS, parseArgs, openBrowser, newPage, serve, warmUp, waitStill, wheelTo, statesInPage, maskToggle, freezeLoops, matchPct, PNG } from './lib.mjs';
+import { SCORED, parseArgs, openBrowser, newPage, serve, warmUp, waitStill, wheelTo, statesInPage, maskToggle, freezeLoops, matchPct, canvasSimilarity, PNG } from './lib.mjs';
 
 const { pos, flags } = parseArgs(process.argv.slice(2));
 const [name] = pos;
@@ -22,7 +22,13 @@ const cloneMode = Boolean(flags.clone);
 const structure = Boolean(flags.structure);
 const stepFrac = Number(flags.step || 0.5);
 const wanted = typeof flags.viewports === 'string' ? flags.viewports.split(',') : null;
-const viewports = VIEWPORTS.filter((v) => !wanted || wanted.includes(v.name));
+const viewportsAll = SCORED.filter((v) => !wanted || wanted.includes(v.name));
+// the clone is only replayed where the reference has states (a capture older than the held-out sizes has none there)
+const viewports = [];
+for (const v of viewportsAll) {
+  if (flags.clone && !(await fs.stat(path.join(ref, 'states', `${v.name}.json`)).then(() => true, () => false))) { console.log(`${v.name}: no reference states (run trueclone states ${name}); skipped`); continue; }
+  viewports.push(v);
+}
 const outRoot = path.join(cloneMode ? path.join(root, 'compare') : ref, 'states');
 
 const server = cloneMode && typeof flags.clone !== 'string' ? await serve(path.join(root, 'clone')) : null;
@@ -75,7 +81,13 @@ try {
       await page.screenshot({ path: path.join(dir, `${file}.mask.png`) });
       await maskToggle(page, false);
       if (!cloneMode) samples.push(await page.evaluate(statesInPage));
-      steps.push({ i, y: actual, target: y, settled: still.settled, settleMs: still.ms });
+      // the canvases in view (scenes a script draws): masked out of the structure score, so compared on their own
+      const canvases = await page.evaluate(() => [...document.querySelectorAll('canvas')].map((c) => {
+        const r = c.getBoundingClientRect(), s = getComputedStyle(c);
+        if (r.width < 40 || r.height < 40 || r.bottom <= 0 || r.top >= innerHeight || s.visibility === 'hidden' || +s.opacity < 0.05) return null;
+        return [Math.max(0, r.left), Math.max(0, r.top), Math.min(innerWidth, r.right), Math.min(innerHeight, r.bottom)].map(Math.round);
+      }).filter((r) => r && r[2] - r[0] >= 40 && r[3] - r[1] >= 40));
+      steps.push({ i, y: actual, target: y, settled: still.settled, settleMs: still.ms, canvases });
     }
     await context.close();
 
@@ -89,7 +101,27 @@ try {
         scored.push({ ...s, match: matchPct(a, b).pct });
       }
       const avg = +(scored.reduce((n, s) => n + s.match, 0) / scored.length).toFixed(2);
-      return { viewport: vp.name, match: avg, worst: [...scored].sort((a, b) => a.match - b.match).slice(0, 5), steps: scored };
+      // canvases: the reference's canvas regions at each step, compared by what is drawn (real pixels, not the mask)
+      const refSteps = JSON.parse(await fs.readFile(path.join(ref, 'states', `${vp.name}.json`), 'utf8')).steps;
+      const canvasScores = [];
+      for (const s of steps) {
+        const regions = refSteps[s.i]?.canvases;
+        if (!regions?.length) continue;
+        const f = `${String(s.i).padStart(2, '0')}.png`;
+        const a = PNG.sync.read(await fs.readFile(path.join(ref, 'states', vp.name, f)));
+        const b = PNG.sync.read(await fs.readFile(path.join(dir, f)));
+        for (const [x0, y0, x1, y1] of regions) {
+          const w = Math.min(x1, a.width, b.width) - x0, h = Math.min(y1, a.height, b.height) - y0;
+          if (w < 40 || h < 40) continue;
+          const ca = new PNG({ width: w, height: h }), cb = new PNG({ width: w, height: h });
+          PNG.bitblt(a, ca, x0, y0, w, h, 0, 0);
+          PNG.bitblt(b, cb, x0, y0, w, h, 0, 0);
+          canvasScores.push({ i: s.i, y: s.y, region: [x0, y0, x1, y1], similarity: canvasSimilarity(ca, cb) });
+        }
+      }
+      const hasCanvasData = refSteps.some((s) => Array.isArray(s.canvases));
+      const canvas = canvasScores.length ? +(canvasScores.reduce((n, c) => n + c.similarity, 0) / canvasScores.length).toFixed(2) : null;
+      return { viewport: vp.name, match: avg, worst: [...scored].sort((a, b) => a.match - b.match).slice(0, 5), steps: scored, canvas, canvasWorst: [...canvasScores].sort((a, b) => a.similarity - b.similarity).slice(0, 5), ...(hasCanvasData ? {} : { canvasNote: 'reference states predate the canvas check: re-run trueclone states' }) };
     } else {
       const summary = summarize(steps, samples, vp, initial);
       await fs.writeFile(path.join(outRoot, `${vp.name}.json`), JSON.stringify({ viewport: vp, steps, samples }));
@@ -105,7 +137,8 @@ try {
 await fs.writeFile(path.join(outRoot, cloneMode ? `report${structure ? '.mask' : ''}.json` : 'report.json'), JSON.stringify(report, null, 2));
 if (cloneMode) {
   console.log(`state match (${report.mode}) - average over scroll steps`);
-  console.table(report.viewports.map((v) => ({ viewport: v.viewport, 'match %': v.match, worst: v.worst.map((s) => `#${s.i} y${s.y} ${s.match}%`).join('  ') })));
+  console.table(report.viewports.map((v) => ({ viewport: v.viewport, 'match %': v.match, 'canvas %': v.canvas ?? '-', worst: v.worst.map((s) => `#${s.i} y${s.y} ${s.match}%`).join('  ') })));
+  for (const v of report.viewports) if (v.canvasNote) console.log(`${v.viewport}: ${v.canvasNote}`);
 } else {
   console.table(report.viewports);
 }

package/scripts/tiles.mjs

@@ -1,25 +1,41 @@
 // Cut a tall full-page screenshot into viewport-sized tiles you can actually read.
-// usage: node scripts/tiles.mjs <png> [tileHeight=1200]  -> <png-dir>/tiles/<name>-01.png ...
+// usage: node scripts/tiles.mjs <name> [--size desktop] [--clone]   -> sites/<name>/reference/tiles/<size>-01.png ...
+//        node scripts/tiles.mjs <png> [tileHeight=1200]              -> <png-dir>/tiles/<png-name>-01.png ...
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { PNG } from 'pngjs';
+import { SCORED, parseArgs } from './lib.mjs';
 
-const [file, h = '1200'] = process.argv.slice(2);
-if (!file) {
-  console.error('usage: npm run tiles -- <png> [tileHeight]');
+const { pos, flags } = parseArgs(process.argv.slice(2));
+const [target, h] = pos;
+if (!target) {
+  console.error('usage: trueclone tiles <name> [--size desktop|tablet|mobile|laptop|wide] [--clone]   or   trueclone tiles <file.png> [tileHeight]');
   process.exit(1);
 }
-const tileH = Number(h);
-const src = PNG.sync.read(await fs.readFile(file));
-const dir = path.join(path.dirname(file), 'tiles');
-await fs.mkdir(dir, { recursive: true });
-const base = path.basename(file, '.png');
-let n = 0;
-for (let y = 0; y < src.height; y += tileH) {
-  const th = Math.min(tileH, src.height - y);
-  const out = new PNG({ width: src.width, height: th });
-  PNG.bitblt(src, out, 0, y, src.width, th, 0, 0);
-  const name = `${base}-${String(++n).padStart(2, '0')}.png`;
-  await fs.writeFile(path.join(dir, name), PNG.sync.write(out));
+let files;
+let tileH = Number(h || 1200);
+if (/\.png$/i.test(target)) files = [path.resolve(target)];
+else {
+  // a site name: the reference's full-page shots (or the clone's last layout shots with --clone)
+  const root = path.resolve('sites', target);
+  const sizes = flags.size ? [flags.size] : SCORED.map((v) => v.name);
+  files = sizes.map((s) => (flags.clone ? path.join(root, 'compare', `${s}.mask.clone.png`) : path.join(root, 'reference', `${s}.png`)));
+  if (!h) tileH = 0; // one tile per screen of that size
+}
+for (const file of files) {
+  const src = await fs.readFile(file).then((b) => PNG.sync.read(b), () => null);
+  if (!src) { console.log(`skipped (not found): ${path.relative(process.cwd(), file)}`); continue; }
+  const size = SCORED.find((v) => path.basename(file).startsWith(`${v.name}.`));
+  const th = tileH || size?.height || 1200;
+  const dir = path.join(path.dirname(file), 'tiles');
+  await fs.mkdir(dir, { recursive: true });
+  const base = path.basename(file, '.png');
+  let n = 0;
+  for (let y = 0; y < src.height; y += th) {
+    const hh = Math.min(th, src.height - y);
+    const out = new PNG({ width: src.width, height: hh });
+    PNG.bitblt(src, out, 0, y, src.width, hh, 0, 0);
+    await fs.writeFile(path.join(dir, `${base}-${String(++n).padStart(2, '0')}.png`), PNG.sync.write(out));
+  }
+  console.log(`${n} tiles of ${th}px -> ${path.relative(process.cwd(), dir)} (${base}-NN.png)`);
 }
-console.log(`${n} tiles -> ${dir}`);

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/scripts/viewport-fit.mjs

@@ -0,0 +1,198 @@
+// Inline styles a script set, read at many screen sizes (capture), turned into what the clone may carry:
+// - a value that is the same at every size stays as it is;
+// - a value that is a function of the viewport (a·width + b·height + c, in px) becomes that function as a CSS calc(),
+//   for all sizes when one function fits them all, or per range of the site's own breakpoints;
+// - a value that fits no such function (it depends on content, time, a container, randomness) is NOT carried: the
+//   clone's script must compute it, the way the site does. It is listed as script-owned.
+// Nothing here is ever exact at the captured sizes only: that is the point.
+
+const MODELS = [
+  { name: 'c', cols: () => [1] },
+  { name: 'w', cols: (w) => [w] },
+  { name: 'h', cols: (w, h) => [h] },
+  { name: 'w+c', cols: (w) => [w, 1] },
+  { name: 'h+c', cols: (w, h) => [h, 1] },
+  { name: 'w+h', cols: (w, h) => [w, h] },
+  { name: 'w+h+c', cols: (w, h) => [w, h, 1] },
+];
+
+function solve(A, b) {
+  const n = b.length;
+  const M = A.map((row, i) => [...row, b[i]]);
+  for (let c = 0; c < n; c++) {
+    let p = c;
+    for (let r = c + 1; r < n; r++) if (Math.abs(M[r][c]) > Math.abs(M[p][c])) p = r;
+    if (Math.abs(M[p][c]) < 1e-9) return null;
+    [M[c], M[p]] = [M[p], M[c]];
+    for (let r = 0; r < n; r++) {
+      if (r === c) continue;
+      const f = M[r][c] / M[c][c];
+      for (let k = c; k <= n; k++) M[r][k] -= f * M[c][k];
+    }
+  }
+  return M.map((row, i) => row[n] / row[i]);
+}
+
+// points: [{ w, h, v }] -> { model, coef } or null. A model needs one point more than it has parameters, so every fit
+// is checked on a point it was not determined by.
+export function fitPoints(points, shaped = true) {
+  for (const m of MODELS) {
+    const k = m.cols(1, 1).length;
+    if (points.length < k + 1) continue;
+    const X = points.map((p) => m.cols(p.w, p.h));
+    const A = Array.from({ length: k }, () => new Array(k).fill(0));
+    const b = new Array(k).fill(0);
+    points.forEach((p, i) => { for (let r = 0; r < k; r++) { b[r] += X[i][r] * p.v; for (let c = 0; c < k; c++) A[r][c] += X[i][r] * X[i][c]; } });
+    const coef = solve(A, b);
+    if (!coef) continue;
+    const tol = Math.max(0.75, 0.003 * Math.max(...points.map((p) => Math.abs(p.v))));
+    if (points.every((p, i) => Math.abs(X[i].reduce((s, x, j) => s + x * coef[j], 0) - p.v) <= tol)) return { model: m.name, coef };
+  }
+  return shaped ? fitTwoLines(points) : null;
+}
+
+// The smaller or larger of two lines: min(L1, L2) / max(L1, L2), each L = a·w + b·h + c. This is what a script
+// computes for "cover" (max(100vw, 177.8vh)), "contain", a cover image centred (min((w - 1.778·h) / 2, 0)), a tile
+// of it, a size clamped at a limit. Which line applies switches at an aspect ratio, a width or a height: the points
+// are split on each of those in turn, each side must fit one line on its own (checked as usual), and then every point
+// must be the min (or max) of both lines. Eight points at least, so two short lines never fit noise.
+function fitTwoLines(points) {
+  if (points.length < 8) return null;
+  const tol = Math.max(0.75, 0.003 * Math.max(...points.map((p) => Math.abs(p.v))));
+  for (const key of [(p) => p.w / p.h, (p) => p.w, (p) => p.h]) {
+    const sorted = [...points].sort((p, q) => key(p) - key(q));
+    for (let s = 2; s <= sorted.length - 2; s++) {
+      if (key(sorted[s - 1]) === key(sorted[s])) continue;
+      const lo = fitPoints(sorted.slice(0, s), false), hi = lo && fitPoints(sorted.slice(s), false);
+      if (!lo || !hi) continue;
+      for (const model of ['min', 'max']) {
+        const f = model === 'min' ? Math.min : Math.max;
+        if (points.every((p) => Math.abs(f(lineAt(lo, p.w, p.h), lineAt(hi, p.w, p.h)) - p.v) <= tol)) return { model, lines: [lo, hi] };
+      }
+    }
+  }
+  return null;
+}
+const lineAt = ({ model, coef }, w, h) => {
+  let i = 0, v = 0;
+  for (const t of model.split('+')) v += coef[i++] * (t === 'w' ? w : t === 'h' ? h : 1);
+  return v;
+};
+
+const r4 = (x) => +x.toFixed(4);
+// a fitted px value as CSS: width terms use --tc-vw (1% of the layout width, scrollbar excluded, set by the seed)
+export function cssOf({ model, coef, lines }) {
+  if (lines) return `${model}(${lines.map((l) => cssOf(l).replace(/^calc\((.*)\)$/, '$1')).join(', ')})`;
+  const parts = model.split('+');
+  let a = 0, b = 0, c = 0;
+  parts.forEach((p, i) => { if (p === 'w') a = coef[i]; else if (p === 'h') b = coef[i]; else c = coef[i]; });
+  const terms = [];
+  if (Math.abs(a) > 1e-6) terms.push([a * 100, (x) => `${r4(Math.abs(x))} * var(--tc-vw, 1vw)`]);
+  if (Math.abs(b) > 1e-6) terms.push([b * 100, (x) => `${r4(Math.abs(x))}vh`]);
+  if (Math.abs(c) > 0.005 || !terms.length) terms.push([c, (x) => `${+Math.abs(x).toFixed(2)}px`]);
+  if (terms.length === 1 && model === 'c') return `${+c.toFixed(2)}px`;
+  return `calc(${terms.map(([x, f], i) => `${i === 0 ? (x < 0 ? '-1 * ' : '') : x < 0 ? '- ' : '+ '}${f(x)}`).join(' ')})`;
+}
+
+const PX = /-?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?px/gi; // 5.68434e-14px is a number too (a script's float noise)
+// one spelling per meaning, so a library that writes translate3d(0px, 0px, 0px) at one size and translate(0px, 0px)
+// at another is not mistaken for a value that changes
+const normalise = (v) => v
+  .replace(/translate3d\(\s*([^,()]+),\s*([^,()]+),\s*0(?:px)?\s*\)/g, 'translate($1, $2)')
+  .replace(/translateX\(\s*([^,()]+)\)/g, 'translate($1, 0px)')
+  .replace(/translateY\(\s*([^,()]+)\)/g, 'translate(0px, $1)')
+  .replace(/translate\(\s*([^,()]+)\)/g, 'translate($1, 0px)')
+  .replace(/(^|[\s(,])0(?=[\s),]|$)/g, '$10px');
+const parseDecls = (text) => {
+  const map = new Map();
+  for (const d of String(text || '').split(/;(?![^(]*\))/)) {
+    const i = d.indexOf(':');
+    if (i < 0) continue;
+    const k = d.slice(0, i).trim(), v = d.slice(i + 1).trim().replace(/\s*!important$/i, '');
+    if (k) map.set(k, /transform|translate/.test(k) ? normalise(v) : v);
+  }
+  return map;
+};
+
+// values: [{ w, h, v: string }] -> CSS value string, or null when no viewport function fits
+function fitValue(values) {
+  const tmpl = values[0].v.replace(PX, '§');
+  if (values.some((x) => x.v.replace(PX, '§') !== tmpl)) return null; // keywords or unitless numbers change: not a function of size
+  if (values.every((x) => x.v === values[0].v)) return values[0].v;
+  const nums = values.map((x) => (x.v.match(PX) || []).map(parseFloat));
+  const out = [];
+  for (let t = 0; t < nums[0].length; t++) {
+    const fit = fitPoints(values.map((x, i) => ({ w: x.w, h: x.h, v: nums[i][t] })));
+    if (!fit) return null;
+    out.push(cssOf(fit));
+  }
+  let k = 0;
+  return tmpl.replace(/§/g, () => out[k++]);
+}
+
+// data: inline-styles.json ({ breakpoints, sizes, styles: { "WxH": { w, h, styles: { path: [style, class] } } } }), or
+// the 0.3 shape ({ desktop: { path: style }, ... }). Returns, per element path: the declarations to set inline, the
+// per-range rules, and the properties left to the clone's script.
+export function planInlineStyles(data, viewports) {
+  let breakpoints = [], sizes = [];
+  if (data?.styles) {
+    breakpoints = data.breakpoints || [];
+    sizes = Object.values(data.styles).map((s) => ({ w: s.w, h: s.h, styles: Object.fromEntries(Object.entries(s.styles).map(([p, v]) => [p, Array.isArray(v) ? v[0] : v])) }));
+  } else if (data) {
+    sizes = Object.entries(data).map(([name, styles]) => { const vp = viewports.find((v) => v.name === name); return vp ? { w: vp.width, h: vp.height, styles } : null; }).filter(Boolean);
+  }
+  const edges = [0, ...breakpoints, 100000];
+  const ranges = edges.slice(0, -1).map((lo, i) => ({ lo: i === 0 ? 0 : lo + 1, hi: edges[i + 1] }));
+  const mediaOf = (r) => (r.lo === 0 ? `(max-width: ${r.hi}px)` : r.hi >= 100000 ? `(min-width: ${r.lo}px)` : `(min-width: ${r.lo}px) and (max-width: ${r.hi}px)`);
+  const plan = {};
+  const owned = [];
+  let fitted = 0, constant = 0;
+  const paths = new Set(sizes.flatMap((s) => Object.keys(s.styles)));
+  for (const p of paths) {
+    const per = sizes.map((s) => ({ w: s.w, h: s.h, d: parseDecls(s.styles[p]) }));
+    const props = new Set(per.flatMap((x) => [...x.d.keys()]));
+    const entry = { inline: {}, rules: [], dropped: [] };
+    for (const k of props) {
+      const vals = per.map((x) => ({ w: x.w, h: x.h, v: x.d.get(k) }));
+      if (vals.every((x) => x.v !== undefined && x.v === vals[0].v)) { constant++; continue; } // same everywhere: as captured
+      // one function for every size
+      if (vals.every((x) => x.v !== undefined)) {
+        const css = fitValue(vals);
+        if (css !== null) { entry.inline[k] = css; fitted++; continue; }
+      }
+      // per range of the site's breakpoints. Neighbouring ranges one function fits are one group (fewer rules, more
+      // points behind each fit); a range no captured size fell in joins its neighbour rather than losing the value.
+      const joins = (a, b) => {
+        if (!a.length || !b.length) return true;
+        const all = [...a, ...b];
+        const unset = all.filter((x) => x.v === undefined).length;
+        return unset === all.length || (!unset && fitValue(all) !== null);
+      };
+      const groups = [];
+      for (const r of ranges.length > 1 ? ranges : []) {
+        const inR = vals.filter((x) => x.w >= r.lo && x.w <= r.hi);
+        const last = groups[groups.length - 1];
+        if (last && joins(last.pts, inR)) { last.hi = r.hi; last.pts.push(...inR); } else groups.push({ lo: r.lo, hi: r.hi, pts: [...inR] });
+      }
+      let anyDrop = !groups.length;
+      const rules = [];
+      for (const g of groups) {
+        if (g.pts.every((x) => x.v === undefined)) continue; // the script doesn't set it at these sizes
+        // a fit needs a point it was not determined by; a group with unset and set sizes is not a function of size
+        if (g.pts.length < 2 || g.pts.some((x) => x.v === undefined)) { anyDrop = true; continue; }
+        const css = fitValue(g.pts);
+        if (css === null) { anyDrop = true; continue; }
+        rules.push({ media: mediaOf(g), prop: k, value: css });
+      }
+      // all or nothing: a property the clone's script must compute at some sizes is the script's at every size
+      // (half carried by the seed, half computed, the two would fight at the edges)
+      const anyRule = !anyDrop && rules.length > 0;
+      if (anyRule) entry.rules.push(...rules);
+      entry.inline[k] = null; // the captured constant no longer applies
+      if (anyRule) fitted++;
+      if (anyDrop || !anyRule) { entry.dropped.push(k); owned.push({ path: p, prop: k, samples: vals.slice(0, 5).map((x) => `${x.w}x${x.h}: ${x.v ?? '(unset)'}`) }); }
+    }
+    if (Object.keys(entry.inline).length || entry.rules.length || entry.dropped.length) plan[p] = entry;
+  }
+  return { plan, owned, fitted, constant, breakpoints, sizes: sizes.length };
+}