launchframe 0.4.13 → 0.4.14

package/.cursor/commands/launchframe.md

@@ -9,7 +9,9 @@
 1. **Reference URL(s)** — Every `http://` or `https://` token (clone each site; use `docs/research/<hostname>/` when there are multiple).
 2. **SaaS idea** — All remaining text that is not a URL (often quoted): product pitch for hero and key marketing lines.
 
-You are a **foreman walking the job site** — write specs per section, dispatch builders in parallel where possible. After Phase 5, **`docs/research/LAUNCHFRAME_SUBAGENTS.md`** defines the **verbatim prompts** you must use to run verification (either four parallel **`Task`/subagents** fed one prompt each — **paste from that file only**, not from memory — or execute those four prompts **yourself sequentially**). Aggregate results only in **`docs/research/LAUNCHFRAME_VERIFICATION.md`**. **Never skip Phase 6** because subagents didn't auto-start — you initiate them explicitly from the Markdown prompt blocks. Narrative/marketing raster slots use **imagery your session generates itself** with the host’s **image-generation** tool (saved into `public/images/`), not missing assets — see **Brand identity**. Verification still covers raster slots, extracted **SVG/icons**, DOM, CSS, and **motion choreography**.
+The **primary deliverable** is a **normal Next.js + Tailwind v4 + shadcn/ui codebase** that future humans (and AI agents) can read and edit: clear file names (`SiteHeader.tsx`, `Hero.tsx`, `FeatureGrid.tsx`, …), readable JSX with semantic Tailwind utilities, tokens in `globals.css`, motion expressed as explicit keyframes / durations / easings. The reference site is the **source of truth for layout, motion, and content**, **not** for JSX. **Do not** paste the reference's compiled DOM, hashed CSS-module class names, or minified bundle output into source files as the implementation. The captures from `npm run inspect:page` (`document.html`, `ai-page-bundle.txt`, `motion-summary.json`, `capture-meta.json`) are **references** you read to remeasure into clean components — they are not artifacts you ship as code.
+
+You are a **foreman walking the job site** — write specs per section, dispatch builders in parallel where possible. After Phase 5, **`docs/research/LAUNCHFRAME_SUBAGENTS.md`** defines the **verbatim prompts** you must use to run verification (either four parallel **`Task`/subagents** fed one prompt each — **paste from that file only**, not from memory — or execute those four prompts **yourself sequentially**). Aggregate results only in **`docs/research/LAUNCHFRAME_VERIFICATION.md`**. **Never skip Phase 6** because subagents didn't auto-start — you initiate them explicitly from the Markdown prompt blocks. Narrative/marketing raster slots use **imagery your session generates itself** with the host’s **image-generation** tool (saved into `public/images/`), not missing assets — see **Brand identity**. Verification covers raster slots, extracted **SVG/icons**, **semantic** DOM structure, CSS tokens + measured-tolerance parity, **motion choreography**, and a side-by-side **screenshot diff**.
 
 ## Step 0 — Persist Launchframe inputs
 
@@ -17,12 +19,48 @@ Before reconnaissance, write or update:
 
 - `src/lib/launchframe-config.ts` — `LAUNCHFRAME_SOURCE_URL` (primary URL, usually first), `LAUNCHFRAME_SAAS_IDEA`
 - `launchframe.context.json`
-- `docs/research/LAUNCHFRAME.md` — URLs and SaaS idea
+- `docs/research/LAUNCHFRAME.md` — URLs, SaaS idea, **plus a `## Decompilation pipeline` section** (see template below)
 - **`docs/research/LAUNCHFRAME_SUBAGENTS.md`** — **before Phase 6**, ensure this runbook holds all four verifier prompts (**copy-ready**). When the bundled template differs from the latest SKILL rubrics (after skill edits), re-sync Section **Phase 6** rubrics **into this file**. Subagents receive prompts **only** from here.
 
+### `docs/research/LAUNCHFRAME.md` — required sections
+
+When you create or update this file, include at minimum:
+
+```markdown
+# Launchframe — <project name>
+
+## Source
+- Reference URL(s): <list>
+- Captured: <ISO date>
+
+## SaaS idea
+<paste LAUNCHFRAME_SAAS_IDEA verbatim>
+
+## Decompilation pipeline
+1. **Inspect** — Run `npm run inspect:page` per URL (Step 0a) and skim with Chrome DevTools MCP. Treat outputs (`document.html`, `ai-page-bundle.txt`, `motion-summary.json`, `capture-meta.json`, network CSS) as **read-only references**.
+2. **Section map** — In `docs/research/PAGE_TOPOLOGY.md`, list every visible section top-to-bottom with a **semantic name** (`SiteHeader`, `Hero`, `FeatureGrid`, `PricingTable`, `CtaBanner`, `SiteFooter`, …) and its interaction model.
+3. **Components** — One spec per section in `docs/research/components/<Name>.spec.md`. Builders write **fresh** React in `src/components/<Name>.tsx` using semantic tags, Tailwind utilities (with arbitrary values where needed), and shadcn primitives. **No** pasted hashed class names from the reference bundle.
+4. **Motion port** — Numeric port from `motion-summary.json` + Chrome MCP `getAnimations` into `globals.css` `@keyframes` and Tailwind `transition-*` / `animate-*` utilities. Match durations/easings within ±20ms / curve equivalence.
+5. **Asset mirror (optional)** — If the reference uses root-relative `/_next/...` (or similar) paths and you need them for offline/iframe work, run `npm run mirror:snapshot-assets` to copy them under `public/`. Mirrored bundles are **runtime fixtures**, never the code humans edit.
+
+## Brand identity
+- Original wordmark/logo: <path>
+- Original favicon set: <path>
+
+## Authored narrative imagery (`public/images/`)
+- `<file>` — role: hero | feature mockup | avatar | … — intent: <line>
+
+## Automated captures
+| URL | Output dir |
+| --- | ---------- |
+| https://… | docs/research/<hostname>/page-inspection/<stamp>/ |
+```
+
 ### Step 0a — Automated page inspection dump (mandatory)
 
-Right after Step 0 files are written, **from the repository root**, run the bundled **Playwright** capture **once per parsed reference URL** (before Phase 1 Chrome MCP). This produces **`ai-page-bundle.txt`** (one plain-text file: full post-JS HTML + all captured CSS), plus `document.html`, network `*.css` bodies, `inline-styles.json`, and `motion-summary.json` — attach **`ai-page-bundle.txt`** to the agent when a single pasteable artifact is enough; the frozen bundle complements live `getComputedStyle` / WAAPI work (**it does not replace** Chrome MCP for numeric motion and interaction sweeps).
+Right after Step 0 files are written, **from the repository root**, run the bundled **Playwright** capture **once per parsed reference URL** (before Phase 1 Chrome MCP). This produces **`ai-page-bundle.txt`** (one plain-text file: full post-JS HTML + all captured CSS), plus `document.html`, network `*.css` bodies, `inline-styles.json`, and `motion-summary.json`.
+
+**These artifacts are reference material, not code.** Use them to read structure, content, tokens, and motion numbers. **Do not** paste their HTML or class strings into JSX as the implementation. If you need a temporary html-to-jsx scaffolding pass (e.g. to lift content blocks of long-form copy), keep it in a scratch branch, then **rewrite into clean React** before merging — minified/compiled markup must not survive into `src/`. Attach **`ai-page-bundle.txt`** to a subagent when a single pasteable artifact is needed for context; the frozen bundle complements live `getComputedStyle` / WAAPI work (**it does not replace** Chrome MCP for numeric motion and interaction sweeps).
 
 1. **One-time per machine:** `npx playwright install chromium`
 2. **Per URL** — use the URL’s hostname for the folder (example hostname `www.example.com`):
@@ -44,14 +82,22 @@ After structure and styles match the reference, apply the **SaaS idea** to hero,
 
 ## Scope Defaults
 
-The target page(s) are the URL(s) you parsed in Pre-Flight. Clone exactly what's visible at each URL. Unless the user specifies otherwise, use these defaults:
-
-- **Fidelity level:** Pixel-perfect — exact match in colors, spacing, typography, **SVG icon presentation** (dimensions, strokes, fills, `viewBox`), **animations** (`@keyframes`, `animation*` / `transition*`, WA API timings, scroll timelines), raster **presentation** (responsive markup + CSS painting), **DOM structure**, and **authored CSS intent** (computed values must match after extraction)
-- **In scope:** Visual layout and styling, component structure and interactions, responsive design, mock data for demo purposes
-- **Out of scope:** Real backend / database, authentication, real-time features, SEO optimization, accessibility audit
-- **Customization:** Structure and visuals — pure emulation of the reference. **Marketing copy** — apply the parsed **SaaS idea** where hero/headlines/CTAs are interchangeable (see “SaaS copy overlay” above); do not invent a different product than the user’s idea.
+The target page(s) are the URL(s) you parsed in Pre-Flight. Rebuild what is visible at each URL as a **clean, hand-authored Next.js codebase** that is visually equivalent to the reference within measured tolerances. Unless the user specifies otherwise, use these defaults:
+
+- **Fidelity level — “visually equivalent within measured tolerances,” *not* compiled-DOM identity.** Match the reference on:
+  - **Colors & typography** — exact tokens (extracted via Chrome MCP `getComputedStyle`) ported into `src/app/globals.css` CSS variables and Tailwind utilities.
+  - **Spacing & layout geometry** — within **±2px** at the documented breakpoints (1440 / 768 / 390). Use Tailwind utilities; reach for **arbitrary values** (`max-w-[872px]`, `pt-[34px]`, `gap-[18px]`) when the design system tokens don't land on the measured number.
+  - **SVG iconography** — lifted geometry: matching `viewBox`, paths, strokes, fills, `currentColor` behavior, exposed in `src/components/icons.tsx` (or section-local files) under **semantic component names**. No opportunistic Lucide swaps for reference glyphs unless the spec proves equivalence.
+  - **Motion** — explicit `@keyframes`, `transition-*` / `animation-*` utilities, and Web Animations API hooks ported from `motion-summary.json` and live `getAnimations()`. Durations within **±20ms**, easing curves equivalent (cubic-beziers preserved or mathematically equivalent), scroll/intersection thresholds preserved.
+  - **Responsive behavior** — breakpoints and what each one changes (column → stack, hidden sidebars, sticky → static). Mobile-first Tailwind; same layout reconfigurations as the reference.
+  - **Raster presentation** — `object-fit`, `object-position`, parent overflow/radius, masks, `<picture>`/`<source>` parity *or* a documented `next/image` `sizes`/`srcSet` mapping that yields the same painted result.
+- **Codebase clarity is a first-class deliverable.** A future human (or another agent) opening `src/components/Hero.tsx` should immediately read normal JSX with clear element nesting, semantic Tailwind utility classes, and self-explanatory component/prop names. **No** preserved hashed class names like `navigation-menu-module__a83f2`, no minified DOM trees pasted from the reference, no inline `className` strings of >120 chars built from copied bundle output. If the reference's structure has obvious wrapper redundancy, collapse it; layout invariants and scroll/sticky behavior must still match.
+- **Layout tree — semantic, not byte-equal.** The component file structure is yours to design (see Phase 1 §Page Topology). Where possible, prefer one component per visible section and one component per repeated card/list-item variant. The visible **section order**, **scroll/sticky containers**, **z-index stacking**, and **responsive reflow** must match the reference.
+- **In scope:** Visual layout, styling, motion, component structure and interactions, responsive design, mock data for demo purposes, **clean human-readable React source**.
+- **Out of scope:** Real backend / database, authentication, real-time features, SEO optimization, accessibility audit, byte-equal DOM cloning of the reference's compiled bundle.
+- **Customization:** Structure and visuals — visually equivalent emulation of the reference. **Marketing copy** — apply the parsed **SaaS idea** where hero/headlines/CTAs are interchangeable (see “SaaS copy overlay” above); do not invent a different product than the user’s idea.
 - **Brand identity:** The reference is a **pattern** for layout, motion, and UI craft — **not** permission to ship their brand. Unless the user **explicitly** asks for a faithful copy of the reference brand (e.g. licensed work, clearly labeled internal mock, private design audit), **invent an original brand** aligned with the SaaS idea: product name, wordmark or simple logomark (SVG or styled text) sized to the same logo slot, favicon / app icon, OG imagery, and a cohesive palette. Do **not** reuse their trademarked logo paths, mascot art, or distinctive illustrative brand assets; use originals or functional UI icons instead. **Every raster slot** that is a photograph, illustration, or narrative marketing image on the reference (hero, feature mockups, social proof portraits, decorative panels, card thumbnails) must ship as **new, original imagery** grounded in the **SaaS idea** — treat the reference shot as a **composition brief** (aspect ratio, mood, subject *role*: dashboard vs lifestyle vs avatar) and recreate with product-relevant scenes, UI surrogates, logosafe crops, or **supporting sub-frames** (detail insets, secondary panels) that read as one family. **Mandatory delivery:** those slots **must** have real raster files checked into `public/images/` (or another committed static path your build serves) — **no** omitted `<img>`/`<Image>`, **no** indefinite placeholder divs/colors standing in for a photo where the reference showed one, **no** broken `href/src`. **You generate these files yourself:** use your host's **built-in image generation** capability (explicit image prompts aligned to the SaaS idea + composition brief from each reference slot), write outputs into `public/images/`, wire them into JSX, and note each file in `docs/research/LAUNCHFRAME.md`. You may **supplement** with composites or screenshots of **your** product UI mocks you build in code, but you **do not** wait for the user to supply artwork. Preserve **exact** framing CSS (`object-fit`, `object-position`, masks, layering). Do **not** hotlink or ship their competitor lifestyle/brand photography bytes except when the user explicitly allows it. Note in `docs/research/LAUNCHFRAME.md` which marks and assets are **original brand** versus **layout-only** extraction, and **list paths** for every authored narrative image.
-- **Functional icons & motion choreography:** Anything the reference treats as **UI iconography that is not a forbidden trademark** (chevrons, menu marks, inline pictograms, sprite symbols, repeating UI glyphs) — **lift path data / sprite refs / mask SVGs from the DOM** and reproduce **`viewBox`, stroke widths, joins, fills, `currentColor` behavior.** Do **not** swap in unrelated Lucide (or arbitrary stock SVG) guesses "that look close." **`@keyframes`**, **`transition` / `animation` longhands**, scroll-driven timelines, carousel timings, stagger delays, easing curves — **lift from live measurement + stylesheet text** per §0.3 — **omit or substitute timing only** when respecting `prefers-reduced-motion` or when the measured reference does the same. Product-themed raster replacements do **not** waive SVG or animation parity.
+- **Functional icons & motion choreography:** Anything the reference treats as **UI iconography that is not a forbidden trademark** (chevrons, menu marks, inline pictograms, sprite symbols, repeating UI glyphs) — **lift path data / sprite refs / mask SVGs from the DOM** and reproduce **`viewBox`, stroke widths, joins, fills, `currentColor` behavior** under semantic component names (e.g. `ChevronDownIcon`, `SearchIcon`, `WordmarkLogo`). Do **not** swap in unrelated Lucide (or arbitrary stock SVG) guesses "that look close." **`@keyframes`**, **`transition` / `animation` longhands**, scroll-driven timelines, carousel timings, stagger delays, easing curves — **lift from live measurement + stylesheet text** and reauthor as Tailwind utilities or CSS in `globals.css` — **omit or substitute timing only** when respecting `prefers-reduced-motion` or when the measured reference does the same. Product-themed raster replacements do **not** waive SVG or animation parity.
 
 If the user provides additional instructions (specific fidelity level, customizations, extra context), honor those over the defaults.
 
@@ -87,13 +133,33 @@ When you traverse the DOM and the Network panel, do **not** treat all nodes equa
 
 Only after the above are accounted for should you spend cycle time on minor text or non-visual refactors. A perfect grid with missing hero art and dead animation still fails the clone.
 
-### 0b. HTML / DOM structure (layout tree, not “vibes”)
+### 0b. HTML / DOM structure — semantic rebuild, not byte-equal copy
 
-**Exact** means the **visible layout tree** matches: **section order**, **sibling order**, **wrapper depth** (decorative `div`s, flex rows, grid shells), and **key hooks** (sticky wrappers, scroll containers). React may rename tags **only** if roles/landmarks still reflect the same outline and **computed layout** is unchanged — do not collapse three nested wrappers into one unless the spec proves they are redundant in the reference. Specs must include a short **DOM outline** (indentation sketch or bullet tree) for complex sections so builders and **Phase 6 verifiers** can diff structure.
+The clone's **visible layout tree** must match the reference: **section order**, **sibling order** of meaningful content, **scroll/sticky containers**, **z-index stacking**, and **responsive reflow**. The clone's **source code** must be **hand-authored React** that a human or another agent can read and edit:
 
-### 0c. CSS fidelity (authored + computed)
+- **Rename to semantic.** Replace machine-named wrappers (`div.navigation-menu-module__a83f2`) with React components named for what they *do* (`<SiteHeader>`, `<NavLinks>`, `<HeroEyebrow>`). Use semantic HTML (`<header>`, `<nav>`, `<main>`, `<section>`, `<article>`, `<footer>`, `<button>`, `<a>`) — landmarks must still reflect the page outline.
+- **Collapse redundant wrappers.** If the reference nests three `div`s for purely build-tool reasons and computed layout (flex axes, padding/margin/gap, scroll behavior, stacking) is unchanged when you flatten them, flatten them. The test is **computed layout equivalence at all documented breakpoints**, not “same number of `<div>`s.”
+- **Never paste compiled DOM as source.** `document.html` and `body-outer.html` are reference material for hierarchy and content — they are **not** the implementation. Hashed class names (`__a83f2`, `module__hash`), inlined runtime data attributes, and minified inline `style="..."` strings copied from those files are **forbidden** in `src/`. If you need a one-time transform pass to lift long-form copy or list data out of `document.html`, do it in a scratch file and rewrite into clean JSX before merging.
+- **Spec includes a DOM outline.** For non-trivial sections, the spec gives a short indentation sketch of the **rebuilt** tree (semantic tag + role, not class names) so builders and **Phase 6 verifiers** know what the rebuild should look like.
 
-Tailwind utilities are fine **only** as a transport for **measured** values. Every critical rule must trace back to **`getComputedStyle()`** (or authored sheet text) from Chrome MCP: **no “close” token swaps** (`rounded-lg` when the radius is `10px`, `gap-4` when gap is `18px`) unless values compile to the same pixel output. Prefer arbitrary values (`max-w-[872px]`, `rounded-[10px]`) when shadcn defaults don’t land on the measured number. **Pseudo-elements** and **custom properties** used by the reference must appear in the clone with the same cascade intent.
+### 0c. CSS fidelity — measured tokens, hand-written utilities
+
+CSS in this codebase is **Tailwind v4 utilities + arbitrary values + tokens in `globals.css`**, all hand-authored. Every critical rule must trace back to `getComputedStyle()` (or authored sheet text) from Chrome MCP / `inspect:page`:
+
+- **Tokens first.** Colors, font families, font sizes, radii, shadows that recur across the page go in `:root` (and `.dark`) inside `src/app/globals.css` as CSS custom properties; reference them via Tailwind `bg-[var(--surface-1)]` or shadcn token names where the role matches.
+- **Tailwind utilities second.** Use semantic utility classes (`flex items-center gap-3 px-6 py-2 rounded-full`) for the bulk of layout. Reach for **arbitrary values** (`max-w-[872px]`, `rounded-[10px]`, `gap-[18px]`, `tracking-[-0.02em]`) when measured values don't land on a default token.
+- **Module CSS only as a documented escape hatch.** If a section needs a snippet of CSS that Tailwind cannot express cleanly (complex `mask-image` with multiple layers, scroll-timeline, container-query-driven backgrounds), write it in a small **hand-authored** `.module.css` (or `globals.css` block) with **meaningful** class names and reference it from JSX via `cn()`. Do **not** import or paste hashed class strings from the reference's compiled CSS modules into JSX.
+- **Pseudo-elements & custom properties** used by the reference must appear in the clone with the same cascade intent. Lift `@keyframes` verbatim into `globals.css`.
+
+### 0d. Decompilation pipeline (mental model)
+
+Every section follows the same five-stage pipeline; never skip a stage:
+
+1. **Inspect** — read `document.html`, `ai-page-bundle.txt`, `motion-summary.json`, `capture-meta.json`, plus live Chrome DevTools MCP measurements.
+2. **Section map** — name the section (`Hero`, `FeatureGrid`, …) and decide its interaction model.
+3. **Components** — write a fresh React component in `src/components/<Name>.tsx` with semantic JSX and Tailwind utilities; import any extracted icons by their semantic name.
+4. **Motion port** — translate measured durations / easings / keyframes into explicit Tailwind utilities or `globals.css` rules; verify with Chrome MCP `getAnimations`.
+5. **Asset mirror (optional)** — if `/_next/...` or other root-relative paths matter for offline preview, run `npm run mirror:snapshot-assets` (Phase 2 step) to sideload them into `public/`. Mirrored output is a fixture, not a source file.
 
 ### 1. Completeness Beats Speed
 
@@ -176,6 +242,16 @@ The spec file is not optional. It is not a nice-to-have. If you dispatch a build
 
 Every builder agent must verify `npx tsc --noEmit` passes before finishing. After merging worktrees, you verify `npm run build` passes. A broken build is never acceptable, even temporarily.
 
+### 10. Codebase Clarity Is a First-Class Deliverable
+
+A future human (or another agent) opening any file under `src/` should be able to read and edit it without consulting the reference site or `document.html`:
+
+- **File names & component names are semantic.** `SiteHeader.tsx`, `Hero.tsx`, `FeatureGrid.tsx`, `PricingTable.tsx`, `TestimonialsCarousel.tsx`, `SiteFooter.tsx` — not `Section1.tsx` or `NavigationMenuModule.tsx`.
+- **JSX is hand-authored Tailwind.** Class strings should read like prose (`flex items-center justify-between px-6 py-3`), not like minified bundle output. Conditional classes go through `cn()` from `src/lib/utils.ts`.
+- **Long pages compose small components.** `src/app/page.tsx` is a thin assembly file: imports, ordered section tags, top-level layout. Each section is its own component.
+- **Props over magic.** Card lists, tab states, pricing tiers, feature lists are passed as typed props/data objects (often defined alongside the component or in `src/lib/data/<name>.ts`), not hard-coded inside one giant return tree.
+- **No dead reference debris.** Once `document.html` has informed the rebuild, do not leave its raw fragments commented out or pasted in `src/`. Reference notes belong in `docs/research/`.
+
 ## Phase 1: Reconnaissance
 
 Navigate to the target URL with browser MCP.
@@ -313,11 +389,18 @@ Save this as `docs/research/PAGE_TOPOLOGY.md` — it becomes your assembly bluep
 This is sequential. Do it yourself (not delegated to an agent) since it touches many files:
 
 1. **Update fonts** in `layout.tsx` to match the target site's actual fonts
-2. **Update globals.css** with the target's color tokens, spacing values, keyframe animations, utility classes, and any **global scroll behaviors** (Lenis, smooth scroll CSS, scroll-snap on body)
+2. **Update globals.css** with the target's color tokens, spacing values, keyframe animations, utility classes, and any **global scroll behaviors** (Lenis, smooth scroll CSS, scroll-snap on body). Lift `@keyframes` blocks **verbatim** from `motion-summary.json` (or the network CSS files in the inspection dump) into `globals.css` — keep their names so utility classes can reference them, or rename them under semantic names and update references.
 3. **Create TypeScript interfaces** in `src/types/` for the content structures you've observed
-4. **Extract SVG icons** — find all inline `<svg>` elements on the page, deduplicate them, and save as named React components in `src/components/icons.tsx`. Name them by visual function (e.g., `SearchIcon`, `ArrowRightIcon`, `LogoIcon`).
-5. **Download global assets** — write and run a Node.js script (`scripts/download-assets.mjs`) that downloads all images, videos, and other binary assets from the page to `public/`. Preserve meaningful directory structure.
-6. Verify: `npm run build` passes
+4. **Extract SVG icons** — find all inline `<svg>` elements on the page, deduplicate them, and save as **semantically named** React components in `src/components/icons.tsx` (`SearchIcon`, `ChevronRightIcon`, `WordmarkLogo`, `MenuIcon`, …). Lift `viewBox` and path data verbatim; do not substitute Lucide unless documented.
+5. **Download structural / permission-neutral assets** — write and run a Node.js script (`scripts/download-assets.mjs`) that downloads textures, gradients, video posters, and other neutral binaries to `public/`. **Do not** download brand-photography or competitor mascot art for narrative slots — those are authored originals per Brand identity.
+6. **(Optional) Mirror snapshot assets** — if the reference uses root-relative `/_next/...` (or similar) paths and you want offline preview to match (e.g. for `/snapshot` or for diff screenshots without the live site), run:
+
+   ```bash
+   npm run mirror:snapshot-assets
+   ```
+
+   This copies `_next/`, `assets/`, fonts, etc. from the latest `docs/research/<host>/page-inspection/<stamp>/` capture (using `LAUNCHFRAME_SOURCE_URL` as the base) into `public/`. **Mirrored bundles are runtime fixtures, never the code humans edit.** They do not replace your hand-authored `src/components/**` rebuild — they only let pages that reference `/_next/...` paths resolve locally.
+7. Verify: `npm run build` passes
 
 ### Asset Discovery Script Pattern
 
@@ -444,12 +527,24 @@ For each section (or sub-component, if you're breaking it up), create a spec fil
 # <ComponentName> Specification
 
 ## Overview
+- **Semantic component name:** `<ComponentName>` (PascalCase, role-based — e.g. `SiteHeader`, `Hero`, `FeatureGrid`, `PricingTier`)
 - **Target file:** `src/components/<ComponentName>.tsx`
 - **Screenshot:** `docs/design-references/<screenshot-name>.png`
 - **Interaction model:** <static | click-driven | scroll-driven | time-driven>
+- **Reference selector(s):** <CSS selectors used during extraction — for traceability only, NOT for pasting into JSX>
+
+## Rebuild plan (semantic JSX outline)
+<Indented bullet tree of the **rebuilt** structure using semantic tags + role-named children. Example:
 
-## DOM Structure
-<Describe the element hierarchy — what contains what>
+- `<header>` (sticky on scroll past 50px)
+  - `<div>` brand row
+    - `<WordmarkLogo />`
+    - `<nav>` primary links (`<NavLink>` × N)
+  - `<div>` actions
+    - `<Button variant="ghost">Sign in</Button>`
+    - `<Button>Get started</Button>`
+
+This is the structure builders implement — NOT a transcription of the reference's hashed-class wrapper soup.>
 
 ## Computed Styles (exact values from getComputedStyle)
 
@@ -503,6 +598,13 @@ For each section (or sub-component, if you're breaking it up), create a spec fil
 - **Tablet (768px):** <what changes — e.g., "maintains 2-column, gap reduces to 16px">
 - **Mobile (390px):** <what changes — e.g., "stacks to single column, images full-width">
 - **Breakpoint:** layout switches at ~<N>px
+
+## Implementation notes (clean-rebuild reminders)
+- Use semantic tags (`<header>`, `<nav>`, `<section>`, `<button>`, `<a>`).
+- Use Tailwind utilities for layout; use **arbitrary values** when measured numbers don't land on a default token.
+- **Do not** paste reference class names like `module__a83f2`, `navigation-menu__item`, or any hashed/build-tool-generated string into JSX.
+- Pull repeating data (cards, links, tiers) into a typed array near the top of the component or in `src/lib/data/<name>.ts`; `.map()` over it.
+- Conditional classes go through `cn()` from `src/lib/utils.ts`.
 ```
 
 Fill every section. If a section doesn't apply (e.g., no states for a static footer), write "N/A" — but think twice before marking States & Behaviors as N/A. Even a footer might have hover states on links.
@@ -519,9 +621,12 @@ Based on complexity, dispatch builder agent(s) in worktree(s):
 - The full contents of its component spec file (inline in the prompt — don't say "go read the spec file")
 - Path to the section screenshot in `docs/design-references/`
 - Which shared components to import (`icons.tsx`, `cn()`, shadcn primitives)
-- The target file path (e.g., `src/components/HeroSection.tsx`)
+- The **semantic** target file path (e.g., `src/components/Hero.tsx`, not `Section1.tsx`)
 - Instruction to verify with `npx tsc --noEmit` before finishing
 - For responsive behavior: the specific breakpoint values and what changes
+- **Explicit rebuild-clean rule** (paste verbatim into every builder prompt):
+
+  > **Write fresh React.** Read the spec to understand structure, content, tokens, and motion numbers. **Do not** paste hashed class names (`module__a83f2`, `navigation-menu__hash`), inline `style="..."` strings, or minified DOM from `document.html` into JSX. Write semantic JSX (`<header>`, `<nav>`, `<section>`, `<button>`, `<a>` …), Tailwind utilities (with arbitrary values where measured numbers demand it), and shadcn primitives. Pull repeating data into typed arrays. Use `cn()` for conditional classes. The result must be readable to a future human or agent without consulting the reference site.
 
 **Don't wait.** As soon as you've dispatched the builder(s) for one section, move to extracting the next section. Builders work in parallel in their worktrees while you continue extraction.
 
@@ -553,11 +658,13 @@ After assembly, do NOT declare the clone complete. Take side-by-side comparison
 2. Compare section by section, top to bottom, at desktop (1440px)
 3. Compare again at mobile (390px)
 4. For each discrepancy found:
+   - **Tolerances:** ±2px on layout dimensions, ±20ms on motion durations, easing curves equivalent. Larger gaps are bugs.
    - Check the component spec file — was the value extracted correctly?
    - If the spec was wrong: re-extract from browser MCP, update the spec, fix the component
    - If the spec was right but the builder got it wrong: fix the component to match the spec
 5. Test all interactive behaviors: scroll through the page, click every button/tab, hover over interactive elements
-6. **Motion QA:** Re-run the **motion audit script** (or per-element `getAnimations`) on the reference and spot-check the clone in devtools — **durations, delays, and easing curves must match** (e.g. 320ms vs 300ms is a failure). Re-scroll hero and sticky headers; carousels and scroll-driven sections must trigger at the same thresholds documented in `BEHAVIORS.md`
+6. **Motion QA:** Re-run the **motion audit script** (or per-element `getAnimations`) on the reference and spot-check the clone in devtools — durations within **±20ms**, easing curves equivalent, scroll/intersection thresholds preserved. Re-scroll hero and sticky headers; carousels and scroll-driven sections must trigger at the same thresholds documented in `BEHAVIORS.md`.
+7. **Codebase clarity sanity check:** open 2–3 random components under `src/components/` and confirm they read like normal hand-authored React (semantic tags, Tailwind utilities, no hashed class strings, no pasted minified markup). If a builder shipped DOM-soup, send it back.
 
 Only after this visual QA pass is the clone ready for **Phase 6 verification**. Immediately **confirm `docs/research/LAUNCHFRAME_SUBAGENTS.md`** contains four self-contained **`## Prompt — Pass N`** sections matching the Phase 6 rubrics; update that file whenever you change rubric wording locally.
 
@@ -576,44 +683,51 @@ Foreman skim is insufficient — someone must execute **all four prompts in `LAU
 
 **Minimum four verification passes** (four subagents **or** four self-executed steps — prompts sourced from **`LAUNCHFRAME_SUBAGENTS.md`;** the authoritative rubric text below must stay mirrored there):
 
-1. **Raster media & icons** — **Narrative slots:** inventory every reference marketing/lifestyle/card/hero image role from specs vs **committed files** (`public/images/...`) actually referenced in JSX; **`FAIL`** if the reference showed a photo/panel thumbnail and this clone relies on placeholders or bare gradients. Then list every raster/video poster and **every authored SVG/component used as an icon** from `src/`. Confirm **files exist** under `public/` with **correct paths** where expected; compare presentation to specs: **`picture`/`source` behavior**, **`sizes` / responsive behavior**, **`object-fit` / `object-position`**, dimensions/aspect-ratio, **parent overflow and radius**, **`background-image`** and **pseudo-elements**. For SVGs/icons: **`viewBox`**, strokes/fills/`currentColor`, and sprite usage must match specs — reject opportunistic Lucide substitutions unless the spec explicitly allowed them. Flag wrong crops, missing layers, or lazy `next/image` `fill` misuse.
-2. **HTML / DOM structure** — Diff **PAGE_TOPOLOGY.md** + component specs against the React tree: **section order**, **wrapper count**, **sibling order**, scroll/sticky containers. Any flattened structure that changes stacking or scroll must be **FAIL** until fixed.
-3. **CSS parity** — Spot-check **hero, nav, first fold, footer** (and any section flagged risky) against spec CSS: tokens in **`globals.css`**, arbitrary Tailwind vs measured px, **keyframes** presence. Run **`npm run lint`** and **`npm run typecheck`** inside the verification worktree; failures = **FAIL** until green.
-4. **Motion & interaction** — Re-walk **`docs/research/BEHAVIORS.md`** and motion audit JSON: headers, carousels, scroll-driven UI, smooth-scroll libs. Phase 5 motion QA must be **confirmed**, not assumed.
+1. **Raster media & icons** — **Narrative slots:** inventory every reference marketing/lifestyle/card/hero image role from specs vs **committed files** (`public/images/...`) actually referenced in JSX; **`FAIL`** if the reference showed a photo/panel thumbnail and this clone relies on placeholders or bare gradients. Then list every raster/video poster and **every authored SVG/component used as an icon** from `src/`. Confirm **files exist** under `public/` with **correct paths**; compare presentation to specs: `picture`/`source` behavior or documented `next/image` mapping, `sizes` / responsive behavior, `object-fit` / `object-position`, dimensions/aspect-ratio, parent overflow and radius, `background-image` and pseudo-elements. For SVGs/icons: `viewBox`, strokes/fills/`currentColor`, and sprite usage must match specs and live under **semantic component names** in `src/components/icons.tsx` — reject opportunistic Lucide substitutions unless the spec explicitly allowed them.
+2. **Semantic structure & code clarity** — Diff `PAGE_TOPOLOGY.md` + component specs against the React tree for **section order**, **scroll/sticky containers**, and **z-index stacking**. Confirm `src/components/` files use **semantic component names** (`SiteHeader`, `Hero`, `FeatureGrid`, …), semantic HTML, and Tailwind utilities. **`FAIL`** if any source file contains hashed class names (`module__a83f2`, `__hash`, `navigation-menu-module`), pasted minified DOM, or inline `style="..."` strings copied from `document.html`. Wrapper-count drift is fine **as long as computed layout, scroll, and stacking match** at 1440 / 768 / 390.
+3. **Visual & CSS parity (within tolerance)** — Take side-by-side screenshots of the clone vs the reference at **1440 / 768 / 390**. Spot-check hero, nav, first fold, footer (plus any spec-flagged risky section): layout dimensions within **±2px**, colors/typography exact, tokens present in `globals.css`, arbitrary Tailwind values matching measured px. Run `npm run lint` and `npm run typecheck`; failures = **`FAIL`** until green.
+4. **Motion & interaction** — Re-walk `docs/research/BEHAVIORS.md` and motion-audit JSON: headers, carousels, scroll-driven UI, smooth-scroll libs. Confirm durations/easings match within **±20ms** / equivalent curves, `@keyframes` ported into `globals.css`, scroll-trigger thresholds preserved. Phase 5 motion QA must be **confirmed**, not assumed.
 
-Each pass (whether another agent or you) returns **`PASS` or `FAIL`**, a **bullet list** of issues with **`file:line`** pointers, and **suggested fixes**. The foreman **resolves or explicitly documents** every `FAIL` (deferred items listed in the completion report under **Known gaps**). **First rubric checklist includes:** confirm **every narrative image slot** from specs has **on-disk raster files** wired in JSX — **`FAIL`** if any slot is placeholder-only while the reference showed imagery. **Do not** declare Launchframe complete until all four passes **`PASS`** or gaps are accepted by the user context.
+Each pass (whether another agent or you) returns **`PASS` or `FAIL`**, a **bullet list** of issues with **`file:line`** pointers, and **suggested fixes**. The foreman **resolves or explicitly documents** every `FAIL` (deferred items listed in the completion report under **Known gaps**). **First rubric checklist includes:** confirm every narrative image slot has on-disk raster files wired in JSX — **`FAIL`** if any slot is placeholder-only while the reference showed imagery. **Do not** declare Launchframe complete until all four passes **`PASS`** or gaps are accepted by the user context.
 
 ## Pre-Dispatch Checklist
 
 Before dispatching ANY builder agent, verify you can check every box. If you can't, go back and extract more.
 
+- [ ] **Semantic component name** chosen (`SiteHeader`, `Hero`, `FeatureGrid`, …) — not `Section1` or a transliteration of a hashed CSS-module name
+- [ ] **Rebuild plan (semantic JSX outline)** included in the spec — drawn from the reference's hierarchy but written in clean tags, NOT pasted DOM
 - [ ] **Authored narrative rasters planned:** list each marketing/lifestyle/card image slot vs **planned `public/images/...` path** (Brand identity originals). No section ships with “TODO image” once built
-- [ ] **Image markup + styling** captured in spec: `picture`/`source`/`sizes`/`srcset` (or documented `next/image` mapping), `object-fit`/`object-position`, clipping parents, pseudo-element backgrounds if any
-- [ ] **Icon/SVG snippets** inlined in spec where needed: dominant paths or sprite `id`s, **`viewBox`**, stroke/fill rules — enough that a builder does not guess Lucide substitutions
-- [ ] **DOM outline** included for non-trivial sections (wrappers, order)
+- [ ] **Image markup + styling** captured in spec: `picture`/`source`/`sizes`/`srcset` or documented `next/image` mapping, `object-fit`/`object-position`, clipping parents, pseudo-element backgrounds if any
+- [ ] **Icon/SVG snippets** inlined in spec where needed: dominant paths or sprite `id`s, `viewBox`, stroke/fill rules — enough that a builder does not guess Lucide substitutions, plus the **semantic component name** the icon will live under in `icons.tsx`
 - [ ] Spec file written to `docs/research/components/<name>.spec.md` with ALL sections filled
-- [ ] Every CSS value in the spec is from `getComputedStyle()`, not estimated
+- [ ] Every CSS value in the spec is from `getComputedStyle()`, not estimated; tolerances documented (±2px / ±20ms)
 - [ ] Interaction model is identified and documented (static / click / scroll / time)
 - [ ] For stateful components: every state's content and styles are captured
 - [ ] For scroll-driven components: trigger threshold, before/after styles, and transition are recorded
 - [ ] For hover states: before/after values and transition timing are recorded
 - [ ] **Motion audit JSON** from Chrome MCP is in `docs/research/BEHAVIORS.md` (`## Motion audit (Chrome MCP)`); follow-up passes exist for any capped/missed selectors
-- [ ] Relevant **`@keyframes`** from the reference appear in `globals.css` or module CSS **verbatim** (or equivalent WAAPI) — not hand-waved
+- [ ] Relevant `@keyframes` from the reference appear in `globals.css` or module CSS **verbatim** (or equivalent WAAPI) — not hand-waved
 - [ ] Elements that move via **Web Animations API** have timing cross-checked with `getAnimations` output from Chrome MCP
 - [ ] All images in the section are identified (including overlays and layered compositions)
 - [ ] Responsive behavior is documented for at least desktop and mobile
-- [ ] Text content is verbatim from the site, not paraphrased
+- [ ] Text content is verbatim from the site (or overlaid with the SaaS idea per Phase 4), not paraphrased into nonsense
 - [ ] The builder prompt is under ~150 lines of spec; if over, the section needs to be split
+- [ ] **Rebuild-clean rule** is included verbatim in the builder prompt (no hashed class strings, no pasted minified DOM)
 
 ## What NOT to Do
 
 These are lessons from previous failed clones — each one cost hours of rework:
 
+- **Don't paste compiled DOM, hashed class names, or minified bundle output as the implementation.** `document.html`, `body-outer.html`, and `ai-page-bundle.txt` are reference material. Class strings like `navigation-menu-module__a83f2`, inline `style="--var:..."`-laden divs, and `__hash__` suffixes copied from those files must NOT survive into `src/`. If you used a transient html-to-jsx pass to lift content blocks, rewrite the result into clean React with semantic tags and Tailwind utilities before merging.
+- **Don't ship `Section1.tsx` / `Block2.tsx`.** Component file and export names must read like the role they play (`Hero`, `PricingTable`, `TestimonialsCarousel`). A future agent should not have to guess.
+- **Don't hand a builder a bare `document.html` excerpt as the spec.** Every builder gets the structured spec from `docs/research/components/<name>.spec.md` — including the semantic JSX outline and the rebuild-clean rule. Pasted minified HTML is not a spec.
 - **Don't build click-based tabs when the original is scroll-driven (or vice versa).** Determine the interaction model FIRST by scrolling before clicking. This is the #1 most expensive mistake — it requires a complete rewrite, not a CSS fix.
 - **Don't extract only the default state.** If there are tabs showing "Featured" on load, click Productivity, Creative, Lifestyle and extract each one's cards/content. If the header changes on scroll, capture styles at position 0 AND position 100+.
 - **Don't miss overlay/layered images.** A background watercolor + foreground UI mockup = 2 images. Check every container's DOM tree for multiple `<img>` elements and positioned overlays.
 - **Don't build mockup components for content that's actually videos/animations.** Check if a section uses `<video>`, Lottie, or canvas before building elaborate HTML mockups of what the video shows.
-- **Don't approximate CSS classes.** "It looks like `text-lg`" is wrong if the computed value is `18px` and `text-lg` is `18px/28px` but the actual line-height is `24px`. Extract exact values.
+- **Don't approximate CSS classes.** "It looks like `text-lg`" is wrong if the computed value is `18px` and `text-lg` is `18px/28px` but the actual line-height is `24px`. Extract exact values, and reach for arbitrary values (`text-[18px] leading-[24px]`) when defaults don't land on the measurement.
+- **Don't import the reference's CSS modules / hashed class names.** If you find yourself wanting `import styles from "./_navigation-menu-module__a83f2.module.css"` and then `<div className={styles["root-3f9"]}>` in JSX, stop — that's the wrong direction. Re-author the styles as Tailwind utilities (with arbitrary values) or, when truly needed, a small hand-authored `.module.css` with **meaningful** class names.
+- **Don't treat `npm run mirror:snapshot-assets` output as code.** Mirrored `public/_next/...` is a runtime fixture for offline preview. The hand-authored `src/components/**` files are the deliverable.
 - **Don't build everything in one monolithic commit.** The whole point of this pipeline is incremental progress with verified builds at each step.
 - **Don't reference docs from builder prompts.** Each builder gets the CSS spec inline in its prompt — never "see DESIGN_TOKENS.md for colors." The builder should have zero need to read external docs.
 - **Don't skip asset extraction.** Without real images, videos, and fonts, the clone will always look fake regardless of how perfect the CSS is.

package/.cursor/commands/snapshot.md

@@ -65,6 +65,16 @@ Use the same **`<host-slug>`** as in Step 3.
 
 Run **`npm run build`** and fix any errors.
 
+## Optional — mirror root-relative assets for offline preview
+
+If the captured `document.html` references root-relative paths like **`/_next/...`**, **`/assets/...`**, or **`/static/...`**, those will 404 in the iframe because they resolve against `localhost:3000`, not the live site. To make the iframe self-contained, run:
+
+```bash
+npm run mirror:snapshot-assets
+```
+
+This downloads referenced root-relative assets from **`LAUNCHFRAME_SOURCE_URL`** into `public/_next/`, `public/assets/`, etc., so the iframe can render fully offline. The mirrored bundles are runtime fixtures — they are **not** code you edit, and `/launchframe` does not use them as the implementation source. Skip this step if the iframe already renders correctly (the page may be fully self-contained, or the live origin may be reachable from the browser without needing local mirrors).
+
 ## What to tell the user
 
 After **`npm run dev`**: