launchframe 0.1.4 → 0.1.6

package/packages/extract/mirror-emit.ts

@@ -0,0 +1,522 @@
+/**
+ * Mirror emitter.
+ *
+ * Consumes a typed `SiteLayout` (produced by `dom-crawler.ts`) and writes:
+ *   - `<dir>/page.tsx`      — a Next.js page that reconstructs the source's
+ *                              section tree, grid composition, and density
+ *                              from typed primitives, with `<TextSlot>` /
+ *                              `<MediaSlot>` placeholders for content.
+ *   - `<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.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type {
+  Composition,
+  SectionLayout,
+  SectionRole,
+  SiteLayout,
+  SlotCount,
+  SlotKind,
+  SiteTokens,
+} from "./types.js";
+
+export function emitMirror(layout: SiteLayout, outDir: string): string[] {
+  mkdirSync(outDir, { recursive: true });
+  const written: string[] = [];
+
+  const pagePath = join(outDir, "page.tsx");
+  writeFileSync(pagePath, emitPage(layout));
+  written.push(pagePath);
+
+  const layoutPath = join(outDir, "layout.json");
+  writeFileSync(layoutPath, JSON.stringify(layout, null, 2) + "\n");
+  written.push(layoutPath);
+
+  const notesPath = join(outDir, "MIRROR_NOTES.md");
+  writeFileSync(notesPath, emitNotes(layout));
+  written.push(notesPath);
+
+  return written;
+}
+
+/* -------------------------------------------------------------------------- */
+/*  page.tsx                                                                  */
+/* -------------------------------------------------------------------------- */
+
+function emitPage(layout: SiteLayout): string {
+  const componentName = toPascalCase(layout.host.replace(/[^a-z0-9]/gi, "-")) + "Mirror";
+
+  const sectionExprs = layout.sections.map((s, i) =>
+    emitSection(s, layout.tokens, i),
+  );
+
+  return [
+    "/**",
+    ` * Mirror page for ${layout.url}`,
+    ` * Captured ${layout.capturedAt}`,
+    ` * Viewport ${layout.viewport.width}×${layout.viewport.height}`,
+    " *",
+    " * 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.',
+    " */",
+    "",
+    'import {',
+    "  FadeUp,",
+    "  MediaSlot,",
+    "  Stagger,",
+    "  StaggerItem,",
+    "  TextSlot,",
+    "  cn,",
+    "} from \"@framework/blocks\";",
+    "",
+    `export const meta = ${JSON.stringify(
+      {
+        kind: "mirror",
+        source: layout.url,
+        capturedAt: layout.capturedAt,
+        sections: layout.sections.map((s) => ({
+          id: s.id,
+          role: s.role,
+          composition: s.composition,
+          density: s.density,
+        })),
+      },
+      null,
+      2,
+    )} as const;`,
+    "",
+    `export default function ${componentName}() {`,
+    "  return (",
+    `    <div className="mirror-root">`,
+    `      <style>{${JSON.stringify(emitScopedTokens(layout.tokens))}}</style>`,
+    ...sectionExprs.map((expr) => "      " + expr.split("\n").join("\n      ")),
+    "    </div>",
+    "  );",
+    "}",
+    "",
+  ].join("\n");
+}
+
+function emitScopedTokens(tokens: SiteTokens): string {
+  const radius = `${(tokens.radiusPx / 16).toFixed(3)}rem`;
+  const containerPx = tokens.containerPx ?? 1120;
+  return [
+    `.mirror-root {`,
+    `  --mirror-background: ${tokens.backgroundHex};`,
+    `  --mirror-foreground: ${tokens.foregroundHex};`,
+    `  --mirror-primary: ${tokens.primaryHex};`,
+    `  --mirror-muted: ${tokens.mutedHex};`,
+    `  --mirror-border: ${tokens.borderHex};`,
+    `  --mirror-radius: ${radius};`,
+    `  --mirror-container: ${containerPx}px;`,
+    `  --mirror-font-body: ${escapeFontFamily(tokens.bodyFontFamily)};`,
+    `  --mirror-font-heading: ${escapeFontFamily(tokens.headingFontFamily)};`,
+    `  background: var(--mirror-background);`,
+    `  color: var(--mirror-foreground);`,
+    `  font-family: var(--mirror-font-body);`,
+    `}`,
+    `.mirror-root h1, .mirror-root h2, .mirror-root h3 {`,
+    `  font-family: var(--mirror-font-heading);`,
+    `}`,
+    `.mirror-section { padding-block: 5rem; }`,
+    `@media (min-width: 768px) { .mirror-section { padding-block: 7rem; } }`,
+    `.mirror-container { max-width: var(--mirror-container); margin-inline: auto; padding-inline: 1.5rem; }`,
+  ].join("\n");
+}
+
+function escapeFontFamily(family: string): string {
+  const trimmed = family.replace(/^["']|["']$/g, "");
+  if (/^[a-zA-Z0-9_-]+$/.test(trimmed)) return `${trimmed}, system-ui, sans-serif`;
+  return `"${trimmed}", system-ui, sans-serif`;
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Per-section rendering                                                     */
+/* -------------------------------------------------------------------------- */
+
+function emitSection(s: SectionLayout, tokens: SiteTokens, index: number): string {
+  const wrapperBg = s.styles.backgroundHex ?? tokens.backgroundHex;
+  const padTop = s.styles.paddingTopPx ?? null;
+  const padBottom = s.styles.paddingBottomPx ?? null;
+  const styleAttr = emitStyleAttr({
+    backgroundColor: wrapperBg,
+    paddingTop: padTop !== null ? `${padTop}px` : undefined,
+    paddingBottom: padBottom !== null ? `${padBottom}px` : undefined,
+  });
+
+  const labelId = `${s.id}-heading`;
+  const inner = emitSectionInner(s, labelId);
+
+  return [
+    `<section`,
+    `  aria-labelledby=${JSON.stringify(labelId)}`,
+    `  data-mirror-section=${JSON.stringify(`${s.id}:${s.role}:${s.composition}:${s.density}`)}`,
+    `  className=${JSON.stringify(sectionWrapperClass(s.role, index))}`,
+    styleAttr ? `  style={${styleAttr}}` : "",
+    `>`,
+    `  <div className="mirror-container">`,
+    inner.split("\n").map((l) => "    " + l).join("\n"),
+    `  </div>`,
+    `</section>`,
+  ]
+    .filter((s) => s.length > 0)
+    .join("\n");
+}
+
+function emitStyleAttr(style: {
+  backgroundColor?: string | null;
+  paddingTop?: string | undefined;
+  paddingBottom?: string | undefined;
+}): string {
+  const entries: string[] = [];
+  if (style.backgroundColor)
+    entries.push(`backgroundColor: ${JSON.stringify(style.backgroundColor)}`);
+  if (style.paddingTop) entries.push(`paddingTop: ${JSON.stringify(style.paddingTop)}`);
+  if (style.paddingBottom)
+    entries.push(`paddingBottom: ${JSON.stringify(style.paddingBottom)}`);
+  if (entries.length === 0) return "";
+  return `{ ${entries.join(", ")} }`;
+}
+
+function sectionWrapperClass(role: SectionRole, index: number): string {
+  const base = "mirror-section";
+  if (role === "nav") return `${base} border-b border-border py-4 md:py-4`;
+  if (role === "footer") return `${base} border-t border-border bg-muted/30`;
+  if (role === "hero" && index === 0) return `${base} border-b border-border`;
+  return `${base} border-b border-border`;
+}
+
+function emitSectionInner(s: SectionLayout, labelId: string): string {
+  switch (s.composition) {
+    case "split-2":
+      return emitSplitTwo(s, labelId);
+    case "grid-2":
+    case "grid-3":
+    case "grid-4":
+      return emitGrid(s, labelId);
+    case "logo-row":
+      return emitLogoRow(s);
+    case "list":
+      return emitList(s, labelId);
+    case "single-column":
+    case "unknown":
+    default:
+      return emitSingleColumn(s, labelId);
+  }
+}
+
+function gridCols(composition: Composition): number {
+  if (composition === "grid-2") return 2;
+  if (composition === "grid-3") return 3;
+  if (composition === "grid-4") return 4;
+  return 1;
+}
+
+/* ---------- composition templates ---------- */
+
+function emitSingleColumn(s: SectionLayout, labelId: string): string {
+  const slots = slotMap(s.slots);
+  const head: string[] = [];
+
+  const eyebrow = slots.eyebrow ?? 0;
+  for (let i = 0; i < eyebrow; i++) head.push(textSlot("eyebrow"));
+
+  if ((slots["heading-1"] ?? 0) > 0) {
+    head.push(textSlot("heading-1", { id: labelId, count: slots["heading-1"]! }));
+  } else if ((slots["heading-2"] ?? 0) > 0) {
+    head.push(textSlot("heading-2", { id: labelId, count: 1 }));
+  }
+  const body = slots.body ?? 0;
+  for (let i = 0; i < Math.min(body, 3); i++) head.push(textSlot("body"));
+
+  const buttons: 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 buttonsBlock =
+    buttons.length > 0
+      ? `<div className="mt-8 flex flex-wrap items-center gap-3">\n${indent(buttons.join("\n"), 2)}\n</div>`
+      : "";
+  const mediaBlock = emitMediaSlots(slots);
+
+  return [headBlock, buttonsBlock, mediaBlock].filter(Boolean).join("\n");
+}
+
+function emitSplitTwo(s: SectionLayout, labelId: string): string {
+  const slots = slotMap(s.slots);
+  const textChildren: string[] = [];
+  if ((slots.eyebrow ?? 0) > 0) textChildren.push(textSlot("eyebrow"));
+  if ((slots["heading-1"] ?? 0) > 0) {
+    textChildren.push(textSlot("heading-1", { id: labelId }));
+  } else if ((slots["heading-2"] ?? 0) > 0) {
+    textChildren.push(textSlot("heading-2", { id: labelId }));
+  }
+  const body = slots.body ?? 0;
+  for (let i = 0; i < Math.min(body, 2); i++) textChildren.push(textSlot("body"));
+
+  const bullets = slots.bullet ?? 0;
+  if (bullets > 0) {
+    const items: string[] = [];
+    for (let i = 0; i < Math.min(bullets, 5); i++) items.push(textSlot("bullet"));
+    textChildren.push(
+      [
+        '<ul className="mt-6 space-y-2 text-sm">',
+        ...items.map((it) => indent(it, 1)),
+        "</ul>",
+      ].join("\n"),
+    );
+  }
+
+  const buttons: string[] = [];
+  if ((slots["button-primary"] ?? 0) > 0) buttons.push(textSlot("button-primary"));
+  if ((slots["button-secondary"] ?? 0) > 0) buttons.push(textSlot("button-secondary"));
+  if (buttons.length > 0) {
+    textChildren.push(
+      [
+        '<div className="mt-8 flex flex-wrap items-center gap-3">',
+        ...buttons.map((b) => indent(b, 1)),
+        "</div>",
+      ].join("\n"),
+    );
+  }
+
+  const textCol = wrapFadeUp(textChildren.join("\n"));
+  const mediaCol = wrapFadeUp(emitMediaSlots(slots, { aspect: "video" }) || mediaSlot("image"));
+
+  return [
+    '<div className="grid items-center gap-12 md:grid-cols-2">',
+    `  <div>${"\n" + indent(textCol, 2) + "\n  "}</div>`,
+    `  <div>${"\n" + indent(mediaCol, 2) + "\n  "}</div>`,
+    "</div>",
+  ].join("\n");
+}
+
+function emitGrid(s: SectionLayout, labelId: string): string {
+  const slots = slotMap(s.slots);
+  const cols = gridCols(s.composition);
+
+  const heading =
+    (slots["heading-1"] ?? 0) > 0
+      ? textSlot("heading-1", { id: labelId })
+      : (slots["heading-2"] ?? 0) > 0
+        ? textSlot("heading-2", { id: labelId })
+        : "";
+  const introBody =
+    (slots.body ?? 0) > 0 ? `<div className="mt-4">${textSlot("body")}</div>` : "";
+
+  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" })}`,
+        `    ${textSlot(cardHeading)}`,
+        `    ${textSlot("body")}`,
+        "  </StaggerItem>",
+      ].join("\n"),
+    ),
+    "</Stagger>",
+  ];
+
+  const head = [
+    heading ? wrapFadeUp(heading) : "",
+    introBody,
+  ]
+    .filter(Boolean)
+    .join("\n");
+
+  return [head, grid.join("\n")].filter(Boolean).join("\n");
+}
+
+function emitLogoRow(s: SectionLayout): string {
+  const slots = slotMap(s.slots);
+  const count = Math.max(4, Math.min(slots["logo-mono"] ?? 6, 8));
+  const items: string[] = [];
+  for (let i = 0; i < count; i++) {
+    items.push(mediaSlot("logo-mono", { aspect: "auto", className: "h-7 w-24" }));
+  }
+  return [
+    '<div className="text-center text-xs font-semibold uppercase tracking-wider text-muted-foreground">',
+    "  <TextSlot kind=\"eyebrow\" />",
+    "</div>",
+    '<div className="mt-8 grid grid-cols-2 items-center justify-items-center gap-x-10 gap-y-6 sm:grid-cols-3 md:grid-cols-6">',
+    ...items.map((it) => `  ${it}`),
+    "</div>",
+  ].join("\n");
+}
+
+function emitList(s: SectionLayout, labelId: string): string {
+  const slots = slotMap(s.slots);
+  const heading =
+    (slots["heading-1"] ?? 0) > 0
+      ? textSlot("heading-1", { id: labelId })
+      : (slots["heading-2"] ?? 0) > 0
+        ? textSlot("heading-2", { id: labelId })
+        : "";
+
+  const items: string[] = [];
+  const count = Math.max(3, Math.min(slots.bullet ?? 5, 8));
+  for (let i = 0; i < count; i++) items.push(textSlot("bullet"));
+
+  return [
+    heading ? wrapFadeUp(heading) : "",
+    `<ul className="mt-8 space-y-3 text-sm">`,
+    ...items.map((it) => `  ${it}`),
+    "</ul>",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+/* ---------- slot helpers ---------- */
+
+function slotMap(slots: SlotCount[]): Partial<Record<SlotKind, number>> {
+  const out: Partial<Record<SlotKind, number>> = {};
+  for (const s of slots) out[s.kind] = s.count;
+  return out;
+}
+
+function textSlot(
+  kind: "eyebrow" | "heading-1" | "heading-2" | "heading-3" | "body" | "bullet" | "button-primary" | "button-secondary" | "badge",
+  opts: { id?: string; count?: number } = {},
+): string {
+  const idAttr = opts.id ? ` id=${JSON.stringify(opts.id)}` : "";
+  return `<TextSlot kind=${JSON.stringify(kind)}${idAttr} />`;
+}
+
+function mediaSlot(
+  kind: "image" | "logo-mono" | "icon" | "video" | "code",
+  opts: { aspect?: "video" | "square" | "4/3" | "21/9" | "auto"; className?: string } = {},
+): string {
+  const attrs: string[] = [`kind=${JSON.stringify(kind)}`];
+  if (opts.aspect) attrs.push(`aspect=${JSON.stringify(opts.aspect)}`);
+  if (opts.className) attrs.push(`className=${JSON.stringify(opts.className)}`);
+  return `<MediaSlot ${attrs.join(" ")} />`;
+}
+
+function emitMediaSlots(
+  slots: Partial<Record<SlotKind, number>>,
+  opts: { aspect?: "video" | "square" | "4/3" | "21/9" | "auto" } = {},
+): string {
+  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 (parts.length === 0) return "";
+  if (parts.length === 1) return `<div className="mt-12">${parts[0]}</div>`;
+  return [
+    '<div className="mt-12 grid gap-6 md:grid-cols-2">',
+    ...parts.map((p) => `  ${p}`),
+    "</div>",
+  ].join("\n");
+}
+
+function wrapFadeUp(children: string): string {
+  return [
+    "<FadeUp>",
+    indent(children, 1),
+    "</FadeUp>",
+  ].join("\n");
+}
+
+function indent(s: string, levels: number): string {
+  const pad = "  ".repeat(levels);
+  return s
+    .split("\n")
+    .map((l) => (l.length > 0 ? pad + l : l))
+    .join("\n");
+}
+
+function toPascalCase(input: string): string {
+  return input
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((w) => w[0]!.toUpperCase() + w.slice(1))
+    .join("") || "Mirror";
+}
+
+/* -------------------------------------------------------------------------- */
+/*  MIRROR_NOTES.md                                                           */
+/* -------------------------------------------------------------------------- */
+
+function emitNotes(layout: SiteLayout): string {
+  const lines: string[] = [];
+  lines.push(`# Mirror notes — ${layout.host}`);
+  lines.push("");
+  lines.push(`Source URL: ${layout.url}`);
+  lines.push(`Captured: ${layout.capturedAt}`);
+  lines.push(`Viewport: ${layout.viewport.width}×${layout.viewport.height}`);
+  lines.push(`Rendered page height: ${layout.pageHeightPx}px`);
+  lines.push("");
+  lines.push("## What was extracted");
+  lines.push("");
+  lines.push(
+    "- Top-level section tree (geometry, role, composition, density)",
+  );
+  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("");
+  lines.push("## What was **not** extracted");
+  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("");
+  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("");
+  lines.push("## Section breakdown");
+  lines.push("");
+  lines.push("| # | role | composition | density | slots |");
+  lines.push("| - | ---- | ----------- | ------- | ----- |");
+  for (const s of layout.sections) {
+    const slotSummary = s.slots
+      .map((sl) => `${sl.kind}×${sl.count}`)
+      .join(", ");
+    lines.push(
+      `| ${s.id} | ${s.role} | ${s.composition} | ${s.density} | ${slotSummary || "—"} |`,
+    );
+  }
+  lines.push("");
+  lines.push("## How to fill in slots");
+  lines.push("");
+  lines.push("```tsx");
+  lines.push('// Empty (renders dashed placeholder):');
+  lines.push('<TextSlot kind="heading-1" />');
+  lines.push("");
+  lines.push("// Filled:");
+  lines.push('<TextSlot kind="heading-1">The thing your product does, in plain language.</TextSlot>');
+  lines.push('<MediaSlot kind="image" aspect="video">');
+  lines.push("  <Image src=\"/hero.jpg\" alt=\"Hero photograph\" width={1200} height={675} />");
+  lines.push("</MediaSlot>");
+  lines.push("```");
+  lines.push("");
+  return lines.join("\n");
+}

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                                                               */
 /* -------------------------------------------------------------------------- */
@@ -180,6 +294,10 @@ export interface SiteCapture {
   capturedAt: string;
   screenshotPath: string;
   rawTokensPath: string;
+  /** Path to the per-site `SiteLayout` JSON, if the mirror crawl succeeded. */
+  layoutPath?: string;
+  /** Path to the per-site mirror page directory, if emission succeeded. */
+  mirrorDir?: string;
   status: "ok" | "skipped" | "failed";
   reason?: string;
 }