launchframe 0.1.6 → 0.1.7

package/README.md

@@ -54,13 +54,19 @@ output/<runId>/
 ├── run.json             ← full run metadata (sources, timing, status)
 ├── screenshots/         ← captured PNGs
 ├── raw/                 ← per-site raw token + SiteLayout JSON
+├── reference/           ← verbatim DOM + copy for AI (see below)
+│   └── <host>/
+│       ├── page.html           ← full HTML after JavaScript
+│       ├── visible-text.txt    ← paste-friendly copy extraction
+│       ├── visible-text.json   ← structured headings / body / buttons
+│       ├── media.json          ← img + video URLs
+│       ├── meta.json           ← title, description, lang
+│       └── FOR_AI_REFERENCE.md
 └── mirror/
     └── <host>/
-        ├── page.tsx         ← Next.js page reconstructed from the source's
-        │                       section tree, with <TextSlot> / <MediaSlot>
-        │                       placeholders for your own copy and assets
-        ├── layout.json      ← the typed SiteLayout the page was built from
-        └── MIRROR_NOTES.md  ← what was extracted and how to fill slots
+        ├── page.tsx         ← Next.js: Motion + Phosphor + image/video patterns
+        ├── layout.json
+        └── MIRROR_NOTES.md
 ```
 
 ---
@@ -68,22 +74,18 @@ output/<runId>/
 ## Hand the output to your AI
 
 1. Run the command above so `output/<runId>/` exists.
-2. Pick the mirror folder that matches the source whose layout you want
-   to start from: `output/<runId>/mirror/<host>/`.
-3. Either:
-   - **Cursor:** `@`-attach the mirror folder along with `FOR_AI.md` and
-     `tokens.json`, then ask the agent to fill in `<TextSlot>` /
-     `<MediaSlot>` placeholders with copy for *your* product.
-   - **Claude Code:** copy the mirror folder into your project, then ask
-     the agent the same thing.
-4. The AI's authority order is **MIRROR_NOTES.md → page.tsx → tokens.json
-   → tailwind.config.ts + globals.css**. It must:
-   - Keep the section tree, grid composition, and density of `page.tsx`
-     intact (that is the source's layout grammar, which is the point).
-   - Replace every `<TextSlot kind="…" />` placeholder with original
-     copy written for *your* product — not paraphrased from the source.
-   - Replace every `<MediaSlot kind="…" />` with your own imagery, code
-     samples, or brand marks.
+2. Attach **`reference/<host>/`** (`visible-text.txt`, `page.html`, `media.json`) so the model sees **exact copy and structure** from the crawl.
+3. Pick the mirror folder: `output/<runId>/mirror/<host>/`.
+4. Either:
+   - **Cursor:** `@`-attach `reference/<host>/`, `mirror/<host>/`, `FOR_AI.md`, and
+     `tokens.json`, then ask the agent to port copy from `visible-text.txt` into
+     `page.tsx` and wire media from `media.json`.
+   - **Claude Code:** copy both folders into your project, then ask the same.
+5. The AI's authority order is **reference/visible-text.txt & page.html →
+   MIRROR_NOTES.md → page.tsx → tokens.json → tailwind.config.ts + globals.css**. It must:
+   - Keep the section tree, grid composition, density, Motion, and Phosphor usage in `page.tsx`.
+   - Map strings from `visible-text.txt` into the right `<TextSlot>` slots (or replace slots with plain JSX).
+   - Use `media.json` for image/video `src` / `poster` (respect licensing; prefer your own assets).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "launchframe",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Point Launchframe at SaaS sites you admire and get back a drop-in shadcn/ui design system (tokens, Tailwind theme, CSS variables, AI handoff) you can build your own UI on top of.",
   "license": "MIT",
   "author": "Evan Gruhlkey",

package/packages/extract/extract.ts

@@ -19,8 +19,8 @@
  *   - Honor robots.txt unless `--no-robots` is passed.
  *   - Per-domain rate limit defaults to 15 req/min (`--rate <n>`).
  *   - The crawler extracts a structured representation (section tree,
- *     computed style tokens, content kinds); it does not store raw HTML,
- *     copy text, or third-party assets in the output.
+ *     computed style tokens, content kinds) and writes a verbatim
+ *     `reference/<host>/` bundle (HTML + visible text + media URLs) for AI.
  */
 
 import { mkdirSync, writeFileSync } from "node:fs";
@@ -32,7 +32,7 @@ import { chromium, type Browser } from "playwright";
 import { harvestTokens } from "./browser-extract.js";
 import { crawlLayout } from "./dom-crawler.js";
 import { emitAll } from "./emit.js";
-import { emitMirror } from "./mirror-emit.js";
+import { emitPageReference } from "./reference-dump.js";
 import { synthesize } from "./synthesize.js";
 import type { ExtractionRun, RawTokens, SiteCapture, SiteLayout } from "./types.js";
 
@@ -101,13 +101,12 @@ function printHelp(): void {
       "",
       "For each URL the CLI:",
       "  1. Renders the page at a desktop viewport in headless Chromium.",
-      "  2. Harvests computed design tokens (colors, type, spacing, radius,",
-      "     shadow).",
-      "  3. Crawls the rendered DOM into a typed SiteLayout (section tree,",
-      "     composition, slot counts, per-section style tokens).",
-      "  4. Emits a layout-mirror Next.js page at",
-      "     output/<runId>/mirror/<host>/page.tsx with <TextSlot> /",
-      "     <MediaSlot> placeholders for your own copy and imagery.",
+      "  2. Captures a full-page screenshot and harvests computed design tokens",
+      "     (colors, type, spacing, radius, shadow) → raw/<host>.tokens.json.",
+      "  3. Writes a verbatim reference bundle → reference/<host>/ (page.html,",
+      "     visible-text.json/.txt, media.json, meta.json, FOR_AI_REFERENCE.md).",
+      "  4. Crawls the DOM into SiteLayout → raw/<host>.layout.json and emits",
+      "     mirror/<host>/page.tsx (Framer Motion + Phosphor + image/video slots).",
       "",
       "After every URL, a drop-in shadcn-compatible design system is",
       "synthesized from the aggregated tokens and written to output/<runId>/.",
@@ -203,6 +202,7 @@ async function captureOne(
   const rawPath = join(outDir, "raw", `${host}.tokens.json`);
   const layoutPath = join(outDir, "raw", `${host}.layout.json`);
   const mirrorDir = join(outDir, "mirror", host);
+  const referenceDir = join(outDir, "reference", host);
 
   const ctx = await browser.newContext({
     userAgent: USER_AGENT,
@@ -235,6 +235,13 @@ async function captureOne(
     mkdirSync(dirname(rawPath), { recursive: true });
     writeFileSync(rawPath, JSON.stringify(raw, null, 2));
 
+    let referenceWritten: string[] = [];
+    try {
+      referenceWritten = await emitPageReference(page, url, referenceDir);
+    } catch (err) {
+      console.warn(`  ! reference dump failed for ${url}: ${(err as Error).message}`);
+    }
+
     let layout: SiteLayout | null = null;
     let mirrorWritten: string[] = [];
     try {
@@ -252,6 +259,7 @@ async function captureOne(
       capturedAt: raw.capturedAt,
       screenshotPath,
       rawTokensPath: rawPath,
+      ...(referenceWritten.length > 0 ? { referenceDir } : {}),
       ...(layout ? { layoutPath } : {}),
       ...(mirrorWritten.length > 0 ? { mirrorDir } : {}),
       status: "ok",
@@ -378,11 +386,17 @@ async function main(): Promise<void> {
   for (const f of written) console.log(`  → ${f}`);
   console.log(`  → ${join(outDir, "run.json")}`);
   const mirrorDirs = captures.filter((c) => c.mirrorDir).map((c) => c.mirrorDir!);
+  const referenceDirs = captures.filter((c) => c.referenceDir).map((c) => c.referenceDir!);
   if (mirrorDirs.length > 0) {
     console.log("");
     console.log("[extract] layout mirrors:");
     for (const d of mirrorDirs) console.log(`  → ${d}/page.tsx`);
   }
+  if (referenceDirs.length > 0) {
+    console.log("");
+    console.log("[extract] AI reference (verbatim DOM + copy):");
+    for (const d of referenceDirs) console.log(`  → ${d}/FOR_AI_REFERENCE.md`);
+  }
   console.log("");
   console.log(`[extract] done. Open ${join(outDir, "REPORT.md")} for the design-system summary.`);
   if (mirrorDirs.length > 0) {
@@ -391,6 +405,11 @@ async function main(): Promise<void> {
     );
     console.log(`[extract] fill the <TextSlot> / <MediaSlot> placeholders with your own content.`);
   }
+  if (referenceDirs.length > 0) {
+    console.log(
+      `[extract] paste reference/<host>/visible-text.txt or page.html into your AI for exact structure + copy.`,
+    );
+  }
   console.log(`[extract] AI handoff: ${join(outDir, "FOR_AI.md")}`);
 }
 

package/packages/extract/mirror-emit.ts

@@ -9,9 +9,9 @@
  *   - `<dir>/layout.json`   — the captured `SiteLayout` model for review.
  *   - `<dir>/MIRROR_NOTES.md` — what was extracted, how slots are filled.
  *
- * The emitter never embeds the source's verbatim copy text or brand
- * assets. Headings, body copy, buttons, images, and logos are rendered as
- * slot placeholders that the operator fills in.
+ * The emitter renders **slot placeholders** in `page.tsx` for final copy;
+ * pair this with `reference/<host>/visible-text.txt` or `page.html` for
+ * verbatim source strings when prompting an AI.
  */
 
 import { mkdirSync, writeFileSync } from "node:fs";
@@ -58,6 +58,8 @@ function emitPage(layout: SiteLayout): string {
   );
 
   return [
+    '"use client";',
+    "",
     "/**",
     ` * Mirror page for ${layout.url}`,
     ` * Captured ${layout.capturedAt}`,
@@ -65,19 +67,30 @@ function emitPage(layout: SiteLayout): string {
     " *",
     " * Generated by launchframe — packages/extract/mirror-emit.ts",
     " *",
-    " * Fill in <TextSlot> and <MediaSlot> placeholders with your own copy",
-    " * and imagery before shipping. The visual tokens (color, type, radius,",
-    ' * container width) reflect the source page and are scoped to the',
-    ' * `.mirror-root` wrapper below — no global CSS leakage.',
+    " * Reference for exact copy + DOM: ../../reference/<host>/",
+    " * (visible-text.txt, page.html, media.json).",
+    " *",
+    " * Framer Motion: MirrorEnter / MirrorEnterFromEnd / MirrorStaggerRow.",
+    " * Icons: @phosphor-icons/react via @framework/blocks.",
+    " * Swap <MediaSlot> for next/image or <video controls playsInline>.",
     " */",
     "",
     'import {',
-    "  FadeUp,",
+    "  CaretRight,",
+    "  Clock,",
+    "  FileText,",
+    "  ListBullets,",
+    "  MirrorEnter,",
+    "  MirrorEnterFromEnd,",
+    "  MirrorStaggerRow,",
     "  MediaSlot,",
+    "  PlayCircle,",
+    "  Queue,",
+    "  Sparkle,",
     "  Stagger,",
     "  StaggerItem,",
     "  TextSlot,",
-    "  cn,",
+    "  VideoCamera,",
     "} from \"@framework/blocks\";",
     "",
     `export const meta = ${JSON.stringify(
@@ -85,6 +98,7 @@ function emitPage(layout: SiteLayout): string {
         kind: "mirror",
         source: layout.url,
         capturedAt: layout.capturedAt,
+        referencePath: `../../reference/${layout.host}`,
         sections: layout.sections.map((s) => ({
           id: s.id,
           role: s.role,
@@ -244,7 +258,7 @@ function emitSingleColumn(s: SectionLayout, labelId: string): string {
   if ((slots["button-primary"] ?? 0) > 0) buttons.push(textSlot("button-primary"));
   if ((slots["button-secondary"] ?? 0) > 0) buttons.push(textSlot("button-secondary"));
 
-  const headBlock = head.length > 0 ? wrapFadeUp(head.join("\n")) : "";
+  const headBlock = head.length > 0 ? wrapMirrorEnter(head.join("\n")) : "";
   const buttonsBlock =
     buttons.length > 0
       ? `<div className="mt-8 flex flex-wrap items-center gap-3">\n${indent(buttons.join("\n"), 2)}\n</div>`
@@ -280,7 +294,11 @@ function emitSplitTwo(s: SectionLayout, labelId: string): string {
   }
 
   const buttons: string[] = [];
-  if ((slots["button-primary"] ?? 0) > 0) buttons.push(textSlot("button-primary"));
+  if ((slots["button-primary"] ?? 0) > 0) {
+    buttons.push(
+      '<span className="inline-flex items-center gap-2 has-[button]:gap-0"><TextSlot kind="button-primary" /><CaretRight className="size-4 opacity-90" weight="bold" aria-hidden /></span>',
+    );
+  }
   if ((slots["button-secondary"] ?? 0) > 0) buttons.push(textSlot("button-secondary"));
   if (buttons.length > 0) {
     textChildren.push(
@@ -292,8 +310,11 @@ function emitSplitTwo(s: SectionLayout, labelId: string): string {
     );
   }
 
-  const textCol = wrapFadeUp(textChildren.join("\n"));
-  const mediaCol = wrapFadeUp(emitMediaSlots(slots, { aspect: "video" }) || mediaSlot("image"));
+  const textCol = wrapMirrorEnter(textChildren.join("\n"));
+  const mediaInner = emitHeroMediaColumn(slots);
+  const mediaCol = [`<MirrorEnterFromEnd>`, indent(mediaInner, 1), `</MirrorEnterFromEnd>`].join(
+    "\n",
+  );
 
   return [
     '<div className="grid items-center gap-12 md:grid-cols-2">',
@@ -303,6 +324,74 @@ function emitSplitTwo(s: SectionLayout, labelId: string): string {
   ].join("\n");
 }
 
+/** Rich right column: product-style card + Phosphor + image/video slots. */
+function emitHeroMediaColumn(slots: Partial<Record<SlotKind, number>>): string {
+  const hasVideo = (slots.video ?? 0) > 0;
+  const queueCard = [
+    '<div className="overflow-hidden rounded-xl border border-border bg-card shadow-lg ring-1 ring-foreground/[0.06]">',
+    '  <header className="flex items-center justify-between gap-3 border-b border-border px-4 py-3">',
+    '    <span className="flex items-center gap-2 min-w-0">',
+    '      <Queue className="size-5 shrink-0 text-[var(--mirror-primary)]" weight="duotone" aria-hidden />',
+    '      <TextSlot kind="eyebrow" />',
+    "    </span>",
+    '    <TextSlot kind="badge" />',
+    "  </header>",
+    '  <ul className="divide-y divide-border">',
+    "    <MirrorStaggerRow index={0} className=\"flex gap-3 px-4 py-3\">",
+    '      <FileText className="size-5 shrink-0 text-[var(--mirror-primary)] mt-0.5" weight="duotone" aria-hidden />',
+    '      <div className="min-w-0 space-y-1">',
+    '        <TextSlot kind="heading-3" />',
+    '        <TextSlot kind="body" />',
+    "      </div>",
+    "    </MirrorStaggerRow>",
+    "    <MirrorStaggerRow index={1} className=\"flex gap-3 px-4 py-3\">",
+    '      <Clock className="size-5 shrink-0 text-[var(--mirror-primary)] mt-0.5" weight="duotone" aria-hidden />',
+    '      <div className="min-w-0 space-y-1">',
+    '        <TextSlot kind="heading-3" />',
+    '        <TextSlot kind="body" />',
+    "      </div>",
+    "    </MirrorStaggerRow>",
+    "    <MirrorStaggerRow index={2} className=\"flex gap-3 px-4 py-3\">",
+    '      <ListBullets className="size-5 shrink-0 text-[var(--mirror-primary)] mt-0.5" weight="duotone" aria-hidden />',
+    '      <div className="min-w-0 space-y-1">',
+    '        <TextSlot kind="heading-3" />',
+    '        <TextSlot kind="body" />',
+    "      </div>",
+    "    </MirrorStaggerRow>",
+    "  </ul>",
+    "</div>",
+  ].join("\n");
+
+  const imageBlock = [
+    '<div className="mt-6 space-y-3">',
+    '  <MediaSlot kind="image" aspect="video" />',
+    "  {/* Drop in when you have assets: import Image from 'next/image' */}",
+    '  {/* <Image src="/hero.jpg" alt="" fill className="object-cover rounded-xl" sizes="(max-width:768px) 100vw, 50vw" /> */}',
+    "</div>",
+  ].join("\n");
+
+  const videoBlock = hasVideo
+    ? [
+        '<div className="mt-6">',
+        '  <div className="relative overflow-hidden rounded-xl border border-border bg-muted/30 aspect-video">',
+        '    <VideoCamera className="absolute left-3 top-3 size-6 text-muted-foreground" weight="duotone" aria-hidden />',
+        '    <video className="h-full w-full object-cover" controls playsInline preload="metadata" poster="/poster-frame.jpg">',
+        '      <source src="/product-demo.mp4" type="video/mp4" />',
+        "    </video>",
+        "  </div>",
+        '  <p className="mt-2 text-xs text-muted-foreground">No autoplay — swap poster + src from reference/media.json.</p>',
+        "</div>",
+      ].join("\n")
+    : [
+        '<div className="mt-6 flex items-center gap-2 text-xs text-muted-foreground">',
+        '  <PlayCircle className="size-4 shrink-0" weight="regular" aria-hidden />',
+        '  <span>Optional: add a <code className="font-mono">video</code> block; see media.json from the crawl.</span>',
+        "</div>",
+      ].join("\n");
+
+  return [queueCard, imageBlock, videoBlock].join("\n");
+}
+
 function emitGrid(s: SectionLayout, labelId: string): string {
   const slots = slotMap(s.slots);
   const cols = gridCols(s.composition);
@@ -319,22 +408,12 @@ function emitGrid(s: SectionLayout, labelId: string): string {
   const cardHeading: SlotKind =
     (slots["heading-2"] ?? 0) >= cols ? "heading-2" : "heading-3";
 
-  const card = [
-    '<li className="flex flex-col gap-3 rounded-lg border border-border bg-card p-6">',
-    `  ${mediaSlot("icon", { aspect: "square", className: "size-10" })}`,
-    `  ${textSlot(cardHeading)}`,
-    `  ${textSlot("body")}`,
-    "</li>",
-  ].join("\n");
-
-  const cards: string[] = [];
-  for (let i = 0; i < cols; i++) cards.push(card);
   const grid = [
     `<Stagger as="ul" className=${JSON.stringify(`mt-12 grid gap-6 md:grid-cols-${cols}`)}>`,
     ...cards.map((c) =>
       [
         '  <StaggerItem as="li" className="flex flex-col gap-3 rounded-lg border border-border bg-card p-6">',
-        `    ${mediaSlot("icon", { aspect: "square", className: "size-10" })}`,
+        '    <Sparkle className="size-10 text-[var(--mirror-primary)]" weight="duotone" aria-hidden />',
         `    ${textSlot(cardHeading)}`,
         `    ${textSlot("body")}`,
         "  </StaggerItem>",
@@ -344,7 +423,7 @@ function emitGrid(s: SectionLayout, labelId: string): string {
   ];
 
   const head = [
-    heading ? wrapFadeUp(heading) : "",
+    heading ? wrapMirrorEnter(heading) : "",
     introBody,
   ]
     .filter(Boolean)
@@ -384,7 +463,7 @@ function emitList(s: SectionLayout, labelId: string): string {
   for (let i = 0; i < count; i++) items.push(textSlot("bullet"));
 
   return [
-    heading ? wrapFadeUp(heading) : "",
+    heading ? wrapMirrorEnter(heading) : "",
     `<ul className="mt-8 space-y-3 text-sm">`,
     ...items.map((it) => `  ${it}`),
     "</ul>",
@@ -426,7 +505,17 @@ function emitMediaSlots(
   const parts: string[] = [];
   if ((slots.image ?? 0) > 0) parts.push(mediaSlot("image", { aspect: opts.aspect ?? "video" }));
   if ((slots.code ?? 0) > 0) parts.push(mediaSlot("code", { aspect: "auto" }));
-  if ((slots.video ?? 0) > 0) parts.push(mediaSlot("video", { aspect: opts.aspect ?? "video" }));
+  if ((slots.video ?? 0) > 0) {
+    parts.push(
+      [
+        '<div className="overflow-hidden rounded-xl border border-border aspect-video bg-muted/20">',
+        '  <video className="h-full w-full object-cover" controls playsInline preload="metadata" poster="/poster.jpg">',
+        '    <source src="/clip.mp4" type="video/mp4" />',
+        "  </video>",
+        "</div>",
+      ].join("\n"),
+    );
+  }
   if (parts.length === 0) return "";
   if (parts.length === 1) return `<div className="mt-12">${parts[0]}</div>`;
   return [
@@ -436,11 +525,11 @@ function emitMediaSlots(
   ].join("\n");
 }
 
-function wrapFadeUp(children: string): string {
+function wrapMirrorEnter(children: string): string {
   return [
-    "<FadeUp>",
+    "<MirrorEnter>",
     indent(children, 1),
-    "</FadeUp>",
+    "</MirrorEnter>",
   ].join("\n");
 }
 
@@ -481,16 +570,22 @@ function emitNotes(layout: SiteLayout): string {
   lines.push("- Slot inventory per section (counts of headings / body / buttons / images / icons / logos)");
   lines.push("- Per-section background and padding");
   lines.push("- Page-level tokens (fonts, primary/muted/border/foreground, radius, container width)");
+  lines.push("- **Polished UI shell** in `page.tsx`: Framer Motion (`MirrorEnter`, `MirrorEnterFromEnd`, `MirrorStaggerRow`), Phosphor icons, image + video placeholders");
   lines.push("");
-  lines.push("## What was **not** extracted");
+  lines.push("## Verbatim reference (same crawl)");
   lines.push("");
-  lines.push("- Source headlines, body copy, or microcopy text");
-  lines.push("- Brand logos, illustrations, or product screenshots");
-  lines.push("- Source HTML, CSS, or class names");
+  lines.push(`Open **../reference/${layout.host}/** alongside this folder:`);
   lines.push("");
-  lines.push(
-    "The `page.tsx` reconstructs the section grammar from typed primitives. Headings, body copy, buttons, images, and logos appear as `<TextSlot>` / `<MediaSlot>` placeholders. Fill them with your own content before shipping.",
-  );
+  lines.push("- `page.html` — full serialized DOM after JS (exact structure for an AI)");
+  lines.push("- `visible-text.txt` / `visible-text.json` — visible headings, paragraphs, buttons");
+  lines.push("- `media.json` — image and video URLs from the page");
+  lines.push("- `FOR_AI_REFERENCE.md` — how to use the bundle");
+  lines.push("");
+  lines.push("Paste `visible-text.txt` or excerpts into your AI when filling `<TextSlot>` nodes.");
+  lines.push("");
+  lines.push("## What stays as slots in page.tsx");
+  lines.push("");
+  lines.push("`<TextSlot>` / `<MediaSlot>` keep the React tree clean until you substitute real strings and assets. Copy text from `visible-text.txt`; swap `poster` / `src` on `<video>` and `next/image` from `media.json`.");
   lines.push("");
   lines.push("## Section breakdown");
   lines.push("");

package/packages/extract/reference-dump.ts

@@ -0,0 +1,230 @@
+/**
+ * Verbatim reference dump for AI / human review.
+ *
+ * Writes everything under `output/<runId>/reference/<host>/`:
+ *   - page.html          — full document HTML after JS render (`page.content()`)
+ *   - visible-text.json  — structured visible copy (headings, buttons, key blocks)
+ *   - media.json         — img / video / source URLs and attributes
+ *   - meta.json          — title, description, canonical, lang
+ *   - FOR_AI_REFERENCE.md — how to use these files with an AI
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { Page } from "playwright";
+
+export interface ReferenceSnapshot {
+  url: string;
+  capturedAt: string;
+  title: string | null;
+  description: string | null;
+  canonical: string | null;
+  lang: string | null;
+  /** Flattened visible strings in DOM order (useful for grep / LLM context). */
+  visibleTextBlocks: Array<{
+    tag: string;
+    role: string | null;
+    text: string;
+  }>;
+  links: Array<{ href: string; text: string }>;
+  media: Array<
+    | { type: "img"; src: string; alt: string; width: number | null; height: number | null }
+    | { type: "video"; src: string | null; poster: string | null }
+    | { type: "source"; src: string; kind: string | null }
+  >;
+}
+
+export async function emitPageReference(page: Page, url: string, refDir: string): Promise<string[]> {
+  mkdirSync(refDir, { recursive: true });
+  const written: string[] = [];
+  const capturedAt = new Date().toISOString();
+
+  await page.evaluate(() => {
+    const g = globalThis as unknown as { __name?: (fn: unknown) => unknown };
+    if (typeof g.__name === "undefined") g.__name = (fn: unknown) => fn;
+  });
+
+  const html = await page.content();
+  const htmlPath = join(refDir, "page.html");
+  writeFileSync(htmlPath, html, "utf8");
+  written.push(htmlPath);
+
+  const snapshot = (await page.evaluate(collectSnapshot)) as Omit<ReferenceSnapshot, "url" | "capturedAt">;
+  const full: ReferenceSnapshot = {
+    url,
+    capturedAt,
+    ...snapshot,
+  };
+
+  writeFileSync(join(refDir, "visible-text.json"), JSON.stringify(full, null, 2) + "\n", "utf8");
+  written.push(join(refDir, "visible-text.json"));
+
+  const txtLines = [
+    `# ${full.title ?? "Untitled"}`,
+    "",
+    ...full.visibleTextBlocks.map((b) => b.text),
+    "",
+    "--- links ---",
+    ...full.links.map((l) => `${l.text}\t${l.href}`),
+  ];
+  writeFileSync(join(refDir, "visible-text.txt"), txtLines.join("\n"), "utf8");
+  written.push(join(refDir, "visible-text.txt"));
+
+  const mediaOnly = { url, capturedAt, media: full.media };
+  writeFileSync(join(refDir, "media.json"), JSON.stringify(mediaOnly, null, 2) + "\n", "utf8");
+  written.push(join(refDir, "media.json"));
+
+  const meta = {
+    url,
+    capturedAt,
+    title: full.title,
+    description: full.description,
+    canonical: full.canonical,
+    lang: full.lang,
+  };
+  writeFileSync(join(refDir, "meta.json"), JSON.stringify(meta, null, 2) + "\n", "utf8");
+  written.push(join(refDir, "meta.json"));
+
+  writeFileSync(join(refDir, "FOR_AI_REFERENCE.md"), emitAiReadme(url, refDir), "utf8");
+  written.push(join(refDir, "FOR_AI_REFERENCE.md"));
+
+  return written;
+}
+
+function emitAiReadme(url: string, refDir: string): string {
+  const base = refDir.replace(/\\/g, "/");
+  return [
+    `# Reference capture — ${url}`,
+    "",
+    "Use these files when rebuilding the page in React / Next.js:",
+    "",
+    "| File | Purpose |",
+    "| ---- | ------- |",
+    "| `page.html` | Full serialized DOM after JavaScript ran in Chromium. Layout, copy, and structure match what crawled (not necessarily valid static HTML elsewhere). |",
+    "| `visible-text.json` | Exact visible strings: headings, buttons, links, and block text — good for **verbatim copy** when rewriting `page.tsx`. |",
+    "| `media.json` | Every image / video / source URL from the DOM. Host your own assets or swap for placeholders; do not hotlink without permission. |",
+    "| `meta.json` | Title, description, lang. |",
+    "",
+    `Sibling folder \`../mirror/<host>/\` has a typed \`page.tsx\` with Framer Motion, Phosphor icons, and slots — wire copy from \`visible-text.json\` and media from \`media.json\` into that file.`,
+    "",
+    `Captured path: \`${base}\``,
+    "",
+  ].join("\n");
+}
+
+/**
+ * Runs in browser context.
+ */
+function collectSnapshot(): Omit<ReferenceSnapshot, "url" | "capturedAt"> {
+  const title = document.title || null;
+  const descEl = document.querySelector('meta[name="description"]');
+  const description = descEl?.getAttribute("content")?.trim() || null;
+  const canonicalEl = document.querySelector('link[rel="canonical"]');
+  const canonical = canonicalEl?.getAttribute("href") || null;
+  const lang = document.documentElement.getAttribute("lang");
+
+  const visibleTextBlocks: Array<{ tag: string; role: string | null; text: string }> = [];
+  const pushBlock = (tag: string, el: HTMLElement, role: string | null) => {
+    const text = el.innerText?.trim().replace(/\s+/g, " ") ?? "";
+    if (text.length < 2 || text.length > 4000) return;
+    visibleTextBlocks.push({ tag, role, text });
+  };
+
+  for (const tag of ["H1", "H2", "H3", "H4", "H5", "H6"] as const) {
+    for (const el of Array.from(document.querySelectorAll(tag))) {
+      if (!(el instanceof HTMLElement)) continue;
+      const style = getComputedStyle(el);
+      if (style.visibility === "hidden" || style.display === "none") continue;
+      pushBlock(tag, el, el.getAttribute("role"));
+    }
+  }
+
+  for (const el of Array.from(document.querySelectorAll("p, li, blockquote, figcaption, label"))) {
+    if (!(el instanceof HTMLElement)) continue;
+    const style = getComputedStyle(el);
+    if (style.visibility === "hidden" || style.display === "none") continue;
+    pushBlock(el.tagName, el, el.getAttribute("role"));
+  }
+
+  for (const el of Array.from(document.querySelectorAll("button, [role='button']"))) {
+    if (!(el instanceof HTMLElement)) continue;
+    const style = getComputedStyle(el);
+    if (style.visibility === "hidden" || style.display === "none") continue;
+    pushBlock("BUTTON", el, el.getAttribute("role"));
+  }
+
+  for (const el of Array.from(document.querySelectorAll("span, div"))) {
+    if (!(el instanceof HTMLElement)) continue;
+    const role = el.getAttribute("role");
+    if (
+      role !== "heading" &&
+      !el.classList.contains("badge") &&
+      el.getAttribute("data-slot") === null
+    ) {
+      // Only capture labeled small UI chrome (badges, pills) via short text + uppercase heuristic
+      const style = getComputedStyle(el);
+      if (style.visibility === "hidden" || style.display === "none") continue;
+      const text = el.innerText?.trim().replace(/\s+/g, " ") ?? "";
+      if (text.length < 8 || text.length > 240) continue;
+      if (!/^[A-Z0-9\s&.,:]+$/.test(text)) continue; // ALL-CAPS-ish eyebrow labels
+      pushBlock(el.tagName, el, role);
+    }
+  }
+
+  const links: Array<{ href: string; text: string }> = [];
+  for (const a of Array.from(document.querySelectorAll("a[href]"))) {
+    const href = a.getAttribute("href") ?? "";
+    if (!href || href.startsWith("javascript:")) continue;
+    const text = (a.textContent ?? "").trim().replace(/\s+/g, " ");
+    if (!text) continue;
+    try {
+      const abs = new URL(href, document.baseURI).href;
+      links.push({ href: abs, text: text.slice(0, 500) });
+    } catch {
+      links.push({ href, text: text.slice(0, 500) });
+    }
+  }
+
+  const media: ReferenceSnapshot["media"] = [];
+  for (const img of Array.from(document.querySelectorAll("img"))) {
+    const src = img.currentSrc || img.src;
+    if (!src) continue;
+    media.push({
+      type: "img",
+      src,
+      alt: img.alt || "",
+      width: img.naturalWidth || null,
+      height: img.naturalHeight || null,
+    });
+  }
+  for (const video of Array.from(document.querySelectorAll("video"))) {
+    const poster = video.getAttribute("poster");
+    let src: string | null = null;
+    if (video.currentSrc) src = video.currentSrc;
+    else {
+      const s = video.querySelector("source[src]");
+      src = s?.getAttribute("src") ?? null;
+    }
+    media.push({ type: "video", src, poster: poster || null });
+  }
+  for (const source of Array.from(document.querySelectorAll("source[src]"))) {
+    const src = source.getAttribute("src");
+    if (!src) continue;
+    media.push({
+      type: "source",
+      src,
+      kind: source.getAttribute("type"),
+    });
+  }
+
+  return {
+    title,
+    description,
+    canonical,
+    lang: lang || null,
+    visibleTextBlocks,
+    links,
+    media,
+  };
+}

package/packages/extract/types.ts

@@ -293,9 +293,8 @@ export interface SiteCapture {
   host: string;
   capturedAt: string;
   screenshotPath: string;
-  rawTokensPath: string;
-  /** Path to the per-site `SiteLayout` JSON, if the mirror crawl succeeded. */
-  layoutPath?: string;
+  /** Verbatim HTML + copy + media listing for AI reference. */
+  referenceDir?: string;
   /** Path to the per-site mirror page directory, if emission succeeded. */
   mirrorDir?: string;
   status: "ok" | "skipped" | "failed";