@trueclone/cli 0.3.0 → 0.4.0

package/README.md

@@ -1,11 +1,11 @@
 # trueclone
 
-**A working twin of any website, from one URL, with scores that prove it.**
+**The exact same website, from one URL, at every screen size, with the checks to prove it.**
 
-Give your coding agent a URL. trueclone captures the site, extracts its design system, guides the rebuild and measures the result against the original until it matches: layout, scroll states, motion curves, interactions, hover effects and computed styles, at phone, tablet and desktop widths. You get the clone as HTML and as a Next.js app, plus the design system as `DESIGN.md` and a shadcn `globals.css`.
+Give your coding agent a URL. trueclone captures the site, extracts its design system, seeds the clone with the original's structure, hands the agent the original's own scripts to port every behaviour from, and measures the result against the original until it matches: layout, scroll states, canvases, motion, interactions, hovers, styles and the load sequence, at the sizes it was built from and at sizes it never saw, plus a frame-by-frame visual review. You get the clone as HTML and as a Next.js app, plus the design system as `DESIGN.md` and a shadcn `globals.css`.
 
 ```bash
-npx @trueclone/cli init            # once per project: installs trueclone, the skill for your agent, REA as an MCP server
+npx @trueclone/cli init            # once per project: installs trueclone and the skill for your agent
 # then tell Claude Code, Codex or Cursor:
 #   "clone https://example.com with trueclone"
 ```
@@ -23,7 +23,7 @@ npx @trueclone/cli init            # once per project: installs trueclone, the s
 
 ## Proof
 
-Three benchmarks with very different stacks, scored by the tool itself:
+Three benchmarks with very different stacks, scored by the tool itself. These numbers were measured at the three build sizes only, before trueclone 0.4 added held-out sizes and the visual review; 0.4's benchmark runs replace them.
 
 **[rea.tools](https://rea.tools/)**: static docs with a canvas game and interactive demos, exact mode (copied with the owner's permission).
 
@@ -60,33 +60,25 @@ The hand-built portfolio isn't perfect yet, and its report says so: computed sty
 ## How it works
 
 ```
-URL ─► capture ─► understand ─► design system ─► build ─► score ─► report
-        3 widths    motion         DESIGN.md        your      8 checks   REPORT.md
-        HAR, HTML   inventory      globals.css      agent     in parallel
-        assets      + REA          tokens.css                  ▲     │
-                                                               └─────┘ until every target passes
+URL ─► capture ─► understand ─► design system ─► seed ─► build ─► score + review ─► report
+        5 sizes    the site's      DESIGN.md        structure  your    10 checks at       REPORT.md
+        scripts    own scripts,    globals.css      + viewport agent   build and held-out
+        HAR        motion runtime  tokens.css       functions          sizes, by eye too
+                                                                  ▲            │
+                                                                  └────────────┘ until every check passes
 ```
 
-1. **Capture** (`trueclone capture`): full-page screenshots at 390, 768 and 1440px, sections, rendered HTML, assets, every network request.
-2. **Understand** (`trueclone motion`, `trueclone understand`): reads the live animation runtime (GSAP timelines, ScrollTriggers, Lenis and Swiper settings, CSS animations, cursor-driven tweens) and, with REA, which scripts actually run while a visitor scrolls, which handler each control has and the code around it, the endpoints in the code, source maps when published: `code.md`, so the agent copies rules instead of guessing them from effects.
+1. **Capture** (`trueclone capture`): full-page screenshots at five sizes (390, 768 and 1440 wide to build from; 1280 and 1920 held out, never used to build), sections, rendered HTML, assets, every network request, every script the page ran (with what ran and where each event listener lives), and the inline values scripts set, read at extra sizes inside each of the site's breakpoint ranges.
+2. **Understand**: `reference/scripts/INDEX.md` (the site's own code, ranked by what ran), the live animation runtime (`trueclone motion`: GSAP timelines, ScrollTriggers, Lenis, Swiper, CSS animations) and the scroll states. The agent ports each behaviour's rule from the site's code instead of guessing it from effects.
 3. **Design system** (`trueclone design`): one canonical `design-tokens.json`, rendered to DESIGN.md, globals.css and the clone's tokens.
-4. **Build**: `trueclone reveals` records, at every width, the original's scroll reveals frame by frame, its scroll-linked curves (parallax) and its scroll-driven class changes; `trueclone widgets` clicks every tab and menu and records each state; `trueclone seed` turns the script-free mirror into the clone (template mode: layout-measured lorem text and same-size media placeholders), cleans what the original's scripts left in the DOM (pin-spacers, canvas buffer sizes) and replays what was recorded. Layout is at 99%+ before anyone writes CSS; your agent writes the remaining behaviour, guided by the skill. `trueclone rules` shows the original's CSS for any element (like DevTools).
-5. **Score** (`trueclone score`): layout pixel diff per section, scroll states replayed, motion curves sampled, interaction scenarios with change assertions, every hover, computed styles at matching points, and the load sequence (how settled each side is at 0.25 to 4 s after navigation, cold cache, same emulated network). Reference measurements are cached, so only the clone is re-measured.
-6. **Report**: `REPORT.md` with the verdict, what to fix first, and what was not copied.
+4. **Seed** (`trueclone seed`): the script-free mirror becomes the clone (template mode: layout-measured lorem text and same-size media placeholders). A value a script computed from the screen size is carried as that function (`calc()`), never as one size's number; a value no such function explains is left to the agent and listed. Pins pin, one-shot reveals and scroll class changes replay, shadow roots render, the first paint is held until the clone's scripts have run.
+5. **Build**: the agent writes `clone/script.js`, scene by scene, from the site's own rules; `clone/patches/` for anything on top of the seed; `trueclone rules` shows the original's CSS for any element.
+6. **Score and review** (`trueclone score`, `trueclone review`): layout, scroll states, canvases, motion curves, details, hovers (outcome, not just "something changed"), interactions (same end state), load sequence, at the build sizes and the held-out sizes; then the reference and the clone side by side, frame by frame, with a verdict for each.
+7. **Report**: `REPORT.md` with every check at every size, the review, what to fix first, and what was not copied.
 
-## Why not just REA?
+## REA
 
-trueclone **bundles** [REA](https://github.com/morluto/rea) (Reverse Engineer Anything) and uses it, but works without it too.
-
-| | REA on its own | trueclone |
-|---|---|---|
-| What it is | A microscope: typed tools that let your agent look inside apps, binaries and pages | A factory with quality control: capture, design system, build guide, scores, report |
-| Capture | Your Chrome over CDP, one page state | 3 widths, every scroll state, motion runtime, assets, network |
-| Knows when the clone is right | No: the agent judges by eye | Yes: 7 measured checks with targets |
-| Tells you what's wrong | No | "Footer column 2 is at x 189, the original's at 732", plus the original's CSS rule |
-| Outputs | Whatever the agent writes | HTML clone, Next.js app, DESIGN.md, globals.css, motion recipe, REPORT.md |
-
-REA answers *how does this work?* trueclone answers *is my copy identical, and where isn't it?* trueclone proves the visual and behavioural match on its own; `trueclone understand` adds REA's code-level evidence (which scripts ran, the handler behind each control with its source, endpoints, original sources when published) so the agent copies rules instead of inferring them. For the hard parts (a bundled physics rule, a shader, a module's data flow) REA's own CLI is one command away.
+trueclone bundles [REA](https://github.com/morluto/rea) (Reverse Engineer Anything) for the rare part no script reading explains (a bundled physics rule, a shader, WASM): `npx trueclone rea --help`. It is not part of the standard flow: the site's scripts, saved and ranked by the capture, carry what the agent needs.
 
 ## Modes and guardrails
 
@@ -103,22 +95,22 @@ REA answers *how does this work?* trueclone answers *is my copy identical, and w
 
 ```bash
 npx @trueclone/cli init                 # set up a project for your agent (then `npx trueclone ...`)
-npx trueclone doctor                    # check Node, Chrome and REA
+npx trueclone doctor                    # check Node and Chrome
 npx trueclone <url> [name]              # capture + design-system draft
 npx trueclone capture <url> [name] [--mode exact --permission "<owner>"]
 npx trueclone motion <name>             # motion inventory
-npx trueclone understand <name>         # code evidence with REA: which scripts ran, each control's handler with its source -> code.md
 npx trueclone design <name>             # DESIGN.md + globals.css
 npx trueclone reveals <name>            # record scroll reveals and scroll class changes
 npx trueclone widgets <name>            # record every tab and menu state
-npx trueclone seed <name>               # clone/ from the mirror (template: placeholder text and media)
+npx trueclone seed <name>               # clone/ from the mirror (template: placeholder text and media); --patches re-applies clone/patches/ in a second
 npx trueclone rules <name> "<selector>" # the original's CSS rules for an element
 npx trueclone textshape <name> --write  # template mode: placeholder text with the original's line breaks
 npx trueclone load <name>               # load sequence on both sides: settledness 0.25-4 s after navigation, cold cache, same network
 npx trueclone score <name> [--quick]    # every check, then REPORT.md (--only detail,load --viewport tablet after a fix; unchanged checks are kept)
 npx trueclone explain <name> <y>        # one place on the page: what every check saw there, plus a reference|clone|diff crop
-npx trueclone next <name> --verify      # Next.js + Tailwind + shadcn app, scored
-npx trueclone rea <args>                # bundled REA
+npx trueclone review <name> --size wide # reference and clone side by side at a held-out size: load, every section, hover
+npx trueclone next <name> --verify      # Next.js + Tailwind + shadcn app, scored into REPORT.next.md
+npx trueclone rea <args>                # bundled REA, for the rare deep case
 npx trueclone help                      # every step
 ```
 
@@ -137,7 +129,7 @@ Node 22.19+, 24.11+ or 26+ (the same as REA), and Google Chrome for captures (it
 
 - **Whole sites:** crawl every route, shared header and footer as components.
 - **Data layer:** captured API responses turned into mock routes and fixtures, so the clone works offline.
-- **Benchmarks:** React with Framer Motion, a Next.js site with source maps, a data-driven app; each scored with and without REA.
+- **Benchmarks by kind of site:** static, Tailwind/Next.js, Webflow, Webflow + GSAP, Framer, WordPress builders, WebGL showcases, docs, e-commerce, SPAs, scroll-jacking, embeds: each scored at build and held-out sizes, published here.
 - **A free web page:** paste a URL, get its DESIGN.md and globals.css.
 
 ## Credits

package/bin/trueclone.mjs

@@ -19,27 +19,28 @@ const require = createRequire(import.meta.url);
 const { name, version } = JSON.parse(await fs.readFile(path.join(PKG, 'package.json'), 'utf8'));
 
 const STEPS = {
-  capture: ['capture.mjs', 'capture a live page: screenshots at 390/768/1440, sections, tokens, rendered HTML, assets'],
-  seed: ['seed.mjs', 'exact mode: start clone/ from the script-free mirror (markup, text, styles, media)'],
+  capture: ['capture.mjs', 'capture a live page at 5 sizes (3 to build from, 2 held out), its scripts, assets, rendered HTML, inline values at extra sizes'],
+  seed: ['seed.mjs', 'clone/ from the script-free mirror: structure, viewport functions, pins, reveals (--patches: re-apply clone/patches/ only)'],
   design: ['design.mjs', 'design-tokens.json -> DESIGN.md (linted), shadcn globals.css, clone/tokens.css'],
   motion: ['motion.mjs', 'motion inventory from the live runtime (GSAP/ScrollTrigger, Lenis, Swiper, CSS animations)'],
-  understand: ['understand.mjs', 'code evidence with REA: which scripts ran, each element\'s handler with its source, endpoints, source maps -> reference/code.md'],
+  understand: ['understand.mjs', 'optional, rarely needed: REA code evidence -> reference/code.md (capture already saves every script, ranked, in reference/scripts/)'],
   reveals: ['reveals.mjs', 'record one-shot scroll reveals frame by frame, so seed can replay them (any library)'],
   widgets: ['widgets.mjs', 'record every tab and menu state by clicking it, so seed can replay them (template mode)'],
-  states: ['states.mjs', 'live scroll states; --clone scores the rebuild step by step'],
+  states: ['states.mjs', 'live scroll states at every scored size; --clone scores the rebuild step by step (canvases too)'],
   curves: ['curves.mjs', 'motion score: sampled property curves, reference vs clone (motion-map.json)'],
   interact: ['interact.mjs', 'interaction tests: click/hover/drag/key scenarios on both sides (interactions.json)'],
   detail: ['detail.mjs', 'style diff at matching points: font, size, weight, line height, colour, background, radius'],
-  hovers: ['hovers.mjs', 'hover every interactive element on both sides and compare what changes'],
+  hovers: ['hovers.mjs', 'hover every control and every element with a hover listener on both sides; the outcome must match'],
   load: ['load.mjs', 'load sequence: how settled each side is 0.25/0.5/1/2/4 s after navigation, cold cache, same network'],
   drift: ['drift.mjs', 'has the live page changed since the capture? (page height and sections per width vs meta.json)'],
   owned: ['owned.mjs', 'which sections of the clone script.js rebuilds at boot (load with scripts blocked vs running)'],
   rules: ['rules.mjs', 'every CSS rule matching an element on the reference (+ ::before/::after, @media); --clone for the clone'],
+  review: ['review.mjs', 'reference and clone side by side at a held-out size: load, every section, hover; verdicts go in notes.md'],
   explain: ['explain.mjs', 'one place on the page: what layout, states, detail and hovers saw there, plus a reference|clone|diff crop'],
   textshape: ['textshape.mjs', 'template mode: placeholder words with the reference word widths, so lines break the same'],
   diff: ['diff.mjs', 'full-page pixel diff per viewport and section (--structure masks text and media)'],
   spec: ['spec.mjs', 'measured boxes and styles of the live page (--clone for the rebuild)'],
-  tiles: ['tiles.mjs', 'cut a tall screenshot into readable tiles'],
+  tiles: ['tiles.mjs', 'the full-page shots cut into one tile per screen: tiles <name> [--size wide] [--clone], or tiles <file.png>'],
   next: ['next.mjs', 'Next.js + Tailwind v4 + shadcn app from the verified clone; --verify scores it'],
   score: ['score.mjs', 'every score in parallel groups, time limit per step, writes REPORT.md'],
   report: ['report.mjs', 'REPORT.md from the latest scores: every number, every gap, what cannot be copied'],
@@ -56,14 +57,14 @@ const run = (file, args) => new Promise((resolve) => {
 });
 
 function help() {
-  console.log(`trueclone ${version}: a working twin of a website, proven by scores
+  console.log(`trueclone ${version}: the exact same website, at every screen size
 
 usage
-  npx @trueclone/cli init            set up this folder for your coding agent (installs trueclone)
+  npx @trueclone/cli init            set up this folder for your coding agent (installs trueclone; --with-rea adds REA as MCP)
   trueclone <url> [name]             capture + design-system draft (template mode)
   trueclone <step> <name> [options]  run one step
-  trueclone rea <args>               bundled REA (Reverse Engineer Anything)
-  trueclone doctor                   check Node, browsers and REA
+  trueclone rea <args>               bundled REA (Reverse Engineer Anything), for the rare deep case
+  trueclone doctor                   check Node and browsers
 
 steps
 ${Object.entries(STEPS).map(([k, [, d]]) => `  ${k.padEnd(10)} ${d}`).join('\n')}
@@ -85,11 +86,15 @@ async function init() {
   let agents = (await exists(agentsFile)) ? await fs.readFile(agentsFile, 'utf8') : '';
   agents = agents.includes('<!-- trueclone:start -->') ? agents.replace(/<!-- trueclone:start -->[\s\S]*?<!-- trueclone:end -->\n?/, block) : `${agents}${agents && !agents.endsWith('\n\n') ? '\n' : ''}${block}`;
   await fs.writeFile(agentsFile, agents);
-  // 3. REA as an MCP server for agents that speak MCP (Claude Code reads .mcp.json)
-  const mcpFile = path.join(cwd, '.mcp.json');
-  const mcp = (await exists(mcpFile)) ? JSON.parse(await fs.readFile(mcpFile, 'utf8')) : {};
-  mcp.mcpServers = { ...(mcp.mcpServers || {}), rea: { command: 'npx', args: ['-y', `${name}@${version}`, 'rea', 'mcp'] } };
-  await fs.writeFile(mcpFile, `${JSON.stringify(mcp, null, 2)}\n`);
+  // 3. REA as an MCP server only on request (--with-rea): the standard flow reads the site's own scripts from the
+  // capture; REA is for the rare deep case and stays reachable as `npx trueclone rea` either way
+  const withRea = process.argv.includes('--with-rea');
+  if (withRea) {
+    const mcpFile = path.join(cwd, '.mcp.json');
+    const mcp = (await exists(mcpFile)) ? JSON.parse(await fs.readFile(mcpFile, 'utf8')) : {};
+    mcp.mcpServers = { ...(mcp.mcpServers || {}), rea: { command: 'npx', args: ['-y', `${name}@${version}`, 'rea', 'mcp'] } };
+    await fs.writeFile(mcpFile, `${JSON.stringify(mcp, null, 2)}\n`);
+  }
   // 4. captures, clones and browser profiles stay local
   const ignoreFile = path.join(cwd, '.gitignore');
   let ignore = (await exists(ignoreFile)) ? await fs.readFile(ignoreFile, 'utf8') : '';
@@ -108,8 +113,7 @@ async function init() {
   console.log(`trueclone set up in ${cwd}
   .claude/skills/trueclone/SKILL.md   the workflow your agent follows
   AGENTS.md                           points Codex, Cursor and others at the skill
-  .mcp.json                           REA as an MCP server
-  .gitignore                          sites/ stays local
+${withRea ? '  .mcp.json                           REA as an MCP server\n' : ''}  .gitignore                          sites/ stays local
   package.json                        ${installed}
 next: npx trueclone doctor, then ask your agent "clone <url> with trueclone"`);
 }
@@ -125,8 +129,8 @@ async function doctor() {
     try { const b = await chromium.launch(opts); await b.close(); console.log(`ok   ${label}`); }
     catch { console.log(`warn ${label} not found${opts.channel ? ': install Google Chrome' : ': npx playwright install chromium'}`); }
   }
-  try { require.resolve('rea-agents/package.json'); console.log('ok   REA bundled (trueclone rea doctor checks its decompilers)'); }
-  catch { console.log('warn REA not installed'); ok = false; }
+  try { require.resolve('rea-agents/package.json'); console.log('ok   REA bundled, for the rare deep case (trueclone rea doctor checks its decompilers)'); }
+  catch { console.log('warn REA not installed (optional)'); }
   process.exitCode = ok ? 0 : 1;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trueclone/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A working twin of any website from its URL: HTML clone, Next.js + Tailwind + shadcn app, DESIGN.md and globals.css, proven by layout, motion, interaction and style scores. Bundles REA.",
   "type": "module",
   "bin": {
@@ -22,6 +22,7 @@
   },
   "dependencies": {
     "@google/design.md": "^0.4.0",
+    "js-beautify": "2.0.3",
     "parse5": "^8.0.1",
     "pixelmatch": "^7.2.0",
     "playwright": "^1.64.0",

package/scripts/capture.mjs

@@ -5,7 +5,8 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import crypto from 'node:crypto';
-import { VIEWPORTS, parseArgs, siteName, openBrowser, newPage, settle, sectionsOf, mask } from './lib.mjs';
+import { SCORED, VIEWPORTS, HELD_OUT, parseArgs, siteName, openBrowser, newPage, settle, sectionsOf, mask } from './lib.mjs';
+import { startScriptEvidence } from './scripts-evidence.mjs';
 
 const { pos, flags } = parseArgs(process.argv.slice(2));
 const [url, nameArg] = pos;
@@ -93,10 +94,13 @@ const manifest = [];
 const summary = [];
 const rootFontSize = {};
 const inlineStyles = {};
+const scriptQueries = new Set(); // media queries the page's scripts asked (matchMedia), at any size
 try {
-  for (const vp of VIEWPORTS) {
+  // the seed sizes and the held-out sizes: the held-out ones are shot and measured for scoring, nothing else
+  for (const vp of SCORED) {
     const desktop = vp.name === 'desktop';
     const { context, page } = await newPage(browser, vp, desktop ? { recordHar: { path: path.join(ref, 'desktop.har'), content: 'omit' } } : {});
+    await page.addInitScript(recordMediaQueries);
     if (desktop) {
       page.on('response', async (res) => {
         const rawType = res.request().resourceType();
@@ -115,6 +119,8 @@ try {
         } catch { /* redirects, data: urls, aborted */ }
       });
     }
+    // desktop: the page's own scripts and what ran, saved as evidence (reference/scripts/)
+    const finishEvidence = desktop ? await startScriptEvidence(page, url).catch(() => null) : null;
     await page.goto(url, { waitUntil: 'load', timeout: 60000 });
     // Components that mount only while in view (a lazy wordmark, an embed) are often unmounted again by the time
     // the DOM is saved. Watch from load: an element that was empty, got content while scrolled into view and is empty
@@ -138,6 +144,16 @@ try {
       }).observe(document.body, { subtree: true, childList: true });
     });
     await settle(page, hide);
+    // inline styles at this size, by element path: scripts size and place things from the viewport (a grid's computed
+    // cells, a pin's distance), and the rendered HTML only keeps one size's values. With the extra sizes read below,
+    // the seed tells a function of the viewport from a constant. Read here, settled and before any screenshot, in the
+    // same state as the extra sizes (a full-page shot mounts content and fires reveals).
+    if (!vp.heldOut) inlineStyles[`${vp.width}x${vp.height}`] = await page.evaluate(readInlineStyles);
+    for (const q of await page.evaluate(() => window.__tcMediaQueries || []).catch(() => [])) scriptQueries.add(q);
+    if (finishEvidence) {
+      const ev = await finishEvidence(path.join(ref, 'scripts')).catch((e) => { console.warn(`WARNING scripts not saved: ${e.message}`); return null; });
+      if (ev) console.log(`scripts: ${ev.scripts} saved to reference/scripts/ (${ev.ran} ran during load and scroll), ${ev.listeners} event-listener handlers located (INDEX.md)`);
+    }
     // A full-page screenshot brings the whole page into view at once, which mounts view-mounted components and starts
     // their reveals: shoot until two shots agree, so the reference shows a settled page, not a fade caught at 0%.
     let shot = await page.screenshot({ fullPage: true });
@@ -151,26 +167,6 @@ try {
     await fs.writeFile(path.join(ref, `${vp.name}.png`), shot);
     const sections = await sectionsOf(page);
     await fs.writeFile(path.join(ref, `${vp.name}.sections.json`), JSON.stringify(sections, null, 2));
-    // inline styles at this width, by element path: scripts size and place things per width (a grid's computed
-    // height, a card's offset), and the rendered HTML only keeps the desktop values. The seed turns what differs
-    // between widths into media-query rules.
-    inlineStyles[vp.name] = await page.evaluate(() => {
-      const SKIP = new Set(['SCRIPT', 'NOSCRIPT', 'TEMPLATE', 'STYLE', 'LINK', 'META']);
-      const pathOf = (el) => {
-        const parts = [];
-        for (let n = el; n && n !== document.body; n = n.parentElement) {
-          const sibs = [...n.parentElement.children].filter((c) => !SKIP.has(c.tagName));
-          parts.unshift(`${n.tagName.toLowerCase()}:${sibs.indexOf(n) + 1}`);
-        }
-        return parts.join('>');
-      };
-      const out = {};
-      for (const el of document.body.querySelectorAll('[style]')) {
-        if (SKIP.has(el.tagName) || (el.closest('svg') && el.tagName !== 'svg')) continue;
-        out[pathOf(el)] = el.getAttribute('style');
-      }
-      return out;
-    });
     const height = await page.evaluate(() => document.documentElement.scrollHeight);
     rootFontSize[vp.name] = await page.evaluate(() => getComputedStyle(document.documentElement).fontSize);
     if (desktop) {
@@ -218,7 +214,7 @@ try {
     }
     await mask(page);
     await page.screenshot({ path: path.join(ref, `${vp.name}.mask.png`), fullPage: true });
-    summary.push({ viewport: vp.name, width: vp.width, pageHeight: height, sections: sections.length });
+    summary.push({ viewport: vp.name, width: vp.width, height: vp.height, ...(vp.heldOut ? { heldOut: true } : {}), pageHeight: height, sections: sections.length });
     await context.close(); // flushes the HAR
   }
 } finally {
@@ -226,7 +222,33 @@ try {
 }
 
 await fs.writeFile(path.join(ref, 'assets', 'manifest.json'), JSON.stringify(manifest, null, 2));
-await fs.writeFile(path.join(ref, 'inline-styles.json'), JSON.stringify(inlineStyles));
+
+// The site's own breakpoints (its @media width queries) and extra sizes inside every range they make: inline styles
+// read there let the seed fit each value a script set as a function of the viewport (a·vw + b·vh + c) per range, or
+// see that it is none and leave it to the agent. Never the held-out sizes: those stay unseen by anything that builds.
+const breakpoints = await siteBreakpoints(manifest, [...scriptQueries]);
+const fitSizes = sizesForFit(breakpoints);
+if (fitSizes.length) {
+  const queue = [...fitSizes];
+  const browser2 = await openBrowser(flags.cdp);
+  try {
+    await Promise.all(Array.from({ length: 3 }, async () => {
+      for (let s = queue.shift(); s; s = queue.shift()) {
+        const { context, page } = await newPage(browser2, { name: `fit${s.width}`, width: s.width, height: s.height });
+        try {
+          await page.goto(url, { waitUntil: 'load', timeout: 60000 });
+          await settle(page, hide);
+          inlineStyles[`${s.width}x${s.height}`] = await page.evaluate(readInlineStyles);
+        } catch (e) { console.warn(`WARNING inline styles at ${s.width}x${s.height} not read: ${e.message.split('\n')[0]}`); }
+        finally { await context.close(); }
+      }
+    }));
+  } finally {
+    if (!flags.cdp) await browser2.close();
+  }
+}
+await fs.writeFile(path.join(ref, 'inline-styles.json'), JSON.stringify({ breakpoints, scriptQueries: [...scriptQueries], sizes: Object.keys(inlineStyles), styles: inlineStyles }));
+console.log(`inline styles read at ${Object.keys(inlineStyles).length} sizes (site breakpoints: ${breakpoints.join(', ') || 'none found'}; ${scriptQueries.size} width quer${scriptQueries.size === 1 ? 'y' : 'ies'} asked by its scripts)`);
 await fs.writeFile(path.join(ref, 'meta.json'), JSON.stringify({ url, name, mode, permission, hide, capturedAt: new Date().toISOString(), rootFontSize, viewports: summary }, null, 2));
 await buildMirror(manifest, url, mode === 'exact' ? `Exact mode, authorised by: ${permission}.` : "Template mode: the site's own content, kept as a reference only.");
 console.table(summary);
@@ -364,3 +386,93 @@ async function fetchMissing(urls, manifest, pageUrl) {
   await Promise.all(Array.from({ length: 6 }, worker));
   return added;
 }
+
+// Inline styles and classes of every styled element, by element path, with the size actually laid out (clientWidth
+// excludes a classic scrollbar; scripts measure that, not the window).
+function readInlineStyles() {
+  const SKIP = new Set(['SCRIPT', 'NOSCRIPT', 'TEMPLATE', 'STYLE', 'LINK', 'META']);
+  const pathOf = (el) => {
+    const parts = [];
+    for (let n = el; n && n !== document.body; n = n.parentElement) {
+      const sibs = [...n.parentElement.children].filter((c) => !SKIP.has(c.tagName));
+      parts.unshift(`${n.tagName.toLowerCase()}:${sibs.indexOf(n) + 1}`);
+    }
+    return parts.join('>');
+  };
+  const styles = {};
+  for (const el of document.body.querySelectorAll('[style]')) {
+    if (SKIP.has(el.tagName) || (el.closest('svg') && el.tagName !== 'svg')) continue;
+    styles[pathOf(el)] = [el.getAttribute('style'), String(el.getAttribute('class') || '')];
+  }
+  return { w: document.documentElement.clientWidth, h: innerHeight, styles };
+}
+
+// Every media query the page's scripts ask (GSAP matchMedia, Webflow, a component's own breakpoint): what a script
+// does can switch at a width no stylesheet mentions.
+function recordMediaQueries() {
+  const seen = (window.__tcMediaQueries = []);
+  const original = window.matchMedia;
+  if (!original) return;
+  window.matchMedia = function matchMedia(q) {
+    if (typeof q === 'string' && /width/.test(q) && !seen.includes(q)) seen.push(q);
+    return original.call(this, q);
+  };
+}
+
+// The width breakpoints the site's stylesheets use at least twice (min-width: 992px is a boundary at 991), and every
+// width its scripts ask about (always kept: a script's breakpoint is behaviour).
+async function siteBreakpoints(manifest, scriptQueries = []) {
+  const count = new Map();
+  for (const q of scriptQueries) {
+    for (const m of q.matchAll(/(min|max)-width\s*:\s*([\d.]+)(px|em|rem)/g)) {
+      const px = Number(m[2]) * (m[3] === 'px' ? 1 : 16);
+      const edge = Math.round(m[1] === 'min' ? px - 1 : px);
+      if (edge >= 300 && edge <= 2600) count.set(edge, (count.get(edge) || 0) + 100);
+    }
+  }
+  const texts = [];
+  for (const m of manifest.filter((x) => x.type === 'stylesheet')) texts.push(await fs.readFile(path.join(ref, m.file), 'utf8').catch(() => ''));
+  const rendered = await fs.readFile(path.join(ref, 'rendered.html'), 'utf8').catch(() => '');
+  for (const m of rendered.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi)) texts.push(m[1]);
+  for (const t of texts) {
+    for (const q of t.matchAll(/@media[^{]*/g)) {
+      for (const m of q[0].matchAll(/(min|max)-width\s*:\s*([\d.]+)(px|em|rem)/g)) {
+        const px = Number(m[2]) * (m[3] === 'px' ? 1 : 16);
+        const edge = Math.round(m[1] === 'min' ? px - 1 : px);
+        if (edge >= 300 && edge <= 2600) count.set(edge, (count.get(edge) || 0) + 1);
+      }
+    }
+  }
+  // breakpoints within 2px of each other are one (991 from max-width, 991 from min-width: 992)
+  const edges = [...count].filter(([, n]) => n >= 2).sort((a, b) => a[0] - b[0]);
+  const merged = [];
+  for (const [e, n] of edges) { const last = merged[merged.length - 1]; if (last && e - last.e <= 2) last.n += n; else merged.push({ e, n }); }
+  return merged.sort((a, b) => b.n - a.n).slice(0, 9).map((x) => x.e).sort((a, b) => a - b);
+}
+
+// Extra sizes for fitting: at least three points in every breakpoint range (counting the seed sizes in it), at
+// different heights, so a value that depends on the width, the height or both can be told apart from a constant.
+function sizesForFit(breakpoints) {
+  const edges = [320, ...breakpoints, 2400];
+  const taken = new Set([...VIEWPORTS, ...HELD_OUT].map((v) => `${v.width}x${v.height}`));
+  const out = [];
+  const heights = [760, 1000, 880];
+  for (let i = 0; i < edges.length - 1; i++) {
+    const lo = i === 0 ? edges[0] : edges[i] + 1, hi = edges[i + 1];
+    if (hi - lo < 8) { // a narrow band (760 and 767 both breakpoints) still has its own rules: sample both edges
+      for (const [w, h] of [[lo, heights[i % 3]], [hi, heights[(i + 1) % 3]]]) if (!taken.has(`${w}x${h}`)) { taken.add(`${w}x${h}`); out.push({ width: w, height: h }); }
+      continue;
+    }
+    const seeds = VIEWPORTS.filter((v) => v.width >= lo && v.width <= hi).length;
+    const want = Math.max(2, 3 - seeds);
+    for (let k = 0; k < want; k++) {
+      const w = Math.round(lo + (hi - lo) * [0.25, 0.75, 0.5][k]);
+      const h = heights[(i + k) % heights.length];
+      if (!taken.has(`${w}x${h}`)) { taken.add(`${w}x${h}`); out.push({ width: w, height: h }); }
+    }
+  }
+  // Two very wide, short screens: most sizes above are taller than 16:9, so a "cover" rule (max(100vw, 177.8vh))
+  // would have one point at most on its width side. Two make it checkable (see fitCover in viewport-fit.mjs).
+  for (const [w, h] of [[2400, 760], [2200, 900]]) if (!taken.has(`${w}x${h}`)) { taken.add(`${w}x${h}`); out.push({ width: w, height: h }); }
+  return out;
+}

package/scripts/curves.mjs

@@ -7,7 +7,7 @@
 //   { "name": "quote reveal", "ref": ".is-quote .reveal-line", "clone": ".is-quote .split-line",
 //     "props": ["ty"], "time": { "before": 0, "at": 700, "ms": 1400, "every": 100 } }
 //
-// selector@n picks the n-th match (default 0). Props: opacity, tx, ty, sx, sy, rot, top, left, width, height, saturate.
+// selector@n picks the n-th match (default 0); path:<recorded path> picks an element the reveals recorder saw. Props: opacity, tx, ty, sx, sy, rot, top, left, width, height, saturate.
 // Viewport-independent ranges: "scroll": { "of": { "ref": "...", "clone": "..." }, "start": "top bottom", "end": "bottom top", "steps": 10 }
 // resolve each side's own scroll positions, so one map scores desktop, tablet and mobile (--viewport tablet).
 // usage: node scripts/curves.mjs <name> [--viewport desktop] [--only "<name substring>"]
@@ -29,7 +29,7 @@ const vp = VIEWPORTS.find((v) => v.name === (flags.viewport || 'desktop'));
 
 // ---------- Draft a map from the motion inventory ----------
 if (flags.draft) {
-  const motion = JSON.parse(await fs.readFile(path.join(ref, `motion.${vp.name}.json`), 'utf8'));
+  const motion = JSON.parse(await fs.readFile(path.join(ref, `motion.${vp.name}.json`), 'utf8').catch(() => '{"triggers":[],"onScroll":[]}'));
   const propsFor = (vars) => {
     const out = new Set();
     for (const k of Object.keys(vars || {})) {
@@ -69,9 +69,27 @@ if (flags.draft) {
     const y = tw.firedAt[0];
     entries.push({ name: `reveal ${sel}`, ref: sel, clone: 'TODO', props: propsFor({ ...leaf.vars, ...(leaf.vars.startAt || {}) }), time: { before: Math.max(0, y - vp.height), at: y, ms: Math.ceil((tw.duration + 0.4) * 10) * 100, every: 100 } });
   }
+  // Scroll-linked curves the recorder sampled (any library, or none the inventory can read): one entry per element,
+  // over the scroll range it was seen moving at this size
+  const recorded = JSON.parse(await fs.readFile(path.join(ref, `reveals.${vp.name}.json`), 'utf8').catch(() => '{}')).scrubs || [];
+  let fromScrubs = 0;
+  for (const s of recorded) {
+    const samples = (s.samples || []).filter((x) => x && Number.isFinite(x.y));
+    if (samples.length < 2 || seen.has(`path:${s.path}`)) continue;
+    const moved = (k) => Math.max(...samples.map((x) => x[k] ?? 0)) - Math.min(...samples.map((x) => x[k] ?? 0));
+    const props = [];
+    if (moved('o') > 0.02) props.push('opacity');
+    if (moved('tx') > 1) props.push('tx');
+    if (moved('ty') > 1) props.push('ty');
+    if (moved('s') > 0.01) props.push('sx', 'sy');
+    if (!props.length) continue;
+    seen.add(`path:${s.path}`);
+    fromScrubs++;
+    entries.push({ name: `scrub ${s.cls || s.path}`, ref: `path:${s.path}`, clone: 'TODO', props, viewports: [vp.name], scroll: { from: samples[0].y, to: samples.at(-1).y, steps: Math.min(12, Math.max(4, samples.length - 1)) } });
+  }
   const out = path.join(root, 'motion-map.draft.json');
   await fs.writeFile(out, JSON.stringify(entries, null, 2));
-  console.log(`${entries.length} entries -> ${path.relative(process.cwd(), out)}. Fill in the clone selectors, then save as motion-map.json.`);
+  console.log(`${entries.length} entries (${fromScrubs} from recorded scroll curves) -> ${path.relative(process.cwd(), out)}. Fill in the clone selectors, then save as motion-map.json.`);
   process.exit(0);
 }
 
@@ -86,9 +104,28 @@ let map = JSON.parse(mapText);
 if (typeof flags.only === 'string') map = map.filter((e) => e.name.includes(flags.only));
 map = map.filter((e) => e.clone && e.clone !== 'TODO' && (!e.viewports || e.viewports.includes(vp.name)));
 
+// `path:section:3>div:2` is a recorded element path (from trueclone reveals: tag:position among the children that
+// are not script/style/meta, 1-based, from <body>); anything else is a CSS selector with an optional @n.
+// Installed on every page as window.__tcFind.
+function installFind() {
+  window.__tcFind = (selector) => {
+    if (selector.startsWith('path:')) {
+      const SKIP = new Set(['SCRIPT', 'NOSCRIPT', 'TEMPLATE', 'STYLE', 'LINK', 'META']);
+      let n = document.body;
+      for (const part of selector.slice(5).split('>')) {
+        const [tag, i] = part.split(':');
+        n = n && [...n.children].filter((c) => !SKIP.has(c.tagName))[Number(i) - 1];
+        if (!n || n.tagName.toLowerCase() !== tag) return null;
+      }
+      return n;
+    }
+    const [sel, idx] = selector.split('@');
+    return document.querySelectorAll(sel)[Number(idx || 0)] || null;
+  };
+}
+
 function sampleInPage([selector, props]) {
-  const [sel, idx] = selector.split('@');
-  const el = document.querySelectorAll(sel)[Number(idx || 0)];
+  const el = window.__tcFind(selector);
   if (!el) return null;
   const s = getComputedStyle(el);
   const m = new DOMMatrixReadOnly(s.transform === 'none' ? undefined : s.transform);
@@ -132,6 +169,7 @@ async function run(url, side, entries, onEntry) {
   };
   try {
     const { context, page } = await newPage(browser, vp, { reducedMotion: 'no-preference' });
+    await page.addInitScript(installFind);
     await page.goto(url, { waitUntil: 'load', timeout: 60000 });
     await page.mouse.move(5, vp.height - 5);
     await waitStill(page, { timeout: 15000, interval: 200 });
@@ -139,8 +177,7 @@ async function run(url, side, entries, onEntry) {
     // Scroll entries: resolve every range first (at the top, before anything is pinned), then visit all sample
     // positions of all curves in one downward pass, so the page glides short distances and never rewinds.
     const resolve = (of, spec) => page.evaluate(([sel, s]) => {
-      const [selector, idx] = sel.split('@');
-      const el = document.querySelectorAll(selector)[Number(idx || 0)];
+      const el = window.__tcFind(sel);
       if (!el) return 0;
       const r = el.getBoundingClientRect();
       const top = r.top + scrollY;

package/scripts/diff.mjs

@@ -3,7 +3,7 @@
 // Without --url it serves sites/<name>/clone/ itself on a free local port.
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { VIEWPORTS, parseArgs, openBrowser, newPage, settle, mask, serve, pad, crop, match, PNG } from './lib.mjs';
+import { SCORED, parseArgs, openBrowser, newPage, settle, mask, serve, pad, crop, match, PNG } from './lib.mjs';
 
 const { pos, flags } = parseArgs(process.argv.slice(2));
 const [name] = pos;
@@ -25,7 +25,9 @@ const target = typeof flags.url === 'string' ? flags.url : server.url;
 const browser = await openBrowser(flags.cdp);
 const report = { name, mode: structure ? 'structure' : 'visual', source: meta.url, clone: target, at: new Date().toISOString(), viewports: [] };
 try {
-  for (const vp of VIEWPORTS) {
+  for (const vp of SCORED) {
+    // a capture made before held-out sizes existed has no reference for them: skipped, not failed
+    if (!(await fs.stat(path.join(ref, `${vp.name}${suffix}.png`)).then(() => true, () => false))) { console.log(`${vp.name}: no reference capture at ${vp.width}x${vp.height} (re-capture to score it)`); continue; }
     const { context, page } = await newPage(browser, vp);
     await page.goto(target, { waitUntil: 'load', timeout: 60000 });
     await settle(page);

package/scripts/drift.mjs

@@ -6,7 +6,7 @@
 // usage: node scripts/drift.mjs <name> [--viewport desktop|all]
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { VIEWPORTS, parseArgs, openBrowser, newPage, settle, sectionsOf } from './lib.mjs';
+import { SCORED as VIEWPORTS, parseArgs, openBrowser, newPage, settle, sectionsOf } from './lib.mjs';
 
 const { pos, flags } = parseArgs(process.argv.slice(2));
 const [name] = pos;
@@ -24,19 +24,26 @@ try {
   for (const vp of vps) {
     const captured = meta.viewports?.find((v) => v.viewport === vp.name);
     if (!captured) continue;
-    const { context, page } = await newPage(browser, vp);
-    try {
-      await page.goto(meta.url, { waitUntil: 'load', timeout: 60000 });
-      await settle(page, meta.hide || []);
-      const livePageHeight = await page.evaluate(() => document.documentElement.scrollHeight);
-      const liveSections = (await sectionsOf(page)).length;
-      // 1% (at least 40px) absorbs font hinting and a rotating line of text; a new section or a block that moved is above that
-      const stale = Math.abs(livePageHeight - captured.pageHeight) > Math.max(40, captured.pageHeight * 0.01) || liveSections !== captured.sections;
-      viewports.push({ viewport: vp.name, livePageHeight, capturedPageHeight: captured.pageHeight, liveSections, capturedSections: captured.sections, stale });
-      console.log(`${vp.name}: live ${livePageHeight}px / ${liveSections} sections, captured ${captured.pageHeight}px / ${captured.sections} sections${stale ? '  <- changed since the capture' : '  (same)'}`);
-    } finally {
-      await context.close();
-    }
+    const sample = async () => {
+      const { context, page } = await newPage(browser, vp);
+      try {
+        await page.goto(meta.url, { waitUntil: 'load', timeout: 60000 });
+        await settle(page, meta.hide || []);
+        return { h: await page.evaluate(() => document.documentElement.scrollHeight), n: (await sectionsOf(page)).length };
+      } finally {
+        await context.close();
+      }
+    };
+    // 1% (at least 40px) absorbs font hinting and a rotating line of text; a new section or a block that moved is above that
+    const differs = (s) => Math.abs(s.h - captured.pageHeight) > Math.max(40, captured.pageHeight * 0.01) || s.n !== captured.sections;
+    // a page that renders differently from one load to the next (a random block, a late embed) is not a changed site:
+    // a difference counts only when a second load shows it too
+    let s = await sample();
+    let confirmed = false;
+    if (differs(s)) { const again = await sample(); confirmed = differs(again); if (!confirmed) s = again; }
+    const stale = confirmed;
+    viewports.push({ viewport: vp.name, livePageHeight: s.h, capturedPageHeight: captured.pageHeight, liveSections: s.n, capturedSections: captured.sections, stale });
+    console.log(`${vp.name}: live ${s.h}px / ${s.n} sections, captured ${captured.pageHeight}px / ${captured.sections} sections${stale ? '  <- changed since the capture (seen on two loads)' : '  (same)'}`);
   }
 } finally {
   if (!flags.cdp) await browser.close();