@trueclone/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ayush Pratap Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,135 @@
-# Temporary Holding Version
+# trueclone
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**A working twin of any website, from one URL, with scores that 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`.
+
+```bash
+npx @trueclone/cli init            # once per project: installs trueclone, the skill for your agent, REA as an MCP server
+# then tell Claude Code, Codex or Cursor:
+#   "clone https://example.com with trueclone"
+```
+
+## What you get from one URL
+
+| Output | What it is |
+|---|---|
+| `clone/` | The site in plain HTML, CSS and JS, interactions included (sliders, tabs, menus, canvas demos, scroll motion) |
+| `next/` | The same site as a Next.js + Tailwind v4 + shadcn app, one component per section, scored against the original too |
+| `DESIGN.md` | The design system in [Google's design.md format](https://github.com/google-labs-code/design.md), linted |
+| `globals.css` | A shadcn theme (Tailwind v4, oklch) generated from the same tokens |
+| `motion.md` | The motion recipe: every ScrollTrigger, tween, reveal and loop with its trigger, range, easing and timing |
+| `REPORT.md` | Every score against its target, what to fix first, and what was not copied (server logic, tracking, each API call) |
+
+## Proof
+
+Two benchmarks with very different stacks, scored by the tool itself:
+
+**[rea.tools](https://rea.tools/)**: static docs with a canvas game and interactive demos, exact mode (copied with the owner's permission).
+
+| Check | Desktop | Tablet | Mobile |
+|---|---|---|---|
+| Layout, real pixels | 100% | 100% | 100% |
+| Scroll states | 100% | 100% | 99.99% |
+| Computed styles (≈280 points per width) | 100% | 100% | 100% |
+| Hover effects | 100% | | |
+| Interactions (copy, tabs, calculator, dinosaur game, language menu) | 5/5 | | |
+
+**A Webflow motorsport portfolio** built with GSAP, ScrollTrigger, SplitText, Lenis, Swiper and three.js (97 scroll triggers), template mode (own placeholder content):
+
+| Check | Desktop | Tablet | Mobile |
+|---|---|---|---|
+| Layout, structure | 99.6% | 99.7% | 96.8% |
+| Scroll states | 97.1% | 96.7% | 96.5% |
+| Motion curves | 96.1% | 98.2% | 100% |
+| Computed styles | 94% | 88.9% | 81.8% |
+| Hover effects | 100% | | |
+| Interactions (drag sliders, drag gallery, cursor follow, menu, skip) | 5/5 | | |
+
+Not perfect yet, and the report says so: the computed-style check is below its 95% target (placeholder text in highlighted phrases, a scroll-linked colour fade, mobile spacing), and so is mobile layout. The generated Next.js app scores within half a point of the HTML clone on every check. A full scoring run takes 1 to 9 minutes.
+
+## How it works
+
+```
+URL ─► capture ─► understand ─► design system ─► build ─► score ─► report
+        3 widths    motion         DESIGN.md        your      7 checks   REPORT.md
+        HAR, HTML   inventory      globals.css      agent     in parallel
+        assets      + REA          tokens.css                  ▲     │
+                                                               └─────┘ until every target passes
+```
+
+1. **Capture** (`trueclone capture`): full-page screenshots at 390, 768 and 1440px, sections, rendered HTML, assets, every network request.
+2. **Understand** (`trueclone motion`, REA): reads the live animation runtime (GSAP timelines, ScrollTriggers, Lenis and Swiper settings, CSS animations, cursor-driven tweens) and, through REA, bundles, source maps, event listeners and API endpoints.
+3. **Design system** (`trueclone design`): one canonical `design-tokens.json`, rendered to DESIGN.md, globals.css and the clone's tokens.
+4. **Build**: your agent writes the clone, guided by the skill. `trueclone rules` shows the original's CSS for any element (like DevTools), `trueclone textshape` gives placeholder text the original's line breaks, `trueclone seed` starts an exact clone from a script-free mirror.
+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. 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.
+
+## Why not just 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?* For the hard parts (a bundled physics rule, a shader, the API a component calls) the skill sends your agent to REA.
+
+## Modes and guardrails
+
+| Mode | For | Content |
+|---|---|---|
+| `template` (default) | Any site: learning, layout study, a starting template | Structure, motion and behaviour of the original; your own text, images and brand |
+| `exact` | Sites you own or are authorised to copy, such as a Webflow, Framer or WordPress site moving to Next.js | The site's own text and media |
+
+- Exact mode refuses to run without `--permission "<who authorised it>"` and records it in the capture and the report.
+- No bot-check, CAPTCHA, login or paywall bypass. Tracking and analytics are never copied.
+- Clones are `noindex`, forms submit nowhere, and everything stays in your local `sites/` folder.
+
+## Commands
+
+```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 <url> [name]              # capture + design-system draft
+npx trueclone capture <url> [name] [--mode exact --permission "<owner>"]
+npx trueclone motion <name>             # motion inventory
+npx trueclone design <name>             # DESIGN.md + globals.css
+npx trueclone seed <name>               # exact mode: start clone/ from the mirror
+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 score <name> [--quick]    # every check, then REPORT.md
+npx trueclone next <name> --verify      # Next.js + Tailwind + shadcn app, scored
+npx trueclone rea <args>                # bundled REA
+npx trueclone help                      # every step
+```
+
+## What it can't do
+
+- **Server-side behaviour** is invisible from outside: databases, accounts, payments, search. trueclone rebuilds the client and lists every API call the original makes in the report.
+- A live site is never pixel-identical twice: rotating content, A/B tests and font hinting vary.
+- One page at a time today. Multi-page crawling with shared components is next.
+- Developed and tested on Windows 11 with Chrome. macOS and Linux should work but aren't tested yet.
+
+## Requirements
+
+Node 22.19+, 24.11+ or 26+ (the same as REA), and Google Chrome for captures (it plays the H.264/HLS video many sites use; Playwright's Chromium is the fallback). A coding agent: Claude Code, Codex, Cursor or any agent that reads `AGENTS.md`.
+
+## Roadmap
+
+- **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.
+- **A free web page:** paste a URL, get its DESIGN.md and globals.css.
+
+## Credits
+
+[REA](https://github.com/morluto/rea) by morluto (MIT), [Playwright](https://playwright.dev), [pixelmatch](https://github.com/mapbox/pixelmatch), [@google/design.md](https://github.com/google-labs-code/design.md), [parse5](https://github.com/inikulin/parse5), and the [shadcn](https://ui.shadcn.com) theme format.
+
+## License
+
+MIT

package/bin/trueclone.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+// trueclone CLI: one entry point for every step. Steps run in the current folder: everything about a site lives
+// in ./sites/<name>/ (reference capture, clone, Next.js app, design system, scores).
+//
+//   npx @trueclone/cli init         set up this folder for a coding agent (skill, AGENTS.md, REA MCP, .gitignore) and
+//                                   install trueclone as a dev dependency, so `npx trueclone <step>` works from then on
+//   trueclone <url> [name]          capture a site (template mode) and draft its design system: the agent's first step
+//   trueclone <step> <name> [...]   run one step (see `trueclone help`)
+//   trueclone rea <args>            REA (Reverse Engineer Anything), bundled: `trueclone rea mcp`, `trueclone rea doctor`
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const PKG = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SCRIPTS = path.join(PKG, 'scripts');
+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)'],
+  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)'],
+  states: ['states.mjs', 'live scroll states; --clone scores the rebuild step by step'],
+  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'],
+  rules: ['rules.mjs', 'every CSS rule matching an element on the reference (+ ::before/::after, @media)'],
+  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'],
+  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'],
+};
+
+const run = (file, args) => new Promise((resolve) => {
+  const child = spawn(process.execPath, [file, ...args], { stdio: 'inherit' });
+  child.on('close', (code) => resolve(code ?? 1));
+});
+
+function help() {
+  console.log(`trueclone ${version}: a working twin of a website, proven by scores
+
+usage
+  npx @trueclone/cli init            set up this folder for your coding agent (installs trueclone)
+  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
+
+steps
+${Object.entries(STEPS).map(([k, [, d]]) => `  ${k.padEnd(10)} ${d}`).join('\n')}
+
+Then ask your agent: "clone <url> with trueclone". The skill walks it through capture, build, scores and report.`);
+}
+
+async function exists(file) { return fs.stat(file).then(() => true, () => false); }
+
+async function init() {
+  const cwd = process.cwd();
+  // 1. the agent skill (Claude Code reads .claude/skills; other agents read AGENTS.md, which points at the same file)
+  const skillDir = path.join(cwd, '.claude', 'skills', 'trueclone');
+  await fs.mkdir(skillDir, { recursive: true });
+  await fs.copyFile(path.join(PKG, 'skill', 'SKILL.md'), path.join(skillDir, 'SKILL.md'));
+  // 2. AGENTS.md block for Codex, Cursor and other agents
+  const agentsFile = path.join(cwd, 'AGENTS.md');
+  const block = `<!-- trueclone:start -->\n## Cloning websites with trueclone\n\nTo clone or rebuild a website, read \`.claude/skills/trueclone/SKILL.md\` first and follow it step by step. Run every step with \`npx trueclone <step> <name>\` and finish only when \`npx trueclone score <name>\` passes the targets in the skill; \`sites/<name>/REPORT.md\` is the deliverable.\n<!-- trueclone:end -->\n`;
+  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`);
+  // 4. captures, clones and browser profiles stay local
+  const ignoreFile = path.join(cwd, '.gitignore');
+  let ignore = (await exists(ignoreFile)) ? await fs.readFile(ignoreFile, 'utf8') : '';
+  const want = ['sites/', '.chrome-profile/', '*.har'].filter((line) => !ignore.split(/\r?\n/).includes(line));
+  if (want.length) await fs.writeFile(ignoreFile, `${ignore}${ignore && !ignore.endsWith('\n') ? '\n' : ''}${want.join('\n')}\n`);
+  // 5. the package itself as a dev dependency, pinned: afterwards `npx trueclone <step>` runs this version, offline
+  let installed = 'skipped (--no-install)';
+  if (!process.argv.includes('--no-install')) {
+    if (!(await exists(path.join(cwd, 'package.json')))) await fs.writeFile(path.join(cwd, 'package.json'), `${JSON.stringify({ name: path.basename(cwd).toLowerCase().replace(/[^a-z0-9-]+/g, '-'), private: true }, null, 2)}\n`);
+    const code = await new Promise((resolve) => {
+      const child = spawn(process.platform === 'win32' ? 'npm.cmd' : 'npm', ['install', '--save-dev', '--save-exact', `${name}@${version}`], { stdio: 'inherit', shell: process.platform === 'win32' });
+      child.on('close', (c) => resolve(c ?? 1));
+    });
+    installed = code === 0 ? `${name}@${version} (dev dependency: npx trueclone <step> now runs it)` : `failed: run npm install -D ${name}@${version} yourself`;
+  }
+  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
+  package.json                        ${installed}
+next: npx trueclone doctor, then ask your agent "clone <url> with trueclone"`);
+}
+
+async function doctor() {
+  let ok = true;
+  const [major, minor] = process.versions.node.split('.').map(Number);
+  const nodeOk = (major === 22 && minor >= 19) || (major === 24 && minor >= 11) || major >= 26;
+  console.log(`${nodeOk ? 'ok  ' : 'FAIL'} Node ${process.versions.node} (needs 22.19+, 24.11+ or 26+)`);
+  ok &&= nodeOk;
+  const { chromium } = await import('playwright');
+  for (const [label, opts] of [['Chrome (captures; plays H.264/HLS video)', { channel: 'chrome' }], ['Playwright Chromium (fallback)', {}]]) {
+    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; }
+  process.exitCode = ok ? 0 : 1;
+}
+
+const [cmd, ...rest] = process.argv.slice(2);
+if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') help();
+else if (cmd === '--version' || cmd === '-v') console.log(version);
+else if (cmd === 'init') await init();
+else if (cmd === 'doctor') await doctor();
+else if (cmd === 'rea') process.exitCode = await run(path.join(path.dirname(require.resolve('rea-agents/package.json')), 'scripts', 'rea.mjs'), rest);
+else if (/^https?:\/\//.test(cmd)) {
+  // the first step for any site: capture it (template mode) and draft its design system
+  const name = rest.find((a) => !a.startsWith('--')) || new URL(cmd).hostname.replace(/^www\./, '').replace(/\.[a-z]+$/, '').replace(/[^a-z0-9]+/gi, '-');
+  let code = await run(path.join(SCRIPTS, 'capture.mjs'), [cmd, name, ...rest.filter((a) => a !== name)]);
+  if (code === 0) code = await run(path.join(SCRIPTS, 'design.mjs'), [name]);
+  if (code === 0) console.log(`\nnext: npx trueclone motion ${name}, then build sites/${name}/clone/ following .claude/skills/trueclone/SKILL.md`);
+  process.exitCode = code;
+} else if (STEPS[cmd]) process.exitCode = await run(path.join(SCRIPTS, STEPS[cmd][0]), rest);
+else {
+  console.error(`unknown command: ${cmd}\n`);
+  help();
+  process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@trueclone/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.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": {
+    "trueclone": "bin/trueclone.mjs"
+  },
+  "files": [
+    "bin/",
+    "scripts/*.mjs",
+    "skill/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": "^22.19.0 || ^24.11.0 || >=26.0.0"
+  },
+  "scripts": {
+    "trueclone": "node bin/trueclone.mjs",
+    "chrome": "powershell -ExecutionPolicy Bypass -File scripts/chrome-debug.ps1"
+  },
+  "dependencies": {
+    "@google/design.md": "^0.4.0",
+    "parse5": "^8.0.1",
+    "pixelmatch": "^7.2.0",
+    "playwright": "^1.64.0",
+    "pngjs": "^7.0.0",
+    "rea-agents": "^6.4.0"
+  },
+  "keywords": [
+    "clone",
+    "website",
+    "replicate",
+    "rebuild",
+    "migration",
+    "design-system",
+    "design.md",
+    "shadcn",
+    "nextjs",
+    "tailwind",
+    "playwright",
+    "pixel-diff",
+    "gsap",
+    "coding-agent",
+    "claude-code",
+    "mcp",
+    "reverse-engineering",
+    "rea"
+  ],
+  "author": "Ayush Pratap Singh",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ayuxh-Pratap/trueclone.git"
+  },
+  "homepage": "https://github.com/Ayuxh-Pratap/trueclone#readme",
+  "bugs": {
+    "url": "https://github.com/Ayuxh-Pratap/trueclone/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/capture.mjs

@@ -0,0 +1,189 @@
+// Capture a live page as the clone's reference: full-page screenshots, sections, design tokens,
+// rendered HTML, CSS/image/font files and a HAR.
+// usage: node scripts/capture.mjs <url> [name] [--hide ".cookie-banner,#popup"] [--cdp [endpoint]]
+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';
+
+const { pos, flags } = parseArgs(process.argv.slice(2));
+const [url, nameArg] = pos;
+if (!url) {
+  console.error('usage: npm run capture -- <url> [name] [--hide "<css selectors>"] [--cdp]');
+  process.exit(1);
+}
+const name = nameArg || siteName(url);
+const hide = typeof flags.hide === 'string' ? flags.hide.split(',').map((s) => s.trim()).filter(Boolean) : [];
+// --mode template (default): assets are kept as reference only; the clone uses placeholder content.
+// --mode exact: the clone may reuse the site's own text and media. Only for sites you own or are
+// authorised to copy, so it refuses to run without --permission "<who authorised it>". Output stays in
+// sites/ (gitignored), the mirror is noindex with every script removed, and nothing here deploys it.
+const mode = flags.mode === 'exact' ? 'exact' : 'template';
+const permission = typeof flags.permission === 'string' ? flags.permission : null;
+if (mode === 'exact' && !permission) {
+  console.error('exact mode copies the site\'s own text and media. Pass --permission "<owner / who authorised this copy>".');
+  process.exit(1);
+}
+const root = path.resolve('sites', name);
+const ref = path.join(root, 'reference');
+const MAX_ASSET_BYTES = mode === 'exact' ? 200 * 1024 * 1024 : 15 * 1024 * 1024;
+const SAVED_TYPES = new Set(['stylesheet', 'image', 'font', 'media']);
+// Exact mode also keeps runtime-fetched media: 3D models, textures, video streams, animation files. Never scripts.
+const EXTRA_MEDIA = /\.(glb|gltf|bin|hdr|exr|ktx2|basis|mp4|webm|mov|m3u8|ts|m4s|lottie|riv|json)(\?|$)/i;
+const keepResponse = (type, url) => SAVED_TYPES.has(type) || (mode === 'exact' && ['fetch', 'xhr', 'other'].includes(type) && EXTRA_MEDIA.test(url));
+
+// Only clear what capture owns; states/, motion.*, *.spec.json come from other scripts and stay.
+await fs.rm(path.join(ref, 'assets'), { recursive: true, force: true });
+await fs.rm(path.join(ref, 'mirror'), { recursive: true, force: true });
+await fs.mkdir(path.join(ref, 'assets'), { recursive: true });
+
+function tokensInPage() {
+  const count = (m, k) => m.set(k, (m.get(k) || 0) + 1);
+  const colors = new Map(), bgs = new Map(), fonts = new Map(), type = new Map(), radii = new Map(), shadows = new Map();
+  for (const el of [...document.querySelectorAll('body *')].slice(0, 8000)) {
+    const s = getComputedStyle(el);
+    if (s.display === 'none' || s.visibility === 'hidden') continue;
+    if ([...el.childNodes].some((n) => n.nodeType === 3 && n.textContent.trim())) {
+      count(colors, s.color);
+      count(fonts, s.fontFamily);
+      count(type, `${s.fontSize} / ${s.lineHeight} / ${s.fontWeight} / ${s.letterSpacing}`);
+    }
+    if (s.backgroundColor !== 'rgba(0, 0, 0, 0)') count(bgs, s.backgroundColor);
+    if (s.backgroundImage !== 'none') count(bgs, s.backgroundImage.slice(0, 200));
+    if (s.borderRadius !== '0px') count(radii, s.borderRadius);
+    if (s.boxShadow !== 'none') count(shadows, s.boxShadow);
+  }
+  const top = (m) => [...m].sort((a, b) => b[1] - a[1]).slice(0, 30).map(([value, uses]) => ({ value, uses }));
+  const cssVariables = {};
+  for (const sheet of document.styleSheets) {
+    try {
+      for (const rule of sheet.cssRules) {
+        if (rule.selectorText === ':root' || rule.selectorText === 'html') {
+          for (const p of rule.style) if (p.startsWith('--')) cssVariables[p] = rule.style.getPropertyValue(p).trim();
+        }
+      }
+    } catch { /* cross-origin sheet */ }
+  }
+  return {
+    title: document.title,
+    lang: document.documentElement.lang,
+    bodyBackground: getComputedStyle(document.body).backgroundColor,
+    textColors: top(colors),
+    backgrounds: top(bgs),
+    fontFamilies: top(fonts),
+    typeScale: top(type),
+    radii: top(radii),
+    shadows: top(shadows),
+    cssVariables,
+    fontsLoaded: [...document.fonts].filter((f) => f.status === 'loaded').map((f) => `${f.family} ${f.weight} ${f.style}`),
+  };
+}
+
+const browser = await openBrowser(flags.cdp);
+const manifest = [];
+const summary = [];
+const rootFontSize = {};
+try {
+  for (const vp of VIEWPORTS) {
+    const desktop = vp.name === 'desktop';
+    const { context, page } = await newPage(browser, vp, desktop ? { recordHar: { path: path.join(ref, 'desktop.har'), content: 'omit' } } : {});
+    if (desktop) {
+      page.on('response', async (res) => {
+        const rawType = res.request().resourceType();
+        if (!keepResponse(rawType, res.url()) || res.status() >= 300) return;
+        const type = SAVED_TYPES.has(rawType) ? rawType : 'media';
+        try {
+          const body = await res.body();
+          if (body.length > MAX_ASSET_BYTES) return;
+          const u = new URL(res.url());
+          const base = (path.basename(u.pathname) || 'index').replace(/[^a-z0-9._-]/gi, '_').slice(-80);
+          const hash = crypto.createHash('sha1').update(res.url()).digest('hex').slice(0, 8);
+          const file = path.join('assets', type, `${hash}-${base}`);
+          await fs.mkdir(path.join(ref, 'assets', type), { recursive: true });
+          await fs.writeFile(path.join(ref, file), body);
+          manifest.push({ url: res.url(), type, file: file.replaceAll('\\', '/'), contentType: res.headers()['content-type'], bytes: body.length });
+        } catch { /* redirects, data: urls, aborted */ }
+      });
+    }
+    await page.goto(url, { waitUntil: 'load', timeout: 60000 });
+    await settle(page, hide);
+    await page.screenshot({ path: path.join(ref, `${vp.name}.png`), fullPage: true });
+    const sections = await sectionsOf(page);
+    await fs.writeFile(path.join(ref, `${vp.name}.sections.json`), JSON.stringify(sections, null, 2));
+    const height = await page.evaluate(() => document.documentElement.scrollHeight);
+    rootFontSize[vp.name] = await page.evaluate(() => getComputedStyle(document.documentElement).fontSize);
+    if (desktop) {
+      const html = await page.evaluate(() => {
+        const doc = document.documentElement.cloneNode(true);
+        doc.querySelector('style[data-lab-freeze]')?.remove();
+        return '<!DOCTYPE html>\n' + doc.outerHTML;
+      });
+      await fs.writeFile(path.join(ref, 'rendered.html'), html);
+      await fs.writeFile(path.join(ref, 'tokens.json'), JSON.stringify(await page.evaluate(tokensInPage), null, 2));
+    }
+    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 });
+    await context.close(); // flushes the HAR
+  }
+} finally {
+  if (!flags.cdp) await browser.close();
+}
+
+await fs.writeFile(path.join(ref, 'assets', 'manifest.json'), JSON.stringify(manifest, null, 2));
+await fs.writeFile(path.join(ref, 'meta.json'), JSON.stringify({ url, name, mode, permission, hide, capturedAt: new Date().toISOString(), rootFontSize, viewports: summary }, null, 2));
+if (mode === 'exact') await buildMirror();
+console.table(summary);
+console.log(`${manifest.length} assets saved. Reference: ${path.relative(process.cwd(), ref)}${mode === 'exact' ? ` (exact mode; mirror in reference/mirror, authorised by: ${permission})` : ''}`);
+
+// ---------- Exact mode: static local mirror of the rendered page ----------
+// Same DOM as rendered.html, asset URLs rewritten to the saved copies, every script and inline handler
+// removed (we never reuse the site's code), forms disabled, noindex. Static by design: motion is rebuilt
+// from the states/motion inventory, not replayed.
+async function buildMirror() {
+  const mirror = path.join(ref, 'mirror');
+  await fs.rm(mirror, { recursive: true, force: true });
+  await fs.mkdir(path.join(mirror, 'css'), { recursive: true });
+  const byUrl = new Map(manifest.map((m) => [m.url.split('#')[0], m]));
+  const abs = (u, base) => { try { return new URL(u.trim().replace(/^['"]|['"]$/g, '').replaceAll('&amp;', '&'), base).href.split('#')[0]; } catch { return null; } };
+  const cssName = (m) => path.basename(m.file);
+  // where a saved asset lives, seen from a file inside `fromDir`
+  const local = (absUrl, fromDir) => {
+    const m = absUrl && byUrl.get(absUrl);
+    if (!m) return null;
+    if (m.type === 'stylesheet') return path.relative(fromDir, path.join(mirror, 'css', cssName(m))).replaceAll('\\', '/');
+    return path.relative(fromDir, path.join(ref, m.file)).replaceAll('\\', '/');
+  };
+  const rewriteCssUrls = (css, base, fromDir) => css
+    .replace(/url\(\s*(['"]?)([^'")]+)\1\s*\)/g, (all, q, u) => (u.startsWith('data:') ? all : `url("${local(abs(u, base), fromDir) || abs(u, base) || u}")`))
+    .replace(/@import\s+(['"])([^'"]+)\1/g, (all, q, u) => `@import "${local(abs(u, base), fromDir) || u}"`);
+
+  // stylesheets: rewritten copies under mirror/css
+  for (const m of manifest.filter((x) => x.type === 'stylesheet')) {
+    const css = await fs.readFile(path.join(ref, m.file), 'utf8');
+    await fs.writeFile(path.join(mirror, 'css', cssName(m)), rewriteCssUrls(css, m.url, path.join(mirror, 'css')));
+  }
+
+  let html = await fs.readFile(path.join(ref, 'rendered.html'), 'utf8');
+  html = html
+    .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, '')
+    .replace(/<script\b[^>]*\/>/gi, '')
+    .replace(/<link\b[^>]*rel=["']?(?:modulepreload|preload)["']?[^>]*as=["']?script["']?[^>]*>/gi, '')
+    .replace(/\son[a-z]+\s*=\s*("[^"]*"|'[^']*')/gi, '')
+    .replace(/<form\b([^>]*?)\saction=("[^"]*"|'[^']*')/gi, '<form$1')
+    .replace(/<form\b/gi, '<form action="#"')
+    .replace(/\s(src|href|poster|data-src)=("|')([^"']+)\2/gi, (all, attr, q, u) => {
+      const l = local(abs(u, url), mirror);
+      return l ? ` ${attr}=${q}${l}${q}` : all;
+    })
+    .replace(/\s(srcset|data-srcset)=("|')([^"']+)\2/gi, (all, attr, q, list) => ` ${attr}=${q}${list.split(',').map((part) => {
+      const [u, ...rest] = part.trim().split(/\s+/);
+      return [local(abs(u, url), mirror) || u, ...rest].join(' ');
+    }).join(', ')}${q}`)
+    .replace(/<style\b([^>]*)>([\s\S]*?)<\/style>/gi, (all, attrs, css) => `<style${attrs}>${rewriteCssUrls(css, url, mirror)}</style>`)
+    .replace(/\sstyle=("|')([^"']*url\([^"']*)\1/gi, (all, q, css) => ` style=${q}${rewriteCssUrls(css, url, mirror)}${q}`)
+    .replace(/<head([^>]*)>/i, `<head$1>\n<!-- rea-lab local mirror of ${url}. Authorised by: ${permission.replace(/--/g, '-')}. Local reference only: do not deploy. -->\n<meta name="robots" content="noindex,nofollow">`);
+  await fs.writeFile(path.join(mirror, 'index.html'), html);
+  const missing = [...html.matchAll(/\s(?:src|href)=["'](https?:[^"']+)["']/gi)].map((m) => m[1]).filter((u) => !/^https?:\/\/[^/]+\/?$/.test(u));
+  console.log(`mirror: reference/mirror/index.html (${manifest.length} local assets, ${missing.length} remote URLs left, e.g. links)`);
+}