clone-site

Rebuilds a target URL in real code by reading the running page: computed styles, CSSOM rules and keyframes, document.fonts, getBoundingClientRect, getAnimations(), the network log. The one rule that makes this work: every number you write into the clone was measured off the live page. Screenshots are for human judgement and for giving each section agent a visual target — never for deriving a color, a gap, or a font size. Assets are mirrored byte-for-byte; text is copied verbatim.

Below, cdp: = mcp__plugin_chrome-devtools-mcp_chrome-devtools__. Every evaluate_script, take_screenshot, and take_snapshot passes filePath; not optional, it is what keeps a 400 KB style dump out of your context.

Step 0 — precheck, flags, resume

Probe the server with mcp__plugin_chrome-devtools-mcp_chrome-devtools__list_pages (no params). It is the cheapest call that proves both "browser alive" and "full tool surface".

If any browser call fails, or the page fights you: read references/troubleshooting.md — precheck, failure→remedy table, lifecycle traps, and the Playwright fallback.

Resolve the target: a bare domain gets https://; a URL the user pasted mid-sentence still counts as the argument. Only ask a question if no URL is recoverable at all — everything else is inferred and reported, never negotiated. Then parse the argument string into run.json.flags. This is the complete flag set; do not invent more.

--profile sets defaults an explicit flag then overrides (--cheap --max-parallel 8 → 8). Dark-mode extraction is not a flag: it runs whenever color.darkMode shows signal.

This table is a copy for immediate branching; references/scaling.md owns it and carries the rows not listed here (sectionAttemptsMax, pages/depth, and why the 7-width fluid sweep is not a profile dial). Any change lands there first.

Resume: run.json lives in the clone project root, which in scaffold mode is --out, not your cwd — so look it up in this order and stop at the first hit: ./.clone/run.json, <--out>/.clone/run.json, ./<domain>-clone/.clone/run.json. On a hit, cd to that root and take every path from its stack; on more than one, use the newest updatedAt and say which you picked. Skipping this lookup silently starts a fresh run and re-measures the whole original — the one cost resume exists to avoid. Then: if phase != "done", skip every done phase and never re-measure the original — measurement is the expensive half. Reset running sections to pending. Write run.json atomically (.tmp → mv) on every state transition, not just wave boundaries.

Before you fan out, and any time the page is large: read references/scaling.md — profiles, filePath discipline, run.json checkpointing, and --resume.

Step 0b — is the target a site or an app?

Everything below measures one page at rest. If the target is an application — behind a login, inside an iframe (Shopify App Bridge, embedded dashboards), or valuable for its multi-step flows rather than its landing page — that shape is wrong and this pipeline quietly produces a shallow answer. Read references/flows.md instead, and return here for the visual layer only if the visual layer is genuinely the deliverable.

It covers operator-driven auth (a persistent profile, never credentials in a script), finding the real document inside an iframe, discovering candidate flows, capturing a state rather than a screenshot, and provoking the empty / validation / loading / error / resume states a happy-path walkthrough misses. For an app the default deliverable is a flow map, not a stylesheet — §F0 says why, including when the target runs on a design system you should import rather than clone.

Step 1 — navigate, and decide where the code goes

1. Motion instrumentation must exist before the page's own scripts do, so the HOOKS IIFE rides in on this navigation: Step 2a — capture motion. Read references/motion.md §M0 now: the initScript hooks must be installed before the page's own scripts run, so read this before you navigate.
2. cdp:new_page {url, isolatedContext:"clone"} for a clean first-visit state, then cdp:navigate_page {url, type:"url", initScript: HOOKS}. initScript applies to the next navigation only — re-pass it after every reload. Navigation failures do not throw: read the response text for Unable to navigate.
3. cdp:wait_for {text:["<a real string from the footer>"]}, then poll cdp:evaluate_script for document.readyState === 'complete' and document.fonts.status === 'loaded' before measuring anything typographic.
4. Consent banner: cdp:take_snapshot {filePath}, cdp:click {uid} the accept control, re-snapshot. An overlay left up sets body{overflow:hidden} and destroys every scrollHeight you are about to read.
5. Step 1b — decide the output stack. Read references/stacks.md now: detect an existing repo's conventions or scaffold, then record the path map into run.json.stack. Adopt mode wins when a repo is detected; otherwise scaffold Next 15 App Router + Tailwind v4; --static overrides both.

Exit gate: run.json has target.finalUrl, stack.mode and the full path map, phase:"prewarm".

Step 2 — measure the original

This order is the pipeline, not a suggestion. The prewarm scroll, the fluid sweep, and emulate each destroy state an earlier pass reads: the prewarm fires every IntersectionObserver reveal and finishes every entrance animation, seven resizes re-run every media query, and emulate can trigger a reload that wipes window.__cloneHooks (installed only via initScript, on one navigation). So the at-load motion passes go first, cold, before anything scrolls.

Skipping the prewarm costs a whole repair iteration and produces sections frozen at opacity:0. Draining the hooks after it produces motion data that describes the end state of every animation and the trigger of none. After any reload — including one emulate caused — re-navigate_page {initScript: HOOKS}, re-install all four payloads, re-prewarm, and record in motion.json.warnings anything the reload took before you drained it.

Step 2a — capture motion. Read references/motion.md now (you already read M0 before navigating): M1's pass table and the ordering rules that this table implements.

Step 2a-ii — recover the motion system from source. Read references/motion-source.md whenever libs() names GSAP/ScrollTrigger/Lenis/SplitType/Barba/Locomotive and no builder manifest was found. Runtime introspection cannot see a once:true trigger that already fired, a timeline for a section still below the fold, or a threshold that lives in an if (x > N) branch — their bundle can. This is also where the declarative motion vocabulary (extract-motion-attrs.js) is harvested so section agents can declare motion instead of inventing it.

Step 2b — measure the foundation. Read references/extraction.md now: it gives you the exact pass order, the evaluate_script invocations, and the merge that writes .clone/foundation.json.

Step 2c — prewarm properly. references/sectioning.md §1 owns it — the install sentence, the imagesDecoded check, and the quiescence poll. Read §1 now and the rest of that file at step 4a: prewarm now, segment later.

Step 2d — sweep the breakpoints. Read references/responsive.md now: the viewport plan, the probe set, and the clamp() solver that turns samples into authored CSS.

Exit gate: the three merged JSONs this step produces — foundation.json, motion.json, responsive.json — validate against their schema field (sections.json is written and gated at step 4a); fonts.faces[] is non-empty when the page uses webfonts; patterns.breakpoints[] is populated; cssom.blocked[] is either empty or backfilled from the network; and fingerprint[] exists (it is the numeric target verification diffs against).

Step 3 — build the foundation

Mirror the bytes, then emit the tokens. Nothing downstream may reference a remote URL.

1. Step 3b — mirror the assets. Read references/assets.md now: the census, the byte-exact download path, and the PROVENANCE.md format.
2. Step 3 — build the foundation. Read references/foundation.md now: it maps every foundation.json field to the tokens, @font-face, and layout shell you must emit.
3. Emit yourself, or dispatch the single clone-foundation agent with absolute paths to .clone/foundation.json and run.json.stack. Either way the orchestrator owns the tokens file, the layout shell, the page file, components/shared/**, and public/** forever after.
4. Write components/sections/_EXAMPLE.tsx (or sections/_EXAMPLE.html). Every section agent reads it as the house style; a bad example multiplies by N.

Exit gate: run.json.foundation.tokenCount > 0; every family in foundation.fontFamilies has ≥1 local woff2 and an @font-face whose src is a local path; zero requests to fonts.googleapis.com / fonts.gstatic.com / use.typekit.net; every mirrored file has a PROVENANCE.md row with URL, content-type, bytes, sha256.

Step 4 — cut the page up and fan out

Step 4a — cut the page into sections. Read references/sectioning.md now: segmentation, per-section captures, dedup, and the wave plan.

Step 4b — brief the team. Read references/agent-brief.md now: the spec.json contract and the exact PROMPT.md each clone-section agent receives.

Segment at the primary width, score, retune KEEP if sections.length lands outside sane bounds, dedup by contentHash/structureHash, then write per section, under .clone/sections/<NN>-<slug>/: spec.json, content.md, PROMPT.md, and each gated width's capture in both formats back to back — orig-w1440.webp + orig-w1440.png, orig-w390.webp + orig-w390.png. The webp is the agent's visual target; the png is the only format visual-diff.mjs decodes, and shooting it later means re-navigating to the original at verify time.

Waves:

wave 0      orchestrator only — assets, tokens, shell, page file, _EXAMPLE
wave 1      shared chrome: SiteHeader, SiteFooter, hash-deduped shared components  (2-4 agents)
wave 2..n   body sections in document order, --max-parallel per wave (default 6)
wave n+1    orchestrator — drain requests.json, wire the page file, build
wave n+2    verify → repair waves (≤ K)

references/sectioning.md §10 owns the wave plan and the ownership map; the block above is the summary you dispatch from. Edit §10 first, then mirror it here.

Dispatch rules, all load-bearing:

• One Task call per section, all of them in a SINGLE assistant message. Sequential messages serialize the team and buy nothing.
• subagent_type: clone-section. Escalate that invocation to model: opus when the spec has carousel != null, counts.forms > 0, or motion.scrollLinked.length > 0.
• Each agent gets absolute paths only: /abs/.clone/sections/<id>/PROMPT.md, spec.json, content.md, both .webp captures, the tokens file, and _EXAMPLE. Never a URL.
• One writer per file. Each agent writes exactly one component file (two in --static: sections/<id>.html + sections/<id>.css) plus its own report.md and requests.json. A shared-chrome section's one file lives in sharedDir — one writer per path, never one directory per role. No agent gets an MCP tool, and clone-section agents get no Bash — the browser is a single serial resource and only you touch it.
• Above-the-fold sections (box.y < 2·VH) go in wave 2 regardless of order, so systemic errors surface early. Never put two sections with the same contentHash in one wave.
• Verify each wave while the next runs. A wrong container width caught at wave 2 is one edit to the tokens file instead of 20 agent repairs.
• At >24 sections warn once ("consider --sections for the top 12 first") and proceed. Do not gate.
• --max-parallel 1, or no Task availability: run the identical contracts in-thread, one section per turn. Same files, ~3× wall clock, run.json shape unchanged.

Multi-page (--pages > 1): routes were already discovered in phase discover, right after step 1's navigation and before the prewarm (it needs only a loaded DOM plus curl), and written to .clone/pages.json; --pages 0 stops there — before any measurement — with the report. Measure each extra route into .clone/pages/<pageId>/ (pageId = home for the entry route, otherwise the slugified path), then dedup across pages by contentHash before any wave is scheduled — promote a shared section to components/shared/** once and let each page file render it. Decisions land in .clone/components.json. Skipping this turns 5 pages into 5× the cost instead of ~2.2×.

Step 5 — verify, repair, report

Step 5 — verify and close the gap. Read references/assembly.md now: the review order, every gate with its number, and the bounded repair loop.

Order is fixed and cheap-first: static sweep (grep) → drain requests.json → wire the page → build → capture the clone → diff → read only the failing sections' reports. Headline gates; the full table, every per-property tolerance, and the geometry probe matrix live in references/assembly.md.

Repair loop, bounded: iterate only failing sections, K iterations max per the profile (1/3/4), sectionAttemptsMax per section. Fix systemic causes in the foundation yourself before dispatching any repair agent — a wrong base unit fails every section at once. Exit early on plateau (mean diff improves < 0.005 between iterations). Whatever is still failing goes into .clone/UNRESOLVED.md with its numbers; never claim a gate you did not measure. Then write .clone/VERIFY.md (worst-first) and .clone/CLONE-REPORT.md (gates, deviations, known limits), and set phase:"done".

The mirror reproduces third-party text, marks, and imagery byte-for-byte; swapping or keeping them before you publish is your call — every mirrored file is listed in .clone/PROVENANCE.md.

Hard rules

• Every cdp:evaluate_script / take_screenshot / take_snapshot passes filePath. The only exception is a small scalar you must branch on immediately.
• Never Read a dumped file whole. Grep/jq the field.
• Only the orchestrator touches Chrome. Subagents are pure file→file transducers.
• One writer per path. A crashed agent damages exactly one file.
• Text is copied verbatim from content.md. Improving the copy is a fidelity failure.
• Zero literal colors, font stacks, or magic px in section files — tokens only.
• scripts/*.js payloads are one arrow function, sent as function, installing onto window.__clone. Re-install after any navigate_page; resize_page does not wipe page state.
• args takes element uids only, never JSON. Interpolate literals into the function source.
• emulate resets every option you omit — restate the whole emulation state in every call.
• Measure with scrollY === 0 and after document.fonts.ready.
• State limits instead of papering over them: :active is unverifiable, prefers-reduced-motion cannot be emulated, closed shadow roots are unreachable, rAF physics motion is fitted not recovered. Mark such output authored-not-verified.
• Screenshots never decide a number.

Artifacts

Everything lives under .clone/ in the clone project root.

Close by linking .clone/CLONE-REPORT.md and .clone/PROVENANCE.md.

Common failure modes