launchframe 0.2.3 → 0.2.5

package/template/docs/research/INSPECTION_GUIDE.md

@@ -1,109 +1,121 @@
-# Website Inspection Guide
-
-## Priority (read first): media & motion
-
-Launchframe clones live pages for a **visual** result. Two things most often separate a convincing build from a hollow one:
-
-### 1. Images & video (do this before obsessing over utility classes)
-
-- [ ] **Every `<img>`** — `src` / `srcset` / `currentSrc`, `sizes`, `loading`, `decoding`, `alt`, intrinsic dimensions
-- [ ] **`<picture>` / `<source>`** — resolution switches, art direction, `type` (WebP/AVIF)
-- [ ] **Every `<video>`** — `src` + nested `<source>`, **poster**, `autoplay`, `loop`, `muted`, `playsinline`, `controls`
-- [ ] **Background images** — `background-image` on ancestors (hero stacks are often **layers** of img + gradient + PNG mockup)
-- [ ] **Lazy / below-fold** — scroll the page once before asset discovery so `data-src` / lazy-loaded URLs resolve if the site uses them
-- [ ] **Download** — mirror into `public/images/` and `public/videos/` with stable paths; list failures in `docs/research/EXTRACTION_LIMITATIONS.md`
-
-If automation hits a bot wall, **do not pretend extraction succeeded** — capture what you can from successful fetches and document gaps.
-
-### 2. Motion (prefer Framer Motion in this repo)
-
-- [ ] **Entrance** — fade/slide/scale on mount or on **scroll into view** (note threshold / `margin`)
-- [ ] **Stagger** — children animating in sequence (hero bullets, card grids)
-- [ ] **Scroll-linked** — progress, parallax, pinned sections (may combine with CSS `animation-timeline` or libs)
-- [ ] **Gestures** — drag, pan, hover follow (often Framer Motion)
-- [ ] **Implementation rule** — use **`framer-motion`** for anything beyond trivial single-property CSS `transition`. Record **duration, easing, delay, stagger**, and **trigger** (scroll, hover, tap) in specs.
-
----
-
-## How to Reverse-Engineer Any Website
-
-This guide outlines what to capture when inspecting a target website via Chrome MCP or browser DevTools.
-
-## Phase 1: Visual Audit
-
-### 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
-- [ ] **Video frames** — capture a frame mid-play for reference if motion is subtle
-- [ ] **Hero / full-bleed** — wide crops where raster layers are easy to miss
-
-### 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?
-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, micro-interactions — **`framer-motion` vs CSS** and exact timing
-
-### 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
-- **Video / Lottie / canvas** blocks (do not substitute with static mockups without documenting why)
-
-## 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 — **mirror URLs you are allowed to fetch**
-- [ ] **Animation library** — site may use GSAP, Lottie, Rive, or CSS only — **in the Next.js clone, default to Framer Motion** unless a different lib is required for parity
-
-## 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. **`MEDIA_MANIFEST.md`** — (recommended) Table of every image/video/poster URL → local `public/` path or “blocked”
-4. `LAYOUT_ARCHITECTURE.md` — Page layouts, grid system, responsive behavior
-5. `INTERACTION_PATTERNS.md` — Animations: **CSS vs Framer Motion**, transitions, hover states
-6. `TECH_STACK_ANALYSIS.md` — What the site uses and our chosen equivalents (Framer Motion for React animation)
+# Website Inspection Guide
+
+## Priority (read first): media & motion
+
+Launchframe clones live pages for a **visual** result. Two things most often separate a convincing build from a hollow one:
+
+### 1. Images & video (do this before obsessing over utility classes)
+
+- [ ] **Every `<img>`** — `src` / `srcset` / `currentSrc`, `sizes`, `loading`, `decoding`, `alt`, intrinsic dimensions
+- [ ] **`<picture>` / `<source>`** — resolution switches, art direction, `type` (WebP/AVIF)
+- [ ] **Every `<video>`** — `src` + nested `<source>`, **poster**, `autoplay`, `loop`, `muted`, `playsinline`, `controls`
+- [ ] **Background images** — `background-image` on ancestors (hero stacks are often **layers** of img + gradient + PNG mockup)
+- [ ] **Lazy / below-fold** — scroll the page once before asset discovery so `data-src` / lazy-loaded URLs resolve if the site uses them
+- [ ] **Download** — mirror into `public/images/` and `public/videos/` with stable paths; list failures in `docs/research/EXTRACTION_LIMITATIONS.md`
+
+If automation hits a bot wall, **do not pretend extraction succeeded** — capture what you can from successful fetches and document gaps.
+
+### 2. Motion (prefer Framer Motion in this repo)
+
+- [ ] **Entrance** — fade/slide/scale on mount or on **scroll into view** (note threshold / `margin`)
+- [ ] **Stagger** — children animating in sequence (hero bullets, card grids)
+- [ ] **Scroll-linked** — progress, parallax, pinned sections (may combine with CSS `animation-timeline` or libs)
+- [ ] **Gestures** — drag, pan, hover follow (often Framer Motion)
+- [ ] **Implementation rule** — use **`framer-motion`** for anything beyond trivial single-property CSS `transition`. Record **duration, easing, delay, stagger**, and **trigger** (scroll, hover, tap) in specs.
+
+### 3. Illustration, pixel art & brand motifs *(production landings)*
+
+When the reference page is **sparse** (mostly type + gray boxes) or after a **rebrand** the UI still reads generic, treat illustration as required inventory — not optional garnish.
+
+- [ ] **Inline SVG** — hero shapes, dividers, card mini-scenes; note `viewBox`, whether fills use **`currentColor`**, and which CSS variables apply
+- [ ] **Pixel art / sprite accents** — intentional palette (list hex fills), grid size, scaling strategy (`imageRendering`), animation frames if any
+- [ ] **Motif thread** — recurring stroke/icon creature/grid that should echo across hero, OG sketch, favicon
+- [ ] **Accent tokens** — beyond monochrome: primary/secondary accent roles for SVG strokes, CTAs, focus (extract or **define** in `:root` for authored pages)
+- [ ] **Motion tiers A–E** — page-load stagger, scroll reveals + staggerChildren, looping ambient (marquee/caret), hover lifts, decorative parallax — document each with **reduced-motion** fallback (`prefers-reduced-motion`)
+
+See **`AGENTS.md` → Production polish for marketing landings** for tier definitions and folder conventions (`src/components/marketing/art/`).
+
+---
+
+## How to Reverse-Engineer Any Website
+
+This guide outlines what to capture when inspecting a target website via Chrome MCP or browser DevTools.
+
+## Phase 1: Visual Audit
+
+### 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
+- [ ] **Video frames** — capture a frame mid-play for reference if motion is subtle
+- [ ] **Hero / full-bleed** — wide crops where raster layers are easy to miss
+
+### 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?
+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, micro-interactions — **`framer-motion` vs CSS** and exact timing
+
+### 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
+- **Video / Lottie / canvas** blocks (do not substitute with static mockups without documenting why)
+
+## 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 — **mirror URLs you are allowed to fetch**
+- [ ] **Animation library** — site may use GSAP, Lottie, Rive, or CSS only — **in the Next.js clone, default to Framer Motion** unless a different lib is required for parity
+
+## 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. **`MEDIA_MANIFEST.md`** — (recommended) Table of every image/video/poster URL → local `public/` path or “blocked”
+4. `LAYOUT_ARCHITECTURE.md` — Page layouts, grid system, responsive behavior
+5. `INTERACTION_PATTERNS.md` — Animations: **CSS vs Framer Motion**, transitions, hover states
+6. `TECH_STACK_ANALYSIS.md` — What the site uses and our chosen equivalents (Framer Motion for React animation)

package/template/package.json

@@ -1,60 +1,63 @@
-{
-  "name": "ai-website-clone-template",
-  "version": "0.3.1",
-  "private": true,
-  "description": "Clone any website into a clean, modern Next.js codebase using AI coding agents",
-  "author": "JCodesMore",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/JCodesMore/ai-website-cloner-template.git"
-  },
-  "homepage": "https://github.com/JCodesMore/ai-website-cloner-template",
-  "bugs": {
-    "url": "https://github.com/JCodesMore/ai-website-cloner-template/issues"
-  },
-  "keywords": [
-    "claude-code",
-    "website-clone",
-    "reverse-engineering",
-    "nextjs",
-    "ai",
-    "template",
-    "tailwindcss",
-    "shadcn-ui"
-  ],
-  "engines": {
-    "node": ">=24"
-  },
-  "scripts": {
-    "dev": "next dev",
-    "build": "next build",
-    "start": "next start",
-    "lint": "eslint",
-    "typecheck": "tsc --noEmit",
-    "check": "npm run lint && npm run typecheck && npm run build"
-  },
-  "dependencies": {
-    "@base-ui/react": "^1.3.0",
-    "class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
-    "framer-motion": "^12.4.0",
-    "lucide-react": "^1.6.0",
-    "next": "16.2.1",
-    "react": "19.2.4",
-    "react-dom": "19.2.4",
-    "shadcn": "^4.1.0",
-    "tailwind-merge": "^3.5.0",
-    "tw-animate-css": "^1.4.0"
-  },
-  "devDependencies": {
-    "@tailwindcss/postcss": "^4",
-    "@types/node": "^24",
-    "@types/react": "^19",
-    "@types/react-dom": "^19",
-    "eslint": "^9",
-    "eslint-config-next": "16.2.1",
-    "tailwindcss": "^4",
-    "typescript": "^5"
-  }
-}
+{
+  "name": "ai-website-clone-template",
+  "version": "0.3.1",
+  "private": true,
+  "description": "Clone any website into a clean, modern Next.js codebase using AI coding agents",
+  "author": "JCodesMore",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JCodesMore/ai-website-cloner-template.git"
+  },
+  "homepage": "https://github.com/JCodesMore/ai-website-cloner-template",
+  "bugs": {
+    "url": "https://github.com/JCodesMore/ai-website-cloner-template/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "website-clone",
+    "reverse-engineering",
+    "nextjs",
+    "ai",
+    "template",
+    "tailwindcss",
+    "shadcn-ui"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run lint && npm run typecheck && npm run build",
+    "recon": "node scripts/recon-playwright.mjs",
+    "recon:headed": "node scripts/recon-playwright.mjs --headed"
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.3.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "framer-motion": "^12.4.0",
+    "lucide-react": "^1.6.0",
+    "next": "16.2.1",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "shadcn": "^4.1.0",
+    "tailwind-merge": "^3.5.0",
+    "tw-animate-css": "^1.4.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^24",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "16.2.1",
+    "playwright": "^1.49.1",
+    "tailwindcss": "^4",
+    "typescript": "^5"
+  }
+}