launchframe 0.1.5 → 0.1.7

package/README.md

@@ -10,10 +10,14 @@ radii, shadows), and synthesizes an original design system as
 `tailwind.config.ts` + `globals.css` + `tokens.json` + a Markdown
 report and an AI-handoff file.
 
-It is **not** a website cloning tool. It does not store HTML, JS, CSS,
-brand assets, logos, illustrations, or copywriting. Proprietary type
-families are substituted with open-source equivalents. See the
-[anti-clone policy](./rules/anti-clone-policy.md).
+It also crawls the rendered DOM into a typed `SiteLayout` and emits a
+**layout-mirror page** per source: a Next.js component that reconstructs
+the source's section tree, grid, and density from typed primitives, with
+`<TextSlot>` / `<MediaSlot>` placeholders where the source had copy,
+logos, illustrations, or product imagery. The mirror does **not** embed
+the source's copy text, brand assets, or product screenshots — fill those
+slots with your own content before shipping. Proprietary type families
+are substituted with open-source equivalents.
 
 ---
 
@@ -35,21 +39,34 @@ cd path/to/your-app-or-empty-folder
 npx launchframe@latest https://site-a.example https://site-b.example
 ```
 
-When it finishes, open **`output/<runId>/FOR_AI.md`** — it tells you
-exactly how to attach the folder in **Cursor** or **Claude Code** so
-the model follows your tokens when building UI.
+When it finishes, every source URL has produced a **layout-mirror
+page** under `output/<runId>/mirror/<host>/page.tsx`, plus a synthesized
+design system at the run root.
 
 ```txt
 output/<runId>/
 ├── FOR_AI.md            ← paste / @-attach this for your AI (handoff instructions)
-├── tokens.json          ← every value, machine-readable
+├── tokens.json          ← every aggregated value, machine-readable
 ├── tailwind.config.ts   ← drop-in Tailwind theme
 ├── globals.css          ← drop-in shadcn-compatible CSS variables
 ├── theme-preview.tsx    ← render this to eyeball the system
 ├── REPORT.md            ← what was extracted, from where, why
 ├── run.json             ← full run metadata (sources, timing, status)
 ├── screenshots/         ← captured PNGs
-└── raw/                 ← per-site raw token observations
+├── 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: Motion + Phosphor + image/video patterns
+        ├── layout.json
+        └── MIRROR_NOTES.md
 ```
 
 ---
@@ -57,10 +74,18 @@ output/<runId>/
 ## Hand the output to your AI
 
 1. Run the command above so `output/<runId>/` exists.
-2. Either:
-   - **Cursor:** `@`-attach the folder (or `FOR_AI.md` + `REPORT.md` + `tokens.json`) and paste the instruction block from `FOR_AI.md` into Composer, or
-   - **Claude Code:** copy the `output/<runId>/` folder into your project and attach it.
-3. The AI's authority order is **REPORT.md → tokens.json → merge tailwind.config.ts and globals.css into the app**. It must use semantic tokens (`bg-background`, `text-muted-foreground`, `bg-primary`, …) and write **original copy only**.
+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).
 
 ---
 
@@ -148,11 +173,11 @@ launchframe/
 │   ├── capture/               # Playwright screenshot capture (lower level)
 │   ├── analysis/              # Layout-tree extraction & section classifier
 │   ├── patterns/              # Typed pattern schemas + atlas registry loader
-│   ├── blocks/                # Original shadcn/ui blocks across families
-│   └── evaluation/            # Coherence / clone-risk / a11y evaluator
-├── pattern-atlas/             # Formalized pattern catalog per category
+│   ├── blocks/                # Shadcn/ui blocks + TextSlot / MediaSlot primitives
+│   └── evaluation/            # Coherence + responsiveness/a11y evaluator
+├── pattern-atlas/             # Pattern catalog per category (block-composition mode)
 ├── prompts/                   # Markdown prompts for AI agents
-├── rules/                     # Design / copy / anti-clone / a11y policy
+├── rules/                     # Design / copy / a11y rules
 ├── registry/                  # shadcn-compatible custom registry manifest
 └── output/                    # ← every `extract` run lands here
 ```
@@ -164,7 +189,7 @@ npm run studio         # Next.js dashboard at localhost:3000
 npm run capture        # Lower-level Playwright capture pipeline
 npm run analyze        # Run section classifier on captured screenshots
 npm run formalize      # Validate the pattern-atlas/*.json files
-npm run evaluate       # Grade a generated page (coherence/clone/a11y)
+npm run evaluate       # Grade a generated page (coherence + a11y)
 npm run typecheck      # Project-wide TypeScript check
 ```
 
@@ -172,26 +197,30 @@ npm run typecheck      # Project-wide TypeScript check
 
 ## What this is not
 
-- **Not a scraper.** It captures only what is publicly rendered, stores
-  no HTML, and never republishes site content.
-- **Not a clone tool.** Anti-clone policy is enforced by capture-side
-  policy and synthesis-side normalization.
+- **Not a verbatim site downloader.** The crawler builds a typed
+  `SiteLayout` model from the rendered DOM — section tree, geometry,
+  computed style tokens, content kinds — and emits code generated from
+  that model. It does not save the source's HTML/CSS to disk.
+- **Not a content lift.** Heading text, body copy, logos, illustrations,
+  and product imagery become `<TextSlot>` / `<MediaSlot>` placeholders in
+  the mirror page. You fill them with your own copy and assets before
+  shipping.
 - **Not a component library replacement.** It sits *on top* of
-  shadcn/ui and produces theme files for it.
+  shadcn/ui and produces theme files plus slot-driven page templates.
 
 ---
 
-## Anti-clone policy in one paragraph
-
-Launchframe captures publicly rendered pages, reads the **computed
-appearance** of those pages, and synthesizes an original design system
-from aggregate signals. It never stores HTML, JS, CSS, brand assets,
-illustrations, logos, or copy. Proprietary type families are
-substituted with open-source equivalents. Generated pages and design
-systems are checked against captured corpora for structural and
-token-level overlap; anything above the configured threshold fails the
-build. Full policy:
-[`rules/anti-clone-policy.md`](./rules/anti-clone-policy.md).
+## Responsible use in one paragraph
+
+Launchframe is intended for layout research and design-system seeding
+against pages you have permission to analyze (your own products, sites
+where the operator has permission, or pages where structural analysis is
+permitted by `robots.txt`). The crawler respects `robots.txt` by default
+and rate-limits per domain. The output is generated code derived from a
+normalized typed model and slot placeholders — not a verbatim copy of
+the source's markup, copy, or assets. Operators are responsible for the
+content they paste into those slots and for honoring third-party
+trademarks, terms of service, and licenses.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "launchframe",
-  "version": "0.1.5",
+  "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/dom-crawler.ts

@@ -0,0 +1,521 @@
+/**
+ * DOM layout crawler.
+ *
+ * Runs inside the rendered page via Playwright's `page.evaluate`. Walks the
+ * DOM, identifies top-level sections, classifies each section's role and
+ * composition, and counts the content slots it contains. Returns a
+ * `SiteLayout` structural model the emitter rebuilds into a Next.js page.
+ *
+ * What this records:
+ *   - Section tree (geometry, role, composition, density)
+ *   - Slot inventory per section: how many headings / body paragraphs /
+ *     buttons / images / icons / logos / code blocks etc. it contains
+ *   - Per-section style tokens: background, foreground, padding
+ *   - Page-level tokens: fonts, primary surface colors, container width
+ *
+ * What this does NOT record:
+ *   - Heading or body text content (slots are counts, not strings).
+ *   - Raw HTML, CSS, or class names from the source.
+ *   - Brand assets (logos, illustrations, product screenshots).
+ *
+ * The structural model is what the mirror emitter uses to reconstruct the
+ * page's section grammar with `<TextSlot>` / `<MediaSlot>` placeholders.
+ */
+
+import type { Page } from "playwright";
+
+import type {
+  Composition,
+  SectionLayout,
+  SectionRole,
+  SiteLayout,
+  SiteTokens,
+  SlotCount,
+  SlotKind,
+} from "./types.js";
+
+export async function crawlLayout(
+  page: Page,
+  url: string,
+  viewport: { width: number; height: number },
+): Promise<SiteLayout> {
+  await page.evaluate(() => {
+    const g = globalThis as unknown as { __name?: (fn: unknown) => unknown };
+    if (typeof g.__name === "undefined") g.__name = (fn: unknown) => fn;
+  });
+
+  const host = new URL(url).host;
+  const partial = await page.evaluate(crawlInPage);
+
+  return {
+    url,
+    host,
+    capturedAt: new Date().toISOString(),
+    viewport,
+    ...partial,
+  };
+}
+
+/**
+ * Browser-context crawler. Dependency-free so Playwright can serialize it.
+ * Returns the layout-bearing fields of `SiteLayout` (url/host/capturedAt
+ * are added on the Node side).
+ */
+function crawlInPage(): Pick<
+  SiteLayout,
+  "pageHeightPx" | "sections" | "tokens"
+> {
+  const VIEWPORT_W = window.innerWidth;
+  const PAGE_H = Math.max(
+    document.documentElement.scrollHeight,
+    document.body.scrollHeight,
+  );
+
+  /* ----- helpers ----- */
+
+  function toHex(rgb: string): string | null {
+    if (!rgb || rgb === "transparent") return null;
+    const m = rgb.match(/rgba?\(([^)]+)\)/);
+    if (!m) return null;
+    const parts = m[1]!.split(",").map((s) => s.trim());
+    const r = parseInt(parts[0]!, 10);
+    const g = parseInt(parts[1]!, 10);
+    const b = parseInt(parts[2]!, 10);
+    const a = parts[3] !== undefined ? parseFloat(parts[3]) : 1;
+    if (a < 0.05) return null;
+    if ([r, g, b].some((n) => Number.isNaN(n))) return null;
+    const h = (n: number) => n.toString(16).padStart(2, "0");
+    return `#${h(r)}${h(g)}${h(b)}`;
+  }
+
+  function isVisible(el: HTMLElement): boolean {
+    const style = getComputedStyle(el);
+    if (style.visibility === "hidden" || style.display === "none") return false;
+    if (parseFloat(style.opacity) < 0.05) return false;
+    const r = el.getBoundingClientRect();
+    return r.width > 0 && r.height > 0;
+  }
+
+  function directTextLength(el: Element): number {
+    let total = 0;
+    for (const child of Array.from(el.childNodes)) {
+      if (child.nodeType === 3) {
+        const text = (child.nodeValue ?? "").trim();
+        if (text) total += text.length;
+      }
+    }
+    return total;
+  }
+
+  function classifySlotForElement(el: HTMLElement): SlotKind | null {
+    const tag = el.tagName;
+    const style = getComputedStyle(el);
+    const fontSize = parseFloat(style.fontSize) || 16;
+    const fontWeight = parseInt(style.fontWeight, 10) || 400;
+
+    if (tag === "IMG" || tag === "PICTURE") {
+      // Heuristic: small square-ish images in a logo strip vs hero photos.
+      const r = el.getBoundingClientRect();
+      const ratio = r.width > 0 && r.height > 0 ? r.width / r.height : 0;
+      if (r.height > 0 && r.height < 56 && ratio < 6) return "logo-mono";
+      return "image";
+    }
+    if (tag === "SVG" || tag === "svg") {
+      const r = el.getBoundingClientRect();
+      if (r.width < 32 && r.height < 32) return "icon";
+      return "image";
+    }
+    if (tag === "VIDEO") return "video";
+    if (tag === "PRE" || tag === "CODE") return "code";
+    if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") return "input";
+
+    if (tag === "BUTTON" || (tag === "A" && el.getAttribute("role") === "button")) {
+      // Decide primary vs secondary by background contrast vs the page.
+      const bg = toHex(style.backgroundColor);
+      if (bg && bg !== toHex(getComputedStyle(document.body).backgroundColor)) {
+        return "button-primary";
+      }
+      return "button-secondary";
+    }
+
+    if (tag === "A" && directTextLength(el) > 0) {
+      // Anchor that looks like a styled CTA (padded, bordered, or backgrounded).
+      const padX = parseFloat(style.paddingLeft) + parseFloat(style.paddingRight);
+      const hasBackdrop =
+        toHex(style.backgroundColor) !== null ||
+        parseFloat(style.borderTopWidth) > 0;
+      if (padX > 16 && hasBackdrop) {
+        return toHex(style.backgroundColor) ? "button-primary" : "button-secondary";
+      }
+    }
+
+    if (directTextLength(el) === 0) return null;
+
+    if (/^H[1-6]$/.test(tag)) {
+      const level = parseInt(tag.slice(1), 10);
+      if (level === 1) return "heading-1";
+      if (level === 2) return "heading-2";
+      return "heading-3";
+    }
+
+    if (tag === "LI") return "bullet";
+
+    if (fontSize >= 36 && fontWeight >= 600) return "heading-1";
+    if (fontSize >= 24 && fontWeight >= 500) return "heading-2";
+    if (fontSize >= 18 && fontWeight >= 500) return "heading-3";
+
+    if (fontSize <= 12 && /uppercase/i.test(style.textTransform)) return "eyebrow";
+    if (fontSize <= 13 && fontWeight >= 600) return "badge";
+
+    if (tag === "P" || tag === "SPAN" || tag === "DIV") return "body";
+
+    return null;
+  }
+
+  function countSlots(root: HTMLElement): SlotCount[] {
+    const buckets = new Map<SlotKind, number>();
+    const all = root.querySelectorAll<HTMLElement>("*");
+    for (const el of Array.from(all)) {
+      if (!isVisible(el)) continue;
+      const kind = classifySlotForElement(el);
+      if (kind) buckets.set(kind, (buckets.get(kind) ?? 0) + 1);
+    }
+    // De-dupe nested H1 spans etc: if an H1 contains spans, the outer H1 counts.
+    // We accept some over-count for body since it's coarse anyway; cap it.
+    if ((buckets.get("body") ?? 0) > 12) buckets.set("body", 12);
+    if ((buckets.get("bullet") ?? 0) > 24) buckets.set("bullet", 24);
+
+    const out: SlotCount[] = [];
+    for (const [kind, count] of buckets) out.push({ kind, count });
+    return out.sort((a, b) => a.kind.localeCompare(b.kind));
+  }
+
+  /* ----- section discovery ----- */
+
+  /**
+   * A top-level section is a block-level element that:
+   *  - is at least ~70% of the viewport wide,
+   *  - has a non-trivial height (>= 80 px),
+   *  - and is one of <header>, <footer>, <main>, <section>, <article>,
+   *    or a direct child of <body> / <main> that visually plays that role.
+   */
+  function findSections(): HTMLElement[] {
+    const candidates = new Set<HTMLElement>();
+    const tagSet = ["HEADER", "MAIN", "SECTION", "ARTICLE", "FOOTER", "NAV"];
+    for (const tag of tagSet) {
+      for (const el of Array.from(document.getElementsByTagName(tag))) {
+        candidates.add(el as HTMLElement);
+      }
+    }
+    // Add direct children of <body> and <main> as fallback.
+    const bodyKids = Array.from(document.body.children) as HTMLElement[];
+    for (const el of bodyKids) candidates.add(el);
+    const main = document.querySelector("main");
+    if (main) {
+      for (const el of Array.from(main.children) as HTMLElement[]) {
+        candidates.add(el);
+      }
+    }
+
+    const accepted: HTMLElement[] = [];
+    for (const el of candidates) {
+      if (!isVisible(el)) continue;
+      const r = el.getBoundingClientRect();
+      if (r.width < VIEWPORT_W * 0.7) continue;
+      if (r.height < 80) continue;
+      // Skip if this element is nested inside another already-accepted candidate.
+      // We'll do a final pass after sorting.
+      accepted.push(el);
+    }
+    // Sort by document y position.
+    accepted.sort((a, b) => {
+      const ay = a.getBoundingClientRect().top + window.scrollY;
+      const by = b.getBoundingClientRect().top + window.scrollY;
+      return ay - by;
+    });
+
+    // Drop any element fully contained in an earlier accepted one.
+    const final: HTMLElement[] = [];
+    for (const el of accepted) {
+      const inside = final.some((p) => p !== el && p.contains(el));
+      if (!inside) final.push(el);
+    }
+    return final;
+  }
+
+  /* ----- per-section classification ----- */
+
+  function classifyRole(
+    el: HTMLElement,
+    indexFromTop: number,
+    indexFromBottom: number,
+    slots: SlotCount[],
+  ): SectionRole {
+    const r = el.getBoundingClientRect();
+    const tag = el.tagName;
+    const count = (k: SlotKind) => slots.find((s) => s.kind === k)?.count ?? 0;
+
+    if (tag === "NAV") return "nav";
+    if (tag === "FOOTER" || (indexFromBottom === 0 && r.height < 600)) return "footer";
+    if (tag === "HEADER" && indexFromTop === 0 && r.height < 140) return "nav";
+
+    const headingCount = count("heading-1") + count("heading-2") + count("heading-3");
+    const buttons = count("button-primary") + count("button-secondary");
+    const images = count("image");
+    const logos = count("logo-mono");
+    const bullets = count("bullet");
+
+    // First in-document, has H1 + CTA → hero.
+    if (indexFromTop <= 1 && count("heading-1") >= 1 && buttons >= 1) return "hero";
+
+    // A wide, short band of small uniform images → logo strip.
+    if (logos >= 4 && headingCount <= 1 && r.height < r.width * 0.25) {
+      return "proof-logos";
+    }
+
+    // Pricing tells: 2–4 tall columns each with bullets and a button.
+    if (bullets >= 6 && buttons >= 2 && r.height > 360) return "pricing";
+
+    // Lots of headings (3+) of the same level + small bodies → feature grid.
+    if (count("heading-2") + count("heading-3") >= 3 && images <= 2) return "feature-grid";
+
+    // One heading, generous body, one media slot → deep dive.
+    if (headingCount >= 1 && images >= 1 && bullets <= 4 && r.height > 320) {
+      return "feature-deep-dive";
+    }
+
+    // Heading + 2 buttons, short height → conversion band near the bottom.
+    if (headingCount <= 2 && buttons >= 1 && r.height < 480 && indexFromBottom <= 2) {
+      return "conversion";
+    }
+
+    // Quote-shaped: short body strings, sometimes 3-up.
+    if (count("body") >= 3 && images === 0 && bullets === 0 && buttons === 0) {
+      return "proof-quotes";
+    }
+
+    return "other";
+  }
+
+  function classifyComposition(el: HTMLElement): Composition {
+    // Find the deepest descendant that uses CSS grid or flex with >1 row of cols.
+    const candidates = el.querySelectorAll<HTMLElement>("*");
+    let bestCols = 1;
+    let bestKind: "grid" | "flex" | "none" = "none";
+    let logoRowCols = 0;
+    for (const c of Array.from(candidates).slice(0, 400)) {
+      if (!isVisible(c)) continue;
+      const s = getComputedStyle(c);
+      if (s.display === "grid") {
+        const cols = s.gridTemplateColumns
+          .split(" ")
+          .filter((x) => x.trim().length > 0).length;
+        if (cols > bestCols) {
+          bestCols = cols;
+          bestKind = "grid";
+        }
+      } else if (s.display === "flex" && s.flexDirection.startsWith("row")) {
+        const kids = Array.from(c.children) as HTMLElement[];
+        const visibleKids = kids.filter(isVisible);
+        if (visibleKids.length > bestCols && visibleKids.length <= 12) {
+          bestCols = visibleKids.length;
+          bestKind = "flex";
+        }
+        if (visibleKids.length >= 4) {
+          const allSmall = visibleKids.every((k) => {
+            const kr = k.getBoundingClientRect();
+            return kr.height < 80 && kr.width < 200;
+          });
+          if (allSmall) logoRowCols = Math.max(logoRowCols, visibleKids.length);
+        }
+      }
+    }
+
+    if (logoRowCols >= 4) return "logo-row";
+    if (bestKind === "none" || bestCols <= 1) return "single-column";
+    if (bestCols === 2) return "split-2";
+    if (bestCols === 3) return "grid-3";
+    if (bestCols === 4) return "grid-4";
+    if (bestCols >= 5) return "list";
+    return "unknown";
+  }
+
+  function classifyDensity(el: HTMLElement, slots: SlotCount[]): "thin" | "balanced" | "dense" {
+    const total = slots.reduce((sum, s) => sum + s.count, 0);
+    const r = el.getBoundingClientRect();
+    const density = total / Math.max(1, r.height / 100);
+    if (density < 0.8) return "thin";
+    if (density > 2.4) return "dense";
+    return "balanced";
+  }
+
+  function extractSectionStyles(el: HTMLElement): SectionLayout["styles"] {
+    const s = getComputedStyle(el);
+    return {
+      backgroundHex: toHex(s.backgroundColor),
+      foregroundHex: toHex(s.color),
+      paddingTopPx: Math.round(parseFloat(s.paddingTop) || 0) || null,
+      paddingBottomPx: Math.round(parseFloat(s.paddingBottom) || 0) || null,
+    };
+  }
+
+  /* ----- page-level token extraction ----- */
+
+  function extractPageTokens(): SiteTokens {
+    const body = document.body;
+    const bodyStyle = getComputedStyle(body);
+    const bodyFontFamily = bodyStyle.fontFamily.split(",")[0]!.trim().replace(/^["']|["']$/g, "") || "system-ui";
+
+    let headingFontFamily = bodyFontFamily;
+    const h = document.querySelector("h1, h2, h3");
+    if (h) {
+      const hs = getComputedStyle(h);
+      headingFontFamily = hs.fontFamily.split(",")[0]!.trim().replace(/^["']|["']$/g, "") || bodyFontFamily;
+    }
+
+    const bg = toHex(bodyStyle.backgroundColor) ?? "#ffffff";
+    const fg = toHex(bodyStyle.color) ?? "#0a0a0a";
+
+    // Primary = the most-used non-text colored button background.
+    const buttonBgCounts = new Map<string, number>();
+    for (const b of Array.from(document.querySelectorAll<HTMLElement>("button, a, [role='button']"))) {
+      if (!isVisible(b)) continue;
+      const sb = toHex(getComputedStyle(b).backgroundColor);
+      if (!sb || sb === bg) continue;
+      buttonBgCounts.set(sb, (buttonBgCounts.get(sb) ?? 0) + 1);
+    }
+    let primary = fg;
+    let primaryCount = 0;
+    for (const [hex, count] of buttonBgCounts) {
+      if (count > primaryCount) {
+        primary = hex;
+        primaryCount = count;
+      }
+    }
+
+    // Muted = a frequent off-white / off-black surface color (non-page).
+    const surfaceCounts = new Map<string, number>();
+    for (const el of Array.from(document.querySelectorAll<HTMLElement>("body *"))) {
+      if (!isVisible(el)) continue;
+      const sb = toHex(getComputedStyle(el).backgroundColor);
+      if (!sb || sb === bg) continue;
+      surfaceCounts.set(sb, (surfaceCounts.get(sb) ?? 0) + 1);
+    }
+    let muted = bg;
+    let mutedCount = 0;
+    for (const [hex, count] of surfaceCounts) {
+      if (hex === primary) continue;
+      if (count > mutedCount) {
+        muted = hex;
+        mutedCount = count;
+      }
+    }
+
+    // Border = most-used border color across all elements with a border.
+    const borderCounts = new Map<string, number>();
+    for (const el of Array.from(document.querySelectorAll<HTMLElement>("body *"))) {
+      if (!isVisible(el)) continue;
+      const s = getComputedStyle(el);
+      if (parseFloat(s.borderTopWidth) <= 0) continue;
+      const bh = toHex(s.borderTopColor);
+      if (!bh) continue;
+      borderCounts.set(bh, (borderCounts.get(bh) ?? 0) + 1);
+    }
+    let border = "#e5e7eb";
+    let borderCount = 0;
+    for (const [hex, count] of borderCounts) {
+      if (count > borderCount) {
+        border = hex;
+        borderCount = count;
+      }
+    }
+
+    // Radius = the most-used non-zero corner radius.
+    const radiusCounts = new Map<number, number>();
+    for (const el of Array.from(document.querySelectorAll<HTMLElement>("body *"))) {
+      if (!isVisible(el)) continue;
+      const r = parseFloat(getComputedStyle(el).borderTopLeftRadius);
+      if (!(r > 0 && r < 64)) continue;
+      const k = Math.round(r);
+      radiusCounts.set(k, (radiusCounts.get(k) ?? 0) + 1);
+    }
+    let radius = 8;
+    let radiusCount = 0;
+    for (const [px, count] of radiusCounts) {
+      if (count > radiusCount) {
+        radius = px;
+        radiusCount = count;
+      }
+    }
+
+    // Container: widest layout block under 1600px.
+    let containerPx: number | null = null;
+    let containerArea = 0;
+    for (const el of Array.from(
+      document.querySelectorAll<HTMLElement>("main, section, header, footer, div"),
+    )) {
+      if (!isVisible(el)) continue;
+      const r = el.getBoundingClientRect();
+      if (r.width < 720 || r.width > 1600) continue;
+      if (r.height < 240) continue;
+      const area = r.width * r.height;
+      if (area > containerArea) {
+        containerArea = area;
+        containerPx = Math.round(r.width);
+      }
+    }
+
+    return {
+      bodyFontFamily,
+      headingFontFamily,
+      backgroundHex: bg,
+      foregroundHex: fg,
+      primaryHex: primary,
+      mutedHex: muted,
+      borderHex: border,
+      radiusPx: radius,
+      containerPx,
+    };
+  }
+
+  /* ----- main pass ----- */
+
+  const sectionEls = findSections();
+  const sections: SectionLayout[] = [];
+  for (let i = 0; i < sectionEls.length; i++) {
+    const el = sectionEls[i]!;
+    const r = el.getBoundingClientRect();
+    const top = r.top + window.scrollY;
+    const slots = countSlots(el);
+    const composition = classifyComposition(el);
+    const density = classifyDensity(el, slots);
+    const role = classifyRole(el, i, sectionEls.length - 1 - i, slots);
+    const styles = extractSectionStyles(el);
+
+    const notes: string[] = [];
+    if (slots.length === 0) notes.push("No content slots detected; rendering an empty wrapper.");
+    if (composition === "unknown") notes.push("Composition was ambiguous; fell back to single-column.");
+
+    sections.push({
+      id: `s${i + 1}`,
+      role,
+      composition,
+      density,
+      bbox: [
+        Math.max(0, Math.min(1, r.left / VIEWPORT_W)),
+        Math.max(0, Math.min(1, top / PAGE_H)),
+        Math.max(0, Math.min(1, r.width / VIEWPORT_W)),
+        Math.max(0, Math.min(1, r.height / PAGE_H)),
+      ],
+      slots,
+      styles,
+      notes,
+    });
+  }
+
+  return {
+    pageHeightPx: PAGE_H,
+    sections,
+    tokens: extractPageTokens(),
+  };
+}