@trueclone/cli 0.2.0 → 0.4.0-rc.1

package/skill/SKILL.md

@@ -1,158 +1,161 @@
 ---
 name: trueclone
-description: Build a working twin of a website from its URL - HTML/CSS/JS clone, Next.js + Tailwind + shadcn app, DESIGN.md and shadcn globals.css - and prove the match with layout, scroll-state, motion, interaction, hover and style scores at mobile, tablet and desktop widths. Use when the user gives a URL and asks to clone, replicate, rebuild or migrate a site or page, or to extract its design system.
+description: Build the exact same website from its URL - HTML/CSS/JS clone and Next.js + Tailwind + shadcn app, identical at every screen size, plus DESIGN.md and a shadcn globals.css - and prove it with layout, scroll, canvas, motion, hover, interaction, style and load checks at seed and held-out screen sizes, and a frame-by-frame visual review. Use when the user gives a URL and asks to clone, replicate, rebuild or migrate a site or page, or to extract its design system.
 ---
 
-# Build a true clone of a website
-
-Everything for a site lives in `sites/<name>/` (gitignored, stays local):
-- `clone/`: plain HTML/CSS/JS, the source of truth.
-- `next/`: the same site as a Next.js + Tailwind v4 + shadcn app, generated from `clone/`.
-- `design-tokens.json`: the **one canonical source** of the design system, rendered to `DESIGN.md` (Google design.md format, linted), `globals.css` (shadcn theme) and `clone/tokens.css`.
-- `REPORT.md`: every score against its target, what to fix first, what was not copied. This is the deliverable.
-- `notes.md`: your notes: stack, motion inventory, decisions, known gaps.
-
-Run every step as `npx trueclone <step> <name>` from the project folder (`npx trueclone help` lists them).
-
-## 0. Pick the mode
-
-| Mode | Use it when | Content in the clone |
-|---|---|---|
-| `template` (default) | Anyone else's site: learning, layout study, a starting template | Placeholder brand, text, images and logos; scored with `--structure` |
-| `exact` | The user owns the site or is authorised to copy it (a client migration, their own Webflow/Framer/WordPress site) | The site's own text and media |
-
-Exact mode refuses to run without `--permission "<who authorised it>"`, and the value is recorded in `meta.json` and in `REPORT.md`. Never use exact mode on a site the user doesn't own or have permission for. If permission is unclear, ask.
+# Build the same website, at every screen size
+
+The goal: the user opens the clone on localhost on any device, at any window size, and it looks and behaves exactly
+like the original. Not at three widths: at every width. Accuracy comes first, time second, scores third: a score is
+an instrument; when it and your eyes disagree, your eyes win and you say so in `notes.md` (Findings).
+
+Everything for a site lives in `sites/<name>/` (gitignored, local): `clone/` (the source of truth), `next/` (the
+Next.js app generated from it), `notes.md` (your record, a contract), `REPORT.md` (the deliverable). Run every step as
+`npx trueclone <step> <name>` from the project folder (`npx trueclone help` lists them).
+
+## The rules
+
+1. **Structure comes from the seed; behaviour is code.** The seed gives the site's markup, stylesheets, media and
+   every value that is the same at every size or a plain function of the screen size. Everything a script does
+   (layout it computes, scenes it builds, motion, hover, state, canvases) you re-implement in `clone/script.js`,
+   **porting the site's own rule** from `reference/scripts/` (`INDEX.md` ranks the scripts by what actually ran and
+   points every event listener at file:line). Read the algorithm; write your own code; never paste the site's code.
+2. **Every screen size.** Your code computes from the live viewport, the way the site's does (`innerWidth`,
+   `innerHeight`, element boxes, `resize`, the site's own breakpoints). Never put a pixel value you measured or
+   recorded at one size into the clone. Elements marked `data-tc-script-owned` (and `reference/script-owned.json`) hold
+   values the site computes that no simple function of the screen size explains: they are yours to compute.
+3. **Never edit generated files.** `clone/index.html` is seed output. What a clone needs on top goes in
+   `clone/patches/` (see Build). A fix that needs the generated markup changed is a tool defect: write it in Findings.
+4. **Look, don't just score.** `npx trueclone review <name>` shows reference and clone side by side at a size the
+   clone was never built from, at load, at every section, with the pointer on a control. You give every frame a
+   verdict in `notes.md`. A frame that differs is open, whatever the numbers say.
+5. **Done means done.** Every check passes at every scored size, the held-out sizes included; every review frame is
+   "same"; an accepted difference is only for the last points of a check already ≥ 95 and names an evidence file.
+   There is no pass limit: keep fixing until that holds or every remaining gap is proven a tool defect in Findings.
+6. **Exact mode only with permission.** `template` (default) is for anyone's site: placeholder text and media, the
+   original's structure and behaviour. `exact` copies the site's own text and media and refuses to run without
+   `--permission "<who authorised it>"`; never use it on a site the user doesn't own or have permission for. Never get
+   past bot checks, logins or paywalls. No tracking scripts; forms submit nowhere; `noindex`.
 
 ## 1. Capture
 
 ```powershell
 npx trueclone capture <url> [name] [--hide "<cookie banner / popup selectors>"] [--mode exact --permission "<owner>"]
-npx trueclone states <name>      # live scroll states + motion inventory (animations running)
-npx trueclone motion <name>      # animation runtime: ScrollTriggers, timelines, reveals, cursor tweens, loops, Lenis/Swiper, CSS
-npx trueclone spec <name>        # measured boxes and styles per viewport
+npx trueclone states <name>    # scroll states at every scored size (reference/states/)
+npx trueclone motion <name>    # the animation runtime: ScrollTriggers, timelines, tweens, loops, Lenis/Swiper, CSS
+npx trueclone spec <name>      # measured boxes and styles per size
 ```
 
-`npx trueclone <url> [name]` is a shortcut for capture + design-system draft.
-
-`reference/` then holds:
-- full-page PNGs and their `*.mask.png` structure versions, `sections.json` and `rendered.html`;
-- `tokens.json` (colours, type, radii, CSS variables), `assets/` with `manifest.json`, and `desktop.har` (every request, including the data/API calls);
-- **`states/<vp>/NN.png`**: what a visitor sees at every half-viewport scroll step, after motion settles;
-- **`states/<vp>.summary.json`** (the motion inventory): `reveals`, `animated`, `parallax`, `pinned` and `fixed` elements;
-- **`motion.<vp>.md`**: the exact animation recipe when the site uses GSAP/ScrollTrigger, Lenis, Swiper or CSS animations: trigger, start/end, scrub, pin, properties and ranges, duration, easing, stagger. Rebuild these with the same public libraries and these numbers, in your own code;
-- in exact mode, `mirror/index.html`: a script-free local snapshot with assets rewritten to local copies.
-
-Read the motion inventory before building. Each entry is a behaviour the clone must have.
-
-If the page is blank or blocked, capture through your own Chrome over CDP (`chrome --remote-debugging-port=9222 --user-data-dir=.chrome-profile`, then `--cdp`). Never try to get past bot checks, logins or paywalls.
-
-## 2. Understand it with REA
-
-trueclone bundles REA (Reverse Engineer Anything). `npx @trueclone/cli init` registers it as an MCP server; without MCP, run `npx trueclone rea <command>`. With the page open in your CDP Chrome:
-- `inspect_web_page`: DOM, scripts, resources.
-- `analyze_web_bundle` with source maps: framework, vendors (GSAP, ScrollTrigger, Lenis, Swiper, Webflow IX2, three.js), routes and API endpoints.
-- `inspect_web_event_listeners`: hover, drag, wheel and click logic.
-
-Use REA when the capture can't tell you how something works: a behaviour's exact rule, bundled shader or physics code, the API a component calls. Write `notes.md`: stack, breakpoints, and the motion inventory turned into a list of behaviours (trigger, property, range).
+`states`, `motion` and `spec` only read the reference: run them one after another in the background while you read.
+Capture shoots five sizes: the seed sizes 390×844, 768×1024, 1440×900 (the clone is built from these) and the
+held-out 1280×720 and 1920×1080 (scored, never used to build). It also reads inline styles at extra sizes inside each
+of the site's breakpoint ranges, and saves every script that ran (`reference/scripts/`). If the page is blank or
+blocked, capture through your own Chrome over CDP (`--cdp`); never get around a bot check.
+
+## 2. Understand
+
+Write `notes.md` (the seed creates it; its sections are a contract): **Stack**, **Behaviours** (one line each:
+element, trigger, property, range, timing, *and the file:line of the rule in reference/scripts/*), **Own-code map**,
+**Findings**, **Accepted differences**, **Unknowns**, **Review**.
+
+- `reference/scripts/INDEX.md`: the scripts by what ran, readable copies of minified ones, every listener's handler.
+  This is where a scene's algorithm is: a grid computed from the viewport, a spring, a pin length, a hover panel.
+- `reference/script-owned.json`: every value the site's scripts set that no function of the screen size explains,
+  with its samples at many sizes (random, content-fitted, state- or scroll-driven); `reference/inline-styles.json`
+  `scriptQueries`: the widths the scripts themselves switch at (`matchMedia`).
+- `reference/motion.<size>.md`: ScrollTriggers, tweens, easings, pins, as the runtime reports them.
+- `reference/states/<size>.summary.json`: reveals, parallax, pinned and fixed elements; `npx trueclone tiles <name>`
+  cuts the full-page shots into readable screens.
+- For a part no script reading explains (a bundled physics rule, a shader, WASM), REA is bundled:
+  `npx trueclone rea --help`. Rarely needed.
 
 ## 3. Design system
 
 ```powershell
-npx trueclone design <name>              # drafts design-tokens.json if missing, renders DESIGN.md, globals.css, clone/tokens.css + lints
-npx trueclone design <name> --redraft    # fresh draft in design-tokens.draft.json (never overwrites your edits)
+npx trueclone design <name>   # design-tokens.json -> DESIGN.md (must lint with 0 errors), globals.css, clone/tokens.css
 ```
 
-Review the draft: role names, the `notes` prose (overview, do's and don'ts), anything marked `origin: generated`. Re-run after every edit. `DESIGN.md` must lint with **0 errors**.
-
-## 4. Build (`clone/`)
+Review the draft (role names, notes, anything `origin: generated`) and re-run after every edit.
 
-**Start every clone from the mirror** (both modes):
+## 4. Build
 
 ```powershell
-npx trueclone reveals <name>   # records scroll reveals frame by frame + class changes caused by scrolling (any library)
-npx trueclone widgets <name>   # clicks every tab and menu and records each state (they often aren't in the page until clicked)
-npx trueclone seed <name>      # clone/ from the script-free mirror; replays what reveals and widgets recorded
+npx trueclone reveals <name>   # one-shot scroll reveals and scroll class changes, recorded at the seed sizes
+npx trueclone widgets <name>   # every tab and menu state (template mode replays them)
+npx trueclone seed <name>      # clone/ from the script-free mirror
 ```
 
-- **Exact mode:** the site's own markup, text, stylesheets and media at local paths.
-- **Template mode:** the same markup and stylesheets, but every text becomes lorem words of the same laid-out width (lines break where the reference's break), every image, video, large SVG and iframe a same-size placeholder, CSS backgrounds a transparent one, every link `#`, brand metadata and tracking hints dropped. No text or media of the site ends up in `clone/`; fonts stay for local study (swap licensed fonts before reusing the result).
-- **Recorded behaviour comes with it:** one-shot scroll reveals replay their measured curve (delay, duration, easing, spring overshoot) with the Web Animations API, and scroll class changes (a header that gets its backdrop past 12px) toggle the same classes at the same point. Both live in `clone/trueclone-reveals.js`; don't rewrite them by hand.
-- **Recorded widgets come with it too** (template mode): every tab set and expandable menu, with each state the original showed after a click, placeholdered like the page. `clone/trueclone-widgets.js` swaps the region on click (menus in a header or nav also on hover). Popovers rendered in a portal (comboboxes, tooltips) are listed as not replayed: build those in `script.js`. In interaction scenarios, `selector@n` picks the n-th match in `at`, `click` and `expectChange`; mind hidden duplicates (a mobile menu button is often the first match).
-
-Then write `clone/script.js`: every remaining interaction in your own code, using the parameters you read from the reference (timings, physics constants, offsets, breakpoints). Never copy the site's scripts. JS-set initial states, such as a `<details>` closed on phones, are part of the layout, so check every viewport. Data the page fetches live (a star count, a feed) stays as captured; no requests to third parties.
-
-A seed is where layout ends up at 99%+ with zero hand-written CSS; your work is behaviour. Build by hand (below) only what the mirror can't carry.
-
-**Building parts by hand:**
-
-- `styles.css` starts with `@import url("tokens.css");` and uses its variables. Never hard-code a token value.
-- Use the site's breakpoints and root font-size behaviour (in `design-tokens.json`, under `layout`).
-- Match `sections.json` heights. In template mode write your own placeholder words, then run `npx trueclone textshape <name> --write` (desktop, then `--viewport tablet` and `mobile`) so lines break where the reference's break. Use `--list "<ref row>" "<clone row>"` for repeated lists (calendar rows, cards), and give every data row its own placeholder text.
-
-**Both modes:**
-
-- **Copy the reference's CSS mechanism, not its look.** Before writing CSS for an element, run `npx trueclone rules <name> "<selector>"` and port the matching rules (with their `@media`). Look-alikes drift in flex/grid: a "capsize" `::before/::after` text trim is not `text-box-trim`, `height: 14.5rem` is not `flex: 1`, and `width: 100%; max-width: 40rem` with default flex shrink is not `flex: 0 10 auto` or `width: min-content`.
-- **Positional selectors:** `:nth-of-type` counts siblings of the same tag only. A logo `<a>` before the column `<div>`s shifts every column by one, so use `:nth-child` or a class.
-- **Stacked media:** keep every layer (colour, grayscale or depth-map images, overlays). Never flatten them into one image.
-- **Canvas/WebGL:** a site can draw its hero or a game on a `<canvas>`. Rebuild the drawing in your own code with the reference's parameters (exact mode) or a placeholder scene. Never drop it silently.
-- **Motion:** implement every inventory entry: reveals, parallax speeds, pinned sections, fixed elements.
-- **Interactions:** sliders, tabs, hover states, cursor followers, menus, counters, demos. Scope query selectors to their own component: a hidden duplicate (a mobile-only list) must never feed a desktop counter.
-- **Sliders in flex/grid:** give the slider and every flex/grid ancestor `min-width: 0`, or Swiper and similar grow to fit their slides and run away. `states --clone` warns when the page height drifts more than 20%.
-- `<meta name="robots" content="noindex">`, forms submit nowhere, no tracking scripts.
+What the seed gives you, and what it leaves to you:
+- the original's markup, stylesheets and media (template mode: lorem text of the same laid-out width, same-size
+  placeholders), open shadow roots as declarative shadow DOM, missing media fetched;
+- **inline values a script set, as functions of the screen size** (`calc()` in `--tc-vw`/`vh`, or `max()`/`min()` for
+  cover/contain, per range of the site's and its scripts' breakpoints) when one fits every captured size; a property
+  that fits at no size or only at some is removed everywhere and marked `data-tc-script-owned`;
+- **pins** as a sticky element in a spacer whose tail is the pin length (`--tc-pin`, a function of the viewport when
+  the site's is);
+- one-shot reveals and scroll class changes replayed by `trueclone-reveals.js` at the visitor's size; **scroll-linked
+  curves (parallax, scrubbed fades) are not replayed**: their samples are evidence in `reference/reveals.<size>.json`,
+  and you write the rule;
+- the boot contract: `<html class="tc-boot">` until your scripts have run; `--hide-until-boot "<selectors>"` keeps
+  regions your script builds invisible meanwhile; `tcBoot.hold()` / `tcBoot.release()` for an intro that waits.
+
+Then `clone/script.js`, scene by scene from `notes.md` Behaviours: find the rule in `reference/scripts/`, port it,
+compute everything from the viewport. When your script drives an element the seed's player also drives, hand it
+over: remove its `data-tc-reveal` / `data-tc-class` mark at the top of `script.js`. After each build round,
+`npx trueclone owned <name>` lists the sections your script rebuilds (hide those until boot if the original hides them).
+
+`clone/patches/` (applied on every seed, or alone in a second with `npx trueclone seed <name> --patches`):
+`head-*.html` before `</head>`, `*.css` linked after the site's stylesheets, `body-*.html` before `script.js`
+(vendored libraries, a hand-over prelude), `*.js` deferred before `script.js`. Vendor libraries at the site's versions.
+
+Copy the reference's CSS mechanism, not its look: `npx trueclone rules <name> "<selector>"` (add `--clone` for yours).
+Canvases are scored: rebuild the drawing from the site's scene code with its parameters (exact mode) or as your own
+scene with the same composition (template mode); never drop one.
 
 ## 5. Verify
 
 ```powershell
-npx trueclone score <name> --quick   # layout, desktop states, interactions: the loop while building (about a minute)
-npx trueclone score <name>           # everything, in parallel groups, then REPORT.md
-```
-
-The steps, if you need one alone:
-
-```powershell
-npx trueclone diff <name> [--structure]            # layout: full page, frozen (structure = text and media masked)
-npx trueclone states <name> --clone [--structure]  # scroll states: the reference's scroll positions replayed on the clone
-npx trueclone curves <name> --draft                # motion-map.draft.json from the inventory: fill in clone selectors, save as motion-map.json
-npx trueclone curves <name> [--viewport tablet]    # motion: property curves (scroll- and time-driven), reference vs clone
-npx trueclone interact <name> --draft              # interactions.draft.json: fill in TODOs, save as interactions.json
-npx trueclone interact <name>                      # interactions: click/hover/drag/key scenarios + expectChange (geometry, text, state attributes, canvas pixels)
-npx trueclone detail <name> --viewport all         # styles at matching points: font, size, weight, line height, colour, boxes
-npx trueclone hovers <name>                        # hover effects present on the reference but missing on the clone
+npx trueclone score <name>                                    # every check at every scored size, then REPORT.md
+npx trueclone score <name> --only layout,states --viewport wide # after a fix: the checks it can move, where
+npx trueclone explain <name> <y | "section label"> --viewport wide  # one place: what every check saw + a crop
+npx trueclone review <name> --size wide                       # side by side by eye; then laptop, tablet, mobile
 ```
 
-Reference measurements are cached until the next capture, so only the clone is re-measured. Sites without scroll/time motion or without interactions simply skip those steps.
-
-Fix in this order: page height drift, the worst layout section, the worst state step, the lowest motion curve, any interaction marked FAIL, then detail and hovers. `REPORT.md` lists them under "Fix first". For a drift, compare the element's ancestor boxes on both sides until one differs, then `rules` that ancestor: the cause is usually one declaration. Fix the cause; never tune numbers to the score.
-
-**Done when:** layout ≥ 98% at every viewport, states within 5 points of layout, motion ≥ 95%, detail ≥ 95%, hovers ≥ 90%, and every interaction passes. Otherwise stop after 8 passes and report what's left and why.
-
-How detail measures, so you can trust it:
-- motion on (many originals ignore `prefers-reduced-motion`, and a clone that honours it lays out differently);
-- both sides measured the same way: a hit test at the same point and scroll position, so sticky and pinned content is compared in place and an identical page scores 100%;
-- through `pointer-events: none` overlays, and never on content the browser doesn't paint (closed `<details>`);
-- colours written by scroll-scrubbed JS show up as in-between values: that is a motion difference, so check the motion inventory.
+The checks: layout (full page, structure), scroll states (every half screen, scrolled with the wheel), canvases (what
+each scene draws), motion curves, detail (styles at matching points), hovers (every control and every element with a
+hover listener: the region after the hover must match), interactions (`interactions.json`: the change must happen on
+both sides and end in the same state), load (0.25-4 s after navigation, cold cache, same network). Unstable probes
+(random motion, timing) are measured twice on the reference and excluded; do not chase a number inside the noise.
+Unchanged checks are not re-measured (`--fresh` forces it). `drift` opens every full score: if the live site changed
+since the capture, the live-measured checks are marked stale; re-capture before trusting them.
 
-How layout and states measure:
-- the structure mask hides text everywhere, gradient text (`background-clip: text`) and `::before/::after` photo backgrounds included;
-- content that a component mounts only while in view (marked `data-tc-viewmount` by capture) can't appear in a full-page still on either side: layout paints its box the same on both and reports the count; the scroll-state check, with a real viewport, scores it;
-- endless animations (marquees, rotating borders) are frozen on their first frame on both sides before every state screenshot: their phase depends on load time, not on the clone.
+Fix in this order: anything the review shows, the held-out sizes, page height drift, the worst layout section, the
+worst state step, canvases, interactions, load, then detail and hovers. Fix the cause; never tune a number to a score.
 
-The live site can change after capture (a redeploy changes its CSS bundle name). When live-site tools (detail, rules) and screenshot scores (layout, states) disagree about a section, re-capture (`capture`, then `states <name>`); that also resets the cached reference measurements.
+**Review verdicts** in `notes.md` under `## Review`, one per frame of `compare/review/<size>/index.md`:
+`- 03-section-2 wide: same` or `- 07-section-4-hover wide: differs: the panel opens on the wrong card`.
+**Accepted differences**: `- <check> <size> <where>: <why>; evidence: compare/explain/wide-5200.png`, only for a check
+already ≥ 95.
 
 ## 6. Next.js (after the HTML clone passes)
 
 ```powershell
-npx trueclone next <name> --verify   # generates sites/<name>/next, installs, builds, serves, and runs every score on it
+npx trueclone next <name> --verify   # generates next/, builds, serves and scores it into REPORT.next.md
 ```
 
-The HTML clone stays the source of truth: change `clone/`, then regenerate. The app has one component per section, the motion script as a client component (GSAP, Lenis, Swiper and three from npm at the clone's versions), `app/globals.css` = shadcn theme + tokens + the clone's stylesheet + preflight parity, and `components.json` so `npx shadcn add <component>` works. It is done when its scores match the HTML clone's within a point.
+The HTML clone stays the source of truth: change `clone/`, then regenerate. One component per section, the clone's
+scripts preloaded and run at hydration, the site's stylesheets after the shadcn theme in the site's cascade-layer order,
+`components.json` for `npx shadcn add`. Done when its report matches the HTML clone's within a point everywhere.
 
 ## 7. Report
 
-`npx trueclone score <name>` writes `REPORT.md` (or run `npx trueclone report <name>`): mode and permission, every score against its target, "Fix first", the motion found on the reference, and what was not copied (server behaviour, tracking, and each data/API call the reference makes). Hand it over with the clone.
+`REPORT.md` (and `REPORT.next.md`) is the deliverable: mode and permission, every check at every size, the review,
+open frames, accepted differences with evidence, Findings, what to fix first, and what was not copied (server
+behaviour, tracking, each data/API call). Hand it over with the clone.
 
 ## Honest limits
 
-- Server-side behaviour is never visible from outside: databases, accounts, payments, search. The clone reproduces the client; data calls are listed in the report.
-- A live site is never pixel-identical twice: rotating content, A/B tests and font hinting vary.
-- Template clones of other people's sites stay local. Exact clones need recorded permission and also stay local unless the owner deploys them.
+- Server-side behaviour is never visible from outside: databases, accounts, payments, search. The clone reproduces
+  the client; data calls are listed in the report.
+- A live site is never pixel-identical twice: rotating content, A/B tests and font hinting vary; that is what the
+  unstable-probe and noise handling is for, not a licence to stop.