launchframe 0.1.5 → 0.1.6

package/packages/extract/emit.ts

@@ -9,8 +9,8 @@
  *   globals.css         — shadcn-compatible CSS variables (light + dark)
  *   theme-preview.tsx   — a self-contained React component that renders
  *                         every token so you can eyeball the system
- *   REPORT.md           — what was extracted, from where, with the
- *                         anti-clone disclaimer
+ *   REPORT.md           — what was extracted, from where, and how the
+ *                         output is meant to be used
  */
 
 import { mkdirSync, writeFileSync } from "node:fs";

package/packages/extract/extract.ts

@@ -4,16 +4,23 @@
  *   npm run extract -- https://site-a.com https://site-b.com https://site-c.com
  *
  * For each URL: open in Chromium, screenshot, harvest computed design
- * tokens via `browser-extract.ts`. After all sites: synthesize an
- * original shadcn-compatible design system and emit drop-in files.
+ * tokens via `browser-extract.ts`, and crawl the rendered DOM into a
+ * typed `SiteLayout` model via `dom-crawler.ts`. After all sites:
+ *   - Synthesize a drop-in shadcn-compatible design system from the
+ *     aggregated tokens.
+ *   - Emit a per-site **layout mirror**: a Next.js page that reconstructs
+ *     the source's section structure from typed primitives, with
+ *     `<TextSlot>` / `<MediaSlot>` placeholders for the user's copy and
+ *     brand assets.
  *
  * Output goes to `output/<runId>/`.
  *
- * Policy (from rules/anti-clone-policy.md):
- *   - Honor robots.txt by default.
- *   - Per-domain rate limit defaults to 15 req/min.
- *   - Store only PNG screenshots and harvested computed-style values.
- *   - Never persist HTML, JS, CSS, or third-party assets.
+ * Operational defaults (configurable via flags):
+ *   - 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.
  */
 
 import { mkdirSync, writeFileSync } from "node:fs";
@@ -23,9 +30,11 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 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 { synthesize } from "./synthesize.js";
-import type { ExtractionRun, RawTokens, SiteCapture } from "./types.js";
+import type { ExtractionRun, RawTokens, SiteCapture, SiteLayout } from "./types.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -90,9 +99,18 @@ function printHelp(): void {
       "Writes to ./output/<runId>/ in your current working directory unless",
       "you pass --out.",
       "",
-      "Captures each URL at a desktop viewport, harvests computed design",
-      "tokens (colors, type, spacing, radius, shadow), and synthesizes a",
-      "drop-in shadcn-compatible design system in output/<runId>/.",
+      "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.",
+      "",
+      "After every URL, a drop-in shadcn-compatible design system is",
+      "synthesized from the aggregated tokens and written to output/<runId>/.",
       "",
       "Options:",
       "  --out <dir>          Output directory (default: output/<runId>)",
@@ -178,11 +196,13 @@ async function captureOne(
   url: string,
   viewport: { width: number; height: number },
   outDir: string,
-): Promise<{ raw: RawTokens; capture: SiteCapture } | null> {
+): Promise<{ raw: RawTokens; layout: SiteLayout | null; capture: SiteCapture } | null> {
   const host = new URL(url).host;
   const stamp = `${host}.png`;
   const screenshotPath = join(outDir, "screenshots", stamp);
   const rawPath = join(outDir, "raw", `${host}.tokens.json`);
+  const layoutPath = join(outDir, "raw", `${host}.layout.json`);
+  const mirrorDir = join(outDir, "mirror", host);
 
   const ctx = await browser.newContext({
     userAgent: USER_AGENT,
@@ -215,18 +235,32 @@ async function captureOne(
     mkdirSync(dirname(rawPath), { recursive: true });
     writeFileSync(rawPath, JSON.stringify(raw, null, 2));
 
+    let layout: SiteLayout | null = null;
+    let mirrorWritten: string[] = [];
+    try {
+      layout = await crawlLayout(page, url, viewport);
+      mkdirSync(dirname(layoutPath), { recursive: true });
+      writeFileSync(layoutPath, JSON.stringify(layout, null, 2));
+      mirrorWritten = emitMirror(layout, mirrorDir);
+    } catch (err) {
+      console.warn(`  ! layout crawl failed for ${url}: ${(err as Error).message}`);
+    }
+
     const capture: SiteCapture = {
       url,
       host,
       capturedAt: raw.capturedAt,
       screenshotPath,
       rawTokensPath: rawPath,
+      ...(layout ? { layoutPath } : {}),
+      ...(mirrorWritten.length > 0 ? { mirrorDir } : {}),
       status: "ok",
     };
-    return { raw, capture };
+    return { raw, layout, capture };
   } catch (err) {
     return {
       raw: emptyRaw(url, viewport),
+      layout: null,
       capture: {
         url,
         host,
@@ -303,7 +337,11 @@ async function main(): Promise<void> {
       captures.push(result.capture);
       if (result.capture.status === "ok") {
         rawList.push(result.raw);
-        console.log(`  ✓ ${url}`);
+        const tag = result.layout ? "mirror" : "tokens-only";
+        const sectionCount = result.layout?.sections.length ?? 0;
+        console.log(
+          `  ✓ ${url}  → ${tag}${result.layout ? ` (${sectionCount} sections)` : ""}`,
+        );
       } else {
         console.log(`  ✗ ${url}  ${result.capture.reason ?? ""}`);
       }
@@ -339,9 +377,21 @@ async function main(): Promise<void> {
   console.log("[extract] wrote:");
   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!);
+  if (mirrorDirs.length > 0) {
+    console.log("");
+    console.log("[extract] layout mirrors:");
+    for (const d of mirrorDirs) console.log(`  → ${d}/page.tsx`);
+  }
   console.log("");
-  console.log(`[extract] done. Open ${join(outDir, "REPORT.md")} for the summary.`);
-  console.log(`[extract] Give your AI: ${join(outDir, "FOR_AI.md")}`);
+  console.log(`[extract] done. Open ${join(outDir, "REPORT.md")} for the design-system summary.`);
+  if (mirrorDirs.length > 0) {
+    console.log(
+      `[extract] each mirror folder ships a Next.js page.tsx + MIRROR_NOTES.md.`,
+    );
+    console.log(`[extract] fill the <TextSlot> / <MediaSlot> placeholders with your own content.`);
+  }
+  console.log(`[extract] AI handoff: ${join(outDir, "FOR_AI.md")}`);
 }
 
 function makeRunId(startedAt: string, name: string | undefined): string {

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");
+}