npm - launchframe - Versions diffs - 0.4.9 → 0.4.11 - Mend

launchframe 0.4.9 → 0.4.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (35) hide show

package/docs/research/INSPECTION_GUIDE.md CHANGED Viewed

@@ -2,89 +2,128 @@
 ## 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/docs/research/example.com/page-inspection/example.com-2026-05-15T21-24-43-488Z/README.txt ADDED Viewed

@@ -0,0 +1,16 @@
+LaunchFrame page inspection capture
+====================================
+Source: https://example.com/
+Files:
+  document.html      — Full <html> outerHTML after JS (attach this for an agent)
+  body-outer.html    — <body> outerHTML only (smaller)
+  inline-styles.json — All inline <style> tag contents
+  motion-summary.json— @keyframes + animation/transition-related lines
+  capture-meta.json  — Viewport, stylesheet URLs, <script> inventory
+  *.css              — Stylesheets observed on the network (unless --no-css-files)
+Notes:
+  • Some sites lazy-load CSS; use --scroll-full to force more requests.
+  • Cross-origin styles you cannot access via JS are still captured here if the browser downloaded them.
+  • Motion inside bundled JS (not CSS) is not fully extracted—check script src in capture-meta.json.

package/docs/research/example.com/page-inspection/example.com-2026-05-15T21-24-43-488Z/body-outer.html ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ <body><div><h1>Example Domain</h1><p>This domain is for use in documentation examples without needing permission. Avoid use in operations.</p><p><a href="https://iana.org/domains/example">Learn more</a></p></div>
2	+ </body>

package/docs/research/example.com/page-inspection/example.com-2026-05-15T21-24-43-488Z/capture-meta.json ADDED Viewed

@@ -0,0 +1,19 @@
+{
+  "sourceUrl": "https://example.com/",
+  "generatedAt": "2026-05-15T21:24:44.058Z",
+  "viewport": {
+    "width": 1440,
+    "height": 900
+  },
+  "waitUntil": "domcontentloaded",
+  "options": {
+    "scrollFull": false,
+    "wroteCssFiles": true
+  },
+  "outputs": {
+    "documentHtmlBytes": 513,
+    "bodyOuterHtmlBytes": 220,
+    "networkStylesheets": []
+  },
+  "scripts": []
+}

package/docs/research/example.com/page-inspection/example.com-2026-05-15T21-24-43-488Z/document.html ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ <html lang="en"><head><title>Example Domain</title><meta name="viewport" content="width=device-width, initial-scale=1"><style>body{background:#eee;width:60vw;margin:15vh auto;font-family:system-ui,sans-serif}h1{font-size:1.5em}div{opacity:0.8}a:link,a:visited{color:#348}</style></head><body><div><h1>Example Domain</h1><p>This domain is for use in documentation examples without needing permission. Avoid use in operations.</p><p><a href="https://iana.org/domains/example">Learn more</a></p></div>
2	+ </body></html>

package/docs/research/example.com/page-inspection/example.com-2026-05-15T21-24-43-488Z/inline-styles.json ADDED Viewed

@@ -0,0 +1,7 @@
+[
+  {
+    "index": 0,
+    "media": "",
+    "text": "body{background:#eee;width:60vw;margin:15vh auto;font-family:system-ui,sans-serif}h1{font-size:1.5em}div{opacity:0.8}a:link,a:visited{color:#348}"
+  }
+]

package/docs/research/example.com/page-inspection/example.com-2026-05-15T21-24-43-488Z/motion-summary.json ADDED Viewed

@@ -0,0 +1,18 @@
+{
+  "sourceUrl": "https://example.com/",
+  "generatedAt": "2026-05-15T21:24:44.057Z",
+  "viewport": {
+    "width": 1440,
+    "height": 900
+  },
+  "counts": {
+    "keyframeRules": 0,
+    "motionRelatedLines": 0,
+    "inlineStyleTags": 1,
+    "networkStylesheets": 0,
+    "scriptElements": 0
+  },
+  "keyframes": [],
+  "motionLinesSample": [],
+  "motionLinesTotal": 0
+}

package/docs/research/page-captures/example.com-2026-05-15T21-21-31-863Z/README.txt ADDED Viewed

@@ -0,0 +1,16 @@
+LaunchFrame page inspection capture
+====================================
+Source: https://example.com/
+Files:
+  document.html      — Full <html> outerHTML after JS (attach this for an agent)
+  body-outer.html    — <body> outerHTML only (smaller)
+  inline-styles.json — All inline <style> tag contents
+  motion-summary.json— @keyframes + animation/transition-related lines
+  capture-meta.json  — Viewport, stylesheet URLs, <script> inventory
+  *.css              — Stylesheets observed on the network (unless --no-css-files)
+Notes:
+  • Some sites lazy-load CSS; use --scroll-full to force more requests.
+  • Cross-origin styles you cannot access via JS are still captured here if the browser downloaded them.
+  • Motion inside bundled JS (not CSS) is not fully extracted—check script src in capture-meta.json.

package/docs/research/page-captures/example.com-2026-05-15T21-21-31-863Z/body-outer.html ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ <body><div><h1>Example Domain</h1><p>This domain is for use in documentation examples without needing permission. Avoid use in operations.</p><p><a href="https://iana.org/domains/example">Learn more</a></p></div>
2	+ </body>

package/docs/research/page-captures/example.com-2026-05-15T21-21-31-863Z/capture-meta.json ADDED Viewed

@@ -0,0 +1,19 @@
+{
+  "sourceUrl": "https://example.com/",
+  "generatedAt": "2026-05-15T21:21:39.771Z",
+  "viewport": {
+    "width": 1440,
+    "height": 900
+  },
+  "waitUntil": "domcontentloaded",
+  "options": {
+    "scrollFull": false,
+    "wroteCssFiles": true
+  },
+  "outputs": {
+    "documentHtmlBytes": 513,
+    "bodyOuterHtmlBytes": 220,
+    "networkStylesheets": []
+  },
+  "scripts": []
+}

package/docs/research/page-captures/example.com-2026-05-15T21-21-31-863Z/document.html ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ <html lang="en"><head><title>Example Domain</title><meta name="viewport" content="width=device-width, initial-scale=1"><style>body{background:#eee;width:60vw;margin:15vh auto;font-family:system-ui,sans-serif}h1{font-size:1.5em}div{opacity:0.8}a:link,a:visited{color:#348}</style></head><body><div><h1>Example Domain</h1><p>This domain is for use in documentation examples without needing permission. Avoid use in operations.</p><p><a href="https://iana.org/domains/example">Learn more</a></p></div>
2	+ </body></html>

package/docs/research/page-captures/example.com-2026-05-15T21-21-31-863Z/inline-styles.json ADDED Viewed

@@ -0,0 +1,7 @@
+[
+  {
+    "index": 0,
+    "media": "",
+    "text": "body{background:#eee;width:60vw;margin:15vh auto;font-family:system-ui,sans-serif}h1{font-size:1.5em}div{opacity:0.8}a:link,a:visited{color:#348}"
+  }
+]

package/docs/research/page-captures/example.com-2026-05-15T21-21-31-863Z/motion-summary.json ADDED Viewed

@@ -0,0 +1,18 @@
+{
+  "sourceUrl": "https://example.com/",
+  "generatedAt": "2026-05-15T21:21:39.770Z",
+  "viewport": {
+    "width": 1440,
+    "height": 900
+  },
+  "counts": {
+    "keyframeRules": 0,
+    "motionRelatedLines": 0,
+    "inlineStyleTags": 1,
+    "networkStylesheets": 0,
+    "scriptElements": 0
+  },
+  "keyframes": [],
+  "motionLinesSample": [],
+  "motionLinesTotal": 0
+}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "launchframe",
-  "version": "0.4.9",
+  "version": "0.4.11",
   "private": false,
   "description": "Scaffold a Next.js app from a reference URL plus your SaaS idea — AI-ready website cloning",
   "author": "JCodesMore",
@@ -72,7 +72,8 @@
     "start": "next start",
     "lint": "eslint",
     "typecheck": "tsc --noEmit",
-    "check": "npm run lint && npm run typecheck && npm run build"
+    "check": "npm run lint && npm run typecheck && npm run build",
+    "inspect:page": "node scripts/page-inspection-dump.mjs"
   },
   "dependencies": {
     "@base-ui/react": "^1.3.0",
@@ -94,6 +95,7 @@
     "eslint": "^9",
     "eslint-config-next": "16.2.1",
     "tailwindcss": "^4",
-    "typescript": "^5"
+    "typescript": "^5",
+    "playwright": "^1.57.0"
   }
 }