launchframe 0.1.5 → 0.1.7

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

@@ -170,6 +170,120 @@ export interface DesignSystem {
   notes: string[];
 }
 
+/* -------------------------------------------------------------------------- */
+/*  Layout mirror (per-site)                                                  */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Structural roles a top-level section can play. Inferred heuristically from
+ * geometry, content kinds, and document position — not from the source's
+ * class names.
+ */
+export type SectionRole =
+  | "nav"
+  | "hero"
+  | "feature-grid"
+  | "feature-deep-dive"
+  | "proof-logos"
+  | "proof-quotes"
+  | "pricing"
+  | "conversion"
+  | "footer"
+  | "other";
+
+/**
+ * Coarse composition shape used by the emitter to pick a wrapper layout.
+ */
+export type Composition =
+  | "single-column"
+  | "split-2"
+  | "grid-2"
+  | "grid-3"
+  | "grid-4"
+  | "list"
+  | "logo-row"
+  | "unknown";
+
+/**
+ * The kinds of content a section can hold. The emitter renders an
+ * appropriately-styled placeholder (`<TextSlot>` / `<MediaSlot>`) per slot
+ * so the user fills in their own copy and assets.
+ */
+export type SlotKind =
+  | "heading-1"
+  | "heading-2"
+  | "heading-3"
+  | "eyebrow"
+  | "body"
+  | "bullet"
+  | "button-primary"
+  | "button-secondary"
+  | "image"
+  | "logo-mono"
+  | "icon"
+  | "code"
+  | "badge"
+  | "input"
+  | "video";
+
+export interface SlotCount {
+  kind: SlotKind;
+  count: number;
+}
+
+/**
+ * A single top-level section in document order. Geometry is normalized to
+ * [0, 1] over the rendered page so the emitter can compare relative weight.
+ */
+export interface SectionLayout {
+  /** Stable id assigned in document order: s1, s2, ... */
+  id: string;
+  role: SectionRole;
+  composition: Composition;
+  density: "thin" | "balanced" | "dense";
+  /** Bounding box [x, y, w, h] normalized to [0, 1] over the rendered page. */
+  bbox: [number, number, number, number];
+  /** Aggregated content-kind counts inside the section. */
+  slots: SlotCount[];
+  /** Per-section style hints; the emitter applies these as inline overrides. */
+  styles: {
+    backgroundHex: string | null;
+    foregroundHex: string | null;
+    paddingTopPx: number | null;
+    paddingBottomPx: number | null;
+  };
+  /** Free-form notes the emitter surfaces in `MIRROR_NOTES.md`. */
+  notes: string[];
+}
+
+/**
+ * Page-level computed-style tokens. These complement the synthesized
+ * `DesignSystem` so a mirror page can apply a site-specific theme without
+ * the system having to reseed the cross-corpus palette.
+ */
+export interface SiteTokens {
+  bodyFontFamily: string;
+  headingFontFamily: string;
+  backgroundHex: string;
+  foregroundHex: string;
+  primaryHex: string;
+  mutedHex: string;
+  borderHex: string;
+  radiusPx: number;
+  containerPx: number | null;
+}
+
+export interface SiteLayout {
+  url: string;
+  host: string;
+  capturedAt: string;
+  viewport: { width: number; height: number };
+  /** Full rendered page height in CSS pixels. */
+  pageHeightPx: number;
+  sections: SectionLayout[];
+  tokens: SiteTokens;
+}
+
 /* -------------------------------------------------------------------------- */
 /*  Run summary                                                               */
 /* -------------------------------------------------------------------------- */
@@ -179,7 +293,10 @@ export interface SiteCapture {
   host: string;
   capturedAt: string;
   screenshotPath: string;
-  rawTokensPath: 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";
   reason?: string;
 }