@trueclone/cli 0.0.0-stage → 0.2.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,146 @@
-# 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
+
+Three 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% | 100% |
+| Computed styles (≈280 points per width) | 100% | 100% | 100% |
+| Hover effects | 100% | | |
+| Interactions (copy, tabs, calculator, dinosaur game, language menu) | 5/5 | | |
+
+**A Next.js + React + Framer Motion developer landing page** (12,000px, 11 scroll reveals with spring easing, a scroll-state header, marquees, view-mounted components), template mode, **seeded automatically**: no hand-written layout code, no original text or media in the clone.
+
+| Check | Desktop | Tablet | Mobile |
+|---|---|---|---|
+| Layout, structure | 99.99% | 99.93% | 99.94% |
+| Scroll states | 99.96% | 99.92% | 99.94% |
+| Computed styles | 99.5% | 98.7% | 99.2% |
+| Hover effects | 100% | | |
+
+**A Webflow motorsport portfolio** built with GSAP, ScrollTrigger, SplitText, Lenis, Swiper and three.js (97 scroll triggers), template mode, built by hand before seeding existed:
+
+| Check | Desktop | Tablet | Mobile |
+|---|---|---|---|
+| Layout, structure | 99.6% | 99.7% | 96.8% |
+| Scroll states | 98.0% | 96.6% | 96.5% |
+| Motion curves | 96.9% | 98.2% | 99.6% |
+| Computed styles | 94% | 88.9% | 85.4% |
+| Hover effects | 100% | | |
+| Interactions (drag sliders, drag gallery, cursor follow, menu, skip) | 5/5 | | |
+
+The hand-built portfolio isn't perfect yet, and its report says so: computed styles and mobile layout are below target (placeholder text in highlighted phrases, a scroll-linked colour fade, mobile spacing). The generated Next.js app scores within half a point of the HTML clone on every check. A full scoring run takes 1.5 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**: `trueclone reveals` records the original's scroll reveals frame by frame 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) 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. 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 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 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,146 @@
+#!/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)'],
+  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'],
+  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'],
+};
+
+// npm/npx are .cmd files on Windows and need a shell; Node warns (DEP0190) when a shell gets separate arguments, so
+// build one quoted command line there instead
+const spawnCmd = (cmd, args, opts = {}) => (process.platform === 'win32'
+  ? spawn([cmd, ...args].map((a) => (/[\s"]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a)).join(' '), { ...opts, shell: true })
+  : spawn(cmd, args, opts));
+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 = spawnCmd('npm', ['install', '--save-dev', '--save-exact', `${name}@${version}`], { stdio: 'inherit' });
+      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.2.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,248 @@
+// 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]] [--mode exact --permission "<owner>"]
+//        node scripts/capture.mjs <url> <name> --mirror-only   (rebuild reference/mirror from the saved capture)
+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));
+
+// --mirror-only: rebuild reference/mirror from an existing capture (no new screenshots, caches stay valid)
+if (flags['mirror-only']) {
+  const meta = JSON.parse(await fs.readFile(path.join(ref, 'meta.json'), 'utf8'));
+  const saved = JSON.parse(await fs.readFile(path.join(ref, 'assets', 'manifest.json'), 'utf8'));
+  await buildMirror(saved, meta.url, meta.mode === 'exact' ? `Exact mode, authorised by: ${meta.permission}.` : "Template mode: the site's own content, kept as a reference only.");
+  process.exit(0);
+}
+
+// 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 });
+    // 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
+    // again at snapshot time is saved with the fullest content it had. Things that start full and empty out (a
+    // loader) are left alone.
+    if (desktop) await page.evaluate(() => {
+      const count = (el) => el.getElementsByTagName('*').length;
+      const initial = new WeakMap();
+      for (const el of document.body.getElementsByTagName('*')) initial.set(el, count(el));
+      window.__tcRich = new Map();
+      new MutationObserver((records) => {
+        for (const r of records) {
+          for (let el = r.target, up = 0; el instanceof Element && el !== document.body && up < 8; el = el.parentElement, up++) {
+            const start = initial.has(el) ? initial.get(el) : 0;
+            const n = count(el);
+            if (start > 0 || n === 0) continue;
+            const best = window.__tcRich.get(el);
+            if (!best || n > best.n) window.__tcRich.set(el, { n, html: el.innerHTML });
+          }
+        }
+      }).observe(document.body, { subtree: true, childList: true });
+    });
+    await settle(page, hide);
+    // 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 });
+    for (let tries = 0; tries < 3; tries++) {
+      await page.waitForTimeout(2000);
+      const again = await page.screenshot({ fullPage: true });
+      const same = again.equals(shot);
+      shot = again;
+      if (same) break;
+    }
+    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));
+    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(() => {
+        // restore view-mounted content (see above): only elements that are empty again now
+        const restore = [];
+        let i = 0;
+        for (const [el, best] of window.__tcRich || []) {
+          if (!el.isConnected || el.getElementsByTagName('*').length > 0) continue;
+          el.setAttribute('data-tc-rich', String(i));
+          restore[i++] = best.html;
+        }
+        const doc = document.documentElement.cloneNode(true);
+        for (const el of document.querySelectorAll('[data-tc-rich]')) el.removeAttribute('data-tc-rich');
+        for (const el of doc.querySelectorAll('[data-tc-rich]')) {
+          el.innerHTML = restore[Number(el.getAttribute('data-tc-rich'))];
+          el.removeAttribute('data-tc-rich');
+          // marked for the layout diff: a full-page still can't show view-mounted content on either side, so its box
+          // is excluded there (the scroll-state check, with a real viewport, scores it)
+          el.setAttribute('data-tc-viewmount', '');
+        }
+        doc.querySelector('style[data-lab-freeze]')?.remove();
+        console.log(`tc-rich: restored ${restore.length} view-mounted element(s)`);
+        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));
+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);
+console.log(`${manifest.length} assets saved. Reference: ${path.relative(process.cwd(), ref)}, mirror in reference/mirror${mode === 'exact' ? ` (exact mode, authorised by: ${permission})` : ''}`);
+
+// ---------- 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. Exact mode seeds the clone from it as is; template mode
+// seeds it with every text and medium swapped for placeholders (seed.mjs).
+async function buildMirror(manifest, url, note) {
+  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
+    // url(#id) points inside the document (SVG gradients, filters, masks): never resolve it against the stylesheet
+    .replace(/url\(\s*(['"]?)([^'")]+)\1\s*\)/g, (all, q, u) => (u.startsWith('data:') || u.trim().startsWith('#') ? 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<!-- trueclone local mirror of ${url}. ${note.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)`);
+}