launchframe 0.2.2 → 0.2.4

package/template/docs/research/INSPECTION_GUIDE.md

@@ -1,80 +1,109 @@
-# Website Inspection Guide
-
-## 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
-
-### 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 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
+# 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)

package/template/package.json

@@ -1,59 +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",
-    "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"
+  }
+}

package/template/scripts/recon-playwright.mjs

@@ -0,0 +1,323 @@
+#!/usr/bin/env node
+/**
+ * Playwright recon when Browser / Chrome DevTools MCP is unavailable or broken.
+ *
+ * Reads URL from launchframe.config.json (or --url). Writes:
+ *   - docs/design-references/playwright-<host>-<w>px.png (full page)
+ *   - docs/research/computed-snapshot.json (styles + asset inventory + bot-wall hint)
+ *   - docs/research/MEDIA_MANIFEST.md (table of discovered media URLs)
+ *
+ * Usage:
+ *   npm run recon
+ *   npm run recon:headed
+ *   node scripts/recon-playwright.mjs --url https://example.com --headed
+ *
+ * First time: npx playwright install chromium
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+function parseArgs(argv) {
+  const out = { url: null, headed: false, channel: process.env.PW_CHANNEL || undefined };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--headed" || a === "-H") out.headed = true;
+    else if (a === "--url" || a === "-u") out.url = argv[++i];
+    else if (a.startsWith("--url=")) out.url = a.slice(6);
+    else if (a === "--channel" || a === "-c") out.channel = argv[++i] || undefined;
+  }
+  return out;
+}
+
+function readLaunchframeUrl() {
+  const p = join(ROOT, "launchframe.config.json");
+  if (!existsSync(p)) return null;
+  try {
+    const j = JSON.parse(readFileSync(p, "utf8"));
+    return j.url || null;
+  } catch {
+    return null;
+  }
+}
+
+function safeHost(url) {
+  try {
+    return new URL(url).hostname.replace(/[^a-z0-9.-]+/gi, "_");
+  } catch {
+    return "unknown-host";
+  }
+}
+
+/** Scroll to bottom slowly to trigger lazy-loaded media */
+async function scrollFullPage(page) {
+  await page.evaluate(async () => {
+    const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+    const step = Math.max(1, Math.floor(window.innerHeight * 0.85));
+    let y = 0;
+    const max = document.documentElement.scrollHeight;
+    while (y < max) {
+      y = Math.min(y + step, max);
+      window.scrollTo(0, y);
+      await delay(200);
+    }
+    window.scrollTo(0, 0);
+    await delay(300);
+  });
+}
+
+async function gatherPageData(page) {
+  return page.evaluate(() => {
+    const title = document.title || "";
+    const text = (document.body?.innerText || "").slice(0, 5000);
+    const likelyBotWall =
+      /just a moment/i.test(title) ||
+      /checking your browser/i.test(text) ||
+      /cf-browser-verification/i.test(document.documentElement?.innerHTML || "") ||
+      document.querySelector("#challenge-running, .cf-browser-verification, #cf-challenge-running") !== null;
+
+    const imgs = [...document.querySelectorAll("img")].map((img) => ({
+      src: img.currentSrc || img.src || "",
+      srcset: img.srcset || "",
+      alt: img.alt || "",
+      w: img.naturalWidth,
+      h: img.naturalHeight,
+    }));
+
+    const videos = [...document.querySelectorAll("video")].map((v) => ({
+      src: v.currentSrc || v.src || "",
+      poster: v.poster || "",
+      autoplay: v.autoplay,
+      loop: v.loop,
+      muted: v.muted,
+    }));
+
+    const bgUrls = [];
+    const seen = new Set();
+    for (const el of document.querySelectorAll("*")) {
+      if (bgUrls.length > 400) break;
+      const bg = getComputedStyle(el).backgroundImage;
+      if (!bg || bg === "none") continue;
+      const m = /url\(["']?([^"')]+)["']?\)/.exec(bg);
+      if (m && m[1] && !seen.has(m[1])) {
+        seen.add(m[1]);
+        bgUrls.push({ url: m[1], tag: el.tagName.toLowerCase() });
+      }
+    }
+
+    const props = [
+      "fontSize",
+      "fontWeight",
+      "fontFamily",
+      "lineHeight",
+      "letterSpacing",
+      "color",
+      "backgroundColor",
+      "padding",
+      "margin",
+      "maxWidth",
+      "display",
+      "gap",
+      "borderRadius",
+      "boxShadow",
+    ];
+
+    function pickStyles(el) {
+      if (!el) return null;
+      const cs = getComputedStyle(el);
+      const o = {};
+      for (const p of props) o[p] = cs[p];
+      return o;
+    }
+
+    const landmarks = {
+      html: pickStyles(document.documentElement),
+      body: pickStyles(document.body),
+      h1: pickStyles(document.querySelector("h1")),
+      header: pickStyles(document.querySelector("header")),
+      main: pickStyles(document.querySelector("main")),
+      firstSection: pickStyles(document.querySelector("main section, section")),
+    };
+
+    return {
+      title,
+      likelyBotWall,
+      textSample: text.slice(0, 1200),
+      assetInventory: {
+        images: imgs.filter((i) => i.src),
+        videos,
+        backgroundImages: bgUrls,
+        svgCount: document.querySelectorAll("svg").length,
+      },
+      computedLandmarks: landmarks,
+    };
+  });
+}
+
+function writeMediaManifest(host, data, limitationsPath) {
+  const { images, videos, backgroundImages } = data.assetInventory;
+  const lines = [
+    "# MEDIA_MANIFEST (Playwright)",
+    "",
+    `Host: **${host}**`,
+    "",
+    "## Images (`<img>`)",
+    "",
+    "| src | alt | natural |",
+    "|-----|-----|---------|",
+  ];
+  for (const i of images.slice(0, 200)) {
+    const s = i.src.replace(/\|/g, "\\|");
+    lines.push(`| ${s} | ${(i.alt || "").replace(/\|/g, "\\|")} | ${i.w}×${i.h} |`);
+  }
+  if (images.length > 200) lines.push(`\n_…and ${images.length - 200} more_\n`);
+
+  lines.push("", "## Video", "", "| src | poster |", "|-----|--------|");
+  for (const v of videos) {
+    lines.push(`| ${(v.src || "").replace(/\|/g, "\\|")} | ${(v.poster || "").replace(/\|/g, "\\|")} |`);
+  }
+
+  lines.push("", "## Background images (sample)", "", "| url |", "|-----|");
+  for (const b of backgroundImages.slice(0, 150)) {
+    lines.push(`| ${b.url.replace(/\|/g, "\\|")} |`);
+  }
+
+  lines.push("", "---", "", `_Generated by scripts/recon-playwright.mjs. Download with scripts/download-assets.mjs when ready._`);
+  if (limitationsPath) lines.push("", `See also: **${limitationsPath}**`);
+
+  writeFileSync(join(ROOT, "docs", "research", "MEDIA_MANIFEST.md"), lines.join("\n") + "\n", "utf8");
+}
+
+function writeLimitations(host, url, finalUrl, data) {
+  const p = join(ROOT, "docs", "research", "EXTRACTION_LIMITATIONS.md");
+  const lines = [
+    "# Extraction limitations",
+    "",
+    `- **Requested URL:** ${url}`,
+    `- **Final URL:** ${finalUrl}`,
+    `- **Host:** ${host}`,
+    `- **Captured at:** ${new Date().toISOString()}`,
+    `- **Tool:** Playwright (\`npm run recon\`)`,
+    "",
+  ];
+  if (data.likelyBotWall) {
+    lines.push(
+      "## Bot / challenge page suspected",
+      "",
+      "Title or DOM matches common WAF/interstitial patterns. **Computed styles and screenshots may not reflect the real marketing page.** Prefer \`npm run recon:headed\` with real Chrome, or open the site manually and export assets.",
+      ""
+    );
+  } else {
+    lines.push(
+      "## Notes",
+      "",
+      "Snapshot-derived data is from Playwright Chromium, not interactive MCP. Re-run after layout shifts; verify against a real browser for pixel QA.",
+      ""
+    );
+  }
+  writeFileSync(p, lines.join("\n"), "utf8");
+  return "docs/research/EXTRACTION_LIMITATIONS.md";
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const url = args.url || readLaunchframeUrl();
+  if (!url) {
+    console.error("No URL: set launchframe.config.json or pass --url https://...");
+    process.exit(1);
+  }
+
+  let chromium;
+  try {
+    ({ chromium } = await import("playwright"));
+  } catch {
+    console.error("Install Playwright: npm i -D playwright && npx playwright install chromium");
+    process.exit(1);
+  }
+
+  const host = safeHost(url);
+  mkdirSync(join(ROOT, "docs", "design-references"), { recursive: true });
+  mkdirSync(join(ROOT, "docs", "research"), { recursive: true });
+
+  const browser = await chromium.launch({
+    headless: !args.headed,
+    channel: args.channel,
+  });
+
+  const context = await browser.newContext({
+    userAgent:
+      "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
+    locale: "en-US",
+  });
+
+  const page = await context.newPage();
+
+  const snapshot = {
+    fetchedAt: new Date().toISOString(),
+    requestedUrl: url,
+    finalUrl: null,
+    viewports: {},
+    title: null,
+    likelyBotWall: false,
+    assetInventory: null,
+    computedLandmarks: null,
+    textSample: null,
+  };
+
+  try {
+    await page.goto(url, { waitUntil: "domcontentloaded", timeout: 90_000 });
+    await new Promise((r) => setTimeout(r, 2500));
+    snapshot.finalUrl = page.url();
+
+    for (const w of [1440, 390]) {
+      await page.setViewportSize({ width: w, height: w === 1440 ? 900 : 844 });
+      if (w === 1440) await scrollFullPage(page);
+
+      const shotPath = join(ROOT, "docs", "design-references", `playwright-${host}-${w}px.png`);
+      await page.screenshot({ path: shotPath, fullPage: true });
+      snapshot.viewports[w] = { screenshot: `docs/design-references/playwright-${host}-${w}px.png` };
+
+      if (w === 1440) {
+        const data = await gatherPageData(page);
+        snapshot.title = data.title;
+        snapshot.likelyBotWall = data.likelyBotWall;
+        snapshot.assetInventory = data.assetInventory;
+        snapshot.computedLandmarks = data.computedLandmarks;
+        snapshot.textSample = data.textSample;
+      }
+    }
+  } finally {
+    await browser.close();
+  }
+
+  const limRel = writeLimitations(host, url, snapshot.finalUrl, {
+    likelyBotWall: snapshot.likelyBotWall,
+  });
+
+  writeFileSync(
+    join(ROOT, "docs", "research", "computed-snapshot.json"),
+    JSON.stringify(snapshot, null, 2) + "\n",
+    "utf8"
+  );
+
+  if (snapshot.assetInventory) {
+    writeMediaManifest(host, { assetInventory: snapshot.assetInventory }, limRel);
+  }
+
+  console.log("Playwright recon finished.");
+  console.log(`  Screenshots: docs/design-references/playwright-${host}-1440px.png (+ 390px)`);
+  console.log(`  Snapshot:    docs/research/computed-snapshot.json`);
+  console.log(`  Media list:  docs/research/MEDIA_MANIFEST.md`);
+  console.log(`  Limits:      ${limRel}`);
+  if (snapshot.likelyBotWall) {
+    console.warn("\n⚠ Possible bot wall / challenge page — check EXTRACTION_LIMITATIONS.md and try: npm run recon:headed\n");
+  }
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});