launchframe 0.1.11 → 0.2.0

package/packages/extract/automated-clone-pass.ts

@@ -0,0 +1,353 @@
+/**
+ * Automated recon pass inspired by ai-website-cloner-template Phase 1–2:
+ * multi-viewport screenshots, scroll sweep frames, header probe, interaction
+ * hints, and optional media downloads — no manual Browser MCP required.
+ */
+
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, existsSync, writeFileSync } from "node:fs";
+import { dirname, extname, join } from "node:path";
+
+import type { Page } from "playwright";
+
+import { hostSlug } from "./host-slug.js";
+
+const RESPONSIVE_PRESETS = [
+  { name: "tablet", width: 768, height: 900 },
+  { name: "mobile", width: 390, height: 844 },
+] as const;
+
+export interface AutomatedClonePassOptions {
+  page: Page;
+  host: string;
+  outDir: string;
+  primaryViewport: { width: number; height: number };
+  referenceDir?: string;
+  userAgent: string;
+  /** When false, skip downloading binaries from media.json (faster / lighter). */
+  downloadAssets: boolean;
+}
+
+/**
+ * Runs while the Playwright page is still open (after reference + layout).
+ * Writes under docs/design-references/<hostSlug>/ and optionally downloaded_assets/.
+ */
+export async function runAutomatedClonePass(opts: AutomatedClonePassOptions): Promise<string[]> {
+  const written: string[] = [];
+  const slug = hostSlug(opts.host);
+  const designRoot = join(opts.outDir, "docs", "design-references", slug);
+  mkdirSync(designRoot, { recursive: true });
+
+  const primary = opts.primaryViewport;
+
+  await opts.page.setViewportSize({ width: primary.width, height: primary.height });
+  await opts.page.waitForTimeout(200);
+
+  const viewportPrimary = join(designRoot, "viewport-desktop.png");
+  await opts.page.screenshot({ path: viewportPrimary, fullPage: false, type: "png" });
+  written.push(viewportPrimary);
+
+  const fullPrimarySrc = join(opts.outDir, "screenshots", `${opts.host}.png`);
+  const fullPrimaryDest = join(designRoot, "full-page-desktop.png");
+  if (existsSync(fullPrimarySrc)) {
+    writeFileSync(fullPrimaryDest, readFileSync(fullPrimarySrc));
+    written.push(fullPrimaryDest);
+  }
+
+  for (const preset of RESPONSIVE_PRESETS) {
+    await opts.page.setViewportSize({ width: preset.width, height: preset.height });
+    await opts.page.waitForTimeout(350);
+    const fp = join(designRoot, `full-page-${preset.name}.png`);
+    await opts.page.screenshot({ path: fp, fullPage: true, type: "png" });
+    written.push(fp);
+    const vp = join(designRoot, `viewport-${preset.name}.png`);
+    await opts.page.screenshot({ path: vp, fullPage: false, type: "png" });
+    written.push(vp);
+  }
+
+  await opts.page.setViewportSize({ width: primary.width, height: primary.height });
+  await opts.page.waitForTimeout(200);
+
+  const scrollWritten = await scrollSweepScreenshots(opts.page, designRoot);
+  written.push(...scrollWritten);
+
+  await opts.page.evaluate(() => window.scrollTo(0, 0));
+  await opts.page.waitForTimeout(150);
+
+  const probePath = join(designRoot, "header-scroll-probe.json");
+  writeFileSync(probePath, JSON.stringify(await headerScrollProbe(opts.page), null, 2) + "\n");
+  written.push(probePath);
+
+  const hintsPath = join(designRoot, "interaction-hints.json");
+  writeFileSync(
+    hintsPath,
+    JSON.stringify(await captureInteractionHints(opts.page), null, 2) + "\n",
+  );
+  written.push(hintsPath);
+
+  const readmePath = join(designRoot, "README.md");
+  writeFileSync(readmePath, emitDesignReferencesReadme(opts.host, slug));
+  written.push(readmePath);
+
+  if (opts.downloadAssets && opts.referenceDir && existsSync(join(opts.referenceDir, "media.json"))) {
+    const assetDir = join(opts.outDir, "downloaded_assets", slug);
+    const manifestPath = join(assetDir, "manifest.json");
+    const manifest = await downloadMediaFromReference({
+      mediaJsonPath: join(opts.referenceDir, "media.json"),
+      destDir: join(assetDir, "files"),
+      userAgent: opts.userAgent,
+      baseUrl: opts.page.url(),
+    });
+    mkdirSync(dirname(manifestPath), { recursive: true });
+    writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+    written.push(manifestPath);
+  }
+
+  return written;
+}
+
+async function scrollSweepScreenshots(page: Page, designRoot: string): Promise<string[]> {
+  const written: string[] = [];
+  await page.evaluate(() => window.scrollTo(0, 0));
+  await page.waitForTimeout(150);
+
+  const scrollHeight = await page.evaluate(() =>
+    Math.max(document.documentElement.scrollHeight, document.body.scrollHeight),
+  );
+  const vh = await page.evaluate(() => window.innerHeight);
+  const steps = Math.min(10, Math.max(4, Math.ceil(scrollHeight / Math.max(1, vh))));
+  const positions: number[] = [];
+  for (let i = 0; i < steps; i++) {
+    const y =
+      steps <= 1 ? 0 : Math.floor(((scrollHeight - vh) * i) / (steps - 1 || 1));
+    positions.push(Math.max(0, y));
+  }
+
+  for (let i = 0; i < positions.length; i++) {
+    const y = positions[i]!;
+    await page.evaluate((yy) => window.scrollTo(0, yy), y);
+    await page.waitForTimeout(220);
+    const path = join(designRoot, `scroll-${String(i).padStart(2, "0")}-y${y}.png`);
+    await page.screenshot({ path, fullPage: false, type: "png" });
+    written.push(path);
+  }
+
+  await page.evaluate(() => window.scrollTo(0, 0));
+  await page.waitForTimeout(120);
+  return written;
+}
+
+async function headerScrollProbe(page: Page): Promise<unknown> {
+  await page.evaluate(() => window.scrollTo(0, 0));
+  await page.waitForTimeout(100);
+  const top = await probePrimaryChrome(page);
+  await page.evaluate(() => window.scrollTo(0, 420));
+  await page.waitForTimeout(180);
+  const scrolled = await probePrimaryChrome(page);
+  await page.evaluate(() => window.scrollTo(0, 0));
+  return {
+    capturedAt: new Date().toISOString(),
+    scrollY0: top,
+    scrollY420: scrolled,
+    note: "Compare boxShadow/background/position — header transitions suggest scroll-driven chrome.",
+  };
+}
+
+async function probePrimaryChrome(page: Page): Promise<unknown> {
+  return page.evaluate(() => {
+    const pick =
+      (document.querySelector("header") as HTMLElement | null) ??
+      (document.querySelector('[role="banner"]') as HTMLElement | null) ??
+      (document.querySelector("nav") as HTMLElement | null);
+    if (!pick || !(pick instanceof HTMLElement)) return null;
+    const cs = getComputedStyle(pick);
+    const r = pick.getBoundingClientRect();
+    return {
+      tag: pick.tagName,
+      position: cs.position,
+      top: Math.round(r.top),
+      height: Math.round(r.height),
+      boxShadow: cs.boxShadow,
+      backgroundColor: cs.backgroundColor,
+      backdropFilter: cs.backdropFilter,
+      borderBottomWidth: cs.borderBottomWidth,
+      borderBottomColor: cs.borderBottomColor,
+    };
+  });
+}
+
+async function captureInteractionHints(page: Page): Promise<unknown> {
+  return page.evaluate(() => {
+    const html = document.documentElement;
+    const body = document.body;
+    const hStyle = getComputedStyle(html);
+    const bStyle = getComputedStyle(body);
+    const stickySelectors = ["header", "nav", '[role="banner"]'];
+    let stickyCount = 0;
+    for (const sel of stickySelectors) {
+      for (const el of Array.from(document.querySelectorAll(sel))) {
+        const p = getComputedStyle(el).position;
+        if (p === "sticky" || p === "fixed") stickyCount++;
+      }
+    }
+    return {
+      capturedAt: new Date().toISOString(),
+      likelyLenis:
+        !!document.querySelector(
+          ".lenis, [data-lenis-prevent], [class*='lenis'], .locomotive-scroll",
+        ),
+      htmlScrollSnapType: hStyle.scrollSnapType,
+      bodyScrollSnapType: bStyle.scrollSnapType,
+      videoCount: document.querySelectorAll("video").length,
+      iframeCount: document.querySelectorAll("iframe").length,
+      stickyHeaderOrNavCount: stickyCount,
+      reducedMotionMedia: window.matchMedia("(prefers-reduced-motion: reduce)").matches,
+    };
+  });
+}
+
+function emitDesignReferencesReadme(host: string, slug: string): string {
+  return `# Design references — ${host}
+
+Automated captures (Landingfram \`automated-clone-pass\`), analogous to **ai-website-cloner-template** \`docs/design-references/\`.
+
+| Artifact | Purpose |
+| -------- | ------- |
+| \`full-page-desktop.png\` | Full-page desktop capture (copy of ../screenshots/${host}.png when present). |
+| \`viewport-desktop.png\` | Above-the-fold desktop viewport. |
+| \`full-page-tablet.png\` / \`viewport-tablet.png\` | 768×900 pass. |
+| \`full-page-mobile.png\` / \`viewport-mobile.png\` | 390×844 pass. |
+| \`scroll-*.png\` | Viewport screenshots while scrolling — quick motion / scroll-snap sanity check. |
+| \`header-scroll-probe.json\` | Header/nav computed styles at scroll Y≈0 vs Y≈420. |
+| \`interaction-hints.json\` | Heuristic signals (Lenis-like classes, scroll-snap, sticky chrome counts). |
+
+Section crops for builders can be derived from these plus \`../research/${slug}/PAGE_TOPOLOGY.md\`.
+
+Compliance: use for structure learning on sites you are allowed to analyze; replace assets when shipping your product.
+`;
+}
+
+interface DownloadManifest {
+  capturedAt: string;
+  baseUrl: string;
+  downloaded: Array<{ url: string; relativePath: string; bytes: number }>;
+  failed: Array<{ url: string; reason: string }>;
+  skippedDataUrls: number;
+}
+
+async function downloadMediaFromReference(opts: {
+  mediaJsonPath: string;
+  destDir: string;
+  userAgent: string;
+  baseUrl: string;
+}): Promise<DownloadManifest> {
+  const manifest: DownloadManifest = {
+    capturedAt: new Date().toISOString(),
+    baseUrl: opts.baseUrl,
+    downloaded: [],
+    failed: [],
+    skippedDataUrls: 0,
+  };
+
+  const raw = JSON.parse(readFileSync(opts.mediaJsonPath, "utf8")) as {
+    media?: Array<
+      | { type: string; src?: string | null; poster?: string | null }
+      | { type: string; src: string }
+    >;
+  };
+
+  const urls = new Set<string>();
+  for (const m of raw.media ?? []) {
+    if (m.type === "img" && "src" in m && m.src) urls.add(m.src);
+    if (m.type === "video") {
+      if ("src" in m && m.src) urls.add(m.src);
+      if ("poster" in m && m.poster) urls.add(m.poster);
+    }
+    if (m.type === "source" && "src" in m && m.src) urls.add(m.src);
+  }
+
+  const MAX_FILES = 72;
+  const MAX_BYTES = 12 * 1024 * 1024;
+  let n = 0;
+  const concurrency = 4;
+  const queue = [...urls].filter((u) => {
+    if (u.startsWith("data:")) {
+      manifest.skippedDataUrls++;
+      return false;
+    }
+    try {
+      const parsed = new URL(u);
+      return parsed.protocol === "https:" || parsed.protocol === "http:";
+    } catch {
+      return false;
+    }
+  });
+
+  mkdirSync(opts.destDir, { recursive: true });
+
+  async function worker(batch: string[]) {
+    for (const url of batch) {
+      if (n >= MAX_FILES) break;
+      const ok = await downloadOne(url, opts.destDir, opts.userAgent, MAX_BYTES);
+      if (ok.ok) {
+        manifest.downloaded.push({ url, relativePath: ok.relativePath, bytes: ok.bytes });
+        n++;
+      } else {
+        manifest.failed.push({ url, reason: ok.reason });
+      }
+    }
+  }
+
+  for (let i = 0; i < queue.length; i += concurrency) {
+    await worker(queue.slice(i, i + concurrency));
+  }
+
+  return manifest;
+}
+
+async function downloadOne(
+  url: string,
+  destDir: string,
+  userAgent: string,
+  maxBytes: number,
+): Promise<
+  { ok: true; relativePath: string; bytes: number } | { ok: false; reason: string }
+> {
+  try {
+    const res = await fetch(url, {
+      headers: { "User-Agent": userAgent, Accept: "*/*" },
+      redirect: "follow",
+    });
+    if (!res.ok) return { ok: false, reason: `HTTP ${res.status}` };
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (buf.length > maxBytes) return { ok: false, reason: "too large" };
+    const hash = createHash("sha256").update(url).digest("hex").slice(0, 12);
+    const ext = guessExt(url, res.headers.get("content-type"));
+    const fileName = `${hash}${ext}`;
+    const path = join(destDir, fileName);
+    writeFileSync(path, buf);
+    const rel = `files/${fileName}`;
+    return { ok: true, relativePath: rel.replace(/\\/g, "/"), bytes: buf.length };
+  } catch (e) {
+    return { ok: false, reason: (e as Error).message };
+  }
+}
+
+function guessExt(url: string, contentType: string | null): string {
+  try {
+    const fromPath = extname(new URL(url).pathname.split("?")[0] ?? "");
+    if (/^\.\w{2,5}$/.test(fromPath)) return fromPath.slice(0, 10);
+  } catch {
+    /* ignore */
+  }
+
+  if (!contentType) return ".bin";
+  if (contentType.includes("jpeg")) return ".jpg";
+  if (contentType.includes("png")) return ".png";
+  if (contentType.includes("webp")) return ".webp";
+  if (contentType.includes("gif")) return ".gif";
+  if (contentType.includes("svg")) return ".svg";
+  if (contentType.includes("mp4")) return ".mp4";
+  if (contentType.includes("webm")) return ".webm";
+  return ".bin";
+}

package/packages/extract/cloner-research-emit.ts

@@ -0,0 +1,270 @@
+/**
+ * Emits research artifacts under each extract run, aligned in layout and intent
+ * with the AI Website Cloner template (topology, behaviors bible, per-section
+ * specs). Values are derived from Landingfram's automated crawl where available;
+ * interactive sweeps still require manual Browser MCP work for full fidelity.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import type { ExtractionRun, SectionLayout, SiteLayout } from "./types.js";
+import { hostSlug } from "./host-slug.js";
+
+export function emitClonerResearch(
+  run: ExtractionRun,
+  layoutsByHost: Map<string, SiteLayout>,
+): string[] {
+  const written: string[] = [];
+  const root = join(run.outputDir, "docs", "research");
+  mkdirSync(root, { recursive: true });
+
+  written.push(
+    writeFile(
+      join(root, "README.md"),
+      emitResearchReadme(run, layoutsByHost.size > 0),
+    ),
+  );
+
+  for (const cap of run.captures) {
+    if (cap.status !== "ok") continue;
+    const layout = layoutsByHost.get(cap.host);
+    const hostDir = join(root, hostSlug(cap.host));
+    mkdirSync(join(hostDir, "components"), { recursive: true });
+
+    written.push(
+      writeFile(join(hostDir, "PAGE_TOPOLOGY.md"), emitTopology(cap.url, cap.host, layout)),
+    );
+    written.push(
+      writeFile(
+        join(hostDir, "BEHAVIORS.md"),
+        emitBehaviors(cap.url, cap.host, run, layout),
+      ),
+    );
+
+    if (layout) {
+      for (const section of layout.sections) {
+        const name = `${section.id}-${section.role}`.replace(/[^a-z0-9-]+/gi, "-");
+        written.push(
+          writeFile(
+            join(hostDir, "components", `${name}.spec.md`),
+            emitSectionSpec(cap.host, layout, section),
+          ),
+        );
+      }
+    }
+  }
+
+  return written;
+}
+
+function writeFile(path: string, body: string): string {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, body, "utf8");
+  return path;
+}
+
+function automatedJsonAppend(outputDir: string, host: string): string {
+  const slug = hostSlug(host);
+  const base = join(outputDir, "docs", "design-references", slug);
+  const probe = join(base, "header-scroll-probe.json");
+  const hints = join(base, "interaction-hints.json");
+  const chunks: string[] = [];
+  if (existsSync(probe)) {
+    chunks.push("\n### Embedded: header-scroll-probe.json\n\n```json\n");
+    chunks.push(readFileSync(probe, "utf8").trimEnd());
+    chunks.push("\n```\n");
+  }
+  if (existsSync(hints)) {
+    chunks.push("\n### Embedded: interaction-hints.json\n\n```json\n");
+    chunks.push(readFileSync(hints, "utf8").trimEnd());
+    chunks.push("\n```\n");
+  }
+  const manifest = join(outputDir, "downloaded_assets", slug, "manifest.json");
+  if (existsSync(manifest)) {
+    chunks.push(
+      `\n### Asset downloads\n\nLocal manifest: \`downloaded_assets/${slug}/manifest.json\`\n`,
+    );
+  }
+  return chunks.join("");
+}
+
+function emitResearchReadme(run: ExtractionRun, hasLayouts: boolean): string {
+  const idea =
+    run.saasIdea?.trim() ||
+    "_No SaaS idea passed. Re-run with:_ `npx launchframe <url> \"your idea\"` _or_ `--idea \"...\"`.";
+
+  const layoutNote = hasLayouts
+    ? ""
+    : "\n**Note:** No `SiteLayout` was available for any host (DOM crawl may have failed). Topology files are stubbed; rely on `reference/<host>/` + tokens.\n";
+
+  return `# Research artifacts
+
+This folder mirrors the **artifact roles** of [ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template) (\`PAGE_TOPOLOGY.md\`, \`BEHAVIORS.md\`, \`components/*.spec.md\`) so coding agents can follow the same **recon → specs → build** cadence.
+
+**Run:** \`${run.runId}\`  
+**Output:** \`${run.outputDir.replace(/\\/g, "/")}\`
+
+## Operator SaaS idea
+
+${idea}
+
+## Per-host paths
+
+For each captured host: \`<host>/PAGE_TOPOLOGY.md\`, \`<host>/BEHAVIORS.md\`, \`<host>/components/*.spec.md\`
+
+Screenshots for visual QA live in \`../design-references/<host-slug>/\` (multi-viewport + scroll sweep). Downloaded binaries (when enabled): \`../downloaded_assets/<host-slug>/manifest.json\`.
+${layoutNote}`;
+}
+
+function emitTopology(url: string, host: string, layout: SiteLayout | undefined): string {
+  const lines: string[] = [
+    `# Page topology`,
+    ``,
+    `- **URL:** ${url}`,
+    `- **Host:** ${host}`,
+    `- **Generated by:** Landingfram automated crawl (primary viewport + optional responsive passes under \`docs/design-references/\`)`,
+    ``,
+    `## Section order (top → bottom)`,
+    ``,
+  ];
+
+  if (!layout?.sections.length) {
+    lines.push(
+      `_No section model — see \`reference/${host}/structure-outline.txt\` and \`dom-structure.json\`._`,
+    );
+    return lines.join("\n");
+  }
+
+  for (const s of layout.sections) {
+    const [x, y, w, h] = s.bbox;
+    lines.push(
+      `### ${s.id} — ${s.role}`,
+      `- **Composition:** ${s.composition}`,
+      `- **Density:** ${s.density}`,
+      `- **BBox (normalized):** x=${x.toFixed(3)}, y=${y.toFixed(3)}, w=${w.toFixed(3)}, h=${h.toFixed(3)}`,
+      `- **Slots:** ${s.slots.map((sl) => `${sl.kind}×${sl.count}`).join(", ") || "_none_"}`,
+      `- **Notes:** ${s.notes.join("; ") || "—"}`,
+      ``,
+    );
+  }
+
+  lines.push(
+    `## Fixed / sticky overlays`,
+    ``,
+    `_Not inferred automatically. Inspect \`reference/${host}/page.html\` or re-scan with Browser MCP per [clone-website skill](https://github.com/JCodesMore/ai-website-cloner-template/blob/master/.claude/skills/clone-website/SKILL.md)._`,
+    ``,
+  );
+
+  return lines.join("\n");
+}
+
+function emitBehaviors(
+  url: string,
+  host: string,
+  run: ExtractionRun,
+  layout: SiteLayout | undefined,
+): string {
+  const vpLine = layout?.viewport
+    ? `${layout.viewport.width}×${layout.viewport.height}px`
+    : "See crawl viewport in run.json / raw/*.layout.json";
+
+  return `# Behaviors bible
+
+- **URL:** ${url}
+- **Capture viewport:** ${vpLine}
+
+## What Landingfram captured automatically
+
+- Single desktop pass in headless Chromium with **reduced motion** forced for deterministic screenshots.
+- **Automated multi-viewport + scroll sweep** PNGs under \`docs/design-references/${hostSlug(host)}/\` (desktop/tablet/mobile + scroll frames).
+- **Header scroll probe** (\`header-scroll-probe.json\`) and **interaction hints** (\`interaction-hints.json\`) — check for scroll-driven chrome, Lenis-like wrappers, scroll-snap.
+- Computed-style tokens and a typed **section scaffold** when DOM crawl succeeds (\`raw/${host}.layout.json\`, \`mirror/${host}/page.tsx\`).
+${automatedJsonAppend(run.outputDir, host)}
+
+## What still needs a manual interaction sweep
+
+Use Browser MCP (or the upstream **clone-website** workflow) to fill gaps — match their checklist:
+
+1. **Scroll sweep** — header shrink, scroll-driven tabs, scroll-snap, sticky sidebars, Lenis / Locomotive markers.
+2. **Click sweep** — modals, dropdowns, tab panels; extract **every** tab state.
+3. **Hover sweep** — transitions (duration + easing), not just before/after colors.
+4. **Responsive sweep** — 1440 / 768 / 390 viewports with breakpoint notes.
+
+Document findings below as you discover them.
+
+## Recorded behaviors (manual)
+
+| Area | Interaction model | Trigger | State A | State B | Transition |
+|------|---------------------|---------|---------|---------|------------|
+| _(empty)_ | | | | | |
+
+---
+
+## Operator SaaS idea
+
+${run.saasIdea?.trim() || "_Pass `--idea` or a second positional string when invoking landingfram._"}
+
+When rebuilding UI, preserve **interaction models** from this table (once filled); rewrite **copy** to match the SaaS idea without impersonating the reference brand.
+`;
+}
+
+function emitSectionSpec(host: string, layout: SiteLayout, s: SectionLayout): string {
+  const mirrorHint = `mirror/${host}/page.tsx — section marker starts with \`${s.id}:\` inside data-mirror-section`;
+  const slotsMd = s.slots.map((sl) => `- **${sl.kind}** × ${sl.count}`).join("\n");
+
+  return `# Section specification — ${s.id}
+
+## Overview
+
+- **Source URL:** ${layout.url}
+- **Mirror:** \`${mirrorHint}\`
+- **Interaction model:** _unknown — infer via scroll-first sweep per clone-website skill; default treated as **static** for this automated extract._
+
+## Section summary
+
+- **Role:** ${s.role}
+- **Composition:** ${s.composition}
+- **Density:** ${s.density}
+
+## Layout hints (from crawl)
+
+### Container style hints
+
+- **Background:** ${s.styles.backgroundHex ?? "—"}
+- **Foreground:** ${s.styles.foregroundHex ?? "—"}
+- **Padding block:** top ${s.styles.paddingTopPx ?? "—"}px / bottom ${s.styles.paddingBottomPx ?? "—"}px
+
+### Site tokens (page-level)
+
+- **Body font:** ${layout.tokens.bodyFontFamily}
+- **Heading font:** ${layout.tokens.headingFontFamily}
+- **Background / foreground:** ${layout.tokens.backgroundHex} / ${layout.tokens.foregroundHex}
+- **Primary:** ${layout.tokens.primaryHex}
+- **Radius:** ${layout.tokens.radiusPx}px
+
+## Slots (mirror placeholders)
+
+${slotsMd || "_None_"}
+
+Fill each \`<TextSlot>\` / \`<MediaSlot>\` using **verbatim** strings from \`reference/${host}/visible-text.txt\` only when you own rights or are authorized; otherwise substitute original copy aligned with the operator SaaS idea.
+
+## States & behaviors
+
+_N/A for automated single-state crawl — add rows after MCP extraction._
+
+## Assets
+
+- Crawl index: \`reference/${host}/media.json\` (respect licensing).
+- When downloads ran (no \`--no-download\`): \`downloaded_assets/${hostSlug(host)}/manifest.json\` maps remote URLs to \`files/*\`.
+
+## Responsive behavior
+
+Automated PNGs live under \`docs/design-references/${hostSlug(host)}/\` (tablet 768×900, mobile 390×844, scroll sweep). Refine breakpoints using those artifacts alongside the mirror scaffold.
+
+## Text content
+
+See \`reference/${host}/visible-text.json\` / \`.txt\`. Map strings into slots by section order and landmark roles.
+
+`;
+}

package/packages/extract/emit.ts

@@ -44,7 +44,7 @@ function write(dir: string, file: string, contents: string): string {
 
 function emitTailwindConfig(system: DesignSystem): string {
   return `/**
- * Tailwind theme extracted by launchframe.
+ * Tailwind theme extracted by landingfram.
  * Run id: ${system.runId}
  *
  * Sources (inspirational only, no source code or assets reused):
@@ -126,7 +126,7 @@ function heightFor(step: string, system: DesignSystem): string {
 
 function emitGlobalsCss(system: DesignSystem): string {
   return `/**
- * Drop-in CSS variables produced by launchframe.
+ * Drop-in CSS variables produced by landingfram.
  * Compatible with shadcn/ui's --background / --foreground / etc. tokens.
  */
 
@@ -424,6 +424,19 @@ function emitForAi(system: DesignSystem, run: ExtractionRun): string {
   const ok = run.captures.filter((c) => c.status === "ok");
   const hasReference = ok.some((c) => c.referenceDir);
   const hasMirror = ok.some((c) => c.mirrorDir);
+  const ideaSection = run.saasIdea?.trim()
+    ? `
+
+## Operator SaaS idea (from CLI)
+
+${run.saasIdea.trim()}
+
+Use this narrative when replacing mirror placeholders and reference copy: headings, subheads, and CTAs should describe **your** product. Do not present another brand's trademarks or product name as yours.
+`
+    : "";
+  const intentPaste =
+    run.saasIdea?.trim() ??
+    "[describe goal — faithful mirror of URL vs new product in same layout; tone and CTA]";
   const perHost = ok
     .filter((c) => c.referenceDir || c.mirrorDir)
     .map((c) => {
@@ -470,6 +483,10 @@ Attach this entire \`output/${system.runId}/\` folder (or copy it into the app r
 **When rebuilding from a crawled URL, also attach (per host):**  
 \`reference/<host>/\` **and** \`mirror/<host>/\` — the model must see both **verbatim DOM/copy** and the **typed React scaffold**.
 
+**For clone-style parallel builders:** attach \`docs/research/\` (per-host topology, behaviors checklist, component specs).
+
+**Automated recon (design references):** \`docs/design-references/<host-slug>/\` — desktop/tablet/mobile captures, scroll sweep frames, header scroll probe, interaction hints — plus optional \`downloaded_assets/<host-slug>/manifest.json\`.
+
 In **Cursor**, \`@\` those paths explicitly.
 
 ## Authority order
@@ -477,7 +494,9 @@ In **Cursor**, \`@\` those paths explicitly.
 1. **Structural fidelity:** \`reference/<host>/dom-structure.json\` + \`page.html\` + \`visible-text.*\` + \`mirror/<host>/page.tsx\` — exact DOM tree shape, then copy and typed scaffold.
 2. **Design tokens:** **REPORT.md** and **tokens.json** — typography scale, spacing, radii, colors, container width, notes.
 3. **Integration:** **tailwind.config.ts** + **globals.css** — merge into a Next.js + Tailwind + shadcn-style app.
-${structureSection}
+4. **Builder specs:** **docs/research/** — per-host \`PAGE_TOPOLOGY.md\`, \`BEHAVIORS.md\`, \`components/*.spec.md\`.
+5. **Visual parity:** **docs/design-references/** — screenshots + automated probes for scroll/chrome behavior (supplement with manual MCP for tab/modal states).
+${ideaSection}${structureSection}
 ## Instruction block (paste into chat)
 
 \`\`\`text
@@ -488,13 +507,13 @@ You must use the attached \`output/${system.runId}/\` folder.
 - If reference/ and mirror/ exist for my source URL: treat them as mandatory context. Preserve **exact DOM nesting and sibling order** from \`dom-structure.json\` (and cross-check \`page.html\`). Align components to \`data-mirror-section\` and the mirror scaffold. Wire copy from visible-text.* and media from media.json unless I say to rewrite for a different product.
 - If I am building a NEW product unrelated to the crawl: keep layout inspiration from mirror/reference but REPLACE product names, claims, and sensitive copy with my copy. Never impersonate another brand.
 
-My product / intent: [describe goal — faithful mirror of URL vs new product in same layout; tone and CTA]
+My product / intent: ${intentPaste}
 \`\`\`
 
 ## After the agent runs
 
 - Compare against **theme-preview.tsx** to verify token usage.
-- Iterate with REPORT.md + reference/ + mirror/ in context.
+- Iterate with REPORT.md + reference/ + mirror/ + **docs/research/** + **docs/design-references/** in context.
 `;
 }