launchframe 0.4.9 → 0.4.11

package/.clinerules

@@ -10,7 +10,7 @@ This version has breaking changes — APIs, conventions, and file structure may
 # Website Reverse-Engineer Template
 
 ## What This Is
-A reusable template for reverse-engineering any website into a clean, modern Next.js codebase using AI coding agents. The Next.js + shadcn/ui + Tailwind v4 base is pre-scaffolded — use **`/launchframe <url> "saas idea"`** for the full pixel-perfect clone plus SaaS landing copy (`src/lib/launchframe-config.ts`, `launchframe.context.json`, `docs/research/LAUNCHFRAME.md`). For a **new empty folder** only, **`npx launchframe@latest`** unpacks this template; then run **`/launchframe`** in that project with your URL and pitch.
+A reusable template for reverse-engineering any website into a clean, modern Next.js codebase using AI coding agents. The Next.js + shadcn/ui + Tailwind v4 base is pre-scaffolded — use **`/launchframe <url> "saas idea"`** for the full pixel-perfect clone plus SaaS landing copy (`src/lib/launchframe-config.ts`, `launchframe.context.json`, `docs/research/LAUNCHFRAME.md`). The agent executing **`/launchframe`** must follow **Step 0a** in that command: run **`npm run inspect:page`** once per reference URL (Playwright: `document.html`, network CSS, `motion-summary.json`) before Phase 1. For a **new empty folder** only, **`npx launchframe@latest`** unpacks this template; then run **`/launchframe`** in that project with your URL and pitch.
 
 ## Tech Stack
 - **Framework:** Next.js 16 (App Router, React 19, TypeScript strict)
@@ -38,7 +38,7 @@ A reusable template for reverse-engineering any website into a clean, modern Nex
 - **No personal aesthetic changes during emulation phase** — match 1:1 first, customize later
 - **Real content** — use actual text and assets from the target site where they are interchangeable chrome; **`/launchframe`** overlays your SaaS pitch on headings and CTAs. **Marketing photographs and illustrative hero/feature imagery are not photocopied**: you **must** ship **committed files** under `public/images/` (etc.) for every such slot — **generate them yourself** with your host **image-generation** tool (prompts tied to the SaaS idea), wire into components, supplement with UI mock composites only if helpful. Blank placeholders count as unfinished. Record paths in `docs/research/LAUNCHFRAME.md`
 - **Beauty-first** — every pixel matters
-- **DOM crawl priority** — when walking the target page, emphasize **images** (raster, responsive sources, CSS backgrounds), **SVGs** (inline icons, sprites, masks — **copy extracted geometry**, do not approximate with unrelated Lucide glyphs), then **motion** (**copy** `@keyframes`, `transition`/`animation` timings, scroll triggers, carousel staggers via Chrome MCP / CSS sources). **Measure and mirror** mounting and styling from the DOM; scrape **permission-neutral** bytes when appropriate. When a raster slot must be original for brand safety, **author** replacements and label them in research notes — **that never waives SVG or animation fidelity**
+- **Inspection workflow (canonical)** — Follow the ordered **five steps** in `docs/research/INSPECTION_GUIDE.md`: (1) **Structure** — DOM as hierarchy reference, not pasted production HTML; (2) **Styles** — Computed/stylesheets and tokens; (3) **Motion** — `@keyframes`, transitions, timings, triggers; (4) **Assets** — rasters/SVGs with brand-safe originals for marketing slots when required; (5) **Implementation** — Next.js components rebuild. Within crawls (Chrome MCP / DevTools), still emphasize **images** (raster, responsive sources, CSS backgrounds), **SVGs** (inline, sprites, masks — **exact geometry**, not unrelated Lucide stand-ins), then **motion fidelity**. **Measure and mirror** from the DOM; scrape **permission-neutral** bytes when appropriate — **SVG and animation fidelity are not waived** when rasters are replaced
 
 ## Project Structure
 ```
@@ -71,89 +71,128 @@ scripts/            # Asset download scripts
 
 ## How to Reverse-Engineer Any Website
 
-This guide outlines what to capture when inspecting a target website via Chrome MCP or browser DevTools.
+This guide is the **canonical workflow** when inspecting a target site (Chrome MCP, DevTools, or similar). Execute the steps **in order**: structure and styles establish the blueprint; motion and assets define feel and legality; implementation is always a deliberate rebuild—not a pasted dump.
 
-## Priority: media, SVGs, and motion (do this early)
+---
 
-When crawling the DOM and network, **tackle these before fine-tuning copy or spacing**:
+## Step 1 — Structure (DOM hierarchy only)
 
-1. **Raster imagery** — Every `<img>`, `<picture>` / `source`, `srcset` / `sizes`, CDN URLs, lazy-loaded `data-src`, `loading="lazy"` nodes, **CSS `background-image`** on the element and ancestors (including `::before` / `::after`), masks that use `url()`, `<video>` still / poster frames. Prefer **downloading** originals via scripts or MCP; if a URL is blocked or session-gated, **export a screenshot** of the element’s bounding box at a crisp DPR and store it under `public/images/`, and note the substitute in the spec.
-2. **SVGs** — Inline `<svg>`, `<use>` / sprite sheets, **SVG in CSS** (`mask-image`, `background-image`), favicons as SVG, logo marks. Prefer extracting path/viewBox into React components or static files under `public/` — **recreate** from a screenshot/trace only when the markup is obfuscated or blocked.
-3. **Motion & animation** — Inspect Styles for `animation`, `animation-name`, `animation-timeline`, `transition`, `transform`, `@keyframes`; check for libraries (Framer Motion, GSAP, Lottie, Lenis). Capture **durations, easings, delays, fill-modes**, scroll/view triggers, and `prefers-reduced-motion` handling. Motion often defines perceived quality — do not leave it as an afterthought.
+Treat HTML as a **map of hierarchy**, not as shippable source code.
 
-Then continue with typography, spacing, and component structure as usual.
+- **DevTools limitation:** Copying `<head>` and `<body>` with “Copy ▸ Copy outerHTML” gives **one frozen snapshot**. It omits most **stylesheet and script** behavior and may inline classes whose meaning lives in external bundles.
+- **What to extract anyway:** Landmark regions, heading levels, nesting (sections → rows → cards), repeated patterns, form fields, navigation trees, semantic roles.
+- **What not to do:** Do not paste a single giant HTML file into production or assume it reproduces routing, hydration, or data fetching.
 
-## Phase 1: Visual Audit
+### Component & layout checklist (supports Step 1)
+
+**Component inventory** — For each distinct UI block, capture:
 
-### Screenshots to Capture
-- [ ] Every distinct page — desktop, tablet, mobile
-- [ ] Dark mode variants (if applicable)
-- [ ] Light mode variants (if applicable)
-- [ ] Key interaction states (hover, active, open menus, modals)
-- [ ] Loading/skeleton states
-- [ ] Empty states
-- [ ] Error states
-
-### Design Tokens to Extract
-- [ ] **Colors** — background, text (primary/secondary/muted), accent, border, hover, error, success, warning
-- [ ] **Typography** — font family, sizes (h1-h6, body, caption, label), weights, line heights, letter spacing
-- [ ] **Spacing** — padding/margin patterns (look for a scale: 4px, 8px, 12px, 16px, 24px, 32px, etc.)
-- [ ] **Border radius** — buttons, cards, avatars, inputs
-- [ ] **Shadows/elevation** — card shadows, dropdown shadows, modal overlay
-- [ ] **Breakpoints** — when does the layout shift? (inspect with DevTools responsive mode)
-- [ ] **Icons** — which icon library? custom SVGs? sizes?
-- [ ] **Avatars** — sizes, shapes, fallback behavior
-- [ ] **Buttons** — all variants (primary, secondary, ghost, icon-only, danger)
-- [ ] **Inputs** — text fields, textareas, selects, checkboxes, toggles
-
-## Phase 2: Component Inventory
-
-For each distinct UI component, document:
 1. **Name** — what would you call this component?
-2. **Structure** — what HTML elements / child components does it contain?
-3. **Variants** — does it have different sizes, colors, or states?
+2. **Structure** — HTML elements / child components and order
+3. **Variants** — sizes, tones, densities
 4. **States** — default, hover, active, disabled, loading, error, empty
-5. **Responsive behavior** — how does it change at different breakpoints?
-6. **Interactions** — click, hover, focus, keyboard navigation
-7. **Animations** — transitions, entrance/exit animations, micro-interactions
-
-### Common Components to Look For
-- Navigation (top bar, sidebar, bottom bar)
-- Cards / list items
-- Buttons and links
-- Forms and inputs
-- Modals and dialogs
-- Dropdowns and menus
-- Tabs and segmented controls
-- Avatars and user badges
-- Loading skeletons
-- Toast notifications
-- Tooltips and popovers
-
-## Phase 3: Layout Architecture
-
-- [ ] **Grid system** — CSS Grid? Flexbox? Fixed widths?
-- [ ] **Column layout** — how many columns at each breakpoint?
-- [ ] **Max-width** — main content area max-width
-- [ ] **Sticky elements** — header, sidebar, floating buttons
-- [ ] **Z-index layers** — navigation, modals, tooltips, overlays
-- [ ] **Scroll behavior** — infinite scroll, pagination, virtual scrolling
-
-## Phase 4: Technical Stack Analysis
-
-- [ ] **Framework** — React? Vue? Angular? Check `__NEXT_DATA__`, `__NUXT__`, `ng-version`
-- [ ] **CSS approach** — Tailwind (utility classes), CSS Modules, Styled Components, Emotion, vanilla CSS
-- [ ] **State management** — Redux (check DevTools), React Query, Zustand, Pinia
-- [ ] **API patterns** — REST, GraphQL (check network tab for `/graphql` requests)
-- [ ] **Font loading** — Google Fonts, self-hosted, system fonts
-- [ ] **Image strategy** — CDN, lazy loading, srcset, WebP/AVIF
-- [ ] **Animation library** — Framer Motion, GSAP, CSS transitions only
-
-## Phase 5: Documentation Output
-
-After inspection, create these files in `docs/research/`:
-1. `DESIGN_TOKENS.md` — All extracted colors, typography, spacing
-2. `COMPONENT_INVENTORY.md` — Every component with structure notes
-3. `LAYOUT_ARCHITECTURE.md` — Page layouts, grid system, responsive behavior
-4. `INTERACTION_PATTERNS.md` — Animations, transitions, hover states
-5. `TECH_STACK_ANALYSIS.md` — What the site uses and our chosen equivalents
+5. **Responsive behavior** — changes per breakpoint
+6. **Interactions** — click, hover, focus, keyboard
+
+**Layout architecture**
+
+- [ ] **Grid vs flex** — primary layout mechanism
+- [ ] **Columns** — count per breakpoint
+- [ ] **Max-width** — content well width
+- [ ] **Sticky / fixed** — header, sidebars, floating CTAs
+- [ ] **Z-index layers** — nav, overlays, tooltips
+- [ ] **Scroll model** — normal, infinite, virtual lists, snap
+
+**Screenshots** (tie each shot to a section in the hierarchy)
+
+- [ ] Every distinct page — desktop, tablet, mobile
+- [ ] Theme variants (light / dark if applicable)
+- [ ] Hover, active, menus open, modals
+- [ ] Loading / skeleton / empty / error states
+
+---
+
+## Step 2 — Styles (computed appearance + real CSS)
+
+Rendered look comes from **CSS** (linked files, injected `<style>` blocks, build output)—not from raw element copy alone.
+
+- **Per-element:** In DevTools **Styles** / **Computed**, capture what matters for fidelity: typography, spacing, colors, borders, shadows, breakpoints where rules change.
+- **Global:** From **Sources** or **Network**, identify main stylesheets / CSS chunks; note filenames or URLs for the agents or scripts that will mirror tokens.
+- **Design tokens to extract**
+
+  - [ ] **Colors** — background, text (primary / secondary / muted), accent, border, hover / focus, semantic (error, success, warning)
+  - [ ] **Typography** — families, scale (h1–h6, body, captions), weights, line-height, letter-spacing
+  - [ ] **Spacing** — padding/margin rhythm (e.g. 4/8/12/16…)
+  - [ ] **Radius & elevation** — cards, buttons, inputs, overlays
+  - [ ] **Breakpoints** — layout shifts (responsive mode)
+  - [ ] **Icons & avatars** — sizes, masks, fallbacks
+
+**Technical CSS context** (informs Tailwind mapping)
+
+- [ ] **CSS approach** — utilities vs modules vs styled components vs vanilla
+- [ ] **Fonts** — Google, self-hosted, system stacks
+- [ ] **Image CSS** — `object-fit`, `aspect-ratio`, background layers
+
+---
+
+## Step 3 — Motion (what moves and how)
+
+Motion is rarely recoverable from HTML copy; it lives in **CSS animations/transitions** and often **JavaScript** (scroll, gestures, carousel timing).
+
+- **Catalog behaviors:** Entrance, hover, focus, drag, scroll-linked, carousel stagger, modal open/close, page transitions.
+- **From Styles / Sources:** `animation-*`, `@keyframes`, `transition`, `transform`, `will-change`; note **duration, easing, delay, fill-mode**.
+- **Libraries:** Identify Framer Motion, GSAP, Lottie, Lenis, CSS-only, etc.
+- **Accessibility:** Note `prefers-reduced-motion` behavior if present.
+
+**Priority reminder:** Capture **motion early** alongside media—perceived polish depends on it; do not leave it until the end.
+
+---
+
+## Step 4 — Assets (permission-neutral bytes + originals where required)
+
+**Early capture**
+
+1. **Raster imagery** — `<img>`, `<picture>` / `<source>`, `srcset` / `sizes`, CDN URLs, lazy `data-src`, `loading="lazy"`, **`background-image`** on elements and ancestors (including `::before` / `::after`), masks using `url()`, video posters / stills.
+2. **SVGs** — Inline `<svg>`, `<use>` / sprites, **SVG in CSS** (`mask-image`, backgrounds), favicons. Prefer extracting path/viewBox into React components or files under `public/` — recreate from screenshot/trace only when markup is blocked or obfuscated.
+3. **Brand-safe slots** — **Marketing photos and illustrative hero/feature art** must not be photocopied when policy requires originality: ship **committed** files under `public/images/` (etc.), generated for **your** product idea; document paths in `docs/research/LAUNCHFRAME.md`. Blank placeholders are unfinished.
+4. **Fallbacks** — If URLs are gated, export a crisp screenshot of the element’s box (note DPR) and record the substitution in research notes.
+
+**Technical**
+
+- [ ] CDN vs origin paths
+- [ ] Lazy loading and responsive image strategy
+
+---
+
+## Step 5 — Implementation (Next.js + components)
+
+Rebuild deliberately in **this template’s stack** (Next.js App Router, React, TypeScript strict, shadcn/ui, Tailwind v4).
+
+- **Do:** Small composable components, shared tokens, `cn()`, extracted icons in `src/components/icons.tsx` (or adjacent), routes under `src/app/`.
+- **Don’t:** Ship one monolithic HTML string as the app or skip TypeScript/component boundaries.
+
+### Stack parity (helps choose libraries)
+
+- [ ] **Framework signals** — e.g. `__NEXT_DATA__`, `__NUXT__`, `ng-version`
+- [ ] **State / data** — REST, GraphQL, client stores (infer from Network)
+- [ ] **Animation stack** — match or approximate with CSS or an approved motion library
+
+### Documentation output (`docs/research/`)
+
+After inspection, produce durable notes:
+
+1. `DESIGN_TOKENS.md` — colors, typography, spacing, radius, shadows
+2. `COMPONENT_INVENTORY.md` — components with structure and states
+3. `LAYOUT_ARCHITECTURE.md` — grids, breakpoints, sticky layers
+4. `INTERACTION_PATTERNS.md` — motion, transitions, hover/focus
+5. `TECH_STACK_ANALYSIS.md` — source stack vs chosen equivalents
+
+### Common components to hunt for
+
+Navigation (top/side/bottom), cards, buttons, links, forms, modals, menus, tabs, avatars/badges, skeletons, toasts, tooltips/popovers.
+
+---
+
+## Reference: Chrome MCP / agent crawl habits
+
+Walk the DOM and network **top-down**. When multiple agents collaborate, reconcile tokens and animation specs in shared research files so Step 5 does not drift. For **`/launchframe`**, tie findings to `launchframe.context.json` and `docs/research/LAUNCHFRAME.md` per project conventions.

package/.codex/skills/launchframe/SKILL.md

@@ -24,6 +24,22 @@ Before reconnaissance, write or update:
 - `docs/research/LAUNCHFRAME.md` — URLs and SaaS idea
 - **`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.
 
+### 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 `document.html`, network `*.css` bodies, `inline-styles.json`, and `motion-summary.json` — a frozen DOM/CSS/motion bundle to attach or diff alongside live `getComputedStyle` / WAAPI work (**this 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`):
+
+```bash
+npm run inspect:page -- "https://www.example.com/" --scroll-full --wait-until networkidle --timeout 120000 --out-parent "docs/research/www.example.com/page-inspection"
+```
+
+That creates `docs/research/<hostname>/page-inspection/<hostname>-<iso-stamp>/` with all artifacts. Omit `--out-parent` to use the default `docs/research/page-captures/<host>-<stamp>/`.
+3. Append an **`Automated captures`** subsection to `docs/research/LAUNCHFRAME.md` listing every URL and its output directory path. Use those files in Phase 1 when structuring specs (DOM outline, stylesheet text, `@keyframes` from `motion-summary.json`) while still measuring behavior in the live tab.
+
+If the dump fails (missing browsers, navigation timeout, TLS, bot wall), increase `--timeout`, retry with `domcontentloaded` only when necessary, or document the failure in `LAUNCHFRAME.md` and unblock before treating Phase 1 as complete.
+
 ## SaaS copy overlay (Phase 4 assembly and final polish)
 
 After structure and styles match the reference, apply the **SaaS idea** to hero, headings, and primary CTAs where the reference uses interchangeable marketing copy, **without** changing layout grids, spacing, or **motion numbers** from extracted specs. **Icon shapes** and **animations** (`@keyframes`, transitions, staggers, scroll triggers) remain **parity goals** sourced from extraction — swapping narrative photos does **not** relax them. **Brand identity** (below) must be **original** for anything you ship as the user’s product — never pass off the reference company’s trademarks or distinctive marks.

package/.continue/commands/launchframe.md

@@ -25,6 +25,22 @@ Before reconnaissance, write or update:
 - `docs/research/LAUNCHFRAME.md` — URLs and SaaS idea
 - **`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.
 
+### 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 `document.html`, network `*.css` bodies, `inline-styles.json`, and `motion-summary.json` — a frozen DOM/CSS/motion bundle to attach or diff alongside live `getComputedStyle` / WAAPI work (**this 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`):
+
+```bash
+npm run inspect:page -- "https://www.example.com/" --scroll-full --wait-until networkidle --timeout 120000 --out-parent "docs/research/www.example.com/page-inspection"
+```
+
+That creates `docs/research/<hostname>/page-inspection/<hostname>-<iso-stamp>/` with all artifacts. Omit `--out-parent` to use the default `docs/research/page-captures/<host>-<stamp>/`.
+3. Append an **`Automated captures`** subsection to `docs/research/LAUNCHFRAME.md` listing every URL and its output directory path. Use those files in Phase 1 when structuring specs (DOM outline, stylesheet text, `@keyframes` from `motion-summary.json`) while still measuring behavior in the live tab.
+
+If the dump fails (missing browsers, navigation timeout, TLS, bot wall), increase `--timeout`, retry with `domcontentloaded` only when necessary, or document the failure in `LAUNCHFRAME.md` and unblock before treating Phase 1 as complete.
+
 ## SaaS copy overlay (Phase 4 assembly and final polish)
 
 After structure and styles match the reference, apply the **SaaS idea** to hero, headings, and primary CTAs where the reference uses interchangeable marketing copy, **without** changing layout grids, spacing, or **motion numbers** from extracted specs. **Icon shapes** and **animations** (`@keyframes`, transitions, staggers, scroll triggers) remain **parity goals** sourced from extraction — swapping narrative photos does **not** relax them. **Brand identity** (below) must be **original** for anything you ship as the user’s product — never pass off the reference company’s trademarks or distinctive marks.

package/.continue/rules/project.md

@@ -14,7 +14,7 @@ This version has breaking changes — APIs, conventions, and file structure may
 # Website Reverse-Engineer Template
 
 ## What This Is
-A reusable template for reverse-engineering any website into a clean, modern Next.js codebase using AI coding agents. The Next.js + shadcn/ui + Tailwind v4 base is pre-scaffolded — use **`/launchframe <url> "saas idea"`** for the full pixel-perfect clone plus SaaS landing copy (`src/lib/launchframe-config.ts`, `launchframe.context.json`, `docs/research/LAUNCHFRAME.md`). For a **new empty folder** only, **`npx launchframe@latest`** unpacks this template; then run **`/launchframe`** in that project with your URL and pitch.
+A reusable template for reverse-engineering any website into a clean, modern Next.js codebase using AI coding agents. The Next.js + shadcn/ui + Tailwind v4 base is pre-scaffolded — use **`/launchframe <url> "saas idea"`** for the full pixel-perfect clone plus SaaS landing copy (`src/lib/launchframe-config.ts`, `launchframe.context.json`, `docs/research/LAUNCHFRAME.md`). The agent executing **`/launchframe`** must follow **Step 0a** in that command: run **`npm run inspect:page`** once per reference URL (Playwright: `document.html`, network CSS, `motion-summary.json`) before Phase 1. For a **new empty folder** only, **`npx launchframe@latest`** unpacks this template; then run **`/launchframe`** in that project with your URL and pitch.
 
 ## Tech Stack
 - **Framework:** Next.js 16 (App Router, React 19, TypeScript strict)
@@ -42,7 +42,7 @@ A reusable template for reverse-engineering any website into a clean, modern Nex
 - **No personal aesthetic changes during emulation phase** — match 1:1 first, customize later
 - **Real content** — use actual text and assets from the target site where they are interchangeable chrome; **`/launchframe`** overlays your SaaS pitch on headings and CTAs. **Marketing photographs and illustrative hero/feature imagery are not photocopied**: you **must** ship **committed files** under `public/images/` (etc.) for every such slot — **generate them yourself** with your host **image-generation** tool (prompts tied to the SaaS idea), wire into components, supplement with UI mock composites only if helpful. Blank placeholders count as unfinished. Record paths in `docs/research/LAUNCHFRAME.md`
 - **Beauty-first** — every pixel matters
-- **DOM crawl priority** — when walking the target page, emphasize **images** (raster, responsive sources, CSS backgrounds), **SVGs** (inline icons, sprites, masks — **copy extracted geometry**, do not approximate with unrelated Lucide glyphs), then **motion** (**copy** `@keyframes`, `transition`/`animation` timings, scroll triggers, carousel staggers via Chrome MCP / CSS sources). **Measure and mirror** mounting and styling from the DOM; scrape **permission-neutral** bytes when appropriate. When a raster slot must be original for brand safety, **author** replacements and label them in research notes — **that never waives SVG or animation fidelity**
+- **Inspection workflow (canonical)** — Follow the ordered **five steps** in `docs/research/INSPECTION_GUIDE.md`: (1) **Structure** — DOM as hierarchy reference, not pasted production HTML; (2) **Styles** — Computed/stylesheets and tokens; (3) **Motion** — `@keyframes`, transitions, timings, triggers; (4) **Assets** — rasters/SVGs with brand-safe originals for marketing slots when required; (5) **Implementation** — Next.js components rebuild. Within crawls (Chrome MCP / DevTools), still emphasize **images** (raster, responsive sources, CSS backgrounds), **SVGs** (inline, sprites, masks — **exact geometry**, not unrelated Lucide stand-ins), then **motion fidelity**. **Measure and mirror** from the DOM; scrape **permission-neutral** bytes when appropriate — **SVG and animation fidelity are not waived** when rasters are replaced
 
 ## Project Structure
 ```
@@ -75,89 +75,128 @@ scripts/            # Asset download scripts
 
 ## How to Reverse-Engineer Any Website
 
-This guide outlines what to capture when inspecting a target website via Chrome MCP or browser DevTools.
+This guide is the **canonical workflow** when inspecting a target site (Chrome MCP, DevTools, or similar). Execute the steps **in order**: structure and styles establish the blueprint; motion and assets define feel and legality; implementation is always a deliberate rebuild—not a pasted dump.
 
-## Priority: media, SVGs, and motion (do this early)
+---
 
-When crawling the DOM and network, **tackle these before fine-tuning copy or spacing**:
+## Step 1 — Structure (DOM hierarchy only)
 
-1. **Raster imagery** — Every `<img>`, `<picture>` / `source`, `srcset` / `sizes`, CDN URLs, lazy-loaded `data-src`, `loading="lazy"` nodes, **CSS `background-image`** on the element and ancestors (including `::before` / `::after`), masks that use `url()`, `<video>` still / poster frames. Prefer **downloading** originals via scripts or MCP; if a URL is blocked or session-gated, **export a screenshot** of the element’s bounding box at a crisp DPR and store it under `public/images/`, and note the substitute in the spec.
-2. **SVGs** — Inline `<svg>`, `<use>` / sprite sheets, **SVG in CSS** (`mask-image`, `background-image`), favicons as SVG, logo marks. Prefer extracting path/viewBox into React components or static files under `public/` — **recreate** from a screenshot/trace only when the markup is obfuscated or blocked.
-3. **Motion & animation** — Inspect Styles for `animation`, `animation-name`, `animation-timeline`, `transition`, `transform`, `@keyframes`; check for libraries (Framer Motion, GSAP, Lottie, Lenis). Capture **durations, easings, delays, fill-modes**, scroll/view triggers, and `prefers-reduced-motion` handling. Motion often defines perceived quality — do not leave it as an afterthought.
+Treat HTML as a **map of hierarchy**, not as shippable source code.
 
-Then continue with typography, spacing, and component structure as usual.
+- **DevTools limitation:** Copying `<head>` and `<body>` with “Copy ▸ Copy outerHTML” gives **one frozen snapshot**. It omits most **stylesheet and script** behavior and may inline classes whose meaning lives in external bundles.
+- **What to extract anyway:** Landmark regions, heading levels, nesting (sections → rows → cards), repeated patterns, form fields, navigation trees, semantic roles.
+- **What not to do:** Do not paste a single giant HTML file into production or assume it reproduces routing, hydration, or data fetching.
 
-## Phase 1: Visual Audit
+### Component & layout checklist (supports Step 1)
+
+**Component inventory** — For each distinct UI block, capture:
 
-### Screenshots to Capture
-- [ ] Every distinct page — desktop, tablet, mobile
-- [ ] Dark mode variants (if applicable)
-- [ ] Light mode variants (if applicable)
-- [ ] Key interaction states (hover, active, open menus, modals)
-- [ ] Loading/skeleton states
-- [ ] Empty states
-- [ ] Error states
-
-### Design Tokens to Extract
-- [ ] **Colors** — background, text (primary/secondary/muted), accent, border, hover, error, success, warning
-- [ ] **Typography** — font family, sizes (h1-h6, body, caption, label), weights, line heights, letter spacing
-- [ ] **Spacing** — padding/margin patterns (look for a scale: 4px, 8px, 12px, 16px, 24px, 32px, etc.)
-- [ ] **Border radius** — buttons, cards, avatars, inputs
-- [ ] **Shadows/elevation** — card shadows, dropdown shadows, modal overlay
-- [ ] **Breakpoints** — when does the layout shift? (inspect with DevTools responsive mode)
-- [ ] **Icons** — which icon library? custom SVGs? sizes?
-- [ ] **Avatars** — sizes, shapes, fallback behavior
-- [ ] **Buttons** — all variants (primary, secondary, ghost, icon-only, danger)
-- [ ] **Inputs** — text fields, textareas, selects, checkboxes, toggles
-
-## Phase 2: Component Inventory
-
-For each distinct UI component, document:
 1. **Name** — what would you call this component?
-2. **Structure** — what HTML elements / child components does it contain?
-3. **Variants** — does it have different sizes, colors, or states?
+2. **Structure** — HTML elements / child components and order
+3. **Variants** — sizes, tones, densities
 4. **States** — default, hover, active, disabled, loading, error, empty
-5. **Responsive behavior** — how does it change at different breakpoints?
-6. **Interactions** — click, hover, focus, keyboard navigation
-7. **Animations** — transitions, entrance/exit animations, micro-interactions
-
-### Common Components to Look For
-- Navigation (top bar, sidebar, bottom bar)
-- Cards / list items
-- Buttons and links
-- Forms and inputs
-- Modals and dialogs
-- Dropdowns and menus
-- Tabs and segmented controls
-- Avatars and user badges
-- Loading skeletons
-- Toast notifications
-- Tooltips and popovers
-
-## Phase 3: Layout Architecture
-
-- [ ] **Grid system** — CSS Grid? Flexbox? Fixed widths?
-- [ ] **Column layout** — how many columns at each breakpoint?
-- [ ] **Max-width** — main content area max-width
-- [ ] **Sticky elements** — header, sidebar, floating buttons
-- [ ] **Z-index layers** — navigation, modals, tooltips, overlays
-- [ ] **Scroll behavior** — infinite scroll, pagination, virtual scrolling
-
-## Phase 4: Technical Stack Analysis
-
-- [ ] **Framework** — React? Vue? Angular? Check `__NEXT_DATA__`, `__NUXT__`, `ng-version`
-- [ ] **CSS approach** — Tailwind (utility classes), CSS Modules, Styled Components, Emotion, vanilla CSS
-- [ ] **State management** — Redux (check DevTools), React Query, Zustand, Pinia
-- [ ] **API patterns** — REST, GraphQL (check network tab for `/graphql` requests)
-- [ ] **Font loading** — Google Fonts, self-hosted, system fonts
-- [ ] **Image strategy** — CDN, lazy loading, srcset, WebP/AVIF
-- [ ] **Animation library** — Framer Motion, GSAP, CSS transitions only
-
-## Phase 5: Documentation Output
-
-After inspection, create these files in `docs/research/`:
-1. `DESIGN_TOKENS.md` — All extracted colors, typography, spacing
-2. `COMPONENT_INVENTORY.md` — Every component with structure notes
-3. `LAYOUT_ARCHITECTURE.md` — Page layouts, grid system, responsive behavior
-4. `INTERACTION_PATTERNS.md` — Animations, transitions, hover states
-5. `TECH_STACK_ANALYSIS.md` — What the site uses and our chosen equivalents
+5. **Responsive behavior** — changes per breakpoint
+6. **Interactions** — click, hover, focus, keyboard
+
+**Layout architecture**
+
+- [ ] **Grid vs flex** — primary layout mechanism
+- [ ] **Columns** — count per breakpoint
+- [ ] **Max-width** — content well width
+- [ ] **Sticky / fixed** — header, sidebars, floating CTAs
+- [ ] **Z-index layers** — nav, overlays, tooltips
+- [ ] **Scroll model** — normal, infinite, virtual lists, snap
+
+**Screenshots** (tie each shot to a section in the hierarchy)
+
+- [ ] Every distinct page — desktop, tablet, mobile
+- [ ] Theme variants (light / dark if applicable)
+- [ ] Hover, active, menus open, modals
+- [ ] Loading / skeleton / empty / error states
+
+---
+
+## Step 2 — Styles (computed appearance + real CSS)
+
+Rendered look comes from **CSS** (linked files, injected `<style>` blocks, build output)—not from raw element copy alone.
+
+- **Per-element:** In DevTools **Styles** / **Computed**, capture what matters for fidelity: typography, spacing, colors, borders, shadows, breakpoints where rules change.
+- **Global:** From **Sources** or **Network**, identify main stylesheets / CSS chunks; note filenames or URLs for the agents or scripts that will mirror tokens.
+- **Design tokens to extract**
+
+  - [ ] **Colors** — background, text (primary / secondary / muted), accent, border, hover / focus, semantic (error, success, warning)
+  - [ ] **Typography** — families, scale (h1–h6, body, captions), weights, line-height, letter-spacing
+  - [ ] **Spacing** — padding/margin rhythm (e.g. 4/8/12/16…)
+  - [ ] **Radius & elevation** — cards, buttons, inputs, overlays
+  - [ ] **Breakpoints** — layout shifts (responsive mode)
+  - [ ] **Icons & avatars** — sizes, masks, fallbacks
+
+**Technical CSS context** (informs Tailwind mapping)
+
+- [ ] **CSS approach** — utilities vs modules vs styled components vs vanilla
+- [ ] **Fonts** — Google, self-hosted, system stacks
+- [ ] **Image CSS** — `object-fit`, `aspect-ratio`, background layers
+
+---
+
+## Step 3 — Motion (what moves and how)
+
+Motion is rarely recoverable from HTML copy; it lives in **CSS animations/transitions** and often **JavaScript** (scroll, gestures, carousel timing).
+
+- **Catalog behaviors:** Entrance, hover, focus, drag, scroll-linked, carousel stagger, modal open/close, page transitions.
+- **From Styles / Sources:** `animation-*`, `@keyframes`, `transition`, `transform`, `will-change`; note **duration, easing, delay, fill-mode**.
+- **Libraries:** Identify Framer Motion, GSAP, Lottie, Lenis, CSS-only, etc.
+- **Accessibility:** Note `prefers-reduced-motion` behavior if present.
+
+**Priority reminder:** Capture **motion early** alongside media—perceived polish depends on it; do not leave it until the end.
+
+---
+
+## Step 4 — Assets (permission-neutral bytes + originals where required)
+
+**Early capture**
+
+1. **Raster imagery** — `<img>`, `<picture>` / `<source>`, `srcset` / `sizes`, CDN URLs, lazy `data-src`, `loading="lazy"`, **`background-image`** on elements and ancestors (including `::before` / `::after`), masks using `url()`, video posters / stills.
+2. **SVGs** — Inline `<svg>`, `<use>` / sprites, **SVG in CSS** (`mask-image`, backgrounds), favicons. Prefer extracting path/viewBox into React components or files under `public/` — recreate from screenshot/trace only when markup is blocked or obfuscated.
+3. **Brand-safe slots** — **Marketing photos and illustrative hero/feature art** must not be photocopied when policy requires originality: ship **committed** files under `public/images/` (etc.), generated for **your** product idea; document paths in `docs/research/LAUNCHFRAME.md`. Blank placeholders are unfinished.
+4. **Fallbacks** — If URLs are gated, export a crisp screenshot of the element’s box (note DPR) and record the substitution in research notes.
+
+**Technical**
+
+- [ ] CDN vs origin paths
+- [ ] Lazy loading and responsive image strategy
+
+---
+
+## Step 5 — Implementation (Next.js + components)
+
+Rebuild deliberately in **this template’s stack** (Next.js App Router, React, TypeScript strict, shadcn/ui, Tailwind v4).
+
+- **Do:** Small composable components, shared tokens, `cn()`, extracted icons in `src/components/icons.tsx` (or adjacent), routes under `src/app/`.
+- **Don’t:** Ship one monolithic HTML string as the app or skip TypeScript/component boundaries.
+
+### Stack parity (helps choose libraries)
+
+- [ ] **Framework signals** — e.g. `__NEXT_DATA__`, `__NUXT__`, `ng-version`
+- [ ] **State / data** — REST, GraphQL, client stores (infer from Network)
+- [ ] **Animation stack** — match or approximate with CSS or an approved motion library
+
+### Documentation output (`docs/research/`)
+
+After inspection, produce durable notes:
+
+1. `DESIGN_TOKENS.md` — colors, typography, spacing, radius, shadows
+2. `COMPONENT_INVENTORY.md` — components with structure and states
+3. `LAYOUT_ARCHITECTURE.md` — grids, breakpoints, sticky layers
+4. `INTERACTION_PATTERNS.md` — motion, transitions, hover/focus
+5. `TECH_STACK_ANALYSIS.md` — source stack vs chosen equivalents
+
+### Common components to hunt for
+
+Navigation (top/side/bottom), cards, buttons, links, forms, modals, menus, tabs, avatars/badges, skeletons, toasts, tooltips/popovers.
+
+---
+
+## Reference: Chrome MCP / agent crawl habits
+
+Walk the DOM and network **top-down**. When multiple agents collaborate, reconcile tokens and animation specs in shared research files so Step 5 does not drift. For **`/launchframe`**, tie findings to `launchframe.context.json` and `docs/research/LAUNCHFRAME.md` per project conventions.

package/.cursor/commands/launchframe.md

@@ -20,6 +20,22 @@ Before reconnaissance, write or update:
 - `docs/research/LAUNCHFRAME.md` — URLs and SaaS idea
 - **`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.
 
+### 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 `document.html`, network `*.css` bodies, `inline-styles.json`, and `motion-summary.json` — a frozen DOM/CSS/motion bundle to attach or diff alongside live `getComputedStyle` / WAAPI work (**this 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`):
+
+```bash
+npm run inspect:page -- "https://www.example.com/" --scroll-full --wait-until networkidle --timeout 120000 --out-parent "docs/research/www.example.com/page-inspection"
+```
+
+That creates `docs/research/<hostname>/page-inspection/<hostname>-<iso-stamp>/` with all artifacts. Omit `--out-parent` to use the default `docs/research/page-captures/<host>-<stamp>/`.
+3. Append an **`Automated captures`** subsection to `docs/research/LAUNCHFRAME.md` listing every URL and its output directory path. Use those files in Phase 1 when structuring specs (DOM outline, stylesheet text, `@keyframes` from `motion-summary.json`) while still measuring behavior in the live tab.
+
+If the dump fails (missing browsers, navigation timeout, TLS, bot wall), increase `--timeout`, retry with `domcontentloaded` only when necessary, or document the failure in `LAUNCHFRAME.md` and unblock before treating Phase 1 as complete.
+
 ## SaaS copy overlay (Phase 4 assembly and final polish)
 
 After structure and styles match the reference, apply the **SaaS idea** to hero, headings, and primary CTAs where the reference uses interchangeable marketing copy, **without** changing layout grids, spacing, or **motion numbers** from extracted specs. **Icon shapes** and **animations** (`@keyframes`, transitions, staggers, scroll triggers) remain **parity goals** sourced from extraction — swapping narrative photos does **not** relax them. **Brand identity** (below) must be **original** for anything you ship as the user’s product — never pass off the reference company’s trademarks or distinctive marks.

package/.gemini/commands/launchframe.toml

@@ -24,6 +24,22 @@ Before reconnaissance, write or update:
 - `docs/research/LAUNCHFRAME.md` — URLs and SaaS idea
 - **`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.
 
+### 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 `document.html`, network `*.css` bodies, `inline-styles.json`, and `motion-summary.json` — a frozen DOM/CSS/motion bundle to attach or diff alongside live `getComputedStyle` / WAAPI work (**this 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`):
+
+```bash
+npm run inspect:page -- "https://www.example.com/" --scroll-full --wait-until networkidle --timeout 120000 --out-parent "docs/research/www.example.com/page-inspection"
+```
+
+That creates `docs/research/<hostname>/page-inspection/<hostname>-<iso-stamp>/` with all artifacts. Omit `--out-parent` to use the default `docs/research/page-captures/<host>-<stamp>/`.
+3. Append an **`Automated captures`** subsection to `docs/research/LAUNCHFRAME.md` listing every URL and its output directory path. Use those files in Phase 1 when structuring specs (DOM outline, stylesheet text, `@keyframes` from `motion-summary.json`) while still measuring behavior in the live tab.
+
+If the dump fails (missing browsers, navigation timeout, TLS, bot wall), increase `--timeout`, retry with `domcontentloaded` only when necessary, or document the failure in `LAUNCHFRAME.md` and unblock before treating Phase 1 as complete.
+
 ## SaaS copy overlay (Phase 4 assembly and final polish)
 
 After structure and styles match the reference, apply the **SaaS idea** to hero, headings, and primary CTAs where the reference uses interchangeable marketing copy, **without** changing layout grids, spacing, or **motion numbers** from extracted specs. **Icon shapes** and **animations** (`@keyframes`, transitions, staggers, scroll triggers) remain **parity goals** sourced from extraction — swapping narrative photos does **not** relax them. **Brand identity** (below) must be **original** for anything you ship as the user’s product — never pass off the reference company’s trademarks or distinctive marks.