launchframe 0.4.9 → 0.4.10

package/.amazonq/rules/project.md

@@ -1,7 +1,5 @@
-<!-- AUTO-GENERATED from AGENTS.md — do not edit directly.
-     Run `bash scripts/sync-agent-rules.sh` to regenerate. -->
-
-<!-- BEGIN:nextjs-agent-rules -->
+<!-- AUTO-GENERATED from AGENTS.md \u2014 do not edit directly.
+     Run \ash scripts/sync-agent-rules.sh\ to regenerate. -->\n\n<!-- BEGIN:nextjs-agent-rules -->
 # This is NOT the Next.js you know
 
 This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
@@ -38,7 +36,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 +69,131 @@ 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.
+
+
+\n

package/.clinerules

@@ -1,7 +1,5 @@
-<!-- AUTO-GENERATED from AGENTS.md — do not edit directly.
-     Run `bash scripts/sync-agent-rules.sh` to regenerate. -->
-
-<!-- BEGIN:nextjs-agent-rules -->
+<!-- AUTO-GENERATED from AGENTS.md \u2014 do not edit directly.
+     Run \ash scripts/sync-agent-rules.sh\ to regenerate. -->\n\n<!-- BEGIN:nextjs-agent-rules -->
 # This is NOT the Next.js you know
 
 This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
@@ -38,7 +36,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 +69,131 @@ 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.
+
+
+\n