multiclone 0.1.0 → 0.2.0

package/skills/multiclone/SKILL.md

@@ -7,29 +7,50 @@ description: Clone a website from a link into a clean React + Vite + TypeScript
 
 The goal is a rebuild that a visitor can't tell apart from the original at any scroll position, on desktop and on mobile, including the intro, the scroll motion and the hover states. It must be clean, typed React that a senior engineer would be happy to own, not a pile of the original's minified code.
 
-The method has five stages. Do not skip the measuring: the difference between a lookalike and a clone is the compare loop at the end.
+## Fast path (use this)
+
+1. **Ask the scope first**, in one short question: just the landing page, specific pages (which ones), or the whole site. Don't start before the user answers.
+2. **Start:** `multiclone start <url> --scope landing|pages|site [--pages /pricing,/about]`. It returns in seconds with a **progress link** (for example `http://127.0.0.1:4300/`). Give that link to the user straight away: it shows live progress and then the clone itself.
+3. **Wait for the draft:** `multiclone status --wait draft`. In about 2–3 minutes the session has a quick capture (desktop and mobile in parallel), a React project with the captured fonts, tokens and media, a **first draft** (one component and CSS module per section with the real text, links, images and video), the clone running on localhost and an offline copy of the original. Status lists all the links.
+4. **Polish, don't rewrite.** The draft is in `<workspace>/clone/src/sections/<page>/`. Compare each section with its crop in `captures/<page>/sections/<id>/`, fix layout, make it responsive and clean, add the motion and hovers. Keep the dev server running; it hot-reloads.
+5. **Deep data arrives in the background.** Other pages (scope pages/site) and the deep pass (motion map, hovers, clicks, coverage, source maps, in `captures/<page>-full`) finish while you work. Check with `multiclone status`. Use the deep capture for motion and hovers when it's done.
+6. **Compare and fix** (stage 5 below), then hand over. `multiclone stop` ends the servers; the files stay.
+
+Run `start` again to resume after a crash or restart: finished captures are reused and drafted pages are never overwritten.
+
+Every command prints a short summary; details live in files. Read big things with `inspect` instead of opening whole files.
+
+## The stages in detail
+
+The fast path runs stages 1 and 3 and a first pass of 4 for you. Use the tools below directly for anything it doesn't cover, or when you need more control.
 
 1. **Capture** the original (one call also analyses it into section bundles).
 2. **Understand** the page from `REPORT.md` and the section bundles.
 3. **Scaffold** the project from the capture: fonts, tokens, media and the mock API come along.
-4. **Rebuild** it section by section, tagging elements with the `data-mc-*` markers.
+4. **Rebuild** (or polish the draft) section by section, tagging elements with the `data-mc-*` markers.
 5. **Compare and fix** until it is close, then hand over the localhost link.
 
-## Tools
+Do not skip the measuring: the difference between a lookalike and a clone is the compare loop at the end.
 
-The multiclone MCP server provides these tools (it runs with `npx -y multiclone mcp`). Without MCP, run the same tools from the terminal: `npx multiclone <command>`, and `npx multiclone <command> --help` lists the flags. Every tool returns a short text summary; big data stays on disk and is read with `inspect`.
+## Tools
 
-| Tool           | What it does                                                                                                                                                                                                                                                                                                                                                                          |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `capture`      | Real Chrome loads the page per viewport, dismisses consent banners, scrolls like a visitor and records the network, every script and its source maps, the computed-style DOM snapshot, fonts, storage, the intro filmstrip, the scroll motion map, runtime animation libraries, WebGL shaders, event listeners, hover/focus/click states and CSS breakpoints. Then it runs `analyze`. |
-| `analyze`      | Rebuilds the derived files from a capture in an isolated worker: section bundles, design tokens, prettified code split into app and vendor, animation calls found in the code, and `REPORT.md`.                                                                                                                                                                                       |
-| `inspect`      | Pages through anything in a capture by facet: `summary`, `section`, `dom`, `styles`, `network`, `motion`, `animations`, `runtime`, `interactions`, `code`, `fonts`, `tokens`. Use `selector`, `viewport`, `query`, `offset` and `limit` to keep pages small.                                                                                                                          |
-| `serve_mirror` | Serves a capture offline on localhost. `live` mode runs the original scripts with the captured storage seeded, so the animations work. `snapshot` mode serves the frozen DOM. Captured API calls become a mock API under `/__mc/api`.                                                                                                                                                 |
-| `scaffold`     | Creates the strict React 19 + Vite + TS starter. With `capture` it installs the captured fonts, `tokens.css`, the media files and a dev proxy to the mock API.                                                                                                                                                                                                                        |
-| `assets`       | Copies captured media into `public/media/<host>/…` and writes `src/content/asset-map.json` (scaffold with `capture` already does this).                                                                                                                                                                                                                                               |
-| `shoot`        | Screenshots at exact scroll offsets with real mouse-wheel scrolling, so Lenis and GSAP move. A `probe` JS expression runs after each scroll: element rects, CSS variables, computed styles.                                                                                                                                                                                           |
-| `compare`      | Compares the clone with the original per viewport: frames, sections aligned by `data-mc-section`, structure, scroll motion by `data-mc-track`, hovers by `data-mc-hover`, and the intro with `intro`. Writes an HTML report and returns the worst sections and frames.                                                                                                                |
-| `doctor`       | Checks Node, Chrome and headless WebGL.                                                                                                                                                                                                                                                                                                                                               |
+Run them from the terminal: `multiclone <command>`, and `multiclone <command> --help` lists the flags (use `npx multiclone` if it isn't installed globally). The same tools are available over MCP (`multiclone mcp`) for agents that prefer it.
+
+| Tool           | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `start`        | The fast path above: background session with quick capture, project, first draft, live clone, offline original, other pages and the deep pass. Returns the progress link.                                                                                                                                                                                                                                                                          |
+| `status`       | Where the session is, with all links. `--wait draft`, `--wait pages` or `--wait deep` blocks until that point.                                                                                                                                                                                                                                                                                                                                     |
+| `stop`         | Stops the session's servers. Files stay.                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `draft`        | Turns a capture into section components inside a scaffolded project (`start` runs it for you).                                                                                                                                                                                                                                                                                                                                                     |
+| `capture`      | Real Chrome loads the page per viewport, dismisses consent banners, scrolls like a visitor and records the network, every script and its source maps, the computed-style DOM snapshot, fonts, storage, the intro filmstrip, the scroll motion map, runtime animation libraries, WebGL shaders, event listeners, hover/focus/click states and CSS breakpoints. `--depth quick` keeps only what a draft needs (1–2 minutes). Then it runs `analyze`. |
+| `analyze`      | Rebuilds the derived files from a capture in an isolated worker: section bundles, design tokens, prettified code split into app and vendor, animation calls found in the code, and `REPORT.md`.                                                                                                                                                                                                                                                    |
+| `inspect`      | Pages through anything in a capture by facet: `summary`, `section`, `dom`, `styles`, `network`, `motion`, `animations`, `runtime`, `interactions`, `code`, `fonts`, `tokens`. Use `selector`, `viewport`, `query`, `offset` and `limit` to keep pages small.                                                                                                                                                                                       |
+| `serve_mirror` | Serves a capture offline on localhost. `live` mode runs the original scripts with the captured storage seeded, so the animations work. `snapshot` mode serves the frozen DOM. Captured API calls become a mock API under `/__mc/api`.                                                                                                                                                                                                              |
+| `scaffold`     | Creates the strict React 19 + Vite + TS starter. With `capture` it installs the captured fonts, `tokens.css`, the media files and a dev proxy to the mock API.                                                                                                                                                                                                                                                                                     |
+| `assets`       | Copies captured media into `public/media/<host>/…` and writes `src/content/asset-map.json` (scaffold with `capture` already does this).                                                                                                                                                                                                                                                                                                            |
+| `shoot`        | Screenshots at exact scroll offsets, scrolling like a visitor so Lenis and GSAP move. A `probe` JS expression runs after each scroll: element rects, CSS variables, computed styles. A slow page or a failed shot becomes a warning, not a failure.                                                                                                                                                                                                |
+| `compare`      | Compares the clone with the original per viewport: frames, sections aligned by `data-mc-section`, structure, scroll motion by `data-mc-track`, hovers by `data-mc-hover`, and the intro with `intro`. Writes an HTML report and returns the worst sections and frames.                                                                                                                                                                             |
+| `doctor`       | Checks Node, Chrome and headless WebGL.                                                                                                                                                                                                                                                                                                                                                                                                            |
 
 The capture folder layout is documented in [references/capture-format.md](references/capture-format.md).
 
@@ -67,7 +88,7 @@ Before coding, write a short plan: the sections and their components, the techni
 Work top to bottom, one section bundle at a time. For pages with many sections, hand independent sections to a sub-agent using the `section-builder` brief ([agents/section-builder.md](../../agents/section-builder.md)), one section each, after the shell is in place.
 
 1. **Shell first:** fonts, tokens, header, footer, smooth scroll and any global background.
-2. **Then each section:** read its `section.md`, rebuild it as one component under `src/components/sections/`, and look at it next to its crop before moving on.
+2. **Then each section:** read its `section.md`. If a draft exists (`src/sections/<page>/<Name>/`), polish it in place: turn repeated markup into data plus a map, rename classes to meaningful names, replace fixed widths with responsive layout, and delete wrappers that only existed for the original's framework. Otherwise rebuild it as one component under `src/sections/<page>/`. Look at it next to its crop before moving on.
 3. **Tag for compare** with the helpers in `@/lib/mc`:
    - `<section {...mcSection('03-pricing')}>` with the section id;
    - `{...mcTrack(id)}` on every element listed in the section's `motion.json`;
@@ -84,7 +105,7 @@ Run `npm run check` whenever a section is done.
 
 The full playbook is in [references/fidelity.md](references/fidelity.md).
 
-1. Serve the capture with `serve_mirror` (`live`) as the stable original, and run the clone's dev server.
+1. Serve the capture with `serve_mirror` (`live`) as the stable original (a `start` session already serves it), and run the clone. For long compare runs prefer `npm run build && npm run preview` over the dev server: it loads much faster and is what ships.
 2. Run `compare` with `original` set to the **capture folder** and `clone` to the dev URL. The capture gives compare its sections, tracks and hovers; it shoots the mirror for pixels. Add `intro: true` when the page has an intro animation.
 3. Fix in this order: missing sections, page height, the worst section, untagged tracks and hovers, then the worst frames. Open the images yourself: the score guides, it doesn't judge.
 4. Measure with `shoot` and a `probe` on both sides instead of guessing.

package/templates/react-vite/src/app/App.tsx

@@ -1,10 +1,15 @@
 import { SmoothScroll } from '@/providers/SmoothScroll';
 import { Page } from '@/app/Page';
+import { routes } from '@/app/routes';
+
+// Links are plain anchors (full page loads), so the route is read once per load.
+const path = window.location.pathname.replace(/\/+$/, '') || '/';
+const Current = routes[path] ?? Page;
 
 export function App() {
   return (
     <SmoothScroll>
-      <Page />
+      <Current />
     </SmoothScroll>
   );
 }

package/templates/react-vite/src/app/Page.tsx

@@ -1,4 +1,11 @@
-/** Rebuilt sections go here, top to bottom, following the outline in the capture's REPORT.md. */
+/**
+ * Fallback page. `multiclone draft` writes real pages to src/pages and sections to src/sections,
+ * then lists them in src/app/routes.ts.
+ */
 export function Page() {
-  return <main id="main" />;
+  return (
+    <main id="main" style={{ padding: '4rem', fontFamily: 'system-ui, sans-serif' }}>
+      <p>multiclone is capturing the page. The first draft appears here in a minute or two.</p>
+    </main>
+  );
 }

package/templates/react-vite/src/app/routes.ts

@@ -0,0 +1,7 @@
+import type { ComponentType } from 'react';
+import { Page } from '@/app/Page';
+
+/** Path → page component. `multiclone draft` regenerates this file for every drafted page. */
+export const routes: Partial<Record<string, ComponentType>> = {
+  '/': Page,
+};

package/templates/react-vite/src/styles/draft.css

@@ -0,0 +1 @@
+/* Filled by `multiclone draft`: element reset and page-level styles of the original. */

package/templates/react-vite/src/styles/index.css

@@ -1,3 +1,4 @@
 @import './fonts.css';
 @import './tokens.css';
 @import './base.css';
+@import './draft.css';