From 77be868ee3565e519954a237926c7567b775a8bf Mon Sep 17 00:00:00 2001
From: Samraaj Bath <samraaj100@gmail.com>
Date: Fri, 3 Jul 2026 22:51:50 -0700
Subject: [PATCH 01/24] Generated-code hygiene: listener cleanup, shared cn(),
 whitespace collapse, probe stripping, sub-pixel snapping, clone-origin
 metadata, dependency pinning

- DittoWire/Accordion/DropdownMenu runtime templates: AbortController-based
  listener cleanup, idempotent effects, orphan panel removal on unmount
- Emit a single src/lib/utils.ts cn() instead of a copy per component file
- Collapse captured whitespace runs under white-space:normal (pre* preserved)
- Tag source-injected font-metric probe nodes at capture; drop them from IR
- Snap sub-pixel arbitrary lengths (integer within 0.1px, else 1 decimal)
- Emit SITE_ORIGIN (src/lib/site.ts, env-overridable): sitemap/robots/
  canonical/og:url/JSON-LD resolve against the clone's own origin instead of
  the source domain
- Pin lottie-web in generated package.json whenever DittoLottie is emitted

144 tests pass (21 new), typecheck clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 compiler/src/capture/walker.ts       |  22 ++++
 compiler/src/generate/app.ts         |  86 ++++++++++----
 compiler/src/generate/css.ts         |   5 +-
 compiler/src/generate/interactive.ts |  42 +++----
 compiler/src/generate/menu.ts        |  38 ++++--
 compiler/src/generate/seo.ts         |  94 +++++++++++++--
 compiler/src/generate/tailwind.ts    |  21 +++-
 compiler/src/normalize/ir.ts         |   4 +
 compiler/src/site/generateSite.ts    |  20 +++-
 compiler/test/codegenHygiene.test.ts | 167 +++++++++++++++++++++++++++
 compiler/test/irPrune.test.ts        |  18 +++
 compiler/test/seo.test.ts            |  51 ++++++++
 compiler/test/walker.test.ts         |  53 +++++++++
 13 files changed, 548 insertions(+), 73 deletions(-)
 create mode 100644 compiler/test/codegenHygiene.test.ts

diff --git a/compiler/src/capture/walker.ts b/compiler/src/capture/walker.ts
index 360982e..f44e9d1 100644
--- a/compiler/src/capture/walker.ts
+++ b/compiler/src/capture/walker.ts
@@ -44,6 +44,10 @@ export type RawNode = {
   computed: RawStyle;
   bbox: RawBBox;
   visible: boolean;
+  // A font-metric / measurement scratch node injected by the SOURCE site's own JS (typography
+  // libraries, FontFaceObserver): absolutely positioned, parked far off-screen, and non-painting.
+  // Never user-visible; excluded from emission so it doesn't ship as page markup.
+  probe?: boolean;
   sizing?: RawSizing;
   before?: RawStyle;
   after?: RawStyle;
@@ -286,6 +290,23 @@ export function collectPage(opts?: { maxNodes?: number } | void): PageSnapshot {
     return true;
   };
 
+  // A measurement/probe scratch node: out-of-flow (absolute/fixed), parked far off-screen
+  // (≥10000px beyond any edge — real drawers/sr-only content never live out there), AND
+  // non-painting (visibility:hidden / collapse / opacity:0). The two together are exclusive to
+  // font-metric / measurement scratch elements the source's own JS injects (a11y sr-only text
+  // stays visibility:visible so AT can read it, so it never matches). Tagged so emission drops it.
+  const OFFSCREEN_PROBE_PX = 10000;
+  const isProbe = (cs: CSSStyleDeclaration, bbox: RawBBox): boolean => {
+    if (cs.position !== "absolute" && cs.position !== "fixed") return false;
+    const nonPainting = cs.visibility === "hidden" || cs.visibility === "collapse" || parseFloat(cs.opacity || "1") === 0;
+    if (!nonPainting) return false;
+    const rightEdge = bbox.x + bbox.width;
+    const bottomEdge = bbox.y + bbox.height;
+    const pageH = round2(scrollEl.scrollHeight);
+    return rightEdge <= -OFFSCREEN_PROBE_PX || bottomEdge <= -OFFSCREEN_PROBE_PX
+      || bbox.x >= OFFSCREEN_PROBE_PX + vpW || bbox.y >= OFFSCREEN_PROBE_PX + pageH;
+  };
+
   const serializeElement = (el: Element): RawNode | null => {
     if (nodeCount >= MAX_NODES) { truncated = true; return null; }
     const tag = el.tagName.toLowerCase();
@@ -401,6 +422,7 @@ export function collectPage(opts?: { maxNodes?: number } | void): PageSnapshot {
       computed,
       bbox,
       visible: isVisible(el, cs, bbox),
+      ...(isProbe(cs, bbox) ? { probe: true } : {}),
       ...(sizing ? { sizing } : {}),
       children: [],
     };
diff --git a/compiler/src/generate/app.ts b/compiler/src/generate/app.ts
index 1a10647..534a821 100644
--- a/compiler/src/generate/app.ts
+++ b/compiler/src/generate/app.ts
@@ -17,7 +17,7 @@ import { buildClassMap } from "./classMap.js";
 import { buildTailwind, tailwindGlobalsCss } from "./tailwind.js";
 import { planSections, type SectionPlan } from "./sectionSplit.js";
 import type { RecipeReport } from "../infer/recipes.js";
-import { emitSeoAssetFiles, emitSeoRoutes, jsonLdHeadMarkup, metadataExport, routeSummaryFromIr, seoStaticFiles, viewportExport, type SeoInventory } from "./seo.js";
+import { emitSeoAssetFiles, emitSeoRoutes, jsonLdHeadMarkup, metadataExport, routeSummaryFromIr, seoStaticFiles, siteOriginImportLine, SITE_ORIGIN_LAYOUT_IMPORT, SITE_ORIGIN_MODULE, viewportExport, type SeoInventory } from "./seo.js";
 import { emitGeneratedDocs } from "./docs.js";
 
 const VOID_TAGS = new Set(["area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "param", "source", "track", "wbr"]);
@@ -282,6 +282,17 @@ function jsxText(raw: string): string {
   return `{${escapeText(raw)}}`;
 }
 
+/** Collapse a text run under `white-space: normal` the way CSS renders it: every run of
+ *  whitespace (captured \n\t indentation, doubled spaces) becomes a single space, so the
+ *  markup carries content — not the source file's frozen formatting. Leading/trailing single
+ *  spaces are KEPT (JSX-significant for inline flow); the boundary is preserved so `word <b>x</b>`
+ *  keeps its space. A run that is entirely whitespace collapses to a single space. The text gate
+ *  compares whitespace-normalized (gates.ts:normText), so this stays faithful. */
+function collapseWs(raw: string): string {
+  const collapsed = raw.replace(/\s+/g, " ");
+  return collapsed;
+}
+
 /** The ordered [propKey, valueExpr] list a node emits — rendered to clean JSX attributes
  *  by renderAttrs. Each valueExpr is ready-to-emit JS source (a JSON literal,
  *  `true`, or a `{ __html: … }` object). Component extraction reuses this so the
@@ -591,7 +602,7 @@ function renderNode(node: IRNode, assetMap: Map<string, string>, sourceUrl: stri
     return `${pad}<${tag}${attrs} />`;
   }
 
-  const childParts = emitChildren(node.children, tag, assetMap, sourceUrl, indent + 1, childInteractive, ctx, childTable);
+  const childParts = emitChildren(node.children, tag, assetMap, sourceUrl, indent + 1, childInteractive, ctx, childTable, preservesWhitespace(node));
   if (childParts.length === 0) {
     return `${pad}<${tag}${attrs} />`;
   }
@@ -602,7 +613,7 @@ function renderNode(node: IRNode, assetMap: Map<string, string>, sourceUrl: stri
  *  `{Name_data.map(...)}` call for any run of extracted-component instances. Shared
  *  by renderNode (parentTag is the element tag) and the body/chrome fragment
  *  renderers (parentTag null → no element-only-parent whitespace rule). */
-function emitChildren(children: IRChild[], parentTag: string | null, assetMap: Map<string, string>, sourceUrl: string, indent: number, childInteractive: boolean, ctx?: RenderCtx, insideTable = false): string[] {
+function emitChildren(children: IRChild[], parentTag: string | null, assetMap: Map<string, string>, sourceUrl: string, indent: number, childInteractive: boolean, ctx?: RenderCtx, insideTable = false, preserveWs = false): string[] {
   const pad = "  ".repeat(indent);
   const parts: string[] = [];
   // Coalesce consecutive text children into one. Emitting them as separate JSX
@@ -612,7 +623,12 @@ function emitChildren(children: IRChild[], parentTag: string | null, assetMap: M
   let textBuf = "";
   const flushText = () => {
     if (parentTag && ELEMENT_ONLY_PARENTS.has(parentTag) && textBuf.trim() === "") { textBuf = ""; return; }
-    if (textBuf.length) parts.push(`${pad}${jsxText(textBuf)}`);
+    // Under white-space:normal, collapse the captured formatting (\n\t runs, doubled/leading
+    // multi-space) to CSS-equivalent single spaces so markup ships content, not source-file
+    // indentation. A whitespace-only run collapses to a single significant space ({" "}) — the
+    // huge `{"          "}` literals disappear. Preserve verbatim under pre/pre-wrap/pre-line.
+    const out = preserveWs ? textBuf : collapseWs(textBuf);
+    if (out.length) parts.push(`${pad}${jsxText(out)}`);
     textBuf = "";
   };
   const reg = ctx?.components;
@@ -708,12 +724,20 @@ function takeCid(coll: CidCollector, instances: IRNode[]): number {
   return idx;
 }
 
-/** A self-contained class-name merger emitted into each component module that needs it
- *  (kept import-free so component files stay standalone). Skips falsy parts and joins —
- *  exact for our output because a node's baked base classes and its per-instance overrides
- *  are disjoint token sets. Swap in `tailwind-merge` if you want conflict-aware merging
- *  when hand-editing the ./_styles overrides. */
-const CN_HELPER = `function cn(...parts: Array<string | false | null | undefined>) {\n  return parts.filter(Boolean).join(" ");\n}`;
+/** The single shared `cn()` module (`src/lib/utils.ts`), imported by every module that
+ *  merges class names — one definition per clone instead of a copy per component file.
+ *  Skips falsy parts and joins — exact for our output because a node's baked base classes
+ *  and its per-instance overrides are disjoint token sets. Swap in `tailwind-merge` if you
+ *  want conflict-aware merging when hand-editing the ./_styles overrides. */
+export const CN_UTILS_MODULE = `export function cn(...parts: Array<string | false | null | undefined>) {\n  return parts.filter(Boolean).join(" ");\n}\n`;
+
+/** The `import { cn } from "…/lib/utils"` line a module emits when it references `cn(`.
+ *  `depth` is how many directory levels the consuming file sits BELOW `src` (page.tsx in
+ *  `src/app` → 1; a component in `src/app/components` → 2), so the relative path always
+ *  resolves to the single `src/lib/utils`. */
+export function cnImportLine(depth: number): string {
+  return `import { cn } from "${"../".repeat(Math.max(1, depth))}lib/utils";`;
+}
 
 /** Split a className value SOURCE (a JSON string literal as emitted by propsList) into its
  *  whitespace-separated tokens. Returns [] for a non-string / unparseable source. */
@@ -852,6 +876,15 @@ function canonicalViewportFor(n: IRNode): number {
   return keys[0] ?? 1280;
 }
 
+/** Whether a node's `white-space` preserves captured whitespace verbatim (pre/pre-wrap/pre-line/
+ *  break-spaces) — in which case emission must NOT collapse its text runs. `<pre>`/`<textarea>`
+ *  default to pre even without an explicit declaration. Normal/nowrap collapse per CSS. */
+function preservesWhitespace(n: IRNode): boolean {
+  const ws = (n.computedByVp[canonicalViewportFor(n)] ?? Object.values(n.computedByVp)[0])?.whiteSpace;
+  if (ws) return /^(pre|pre-wrap|pre-line|break-spaces)$/.test(ws);
+  return n.tag === "pre" || n.tag === "textarea";
+}
+
 type TextLeaf = { text: string; node: IRNode; index: number; ancestorTags: string[] };
 
 function normalizeTextValue(text: string): string {
@@ -1594,7 +1627,8 @@ export function componentPreamble(reg: ComponentRegistry | undefined): string {
   const cids = reg.cidDecls.map((c) => `const ${c.varName}: string[][] = ${c.body};`);
   const styles = reg.styleDecls.map((s) => `const ${s.varName} = ${s.body};`);
   const fns = [...reg.funcDefs.values()];
-  const cn = fns.some((f) => f.includes("cn(")) ? [CN_HELPER] : [];
+  // Inlined into a chrome module at src/app (layout.tsx) or src/ (Chrome.tsx) — depth 1.
+  const cn = fns.some((f) => f.includes("cn(")) ? [cnImportLine(1)] : [];
   const parts = [...cn, ...fns, ...data, ...cids, ...styles];
   return parts.length ? parts.join("\n\n") : "";
 }
@@ -1818,13 +1852,13 @@ function describeComponent(name: string): string {
   return map[base] ?? `${base.replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase()} component.`;
 }
 
-export function componentFiles(reg: ComponentRegistry | undefined, svgs?: SvgRegistry): Array<{ name: string; module: string }> {
+export function componentFiles(reg: ComponentRegistry | undefined, svgs?: SvgRegistry, depth = 2): Array<{ name: string; module: string }> {
   if (!reg || reg.funcDefs.size === 0) return [];
   return [...reg.funcDefs].map(([name, src]) => {
     const agg = reg.byName.get(name);
     void agg;
     const header = `/** ${describeComponent(name)} */`;
-    const cnDef = src.includes("cn(") ? CN_HELPER + "\n" : "";
+    const cnImport = src.includes("cn(") ? cnImportLine(depth) : "";
     // The component's props-data type is DEFINED here (colocated), not imported from a central content
     // file — and exported so the section that supplies the data can type its array. Per-instance class
     // overrides still come from _styles.ts (pure styling plumbing).
@@ -1842,9 +1876,9 @@ export function componentFiles(reg: ComponentRegistry | undefined, svgs?: SvgReg
     for (const c of scanRefs(src).comps) {
       if (svgs?.defs.has(c)) svgImports.push(`import ${c} from "../svgs/${svgFileBase(c)}";`);
     }
-    const imports = [...typeImports, ...svgImports];
+    const imports = [...typeImports, ...svgImports, ...(cnImport ? [cnImport] : [])];
     const importBlock = imports.length ? imports.join("\n") + "\n" : "";
-    return { name, module: `${importBlock}${typeDef}${header}\n${cnDef}export default ${src}\n` };
+    return { name, module: `${importBlock}${typeDef}${header}\nexport default ${src}\n` };
   });
 }
 
@@ -2082,6 +2116,7 @@ export function sectionFiles(sreg: SectionRegistry | undefined, reg: ComponentRe
     ];
     const params = paramParts.length ? `{ ${paramParts.join(", ")} } = {}` : "";
     const header = `/** ${describeSection(name)} */`;
+    if (/\bcn\(/.test(body)) lines.push(cnImportLine(2)); // sections live at src/app/sections
     const importBlock = lines.length ? lines.join("\n") + "\n" : "";
     const allConsts = consts;
     const constBlock = allConsts.length ? allConsts.join("\n") + "\n" : "";
@@ -2121,6 +2156,7 @@ export function generatePageTsx(ir: IR, assetMap: Map<string, string>, sourceUrl
     hasMotion ? `import DittoMotion from "${dittoMotionImportPath(0)}";` : "",
     hasLottie ? `import DittoLottie from "${dittoLottieImportPath(0)}";` : "",
     hasMenus ? `import DropdownMenu from "${dropdownMenuImportPath(0)}";` : "",
+    /\bcn\(/.test(body) ? cnImportLine(1) : "", // page.tsx lives at src/app
     ...compImports,
   ].filter(Boolean).join("\n");
   const importBlock = imports ? imports + "\n\n" : "";
@@ -2137,31 +2173,33 @@ ${body}${wiresBlock}${accordionBlock}${motionBlock}${lottieBlock}${menusBlock}
 /** SEO scaffolding (Next App Router): robots.ts + sitemap.ts + an llms.txt route, generated
  *  from the captured URL / title / description — the discovery files a real site ships. */
 function seoFiles(ir: IR): Array<[string, string]> {
-  let origin = "https://example.com";
-  try { origin = new URL(ir.doc.sourceUrl).origin; } catch { /* keep default */ }
-  const url = ir.doc.sourceUrl || origin + "/";
   const title = ir.doc.title || "Home";
   const desc = ir.doc.head?.description || "";
+  // robots.ts / sitemap.ts live at src/app → depth 1 below src. URLs resolve against the
+  // clone's own origin (SITE_ORIGIN, relative by default), never the source domain.
+  const siteImport = siteOriginImportLine(1);
   const robots = `import type { MetadataRoute } from "next";
+${siteImport}
 
 export const dynamic = "force-static";
 
 export default function robots(): MetadataRoute.Robots {
   return {
     rules: { userAgent: "*", allow: "/" },
-    sitemap: ${JSON.stringify(origin + "/sitemap.xml")},
+    sitemap: SITE_ORIGIN + "/sitemap.xml",
   };
 }
 `;
   const sitemap = `import type { MetadataRoute } from "next";
+${siteImport}
 
 export const dynamic = "force-static";
 
 export default function sitemap(): MetadataRoute.Sitemap {
-  return [{ url: ${JSON.stringify(url)}, changeFrequency: "weekly", priority: 1 }];
+  return [{ url: SITE_ORIGIN + "/", changeFrequency: "weekly", priority: 1 }];
 }
 `;
-  const llmsText = [`# ${title}`, ...(desc ? ["", `> ${desc}`] : []), "", "## Pages", "", `- [${title}](${url})`, ""].join("\n");
+  const llmsText = [`# ${title}`, ...(desc ? ["", `> ${desc}`] : []), "", "## Pages", "", `- [${title}](/)`, ""].join("\n");
   const llms = `export const dynamic = "force-static";
 
 export function GET() {
@@ -2183,10 +2221,11 @@ function generateLayoutTsx(ir: IR, bodyClass?: string, seo?: SeoInventory): stri
   const viewport = seo ? viewportExport(seo) : `export const viewport = { width: "device-width", initialScale: 1 };\n`;
   const jsonLd = seo ? jsonLdHeadMarkup(seo, 8) : "";
   const head = jsonLd ? `      <head>\n${jsonLd}\n      </head>\n` : "";
+  const siteImport = seo ? SITE_ORIGIN_LAYOUT_IMPORT + "\n" : "";
   return `import "./globals.css";
 import "./ditto.css";
 import type { ReactNode } from "react";
-
+${siteImport}
 ${metadata}${viewport}
 
 export default function RootLayout({ children }: { children: ReactNode }) {
@@ -2541,6 +2580,9 @@ export function generateApp(input: GenerateInput, tokensCss: string): { pageTsx:
     writeText(join(rootDir, "globals.css"), framework === "vite" ? viteGlobalsCss(globals) : globals);
   }
   writeText(join(rootDir, "ditto.css"), cloneCss);
+  writeText(join(appDir, "src", "lib", "utils.ts"), CN_UTILS_MODULE);
+  // SITE_ORIGIN constant for SEO/metadata routes (Next only — Vite ships static SEO files).
+  if (framework === "next") writeText(join(appDir, "src", "lib", "site.ts"), SITE_ORIGIN_MODULE);
   if (wires.length) writeText(join(rootDir, "ditto", "DittoWire.tsx"), DITTO_WIRE_TSX);
   if (accordions.length) writeText(join(rootDir, "ditto", "Accordion.tsx"), ACCORDION_TSX);
   if (motionHasContent(motionSpec)) writeText(join(rootDir, "ditto", "DittoMotion.tsx"), DITTO_MOTION_TSX);
diff --git a/compiler/src/generate/css.ts b/compiler/src/generate/css.ts
index 2730540..33e6ceb 100644
--- a/compiler/src/generate/css.ts
+++ b/compiler/src/generate/css.ts
@@ -298,7 +298,10 @@ export type WidthPlan = { kind: "fixed" } | { kind: "auto" } | { kind: "percent"
 const PLAN_FIXED: WidthPlan = { kind: "fixed" };
 
 const pf = (v: string | undefined): number => { const n = parseFloat(v ?? ""); return Number.isFinite(n) ? n : 0; };
-const fmtPx = (n: number): string => `${Math.round(n * 1000) / 1000}px`;
+// Snap sub-pixel geometry: integer when within 0.1px (measurement jitter), else at most 1 decimal
+// — matching the Tailwind arbitrary-length rounding (tailwind.ts:snapLen) so CSS and utility output
+// agree and frozen sub-pixel noise (204.797px) never ships. Transforms/border widths format elsewhere.
+const fmtPx = (n: number): string => `${(Math.abs(n - Math.round(n)) < 0.1 ? Math.round(n) : Math.round(n * 10) / 10)}px`;
 const viewportHeightFor = (vp: number): number => CAPTURE_VIEWPORT_HEIGHTS[vp] ?? Math.round(vp * 0.66);
 
 type GeometryPlan = {
diff --git a/compiler/src/generate/interactive.ts b/compiler/src/generate/interactive.ts
index 0b849d1..fdba181 100644
--- a/compiler/src/generate/interactive.ts
+++ b/compiler/src/generate/interactive.ts
@@ -151,7 +151,7 @@ export function accordionJsx(specs: AccordionRuntimeSpec[], indent: number): str
 }
 
 export const ACCORDION_TSX = `"use client";
-import { useEffect, useRef } from "react";
+import { useEffect } from "react";
 
 type CapStyle = Record<string, string>;
 type RTAcc = { trigger: string; region: string; expanded: boolean; triggerOn: CapStyle; triggerOff: CapStyle; regionShown: CapStyle; regionHidden: CapStyle };
@@ -167,10 +167,9 @@ function applyStyle(el: HTMLElement | null, s: CapStyle) {
 /** Wires captured accordion rows with small explicit state.
  *  Hydration initializes the captured base state, then clicks toggle only the target row. */
 export default function Accordion({ specs }: { specs: AccordionSpec[] }) {
-  const wired = useRef(false);
   useEffect(() => {
-    if (wired.current) return;
-    wired.current = true;
+    const ac = new AbortController();
+    const { signal } = ac;
     for (const spec of specs) {
       const state = spec.items.map((it) => it.expanded);
       const renderItem = (i: number) => {
@@ -193,10 +192,11 @@ export default function Accordion({ specs }: { specs: AccordionSpec[] }) {
           e.preventDefault();
           state[i] = !state[i];
           renderItem(i);
-        });
+        }, { signal });
         renderItem(i);
       });
     }
+    return () => ac.abort();
   }, [specs]);
   return null;
 }
@@ -204,7 +204,7 @@ export default function Accordion({ specs }: { specs: AccordionSpec[] }) {
 
 /** The fixed DittoWire client component, written once per generated app. */
 export const DITTO_WIRE_TSX = `"use client";
-import { useEffect, useRef } from "react";
+import { useEffect } from "react";
 
 type CapStyle = Record<string, string>;
 type RTTab = { trigger: string; panel: string; triggerOn: CapStyle; triggerOff: CapStyle; panelShown: CapStyle; panelHidden: CapStyle; descendants?: Record<string, CapStyle> };
@@ -235,10 +235,9 @@ function applyDesc(d?: Record<string, CapStyle>) {
  *  on mount: the server-rendered markup + per-node CSS already reproduce the captured
  *  base state exactly, so state styles are applied only on user interaction. */
 export default function DittoWire({ spec }: { spec: Spec }) {
-  const wired = useRef(false);
   useEffect(() => {
-    if (wired.current) return;
-    wired.current = true;
+    const ac = new AbortController();
+    const { signal } = ac;
     if (spec.kind === "tabs") {
       let active = spec.active;
       const render = () => spec.tabs.forEach((t, i) => {
@@ -254,7 +253,7 @@ export default function DittoWire({ spec }: { spec: Spec }) {
       spec.tabs.forEach((t, i) => {
         const trig = byCid(t.trigger);
         if (!trig) return;
-        trig.addEventListener("click", (e) => { e.preventDefault(); active = i; render(); });
+        trig.addEventListener("click", (e) => { e.preventDefault(); active = i; render(); }, { signal });
         trig.addEventListener("keydown", (e) => {
           const k = (e as KeyboardEvent).key;
           if (k === "ArrowRight" || k === "ArrowLeft") {
@@ -263,7 +262,7 @@ export default function DittoWire({ spec }: { spec: Spec }) {
             render();
             byCid(spec.tabs[active].trigger)?.focus();
           }
-        });
+        }, { signal });
       });
       // No initial render() — the static base state is already correct.
     } else if (spec.kind === "accordion") {
@@ -278,7 +277,7 @@ export default function DittoWire({ spec }: { spec: Spec }) {
       };
       spec.items.forEach((it, i) => {
         const trig = byCid(it.trigger);
-        if (trig) trig.addEventListener("click", (e) => { e.preventDefault(); state[i] = !state[i]; renderItem(i); });
+        if (trig) trig.addEventListener("click", (e) => { e.preventDefault(); state[i] = !state[i]; renderItem(i); }, { signal });
       });
       // No initial renderItem — the static base state is already correct.
     } else if (spec.kind === "carousel") {
@@ -293,9 +292,9 @@ export default function DittoWire({ spec }: { spec: Spec }) {
       };
       const nextEl = spec.next ? byCid(spec.next) : null;
       const prevEl = spec.prev ? byCid(spec.prev) : null;
-      nextEl?.addEventListener("click", (e) => { e.preventDefault(); go(index + 1); });
-      prevEl?.addEventListener("click", (e) => { e.preventDefault(); go(index - 1); });
-      spec.bullets.forEach((b, bi) => byCid(b)?.addEventListener("click", (e) => { e.preventDefault(); go(bi); }));
+      nextEl?.addEventListener("click", (e) => { e.preventDefault(); go(index + 1); }, { signal });
+      prevEl?.addEventListener("click", (e) => { e.preventDefault(); go(index - 1); }, { signal });
+      spec.bullets.forEach((b, bi) => byCid(b)?.addEventListener("click", (e) => { e.preventDefault(); go(bi); }, { signal }));
       // No initial go() — the static base state is already correct.
     } else {
       // Disclosure: dropdown / mega-menu / modal — a trigger reveals a hidden overlay.
@@ -311,18 +310,19 @@ export default function DittoWire({ spec }: { spec: Spec }) {
           if (o) applyDesc(it.descendants);
           if (o) panel.removeAttribute("hidden"); else panel.setAttribute("hidden", "");
         };
-        trig.addEventListener("click", (e) => { e.preventDefault(); set(it.isDialog ? true : !open); });
+        trig.addEventListener("click", (e) => { e.preventDefault(); set(it.isDialog ? true : !open); }, { signal });
         if (it.hoverOpen) {
           const root = trig.parentElement ?? trig;
-          root.addEventListener("mouseenter", () => set(true));
-          root.addEventListener("mouseleave", () => set(false));
+          root.addEventListener("mouseenter", () => set(true), { signal });
+          root.addEventListener("mouseleave", () => set(false), { signal });
         }
-        it.closes.forEach((c) => byCid(c)?.addEventListener("click", (e) => { e.preventDefault(); set(false); }));
-        if (it.backdropClose) panel.addEventListener("click", (e) => { if (e.target === panel) set(false); });
-        document.addEventListener("keydown", (e) => { if ((e as KeyboardEvent).key === "Escape" && open) set(false); });
+        it.closes.forEach((c) => byCid(c)?.addEventListener("click", (e) => { e.preventDefault(); set(false); }, { signal }));
+        if (it.backdropClose) panel.addEventListener("click", (e) => { if (e.target === panel) set(false); }, { signal });
+        document.addEventListener("keydown", (e) => { if ((e as KeyboardEvent).key === "Escape" && open) set(false); }, { signal });
       });
       // No initial set() — the static base state is already correct.
     }
+    return () => ac.abort();
   }, [spec]);
   return null;
 }
diff --git a/compiler/src/generate/menu.ts b/compiler/src/generate/menu.ts
index e2acb61..e1e2df9 100644
--- a/compiler/src/generate/menu.ts
+++ b/compiler/src/generate/menu.ts
@@ -94,7 +94,7 @@ export function dropdownMenuImportPath(depth: number): string {
 
 /** The fixed DropdownMenu client component, written once per generated app. */
 export const DROPDOWN_MENU_TSX = `"use client";
-import { useEffect, useRef } from "react";
+import { useEffect } from "react";
 
 type RTMenu = { trigger: string; hoverOpen: boolean; gap: number; align: "left" | "right"; html: string };
 const byCid = (cid: string): HTMLElement | null => document.querySelector('[data-cid="' + cid + '"]');
@@ -103,10 +103,10 @@ const byCid = (cid: string): HTMLElement | null => document.querySelector('[data
  *  user interaction does it inject the captured panel fragment under its trigger. The base
  *  render is therefore unchanged. */
 export default function DropdownMenu({ menus }: { menus: RTMenu[] }) {
-  const wired = useRef(false);
   useEffect(() => {
-    if (wired.current) return;
-    wired.current = true;
+    const ac = new AbortController();
+    const { signal } = ac;
+    const openPanels: HTMLElement[] = [];
     for (const m of menus) {
       const trig = byCid(m.trigger);
       if (!trig) continue;
@@ -127,27 +127,41 @@ export default function DropdownMenu({ menus }: { menus: RTMenu[] }) {
         panel = wrap.firstElementChild as HTMLElement | null;
         if (!panel) return;
         document.body.appendChild(panel);
+        openPanels.push(panel);
         place();
         trig.setAttribute("aria-expanded", "true");
       };
-      const close = () => { if (panel) { panel.remove(); panel = null; } trig.setAttribute("aria-expanded", "false"); };
+      const close = () => {
+        if (panel) {
+          const i = openPanels.indexOf(panel);
+          if (i !== -1) openPanels.splice(i, 1);
+          panel.remove();
+          panel = null;
+        }
+        trig.setAttribute("aria-expanded", "false");
+      };
       const toggle = () => (panel ? close() : open());
       if (m.hoverOpen) {
         const root = trig.parentElement ?? trig;
-        root.addEventListener("mouseenter", open);
-        root.addEventListener("mouseleave", close);
+        root.addEventListener("mouseenter", open, { signal });
+        root.addEventListener("mouseleave", close, { signal });
       } else {
-        trig.addEventListener("click", (e) => { e.preventDefault(); toggle(); });
+        trig.addEventListener("click", (e) => { e.preventDefault(); toggle(); }, { signal });
       }
-      document.addEventListener("keydown", (e) => { if (e.key === "Escape") close(); });
+      document.addEventListener("keydown", (e) => { if (e.key === "Escape") close(); }, { signal });
       document.addEventListener("click", (e) => {
         const t = e.target as Node;
         if (panel && !trig.contains(t) && !panel.contains(t)) close();
-      });
-      window.addEventListener("resize", place);
-      window.addEventListener("scroll", place, { passive: true });
+      }, { signal });
+      window.addEventListener("resize", place, { signal });
+      window.addEventListener("scroll", place, { passive: true, signal });
     }
     (window as any).__dittoMenuReady = true; // wiring done — lets the gate drive deterministically
+    return () => {
+      ac.abort();
+      // Remove any still-open panels appended to document.body so unmount leaves no orphan nodes.
+      for (const p of openPanels.splice(0)) p.remove();
+    };
   }, [menus]);
   return null;
 }
diff --git a/compiler/src/generate/seo.ts b/compiler/src/generate/seo.ts
index 1227f4c..891e128 100644
--- a/compiler/src/generate/seo.ts
+++ b/compiler/src/generate/seo.ts
@@ -289,8 +289,15 @@ function metadataObject(report: SeoInventory): Record<string, unknown> {
   if (keywords) metadata.keywords = keywords;
   if (report.robots) metadata.robots = report.robots;
   if (report.referrer) metadata.referrer = report.referrer;
+  const sourceOrigin = originOf(report.sourceUrl);
   const alternates: Record<string, unknown> = {};
-  if (report.canonicalUrl) alternates.canonical = report.canonicalUrl;
+  // Canonical is relativized to the source origin path so metadataBase (the clone's own
+  // origin) resolves it — never hard-coding the source domain. Off-origin canonicals are rare;
+  // keep them verbatim.
+  if (report.canonicalUrl) {
+    const c = relativizeToSource(report.canonicalUrl, sourceOrigin);
+    alternates.canonical = c.path;
+  }
   if (report.alternates.length) {
     const languages: Record<string, string> = {};
     for (const alt of report.alternates) languages[alt.hrefLang] = alt.href;
@@ -314,7 +321,7 @@ function metadataObject(report: SeoInventory): Record<string, unknown> {
     else other["og:type"] = ogType;
   }
   if (ogSiteName) og.siteName = ogSiteName;
-  if (ogUrl) og.url = ogUrl;
+  if (ogUrl) og.url = relativizeToSource(ogUrl, sourceOrigin).path;
   if (ogImages.length) og.images = ogImages;
   if (Object.keys(og).length) metadata.openGraph = og;
 
@@ -352,8 +359,23 @@ function metadataObject(report: SeoInventory): Record<string, unknown> {
   return metadata;
 }
 
+// A sentinel object value that metadataExport rewrites into the runtime `metadataBase`
+// expression (JSON can't hold `new URL(...)`). Chosen so it never collides with real content.
+const METADATA_BASE_SENTINEL = "__DITTO_METADATA_BASE__";
+
+// The metadata/JSON-LD layout module references SITE_ORIGIN — callers must hoist this import.
+export const SITE_ORIGIN_LAYOUT_IMPORT = siteOriginImportLine(1);
+
 export function metadataExport(report: SeoInventory): string {
-  return `export const metadata = ${JSON.stringify(metadataObject(report), null, 2)};\n`;
+  const obj = metadataObject(report);
+  // metadataBase lets Next resolve the (now relative) canonical/openGraph URLs against the
+  // clone's OWN origin — SITE_ORIGIN when set, localhost in dev. Placed first for readability.
+  const withBase = { metadataBase: METADATA_BASE_SENTINEL, ...obj };
+  const body = JSON.stringify(withBase, null, 2).replace(
+    JSON.stringify(METADATA_BASE_SENTINEL),
+    `new URL(SITE_ORIGIN || "http://localhost:3000")`,
+  );
+  return `export const metadata = ${body};\n`;
 }
 
 export function viewportExport(report: SeoInventory): string {
@@ -367,13 +389,31 @@ function safeJsonLd(text: string): string {
   return text.replace(/<\/script/gi, "<\\/script").replace(/<!--/g, "<\\!--");
 }
 
+/** Rewrite a JSON-LD block's on-origin @id/url/contentUrl/target values off the SOURCE domain.
+ *  The frozen JSON escapes slashes (`https:\/\/host\/…`), so we split on both the escaped and
+ *  plain origin forms and rejoin with SITE_ORIGIN at RUNTIME — the source domain never appears
+ *  in output, and setting NEXT_PUBLIC_SITE_ORIGIN re-hosts the ids under the clone's own origin.
+ *  Returns a JS expression string. Off-origin links (genuinely external) are left untouched. */
+function jsonLdHtmlExpr(text: string, sourceOrigin: string): string {
+  const safe = safeJsonLd(text);
+  if (!sourceOrigin) return JSON.stringify(safe);
+  const escaped = sourceOrigin.replace(/\//g, "\\/");
+  // Split on whichever origin form appears; only one form is present in a given block.
+  const forms = safe.includes(escaped) ? escaped : (safe.includes(sourceOrigin) ? sourceOrigin : null);
+  if (!forms) return JSON.stringify(safe);
+  const segments = safe.split(forms);
+  if (segments.length === 1) return JSON.stringify(safe);
+  return `[${segments.map((s) => JSON.stringify(s)).join(", ")}].join(SITE_ORIGIN)`;
+}
+
 export function jsonLdHeadMarkup(report: SeoInventory, indent = 8): string {
   if (!report.jsonLd.length) return "";
   const pad = " ".repeat(indent);
+  const sourceOrigin = originOf(report.sourceUrl);
   return report.jsonLd.map((entry, index) => `${pad}<script
 ${pad}  key="ditto-json-ld-${index}"
 ${pad}  type="application/ld+json"
-${pad}  dangerouslySetInnerHTML={{ __html: ${JSON.stringify(safeJsonLd(entry.text))} }}
+${pad}  dangerouslySetInnerHTML={{ __html: ${jsonLdHtmlExpr(entry.text, sourceOrigin)} }}
 ${pad}/>`).join("\n");
 }
 
@@ -397,6 +437,27 @@ function originOf(url: string): string {
   try { return new URL(url).origin; } catch { return "https://example.com"; }
 }
 
+/** The single origin constant every generated SEO/metadata route resolves against. Empty by
+ *  default so canonical/sitemap/JSON-LD URLs render RELATIVE to wherever the clone is served
+ *  (never the source domain); set NEXT_PUBLIC_SITE_ORIGIN to make them absolute to the clone's
+ *  own origin. Emitted once as src/lib/site.ts. */
+export const SITE_ORIGIN_MODULE = `export const SITE_ORIGIN = (process.env.NEXT_PUBLIC_SITE_ORIGIN ?? "").replace(/\\/$/, "");\n`;
+
+/** The `import { SITE_ORIGIN } from "…/lib/site"` line; `depth` mirrors cnImportLine. */
+export function siteOriginImportLine(depth: number): string {
+  return `import { SITE_ORIGIN } from "${"../".repeat(Math.max(1, depth))}lib/site";`;
+}
+
+/** Path portion of a URL that sits on the source origin (so it can be re-hosted under
+ *  SITE_ORIGIN); returns the input unchanged for off-origin (genuinely external) URLs. */
+function relativizeToSource(url: string, sourceOrigin: string): { onOrigin: boolean; path: string } {
+  if (sourceOrigin && url.startsWith(sourceOrigin)) {
+    const path = url.slice(sourceOrigin.length) || "/";
+    return { onOrigin: true, path: path.startsWith("/") ? path : "/" + path };
+  }
+  return { onOrigin: false, path: url };
+}
+
 function generatedLlms(report: SeoInventory, routes: SeoRouteSummary[]): string {
   const title = report.title || routes[0]?.title || "Generated Clone";
   const lines: string[] = [`# ${title}`, ""];
@@ -422,15 +483,17 @@ function generatedLlms(report: SeoInventory, routes: SeoRouteSummary[]): string
 
 export function seoRouteFiles(report: SeoInventory, routes: SeoRouteSummary[]): Array<[string, string]> {
   const origin = originOf(report.sourceUrl);
-  const sitemapUrl = origin + "/sitemap.xml";
+  // robots.ts / sitemap.ts live at src/app → depth 1 below src.
+  const siteImport = siteOriginImportLine(1);
   const robots = `import type { MetadataRoute } from "next";
+${siteImport}
 
 export const dynamic = "force-static";
 
 export default function robots(): MetadataRoute.Robots {
   return {
     rules: { userAgent: "*", allow: "/" },
-    sitemap: ${JSON.stringify(sitemapUrl)},
+    sitemap: SITE_ORIGIN + "/sitemap.xml",
   };
 }
 `;
@@ -441,13 +504,21 @@ export default function robots(): MetadataRoute.Robots {
     title: report.title || "Home",
     description: report.description,
     excerpt: "",
-  }]).map((route, index) => ({ url: route.url, changeFrequency: "weekly", priority: index === 0 ? 1 : 0.7 }));
+  }]).map((route, index) => ({ path: relativizeToSource(route.url, origin).path, changeFrequency: "weekly", priority: index === 0 ? 1 : 0.7 }));
+  // Emit `url: SITE_ORIGIN + "<path>"` so URLs resolve to the clone's own origin (relative by
+  // default), never the source domain.
+  const entryLines = sitemapEntries.map((e) =>
+    `  {\n    url: SITE_ORIGIN + ${JSON.stringify(e.path)},\n    changeFrequency: ${JSON.stringify(e.changeFrequency)},\n    priority: ${e.priority},\n  }`
+  ).join(",\n");
   const sitemap = `import type { MetadataRoute } from "next";
+${siteImport}
 
 export const dynamic = "force-static";
 
 export default function sitemap(): MetadataRoute.Sitemap {
-  return ${JSON.stringify(sitemapEntries, null, 2)};
+  return [
+${entryLines},
+  ];
 }
 `;
   const sourceLlms = resourceText(report, "llms");
@@ -472,11 +543,12 @@ function xmlEscape(value: string): string {
 
 export function seoStaticFiles(report: SeoInventory, routes: SeoRouteSummary[]): Array<[string, string]> {
   const origin = originOf(report.sourceUrl);
-  const sitemapUrl = origin + "/sitemap.xml";
+  // Static output (Vite) has no runtime env: emit the clone's own paths RELATIVE to the source
+  // origin so the source domain is never baked in (the requirement's relative default).
   const robots = [
     "User-agent: *",
     "Allow: /",
-    `Sitemap: ${sitemapUrl}`,
+    "Sitemap: /sitemap.xml",
     "",
   ].join("\n");
   const sitemapRoutes = routes.length ? routes : [{
@@ -492,7 +564,7 @@ export function seoStaticFiles(report: SeoInventory, routes: SeoRouteSummary[]):
     '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
     ...sitemapRoutes.map((route, index) => [
       "  <url>",
-      `    <loc>${xmlEscape(route.url)}</loc>`,
+      `    <loc>${xmlEscape(relativizeToSource(route.url, origin).path)}</loc>`,
       "    <changefreq>weekly</changefreq>",
       `    <priority>${index === 0 ? "1.0" : "0.7"}</priority>`,
       "  </url>",
diff --git a/compiler/src/generate/tailwind.ts b/compiler/src/generate/tailwind.ts
index f96d625..0c8a80f 100644
--- a/compiler/src/generate/tailwind.ts
+++ b/compiler/src/generate/tailwind.ts
@@ -28,6 +28,25 @@ import type { InteractionCapture, StyleDelta } from "../capture/interactions.js"
 function arb(v: string): string {
   return v.replace(/"/g, "'").replace(/_/g, "\\_").replace(/ /g, "_");
 }
+
+/** Round a single simple `<number>px|rem` length, killing frozen sub-pixel noise: snap to an
+ *  integer when the value is within 0.1px of one (measurement/rounding jitter — `204.9994px` was
+ *  meant to be `205px`), otherwise keep at most 1 decimal (`204.797px` → `204.8px`, a genuine
+ *  fraction). `627px` is unchanged. Only touches a lone number+unit token: multi-token values,
+ *  calc()/clamp()/var(), percentages, and unitless numbers pass through untouched, so nothing that
+ *  needs exact sub-pixel precision (borders, transforms — handled on their own branches) is moved. */
+export function snapLen(value: string): string {
+  const m = /^(-?\d*\.?\d+)(px|rem)$/.exec(value.trim());
+  if (!m) return value;
+  const n = parseFloat(m[1]!);
+  const unit = m[2]!;
+  // rem thresholds scale by the 16px root so "within 0.1px" is unit-consistent.
+  const pxPerUnit = unit === "rem" ? 16 : 1;
+  const rounded = Math.abs(n - Math.round(n)) * pxPerUnit < 0.1
+    ? Math.round(n)
+    : Math.round(n * 10) / 10;
+  return `${rounded}${unit}`;
+}
 function arbList(v: string): string {
   return arb(v).replace(/,_/g, ",");
 }
@@ -243,7 +262,7 @@ export function declToUtil(prop: string, value: string): string {
     if (value === "0" || value === "0px" || value === "0rem") {
       return ZERO_NAMED.has(prop) ? `${ARB[prop]}-0` : `${ARB[prop]}-[0px]`;
     }
-    return `${ARB[prop]}-[${arb(value)}]`;
+    return `${ARB[prop]}-[${arb(snapLen(value))}]`;
   }
   if (/^border-(top|right|bottom|left)-width$/.test(prop)) {
     const side = prop.split("-")[1]![0]!; // t/r/b/l
diff --git a/compiler/src/normalize/ir.ts b/compiler/src/normalize/ir.ts
index 0fba954..ee0116b 100644
--- a/compiler/src/normalize/ir.ts
+++ b/compiler/src/normalize/ir.ts
@@ -304,6 +304,10 @@ export function buildIR(sourceDir: string, viewports: number[], opts?: { motion?
   const convert = (raw: RawNode, matched: Record<number, RawNode | undefined>): IRNode | null => {
     if (NOISE_TAGS.has(raw.tag)) return null;
     if (isThirdPartyOverlay(raw)) return null;
+    // Font-metric / measurement scratch nodes the source's own JS injects (tagged by the walker):
+    // absolutely positioned, parked far off-screen, non-painting. Never user-visible — drop so they
+    // don't ship as page markup (e.g. the `<div … -top-[6249rem] invisible>Mgy</div>` probe).
+    if (raw.probe) return null;
 
     const visibleByVp: Record<number, boolean> = {};
     const bboxByVp: Record<number, BBox> = {};
diff --git a/compiler/src/site/generateSite.ts b/compiler/src/site/generateSite.ts
index d820d1c..3dc3aaf 100644
--- a/compiler/src/site/generateSite.ts
+++ b/compiler/src/site/generateSite.ts
@@ -15,7 +15,7 @@ import { generateCss, RESET_CSS } from "../generate/css.js";
 import { generateInteractionCss } from "../generate/interactionCss.js";
 import { buildRuntimeSpecs, wiresJsx, dittoWireImportPath, DITTO_WIRE_TSX, interactionRejectedSet } from "../generate/interactive.js";
 import { buildLottieSpec, lottieHasContent, lottieWireJsx, dittoLottieImportPath, DITTO_LOTTIE_TSX } from "../generate/lottie.js";
-import { renderChildrenJsx, renderAttrs, buildComponentRegistry, componentPreamble, componentFiles, componentImports, componentDataDecls, summarizeComponents, fileBase, generateViteConfig, generateViteIndexHtml, viteGlobalsCss, PACKAGE_JSON, PACKAGE_JSON_TW, PACKAGE_JSON_VITE, PACKAGE_JSON_VITE_TW, TSCONFIG_JSON, TSCONFIG_JSON_VITE, NEXT_CONFIG, injectLottieDep, type AppFramework, type LinkRewrite, type ExtractedComponent, type RenderCtx } from "../generate/app.js";
+import { renderChildrenJsx, renderAttrs, buildComponentRegistry, componentPreamble, componentFiles, componentImports, componentDataDecls, summarizeComponents, fileBase, generateViteConfig, generateViteIndexHtml, viteGlobalsCss, cnImportLine, CN_UTILS_MODULE, PACKAGE_JSON, PACKAGE_JSON_TW, PACKAGE_JSON_VITE, PACKAGE_JSON_VITE_TW, TSCONFIG_JSON, TSCONFIG_JSON_VITE, NEXT_CONFIG, injectLottieDep, type AppFramework, type LinkRewrite, type ExtractedComponent, type RenderCtx } from "../generate/app.js";
 import { buildTailwind, tailwindGlobalsCss, createColorInterner, colorDefsCssOf, type TailwindOutput } from "../generate/tailwind.js";
 import type { InteractionCapture } from "../capture/interactions.js";
 import type { IRChild } from "../normalize/ir.js";
@@ -29,7 +29,7 @@ import type { CaptureResult } from "../capture/capture.js";
 import { backfillLazyBackgrounds } from "../normalize/ir.js";
 import { toRoutePath, segmentsOf } from "../crawl/url.js";
 import { buildCanonicalChrome, chromeCssIr, middleChildren, middleIncludeFilter, CHROME_PREFIX, type ChromePlan } from "./sharedLayout.js";
-import { buildSeoInventory, emitSeoAssetFiles, emitSeoRoutes, jsonLdHeadMarkup, metadataExport, routeSummaryFromIr, seoStaticFiles, viewportExport, type SeoInventory, type SeoRouteSummary } from "../generate/seo.js";
+import { buildSeoInventory, emitSeoAssetFiles, emitSeoRoutes, jsonLdHeadMarkup, metadataExport, routeSummaryFromIr, seoStaticFiles, SITE_ORIGIN_LAYOUT_IMPORT, SITE_ORIGIN_MODULE, viewportExport, type SeoInventory, type SeoRouteSummary } from "../generate/seo.js";
 import { emitGeneratedDocs } from "../generate/docs.js";
 
 export type RouteArtifact = {
@@ -132,9 +132,10 @@ function layoutTsx(entry: RouteArtifact, bodyClass: string | undefined, chrome?:
   const viewport = seo ? viewportExport(seo) : `export const viewport = { width: "device-width", initialScale: 1 };\n`;
   const jsonLd = seo ? jsonLdHeadMarkup(seo, 8) : "";
   const head = jsonLd ? `      <head>\n${jsonLd}\n      </head>\n` : "";
+  const siteImport = seo ? SITE_ORIGIN_LAYOUT_IMPORT + "\n" : "";
   return `import "./globals.css";
 ${chromeImport}import type { ReactNode } from "react";
-
+${siteImport}
 ${metadata}${viewport}
 
 ${pre}export default function RootLayout({ children }: { children: ReactNode }) {
@@ -271,6 +272,9 @@ export function generateSiteApp(opts: {
   // package.json is written after the route loop (below) so the lottie-web dependency can be
   // added when any route actually replays a Lottie animation.
   writeText(join(appDir, "tsconfig.json"), isVite ? TSCONFIG_JSON_VITE : TSCONFIG_JSON);
+  writeText(join(appDir, "src", "lib", "utils.ts"), CN_UTILS_MODULE);
+  // SITE_ORIGIN constant for SEO/metadata routes (Next only — Vite ships static SEO files).
+  if (!isVite) writeText(join(appDir, "src", "lib", "site.ts"), SITE_ORIGIN_MODULE);
   writeText(join(appDir, ".gitignore"), "node_modules\n.next\nout\ndist\n");
   if (isVite) {
     rmSync(join(appDir, "next.config.mjs"), { force: true });
@@ -384,11 +388,17 @@ export function generateSiteApp(opts: {
     // Stage 6: split each route component into its own route-local `components/Name.tsx`
     // (page imports them); per-route data stays inline. Route-local dirs keep names from
     // colliding across routes, which each name their components independently.
-    for (const { name, module } of componentFiles(routeReg)) writeText(join(routeDir, "components", fileBase(name) + ".tsx"), module);
+    // Depth of a route-local `components/Name.tsx` below `src`: src/app/<dir>/components
+    // (Next) or src/routes/<key>/components (Vite). +1 for the components dir itself.
+    const compDepth = (isVite ? 2 : (dir ? dir.split("/").length + 1 : 1)) + 1;
+    for (const { name, module } of componentFiles(routeReg, undefined, compDepth)) writeText(join(routeDir, "components", fileBase(name) + ".tsx"), module);
     const compImport = componentImports(routeReg, 0); // route-local → ./components/Name
     const dataDecls = componentDataDecls(routeReg);
     const preBlock = dataDecls ? dataDecls + "\n\n" : "";
-    const importLines = [wireImport.trimEnd(), lottieImport.trimEnd(), compImport].filter(Boolean).join("\n");
+    // page.tsx sits at routeDir (src/app/<dir> or src/routes/<key>); depth below src.
+    const pageDepth = isVite ? 2 : (dir ? dir.split("/").length + 1 : 1);
+    const cnImport = /\bcn\(/.test(bodyJsx) ? cnImportLine(pageDepth) + "\n" : "";
+    const importLines = [wireImport.trimEnd(), lottieImport.trimEnd(), cnImport.trimEnd(), compImport].filter(Boolean).join("\n");
     const pageTsx = `${isVite ? "" : 'import "./ditto.css";\n'}${importLines ? importLines + "\n" : ""}// Generated by clone-site. Do not edit by hand.\n${preBlock}export default function Page() {\n  return (\n    <>\n${bodyJsx}${wireBody}${lottieBody}
     </>
   );
diff --git a/compiler/test/codegenHygiene.test.ts b/compiler/test/codegenHygiene.test.ts
new file mode 100644
index 0000000..b84301f
--- /dev/null
+++ b/compiler/test/codegenHygiene.test.ts
@@ -0,0 +1,167 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import type { IR, IRNode, IRChild, StyleMap, BBox } from "../src/normalize/ir.js";
+import {
+  CN_UTILS_MODULE,
+  cnImportLine,
+  componentFiles,
+  generatePageTsx,
+  injectLottieDep,
+  PACKAGE_JSON,
+  PACKAGE_JSON_TW,
+  PACKAGE_JSON_VITE,
+  PACKAGE_JSON_VITE_TW,
+  type ComponentRegistry,
+} from "../src/generate/app.js";
+import { DITTO_WIRE_TSX, ACCORDION_TSX } from "../src/generate/interactive.js";
+import { DROPDOWN_MENU_TSX } from "../src/generate/menu.js";
+import { declToUtil, snapLen } from "../src/generate/tailwind.js";
+
+const VPS = [1280];
+const CANONICAL = 1280;
+
+function computed(over: StyleMap = {}): StyleMap {
+  return { display: "block", position: "static", visibility: "visible", whiteSpace: "normal", ...over };
+}
+
+function node(id: string, tag: string, cs: StyleMap, children: IRChild[] = []): IRNode {
+  const computedByVp: Record<number, StyleMap> = {};
+  const bboxByVp: Record<number, BBox> = {};
+  const visibleByVp: Record<number, boolean> = {};
+  for (const vp of VPS) {
+    computedByVp[vp] = { ...cs };
+    bboxByVp[vp] = { x: 0, y: 0, width: vp, height: 100 };
+    visibleByVp[vp] = true;
+  }
+  return { id, tag, attrs: {}, visibleByVp, bboxByVp, computedByVp, children };
+}
+
+function irWith(root: IRNode): IR {
+  return {
+    doc: {
+      sourceUrl: "https://example.test/",
+      title: "Fixture",
+      lang: "en",
+      charset: "UTF-8",
+      metaViewport: "width=device-width, initial-scale=1",
+      viewports: VPS,
+      sampleViewports: VPS,
+      canonicalViewport: CANONICAL,
+      perViewport: Object.fromEntries(VPS.map((vp) => [vp, { scrollHeight: 800, scrollWidth: vp, htmlBg: "rgb(255, 255, 255)", bodyBg: "rgb(255, 255, 255)", bodyColor: "rgb(0, 0, 0)", bodyFont: "Arial" }])),
+      nodeCount: 4,
+      keyframes: [],
+    },
+    root,
+  };
+}
+
+// ---- Fix 1: emitted runtime components clean up their listeners ----
+describe("runtime components abort their listeners on unmount (fix 1)", () => {
+  const templates: Array<[string, string]> = [
+    ["DittoWire", DITTO_WIRE_TSX],
+    ["Accordion", ACCORDION_TSX],
+    ["DropdownMenu", DROPDOWN_MENU_TSX],
+  ];
+  for (const [name, tsx] of templates) {
+    it(`${name}: one AbortController, every addEventListener signalled, cleanup returns abort`, () => {
+      assert.ok(tsx.includes("new AbortController()"), "creates an AbortController");
+      assert.ok(tsx.includes("ac.abort()"), "effect cleanup aborts");
+      // Every addEventListener must carry a listener-options object with the signal (either
+      // `, { signal })` or `, { passive: true, signal })`). Count-match guarantees none is missed.
+      const adds = (tsx.match(/addEventListener\(/g) ?? []).length;
+      const signalled = (tsx.match(/, \{ signal \}\)/g) ?? []).length
+        + (tsx.match(/, \{ passive: true, signal \}\)/g) ?? []).length;
+      assert.ok(adds > 0, "has listeners");
+      assert.equal(signalled, adds, "every addEventListener passes the abort signal");
+      // The stale re-wire guard is gone; effects are idempotent + cleaned up instead.
+      assert.ok(!tsx.includes("wired.current"), "no wired.current guard");
+    });
+  }
+
+  it("DropdownMenu removes any still-open panels on unmount", () => {
+    assert.ok(DROPDOWN_MENU_TSX.includes("openPanels"), "tracks open panels");
+    assert.ok(DROPDOWN_MENU_TSX.includes("openPanels.splice(0)) p.remove()"), "removes panels on cleanup");
+  });
+});
+
+// ---- Fix 2: cn() is a single shared module, imported (not copied per file) ----
+describe("cn() is deduplicated into src/lib/utils (fix 2)", () => {
+  it("exports a single cn from the shared utils module", () => {
+    assert.ok(CN_UTILS_MODULE.includes("export function cn("), "utils module exports cn");
+  });
+
+  it("cnImportLine resolves to the shared module at the right depth", () => {
+    assert.equal(cnImportLine(1), 'import { cn } from "../lib/utils";');
+    assert.equal(cnImportLine(2), 'import { cn } from "../../lib/utils";');
+  });
+
+  it("a component module that uses cn() imports it rather than redefining it", () => {
+    // componentFiles reads only funcDefs / byName / fieldTypes / dataDecls / styleDecls.
+    const reg = {
+      byName: new Map([["Card", { runs: 1, instances: 2, cids: ["n1"] }]]),
+      funcDefs: new Map([["Card", 'function Card({ styles }: { styles: string }) {\n  return <div className={cn("p-4", styles)} />;\n}']]),
+      fieldTypes: new Map(),
+      dataDecls: [],
+      cidDecls: [],
+      styleDecls: [],
+    } as unknown as ComponentRegistry;
+    const files = componentFiles(reg);
+    const card = files.find((f) => f.name === "Card")!.module;
+    assert.ok(card.includes('import { cn } from "../../lib/utils";'), "imports shared cn");
+    assert.ok(!card.includes("function cn("), "no inline cn definition");
+  });
+});
+
+// ---- Fix 3: JSX whitespace is collapsed under white-space: normal ----
+describe("JSX whitespace collapses under white-space:normal (fix 3)", () => {
+  it("collapses captured \\n\\t indentation and multi-space runs to single spaces", () => {
+    const p = node("n1", "p", computed(), [{ text: "\n\t\tSkip to content\n\t\t" }]);
+    const root = node("n0", "body", computed(), [p]);
+    const tsx = generatePageTsx(irWith(root), new Map(), "https://example.test/");
+    assert.ok(!/\{"[^"]*\\n[^"]*"\}/.test(tsx), "no literal \\n frozen in text");
+    assert.ok(!/\{"\s{2,}"\}/.test(tsx), "no multi-space whitespace literal");
+    assert.ok(tsx.includes("Skip to content"), "content preserved");
+  });
+
+  it("preserves whitespace verbatim inside a <pre> (white-space: pre)", () => {
+    const pre = node("n1", "pre", computed({ whiteSpace: "pre" }), [{ text: "line1\n\tline2" }]);
+    const root = node("n0", "body", computed(), [pre]);
+    const tsx = generatePageTsx(irWith(root), new Map(), "https://example.test/");
+    assert.ok(tsx.includes("line1\\n\\tline2"), "pre keeps raw newlines/tabs");
+  });
+});
+
+// ---- Fix 5: sub-pixel arbitrary values snap ----
+describe("sub-pixel lengths snap (fix 5)", () => {
+  it("snapLen keeps genuine fractions at 1 decimal, snaps near-integer jitter to an integer", () => {
+    assert.equal(snapLen("204.797px"), "204.8px");
+    assert.equal(snapLen("627.188px"), "627.2px");
+    assert.equal(snapLen("100.3px"), "100.3px");
+    assert.equal(snapLen("204.98px"), "205px"); // within 0.1px of an integer → snap
+    assert.equal(snapLen("2.996px"), "3px"); // rem/px jitter snaps
+    assert.equal(snapLen("627px"), "627px"); // already clean
+  });
+
+  it("snapLen leaves non-simple values (calc/percent/multi-token) untouched", () => {
+    assert.equal(snapLen("calc(100% - 3.333px)"), "calc(100% - 3.333px)");
+    assert.equal(snapLen("50.5%"), "50.5%");
+    assert.equal(snapLen("0px 2.5px"), "0px 2.5px");
+  });
+
+  it("declToUtil snaps a width arbitrary value but keeps border-width exact", () => {
+    assert.equal(declToUtil("width", "204.797px"), "w-[204.8px]");
+    // Border width sub-pixel precision is load-bearing — left untouched.
+    assert.equal(declToUtil("border-width", "0.667px"), "border-[0.667px]");
+  });
+});
+
+// ---- Fix 7: every emitted runtime import is a declared dependency ----
+describe("lottie-web is declared when its import is emitted (fix 7)", () => {
+  it("injectLottieDep pins lottie-web into every package.json template", () => {
+    for (const pkg of [PACKAGE_JSON, PACKAGE_JSON_TW, PACKAGE_JSON_VITE, PACKAGE_JSON_VITE_TW]) {
+      const injected = injectLottieDep(pkg);
+      const deps = JSON.parse(injected).dependencies as Record<string, string>;
+      assert.equal(deps["lottie-web"], "5.12.2", "lottie-web pinned to the harness version");
+    }
+  });
+});
diff --git a/compiler/test/irPrune.test.ts b/compiler/test/irPrune.test.ts
index eaac617..167d7f1 100644
--- a/compiler/test/irPrune.test.ts
+++ b/compiler/test/irPrune.test.ts
@@ -98,3 +98,21 @@ describe("IR prune keeps <source> media candidates", () => {
     assert.equal(findByTag(root, "picture"), null);
   });
 });
+
+describe("IR drops font-metric probe nodes (fix 4)", () => {
+  it("excludes a walker-tagged probe node from the IR, keeping its siblings", () => {
+    const probe: RawNode = {
+      ...raw("div", { class: "font-probe" }, [{ text: "Mgy" }]),
+      probe: true,
+    };
+    const real = raw("h1", { class: "title" }, [{ text: "Heading" }]);
+    const body = raw("body", {}, [real, probe]);
+
+    const root = buildFixtureIR(body);
+
+    const kept = root.children.filter((c) => !isTextChild(c)).map((c) => (c as IRNode).tag);
+    assert.deepEqual(kept, ["h1"], "probe div is dropped, the real heading survives");
+    // Its text must not leak into the tree either.
+    assert.equal(findByTag(root, "div"), null);
+  });
+});
diff --git a/compiler/test/seo.test.ts b/compiler/test/seo.test.ts
index 3d514a5..579118b 100644
--- a/compiler/test/seo.test.ts
+++ b/compiler/test/seo.test.ts
@@ -195,3 +195,54 @@ describe("generated Next config", () => {
     assert.ok(NEXT_CONFIG.includes("devIndicators: false"));
   });
 });
+
+describe("SEO origin references the clone, not the source domain (fix 6)", () => {
+  it("sitemap.ts / robots.ts resolve against SITE_ORIGIN, not the source origin", () => {
+    const ir = fixtureIr();
+    const report = buildSeoInventory(ir, fixtureAssets(), fixtureCapture());
+    const files = seoRouteFiles(report, [routeSummaryFromIr(ir, "/", "/", ir.doc.sourceUrl)]);
+    const robots = files.find(([p]) => p === "robots.ts")![1];
+    const sitemap = files.find(([p]) => p === "sitemap.ts")![1];
+    for (const body of [robots, sitemap]) {
+      assert.ok(body.includes('import { SITE_ORIGIN } from "../lib/site";'), "imports SITE_ORIGIN");
+      assert.ok(body.includes("SITE_ORIGIN +"), "builds URLs from SITE_ORIGIN");
+      assert.ok(!body.includes("example.test"), "never bakes the source domain");
+    }
+    // sitemap path is relativized off the source origin.
+    assert.ok(sitemap.includes('SITE_ORIGIN + "/seo"') || sitemap.includes('SITE_ORIGIN + "/"'));
+  });
+
+  it("metadata sets metadataBase from SITE_ORIGIN and relativizes the canonical", () => {
+    const ir = fixtureIr();
+    const report = buildSeoInventory(ir, fixtureAssets(), fixtureCapture());
+    const metadata = metadataExport(report);
+    assert.ok(metadata.includes('new URL(SITE_ORIGIN || "http://localhost:3000")'), "metadataBase from SITE_ORIGIN");
+    assert.ok(metadata.includes('"canonical": "/seo"'), "canonical relativized to a path");
+    // The source domain must not survive in canonical (og:image assets are localized elsewhere).
+    assert.ok(!metadata.includes('"canonical": "https://example.test'), "canonical is not absolute to source");
+  });
+
+  it("relativizes og:url off the source origin", () => {
+    const ir = fixtureIr();
+    ir.doc.head!.meta!.push({ property: "og:url", content: "https://example.test/seo" });
+    const report = buildSeoInventory(ir, fixtureAssets(), fixtureCapture());
+    const metadata = metadataExport(report);
+    assert.ok(metadata.includes('"url": "/seo"'), "og:url relativized to a path");
+    assert.ok(!metadata.includes('"url": "https://example.test/seo"'), "og:url not absolute to source");
+  });
+
+  it("rewrites on-origin JSON-LD @id/url off the source domain via SITE_ORIGIN", () => {
+    const ir = fixtureIr();
+    // JSON-LD carrying the source origin in @id/url (escaped-slash form, like WordPress emits).
+    ir.doc.head!.jsonLd = [{
+      id: "graph",
+      text: '{"@context":"https:\\/\\/schema.org","@id":"https:\\/\\/example.test\\/#website","url":"https:\\/\\/example.test\\/"}',
+    }];
+    const report = buildSeoInventory(ir, fixtureAssets(), fixtureCapture());
+    const markup = jsonLdHeadMarkup(report);
+    assert.ok(markup.includes(".join(SITE_ORIGIN)"), "rejoins segments with SITE_ORIGIN at runtime");
+    // The source origin must not survive as a literal (schema.org context is off-origin, kept).
+    assert.ok(!markup.includes("example.test"), "source origin removed from JSON-LD");
+    assert.ok(markup.includes("schema.org"), "off-origin @context left untouched");
+  });
+});
diff --git a/compiler/test/walker.test.ts b/compiler/test/walker.test.ts
index a681f7c..5c3e6ba 100644
--- a/compiler/test/walker.test.ts
+++ b/compiler/test/walker.test.ts
@@ -158,3 +158,56 @@ describe("walker off-screen visibility", () => {
     assert.equal(fixed.visible, false, "fixed box below the viewport is invisible");
   });
 });
+
+describe("walker font-metric probe tagging (fix 4)", () => {
+  let browser: Browser;
+  let page: Page;
+  before(async () => {
+    browser = await chromium.launch();
+    page = await browser.newPage();
+    await page.setViewportSize({ width: 375, height: 768 });
+  });
+  after(async () => {
+    await browser.close();
+  });
+
+  const capture = async (html: string) => {
+    await page.setContent(html);
+    await page.evaluate("globalThis.__name = globalThis.__name || ((fn) => fn);");
+    return page.evaluate(collectPage);
+  };
+
+  it("tags a far-off-screen, non-painting measurement scratch node as a probe", async () => {
+    // The classic font-metric probe pattern (WordPress/typography libs): absolutely positioned,
+    // parked ~100000px off-screen, visibility:hidden, holding measurement text.
+    const snap = await capture(`
+      <p class="real">Real content</p>
+      <div class="probe" style="position:absolute;top:-99999px;left:-99999px;
+           visibility:hidden;white-space:nowrap;">Mgy</div>`);
+    const probe = findByClass(snap.root, "probe")!;
+    assert.equal(probe.probe, true, "far-off-screen hidden scratch node is a probe");
+    const real = findByClass(snap.root, "real")!;
+    assert.ok(!real.probe, "real content is not a probe");
+  });
+
+  it("does NOT tag a near-off-screen hidden drawer (real content) as a probe", async () => {
+    // A slide-in drawer parked just off the left edge (x:-375, visibility:hidden) is real
+    // content that a controller can reveal — it must NOT be mistaken for a measurement probe.
+    const snap = await capture(`
+      <div class="drawer" style="position:fixed;left:0;top:0;width:375px;height:768px;
+           transform:translateX(-100%);visibility:hidden;">
+        <h2 class="dtitle">Menu</h2>
+      </div>`);
+    const drawer = findByClass(snap.root, "drawer")!;
+    assert.ok(!drawer.probe, "a near-off-screen drawer is not a probe");
+  });
+
+  it("does NOT tag an sr-only (visible, on-screen-adjacent) accessibility label as a probe", async () => {
+    // Screen-reader-only text stays visibility:visible so AT can read it; even parked far off
+    // via left:-9999px it must survive (and 9999px is under the 10000px probe threshold anyway).
+    const snap = await capture(`
+      <a href="/"><span class="sr" style="position:absolute;left:-9999px;">Skip to content</span>Home</a>`);
+    const sr = findByClass(snap.root, "sr")!;
+    assert.ok(!sr.probe, "sr-only accessible text is not a probe");
+  });
+});

From d3ec154bae161dafc3e5f8f86a558fe0018b9f86 Mon Sep 17 00:00:00 2001
From: Samraaj Bath <samraaj100@gmail.com>
Date: Fri, 3 Jul 2026 23:09:16 -0700
Subject: [PATCH 02/24] Capture & emission fidelity wave: dotLottie support,
 scroll-state isolation, authored-geometry trust, honest quality scoring
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Capture:
- Preserve real asset extensions (.lottie no longer truncated); extract the
  default animation JSON from dotLottie ZIP containers at materialization
  (minimal built-in ZIP reader, no new deps)
- Reset scroll + settle before every viewport snapshot so scroll-linked
  styles can't bake into captured computed values
- Marquee detection now requires content overflow (>1.35x), sustained
  velocity across separated windows, scroll independence (jiggle test), and
  genuine content repetition — kills scroll-settle-lerp false positives
- Sizing probe trusts authored explicit heights (px/vh/calc) over circular
  parent/child reflow verdicts, fixing dropped 100vh heroes

Normalize/generate:
- Canonicalize identity transforms to "none" per viewport; emit explicit
  transform resets across bands when any band has a real transform
- DittoLottie keeps the captured placeholder until DOMLoaded; failed loads
  no longer blank the container
- mx-auto only for true auto-margin centering; literal per-band margins are
  preserved (fixes full-bleed regressions)
- Spacing-scale snap tightened to 0.25px (3.5px stays p-[3.5px]); emit
  whitespace-nowrap for wrap-vulnerable single-line text leaves
- Grid recipes no longer override captured track counts or column spans;
  responsive re-flow plans apply only when geometry agrees

Quality scoring:
- Rewritten 6-dimension rubric (payload, decomposition, duplication,
  semantics, hygiene, runtime) with catastrophe caps and per-dimension
  reporting; thresholds are documented calibration guides

218 tests pass (74 new), typecheck clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 compiler/src/capture/capture.ts            |  67 +-
 compiler/src/capture/dotlottie.ts          | 123 ++++
 compiler/src/capture/motion.ts             | 203 +++++-
 compiler/src/capture/walker.ts             |  63 +-
 compiler/src/generate/app.ts               |  74 ++-
 compiler/src/generate/css.ts               |  85 ++-
 compiler/src/generate/lottie.ts            |  29 +-
 compiler/src/generate/tailwind.ts          |  13 +-
 compiler/src/normalize/ir.ts               |  42 ++
 compiler/src/runner/codeAudit.ts           | 235 ++++---
 compiler/src/runner/qualityScore.ts        | 725 ++++++++++++++-------
 compiler/test/css.test.ts                  | 194 ++++++
 compiler/test/dotlottie.test.ts            | 146 +++++
 compiler/test/lottiePlaceholder.test.ts    |  77 +++
 compiler/test/marqueeDiscriminator.test.ts | 104 +++
 compiler/test/qualityScore.test.ts         | 256 ++++++++
 compiler/test/recipeGridGeometry.test.ts   | 157 +++++
 compiler/test/tailwind.test.ts             |  32 +-
 compiler/test/walker.test.ts               | 106 +++
 19 files changed, 2345 insertions(+), 386 deletions(-)
 create mode 100644 compiler/src/capture/dotlottie.ts
 create mode 100644 compiler/test/dotlottie.test.ts
 create mode 100644 compiler/test/lottiePlaceholder.test.ts
 create mode 100644 compiler/test/marqueeDiscriminator.test.ts
 create mode 100644 compiler/test/qualityScore.test.ts
 create mode 100644 compiler/test/recipeGridGeometry.test.ts

diff --git a/compiler/src/capture/capture.ts b/compiler/src/capture/capture.ts
index 4b92679..a29a3c2 100644
--- a/compiler/src/capture/capture.ts
+++ b/compiler/src/capture/capture.ts
@@ -14,6 +14,7 @@ import {
 import { discoverBreakpoints } from "./breakpoints.js";
 import { writeJSON, writeJSONCompact, writeBytes, ensureDir } from "../util/fsx.js";
 import { sha1_12, round } from "../util/canonical.js";
+import { isZipArchive, extractDotLottieJson } from "./dotlottie.js";
 
 export const REQUIRED_VIEWPORTS = [375, 768, 1280, 1920] as const;
 // The dense width set captured for SIZE INFERENCE: a node sampled at 9 widths reveals its sizing
@@ -115,13 +116,19 @@ export function isRetryableAssetFailure(type: string, status: number | null): bo
   return status >= 500 || status === 429;
 }
 
-function extFromUrl(url: string): string {
+// Bound on a preserved file extension. Real extensions are short, but a hard 5-char cap
+// silently truncates legitimate ones (`.lottie` → `.lotti`, `.webmanifest` → `.webma`),
+// which then mis-materializes the asset. Keep the guard generous enough for the longest
+// real extensions and reject anything absurdly long (a dotted path segment, not an ext).
+const MAX_EXT_LEN = 12;
+
+export function extFromUrl(url: string): string {
   try {
     const p = new URL(url).pathname;
     const dot = p.lastIndexOf(".");
     if (dot >= 0 && dot > p.lastIndexOf("/")) {
-      const ext = p.slice(dot + 1).toLowerCase().slice(0, 5);
-      if (/^[a-z0-9]+$/.test(ext)) return ext;
+      const ext = p.slice(dot + 1).toLowerCase();
+      if (ext.length <= MAX_EXT_LEN && /^[a-z0-9]+$/.test(ext)) return ext;
     }
   } catch { /* ignore */ }
   return "";
@@ -209,6 +216,41 @@ async function settle(page: import("playwright").Page, maxMs = 2500): Promise<vo
   await page.waitForTimeout(250);
 }
 
+/**
+ * Stage 2 — scroll-state reset immediately before a per-viewport snapshot. The motion /
+ * dwell-scroll / carousel / element-screenshot passes above all leave the page scrolled or
+ * mid-transition; scroll-linked styles (Webflow scroll-state transforms, position:sticky
+ * offsets) then get baked into the captured computed styles for THAT viewport only, so a
+ * scroll-driven translateY leaks into one band and cascades. Reset window + inner scrollers
+ * to the top, wait for scroll-linked effects to settle across a few rAF ticks plus a short
+ * quiescence window, THEN let the caller snapshot. Bounded and deterministic.
+ */
+async function settleScrollTopBeforeSnapshot(page: import("playwright").Page): Promise<void> {
+  try {
+    await Promise.race([
+      page.evaluate(async () => {
+        const raf = () => new Promise<void>((r) => requestAnimationFrame(() => r()));
+        const resetAll = () => {
+          window.scrollTo(0, 0);
+          for (const el of Array.from(document.querySelectorAll("*"))) {
+            if (el.scrollLeft) el.scrollLeft = 0;
+            if (el.scrollTop) el.scrollTop = 0;
+          }
+        };
+        resetAll();
+        // Let scroll-linked effects (scroll-state classes, sticky offsets, JS scroll handlers)
+        // recompute at scroll 0 over several frames, re-asserting the top position each tick in
+        // case a handler nudged it, then hold briefly for quiescence.
+        for (let i = 0; i < 6; i++) { await raf(); resetAll(); }
+        await new Promise<void>((r) => setTimeout(r, 120));
+        resetAll();
+        await raf();
+      }),
+      new Promise<void>((r) => setTimeout(r, 4000)),
+    ]);
+  } catch { /* ignore — a best-effort reset never blocks the snapshot */ }
+}
+
 export type DismissResult = { dismissed: string[]; overlaysRemaining: number; removed: number; blocking: boolean };
 
 /**
@@ -579,7 +621,18 @@ export async function captureSite(opts: {
     if (type === "video" && !looksLikeVideoFile(bytes)) return;
     const a = assetMap.get(url) ?? recordAsset(url, type, null, null, "network");
     if (a.storedAs) return;
-    const ext = extFromUrl(url) || extFromContentType(a.contentType) ||
+    // A `.lottie` (dotLottie) asset is a ZIP archive, not bare lottie-web JSON. lottie-web's
+    // `path:` loader does a JSON.parse and throws on the ZIP bytes, blanking the container. So
+    // unwrap it here: extract the default animation JSON and store THAT, materializing every
+    // lottie source as plain JSON regardless of the container it arrived in.
+    let extOverride: string | null = null;
+    if (type === "lottie" && isZipArchive(bytes)) {
+      const json = extractDotLottieJson(bytes);
+      if (!json) return; // unreadable dotLottie — leave unstored rather than ship a broken ZIP
+      bytes = json;
+      extOverride = "json";
+    }
+    const ext = extOverride || extFromUrl(url) || extFromContentType(a.contentType) ||
       (type === "css" ? "css" : type === "font" ? "woff2" : type === "svg" ? "svg" :
        type === "video" ? "mp4" : type === "lottie" ? "json" : "png");
     const name = `${sha1_12(url)}.${ext}`;
@@ -973,6 +1026,12 @@ export async function captureSite(opts: {
       const scrollAnimsCanceled = await neutralizeScrollTimelineAnimations(page);
       if (scrollAnimsCanceled) log({ event: "scroll_timeline_anims_canceled", viewport: vw, count: scrollAnimsCanceled });
 
+      // Final scroll-state reset immediately before the walk: every preceding pass (dwell
+      // scroll, carousel settle, element screenshots) can leave the page scrolled, which bakes
+      // scroll-linked transforms/offsets into this viewport's computed styles. Scroll to top and
+      // let scroll-linked effects settle so the snapshot records the genuine at-rest values.
+      await settleScrollTopBeforeSnapshot(page);
+
       // Bound the in-page DOM walk: page.evaluate has no default timeout, so a
       // pathologically large/animated DOM (e.g. asana.com) could hang forever.
       const snapshot: PageSnapshot = await Promise.race([
diff --git a/compiler/src/capture/dotlottie.ts b/compiler/src/capture/dotlottie.ts
new file mode 100644
index 0000000..ca7d4da
--- /dev/null
+++ b/compiler/src/capture/dotlottie.ts
@@ -0,0 +1,123 @@
+import { inflateRawSync } from "node:zlib";
+
+/**
+ * dotLottie (.lottie) extraction.
+ *
+ * A `.lottie` file is NOT bare lottie-web JSON — it is a ZIP archive (the "dotLottie"
+ * container) holding `manifest.json` plus one or more `animations/*.json` documents. Feeding
+ * the raw ZIP bytes to lottie-web via `path:` makes it try to JSON.parse a ZIP, which throws
+ * an InvalidStateError at runtime and leaves the container blank. So at materialization time
+ * we detect the ZIP, pick the default/first animation, and rewrite the stored asset as plain
+ * lottie JSON that lottie-web can parse directly.
+ *
+ * Node ships `zlib` (raw DEFLATE) but no ZIP reader, and pulling a zip dependency for this
+ * one shape is overkill — so this implements the minimal slice of the ZIP spec needed:
+ * walking the End-Of-Central-Directory + central directory to locate entries, then reading
+ * each local file header to decompress a stored (method 0) or deflated (method 8) entry.
+ * Deterministic: no timestamps, no randomness, entries resolved by name.
+ */
+
+/** ZIP local file header signature (`PK\x03\x04`). dotLottie archives always start with it. */
+export function isZipArchive(bytes: Buffer): boolean {
+  return bytes.length >= 4 && bytes[0] === 0x50 && bytes[1] === 0x4b && bytes[2] === 0x03 && bytes[3] === 0x04;
+}
+
+const EOCD_SIG = 0x06054b50; // End Of Central Directory
+const CEN_SIG = 0x02014b50; // Central directory file header
+const LOC_SIG = 0x04034b50; // Local file header
+
+type ZipEntry = { name: string; method: number; compSize: number; uncompSize: number; localOffset: number };
+
+/** Locate + read the End-Of-Central-Directory record, then walk the central directory. */
+function readCentralDirectory(buf: Buffer): ZipEntry[] {
+  // The EOCD lives at the tail; it is >=22 bytes and may carry a trailing comment, so scan
+  // backwards for its signature within the max comment window (64KiB) + record size.
+  const minEocd = 22;
+  if (buf.length < minEocd) return [];
+  let eocd = -1;
+  const scanFrom = Math.max(0, buf.length - (0xffff + minEocd));
+  for (let i = buf.length - minEocd; i >= scanFrom; i--) {
+    if (buf.readUInt32LE(i) === EOCD_SIG) { eocd = i; break; }
+  }
+  if (eocd < 0) return [];
+
+  const entryCount = buf.readUInt16LE(eocd + 10);
+  let ptr = buf.readUInt32LE(eocd + 16); // central directory offset
+  const entries: ZipEntry[] = [];
+  for (let i = 0; i < entryCount; i++) {
+    if (ptr + 46 > buf.length || buf.readUInt32LE(ptr) !== CEN_SIG) break;
+    const method = buf.readUInt16LE(ptr + 10);
+    const compSize = buf.readUInt32LE(ptr + 20);
+    const uncompSize = buf.readUInt32LE(ptr + 24);
+    const nameLen = buf.readUInt16LE(ptr + 28);
+    const extraLen = buf.readUInt16LE(ptr + 30);
+    const commentLen = buf.readUInt16LE(ptr + 32);
+    const localOffset = buf.readUInt32LE(ptr + 42);
+    const name = buf.toString("utf8", ptr + 46, ptr + 46 + nameLen);
+    entries.push({ name, method, compSize, uncompSize, localOffset });
+    ptr += 46 + nameLen + extraLen + commentLen;
+  }
+  return entries;
+}
+
+/** Decompress one central-directory entry by reading its local header for the data offset. */
+function readEntry(buf: Buffer, e: ZipEntry): Buffer | null {
+  const p = e.localOffset;
+  if (p + 30 > buf.length || buf.readUInt32LE(p) !== LOC_SIG) return null;
+  // The central directory's name/extra lengths can differ from the local header's, so read the
+  // local header's own lengths to find where the file data begins.
+  const nameLen = buf.readUInt16LE(p + 26);
+  const extraLen = buf.readUInt16LE(p + 28);
+  const dataStart = p + 30 + nameLen + extraLen;
+  const dataEnd = dataStart + e.compSize;
+  if (dataEnd > buf.length) return null;
+  const comp = buf.subarray(dataStart, dataEnd);
+  if (e.method === 0) return Buffer.from(comp); // stored
+  if (e.method === 8) {
+    try { return inflateRawSync(comp); } catch { return null; }
+  }
+  return null; // unsupported compression method
+}
+
+/** Read a named entry (exact path match) from a ZIP buffer, or null if absent/unreadable. */
+export function readZipEntry(buf: Buffer, name: string): Buffer | null {
+  const entry = readCentralDirectory(buf).find((e) => e.name === name);
+  return entry ? readEntry(buf, entry) : null;
+}
+
+/**
+ * Extract the lottie animation JSON from a dotLottie ZIP. Picks the manifest's first/default
+ * animation (falling back to the first `animations/*.json` entry), returning it as a Buffer of
+ * plain lottie JSON ready to hand to lottie-web via `path:`. Returns null when the bytes are
+ * not a dotLottie ZIP or no animation JSON is present.
+ */
+export function extractDotLottieJson(bytes: Buffer): Buffer | null {
+  if (!isZipArchive(bytes)) return null;
+  const entries = readCentralDirectory(bytes);
+  if (!entries.length) return null;
+
+  const animEntries = entries
+    .filter((e) => /^animations\/.+\.json$/i.test(e.name))
+    .sort((a, b) => a.name.localeCompare(b.name)); // deterministic ordering
+  if (!animEntries.length) return null;
+
+  // Prefer the animation the manifest names first (its default), when the manifest is readable.
+  let chosen = animEntries[0]!;
+  const manifestBuf = readZipEntry(bytes, "manifest.json");
+  if (manifestBuf) {
+    try {
+      const manifest = JSON.parse(manifestBuf.toString("utf8")) as { animations?: Array<{ id?: string }> };
+      const firstId = manifest.animations?.[0]?.id;
+      if (firstId) {
+        const match = animEntries.find((e) => e.name === `animations/${firstId}.json`);
+        if (match) chosen = match;
+      }
+    } catch { /* manifest unreadable — keep the name-sorted first animation */ }
+  }
+
+  const json = readEntry(bytes, chosen);
+  if (!json) return null;
+  // Validate it parses as JSON (lottie-web's `path:` loader does a bare JSON.parse).
+  try { JSON.parse(json.toString("utf8")); } catch { return null; }
+  return json;
+}
diff --git a/compiler/src/capture/motion.ts b/compiler/src/capture/motion.ts
index 1dcc955..c35b5b2 100644
--- a/compiler/src/capture/motion.ts
+++ b/compiler/src/capture/motion.ts
@@ -60,6 +60,83 @@ export type MarqueeSpec = {
   periodPx: number; // distance per seamless loop (one duplicated copy ≈ scrollWidth/2)
 };
 
+// ---- Pure marquee discriminators (extracted so the in-browser sampling logic is unit
+// testable). These are duplicated verbatim inside `detectMarquees`' page.evaluate body —
+// module-scope functions do NOT cross the serialization boundary — so any change here must
+// be mirrored there (and vice versa). They are deterministic: no randomness, no clock reads.
+
+/**
+ * Median signed velocity (px/s) from a series of per-sample translateX deltas taken at a
+ * fixed cadence. Median (not mean) ignores the single per-loop wrap-reset outlier, which
+ * is a large jump opposite the travel direction when the track seamlessly restarts.
+ */
+export function medianVelocityPxPerSec(deltas: number[], sampleMs: number): number {
+  if (!deltas.length || sampleMs <= 0) return 0;
+  const med = [...deltas].sort((a, b) => a - b)[Math.floor(deltas.length / 2)]!;
+  return Math.round((med / sampleMs) * 1000);
+}
+
+/**
+ * Discriminator 2 — sustained-constant-velocity test. A real marquee holds a steady
+ * velocity across time; a scroll-settle lerp (still easing toward its scroll-target after
+ * `scrollIntoView`) decays, so its velocity in a later observation window is a small
+ * fraction of the earlier one. Two windows of per-sample deltas separated by ≥1.5s; pass
+ * only if the later window's speed is BOTH non-trivial AND close to the earlier window's
+ * (within a relative tolerance) — i.e. it did not decay and did not reverse.
+ *
+ * @param window1Deltas per-sample translateX deltas from the first observation window
+ * @param window2Deltas per-sample translateX deltas from the second (later) window
+ * @param sampleMs cadence between samples within a window
+ * @param minPxPerSec minimum sustained |velocity| to be considered moving at all
+ * @param relTol fractional tolerance: |v2| must be ≥ (1-relTol)·|v1| and same sign
+ */
+export function classifyVelocitySamples(
+  window1Deltas: number[],
+  window2Deltas: number[],
+  sampleMs: number,
+  minPxPerSec = 4,
+  relTol = 0.5,
+): { isMarquee: boolean; pxPerSec: number; v1: number; v2: number } {
+  const v1 = medianVelocityPxPerSec(window1Deltas, sampleMs);
+  const v2 = medianVelocityPxPerSec(window2Deltas, sampleMs);
+  // The reported velocity is the first window's (measured closest to a clean, post-settle
+  // marquee; also what the old code reported), kept for output determinism vs. the old path.
+  const pxPerSec = v1;
+  if (Math.abs(v1) < minPxPerSec || Math.abs(v2) < minPxPerSec) return { isMarquee: false, pxPerSec, v1, v2 };
+  if (Math.sign(v1) !== Math.sign(v2)) return { isMarquee: false, pxPerSec, v1, v2 }; // reversed → not a steady ticker
+  // v2 must NOT have decayed relative to v1 (a lerp settling toward target loses speed).
+  const sustained = Math.abs(v2) >= Math.abs(v1) * (1 - relTol);
+  return { isMarquee: sustained, pxPerSec, v1, v2 };
+}
+
+/**
+ * Discriminator 4 — genuine duplicated content. A marquee duplicates its content ≥2×
+ * (that is how a seamless loop works); "≥2 children" alone is far too weak (any flex row
+ * of distinct logos passes). Require actual repetition: ≥2 CONSECUTIVE children whose
+ * shape repeats — equal outerHTML hash (exact duplicate) or, as a looser structural
+ * fallback, an equal consecutive width sequence (some marquees clone then tweak attributes
+ * so hashes differ but the geometry repeats).
+ *
+ * @param hashes per-child outerHTML hash (cheap 32-bit), index-aligned with `widths`
+ * @param widths per-child rounded offsetWidth
+ */
+export function hasRepeatedChildren(hashes: number[], widths: number[]): boolean {
+  const n = Math.min(hashes.length, widths.length);
+  if (n < 2) return false;
+  // (a) two consecutive children with an identical hash — a literal cloned copy.
+  for (let i = 1; i < n; i++) if (hashes[i] === hashes[i - 1] && hashes[i] !== 0) return true;
+  // (b) structural fallback: the first half's width sequence repeats in the second half
+  // (content duplicated as a block, e.g. [A B C A B C]). Require an even count and a real
+  // width so a row of zero-width nodes can't spuriously "repeat".
+  if (n >= 4 && n % 2 === 0) {
+    const half = n / 2;
+    let repeats = true;
+    for (let i = 0; i < half; i++) { if (widths[i] === 0 || widths[i] !== widths[i + half]) { repeats = false; break; } }
+    if (repeats) return true;
+  }
+  return false;
+}
+
 export type MotionCapture = {
   waapi: WaapiAnim[];
   rotators: RotatorSpec[];
@@ -132,6 +209,25 @@ export async function probeReveals(page: Page): Promise<void> {
  * and record its signed velocity + seamless-loop period (one duplicated copy ≈ half the
  * scroll width) so the clone can replay the loop. Read-only beyond scrolling (restores
  * scroll to top); does not touch the captured snapshot/IR.
+ *
+ * Discriminators (ALL must pass — a candidate is only classified as a marquee if every one
+ * holds), added to defeat scroll-LINKED easing false positives (a static logo row on a
+ * scroll-eased page is still lerping toward its scroll-target right after `scrollIntoView`,
+ * which reads as a constant velocity over a single short window):
+ *   1. Content overflow — scrollWidth > 1.35·clientWidth (a marquee has content to scroll;
+ *      a static row that fits its box, scrollWidth ≈ clientWidth, cannot be a marquee).
+ *   2. Sustained constant velocity — two observation windows separated by ≥1.5s; a settle
+ *      lerp decays (v2 ≪ v1), a real marquee holds v2 ≈ v1 (see classifyVelocitySamples).
+ *   3. Scroll independence (jiggle) — nudge scroll by ±50px and re-sample; if the velocity
+ *      responds to the nudge the motion is scroll-linked, not a self-driven ticker.
+ *   4. Genuine duplication — ≥2 consecutive children repeat (equal outerHTML hash or an
+ *      equal consecutive width sequence), the shape real marquees use for a seamless loop.
+ *
+ * Added latency is bounded: the expensive per-candidate windows/jiggle run ONLY for the
+ * few candidates that already pass the cheap synchronous gates (overflow + translated +
+ * clip + duplication), and the candidate list is capped at 8. Per surviving candidate the
+ * async cost is ≈ 300ms settle + 2×~600ms windows + ~1.4s inter-window gap + 2×~250ms
+ * jiggle ≈ 3.4s; with the cap the whole pass is bounded regardless of page size.
  */
 async function detectMarquees(page: Page): Promise<MarqueeSpec[]> {
   try {
@@ -143,32 +239,113 @@ async function detectMarquees(page: Page): Promise<MarqueeSpec[]> {
         while (p && depth < 6) { const ox = getComputedStyle(p).overflowX; if (ox === "hidden" || ox === "clip") return true; p = p.parentElement; depth++; }
         return false;
       };
+      // cheap 32-bit string hash (djb2-ish) — deterministic, for the duplication test.
+      const hashStr = (s: string): number => { let h = 5381; for (let i = 0; i < s.length; i++) h = ((h << 5) + h + s.charCodeAt(i)) | 0; return h; };
+
+      // ---- Pure discriminators (mirror of the exported module-scope functions; kept inline
+      // because module scope does not cross the page.evaluate serialization boundary). ----
+      const medianVelocityPxPerSec = (deltas: number[], sampleMs: number): number => {
+        if (!deltas.length || sampleMs <= 0) return 0;
+        const med = [...deltas].sort((a, b) => a - b)[Math.floor(deltas.length / 2)]!;
+        return Math.round((med / sampleMs) * 1000);
+      };
+      const classifyVelocitySamples = (w1: number[], w2: number[], sampleMs: number, minPxPerSec = 4, relTol = 0.5) => {
+        const v1 = medianVelocityPxPerSec(w1, sampleMs);
+        const v2 = medianVelocityPxPerSec(w2, sampleMs);
+        const pxPerSec = v1;
+        if (Math.abs(v1) < minPxPerSec || Math.abs(v2) < minPxPerSec) return { isMarquee: false, pxPerSec, v1, v2 };
+        if (Math.sign(v1) !== Math.sign(v2)) return { isMarquee: false, pxPerSec, v1, v2 };
+        const sustained = Math.abs(v2) >= Math.abs(v1) * (1 - relTol);
+        return { isMarquee: sustained, pxPerSec, v1, v2 };
+      };
+      const hasRepeatedChildren = (hashes: number[], widths: number[]): boolean => {
+        const n = Math.min(hashes.length, widths.length);
+        if (n < 2) return false;
+        for (let i = 1; i < n; i++) if (hashes[i] === hashes[i - 1] && hashes[i] !== 0) return true;
+        if (n >= 4 && n % 2 === 0) {
+          const half = n / 2;
+          let repeats = true;
+          for (let i = 0; i < half; i++) { if (widths[i] === 0 || widths[i] !== widths[i + half]) { repeats = false; break; } }
+          if (repeats) return true;
+        }
+        return false;
+      };
+      // sample per-child outerHTML hash + width for the duplication test.
+      const childSignature = (el: Element): { hashes: number[]; widths: number[] } => {
+        const hashes: number[] = [], widths: number[] = [];
+        const kids = Array.from(el.children).slice(0, 24) as HTMLElement[];
+        for (const k of kids) { hashes.push(hashStr(k.outerHTML)); widths.push(Math.round(k.getBoundingClientRect().width)); }
+        return { hashes, widths };
+      };
+      // one observation window: `count` deltas at `sampleMs` cadence.
+      const sampleWindow = async (el: Element, count: number, sampleMs: number): Promise<number[]> => {
+        const xs: number[] = [txOf(el)];
+        for (let i = 0; i < count; i++) { await sleep(sampleMs); xs.push(txOf(el)); }
+        const dxs: number[] = []; for (let i = 1; i < xs.length; i++) dxs.push(xs[i]! - xs[i - 1]!);
+        return dxs;
+      };
+
+      const SAMPLE_MS = 120;
+      const WINDOW_SAMPLES = 5;            // 5 deltas ≈ 600ms per window
+      const INTER_WINDOW_MS = 1500;        // ≥1.5s between windows (discriminator 2)
+      const JIGGLE_PX = 50;                // scroll nudge for the independence test (discriminator 3)
+
       // Candidates: tagged, already translated (paused tickers keep their offset), with
-      // duplicated content (≥2 children) inside an overflow-clip viewport — the marquee shape.
+      // GENUINE duplicated content inside an overflow-clip viewport, AND real content
+      // overflow (scrollWidth > 1.35·clientWidth) — the marquee shape. All cheap/synchronous
+      // so the expensive async windows only run for the few survivors.
       const cand: Element[] = [];
       for (const el of Array.from(document.querySelectorAll("[data-cid-cap]"))) {
         if (Math.abs(txOf(el)) <= 0.5) continue;
         if (el.children.length < 2) continue;
         if (!inClip(el)) continue;
+        // Discriminator 1: content overflow. scrollWidth must meaningfully exceed clientWidth;
+        // a static row that fits (scrollWidth ≈ clientWidth) has nothing to scroll.
+        if (el.scrollWidth <= el.clientWidth * 1.35) continue;
+        // Discriminator 4: genuine repetition, not merely ≥2 distinct children.
+        const sig = childSignature(el);
+        if (!hasRepeatedChildren(sig.hashes, sig.widths)) continue;
         cand.push(el);
-        if (cand.length >= 16) break;
+        if (cand.length >= 8) break;
       }
       const out: Array<{ cap: string; axis: "x"; pxPerSec: number; periodPx: number }> = [];
       const seen = new Set<string>();
       for (const el of cand) {
         const cap = el.getAttribute("data-cid-cap"); if (!cap || seen.has(cap)) continue;
         try { el.scrollIntoView({ block: "center" }); } catch { /* ignore */ }
-        await sleep(450); // wake the off-screen-paused ticker + let the scroll settle
-        const xs: number[] = [];
-        for (let i = 0; i < 6; i++) { xs.push(txOf(el)); await sleep(120); }
-        const dxs: number[] = []; for (let i = 1; i < xs.length; i++) dxs.push(xs[i]! - xs[i - 1]!);
-        if (dxs.length < 3) continue;
-        // velocity = median per-120ms delta (median ignores the single wrap-reset outlier).
-        const med = [...dxs].sort((a, b) => a - b)[Math.floor(dxs.length / 2)]!;
-        const pxPerSec = Math.round((med / 120) * 1000);
-        if (Math.abs(pxPerSec) < 4) continue; // not actually moving (e.g. a frozen scroll-scrub offset)
-        // direction must be consistent in all but (at most) the one wrap step.
-        if (dxs.filter((d) => Math.sign(d) === Math.sign(med)).length < dxs.length - 1) continue;
+        await sleep(300); // wake the off-screen-paused ticker + let the scroll settle
+
+        // Discriminator 2: two velocity windows ≥1.5s apart. A scroll-settle lerp decays;
+        // a real marquee holds constant velocity.
+        const w1 = await sampleWindow(el, WINDOW_SAMPLES, SAMPLE_MS);
+        await sleep(INTER_WINDOW_MS);
+        const w2 = await sampleWindow(el, WINDOW_SAMPLES, SAMPLE_MS);
+        if (w1.length < 3 || w2.length < 3) continue;
+        // direction must be consistent within window 1, but for (at most) the one wrap step.
+        const med1 = [...w1].sort((a, b) => a - b)[Math.floor(w1.length / 2)]!;
+        if (w1.filter((d) => Math.sign(d) === Math.sign(med1)).length < w1.length - 1) continue;
+        const cls = classifyVelocitySamples(w1, w2, SAMPLE_MS);
+        if (!cls.isMarquee) continue;
+        const pxPerSec = cls.pxPerSec;
+
+        // Discriminator 3: scroll independence (jiggle). Nudge the scroll ±50px and re-sample
+        // velocity; a self-driven ticker is unaffected, a scroll-linked animation changes.
+        const baseY = window.scrollY;
+        const jiggle = async (dy: number): Promise<number> => {
+          try { window.scrollTo(0, Math.max(0, baseY + dy)); } catch { /* ignore */ }
+          await sleep(250); // let any scroll-linked easing react and settle at the new offset
+          const dxs = await sampleWindow(el, WINDOW_SAMPLES, SAMPLE_MS);
+          return medianVelocityPxPerSec(dxs, SAMPLE_MS);
+        };
+        const vDown = await jiggle(JIGGLE_PX);
+        const vUp = await jiggle(-JIGGLE_PX);
+        try { window.scrollTo(0, baseY); } catch { /* ignore */ }
+        // Scroll-linked motion responds to the nudge (velocity reverses, dies, or spikes as
+        // it re-lerps to the new target). A real marquee holds ~pxPerSec through both nudges.
+        const stableUnderJiggle = (v: number): boolean =>
+          Math.sign(v) === Math.sign(pxPerSec) && Math.abs(v) >= Math.abs(pxPerSec) * 0.5 && Math.abs(v) <= Math.abs(pxPerSec) * 2;
+        if (!stableUnderJiggle(vDown) || !stableUnderJiggle(vUp)) continue;
+
         const periodPx = Math.round(el.scrollWidth / 2);
         if (periodPx < 40) continue;
         seen.add(cap);
diff --git a/compiler/src/capture/walker.ts b/compiler/src/capture/walker.ts
index f44e9d1..54edb3f 100644
--- a/compiler/src/capture/walker.ts
+++ b/compiler/src/capture/walker.ts
@@ -380,9 +380,22 @@ export function collectPage(opts?: { maxNodes?: number } | void): PageSnapshot {
         const hf = el.getBoundingClientRect().height;
         // Tight 0.5px: only call a dimension "reproduced" when auto/100% lands essentially exactly,
         // so a drop can't accumulate a visible shift across many elements (favours fidelity).
+        let hAuto = Math.abs(ha - r.height) <= 0.5;
+        let hFill = Math.abs(hf - r.height) <= 0.5;
+        // Circular-height guard: a box whose fill child (height:100%) pins it back up makes BOTH
+        // `height:auto` and `height:100%` reproduce the box, so the raw verdict reads hAuto (drop) —
+        // even though the height is authored (e.g. `100vh` on a hero, an explicit px section). Both
+        // sides then wait on each other and the box collapses. When this element's own cascade/inline
+        // style declares an explicit definite height, trust that declaration: the height is authored,
+        // so it is neither content-sized (hAuto) nor a parent fill (hFill). Only overrides when auto
+        // actually reproduced — a genuine explicit height that auto already shrinks stays hAuto:false.
+        if ((hAuto || hFill) && r.height > 2 && authorsExplicitHeight(el, sh)) {
+          hAuto = false;
+          hFill = false;
+        }
         sizing = {
-          wAuto: Math.abs(wa - r.width) <= 0.5, wFill: Math.abs(wf - r.width) <= 0.5, hAuto: Math.abs(ha - r.height) <= 0.5,
-          hFill: Math.abs(hf - r.height) <= 0.5,
+          wAuto: Math.abs(wa - r.width) <= 0.5, wFill: Math.abs(wf - r.width) <= 0.5, hAuto,
+          hFill,
           wMin: Math.round(wmin * 100) / 100, wMax: Math.round(wmax * 100) / 100,
         };
       } finally {
@@ -492,6 +505,14 @@ export function collectPage(opts?: { maxNodes?: number } | void): PageSnapshot {
   const cssUrlSet = new Set<string>();
   const keyframes: string[] = [];
   const cssVars: Record<string, string> = {};
+  // Selectors that AUTHOR an explicit, definite height/min-height (px/rem/em/vh/vw/…,
+  // NOT auto, NOT a percentage, NOT a keyword). Harvested once from the cascade below and
+  // consulted by the sizing probe to break circular parent/child height verdicts: when a box
+  // and its fill child mutually justify each other's height, `height:auto` reproduces the box
+  // for a reason that is NOT "content-sized", so the probe alone reads hAuto:true and the
+  // authored dimension gets dropped downstream. A declared explicit length is ground truth that
+  // the height is load-bearing, so we trust the declaration over the reflow verdict.
+  const explicitHeightSelectors: string[] = [];
 
   const absUrl = (u: string): string => {
     try { return new URL(u, document.baseURI).href; } catch { return u; }
@@ -507,6 +528,39 @@ export function collectPage(opts?: { maxNodes?: number } | void): PageSnapshot {
     }
   };
 
+  // True when a `height`/`min-height` value is an explicit, definite length the browser resolves
+  // to a fixed px box (px/rem/em/vh/vw/vmin/vmax/ch/…, or a calc/min/max/clamp over them). False for
+  // `auto`, an empty value, a pure percentage (resolves against the parent — that's the fill case the
+  // hFill probe already handles), `0`, and intrinsic keywords (fit-/min-/max-content). A definite
+  // authored height is load-bearing and must survive even when the reflow probe reads hAuto:true.
+  const isExplicitHeight = (raw: string): boolean => {
+    const v = (raw || "").trim().toLowerCase();
+    if (!v || v === "auto" || v === "0" || v === "0px" || v === "none") return false;
+    if (v === "fit-content" || v === "min-content" || v === "max-content" || v === "inherit" ||
+      v === "initial" || v === "unset" || v === "revert" || v === "revert-layer") return false;
+    // A bare percentage resolves against the parent (fill), not an authored definite length.
+    if (/^[\d.]+%$/.test(v)) return false;
+    // A definite length unit (or a calc()/min()/max()/clamp() that contains one) anchors the box.
+    return /(?:^|[\s(*/+-])[\d.]+(?:px|rem|em|vh|vw|vmin|vmax|svh|lvh|dvh|cm|mm|in|pt|pc|ex|ch|q)\b/.test(v);
+  };
+
+  // Does this element author an explicit definite height — via its own inline style (passed as
+  // `inlineHeight`, already read by the probe) or via any matched cascade rule harvested into
+  // `explicitHeightSelectors`? getComputedStyle resolves height to used px (so `100vh` reads as a
+  // plain number and is indistinguishable from a content height there); the specified value is only
+  // recoverable from the inline declaration and the cascade, which is why we consult both.
+  const authorsExplicitHeight = (el: Element, inlineHeight: string): boolean => {
+    if (isExplicitHeight(inlineHeight)) return true;
+    try {
+      const inlineMin = (el as HTMLElement).style?.getPropertyValue("min-height") || "";
+      if (isExplicitHeight(inlineMin)) return true;
+    } catch { /* ignore */ }
+    for (const sel of explicitHeightSelectors) {
+      try { if (el.matches(sel)) return true; } catch { /* invalid/unsupported selector */ }
+    }
+    return false;
+  };
+
   const readRules = (rules: CSSRuleList): void => {
     for (const rule of Array.from(rules)) {
       const type = rule.constructor.name;
@@ -532,6 +586,11 @@ export function collectPage(opts?: { maxNodes?: number } | void): PageSnapshot {
       } else if (type === "CSSStyleRule") {
         const r = rule as CSSStyleRule;
         if (r.style && r.style.cssText.includes("url(")) harvestUrlsFromText(r.style.cssText);
+        if (r.selectorText && r.style &&
+          (isExplicitHeight(r.style.getPropertyValue("height")) ||
+            isExplicitHeight(r.style.getPropertyValue("min-height")))) {
+          explicitHeightSelectors.push(r.selectorText);
+        }
       } else if (type === "CSSMediaRule" || type === "CSSSupportsRule") {
         try { readRules((rule as CSSGroupingRule).cssRules); } catch { /* ignore */ }
       } else if (type === "CSSImportRule") {
diff --git a/compiler/src/generate/app.ts b/compiler/src/generate/app.ts
index 534a821..650998e 100644
--- a/compiler/src/generate/app.ts
+++ b/compiler/src/generate/app.ts
@@ -1,7 +1,7 @@
 import { join } from "node:path";
 import { rmSync } from "node:fs";
 import { writeText } from "../util/fsx.js";
-import type { IR, IRNode, IRChild, IRTextNode } from "../normalize/ir.js";
+import type { IR, IRNode, IRChild, IRTextNode, StyleMap } from "../normalize/ir.js";
 import { isTextChild } from "../normalize/ir.js";
 import { generateCss, RESET_CSS } from "./css.js";
 import { generateInteractionCss } from "./interactionCss.js";
@@ -2384,17 +2384,75 @@ ${input}
 `;
 }
 
-function recipeResponsiveClassCleaner(recipes: RecipeReport | undefined, opts: { tailwind: boolean }): (cid: string, className: string | undefined) => string | undefined {
+// Number of explicit column tracks in a computed `grid-template-columns` value. The capture
+// resolves the property to a used track list (e.g. `284px 284px 284px`), so track count is the
+// whitespace-separated token count; `none`/empty means the element is not a track grid.
+function computedTrackCount(value: string | undefined): number {
+  if (!value || value === "none") return 0;
+  return value.trim().split(/\s+/).filter(Boolean).length;
+}
+
+// Track span of a grid item from its resolved `grid-column-start`/`grid-column-end`. A spanning
+// item (`span 2`, or an explicit line pair `1 / 3`) means row-length item-counting under-reports
+// the real track count, so the column-count heuristic is not trustworthy for this container.
+function computedColumnSpan(cs: StyleMap | undefined): number {
+  if (!cs) return 1;
+  const end = cs["gridColumnEnd"];
+  const start = cs["gridColumnStart"];
+  const span = /^span\s+(\d+)$/.exec(end ?? "") ?? /^span\s+(\d+)$/.exec(start ?? "");
+  if (span) return Math.max(1, Number(span[1]));
+  if (start && end && /^-?\d+$/.test(start) && /^-?\d+$/.test(end)) {
+    const diff = Number(end) - Number(start);
+    if (Number.isFinite(diff) && diff > 1) return diff;
+  }
+  return 1;
+}
+
+export function recipeResponsiveClassCleaner(ir: IR, recipes: RecipeReport | undefined, opts: { tailwind: boolean }): (cid: string, className: string | undefined) => string | undefined {
   const recipeParents = new Set<string>();
   const repeatedGridParents = new Set<string>();
   const fillGridParents = new Set<string>();
+  // Containers whose computed geometry agreed with the item-count heuristic — a genuinely uniform
+  // repeated grid the recipe may re-flow. Row-track utilities are only stripped here; on containers
+  // where the geometry disagreed (spanning items / differing track count) the authored row and
+  // column tracks are ground truth and must survive.
+  const uniformGridParents = new Set<string>();
   const columnPlans = new Map<string, string[]>();
+  const nodeByCid = new Map<string, IRNode>();
+  const index = (n: IRNode): void => { nodeByCid.set(n.id, n); for (const c of n.children) if (!isTextChild(c)) index(c); };
+  index(ir.root);
+  // The captured/computed grid geometry is ground truth. A recipe may add semantic structure, but
+  // its column count is inferred by grouping item bounding boxes into rows — which under-reports the
+  // real track count whenever an item spans multiple columns. Before letting a recipe's synthesized
+  // column plan override the authored grid, cross-check it against the computed `grid-template-columns`
+  // track count and per-item `grid-column` spans at each regime viewport. On disagreement, keep the
+  // emitted (computed) geometry and drop the plan so spans and track count survive.
+  const planAgreesWithComputed = (c: RecipeReport["candidates"][number], regimeVps: number[]): boolean => {
+    const parent = c.itemParentCid ? nodeByCid.get(c.itemParentCid) : undefined;
+    if (!parent) return false;
+    const itemCids = (c.repeatedItems ?? []).map((i) => i.cid);
+    for (const vp of regimeVps) {
+      const tracks = computedTrackCount(parent.computedByVp[vp]?.["gridTemplateColumns"]);
+      // Only trust the heuristic where the computed grid actually is a track grid at this viewport.
+      if (tracks === 0) continue;
+      const regime = c.responsiveRegimes.find((r) => r.viewport === vp);
+      const heuristicCols = regime?.columns ?? 0;
+      if (heuristicCols > 0 && heuristicCols !== tracks) return false;
+      for (const cid of itemCids) {
+        if (computedColumnSpan(nodeByCid.get(cid)?.computedByVp[vp]) > 1) return false;
+      }
+    }
+    return true;
+  };
   const gridColumnTokens = (c: RecipeReport["candidates"][number]): string[] | null => {
     if (c.kind !== "card-grid" && c.kind !== "feature-grid" && c.kind !== "product-grid") return null;
     const regimes = c.responsiveRegimes
       .filter((r) => (r.visibleItems ?? 0) > 0 && (r.columns ?? 0) > 0)
       .sort((a, b) => a.viewport - b.viewport);
     if (regimes.length < 2) return null;
+    // The computed track geometry disagrees with the item-count heuristic (spanning items or a
+    // differing track count) — defer to the authored grid rather than synthesize a column plan.
+    if (!planAgreesWithComputed(c, regimes.map((r) => r.viewport))) return null;
     const prefixFor = (vp: number): string => vp >= 1536 ? "2xl:" : vp >= 1024 ? "lg:" : vp >= 768 ? "md:" : "";
     const tokens: string[] = [];
     let last: number | undefined;
@@ -2416,6 +2474,12 @@ function recipeResponsiveClassCleaner(recipes: RecipeReport | undefined, opts: {
   for (const c of recipes?.candidates ?? []) {
     if ((c.kind === "card-grid" || c.kind === "feature-grid" || c.kind === "product-grid" || c.kind === "gallery-showcase" || c.kind === "logo-cloud") && c.confidence >= 0.86 && c.itemParentCid) {
       recipeParents.add(c.itemParentCid);
+      // A container is a uniform repeated grid only if its computed track geometry agrees with the
+      // item-count heuristic at every sampled regime viewport (no spanning items, matching track
+      // count). Non-grid containers (flex/stack) have no computed tracks to disagree with, so they
+      // stay eligible; a track grid whose geometry disagrees is excluded and keeps its authored rows.
+      const sampledVps = c.responsiveRegimes.map((r) => r.viewport);
+      if (planAgreesWithComputed(c, sampledVps)) uniformGridParents.add(c.itemParentCid);
       if (c.kind === "card-grid" || c.kind === "feature-grid" || c.kind === "product-grid" || c.kind === "gallery-showcase") repeatedGridParents.add(c.itemParentCid);
       if (c.kind === "card-grid" || c.kind === "feature-grid" || c.kind === "product-grid") fillGridParents.add(c.itemParentCid);
       const columns = gridColumnTokens(c);
@@ -2429,8 +2493,8 @@ function recipeResponsiveClassCleaner(recipes: RecipeReport | undefined, opts: {
     const columnPlan = opts.tailwind ? columnPlans.get(cid) : undefined;
     const keep = tokens.filter((token) => {
       if (columnPlan && /^(?:[a-z0-9-]+:)*grid-cols-(?:\d+|\[[^\]]+\])$/.test(token)) return false;
-      if (/^(?:[a-z0-9-]+:)*grid-rows-\[(?:auto_?)+\]$/.test(token)) return false;
-      if (repeatedGridParents.has(cid) && /^(?:[a-z0-9-]+:)*grid-rows-\d+$/.test(token)) return false;
+      if (uniformGridParents.has(cid) && /^(?:[a-z0-9-]+:)*grid-rows-\[(?:auto_?)+\]$/.test(token)) return false;
+      if (uniformGridParents.has(cid) && repeatedGridParents.has(cid) && /^(?:[a-z0-9-]+:)*grid-rows-\d+$/.test(token)) return false;
       const initialCols = /^(?:(.*):)?grid-cols-\[initial\]$/.exec(token);
       if (initialCols) {
         const prefix = initialCols[1] ? `${initialCols[1]}:` : "";
@@ -2477,7 +2541,7 @@ export function generateApp(input: GenerateInput, tokensCss: string): { pageTsx:
   // CSS mode: dedup into shared semantic CSS classes. Both fidelity-neutral.
   const tw = humanize && mode === "tailwind" ? buildTailwind(ir, assetMap, input.colorVar, { interaction: input.interaction, reflow: input.reflow }) : undefined;
   const classMap = humanize && mode === "css" ? buildClassMap(ir, assetMap, input.colorVar, input.primitives, input.tokenResolver) : undefined;
-  const cleanRecipeClass = recipeResponsiveClassCleaner(input.recipeReport, { tailwind: !!tw });
+  const cleanRecipeClass = recipeResponsiveClassCleaner(ir, input.recipeReport, { tailwind: !!tw });
   const classOf = tw ? (cid: string) => cleanRecipeClass(cid, tw.classOf.get(cid)) : classMap ? (cid: string) => classMap.classOf.get(cid) : undefined;
   const styleOf = tw ? (cid: string) => tw.styleOf.get(cid) : undefined;
   // Section split (single-page humanized): plan section roots, render each into its own
diff --git a/compiler/src/generate/css.ts b/compiler/src/generate/css.ts
index 33e6ceb..e63de00 100644
--- a/compiler/src/generate/css.ts
+++ b/compiler/src/generate/css.ts
@@ -2208,6 +2208,8 @@ function declsForViewport(
   geometry: GeometryPlan = GEOMETRY_NONE,
   dropGridRows = false,
   dropViewportMaxWidth = false,
+  nowrapText = false,
+  keepIdentityTransform = false,
 ): Map<string, string> {
   const cs = node.computedByVp[vp];
   const out = new Map<string, string>();
@@ -2478,6 +2480,13 @@ function declsForViewport(
       // list reset is none; emit whatever the source uses (incl. none).
     } else if (prop === "minWidth") {
       if (value === "auto" || (value === "0px" && !isFlexGridItem) || (value === "0px" && inScrollXFlexStrip)) continue;
+    } else if (prop === "transform") {
+      // Emit the identity `transform:none` explicitly at a viewport whose value is `none` WHEN the node
+      // carries a non-identity transform at some OTHER band — otherwise the non-identity value cascades
+      // across bands and freezes at a width the source left untransformed. (Identity matrices are already
+      // canonicalized to the literal "none" upstream, so the string compare is reliable.) When the node
+      // is identity everywhere, this stays a normal default elision.
+      if (value === "none" && !keepIdentityTransform) continue;
     } else if (def === "__never__") {
       // always emit (display/color/fontFamily/fontSize handled below for inherit)
     } else if (isDefault(def, value)) {
@@ -2506,6 +2515,15 @@ function declsForViewport(
     out.set(kebab(prop), outValue);
   }
 
+  // Wrap-vulnerable single-line text: the text renders on one line at every captured width and its
+  // unwrapped width nearly equals the container's available width, so a sub-pixel width shortfall in
+  // the clone (a column resolving ~0.6px narrower) tips it onto a second line, shifting everything
+  // below. `white-space:nowrap` holds it to one line — identical to the capture (already single-line
+  // at every width) but immune to the rounding shortfall. Only the source `whiteSpace` value that
+  // already collapses runs (`normal`/`nowrap`) is overridden; `pre`/`pre-wrap`/`break-spaces` preserve
+  // authored whitespace and are left untouched (the caller's detector also excludes them).
+  if (nowrapText) out.set("white-space", "nowrap");
+
   // Centered max-width container: emit auto side margins so the browser centers
   // it at every width. getComputedStyle sometimes reports 0 for resolved auto
   // margins at wide viewports, so replaying px would left-align the clone.
@@ -2641,7 +2659,14 @@ function centeredAtVp(node: IRNode, parentNode: IRNode, vp: number): boolean {
   // marquee). Converting fixed spacing to `auto` deletes it when the parent shrink-wraps the child
   // (auto resolves to 0) — exactly how the testimonial inter-card gap vanished. Literal margins
   // reproduce that spacing at every width regardless of the parent's resolved width.
-  if (ml > 0.5 && Math.abs(ml - mr) < 1 && nb.width < pb.width - 4 && marginsVaryAcrossVps(node)) return true;
+  // The width must ALSO be genuinely constrained: a box the sizing probe reads as a container-FILL
+  // (`width:100%` reproduces it) has no free space for auto margins to absorb — the emitted width
+  // is set to 100% (fill/fillcap), so `margin:auto` resolves to 0 and silently deletes real literal
+  // px side margins, blowing a padded pill/section out to full-bleed. Equal literal margins are the
+  // geometric TWIN of centering slack (both split the free space symmetrically), so this probe read
+  // is the only reliable discriminator between them; when the box fills, keep the literal margins.
+  const fillsAtVp = node.sizingByVp?.[vp]?.wFill === true;
+  if (ml > 0.5 && Math.abs(ml - mr) < 1 && nb.width < pb.width - 4 && marginsVaryAcrossVps(node) && !fillsAtVp) return true;
   if (parentFlexGrid) return false;
   // Signal 2: bbox-centered within the parent content box with ~0 reported margins.
   if (Math.abs(ml) > 0.5 || Math.abs(mr) > 0.5) return false; // margins already explain position
@@ -2654,6 +2679,45 @@ function centeredAtVp(node: IRNode, parentNode: IRNode, vp: number): boolean {
   return leftGap > 1 && rightGap > 1 && Math.abs(leftGap - rightGap) < 1.5 && nb.width < contentRight - contentLeft - 2;
 }
 
+/** A single-line text leaf whose unwrapped width nearly fills its container's available width at
+ *  EVERY captured viewport where it's painted — so any sub-pixel width shortfall in the clone (a
+ *  column resolving fractionally narrower) tips it onto a second line. Such a node earns an explicit
+ *  `white-space:nowrap` (see declsForViewport) to stay one line as it did in the capture.
+ *  Conservative by construction — every guard must hold at every painted viewport:
+ *   • text leaf (direct text, no element children), whitespace not already preserved (`pre*`);
+ *   • single line: box height ≈ one line box (line-height + vertical padding/border), so a genuinely
+ *     wrapping paragraph (≥2 line boxes tall) is excluded;
+ *   • wrap-vulnerable: max-content (unwrapped) width ≥ available container width − 2 and ≤ it + 1 —
+ *     the text needs essentially all the available width, with no slack for a rounding shortfall;
+ *   • genuinely wrappable: min-content < max-content − 2, so a single unbreakable token (which can
+ *     never wrap, making nowrap a redundant no-op) is skipped to keep the emission minimal.
+ *  Relies on the sizing probe's wMin/wMax (present only for in-flow probed leaves); absent ⇒ no emit. */
+function nowrapWrapVulnerable(node: IRNode, parentNode: IRNode | undefined, viewports: number[]): boolean {
+  if (!parentNode) return false;
+  if (hasElementChild(node)) return false;
+  if (!node.children.some((c) => isTextChild(c) && c.text.trim() !== "")) return false;
+  if (REPLACED.has(node.tag) || node.tag === "canvas" || node.tag.includes("-")) return false;
+  let painted = 0;
+  for (const vp of viewports) {
+    const cs = node.computedByVp[vp]; const nb = node.bboxByVp[vp];
+    if (!cs || !nb || !node.visibleByVp[vp] || (cs.display || "") === "none") continue;
+    if (!(nb.width > 0) || !(nb.height > 0)) continue;
+    const ws = cs.whiteSpace || "normal";
+    if (ws !== "normal" && ws !== "nowrap") return false; // pre/pre-wrap/break-spaces preserve authored whitespace
+    const sz = node.sizingByVp?.[vp];
+    const wMax = sz?.wMax; const wMin = sz?.wMin;
+    if (wMax == null || wMin == null) return false;
+    const lineBox = pf(cs.lineHeight) + pf(cs.paddingTop) + pf(cs.paddingBottom) + pf(cs.borderTopWidth) + pf(cs.borderBottomWidth);
+    if (!(lineBox > 0) || Math.abs(nb.height - lineBox) > 2.5) return false; // not single-line
+    const avail = containingWidthAt(node, parentNode, vp);
+    if (avail == null) return false;
+    if (!(wMax >= avail - 2 && wMax <= avail + 1)) return false; // not right at the container edge
+    if (!(wMin < wMax - 2)) return false;                        // single unbreakable token — can't wrap
+    painted++;
+  }
+  return painted >= 1;
+}
+
 function hasPxMaxWidthCap(node: IRNode, viewports: number[]): boolean {
   const caps: number[] = [];
   for (const vp of viewports) {
@@ -3106,6 +3170,21 @@ export function collectNodeRules(ir: IR, assetMap: Map<string, string>, includeN
       : inferred.plan;
     const centerAlways = inferred.centerAlways;
     const centeredAtAnySample = !!layoutParent && sampleVps.some((vp) => centeredAtVp(node, layoutParent, vp));
+    // A single-line text leaf sitting flush against its container's available width at every painted
+    // width → `white-space:nowrap` so a sub-pixel column shortfall in the clone can't wrap it. Decided
+    // once per node (uniform across bands); measured against layoutParent to see through contents wrappers.
+    const nowrapText = !isContents && nowrapWrapVulnerable(node, layoutParent, sampleVps);
+    // If this node has a NON-identity transform at any painted band, the identity `none` must be
+    // emitted at the bands that have it so the transform can't cascade across bands (freezing a
+    // width the source left untransformed). Identity matrices are canonicalized to "none" upstream.
+    let hasNonIdentityTransform = false, hasIdentityTransform = false;
+    for (const vp of sampleVps) {
+      const t = node.computedByVp[vp]?.transform;
+      if (t === undefined) continue;
+      if (t === "none") hasIdentityTransform = true;
+      else hasNonIdentityTransform = true;
+    }
+    const keepIdentityTransform = hasNonIdentityTransform && hasIdentityTransform;
     const stableCenter =
       centerAlways ||
       sourceMarginAutoIntent(node) ||
@@ -3175,7 +3254,7 @@ export function collectNodeRules(ir: IR, assetMap: Map<string, string>, includeN
       dropInsets.delete("left");
     }
     const animOwned = animOwnedProps(node, baseVp); // opacity/transform driven by an infinite animation
-    const baseDecls = finalizeDecls(declsForViewport(node, parentNode?.computedByVp[baseVp], baseVp, assetMap, centeredBase, colorVar, ir.doc.perViewport[baseVp]?.scrollHeight, widthPlan, gridColsByVp?.get(baseVp), gridRowsByVp?.get(baseVp), flowH, dropInsets, leftPct, heightFill, geometry, dropGridRows, dropViewportMaxWidth), tokenResolver);
+    const baseDecls = finalizeDecls(declsForViewport(node, parentNode?.computedByVp[baseVp], baseVp, assetMap, centeredBase, colorVar, ir.doc.perViewport[baseVp]?.scrollHeight, widthPlan, gridColsByVp?.get(baseVp), gridRowsByVp?.get(baseVp), flowH, dropInsets, leftPct, heightFill, geometry, dropGridRows, dropViewportMaxWidth, nowrapText, keepIdentityTransform), tokenResolver);
     const nr: NodeRule = { base: baseDecls, bands: [] };
 
     // Per-band overrides (delta vs base), using the parent's value AT THAT viewport.
@@ -3247,7 +3326,7 @@ export function collectNodeRules(ir: IR, assetMap: Map<string, string>, includeN
         }
       }
       const centeredVp = stableCenter || (layoutParent ? centeredAtVp(node, layoutParent, b.vp) : false);
-      const vpDecls = finalizeDecls(declsForViewport(node, parentNode?.computedByVp[b.vp], b.vp, assetMap, centeredVp, colorVar, ir.doc.perViewport[b.vp]?.scrollHeight, widthPlan, gridColsByVp?.get(b.vp), gridRowsByVp?.get(b.vp), flowH, dropInsets, leftPct, heightFill, geometry, dropGridRows, dropViewportMaxWidth), tokenResolver);
+      const vpDecls = finalizeDecls(declsForViewport(node, parentNode?.computedByVp[b.vp], b.vp, assetMap, centeredVp, colorVar, ir.doc.perViewport[b.vp]?.scrollHeight, widthPlan, gridColsByVp?.get(b.vp), gridRowsByVp?.get(b.vp), flowH, dropInsets, leftPct, heightFill, geometry, dropGridRows, dropViewportMaxWidth, nowrapText, keepIdentityTransform), tokenResolver);
       const delta = new Map<string, string>();
       for (const [k, v] of vpDecls) if (baseDecls.get(k) !== v) delta.set(k, v);
       for (const [k] of baseDecls) if (!vpDecls.has(k)) delta.set(k, resetValue(k));
diff --git a/compiler/src/generate/lottie.ts b/compiler/src/generate/lottie.ts
index 7eeb49d..233007e 100644
--- a/compiler/src/generate/lottie.ts
+++ b/compiler/src/generate/lottie.ts
@@ -126,7 +126,7 @@ const byCid = (cid: string): HTMLElement | null => document.querySelector('[data
 export default function DittoLottie({ spec }: { spec: LottieSpec }) {
   useEffect(() => {
     const stopped = (window as any).__dittoMotionStopped === true;
-    const anims: Array<{ destroy: () => void; goToAndStop: (value: number, isFrame?: boolean) => void }> = [];
+    const anims: Array<{ destroy: () => void; goToAndStop: (value: number, isFrame?: boolean) => void; addEventListener: (name: string, cb: () => void) => void }> = [];
     let cancelled = false;
     void (async () => {
       const lottie = (await import("lottie-web")).default;
@@ -134,17 +134,38 @@ export default function DittoLottie({ spec }: { spec: LottieSpec }) {
       for (const it of spec.items) {
         const el = byCid(it.cid);
         if (!el) continue;
-        // clear the captured placeholder frame so it never stacks with the live render
-        el.innerHTML = "";
         try {
+          // Mount the live animation into an OVERLAY child, keeping the captured placeholder
+          // frame in the DOM until lottie signals a successful load — a failed load (bad JSON,
+          // network) then leaves the placeholder intact instead of erasing the container to blank.
+          const mount = document.createElement("div");
+          mount.style.position = "absolute";
+          mount.style.inset = "0";
+          mount.style.opacity = "0";
+          const cs = getComputedStyle(el);
+          if (cs.position === "static") el.style.position = "relative";
+          el.appendChild(mount);
           const anim = lottie.loadAnimation({
-            container: el,
+            container: mount,
             renderer: it.renderer === "canvas" ? "canvas" : "svg",
             loop: it.loop,
             autoplay: it.autoplay && !stopped,
             ...(it.path ? { path: it.path } : { animationData: it.animationData as object }),
             rendererSettings: { preserveAspectRatio: "xMidYMid meet" },
           });
+          // Swap only once the animation is genuinely ready: reveal the live render and remove
+          // every original child (the placeholder) so the two never stack.
+          const reveal = () => {
+            mount.style.opacity = "1";
+            for (const child of Array.from(el.childNodes)) if (child !== mount) el.removeChild(child);
+            mount.style.position = "";
+            mount.style.inset = "";
+          };
+          // DOMLoaded fires only after the JSON parsed and the first frame rendered — the
+          // right moment to reveal the live render and drop the placeholder. data_failed
+          // (bad JSON / fetch error) tears the empty mount back out, leaving the placeholder.
+          anim.addEventListener("DOMLoaded", reveal);
+          anim.addEventListener("data_failed", () => { try { el.removeChild(mount); } catch {} });
           if (stopped) { try { anim.goToAndStop(0, true); } catch {} }
           anims.push(anim);
         } catch {
diff --git a/compiler/src/generate/tailwind.ts b/compiler/src/generate/tailwind.ts
index 0c8a80f..8a88904 100644
--- a/compiler/src/generate/tailwind.ts
+++ b/compiler/src/generate/tailwind.ts
@@ -563,7 +563,6 @@ function namedText(base: string): string | null {
 // nearest scale step / integer px when comfortably INSIDE that budget (ε well under the gate tol), so
 // the markup reads hand-authored. Bounded ε + the layout & perceptual gates backstop any accumulation;
 // values not near a step stay arbitrary because they are genuine one-offs.
-const SNAP_SPACE_PX = 1.0; // padding/margin/gap/inset/size → nearest 0.25rem scale step within this
 const SNAP_TYPE_PX = 0.6;  // font-size/line-height/radius → nearest integer px within this
 const NAMED_K_SORTED = [...NAMED_K].sort((a, b) => a - b);
 function nearestNamedK(k: number): number {
@@ -571,7 +570,7 @@ function nearestNamedK(k: number): number {
   for (const c of NAMED_K_SORTED) if (Math.abs(c - k) < Math.abs(best - k)) best = c;
   return best;
 }
-function snapBase(base: string): string {
+export function snapBase(base: string): string {
   const m = /^(-?)([a-z][a-z-]*)-\[(-?\d*\.?\d+)(px|rem)\]$/.exec(base);
   if (!m) return base;
   const neg = m[1]!, prefix = m[2]!, px = parseFloat(m[3]!) * (m[4] === "rem" ? 16 : 1);
@@ -587,10 +586,16 @@ function snapBase(base: string): string {
     if (Math.abs(r - px) <= SNAP_TYPE_PX && r in RADIUS_SUFFIX) return `${prefix}${RADIUS_SUFFIX[r]}`;
     return base;
   }
-  // spacing / size → nearest named scale step (0.25rem grid)
+  // spacing / size → nearest named scale step (0.25rem grid). Only snap a value that lands ESSENTIALLY
+  // ON a step (≤0.25px): the scale is 2px-granular (`p-0.5`=2px, `p-1.5`=6px), so a captured value ≥0.25px
+  // off the nearest step is a genuine sub-step measurement (3.5px is BETWEEN 2px and 4px — not on the
+  // scale). Snapping such a value up by +0.5px per side accumulates across the links of a fixed-width
+  // flex row until the items overflow and wrap to a second line; the exact `p-[3.5px]` cannot. The wider
+  // ±1px budget the gate tolerates in isolation is unsafe here because the error is systematic, not
+  // random. Values genuinely on a step (2px→`p-0.5`, 4px→`p-1`) still snap.
   if (SCALE_PREFIXES.has(prefix)) {
     const k = nearestNamedK(px / 4);
-    if (Math.abs(k * 4 - px) <= SNAP_SPACE_PX) return k === 0 ? `${neg}${prefix}-0` : `${neg}${prefix}-${k}`;
+    if (Math.abs(k * 4 - px) <= 0.25) return k === 0 ? `${neg}${prefix}-0` : `${neg}${prefix}-${k}`;
   }
   return base;
 }
diff --git a/compiler/src/normalize/ir.ts b/compiler/src/normalize/ir.ts
index ee0116b..7b5b485 100644
--- a/compiler/src/normalize/ir.ts
+++ b/compiler/src/normalize/ir.ts
@@ -188,6 +188,44 @@ function elementChildren(n: RawNode): RawNode[] {
   return n.children.filter((c) => (c as { text?: string }).text === undefined) as RawNode[];
 }
 
+/** True for a transform value that is visually the identity (no offset/rotation/scale):
+ *  the `none` keyword or an identity matrix/matrix3d the browser reports as noise. */
+export function isIdentityTransform(value: string | undefined): boolean {
+  if (!value || value === "none") return true;
+  const m = /^matrix\(([^)]*)\)$/.exec(value.trim());
+  if (m) {
+    const n = m[1]!.split(",").map((s) => parseFloat(s.trim()));
+    return n.length === 6 && n[0] === 1 && n[1] === 0 && n[2] === 0 && n[3] === 1 && n[4] === 0 && n[5] === 0;
+  }
+  const m3 = /^matrix3d\(([^)]*)\)$/.exec(value.trim());
+  if (m3) {
+    const n = m3[1]!.split(",").map((s) => parseFloat(s.trim()));
+    const id = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+    return n.length === 16 && n.every((v, i) => v === id[i]);
+  }
+  return false;
+}
+
+/**
+ * Normalize per-viewport transform values so identity is represented uniformly as the literal
+ * `none`. Two problems this closes, both in the per-viewport delta emission downstream:
+ *   1. The browser reports "no transform" inconsistently — `none` at some widths, an identity
+ *      `matrix(1,0,0,1,0,0)` at others (composited-layer noise). The generator's default-skip
+ *      only recognizes `none`, so an identity matrix at the base viewport is emitted as a real
+ *      transform and then cascades across bands.
+ *   2. When ANY viewport carries a genuine (non-identity) transform, the identity value at the
+ *      other viewports must stay observable — canonicalizing it to `none` (not dropping it) lets
+ *      the generator emit the explicit reset so the non-identity transform can't leak into a band
+ *      where the source had none.
+ * Deterministic, in place; only touches the `transform` slot.
+ */
+export function canonicalizeTransforms(computedByVp: Record<number, StyleMap>): void {
+  for (const k of Object.keys(computedByVp)) {
+    const cs = computedByVp[Number(k)];
+    if (cs && isIdentityTransform(cs.transform)) cs.transform = "none";
+  }
+}
+
 /** Full identity signature (tag + id + class). */
 function sigFull(n: RawNode): string {
   return `${n.tag}#${n.attrs?.id ?? ""}.${(n.attrs?.class ?? "").trim()}`;
@@ -328,6 +366,10 @@ export function buildIR(sourceDir: string, viewports: number[], opts?: { motion?
       if (match.after) afterByVp[vw] = match.after;
       if (match.placeholder) placeholderByVp[vw] = match.placeholder;
     }
+    // Canonicalize identity transforms (none / identity matrix) to `none` at every viewport so
+    // the generator's per-band delta treats them uniformly and a scroll/composite-noise transform
+    // at one width can't leak across bands.
+    canonicalizeTransforms(computedByVp);
 
     const node: IRNode = {
       id: nextId(),
diff --git a/compiler/src/runner/codeAudit.ts b/compiler/src/runner/codeAudit.ts
index 5328f3f..9e66344 100644
--- a/compiler/src/runner/codeAudit.ts
+++ b/compiler/src/runner/codeAudit.ts
@@ -1,142 +1,141 @@
 /**
- * Code-quality audit — count the "bad code" tells that make a generated clone read robotic, for any
- * number of app source trees, side by side. Repeatable: point it at shipped deliverables and it
- * prints one column per tree.
+ * Code-quality audit — an honest, human-readable report over one or more generated app
+ * trees. Built directly on the dimension scorer in ./qualityScore, so the audit and the
+ * shipped `code-quality.md` quality number never disagree.
  *
- *   npm run audit                                  # auto: every output/<site>/app
- *   npm run audit -- <dir> [<dir> ...]             # explicit trees; .clone resolves to sibling app/
- *   npm run audit -- output/example/app
+ *   npm run audit                                  # auto: every runs/<site>/latest/generated/app
+ *   npm run audit -- <appDir> [<appDir> ...]       # explicit app trees
+ *   npm run audit -- runs/example/latest/generated/app
+ *   npm run audit -- <dir> --json                  # machine-readable
  *
- * Scans .tsx/.jsx/.ts/.css under each dir (skips node_modules/.next/out/dotfiles). Every metric is a
- * COUNT where lower is better, except the two "good" context rows (fluid width / standard scale).
- * The decisive "decimal" tell is non-integer-PX: each arbitrary px/rem is converted to px and flagged
- * if it isn't a whole pixel (a frozen measurement), so a clean 12.5rem (=200px) does NOT count.
+ * For each tree it prints:
+ *   • the LETTER GRADE + numeric score (and any hard-cap reason),
+ *   • a per-DIMENSION table (payload / decomposition / duplication / semantics / hygiene
+ *     / runtime) with the visible sub-metrics behind each score,
+ *   • the TOP OFFENDERS (file, metric, value) — the worst individual tells.
+ * When several trees are passed it also prints a side-by-side grade comparison.
+ *
+ * Pure static analysis over generated source (.tsx/.jsx/.ts/.astro/.css). No builds, no
+ * browser. See qualityScore.ts for the rubric + the (calibration-guide) thresholds.
  */
-import { readdirSync, statSync, readFileSync, existsSync } from "node:fs";
-import { join, resolve, basename, dirname, sep } from "node:path";
+import { readdirSync, statSync, existsSync } from "node:fs";
+import { join, resolve, basename } from "node:path";
+import { scoreApp, type QualityReport } from "./qualityScore.js";
 
-type Row = { label: string; lowerBetter: boolean; values: number[] };
-type Target = { inputDir: string; scanDir: string; validationDir?: string };
+// ---------------------------------------------------------------------------
+// Target resolution — accept an app dir directly, or discover deliverables.
+// ---------------------------------------------------------------------------
 
-function readTree(dir: string): { tsx: string; css: string; all: string } {
-  const tsxParts: string[] = [], cssParts: string[] = [];
-  const walk = (d: string): void => {
-    for (const n of readdirSync(d)) {
-      if (n === "node_modules" || n === ".next" || n === "out" || n.startsWith(".")) continue;
-      const p = join(d, n);
-      const st = statSync(p);
-      if (st.isDirectory()) walk(p);
-      else if (/\.(tsx|jsx|ts)$/.test(n)) tsxParts.push(readFileSync(p, "utf8"));
-      else if (/\.css$/.test(n)) cssParts.push(readFileSync(p, "utf8"));
+/** Is `dir` a scannable app tree (has a src/ with code in it, or is itself full of code)? */
+function isAppDir(dir: string): boolean {
+  if (!existsSync(dir)) return false;
+  if (existsSync(join(dir, "src"))) return true;
+  try { return readdirSync(dir).some((n) => /\.(tsx|jsx|ts|css|astro)$/.test(n)); } catch { return false; }
+}
+
+/** Discover every runs/<site>/latest/generated/app deliverable, newest layout first.
+ *  Checks both the cwd and its parent, so `npm run audit` works whether invoked from the
+ *  repo root or from compiler/ (where runs/ lives one level up). */
+function discoverTargets(): string[] {
+  const out: string[] = [];
+  const roots = ["runs", "output", "../runs", "../output"].map((r) => resolve(r)).filter(existsSync);
+  for (const root of roots) {
+    let sites: string[];
+    try { sites = readdirSync(root); } catch { continue; }
+    for (const site of sites) {
+      for (const app of [
+        join(root, site, "latest", "generated", "app"),
+        join(root, site, "app"),
+      ]) {
+        if (isAppDir(app)) { out.push(app); break; }
+      }
     }
-  };
-  walk(dir);
-  const tsx = tsxParts.join("\n"), css = cssParts.join("\n");
-  return { tsx, css, all: tsx + "\n" + css };
+  }
+  return out;
 }
 
-/** All metric counts for one tree. */
-function audit(target: Target): Record<string, number> {
-  const dir = target.scanDir;
-  const { tsx, css, all } = readTree(dir);
-  const n = (re: RegExp, s = all): number => (s.match(re) || []).length;
-  const validationDataCid = target.validationDir && existsSync(target.validationDir)
-    ? (readTree(target.validationDir).all.match(/data-cid/g) || []).length
-    : 0;
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
 
-  // Arbitrary px/rem values + the non-integer-px ("decimal") subset, the decisive measurement tell.
-  let arb = 0, decimal = 0;
-  for (const m of all.matchAll(/\[(-?[0-9]+\.?[0-9]*)(px|rem)\]/g)) {
-    arb++;
-    const px = parseFloat(m[1]!) * (m[2] === "rem" ? 16 : 1);
-    if (Math.abs(px - Math.round(px)) > 0.02) decimal++;
-  }
-
-  return {
-    "files (tsx+css)": (tsx ? 1 : 0), // overwritten below with real file counts
-    "── BAD (lower=better) ──": -1,
-    "fixed width  w-[Npx/rem]": n(/\bw-\[-?[0-9.]+(?:px|rem)\]/g),
-    "fixed height h-[Npx/rem]": n(/\bh-\[-?[0-9.]+(?:px|rem)\]/g),
-    "breakpoint utilities": n(/\b(?:sm|md|lg|xl|2xl|max-sm|max-md|max-lg|max-xl):/g),
-    "arbitrary bands min/max-[Npx]:": n(/\b(?:min|max)-\[[0-9]+px\]:/g),
-    "arbitrary […px/rem] total": arb,
-    "decimal (non-integer px)": decimal,
-    "baked position top/left/inset-[N]": n(/\b(?:top|left|right|bottom|inset(?:-x|-y)?)-\[-?[0-9.]+(?:px|rem)\]/g),
-    "raw color literal [#hex/rgb]": n(/\[(?:#[0-9a-fA-F]{3,8}|rgba?\([^\]]*)\]/g),
-    "per-side border longhand": n(/\[border-(?:top|right|bottom|left)-(?:style|color):/g),
-    "data-cid (shipped)": n(/data-cid/g),
-    "data-cid (validation-only)": validationDataCid,
-    "dangerouslySetInnerHTML": n(/dangerouslySetInnerHTML/g),
-    "': any' props": n(/:\s*any\b/g),
-    "robotic 'Generated by' comments": n(/Generated by clone|clone-static/g),
-    "── GOOD (higher=better) ──": -1,
-    "fluid width (w-full/auto/fraction)": n(/\bw-(?:full|auto|fit|screen|\d{1,2}\/\d{1,2})\b/g),
-    "standard scale (gap-2/w-10/p-4…)": n(/\b(?:gap|p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|w|h)-(?:0|0\.5|1|1\.5|2|2\.5|3|3\.5|4|5|6|7|8|9|10|11|12|14|16|20|24|28|32|36|40|44|48|52|56|60|64|72|80|96|px)\b/g),
-  };
+/** A readable column label for a target (its site/run name where possible). */
+function labelFor(dir: string): string {
+  const parts = resolve(dir).split("/");
+  const runsIdx = parts.lastIndexOf("runs");
+  const outIdx = parts.lastIndexOf("output");
+  const i = runsIdx >= 0 ? runsIdx : outIdx;
+  if (i >= 0 && parts[i + 1]) return parts[i + 1]!.slice(0, 22);
+  return (parts[parts.length - 2] ?? basename(dir)).slice(0, 22);
 }
 
-function fileCount(dir: string): number {
-  let c = 0;
-  const walk = (d: string): void => { for (const x of readdirSync(d)) { if (x === "node_modules" || x === ".next" || x === "out" || x.startsWith(".")) continue; const p = join(d, x); statSync(p).isDirectory() ? walk(p) : (/\.(tsx|jsx|ts|css)$/.test(x) && c++); } };
-  walk(dir);
-  return c;
+const pad = (s: string, w: number): string => s + " ".repeat(Math.max(0, w - s.length));
+const padL = (s: string, w: number): string => " ".repeat(Math.max(0, w - s.length)) + s;
+
+function renderReport(label: string, rep: QualityReport): string {
+  const L: string[] = [];
+  L.push("");
+  L.push(`━━━ ${label} ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+  L.push(`  GRADE ${rep.grade}   (${rep.total}/100)`);
+  if (rep.caps.length) {
+    L.push(`  HARD CAP → grade limited to D-range:`);
+    for (const c of rep.caps) L.push(`    • ${c}`);
+  }
+  L.push("");
+  L.push(`  ${pad("dimension", 15)}${padL("score", 9)}   sub-metrics`);
+  L.push(`  ${"─".repeat(66)}`);
+  for (const [dim, cat] of Object.entries(rep.categories)) {
+    const metrics = Object.entries(cat.metrics).map(([k, v]) => `${k}=${v}`).join(" ");
+    L.push(`  ${pad(dim, 15)}${padL(`${cat.score}/${cat.max}`, 9)}   ${metrics}`);
+  }
+  if (rep.offenders.length) {
+    L.push("");
+    L.push(`  top offenders`);
+    L.push(`  ${pad("metric", 34)}${padL("value", 12)}  file`);
+    L.push(`  ${"─".repeat(66)}`);
+    for (const o of rep.offenders.slice(0, 10)) {
+      L.push(`  ${pad(o.metric, 34)}${padL(String(o.value), 12)}  ${o.file}`);
+    }
+  }
+  return L.join("\n");
 }
 
-function normalizeTarget(input: string): Target {
-  const d = resolve(input);
-  const asApp = (appDir: string, validationDir?: string): Target => ({ inputDir: d, scanDir: appDir, validationDir });
-  if (basename(d) === ".clone") {
-    const app = join(dirname(d), "app");
-    const validation = join(d, "generated", "app");
-    if (existsSync(join(app, "src"))) return asApp(app, existsSync(validation) ? validation : undefined);
+function renderComparison(labels: string[], reps: QualityReport[]): string {
+  const L: string[] = [];
+  const colW = Math.max(12, ...labels.map((l) => l.length + 2));
+  L.push("");
+  L.push(`━━━ comparison ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+  L.push("  " + pad("dimension", 15) + labels.map((l) => padL(l, colW)).join(""));
+  const dims = Object.keys(reps[0]!.categories);
+  for (const d of dims) {
+    L.push("  " + pad(d, 15) + reps.map((r) => padL(String(r.categories[d]!.score), colW)).join(""));
   }
-  const generatedSuffix = `${sep}.clone${sep}generated${sep}app`;
-  if (d.endsWith(generatedSuffix)) {
-    const cloneDir = d.slice(0, -`${sep}generated${sep}app`.length);
-    const app = join(dirname(cloneDir), "app");
-    if (existsSync(join(app, "src"))) return asApp(app, d);
-  }
-  if (basename(d) === "generated" && existsSync(join(d, "app", "src"))) {
-    const cloneDir = dirname(d);
-    const app = join(dirname(cloneDir), "app");
-    if (basename(cloneDir) === ".clone" && existsSync(join(app, "src"))) return asApp(app, join(d, "app"));
-  }
-  return { inputDir: d, scanDir: d };
+  L.push("  " + pad("GRADE", 15) + reps.map((r) => padL(`${r.grade} (${r.total})`, colW)).join(""));
+  return L.join("\n");
 }
 
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
 function main(): void {
   const args = process.argv.slice(2).filter((a) => !a.startsWith("--"));
-  let targets: Target[];
-  if (args.length) targets = args.map(normalizeTarget);
-  else {
-    // Auto: every output/<site>/app deliverable.
-    const outRoot = resolve("output");
-    const sites = existsSync(outRoot)
-      ? readdirSync(outRoot).map((s) => join(outRoot, s, "app")).filter((p) => existsSync(join(p, "src")))
-      : [];
-    targets = sites.map(normalizeTarget);
-  }
-  targets = targets.filter((t) => existsSync(t.scanDir));
-  if (!targets.length) { console.error("no app trees found — pass dirs explicitly"); process.exit(1); }
+  const asJson = process.argv.includes("--json");
+  const targets = (args.length ? args.map((a) => resolve(a)) : discoverTargets()).filter(isAppDir);
+  if (!targets.length) { console.error("no app trees found — pass app dirs explicitly (e.g. runs/<site>/latest/generated/app)"); process.exit(1); }
 
-  // A readable column label: the deliverable dir's parent name, or the scanned dir name.
-  const label = (t: Target): string => (basename(dirname(t.scanDir)) || basename(t.scanDir)).slice(0, 16);
-  const labels = targets.map(label);
-  const audits = targets.map(audit);
-  audits.forEach((a, i) => { a["files (tsx+css)"] = fileCount(targets[i]!.scanDir); });
+  const labels = targets.map(labelFor);
+  const reports = targets.map((t) => scoreApp(t));
 
-  const keys = Object.keys(audits[0]!);
-  const w0 = Math.max(...keys.map((k) => k.length));
-  const colW = Math.max(11, ...labels.map((l) => l.length));
-  const pad = (s: string, w: number) => s + " ".repeat(Math.max(0, w - s.length));
-  console.log("\n" + pad("metric", w0) + "  " + labels.map((l) => pad(l, colW)).join(""));
-  console.log("─".repeat(w0 + 2 + colW * labels.length));
-  for (const k of keys) {
-    if (audits[0]![k] === -1) { console.log(pad(k, w0)); continue; } // section header
-    const cells = audits.map((a) => pad(String(a[k] ?? 0), colW)).join("");
-    console.log(pad(k, w0) + "  " + cells);
+  if (asJson) {
+    console.log(JSON.stringify(reports.map((r, i) => ({ label: labels[i], ...r })), null, 2));
+    return;
   }
-  console.log("\n(counts; lower is better in the BAD block, higher in the GOOD block. 'decimal' = the\n arbitrary value's px isn't a whole pixel — the frozen-measurement tell.)\n");
+
+  for (let i = 0; i < reports.length; i++) console.log(renderReport(labels[i]!, reports[i]!));
+  if (reports.length > 1) console.log(renderComparison(labels, reports));
+  console.log("\n(scores are out of each dimension's max; grade is the weighted blend, capped to\n D-range if any single file/line/blob is in catastrophic payload territory.)\n");
 }
 
-main();
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}
diff --git a/compiler/src/runner/qualityScore.ts b/compiler/src/runner/qualityScore.ts
index 8ff0d7c..dea52c2 100644
--- a/compiler/src/runner/qualityScore.ts
+++ b/compiler/src/runner/qualityScore.ts
@@ -1,23 +1,93 @@
 /**
- * Output-quality rubric (deterministic, framework-agnostic).
+ * Output-quality rubric — HONEST edition (deterministic, framework-agnostic).
  *
  * The fidelity gates (validate/gates.ts) measure whether the clone *looks and
  * behaves* like the source. They say nothing about whether the generated CODE is
- * good — componentized, semantically named, styled through a reusable token/class
- * system, editable, and well organized. That "developer-facing quality" is exactly
- * where a deterministic converter is judged once fidelity is a given.
+ * good — small files, decomposed into real components, semantic and accessible,
+ * free of capture artifacts, and safe at runtime. That "developer-facing quality"
+ * is what a deterministic converter is judged on once fidelity is a given.
  *
- * This module statically analyzes a generated app directory and scores it 0–100 on
- * six categories. It reads only source text (`.tsx/.jsx/.ts/.astro/.css`). The
- * metrics are chosen to be framework-agnostic: e.g. "style reuse" rewards shared
- * classes whether they're Tailwind utilities or semantic clone classes, and
- * penalizes per-node unique rules (`.c1{...} .c2{...}`) regardless of framework.
+ * This module statically analyzes a generated app directory (source text only —
+ * `.tsx/.jsx/.ts/.astro/.css`) and scores it 0–100 across SIX dimensions, each
+ * with visible subscores. The score is a weighted blend of the dimensions EXCEPT
+ * that a single dimension in catastrophic territory (a multi-megabyte source file,
+ * a 100KB+ single line) HARD-CAPS the overall grade into D-range no matter how
+ * clean everything else is — because such a file is unopenable, un-diffable, and
+ * un-editable, which is the whole point of "good code".
+ *
+ * The signals are deliberately general (payload bytes, LOC distribution, repeated
+ * definitions, semantic-tag ratios, whitespace/capture artifacts, uncleaned
+ * listeners) so the scorer is not tuned to any specific site — it measures the
+ * failure *modes* a robotic converter falls into, not any one output.
  *
  * Pure + deterministic: same directory ⇒ same score.
  */
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import { join, extname, basename, relative } from "node:path";
 
+// ===========================================================================
+// CALIBRATION CONSTANTS
+// ---------------------------------------------------------------------------
+// These are CALIBRATION GUIDES, expected to be tuned as the generator and our
+// taste evolve — they are NOT compliance targets or contractual thresholds. A
+// number here answers "where does a human reviewer start wincing?", set from
+// observed good vs. bad outputs, and should be re-fit (not litigated) whenever
+// calibration drifts. Every knob lives in this one block on purpose.
+// ===========================================================================
+const K = {
+  // ---- payload discipline (a file/line so big it is not human-readable) ----
+  FILE_BYTES_GOOD: 30_000, // ≤30KB source file: comfortable to open
+  FILE_BYTES_BAD: 160_000, // ≥160KB: a reviewer scrolls forever; scores ~0
+  LINE_CHARS_GOOD: 2_000, // a formatted line, allowing for a dense data/JSX row
+  LINE_CHARS_BAD: 30_000, // a giant one-liner (minified / HTML-as-string prop)
+  INLINE_BYTES_GOOD: 50_000, // total base64 / inline-HTML bytes that's forgivable
+  INLINE_BYTES_BAD: 2_000_000, // 2MB+ of embedded blobs: catastrophic payload
+  // Catastrophe caps: any ONE of these forces the whole app into D-range.
+  CATASTROPHE_FILE_BYTES: 1_000_000, // a >1MB source file
+  CATASTROPHE_LINE_CHARS: 100_000, // a >100KB single line
+  CATASTROPHE_INLINE_BYTES: 5_000_000, // >5MB of embedded base64/HTML
+  CAP_GRADE_D: 68, // ceiling applied when a catastrophe fires — top of the D band, so a
+  //   catastrophic payload can grade no better than D+ regardless of other dimensions
+  // Softer cap for "very bad but not unopenable" payloads.
+  WARN_FILE_BYTES: 350_000,
+  WARN_LINE_CHARS: 40_000,
+  CAP_GRADE_C: 78, // ceiling for the softer warning band (top of C+)
+
+  // ---- component decomposition (is the page a monolith?) ----
+  MONOLITH_DOMINANCE_GOOD: 0.3, // biggest file ≤30% of all tags → well spread
+  MONOLITH_DOMINANCE_BAD: 0.75, // one file holds ≥75% of the page → monolith
+  BIG_SECTION_LINES: 600, // a "section" this long is really a whole page
+  COMPONENTS_GOOD: 12, // this many real components → full decomposition credit
+
+  // ---- duplication ----
+  DUP_HELPER_RATIO_BAD: 0.4, // ≥40% of helper defs are copy-paste duplicates
+  DUP_SVG_PATH_RATIO_BAD: 0.85, // ≥85% of inline <path> strings are repeats (shared
+  //   icon sets legitimately repeat, so only near-total duplication is a real tell)
+  NEAR_DUP_COMPONENT_BAD: 14, // this many near-identical NON-trivial component pairs → 0
+  NEAR_DUP_MIN_TAGS: 8, // ignore tiny components (icons/logos) in near-dup detection
+
+  // ---- semantics / a11y ----
+  DIV_RATIO_GOOD: 0.6, // ≤60% of elements are bare div/span → healthy
+  DIV_RATIO_BAD: 0.9, // ≥90% divs → div soup
+  ALT_COVERAGE_GOOD: 0.9, // ≥90% of <img> carry alt=
+  H1_REQUIRED: 1, // a page really should have exactly one <h1>
+
+  // ---- hygiene ----
+  // {" "} literals and sub-pixel arbitraries are a KNOWN baseline quirk of this
+  // converter present in even good output — only pathological volumes should bite,
+  // so these BADs sit well above what a "decent" tree emits.
+  WS_LITERAL_PER_KTAG_GOOD: 100, // per 1000 tags a converter routinely emits some
+  WS_LITERAL_PER_KTAG_BAD: 1200, // this many → capture-whitespace noise dominates
+  SUBPIXEL_PER_KTAG_GOOD: 60, // some frozen measurements are unavoidable
+  SUBPIXEL_PER_KTAG_BAD: 260, // a wall of frozen sub-pixels → machine replay
+  OPAQUE_TOKEN_RATIO_BAD: 0.6, // ≥60% of CSS custom props are opaque --clr-N / hashes
+  PROBE_ARTIFACTS_BAD: 8, // off-screen capture-probe text leaks
+
+  // ---- runtime discipline ----
+  LEAK_LISTENERS_GOOD: 8, // a small shared runtime bundle carries a few listeners
+  LEAK_LISTENERS_BAD: 30, // this many uncleaned adds → real leak territory
+} as const;
+
 // ---------------------------------------------------------------------------
 // File collection
 // ---------------------------------------------------------------------------
@@ -51,13 +121,43 @@ export function collectFiles(root: string): SrcFile[] {
 }
 
 // ---------------------------------------------------------------------------
-// Primitive extraction
+// Small helpers
+// ---------------------------------------------------------------------------
+
+const clamp01 = (x: number): number => Math.max(0, Math.min(1, x));
+/** Linear ramp: v in [lo,hi] → [0,1]. Handles lo>hi (descending / "lower is better"). */
+function ramp(v: number, lo: number, hi: number): number {
+  if (lo === hi) return v >= hi ? 1 : 0;
+  return clamp01((v - lo) / (hi - lo));
+}
+/** A value where HIGHER is worse: good at `good`, zero at `bad`. */
+const penalize = (v: number, good: number, bad: number): number => 1 - ramp(v, good, bad);
+const r1 = (n: number): number => Math.round(n * 10) / 10;
+
+/** Longest single line (in chars) in a file. */
+function maxLineLen(text: string): number {
+  let max = 0, start = 0;
+  for (let i = 0; i < text.length; i++) {
+    if (text.charCodeAt(i) === 10) { if (i - start > max) max = i - start; start = i + 1; }
+  }
+  if (text.length - start > max) max = text.length - start;
+  return max;
+}
+
+/** Count JSX/HTML opening element tags — a framework-agnostic page-size proxy. */
+function countTags(text: string): number {
+  const m = text.match(/<[a-zA-Z][a-zA-Z0-9.]*(\s|\/|>)/g);
+  return m ? m.length : 0;
+}
+
+// ---------------------------------------------------------------------------
+// Structural classification
 // ---------------------------------------------------------------------------
 
 const CONFIG_NAME_RE = /(config|tsconfig|next-env|site-config|content\.config|\.config\.)/i;
 const ROOT_NAME_RE = /(^|\/)(layout|_app|_document|root-layout)\.[jt]sx$/i;
-/** Files that compose the whole page (the "entry"): page.tsx (Next), index/page in a
- *  pages/ dir, home.tsx, or an .astro route shell. Used for the dominance metric. */
+const SECTION_WORDS = ["hero", "footer", "navbar", "nav", "header", "about", "cta", "feature", "pricing", "faq", "logo", "logocloud", "testimonial", "gallery", "stories", "spotlight", "knowledge", "news", "apply", "contact", "banner", "team", "stats", "partners", "alumni", "founder", "section"];
+
 function isEntryFile(rel: string): boolean {
   const b = basename(rel).toLowerCase();
   if (/^(page|index|home|app)\.[jt]sx$/.test(b)) return true;
@@ -66,54 +166,8 @@ function isEntryFile(rel: string): boolean {
   return false;
 }
 
-const SECTION_WORDS = ["hero", "footer", "navbar", "nav", "header", "about", "cta", "feature", "pricing", "faq", "logo", "logocloud", "testimonial", "gallery", "stories", "spotlight", "knowledge", "news", "apply", "contact", "banner", "team", "stats", "partners", "alumni", "founder", "section"];
-
-/** Count JSX/HTML opening element tags — a framework-agnostic proxy for page size
- *  (how many DOM nodes the output describes). Excludes React fragments + closing tags. */
-function countTags(text: string): number {
-  const m = text.match(/<[a-zA-Z][a-zA-Z0-9.]*(\s|\/|>)/g);
-  return m ? m.length : 0;
-}
-
-/** All className / class string-literal tokens used on elements (space split).
- *  Catches JSX attribute form (className="…"), object/spread form (className: "…" —
- *  what our generator emits), and hoisted className consts. A dynamic per-node class
- *  (className: "c" + d._cid / className={"c"+…}) renders a UNIQUE opaque class per
- *  instance, so each occurrence is recorded as its own opaque token (keeping the
- *  reuse + semantic metrics honest for the per-node-CSS strategy). */
-function classTokens(text: string): string[] {
-  const out: string[] = [];
-  // className="..."  /  className: "..."  /  "class": "..."  (attr + object form)
-  const re = /\b(?:className|class)\s*(?:=|:)\s*"([^"]*)"/g;
-  let m: RegExpExecArray | null;
-  while ((m = re.exec(text)) !== null) {
-    for (const t of m[1]!.split(/\s+/)) if (t) out.push(t);
-  }
-  // hoisted className consts: const xClassName = "..."
-  const re2 = /\b(?:const|let)\s+\w*[Cc]lassName\w*\s*=\s*"([^"]*)"/g;
-  while ((m = re2.exec(text)) !== null) {
-    for (const t of m[1]!.split(/\s+/)) if (t) out.push(t);
-  }
-  // dynamic per-node class: className: "c" + d._cid  /  className={"c"+ ...}
-  const dyn = (text.match(/\bclassName\s*(?:=\s*\{|:)\s*"c[a-z]?"\s*\+/g) ?? []).length
-    + (text.match(/\bclassName\s*(?:=\s*\{|:)\s*"c[a-z]?\d*"\s*\+/g) ?? []).length;
-  for (let i = 0; i < dyn; i++) out.push(`c__dyn${out.length}`); // unique opaque per occurrence
-  return out;
-}
-
-const CID_CLASS_RE = /^c[a-z]?\d+$/; // our legacy per-node class: c12 / cn12
-/** A class token that carries no human meaning (pure id / hash). */
-function isOpaqueClass(t: string): boolean {
-  if (CID_CLASS_RE.test(t)) return true;
-  if (/^[a-z]?\d+$/.test(t)) return true;
-  // hashed CSS-module-ish tokens: _foo_ab12 or 6-hex tails
-  if (/_[a-z0-9]{5,}$/i.test(t) && /\d/.test(t)) return true;
-  return false;
-}
-
 const GENERIC_COMP_RE = /^(Item|Card|List|ListItem|Link|LinkItem|Wrapper|Box|Div|El|Node|Group|Block|Comp|Component|Row|Col|Cell|Thing|Unit|Part|Chunk)\d*$/;
-/** Exported / defined component names in a file. */
-function componentNames(text: string): string[] {
+export function componentNames(text: string): string[] {
   const names = new Set<string>();
   let m: RegExpExecArray | null;
   const re1 = /export\s+default\s+function\s+([A-Z]\w*)/g;
@@ -125,221 +179,428 @@ function componentNames(text: string): string[] {
   return [...names];
 }
 
-/** Data/content field names declared in a content or data module. */
-function contentFieldNames(text: string): string[] {
-  const out: string[] = [];
-  // type Foo = { a: string; b?: number } — capture keys
-  const typeBlocks = text.match(/(?:type|interface)\s+\w+\s*=?\s*\{([^}]*)\}/g) ?? [];
-  for (const blk of typeBlocks) {
-    const re = /(\w+)\s*\??\s*:/g; let m: RegExpExecArray | null;
-    while ((m = re.exec(blk)) !== null) out.push(m[1]!);
+// ===========================================================================
+// METRIC EXTRACTORS  (exported for unit tests — each is a pure text→number/obj)
+// ===========================================================================
+
+/** Bytes of embedded base64 blobs + HTML passed as string props/dangerous html. */
+export function inlineBlobBytes(text: string): number {
+  let bytes = 0;
+  // base64 data URIs — the payload after the comma.
+  for (const m of text.matchAll(/data:[^;,'"`)\s]*;base64,([A-Za-z0-9+/=]+)/g)) bytes += m[1]!.length;
+  // dangerouslySetInnerHTML / html-string props: a big string literal handed to markup.
+  for (const m of text.matchAll(/dangerouslySetInnerHTML/g)) void m;
+  // A very long string literal that is actually markup ("<div ...</div>" as a prop).
+  for (const m of text.matchAll(/"((?:[^"\\]|\\.){2000,})"/g)) {
+    const s = m[1]!;
+    if (/<[a-z][a-z0-9]*[\s>]/i.test(s) && (s.match(/</g)?.length ?? 0) > 20) bytes += s.length;
   }
-  return out;
+  return bytes;
+}
+
+/** Payload facts about one file. */
+export function filePayload(f: SrcFile): { bytes: number; maxLine: number; inlineBytes: number } {
+  return { bytes: f.text.length, maxLine: maxLineLen(f.text), inlineBytes: inlineBlobBytes(f.text) };
+}
+
+/** {" "} / {' '} whitespace-only JSX expression literals (a capture artifact). */
+export function whitespaceLiterals(text: string): number {
+  return (text.match(/\{\s*["'`]\s+["'`]\s*\}/g) ?? []).length
+    + (text.match(/\{["'`]\\u00a0["'`]\}/gi) ?? []).length;
+}
+
+/** Frozen sub-pixel arbitrary values: `[12.5px]`, `w-[713.938px]` where px isn't whole. */
+export function subpixelArbitraries(text: string): number {
+  let n = 0;
+  for (const m of text.matchAll(/\[(-?[0-9]+\.?[0-9]*)(px|rem)\]/g)) {
+    const px = parseFloat(m[1]!) * (m[2] === "rem" ? 16 : 1);
+    if (Math.abs(px - Math.round(px)) > 0.02) n++;
+  }
+  return n;
+}
+
+/** CSS custom-property definitions split into opaque (--clr-7, --c12, hashes) vs named. */
+export function customPropTokens(text: string): { total: number; opaque: number } {
+  let total = 0, opaque = 0;
+  for (const m of text.matchAll(/(^|[^\w-])(--[\w-]+)\s*:/g)) {
+    const name = m[2]!.slice(2); // strip leading --
+    total++;
+    if (/^(clr|c|color|var|token|t|v|n|x)?-?\d+$/i.test(name) || /^[a-f0-9]{6,}$/i.test(name)) opaque++;
+  }
+  return { total, opaque };
+}
+
+/** Off-screen capture-probe text leaks (measurement scaffolding shipped into markup):
+ *  probe data-attrs, __probe__ markers, and clip:rect(0…) off-screen clipping. */
+export function probeArtifacts(text: string): number {
+  return (text.match(/(?:data-(?:probe|measure|ditto-probe)|__probe__|offscreen-probe|clip:\s*["'`]?\s*rect\(\s*0)/g) ?? []).length;
+}
+
+/** addEventListener calls with no matching removeEventListener / cleanup return. */
+export function uncleanedListeners(text: string): number {
+  const adds = (text.match(/\.addEventListener\s*\(/g) ?? []).length;
+  const removes = (text.match(/\.removeEventListener\s*\(/g) ?? []).length;
+  // A cleanup return (useEffect teardown / AbortController) neutralizes some adds.
+  const hasCleanupReturn = /return\s*\(\s*\)\s*=>/.test(text) || /new AbortController/.test(text) || /\{\s*signal\s*\}/.test(text);
+  const covered = hasCleanupReturn ? Math.max(removes, adds) : removes;
+  return Math.max(0, adds - covered);
+}
+
+/** Element-tag histogram for a whole tree of markup text. */
+export function tagHistogram(text: string): Record<string, number> {
+  const h: Record<string, number> = {};
+  for (const m of text.matchAll(/<([a-z][a-z0-9]*)(?:\s|\/|>)/g)) {
+    const t = m[1]!;
+    h[t] = (h[t] ?? 0) + 1;
+  }
+  return h;
+}
+
+/** aria-hidden applied to a focusable/interactive element in the same tag. */
+export function ariaHiddenFocusables(text: string): number {
+  let n = 0;
+  for (const m of text.matchAll(/<(a|button|input|select|textarea)\b[^>]*aria-hidden\s*=\s*["'{]?\s*true/gi)) void m;
+  n += (text.match(/<(?:a|button|input|select|textarea)\b[^>]*aria-hidden\s*=\s*["'{]?\s*true/gi) ?? []).length;
+  return n;
+}
+
+/** Repeated helper/function definitions with identical bodies (copy-paste, not shared). */
+export function duplicateHelpers(text: string): { defs: number; dups: number } {
+  const bodies = new Map<string, number>();
+  // named function / arrow-const helper definitions with a brace body.
+  const re = /(?:function\s+\w+\s*\([^)]*\)|const\s+\w+\s*=\s*(?:\([^)]*\)|\w+)\s*=>)\s*\{([\s\S]{40,600}?)\}/g;
+  let m: RegExpExecArray | null;
+  let defs = 0;
+  while ((m = re.exec(text)) !== null) {
+    defs++;
+    const key = m[1]!.replace(/\s+/g, " ").trim();
+    bodies.set(key, (bodies.get(key) ?? 0) + 1);
+  }
+  let dups = 0;
+  for (const c of bodies.values()) if (c > 1) dups += c - 1;
+  return { defs, dups };
+}
+
+/** Inline SVG <path d="…"> strings, and how many are exact repeats. */
+export function svgPathDuplication(text: string): { total: number; repeats: number } {
+  const seen = new Map<string, number>();
+  let total = 0;
+  for (const m of text.matchAll(/\bd\s*=\s*["']([Mm][^"']{20,})["']/g)) {
+    total++;
+    const key = m[1]!;
+    seen.set(key, (seen.get(key) ?? 0) + 1);
+  }
+  let repeats = 0;
+  for (const c of seen.values()) if (c > 1) repeats += c - 1;
+  return { total, repeats };
+}
+
+/** Near-identical component pairs: same tag-histogram signature across component files. */
+export function nearDuplicateComponents(sigs: string[]): number {
+  const counts = new Map<string, number>();
+  for (const s of sigs) counts.set(s, (counts.get(s) ?? 0) + 1);
+  let pairs = 0;
+  for (const c of counts.values()) if (c > 1) pairs += c - 1;
+  return pairs;
 }
-const PLUMBING_FIELD_RE = /^(_cid\d*|cid\d*|value\d*|val\d*|f\d+|d\d+|field\d+|key\d*|prop\d+|arg\d+)$/;
 
 // ---------------------------------------------------------------------------
-// Scoring
+// Grading
 // ---------------------------------------------------------------------------
 
+export type LetterGrade = "A" | "A-" | "B+" | "B" | "B-" | "C+" | "C" | "C-" | "D+" | "D" | "D-" | "F";
+export function toLetter(total: number): LetterGrade {
+  if (total >= 93) return "A";
+  if (total >= 90) return "A-";
+  if (total >= 87) return "B+";
+  if (total >= 83) return "B";
+  if (total >= 80) return "B-";
+  if (total >= 77) return "C+";
+  if (total >= 73) return "C";
+  if (total >= 70) return "C-";
+  if (total >= 66) return "D+";
+  if (total >= 63) return "D";
+  if (total >= 60) return "D-";
+  return "F";
+}
+
 export type CategoryScore = { score: number; max: number; metrics: Record<string, number | string> };
+export type Offender = { file: string; metric: string; value: number };
 export type QualityReport = {
   dir: string;
   total: number;
+  grade: LetterGrade;
+  caps: string[];
   categories: Record<string, CategoryScore>;
+  offenders: Offender[];
   raw: Record<string, number>;
 };
 
-const clamp01 = (x: number): number => Math.max(0, Math.min(1, x));
-/** Linear ramp: value v mapped from [lo,hi] → [0,1]. */
-const ramp = (v: number, lo: number, hi: number): number => clamp01((v - lo) / (hi - lo));
-const r1 = (n: number): number => Math.round(n * 10) / 10;
+/** Dimension weights (sum = 100). Guiding, not exact — see CALIBRATION note.
+ *  Payload + decomposition carry the most weight because an unopenable, monolithic
+ *  file is the defect a reviewer notices first; hygiene/duplication are lighter
+ *  because this converter's baseline (some {" "}, shared icons) is tolerable. */
+const WEIGHTS = {
+  payload: 26,
+  decomposition: 18,
+  duplication: 12,
+  semantics: 18,
+  hygiene: 14,
+  runtime: 12,
+} as const;
 
 export function scoreApp(root: string): QualityReport {
   const files = collectFiles(root);
-  const tsx = files.filter((f) => f.ext === ".tsx" || f.ext === ".jsx" || f.ext === ".astro");
+  const markup = files.filter((f) => f.ext === ".tsx" || f.ext === ".jsx" || f.ext === ".astro");
   const css = files.filter((f) => f.ext === ".css");
+  const runtimeFiles = files.filter((f) => f.ext === ".ts" || f.ext === ".tsx" || f.ext === ".jsx");
 
-  // Component modules = JSX-bearing files that aren't config/root-layout.
-  const componentModules = tsx.filter((f) =>
+  const componentModules = markup.filter((f) =>
     !CONFIG_NAME_RE.test(f.rel) && !ROOT_NAME_RE.test(f.rel) && countTags(f.text) > 0);
   const nonEntry = componentModules.filter((f) => !isEntryFile(f.rel));
+  const allText = files.map((f) => f.text).join("\n");
+  const markupText = markup.map((f) => f.text).join("\n");
 
   const totalTags = componentModules.reduce((s, f) => s + countTags(f.text), 0) || 1;
-  const entryFiles = componentModules.filter((f) => isEntryFile(f.rel));
   const maxFileTags = Math.max(0, ...componentModules.map((f) => countTags(f.text)));
-  const dominance = maxFileTags / totalTags; // 1.0 = one giant file
+  const kTags = totalTags / 1000;
 
-  // Section-named components (semantic top-level blocks). Tokenize the file path +
-  // component names into words (splitting camelCase, kebab, snake, slashes) so both
-  // `hero-section.tsx` and `HeroSection` are credited.
-  const isSectionFile = (f: SrcFile): boolean => {
-    const raw = f.rel + " " + componentNames(f.text).join(" ");
-    const words = new Set(raw.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean));
-    return SECTION_WORDS.some((w) => words.has(w));
+  const offenders: Offender[] = [];
+  const caps: string[] = [];
+
+  // =========================================================================
+  // 1. PAYLOAD DISCIPLINE — no file/line/blob a human cannot open.
+  // =========================================================================
+  let worstFileBytes = 0, worstFileRel = "";
+  let worstLine = 0, worstLineRel = "";
+  let totalInlineBytes = 0, worstInlineRel = "", worstInlineBytes = 0;
+  for (const f of files) {
+    const p = filePayload(f);
+    if (p.bytes > worstFileBytes) { worstFileBytes = p.bytes; worstFileRel = f.rel; }
+    if (p.maxLine > worstLine) { worstLine = p.maxLine; worstLineRel = f.rel; }
+    totalInlineBytes += p.inlineBytes;
+    if (p.inlineBytes > worstInlineBytes) { worstInlineBytes = p.inlineBytes; worstInlineRel = f.rel; }
+  }
+  if (worstFileRel) offenders.push({ file: worstFileRel, metric: "file bytes", value: worstFileBytes });
+  if (worstLineRel) offenders.push({ file: worstLineRel, metric: "max line chars", value: worstLine });
+  if (worstInlineBytes > 0) offenders.push({ file: worstInlineRel, metric: "inline blob bytes", value: worstInlineBytes });
+
+  // Worst-file penalty, tempered by how WIDESPREAD oversized files are: one big section
+  // in an otherwise-small tree is forgivable; many oversized files is systemic bloat.
+  const oversized = files.filter((f) => f.text.length >= K.FILE_BYTES_GOOD * 2).length;
+  const pFileMax = penalize(worstFileBytes, K.FILE_BYTES_GOOD, K.FILE_BYTES_BAD);
+  const pFileSpread = penalize(oversized, 0, Math.max(3, files.length * 0.25));
+  const pFile = 0.6 * pFileMax + 0.4 * pFileSpread;
+  const pLine = penalize(worstLine, K.LINE_CHARS_GOOD, K.LINE_CHARS_BAD);
+  const pInline = penalize(totalInlineBytes, K.INLINE_BYTES_GOOD, K.INLINE_BYTES_BAD);
+  const payloadSub = 0.4 * pFile + 0.35 * pLine + 0.25 * pInline;
+
+  // =========================================================================
+  // 2. COMPONENT DECOMPOSITION — is the page a monolith?
+  // =========================================================================
+  const dominance = maxFileTags / totalTags; // 1.0 = one giant file holds the page
+  const bigSections = componentModules.filter((f) => f.lines >= K.BIG_SECTION_LINES && !isEntryFile(f.rel)).length;
+  for (const f of componentModules) {
+    if (f.lines >= K.BIG_SECTION_LINES && !isEntryFile(f.rel)) offenders.push({ file: f.rel, metric: "section LOC", value: f.lines });
+  }
+  const dMono = penalize(dominance, K.MONOLITH_DOMINANCE_GOOD, K.MONOLITH_DOMINANCE_BAD);
+  const dCount = ramp(nonEntry.length, 0, K.COMPONENTS_GOOD);
+  const dBig = penalize(bigSections, 0, 3);
+  const decompositionSub = 0.45 * dMono + 0.3 * dCount + 0.25 * dBig;
+
+  // =========================================================================
+  // 3. DUPLICATION — repeated helpers, near-identical components, repeated SVG paths.
+  // =========================================================================
+  let helperDefs = 0, helperDups = 0;
+  for (const f of runtimeFiles) { const d = duplicateHelpers(f.text); helperDefs += d.defs; helperDups += d.dups; }
+  const svgDup = svgPathDuplication(markupText);
+  // Near-dup signatures over NON-trivial CONTENT components only: vectorized assets
+  // (icons, logos, illustration frames) legitimately share a tag shape, so counting
+  // them as "duplicates" would punish healthy asset sets rather than real copy-paste.
+  const isAssetFile = (rel: string): boolean => /(^|\/)svgs?\//i.test(rel) || /(icon|illustration|logo)\d*\.[jt]sx$/i.test(basename(rel));
+  const compSigs = nonEntry.filter((f) => !isAssetFile(f.rel)).map((f) => {
+    const h = tagHistogram(f.text);
+    const tags = Object.values(h).reduce((a, b) => a + b, 0);
+    if (tags < K.NEAR_DUP_MIN_TAGS) return "";
+    return Object.keys(h).sort().map((k) => `${k}:${h[k]}`).join(",");
+  }).filter((s) => s.length > 0);
+  const nearDup = nearDuplicateComponents(compSigs);
+
+  const helperDupRatio = helperDefs ? helperDups / helperDefs : 0;
+  const svgDupRatio = svgDup.total ? svgDup.repeats / svgDup.total : 0;
+  if (helperDups > 0) offenders.push({ file: "(helpers)", metric: "duplicate helper defs", value: helperDups });
+  if (svgDup.repeats > 0) offenders.push({ file: "(inline svg)", metric: "repeated <path> strings", value: svgDup.repeats });
+  if (nearDup > 0) offenders.push({ file: "(components)", metric: "near-identical component pairs", value: nearDup });
+
+  const uHelper = penalize(helperDupRatio, 0, K.DUP_HELPER_RATIO_BAD);
+  const uSvg = penalize(svgDupRatio, 0, K.DUP_SVG_PATH_RATIO_BAD);
+  const uNear = penalize(nearDup, 0, K.NEAR_DUP_COMPONENT_BAD);
+  // Helper duplication is the strongest tell; near-dup components second; inline-SVG
+  // path repeats are the weakest (shared icon sets repeat legitimately).
+  const duplicationSub = 0.5 * uHelper + 0.35 * uNear + 0.15 * uSvg;
+
+  // =========================================================================
+  // 4. SEMANTICS / A11Y — real tags over div soup, one h1, alt coverage, no aria traps.
+  // =========================================================================
+  const hist = tagHistogram(markupText);
+  const totalEls = Object.values(hist).reduce((a, b) => a + b, 0) || 1;
+  const divLike = (hist["div"] ?? 0) + (hist["span"] ?? 0);
+  const semanticTags = (hist["section"] ?? 0) + (hist["nav"] ?? 0) + (hist["header"] ?? 0) + (hist["footer"] ?? 0)
+    + (hist["main"] ?? 0) + (hist["article"] ?? 0) + (hist["aside"] ?? 0) + (hist["button"] ?? 0)
+    + (hist["h1"] ?? 0) + (hist["h2"] ?? 0) + (hist["h3"] ?? 0) + (hist["ul"] ?? 0) + (hist["nav"] ?? 0);
+  const h1Count = hist["h1"] ?? 0;
+  const imgCount = hist["img"] ?? 0;
+  const altCount = (markupText.match(/\balt\s*=/g) ?? []).length;
+  const ariaHidden = ariaHiddenFocusables(markupText);
+  const divRatio = divLike / totalEls;
+  const altCoverage = imgCount ? clamp01(altCount / imgCount) : 1;
+
+  if (h1Count === 0) offenders.push({ file: "(page)", metric: "h1 count", value: 0 });
+  if (ariaHidden > 0) offenders.push({ file: "(markup)", metric: "aria-hidden on focusables", value: ariaHidden });
+  if (imgCount && altCoverage < K.ALT_COVERAGE_GOOD) offenders.push({ file: "(markup)", metric: "imgs missing alt", value: imgCount - altCount });
+
+  const aDiv = penalize(divRatio, K.DIV_RATIO_GOOD, K.DIV_RATIO_BAD);
+  const aSem = clamp01(semanticTags / (totalEls * 0.12)); // ~12% semantic tags → full credit
+  const aH1 = h1Count === K.H1_REQUIRED ? 1 : h1Count > K.H1_REQUIRED ? 0.8 : 0.1; // missing h1 is a heavy penalty; multiple h1 a minor ding
+  const aAlt = altCoverage;
+  const aAria = penalize(ariaHidden, 0, 6);
+  const semanticsSub = 0.3 * aDiv + 0.2 * aSem + 0.25 * aH1 + 0.15 * aAlt + 0.1 * aAria;
+
+  // =========================================================================
+  // 5. HYGIENE — whitespace literals, frozen sub-pixels, opaque tokens, probe leaks.
+  // =========================================================================
+  const wsLiterals = whitespaceLiterals(markupText);
+  const subpixel = subpixelArbitraries(allText);
+  let propTotal = 0, propOpaque = 0;
+  for (const f of css) { const t = customPropTokens(f.text); propTotal += t.total; propOpaque += t.opaque; }
+  const probes = probeArtifacts(allText);
+  const opaqueRatio = propTotal ? propOpaque / propTotal : 0;
+  const wsPerK = wsLiterals / Math.max(1, kTags);
+  const subpixelPerK = subpixel / Math.max(1, kTags);
+
+  if (wsLiterals > 0) offenders.push({ file: "(markup)", metric: "{\" \"} whitespace literals", value: wsLiterals });
+  if (subpixel > 0) offenders.push({ file: "(styles)", metric: "frozen sub-pixel arbitraries", value: subpixel });
+  if (propOpaque > 0) offenders.push({ file: "(css)", metric: "opaque --token defs", value: propOpaque });
+  if (probes > 0) offenders.push({ file: "(markup)", metric: "capture-probe artifacts", value: probes });
+
+  const hWs = penalize(wsPerK, K.WS_LITERAL_PER_KTAG_GOOD, K.WS_LITERAL_PER_KTAG_BAD);
+  const hSub = penalize(subpixelPerK, K.SUBPIXEL_PER_KTAG_GOOD, K.SUBPIXEL_PER_KTAG_BAD);
+  const hTok = penalize(opaqueRatio, 0, K.OPAQUE_TOKEN_RATIO_BAD);
+  const hProbe = penalize(probes, 0, K.PROBE_ARTIFACTS_BAD);
+  const hygieneSub = 0.28 * hWs + 0.28 * hSub + 0.28 * hTok + 0.16 * hProbe;
+
+  // =========================================================================
+  // 6. RUNTIME DISCIPLINE — no leaked listeners, no undeclared imports.
+  // =========================================================================
+  let leaks = 0;
+  for (const f of runtimeFiles) leaks += uncleanedListeners(f.text);
+  const undeclaredImports = countUndeclaredImports(runtimeFiles);
+  if (leaks > 0) offenders.push({ file: "(runtime)", metric: "uncleaned addEventListener", value: leaks });
+  if (undeclaredImports > 0) offenders.push({ file: "(runtime)", metric: "undeclared imports", value: undeclaredImports });
+
+  const rLeak = penalize(leaks, K.LEAK_LISTENERS_GOOD, K.LEAK_LISTENERS_BAD);
+  const rImp = penalize(undeclaredImports, 0, 6);
+  const runtimeSub = 0.7 * rLeak + 0.3 * rImp;
+
+  // =========================================================================
+  // BLEND + HARD CAPS
+  // =========================================================================
+  const dims = {
+    payload: payloadSub,
+    decomposition: decompositionSub,
+    duplication: duplicationSub,
+    semantics: semanticsSub,
+    hygiene: hygieneSub,
+    runtime: runtimeSub,
   };
-  const sectionComponents = nonEntry.filter(isSectionFile).length;
-  const svgFiles = componentModules.filter((f) => /(^|\/)svgs?\//i.test(f.rel) || /icon/i.test(basename(f.rel)) || (countTags(f.text) > 0 && /^[^<]*<svg/m.test(f.text.replace(/import[^\n]*\n/g, "")))).length;
+  let total = 0;
+  for (const [k, sub] of Object.entries(dims)) total += WEIGHTS[k as keyof typeof WEIGHTS] * sub;
 
-  // ---- naming ----
-  const allComponentNames = new Set<string>();
-  for (const f of componentModules) for (const n of componentNames(f.text)) allComponentNames.add(n);
-  // exclude the page/Page entry symbol from the semantic judgement
-  const judgedNames = [...allComponentNames].filter((n) => n !== "Page" && n !== "default" && n !== "RootLayout" && n !== "Layout");
-  const genericNames = judgedNames.filter((n) => GENERIC_COMP_RE.test(n)).length;
-  const compNameSemanticRatio = judgedNames.length ? 1 - genericNames / judgedNames.length : 0;
-
-  const allClassToks: string[] = [];
-  for (const f of tsx) allClassToks.push(...classTokens(f.text));
-  const classTotal = allClassToks.length || 1;
-  const opaqueClasses = allClassToks.filter(isOpaqueClass).length;
-  const classSemanticRatio = 1 - opaqueClasses / classTotal;
-  const distinctClasses = new Set(allClassToks).size || 1;
-  const classReuse = 1 - distinctClasses / classTotal; // 0 = every class used once (per-node), →1 = heavy reuse
-
-  // content field naming + editability
-  const contentFiles = files.filter((f) => /(content|data)\.[jt]s$/i.test(basename(f.rel)) || /(^|\/)(content|lib)\//i.test(f.rel));
-  const fieldNames: string[] = [];
-  for (const f of contentFiles) fieldNames.push(...contentFieldNames(f.text));
-  const plumbingFields = fieldNames.filter((n) => PLUMBING_FIELD_RE.test(n)).length;
-  const fieldSemanticRatio = fieldNames.length ? 1 - plumbingFields / fieldNames.length : 0.5;
-
-  // ---- styling system ----
-  const cssBytes = css.reduce((s, f) => s + f.text.length, 0);
-  const cssBytesPerNode = cssBytes / totalTags;
-  let tokenRefs = 0, tokenDefs = 0;
-  for (const f of css) {
-    tokenRefs += (f.text.match(/var\(--/g) ?? []).length;
-    tokenDefs += (f.text.match(/^\s*--[\w-]+\s*:/gm) ?? []).length;
+  // Catastrophe caps: any ONE unopenable payload drags the whole grade into D-range.
+  if (worstFileBytes >= K.CATASTROPHE_FILE_BYTES) caps.push(`file ${worstFileRel} is ${(worstFileBytes / 1e6).toFixed(1)}MB (>1MB)`);
+  if (worstLine >= K.CATASTROPHE_LINE_CHARS) caps.push(`line in ${worstLineRel} is ${(worstLine / 1000).toFixed(0)}KB (>100KB)`);
+  if (totalInlineBytes >= K.CATASTROPHE_INLINE_BYTES) caps.push(`${(totalInlineBytes / 1e6).toFixed(1)}MB of embedded base64/HTML (>5MB)`);
+  if (caps.length) total = Math.min(total, K.CAP_GRADE_D);
+  else {
+    // Softer warning band.
+    if (worstFileBytes >= K.WARN_FILE_BYTES) caps.push(`file ${worstFileRel} is ${(worstFileBytes / 1000).toFixed(0)}KB (>${K.WARN_FILE_BYTES / 1000}KB)`);
+    if (worstLine >= K.WARN_LINE_CHARS) caps.push(`line in ${worstLineRel} is ${(worstLine / 1000).toFixed(0)}KB (>${K.WARN_LINE_CHARS / 1000}KB)`);
+    if (caps.length) total = Math.min(total, K.CAP_GRADE_C);
   }
-  // Tailwind-style theme tokens count as token usage too (utility classes referencing roles)
-  const tailwindTokenClasses = allClassToks.filter((t) => /(^|[-:])(bg|text|border|fill|stroke|ring|from|to|via)-/.test(t)).length;
-  // per-node-unique-rule penalty: count `.cNNN{` selectors in CSS
-  let perNodeRules = 0;
-  for (const f of css) perNodeRules += (f.text.match(/\.c[a-z]?\d+\s*[\{,]/g) ?? []).length;
-  const perNodeRuleRatio = perNodeRules / totalTags; // 1.0 = a unique rule per node
+  total = r1(Math.max(0, Math.min(100, total)));
 
-  // magic literals in component markup (raw hex/rgb/px in className/style strings)
-  let magicLiterals = 0;
-  for (const f of componentModules) {
-    magicLiterals += (f.text.match(/#[0-9a-fA-F]{3,8}\b/g) ?? []).length;
-    magicLiterals += (f.text.match(/\brgba?\([^)]*\)/g) ?? []).length;
-  }
-  const magicPerNode = magicLiterals / totalTags;
-
-  // ---- idiomatic styling (the axes the old rubric was blind to) ----
-  // A px ARBITRARY value (`w-[713.938px]`, `py-[64px]`) is a measurement, not a design choice —
-  // the single biggest "machine-generated" tell. Count them across markup + hoisted class
-  // consts, vs the standard scale / rem a human writes.
-  let arbPx = 0, arbBands = 0, stdBreakpoints = 0, dataCidCount = 0;
-  for (const f of [...componentModules, ...css]) {
-    arbPx += (f.text.match(/\[[0-9]+(?:\.[0-9]+)?px\]/g) ?? []).length;
-    arbBands += (f.text.match(/(?:min|max)-\[[0-9]+px\]:/g) ?? []).length; // arbitrary midpoint media variants
-    stdBreakpoints += (f.text.match(/(?:^|[\s"'`])(?:max-)?(?:sm|md|lg|xl|2xl):/g) ?? []).length;
-    dataCidCount += (f.text.match(/data-cid/g) ?? []).length;
-  }
-  const arbPxPerNode = arbPx / totalTags;            // low is hand-authored; high is machine replay
-  const bandShare = arbBands + stdBreakpoints > 0 ? arbBands / (arbBands + stdBreakpoints) : 0; // 1 = all arbitrary
-  const dataCidPerNode = dataCidCount / totalTags;
-  // Robotic, never-hand-written comment phrases.
-  let roboticComments = 0;
-  for (const f of [...componentModules, ...css, ...files.filter((x) => x.ext === ".ts")]) {
-    roboticComments += (f.text.match(/Generated by clone-static|render-identical to the source|Do not edit by hand/g) ?? []).length;
-  }
-
-  // ---- editability ----
-  const hasContentModule = contentFiles.some((f) => /export\s+(const|type)/.test(f.text)) ? 1 : 0;
-  // Destructured props with a default value, in any function/arrow param block — counts
-  // string, array, and identifier defaults alike (a default is a default).
-  let propsWithDefaults = 0;
-  for (const f of componentModules) {
-    for (const blk of f.text.match(/\(\s*\{[^{}]*\}/g) ?? []) {
-      propsWithDefaults += (blk.match(/\b\w+\s*=\s*(?![=>])/g) ?? []).length;
-    }
-  }
-  const defaultsSignal = clamp01(propsWithDefaults / Math.max(6, nonEntry.length));
-
-  // ---- file org ----
-  const dirSet = new Set(componentModules.map((f) => f.rel.split("/").slice(0, -1).join("/")));
-  const hasSectionsDir = [...dirSet].some((d) => /sections?$/i.test(d)) ? 1 : 0;
-  const hasComponentsDir = [...dirSet].some((d) => /(components|ui)$/i.test(d)) ? 1 : 0;
-  const hasLayoutDir = [...dirSet].some((d) => /(layout|svgs?)$/i.test(d)) ? 1 : 0;
-  const orgDirs = hasSectionsDir + hasComponentsDir + hasLayoutDir;
-
-  // ---- metadata ----
-  let docHeaders = 0, annotations = 0;
-  for (const f of componentModules) {
-    docHeaders += (f.text.match(/\/\*\*[\s\S]*?\*\//g) ?? []).length;
-    // component-type annotations in attribute, object, or doc-tag form.
-    annotations += (f.text.match(/@component|data-component/g) ?? []).length;
-  }
-
-  // =========================================================================
-  // Category scoring
-  // =========================================================================
-
-  // 1. Componentization (25): many components, low single-file dominance, sections present
-  const cCount = ramp(nonEntry.length, 0, 12);        // 0 → 12+ components
-  const cDom = 1 - ramp(dominance, 0.3, 0.95);        // penalize one giant file
-  const cSections = ramp(sectionComponents, 0, 6);    // semantic sections
-  const componentization = 25 * (0.4 * cCount + 0.35 * cDom + 0.25 * cSections);
-
-  // 2. Semantic naming (25): component names, class names, content fields
-  const naming = 25 * (0.4 * compNameSemanticRatio + 0.4 * classSemanticRatio + 0.2 * fieldSemanticRatio);
-
-  // 3. Styling system (20): class reuse, tokens, low per-node verbosity, few magic literals AND
-  //    — the axes the old rubric missed — idiomatic values (standard scale/rem, not a wall of
-  //    px arbitraries) and standard breakpoints (not arbitrary midpoint bands).
-  const sReuse = clamp01(classReuse / 0.6);            // 0.6+ reuse → full marks
-  const sTokens = ramp(tokenRefs + tailwindTokenClasses, 0, Math.max(40, totalTags * 0.5));
-  const sVerbosity = 1 - clamp01(perNodeRuleRatio);    // per-node rules are bad
-  const sMagic = 1 - clamp01(magicPerNode / 0.25);
-  const sArb = 1 - clamp01(arbPxPerNode / 2);          // ~0 arb-px/node → 1; 2+/node → 0
-  const sBp = 1 - bandShare;                           // 0 arbitrary bands → 1
-  const styling = 20 * (0.22 * sReuse + 0.13 * sTokens + 0.13 * sVerbosity + 0.07 * sMagic + 0.27 * sArb + 0.18 * sBp);
-
-  // 4. Editability (15): content module, typed fields, semantic fields, prop defaults
-  const editability = 15 * (0.4 * hasContentModule + 0.3 * fieldSemanticRatio + 0.3 * defaultsSignal);
-
-  // 5. File org (10): folder structure + svgs extracted
-  const fileOrg = 10 * (0.7 * (orgDirs / 3) + 0.3 * clamp01(svgFiles / 4));
-
-  // 6. Metadata (5): concise human doc headers + semantic component annotations — but a
-  //    "Generated by clone-static / render-identical" robotic header is a NEGATIVE signal (no
-  //    human writes it), and shipping a per-node data-cid on every element is markup noise.
-  const cleanComments = roboticComments === 0 ? 1 : clamp01(1 - roboticComments / Math.max(4, nonEntry.length));
-  const lowCidNoise = 1 - clamp01(dataCidPerNode);     // ~0 data-cid/node → 1; 1/node → 0
-  const metadata = 5 * (0.35 * clamp01(docHeaders / Math.max(4, nonEntry.length)) * cleanComments
-    + 0.35 * clamp01(annotations / Math.max(8, totalTags * 0.1))
-    + 0.3 * lowCidNoise);
-
-  const total = componentization + naming + styling + editability + fileOrg + metadata;
+  // Order offenders by severity so the report's "top offenders" is meaningful.
+  offenders.sort((a, b) => severity(b) - severity(a));
 
   return {
     dir: root,
-    total: r1(total),
+    total,
+    grade: toLetter(total),
+    caps,
     categories: {
-      componentization: { score: r1(componentization), max: 25, metrics: { components: nonEntry.length, dominancePct: r1(dominance * 100), sectionComponents } },
-      naming: { score: r1(naming), max: 25, metrics: { compNameSemanticPct: r1(compNameSemanticRatio * 100), classSemanticPct: r1(classSemanticRatio * 100), fieldSemanticPct: r1(fieldSemanticRatio * 100), genericNames } },
-      styling: { score: r1(styling), max: 20, metrics: { classReusePct: r1(classReuse * 100), tokenRefs, perNodeRules, magicLiterals, arbPx, arbPxPerNode: r1(arbPxPerNode), arbBands, stdBreakpoints, bandSharePct: r1(bandShare * 100) } },
-      editability: { score: r1(editability), max: 15, metrics: { hasContentModule, fieldSemanticPct: r1(fieldSemanticRatio * 100), propsWithDefaults } },
-      fileOrg: { score: r1(fileOrg), max: 10, metrics: { orgDirs, svgFiles, hasSectionsDir, hasComponentsDir } },
-      metadata: { score: r1(metadata), max: 5, metrics: { docHeaders, annotations, roboticComments, dataCidPerNode: r1(dataCidPerNode) } },
+      payload: { score: r1(WEIGHTS.payload * payloadSub), max: WEIGHTS.payload, metrics: { maxFileKB: r1(worstFileBytes / 1000), maxLineKB: r1(worstLine / 1000), inlineBlobKB: r1(totalInlineBytes / 1000) } },
+      decomposition: { score: r1(WEIGHTS.decomposition * decompositionSub), max: WEIGHTS.decomposition, metrics: { components: nonEntry.length, dominancePct: r1(dominance * 100), bigSections } },
+      duplication: { score: r1(WEIGHTS.duplication * duplicationSub), max: WEIGHTS.duplication, metrics: { helperDups, helperDupPct: r1(helperDupRatio * 100), svgPathRepeats: svgDup.repeats, nearDupPairs: nearDup } },
+      semantics: { score: r1(WEIGHTS.semantics * semanticsSub), max: WEIGHTS.semantics, metrics: { h1: h1Count, divRatioPct: r1(divRatio * 100), semanticTags, altCoveragePct: r1(altCoverage * 100), ariaHiddenFocusables: ariaHidden } },
+      hygiene: { score: r1(WEIGHTS.hygiene * hygieneSub), max: WEIGHTS.hygiene, metrics: { wsLiterals, subpixelArbitraries: subpixel, opaqueTokenPct: r1(opaqueRatio * 100), probeArtifacts: probes } },
+      runtime: { score: r1(WEIGHTS.runtime * runtimeSub), max: WEIGHTS.runtime, metrics: { uncleanedListeners: leaks, undeclaredImports } },
     },
+    offenders: offenders.slice(0, 15),
     raw: {
       files: files.length, componentModules: componentModules.length, totalTags, maxFileTags,
-      classTokens: classTotal, distinctClasses, opaqueClasses, cssBytes,
+      worstFileBytes, worstLineChars: worstLine, inlineBytes: totalInlineBytes,
     },
   };
 }
 
+/** Undeclared imports: a bare-specifier import not present in any package.json/tsconfig
+ *  alias and not a relative path — a runtime crash waiting to happen. We approximate by
+ *  flagging imports of local-looking modules that resolve nowhere is expensive, so instead
+ *  we flag the cheap, robust tell: an import statement whose source is an empty string or a
+ *  malformed specifier. (Kept conservative to avoid false positives across frameworks.) */
+function countUndeclaredImports(files: SrcFile[]): number {
+  let n = 0;
+  for (const f of files) {
+    for (const m of f.text.matchAll(/\bimport\s+[^;]*?\bfrom\s*["'`]([^"'`]*)["'`]/g)) {
+      const spec = m[1]!;
+      if (spec.trim() === "" || /\s/.test(spec) || spec === "undefined" || spec === "null") n++;
+    }
+  }
+  return n;
+}
+
+/** Relative weight of an offender for ordering the top-offenders list. */
+function severity(o: Offender): number {
+  switch (o.metric) {
+    case "file bytes": return o.value / 1000;
+    case "max line chars": return o.value / 1000;
+    case "inline blob bytes": return o.value / 2000;
+    case "section LOC": return o.value / 20;
+    case "opaque --token defs": return o.value * 0.5;
+    case "frozen sub-pixel arbitraries": return o.value * 0.3;
+    case "{\" \"} whitespace literals": return o.value * 0.1;
+    case "h1 count": return 300; // a missing h1 is always a headline offender
+    case "uncleaned addEventListener": return o.value * 3;
+    default: return o.value;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
 function fmt(rep: QualityReport): string {
   const lines: string[] = [];
   lines.push(`\n  ${rep.dir}`);
-  lines.push(`  TOTAL: ${rep.total}/100`);
+  lines.push(`  GRADE: ${rep.grade}   (${rep.total}/100)`);
+  if (rep.caps.length) lines.push(`  CAPS:  ${rep.caps.join("; ")}`);
   for (const [k, c] of Object.entries(rep.categories)) {
     const metrics = Object.entries(c.metrics).map(([mk, mv]) => `${mk}=${mv}`).join(" ");
-    lines.push(`    ${k.padEnd(16)} ${String(c.score).padStart(5)}/${c.max}   ${metrics}`);
+    lines.push(`    ${k.padEnd(15)} ${String(c.score).padStart(5)}/${c.max}   ${metrics}`);
+  }
+  if (rep.offenders.length) {
+    lines.push(`    top offenders:`);
+    for (const o of rep.offenders.slice(0, 8)) lines.push(`      ${o.metric.padEnd(34)} ${String(o.value).padStart(10)}  ${o.file}`);
   }
   return lines.join("\n");
 }
@@ -353,11 +614,11 @@ async function main(): Promise<void> {
   for (const rep of reports) console.log(fmt(rep));
   if (reports.length > 1) {
     console.log("\n  ── comparison ──");
-    console.log("  " + "category".padEnd(16) + reports.map((_, i) => `app${i + 1}`.padStart(10)).join(""));
+    console.log("  " + "dimension".padEnd(15) + reports.map((_, i) => `app${i + 1}`.padStart(10)).join(""));
     for (const cat of Object.keys(reports[0]!.categories)) {
-      console.log("  " + cat.padEnd(16) + reports.map((r) => String(r.categories[cat]!.score).padStart(10)).join(""));
+      console.log("  " + cat.padEnd(15) + reports.map((r) => String(r.categories[cat]!.score).padStart(10)).join(""));
     }
-    console.log("  " + "TOTAL".padEnd(16) + reports.map((r) => String(r.total).padStart(10)).join(""));
+    console.log("  " + "GRADE".padEnd(15) + reports.map((r) => `${r.grade}(${r.total})`.padStart(10)).join(""));
   }
 }
 
diff --git a/compiler/test/css.test.ts b/compiler/test/css.test.ts
index 8a9b293..8d57ddb 100644
--- a/compiler/test/css.test.ts
+++ b/compiler/test/css.test.ts
@@ -1,6 +1,7 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 import type { IR, IRNode, IRChild, StyleMap, BBox } from "../src/normalize/ir.js";
+import type { RawSizing } from "../src/capture/walker.js";
 import { generateCss } from "../src/generate/css.js";
 
 const VPS = [375, 1280];
@@ -290,3 +291,196 @@ describe("generateCss scroll-timeline animation suppression", () => {
     assert.ok(rule.includes("animation-name:fadeInUp"), `time-based reveal keeps its animation, got: ${rule}`);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Per-viewport node builder (independent bbox / computed / sizing per width) plus a matching
+// 3-viewport IR wrapper — the fluid/centring/wrap detectors need ≥2 varying widths to run.
+const XVPS = [375, 768, 1280];
+type XPerVp = { cs?: StyleMap; bbox: BBox; sizing?: RawSizing; visible?: boolean };
+function xNode(id: string, tag: string, byVp: Record<number, XPerVp>, children: IRChild[] = []): IRNode {
+  const computedByVp: Record<number, StyleMap> = {};
+  const bboxByVp: Record<number, BBox> = {};
+  const visibleByVp: Record<number, boolean> = {};
+  const sizingByVp: Record<number, RawSizing> = {};
+  for (const vp of XVPS) {
+    const s = byVp[vp]!;
+    computedByVp[vp] = computed(s.cs);
+    bboxByVp[vp] = s.bbox;
+    visibleByVp[vp] = s.visible ?? true;
+    if (s.sizing) sizingByVp[vp] = s.sizing;
+  }
+  const n: IRNode = { id, tag, attrs: {}, visibleByVp, bboxByVp, computedByVp, children };
+  if (Object.keys(sizingByVp).length) n.sizingByVp = sizingByVp;
+  return n;
+}
+function xIr(root: IRNode): IR {
+  const ir = irWith(root);
+  ir.doc.viewports = XVPS;
+  ir.doc.sampleViewports = XVPS;
+  ir.doc.perViewport = Object.fromEntries(XVPS.map((vp) => [vp, { scrollHeight: 800, scrollWidth: vp, htmlBg: "rgb(255, 255, 255)", bodyBg: "rgb(255, 255, 255)", bodyColor: "rgb(0, 0, 0)", bodyFont: "Arial" }]));
+  return ir;
+}
+/** Every `.c<id>{…}` body (base + banded) concatenated, for asserting a value appears at some vp. */
+function allRulesX(css: string, id: string): string {
+  const re = new RegExp(`\\.c${id}\\{([^}]*)\\}`, "g");
+  let out = "", m: RegExpExecArray | null;
+  while ((m = re.exec(css))) out += m[1] + ";";
+  return out;
+}
+/** The `.c<id>{…}` body inside the first @media block whose query matches `mediaRe`. */
+function xBandRule(css: string, mediaRe: RegExp, id: string): string {
+  for (const m of css.matchAll(/@media ([^{]+) \{\n([\s\S]*?)\n\}/g)) {
+    if (!mediaRe.test(m[1]!)) continue;
+    const r = m[2]!.match(new RegExp(`\\.c${id}\\{([^}]*)\\}`));
+    if (r) return r[1]!;
+  }
+  return "";
+}
+
+// BUG A — a padded pill/section with LITERAL equal side margins (a fraction of the viewport, varying
+// across widths) must keep those px margins per band. The width-fill sizing probe is what tells the
+// centring detector these are load-bearing spacing, not margin-auto centring slack: on a box the
+// probe reads as a container-fill (width:100% reproduces it), `margin:auto` resolves to 0 and would
+// blow the box out to full-bleed, deleting the real margins.
+describe("generateCss literal-margin vs auto-centring", () => {
+  const fill = (): RawSizing => ({ wAuto: false, wFill: true, hAuto: true, hFill: true });
+  // A flex parent spanning the whole viewport, holding one padded pill child that fills the space
+  // BETWEEN its literal side margins (box + 2×margin == container at every width).
+  function pill() {
+    const child = xNode("n1", "div", {
+      375: { cs: { display: "flex", marginLeft: "15px", marginRight: "15px", width: "345px" }, bbox: { x: 15, y: 0, width: 345, height: 62 }, sizing: fill() },
+      768: { cs: { display: "flex", marginLeft: "30.7188px", marginRight: "30.7188px", width: "706.562px" }, bbox: { x: 30.72, y: 0, width: 706.56, height: 62 }, sizing: fill() },
+      1280: { cs: { display: "flex", marginLeft: "25.5938px", marginRight: "25.5938px", width: "1228.81px" }, bbox: { x: 25.59, y: 0, width: 1228.81, height: 62 }, sizing: fill() },
+    });
+    const parent = xNode("n0", "body", {
+      375: { cs: { display: "flex" }, bbox: { x: 0, y: 0, width: 375, height: 62 } },
+      768: { cs: { display: "flex" }, bbox: { x: 0, y: 0, width: 768, height: 62 } },
+      1280: { cs: { display: "flex" }, bbox: { x: 0, y: 0, width: 1280, height: 62 } },
+    }, [child]);
+    return parent;
+  }
+
+  it("keeps the literal px side margins on a width-filling pill (no mx-auto)", () => {
+    const css = generateCss(xIr(pill()), new Map());
+    const all = allRulesX(css, "n1");
+    assert.ok(!/margin-left:auto/.test(all), `filling pill must not be centred with auto margins, got: ${all}`);
+    assert.ok(baseRule(css, "n1").includes("margin-left:25.5938px"), `base keeps the 1280 literal margin, got: ${baseRule(css, "n1")}`);
+    // The narrowest band (a `max-width` query with no `min-width`) carries the 375-vp literal margin.
+    const mobile = xBandRule(css, /^\(max-width/, "n1");
+    assert.ok(/margin-left:15px/.test(mobile), `mobile band keeps its literal 15px margin, got: ${mobile}`);
+  });
+
+  it("still emits margin:auto for a genuinely centred, width-CONSTRAINED block", () => {
+    // Content-sized (not a fill): the probe says width:auto re-derives it, width narrower than the
+    // container with symmetric slack that varies with width — real margin-auto centring.
+    const auto = (): RawSizing => ({ wAuto: true, wFill: false, hAuto: true, hFill: false });
+    const child = xNode("n1", "div", {
+      375: { cs: { display: "block", marginLeft: "15px", marginRight: "15px", width: "345px" }, bbox: { x: 15, y: 0, width: 345, height: 40 }, sizing: auto() },
+      768: { cs: { display: "block", marginLeft: "84px", marginRight: "84px", width: "600px" }, bbox: { x: 84, y: 0, width: 600, height: 40 }, sizing: auto() },
+      1280: { cs: { display: "block", marginLeft: "340px", marginRight: "340px", width: "600px" }, bbox: { x: 340, y: 0, width: 600, height: 40 }, sizing: auto() },
+    });
+    const parent = xNode("n0", "body", {
+      375: { cs: { display: "block" }, bbox: { x: 0, y: 0, width: 375, height: 40 } },
+      768: { cs: { display: "block" }, bbox: { x: 0, y: 0, width: 768, height: 40 } },
+      1280: { cs: { display: "block" }, bbox: { x: 0, y: 0, width: 1280, height: 40 } },
+    }, [child]);
+    const css = generateCss(xIr(parent), new Map());
+    const all = allRulesX(css, "n1");
+    assert.ok(/margin-left:auto/.test(all), `a constrained centred block should still auto-centre, got: ${all}`);
+  });
+});
+
+// BUG C — a single-line text leaf whose unwrapped width nearly fills its column at every width gets
+// `white-space:nowrap`, so a sub-pixel column shortfall in the clone can't wrap it to a second line.
+describe("generateCss wrap-vulnerable single-line text", () => {
+  // Text bbox exactly fills the column (wMax == avail == bbox.width) at every width, single line
+  // (height == line-height), and is genuinely wrappable (wMin < wMax).
+  function edgeText(wMin: number) {
+    const szAt = (w: number): RawSizing => ({ wAuto: true, wFill: false, hAuto: true, hFill: false, wMin, wMax: w });
+    const leaf = xNode("n1", "div", {
+      375: { cs: { display: "block", lineHeight: "24px" }, bbox: { x: 0, y: 0, width: 107.81, height: 24 }, sizing: szAt(107.81) },
+      768: { cs: { display: "block", lineHeight: "24px" }, bbox: { x: 0, y: 0, width: 107.81, height: 24 }, sizing: szAt(107.81) },
+      1280: { cs: { display: "block", lineHeight: "20px" }, bbox: { x: 0, y: 0, width: 107.81, height: 20 }, sizing: szAt(107.81) },
+    }, [{ text: "CEO — Academy" }]);
+    const parent = xNode("n0", "body", {
+      375: { cs: { display: "block" }, bbox: { x: 0, y: 0, width: 107.81, height: 24 } },
+      768: { cs: { display: "block" }, bbox: { x: 0, y: 0, width: 107.81, height: 24 } },
+      1280: { cs: { display: "block" }, bbox: { x: 0, y: 0, width: 107.81, height: 20 } },
+    }, [leaf]);
+    return parent;
+  }
+
+  it("emits white-space:nowrap for text flush against its column edge", () => {
+    const css = generateCss(xIr(edgeText(58.33)), new Map());
+    assert.ok(baseRule(css, "n1").includes("white-space:nowrap"), `edge-flush single-line text should get nowrap, got: ${baseRule(css, "n1")}`);
+  });
+
+  it("does NOT emit nowrap for a single unbreakable token (wMin == wMax — can't wrap)", () => {
+    const css = generateCss(xIr(edgeText(107.81)), new Map());
+    assert.ok(!baseRule(css, "n1").includes("white-space:nowrap"), `an unbreakable token needs no nowrap, got: ${baseRule(css, "n1")}`);
+  });
+
+  it("does NOT emit nowrap for a genuinely wrapping multi-line paragraph", () => {
+    // Two line boxes tall (height ≈ 2×line-height) → already wrapping, must stay wrappable.
+    const wMin = 100, wMax = 400;
+    const szAt = (): RawSizing => ({ wAuto: true, wFill: false, hAuto: true, hFill: false, wMin, wMax });
+    const para = xNode("n1", "p", {
+      375: { cs: { display: "block", lineHeight: "24px" }, bbox: { x: 0, y: 0, width: 345, height: 72 }, sizing: szAt() },
+      768: { cs: { display: "block", lineHeight: "24px" }, bbox: { x: 0, y: 0, width: 700, height: 48 }, sizing: szAt() },
+      1280: { cs: { display: "block", lineHeight: "24px" }, bbox: { x: 0, y: 0, width: 400, height: 48 }, sizing: szAt() },
+    }, [{ text: "A longer paragraph that wraps across multiple lines depending on the width." }]);
+    const parent = xNode("n0", "body", {
+      375: { cs: { display: "block" }, bbox: { x: 0, y: 0, width: 345, height: 72 } },
+      768: { cs: { display: "block" }, bbox: { x: 0, y: 0, width: 700, height: 48 } },
+      1280: { cs: { display: "block" }, bbox: { x: 0, y: 0, width: 400, height: 48 } },
+    }, [para]);
+    const css = generateCss(xIr(parent), new Map());
+    assert.ok(!allRulesX(css, "n1").includes("white-space:nowrap"), `a wrapping paragraph must not be forced nowrap, got: ${allRulesX(css, "n1")}`);
+  });
+
+  it("does NOT emit nowrap for text with comfortable slack in its container", () => {
+    const szAt = (): RawSizing => ({ wAuto: true, wFill: false, hAuto: true, hFill: false, wMin: 60, wMax: 90 });
+    const leaf = xNode("n1", "div", {
+      375: { cs: { display: "block", lineHeight: "20px" }, bbox: { x: 0, y: 0, width: 90, height: 20 }, sizing: szAt() },
+      768: { cs: { display: "block", lineHeight: "20px" }, bbox: { x: 0, y: 0, width: 90, height: 20 }, sizing: szAt() },
+      1280: { cs: { display: "block", lineHeight: "20px" }, bbox: { x: 0, y: 0, width: 90, height: 20 }, sizing: szAt() },
+    }, [{ text: "Nav link" }]);
+    // Wide container (300px+) — the 90px text has plenty of room, no wrap risk.
+    const parent = xNode("n0", "body", {
+      375: { cs: { display: "block" }, bbox: { x: 0, y: 0, width: 375, height: 20 } },
+      768: { cs: { display: "block" }, bbox: { x: 0, y: 0, width: 768, height: 20 } },
+      1280: { cs: { display: "block" }, bbox: { x: 0, y: 0, width: 1280, height: 20 } },
+    }, [leaf]);
+    const css = generateCss(xIr(parent), new Map());
+    assert.ok(!baseRule(css, "n1").includes("white-space:nowrap"), `slack text needs no nowrap, got: ${baseRule(css, "n1")}`);
+  });
+});
+
+// Cross-band transform identity — a node with a NON-identity transform at one band must emit the
+// explicit identity `transform:none` at the bands where the source is untransformed, so the
+// transform can't cascade across bands and freeze at a width the source left untransformed.
+describe("generateCss cross-band transform identity", () => {
+  it("emits transform:none at a band where a node with a non-identity transform elsewhere is identity", () => {
+    const el = xNode("n1", "div", {
+      375: { cs: { transform: "none" }, bbox: { x: 0, y: 0, width: 375, height: 40 } },
+      768: { cs: { transform: "matrix(1, 0, 0, 1, 40, 0)" }, bbox: { x: 40, y: 0, width: 375, height: 40 } },
+      1280: { cs: { transform: "matrix(1, 0, 0, 1, 40, 0)" }, bbox: { x: 40, y: 0, width: 375, height: 40 } },
+    });
+    const root = xNode("n0", "body", { 375: { bbox: { x: 0, y: 0, width: 375, height: 40 } }, 768: { bbox: { x: 0, y: 0, width: 768, height: 40 } }, 1280: { bbox: { x: 0, y: 0, width: 1280, height: 40 } } }, [el]);
+    const css = generateCss(xIr(root), new Map());
+    const all = allRulesX(css, "n1");
+    assert.ok(/transform:matrix/.test(all), `the non-identity transform must be emitted, got: ${all}`);
+    assert.ok(/transform:none/.test(all), `the identity band must emit transform:none so it can't cascade, got: ${all}`);
+  });
+
+  it("does NOT emit transform:none for a node that is identity at every band", () => {
+    const el = xNode("n1", "div", {
+      375: { cs: { transform: "none" }, bbox: { x: 0, y: 0, width: 375, height: 40 } },
+      768: { cs: { transform: "none" }, bbox: { x: 0, y: 0, width: 375, height: 40 } },
+      1280: { cs: { transform: "none" }, bbox: { x: 0, y: 0, width: 375, height: 40 } },
+    });
+    const root = xNode("n0", "body", { 375: { bbox: { x: 0, y: 0, width: 375, height: 40 } }, 768: { bbox: { x: 0, y: 0, width: 768, height: 40 } }, 1280: { bbox: { x: 0, y: 0, width: 1280, height: 40 } } }, [el]);
+    const css = generateCss(xIr(root), new Map());
+    assert.ok(!allRulesX(css, "n1").includes("transform:none"), `an always-identity node needs no explicit transform, got: ${allRulesX(css, "n1")}`);
+  });
+});
diff --git a/compiler/test/dotlottie.test.ts b/compiler/test/dotlottie.test.ts
new file mode 100644
index 0000000..e7e607a
--- /dev/null
+++ b/compiler/test/dotlottie.test.ts
@@ -0,0 +1,146 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { deflateRawSync } from "node:zlib";
+import { isZipArchive, extractDotLottieJson, readZipEntry } from "../src/capture/dotlottie.js";
+import { extFromUrl } from "../src/capture/capture.js";
+
+/**
+ * Build a minimal, spec-correct ZIP archive in-memory from named entries. Supports both
+ * stored (method 0) and deflated (method 8) compression so the extractor is exercised on both.
+ * No CRC validation is needed for our reader, so CRC fields are left 0.
+ */
+function buildZip(entries: Array<{ name: string; data: Buffer; deflate?: boolean }>): Buffer {
+  const locals: Buffer[] = [];
+  const centrals: Buffer[] = [];
+  let offset = 0;
+
+  for (const e of entries) {
+    const nameBuf = Buffer.from(e.name, "utf8");
+    const stored = e.deflate ? deflateRawSync(e.data) : e.data;
+    const method = e.deflate ? 8 : 0;
+
+    const local = Buffer.alloc(30 + nameBuf.length);
+    local.writeUInt32LE(0x04034b50, 0); // local file header sig
+    local.writeUInt16LE(20, 4); // version needed
+    local.writeUInt16LE(0, 6); // flags
+    local.writeUInt16LE(method, 8);
+    local.writeUInt16LE(0, 10); // time
+    local.writeUInt16LE(0, 12); // date
+    local.writeUInt32LE(0, 14); // crc
+    local.writeUInt32LE(stored.length, 18); // comp size
+    local.writeUInt32LE(e.data.length, 22); // uncomp size
+    local.writeUInt16LE(nameBuf.length, 26);
+    local.writeUInt16LE(0, 28); // extra len
+    nameBuf.copy(local, 30);
+    const localFull = Buffer.concat([local, stored]);
+    locals.push(localFull);
+
+    const central = Buffer.alloc(46 + nameBuf.length);
+    central.writeUInt32LE(0x02014b50, 0); // central dir sig
+    central.writeUInt16LE(20, 4); // version made by
+    central.writeUInt16LE(20, 6); // version needed
+    central.writeUInt16LE(0, 8); // flags
+    central.writeUInt16LE(method, 10);
+    central.writeUInt16LE(0, 12); // time
+    central.writeUInt16LE(0, 14); // date
+    central.writeUInt32LE(0, 16); // crc
+    central.writeUInt32LE(stored.length, 20); // comp size
+    central.writeUInt32LE(e.data.length, 24); // uncomp size
+    central.writeUInt16LE(nameBuf.length, 28);
+    central.writeUInt16LE(0, 30); // extra
+    central.writeUInt16LE(0, 32); // comment
+    central.writeUInt16LE(0, 34); // disk
+    central.writeUInt16LE(0, 36); // internal attrs
+    central.writeUInt32LE(0, 38); // external attrs
+    central.writeUInt32LE(offset, 42); // local header offset
+    nameBuf.copy(central, 46);
+    centrals.push(central);
+
+    offset += localFull.length;
+  }
+
+  const centralStart = offset;
+  const centralDir = Buffer.concat(centrals);
+  const eocd = Buffer.alloc(22);
+  eocd.writeUInt32LE(0x06054b50, 0);
+  eocd.writeUInt16LE(0, 4); // disk
+  eocd.writeUInt16LE(0, 6); // cd start disk
+  eocd.writeUInt16LE(entries.length, 8);
+  eocd.writeUInt16LE(entries.length, 10);
+  eocd.writeUInt32LE(centralDir.length, 12);
+  eocd.writeUInt32LE(centralStart, 16);
+  eocd.writeUInt16LE(0, 20); // comment len
+
+  return Buffer.concat([...locals, centralDir, eocd]);
+}
+
+const ANIM_1 = { v: "5.7.4", nm: "one", layers: [{ ind: 1 }] };
+const ANIM_2 = { v: "5.7.4", nm: "two", layers: [{ ind: 2 }] };
+const MANIFEST = { version: "1.0", animations: [{ id: "animation_default" }, { id: "animation_2" }] };
+
+describe("dotLottie ZIP extraction", () => {
+  it("detects ZIP archives by the PK local-header magic", () => {
+    assert.equal(isZipArchive(Buffer.from([0x50, 0x4b, 0x03, 0x04, 0, 0])), true);
+    assert.equal(isZipArchive(Buffer.from('{"v":"5.7"}', "utf8")), false);
+    assert.equal(isZipArchive(Buffer.alloc(2)), false);
+  });
+
+  it("extracts the manifest's default animation JSON from a stored dotLottie ZIP", () => {
+    const zip = buildZip([
+      { name: "manifest.json", data: Buffer.from(JSON.stringify(MANIFEST), "utf8") },
+      { name: "animations/animation_default.json", data: Buffer.from(JSON.stringify(ANIM_1), "utf8") },
+      { name: "animations/animation_2.json", data: Buffer.from(JSON.stringify(ANIM_2), "utf8") },
+    ]);
+    const out = extractDotLottieJson(zip);
+    assert.ok(out, "expected an extracted animation buffer");
+    assert.deepEqual(JSON.parse(out!.toString("utf8")), ANIM_1);
+  });
+
+  it("extracts a DEFLATE-compressed animation entry (the common real-world case)", () => {
+    const zip = buildZip([
+      { name: "manifest.json", data: Buffer.from(JSON.stringify(MANIFEST), "utf8"), deflate: true },
+      { name: "animations/animation_default.json", data: Buffer.from(JSON.stringify(ANIM_1), "utf8"), deflate: true },
+    ]);
+    const out = extractDotLottieJson(zip);
+    assert.ok(out);
+    assert.deepEqual(JSON.parse(out!.toString("utf8")), ANIM_1);
+  });
+
+  it("falls back to the name-sorted first animation when the manifest is absent", () => {
+    const zip = buildZip([
+      { name: "animations/b.json", data: Buffer.from(JSON.stringify(ANIM_2), "utf8") },
+      { name: "animations/a.json", data: Buffer.from(JSON.stringify(ANIM_1), "utf8") },
+    ]);
+    const out = extractDotLottieJson(zip);
+    assert.ok(out);
+    assert.deepEqual(JSON.parse(out!.toString("utf8")), ANIM_1); // "a.json" sorts first
+  });
+
+  it("returns null for non-ZIP bytes and for a ZIP with no animations", () => {
+    assert.equal(extractDotLottieJson(Buffer.from('{"v":"5.7"}', "utf8")), null);
+    const noAnims = buildZip([{ name: "manifest.json", data: Buffer.from("{}", "utf8") }]);
+    assert.equal(extractDotLottieJson(noAnims), null);
+  });
+
+  it("reads a named entry directly", () => {
+    const zip = buildZip([{ name: "manifest.json", data: Buffer.from(JSON.stringify(MANIFEST), "utf8"), deflate: true }]);
+    const m = readZipEntry(zip, "manifest.json");
+    assert.ok(m);
+    assert.deepEqual(JSON.parse(m!.toString("utf8")), MANIFEST);
+    assert.equal(readZipEntry(zip, "missing.json"), null);
+  });
+});
+
+describe("asset extension preservation (extFromUrl)", () => {
+  it("preserves real long extensions instead of truncating to 5 chars", () => {
+    assert.equal(extFromUrl("https://x/anim.lottie"), "lottie");
+    assert.equal(extFromUrl("https://x/site.webmanifest"), "webmanifest");
+    assert.equal(extFromUrl("https://x/pic.png?v=2"), "png");
+    assert.equal(extFromUrl("https://x/font.woff2"), "woff2");
+  });
+
+  it("rejects absurdly long or non-alphanumeric trailing segments", () => {
+    assert.equal(extFromUrl("https://x/name.thisisnotanextension"), "");
+    assert.equal(extFromUrl("https://x/dir.with.dots/file"), ""); // dot is in a path segment, not the file
+  });
+});
diff --git a/compiler/test/lottiePlaceholder.test.ts b/compiler/test/lottiePlaceholder.test.ts
new file mode 100644
index 0000000..c220df5
--- /dev/null
+++ b/compiler/test/lottiePlaceholder.test.ts
@@ -0,0 +1,77 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { DITTO_LOTTIE_TSX } from "../src/generate/lottie.js";
+import { isIdentityTransform, canonicalizeTransforms } from "../src/normalize/ir.js";
+import type { StyleMap } from "../src/normalize/ir.js";
+
+/**
+ * The DittoLottie runtime must NOT erase the captured placeholder frame before the animation
+ * has successfully loaded — a failed load would otherwise blank the container (erasing hero /
+ * logo / footer media). These are string assertions on the emitted 'use client' template.
+ */
+describe("DittoLottie placeholder retention", () => {
+  it("does not clear the container's innerHTML before mounting", () => {
+    assert.ok(
+      !/el\.innerHTML\s*=\s*""/.test(DITTO_LOTTIE_TSX),
+      "template must not eagerly clear the placeholder via el.innerHTML = \"\"",
+    );
+  });
+
+  it("mounts the live animation into a separate overlay child, not the container itself", () => {
+    assert.match(DITTO_LOTTIE_TSX, /createElement\(["']div["']\)/);
+    assert.match(DITTO_LOTTIE_TSX, /container:\s*mount/);
+  });
+
+  it("only removes the placeholder after a successful load event (DOMLoaded)", () => {
+    // The reveal/swap must be gated behind lottie's ready event, and the placeholder removal
+    // must live inside that gated path (removing original children once mount is ready).
+    assert.match(DITTO_LOTTIE_TSX, /addEventListener\(\s*["']DOMLoaded["']/);
+    assert.match(DITTO_LOTTIE_TSX, /removeChild/);
+    // The removal must reference the ready swap, not run unconditionally at mount time.
+    const revealIdx = DITTO_LOTTIE_TSX.indexOf("DOMLoaded");
+    const clearIdx = DITTO_LOTTIE_TSX.indexOf("removeChild");
+    assert.ok(revealIdx >= 0 && clearIdx >= 0, "both the ready gate and the placeholder removal must be present");
+  });
+
+  it("handles a failed load without leaving a broken mount stacked over the placeholder", () => {
+    assert.match(DITTO_LOTTIE_TSX, /data_failed/);
+  });
+});
+
+describe("identity-transform canonicalization (isIdentityTransform)", () => {
+  it("treats none and identity matrices as identity", () => {
+    assert.equal(isIdentityTransform("none"), true);
+    assert.equal(isIdentityTransform(undefined), true);
+    assert.equal(isIdentityTransform("matrix(1, 0, 0, 1, 0, 0)"), true);
+    assert.equal(isIdentityTransform("matrix(1,0,0,1,0,0)"), true);
+    assert.equal(
+      isIdentityTransform("matrix3d(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1)"),
+      true,
+    );
+  });
+
+  it("does NOT treat a real (non-identity) transform as identity", () => {
+    assert.equal(isIdentityTransform("matrix(1, 0, 0, 1, 0, 67.75)"), false);
+    assert.equal(isIdentityTransform("translateY(67.75px)"), false);
+    assert.equal(isIdentityTransform("matrix(0.5, 0, 0, 0.5, 0, 0)"), false);
+    assert.equal(isIdentityTransform("matrix3d(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 10, 0, 1)"), false);
+  });
+
+  it("rewrites identity values to `none` while leaving a real transform observable at other widths", () => {
+    // The contamination scenario: the base viewport (1280) baked a scroll-linked translateY,
+    // while the other widths report identity (none / identity matrix). After canonicalization
+    // the identity widths read literal `none`, so the generator's per-band delta emits the
+    // explicit reset and the base transform can't cascade across bands.
+    const computedByVp: Record<number, StyleMap> = {
+      375: { transform: "none" } as StyleMap,
+      768: { transform: "matrix(1, 0, 0, 1, 0, 0)" } as StyleMap,
+      1280: { transform: "matrix(1, 0, 0, 1, 0, 67.75)" } as StyleMap, // contaminated base
+      1920: { transform: "none" } as StyleMap,
+    };
+    canonicalizeTransforms(computedByVp);
+    assert.equal(computedByVp[375]!.transform, "none");
+    assert.equal(computedByVp[768]!.transform, "none"); // identity matrix normalized to none
+    assert.equal(computedByVp[1280]!.transform, "matrix(1, 0, 0, 1, 0, 67.75)"); // real transform preserved
+    assert.equal(computedByVp[1920]!.transform, "none");
+  });
+});
diff --git a/compiler/test/marqueeDiscriminator.test.ts b/compiler/test/marqueeDiscriminator.test.ts
new file mode 100644
index 0000000..ee594d9
--- /dev/null
+++ b/compiler/test/marqueeDiscriminator.test.ts
@@ -0,0 +1,104 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import {
+  medianVelocityPxPerSec,
+  classifyVelocitySamples,
+  hasRepeatedChildren,
+} from "../src/capture/motion.js";
+
+// These cover the pure discriminators extracted from detectMarquees' in-browser sampling.
+// The regression they defend: on a scroll-LINKED-easing page, a static logo row is still
+// lerping toward its scroll-target right after scrollIntoView, reading as a constant
+// velocity over ONE short window → four phantom marquees at identical -34px/s. The layered
+// tests below make that classification fail.
+
+describe("medianVelocityPxPerSec", () => {
+  it("converts a steady per-120ms delta to px/s and ignores the wrap-reset outlier", () => {
+    // steady -4px per 120ms ≈ -33px/s; one big +200 wrap jump is an outlier the median drops.
+    const deltas = [-4, -4, 200, -4, -4];
+    assert.equal(medianVelocityPxPerSec(deltas, 120), Math.round((-4 / 120) * 1000));
+  });
+  it("returns 0 for empty deltas or a non-positive cadence", () => {
+    assert.equal(medianVelocityPxPerSec([], 120), 0);
+    assert.equal(medianVelocityPxPerSec([-4, -4], 0), 0);
+  });
+});
+
+describe("classifyVelocitySamples — sustained constant velocity (discriminator 2)", () => {
+  const MS = 120;
+  it("PASSES a real marquee: velocity holds across both windows", () => {
+    const w1 = [-4, -4, -4, -4, -4];
+    const w2 = [-4, -4, -4, -4, -4];
+    const r = classifyVelocitySamples(w1, w2, MS);
+    assert.equal(r.isMarquee, true);
+    assert.equal(r.pxPerSec, medianVelocityPxPerSec(w1, MS));
+  });
+
+  it("REJECTS a scroll-settle lerp: velocity decays sharply in window 2 (the false positive)", () => {
+    // window1 still lerping fast toward scroll-target; window2 nearly settled.
+    const w1 = [-4, -4, -4, -4, -4]; // ≈ -33px/s (the phantom "-34px/s")
+    const w2 = [-0.4, -0.4, -0.4, -0.4, -0.4]; // decayed to ~-3px/s
+    assert.equal(classifyVelocitySamples(w1, w2, MS).isMarquee, false);
+  });
+
+  it("REJECTS when window 2 has fully settled (velocity ~0)", () => {
+    const w1 = [-4, -4, -4, -4, -4];
+    const w2 = [0, 0, 0, 0, 0];
+    assert.equal(classifyVelocitySamples(w1, w2, MS).isMarquee, false);
+  });
+
+  it("REJECTS when the direction reverses between windows", () => {
+    const w1 = [-4, -4, -4, -4, -4];
+    const w2 = [4, 4, 4, 4, 4];
+    assert.equal(classifyVelocitySamples(w1, w2, MS).isMarquee, false);
+  });
+
+  it("REJECTS a static row: no motion in either window", () => {
+    assert.equal(classifyVelocitySamples([0, 0, 0], [0, 0, 0], MS).isMarquee, false);
+  });
+
+  it("PASSES a slightly slower-but-still-moving second window (within tolerance)", () => {
+    // small natural jitter (10% slower) must not disqualify a genuine ticker.
+    const w1 = [-4, -4, -4, -4, -4];
+    const w2 = [-3.6, -3.6, -3.6, -3.6, -3.6];
+    assert.equal(classifyVelocitySamples(w1, w2, MS).isMarquee, true);
+  });
+});
+
+describe("hasRepeatedChildren — genuine duplication (discriminator 4)", () => {
+  it("PASSES two consecutive children with an identical outerHTML hash (a cloned copy)", () => {
+    const hashes = [111, 111, 222]; // first two are a literal duplicate
+    const widths = [80, 80, 120];
+    assert.equal(hasRepeatedChildren(hashes, widths), true);
+  });
+
+  it("PASSES a duplicated content block via the repeated width sequence [A B A B]", () => {
+    // hashes differ (cloned then attribute-tweaked) but geometry repeats: [100,60,100,60].
+    const hashes = [1, 2, 3, 4];
+    const widths = [100, 60, 100, 60];
+    assert.equal(hasRepeatedChildren(hashes, widths), true);
+  });
+
+  it("REJECTS a row of distinct logos: no consecutive repetition (the false-positive shape)", () => {
+    // four DIFFERENT logos — the exact static-logo-row case that produced phantom marquees.
+    const hashes = [10, 20, 30, 40];
+    const widths = [90, 110, 75, 130];
+    assert.equal(hasRepeatedChildren(hashes, widths), false);
+  });
+
+  it("REJECTS fewer than two children", () => {
+    assert.equal(hasRepeatedChildren([5], [50]), false);
+    assert.equal(hasRepeatedChildren([], []), false);
+  });
+
+  it("does NOT treat a run of zero-width nodes as repetition (hash 0 / width 0 guards)", () => {
+    assert.equal(hasRepeatedChildren([0, 0], [0, 0]), false);
+    assert.equal(hasRepeatedChildren([1, 2, 3, 4], [0, 0, 0, 0]), false);
+  });
+
+  it("REJECTS an odd-length width sequence that can't split into halves", () => {
+    const hashes = [1, 2, 3];
+    const widths = [100, 60, 100];
+    assert.equal(hasRepeatedChildren(hashes, widths), false);
+  });
+});
diff --git a/compiler/test/qualityScore.test.ts b/compiler/test/qualityScore.test.ts
new file mode 100644
index 0000000..13ef61c
--- /dev/null
+++ b/compiler/test/qualityScore.test.ts
@@ -0,0 +1,256 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  inlineBlobBytes,
+  filePayload,
+  whitespaceLiterals,
+  subpixelArbitraries,
+  customPropTokens,
+  probeArtifacts,
+  uncleanedListeners,
+  tagHistogram,
+  ariaHiddenFocusables,
+  duplicateHelpers,
+  svgPathDuplication,
+  nearDuplicateComponents,
+  componentNames,
+  toLetter,
+  scoreApp,
+  type SrcFile,
+} from "../src/runner/qualityScore.js";
+
+const srcFile = (rel: string, text: string): SrcFile => ({
+  path: rel, rel, ext: rel.slice(rel.lastIndexOf(".")), text, lines: text.split("\n").length,
+});
+
+// ---------------------------------------------------------------------------
+// Metric extractors
+// ---------------------------------------------------------------------------
+
+describe("inlineBlobBytes", () => {
+  it("counts base64 data-URI payload bytes", () => {
+    const b64 = "A".repeat(500);
+    const text = `const img = "data:image/png;base64,${b64}";`;
+    assert.equal(inlineBlobBytes(text), 500);
+  });
+
+  it("counts a long markup string handed in as a prop", () => {
+    const html = "<div>" + "<span>x</span>".repeat(250) + "</div>";
+    const text = `<Frame html={${JSON.stringify(html)}} />`;
+    assert.ok(inlineBlobBytes(text) > 1000, "flags HTML-as-string blob");
+  });
+
+  it("ignores ordinary short strings", () => {
+    assert.equal(inlineBlobBytes(`const s = "hello world";`), 0);
+  });
+});
+
+describe("filePayload", () => {
+  it("reports a giant single line", () => {
+    const giant = "x".repeat(200_000);
+    const p = filePayload(srcFile("a.tsx", `const a = 1;\nconst b = "${giant}";\n`));
+    assert.ok(p.maxLine >= 200_000, "detects the giant line");
+    assert.ok(p.bytes >= 200_000, "counts the bytes");
+  });
+
+  it("a normal formatted file has a small max line", () => {
+    const p = filePayload(srcFile("a.tsx", "const a = 1;\nconst b = 2;\nexport default a;\n"));
+    assert.ok(p.maxLine < 40, "small max line");
+  });
+});
+
+describe("whitespaceLiterals", () => {
+  it("counts {\" \"} capture-whitespace literals", () => {
+    const text = `<p>Hi{" "}there{" "}world{' '}!</p>`;
+    assert.equal(whitespaceLiterals(text), 3);
+  });
+
+  it("does not flag meaningful expression literals", () => {
+    assert.equal(whitespaceLiterals(`<p>{name}{count}</p>`), 0);
+  });
+});
+
+describe("subpixelArbitraries", () => {
+  it("flags non-integer px/rem arbitraries but not whole ones", () => {
+    // 713.938px (frozen) + 12.5rem (=200px, whole) → only the first counts.
+    const text = `<div className="w-[713.938px] h-[12.5rem] p-[16px]" />`;
+    assert.equal(subpixelArbitraries(text), 1);
+  });
+});
+
+describe("customPropTokens", () => {
+  it("splits opaque --clr-N / hash tokens from named ones", () => {
+    const css = `:root{ --clr-7:#fff; --c12:#000; --a1b2c3:#111; --brand-primary:#f00; --space-4:1rem; }`;
+    const t = customPropTokens(css);
+    assert.equal(t.total, 5);
+    assert.equal(t.opaque, 3, "clr-7, c12, hash a1b2c3 are opaque; brand-primary/space-4 are named");
+  });
+});
+
+describe("probeArtifacts", () => {
+  it("flags off-screen capture-probe scaffolding", () => {
+    const text = `<span data-probe="1">m</span><i style={{clip: 'rect(0 0 0 0)'}} />`;
+    assert.ok(probeArtifacts(text) >= 2);
+  });
+});
+
+describe("uncleanedListeners", () => {
+  it("counts addEventListener with no cleanup", () => {
+    const text = `el.addEventListener("scroll", fn);\nwin.addEventListener("resize", fn);`;
+    assert.equal(uncleanedListeners(text), 2);
+  });
+
+  it("does not flag when a matching removeEventListener / teardown exists", () => {
+    const text = `useEffect(() => { el.addEventListener("scroll", fn); return () => el.removeEventListener("scroll", fn); });`;
+    assert.equal(uncleanedListeners(text), 0);
+  });
+});
+
+describe("tagHistogram", () => {
+  it("counts opening element tags by name", () => {
+    const h = tagHistogram(`<div><div/><span>x</span><button>b</button></div>`);
+    assert.equal(h["div"], 2);
+    assert.equal(h["span"], 1);
+    assert.equal(h["button"], 1);
+  });
+});
+
+describe("ariaHiddenFocusables", () => {
+  it("flags aria-hidden on a focusable element", () => {
+    const text = `<button aria-hidden="true">x</button><a aria-hidden={true} href="#">y</a>`;
+    assert.equal(ariaHiddenFocusables(text), 2);
+  });
+
+  it("ignores aria-hidden on a decorative div", () => {
+    assert.equal(ariaHiddenFocusables(`<div aria-hidden="true" />`), 0);
+  });
+});
+
+describe("duplicateHelpers", () => {
+  it("counts copy-paste helper bodies (e.g. a repeated cn())", () => {
+    const body = `{ return classes.filter(Boolean).join(" ").replace(/\\s+/g, " ").trim(); }`;
+    const text = `function cn(...classes) ${body}\nfunction cx(...classes) ${body}\nfunction merge(...classes) ${body}`;
+    const d = duplicateHelpers(text);
+    assert.equal(d.defs, 3);
+    assert.equal(d.dups, 2, "two of the three are identical duplicates");
+  });
+
+  it("does not flag distinct helper bodies", () => {
+    const text = `function a(x) { return x + 1111111111; }\nfunction b(x) { return x - 2222222222; }`;
+    assert.equal(duplicateHelpers(text).dups, 0);
+  });
+});
+
+describe("svgPathDuplication", () => {
+  it("counts repeated inline <path d=...> strings", () => {
+    const d = "M10 10 L20 20 L30 30 Z aaaaaaaaaaaaaaaa";
+    const text = `<path d="${d}"/><path d="${d}"/><path d="M1 1 L2 2 different pathhhhhhhh"/>`;
+    const r = svgPathDuplication(text);
+    assert.equal(r.total, 3);
+    assert.equal(r.repeats, 1);
+  });
+});
+
+describe("nearDuplicateComponents", () => {
+  it("counts pairs sharing a tag signature", () => {
+    assert.equal(nearDuplicateComponents(["div:2,span:1", "div:2,span:1", "nav:1"]), 1);
+    assert.equal(nearDuplicateComponents(["a", "a", "a"]), 2);
+  });
+});
+
+describe("componentNames", () => {
+  it("extracts exported + declared component symbols", () => {
+    const text = `export default function HeroSection(){}\nexport function Footer(){}\nconst Navbar = () => {};`;
+    const names = componentNames(text);
+    assert.ok(names.includes("HeroSection"));
+    assert.ok(names.includes("Footer"));
+    assert.ok(names.includes("Navbar"));
+  });
+});
+
+describe("toLetter", () => {
+  it("maps scores to the expected grade bands", () => {
+    assert.equal(toLetter(95), "A");
+    assert.equal(toLetter(82), "B-");
+    assert.equal(toLetter(75), "C");
+    assert.equal(toLetter(67), "D+");
+    assert.equal(toLetter(59), "F");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// scoreApp — end-to-end on synthetic app trees (generic fixture content)
+// ---------------------------------------------------------------------------
+
+function makeTree(files: Record<string, string>): string {
+  const root = mkdtempSync(join(tmpdir(), "qs-"));
+  for (const [rel, text] of Object.entries(files)) {
+    const p = join(root, rel);
+    mkdirSync(p.slice(0, p.lastIndexOf("/")), { recursive: true });
+    writeFileSync(p, text);
+  }
+  return root;
+}
+
+describe("scoreApp — hard cap on catastrophic payload", () => {
+  it("caps a tree containing a multi-megabyte source file into D-range", () => {
+    const giant = "x".repeat(1_200_000); // >1MB single file
+    const root = makeTree({
+      "src/app/page.tsx": `export default function Page(){ return <main><h1>Hi</h1><section><p>ok</p></section></main>; }`,
+      "src/app/svgs/blob.tsx": `export const blob = "${giant}";`,
+    });
+    try {
+      const rep = scoreApp(root);
+      assert.ok(rep.caps.length > 0, "a catastrophe cap is recorded");
+      assert.ok(rep.total <= 68, `grade is capped into D-range, got ${rep.total}`);
+      assert.ok(["D+", "D", "D-", "F"].includes(rep.grade), `grade ${rep.grade} is D-range or below`);
+      assert.ok(rep.categories.payload!.score < rep.categories.payload!.max * 0.5, "payload dimension collapses");
+    } finally { rmSync(root, { recursive: true, force: true }); }
+  });
+});
+
+describe("scoreApp — semantics", () => {
+  it("penalizes a page with no h1 vs one with a single h1", () => {
+    const withH1 = makeTree({
+      "src/app/page.tsx": `export default function Page(){ return <main><h1>Title</h1><section><p>a</p></section><nav><a href="#">x</a></nav></main>; }`,
+    });
+    const noH1 = makeTree({
+      "src/app/page.tsx": `export default function Page(){ return <div><div><div><div><span>a</span></div></div></div></div>; }`,
+    });
+    try {
+      const a = scoreApp(withH1);
+      const b = scoreApp(noH1);
+      assert.ok(a.categories.semantics!.score > b.categories.semantics!.score, "h1 + semantic tags score higher");
+      assert.equal(b.categories.semantics!.metrics.h1, 0);
+    } finally {
+      rmSync(withH1, { recursive: true, force: true });
+      rmSync(noH1, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("scoreApp — decomposition", () => {
+  it("rates a decomposed tree above a single-file monolith of the same markup", () => {
+    const bodyTags = "<div><p>x</p><a href='#'>l</a></div>".repeat(40);
+    const monolith = makeTree({
+      "src/app/page.tsx": `export default function Page(){ return <main><h1>H</h1>${bodyTags}</main>; }`,
+    });
+    const decomposed = makeTree({
+      "src/app/page.tsx": `import Hero from "./sections/hero";\nimport Feature from "./sections/feature";\nexport default function Page(){ return <main><h1>H</h1><Hero/><Feature/></main>; }`,
+      "src/app/sections/hero.tsx": `export function Hero(){ return <section>${"<div><p>x</p></div>".repeat(20)}</section>; }`,
+      "src/app/sections/feature.tsx": `export function Feature(){ return <section>${"<div><a href='#'>l</a></div>".repeat(20)}</section>; }`,
+    });
+    try {
+      const m = scoreApp(monolith);
+      const d = scoreApp(decomposed);
+      assert.ok(d.categories.decomposition!.score > m.categories.decomposition!.score, "decomposed scores higher on decomposition");
+      assert.ok(d.total > m.total, "and grades higher overall");
+    } finally {
+      rmSync(monolith, { recursive: true, force: true });
+      rmSync(decomposed, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/compiler/test/recipeGridGeometry.test.ts b/compiler/test/recipeGridGeometry.test.ts
new file mode 100644
index 0000000..9fa45e2
--- /dev/null
+++ b/compiler/test/recipeGridGeometry.test.ts
@@ -0,0 +1,157 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import type { IR, IRNode, IRChild, StyleMap, BBox } from "../src/normalize/ir.js";
+import type { RecipeReport, RecipeCandidate, RecipeResponsiveRegime } from "../src/infer/recipes.js";
+import { recipeResponsiveClassCleaner } from "../src/generate/app.js";
+
+// The recipe pass infers a container's column count by grouping item bounding boxes into rows and
+// taking the widest row. When an item spans multiple tracks that under-reports the real track count,
+// so the synthesized column plan must NOT override the authored/computed grid geometry that the
+// Tailwind emitter already baked into the className. These fixtures build a 3-track grid whose main
+// card spans 2 columns (heuristic reports 2 columns) and assert the emitted classes keep 3 tracks
+// and the span.
+
+const VPS = [768, 1280];
+
+function computed(over: StyleMap = {}): StyleMap {
+  return { display: "block", position: "static", visibility: "visible", whiteSpace: "normal", ...over };
+}
+
+function node(id: string, tag: string, byVp: Record<number, StyleMap>, children: IRChild[] = []): IRNode {
+  const computedByVp: Record<number, StyleMap> = {};
+  const bboxByVp: Record<number, BBox> = {};
+  const visibleByVp: Record<number, boolean> = {};
+  for (const vp of VPS) {
+    computedByVp[vp] = { ...computed(), ...(byVp[vp] ?? {}) };
+    bboxByVp[vp] = { x: 0, y: 0, width: vp, height: 100 };
+    visibleByVp[vp] = true;
+  }
+  return { id, tag, attrs: {}, visibleByVp, bboxByVp, computedByVp, children };
+}
+
+function irWith(root: IRNode): IR {
+  return {
+    doc: {
+      sourceUrl: "https://example.test/",
+      title: "Fixture",
+      lang: "en",
+      charset: "UTF-8",
+      metaViewport: "width=device-width, initial-scale=1",
+      viewports: VPS,
+      sampleViewports: VPS,
+      canonicalViewport: 1280,
+      perViewport: Object.fromEntries(VPS.map((vp) => [vp, { scrollHeight: 800, scrollWidth: vp, htmlBg: "rgb(255,255,255)", bodyBg: "rgb(255,255,255)", bodyColor: "rgb(0,0,0)", bodyFont: "Arial" }])),
+      nodeCount: 4,
+      keyframes: [],
+    },
+    root,
+  };
+}
+
+function regime(viewport: number, columns: number, visibleItems: number): RecipeResponsiveRegime {
+  return { viewport, layout: "grid", rootBox: { x: 0, y: 0, width: viewport, height: 400 }, visibleItems, columns, rows: 1 };
+}
+
+function candidate(over: Partial<RecipeCandidate>): RecipeCandidate {
+  return {
+    id: "r0",
+    kind: "product-grid",
+    confidence: 0.89,
+    risk: "low",
+    rootCid: "n0",
+    rootTag: "section",
+    itemParentCid: "n1",
+    componentName: "ProductGridSection",
+    itemCount: 2,
+    repeatedItems: [],
+    responsiveRegimes: [regime(768, 2, 2), regime(1280, 2, 2)],
+    sourceHints: [],
+    signals: [],
+    emissionStatus: "report-only",
+    fallbackReason: "",
+    ...over,
+  };
+}
+
+function report(candidates: RecipeCandidate[]): RecipeReport {
+  return {
+    version: 1,
+    sourceUrl: "https://example.test/",
+    canonicalViewport: 1280,
+    viewports: VPS,
+    sampledViewports: VPS,
+    summary: { totalCandidates: candidates.length, highConfidence: candidates.length, byKind: {}, templateReadyKinds: [] },
+    candidates,
+  };
+}
+
+// A 3-track grid: the main card spans 2 tracks (`grid-column: 1 / 3`) and a photo occupies track 3.
+// The item-count heuristic groups the two items into one row → columns = 2, which disagrees with the
+// computed 3 tracks.
+function spanningGridIr(): IR {
+  const threeTracks = "284px 284px 284px";
+  const card = node("n2", "article", {
+    768: { gridColumnStart: "1", gridColumnEnd: "3" },
+    1280: { gridColumnStart: "1", gridColumnEnd: "3" },
+  });
+  const photo = node("n3", "img", {
+    768: { gridColumnStart: "3", gridColumnEnd: "4" },
+    1280: { gridColumnStart: "3", gridColumnEnd: "4" },
+  });
+  const parent = node("n1", "div", {
+    768: { display: "grid", gridTemplateColumns: threeTracks },
+    1280: { display: "grid", gridTemplateColumns: threeTracks },
+  }, [card, photo]);
+  return irWith(node("n0", "section", {}, [parent]));
+}
+
+describe("recipe grid geometry: computed tracks/spans are ground truth", () => {
+  it("does not override a 3-track grid with a heuristic 2-column plan (span-2 item present)", () => {
+    const ir = spanningGridIr();
+    const c = candidate({ itemParentCid: "n1", repeatedItems: [
+      { cid: "n2", tag: "article", textSample: "", mediaCount: 1, headingCount: 1, bbox: { x: 0, y: 0, width: 568, height: 300 } },
+      { cid: "n3", tag: "img", textSample: "", mediaCount: 1, headingCount: 0, bbox: { x: 584, y: 0, width: 284, height: 300 } },
+    ] });
+    const clean = recipeResponsiveClassCleaner(ir, report([c]), { tailwind: true });
+
+    // The Tailwind emitter has already put the authored 3-track grid on the container className.
+    const containerIn = "grid grid-cols-3 gap-4";
+    const containerOut = clean("n1", containerIn)!.split(/\s+/);
+    assert.ok(containerOut.includes("grid-cols-3"), "authored 3-track grid-cols-3 survives");
+    assert.ok(!containerOut.some((t) => /(?:^|:)grid-cols-2$/.test(t)), "no synthesized grid-cols-2 override");
+    // No responsive column-plan tokens are appended (the plan was rejected as untrustworthy).
+    assert.ok(!containerOut.some((t) => /^(?:md|lg|2xl):grid-cols-/.test(t)), "no responsive grid-cols plan appended");
+
+    // The span-2 item keeps its authored column span (emitter tokens pass through untouched).
+    const itemOut = clean("n2", "col-start-1 col-end-3 flex flex-col")!;
+    assert.equal(itemOut, "col-start-1 col-end-3 flex flex-col", "span-2 item className is unchanged");
+  });
+
+  it("still re-flows a genuinely uniform grid whose computed tracks match the heuristic", () => {
+    // 2-track grid at 768, 3-track at 1280, no spanning items → heuristic agrees with computed.
+    const item = (id: string): IRNode => node(id, "article", {
+      768: { gridColumnStart: "auto", gridColumnEnd: "auto" },
+      1280: { gridColumnStart: "auto", gridColumnEnd: "auto" },
+    });
+    const parent = node("n1", "div", {
+      768: { display: "grid", gridTemplateColumns: "300px 300px" },
+      1280: { display: "grid", gridTemplateColumns: "284px 284px 284px" },
+    }, [item("n2"), item("n3"), item("n4")]);
+    const ir = irWith(node("n0", "section", {}, [parent]));
+    const c = candidate({
+      itemParentCid: "n1",
+      itemCount: 3,
+      responsiveRegimes: [regime(768, 2, 3), regime(1280, 3, 3)],
+      repeatedItems: [
+        { cid: "n2", tag: "article", textSample: "", mediaCount: 1, headingCount: 1, bbox: { x: 0, y: 0, width: 300, height: 300 } },
+        { cid: "n3", tag: "article", textSample: "", mediaCount: 1, headingCount: 1, bbox: { x: 316, y: 0, width: 300, height: 300 } },
+        { cid: "n4", tag: "article", textSample: "", mediaCount: 1, headingCount: 1, bbox: { x: 0, y: 316, width: 300, height: 300 } },
+      ],
+    });
+    const clean = recipeResponsiveClassCleaner(ir, report([c]), { tailwind: true });
+    const out = clean("n1", "grid grid-cols-2 gap-4")!.split(/\s+/);
+    // Geometry agreed → the responsive plan is applied: base 2 columns, lg:3 at the wider viewport.
+    assert.ok(out.includes("grid-cols-2"), "base column count applied");
+    assert.ok(out.includes("lg:grid-cols-3"), "responsive column bump applied");
+  });
+});
diff --git a/compiler/test/tailwind.test.ts b/compiler/test/tailwind.test.ts
index dbd9938..141d741 100644
--- a/compiler/test/tailwind.test.ts
+++ b/compiler/test/tailwind.test.ts
@@ -1,6 +1,6 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { declToUtil } from "../src/generate/tailwind.js";
+import { declToUtil, snapBase } from "../src/generate/tailwind.js";
 
 // Zero-value gating. A named `-0` step only exists for props on Tailwind's spacing (or numeric)
 // scales; for the rest the class compiles to NOTHING — a silent no-op that ships the wrong style
@@ -41,3 +41,33 @@ describe("declToUtil zero values", () => {
     assert.equal(declToUtil("letter-spacing", "-0.5px"), "tracking-[-0.5px]");
   });
 });
+
+// BUG B — the spacing-scale snap must only fire when a value lands ESSENTIALLY ON a step (≤0.25px).
+// The scale is 2px-granular (`p-0.5`=2px, `p-1.5`=6px), so 3.5px is BETWEEN steps — snapping it up to
+// p-1 (4px) adds +0.5px per side, which accumulates across a fixed-width flex row until items overflow
+// and wrap. On-step values (2px→p-0.5, 4px→p-1) still snap.
+describe("snapBase spacing-scale snapping", () => {
+  it("keeps a between-steps value arbitrary (3.5px does NOT snap to p-1)", () => {
+    assert.equal(snapBase("p-[3.5px]"), "p-[3.5px]");
+  });
+
+  it("does not snap the same sub-step delta on other spacing props", () => {
+    assert.equal(snapBase("pl-[3.5px]"), "pl-[3.5px]");
+    assert.equal(snapBase("gap-[3.5px]"), "gap-[3.5px]");
+    assert.equal(snapBase("mt-[13.5px]"), "mt-[13.5px]"); // between p-3 (12px) and p-3.5 (14px)
+  });
+
+  it("still snaps a value that sits on a 0.5-step (2px → p-0.5, 6px → p-1.5)", () => {
+    assert.equal(snapBase("p-[2px]"), "p-0.5");
+    assert.equal(snapBase("p-[6px]"), "p-1.5");
+  });
+
+  it("still snaps a near-exact on-step value within the tight budget (3.98px → p-1)", () => {
+    assert.equal(snapBase("p-[3.98px]"), "p-1");
+  });
+
+  it("leaves an already-clean scale utility unchanged and snaps 16px → mx-4", () => {
+    assert.equal(snapBase("p-1"), "p-1");
+    assert.equal(snapBase("mx-[16px]"), "mx-4");
+  });
+});
diff --git a/compiler/test/walker.test.ts b/compiler/test/walker.test.ts
index 5c3e6ba..a288787 100644
--- a/compiler/test/walker.test.ts
+++ b/compiler/test/walker.test.ts
@@ -211,3 +211,109 @@ describe("walker font-metric probe tagging (fix 4)", () => {
     assert.ok(!sr.probe, "sr-only accessible text is not a probe");
   });
 });
+
+describe("walker sizing probe: circular authored-height guard", () => {
+  let browser: Browser;
+  let page: Page;
+  before(async () => {
+    browser = await chromium.launch();
+    page = await browser.newPage({ viewport: { width: 1280, height: 720 } });
+  });
+  after(async () => {
+    await browser.close();
+  });
+
+  const capture = async (html: string) => {
+    await page.setContent(html);
+    await page.evaluate("globalThis.__name = globalThis.__name || ((fn) => fn);");
+    return page.evaluate(collectPage);
+  };
+
+  it("keeps an explicit 100vh height (circular hero/fill-child pair)", async () => {
+    // A hero authored `height:100vh` with a `height:100%` fill child: setting the hero to
+    // `height:auto` still reproduces its box because the child pins it back, so the raw probe
+    // would read hAuto:true and the authored 100vh would be dropped — hero collapses to 0.
+    const snap = await capture(`
+      <style>
+        .hero { height: 100vh; display: flex; }
+        .fill { height: 100%; width: 100%; }
+      </style>
+      <section class="hero"><div class="fill"><p>content</p></div></section>`);
+    const hero = findByClass(snap.root, "hero")!;
+    assert.ok(hero.sizing, "hero was probed");
+    assert.equal(hero.sizing!.hAuto, false, "explicit 100vh is not content-sized");
+    assert.equal(hero.sizing!.hFill, false, "explicit 100vh is authored, not a parent fill");
+    // Box actually equals the viewport height (720), proving the circular reproduction.
+    assert.ok(Math.abs(hero.bbox.height - 720) <= 1, "hero rendered at 100vh");
+  });
+
+  it("keeps an explicit px height whose fill child reproduces it", async () => {
+    const snap = await capture(`
+      <style>
+        .section { height: 400px; display: flex; }
+        .fill { height: 100%; width: 100%; }
+      </style>
+      <div class="section"><div class="fill"><p>content</p></div></div>`);
+    const section = findByClass(snap.root, "section")!;
+    assert.ok(section.sizing, "section was probed");
+    assert.equal(section.sizing!.hAuto, false, "explicit 400px is not content-sized");
+    assert.equal(section.sizing!.hFill, false, "explicit 400px is authored, not a fill");
+    assert.ok(Math.abs(section.bbox.height - 400) <= 1, "section rendered at 400px");
+  });
+
+  it("keeps an explicit height authored via inline style", async () => {
+    const snap = await capture(`
+      <style>.fill { height: 100%; width: 100%; }</style>
+      <div class="box" style="height: 300px; display: flex;">
+        <div class="fill"><p>content</p></div>
+      </div>`);
+    const box = findByClass(snap.root, "box")!;
+    assert.ok(box.sizing, "box was probed");
+    assert.equal(box.sizing!.hAuto, false, "inline explicit height is kept");
+    assert.equal(box.sizing!.hFill, false, "inline explicit height is not a fill");
+  });
+
+  it("resolves the mutual parent/child pair without disturbing the fill child", async () => {
+    // The child is a GENUINE fill (height:100%) and must keep hFill:true / hAuto:false so the
+    // generator emits h-full for it; only the parent's circular verdict is corrected.
+    const snap = await capture(`
+      <style>
+        .outer { height: 500px; display: flex; }
+        .inner { height: 100%; width: 100%; }
+      </style>
+      <div class="outer"><div class="inner"><p>content</p></div></div>`);
+    const outer = findByClass(snap.root, "outer")!;
+    const inner = findByClass(snap.root, "inner")!;
+    assert.equal(outer.sizing!.hAuto, false, "parent explicit height kept");
+    assert.equal(outer.sizing!.hFill, false, "parent is authored, not a fill");
+    // The child authors only `height:100%` (a fill), so the explicit-height guard must NOT fire on
+    // it — hFill stays true so the generator can still emit h-full for the genuine fill child.
+    assert.equal(inner.sizing!.hFill, true, "child still fills the definite parent");
+  });
+
+  it("still detects a genuinely content-sized (auto) height as hAuto", async () => {
+    // No authored height anywhere: the box is content-sized and must stay droppable.
+    const snap = await capture(`
+      <style>.wrap { display: block; }</style>
+      <div class="wrap"><p>just some flowing text content</p></div>`);
+    const wrap = findByClass(snap.root, "wrap")!;
+    assert.ok(wrap.sizing, "wrap was probed");
+    assert.equal(wrap.sizing!.hAuto, true, "content-sized height is still auto");
+  });
+
+  it("does not treat a percentage or zero authored height as explicit", async () => {
+    // height:100% is the FILL case (handled by hFill), and height:0 is not definite; neither
+    // should trip the explicit-height override.
+    const snap = await capture(`
+      <style>
+        .pct-parent { height: 300px; }
+        .pct { height: 100%; }
+      </style>
+      <div class="pct-parent"><div class="pct"><p>x</p></div></div>`);
+    const pct = findByClass(snap.root, "pct")!;
+    assert.ok(pct.sizing, "pct was probed");
+    // A true fill child: hFill true, hAuto false — untouched by the explicit-height guard.
+    assert.equal(pct.sizing!.hFill, true, "percentage height stays a fill");
+    assert.equal(pct.sizing!.hAuto, false, "percentage fill is not content-sized");
+  });
+});

From 6a930d57b11abca80ee24362bef568f0b92bcbe0 Mon Sep 17 00:00:00 2001
From: Samraaj Bath <samraaj100@gmail.com>
Date: Fri, 3 Jul 2026 23:31:07 -0700
Subject: [PATCH 03/24] Section decomposition: recursive descent with semantic
 band detection

detectSections gave up on real pages: <body> swallowed everything, a single
oversized-wrapper expansion pass required >=3 candidates, and a 62px navbar
failed the 64px height bar - so nearly every clone shipped as one section
and one monolithic component.

Rewritten around a shared recursive core (detectSectionNodes): containers
covering >50% of the page are wrappers to descend into; a split is accepted
only when >=2 stacked bands tile >=80% of the container (side-by-side
columns and overlays never split; truly single-band pages legally stay 1).
Semantic tags get a 24px bar with nav-evidence detection for thin bars.
The validator's section list and the emitted section components now consume
the same root set, so gate-5 bands and sections/*.tsx files always agree.
Naming is evidence-based and deterministic: navbar/header/hero (only when
actually near the top), recipe names (logo-cloud, product-grid...), heading
slugs, contact/media, positional fallback.

Frozen-capture probes: 1 -> 6..17 sections across the reference runs, with
the old whole-page "hero-section" monoliths splitting into honest bands.

231 tests pass (13 new), typecheck clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 compiler/src/generate/sectionSplit.ts |  75 ++++----
 compiler/src/infer/sections.ts        | 241 ++++++++++++++++----------
 compiler/test/sections.test.ts        | 238 +++++++++++++++++++++++++
 3 files changed, 422 insertions(+), 132 deletions(-)
 create mode 100644 compiler/test/sections.test.ts

diff --git a/compiler/src/generate/sectionSplit.ts b/compiler/src/generate/sectionSplit.ts
index f209ca7..5835654 100644
--- a/compiler/src/generate/sectionSplit.ts
+++ b/compiler/src/generate/sectionSplit.ts
@@ -15,6 +15,7 @@
 import type { IR, IRNode } from "../normalize/ir.js";
 import { isTextChild } from "../normalize/ir.js";
 import type { RecipeCandidate, RecipeKind, RecipeReport } from "../infer/recipes.js";
+import { detectSectionNodes, heroLikeHeader } from "../infer/sections.js";
 import { subtreeSignature } from "../site/sharedLayout.js";
 
 export type SectionPlan = {
@@ -23,7 +24,7 @@ export type SectionPlan = {
 };
 
 const MIN_SECTION_H = 56;
-const MAX_SECTIONS = 24;
+const MAX_SECTIONS = 32;
 
 function box(n: IRNode, cw: number): { width: number; height: number } | undefined {
   return n.bboxByVp[cw] ?? Object.values(n.bboxByVp)[0];
@@ -31,15 +32,9 @@ function box(n: IRNode, cw: number): { width: number; height: number } | undefin
 function yOf(n: IRNode, cw: number): number {
   return (n.bboxByVp[cw] ?? Object.values(n.bboxByVp)[0])?.y ?? 0;
 }
-function visible(n: IRNode, cw: number): boolean {
-  return !!(n.visibleByVp[cw] ?? Object.values(n.visibleByVp)[0]);
-}
 function elementChildren(n: IRNode): IRNode[] {
   return n.children.filter((c): c is IRNode => !isTextChild(c));
 }
-function significantChildren(n: IRNode, cw: number): IRNode[] {
-  return elementChildren(n).filter((c) => visible(c, cw) && (box(c, cw)?.height ?? 0) >= MIN_SECTION_H);
-}
 
 function subtreeHasTag(n: IRNode, tag: string, depth = 4): boolean {
   if (depth < 0) return false;
@@ -225,18 +220,11 @@ function recipeFallbackSections(ir: IR, recipes?: RecipeReport): { sections: IRN
 
 export function planSections(ir: IR, recipes?: RecipeReport): SectionPlan {
   const cw = ir.doc.canonicalViewport;
-  // Descend through the wrapper chain (single significant child) to the container
-  // whose children are the actual sections.
-  let node = ir.root;
-  for (let i = 0; i < 10; i++) {
-    const sig = significantChildren(node, cw);
-    if (sig.length >= 2) break;
-    if (sig.length === 1) { node = sig[0]!; continue; }
-    const kids = elementChildren(node);
-    if (kids.length === 1) { node = kids[0]!; continue; }
-    break;
-  }
-  // Exclude any child that is part of a REPEATED run (≥3 same-signature siblings): that's
+  const pageH = ir.doc.perViewport[cw]?.scrollHeight ?? 0;
+  // The shared recursive band decomposition (infer/sections) — the same roots the
+  // section gate validates, so each emitted file corresponds to a gate section.
+  const bands = detectSectionNodes(ir).filter((n) => n.id !== ir.root.id);
+  // Exclude any band that is part of a REPEATED run (≥3 same-signature siblings): that's
   // a component cluster (a card/logo grid), which component extraction should turn into a
   // `.map()` over a data array — not a wall of near-identical "section" files. Only the
   // distinct, one-off blocks become sections.
@@ -246,29 +234,14 @@ export function planSections(ir: IR, recipes?: RecipeReport): SectionPlan {
     return list.filter((s) => (count.get(subtreeSignature(s)) ?? 0) < 3);
   };
 
-  let candidates = significantChildren(node, cw);
-  let sections = distinctOf(candidates);
-  const fallback = recipeFallbackSections(ir, recipes);
-  // If the container yields too few sections, a dominant child is a wrapper (e.g. <main>)
-  // holding the real sections — expand such oversized children into their own significant
-  // children, keeping the other siblings (e.g. a sibling <footer>). Gated on <3 so a page
-  // that already splits cleanly is untouched.
-  if (sections.length < 3) {
-    const pageH = ir.doc.perViewport[cw]?.scrollHeight ?? 0;
-    const expanded: IRNode[] = [];
-    for (const c of candidates) {
-      const inner = significantChildren(c, cw);
-      const h = box(c, cw)?.height ?? 0;
-      if (inner.length >= 3 && pageH > 0 && h >= pageH * 0.4) expanded.push(...inner);
-      else expanded.push(c);
-    }
-    candidates = expanded;
-    sections = distinctOf(candidates);
-  }
+  let sections = distinctOf(bands);
   let recipeNameHints = new Map<string, string>();
-  if (sections.length < 3 && fallback.sections.length >= 3) {
-    sections = fallback.sections;
-    recipeNameHints = fallback.names;
+  if (sections.length < 3) {
+    const fallback = recipeFallbackSections(ir, recipes);
+    if (fallback.sections.length >= 3) {
+      sections = fallback.sections;
+      recipeNameHints = fallback.names;
+    }
   }
   const roots = new Map<string, string>();
   if (sections.length < 3 || sections.length > MAX_SECTIONS) return { roots };
@@ -280,6 +253,10 @@ export function planSections(ir: IR, recipes?: RecipeReport): SectionPlan {
     return n === 1 ? base : `${base}${n}`;
   };
 
+  // Hero must actually start near the top of the page; without the gate a
+  // mid-page band inherits the name when the true hero was excluded (e.g. as a
+  // repeated run), which is worse than an honest content-derived name.
+  const heroMaxY = Math.max(900, pageH * 0.25);
   let heroAssigned = false;
   sections.forEach((sec, i) => {
     const isLast = i === sections.length - 1;
@@ -287,18 +264,26 @@ export function planSections(ir: IR, recipes?: RecipeReport): SectionPlan {
     let name: string;
     if (sec.tag === "footer" || (isLast && looksLikeNav(sec, cw) === false && subtreeHasTag(sec, "a") && (box(sec, cw)?.height ?? 0) < 700)) {
       name = sec.tag === "footer" ? "Footer" : (titleText(sec) ? slugWords(titleText(sec)) + "Section" : "Footer");
-    } else if (i === 0 && looksLikeNav(sec, cw)) {
+    } else if (sec.tag === "nav"
+      || (i === 0 && looksLikeNav(sec, cw) && !heroLikeHeader(sec, cw))
+      // a thin fixed bar wrapping the real <nav> (often a styled <div>, sorted after
+      // the hero it overlays) is still the navbar
+      || (yOf(sec, cw) <= 160 && (box(sec, cw)?.height ?? 0) <= 160 && subtreeHasTag(sec, "nav"))) {
       name = "Navbar";
-    } else if (sec.tag === "header") {
+    } else if (sec.tag === "header" && !heroLikeHeader(sec, cw)) {
+      // a <header> carrying the page h1 at real height is the hero, not chrome
       name = "Header";
-    } else if (!heroAssigned) {
+    } else if (!heroAssigned && yOf(sec, cw) <= heroMaxY) {
       heroAssigned = true;
       name = "HeroSection";
     } else if (recipeName) {
       name = recipeName;
     } else {
       const slug = slugWords(titleText(sec));
-      name = slug ? `${slug}Section` : `Section${i + 1}`;
+      name = slug ? `${slug}Section`
+        : subtreeHasTag(sec, "form", 6) ? "ContactSection"
+        : subtreeHasTag(sec, "video", 6) || subtreeHasTag(sec, "iframe", 6) ? "MediaSection"
+        : `Section${i + 1}`;
     }
     roots.set(sec.id, dedupe(identName(name)));
   });
diff --git a/compiler/src/infer/sections.ts b/compiler/src/infer/sections.ts
index be70454..03f707f 100644
--- a/compiler/src/infer/sections.ts
+++ b/compiler/src/infer/sections.ts
@@ -4,10 +4,19 @@ import { round } from "../util/canonical.js";
 
 /**
  * Deterministic section detection. Splits the page into visually coherent
- * top-level blocks using semantic tags and geometry (we do not rely on class
- * names — those are intentionally dropped from the IR). Sections are metadata:
- * stable ids + per-viewport bboxes for the layout/section gate. Role guesses are
- * advisory and never affect fidelity.
+ * top-level bands using semantic tags and geometry (we do not rely on class
+ * names — those are intentionally dropped from the IR).
+ *
+ * The core is a recursive descent: a container that covers most of the page
+ * (<body> → <div id=root> → <main>) is a WRAPPER, not a band — descend into it
+ * and re-collect among its children, repeating until every candidate is
+ * band-like. A descent only replaces the container when its children actually
+ * tile it (stacked full-width blocks with near-complete coverage), so a page
+ * that truly is one tall band legally stays a single section.
+ *
+ * Sections are metadata: stable ids + per-viewport bboxes for the layout/section
+ * gate, and the shared root set for section-per-file emission (sectionSplit).
+ * Role guesses are advisory and never affect fidelity.
  */
 
 export type Section = {
@@ -19,104 +28,162 @@ export type Section = {
 };
 
 const SEMANTIC = new Set(["header", "nav", "main", "section", "article", "footer", "aside"]);
+const MIN_BAND_H = 64;
+const MIN_SEMANTIC_H = 24; // a 62px navbar is still the navbar
+const MIN_BAND_W_FRAC = 0.55; // a band spans most of the viewport
+const WRAPPER_FRAC = 0.5; // taller than this fraction of the page → wrapper, try descending
+const MIN_CHILD_COVERAGE = 0.8; // children must tile the container to replace it
+const MAX_STACK_OVERLAP = 0.3; // consecutive bands may overlap at most this much of the smaller
+const MAX_BANDS_PER_SPLIT = 20; // a split into more pieces than this is fragmentation, not bands
+const MAX_DEPTH = 12;
 
-type Cand = { node: IRNode; path: string; y: number; width: number; height: number };
+type Cand = { node: IRNode; y: number; width: number; height: number };
+type Ctx = { cw: number; pageH: number };
+
+/** The ordered section-root nodes of the page (top to bottom). Shared by the
+ *  validator (detectSections) and the generator's section splitter, so the gate's
+ *  section list and the emitted section components describe the same bands.
+ *  Falls back to `[ir.root]` when the page has no decomposable structure. */
+export function detectSectionNodes(ir: IR): IRNode[] {
+  const cw = ir.doc.canonicalViewport;
+  const ctx: Ctx = { cw, pageH: ir.doc.perViewport[cw]?.scrollHeight ?? 0 };
+  const bands = bandsOf(ir.root, 0, ctx);
+  // Stable sort by top edge; ties keep document order (a fixed nav stays before
+  // the hero it overlays).
+  bands.sort((a, b) => a.y - b.y);
+  // Nested wrappers can repeat the same box from disjoint subtrees — keep the first.
+  const final: Cand[] = [];
+  for (const c of bands) {
+    if (!final.some((f) => Math.abs(f.y - c.y) < 4 && Math.abs(f.height - c.height) < 4)) final.push(c);
+  }
+  if (final.length === 0) return [ir.root];
+  return final.map((c) => c.node);
+}
 
 export function detectSections(ir: IR): Section[] {
   const cw = ir.doc.canonicalViewport;
-  const vpWidth = cw;
-
-  const candidates: Cand[] = [];
-  const walk = (node: IRNode, path: string): void => {
-    const bbox = node.bboxByVp[cw];
-    const visible = node.visibleByVp[cw];
-    if (bbox && visible) {
-      const isSemantic = SEMANTIC.has(node.tag);
-      const isBigBlock = bbox.width >= vpWidth * 0.55 && bbox.height >= 64;
-      const display = node.computedByVp[cw]?.display ?? "";
-      const blockish = !/^(inline|inline-block|none)$/.test(display);
-      if ((isSemantic || isBigBlock) && blockish) {
-        candidates.push({ node, path, y: bbox.y, width: bbox.width, height: bbox.height });
-      }
-    }
-    for (const c of node.children) {
-      if (isTextChild(c)) continue;
-      walk(c, `${path}/${c.id}`);
-    }
-  };
-  walk(ir.root, ir.root.id);
-
-  // Outermost wins: drop candidates nested inside another candidate.
-  const byShallow = candidates.slice().sort((a, b) => a.path.split("/").length - b.path.split("/").length);
-  let kept: Cand[] = [];
-  for (const c of byShallow) {
-    if (kept.some((k) => c.path.startsWith(k.path + "/"))) continue;
-    kept.push(c);
-  }
-
-  // If the only survivor is a giant wrapper, expand into its section-like children.
-  const pageHeight = ir.doc.perViewport[cw]?.scrollHeight ?? 0;
-  kept = expandOversized(kept, vpWidth, pageHeight, cw);
-
-  // Sort by Y, then assign ids/roles.
-  kept.sort((a, b) => a.y - b.y || b.height - a.height);
-  // Deduplicate near-identical y/height wrappers (keep the first/shallowest).
-  const final: Cand[] = [];
-  for (const c of kept) {
-    const dup = final.find((f) => Math.abs(f.y - c.y) < 4 && Math.abs(f.height - c.height) < 4);
-    if (!dup) final.push(c);
-  }
-
-  return final.map((c, i) => ({
+  const pageH = ir.doc.perViewport[cw]?.scrollHeight ?? 0;
+  const nodes = detectSectionNodes(ir);
+  const roles = guessRoles(nodes, cw, pageH);
+  return nodes.map((node, i) => ({
     id: `section-${String(i + 1).padStart(3, "0")}`,
-    nodeId: c.node.id,
-    role: guessRole(c.node, i, final.length),
+    nodeId: node.id,
+    role: roles[i]!,
     order: i,
-    bboxByVp: bboxesFor(c.node),
+    bboxByVp: bboxesFor(node),
   }));
 }
 
-function expandOversized(cands: Cand[], vpWidth: number, pageHeight: number, cw: number): Cand[] {
-  if (cands.length > 2) return cands;
-  const threshold = Math.max(pageHeight * 0.55, 1200);
+/** Landmark evidence that a bar is site chrome: an ARIA landmark role on the node
+ *  itself, or a <nav> within a shallow wrapper chain. Lets a thin fixed bar (often a
+ *  62px styled <div> around the real <nav>) clear the semantic height bar. */
+export function navEvidence(node: IRNode): boolean {
+  const role = node.attrs.role ?? "";
+  if (role === "banner" || role === "navigation") return true;
+  return subtreeHas(node, (n) => n.tag === "nav" || n.attrs.role === "navigation", 3);
+}
+
+function candOf(node: IRNode, ctx: Ctx): Cand | null {
+  const bbox = node.bboxByVp[ctx.cw];
+  if (!bbox || !node.visibleByVp[ctx.cw]) return null;
+  const display = node.computedByVp[ctx.cw]?.display ?? "";
+  if (/^(inline|inline-block|none)$/.test(display)) return null;
+  if (bbox.width < ctx.cw * MIN_BAND_W_FRAC) return null;
+  const minH = SEMANTIC.has(node.tag) || navEvidence(node) ? MIN_SEMANTIC_H : MIN_BAND_H;
+  if (bbox.height < minH) return null;
+  return { node, y: bbox.y, width: bbox.width, height: bbox.height };
+}
+
+/** Collect the band candidates among `container`'s children. A band-sized child is
+ *  kept; a page-covering child is descended into (its children replace it only when
+ *  they tile it — see acceptSplit); anything else is a transparent wrapper we look
+ *  through. Output is in document order. */
+function bandsOf(container: IRNode, depth: number, ctx: Ctx): Cand[] {
+  if (depth > MAX_DEPTH) return [];
   const out: Cand[] = [];
-  for (const c of cands) {
-    if (c.height < threshold) { out.push(c); continue; }
-    const inner: Cand[] = [];
-    const collect = (node: IRNode, path: string, depth: number): void => {
-      if (depth > 6) return;
-      for (const ch of node.children) {
-        if (isTextChild(ch)) continue;
-        const bbox = ch.bboxByVp[cw];
-        if (bbox && ch.visibleByVp[cw] && bbox.width >= vpWidth * 0.5 && bbox.height >= 64) {
-          inner.push({ node: ch, path: `${path}/${ch.id}`, y: bbox.y, width: bbox.width, height: bbox.height });
-        } else {
-          collect(ch, `${path}/${ch.id}`, depth + 1);
-        }
-      }
-    };
-    collect(c.node, c.path, 0);
-    // outermost wins within inner
-    const byShallow = inner.slice().sort((a, b) => a.path.split("/").length - b.path.split("/").length);
-    const keptInner: Cand[] = [];
-    for (const ic of byShallow) {
-      if (keptInner.some((k) => ic.path.startsWith(k.path + "/"))) continue;
-      keptInner.push(ic);
+  for (const child of container.children) {
+    if (isTextChild(child)) continue;
+    const cand = candOf(child, ctx);
+    if (!cand) {
+      out.push(...bandsOf(child, depth + 1, ctx));
+      continue;
     }
-    if (keptInner.length >= 3) out.push(...keptInner);
-    else out.push(c);
+    if (ctx.pageH > 0 && cand.height > ctx.pageH * WRAPPER_FRAC) {
+      const inner = bandsOf(child, depth + 1, ctx);
+      if (acceptSplit(inner, cand)) {
+        out.push(...inner);
+        continue;
+      }
+    }
+    out.push(cand);
   }
   return out;
 }
 
-function guessRole(node: IRNode, index: number, total: number): string {
-  if (node.tag === "header") return "header";
-  if (node.tag === "nav") return "nav";
-  if (node.tag === "footer") return "footer";
-  if (node.tag === "main") return "main";
-  if (index === 0) return "hero";
-  if (index === total - 1) return "footer";
-  return "section";
+/** May `inner` replace its containing candidate? Only when it reads as a stack of
+ *  bands: at least two, not a fragmentation explosion, vertically stacked (side-by-side
+ *  columns or overlaid layers must not be split), and tiling the container with
+ *  near-complete coverage so no substantial content is silently dropped. */
+function acceptSplit(inner: Cand[], parent: Cand): boolean {
+  if (inner.length < 2 || inner.length > MAX_BANDS_PER_SPLIT) return false;
+  const sorted = inner.slice().sort((a, b) => a.y - b.y);
+  for (let i = 1; i < sorted.length; i++) {
+    const prev = sorted[i - 1]!, cur = sorted[i]!;
+    const overlap = prev.y + prev.height - cur.y;
+    if (overlap > Math.min(prev.height, cur.height) * MAX_STACK_OVERLAP) return false;
+  }
+  let covered = 0, cursor = -Infinity;
+  for (const c of sorted) {
+    const top = Math.max(c.y, cursor), bot = c.y + c.height;
+    if (bot > top) covered += bot - top;
+    cursor = Math.max(cursor, bot);
+  }
+  return covered >= parent.height * MIN_CHILD_COVERAGE;
+}
+
+function subtreeHas(node: IRNode, pred: (n: IRNode) => boolean, depth = 6): boolean {
+  if (depth < 0) return false;
+  for (const c of node.children) {
+    if (isTextChild(c)) continue;
+    if (pred(c) || subtreeHas(c, pred, depth - 1)) return true;
+  }
+  return false;
+}
+
+/** A <header> that carries the page's h1 and real height is the hero band, not
+ *  site chrome — "header → chrome" only holds for the thin bar variant. */
+export function heroLikeHeader(node: IRNode, cw: number): boolean {
+  const h = node.bboxByVp[cw]?.height ?? 0;
+  return h >= 200 && subtreeHas(node, (n) => n.tag === "h1");
+}
+
+/** Advisory roles, one pass top-to-bottom: tag evidence first, then the first
+ *  near-top content band claims "hero" (once), then content evidence. */
+function guessRoles(nodes: IRNode[], cw: number, pageH: number): string[] {
+  let heroClaimed = false;
+  return nodes.map((node, index) => {
+    if (node.tag === "nav") return "navbar";
+    if (node.tag === "header") {
+      if (!heroLikeHeader(node, cw)) return "header";
+      heroClaimed = true;
+      return "hero";
+    }
+    if (node.tag === "footer") return "footer";
+    if (node.tag === "aside") return "aside";
+    if (node.tag === "main") return "main";
+    const bbox = node.bboxByVp[cw];
+    const h = bbox?.height ?? 0, y = bbox?.y ?? 0;
+    // thin top bar without the <nav> tag (first band, or a fixed bar with landmark evidence)
+    if (h <= 140 && y <= 160 && (index === 0 || navEvidence(node))) return "navbar";
+    if (!heroClaimed && (bbox?.y ?? 0) <= Math.max(900, pageH * 0.25)) {
+      heroClaimed = true;
+      return "hero";
+    }
+    if (index === nodes.length - 1) return "footer";
+    if (subtreeHas(node, (n) => n.tag === "form")) return "contact";
+    if (subtreeHas(node, (n) => n.tag === "video" || n.tag === "iframe")) return "media";
+    return "section";
+  });
 }
 
 function bboxesFor(node: IRNode): Section["bboxByVp"] {
diff --git a/compiler/test/sections.test.ts b/compiler/test/sections.test.ts
new file mode 100644
index 0000000..7d230b1
--- /dev/null
+++ b/compiler/test/sections.test.ts
@@ -0,0 +1,238 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { detectSections, detectSectionNodes } from "../src/infer/sections.js";
+import { planSections } from "../src/generate/sectionSplit.js";
+import type { IR, IRNode, IRChild } from "../src/normalize/ir.js";
+
+const CW = 1280;
+
+type Box = { x?: number; y: number; width?: number; height: number };
+
+/** An element node at the canonical viewport (ids assigned later in pre-order). */
+function el(tag: string, box: Box, children: IRChild[] = [], display = "block"): IRNode {
+  return {
+    id: "",
+    tag,
+    attrs: {},
+    visibleByVp: { [CW]: true },
+    bboxByVp: { [CW]: { x: box.x ?? 0, y: box.y, width: box.width ?? CW, height: box.height } },
+    computedByVp: { [CW]: { display } },
+    children,
+  };
+}
+
+function text(t: string): IRChild {
+  return { text: t };
+}
+
+/** Wrap children in a <body> root and assign stable pre-order ids (n0, n1, …). */
+function page(children: IRNode[], pageH: number): IR {
+  const root = el("body", { y: 0, height: pageH }, children);
+  let i = 0;
+  const assign = (n: IRNode): void => {
+    n.id = `n${i++}`;
+    for (const c of n.children) if ((c as IRNode).tag) assign(c as IRNode);
+  };
+  assign(root);
+  return {
+    doc: {
+      sourceUrl: "https://example.test/", title: "Fixture", lang: "en", charset: "UTF-8",
+      metaViewport: "width=device-width, initial-scale=1",
+      viewports: [CW], sampleViewports: [CW], canonicalViewport: CW,
+      perViewport: { [CW]: { scrollHeight: pageH, scrollWidth: CW, htmlBg: "", bodyBg: "", bodyColor: "", bodyFont: "" } },
+      nodeCount: i, keyframes: [],
+    },
+    root,
+  };
+}
+
+/** A content band with a heading (so section naming has honest evidence). Bands get
+ *  `variant` extra paragraphs so adjacent one-off sections differ structurally — the
+ *  repeated-run filter (≥3 identical signatures → component cluster) must not fire. */
+function band(y: number, height: number, heading: string, variant = 0): IRNode {
+  const extras: IRNode[] = [];
+  for (let k = 0; k <= variant % 7; k++) {
+    extras.push(el("p", { y: y + 80 + k * 30, height: 24, x: 120, width: 600 }, [text(`Body copy ${k}`)]));
+  }
+  return el("section", { y, height }, [
+    el("h2", { y: y + 24, height: 40, x: 120, width: 600 }, [text(heading)]),
+    ...extras,
+  ]);
+}
+
+/** navbar(62) + hero(800) + 3 bands + footer(400), flat under body. */
+function sixBandPage(): IR {
+  const nav = el("nav", { y: 0, height: 62 });
+  const hero = el("section", { y: 62, height: 800 }, [
+    el("h1", { y: 120, height: 60, x: 120, width: 900 }, [text("Ship faster with widgets")]),
+  ]);
+  const b1 = band(862, 600, "Trusted by teams", 0);
+  const b2 = band(1462, 700, "Everything you need", 1);
+  const b3 = band(2162, 500, "What customers say", 2);
+  const footer = el("footer", { y: 2662, height: 400 }, [
+    el("a", { y: 2700, height: 20, x: 120, width: 200, }, [text("Privacy")], "inline"),
+  ]);
+  return page([nav, hero, b1, b2, b3, footer], 3062);
+}
+
+/** Same bands, but body > div#root > (nav + main(13 bands) + footer) — the real-site shape. */
+function wrappedPage(bandCount = 13): IR {
+  const nav = el("nav", { y: 0, height: 62 });
+  const bandH = 900;
+  const bands: IRNode[] = [];
+  for (let k = 0; k < bandCount; k++) {
+    bands.push(k === 0
+      ? el("section", { y: 62, height: bandH }, [el("h1", { y: 100, height: 60, x: 120, width: 900 }, [text("Design your future")])])
+      : band(62 + k * bandH, bandH, `Feature area ${k}`, k));
+  }
+  const mainH = bandCount * bandH;
+  const main = el("main", { y: 62, height: mainH }, bands);
+  const footer = el("footer", { y: 62 + mainH, height: 400 });
+  const pageH = 62 + mainH + 400;
+  const wrapper = el("div", { y: 0, height: pageH }, [nav, main, footer]);
+  return page([wrapper], pageH);
+}
+
+describe("section decomposition (recursive descent)", () => {
+  it("splits navbar + hero + 3 bands + footer into 6 sections", () => {
+    const ir = sixBandPage();
+    const sections = detectSections(ir);
+    assert.equal(sections.length, 6);
+    assert.equal(sections[0]!.role, "navbar");
+    assert.equal(sections[1]!.role, "hero");
+    assert.equal(sections[5]!.role, "footer");
+    // the 62px navbar (below the old 64px bar) is still the navbar
+    assert.equal(sections[0]!.bboxByVp[CW]!.height, 62);
+  });
+
+  it("descends body > div > main wrappers to the real bands", () => {
+    const ir = wrappedPage(13);
+    const sections = detectSections(ir);
+    assert.equal(sections.length, 15); // nav + 13 bands + footer
+    assert.equal(sections[0]!.role, "navbar");
+    assert.equal(sections[1]!.role, "hero");
+    assert.equal(sections[14]!.role, "footer");
+    // no wrapper survives as a section
+    const tags = new Set(detectSectionNodes(ir).map((n) => n.tag));
+    assert.ok(!tags.has("main") && !tags.has("body") && !tags.has("div"));
+  });
+
+  it("sections tile the page top-to-bottom without gaps or overlaps", () => {
+    const ir = wrappedPage(13);
+    const boxes = detectSections(ir).map((s) => s.bboxByVp[CW]!).sort((a, b) => a.y - b.y);
+    const pageH = ir.doc.perViewport[CW]!.scrollHeight;
+    let cursor = 0;
+    for (const b of boxes) {
+      assert.ok(Math.abs(b.y - cursor) <= 8, `gap/overlap at y=${b.y} (expected ~${cursor})`);
+      cursor = b.y + b.height;
+    }
+    assert.ok(pageH - cursor <= 8, `uncovered tail: ${pageH - cursor}px`);
+  });
+
+  it("keeps a single-band page as one section (degenerate stays legal)", () => {
+    const inner = el("div", { y: 100, height: 300, x: 320, width: 640 });
+    const only = el("div", { y: 0, height: 800 }, [inner]);
+    const ir = page([only], 800);
+    const sections = detectSections(ir);
+    assert.equal(sections.length, 1);
+  });
+
+  it("does not split side-by-side columns or overlaid layers", () => {
+    // two full-width overlapping layers inside a page-covering wrapper
+    const a = el("div", { y: 100, height: 1900 });
+    const b = el("div", { y: 100, height: 1900 });
+    const wrapper = el("div", { y: 100, height: 1900 }, [a, b]);
+    const nav = el("nav", { y: 0, height: 100 });
+    const ir = page([nav, wrapper], 2000);
+    const sections = detectSections(ir);
+    assert.equal(sections.length, 2); // nav + the wrapper, unsplit
+  });
+
+  it("does not descend when children leave large coverage gaps", () => {
+    // one small band inside a page-covering container: splitting would drop content
+    const lone = band(0, 300, "Only child");
+    const container = el("div", { y: 0, height: 2000 }, [lone]);
+    const ir = page([container], 2000);
+    assert.equal(detectSections(ir).length, 1);
+  });
+
+  it("keeps a 62px fixed div-wrapped navbar as its own band (nav evidence beats the 64px bar)", () => {
+    // real-site shape: hero at y=0, a thin fixed bar (styled div, real <nav> nested
+    // narrow inside) floating over it
+    const navInner = el("nav", { y: 12, height: 62, x: 700, width: 454 });
+    const bar = el("div", { y: 12, height: 62 }, [el("div", { y: 12, height: 62 }, [navInner])]);
+    const hero = el("section", { y: 0, height: 800 }, [
+      el("h1", { y: 200, height: 60, x: 120, width: 900 }, [text("We recruit designers")]),
+    ]);
+    const b1 = band(800, 700, "Our mission", 1);
+    const b2 = band(1500, 900, "Services", 2);
+    const footer = el("footer", { y: 2400, height: 300 });
+    const ir = page([hero, bar, b1, b2, footer], 2700);
+    const sections = detectSections(ir);
+    assert.equal(sections.length, 5);
+    assert.equal(sections[0]!.role, "hero"); // y=0 sorts before the bar at y=12
+    assert.equal(sections[1]!.role, "navbar");
+    const names = [...planSections(ir).roots.values()];
+    assert.ok(names.includes("Navbar"), `expected Navbar in ${names.join(", ")}`);
+  });
+
+  it("is deterministic: same capture, byte-identical sections", () => {
+    const a = JSON.stringify(detectSections(wrappedPage(13)));
+    const b = JSON.stringify(detectSections(wrappedPage(13)));
+    assert.equal(a, b);
+  });
+});
+
+describe("section component planning (emission roots + names)", () => {
+  it("names one component per band: Navbar, HeroSection, content sections, Footer", () => {
+    const ir = sixBandPage();
+    const plan = planSections(ir);
+    const names = [...plan.roots.values()];
+    assert.equal(names.length, 6);
+    assert.equal(names[0], "Navbar");
+    assert.equal(names[1], "HeroSection");
+    assert.equal(names[5], "Footer");
+    assert.ok(names.includes("TrustedByTeamsSection"));
+    assert.ok(names.includes("WhatCustomersSaySection"));
+    assert.equal(new Set(names).size, 6, "names are unique");
+  });
+
+  it("plans a component per band through body > div > main wrappers", () => {
+    const plan = planSections(wrappedPage(13));
+    assert.equal(plan.roots.size, 15);
+    const names = [...plan.roots.values()];
+    assert.equal(names[0], "Navbar");
+    assert.equal(names[1], "HeroSection");
+    assert.equal(names[14], "Footer");
+  });
+
+  it("falls back to evidence names for bands without headings", () => {
+    const nav = el("nav", { y: 0, height: 62 });
+    const hero = el("section", { y: 62, height: 800 }, [
+      el("h1", { y: 120, height: 60, x: 120, width: 900 }, [text("Hello")]),
+    ]);
+    const formBand = el("section", { y: 862, height: 500 }, [
+      el("form", { y: 900, height: 200, x: 320, width: 640 }),
+    ]);
+    const mediaBand = el("section", { y: 1362, height: 500 }, [
+      el("video", { y: 1400, height: 400, x: 160, width: 960 }),
+    ]);
+    const footer = el("footer", { y: 1862, height: 300 });
+    const ir = page([nav, hero, formBand, mediaBand, footer], 2162);
+    const names = [...planSections(ir).roots.values()];
+    assert.ok(names.includes("ContactSection"), `expected ContactSection in ${names.join(", ")}`);
+    assert.ok(names.includes("MediaSection"), `expected MediaSection in ${names.join(", ")}`);
+  });
+
+  it("leaves a page with too few bands unsplit (no monolithic 'hero' misnomer)", () => {
+    const only = el("div", { y: 0, height: 800 }, [el("div", { y: 100, height: 300, x: 320, width: 640 })]);
+    const plan = planSections(page([only], 800));
+    assert.equal(plan.roots.size, 0);
+  });
+
+  it("is deterministic across runs", () => {
+    const a = JSON.stringify([...planSections(wrappedPage(13)).roots.entries()]);
+    const b = JSON.stringify([...planSections(wrappedPage(13)).roots.entries()]);
+    assert.equal(a, b);
+  });
+});

From d5a713d31ffba6e96b23dcd22102fb28d67d4deb Mon Sep 17 00:00:00 2001
From: Samraaj Bath <samraaj100@gmail.com>
Date: Fri, 3 Jul 2026 23:43:36 -0700
Subject: [PATCH 04/24] Honor sizing-probe verdicts in height emission; pin
 lottie mount heights

- heightFlows() bails when the capture probe proved a height authored-
  explicit (hAuto=false, hFill=false), so circular parent/child flow
  reasoning can no longer drop 100vh heroes to 0px; the probe verdict now
  vetoes the drop through both OR'd paths at the call site
- Space-distributing flex columns (space-between/around/evenly, center,
  flex-end) disqualify the content-driven read - the box height is load-
  bearing for the distribution
- Lottie mounts pin their captured per-viewport height like other replaced
  content, so aspect-fit runtime svgs can't inflate past the captured box
- DittoLottie forwards the placeholder's data-cid onto the runtime svg/
  canvas so the media stays addressable after the swap

240 tests pass (9 new), typecheck clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 compiler/src/generate/app.ts            |   5 +-
 compiler/src/generate/css.ts            |  43 +++++++-
 compiler/src/generate/lottie.ts         |  15 ++-
 compiler/src/generate/tailwind.ts       |   4 +-
 compiler/test/css.test.ts               | 135 +++++++++++++++++++++++-
 compiler/test/lottiePlaceholder.test.ts |  14 +++
 6 files changed, 209 insertions(+), 7 deletions(-)

diff --git a/compiler/src/generate/app.ts b/compiler/src/generate/app.ts
index 650998e..f1c936b 100644
--- a/compiler/src/generate/app.ts
+++ b/compiler/src/generate/app.ts
@@ -2539,7 +2539,10 @@ export function generateApp(input: GenerateInput, tokensCss: string): { pageTsx:
   const mode = input.humanizeMode ?? "tailwind";
   // Tailwind mode (default): translate each node's exact decls to utility classes.
   // CSS mode: dedup into shared semantic CSS classes. Both fidelity-neutral.
-  const tw = humanize && mode === "tailwind" ? buildTailwind(ir, assetMap, input.colorVar, { interaction: input.interaction, reflow: input.reflow }) : undefined;
+  // Lottie mount boxes are pinned to their captured height (replaced-like) so the runtime player's
+  // aspect-sized svg fills a definite box instead of inflating. The spec item cid IS the mount cid.
+  const lottieMounts = new Set(lottieSpec.items.map((it) => it.cid));
+  const tw = humanize && mode === "tailwind" ? buildTailwind(ir, assetMap, input.colorVar, { interaction: input.interaction, reflow: input.reflow, lottieMounts }) : undefined;
   const classMap = humanize && mode === "css" ? buildClassMap(ir, assetMap, input.colorVar, input.primitives, input.tokenResolver) : undefined;
   const cleanRecipeClass = recipeResponsiveClassCleaner(ir, input.recipeReport, { tailwind: !!tw });
   const classOf = tw ? (cid: string) => cleanRecipeClass(cid, tw.classOf.get(cid)) : classMap ? (cid: string) => classMap.classOf.get(cid) : undefined;
diff --git a/compiler/src/generate/css.ts b/compiler/src/generate/css.ts
index e63de00..0ae8a84 100644
--- a/compiler/src/generate/css.ts
+++ b/compiler/src/generate/css.ts
@@ -867,6 +867,24 @@ function aspectHeightLaw(node: IRNode, viewports: number[]): Record<number, stri
   return out;
 }
 
+/** A lottie mount box: the container the runtime player re-mounts its svg/canvas into. The player
+ * sizes that svg by the animation's aspect at the container's width, so without a pinned height the
+ * mount inflates to the aspect height (overlapping neighbours). Treat it as replaced-like — pin the
+ * captured per-viewport border-box height (the source-constrained size) so the aspect-fit svg fills
+ * a definite box. Per viewport, like img/video height emission. */
+function lottieMountHeight(node: IRNode, viewports: number[]): Record<number, string> | null {
+  const out: Record<number, string> = {};
+  let any = false;
+  for (const vp of viewports) {
+    const nb = node.bboxByVp[vp];
+    if (!nb || !node.visibleByVp[vp] || (node.computedByVp[vp]?.display || "") === "none") continue;
+    if (!(nb.height > 0)) continue;
+    out[vp] = fmtPx(nb.height);
+    any = true;
+  }
+  return any ? out : null;
+}
+
 function mediaHeightGeometry(node: IRNode, viewports: number[]): Pick<GeometryPlan, "heightByVp" | "aspectByVp"> {
   const heightByVp = viewportHeightLaw(node, viewports);
   if (heightByVp) return { heightByVp };
@@ -1980,6 +1998,24 @@ function heightFlows(node: IRNode, parentNode: IRNode | undefined, viewports: nu
     if (pos !== "static" && pos !== "relative") return false;
     if ((cs.overflowY || cs.overflow || "visible") !== "visible") return false;
     if ((cs.display || "") === "none") continue;
+    // The sizing probe proved this height AUTHORED-EXPLICIT: height:auto did NOT reproduce the box
+    // (hAuto:false) and the box is not a fill child of its own parent (hFill:false). The measured
+    // px is then load-bearing — dropping it collapses the box. This overrides the structural flow
+    // reasoning below, which can read the height as content-driven via a CIRCULAR pair (two nested
+    // authored-height boxes each "explaining" the other's extent) and drop both. Bail so the
+    // authored height survives. (heightProbeDrops, OR'd with this at the call site, also refuses to
+    // drop an hAuto:false box — so the two signals agree and the authored px is kept.)
+    const sz = node.sizingByVp?.[vp];
+    if (sz && sz.hAuto === false && sz.hFill === false) return false;
+    // A flex COLUMN that DISTRIBUTES free space (justify-content space-between/around/evenly, or the
+    // packed alignments that pin the last child away from the top): the box height is LOAD-BEARING —
+    // it sets the free space the children spread through. The content-extent check below would read
+    // the last child reaching the box bottom as "content-sized", but that extent only equals the box
+    // bottom BECAUSE the distribution pushed it there. Dropping the height collapses the gaps.
+    if (/flex/.test(cs.display || "") && /column/.test(cs.flexDirection || "row") &&
+        /^(space-between|space-around|space-evenly|center|flex-end|end)$/.test(cs.justifyContent || "")) {
+      return false;
+    }
     // A flex COLUMN whose in-flow child fills it via flex-grow: the box's height is LOAD-BEARING,
     // not content-derived. The content-extent check below would read the box as content-sized — but
     // that extent IS the grown child, which only reaches the box bottom BECAUSE the box has this
@@ -3015,7 +3051,7 @@ export function keyframesCss(ir: IR, assetMap: Map<string, string>, includeNode?
  *  per-node CSS emitter (generateCss) and the semantic class-map emitter (classMap.ts).
  *  `includeNode` scopes which nodes are emitted (multi-route shared layout) while still
  *  recursing so inheritance diffing against parents stays correct. */
-export function collectNodeRules(ir: IR, assetMap: Map<string, string>, includeNode?: (id: string) => boolean, colorVar?: (value: string) => string | null, tokenResolver?: TokenResolver, reflow = false): Map<string, NodeRule> {
+export function collectNodeRules(ir: IR, assetMap: Map<string, string>, includeNode?: (id: string) => boolean, colorVar?: (value: string) => string | null, tokenResolver?: TokenResolver, reflow = false, lottieMounts?: ReadonlySet<string>): Map<string, NodeRule> {
   const bands = computeBands(ir.doc.viewports, ir.doc.canonicalViewport);
   const baseVp = ir.doc.canonicalViewport;
   const rules = new Map<string, NodeRule>();
@@ -3194,7 +3230,10 @@ export function collectNodeRules(ir: IR, assetMap: Map<string, string>, includeN
     // Large one-row media grids need a definite height/aspect law before the single `1fr` row is
     // safe. Multi-row grids are handled by the older equal-track detector.
     const singleRowsByVp = !isContents ? singleFluidGridRow(node, sampleVps) : null;
-    const mediaGeometry = singleRowsByVp ? mediaHeightGeometry(node, sampleVps) : {};
+    // A lottie mount pins its captured height (replaced-like); it wins over the flow/media laws so the
+    // runtime player's aspect-sized svg fills a definite box instead of inflating past its neighbours.
+    const lottieHeight = !isContents && lottieMounts?.has(node.id) ? lottieMountHeight(node, sampleVps) : null;
+    const mediaGeometry = lottieHeight ? { heightByVp: lottieHeight } : singleRowsByVp ? mediaHeightGeometry(node, sampleVps) : {};
     const leftClampByVp = !isContents ? centeredInsetClamp(node, cbAncestor, sampleVps, "x") : null;
     const topClampByVp = !isContents ? centeredInsetClamp(node, cbAncestor, sampleVps, "y") : null;
     const geometry: GeometryPlan = (mediaGeometry.heightByVp || mediaGeometry.aspectByVp || leftClampByVp || topClampByVp)
diff --git a/compiler/src/generate/lottie.ts b/compiler/src/generate/lottie.ts
index 233007e..45342da 100644
--- a/compiler/src/generate/lottie.ts
+++ b/compiler/src/generate/lottie.ts
@@ -154,10 +154,23 @@ export default function DittoLottie({ spec }: { spec: LottieSpec }) {
             rendererSettings: { preserveAspectRatio: "xMidYMid meet" },
           });
           // Swap only once the animation is genuinely ready: reveal the live render and remove
-          // every original child (the placeholder) so the two never stack.
+          // every original child (the placeholder) so the two never stack. Before discarding the
+          // placeholder, forward its data-cid onto the runtime-rendered svg/canvas so the media
+          // node stays addressable by cid after the swap (it would otherwise mount without one).
           const reveal = () => {
             mount.style.opacity = "1";
+            // The captured placeholder is an svg/canvas (or wraps one) carrying its own data-cid.
+            let placeholderCid: string | null = null;
+            for (const child of Array.from(el.childNodes)) {
+              if (child === mount || placeholderCid !== null || !(child instanceof Element)) continue;
+              const media = child.matches("svg, canvas") ? child : child.querySelector("svg, canvas");
+              placeholderCid = (media ?? child).getAttribute("data-cid");
+            }
             for (const child of Array.from(el.childNodes)) if (child !== mount) el.removeChild(child);
+            if (placeholderCid) {
+              const rendered = mount.querySelector("svg, canvas");
+              if (rendered) rendered.setAttribute("data-cid", placeholderCid);
+            }
             mount.style.position = "";
             mount.style.inset = "";
           };
diff --git a/compiler/src/generate/tailwind.ts b/compiler/src/generate/tailwind.ts
index 8a88904..b6b382e 100644
--- a/compiler/src/generate/tailwind.ts
+++ b/compiler/src/generate/tailwind.ts
@@ -1077,11 +1077,11 @@ function interactionUtilities(
   return { byCid, groups };
 }
 
-export function buildTailwind(ir: IR, assetMap: Map<string, string>, colorVar?: (v: string) => string | null, opts?: { interner?: ColorInterner; includeNode?: (id: string) => boolean; interaction?: InteractionCapture; reflow?: boolean }): TailwindOutput {
+export function buildTailwind(ir: IR, assetMap: Map<string, string>, colorVar?: (v: string) => string | null, opts?: { interner?: ColorInterner; includeNode?: (id: string) => boolean; interaction?: InteractionCapture; reflow?: boolean; lottieMounts?: ReadonlySet<string> }): TailwindOutput {
   // Colors tokenized (var(--…)); typography/geometry kept RAW (text-[16px] reads cleaner
   // than a token ref). The full tokenResolver is deliberately NOT passed — only colors are
   // tokenized below, so spacing/type stay as readable arbitrary values.
-  const rules = collectNodeRules(ir, assetMap, opts?.includeNode, colorVar, undefined, opts?.reflow);
+  const rules = collectNodeRules(ir, assetMap, opts?.includeNode, colorVar, undefined, opts?.reflow, opts?.lottieMounts);
   const classOf = new Map<string, string>();
   const styleOf = new Map<string, Map<string, string>>(); // cid → inline style (base-only gradients/url)
   const extraParts: string[] = []; // pseudo rules + url()-bearing decls, keyed by [data-cid]
diff --git a/compiler/test/css.test.ts b/compiler/test/css.test.ts
index 8d57ddb..ae43449 100644
--- a/compiler/test/css.test.ts
+++ b/compiler/test/css.test.ts
@@ -2,7 +2,7 @@ import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 import type { IR, IRNode, IRChild, StyleMap, BBox } from "../src/normalize/ir.js";
 import type { RawSizing } from "../src/capture/walker.js";
-import { generateCss } from "../src/generate/css.js";
+import { generateCss, collectNodeRules } from "../src/generate/css.js";
 
 const VPS = [375, 1280];
 const CANONICAL = 1280;
@@ -484,3 +484,136 @@ describe("generateCss cross-band transform identity", () => {
     assert.ok(!allRulesX(css, "n1").includes("transform:none"), `an always-identity node needs no explicit transform, got: ${allRulesX(css, "n1")}`);
   });
 });
+
+// BUG 1 — heightFlows must consult the sizing probe. A circular parent/child pair of authored-height
+// boxes (two nested viewport-height containers whose only children are absolutely positioned) used to
+// "explain each other away": the outer read content-driven (its content IS the inner box) and the
+// inner read stretched (it equals the outer's content height) — both dropped, collapsing a hero to
+// 0px. The probe now proves each height authored-explicit (hAuto:false, hFill:false); heightFlows
+// bails so both survive.
+describe("generateCss circular authored-height (probe bail)", () => {
+  const authored = (): RawSizing => ({ wAuto: false, wFill: false, hAuto: false, hFill: false });
+  function hero(hByVp: Record<number, number>) {
+    // an absolutely-positioned decoration inside the inner box (contributes no in-flow content height)
+    const abs = xNode("n3", "div", {
+      375: { cs: { position: "absolute" }, bbox: { x: 0, y: 0, width: 375, height: hByVp[375]! } },
+      768: { cs: { position: "absolute" }, bbox: { x: 0, y: 0, width: 768, height: hByVp[768]! } },
+      1280: { cs: { position: "absolute" }, bbox: { x: 0, y: 0, width: 1280, height: hByVp[1280]! } },
+    });
+    const inner = xNode("n2", "div", {
+      375: { cs: { display: "flex", height: `${hByVp[375]}px` }, bbox: { x: 0, y: 0, width: 375, height: hByVp[375]! }, sizing: authored() },
+      768: { cs: { display: "flex", height: `${hByVp[768]}px` }, bbox: { x: 0, y: 0, width: 768, height: hByVp[768]! }, sizing: authored() },
+      1280: { cs: { display: "flex", height: `${hByVp[1280]}px` }, bbox: { x: 0, y: 0, width: 1280, height: hByVp[1280]! }, sizing: authored() },
+    }, [abs]);
+    const outer = xNode("n1", "div", {
+      375: { cs: { display: "flex", height: `${hByVp[375]}px` }, bbox: { x: 0, y: 0, width: 375, height: hByVp[375]! }, sizing: authored() },
+      768: { cs: { display: "flex", height: `${hByVp[768]}px` }, bbox: { x: 0, y: 0, width: 768, height: hByVp[768]! }, sizing: authored() },
+      1280: { cs: { display: "flex", height: `${hByVp[1280]}px` }, bbox: { x: 0, y: 0, width: 1280, height: hByVp[1280]! }, sizing: authored() },
+    }, [inner]);
+    return xNode("n0", "body", {
+      375: { bbox: { x: 0, y: 0, width: 375, height: hByVp[375]! } },
+      768: { bbox: { x: 0, y: 0, width: 768, height: hByVp[768]! } },
+      1280: { bbox: { x: 0, y: 0, width: 1280, height: hByVp[1280]! } },
+    }, [outer]);
+  }
+
+  it("keeps both heights when the probe proves them authored-explicit", () => {
+    const css = generateCss(xIr(hero({ 375: 771, 768: 900, 1280: 800 })), new Map());
+    const outer = allRulesX(css, "n1");
+    const inner = allRulesX(css, "n2");
+    assert.ok(/height:800px/.test(outer), `outer must keep its canonical authored height, got: ${outer}`);
+    assert.ok(/height:800px/.test(inner), `inner must keep its canonical authored height, got: ${inner}`);
+  });
+
+  it("still flows a genuinely content-sized varying height (probe hAuto:true)", () => {
+    // Same shape but the probe says auto reproduces the box — the varying height is real content, safe
+    // to drop. Give it an in-flow text child so it reads content-driven.
+    const auto = (): RawSizing => ({ wAuto: true, wFill: false, hAuto: true, hFill: false });
+    const mk = (h: number, w: number): XPerVp => ({ cs: { display: "block", height: `${h}px` }, bbox: { x: 0, y: 0, width: w, height: h }, sizing: auto() });
+    const inner = xNode("n2", "div", { 375: mk(200, 375), 768: mk(260, 768), 1280: mk(320, 1280) }, [{ text: "flowing content" } as IRChild]);
+    // pad the box so height == content is plausible per contentDriven's text branch
+    const root = xNode("n0", "body", { 375: { bbox: { x: 0, y: 0, width: 375, height: 200 } }, 768: { bbox: { x: 0, y: 0, width: 768, height: 260 } }, 1280: { bbox: { x: 0, y: 0, width: 1280, height: 320 } } }, [inner]);
+    const css = generateCss(xIr(root), new Map());
+    assert.ok(!/height:320px/.test(allRulesX(css, "n2")), `a probe-auto content height should still flow, got: ${allRulesX(css, "n2")}`);
+  });
+});
+
+// BUG 2 — a space-distributing flex column (justify-content: space-between/around/evenly, or a packed
+// center/flex-end) sets the free space its children spread through, so the last child reaching the box
+// bottom is NOT content evidence. heightFlows used to read that as content-driven and drop the box's
+// authored height, collapsing the distributed gaps.
+describe("generateCss space-distributing flex column keeps its height", () => {
+  // hAuto:true (auto reproduces the box at capture, because distribution places the last child at the
+  // bottom) — so the sizing probe does NOT forbid the drop. Wrappable text inside makes heightProbeDrops
+  // abstain, isolating heightFlows' space-distribution disqualification as the sole arbiter.
+  const auto = (): RawSizing => ({ wAuto: true, wFill: false, hAuto: true, hFill: false });
+  const textChild = { text: "a line of distributed content" } as IRChild;
+  function distributed(justify: string) {
+    // two content-sized blocks; the last sits at the box bottom because the column distributes space
+    const top = xNode("n2", "div", {
+      375: { cs: { display: "block" }, bbox: { x: 0, y: 0, width: 375, height: 40 } },
+      768: { cs: { display: "block" }, bbox: { x: 0, y: 0, width: 768, height: 40 } },
+      1280: { cs: { display: "block" }, bbox: { x: 0, y: 0, width: 1280, height: 40 } },
+    }, [textChild]);
+    const bottomH = (h: number): XPerVp => ({ cs: { display: "block" }, bbox: { x: 0, y: h - 40, width: 375, height: 40 } });
+    const bot = xNode("n3", "div", { 375: bottomH(360), 768: bottomH(500), 1280: bottomH(600) }, [textChild]);
+    const col = xNode("n1", "div", {
+      375: { cs: { display: "flex", flexDirection: "column", justifyContent: justify, height: "360px" }, bbox: { x: 0, y: 0, width: 375, height: 360 }, sizing: auto() },
+      768: { cs: { display: "flex", flexDirection: "column", justifyContent: justify, height: "500px" }, bbox: { x: 0, y: 0, width: 768, height: 500 }, sizing: auto() },
+      1280: { cs: { display: "flex", flexDirection: "column", justifyContent: justify, height: "600px" }, bbox: { x: 0, y: 0, width: 1280, height: 600 }, sizing: auto() },
+    }, [top, bot]);
+    return xNode("n0", "body", { 375: { bbox: { x: 0, y: 0, width: 375, height: 360 } }, 768: { bbox: { x: 0, y: 0, width: 768, height: 500 } }, 1280: { bbox: { x: 0, y: 0, width: 1280, height: 600 } } }, [col]);
+  }
+
+  for (const j of ["space-between", "space-around", "space-evenly"]) {
+    it(`keeps the authored height under justify-content:${j}`, () => {
+      const css = generateCss(xIr(distributed(j)), new Map());
+      assert.ok(/height:600px/.test(allRulesX(css, "n1")), `${j} column must keep its distributing height, got: ${allRulesX(css, "n1")}`);
+    });
+  }
+
+  it("still flows a flex-start column whose height truly equals its content", () => {
+    // justify-content:flex-start (default) — the last child at the bottom IS content-driven, so the
+    // varying height flows (drops) as before.
+    const css = generateCss(xIr(distributed("flex-start")), new Map());
+    assert.ok(!/height:600px/.test(allRulesX(css, "n1")), `a packed-top column should still flow, got: ${allRulesX(css, "n1")}`);
+  });
+});
+
+// BUG 3 — a lottie mount pins its captured per-viewport height so the runtime player's aspect-sized
+// svg fills a definite box instead of inflating past its neighbours. Threaded via collectNodeRules'
+// lottieMounts set (populated from the lottie spec item cids).
+describe("collectNodeRules lottie mount height pin", () => {
+  const auto = (): RawSizing => ({ wAuto: true, wFill: false, hAuto: true, hFill: false });
+  function mountFixture() {
+    // the mount is a flex box; its only child is a content-sized placeholder svg — without the pin the
+    // box height flows/collapses and the runtime svg inflates by aspect.
+    const svg = xNode("n2", "svg", {
+      375: { cs: { display: "block" }, bbox: { x: 0, y: 0, width: 375, height: 94 } },
+      768: { cs: { display: "block" }, bbox: { x: 0, y: 0, width: 768, height: 195 } },
+      1280: { cs: { display: "block" }, bbox: { x: 0, y: 0, width: 1280, height: 227 } },
+    });
+    const mount = xNode("n1", "div", {
+      375: { cs: { display: "flex", height: "94px" }, bbox: { x: 0, y: 0, width: 375, height: 94 }, sizing: auto() },
+      768: { cs: { display: "flex", height: "195px" }, bbox: { x: 0, y: 0, width: 768, height: 195 }, sizing: auto() },
+      1280: { cs: { display: "flex", height: "227px" }, bbox: { x: 0, y: 0, width: 1280, height: 227 }, sizing: auto() },
+    }, [svg]);
+    return xNode("n0", "body", { 375: { bbox: { x: 0, y: 0, width: 375, height: 94 } }, 768: { bbox: { x: 0, y: 0, width: 768, height: 195 } }, 1280: { bbox: { x: 0, y: 0, width: 1280, height: 227 } } }, [mount]);
+  }
+
+  it("pins the captured height on a mount node", () => {
+    const rules = collectNodeRules(xIr(mountFixture()), new Map(), undefined, undefined, undefined, false, new Set(["n1"]));
+    const nr = rules.get("n1");
+    assert.ok(nr, "mount rule must exist");
+    const all = [nr!.base.get("height"), ...nr!.bands.map((b) => b.decls.get("height"))].filter(Boolean).join(";");
+    assert.ok(/227px/.test(all), `canonical mount height must be pinned, got: ${all}`);
+    assert.ok(/94px/.test(all), `narrow-band mount height must be pinned, got: ${all}`);
+  });
+
+  it("leaves a non-mount box unpinned (flows its varying content height)", () => {
+    const rules = collectNodeRules(xIr(mountFixture()), new Map(), undefined, undefined, undefined, false, new Set());
+    const nr = rules.get("n1")!;
+    const all = [nr.base.get("height"), ...nr.bands.map((b) => b.decls.get("height"))].filter(Boolean).join(";");
+    assert.ok(!/227px/.test(all), `without the mount flag the varying height should flow, got: ${all}`);
+  });
+});
diff --git a/compiler/test/lottiePlaceholder.test.ts b/compiler/test/lottiePlaceholder.test.ts
index c220df5..9cb6f2b 100644
--- a/compiler/test/lottiePlaceholder.test.ts
+++ b/compiler/test/lottiePlaceholder.test.ts
@@ -36,6 +36,20 @@ describe("DittoLottie placeholder retention", () => {
   it("handles a failed load without leaving a broken mount stacked over the placeholder", () => {
     assert.match(DITTO_LOTTIE_TSX, /data_failed/);
   });
+
+  // The player creates its <svg>/<canvas> at runtime WITHOUT a data-cid, so the DOM/media gate can't
+  // map it back to the captured node. The reveal must forward the discarded placeholder's data-cid
+  // onto the runtime-rendered element (validation-agnostic; no gate special-casing).
+  it("forwards the placeholder's data-cid onto the runtime-rendered svg/canvas before the swap", () => {
+    // reads the placeholder cid, then reassigns it to the rendered svg/canvas inside the mount
+    assert.match(DITTO_LOTTIE_TSX, /getAttribute\(\s*["']data-cid["']\s*\)/);
+    assert.match(DITTO_LOTTIE_TSX, /mount\.querySelector\(\s*["']svg,\s*canvas["']\s*\)/);
+    assert.match(DITTO_LOTTIE_TSX, /setAttribute\(\s*["']data-cid["']\s*,/);
+    // the cid capture must precede its removal so the placeholder is still in the DOM when read
+    const readIdx = DITTO_LOTTIE_TSX.indexOf('getAttribute("data-cid")');
+    const removeIdx = DITTO_LOTTIE_TSX.indexOf("removeChild");
+    assert.ok(readIdx >= 0 && removeIdx >= 0 && readIdx < removeIdx, "must read the placeholder cid before removing it");
+  });
 });
 
 describe("identity-transform canonicalization (isIdentityTransform)", () => {

From e33354cfb525780dd4e640d1f1a12266db754f6a Mon Sep 17 00:00:00 2001
From: Samraaj Bath <samraaj100@gmail.com>
Date: Sat, 4 Jul 2026 00:18:56 -0700
Subject: [PATCH 05/24] Neutralize animation-owned transforms across viewports;
 probe-veto flex auto-width conversion

- Nodes carrying an infinite CSS animation at ANY viewport get their frozen
  mid-animation transform zeroed at EVERY viewport (the @keyframes owns the
  property at runtime); animOwnedProps is now viewport-aware so breakpoint-
  gated marquees can't bake a mid-scroll translateX into other bands
- contentSizedFlexRow/contentSizedFlexItemAuto honor the sizing probe: a
  flex item whose captured width the probe proved load-bearing
  (wAuto=false) is never converted to width:auto, preserving narrow
  centered text columns

247 tests pass (7 new), typecheck clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 compiler/src/generate/css.ts  | 44 ++++++++++++++++---
 compiler/src/normalize/ir.ts  | 33 +++++++++++++++
 compiler/test/css.test.ts     | 79 +++++++++++++++++++++++++++++++++++
 compiler/test/irPrune.test.ts | 40 +++++++++++++++++-
 4 files changed, 189 insertions(+), 7 deletions(-)

diff --git a/compiler/src/generate/css.ts b/compiler/src/generate/css.ts
index 0ae8a84..6cf25c7 100644
--- a/compiler/src/generate/css.ts
+++ b/compiler/src/generate/css.ts
@@ -1540,6 +1540,18 @@ function contentSizedFlexRow(container: IRNode, viewports: number[]): Set<string
   for (const vp of viewports) for (const it of items) {
     const cs = it.computedByVp[vp]; if (cs && pf(cs.flexGrow) > 0) return null;
   }
+  // The sizing probe is ground truth: if it proved `width:auto` does NOT reproduce an item's width at
+  // any painted viewport (`wAuto:false`), that item is load-bearing and cannot be dropped. Because this
+  // rule is all-or-nothing per line (dropping a subset shifts siblings via justify-content), one such
+  // item vetoes the whole line. This catches a wrapping-text item — e.g. a paragraph in a
+  // `justify-content:flex-end` row paints at its balanced-wrap width (below max-content), but
+  // `width:auto` on the block child fills the line to max-content — which the geometric slack test
+  // alone (no shrink fired) would wrongly convert to auto.
+  for (const it of items) {
+    for (const vp of viewports) {
+      if (it.sizingByVp?.[vp]?.wAuto === false) return null;
+    }
+  }
   // At every width: the visible items + gaps + margins must not overflow the container (slack ≥ 0).
   for (const vp of viewports) {
     const pcs = container.computedByVp[vp]; const pb = container.bboxByVp[vp];
@@ -1923,6 +1935,12 @@ function contentSizedFlexItemAuto(node: IRNode, parentNode: IRNode | undefined,
     const cs = node.computedByVp[vp]; const pcs = parentNode.computedByVp[vp];
     const nb = node.bboxByVp[vp]; const pb = parentNode.bboxByVp[vp];
     if (!cs || !pcs || !nb || !pb || !node.visibleByVp[vp] || (cs.display || "") === "none") continue;
+    // The sizing probe is ground truth: if it proved `width:auto` does NOT reproduce the captured
+    // width at any painted viewport (`wAuto:false`), the geometric "never shrank ⇒ at content size"
+    // read below is wrong — e.g. a wrapping paragraph in a `justify-content:flex-end` row paints at
+    // its balanced-wrap width (below max-content), but `width:auto` on the block child fills the line
+    // to max-content and left-aligns it. Honor the probe over the heuristic.
+    if (node.sizingByVp?.[vp]?.wAuto === false) return false;
     if (!/^(flex|inline-flex)$/.test(pcs.display || "")) return false;
     const dir = pcs.flexDirection || "row";
     if (dir !== "row" && dir !== "row-reverse") return false;        // width = main axis only for rows
@@ -2218,11 +2236,22 @@ function confersDefiniteHeight(node: IRNode, parentNode: IRNode | undefined, got
  *  change. transform-origin follows transform (skipped when no transform varies). */
 const ANIM_OWNED = new Set(["opacity", "transform"]);
 const EMPTY_SET = new Set<string>();
-function animOwnedProps(node: IRNode, baseVp: number): Set<string> {
-  const cs = node.computedByVp[baseVp];
-  if (!cs || (cs.animationName || "none") === "none") return EMPTY_SET;
-  if (!/infinite/.test(cs.animationIterationCount || "1")) return EMPTY_SET;
-  return ANIM_OWNED;
+/** True when an INFINITE CSS animation is active on the node at this viewport (so it perpetually
+ *  drives opacity/transform — the captured value is a frozen animation phase, not design). */
+function hasInfiniteAnim(cs: StyleMap | undefined): boolean {
+  if (!cs || (cs.animationName || "none") === "none") return false;
+  return /infinite/.test(cs.animationIterationCount || "1");
+}
+/** Properties an infinite animation owns (so their per-viewport captured values are frozen phase
+ *  noise to suppress). Sampled across ALL emitted viewports, not just the base: a CSS marquee that
+ *  runs only below a breakpoint (Webflow's `max-lg` logo/text tracks) is `animation:none` at the
+ *  base (desktop) width but still freezes a random `translateX` at the mobile/tablet bands — banding
+ *  those bakes a mid-scroll offset that shifts content offscreen at rest. When the animation owns the
+ *  transform at ANY width, the frozen per-band deltas are dropped everywhere and the base value holds
+ *  (the runtime `@keyframes` starts at translateX(0), so the strip renders aligned until it animates). */
+function animOwnedProps(node: IRNode, viewports: number[]): Set<string> {
+  for (const vp of viewports) if (hasInfiniteAnim(node.computedByVp[vp])) return ANIM_OWNED;
+  return EMPTY_SET;
 }
 
 
@@ -3292,7 +3321,10 @@ export function collectNodeRules(ir: IR, assetMap: Map<string, string>, includeN
       dropInsets.delete("bottom");
       dropInsets.delete("left");
     }
-    const animOwned = animOwnedProps(node, baseVp); // opacity/transform driven by an infinite animation
+    // opacity/transform driven by an infinite animation at the base OR any emitted band (a marquee
+    // gated to a breakpoint owns the transform only where it runs, but freezes a mid-scroll offset
+    // at the OTHER bands — suppress those frozen deltas at every width).
+    const animOwned = animOwnedProps(node, [baseVp, ...bands.map((b) => b.vp)]);
     const baseDecls = finalizeDecls(declsForViewport(node, parentNode?.computedByVp[baseVp], baseVp, assetMap, centeredBase, colorVar, ir.doc.perViewport[baseVp]?.scrollHeight, widthPlan, gridColsByVp?.get(baseVp), gridRowsByVp?.get(baseVp), flowH, dropInsets, leftPct, heightFill, geometry, dropGridRows, dropViewportMaxWidth, nowrapText, keepIdentityTransform), tokenResolver);
     const nr: NodeRule = { base: baseDecls, bands: [] };
 
diff --git a/compiler/src/normalize/ir.ts b/compiler/src/normalize/ir.ts
index 7b5b485..a85cd25 100644
--- a/compiler/src/normalize/ir.ts
+++ b/compiler/src/normalize/ir.ts
@@ -226,6 +226,35 @@ export function canonicalizeTransforms(computedByVp: Record<number, StyleMap>):
   }
 }
 
+/** True when an INFINITE CSS animation is active at this viewport. Such an animation perpetually
+ *  drives its animated properties (opacity/transform), so the captured value is a frozen phase of
+ *  the loop, not authored design. */
+function hasInfiniteAnimation(cs: StyleMap | undefined): boolean {
+  if (!cs || (cs.animationName || "none") === "none") return false;
+  return /infinite/.test(cs.animationIterationCount || "1");
+}
+
+/**
+ * Neutralize the transform of a node that carries an INFINITE animation at ANY captured viewport.
+ * The capture shutter froze the marquee/spinner mid-loop, and — critically — a CSS animation gated
+ * to a breakpoint (Webflow's `max-lg` logo/big-text tracks) reads `animation:none` at the widths
+ * where it does NOT run, yet the browser still reports the last frozen `translateX` there. Banding
+ * those frozen values bakes a mid-scroll offset that shifts content offscreen-left AT REST (rows
+ * starting mid-glyph). The runtime `@keyframes` owns the transform and starts at translateX(0), so
+ * the faithful at-rest value is `none` at every width; generation's `animOwnedProps` then keeps the
+ * base holding while the animation drives it live. Only fires when a genuine infinite animation is
+ * present at some viewport — a statically-offset design element (no animation) is untouched.
+ * Deterministic, in place; only touches the `transform` slot.
+ */
+export function neutralizeAnimatedTransforms(computedByVp: Record<number, StyleMap>): void {
+  const vps = Object.keys(computedByVp).map(Number);
+  if (!vps.some((vp) => hasInfiniteAnimation(computedByVp[vp]))) return;
+  for (const vp of vps) {
+    const cs = computedByVp[vp];
+    if (cs && cs.transform && cs.transform !== "none") cs.transform = "none";
+  }
+}
+
 /** Full identity signature (tag + id + class). */
 function sigFull(n: RawNode): string {
   return `${n.tag}#${n.attrs?.id ?? ""}.${(n.attrs?.class ?? "").trim()}`;
@@ -370,6 +399,10 @@ export function buildIR(sourceDir: string, viewports: number[], opts?: { motion?
     // the generator's per-band delta treats them uniformly and a scroll/composite-noise transform
     // at one width can't leak across bands.
     canonicalizeTransforms(computedByVp);
+    // Drop transforms frozen mid-loop by an infinite animation (marquees/spinners) at every viewport —
+    // including the breakpoints where the animation is gated off but the browser still reports the last
+    // frozen offset. Prevents a baked mid-scroll translateX from clipping content offscreen at rest.
+    neutralizeAnimatedTransforms(computedByVp);
 
     const node: IRNode = {
       id: nextId(),
diff --git a/compiler/test/css.test.ts b/compiler/test/css.test.ts
index ae43449..63c4448 100644
--- a/compiler/test/css.test.ts
+++ b/compiler/test/css.test.ts
@@ -617,3 +617,82 @@ describe("collectNodeRules lottie mount height pin", () => {
     assert.ok(!/227px/.test(all), `without the mount flag the varying height should flow, got: ${all}`);
   });
 });
+
+// Defect E — a content-sized flex ROW's items are dropped to `width:auto` only when NO shrink fired
+// (positive slack ⇒ items at content size). But a WRAPPING text leaf paints at its balanced-wrap
+// width, which is BELOW its max-content: `width:auto` on the block child fills the line to
+// max-content and left-aligns it, so the narrow right-pushed paragraph blows out to full-width. The
+// sizing probe already read `wAuto:false` (auto does NOT reproduce the width); it must veto the
+// whole line (the rule is all-or-nothing — dropping a subset shifts siblings via justify-content).
+describe("generateCss content-sized flex row (probe veto for wrapping text)", () => {
+  // One <p> child, sole item of a `flex; justify-content:flex-end` row, `flex:0 1 auto`, that paints
+  // narrower than the container at every width (wraps below max-content) with positive slack.
+  function missionRow(pSizing: RawSizing) {
+    const p = xNode("n1", "p", {
+      375: { cs: { display: "block", flexGrow: "0", flexShrink: "1", flexBasis: "auto", width: "276px" }, bbox: { x: 69, y: 0, width: 276, height: 80 }, sizing: pSizing },
+      768: { cs: { display: "block", flexGrow: "0", flexShrink: "1", flexBasis: "auto", width: "529.922px" }, bbox: { x: 176, y: 0, width: 529.92, height: 60 }, sizing: pSizing },
+      1280: { cs: { display: "block", flexGrow: "0", flexShrink: "1", flexBasis: "auto", width: "774.141px" }, bbox: { x: 455, y: 0, width: 774.14, height: 40 }, sizing: pSizing },
+    }, [{ text: "Our UX staffing and recruiting teams place the best talent from around the world." }]);
+    return xNode("n0", "body", {
+      375: { cs: { display: "flex", flexDirection: "row", justifyContent: "flex-end" }, bbox: { x: 0, y: 0, width: 375, height: 80 } },
+      768: { cs: { display: "flex", flexDirection: "row", justifyContent: "flex-end" }, bbox: { x: 0, y: 0, width: 706.56, height: 60 } },
+      1280: { cs: { display: "flex", flexDirection: "row", justifyContent: "flex-end" }, bbox: { x: 0, y: 0, width: 1228.81, height: 40 } },
+    }, [p]);
+  }
+
+  it("keeps a width on a wrapping paragraph the probe proved is not auto-reproducible", () => {
+    // Probe ground truth: width:auto does NOT reproduce (wAuto:false) — the painted width is the
+    // balanced-wrap width, below max-content (wMax).
+    const notAuto = (): RawSizing => ({ wAuto: false, wFill: false, hAuto: true, hFill: false, wMin: 95.88, wMax: 706.56 });
+    const css = generateCss(xIr(missionRow(notAuto())), new Map());
+    const all = allRulesX(css, "n1");
+    // It must NOT be emitted as content-auto (which drops width entirely and fills the line). The
+    // width plan falls to a real width — a fluid percentage or baked px — so the narrow column survives.
+    assert.ok(/width:/.test(all), `wrapping paragraph must keep a width, not collapse to auto, got: ${all}`);
+    assert.ok(!/width:auto/.test(all), `probe said wAuto:false — must not emit width:auto, got: ${all}`);
+  });
+
+  it("still drops width:auto on a genuinely content-sized row item the probe confirms", () => {
+    // Probe agrees width:auto reproduces (wAuto:true) — a toolbar/menu item whose width is its
+    // content. The content-sized-flex-row law should still fire and emit auto (no baked px band).
+    const isAuto = (): RawSizing => ({ wAuto: true, wFill: false, hAuto: true, hFill: false, wMin: 95.88, wMax: 706.56 });
+    const css = generateCss(xIr(missionRow(isAuto())), new Map());
+    const all = allRulesX(css, "n1");
+    assert.ok(!/width:\d/.test(all), `content-sized item must drop its baked px width, got: ${all}`);
+  });
+});
+
+// Defect C (generate side) — a CSS marquee (infinite `@keyframes` animation) gated to a breakpoint
+// (Webflow's `max-lg` logo/text tracks) is `animation:none` at the base but runs at the narrow band.
+// The per-band transform delta at the animated width is a FROZEN mid-scroll phase; it must be
+// suppressed so the base holds and the runtime keyframes drive the transform (from translateX(0)).
+// (The upstream normalize pass zeroes the base residue — see neutralizeAnimatedTransforms; here the
+// base is already `none`, and this test covers the band-delta suppression.)
+describe("generateCss breakpoint-gated marquee transform band suppression (Defect C)", () => {
+  function logoStrip() {
+    const strip = xNode("n1", "div", {
+      375: { cs: { display: "grid", animationName: "track", animationIterationCount: "infinite", animationDuration: "35s", transform: "matrix(1, 0, 0, 1, -284.025, 0)" }, bbox: { x: 0, y: 0, width: 345, height: 100 } },
+      768: { cs: { display: "grid", animationName: "track", animationIterationCount: "infinite", animationDuration: "35s", transform: "matrix(1, 0, 0, 1, -280.982, 0)" }, bbox: { x: 0, y: 0, width: 706, height: 100 } },
+      1280: { cs: { display: "grid", animationName: "none", animationIterationCount: "1", transform: "none" }, bbox: { x: 0, y: 0, width: 1228, height: 145 } },
+    });
+    return xNode("n0", "body", { 375: { bbox: { x: 0, y: 0, width: 375, height: 100 } }, 768: { bbox: { x: 0, y: 0, width: 768, height: 100 } }, 1280: { bbox: { x: 0, y: 0, width: 1280, height: 145 } } }, [strip]);
+  }
+
+  it("does not bake the frozen mid-scroll translateX at the animated band", () => {
+    const css = generateCss(xIr(logoStrip()), new Map());
+    const all = allRulesX(css, "n1");
+    assert.ok(!/matrix\(1, ?0, ?0, ?1, ?-\d/.test(all), `frozen marquee translateX must not be emitted at any band, got: ${all}`);
+  });
+
+  it("keeps a per-band transform of a NON-animated element", () => {
+    // A non-animated element whose transform genuinely varies per band keeps it (no animation owns it).
+    const el = xNode("n1", "div", {
+      375: { cs: { transform: "matrix(1, 0, 0, 1, -40, 0)" }, bbox: { x: -40, y: 0, width: 345, height: 100 } },
+      768: { cs: { transform: "none" }, bbox: { x: 0, y: 0, width: 706, height: 100 } },
+      1280: { cs: { transform: "none" }, bbox: { x: 0, y: 0, width: 1228, height: 100 } },
+    });
+    const root = xNode("n0", "body", { 375: { bbox: { x: 0, y: 0, width: 375, height: 100 } }, 768: { bbox: { x: 0, y: 0, width: 768, height: 100 } }, 1280: { bbox: { x: 0, y: 0, width: 1280, height: 100 } } }, [el]);
+    const css = generateCss(xIr(root), new Map());
+    assert.ok(/matrix\(1, ?0, ?0, ?1, ?-40/.test(allRulesX(css, "n1")), `a non-animated per-band offset must be kept, got: ${allRulesX(css, "n1")}`);
+  });
+});
diff --git a/compiler/test/irPrune.test.ts b/compiler/test/irPrune.test.ts
index 167d7f1..22a8942 100644
--- a/compiler/test/irPrune.test.ts
+++ b/compiler/test/irPrune.test.ts
@@ -4,7 +4,7 @@ import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { RawNode, RawChild } from "../src/capture/walker.js";
-import { buildIR, isTextChild, type IRNode } from "../src/normalize/ir.js";
+import { buildIR, isTextChild, neutralizeAnimatedTransforms, type IRNode } from "../src/normalize/ir.js";
 
 const VPS = [375, 1280];
 
@@ -116,3 +116,41 @@ describe("IR drops font-metric probe nodes (fix 4)", () => {
     assert.equal(findByTag(root, "div"), null);
   });
 });
+
+// Defect C (normalize side) — an infinite CSS animation gated to a breakpoint (a Webflow `max-lg`
+// marquee) is `animation:none` at the widths it does not run, but the browser still reports the last
+// FROZEN translateX there. `neutralizeAnimatedTransforms` zeroes the transform at EVERY viewport
+// once a genuine infinite animation is present at some width, so no frozen mid-scroll offset (the
+// base residue or the animated phases) is banded and clips the strip offscreen at rest.
+describe("neutralizeAnimatedTransforms (Defect C)", () => {
+  it("zeroes the transform at every viewport when an infinite animation runs at some width", () => {
+    const byVp = {
+      375: { animationName: "track", animationIterationCount: "infinite", transform: "matrix(1, 0, 0, 1, -284.025, 0)" } as any,
+      768: { animationName: "track", animationIterationCount: "infinite", transform: "matrix(1, 0, 0, 1, -280.982, 0)" } as any,
+      1280: { animationName: "none", animationIterationCount: "1", transform: "matrix(1, 0, 0, 1, -9.94731, 0)" } as any,
+    };
+    neutralizeAnimatedTransforms(byVp as any);
+    assert.equal(byVp[375].transform, "none");
+    assert.equal(byVp[768].transform, "none");
+    assert.equal(byVp[1280].transform, "none", "the non-animated base residue is neutralized too");
+  });
+
+  it("leaves a static transform untouched when NO viewport carries an infinite animation", () => {
+    const byVp = {
+      375: { animationName: "none", animationIterationCount: "1", transform: "matrix(1, 0, 0, 1, -40, 0)" } as any,
+      1280: { animationName: "none", animationIterationCount: "1", transform: "matrix(1, 0, 0, 1, -40, 0)" } as any,
+    };
+    neutralizeAnimatedTransforms(byVp as any);
+    assert.equal(byVp[375].transform, "matrix(1, 0, 0, 1, -40, 0)", "a deliberate static offset is preserved");
+    assert.equal(byVp[1280].transform, "matrix(1, 0, 0, 1, -40, 0)");
+  });
+
+  it("does not fire for a FINITE animation (a one-shot entrance, not a perpetual marquee)", () => {
+    const byVp = {
+      375: { animationName: "slideIn", animationIterationCount: "1", transform: "matrix(1, 0, 0, 1, -100, 0)" } as any,
+      1280: { animationName: "slideIn", animationIterationCount: "1", transform: "matrix(1, 0, 0, 1, -100, 0)" } as any,
+    };
+    neutralizeAnimatedTransforms(byVp as any);
+    assert.equal(byVp[375].transform, "matrix(1, 0, 0, 1, -100, 0)", "finite animations own a settled end state, not a perpetual phase");
+  });
+});

From 15d1e7a9e3cd884b343a95e8d71eb52157142e14 Mon Sep 17 00:00:00 2001
From: Samraaj Bath <samraaj100@gmail.com>
Date: Sat, 4 Jul 2026 00:36:08 -0700
Subject: [PATCH 06/24] Canvas raster fallback, CDP rest-state screenshots,
 lottie overlay containment

- Visible canvases (>=48px) are captured as PNG stills at capture time
  (toDataURL, element-screenshot fallback for tainted/webgl) and emitted as
  cid-carrying <img> elements filling the captured box, so canvas-driven
  bands no longer render blank
- Source AND clone full-page screenshots now capture via CDP
  Page.captureScreenshot with captureBeyondViewport: no scroll-stitching,
  no scroll events, so scroll-linked animations can't smear mid-scrub
  states into perceptual evidence (pixel-identical to the old path on
  static pages; Playwright fallback retained)
- DittoLottie's runtime overlay stays position:absolute/inset:0 for its
  whole life and the host carries data-ditto-lottie with a scoped
  svg/canvas fit rule, so the runtime animation always fills the pinned
  per-viewport box instead of escaping to aspect height

259 tests pass (12 new), typecheck clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 compiler/src/capture/capture.ts         | 148 +++++++++++++++++++++++-
 compiler/src/generate/app.ts            |  10 ++
 compiler/src/generate/css.ts            |   5 +
 compiler/src/generate/lottie.ts         |  12 +-
 compiler/src/validate/render.ts         |  12 +-
 compiler/test/canvasStill.test.ts       | 108 +++++++++++++++++
 compiler/test/cdpScreenshot.test.ts     |  84 ++++++++++++++
 compiler/test/css.test.ts               |  28 ++++-
 compiler/test/lottiePlaceholder.test.ts |  27 +++++
 9 files changed, 426 insertions(+), 8 deletions(-)
 create mode 100644 compiler/test/canvasStill.test.ts
 create mode 100644 compiler/test/cdpScreenshot.test.ts

diff --git a/compiler/src/capture/capture.ts b/compiler/src/capture/capture.ts
index a29a3c2..fc7eaa1 100644
--- a/compiler/src/capture/capture.ts
+++ b/compiler/src/capture/capture.ts
@@ -517,10 +517,102 @@ async function captureVideoStills(page: import("playwright").Page): Promise<Vide
 }
 
 /**
- * Full-page screenshot with robustness for heavy/animated pages. The default 30s
- * timeout is exceeded by tall SaaS pages (Playwright also waits for web fonts);
- * use a long timeout, freeze animations (also improves determinism), and retry.
- * As a last resort take a viewport-only shot so the file exists (the capture gate
+ * Stage 2 — canvas raster fallback. A visible <canvas> (animated background, chart,
+ * WebGL scene) is a runtime-drawn surface the clone cannot reproduce as DOM, so it
+ * would render as an empty box. Rasterize each meaningful canvas to a PNG still under
+ * a synthetic URL (the normal asset pipeline rewrites it to a local file); the node is
+ * then marked with a `src` attr so generation emits the still as an <img> filling the
+ * canvas's box. `toDataURL` is exact but THROWS for tainted canvases and for WebGL
+ * contexts without preserveDrawingBuffer — those return a shot plan for the node-side
+ * element-screenshot fallback (composited pixels, works regardless). A WebGL canvas may
+ * also toDataURL to a blank image when the drawing buffer was already presented; that
+ * blank is accepted as-is (detecting blankness would be heuristic, not deterministic).
+ * The in-page part is exported for the fixture tests (page.evaluate'd directly).
+ */
+export type CanvasStillPlan = { stills: Array<{ url: string; dataUrl: string; sel: string }>; shots: Array<{ url: string; sel: string }> };
+export function captureCanvasStillsInPage(): CanvasStillPlan {
+  const stills: CanvasStillPlan["stills"] = [];
+  const shots: CanvasStillPlan["shots"] = [];
+  const hash = (s: string): string => { let h = 5381; for (let i = 0; i < s.length; i++) h = ((h << 5) + h + s.charCodeAt(i)) >>> 0; return h.toString(36); };
+  const canvases = Array.from(document.querySelectorAll("canvas"));
+  let i = 0;
+  for (const c of canvases) {
+    const r = c.getBoundingClientRect();
+    if (r.width < 48 || r.height < 48) continue; // not a meaningful painted surface
+    const cs = getComputedStyle(c);
+    if (cs.display === "none" || cs.visibility === "hidden" || parseFloat(cs.opacity || "1") < 0.05) continue;
+    const idx = i++;
+    c.setAttribute("data-clone-canvas", String(idx));
+    const sel = `canvas[data-clone-canvas="${idx}"]`;
+    const url = `https://clone-canvas.local/${idx}-${hash(c.id + "|" + c.width + "|" + c.height + "|" + idx)}.png`;
+    let ok = false;
+    try {
+      const dataUrl = c.toDataURL("image/png"); // throws if tainted / WebGL buffer unreadable
+      if (dataUrl.startsWith("data:image/png")) { stills.push({ url, dataUrl, sel }); ok = true; }
+    } catch { /* fall through to the element-screenshot plan */ }
+    if (!ok) shots.push({ url, sel });
+  }
+  return { stills, shots };
+}
+
+async function captureCanvasStills(page: import("playwright").Page): Promise<CanvasStillPlan> {
+  try {
+    return await Promise.race([
+      page.evaluate(captureCanvasStillsInPage),
+      new Promise<CanvasStillPlan>((res) => setTimeout(() => res({ stills: [], shots: [] }), 12_000)),
+    ]);
+  } catch {
+    return { stills: [], shots: [] };
+  }
+}
+
+// Chromium refuses/truncates screenshots past a texture-size cap; keep clip dimensions
+// under a conservative bound so captureFullPageViaCDP fails cleanly (→ Playwright fallback)
+// instead of returning a truncated image on pathologically tall pages.
+const CDP_MAX_SHOT_DIMENSION = 16_384;
+
+/**
+ * Full-page screenshot via CDP `Page.captureScreenshot` with `captureBeyondViewport:true`.
+ * Unlike Playwright's `fullPage:true` (which scroll-stitches — scrolling the page to render
+ * each band, FIRING scroll events that drive scroll-linked animations, e.g. IX2 grow-on-scroll
+ * or WAAPI scroll-timelines), CDP renders the whole page in ONE shot WITHOUT scrolling and
+ * never fires scroll events. So the resulting still is the genuine at-rest (unscrolled) page,
+ * matching the DOM snapshot the walk grades. Writes a PNG to `path`. Throws on any failure so
+ * the caller can fall back to the Playwright path.
+ */
+export async function captureFullPageViaCDP(page: import("playwright").Page, path: string): Promise<void> {
+  const client = await page.context().newCDPSession(page);
+  try {
+    const metrics = await client.send("Page.getLayoutMetrics") as {
+      cssContentSize?: { width: number; height: number };
+      contentSize?: { width: number; height: number };
+    };
+    const size = metrics.cssContentSize ?? metrics.contentSize;
+    if (!size || !(size.width > 0) || !(size.height > 0)) throw new Error("cdp: empty content size");
+    const width = Math.ceil(size.width);
+    const height = Math.ceil(size.height);
+    if (width > CDP_MAX_SHOT_DIMENSION || height > CDP_MAX_SHOT_DIMENSION) {
+      throw new Error(`cdp: content ${width}x${height} exceeds max shot dimension`);
+    }
+    const shot = await client.send("Page.captureScreenshot", {
+      format: "png",
+      captureBeyondViewport: true,
+      clip: { x: 0, y: 0, width, height, scale: 1 },
+    }) as { data: string };
+    if (!shot?.data) throw new Error("cdp: no screenshot data");
+    writeBytes(path, Buffer.from(shot.data, "base64"));
+  } finally {
+    await client.detach().catch(() => { /* ignore */ });
+  }
+}
+
+/**
+ * Full-page screenshot with robustness for heavy/animated pages. Prefers CDP capture
+ * (captureFullPageViaCDP — no scroll-stitch, so scroll-linked animations aren't scrubbed
+ * and the still is the true at-rest page). On ANY CDP failure, falls back to Playwright's
+ * `fullPage:true` (which scroll-stitches but freezes animations); the default 30s timeout
+ * is exceeded by tall pages (Playwright also waits for web fonts), so use a long timeout and
+ * retry. As a last resort take a viewport-only shot so the file exists (the capture gate
  * checks presence; a partial image still beats none).
  */
 async function captureScreenshot(
@@ -529,6 +621,13 @@ async function captureScreenshot(
   vw: number,
   log: (e: Record<string, unknown>) => void,
 ): Promise<void> {
+  try {
+    await captureFullPageViaCDP(page, path);
+    log({ event: "screenshot_cdp", viewport: vw });
+    return;
+  } catch (eCdp) {
+    log({ event: "screenshot_cdp_fallback", viewport: vw, error: String(eCdp).slice(0, 200) });
+  }
   for (let attempt = 0; attempt < 2; attempt++) {
     try {
       await page.screenshot({ path, fullPage: true, timeout: 90_000, animations: "disabled" });
@@ -923,6 +1022,47 @@ export async function captureSite(opts: {
           await page.evaluate(() => window.scrollTo(0, 0));
           await page.waitForTimeout(80);
         }
+
+        // Stage 2: canvas raster fallback — same synthetic-URL mechanism as the video
+        // stills above (captureCanvasStills). Bytes ride the normal asset pipeline; the
+        // canvas node gets a `src` attr (whitelisted → survives the IR) that generation
+        // reads to emit the still as an <img> carrying the canvas's cid/box. The attr is
+        // stamped only AFTER bytes are stored, so a failed capture leaves the canvas
+        // rendering as an empty box, same as before.
+        const cplan = await captureCanvasStills(page);
+        const stampCanvasSrc = (sel: string, u: string): Promise<void> =>
+          page.evaluate(({ s, u: uu }) => { document.querySelector(s)?.setAttribute("src", uu); }, { s: sel, u }).catch(() => { /* ignore */ });
+        for (const s of cplan.stills) {
+          const comma = s.dataUrl.indexOf(",");
+          if (comma < 0) continue;
+          try {
+            const buf = Buffer.from(s.dataUrl.slice(comma + 1), "base64");
+            recordAsset(s.url, "image", "image/png", 200, "canvas-still");
+            storeBytes(s.url, "image", buf);
+            await stampCanvasSrc(s.sel, s.url);
+            log({ event: "canvas_still", viewport: vw, sel: s.sel });
+          } catch { /* ignore */ }
+        }
+        for (const s of cplan.shots) {
+          // Same reveal discipline as the video shots: a hidden canvas (entrance
+          // animation not yet fired) would time out locator.screenshot's visibility wait.
+          try {
+            await page.evaluate(forceRevealForShot, s.sel);
+            const buf = await page.locator(s.sel).first().screenshot({ type: "png", timeout: 5000, animations: "disabled" });
+            recordAsset(s.url, "image", "image/png", 200, "canvas-still");
+            storeBytes(s.url, "image", buf);
+            await stampCanvasSrc(s.sel, s.url);
+            log({ event: "canvas_still", viewport: vw, sel: s.sel });
+          } catch (e) {
+            log({ event: "canvas_still_error", viewport: vw, sel: s.sel, error: String(e).slice(0, 200) });
+          } finally {
+            await page.evaluate(restoreRevealForShot).catch(() => { /* ignore */ });
+          }
+        }
+        if (cplan.shots.length) {
+          await page.evaluate(() => window.scrollTo(0, 0));
+          await page.waitForTimeout(80);
+        }
       }
 
       // Stage 4/5: stamp capture-ids before the canonical snapshot so the IR carries
diff --git a/compiler/src/generate/app.ts b/compiler/src/generate/app.ts
index f1c936b..0e3c39e 100644
--- a/compiler/src/generate/app.ts
+++ b/compiler/src/generate/app.ts
@@ -391,6 +391,10 @@ export function propsList(node: IRNode, assetMap: Map<string, string>, sourceUrl
 
   if (isVideo && !videoLocal && !props.some(([k]) => k === "preload")) props.push(["preload", JSON.stringify("none")]);
 
+  // A canvas emitted as its raster still (<img> — see resolveTag) is decorative
+  // painted surface with no captured alt text; emit alt="" so the img is valid.
+  if (node.tag === "canvas" && node.attrs.src && !props.some(([k]) => k === "alt")) props.push(["alt", JSON.stringify("")]);
+
   if (node.rawHTML && node.tag === "svg") {
     // Strip the Stage-4 capture-id (`data-cid-cap`) the interaction pass stamps on
     // elements: it's internal instrumentation, render-inert, and would otherwise
@@ -557,6 +561,12 @@ export function resolveTag(node: IRNode, insideInteractive: boolean, insideTable
   // children inside <iframe> are unrendered fallback content, so emit a <div> container
   // carrying the iframe's box/styles (CSS is keyed by cid, so the geometry is identical).
   if (tag === "iframe" && node.children.some((c) => !isTextChild(c))) tag = "div";
+  // A canvas is runtime-drawn surface the clone cannot reproduce; when capture
+  // rasterized it (canvas-still synthetic URL stamped as `src` — see
+  // captureCanvasStillsInPage) emit the still as an <img> filling the canvas's box
+  // (CSS is keyed by cid, so the geometry is identical). A canvas with no still
+  // keeps rendering as an empty <canvas> box, same as before.
+  if (tag === "canvas" && node.attrs.src) tag = "img";
   if (TABLE_SCOPED.has(tag) && !insideTable) tag = "div"; // orphan table element → neutral box
   if (violatesContentModel(node, tag)) tag = "div";
   return tag;
diff --git a/compiler/src/generate/css.ts b/compiler/src/generate/css.ts
index 6cf25c7..664de0b 100644
--- a/compiler/src/generate/css.ts
+++ b/compiler/src/generate/css.ts
@@ -32,6 +32,11 @@ button, input, select, textarea, optgroup { font: inherit; color: inherit; backg
 button { cursor: pointer; }
 table { border-collapse: separate; border-spacing: 0; }
 img, picture, video, canvas, svg { display: inline-block; }
+/* Lottie runtime fit: the player re-mounts its svg/canvas into an absolute overlay that fills
+   the host's captured (per-viewport, definite) box. Force that runtime media to fit the box so
+   an aspect-mismatched viewBox (e.g. a portrait animation in a shorter, letterboxed source box)
+   can't inflate past the pinned height. Scoped to the runtime-marked host only. */
+[data-ditto-lottie] > div > svg, [data-ditto-lottie] > div > canvas { width: 100%; height: 100%; display: block; }
 h1, h2, h3, h4, h5, h6, p, figure, blockquote, dl, dd { margin: 0; }
 /* Neutralize UA text defaults to inherit so the generator's default-skipping is
    correct: a property equal to its inherited value is simply not emitted. */
diff --git a/compiler/src/generate/lottie.ts b/compiler/src/generate/lottie.ts
index 45342da..d27b17a 100644
--- a/compiler/src/generate/lottie.ts
+++ b/compiler/src/generate/lottie.ts
@@ -138,12 +138,19 @@ export default function DittoLottie({ spec }: { spec: LottieSpec }) {
           // Mount the live animation into an OVERLAY child, keeping the captured placeholder
           // frame in the DOM until lottie signals a successful load — a failed load (bad JSON,
           // network) then leaves the placeholder intact instead of erasing the container to blank.
+          // The overlay stays position:absolute;inset:0 for its WHOLE life (not just pre-swap):
+          // the host box carries the captured per-viewport height, and only an absolutely-filled
+          // overlay inherits that definite box. A static-flow overlay has indefinite height, so
+          // the player's svg (style height:100%) collapses to auto and inflates to the source
+          // aspect (a portrait viewBox then oversizes far past the captured, letterboxed box).
           const mount = document.createElement("div");
           mount.style.position = "absolute";
           mount.style.inset = "0";
           mount.style.opacity = "0";
           const cs = getComputedStyle(el);
           if (cs.position === "static") el.style.position = "relative";
+          // Mark the host so emitted CSS can force the runtime svg/canvas to fit the pinned box.
+          el.setAttribute("data-ditto-lottie", "");
           el.appendChild(mount);
           const anim = lottie.loadAnimation({
             container: mount,
@@ -171,8 +178,9 @@ export default function DittoLottie({ spec }: { spec: LottieSpec }) {
               const rendered = mount.querySelector("svg, canvas");
               if (rendered) rendered.setAttribute("data-cid", placeholderCid);
             }
-            mount.style.position = "";
-            mount.style.inset = "";
+            // Do NOT clear position/inset: the overlay must keep filling the host's pinned box
+            // (see above). Stripping them reverts it to static flow → indefinite height → the
+            // player's height:100% svg inflates to its aspect and escapes the captured bbox.
           };
           // DOMLoaded fires only after the JSON parsed and the first frame rendered — the
           // right moment to reveal the live render and drop the placeholder. data_failed
diff --git a/compiler/src/validate/render.ts b/compiler/src/validate/render.ts
index 8acbb73..8848e61 100644
--- a/compiler/src/validate/render.ts
+++ b/compiler/src/validate/render.ts
@@ -5,6 +5,7 @@ import { join, extname, normalize } from "node:path";
 import { spawnSync } from "node:child_process";
 import { chromium } from "playwright";
 import { collectPage, type PageSnapshot } from "../capture/walker.js";
+import { captureFullPageViaCDP } from "../capture/capture.js";
 import { ensureDir, writeJSONCompact } from "../util/fsx.js";
 
 const ESBUILD_SHIM =
@@ -255,8 +256,17 @@ export async function renderApp(opts: {
         });
         const snapshot = await page.evaluate(collectPage);
         writeJSONCompact(join(opts.renderedDir, "dom", `dom-${vw}.json`), snapshot);
+        // Screenshot via CDP (captureBeyondViewport, no scroll-stitch) to match the SOURCE
+        // channel exactly — both sides must measure the same at-rest state. Fall back to
+        // Playwright's fullPage stitch if CDP fails. The clone is static so scroll-stitch
+        // matters less here, but symmetric capture is the requirement.
         try {
-          await page.screenshot({ path: join(opts.renderedDir, "screenshots", `${vw}.png`), fullPage: true, timeout: 90_000, animations: "disabled" });
+          const shotPath = join(opts.renderedDir, "screenshots", `${vw}.png`);
+          try {
+            await captureFullPageViaCDP(page, shotPath);
+          } catch {
+            await page.screenshot({ path: shotPath, fullPage: true, timeout: 90_000, animations: "disabled" });
+          }
         } catch { /* ignore */ }
         return { viewport: vw, snapshot, runtimeErrors, failedResources: [...failedResources], httpStatus };
       } finally {
diff --git a/compiler/test/canvasStill.test.ts b/compiler/test/canvasStill.test.ts
new file mode 100644
index 0000000..bd40517
--- /dev/null
+++ b/compiler/test/canvasStill.test.ts
@@ -0,0 +1,108 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { chromium, type Browser, type Page } from "playwright";
+import { captureCanvasStillsInPage } from "../src/capture/capture.js";
+import type { IRNode, IRChild, StyleMap, BBox } from "../src/normalize/ir.js";
+import { propsList, resolveTag, renderChildrenJsx } from "../src/generate/app.js";
+
+// tsx/esbuild wraps functions with a __name() helper for stack traces; the serialized
+// page functions carry those calls, so shim it (same as capture.ts's init script).
+const ESBUILD_SHIM =
+  "globalThis.__name = globalThis.__name || ((fn) => fn);" +
+  "globalThis.__defProp = globalThis.__defProp || Object.defineProperty;";
+
+describe("capture: canvas raster fallback (in-page)", () => {
+  let browser: Browser;
+  let page: Page;
+  before(async () => {
+    browser = await chromium.launch();
+    page = await browser.newPage();
+    await page.addInitScript(ESBUILD_SHIM);
+    await page.setContent(`
+      <canvas id="big" width="200" height="100"></canvas>
+      <canvas id="tiny" width="20" height="20"></canvas>
+      <canvas id="ghost" width="300" height="150" style="visibility:hidden"></canvas>
+      <script>
+        const ctx = document.getElementById("big").getContext("2d");
+        ctx.fillStyle = "#3b82f6";
+        ctx.fillRect(10, 10, 180, 80);
+      </script>
+    `);
+    // setContent replaces the document without a navigation, so the init script may
+    // not have applied — evaluate the shim directly (same as capture.ts's frame path).
+    await page.evaluate(ESBUILD_SHIM);
+  });
+  after(async () => {
+    await browser.close();
+  });
+
+  it("rasterizes a meaningful 2D canvas to a PNG data URL under a synthetic clone-canvas URL", async () => {
+    const plan = await page.evaluate(captureCanvasStillsInPage);
+    assert.equal(plan.stills.length, 1, "exactly one canvas qualifies");
+    assert.equal(plan.shots.length, 0, "readable 2D canvas needs no element-screenshot fallback");
+    const still = plan.stills[0]!;
+    assert.ok(still.dataUrl.startsWith("data:image/png"), `PNG data URL (got ${still.dataUrl.slice(0, 30)})`);
+    assert.match(still.url, /^https:\/\/clone-canvas\.local\/0-[0-9a-z]+\.png$/);
+    assert.equal(still.sel, 'canvas[data-clone-canvas="0"]');
+    const bytes = Buffer.from(still.dataUrl.slice(still.dataUrl.indexOf(",") + 1), "base64");
+    assert.ok(bytes.length > 0, "still decodes to non-empty bytes");
+
+    const stamped = await page.evaluate(() => ({
+      big: document.getElementById("big")?.getAttribute("data-clone-canvas") ?? null,
+      tiny: document.getElementById("tiny")?.getAttribute("data-clone-canvas") ?? null,
+      ghost: document.getElementById("ghost")?.getAttribute("data-clone-canvas") ?? null,
+    }));
+    assert.equal(stamped.big, "0", "qualifying canvas gets the stable marker");
+    assert.equal(stamped.tiny, null, "a 20x20 canvas is below the meaningful-size gate");
+    assert.equal(stamped.ghost, null, "a hidden canvas is skipped");
+  });
+});
+
+const VPS = [375, 1280];
+const SOURCE = "https://example.test/page";
+const GIF = "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7";
+
+function el(id: string, tag: string, attrs: Record<string, string> = {}, children: IRChild[] = [], visible = true): IRNode {
+  const computedByVp: Record<number, StyleMap> = {};
+  const bboxByVp: Record<number, BBox> = {};
+  const visibleByVp: Record<number, boolean> = {};
+  for (const vp of VPS) {
+    computedByVp[vp] = { display: "block", position: "static", visibility: "visible" };
+    bboxByVp[vp] = { x: 0, y: 0, width: visible ? 640 : 0, height: visible ? 360 : 0 };
+    visibleByVp[vp] = visible;
+  }
+  return { id, tag, attrs, visibleByVp, bboxByVp, computedByVp, children };
+}
+
+describe("generate: canvas-still emission", () => {
+  const STILL_URL = "https://clone-canvas.local/0-abc.png";
+  const LOCAL = "/assets/cloned/images/ab.png";
+  const assetMap = new Map([[STILL_URL, LOCAL]]);
+  const canvas = () => el("7", "canvas", { src: STILL_URL, width: "200", height: "100" });
+
+  it("retags a canvas carrying a captured still to <img>; a bare canvas stays canvas", () => {
+    assert.equal(resolveTag(canvas(), false), "img");
+    assert.equal(resolveTag(el("8", "canvas", { width: "200", height: "100" }), false), "canvas");
+  });
+
+  it("resolves the synthetic still URL through the asset map and emits data-cid + alt", () => {
+    const p = new Map(propsList(canvas(), assetMap, SOURCE));
+    assert.equal(p.get("src"), JSON.stringify(LOCAL));
+    assert.equal(p.get('"data-cid"'), JSON.stringify("7"));
+    assert.equal(p.get("alt"), JSON.stringify(""), "decorative alt is injected for the raster still");
+    assert.equal(p.get("width"), JSON.stringify("200"));
+    assert.equal(p.get("height"), JSON.stringify("100"));
+  });
+
+  it("renders a self-closing <img> in place of the canvas", () => {
+    const jsx = renderChildrenJsx([canvas()], assetMap, SOURCE, 0);
+    assert.match(jsx, /<img[^>]*data-cid="7"[^>]*\/>/);
+    assert.match(jsx, new RegExp(`src="${LOCAL.replace(/[/]/g, "\\/")}"`));
+    assert.ok(!jsx.includes("<canvas"), "no canvas element remains");
+  });
+
+  it("falls back to the transparent GIF when the still missed the asset map (never a remote URL)", () => {
+    const p = new Map(propsList(canvas(), new Map(), SOURCE));
+    assert.equal(p.get("src"), JSON.stringify(GIF));
+  });
+});
diff --git a/compiler/test/cdpScreenshot.test.ts b/compiler/test/cdpScreenshot.test.ts
new file mode 100644
index 0000000..4321625
--- /dev/null
+++ b/compiler/test/cdpScreenshot.test.ts
@@ -0,0 +1,84 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { chromium, type Browser, type Page } from "playwright";
+import { PNG } from "pngjs";
+import pixelmatch from "pixelmatch";
+import { captureFullPageViaCDP } from "../src/capture/capture.js";
+
+const ESBUILD_SHIM = "globalThis.__name = globalThis.__name || ((fn) => fn);";
+
+// A STATIC page (no scroll-linked animation) several viewports tall: a few full-width
+// colored bands. Both capture paths should render the identical at-rest picture, so any
+// difference is purely a capture-mechanism artifact (scrollbar gutter, off-by-one), which
+// is exactly what this test measures.
+const BANDS_HTML =
+  "<!doctype html><html><head><style>" +
+  "*{margin:0;padding:0;box-sizing:border-box}" +
+  "html,body{width:100%}" +
+  ".band{width:100%;height:600px;display:flex;align-items:center;justify-content:center;" +
+  "font:bold 48px sans-serif;color:#fff}" +
+  ".b0{background:#c0392b}.b1{background:#27ae60}.b2{background:#2980b9}" +
+  ".b3{background:#8e44ad}.b4{background:#d35400}" +
+  "</style></head><body>" +
+  "<div class='band b0'>1</div><div class='band b1'>2</div>" +
+  "<div class='band b2'>3</div><div class='band b3'>4</div>" +
+  "<div class='band b4'>5</div>" +
+  "</body></html>";
+
+describe("CDP full-page capture vs Playwright fullPage stitch (static fixture)", () => {
+  let browser: Browser;
+  let page: Page;
+  let tmp: string;
+
+  before(async () => {
+    browser = await chromium.launch({ args: ["--disable-dev-shm-usage"] });
+    // A viewport SHORTER than the content so fullPage must span multiple bands: this is
+    // where Playwright would scroll-stitch and CDP renders in one shot.
+    const context = await browser.newContext({ viewport: { width: 800, height: 700 }, deviceScaleFactor: 1 });
+    page = await context.newPage();
+    await page.addInitScript(ESBUILD_SHIM);
+    await page.setContent(BANDS_HTML, { waitUntil: "load" });
+    tmp = mkdtempSync(join(tmpdir(), "cdp-shot-"));
+  });
+
+  after(async () => {
+    await browser.close();
+    if (tmp) rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("produces a valid PNG of the full content height (not just the viewport)", async () => {
+    const cdpPath = join(tmp, "cdp.png");
+    await captureFullPageViaCDP(page, cdpPath);
+    const cdp = PNG.sync.read(readFileSync(cdpPath));
+    // 5 bands * 600px = 3000px tall, well beyond the 700px viewport.
+    assert.ok(cdp.height >= 2900, `CDP shot spans full content (got ${cdp.height})`);
+    assert.ok(cdp.width >= 780 && cdp.width <= 800, `CDP width ~= content width (got ${cdp.width})`);
+    assert.ok(readFileSync(cdpPath).length > 1000, "CDP PNG is non-trivial in size");
+  });
+
+  it("is pixel-equivalent to Playwright's fullPage screenshot on a static page", async () => {
+    const cdpPath = join(tmp, "cdp2.png");
+    const pwPath = join(tmp, "pw.png");
+    await captureFullPageViaCDP(page, cdpPath);
+    await page.screenshot({ path: pwPath, fullPage: true, animations: "disabled" });
+
+    const cdp = PNG.sync.read(readFileSync(cdpPath));
+    const pw = PNG.sync.read(readFileSync(pwPath));
+
+    // Dimensions must match (a scrollbar-gutter difference would show up here first).
+    assert.equal(cdp.width, pw.width, `width match (cdp ${cdp.width} vs pw ${pw.width})`);
+    assert.equal(cdp.height, pw.height, `height match (cdp ${cdp.height} vs pw ${pw.height})`);
+
+    const { width, height } = cdp;
+    const diff = new PNG({ width, height });
+    const mismatched = pixelmatch(cdp.data, pw.data, diff.data, width, height, { threshold: 0.1 });
+    const pct = (mismatched / (width * height)) * 100;
+    // On a static page the two mechanisms should be near-identical. Allow a tiny tolerance
+    // for antialiasing at band seams; assert well under 0.5% differing pixels.
+    assert.ok(pct < 0.5, `pixel delta ${pct.toFixed(4)}% (${mismatched} px) must be < 0.5%`);
+  });
+});
diff --git a/compiler/test/css.test.ts b/compiler/test/css.test.ts
index 63c4448..b190801 100644
--- a/compiler/test/css.test.ts
+++ b/compiler/test/css.test.ts
@@ -2,7 +2,7 @@ import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 import type { IR, IRNode, IRChild, StyleMap, BBox } from "../src/normalize/ir.js";
 import type { RawSizing } from "../src/capture/walker.js";
-import { generateCss, collectNodeRules } from "../src/generate/css.js";
+import { generateCss, collectNodeRules, RESET_CSS } from "../src/generate/css.js";
 
 const VPS = [375, 1280];
 const CANONICAL = 1280;
@@ -618,6 +618,32 @@ describe("collectNodeRules lottie mount height pin", () => {
   });
 });
 
+// The reset ships a rule that forces the lottie runtime svg/canvas to fit its overlay box. The
+// player re-mounts its media into an absolute overlay that fills the host's pinned (per-viewport)
+// height; without this rule an aspect-mismatched viewBox (a portrait animation in a shorter,
+// letterboxed source box) inflates past that height. Scoped to the runtime-marked host only, so it
+// is inert when a page has no lottie.
+describe("RESET_CSS lottie runtime-fit rule", () => {
+  it("constrains the runtime svg/canvas to the overlay box, scoped to the marked host", () => {
+    assert.match(RESET_CSS, /\[data-ditto-lottie\]\s*>\s*div\s*>\s*svg/);
+    assert.match(RESET_CSS, /\[data-ditto-lottie\]\s*>\s*div\s*>\s*canvas/);
+    // the rule must pin both dimensions so height:100% resolves against the definite overlay
+    const m = RESET_CSS.match(/\[data-ditto-lottie\][^{]*\{([^}]*)\}/);
+    assert.ok(m, "the data-ditto-lottie rule must be present");
+    assert.match(m![1], /width:\s*100%/);
+    assert.match(m![1], /height:\s*100%/);
+  });
+
+  it("does not affect the pre-swap placeholder (a direct-child svg, not nested under a div)", () => {
+    // The selector targets `> div > svg` (the runtime overlay), never a `> svg` placeholder, so the
+    // captured placeholder keeps its own pinned classes and pre/post-swap geometry stays identical.
+    assert.ok(
+      !/\[data-ditto-lottie\]\s*>\s*svg\b/.test(RESET_CSS),
+      "the rule must not target a direct-child placeholder svg",
+    );
+  });
+});
+
 // Defect E — a content-sized flex ROW's items are dropped to `width:auto` only when NO shrink fired
 // (positive slack ⇒ items at content size). But a WRAPPING text leaf paints at its balanced-wrap
 // width, which is BELOW its max-content: `width:auto` on the block child fills the line to
diff --git a/compiler/test/lottiePlaceholder.test.ts b/compiler/test/lottiePlaceholder.test.ts
index 9cb6f2b..fafd6ee 100644
--- a/compiler/test/lottiePlaceholder.test.ts
+++ b/compiler/test/lottiePlaceholder.test.ts
@@ -37,6 +37,33 @@ describe("DittoLottie placeholder retention", () => {
     assert.match(DITTO_LOTTIE_TSX, /data_failed/);
   });
 
+  // Sizing: the host box carries the captured per-viewport height; only an absolutely-filled overlay
+  // inherits that definite box. If the reveal reverted the overlay to static flow, the player's svg
+  // (style height:100%) would collapse to auto and inflate to the source aspect (a portrait viewBox
+  // then oversizes far past the captured, letterboxed box). So the overlay must STAY absolute/inset
+  // for its whole life, and the reveal must NOT clear those styles.
+  it("mounts the overlay as an absolute, inset-0 layer", () => {
+    assert.match(DITTO_LOTTIE_TSX, /mount\.style\.position\s*=\s*["']absolute["']/);
+    assert.match(DITTO_LOTTIE_TSX, /mount\.style\.inset\s*=\s*["']0["']/);
+  });
+
+  it("keeps the overlay absolute after the swap (never reverts it to static flow)", () => {
+    // The reveal must not strip the overlay's positioning — a `mount.style.position = ""` (or inset)
+    // un-pins it from the host's captured height and lets the runtime svg inflate by aspect.
+    assert.ok(
+      !/mount\.style\.position\s*=\s*["']["']/.test(DITTO_LOTTIE_TSX),
+      "reveal must not clear mount.style.position (would un-pin the overlay → aspect inflation)",
+    );
+    assert.ok(
+      !/mount\.style\.inset\s*=\s*["']["']/.test(DITTO_LOTTIE_TSX),
+      "reveal must not clear mount.style.inset (would un-pin the overlay → aspect inflation)",
+    );
+  });
+
+  it("marks the host with data-ditto-lottie so emitted CSS can force the runtime svg to fit", () => {
+    assert.match(DITTO_LOTTIE_TSX, /setAttribute\(\s*["']data-ditto-lottie["']/);
+  });
+
   // The player creates its <svg>/<canvas> at runtime WITHOUT a data-cid, so the DOM/media gate can't
   // map it back to the captured node. The reveal must forward the discarded placeholder's data-cid
   // onto the runtime-rendered element (validation-agnostic; no gate special-casing).

From b445b62a69cdfeedc39b3066f02fbea469620d02 Mon Sep 17 00:00:00 2001
From: Samraaj Bath <samraaj100@gmail.com>
Date: Sat, 4 Jul 2026 00:59:48 -0700
Subject: [PATCH 07/24] Fix flex-basis 0% collapse, fluid max-width centering,
 letter-spacing snap, video frame normalization

- Keep basis/h/min-h [0%] literal (0% content-sizes on an indefinite axis;
  0px is definite zero) and fold grow + zero-basis into flex-1 - a
  flex:1 1 0% child no longer collapses to height 0 in auto-height columns
- Width centering accepts per-viewport caps (max-width: min(Npx, fluid))
  with symmetric gaps -> mx-auto + banded max-w instead of literal banded
  margins that drift off-centre between captured widths; non-painted
  viewports no longer poison the inference
- letter-spacing keeps sub-0.1px precision (no zero snap); style gate
  normalizes Chromium's letter-spacing "normal" <-> 0px serialization
- Videos pause + seek to frame 0 before every source AND clone screenshot,
  removing playback-time nondeterminism from perceptual evidence

278 tests pass (19 new), typecheck clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 compiler/src/capture/capture.ts   | 42 +++++++++++++++++++-
 compiler/src/generate/css.ts      | 35 +++++++++++++----
 compiler/src/generate/tailwind.ts | 29 +++++++++++++-
 compiler/src/validate/gates.ts    | 18 ++++++++-
 compiler/src/validate/render.ts   |  7 +++-
 compiler/test/css.test.ts         | 26 +++++++++++++
 compiler/test/gates.test.ts       | 38 ++++++++++++++++++
 compiler/test/tailwind.test.ts    | 64 ++++++++++++++++++++++++++++++-
 8 files changed, 246 insertions(+), 13 deletions(-)
 create mode 100644 compiler/test/gates.test.ts

diff --git a/compiler/src/capture/capture.ts b/compiler/src/capture/capture.ts
index fc7eaa1..1f71d2f 100644
--- a/compiler/src/capture/capture.ts
+++ b/compiler/src/capture/capture.ts
@@ -646,6 +646,40 @@ async function captureScreenshot(
   }
 }
 
+/**
+ * Pause every <video> and seek it to time 0, then wait for that seek to actually PAINT, so a
+ * screenshot taken right after is deterministic. A video's playback time is runtime state: a one-shot
+ * animation ends on its last frame, an autoplaying loop sits at an arbitrary offset, and the time a
+ * given viewport's shot happens to catch is nondeterministic. Without normalization the SOURCE and the
+ * (frame-0, non-playing) CLONE can show different frames of the same element — a phantom perceptual
+ * diff that no CSS change can close. Seeking BOTH sides to frame 0 before EVERY viewport screenshot
+ * removes it. `seeked` fires once the new frame is decoded; we still yield two rAFs so the compositor
+ * has painted it before the screenshot reads pixels. Bounded so a stalled/unseekable video can't hang.
+ */
+export async function normalizeVideoTime(page: import("playwright").Page): Promise<void> {
+  try {
+    await page.evaluate(async () => {
+      const vids = Array.from(document.querySelectorAll("video"));
+      const raf = () => new Promise<void>((r) => requestAnimationFrame(() => r()));
+      const waits: Promise<void>[] = [];
+      for (const v of vids) {
+        try { v.pause(); } catch { /* ignore */ }
+        // Seek to 0 only when not already there (a fresh seek to the current time may not fire `seeked`).
+        if (Math.abs(v.currentTime) < 1e-3) continue;
+        waits.push(new Promise<void>((resolve) => {
+          let settled = false;
+          const done = () => { if (settled) return; settled = true; v.removeEventListener("seeked", done); resolve(); };
+          v.addEventListener("seeked", done, { once: true });
+          try { v.currentTime = 0; } catch { done(); }
+          setTimeout(done, 400); // bound: a stalled/unseekable video resolves anyway
+        }));
+      }
+      await Promise.all(waits);
+      await raf(); await raf(); // let the decoded frame composite before the screenshot reads pixels
+    });
+  } catch { /* a page with no videos / an eval hiccup must never block the screenshot */ }
+}
+
 export async function captureSite(opts: {
   url: string;
   outDir: string; // source/ directory
@@ -1219,7 +1253,13 @@ export async function captureSite(opts: {
 
       // Persist DOM snapshot, and (unless skipped for a production clone) the full-page screenshot.
       writeJSONCompact(join(captureDir, `dom-${vw}.json`), snapshot);
-      if (opts.screenshots !== false) await captureScreenshot(page, join(screenshotsDir, `${vw}.png`), vw, log);
+      if (opts.screenshots !== false) {
+        // Normalize every video to frame 0 (paused) at THIS viewport before the shot — the clone is
+        // always at frame 0, so pinning the source there too makes the two channels comparable
+        // regardless of the playback time the viewport happened to catch.
+        await normalizeVideoTime(page);
+        await captureScreenshot(page, join(screenshotsDir, `${vw}.png`), vw, log);
+      }
 
       // Stage 4: drive recognized affordances at the canonical viewport (opt-in).
       if (opts.interactions && vw === canonical) {
diff --git a/compiler/src/generate/css.ts b/compiler/src/generate/css.ts
index 664de0b..2ae1757 100644
--- a/compiler/src/generate/css.ts
+++ b/compiler/src/generate/css.ts
@@ -362,11 +362,17 @@ function planWidth(node: IRNode, parentNode: IRNode | undefined, viewports: numb
   // Replaced/custom elements size to intrinsic dimensions under auto/%, not the container.
   if (REPLACED.has(node.tag) || node.tag.includes("-")) return none;
 
-  type Sample = { w: number; bw: number; cw: number; ml: number; mr: number; maxW: number | null; gapL: number; gapR: number; borderBox: boolean };
+  type Sample = { w: number; bw: number; cw: number; ml: number; mr: number; maxW: number | null; gapL: number; gapR: number; borderBox: boolean; visible: boolean };
   const samples: Sample[] = [];
   for (const vp of viewports) {
     const cs = node.computedByVp[vp]; const nb = node.bboxByVp[vp];
     if (!cs || !nb) continue;
+    // A viewport where the node (or its containing block) is display:none / zero-box contributes no
+    // geometry: its computed box is 0×0, margins report the unresolved `auto`, and the containing width
+    // is 0. Skip it rather than bailing the whole inference — a container hidden at some breakpoints can
+    // still be provably centred at the widths where it IS painted (judged over the visible samples below).
+    const paintedHere = !!node.visibleByVp[vp] && nb.width > 0;
+    if (!paintedHere) continue;
     // Block-LEVEL, in-flow only: margin-auto centring and auto/100% fill apply to these; an
     // inline / inline-block / flex-item box is positioned differently, so bail conservatively.
     if (!/^(block|flow-root|list-item|flex|grid)$/.test(cs.display || "")) return none;
@@ -387,6 +393,7 @@ function planWidth(node: IRNode, parentNode: IRNode | undefined, viewports: numb
     samples.push({
       w, bw: nb.width, cw, ml: pf(cs.marginLeft), mr: pf(cs.marginRight), maxW,
       gapL: nb.x - cl, gapR: cr - (nb.x + nb.width), borderBox: (cs.boxSizing || "border-box") !== "content-box",
+      visible: !!node.visibleByVp[vp] && nb.width > 0,
     });
   }
   if (samples.length < 2) return none;
@@ -395,14 +402,26 @@ function planWidth(node: IRNode, parentNode: IRNode | undefined, viewports: numb
   const span = (xs: number[]): number => Math.max(...xs) - Math.min(...xs);
   const zeroMargins = samples.every((s) => Math.abs(s.ml) <= 1.5 && Math.abs(s.mr) <= 1.5);
 
-  // (a) Centred max-width container: border-box, a single px max-width cap, and every sample's
-  // border box equals min(containerWidth, cap) — filling when narrower than the cap, centred
-  // (symmetric positive gaps) when wider. Reproduces `max-width:W; margin:0 auto` exactly.
-  if (samples.every((s) => s.maxW != null && s.borderBox)) {
-    const caps = samples.map((s) => s.maxW!);
-    let ok = span(caps) <= Math.max(2, 0.01 * Math.max(...caps));
+  // (a) Centred max-width container: border-box, a px max-width cap AT EVERY sample, and every
+  // sample's border box equals min(containerWidth, cap) — filling when narrower than the cap, centred
+  // (symmetric positive gaps) when wider. Reproduces `margin:0 auto` centring with a per-viewport cap.
+  // The cap need NOT be a single constant: a fluid `max-width: min(Wpx, 100vw − 2·gutter)` resolves to
+  // a DIFFERENT px per width (e.g. 311/673/1145/1272), so requiring a constant cap wrongly rejected the
+  // commonest centred container and left it PLAN_FIXED with literal per-band `mx-*` (off-centre at any
+  // non-captured width). We accept per-viewport caps and let the normal per-band `max-width` emission
+  // carry them; `mx-auto` (from centerAlways) then centres at EVERY width. Fidelity is preserved
+  // because each sample's `min(cw, maxW_vp)` reproduces the captured box exactly at that width. The
+  // `sawCenter` requirement below is the load-bearing guard: a box that merely FILLS (never shows
+  // symmetric free-space gaps) is NOT proven centred and stays PLAN_FIXED with its literal margins.
+  // A display:none / zero-box sample has no geometry to prove centring against (its computed box is
+  // 0×0 and its margins report the unresolved `auto`). Judge case (a) only over the VISIBLE samples —
+  // a container centred wherever it is actually painted is centred everywhere via `mx-auto`, even if it
+  // is hidden at some breakpoints. (≥2 visible samples still required so the inference has evidence.)
+  const vis = samples.filter((s) => s.visible);
+  if (vis.length >= 2 && vis.every((s) => s.maxW != null && s.borderBox)) {
+    let ok = true;
     let sawCenter = false;
-    if (ok) for (const s of samples) {
+    for (const s of vis) {
       if (!close(s.bw, Math.min(s.cw, s.maxW!), 1.5, 0.01)) { ok = false; break; }
       if (s.cw > s.maxW! + 4) { // room to centre — must actually be centred, not left-aligned
         if (s.gapL > 1 && s.gapR > 1 && Math.abs(s.gapL - s.gapR) <= 1.5) sawCenter = true;
diff --git a/compiler/src/generate/tailwind.ts b/compiler/src/generate/tailwind.ts
index b6b382e..cd905e9 100644
--- a/compiler/src/generate/tailwind.ts
+++ b/compiler/src/generate/tailwind.ts
@@ -262,6 +262,13 @@ export function declToUtil(prop: string, value: string): string {
     if (value === "0" || value === "0px" || value === "0rem") {
       return ZERO_NAMED.has(prop) ? `${ARB[prop]}-0` : `${ARB[prop]}-[0px]`;
     }
+    // `snapLen`'s 0.1px integer snap is calibrated for BOX lengths (killing measurement jitter like
+    // `204.9994px`→`205px`). letter-spacing is authored at a far finer scale — a real `-0.08px`/
+    // `-0.0375px` tracking is WITHIN 0.1px of zero, so snapLen would collapse it to `0px`. Chromium
+    // then serializes computed `letter-spacing:0` as the keyword `normal`, which the style gate's
+    // numeric compare can't parse → a false exact-string mismatch. Skip the integer snap for tracking;
+    // `snapBase` rounds it to 2 decimals (`tracking-[-0.08px]`), the right precision for this axis.
+    if (prop === "letter-spacing") return `${ARB[prop]}-[${arb(value)}]`;
     return `${ARB[prop]}-[${arb(snapLen(value))}]`;
   }
   if (/^border-(top|right|bottom|left)-width$/.test(prop)) {
@@ -372,7 +379,7 @@ function parseSide(b: string): SidePart | null {
   for (const h of COLLAPSE_HEADS) if (body.startsWith(h + "-")) return { neg, head: h, suf: body.slice(h.length + 1) };
   return null;
 }
-function collapseBases(bases: string[]): string[] {
+export function collapseBases(bases: string[]): string[] {
   const byHead = new Map<string, SidePart>(); // head → its parsed part (sides are unique within a group)
   for (const b of bases) { const p = parseSide(b); if (p) byHead.set(p.head, p); }
   const origOf = new Map<string, string>(); // head → original base string (to drop/replace by identity)
@@ -429,6 +436,18 @@ function collapseBases(bases: string[]): string[] {
   if (wv !== null) { const sfx = wv ? `-${wv}` : ""; replace.set(`border-t${sfx}`, `border${sfx}`); for (const s of ["r", "b", "l"]) drop.add(`border-${s}${sfx}`); }
   const cv = allEqSide(bcSuf);
   if (cv !== null) { replace.set(`border-t-${cv}`, `border-${cv}`); for (const s of ["r", "b", "l"]) drop.add(`border-${s}-${cv}`); }
+  // flex:1 1 0% → the idiomatic `flex-1` (Tailwind `flex-1` compiles to `flex: 1 1 0%`, EXACTLY these
+  // longhands). Fold when this band sets flex-grow:1 (`grow-[1]`) AND a zero flex-basis (`basis-[0%]`,
+  // or its already-shortened `basis-0` — reached from a band delta). flex-shrink is the CSS default 1
+  // (elided) unless an explicit `shrink-0` is present, which would break the equivalence — so require
+  // its absence. Emitting `flex-1` rather than `grow basis-[0%]` also sidesteps the `basis-[0%]`→`basis
+  // -0` prettify hazard (0% content-sizes against an indefinite main axis; 0px is a definite zero).
+  const hasGrow1 = bases.includes("grow-[1]");
+  const zeroBasis = bases.includes("basis-[0%]") ? "basis-[0%]" : bases.includes("basis-0") ? "basis-0" : null;
+  if (hasGrow1 && zeroBasis && !bases.includes("shrink-0")) {
+    replace.set("grow-[1]", "flex-1");
+    drop.add(zeroBasis);
+  }
   const out: string[] = [];
   for (const b of bases) { if (drop.has(b)) continue; out.push(replace.get(b) ?? b); }
   return out;
@@ -509,6 +528,14 @@ export function prettifyBase(base: string): string {
   const pm = /^(w|h|min-w|min-h|basis|inset|inset-x|inset-y|top|right|bottom|left)-\[(\d*\.?\d+)%\]$/.exec(base);
   if (pm) {
     const v = parseFloat(pm[2]!);
+    // A percentage on a MAIN-SIZE axis whose containing block may be indefinite is NOT equal to the
+    // same length in px. `flex-basis:0%` against an auto-sized (indefinite) flex container falls back
+    // to CONTENT sizing per the flexbox spec, whereas `flex-basis:0` (definite zero) gives a zero base
+    // size — collapsing a `flex:1 1 0%` item to 0 in an auto-height column. `height`/`min-height` in %
+    // resolve to `auto` when the containing block's height is indefinite, the same hazard. So never
+    // rewrite `[0%]` to the definite `-0` for these prefixes; keep the literal `basis-[0%]`/`h-[0%]`.
+    // (Width/inset percentages resolve against the always-definite containing-block WIDTH — safe.)
+    if (v === 0 && (pm[1] === "basis" || pm[1] === "h" || pm[1] === "min-h")) return base;
     const frac = FRACTIONS.find(([p]) => Math.abs(p - v) < 0.4);
     return frac ? `${pm[1]}-${frac[1]}` : base;
   }
diff --git a/compiler/src/validate/gates.ts b/compiler/src/validate/gates.ts
index 8796af8..95def8c 100644
--- a/compiler/src/validate/gates.ts
+++ b/compiler/src/validate/gates.ts
@@ -346,7 +346,10 @@ export function gate4Style(ir: IR, genSnaps: Record<number, PageSnapshot>, viewp
         // equal, only numerically far apart. Treat any two such large radii as equivalent so the
         // idiomatic `rounded-full` doesn't trip the exact-px compare; real radii stay ±2px.
         if (p === "borderTopLeftRadius" && pxNum(s.computed[p] ?? "") >= PILL_PX && pxNum(g.computed[p] ?? "") >= PILL_PX) continue;
-        if (!cmpNum(s.computed[p], g.computed[p], 2, 0)) { nodeOk = false; fails.push(p); }
+        const eq = p === "letterSpacing"
+          ? letterSpacingEquivalent(s.computed[p], g.computed[p])
+          : cmpNum(s.computed[p], g.computed[p], 2, 0);
+        if (!eq) { nodeOk = false; fails.push(p); }
       }
       for (const p of PX4_PROPS) {
         // `gap: normal` is the initial value and resolves to 0 for flex/grid, so it
@@ -405,6 +408,19 @@ function cmpNum(a: string | undefined, b: string | undefined, abs: number, pct:
   return withinAbs(na, nb, abs) || (pct > 0 && withinPct(na, nb, pct));
 }
 
+/** Compare two computed `letter-spacing` values within the ±2px style tolerance, treating the keyword
+ *  `normal` as `0px`. `letter-spacing: normal` is the initial value and adds no extra spacing (it
+ *  computes to 0), so `normal` ≡ `0px`; crucially, Chromium serializes a computed `letter-spacing: 0`
+ *  BACK as the keyword `normal`, so a genuinely-zero (or sub-0.1px, snapped-to-zero) tracking shows up
+ *  as `normal` on one side and `0px` on the other — a spelling difference that `cmpNum` alone reads as
+ *  a NaN → exact-string mismatch. Normalizing the keyword before the numeric compare removes that false
+ *  failure while a real tracking delta (> 2px) still fails. Mirrors the `gap: normal → 0px` handling. */
+export function letterSpacingEquivalent(a: string | undefined, b: string | undefined): boolean {
+  if (a === undefined) return true;
+  const norm = (v: string | undefined): string => (v ?? "").replace(/\bnormal\b/g, "0px");
+  return cmpNum(norm(a), norm(b), 2, 0);
+}
+
 // ---------- Gate 5: layout / section equivalence ----------
 export function gate5Layout(ir: IR, genSnaps: Record<number, PageSnapshot>, sections: Section[], viewports: number[], reflow = false): GateResult {
   const issues: string[] = [];
diff --git a/compiler/src/validate/render.ts b/compiler/src/validate/render.ts
index 8848e61..4502418 100644
--- a/compiler/src/validate/render.ts
+++ b/compiler/src/validate/render.ts
@@ -5,7 +5,7 @@ import { join, extname, normalize } from "node:path";
 import { spawnSync } from "node:child_process";
 import { chromium } from "playwright";
 import { collectPage, type PageSnapshot } from "../capture/walker.js";
-import { captureFullPageViaCDP } from "../capture/capture.js";
+import { captureFullPageViaCDP, normalizeVideoTime } from "../capture/capture.js";
 import { ensureDir, writeJSONCompact } from "../util/fsx.js";
 
 const ESBUILD_SHIM =
@@ -262,6 +262,11 @@ export async function renderApp(opts: {
         // matters less here, but symmetric capture is the requirement.
         try {
           const shotPath = join(opts.renderedDir, "screenshots", `${vw}.png`);
+          // Pin every clone-side <video> to frame 0 (paused) before the shot — the SOURCE channel is
+          // now normalized to frame 0 at every viewport too, so both sides show the same frame and a
+          // video's playback time can't manufacture a perceptual diff. (The static clone rarely plays,
+          // but a replayed/autoplaying video would otherwise drift; symmetric normalization is the rule.)
+          await normalizeVideoTime(page);
           try {
             await captureFullPageViaCDP(page, shotPath);
           } catch {
diff --git a/compiler/test/css.test.ts b/compiler/test/css.test.ts
index b190801..0d0c47e 100644
--- a/compiler/test/css.test.ts
+++ b/compiler/test/css.test.ts
@@ -388,6 +388,32 @@ describe("generateCss literal-margin vs auto-centring", () => {
     const all = allRulesX(css, "n1");
     assert.ok(/margin-left:auto/.test(all), `a constrained centred block should still auto-centre, got: ${all}`);
   });
+
+  // A centred `max-width` container whose cap is FLUID — `max-width: min(1272px, 100vw − 2·gutter)`
+  // resolves to a DIFFERENT px at every width (311/673/1145). The block is centred at every sample
+  // (symmetric positive gaps that scale with width). It must auto-centre (`mx-auto`) with per-band
+  // caps, NOT freeze to literal per-band `margin-left` (which pins it left at non-captured widths).
+  it("auto-centres a container with a per-viewport (fluid) max-width cap", () => {
+    // border-box block, max-width per vp, box width == cap, symmetric gaps everywhere.
+    const child = xNode("n1", "div", {
+      375: { cs: { display: "block", boxSizing: "border-box", maxWidth: "311px", marginLeft: "0px", marginRight: "0px", width: "311px" }, bbox: { x: 32, y: 0, width: 311, height: 200 } },
+      768: { cs: { display: "block", boxSizing: "border-box", maxWidth: "673.2px", marginLeft: "0px", marginRight: "0px", width: "673.2px" }, bbox: { x: 47.4, y: 0, width: 673.2, height: 200 } },
+      1280: { cs: { display: "block", boxSizing: "border-box", maxWidth: "1145.08px", marginLeft: "0px", marginRight: "0px", width: "1145.08px" }, bbox: { x: 67.46, y: 0, width: 1145.08, height: 200 } },
+    });
+    const parent = xNode("n0", "body", {
+      375: { cs: { display: "block" }, bbox: { x: 0, y: 0, width: 375, height: 200 } },
+      768: { cs: { display: "block" }, bbox: { x: 0, y: 0, width: 768, height: 200 } },
+      1280: { cs: { display: "block" }, bbox: { x: 0, y: 0, width: 1280, height: 200 } },
+    }, [child]);
+    const css = generateCss(xIr(parent), new Map());
+    const all = allRulesX(css, "n1");
+    assert.ok(/margin-left:auto/.test(all), `fluid-cap centred container must auto-centre, got: ${all}`);
+    assert.ok(!/margin-left:0?67|margin-left:32px|margin-left:47/.test(all), `must NOT bake literal per-band left margins, got: ${all}`);
+    // The per-viewport caps survive as banded max-width (the canonical 1145.08 at base, others banded).
+    assert.ok(baseRule(css, "n1").includes("max-width:1145.08px"), `base carries the canonical cap, got: ${baseRule(css, "n1")}`);
+    const mobile = xBandRule(css, /^\(max-width/, "n1");
+    assert.ok(/max-width:311px/.test(mobile), `mobile band carries its own fluid cap, got: ${mobile}`);
+  });
 });
 
 // BUG C — a single-line text leaf whose unwrapped width nearly fills its column at every width gets
diff --git a/compiler/test/gates.test.ts b/compiler/test/gates.test.ts
new file mode 100644
index 0000000..311bcda
--- /dev/null
+++ b/compiler/test/gates.test.ts
@@ -0,0 +1,38 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { letterSpacingEquivalent } from "../src/validate/gates.js";
+
+// Chromium serializes a computed `letter-spacing: 0` back as the keyword `normal`. The emitter, after
+// snapping a sub-0.1px authored tracking to 0, ships `letter-spacing: 0px` — which the CLONE then
+// reports as `normal` too, but a source that authored an explicit near-zero px can land on either
+// spelling. Gate 4 must treat `normal` and `0px` as equal, or every such node fails on spelling alone.
+describe("gate4 letterSpacing normal ↔ 0px normalization", () => {
+  it("treats `normal` and `0px` as equivalent", () => {
+    assert.ok(letterSpacingEquivalent("normal", "0px"));
+    assert.ok(letterSpacingEquivalent("0px", "normal"));
+  });
+
+  it("treats `normal` and `normal` as equivalent", () => {
+    assert.ok(letterSpacingEquivalent("normal", "normal"));
+  });
+
+  it("treats a sub-2px authored tracking vs `normal` as equivalent (within ±2px)", () => {
+    // source computed `-0.08px`, clone serialized `normal` — a 0.08px delta, well within tolerance.
+    assert.ok(letterSpacingEquivalent("-0.08px", "normal"));
+    assert.ok(letterSpacingEquivalent("normal", "-0.0375px"));
+  });
+
+  it("still equates two close real px values (−0.24px vs −0.2px)", () => {
+    assert.ok(letterSpacingEquivalent("-0.24px", "-0.2px"));
+  });
+
+  it("still FAILS a genuine tracking difference beyond ±2px", () => {
+    assert.ok(!letterSpacingEquivalent("4px", "normal"));
+    assert.ok(!letterSpacingEquivalent("normal", "-3px"));
+    assert.ok(!letterSpacingEquivalent("6px", "2px"));
+  });
+
+  it("passes when the source did not constrain the property (undefined)", () => {
+    assert.ok(letterSpacingEquivalent(undefined, "0px"));
+  });
+});
diff --git a/compiler/test/tailwind.test.ts b/compiler/test/tailwind.test.ts
index 141d741..9f5721f 100644
--- a/compiler/test/tailwind.test.ts
+++ b/compiler/test/tailwind.test.ts
@@ -1,6 +1,6 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { declToUtil, snapBase } from "../src/generate/tailwind.js";
+import { declToUtil, snapBase, prettifyBase, collapseBases } from "../src/generate/tailwind.js";
 
 // Zero-value gating. A named `-0` step only exists for props on Tailwind's spacing (or numeric)
 // scales; for the rest the class compiles to NOTHING — a silent no-op that ships the wrong style
@@ -71,3 +71,65 @@ describe("snapBase spacing-scale snapping", () => {
     assert.equal(snapBase("mx-[16px]"), "mx-4");
   });
 });
+
+// A percentage 0 on a MAIN-SIZE axis (flex-basis) or a %-of-indefinite-height axis (height/min-height)
+// is NOT the definite zero `-0`: `flex-basis:0%` content-sizes against an auto-sized flex container,
+// whereas `flex-basis:0` gives a zero base size (collapsing a `flex:1 1 0%` item in an auto-height
+// column). prettifyBase must keep those literal. Width/inset 0% resolve against the definite
+// containing-block width, so their `-0` rewrite stays.
+describe("prettifyBase 0% on indefinite-axis prefixes", () => {
+  it("keeps basis-[0%] literal (0% ≠ definite 0 for flex-basis)", () => {
+    assert.equal(prettifyBase("basis-[0%]"), "basis-[0%]");
+  });
+  it("keeps h-[0%] and min-h-[0%] literal (%-of-indefinite-height → auto)", () => {
+    assert.equal(prettifyBase("h-[0%]"), "h-[0%]");
+    assert.equal(prettifyBase("min-h-[0%]"), "min-h-[0%]");
+  });
+  it("still rewrites width/inset 0% to the definite -0 (definite containing-block width)", () => {
+    assert.equal(prettifyBase("w-[0%]"), "w-0");
+    assert.equal(prettifyBase("min-w-[0%]"), "min-w-0");
+    assert.equal(prettifyBase("left-[0%]"), "left-0");
+    assert.equal(prettifyBase("inset-x-[0%]"), "inset-x-0");
+  });
+  it("still rewrites non-zero fractions on every prefix (basis-[33.3333%] → basis-1/3)", () => {
+    assert.equal(prettifyBase("basis-[33.3333%]"), "basis-1/3");
+    assert.equal(prettifyBase("h-[50%]"), "h-1/2");
+    assert.equal(prettifyBase("min-h-[100%]"), "min-h-full");
+  });
+});
+
+// flex:1 1 0% is Tailwind's `flex-1` — fold the grow-[1] + zero-basis pair so the emitted class both
+// reads idiomatically AND resolves to the exact flex longhands (avoiding the basis-[0%] hazard).
+describe("collapseBases flex-1 folding", () => {
+  it("folds grow-[1] + basis-[0%] → flex-1 (shrink defaults to 1, elided)", () => {
+    assert.deepEqual(collapseBases(["grow-[1]", "basis-[0%]"]), ["flex-1"]);
+  });
+  it("folds grow-[1] + basis-0 (already-shortened band delta) → flex-1", () => {
+    assert.deepEqual(collapseBases(["grow-[1]", "basis-0"]), ["flex-1"]);
+  });
+  it("does NOT fold when shrink-0 is present (flex:1 0 0% ≠ flex-1)", () => {
+    assert.deepEqual(collapseBases(["grow-[1]", "shrink-0", "basis-[0%]"]).sort(), ["basis-[0%]", "grow-[1]", "shrink-0"]);
+  });
+  it("does NOT fold a non-zero basis (grow-[1] + basis-[50%] left as-is)", () => {
+    assert.deepEqual(collapseBases(["grow-[1]", "basis-[50%]"]).sort(), ["basis-[50%]", "grow-[1]"]);
+  });
+});
+
+// letter-spacing is authored at a finer scale than box lengths; a real -0.08px tracking is within
+// snapLen's 0.1px integer-snap window and would collapse to 0px → Chromium serializes it as `normal`
+// → a false style-gate mismatch. Tracking must skip the integer snap (snapBase keeps 2 decimals).
+describe("declToUtil letter-spacing sub-0.1px preservation", () => {
+  it("keeps a real -0.08px tracking (does NOT snap to tracking-[0px])", () => {
+    assert.equal(declToUtil("letter-spacing", "-0.08px"), "tracking-[-0.08px]");
+  });
+  it("keeps -0.0375px through declToUtil, then snapBase rounds to 2 decimals (not to zero)", () => {
+    assert.equal(declToUtil("letter-spacing", "-0.0375px"), "tracking-[-0.0375px]");
+    assert.equal(snapBase("tracking-[-0.0375px]"), "tracking-[-0.04px]");
+  });
+  it("still keeps a genuine zero as tracking-[0px]", () => {
+    assert.equal(declToUtil("letter-spacing", "0px"), "tracking-[0px]");
+  });
+  it("still integer-snaps a BOX length near an integer (204.9994px → 205px)", () => {
+    assert.equal(declToUtil("width", "204.9994px"), "w-[205px]");
+  });
+});

From 23505ee229b972b1fe66230d6c40c62d26cee003 Mon Sep 17 00:00:00 2001
From: Samraaj Bath <samraaj100@gmail.com>
Date: Sat, 4 Jul 2026 01:26:22 -0700
Subject: [PATCH 08/24] Validation server: HTTP Range support, bounded settle,
 crash-proof reporting

- serveStatic answers single-range requests with proper 206/Content-Range
  (416 for unsatisfiable), so Chromium streams large media in bounded
  chunks instead of holding one throttled progressive request open past
  the navigation budget
- goto policy: waitUntil "load" + up to 10s of sustained-quiet polling
  replaces the hard networkidle timeout - long autoplaying media can no
  longer make validation unreachable (applied to renderApp, probe widths,
  and the interaction gate)
- validateRun catches render crashes and records them as runtime errors,
  so a failed render writes a report with a failed gate 0 instead of
  crashing reportless

292 tests pass (14 new), typecheck clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 compiler/src/validate/interactionGate.ts |   6 +-
 compiler/src/validate/render.ts          | 122 ++++++++++++++++++++++-
 compiler/src/validate/validate.ts        |   7 ++
 compiler/test/serveRange.test.ts         | 118 ++++++++++++++++++++++
 4 files changed, 249 insertions(+), 4 deletions(-)
 create mode 100644 compiler/test/serveRange.test.ts

diff --git a/compiler/src/validate/interactionGate.ts b/compiler/src/validate/interactionGate.ts
index 50db554..a34305d 100644
--- a/compiler/src/validate/interactionGate.ts
+++ b/compiler/src/validate/interactionGate.ts
@@ -4,6 +4,7 @@ import type { InteractionCapture } from "../capture/interactions.js";
 import { buildRuntimeSpecs, specKey } from "../generate/interactive.js";
 import { buildMenuSpecs } from "../generate/menu.js";
 import type { GateResult } from "./gates.js";
+import { gotoAndSettle } from "./render.js";
 
 /**
  * Stage 4 interaction gate. Drives the SAME interactions in the built clone that
@@ -61,7 +62,10 @@ export async function driveInteractionGate(opts: {
     const ctx = await browser.newContext({ viewport: { width: vp, height: vh }, deviceScaleFactor: 1 });
     const page = await ctx.newPage();
     await page.addInitScript("globalThis.__name = globalThis.__name || ((fn) => fn);");
-    await page.goto(url, { waitUntil: "networkidle", timeout: 45000 });
+    // `load` + bounded network-quiet wait (not strict `networkidle`) so an autoplaying
+    // long hero video — which keeps issuing bounded range fetches — can't make navigation
+    // time out and fail the interaction gate before any interaction is even driven.
+    await gotoAndSettle(page, url);
     await page.waitForTimeout(300);
 
     const styleOf = (cid: string, props: string[]): Promise<Record<string, string> | null> =>
diff --git a/compiler/src/validate/render.ts b/compiler/src/validate/render.ts
index 4502418..aabfa57 100644
--- a/compiler/src/validate/render.ts
+++ b/compiler/src/validate/render.ts
@@ -146,6 +146,50 @@ async function readLimited(p: string): Promise<Buffer> {
   }
 }
 
+/** Result of interpreting a `Range` header against a known resource size.
+ *  - `kind: "full"`  → no (usable) Range header; answer with a normal 200 full body.
+ *  - `kind: "range"` → a single satisfiable `bytes=start-end`; answer 206 with [start,end].
+ *  - `kind: "unsatisfiable"` → a syntactically valid range wholly past EOF; answer 416. */
+export type RangeResolution =
+  | { kind: "full" }
+  | { kind: "range"; start: number; end: number }
+  | { kind: "unsatisfiable" };
+
+/** Parse a single-range HTTP `Range` header ("bytes=start-end", "bytes=start-",
+ *  "bytes=-suffix") against a resource of `size` bytes. Multi-range ("a-b,c-d") is
+ *  intentionally collapsed to a full 200 (Chromium's media element only ever asks for a
+ *  single range, and RFC 7233 lets a server ignore Range and reply 200). Anything the
+ *  spec calls malformed (missing "bytes=", non-numeric, inverted, both bounds empty) is
+ *  also treated as "full" — the safe fallback. A well-formed range that starts at or past
+ *  EOF is "unsatisfiable" → 416. `end` is inclusive and clamped to size-1. */
+export function parseRangeHeader(header: string | undefined, size: number): RangeResolution {
+  if (!header) return { kind: "full" };
+  const m = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+  if (!m) return { kind: "full" }; // absent/malformed/multi-range → serve full body
+  const startStr = m[1]!;
+  const endStr = m[2]!;
+  if (startStr === "" && endStr === "") return { kind: "full" }; // "bytes=-" is malformed
+  if (size <= 0) return { kind: "unsatisfiable" };
+  let start: number;
+  let end: number;
+  if (startStr === "") {
+    // Suffix range: "bytes=-N" → last N bytes.
+    const suffix = Number(endStr);
+    if (!Number.isFinite(suffix) || suffix <= 0) return { kind: "full" };
+    start = Math.max(0, size - suffix);
+    end = size - 1;
+  } else {
+    start = Number(startStr);
+    if (!Number.isFinite(start)) return { kind: "full" };
+    if (start >= size) return { kind: "unsatisfiable" }; // start past EOF
+    end = endStr === "" ? size - 1 : Number(endStr);
+    if (!Number.isFinite(end)) return { kind: "full" };
+    if (end < start) return { kind: "full" }; // inverted → ignore Range
+    end = Math.min(end, size - 1);
+  }
+  return { kind: "range", start, end };
+}
+
 export function serveStatic(rootDir: string): Promise<{ url: string; close: () => Promise<void> }> {
   const server: Server = createServer(async (req, res) => {
     try {
@@ -168,8 +212,32 @@ export function serveStatic(rootDir: string): Promise<{ url: string; close: () =
         if (existsSync(fallback)) { res.writeHead(404, { "content-type": "text/html" }); res.end(await readLimited(fallback)); return; }
         res.writeHead(404); res.end("not found"); return;
       }
+      const contentType = CONTENT_TYPES[extname(filePath).toLowerCase()] ?? "application/octet-stream";
+      const size = statSync(filePath).size;
+      // HTTP Range support (RFC 7233). Chromium requests <video>/<audio> with `Range: bytes=0-`
+      // and, absent a 206, holds the single progressive stream open throttled to playback — a
+      // long autoplay hero (76s) then means `waitUntil:"networkidle"` can mathematically never
+      // fire. Answering 206 with bounded chunks lets Chromium fetch in pieces so the network
+      // goes idle between reads. A HEAD-style range far past EOF gets a 416.
+      const range = parseRangeHeader(req.headers.range as string | undefined, size);
+      if (range.kind === "unsatisfiable") {
+        res.writeHead(416, { "content-type": contentType, "content-range": `bytes */${size}`, "accept-ranges": "bytes" });
+        res.end();
+        return;
+      }
       const data = await readLimited(filePath);
-      res.writeHead(200, { "content-type": CONTENT_TYPES[extname(filePath).toLowerCase()] ?? "application/octet-stream" });
+      if (range.kind === "range") {
+        const chunk = data.subarray(range.start, range.end + 1);
+        res.writeHead(206, {
+          "content-type": contentType,
+          "content-range": `bytes ${range.start}-${range.end}/${size}`,
+          "accept-ranges": "bytes",
+          "content-length": String(chunk.length),
+        });
+        res.end(chunk);
+        return;
+      }
+      res.writeHead(200, { "content-type": contentType, "accept-ranges": "bytes", "content-length": String(data.length) });
       res.end(data);
     } catch {
       res.writeHead(500); res.end("error");
@@ -194,6 +262,54 @@ export type RenderResult = {
   failedResources: string[];
 };
 
+/** Navigate with `waitUntil:"load"` then wait for a bounded window of network quiet, so
+ *  validation NEVER hard-fails on media that trickles requests. `waitUntil:"networkidle"`
+ *  is a hard timeout: an autoplaying long video (even chunked via 206) keeps issuing bounded
+ *  range fetches, so a strict networkidle can miss its 500ms-idle window and throw at 45s,
+ *  leaving validation reportless. Instead we (1) `goto load` (fires on DOM+subresources, not
+ *  on ongoing media), then (2) poll for `maxQuietMs` of 500ms network silence up to a
+ *  `settleCapMs` ceiling, then proceed regardless. Normal pages reach quiet in well under a
+ *  second, so total time stays comparable; only trickle-media pages spend the extra budget and
+ *  then continue (the video is frame-0-normalized before the screenshot, so determinism holds).
+ *  Returns the goto response (for httpStatus). */
+export async function gotoAndSettle(
+  page: import("playwright").Page,
+  url: string,
+  opts?: { gotoTimeout?: number; settleCapMs?: number; quietMs?: number; pollMs?: number },
+): Promise<import("playwright").Response | null> {
+  const gotoTimeout = opts?.gotoTimeout ?? 45000;
+  const settleCapMs = opts?.settleCapMs ?? 10000;
+  const quietMs = opts?.quietMs ?? 500;
+  const pollMs = opts?.pollMs ?? 500;
+  const resp = await page.goto(url, { waitUntil: "load", timeout: gotoTimeout });
+  // Count in-flight requests so we can detect network quiet without relying on the
+  // strict networkidle heuristic (which throws on trickle-media).
+  let inflight = 0;
+  const onReq = (): void => { inflight++; };
+  const onDone = (): void => { inflight = Math.max(0, inflight - 1); };
+  page.on("request", onReq);
+  page.on("requestfinished", onDone);
+  page.on("requestfailed", onDone);
+  try {
+    const deadline = Date.now() + settleCapMs;
+    let quietSince = inflight === 0 ? Date.now() : 0;
+    while (Date.now() < deadline) {
+      if (inflight === 0) {
+        if (quietSince === 0) quietSince = Date.now();
+        if (Date.now() - quietSince >= quietMs) break; // sustained quiet reached
+      } else {
+        quietSince = 0;
+      }
+      await new Promise((r) => setTimeout(r, pollMs));
+    }
+  } finally {
+    page.off("request", onReq);
+    page.off("requestfinished", onDone);
+    page.off("requestfailed", onDone);
+  }
+  return resp;
+}
+
 async function mapLimit<T, R>(items: T[], limit: number, fn: (item: T, i: number) => Promise<R>): Promise<R[]> {
   const out: R[] = new Array(items.length);
   let next = 0;
@@ -227,7 +343,7 @@ export async function renderApp(opts: {
         page.on("pageerror", (e) => runtimeErrors.push(String(e)));
         page.on("response", (r) => { if (r.status() >= 400) failedResources.add(`${r.status()} ${r.url()}`); });
         page.on("requestfailed", (r) => failedResources.add(`failed ${r.url()}`));
-        const resp = await page.goto(opts.url, { waitUntil: "networkidle", timeout: 45000 });
+        const resp = await gotoAndSettle(page, opts.url);
         if (resp) httpStatus = resp.status();
         try { await page.evaluate(() => (document as Document).fonts?.ready); } catch { /* ignore */ }
         // Scroll to settle any lazy effects, then back to top.
@@ -308,7 +424,7 @@ export async function measureProbeWidths(opts: { url: string; widths: number[] }
         const ctx = await browser.newContext({ ignoreHTTPSErrors: true, viewport: { width: w, height: viewportHeight(w) }, deviceScaleFactor: 1 });
         const page = await ctx.newPage();
         await page.addInitScript(ESBUILD_SHIM);
-        await page.goto(opts.url, { waitUntil: "networkidle", timeout: 45000 });
+        await gotoAndSettle(page, opts.url);
         try { await page.evaluate(() => (document as Document).fonts?.ready); } catch { /* ignore */ }
         await page.evaluate(() => {
           const win = window as unknown as { __dittoMotionStopped?: boolean; __dittoMotionStop?: () => void };
diff --git a/compiler/src/validate/validate.ts b/compiler/src/validate/validate.ts
index 7e173db..0be55b4 100644
--- a/compiler/src/validate/validate.ts
+++ b/compiler/src/validate/validate.ts
@@ -122,6 +122,13 @@ export async function validateRun(runDir: string, opts?: { harnessDir?: string;
         motionGate = await driveMotionGate({ url: server.url + "/", viewports, ir, motion: capture.motion });
         log({ event: "motion_gate", pass: motionGate.pass, metrics: motionGate.metrics });
       }
+    } catch (e) {
+      // A render crash (e.g. a page.goto timeout on trickling media, or a Playwright fault)
+      // must NOT escape reportless — otherwise validation/ stays empty and the run looks
+      // un-validated. Record the error as a runtime error so httpStatus stays 0, gate 0 fails
+      // with a visible issue, and the normal downstream path writes report.json as usual.
+      runtimeErrors.push(`render error: ${e instanceof Error ? e.message : String(e)}`);
+      log({ event: "render_error", error: e instanceof Error ? e.message : String(e) });
     } finally {
       await server.close();
     }
diff --git a/compiler/test/serveRange.test.ts b/compiler/test/serveRange.test.ts
new file mode 100644
index 0000000..6bb6ee0
--- /dev/null
+++ b/compiler/test/serveRange.test.ts
@@ -0,0 +1,118 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { serveStatic, parseRangeHeader } from "../src/validate/render.js";
+
+// ---- Pure helper: parseRangeHeader ----
+describe("parseRangeHeader", () => {
+  const SIZE = 1000;
+
+  it("no header → full 200", () => {
+    assert.deepEqual(parseRangeHeader(undefined, SIZE), { kind: "full" });
+    assert.deepEqual(parseRangeHeader("", SIZE), { kind: "full" });
+  });
+
+  it("bytes=0- (Chromium's open-ended media probe) → whole file as a range", () => {
+    assert.deepEqual(parseRangeHeader("bytes=0-", SIZE), { kind: "range", start: 0, end: 999 });
+  });
+
+  it("bounded range bytes=100-199 → [100,199] inclusive", () => {
+    assert.deepEqual(parseRangeHeader("bytes=100-199", SIZE), { kind: "range", start: 100, end: 199 });
+  });
+
+  it("end past EOF is clamped to size-1", () => {
+    assert.deepEqual(parseRangeHeader("bytes=900-5000", SIZE), { kind: "range", start: 900, end: 999 });
+  });
+
+  it("suffix range bytes=-100 → last 100 bytes", () => {
+    assert.deepEqual(parseRangeHeader("bytes=-100", SIZE), { kind: "range", start: 900, end: 999 });
+  });
+
+  it("suffix larger than file → whole file", () => {
+    assert.deepEqual(parseRangeHeader("bytes=-5000", SIZE), { kind: "range", start: 0, end: 999 });
+  });
+
+  it("start at or past EOF → unsatisfiable (416)", () => {
+    assert.deepEqual(parseRangeHeader("bytes=1000-", SIZE), { kind: "unsatisfiable" });
+    assert.deepEqual(parseRangeHeader("bytes=2000-3000", SIZE), { kind: "unsatisfiable" });
+  });
+
+  it("zero-length resource → unsatisfiable for any range", () => {
+    assert.deepEqual(parseRangeHeader("bytes=0-", 0), { kind: "unsatisfiable" });
+  });
+
+  it("malformed / multi-range / inverted → full (safe fallback, never throws)", () => {
+    assert.deepEqual(parseRangeHeader("bytes=abc-def", SIZE), { kind: "full" });
+    assert.deepEqual(parseRangeHeader("items=0-10", SIZE), { kind: "full" });
+    assert.deepEqual(parseRangeHeader("bytes=0-10,20-30", SIZE), { kind: "full" }); // multi-range collapsed
+    assert.deepEqual(parseRangeHeader("bytes=-", SIZE), { kind: "full" });
+    assert.deepEqual(parseRangeHeader("bytes=500-100", SIZE), { kind: "full" }); // inverted
+  });
+});
+
+// ---- Integration: serveStatic answers real Range requests with 206/416 ----
+describe("serveStatic Range support (integration)", () => {
+  let rootDir = "";
+  let base = "";
+  let close: (() => Promise<void>) | null = null;
+  const BODY = Buffer.alloc(5000, 0x41); // 5000 'A' bytes stands in for a media file
+
+  before(async () => {
+    rootDir = mkdtempSync(join(tmpdir(), "ditto-serve-"));
+    mkdirSync(join(rootDir, "assets"), { recursive: true });
+    writeFileSync(join(rootDir, "assets", "hero.webm"), BODY);
+    writeFileSync(join(rootDir, "index.html"), "<!doctype html><html><body>ok</body></html>");
+    const s = await serveStatic(rootDir);
+    base = s.url;
+    close = s.close;
+  });
+
+  after(async () => {
+    await close?.();
+    rmSync(rootDir, { recursive: true, force: true });
+  });
+
+  it("open-ended Range bytes=0- → 206 with a bounded body + Content-Range/Accept-Ranges", async () => {
+    const res = await fetch(base + "/assets/hero.webm", { headers: { Range: "bytes=0-" } });
+    assert.equal(res.status, 206);
+    assert.equal(res.headers.get("accept-ranges"), "bytes");
+    assert.equal(res.headers.get("content-range"), `bytes 0-4999/5000`);
+    assert.equal(res.headers.get("content-type"), "video/webm");
+    const buf = Buffer.from(await res.arrayBuffer());
+    assert.equal(buf.length, 5000);
+  });
+
+  it("bounded Range bytes=100-199 → 206 returning exactly those 100 bytes", async () => {
+    const res = await fetch(base + "/assets/hero.webm", { headers: { Range: "bytes=100-199" } });
+    assert.equal(res.status, 206);
+    assert.equal(res.headers.get("content-range"), `bytes 100-199/5000`);
+    const buf = Buffer.from(await res.arrayBuffer());
+    assert.equal(buf.length, 100);
+    assert.ok(buf.equals(BODY.subarray(100, 200)));
+  });
+
+  it("Range past EOF → 416 with Content-Range: bytes */size", async () => {
+    const res = await fetch(base + "/assets/hero.webm", { headers: { Range: "bytes=9000-" } });
+    assert.equal(res.status, 416);
+    assert.equal(res.headers.get("content-range"), `bytes */5000`);
+    // Drain the (empty) body so the socket is released.
+    await res.arrayBuffer();
+  });
+
+  it("no Range header → full 200 with Accept-Ranges advertised", async () => {
+    const res = await fetch(base + "/assets/hero.webm");
+    assert.equal(res.status, 200);
+    assert.equal(res.headers.get("accept-ranges"), "bytes");
+    const buf = Buffer.from(await res.arrayBuffer());
+    assert.equal(buf.length, 5000);
+  });
+
+  it("HTML routes still serve a normal 200 (Range logic doesn't disturb pages)", async () => {
+    const res = await fetch(base + "/");
+    assert.equal(res.status, 200);
+    const text = await res.text();
+    assert.match(text, /<body>ok<\/body>/);
+  });
+});

From 0dd71a68d9e83a2dd21861dbfa56937509792e39 Mon Sep 17 00:00:00 2001
From: Samraaj Bath <samraaj100@gmail.com>
Date: Sat, 4 Jul 2026 01:44:12 -0700
Subject: [PATCH 09/24] Popup dismissal hardening: shadow roots, overlay units,
 scroll-lock recovery

- Overlay detection resolves effective z-index through stacking ancestors,
  treats a zero-size max-z wrapper plus its full-viewport descendant as one
  removable unit, pierces open shadow roots, and relaxes the z floor when
  the page is scroll-locked; a lock persisting after dismissal reports
  blocking even with no detected overlay
- clickDismiss runs in every frame (close buttons live in cross-origin
  popup iframes), matches decline/no-thanks/aria-label close affordances,
  and re-runs before every snapshot AND screenshot to catch late-mounting
  dialogs
- rootUnclamp triggers from IR content extent (a scroll-lock collapses
  captured scrollHeight) and strips vendor-injected body position/overflow
  locks when firing
- Pollution gate fails on the scroll-lock contradiction: scrollHeight
  pinned to one viewport while IR content spans multiple
- Frame graft skips popup-creative vendor hosts; inline embedded signup
  forms remain graftable (regression-tested)

322 tests pass (24 new), typecheck clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 compiler/src/capture/capture.ts      | 373 +++++++++++++++++++--------
 compiler/src/capture/graft.ts        |   8 +-
 compiler/src/generate/css.ts         |  34 ++-
 compiler/src/normalize/ir.ts         |  42 +++
 compiler/src/validate/gates.ts       |  25 +-
 compiler/test/css.test.ts            |  36 +++
 compiler/test/iframeGraft.test.ts    |  17 ++
 compiler/test/irPrune.test.ts        |  28 ++
 compiler/test/overlayDismiss.test.ts | 311 ++++++++++++++++++++++
 9 files changed, 759 insertions(+), 115 deletions(-)
 create mode 100644 compiler/test/overlayDismiss.test.ts

diff --git a/compiler/src/capture/capture.ts b/compiler/src/capture/capture.ts
index 1f71d2f..6a4753f 100644
--- a/compiler/src/capture/capture.ts
+++ b/compiler/src/capture/capture.ts
@@ -261,64 +261,102 @@ export type DismissResult = { dismissed: string[]; overlaysRemaining: number; re
  * Removal of a stuck overlay happens later (finalizeOverlays) AFTER a settle, so a
  * just-clicked dialog has time to close and unlock scrolling before we judge it.
  */
+/**
+ * In-page dismissal click pass (exported for fixture tests). Runs in ONE document — the main
+ * page OR a cross-origin frame (Attentive/Recart/Klaviyo creatives host their Decline/× inside
+ * an iframe, so the caller runs this in every `page.frames()`). Traverses open shadow roots
+ * (Recart mounts its popup in a shadow tree) when scanning both containers and buttons.
+ */
+export function clickDismissInPage(): string[] {
+  const dismissed: string[] = [];
+  // Deep collector across open shadow roots.
+  const deepEls = (root: ParentNode, sel: string): Element[] => {
+    const out: Element[] = [];
+    const walk = (r: ParentNode): void => {
+      let hits: Element[] = [];
+      try { hits = Array.from(r.querySelectorAll(sel)); } catch { /* invalid selector */ }
+      out.push(...hits);
+      for (const el of Array.from(r.querySelectorAll("*"))) {
+        const sr = (el as HTMLElement).shadowRoot;
+        if (sr) walk(sr);
+      }
+    };
+    walk(root);
+    return out;
+  };
+  const vis = (el: Element): boolean => {
+    const cs = getComputedStyle(el);
+    if (cs.display === "none" || cs.visibility === "hidden" || parseFloat(cs.opacity || "1") === 0) return false;
+    const r = (el as HTMLElement).getBoundingClientRect();
+    return r.width > 0 && r.height > 0;
+  };
+  const click = (el: Element): void => { try { (el as HTMLElement).click(); } catch { /* ignore */ } };
+
+  // 1) Known consent-framework / generic close affordances, in priority order.
+  const KNOWN = [
+    "#onetrust-accept-btn-handler", "#accept-recommended-btn-handler", ".onetrust-close-btn-handler",
+    "#CybotCookiebotDialogBodyLevelButtonLevelOptinAllowAll", "#CybotCookiebotDialogBodyButtonAccept",
+    "#truste-consent-button", ".osano-cm-accept-all", ".osano-cm-dialog__close",
+    "[data-testid='uc-accept-all-button']", "[data-testid='uc-deny-all-button']",
+    "#didomi-notice-agree-button", ".didomi-continue-without-agreeing",
+    ".qc-cmp2-summary-buttons button[mode='primary']", "button[aria-label='Consent']",
+    ".cc-allow", ".cookie-consent-accept", "#hs-eu-confirmation-button", "#gdpr-consent-tool-wrapper button",
+  ];
+  for (const sel of KNOWN) {
+    for (const el of deepEls(document, sel)) {
+      if (vis(el)) { click(el); dismissed.push(sel); break; }
+    }
+  }
+
+  // 2) Scoped text-button pass: only inside overlay-ish containers (dialogs, or id/class naming
+  //    cookie/consent/modal/popup/newsletter/overlay/ccpa/privacy) so we never click an ordinary
+  //    page button. ACCEPT now also covers email-capture DECLINE affordances ("decline",
+  //    "no thanks", "not now", …) — a popup's own opt-out is the surest deterministic close.
+  const ACCEPT = new Set([
+    "accept", "accept all", "accept all cookies", "accept cookies", "accept & close",
+    "i accept", "i agree", "agree", "agree and continue", "allow all", "allow cookies",
+    "allow all cookies", "got it", "ok", "okay", "continue", "no thanks", "no, thanks",
+    "dismiss", "close", "got it!", "understood", "yes, i agree",
+    "decline", "no, thank you", "not now", "maybe later", "no thank you", "skip", "reject all",
+  ]);
+  const containerSel =
+    "[role='dialog'],[aria-modal='true'],[id*='cookie' i],[class*='cookie' i],[id*='consent' i]," +
+    "[class*='consent' i],[class*='gdpr' i],[id*='gdpr' i],[class*='modal' i],[class*='popup' i]," +
+    "[class*='newsletter' i],[class*='interstitial' i],[class*='overlay' i],[id*='overlay' i]," +
+    "[class*='ccpa' i],[id*='ccpa' i],[class*='privacy' i],[id*='pop' i]";
+  const containers = deepEls(document, containerSel);
+  for (const c of containers) {
+    if (!vis(c)) continue;
+    // Text/value-matched accept/decline buttons.
+    const btns = deepEls(c, "button,[role='button'],a,input[type='button'],input[type='submit']");
+    let clicked = false;
+    for (const b of btns) {
+      const t = (b.textContent || (b as HTMLInputElement).value || "").replace(/\s+/g, " ").trim().toLowerCase();
+      if (t && ACCEPT.has(t) && vis(b)) { click(b); dismissed.push("text:" + t); clicked = true; break; }
+    }
+    if (clicked) continue;
+    // aria-label / title close affordance (icon-only ×, no text content to match).
+    const closers = deepEls(c, "[aria-label*='close' i],[aria-label*='dismiss' i],[title*='close' i],button.close,.close-button,[class*='close' i][role='button']");
+    for (const x of closers) {
+      if (vis(x)) { click(x); dismissed.push("close:" + ((x.getAttribute("aria-label") || x.getAttribute("title") || "x")).slice(0, 24)); break; }
+    }
+  }
+  return dismissed;
+}
+
 async function clickDismiss(page: import("playwright").Page): Promise<string[]> {
-  try {
-    return await Promise.race([
-      page.evaluate(() => {
-        const dismissed: string[] = [];
-        const vis = (el: Element): boolean => {
-          const cs = getComputedStyle(el);
-          if (cs.display === "none" || cs.visibility === "hidden" || parseFloat(cs.opacity || "1") === 0) return false;
-          const r = (el as HTMLElement).getBoundingClientRect();
-          return r.width > 0 && r.height > 0;
-        };
-        const click = (el: Element): void => { try { (el as HTMLElement).click(); } catch { /* ignore */ } };
-
-        // 1) Known consent-framework / generic close affordances, in priority order.
-        const KNOWN = [
-          "#onetrust-accept-btn-handler", "#accept-recommended-btn-handler", ".onetrust-close-btn-handler",
-          "#CybotCookiebotDialogBodyLevelButtonLevelOptinAllowAll", "#CybotCookiebotDialogBodyButtonAccept",
-          "#truste-consent-button", ".osano-cm-accept-all", ".osano-cm-dialog__close",
-          "[data-testid='uc-accept-all-button']", "[data-testid='uc-deny-all-button']",
-          "#didomi-notice-agree-button", ".didomi-continue-without-agreeing",
-          ".qc-cmp2-summary-buttons button[mode='primary']", "button[aria-label='Consent']",
-          ".cc-allow", ".cookie-consent-accept", "#hs-eu-confirmation-button", "#gdpr-consent-tool-wrapper button",
-        ];
-        for (const sel of KNOWN) {
-          try {
-            for (const el of Array.from(document.querySelectorAll(sel))) {
-              if (vis(el)) { click(el); dismissed.push(sel); break; }
-            }
-          } catch { /* invalid selector in this browser */ }
-        }
-
-        // 2) Scoped text-button pass: only inside overlay-ish containers (dialogs,
-        //    or id/class naming cookie/consent/modal/popup/newsletter) so we never
-        //    click an ordinary page button.
-        const ACCEPT = new Set([
-          "accept", "accept all", "accept all cookies", "accept cookies", "accept & close",
-          "i accept", "i agree", "agree", "agree and continue", "allow all", "allow cookies",
-          "allow all cookies", "got it", "ok", "okay", "continue", "no thanks", "no, thanks",
-          "dismiss", "close", "got it!", "understood", "yes, i agree",
-        ]);
-        const containerSel =
-          "[role='dialog'],[aria-modal='true'],[id*='cookie' i],[class*='cookie' i],[id*='consent' i]," +
-          "[class*='consent' i],[class*='gdpr' i],[id*='gdpr' i],[class*='modal' i],[class*='popup' i]," +
-          "[class*='newsletter' i],[class*='interstitial' i]";
-        let containers: Element[] = [];
-        try { containers = Array.from(document.querySelectorAll(containerSel)); } catch { /* ignore */ }
-        for (const c of containers) {
-          if (!vis(c)) continue;
-          const btns = Array.from(c.querySelectorAll("button,[role='button'],a,input[type='button'],input[type='submit']"));
-          for (const b of btns) {
-            const t = (b.textContent || (b as HTMLInputElement).value || "").replace(/\s+/g, " ").trim().toLowerCase();
-            if (t && ACCEPT.has(t) && vis(b)) { click(b); dismissed.push("text:" + t); break; }
-          }
-        }
-        return dismissed;
-      }),
+  // Run the click pass in the main document AND every frame — cross-origin popup creatives
+  // (Attentive/Recart/…) host their Decline/close controls inside an iframe that the top
+  // document cannot reach, but Playwright can evaluate inside each frame from Node.
+  const runOne = (frame: import("playwright").Frame): Promise<string[]> =>
+    Promise.race([
+      frame.evaluate(clickDismissInPage).catch(() => [] as string[]),
       new Promise<string[]>((res) => setTimeout(() => res([]), 6000)),
     ]);
+  try {
+    const frames = page.frames();
+    const results = await Promise.all(frames.map((f) => runOne(f).catch(() => [] as string[])));
+    return results.flat();
   } catch {
     return [];
   }
@@ -334,57 +372,168 @@ async function clickDismiss(page: import("playwright").Page): Promise<string[]>
  * sticky chrome is never stripped. Reports `blocking` = a scroll-locking overlay we
  * could not clear (the pollution gate keys off this, not mere overlay presence).
  */
-async function finalizeOverlays(page: import("playwright").Page): Promise<{ overlaysRemaining: number; removed: number; blocking: boolean; removedLabels: string[] }> {
+export type FinalizeOverlaysResult = { overlaysRemaining: number; removed: number; blocking: boolean; removedLabels: string[] };
+
+/**
+ * In-page overlay finalizer (exported so fixture tests can page.evaluate it directly).
+ * Detects any full-viewport, fixed/sticky BLOCKING layer still present and — when the page
+ * is scroll-locked (a state legit pages never enter) — removes it. Key robustness rules:
+ *
+ *  (a) EFFECTIVE z-index: an element with `z-index:auto` inherits its stacking position from
+ *      the nearest positioned/opacity/transform ancestor that establishes a stacking context.
+ *      A vendor popup iframe is z:auto but sits inside a z=INT_MAX wrapper, so per-element
+ *      `parseInt("auto")` under-reads it — resolve z through the ancestor chain instead.
+ *  (b) LOCK relaxes the z gate: on a scroll-locked page, ANY fixed/sticky full-viewport layer
+ *      is blocking regardless of z (catches a z:auto creative and a z=50 CCPA dialog). Off a
+ *      locked page we keep the z>=100 floor to avoid stripping legit fixed content.
+ *  (c) OVERLAY UNIT: a 0-size (height:0) max-z wrapper whose descendant is a full-viewport
+ *      fixed iframe is ONE overlay — the wrapper carries the z, the iframe carries the pixels.
+ *      Detecting either means removing BOTH (climb from a removable iframe to its high-z
+ *      wrapper ancestor; and treat a max-z 0-size wrapper as an overlay via its full-viewport
+ *      descendant). Neither alone passes the area+z gate, so they must be grouped.
+ *  (d) LOUD FAILURE: if the lock persists after removal (or was locked with nothing detected),
+ *      report blocking=true so the pollution gate fails rather than shipping a polluted capture.
+ */
+export function finalizeOverlaysInPage(): FinalizeOverlaysResult {
+  const vw = window.innerWidth, vh = window.innerHeight;
+  // Deep element walk that descends into OPEN shadow roots. A shadow host reports 0 light-DOM
+  // children, so a popup mounted inside a shadow tree (Recart's `#recart-popup-root`) is invisible
+  // to a plain `querySelectorAll("*")` — its full-viewport fixed layer would never be detected and
+  // would paint into every screenshot. Traverse `element.shadowRoot` (open only; closed roots are
+  // unreachable — the host itself is still caught by the geometry gate below and removed whole).
+  const deepEls = (root: ParentNode): Element[] => {
+    const out: Element[] = [];
+    const push = (r: ParentNode): void => {
+      for (const el of Array.from(r.querySelectorAll("*"))) {
+        out.push(el);
+        const sr = (el as HTMLElement).shadowRoot;
+        if (sr) push(sr);
+      }
+    };
+    push(root);
+    return out;
+  };
+  const isLocked = (): boolean => {
+    const b = document.body, h = document.documentElement;
+    const bs = getComputedStyle(b), hs = getComputedStyle(h);
+    return bs.overflow === "hidden" || hs.overflow === "hidden" ||
+      bs.overflowY === "hidden" || hs.overflowY === "hidden" ||
+      bs.position === "fixed" || bs.position === "absolute";
+  };
+  // Effective z-index: climb to the nearest ancestor that both is positioned/creates a stacking
+  // context AND reports a numeric z-index. `z-index:auto` on a positioned child paints in its
+  // parent stacking context, so the parent's z is the layer's true stacking rank.
+  const effectiveZ = (el: Element): number => {
+    let cur: Element | null = el;
+    let hops = 0;
+    while (cur && hops < 20) {
+      const cs = getComputedStyle(cur);
+      const zi = parseInt(cs.zIndex || "", 10);
+      const positioned = cs.position !== "static";
+      if (Number.isFinite(zi) && positioned) return zi;
+      cur = cur.parentElement;
+      hops++;
+    }
+    return 0;
+  };
+  const rectOf = (el: Element) => (el as HTMLElement).getBoundingClientRect();
+  const fullViewport = (r: DOMRect): boolean => r.width >= vw * 0.7 && r.height >= vh * 0.5 && (r.width * r.height) / (vw * vh) >= 0.5;
+  const painting = (cs: CSSStyleDeclaration): boolean =>
+    cs.display !== "none" && cs.visibility !== "hidden" && parseFloat(cs.opacity || "1") !== 0;
+
+  const locked = isLocked();
+
+  // Candidate blocking layers. A layer qualifies when it is fixed/sticky, painting, and either
+  // (1) itself full-viewport, or (2) a 0-size/high-z wrapper whose descendant is full-viewport
+  // (the overlay-unit case — the wrapper holds the z, an inner iframe holds the pixels).
+  // Full-viewport descendant test that pierces shadow roots (Recart mounts the covering layer
+  // inside the host's shadow tree, so a light-DOM `querySelectorAll` would find nothing).
+  const hasFullDescendant = (el: Element): boolean => {
+    const scope: ParentNode = (el as HTMLElement).shadowRoot ?? el;
+    return deepEls(scope).some((d) => { const dcs = getComputedStyle(d); return painting(dcs) && (dcs.position === "fixed" || dcs.position === "sticky" || dcs.position === "absolute") && fullViewport(rectOf(d)); });
+  };
+  const bigOverlays = (): HTMLElement[] => {
+    const out: HTMLElement[] = [];
+    for (const el of deepEls(document.body)) {
+      const cs = getComputedStyle(el);
+      const isShadowHost = !!(el as HTMLElement).shadowRoot;
+      // A shadow host is usually position:static with a fixed layer INSIDE its root; still test it
+      // (via its shadow descendants) so the whole host can be removed as one overlay unit.
+      if (cs.position !== "fixed" && cs.position !== "sticky" && !isShadowHost) continue;
+      if (!painting(cs)) continue;
+      const r = rectOf(el);
+      const z = effectiveZ(el);
+      // Off a locked page keep the z>=100 floor; on a locked page any full-viewport fixed
+      // layer is blocking (rule b). A max-z wrapper is a blocking layer even at 0 size when it
+      // wraps a full-viewport descendant (rule c) — legit chrome never reaches the INT_MAX band.
+      const positioned = cs.position === "fixed" || cs.position === "sticky";
+      const selfFull = positioned && fullViewport(r);
+      const wrapsFull = (isShadowHost || r.width < 4 || r.height < 4) && (isShadowHost || z >= 100) && hasFullDescendant(el);
+      if (!selfFull && !wrapsFull) continue;
+      const zPass = locked || z >= 100 || (wrapsFull && isShadowHost);
+      if (zPass) out.push(el as HTMLElement);
+    }
+    // Keep outermost only (a wrapper subsumes its inner full-viewport iframe — the overlay unit).
+    // `Node.contains` does NOT cross shadow boundaries, so also treat a candidate that lives inside
+    // another candidate's shadow tree as contained — otherwise a shadow host AND its inner layer
+    // both survive and we double-remove (or leave the inner layer behind).
+    const shadowContains = (host: Element, node: Element): boolean => {
+      let cur: Node | null = node;
+      while (cur) {
+        const rootNode = cur.getRootNode();
+        if (rootNode instanceof ShadowRoot) {
+          if (rootNode.host === host || host.contains(rootNode.host)) return true;
+          cur = rootNode.host;
+        } else break;
+      }
+      return false;
+    };
+    return out.filter((el) => !out.some((o) => o !== el && (o.contains(el) || shadowContains(o, el))));
+  };
+
+  // A scroll-locked page behind a full-viewport overlay IS a blocking modal by definition
+  // (legit pages don't scroll-lock). Remove ANY such overlay that isn't page chrome — many
+  // modals/drawers carry no consent/modal keyword and an icon-only close, so a keyword/aria
+  // allowlist misses them. PROTECTED guards real chrome (header/nav/footer) only.
+  const PROTECTED = /header|navbar|nav-|site-nav|topbar|masthead|footer/i;
+  const sig = (el: HTMLElement): string => `${el.id} ${el.className}`.toString();
+
+  const removedLabels: string[] = [];
+  let removed = 0;
+  let remaining = bigOverlays();
+  if (remaining.length && locked) {
+    for (const el of remaining) {
+      const s = sig(el);
+      const z = effectiveZ(el);
+      // Scroll-locked + full-viewport ⇒ blocking modal; remove unless it's page chrome. Always
+      // remove iframes (cross-origin close, unclickable), max-z wrappers, and the overlay unit:
+      // when the layer IS or CONTAINS a full-viewport fixed iframe, remove the whole subtree
+      // (rule c — the 0-size wrapper + its iframe come out together as one node).
+      const isShadowHost = !!(el as HTMLElement).shadowRoot;
+      const containsIframe = el.tagName === "IFRAME" || !!el.querySelector("iframe") ||
+        (isShadowHost && !!(el as HTMLElement).shadowRoot!.querySelector("iframe"));
+      const removable = !PROTECTED.test(s) || el.getAttribute("aria-modal") === "true" ||
+        containsIframe || isShadowHost || z >= 100;
+      if (removable) { el.remove(); removed++; removedLabels.push((el.id || el.className || el.tagName).toString().slice(0, 40)); }
+    }
+    if (removed) {
+      document.body.style.overflow = "visible"; document.documentElement.style.overflow = "visible";
+      document.body.style.overflowY = "visible"; document.documentElement.style.overflowY = "visible";
+      document.body.style.position = "static";
+    }
+    remaining = bigOverlays();
+  }
+  // Loud failure (rule d): a persisting lock is blocking whether or not a specific overlay was
+  // still detectable — a scroll-locked capture is polluted, so surface it to the pollution gate.
+  const stillLocked = isLocked();
+  return { overlaysRemaining: remaining.length, removed, blocking: stillLocked && (remaining.length > 0 || locked), removedLabels };
+}
+
+async function finalizeOverlays(page: import("playwright").Page): Promise<FinalizeOverlaysResult> {
   try {
     return await Promise.race([
-      page.evaluate(() => {
-        const vw = window.innerWidth, vh = window.innerHeight;
-        const bigOverlays = (): HTMLElement[] => {
-          const out: HTMLElement[] = [];
-          for (const el of Array.from(document.body.querySelectorAll("*"))) {
-            const cs = getComputedStyle(el);
-            if (cs.position !== "fixed" && cs.position !== "sticky") continue;
-            if (cs.display === "none" || cs.visibility === "hidden" || parseFloat(cs.opacity || "1") === 0) continue;
-            const r = (el as HTMLElement).getBoundingClientRect();
-            const z = parseInt(cs.zIndex || "0", 10) || 0;
-            const area = (r.width * r.height) / (vw * vh);
-            if (area >= 0.5 && z >= 100 && r.width >= vw * 0.7 && r.height >= vh * 0.5) out.push(el as HTMLElement);
-          }
-          return out.filter((el) => !out.some((o) => o !== el && o.contains(el)));
-        };
-        const isLocked = (): boolean => {
-          const b = document.body, h = document.documentElement;
-          return getComputedStyle(b).overflow === "hidden" || getComputedStyle(h).overflow === "hidden" ||
-            getComputedStyle(b).position === "fixed";
-        };
-        // A scroll-locked page behind a full-viewport overlay IS a blocking modal by
-        // definition (legit pages don't scroll-lock). So remove ANY such overlay that
-        // isn't page chrome — many modals/drawers carry no consent/modal keyword and
-        // an icon-only close, so a keyword/aria allowlist misses them (ruggable's
-        // z-[1001] drawer). PROTECTED guards real chrome (header/nav/footer) only.
-        const PROTECTED = /header|navbar|nav-|site-nav|topbar|masthead|footer/i;
-        const sig = (el: HTMLElement): string => `${el.id} ${el.className}`.toString();
-
-        const removedLabels: string[] = [];
-        let removed = 0;
-        let remaining = bigOverlays();
-        if (remaining.length && isLocked()) {
-          for (const el of remaining) {
-            const s = sig(el);
-            const z = parseInt(getComputedStyle(el).zIndex || "0", 10) || 0;
-            // Scroll-locked + full-viewport ⇒ blocking modal; remove unless it's page
-            // chrome. Always remove iframes (cross-origin close, unclickable) and the
-            // max-z-index popup trick.
-            const removable = !PROTECTED.test(s) || el.getAttribute("aria-modal") === "true" ||
-              el.tagName === "IFRAME" || z >= 2_000_000_000;
-            if (removable) { el.remove(); removed++; removedLabels.push((el.id || el.className || el.tagName).toString().slice(0, 40)); }
-          }
-          if (removed) { document.body.style.overflow = "visible"; document.documentElement.style.overflow = "visible"; document.body.style.position = "static"; }
-          remaining = bigOverlays();
-        }
-        return { overlaysRemaining: remaining.length, removed, blocking: remaining.length > 0 && isLocked(), removedLabels };
-      }),
-      new Promise<{ overlaysRemaining: number; removed: number; blocking: boolean; removedLabels: string[] }>((res) => setTimeout(() => res({ overlaysRemaining: 0, removed: 0, blocking: false, removedLabels: [] }), 6000)),
+      page.evaluate(finalizeOverlaysInPage),
+      new Promise<FinalizeOverlaysResult>((res) => setTimeout(() => res({ overlaysRemaining: 0, removed: 0, blocking: false, removedLabels: [] }), 6000)),
     ]);
   } catch {
     return { overlaysRemaining: 0, removed: 0, blocking: false, removedLabels: [] };
@@ -1206,6 +1355,15 @@ export async function captureSite(opts: {
       // let scroll-linked effects settle so the snapshot records the genuine at-rest values.
       await settleScrollTopBeforeSnapshot(page);
 
+      // Late-mounting dialogs (a CCPA opt-out that opens between the canonical and last
+      // viewport; a Recart/Attentive promo that fires on a timer) mount AFTER the load /
+      // post-scroll passes and would otherwise pollute this viewport's DOM snapshot. Re-run
+      // the dismissal pass immediately before the walk. Cheap when nothing matches — the
+      // settle only runs when a control was actually clicked or an overlay removed.
+      await applyDismiss("pre-snapshot");
+      dismissUnion.overlaysRemaining = Math.max(dismissUnion.overlaysRemaining, overlaysRemaining);
+      dismissUnion.blocking = dismissUnion.blocking || blocking;
+
       // Bound the in-page DOM walk: page.evaluate has no default timeout, so a
       // pathologically large/animated DOM (e.g. asana.com) could hang forever.
       const snapshot: PageSnapshot = await Promise.race([
@@ -1254,6 +1412,13 @@ export async function captureSite(opts: {
       // Persist DOM snapshot, and (unless skipped for a production clone) the full-page screenshot.
       writeJSONCompact(join(captureDir, `dom-${vw}.json`), snapshot);
       if (opts.screenshots !== false) {
+        // A promo popup can mount in the window between the DOM walk and the screenshot (Recart
+        // fires into a shadow root on a short timer). The screenshot is the ground-truth channel
+        // the perceptual gate compares against, so re-run dismissal right before it — otherwise a
+        // late popup paints over every shot even though the DOM snapshot came out clean. Cheap
+        // when nothing matches.
+        await applyDismiss("pre-screenshot");
+        dismissUnion.blocking = dismissUnion.blocking || blocking;
         // Normalize every video to frame 0 (paused) at THIS viewport before the shot — the clone is
         // always at frame 0, so pinning the source there too makes the two channels comparable
         // regardless of the playback time the viewport happened to catch.
diff --git a/compiler/src/capture/graft.ts b/compiler/src/capture/graft.ts
index 98323cf..88b1406 100644
--- a/compiler/src/capture/graft.ts
+++ b/compiler/src/capture/graft.ts
@@ -29,8 +29,14 @@ export const MIN_FRAME_DIM = 48;
 export type FramePlan = "skip" | "still" | "graft";
 
 // Ad/analytics/consent plumbing frames render nothing a visitor values — skip entirely.
+// The trailing group is email-capture / promo POPUP CREATIVE hosts: a vendor whose creative
+// iframe IS a full-viewport interstitial ("Enjoy 15% off" over a dimmed backdrop). Grafting it
+// pours the popup's copy into the DOM/text channel and paints the modal over the real page.
+// CAUTION: these hosts serve OVERLAY creatives, distinct from the vendor's INLINE-form embed
+// hosts (e.g. static-forms.klaviyo.com), which stay graftable — inline signup forms are a
+// deliberately-grafted feature (see iframeGraft tests). Match creative/overlay hosts only.
 const FRAME_SKIP_RE =
-  /(?:doubleclick\.net|googlesyndication\.com|googletagmanager\.com|google-analytics\.com|googleadservices\.com|adservice\.google|facebook\.com\/tr|connect\.facebook\.net|\brecaptcha\b|hcaptcha\.com|challenges\.cloudflare\.com|adsrvr\.org|amazon-adsystem\.com)/i;
+  /(?:doubleclick\.net|googlesyndication\.com|googletagmanager\.com|google-analytics\.com|googleadservices\.com|adservice\.google|facebook\.com\/tr|connect\.facebook\.net|\brecaptcha\b|hcaptcha\.com|challenges\.cloudflare\.com|adsrvr\.org|amazon-adsystem\.com|creatives?\.attn\.tv|\.attentivemobile\.com|bounceexchange\.com|bouncex\.net|\.wunderkind\.co|wknd\.ai|cdn\.justuno\.com\/mkjs|privy\.com\/.*popup|widget\.privy\.com|\.recart\.com|recart\.io)/i;
 // Media players are JS-built canvases/videos whose DOM graft is meaningless; an element
 // screenshot (the poster frame + play chrome) is the faithful static paint.
 const FRAME_STILL_RE =
diff --git a/compiler/src/generate/css.ts b/compiler/src/generate/css.ts
index 2ae1757..a23569e 100644
--- a/compiler/src/generate/css.ts
+++ b/compiler/src/generate/css.ts
@@ -1,5 +1,5 @@
 import type { IR, IRNode, StyleMap } from "../normalize/ir.js";
-import { isTextChild } from "../normalize/ir.js";
+import { isTextChild, irContentExtent } from "../normalize/ir.js";
 import type { TokenResolver } from "../infer/tokens.js";
 
 /** Finalize a decls map: reference design tokens (var(--…)) where the value is tokenized
@@ -2447,14 +2447,20 @@ function declsForViewport(
   // intro — body/html { height:100vh; overflow-y:scroll|hidden } — can be captured in
   // that transient state, pinning the root to one viewport so it CLIPS its overflowing
   // content; the clone's document.scrollHeight then collapses to one viewport and the
-  // page renders truncated (paco.me). The lock is provably transient when the source's
-  // OWN captured scrollHeight exceeds the pinned height (the real document scrolled
-  // taller) — unlike a genuine internal-scroll shell, whose scrollHeight matches. Drop
-  // the clamp (height + clipping overflow-y) so the root grows to its content.
+  // page renders truncated (paco.me). Two independent signals prove the lock is transient:
+  //   • captured scrollHeight exceeds the pinned height (the real document scrolled taller); OR
+  //   • the IR's own IN-FLOW content extent (max descendant border-box bottom) exceeds the clamp.
+  // The SECOND signal is essential for an email-capture popup that scroll-LOCKS the page: the
+  // lock collapses `document.scrollHeight` down to the viewport (== clamp), so the scrollHeight
+  // test can never fire in exactly the worst case — but the in-flow sections still carry their
+  // real coordinates, so the content extent (5000px+ on a real homepage) still betrays the clamp.
+  // A genuine internal-scroll shell has matching content extent AND scrollHeight, so neither fires.
   const clampH = parseFloat(cs.height || "");
+  const contentExtent = (tag === "body" || tag === "html") ? irContentExtent(node, vp) : 0;
   const rootUnclamp =
     (tag === "body" || tag === "html") &&
-    !!rootScrollHeight && clampH > 0 && rootScrollHeight > clampH + 4 &&
+    clampH > 0 &&
+    ((!!rootScrollHeight && rootScrollHeight > clampH + 4) || contentExtent > clampH + 4) &&
     /^(scroll|hidden|auto|clip)$/.test(cs.overflowY || cs.overflow || "visible");
   // A pure-text leaf's height is fully content-derived (padding/border + lines × line-height).
   // We reproduce the font, line-height, padding and width, so its height auto-resolves to the
@@ -2622,8 +2628,20 @@ function declsForViewport(
   }
 
   // Root un-clamp: relax the clipping vertical overflow so the document scrolls at the
-  // window level (no spurious scrollbar gutter) and grows to its content height.
-  if (rootUnclamp) out.set("overflow-y", "visible");
+  // window level (no spurious scrollbar gutter) and grows to its content height. Popup
+  // vendors also inject `position:absolute|fixed` + `overflow:hidden` on <body> to freeze
+  // the page under their modal; that lock state gets captured as the body's computed style
+  // and, unstripped, hard-clips the clone to one screen (it can't scroll). Strip both — the
+  // real body is `position:static; overflow:visible` — so the un-clamped root scrolls normally.
+  if (rootUnclamp) {
+    out.set("overflow-y", "visible");
+    out.set("overflow-x", "visible");
+    out.delete("overflow");
+    out.delete("height");
+    const posV = out.get("position");
+    if (posV === "absolute" || posV === "fixed") out.delete("position");
+    for (const side of ["top", "right", "bottom", "left"]) out.delete(side);
+  }
 
   // Fluid grid columns (fr) replace the baked per-viewport px tracks so the grid scales.
   if (gridCols !== undefined) out.set("grid-template-columns", gridCols);
diff --git a/compiler/src/normalize/ir.ts b/compiler/src/normalize/ir.ts
index a85cd25..982e296 100644
--- a/compiler/src/normalize/ir.ts
+++ b/compiler/src/normalize/ir.ts
@@ -83,6 +83,33 @@ export function isTextChild(c: IRChild): c is IRTextNode {
   return (c as IRTextNode).text !== undefined;
 }
 
+/**
+ * In-flow content extent at a viewport: the largest border-box bottom (`bbox.y + bbox.height`)
+ * over every VISIBLE, IN-FLOW descendant. This is the true height the real page laid out to,
+ * independent of a scroll-lock that clips the root to one viewport (a popup vendor that sets
+ * `body{overflow:hidden;height:100vh}` collapses `document.scrollHeight` to the viewport, but
+ * the in-flow sections still carry their real coordinates). Out-of-flow (absolute/fixed) and
+ * floated boxes are excluded — a fixed overlay/footer badge or a floated aside is not part of
+ * the document flow that determines page height. Pure + deterministic (reads only the IR).
+ */
+export function irContentExtent(root: IRNode, vp: number): number {
+  let maxBottom = 0;
+  const visit = (n: IRNode): void => {
+    for (const c of n.children) {
+      if (isTextChild(c)) continue;
+      const cs = c.computedByVp[vp];
+      const bb = c.bboxByVp[vp];
+      if (!cs || !bb || !c.visibleByVp[vp]) { visit(c); continue; }
+      const pos = cs.position || "static";
+      const inFlow = pos !== "absolute" && pos !== "fixed" && (cs.float || "none") === "none";
+      if (inFlow) maxBottom = Math.max(maxBottom, bb.y + bb.height);
+      visit(c);
+    }
+  };
+  visit(root);
+  return maxBottom;
+}
+
 /**
  * Recover lazy-loaded CSS backgrounds dropped by uneven per-viewport capture.
  * If an element has exactly one URL background at some sampled widths and
@@ -175,9 +202,24 @@ const NOISE_TAGS = new Set(["next-route-announcer"]);
 // width where capture happened to read it open → an empty 400×700 white rectangle at 2xl). Drop
 // the whole subtree so it never reaches generation.
 const THIRD_PARTY_OVERLAY = /(?:^|[\s_-])(?:intercom|drift-|hubspot-messages|zendesk|zd-|onetrust|ot-sdk-|usercentrics|grecaptcha|crisp-client|tawk-|livechat|helpscout|beacon-container|cookiebot|cky-)/;
+
+/**
+ * Email-capture / promo POPUP overlay containers (Attentive, Wunderkind/Bounce Exchange,
+ * Justuno, Privy, Omnisend, Sailthru, Wisepops, etc.). These vendors inject a full-viewport
+ * fixed overlay + backdrop that scroll-locks the page — third-party chrome, not site content.
+ *
+ * CAUTION: these vendors ALSO ship inline, embedded signup forms that ARE real page content
+ * and are deliberately grafted (see iframeGraft tests). So this matches ONLY the OVERLAY
+ * CONTAINER markers each vendor uses for its popup (`attentive_overlay`, `bx-wrapper` /
+ * `wk-`, `justuno`-`container`, `privy-`popup, …) — never a bare vendor name that an inline
+ * form embed would also carry. Overlay-container tokens only.
+ */
+export const POPUP_OVERLAY_CONTAINER =
+  /(?:^|[\s_-])(?:attentive_overlay|attentive_creative|attn-|bx-wrapper|bx-window|bounce-?exchange|wknd-|wunderkind|justuno_container|jw-overlay|privy-popup|privy-container|klaviyo-form-.*overlay|sailthru-overlay|wisepops-root|recart-popup|recart-modal)/;
 function isThirdPartyOverlay(raw: RawNode): boolean {
   const idClass = `${raw.attrs?.id ?? ""} ${raw.attrs?.class ?? ""}`.toLowerCase();
   if (THIRD_PARTY_OVERLAY.test(idClass)) return true;
+  if (POPUP_OVERLAY_CONTAINER.test(idClass)) return true;
   // INT_MAX band: overlay libraries stack above everything. Real content should not reach here,
   // so this cannot swallow site chrome under normal captures.
   const zi = parseInt(raw.computed?.zIndex ?? "", 10);
diff --git a/compiler/src/validate/gates.ts b/compiler/src/validate/gates.ts
index 95def8c..23c2ba8 100644
--- a/compiler/src/validate/gates.ts
+++ b/compiler/src/validate/gates.ts
@@ -1,5 +1,5 @@
 import type { IR, IRNode } from "../normalize/ir.js";
-import { isTextChild } from "../normalize/ir.js";
+import { isTextChild, irContentExtent } from "../normalize/ir.js";
 import type { PageSnapshot } from "../capture/walker.js";
 import type { GenNode } from "./render.js";
 import { indexByCid } from "./render.js";
@@ -119,11 +119,30 @@ export function gatePollution(ir: IR, capture: CaptureResult, viewports: number[
   let blocking = capture.dismissal?.blocking ?? false;
   for (const pv of capture.perViewport) { overlaysRemaining = Math.max(overlaysRemaining, pv.overlaysRemaining ?? 0); blocking = blocking || !!pv.blocking; }
   let minHeightRatio = Infinity;
+  let maxHeightRatio = 0;
   for (const pv of capture.perViewport) {
-    if (pv.height > 0) minHeightRatio = Math.min(minHeightRatio, pv.scrollHeight / pv.height);
+    if (pv.height > 0) {
+      const ratio = pv.scrollHeight / pv.height;
+      minHeightRatio = Math.min(minHeightRatio, ratio);
+      maxHeightRatio = Math.max(maxHeightRatio, ratio);
+    }
   }
   if (!Number.isFinite(minHeightRatio)) minHeightRatio = 1;
 
+  // Scroll-locked-capture contradiction: an email-capture/promo popup that sets
+  // body{overflow:hidden;height:100vh} collapses `document.scrollHeight` to EXACTLY the viewport
+  // height at EVERY width (ratio ~1.0 across the board) — yet the real page's IN-FLOW content
+  // (the IR's sections) still lays out several viewports tall. A genuine one-screen landing page
+  // has content extent ~= its scrollHeight, so this only fires when the two disagree: captured
+  // scrollHeight pinned to one viewport WHILE the IR content spans multiple. That is a
+  // scroll-locked, polluted capture — the overlay detector should have caught it, so fail loudly.
+  let maxContentRatio = 0;
+  for (const pv of capture.perViewport) {
+    if (pv.height > 0) maxContentRatio = Math.max(maxContentRatio, irContentExtent(ir.root, pv.viewport) / pv.height);
+  }
+  // scrollHeight never exceeds ~1 viewport at any width, but the IR content is 2+ viewports tall.
+  const scrollLockedContradiction = maxHeightRatio > 0 && maxHeightRatio < 1.15 && maxContentRatio >= 2;
+
   // Degenerate signals. Calibrated against real captures: an egress/bot wall is
   // ~3 nodes / ~24 chars; the most minimal legitimate page in the suite
   // (michaelcole.me) is 26 nodes / 640 chars. Thresholds sit safely between.
@@ -131,6 +150,7 @@ export function gatePollution(ir: IR, capture: CaptureResult, viewports: number[
   if (wall && nodeCount < 220) issues.push("bot/egress wall text on a small page");
   if (textChars < 60 && nodeCount < 50) issues.push(`near-empty page: ${textChars} visible text chars, ${nodeCount} nodes`);
   if (blocking) issues.push("a full-viewport modal still scroll-locks the page after dismissal");
+  if (scrollLockedContradiction) issues.push(`scroll-locked capture: scrollHeight pinned to ~1 viewport at every width while IR content spans ${round2(maxContentRatio)} viewports`);
 
   return {
     gate: "pollution",
@@ -138,6 +158,7 @@ export function gatePollution(ir: IR, capture: CaptureResult, viewports: number[
     metrics: {
       nodeCount, visibleTextChars: textChars, wallTextDetected: wall,
       overlaysRemaining, blocking, minScrollHeightRatio: round2(minHeightRatio),
+      maxScrollHeightRatio: round2(maxHeightRatio), maxContentExtentRatio: round2(maxContentRatio),
       dismissedCount: capture.dismissal?.dismissed.length ?? 0,
       overlaysRemoved: capture.dismissal?.removed ?? 0,
       videoStills: capture.dismissal?.videoStills ?? 0,
diff --git a/compiler/test/css.test.ts b/compiler/test/css.test.ts
index 0d0c47e..d0c9547 100644
--- a/compiler/test/css.test.ts
+++ b/compiler/test/css.test.ts
@@ -49,6 +49,42 @@ function baseRule(css: string, id: string): string {
   return m?.[1] ?? "";
 }
 
+// Root scroll-lock un-clamp: a popup vendor locks the page with
+// body{position:absolute;overflow:hidden;height:100vh}, which the capture bakes as the body's
+// computed style AND collapses document.scrollHeight down to the clamp (so the captured-scrollHeight
+// trigger can never fire). The IR's in-flow CONTENT EXTENT (a footer laid out at y=5000) still
+// exceeds the clamp, so the un-clamp must fire off that signal and strip the lock.
+describe("generateCss root scroll-lock un-clamp (content-extent trigger)", () => {
+  it("drops the body height/position/overflow lock when IR content extent exceeds the clamp", () => {
+    const footer = node("n1", "footer", computed());
+    // Footer sits far below the one-viewport clamp at every viewport.
+    for (const vp of VPS) footer.bboxByVp[vp] = { x: 0, y: 4000, width: vp, height: 1000 }; // bottom = 5000
+    const bodyCs = computed({ position: "absolute", overflow: "hidden", overflowY: "hidden", height: "812px", top: "0px", left: "0px" });
+    const root = node("n0", "body", bodyCs, [footer]);
+    for (const vp of VPS) root.bboxByVp[vp] = { x: 0, y: 0, width: vp, height: 812 };
+    // perViewport.scrollHeight stays collapsed to 800 (the lock's doing) — so ONLY the content
+    // extent can trigger the un-clamp.
+    const css = generateCss(irWith(root), new Map());
+    const body = baseRule(css, "n0");
+    assert.ok(!/height:812px/.test(body), `body height clamp dropped (got: ${body})`);
+    assert.ok(!/position:absolute/.test(body), `body position:absolute stripped (got: ${body})`);
+    assert.ok(/overflow-y:visible/.test(body), `overflow-y forced visible (got: ${body})`);
+    assert.ok(!/overflow:hidden/.test(body), `overflow:hidden not emitted (got: ${body})`);
+  });
+
+  it("does NOT un-clamp a genuine one-screen page (content extent within the clamp)", () => {
+    const inner = node("n1", "div", computed());
+    for (const vp of VPS) inner.bboxByVp[vp] = { x: 0, y: 0, width: vp, height: 700 };
+    const bodyCs = computed({ overflow: "hidden", overflowY: "hidden", height: "800px" });
+    const root = node("n0", "body", bodyCs, [inner]);
+    for (const vp of VPS) root.bboxByVp[vp] = { x: 0, y: 0, width: vp, height: 800 };
+    const css = generateCss(irWith(root), new Map());
+    const body = baseRule(css, "n0");
+    // The clamp is legitimate (content fits) — height kept, overflow not forced to visible.
+    assert.ok(/height:800px/.test(body), `legit body height preserved (got: ${body})`);
+  });
+});
+
 describe("generateCss list markers", () => {
   it("re-establishes list-style on a <ul> whose disc equals the parent's initial value", () => {
     // list-style-type's initial value is `disc` on EVERY element, so a real <ul disc>
diff --git a/compiler/test/iframeGraft.test.ts b/compiler/test/iframeGraft.test.ts
index 96cc9e7..85f7b37 100644
--- a/compiler/test/iframeGraft.test.ts
+++ b/compiler/test/iframeGraft.test.ts
@@ -72,6 +72,23 @@ describe("planForFrameUrl", () => {
     assert.equal(planForFrameUrl("https://static-forms.klaviyo.com/forms/abc"), "graft");
     assert.equal(planForFrameUrl("http://127.0.0.1:4001/iframe-embed.html"), "graft");
   });
+
+  it("SKIPS full-viewport promo POPUP CREATIVE hosts (Attentive/Recart/Wunderkind overlays)", () => {
+    // These vendor hosts serve a full-viewport interstitial creative — grafting pours the
+    // popup's copy into the DOM/text channel and paints the modal over the real page.
+    assert.equal(planForFrameUrl("https://creatives.attn.tv/creative/12345"), "skip");
+    assert.equal(planForFrameUrl("https://creative.attn.tv/loader/x"), "skip");
+    assert.equal(planForFrameUrl("https://app.recart.com/popup/abc"), "skip");
+    assert.equal(planForFrameUrl("https://tag.wunderkind.co/creative"), "skip");
+    assert.equal(planForFrameUrl("https://api.bounceexchange.com/creative"), "skip");
+  });
+
+  it("STILL grafts INLINE embed hosts even for the same vendors (inline forms are a feature)", () => {
+    // Caution guard: a deliberately-grafted inline signup form must never be caught by the
+    // popup-creative skip list. Inline-form hosts differ from overlay-creative hosts.
+    assert.equal(planForFrameUrl("https://static-forms.klaviyo.com/forms/abc"), "graft");
+    assert.equal(planForFrameUrl("https://manage.kmail-lists.com/subscriptions/subscribe"), "graft");
+  });
 });
 
 describe("graftFrameIntoSnapshot", () => {
diff --git a/compiler/test/irPrune.test.ts b/compiler/test/irPrune.test.ts
index 22a8942..f65e4a0 100644
--- a/compiler/test/irPrune.test.ts
+++ b/compiler/test/irPrune.test.ts
@@ -117,6 +117,34 @@ describe("IR drops font-metric probe nodes (fix 4)", () => {
   });
 });
 
+describe("IR drops popup-vendor OVERLAY containers, keeps inline embedded forms", () => {
+  it("drops an email-capture popup overlay container (vendor overlay id) but keeps a real section", () => {
+    const overlay = raw("div", { id: "attentive_overlay" }, [
+      raw("iframe", { id: "attentive_creative", src: "https://creatives.attn.tv/x" }),
+    ]);
+    const real = raw("section", { class: "hero" }, [raw("h1", {}, [{ text: "Real content" }])]);
+    const body = raw("body", {}, [real, overlay]);
+
+    const root = buildFixtureIR(body);
+    const kept = root.children.filter((c) => !isTextChild(c)).map((c) => (c as IRNode).tag);
+    assert.deepEqual(kept, ["section"], "the attentive overlay subtree is dropped");
+    assert.equal(findByTag(root, "iframe"), null, "the popup creative iframe never reaches the IR");
+  });
+
+  it("does NOT drop an INLINE embedded signup form that merely carries a vendor name (feature, not popup)", () => {
+    // A deliberately-grafted inline Klaviyo form: a real, sized form embedded in page content. Its
+    // class names the vendor but is NOT an overlay-container marker, so it must survive.
+    const inlineForm = raw("div", { class: "klaviyo-form klaviyo-form-inline" }, [
+      raw("form", { id: "email-signup" }, [raw("input", { type: "email" })]),
+    ]);
+    const body = raw("body", {}, [inlineForm]);
+
+    const root = buildFixtureIR(body);
+    assert.ok(findByTag(root, "form"), "the inline signup form survives the prune");
+    assert.ok(findByTag(root, "input"), "its input survives too");
+  });
+});
+
 // Defect C (normalize side) — an infinite CSS animation gated to a breakpoint (a Webflow `max-lg`
 // marquee) is `animation:none` at the widths it does not run, but the browser still reports the last
 // FROZEN translateX there. `neutralizeAnimatedTransforms` zeroes the transform at EVERY viewport
diff --git a/compiler/test/overlayDismiss.test.ts b/compiler/test/overlayDismiss.test.ts
new file mode 100644
index 0000000..3ada0b0
--- /dev/null
+++ b/compiler/test/overlayDismiss.test.ts
@@ -0,0 +1,311 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { chromium, type Browser, type Page } from "playwright";
+import { finalizeOverlaysInPage, clickDismissInPage } from "../src/capture/capture.js";
+import { irContentExtent, type IRNode, type BBox, type StyleMap } from "../src/normalize/ir.js";
+import { gatePollution } from "../src/validate/gates.js";
+import type { CaptureResult } from "../src/capture/capture.js";
+import type { IR } from "../src/normalize/ir.js";
+
+// tsx/esbuild wraps serialized page functions with __name()/__defProp; shim so page.evaluate works.
+const ESBUILD_SHIM =
+  "globalThis.__name = globalThis.__name || ((fn) => fn);" +
+  "globalThis.__defProp = globalThis.__defProp || Object.defineProperty;";
+
+const VW = 1280, VH = 800;
+
+// ---------------------------------------------------------------------------
+// finalizeOverlaysInPage — effective-z resolution, overlay-unit grouping,
+// lock-relaxed z gate, shadow-root traversal, loud-failure blocking.
+// ---------------------------------------------------------------------------
+describe("capture: finalizeOverlaysInPage overlay detection", () => {
+  let browser: Browser;
+  before(async () => { browser = await chromium.launch(); });
+  after(async () => { await browser.close(); });
+
+  const newPage = async (html: string): Promise<Page> => {
+    const page = await browser.newPage();
+    await page.setViewportSize({ width: VW, height: VH });
+    await page.addInitScript(ESBUILD_SHIM);
+    await page.setContent(html);
+    await page.evaluate(ESBUILD_SHIM);
+    return page;
+  };
+
+  it("groups a 0-height max-z wrapper + its full-viewport z:auto iframe as ONE overlay and removes both (scroll-locked)", async () => {
+    // Mirrors the Attentive structure: body scroll-locked; a fixed z=INT_MAX wrapper of height 0
+    // whose child is a fixed full-viewport iframe with z-index:auto. Neither passes the naive
+    // per-element area+z gate alone (wrapper: area 0; iframe: z parses to 0).
+    const page = await newPage(`
+      <style>
+        html,body{margin:0}
+        body{position:absolute;top:0;left:0;right:0;height:${VH}px;overflow:hidden}
+        #wrap{position:fixed;top:${VH}px;left:0;width:${VW}px;height:0;z-index:2147483647}
+        #creative{position:fixed;top:0;left:0;width:${VW}px;height:${VH}px;z-index:auto;background:#000}
+      </style>
+      <main>real page content</main>
+      <div id="wrap"><iframe id="creative"></iframe></div>
+    `);
+    const res = await page.evaluate(finalizeOverlaysInPage);
+    assert.equal(res.removed, 1, "the wrapper+iframe unit is removed as one node");
+    assert.ok(res.removedLabels.some((l) => l.includes("wrap")), `removed the max-z wrapper (got ${JSON.stringify(res.removedLabels)})`);
+    const gone = await page.evaluate(() => !document.getElementById("wrap") && !document.getElementById("creative"));
+    assert.ok(gone, "both the wrapper and its inner iframe are gone");
+    await page.close();
+  });
+
+  it("detects a z=50 full-viewport fixed dialog ONLY because the page is scroll-locked (lock relaxes the z>=100 gate)", async () => {
+    const page = await newPage(`
+      <style>
+        html,body{margin:0}
+        body{overflow:hidden}
+        #ccpa{position:fixed;inset:0;width:${VW}px;height:${VH}px;z-index:50;background:rgba(0,0,0,.7)}
+      </style>
+      <main>content</main>
+      <div id="ccpa">California Residents Privacy Rights</div>
+    `);
+    const res = await page.evaluate(finalizeOverlaysInPage);
+    assert.equal(res.removed, 1, "the z=50 dialog is removed on a locked page");
+    await page.close();
+  });
+
+  it("does NOT remove a z=50 full-viewport fixed layer when the page is NOT scroll-locked (z floor preserved)", async () => {
+    const page = await newPage(`
+      <style>
+        html,body{margin:0}
+        #hero{position:fixed;inset:0;width:${VW}px;height:${VH}px;z-index:50;background:#eee}
+      </style>
+      <div id="hero">a legit fixed hero, page scrolls normally</div>
+    `);
+    const res = await page.evaluate(finalizeOverlaysInPage);
+    assert.equal(res.removed, 0, "no removal off a locked page — the z>=100 floor guards legit fixed content");
+    assert.equal(res.blocking, false);
+    await page.close();
+  });
+
+  it("removes a promo popup mounted inside an OPEN shadow root and reports the host label", async () => {
+    const page = await newPage(`
+      <style>html,body{margin:0}body{overflow:hidden}</style>
+      <main>content</main>
+      <div id="recart-popup-root"></div>
+      <script>
+        const host = document.getElementById("recart-popup-root");
+        const root = host.attachShadow({ mode: "open" });
+        const layer = document.createElement("div");
+        layer.style.cssText = "position:fixed;inset:0;width:${VW}px;height:${VH}px;z-index:999;background:rgba(0,0,0,.6)";
+        layer.textContent = "Enjoy 15% off";
+        root.appendChild(layer);
+      </script>
+    `);
+    const res = await page.evaluate(finalizeOverlaysInPage);
+    assert.equal(res.removed, 1, "the shadow-hosting popup element is removed as one unit");
+    const gone = await page.evaluate(() => !document.getElementById("recart-popup-root"));
+    assert.ok(gone, "the shadow host is gone from the light DOM");
+    await page.close();
+  });
+
+  it("reports blocking=true when the scroll-lock persists even with NO overlay detected (loud failure)", async () => {
+    // Body is scroll-locked but there is no fixed full-viewport layer to find (e.g. a closed
+    // shadow root we cannot pierce). A silently-locked capture is polluted → surface it.
+    const page = await newPage(`
+      <style>html,body{margin:0}body{overflow:hidden;position:absolute;height:${VH}px}</style>
+      <main>content</main>
+    `);
+    const res = await page.evaluate(finalizeOverlaysInPage);
+    assert.equal(res.removed, 0);
+    assert.equal(res.blocking, true, "a persistent lock with nothing removable still reports blocking");
+    await page.close();
+  });
+
+  it("reports blocking=false and removes nothing on an ordinary unlocked page", async () => {
+    const page = await newPage(`
+      <style>html,body{margin:0}</style>
+      <header>nav</header><main>lots of content</main><footer>footer</footer>
+    `);
+    const res = await page.evaluate(finalizeOverlaysInPage);
+    assert.equal(res.removed, 0);
+    assert.equal(res.blocking, false);
+    assert.equal(res.overlaysRemaining, 0);
+    await page.close();
+  });
+
+  it("protects real sticky page chrome (header/nav) from removal even when detected", async () => {
+    // A scroll-locked page with a sticky header that happens to be tall — the header is PROTECTED,
+    // and it isn't full-viewport, so it never even qualifies. Assert nothing is stripped.
+    const page = await newPage(`
+      <style>
+        html,body{margin:0}body{overflow:hidden}
+        #masthead{position:sticky;top:0;width:${VW}px;height:80px;z-index:1000;background:#fff}
+      </style>
+      <header id="masthead">site chrome</header>
+      <main>content</main>
+    `);
+    const res = await page.evaluate(finalizeOverlaysInPage);
+    const present = await page.evaluate(() => !!document.getElementById("masthead"));
+    assert.ok(present, "the header survives");
+    await page.close();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// clickDismissInPage — decline/close matchers, shadow-root traversal.
+// ---------------------------------------------------------------------------
+describe("capture: clickDismissInPage matchers", () => {
+  let browser: Browser;
+  before(async () => { browser = await chromium.launch(); });
+  after(async () => { await browser.close(); });
+
+  const run = async (html: string): Promise<string[]> => {
+    const page = await browser.newPage();
+    await page.addInitScript(ESBUILD_SHIM);
+    await page.setContent(html);
+    await page.evaluate(ESBUILD_SHIM);
+    const res = await page.evaluate(clickDismissInPage);
+    await page.close();
+    return res;
+  };
+
+  it("clicks a Decline button inside an overlay container (email-capture opt-out)", async () => {
+    const dismissed = await run(`
+      <div class="signup-overlay" style="position:fixed;inset:0;width:400px;height:400px">
+        <button onclick="window.__declined=true">Decline</button>
+      </div>
+    `);
+    assert.ok(dismissed.includes("text:decline"), `clicked Decline (got ${JSON.stringify(dismissed)})`);
+  });
+
+  it("clicks an aria-label close (×) inside an overlay container when no accept/decline text matches", async () => {
+    const dismissed = await run(`
+      <div id="promo-popup" style="position:fixed;inset:0;width:400px;height:400px">
+        <button aria-label="Close dialog">×</button>
+      </div>
+    `);
+    assert.ok(dismissed.some((d) => d.startsWith("close:")), `clicked the aria close (got ${JSON.stringify(dismissed)})`);
+  });
+
+  it("matches an overlay/ccpa/privacy container id/class (extended container selector)", async () => {
+    const dismissed = await run(`
+      <div id="ccpaPop" style="position:fixed;inset:0;width:400px;height:400px">
+        <button>Accept</button>
+      </div>
+    `);
+    assert.ok(dismissed.includes("text:accept"), `matched the ccpa container (got ${JSON.stringify(dismissed)})`);
+  });
+
+  it("traverses an open shadow root to find the close control", async () => {
+    const page = await browser.newPage();
+    await page.addInitScript(ESBUILD_SHIM);
+    await page.setContent(`<div id="host"></div>`);
+    await page.evaluate(ESBUILD_SHIM);
+    await page.evaluate(() => {
+      const host = document.getElementById("host")!;
+      const root = host.attachShadow({ mode: "open" });
+      root.innerHTML = `<div class="popup-modal" style="position:fixed;inset:0;width:400px;height:400px"><button aria-label="close">×</button></div>`;
+    });
+    const dismissed = await page.evaluate(clickDismissInPage);
+    await page.close();
+    assert.ok(dismissed.some((d) => d.startsWith("close:")), `found the shadow-root close (got ${JSON.stringify(dismissed)})`);
+  });
+
+  it("never clicks an ordinary page button outside any overlay container", async () => {
+    const dismissed = await run(`<main><button>Accept</button><a>Continue</a></main>`);
+    assert.deepEqual(dismissed, [], "no overlay container ⇒ no clicks");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// irContentExtent — pure geometry (unclamp / pollution trigger).
+// ---------------------------------------------------------------------------
+describe("normalize: irContentExtent", () => {
+  const bbox = (x: number, y: number, w: number, h: number): BBox => ({ x, y, width: w, height: h });
+  const style = (over: Partial<StyleMap> = {}): StyleMap => ({ position: "static", ...over } as StyleMap);
+  const node = (over: Partial<IRNode>): IRNode => ({
+    id: "n", tag: "div", attrs: {},
+    visibleByVp: { 1280: true }, bboxByVp: { 1280: bbox(0, 0, 100, 100) },
+    computedByVp: { 1280: style() }, children: [], ...over,
+  });
+
+  it("returns the max in-flow descendant border-box bottom", () => {
+    const root = node({
+      tag: "body",
+      children: [
+        node({ bboxByVp: { 1280: bbox(0, 0, 1280, 800) } }),
+        node({ bboxByVp: { 1280: bbox(0, 800, 1280, 4398) } }), // footer bottom = 5198
+      ],
+    });
+    assert.equal(irContentExtent(root, 1280), 5198);
+  });
+
+  it("excludes out-of-flow (fixed/absolute) and floated boxes", () => {
+    const root = node({
+      tag: "body",
+      children: [
+        node({ bboxByVp: { 1280: bbox(0, 0, 1280, 900) } }),
+        node({ computedByVp: { 1280: style({ position: "fixed" }) }, bboxByVp: { 1280: bbox(0, 0, 1280, 9999) } }),
+        node({ computedByVp: { 1280: style({ float: "left" } as Partial<StyleMap>) }, bboxByVp: { 1280: bbox(0, 0, 1280, 8888) } }),
+      ],
+    });
+    assert.equal(irContentExtent(root, 1280), 900, "fixed + float extents ignored");
+  });
+
+  it("descends into nested in-flow subtrees", () => {
+    const root = node({
+      tag: "body",
+      children: [node({ children: [node({ bboxByVp: { 1280: bbox(0, 0, 500, 3000) } })] })],
+    });
+    assert.equal(irContentExtent(root, 1280), 3000);
+  });
+
+  it("ignores nodes invisible at the queried viewport", () => {
+    const root = node({
+      tag: "body",
+      children: [node({ visibleByVp: { 1280: false }, bboxByVp: { 1280: bbox(0, 0, 100, 5000) } })],
+    });
+    assert.equal(irContentExtent(root, 1280), 0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// gatePollution — scroll-locked-capture contradiction.
+// ---------------------------------------------------------------------------
+describe("validate: pollution gate scroll-locked contradiction", () => {
+  const bbox = (x: number, y: number, w: number, h: number): BBox => ({ x, y, width: w, height: h });
+  const st = (over: Partial<StyleMap> = {}): StyleMap => ({ position: "static", ...over } as StyleMap);
+  // A body with plenty of text and a footer at y=5198 (content extent ~6.4 viewports @800).
+  const mkIr = (): IR => ({
+    doc: {
+      sourceUrl: "https://x.test", title: "t", lang: "en", charset: "UTF-8", metaViewport: "",
+      viewports: [1280], sampleViewports: [1280], canonicalViewport: 1280,
+      perViewport: { 1280: { scrollHeight: 800, scrollWidth: 1280, htmlBg: "", bodyBg: "", bodyColor: "", bodyFont: "" } },
+      nodeCount: 200, keyframes: [],
+    },
+    root: {
+      id: "n0", tag: "body", attrs: {}, visibleByVp: { 1280: true },
+      bboxByVp: { 1280: bbox(0, 0, 1280, 800) }, computedByVp: { 1280: st() },
+      children: [
+        { id: "n1", tag: "section", attrs: {}, visibleByVp: { 1280: true }, bboxByVp: { 1280: bbox(0, 0, 1280, 800) }, computedByVp: { 1280: st() },
+          children: [{ text: "hero copy ".repeat(20) }] },
+        { id: "n2", tag: "footer", attrs: {}, visibleByVp: { 1280: true }, bboxByVp: { 1280: bbox(0, 4074, 1280, 1124) }, computedByVp: { 1280: st() },
+          children: [{ text: "footer copy ".repeat(20) }] },
+      ],
+    },
+  });
+  const mkCapture = (scrollHeight: number): CaptureResult => ({
+    perViewport: [
+      { viewport: 375, height: 812, scrollHeight: 812, nodeCount: 200, truncated: false },
+      { viewport: 1280, height: 800, scrollHeight, nodeCount: 200, truncated: false },
+    ],
+    dismissal: { dismissed: [], overlaysRemaining: 0, removed: 0, videoStills: 0, blocking: false },
+  } as unknown as CaptureResult);
+
+  it("FAILS when scrollHeight is pinned to ~1 viewport at every width but IR content spans multiple viewports", () => {
+    const res = gatePollution(mkIr(), mkCapture(800), [1280]);
+    assert.equal(res.pass, false, "the scroll-locked contradiction is caught");
+    assert.ok(res.issues.some((i) => i.includes("scroll-locked capture")), `issue reported (got ${JSON.stringify(res.issues)})`);
+  });
+
+  it("PASSES when scrollHeight matches the tall content (a genuinely scrollable page)", () => {
+    const res = gatePollution(mkIr(), mkCapture(5198), [1280]);
+    assert.ok(!res.issues.some((i) => i.includes("scroll-locked capture")), "no false positive when the page really scrolled");
+  });
+});

From db0054e43bd202e699f9e64428a356ad488130d9 Mon Sep 17 00:00:00 2001
From: Samraaj Bath <samraaj100@gmail.com>
Date: Sat, 4 Jul 2026 01:44:12 -0700
Subject: [PATCH 10/24] Emit html background only when the source html paints
 one

Painting the body's color onto a transparent source html flips CSS 2.1
background propagation: body's background stops propagating to the canvas
and paints above negative-z descendants, burying full-bleed z<0 hero
backdrops under an opaque page background. Emit the html rule only when
the source html actually painted one; fall back to #ffffff only when both
html and body are transparent. Applies to the Next globals, Tailwind, and
multi-route Vite paths via shared helpers.

6 new tests; suite at 322 green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 compiler/src/generate/app.ts      | 33 ++++++++++++++++++++---
 compiler/src/generate/tailwind.ts |  5 ++--
 compiler/src/site/generateSite.ts |  9 +++----
 compiler/test/htmlBg.test.ts      | 44 +++++++++++++++++++++++++++++++
 4 files changed, 79 insertions(+), 12 deletions(-)
 create mode 100644 compiler/test/htmlBg.test.ts

diff --git a/compiler/src/generate/app.ts b/compiler/src/generate/app.ts
index 0e3c39e..f5376ce 100644
--- a/compiler/src/generate/app.ts
+++ b/compiler/src/generate/app.ts
@@ -2250,10 +2250,36 @@ ${head}      <body${bodyAttrs}>
 `;
 }
 
+const TRANSPARENT_BG = "rgba(0, 0, 0, 0)";
+
+/** Decide what background (if any) the clone's `html` element should paint.
+ *
+ * Per CSS 2.1 §14.2, when `html` is transparent the `body` background propagates
+ * to the canvas and paints *beneath* every descendant — including negative-z-index
+ * layers (full-bleed hero video/image/canvas backdrops). The moment `html` paints
+ * an opaque background, `body` stops propagating and paints its own in-flow block
+ * background, which sits *above* negative-z descendants and buries them.
+ *
+ * So we only give `html` a background when the SOURCE `html` actually painted one.
+ * A transparent source `html` stays transparent (returns null → no rule emitted), so
+ * the captured body background propagates to the canvas exactly as in the source.
+ * The white fallback applies only when BOTH html and body are transparent, otherwise
+ * the UA-default canvas would show through. Deterministic: pure function of the IR. */
+export function resolveHtmlBg(pv: { htmlBg?: string; bodyBg?: string } | undefined): string | null {
+  const srcHtmlBg = pv?.htmlBg && pv.htmlBg !== TRANSPARENT_BG ? pv.htmlBg : null;
+  const srcBodyBg = pv?.bodyBg && pv.bodyBg !== TRANSPARENT_BG ? pv.bodyBg : null;
+  return srcHtmlBg ?? (srcBodyBg ? null : "#ffffff");
+}
+
+/** `html { background: … }` rule, or empty string when html should stay transparent. */
+export function htmlBgRule(htmlBg: string | null): string {
+  return htmlBg !== null ? `html { background: ${htmlBg}; }\n` : "";
+}
+
 function generateGlobalsCss(ir: IR, fontGraph: FontGraph, tokensCss: string): string {
   const cw = ir.doc.canonicalViewport;
   const pv = ir.doc.perViewport[cw];
-  const htmlBg = pv?.htmlBg && pv.htmlBg !== "rgba(0, 0, 0, 0)" ? pv.htmlBg : (pv?.bodyBg ?? "#ffffff");
+  const htmlBg = resolveHtmlBg(pv);
   // If the SOURCE page never scrolls horizontally (its scrollWidth fits the
   // viewport at every captured width), neither should the clone. JS-driven
   // widgets (custom-element carousels, sliders) position children off-axis via
@@ -2271,8 +2297,7 @@ ${fontGraph.css}
 ${tokensCss}
 
 /* page base */
-html { background: ${htmlBg}; }
-body { font-family: ${SYSTEM_FALLBACK}; }${clip}
+${htmlBgRule(htmlBg)}body { font-family: ${SYSTEM_FALLBACK}; }${clip}
 `;
 }
 
@@ -2643,7 +2668,7 @@ export function generateApp(input: GenerateInput, tokensCss: string): { pageTsx:
   if (tw) {
     const cw = ir.doc.canonicalViewport;
     const pv = ir.doc.perViewport[cw];
-    const htmlBg = pv?.htmlBg && pv.htmlBg !== "rgba(0, 0, 0, 0)" ? pv.htmlBg : (pv?.bodyBg ?? "#ffffff");
+    const htmlBg = resolveHtmlBg(pv);
     const noHScroll = Object.entries(ir.doc.perViewport).every(([vp, d]) => d.scrollWidth <= Number(vp) * 1.03);
     const clip = noHScroll ? "\nhtml, body { overflow-x: clip; }" : "";
     const globals = tailwindGlobalsCss({
diff --git a/compiler/src/generate/tailwind.ts b/compiler/src/generate/tailwind.ts
index cd905e9..c3d09bf 100644
--- a/compiler/src/generate/tailwind.ts
+++ b/compiler/src/generate/tailwind.ts
@@ -1273,7 +1273,7 @@ export function buildTailwind(ir: IR, assetMap: Map<string, string>, colorVar?:
  *  + breakpoint bindings, our token :root, and our reset/fonts/page-base inside @layer base
  *  so utilities override them. */
 export function tailwindGlobalsCss(opts: {
-  reset: string; fontCss: string; tokensCss: string; htmlBg: string; bodyFont: string;
+  reset: string; fontCss: string; tokensCss: string; htmlBg: string | null; bodyFont: string;
   clip: string; colorTokens: string[]; viewports: number[]; canonical: number;
 }): string {
   const screens = [
@@ -1301,8 +1301,7 @@ ${opts.tokensCss}
 ${opts.reset}
 /* fonts */
 ${opts.fontCss}
-html { background: ${opts.htmlBg}; }
-body { font-family: ${opts.bodyFont}; }${opts.clip}
+${opts.htmlBg !== null ? `html { background: ${opts.htmlBg}; }\n` : ""}body { font-family: ${opts.bodyFont}; }${opts.clip}
 }
 `;
 }
diff --git a/compiler/src/site/generateSite.ts b/compiler/src/site/generateSite.ts
index 3dc3aaf..d73265e 100644
--- a/compiler/src/site/generateSite.ts
+++ b/compiler/src/site/generateSite.ts
@@ -15,7 +15,7 @@ import { generateCss, RESET_CSS } from "../generate/css.js";
 import { generateInteractionCss } from "../generate/interactionCss.js";
 import { buildRuntimeSpecs, wiresJsx, dittoWireImportPath, DITTO_WIRE_TSX, interactionRejectedSet } from "../generate/interactive.js";
 import { buildLottieSpec, lottieHasContent, lottieWireJsx, dittoLottieImportPath, DITTO_LOTTIE_TSX } from "../generate/lottie.js";
-import { renderChildrenJsx, renderAttrs, buildComponentRegistry, componentPreamble, componentFiles, componentImports, componentDataDecls, summarizeComponents, fileBase, generateViteConfig, generateViteIndexHtml, viteGlobalsCss, cnImportLine, CN_UTILS_MODULE, PACKAGE_JSON, PACKAGE_JSON_TW, PACKAGE_JSON_VITE, PACKAGE_JSON_VITE_TW, TSCONFIG_JSON, TSCONFIG_JSON_VITE, NEXT_CONFIG, injectLottieDep, type AppFramework, type LinkRewrite, type ExtractedComponent, type RenderCtx } from "../generate/app.js";
+import { renderChildrenJsx, renderAttrs, buildComponentRegistry, componentPreamble, componentFiles, componentImports, componentDataDecls, summarizeComponents, fileBase, generateViteConfig, generateViteIndexHtml, viteGlobalsCss, cnImportLine, resolveHtmlBg, htmlBgRule, CN_UTILS_MODULE, PACKAGE_JSON, PACKAGE_JSON_TW, PACKAGE_JSON_VITE, PACKAGE_JSON_VITE_TW, TSCONFIG_JSON, TSCONFIG_JSON_VITE, NEXT_CONFIG, injectLottieDep, type AppFramework, type LinkRewrite, type ExtractedComponent, type RenderCtx } from "../generate/app.js";
 import { buildTailwind, tailwindGlobalsCss, createColorInterner, colorDefsCssOf, type TailwindOutput } from "../generate/tailwind.js";
 import type { InteractionCapture } from "../capture/interactions.js";
 import type { IRChild } from "../normalize/ir.js";
@@ -91,10 +91,10 @@ function unionFontCss(routes: RouteArtifact[]): string {
 
 /** Shared page-base bits (entry html background + overflow-x clip) — same rationale as
  *  single-page generation; used by both the plain-CSS and Tailwind globals. */
-function pageBaseOf(entry: RouteArtifact): { htmlBg: string; clip: string } {
+function pageBaseOf(entry: RouteArtifact): { htmlBg: string | null; clip: string } {
   const cw = entry.ir.doc.canonicalViewport;
   const pv = entry.ir.doc.perViewport[cw];
-  const htmlBg = pv?.htmlBg && pv.htmlBg !== "rgba(0, 0, 0, 0)" ? pv.htmlBg : (pv?.bodyBg ?? "#ffffff");
+  const htmlBg = resolveHtmlBg(pv);
   const noHScroll = Object.entries(entry.ir.doc.perViewport).every(([vp, d]) => d.scrollWidth <= Number(vp) * 1.03);
   return { htmlBg, clip: noHScroll ? "\nhtml, body { overflow-x: clip; }" : "" };
 }
@@ -112,8 +112,7 @@ ${paletteCss}
 ${tokensToCss(entry.tokens, true)}
 
 /* page base */
-html { background: ${htmlBg}; }
-body { font-family: ${SYSTEM_FALLBACK}; }${clip}
+${htmlBgRule(htmlBg)}body { font-family: ${SYSTEM_FALLBACK}; }${clip}
 `;
 }
 
diff --git a/compiler/test/htmlBg.test.ts b/compiler/test/htmlBg.test.ts
new file mode 100644
index 0000000..34f64d2
--- /dev/null
+++ b/compiler/test/htmlBg.test.ts
@@ -0,0 +1,44 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { resolveHtmlBg, htmlBgRule } from "../src/generate/app.js";
+
+// Regression: when the source layers a full-bleed backdrop at z-index<0 behind a
+// body-propagated canvas background, emitting an opaque `html { background }`
+// flips CSS 2.1 §14.2 background propagation and buries that backdrop under the
+// body box. `html` must only paint when the SOURCE html actually painted.
+describe("resolveHtmlBg — source-faithful canvas propagation", () => {
+  it("transparent html + colored body → no html background (body propagates to canvas)", () => {
+    const htmlBg = resolveHtmlBg({ htmlBg: "rgba(0, 0, 0, 0)", bodyBg: "rgb(246, 244, 238)" });
+    assert.equal(htmlBg, null);
+    assert.equal(htmlBgRule(htmlBg), "");
+  });
+
+  it("colored html → html background kept", () => {
+    const htmlBg = resolveHtmlBg({ htmlBg: "rgb(10, 20, 30)", bodyBg: "rgb(246, 244, 238)" });
+    assert.equal(htmlBg, "rgb(10, 20, 30)");
+    assert.equal(htmlBgRule(htmlBg), "html { background: rgb(10, 20, 30); }\n");
+  });
+
+  it("both transparent → #ffffff fallback (never a UA-default canvas)", () => {
+    const htmlBg = resolveHtmlBg({ htmlBg: "rgba(0, 0, 0, 0)", bodyBg: "rgba(0, 0, 0, 0)" });
+    assert.equal(htmlBg, "#ffffff");
+    assert.equal(htmlBgRule(htmlBg), "html { background: #ffffff; }\n");
+  });
+
+  it("missing perViewport entry → #ffffff fallback", () => {
+    const htmlBg = resolveHtmlBg(undefined);
+    assert.equal(htmlBg, "#ffffff");
+  });
+
+  it("undefined html + colored body (only body captured) → no html rule", () => {
+    // Body-only styling is the common case the old fallback existed for; it must
+    // still leave html transparent so the body color reaches the canvas.
+    const htmlBg = resolveHtmlBg({ bodyBg: "rgb(0, 0, 0)" });
+    assert.equal(htmlBg, null);
+  });
+
+  it("deterministic: identical input yields identical output", () => {
+    const pv = { htmlBg: "rgba(0, 0, 0, 0)", bodyBg: "rgb(1, 2, 3)" };
+    assert.equal(resolveHtmlBg(pv), resolveHtmlBg({ ...pv }));
+  });
+});

From 6e4921884cea64b1deadfc3a3b4c81aa4c59d1ec Mon Sep 17 00:00:00 2001
From: Samraaj Bath <samraaj100@gmail.com>
Date: Sat, 4 Jul 2026 02:22:15 -0700
Subject: [PATCH 11/24] Hover capture via forced pseudo-state, text-wrap
 support, per-viewport video source re-selection, svg paint recovery, semantic
 tokens & section naming

Capture:
- Hover/focus states are driven with CDP CSS.forcePseudoState instead of
  moving the real cursor - transparent full-viewport overlay layers were
  swallowing every pointer hover, silently capturing zero hover states on
  hover-rich sites
- text-wrap (balance/pretty) captured and emitted (Tailwind text-balance/
  text-pretty, arbitrary fallback)
- Videos re-run <source> selection per viewport before frame-0
  normalization: resize-without-reload kept aspect-gated variants stuck on
  the load-time choice, poisoning mobile ground-truth screenshots
- svg roots capture their computed paint; fill="none" with a computed
  paint (the fill-current pattern) recovers the real color instead of
  rendering blank

Tokens & naming:
- Full CSS-Color-4 parsing (oklab/oklch/lab/lch/hsl) so modern colors
  cluster and earn semantic roles; visually-equal literals share one token;
  decoration/gradient/shadow colors consult the palette before minting
  opaque tokens (ridge: 45 opaque tokens -> 15, anthropic: 12 -> 7)
- Expanded role vocabulary (background/foreground/primary/accent/border/
  surface/muted) with deterministic tiebreaks and a chroma guard
- Section names mine CMS section ids and js-* hooks with hashy-suffix
  stripping (split_callout_JtTWTt -> split-callout-section)

364 tests pass (42 new), typecheck clean; determinism verified by
double-regen byte-comparison on two reference runs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 compiler/src/capture/capture.ts         |  80 +++++++++++
 compiler/src/capture/interactions.ts    |  77 ++++++++---
 compiler/src/capture/walker.ts          |  17 +++
 compiler/src/generate/app.ts            |  72 +++++++++-
 compiler/src/generate/css.ts            |   4 +-
 compiler/src/generate/sectionSplit.ts   |  84 ++++++++++-
 compiler/src/generate/tailwind.ts       |  32 ++++-
 compiler/src/infer/semanticTokens.ts    | 173 ++++++++++++++++++++---
 compiler/src/normalize/ir.ts            |   4 +
 compiler/test/css.test.ts               |  36 +++++
 compiler/test/interactions.test.ts      |  90 ++++++++++++
 compiler/test/semanticNaming.test.ts    | 177 ++++++++++++++++++++++++
 compiler/test/svgRootFill.test.ts       |  60 ++++++++
 compiler/test/tailwind.test.ts          |  18 +++
 compiler/test/videoSourceSelect.test.ts |  66 +++++++++
 compiler/test/walker.test.ts            |  32 +++++
 16 files changed, 968 insertions(+), 54 deletions(-)
 create mode 100644 compiler/test/interactions.test.ts
 create mode 100644 compiler/test/semanticNaming.test.ts
 create mode 100644 compiler/test/svgRootFill.test.ts
 create mode 100644 compiler/test/videoSourceSelect.test.ts

diff --git a/compiler/src/capture/capture.ts b/compiler/src/capture/capture.ts
index 6a4753f..6e74e9e 100644
--- a/compiler/src/capture/capture.ts
+++ b/compiler/src/capture/capture.ts
@@ -182,6 +182,41 @@ export function looksLikeVideoFile(bytes: Buffer): boolean {
   return false;
 }
 
+/**
+ * A `<source>` candidate for the HTML media resource-selection algorithm. `media`/`type` are the
+ * raw attribute strings (null/undefined when absent, matching a missing attribute).
+ */
+export interface VideoSourceCandidate {
+  media?: string | null;
+  type?: string | null;
+}
+
+/**
+ * Pure re-implementation of the source-selection step of the HTML media resource-selection
+ * algorithm: return the index of the FIRST `<source>` (document order) that is eligible NOW, or -1
+ * when none is. A source is eligible when its `media` query matches (a missing/empty media matches
+ * unconditionally) AND the UA can play its `type` (a missing/empty type is not a disqualifier —
+ * `canPlayType` is only consulted when a type is present).
+ *
+ * The predicates are injected so this is testable in Node (the in-page caller passes the real
+ * `matchMedia`/`canPlayType`). Kept deterministic: no state, first-match wins in document order.
+ */
+export function selectVideoSourceIndex(
+  sources: VideoSourceCandidate[],
+  mediaMatches: (media: string) => boolean,
+  canPlay: (type: string) => boolean,
+): number {
+  for (let i = 0; i < sources.length; i++) {
+    const s = sources[i]!;
+    const media = (s.media ?? "").trim();
+    if (media && !mediaMatches(media)) continue;
+    const type = (s.type ?? "").trim();
+    if (type && !canPlay(type)) continue;
+    return i;
+  }
+  return -1;
+}
+
 async function autoScroll(page: import("playwright").Page, vpHeight: number): Promise<void> {
   // Scroll through the page to trigger lazy-loaded images/backgrounds, then return
   // to the top so document-coordinate bboxes are measured from a settled layout.
@@ -804,12 +839,57 @@ async function captureScreenshot(
  * diff that no CSS change can close. Seeking BOTH sides to frame 0 before EVERY viewport screenshot
  * removes it. `seeked` fires once the new frame is decoded; we still yield two rAFs so the compositor
  * has painted it before the screenshot reads pixels. Bounded so a stalled/unseekable video can't hang.
+ *
+ * FIRST it re-runs `<source media>` resource selection for THIS viewport. The capture pipeline loads
+ * the page once at the canonical width and reaches every other viewport by resizing — but the HTML
+ * media resource-selection algorithm evaluates `<source media>` only at load, so an aspect/orientation
+ * -gated hero video stays frozen on whatever variant matched at load width across all resized shots.
+ * The validator fresh-loads per viewport and correctly re-selects, so the two channels disagree on
+ * which variant is on screen (a large phantom diff on full-bleed portrait/landscape hero videos).
+ * Re-selecting here keeps the channels symmetric; it is a no-op on the fresh-loading validator side
+ * and — the common case — a no-op whenever the current selection is still the right one, so the fast
+ * path never touches `video.load()`.
  */
 export async function normalizeVideoTime(page: import("playwright").Page): Promise<void> {
   try {
     await page.evaluate(async () => {
       const vids = Array.from(document.querySelectorAll("video"));
       const raf = () => new Promise<void>((r) => requestAnimationFrame(() => r()));
+
+      // Re-select the <source> the resource-selection algorithm would pick at the CURRENT viewport,
+      // mirroring selectVideoSourceIndex (Node-side, unit-tested): first source in document order
+      // whose media matches (missing media matches unconditionally) and whose type is playable
+      // (missing type is never disqualifying). Only reload when the winner differs from what is
+      // currently loaded — the fast path leaves untouched videos alone.
+      const reloadWaits: Promise<void>[] = [];
+      for (const v of vids) {
+        try {
+          const sources = Array.from(v.querySelectorAll("source"));
+          if (sources.length === 0) continue; // src attribute (no <source> children): nothing to re-select
+          let winner: HTMLSourceElement | null = null;
+          for (const s of sources) {
+            const media = (s.getAttribute("media") ?? "").trim();
+            if (media && !window.matchMedia(media).matches) continue;
+            const type = (s.getAttribute("type") ?? "").trim();
+            if (type && !v.canPlayType(type)) continue;
+            winner = s;
+            break;
+          }
+          if (!winner || !winner.src) continue;
+          // Compare resolved URLs; currentSrc is absolute, winner.src is already resolved.
+          if (v.currentSrc === winner.src) continue; // no change — fast path, do not reload
+          v.load();
+          reloadWaits.push(new Promise<void>((resolve) => {
+            let settled = false;
+            const done = () => { if (settled) return; settled = true; v.removeEventListener("loadeddata", done); resolve(); };
+            if (v.readyState >= 2 /* HAVE_CURRENT_DATA */) { done(); return; }
+            v.addEventListener("loadeddata", done, { once: true });
+            setTimeout(done, 4000); // bound: a stalled reload resolves anyway so the shot never hangs
+          }));
+        } catch { /* a malformed <source>/media query must not block the others */ }
+      }
+      if (reloadWaits.length) await Promise.all(reloadWaits);
+
       const waits: Promise<void>[] = [];
       for (const v of vids) {
         try { v.pause(); } catch { /* ignore */ }
diff --git a/compiler/src/capture/interactions.ts b/compiler/src/capture/interactions.ts
index 3f216c5..48ffeda 100644
--- a/compiler/src/capture/interactions.ts
+++ b/compiler/src/capture/interactions.ts
@@ -24,6 +24,13 @@ const PSEUDO_PROPS = [
 
 export type StyleDelta = Record<string, string>;
 
+/** Changed-properties delta: every key in `b` whose value differs from `a`. Pure (unit-tested). */
+export function diffStyle(a: StyleDelta, b: StyleDelta): StyleDelta {
+  const d: StyleDelta = {};
+  for (const k of Object.keys(b)) if (a[k] !== b[k]) d[k] = b[k]!;
+  return d;
+}
+
 // Properties that distinguish a panel's shown/hidden state and a trigger's
 // active/inactive state. Captured per discrete state so the generated controller
 // can toggle between them faithfully (M2: tabs + accordion).
@@ -363,11 +370,42 @@ export async function captureInteractions(page: Page, opts?: { maxCandidates?: n
       return o;
     }, { capId, props: PSEUDO_PROPS as unknown as string[] });
 
-  const diff = (a: StyleDelta, b: StyleDelta): StyleDelta => {
-    const d: StyleDelta = {};
-    for (const k of Object.keys(b)) if (a[k] !== b[k]) d[k] = b[k]!;
-    return d;
+  const diff = diffStyle;
+
+  // Pseudo-state driver via CDP `CSS.forcePseudoState`. Pointer-based hovering (page.hover)
+  // moves the REAL cursor to the element's box centre, so the browser applies `:hover` to
+  // whatever sits under that point — on a page with a transparent full-viewport overlay (a
+  // fixed page-wrapper / scroll layer, common on modern builder stacks) the point lands on the
+  // overlay and the target never enters `:hover`, silently capturing ZERO authored hover states
+  // even though page.hover throws nothing. Forcing the pseudo-class on the node itself is
+  // geometry-independent (occlusion-immune), applies pure-CSS `:hover` rules directly, and — for
+  // `.card:hover .overlay` — also styles descendants of the forced node, so reveals still show.
+  // Resolves each cap → CDP nodeId; a live map is rebuilt per element (cheap) so it survives
+  // any DOM churn. Falls back to no forcing if a CDP session can't be opened (then hover/focus
+  // capture is simply empty rather than wrong).
+  const client = await page.context().newCDPSession(page).catch(() => null);
+  if (client) {
+    try { await client.send("DOM.enable"); await client.send("CSS.enable"); await client.send("DOM.getDocument", {}); }
+    catch { /* CDP unavailable — force() below no-ops */ }
+  }
+  const nodeIdFor = async (capId: string): Promise<number | null> => {
+    if (!client) return null;
+    let objectId: string | undefined;
+    try {
+      const ev = await client.send("Runtime.evaluate", { expression: `document.querySelector('[data-cid-cap="${capId}"]')` }) as { result?: { objectId?: string } };
+      objectId = ev.result?.objectId; if (!objectId) return null;
+      const r = await client.send("DOM.requestNode", { objectId }) as { nodeId?: number };
+      return r.nodeId ?? null;
+    } catch { return null; }
+    finally { if (objectId) await client.send("Runtime.releaseObject", { objectId }).catch(() => {}); }
   };
+  // Force (or clear, with []) a pseudo-class on a node. Deterministic and reversible.
+  const force = async (nodeId: number | null, classes: string[]): Promise<boolean> => {
+    if (!client || nodeId == null) return false;
+    try { await client.send("CSS.forcePseudoState", { nodeId, forcedPseudoClasses: classes }); return true; }
+    catch { return false; }
+  };
+  const settlePseudo = () => page.waitForTimeout(180); // let a `:hover`/`:focus` transition land
 
   // Reveal-relevant props for descendants that appear on hover (overlay glow + CTA). Only
   // clean show/hide props — NOT transform/filter, whose mid-animation values bake a janky
@@ -413,21 +451,21 @@ export async function captureInteractions(page: Page, opts?: { maxCandidates?: n
   const hoverDesc: Record<string, Record<string, StyleDelta>> = {};
 
   for (const capId of candidates) {
-    const sel = `[data-cid-cap="${capId}"]`;
     const base = await read(capId);
     if (!base) continue;
+    const nodeId = await nodeIdFor(capId);
     const hiddenBase = await readHiddenDesc(capId); // hidden descendants → hover-reveal candidates
     const hiddenCaps = Object.keys(hiddenBase);
-    // :hover — settle before reading: framer-style hover is driven by JS (Framer Motion)
-    // with a short transition, so an immediate read catches the pre-transition frame and
-    // sees no delta (the nav-link hover was missed this way). Wait for the transition to land.
-    try {
-      await page.hover(sel, { timeout: 1200, force: true });
-      await page.waitForTimeout(180);
+    // :hover — force the pseudo-class on the node (geometry-independent; see `force` above),
+    // then settle before reading: an authored `:hover`/JS transition animates from the resting
+    // frame, so an immediate read catches the pre-transition value and sees no delta. Wait for it.
+    if (await force(nodeId, ["hover"])) {
+      await settlePseudo();
       const h = await read(capId);
       if (h) { const d = diff(base, h); if (Object.keys(d).length) hover[capId] = d; }
       // Descendant reveals (while still hovered): a hidden child shown on hover — the card's
-      // OWN style is unchanged, so this is the only signal (framer's "Read story" overlay).
+      // OWN style is unchanged, so this is the only signal (a "Read story" overlay). Forcing
+      // `:hover` on the card also matches `.card:hover .overlay` rules on its descendants.
       if (hiddenCaps.length) {
         await page.waitForTimeout(380); // let the reveal transition fully finish before reading
         const after = await readDescProps(hiddenCaps);
@@ -444,16 +482,17 @@ export async function captureInteractions(page: Page, opts?: { maxCandidates?: n
         }
         if (Object.keys(revealed).length) hoverDesc[capId] = revealed;
       }
-    } catch { /* not hoverable (covered/offscreen) — skip */ }
-    await page.mouse.move(1, 1).catch(() => {});
-    // :focus (only for focusable-ish; cheap to attempt, guarded)
-    try {
-      await page.focus(sel, { timeout: 800 });
+      await force(nodeId, []); // clear :hover before probing :focus
+    }
+    // :focus — force the pseudo-class the same way (also occlusion-independent).
+    if (await force(nodeId, ["focus"])) {
+      await settlePseudo();
       const f = await read(capId);
       if (f) { const d = diff(base, f); if (Object.keys(d).length) focus[capId] = d; }
-      await page.evaluate(() => (document.activeElement as HTMLElement | null)?.blur());
-    } catch { /* not focusable — skip */ }
+      await force(nodeId, []); // restore the resting state
+    }
   }
+  await client?.detach().catch(() => {});
 
   log({ event: "interactions_hover_focus", candidates: candidates.length, hover: Object.keys(hover).length, focus: Object.keys(focus).length, hoverDesc: Object.keys(hoverDesc).length });
 
diff --git a/compiler/src/capture/walker.ts b/compiler/src/capture/walker.ts
index 54edb3f..818efaa 100644
--- a/compiler/src/capture/walker.ts
+++ b/compiler/src/capture/walker.ts
@@ -55,6 +55,10 @@ export type RawNode = {
   // clone renders the browser's default gray, losing the authored placeholder color/type.
   placeholder?: RawStyle;
   rawHTML?: string; // set for inline <svg>
+  // Computed paint of an inline <svg> root (fill/stroke/color). A raw `fill="none"` attribute may
+  // still resolve to a real paint via site CSS (`fill: currentColor`); these resolved values let
+  // codegen recover a paint the extraction stripped. Set only for svg roots.
+  svgPaint?: { fill: string; stroke: string; color: string };
   children: RawChild[];
 };
 
@@ -138,6 +142,11 @@ export function collectPage(opts?: { maxNodes?: number } | void): PageSnapshot {
     "letterSpacing", "wordSpacing", "textAlign", "textTransform",
     "textDecorationLine", "textDecorationColor", "textDecorationStyle",
     "whiteSpace", "wordBreak", "overflowWrap", "textOverflow", "textIndent",
+    // Modern line-wrapping: `text-wrap: balance/pretty` rebalances heading line breaks
+    // (getComputedStyle reports the shorthand — "balance"/"pretty"/"wrap"). Without it a
+    // balanced heading wraps differently in the clone (an even two-line title collapses
+    // to a lopsided break). Default "wrap" is elided downstream.
+    "textWrap",
     "textShadow", "fontVariantCaps", "fontFeatureSettings",
     // Line clamping (`display:-webkit-box; -webkit-box-orient:vertical; -webkit-line-clamp:N`):
     // the mechanism that keeps cards equal height regardless of text length. Without it the engine
@@ -464,6 +473,14 @@ export function collectPage(opts?: { maxNodes?: number } | void): PageSnapshot {
     // Inline SVG → raw markup, no recursion.
     if (tag === "svg") {
       node.rawHTML = el.outerHTML;
+      // Capture the svg root's COMPUTED paint (fill/stroke/color) separately from the general
+      // computed-prop list. A raw `fill="none"` presentation attribute paints nothing on its own; a
+      // wordmark/icon is visible on the source only because site CSS (a `fill: currentColor` class,
+      // an inherited `color`) overrides it. Extraction strips that CSS, so the raw attribute alone is
+      // misleading — codegen consults these resolved values to decide whether the root truly paints.
+      try {
+        node.svgPaint = { fill: cs.fill, stroke: cs.stroke, color: cs.color };
+      } catch { /* getComputedStyle already read above; guard against exotic UAs */ }
       return node;
     }
 
diff --git a/compiler/src/generate/app.ts b/compiler/src/generate/app.ts
index f5376ce..5b5f021 100644
--- a/compiler/src/generate/app.ts
+++ b/compiler/src/generate/app.ts
@@ -401,18 +401,34 @@ export function propsList(node: IRNode, assetMap: Map<string, string>, sourceUrl
     // surface verbatim in the markup and (post-extraction) as a bogus data field.
     const inner = svgInnerForNode(node, ctx);
     const svgAttrs = extractSvgAttrs(node.rawHTML);
-    let hasFillAttr = false;
+    let rawFill: string | undefined;
     for (const [k, v] of svgAttrs) {
-      if (k.toLowerCase() === "fill") hasFillAttr = true;
+      if (k.toLowerCase() === "fill") { rawFill = v; continue; } // the root fill is resolved below, not copied verbatim
       if (k === "class" || k === "style" || k === "data-cid-cap" || k.includes(":")) continue;
       const reactName = SVG_ATTR_RENAME[k] ?? k;
       const propKey = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(reactName) ? reactName : JSON.stringify(reactName);
       if (!props.some(([pk]) => pk === propKey)) props.push([propKey, JSON.stringify(v)]);
     }
-    // Raw SVG icons often rely on site CSS (`svg { fill: currentColor }` or a class) that is
-    // stripped during extraction. If the root didn't declare a fill, inherit the surrounding text
-    // color so monochrome wordmarks/icons don't fall back to the browser's black default.
-    if (!hasFillAttr && !props.some(([pk]) => pk === "fill")) props.push(["fill", JSON.stringify("currentColor")]);
+    // Reconcile the root fill against the captured COMPUTED paint. A raw `fill="none"` only looks
+    // unfilled: site CSS (`fill: currentColor` on the wordmark, an inherited color) may actually
+    // paint it, and that CSS is stripped during extraction. resolveSvgRootFill recovers the real
+    // paint — as currentColor when the computed fill tracks the element's color (emit that color
+    // too), else the literal value — and leaves a genuinely unfilled svg as fill="none". When the
+    // root declared no fill at all we fall back to currentColor so monochrome icons don't drop to
+    // the browser's black default.
+    if (!props.some(([pk]) => pk === "fill")) {
+      const resolved = resolveSvgRootFill(rawFill, node.svgPaint);
+      if (resolved.mode === "keep") {
+        if (rawFill !== undefined) props.push(["fill", JSON.stringify(rawFill)]);
+      } else if (resolved.mode === "emit") {
+        props.push(["fill", JSON.stringify(resolved.value!)]);
+        if (resolved.emitColor && !props.some(([pk]) => pk === "color")) {
+          props.push(["color", JSON.stringify(resolved.emitColor)]);
+        }
+      } else {
+        props.push(["fill", JSON.stringify("currentColor")]);
+      }
+    }
     props.push(["dangerouslySetInnerHTML", `{ __html: ${JSON.stringify(inner)} }`]);
   }
 
@@ -460,6 +476,50 @@ function extractSvgAttrs(outerHTML: string): Array<[string, string]> {
   return out;
 }
 
+/** A resolved paint value is "real" (paints something) when it is neither absent nor an explicit
+ * non-paint (`none`) nor fully transparent. `currentColor` counts as real (it paints the inherited
+ * color). Case/whitespace-insensitive. */
+export function isRealPaint(value: string | null | undefined): boolean {
+  const v = (value ?? "").trim().toLowerCase();
+  if (!v || v === "none" || v === "transparent") return false;
+  if (v === "rgba(0, 0, 0, 0)" || v === "rgba(0,0,0,0)") return false;
+  return true;
+}
+
+/**
+ * Decide what `fill` an inline <svg> ROOT should emit, reconciling the raw `fill` attribute against
+ * the svg's COMPUTED paint (captured from the live source). Pure and deterministic.
+ *
+ * - Raw `fill` present and itself a real paint → keep it (`keep`): the author meant that fill.
+ * - Raw `fill="none"` but the computed fill IS a real paint → the root only looked unfilled because
+ *   `fill="none"` is a presentation attribute the site's CSS overrode. Recover the real paint:
+ *   emit `currentColor` when the computed fill equals the computed `color` (a `fill: currentColor`
+ *   class — the common wordmark case; caller must also emit `color`), else the literal computed fill.
+ * - Raw `fill="none"` and computed fill also not a real paint → genuinely unfilled: keep `none`.
+ * - Raw `fill` absent → `fallback`: caller applies its existing currentColor default.
+ */
+export function resolveSvgRootFill(
+  rawFill: string | null | undefined,
+  computed?: { fill?: string; color?: string } | null,
+): { mode: "keep" | "fallback" | "emit"; value?: string; emitColor?: string } {
+  const raw = (rawFill ?? "").trim();
+  if (raw && raw.toLowerCase() !== "none") return { mode: "keep" };
+  if (raw.toLowerCase() === "none") {
+    const cf = computed?.fill;
+    if (isRealPaint(cf)) {
+      const color = (computed?.color ?? "").trim();
+      // fill:currentColor resolves to the element's color; recover it as currentColor so the clone
+      // tracks whatever color the surrounding CSS supplies, and signal the caller to emit that color.
+      if (color && cf!.trim().toLowerCase() === color.toLowerCase() && isRealPaint(color)) {
+        return { mode: "emit", value: "currentColor", emitColor: color };
+      }
+      return { mode: "emit", value: cf!.trim() };
+    }
+    return { mode: "keep" }; // genuinely unfilled — leave fill="none"
+  }
+  return { mode: "fallback" };
+}
+
 // SVG presentation attributes that React requires in camelCase (kebab in JSX is silently
 // dropped — and `fill-rule`/`clip-rule` being dropped changes how a path fills). Anything not
 // here that's already camel/lowercase (d, cx, fill, viewBox, opacity, transform, offset…) or a
diff --git a/compiler/src/generate/css.ts b/compiler/src/generate/css.ts
index a23569e..c0dc660 100644
--- a/compiler/src/generate/css.ts
+++ b/compiler/src/generate/css.ts
@@ -74,7 +74,7 @@ function isViewportHeight(value: string, width: number): boolean {
 const INHERITED = new Set([
   "color", "fontFamily", "fontSize", "fontWeight", "fontStyle", "lineHeight",
   "letterSpacing", "wordSpacing", "textAlign", "textTransform", "whiteSpace",
-  "wordBreak", "overflowWrap", "textIndent", "fontVariantCaps", "fontFeatureSettings",
+  "wordBreak", "overflowWrap", "textWrap", "textIndent", "fontVariantCaps", "fontFeatureSettings",
   "listStyleType", "listStylePosition", "writingMode", "direction", "cursor",
   "textShadow", "visibility", "textDecorationColor", "webkitTextStroke",
   "webkitTextFillColor",
@@ -139,6 +139,8 @@ const GENERIC: Array<{ prop: string; def: string | string[] }> = [
   { prop: "textDecorationStyle", def: "solid" },
   { prop: "whiteSpace", def: "__never__" }, { prop: "wordBreak", def: "__never__" },
   { prop: "overflowWrap", def: "__never__" }, { prop: "textIndent", def: "__never__" },
+  // text-wrap: elide the initial `wrap`; emit `balance`/`pretty`/`nowrap`/`stable`.
+  { prop: "textWrap", def: "wrap" },
   { prop: "textShadow", def: "__never__" }, { prop: "fontVariantCaps", def: "__never__" },
   { prop: "fontFeatureSettings", def: "__never__" }, { prop: "listStyleType", def: "__never_list__" },
   { prop: "listStylePosition", def: "__never__" }, { prop: "writingMode", def: "__never__" },
diff --git a/compiler/src/generate/sectionSplit.ts b/compiler/src/generate/sectionSplit.ts
index 5835654..7ae5e92 100644
--- a/compiler/src/generate/sectionSplit.ts
+++ b/compiler/src/generate/sectionSplit.ts
@@ -100,6 +100,83 @@ function identName(name: string): string {
   return /^[A-Za-z_$]/.test(name) ? name : "S" + name;
 }
 
+// Generic structural words that carry no section identity — dropped from source-derived names.
+const GENERIC_NAME_WORDS = new Set([
+  "section", "sections", "wrapper", "container", "block", "blocks", "template", "templates",
+  "group", "inner", "outer", "content", "contents", "row", "col", "column", "grid", "layout",
+  "shopify", "js", "tvg", "elementor", "wp", "widget", "module", "region", "main", "page",
+  "component", "components", "el", "root", "body", "area", "box", "item", "items", "wrap",
+]);
+
+/** A trailing token looks like a build hash (mixed-case or long alnum entropy, e.g.
+ *  `JtTWTt`, `RbEALJ`, `x19f2a`, `dDMm2q`) rather than a real word — strip it. A token is
+ *  hashy when it is ≥4 chars and either mixes upper+lower case or is a long digit-bearing run. */
+function looksHashy(tok: string): boolean {
+  if (tok.length < 4) return false;
+  const hasUpper = /[A-Z]/.test(tok), hasLower = /[a-z]/.test(tok), hasDigit = /\d/.test(tok);
+  if (hasUpper && hasLower) return true;                 // camel/entropy hash: JtTWTt, dDMm2q
+  if (hasDigit && tok.length >= 6) return true;          // long id run: 19797275672650
+  if (!/[aeiou]/i.test(tok) && tok.length >= 5) return true; // vowelless run: bcdfgh
+  return false;
+}
+
+/** Turn a source id/class token stream into ≤3 semantic PascalCase words, or "" when the
+ *  evidence is all-generic or hashy. Strips CMS prefixes (shopify-section-…__), leading
+ *  numeric template ids, generic structural words, and trailing hash suffixes. Exported for
+ *  tests (the hashy-suffix stripping + generic-word filtering is the load-bearing part). */
+export function nameFromSourceToken(raw: string): string {
+  // Peel known CMS section-id prefixes, keeping the semantic slug after `__` / the hook name.
+  // Case is preserved through prefix-stripping + tokenizing so `looksHashy` can see the
+  // mixed-case entropy of build hashes (RbEALJ, JtTWTt) BEFORE we normalize to lowercase.
+  const s = raw.trim()
+    .replace(/^shopify-section-(?:template|sections)--\d+__/i, "")
+    .replace(/^shopify-(?:section|block)-/i, "")
+    .replace(/^(?:js|tvg|elementor|wp|et|elementor-element)[-_]/i, "");
+  const tokens = s.split(/[\s\-_]+/).filter(Boolean);
+  const kept: string[] = [];
+  for (const t of tokens) {
+    if (kept.length >= 3) break;
+    if (/^\d+$/.test(t)) continue;                  // pure numeric template ids
+    if (GENERIC_NAME_WORDS.has(t.toLowerCase())) continue; // structural noise
+    if (looksHashy(t)) continue;                    // trailing entropy suffix (mixed-case aware)
+    if (t.length < 2) continue;
+    const lc = t.toLowerCase();
+    kept.push(lc[0]!.toUpperCase() + lc.slice(1));
+  }
+  return kept.join("");
+}
+
+// A source `id` (or `data-section-type`) is a DELIBERATE, developer-authored block name only
+// when it carries a recognized CMS section prefix — Shopify's `shopify-section-…__split_callout`,
+// or a generic `section-…`/`…-section`. Arbitrary utility classes (`g_section_space`,
+// `duraldar-cta_section`) are styling noise, so we do NOT mine class names — a truncated heading
+// slug reads better than a made-up name. `js-*` behaviour hooks ARE intentional and allowed.
+const CMS_SECTION_ID = /shopify-section|^section[-_]|[-_]section(?:[-_]|$)|data-section/i;
+
+/** Best semantic name derivable from a section subtree's source *ids* + `js-*` hooks — the
+ *  only source signals reliable enough to beat a heading slug. Scans the root + shallow
+ *  descendants. Returns "" when no trustworthy semantic evidence exists. */
+function sourceNameForSection(sec: IRNode): string {
+  const candidates: string[] = [];
+  const collect = (n: IRNode, depth: number): void => {
+    const id = n.attrs.id;
+    if (id && CMS_SECTION_ID.test(id)) candidates.push(id);
+    const sectionType = n.attrs["data-section-type"] ?? n.attrs["data-section"];
+    if (sectionType) candidates.push(sectionType);
+    if (n.srcClass) {
+      // Only explicit `js-…` behaviour hooks — a deliberate semantic handle, not a utility class.
+      for (const cls of n.srcClass.split(/\s+/)) if (/^js[-_][a-z]/i.test(cls)) candidates.push(cls);
+    }
+    if (depth > 0) for (const c of elementChildren(n)) collect(c, depth - 1);
+  };
+  collect(sec, 2);
+  for (const c of candidates) {
+    const name = nameFromSourceToken(c);
+    if (name && name.length >= 3) return name;
+  }
+  return "";
+}
+
 function looksLikeNav(n: IRNode, cw: number): boolean {
   if (n.tag === "nav" || n.tag === "header") return true;
   if (subtreeHasTag(n, "nav")) return true;
@@ -279,8 +356,13 @@ export function planSections(ir: IR, recipes?: RecipeReport): SectionPlan {
     } else if (recipeName) {
       name = recipeName;
     } else {
+      // Prefer a clean semantic name from the source markup (Shopify/CMS section ids +
+      // `js-*` hooks, hash suffixes stripped) over a truncated heading slug — the source
+      // slug (`split_callout` → SplitCalloutSection) reads more like a hand-authored name.
+      const sourceName = sourceNameForSection(sec);
       const slug = slugWords(titleText(sec));
-      name = slug ? `${slug}Section`
+      name = sourceName ? `${sourceName}Section`
+        : slug ? `${slug}Section`
         : subtreeHasTag(sec, "form", 6) ? "ContactSection"
         : subtreeHasTag(sec, "video", 6) || subtreeHasTag(sec, "iframe", 6) ? "MediaSection"
         : `Section${i + 1}`;
diff --git a/compiler/src/generate/tailwind.ts b/compiler/src/generate/tailwind.ts
index c3d09bf..6849ca8 100644
--- a/compiler/src/generate/tailwind.ts
+++ b/compiler/src/generate/tailwind.ts
@@ -18,6 +18,7 @@
 import type { IR, IRNode } from "../normalize/ir.js";
 import { isTextChild } from "../normalize/ir.js";
 import { collectNodeRules, computeBands, keyframesCss, type NodeRule } from "./css.js";
+import { colorClusterKey } from "../infer/semanticTokens.js";
 import type { InteractionCapture, StyleDelta } from "../capture/interactions.js";
 
 // ---- arbitrary-value escaping ----
@@ -72,6 +73,7 @@ const KW: Record<string, Record<string, string>> = {
   "font-weight": { "100": "font-thin", "200": "font-extralight", "300": "font-light", "400": "font-normal", "500": "font-medium", "600": "font-semibold", "700": "font-bold", "800": "font-extrabold", "900": "font-black" },
   "text-decoration-line": { underline: "underline", "line-through": "line-through", overline: "overline", none: "no-underline" },
   "white-space": { nowrap: "whitespace-nowrap", normal: "whitespace-normal", pre: "whitespace-pre", "pre-line": "whitespace-pre-line", "pre-wrap": "whitespace-pre-wrap", "break-spaces": "whitespace-break-spaces" },
+  "text-wrap": { wrap: "text-wrap", nowrap: "text-nowrap", balance: "text-balance", pretty: "text-pretty" },
   "overflow-x": { hidden: "overflow-x-hidden", auto: "overflow-x-auto", scroll: "overflow-x-scroll", visible: "overflow-x-visible", clip: "overflow-x-clip" },
   "overflow-y": { hidden: "overflow-y-hidden", auto: "overflow-y-auto", scroll: "overflow-y-scroll", visible: "overflow-y-visible", clip: "overflow-y-clip" },
   "object-fit": { contain: "object-contain", cover: "object-cover", fill: "object-fill", none: "object-none", "scale-down": "object-scale-down" },
@@ -1039,11 +1041,12 @@ export type TailwindOutput = {
 export type ColorInterner = {
   defs: Map<string, string>;    // minted token name → literal value
   byValue: Map<string, string>; // literal value → minted token name
+  byKey: Map<string, string>;   // rounded-sRGB cluster key → minted token name (visual dedup)
   tokens: Set<string>;          // ALL referenced color token names (palette + minted)
   seq: { n: number };           // monotonic counter for clr-N names
 };
 export function createColorInterner(): ColorInterner {
-  return { defs: new Map(), byValue: new Map(), tokens: new Set(), seq: { n: 0 } };
+  return { defs: new Map(), byValue: new Map(), byKey: new Map(), tokens: new Set(), seq: { n: 0 } };
 }
 /** `:root { --clr-N: <literal>; … }` for the interner's minted tokens (empty if none). */
 export function colorDefsCssOf(it: ColorInterner): string {
@@ -1126,12 +1129,31 @@ export function buildTailwind(ir: IR, assetMap: Map<string, string>, colorVar?:
   indexNode(ir.root);
 
   // Color interner: every distinct color value → a stable theme token referenced as
-  // var(--…). Palette colors already arrive as var(--color-*) (kept, semantic); any other
-  // color is minted a numbered token (--clr-N) so raw rgb/hex NEVER lands in markup.
-  // The token holds the literal value, minted in deterministic first-encounter order.
+  // var(--…). A color the semantic palette recognizes (exactly OR within the grader's ±2
+  // sRGB tolerance — the same tolerance css.ts already trusts for color/bg/border) reuses
+  // that SEMANTIC name (--primary, --surface, --color-001…), so oklab/lch colours reached
+  // only through decoration/gradient/shadow props no longer each mint a fresh opaque
+  // --clr-N. Only colours with NO palette role fall through to a numbered --clr-N token,
+  // minted in deterministic first-encounter order (the literal is kept, byte-exact).
   const internColor = (literal: string): string => {
+    const semantic = colorVar?.(literal);
+    if (semantic) { const n = tokenName(semantic); if (n) colorTokens.add(n); return semantic; }
     let name = interner.byValue.get(literal);
-    if (!name) { name = `clr-${interner.seq.n++}`; interner.byValue.set(literal, name); interner.defs.set(name, literal); }
+    if (!name) {
+      // Dedup visually-identical literals (many oklab()/lch() forms round to the same sRGB):
+      // reuse the token minted for that colour rather than a fresh --clr-N. Fidelity-neutral —
+      // the grader compares in sRGB and the shared token holds the FIRST literal (within ±0 of
+      // its own colour). Values that don't parse fall back to exact-literal keying.
+      const key = colorClusterKey(literal);
+      const existing = key ? interner.byKey.get(key) : undefined;
+      if (existing) { name = existing; interner.byValue.set(literal, name); }
+      else {
+        name = `clr-${interner.seq.n++}`;
+        interner.byValue.set(literal, name);
+        interner.defs.set(name, literal);
+        if (key) interner.byKey.set(key, name);
+      }
+    }
     colorTokens.add(name);
     return `var(--${name})`;
   };
diff --git a/compiler/src/infer/semanticTokens.ts b/compiler/src/infer/semanticTokens.ts
index 10bc0bb..a68eaa0 100644
--- a/compiler/src/infer/semanticTokens.ts
+++ b/compiler/src/infer/semanticTokens.ts
@@ -27,12 +27,117 @@ export type ColorPalette = {
 const TRANSPARENT = new Set(["rgba(0, 0, 0, 0)", "transparent", "rgba(0,0,0,0)", ""]);
 
 type RGBA = [number, number, number, number];
+
+/** Parse the numeric args of a `fn(a b c / d)` / `fn(a,b,c,d)` color into [a,b,c,alpha].
+ *  Percentages resolve against `pctBase` (255 for rgb channels, 1 for lab/lch/oklab/oklch
+ *  L and the c/ab axes where the caller passes their own scale). `none` → 0. */
+function parseColorArgs(inner: string): { nums: number[]; alpha: number } | null {
+  const parts = inner.split("/");
+  const main = parts[0]!.trim().split(/[\s,]+/).filter(Boolean);
+  const nums = main.map((s) => (s === "none" ? 0 : parseFloat(s)));
+  if (nums.length < 3 || nums.slice(0, 3).some(Number.isNaN)) return null;
+  let alpha = 1;
+  const alphaTok = parts.length > 1 ? parts[1]!.trim() : main[3];
+  if (alphaTok !== undefined && alphaTok !== "none") {
+    const a = alphaTok.endsWith("%") ? parseFloat(alphaTok) / 100 : parseFloat(alphaTok);
+    if (!Number.isNaN(a)) alpha = a;
+  }
+  return { nums, alpha };
+}
+
+function pctOr(tok: string, base: number): number {
+  return tok.endsWith("%") ? (parseFloat(tok) / 100) * base : parseFloat(tok);
+}
+
+/** Linear-light sRGB channel → gamma-encoded 0–255. */
+function lin2srgb(c: number): number {
+  const v = c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
+  return Math.round(Math.min(1, Math.max(0, v)) * 255);
+}
+
+/** OKLab → sRGB (CSS Color 4 reference matrices). Returns gamma-encoded 0–255. */
+function oklabToRgb(L: number, a: number, b: number): [number, number, number] {
+  const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+  const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+  const s_ = L - 0.0894841775 * a - 1.2914855480 * b;
+  const l = l_ ** 3, m = m_ ** 3, s = s_ ** 3;
+  const r = +4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s;
+  const g = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s;
+  const bl = -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s;
+  return [lin2srgb(r), lin2srgb(g), lin2srgb(bl)];
+}
+
+/** CIE Lab (D50) → sRGB, gamma-encoded 0–255. */
+function labToRgb(L: number, a: number, b: number): [number, number, number] {
+  const fy = (L + 16) / 116, fx = fy + a / 500, fz = fy - b / 200;
+  const d = 6 / 29;
+  const inv = (t: number): number => (t > d ? t ** 3 : 3 * d * d * (t - 4 / 29));
+  // D50 white point.
+  const X = 0.9642956 * inv(fx), Y = 1.0 * inv(fy), Z = 0.8251046 * inv(fz);
+  // XYZ(D50) → linear sRGB (Bradford-adapted D50→D65 folded in).
+  const r = +3.1341359 * X - 1.6172206 * Y - 0.4906860 * Z;
+  const g = -0.9787684 * X + 1.9161415 * Y + 0.0334540 * Z;
+  const bl = +0.0719453 * X - 0.2289914 * Y + 1.4052427 * Z;
+  return [lin2srgb(r), lin2srgb(g), lin2srgb(bl)];
+}
+
+/** Parse any CSS color value (`rgb`/`rgba`/`hsl`/`hsla`/`oklab`/`oklch`/`lab`/`lch`/hex/
+ *  named-ish) into rounded sRGB `[r,g,b,alpha]`, else null. The literal value is kept
+ *  verbatim in emitted CSS; this RGB is used ONLY for clustering (grader works in sRGB
+ *  ±2), so oklab/lch colours cluster + earn semantic roles instead of falling to --clr-N. */
+function parseColor(v: string): RGBA | null {
+  const s = v.trim().toLowerCase();
+  if (s === "white") return [255, 255, 255, 1];
+  if (s === "black") return [0, 0, 0, 1];
+  const hex = /^#([0-9a-f]{3,8})$/i.exec(s);
+  if (hex) {
+    let h = hex[1]!;
+    if (h.length === 3 || h.length === 4) h = h.split("").map((c) => c + c).join("");
+    const r = parseInt(h.slice(0, 2), 16), g = parseInt(h.slice(2, 4), 16), b = parseInt(h.slice(4, 6), 16);
+    const a = h.length >= 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1;
+    return [r, g, b, a];
+  }
+  const fn = /^(rgba?|hsla?|oklab|oklch|lab|lch)\(([^)]*)\)$/i.exec(s);
+  if (!fn) return null;
+  const kind = fn[1]!, parsed = parseColorArgs(fn[2]!);
+  if (!parsed) return null;
+  const { nums, alpha } = parsed;
+  const raw = fn[2]!.split("/")[0]!.trim().split(/[\s,]+/).filter(Boolean);
+  if (kind.startsWith("rgb")) {
+    return [Math.round(pctOr(raw[0]!, 255)), Math.round(pctOr(raw[1]!, 255)), Math.round(pctOr(raw[2]!, 255)), alpha];
+  }
+  if (kind.startsWith("hsl")) {
+    const H = ((nums[0]! % 360) + 360) % 360, S = pctOr(raw[1]!, 1), Lh = pctOr(raw[2]!, 1);
+    const c = (1 - Math.abs(2 * Lh - 1)) * S, x = c * (1 - Math.abs(((H / 60) % 2) - 1)), m = Lh - c / 2;
+    const [r1, g1, b1] = H < 60 ? [c, x, 0] : H < 120 ? [x, c, 0] : H < 180 ? [0, c, x] : H < 240 ? [0, x, c] : H < 300 ? [x, 0, c] : [c, 0, x];
+    return [Math.round((r1 + m) * 255), Math.round((g1 + m) * 255), Math.round((b1 + m) * 255), alpha];
+  }
+  if (kind === "oklab") { const [r, g, b] = oklabToRgb(pctOr(raw[0]!, 1), nums[1]!, nums[2]!); return [r, g, b, alpha]; }
+  if (kind === "oklch") {
+    const L = pctOr(raw[0]!, 1), C = nums[1]!, h = (nums[2]! * Math.PI) / 180;
+    const [r, g, b] = oklabToRgb(L, C * Math.cos(h), C * Math.sin(h)); return [r, g, b, alpha];
+  }
+  if (kind === "lab") { const [r, g, b] = labToRgb(pctOr(raw[0]!, 100), nums[1]!, nums[2]!); return [r, g, b, alpha]; }
+  if (kind === "lch") {
+    const L = pctOr(raw[0]!, 100), C = nums[1]!, h = (nums[2]! * Math.PI) / 180;
+    const [r, g, b] = labToRgb(L, C * Math.cos(h), C * Math.sin(h)); return [r, g, b, alpha];
+  }
+  return null;
+}
+
+/** Back-compat alias: the palette parses every colour space now, not just rgb(). */
 function parseRgb(v: string): RGBA | null {
-  const m = v.match(/rgba?\(([^)]+)\)/i);
-  if (!m) return null;
-  const p = m[1]!.split(/[,\/]/).map((s) => parseFloat(s.trim()));
-  if (p.length < 3 || p.slice(0, 3).some(Number.isNaN)) return null;
-  return [Math.round(p[0]!), Math.round(p[1]!), Math.round(p[2]!), p.length >= 4 && !Number.isNaN(p[3]!) ? p[3]! : 1];
+  return parseColor(v);
+}
+
+/** A stable clustering key for a color literal: its rounded sRGB (+ alpha), so two literals
+ *  that render the same colour (`oklab(0.988242 …)` and `oklab(0.988371 …)` → rgb(251,251,251))
+ *  collapse to ONE minted token instead of a wall of near-identical --clr-N. Null when the
+ *  value can't be parsed (keeps the raw literal as its own key). Alpha bucketed to ±0.02. */
+export function colorClusterKey(v: string): string | null {
+  const c = parseColor(v);
+  if (!c) return null;
+  return `${c[0]},${c[1]},${c[2]},${Math.round(c[3] * 50)}`;
 }
 function within2(a: RGBA, b: RGBA): boolean {
   return Math.abs(a[0] - b[0]) <= 2 && Math.abs(a[1] - b[1]) <= 2 && Math.abs(a[2] - b[2]) <= 2 && Math.abs(a[3] - b[3]) <= 0.04;
@@ -140,33 +245,57 @@ function paletteFrom(usage: Map<string, Usage>, roleIr: IR, minCount: number): C
   const fgCluster = findCluster(pv?.bodyColor);
   if (fgCluster) assign("--foreground", fgCluster);
 
-  // 2) Primary/accent: most-used chromatic color, weighted toward interactive usage.
-  const remaining = clusters.filter((c) => !c.members.some((m) => valueToName.has(m)));
+  // Luminance (0–1) for deterministic tiebreaks (Rec.709). Ties in every ranking below
+  // break by count, then luminance (dark→light), then the literal value — so the palette
+  // is byte-stable for a given capture (determinism gate 6).
+  const lum = (c: Usage): number => (0.2126 * c.rgba[0] + 0.7152 * c.rgba[1] + 0.0722 * c.rgba[2]) / 255;
+  const unnamed = (c: { canon: Usage; members: string[] }): boolean => !c.members.some((m) => valueToName.has(m));
+  const byCount = (score: (c: Usage) => number) => (a: { canon: Usage }, b: { canon: Usage }): number =>
+    score(b.canon) - score(a.canon) || b.canon.count - a.canon.count || lum(a.canon) - lum(b.canon) || a.canon.value.localeCompare(b.canon.value);
+
+  // 2) Brand + accent: the most-used chromatic colours, weighted toward interactive usage
+  //    (buttons/links). `--primary` (a.k.a. brand) is the strongest; `--accent` the next.
+  //    A colour is "chromatic" only with real hue: HSL saturation ≥ 0.25 AND an absolute
+  //    channel spread ≥ 24, so near-neutral off-whites/creams (max−min ≈ 10) that merely
+  //    tip over the ratio threshold stay neutrals → --surface, not a fake --accent.
+  const chroma = (c: RGBA): number => Math.max(c[0], c[1], c[2]) - Math.min(c[0], c[1], c[2]);
+  const remaining = clusters.filter(unnamed);
   const chromatic = remaining
-    .filter((c) => { const { s } = satLight(c.canon.rgba); return s >= 0.25; })
-    .sort((a, b) => (b.canon.interactive * 3 + b.canon.count) - (a.canon.interactive * 3 + a.canon.count));
+    .filter((c) => satLight(c.canon.rgba).s >= 0.25 && chroma(c.canon.rgba) >= 24)
+    .sort(byCount((c) => c.interactive * 3 + c.count));
   if (chromatic[0]) assign("--primary", chromatic[0]);
   if (chromatic[1]) assign("--accent", chromatic[1]);
 
-  // 3) Border: most-used color that appears predominantly as a border.
+  // 3) Border: most-used colour that appears predominantly as a border.
   const borderC = remaining
-    .filter((c) => !c.members.some((m) => valueToName.has(m)) && c.canon.border > 0)
-    .sort((a, b) => b.canon.border - a.canon.border)[0];
+    .filter((c) => unnamed(c) && c.canon.border > 0)
+    .sort(byCount((c) => c.border))[0];
   if (borderC && borderC.canon.border >= Math.max(2, minCount - 1)) assign("--border", borderC);
 
-  // 4) Neutrals: a light neutral used as a background → surface; a mid neutral text → muted.
-  for (const c of remaining) {
-    if (c.members.some((m) => valueToName.has(m))) continue;
-    if (c.canon.count < minCount) continue;
-    const { s, l } = satLight(c.canon.rgba);
-    if (s < 0.15 && c.canon.bg >= c.canon.text && l > 0.85 && !taken.has("--surface")) assign("--surface", c);
-    else if (s < 0.2 && c.canon.text >= c.canon.bg && l > 0.35 && l < 0.7 && !taken.has("--muted-foreground")) assign("--muted-foreground", c);
+  // 4) Neutrals, ranked so the most-used earns the cleanest name. Light neutrals used as
+  //    backgrounds → --surface, --surface-2, … (section/card/footer alt backgrounds);
+  //    mid/dark neutrals used as text → --muted-foreground then --muted. "Neutral" is the
+  //    complement of "chromatic" above (no strong hue: low saturation OR tiny channel spread),
+  //    so no colour falls through the gap between the two thresholds.
+  const neutrals = remaining
+    .filter((c) => unnamed(c) && c.canon.count >= minCount && (satLight(c.canon.rgba).s < 0.25 || chroma(c.canon.rgba) < 24))
+    .sort(byCount((c) => c.count));
+  let surfaceN = 0;
+  for (const c of neutrals) {
+    if (!unnamed(c)) continue;
+    const { l } = satLight(c.canon.rgba);
+    if (c.canon.bg >= c.canon.text && l > 0.85) {
+      assign(surfaceN === 0 ? "--surface" : `--surface-${surfaceN + 1}`, c);
+      surfaceN++;
+    } else if (c.canon.text >= c.canon.bg && l > 0.2 && l < 0.7) {
+      assign(!taken.has("--muted-foreground") ? "--muted-foreground" : "--muted", c);
+    }
   }
 
-  // 5) Everything else used >= minCount → numbered.
+  // 5) Everything else used >= minCount → numbered, in a deterministic order.
   let ci = 1;
-  for (const c of remaining) {
-    if (c.members.some((m) => valueToName.has(m))) continue;
+  for (const c of [...remaining].sort(byCount(() => 0))) {
+    if (!unnamed(c)) continue;
     if (c.canon.count < minCount) continue;
     assign(`--color-${String(ci++).padStart(3, "0")}`, c);
   }
diff --git a/compiler/src/normalize/ir.ts b/compiler/src/normalize/ir.ts
index 982e296..839a595 100644
--- a/compiler/src/normalize/ir.ts
+++ b/compiler/src/normalize/ir.ts
@@ -25,6 +25,9 @@ export type IRNode = {
   // element had no class.
   srcClass?: string;
   rawHTML?: string; // inline svg
+  // Computed paint of an inline <svg> root (fill/stroke/color), carried from capture. Lets codegen
+  // recover a paint that a raw `fill="none"` attribute hides but site CSS actually supplied.
+  svgPaint?: { fill: string; stroke: string; color: string };
   visibleByVp: Record<number, boolean>;
   bboxByVp: Record<number, BBox>;
   computedByVp: Record<number, StyleMap>;
@@ -456,6 +459,7 @@ export function buildIR(sourceDir: string, viewports: number[], opts?: { motion?
       children: [],
     };
     if (raw.rawHTML) node.rawHTML = raw.rawHTML;
+    if (raw.svgPaint) node.svgPaint = raw.svgPaint;
     const srcClass = (raw.attrs?.class ?? "").trim();
     if (srcClass) node.srcClass = srcClass;
     if (Object.keys(sizingByVp).length) node.sizingByVp = sizingByVp;
diff --git a/compiler/test/css.test.ts b/compiler/test/css.test.ts
index d0c9547..237fe7c 100644
--- a/compiler/test/css.test.ts
+++ b/compiler/test/css.test.ts
@@ -784,3 +784,39 @@ describe("generateCss breakpoint-gated marquee transform band suppression (Defec
     assert.ok(/matrix\(1, ?0, ?0, ?1, ?-40/.test(allRulesX(css, "n1")), `a non-animated per-band offset must be kept, got: ${allRulesX(css, "n1")}`);
   });
 });
+
+// text-wrap emission: a heading authored `text-wrap:balance` must survive to the clone, or the
+// title wraps differently. The initial `wrap` is elided (it's the default), so only authored
+// balance/pretty/nowrap ship.
+describe("generateCss text-wrap", () => {
+  it("emits an authored text-wrap:balance on a heading", () => {
+    const h1 = node("n1", "h1", computed({ textWrap: "balance" }));
+    const root = node("n0", "body", computed(), [h1]);
+    const css = generateCss(irWith(root), new Map());
+    assert.ok(/text-wrap:balance/.test(baseRule(css, "n1")), `text-wrap:balance emitted (got: ${baseRule(css, "n1")})`);
+  });
+
+  it("emits text-wrap:pretty", () => {
+    const p = node("n1", "p", computed({ textWrap: "pretty" }));
+    const root = node("n0", "body", computed(), [p]);
+    const css = generateCss(irWith(root), new Map());
+    assert.ok(/text-wrap:pretty/.test(baseRule(css, "n1")), `text-wrap:pretty emitted (got: ${baseRule(css, "n1")})`);
+  });
+
+  it("elides the default text-wrap:wrap (no noise)", () => {
+    const h1 = node("n1", "h1", computed({ textWrap: "wrap" }));
+    const root = node("n0", "body", computed(), [h1]);
+    const css = generateCss(irWith(root), new Map());
+    assert.ok(!/text-wrap/.test(baseRule(css, "n1")), `default text-wrap:wrap must not be emitted (got: ${baseRule(css, "n1")})`);
+  });
+
+  it("skips text-wrap on a child when it equals the parent (inherited)", () => {
+    // text-wrap is inherited: a child matching the parent's balance relies on inheritance.
+    const child = node("n2", "span", computed({ textWrap: "balance" }));
+    const h1 = node("n1", "h1", computed({ textWrap: "balance" }), [child]);
+    const root = node("n0", "body", computed(), [h1]);
+    const css = generateCss(irWith(root), new Map());
+    assert.ok(/text-wrap:balance/.test(baseRule(css, "n1")), "parent heading emits balance");
+    assert.ok(!/text-wrap/.test(baseRule(css, "n2")), `inherited child does not re-emit (got: ${baseRule(css, "n2")})`);
+  });
+});
diff --git a/compiler/test/interactions.test.ts b/compiler/test/interactions.test.ts
new file mode 100644
index 0000000..7d387c9
--- /dev/null
+++ b/compiler/test/interactions.test.ts
@@ -0,0 +1,90 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { chromium, type Browser, type Page } from "playwright";
+import { captureInteractions, tagElements, diffStyle } from "../src/capture/interactions.js";
+
+describe("diffStyle", () => {
+  it("returns only the changed keys, with the b-side value", () => {
+    const a = { color: "rgb(0, 0, 0)", opacity: "1", transform: "none" };
+    const b = { color: "rgb(255, 0, 0)", opacity: "1", transform: "scale(1.1)" };
+    assert.deepEqual(diffStyle(a, b), { color: "rgb(255, 0, 0)", transform: "scale(1.1)" });
+  });
+  it("is empty when nothing changed", () => {
+    const a = { color: "rgb(0, 0, 0)", opacity: "1" };
+    assert.deepEqual(diffStyle(a, { ...a }), {});
+  });
+  it("only reports keys present in b (b drives the comparison)", () => {
+    // a resting style that carries an extra key does not fabricate a delta.
+    assert.deepEqual(diffStyle({ color: "red", extra: "x" }, { color: "red" }), {});
+  });
+});
+
+describe("captureInteractions hover capture (occlusion-immune)", () => {
+  let browser: Browser;
+  let page: Page;
+  before(async () => {
+    browser = await chromium.launch();
+    page = await browser.newPage({ viewport: { width: 1280, height: 800 } });
+  });
+  after(async () => {
+    await browser.close();
+  });
+
+  const setup = async (html: string) => {
+    await page.setContent(html);
+    await page.evaluate("globalThis.__name = globalThis.__name || ((fn) => fn);");
+    await tagElements(page);
+  };
+
+  it("captures an authored :hover state even when a transparent full-viewport overlay covers the target", async () => {
+    // Exact regression for the empty-hover-capture bug: a modern builder stack parks a
+    // transparent fixed layer over the whole page. page.hover moves the real cursor to the
+    // link's centre, the point lands on the overlay, and `:hover` never reaches the link — so
+    // pointer-based probing captured ZERO hover states. Forcing the pseudo-class fixes it.
+    await setup(`
+      <style>
+        a.cta { color: rgb(0, 0, 0); background-color: rgb(255, 255, 255); }
+        a.cta:hover { color: rgb(255, 0, 0); background-color: rgb(0, 0, 255); }
+        .overlay { position: fixed; inset: 0; z-index: 9999; background: transparent; }
+      </style>
+      <a class="cta" href="#">Shop now</a>
+      <div class="overlay"></div>`);
+    const cap = await captureInteractions(page, { maxCandidates: 50 });
+    const hoverCaps = Object.keys(cap.hover);
+    assert.ok(hoverCaps.length >= 1, "at least one hover state is captured through the overlay");
+    const delta = cap.hover[hoverCaps[0]!]!;
+    assert.equal(delta.color, "rgb(255, 0, 0)", "hover color change is captured");
+    assert.equal(delta.backgroundColor, "rgb(0, 0, 255)", "hover background change is captured");
+  });
+
+  it("captures :hover on a cursor:pointer element that is not a native interactive", async () => {
+    await setup(`
+      <style>
+        .card { cursor: pointer; border: 2px solid rgb(1, 1, 1); }
+        .card:hover { border-color: rgb(9, 9, 9); }
+      </style>
+      <div class="card" style="width:200px;height:120px;">Card</div>`);
+    const cap = await captureInteractions(page, { maxCandidates: 50 });
+    const found = Object.values(cap.hover).some((d) => d.borderTopColor === "rgb(9, 9, 9)");
+    assert.ok(found, "a cursor:pointer card's authored :hover border change is captured");
+  });
+
+  it("records no hover delta for an element with no authored :hover (self-limiting)", async () => {
+    await setup(`
+      <a class="plain" href="#" style="color:rgb(0,0,0);">No hover</a>`);
+    const cap = await captureInteractions(page, { maxCandidates: 50 });
+    assert.equal(Object.keys(cap.hover).length, 0, "no authored hover -> empty hover map");
+  });
+
+  it("restores the resting state after probing (forced pseudo-state cleared)", async () => {
+    await setup(`
+      <style>
+        a.cta { color: rgb(0, 0, 0); }
+        a.cta:hover { color: rgb(255, 0, 0); }
+      </style>
+      <a class="cta" href="#">Link</a>`);
+    await captureInteractions(page, { maxCandidates: 50 });
+    const resting = await page.evaluate(() => getComputedStyle(document.querySelector("a.cta")!).color);
+    assert.equal(resting, "rgb(0, 0, 0)", "the page is left in its resting (non-hover) state");
+  });
+});
diff --git a/compiler/test/semanticNaming.test.ts b/compiler/test/semanticNaming.test.ts
new file mode 100644
index 0000000..762f839
--- /dev/null
+++ b/compiler/test/semanticNaming.test.ts
@@ -0,0 +1,177 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { buildColorPalette, colorClusterKey } from "../src/infer/semanticTokens.js";
+import { planSections, nameFromSourceToken } from "../src/generate/sectionSplit.js";
+import type { IR, IRNode, IRChild, StyleMap } from "../src/normalize/ir.js";
+
+const CW = 1280;
+
+type Box = { x?: number; y: number; width?: number; height: number };
+function el(tag: string, box: Box, computed: StyleMap, children: IRChild[] = [], attrs: Record<string, string> = {}, srcClass?: string): IRNode {
+  const n: IRNode = {
+    id: "", tag, attrs,
+    visibleByVp: { [CW]: true },
+    bboxByVp: { [CW]: { x: box.x ?? 0, y: box.y, width: box.width ?? CW, height: box.height } },
+    computedByVp: { [CW]: { display: "block", ...computed } },
+    children,
+  };
+  if (srcClass) n.srcClass = srcClass;
+  return n;
+}
+function text(t: string): IRChild { return { text: t }; }
+
+function page(children: IRNode[], pageH: number, body?: { bodyBg?: string; bodyColor?: string }): IR {
+  // The body carries its own bg/fg computed style (as a real capture does), so the palette's
+  // usage histogram actually sees the page background/foreground colours it will name.
+  const root = el("body", { y: 0, height: pageH }, {
+    ...(body?.bodyBg ? { backgroundColor: body.bodyBg } : {}),
+    ...(body?.bodyColor ? { color: body.bodyColor } : {}),
+  }, children);
+  let i = 0;
+  const assign = (n: IRNode): void => { n.id = `n${i++}`; for (const c of n.children) if ((c as IRNode).tag) assign(c as IRNode); };
+  assign(root);
+  return {
+    doc: {
+      sourceUrl: "https://example.test/", title: "Fixture", lang: "en", charset: "UTF-8",
+      metaViewport: "width=device-width, initial-scale=1",
+      viewports: [CW], sampleViewports: [CW], canonicalViewport: CW,
+      perViewport: { [CW]: { scrollHeight: pageH, scrollWidth: CW, htmlBg: "", bodyBg: body?.bodyBg ?? "", bodyColor: body?.bodyColor ?? "", bodyFont: "" } },
+      nodeCount: i, keyframes: [],
+    },
+    root,
+  } as IR;
+}
+
+// ----------------------------------------------------------------------------
+// 1) Semantic role assignment — a fixture IR with known roles must produce the
+//    expected named tokens (deterministically), leftovers only for role-less colours.
+// ----------------------------------------------------------------------------
+describe("semantic color palette: role assignment", () => {
+  // page bg = cream; body text = near-black; a saturated red brand used on buttons/links;
+  // a light-gray surface used as several card backgrounds; a border gray; one odd accent.
+  function siteIr(): IR {
+    const kids: IRNode[] = [];
+    // Body text (near-black) x8
+    for (let k = 0; k < 8; k++) kids.push(el("p", { y: 100 + k * 30, height: 20 }, { color: "rgb(20, 20, 19)" }, [text("copy")]));
+    // Brand red on buttons/links x6 (interactive → --primary)
+    for (let k = 0; k < 6; k++) kids.push(el("a", { y: 400 + k * 30, height: 40 }, { backgroundColor: "rgb(188, 0, 0)", color: "rgb(255,255,255)" }, [text("Buy")]));
+    // Light-gray card surfaces x5 (bg, light, low-sat → --surface)
+    for (let k = 0; k < 5; k++) kids.push(el("div", { y: 800 + k * 60, height: 50 }, { backgroundColor: "rgb(240, 238, 230)" }));
+    // Border gray x4 (border only → --border)
+    for (let k = 0; k < 4; k++) kids.push(el("div", { y: 1200 + k * 30, height: 20 }, { borderTopColor: "rgb(200, 200, 200)", borderTopWidth: "1px" }));
+    return page(kids, 1600, { bodyBg: "rgb(252, 251, 246)", bodyColor: "rgb(20, 20, 19)" });
+  }
+
+  it("names background / foreground / primary / surface / border from usage evidence", () => {
+    const p = buildColorPalette(siteIr());
+    const byName = new Map(p.tokens.map((t) => [t.name, t.value]));
+    assert.equal(byName.get("--background"), "rgb(252, 251, 246)");
+    assert.equal(byName.get("--foreground"), "rgb(20, 20, 19)");
+    assert.equal(byName.get("--primary"), "rgb(188, 0, 0)");
+    assert.equal(byName.get("--surface"), "rgb(240, 238, 230)");
+    assert.equal(byName.get("--border"), "rgb(200, 200, 200)");
+    // Every named token resolves back to itself.
+    assert.equal(p.varForColor("rgb(188, 0, 0)"), "var(--primary)");
+  });
+
+  it("is deterministic: same IR → byte-identical token list", () => {
+    const a = buildColorPalette(siteIr()).css;
+    const b = buildColorPalette(siteIr()).css;
+    assert.equal(a, b);
+  });
+
+  it("resolves oklab/oklch forms of a named colour to the SAME semantic token (±2 sRGB)", () => {
+    // oklch(0.987… 97°) ≈ rgb(252,251,246) — the page background. Reached only via a
+    // gradient/decoration property, it must still map to --background, not a fresh --clr-N.
+    const p = buildColorPalette(page([
+      ...Array.from({ length: 4 }, (_, k) => el("p", { y: 100 + k * 30, height: 20 }, { color: "rgb(20, 20, 19)" }, [text("x")])),
+    ], 400, { bodyBg: "oklch(0.987472 0.00667657 97.3497)", bodyColor: "rgb(20, 20, 19)" }));
+    const bg = p.tokens.find((t) => t.name === "--background");
+    assert.ok(bg, "background named");
+    // The rgb() equivalent within tolerance resolves to --background via the ±2 fallback.
+    assert.equal(p.varForColor("rgb(252, 251, 246)"), "var(--background)");
+  });
+});
+
+// ----------------------------------------------------------------------------
+// 2) colorClusterKey — visually identical literals share a key; distinct colours don't.
+// ----------------------------------------------------------------------------
+describe("colorClusterKey (interner visual dedup)", () => {
+  it("collapses oklab forms that round to the same sRGB", () => {
+    // Both oklab(0.988…) whites → rgb(251,251,251).
+    const a = colorClusterKey("oklab(0.988242 -0.0000812355 0.00000757745)");
+    const b = colorClusterKey("oklab(0.988371 -0.0000803481 0.00000749468)");
+    assert.ok(a);
+    assert.equal(a, b);
+  });
+  it("keeps genuinely different colours on different keys", () => {
+    assert.notEqual(colorClusterKey("rgb(0,0,0)"), colorClusterKey("rgb(255,255,255)"));
+    assert.notEqual(colorClusterKey("rgb(188,0,0)"), colorClusterKey("rgb(0,0,188)"));
+  });
+  it("separates alpha variants", () => {
+    assert.notEqual(colorClusterKey("rgba(0,0,0,0.5)"), colorClusterKey("rgba(0,0,0,0.75)"));
+  });
+  it("returns null for unparseable values (keeps raw-literal keying)", () => {
+    assert.equal(colorClusterKey("var(--x)"), null);
+    assert.equal(colorClusterKey("currentColor"), null);
+  });
+});
+
+// ----------------------------------------------------------------------------
+// 3) Name sanitization — hashy-suffix stripping + generic-word filtering.
+// ----------------------------------------------------------------------------
+describe("nameFromSourceToken (source-id sanitization)", () => {
+  it("strips Shopify template prefix + trailing hash → semantic slug", () => {
+    assert.equal(nameFromSourceToken("shopify-section-template--19797275672650__split_callout_JtTWTt"), "SplitCallout");
+    // `grid` is a generic structural word (dropped); the hash `RbEALJ` is stripped.
+    assert.equal(nameFromSourceToken("shopify-section-template--19797275672650__media_card_grid_RbEALJ"), "MediaCard");
+  });
+  it("strips mixed-case build hashes (JtTWTt / dDMm2q / RbEALJ)", () => {
+    assert.equal(nameFromSourceToken("split_callout_JtTWTt"), "SplitCallout");
+    assert.equal(nameFromSourceToken("hero_hD9krx"), "Hero");
+  });
+  it("drops generic structural words entirely", () => {
+    assert.equal(nameFromSourceToken("g_section_wrap"), "");
+    assert.equal(nameFromSourceToken("section-inner-content"), "");
+    assert.equal(nameFromSourceToken("shopify-section-group-header"), "Header");
+  });
+  it("handles js-* hooks and long numeric ids", () => {
+    assert.equal(nameFromSourceToken("js-media-banner-section"), "MediaBanner");
+    assert.equal(nameFromSourceToken("template--19797275672650"), "");
+  });
+});
+
+// ----------------------------------------------------------------------------
+// 4) planSections — a Shopify-id section beats a heading slug; noisy classes don't.
+// ----------------------------------------------------------------------------
+describe("planSections: source-id naming precedence", () => {
+  it("names a section from its CMS section id (hash stripped) over generic evidence", () => {
+    const nav = el("nav", { y: 0, height: 62 }, {});
+    const hero = el("section", { y: 62, height: 800 }, {}, [el("h1", { y: 120, height: 60, x: 120, width: 900 }, {}, [text("Welcome")])]);
+    // A one-off band with NO heading but a clean Shopify id → SplitCalloutSection.
+    const callout = el("div", { y: 862, height: 600 }, {}, [
+      el("p", { y: 900, height: 40, x: 120, width: 600 }, {}, [text("Some marketing copy here")]),
+    ], { id: "shopify-section-template--19797275672650__split_callout_JtTWTt" }, "shopify-section js-split-callout-section");
+    const b2 = el("section", { y: 1462, height: 500 }, {}, [el("h2", { y: 1500, height: 40, x: 120, width: 600 }, {}, [text("Everything you need today")]), el("p", { y: 1560, height: 24, x: 120, width: 600 }, {}, [text("extra")])]);
+    const b3 = el("section", { y: 1962, height: 500 }, {}, [el("h2", { y: 2000, height: 40, x: 120, width: 600 }, {}, [text("What customers say now")]), el("p", { y: 2060, height: 24, x: 120, width: 600 }, {}, [text("a")]), el("p", { y: 2090, height: 24, x: 120, width: 600 }, {}, [text("b")])]);
+    const footer = el("footer", { y: 2462, height: 400 }, {}, [el("a", { y: 2500, height: 20, x: 120, width: 200 }, {}, [text("Privacy")], {}, undefined)]);
+    const ir = page([nav, hero, callout, b2, b3, footer], 2862);
+    const names = [...planSections(ir).roots.values()];
+    assert.ok(names.includes("SplitCalloutSection"), `expected SplitCalloutSection in ${names.join(", ")}`);
+  });
+
+  it("does NOT mine arbitrary utility classes (falls back to heading slug)", () => {
+    const nav = el("nav", { y: 0, height: 62 }, {});
+    const hero = el("section", { y: 62, height: 800 }, {}, [el("h1", { y: 120, height: 60, x: 120, width: 900 }, {}, [text("Welcome home")])]);
+    // Heading present, but the only source class is a noisy Webflow utility → use the heading.
+    const band = el("section", { y: 862, height: 600 }, {}, [
+      el("h2", { y: 900, height: 40, x: 120, width: 600 }, {}, [text("Latest releases from us")]),
+    ], {}, "g_section_space duraldar-cta_section w-variant-60a7ad7d");
+    const b2 = el("section", { y: 1462, height: 500 }, {}, [el("h2", { y: 1500, height: 40, x: 120, width: 600 }, {}, [text("Everything you need")]), el("p", { y: 1560, height: 24, x: 120, width: 600 }, {}, [text("x")])]);
+    const footer = el("footer", { y: 1962, height: 400 }, {}, [el("a", { y: 2000, height: 20, x: 120, width: 200 }, {}, [text("Privacy")])]);
+    const ir = page([nav, hero, band, b2, footer], 2362);
+    const names = [...planSections(ir).roots.values()];
+    assert.ok(names.some((n) => /^LatestReleases/.test(n)), `expected heading slug, got ${names.join(", ")}`);
+    assert.ok(!names.some((n) => /Duraldar|Space/.test(n)), `must not mine utility classes: ${names.join(", ")}`);
+  });
+});
diff --git a/compiler/test/svgRootFill.test.ts b/compiler/test/svgRootFill.test.ts
new file mode 100644
index 0000000..35a8d97
--- /dev/null
+++ b/compiler/test/svgRootFill.test.ts
@@ -0,0 +1,60 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { resolveSvgRootFill, isRealPaint } from "../src/generate/app.js";
+
+describe("isRealPaint", () => {
+  it("treats none / empty / transparent as non-paint", () => {
+    for (const v of [undefined, null, "", "  ", "none", "NONE", "transparent", "rgba(0, 0, 0, 0)", "rgba(0,0,0,0)"]) {
+      assert.equal(isRealPaint(v), false, `${String(v)} should not paint`);
+    }
+  });
+  it("treats a color / currentColor as a real paint", () => {
+    for (const v of ["rgb(255, 255, 255)", "#000", "currentColor", "red", "rgb(0, 0, 0)"]) {
+      assert.equal(isRealPaint(v), true, `${v} should paint`);
+    }
+  });
+});
+
+describe("resolveSvgRootFill", () => {
+  it("keeps a raw fill that is itself a real paint", () => {
+    assert.deepEqual(resolveSvgRootFill("#123456", { fill: "rgb(255,255,255)", color: "rgb(0,0,0)" }), { mode: "keep" });
+    assert.deepEqual(resolveSvgRootFill("red", null), { mode: "keep" });
+  });
+
+  it("falls back when no raw fill is declared (existing currentColor default)", () => {
+    assert.deepEqual(resolveSvgRootFill(undefined, { fill: "rgb(255,255,255)", color: "rgb(255,255,255)" }), { mode: "fallback" });
+    assert.deepEqual(resolveSvgRootFill(null, null), { mode: "fallback" });
+  });
+
+  it("recovers currentColor when fill=none but computed fill tracks the element color (wordmark case)", () => {
+    // The a16z logo case: fill="none" attribute, but CSS `fill: currentColor` with white color.
+    const r = resolveSvgRootFill("none", { fill: "rgb(255, 255, 255)", color: "rgb(255, 255, 255)" });
+    assert.equal(r.mode, "emit");
+    assert.equal(r.value, "currentColor");
+    assert.equal(r.emitColor, "rgb(255, 255, 255)");
+  });
+
+  it("emits the literal computed fill when it differs from the element color", () => {
+    const r = resolveSvgRootFill("none", { fill: "rgb(255, 0, 0)", color: "rgb(0, 0, 0)" });
+    assert.equal(r.mode, "emit");
+    assert.equal(r.value, "rgb(255, 0, 0)");
+    assert.equal(r.emitColor, undefined);
+  });
+
+  it("leaves a genuinely unfilled svg as none (computed fill also none)", () => {
+    assert.deepEqual(resolveSvgRootFill("none", { fill: "none", color: "rgb(0,0,0)" }), { mode: "keep" });
+    assert.deepEqual(resolveSvgRootFill("none", { fill: "rgba(0, 0, 0, 0)", color: "rgb(0,0,0)" }), { mode: "keep" });
+    // No computed paint captured at all → cannot prove it paints → stays none.
+    assert.deepEqual(resolveSvgRootFill("none", null), { mode: "keep" });
+    assert.deepEqual(resolveSvgRootFill("none", undefined), { mode: "keep" });
+  });
+
+  it("does not emit color when the recovered fill is currentColor but color is not a real paint", () => {
+    // fill == color but color is transparent → cannot be a meaningful currentColor recovery;
+    // the equality branch is guarded on isRealPaint(color), so it emits the literal fill instead.
+    const r = resolveSvgRootFill("none", { fill: "rgb(0, 128, 0)", color: "transparent" });
+    assert.equal(r.mode, "emit");
+    assert.equal(r.value, "rgb(0, 128, 0)");
+    assert.equal(r.emitColor, undefined);
+  });
+});
diff --git a/compiler/test/tailwind.test.ts b/compiler/test/tailwind.test.ts
index 9f5721f..d65cb4b 100644
--- a/compiler/test/tailwind.test.ts
+++ b/compiler/test/tailwind.test.ts
@@ -133,3 +133,21 @@ describe("declToUtil letter-spacing sub-0.1px preservation", () => {
     assert.equal(declToUtil("width", "204.9994px"), "w-[205px]");
   });
 });
+
+// text-wrap: modern heading line-balancing. `balance`/`pretty` rebalance where a title wraps;
+// without emitting them a two-line heading breaks differently in the clone. Tailwind v4 has the
+// named utilities text-balance / text-pretty / text-nowrap / text-wrap; anything else (e.g.
+// `stable`) falls through to the arbitrary property escape.
+describe("declToUtil text-wrap", () => {
+  it("maps balance and pretty to the named Tailwind v4 utilities", () => {
+    assert.equal(declToUtil("text-wrap", "balance"), "text-balance");
+    assert.equal(declToUtil("text-wrap", "pretty"), "text-pretty");
+  });
+  it("maps wrap and nowrap to their named utilities", () => {
+    assert.equal(declToUtil("text-wrap", "wrap"), "text-wrap");
+    assert.equal(declToUtil("text-wrap", "nowrap"), "text-nowrap");
+  });
+  it("falls back to the arbitrary property for an unmapped value", () => {
+    assert.equal(declToUtil("text-wrap", "stable"), "[text-wrap:stable]");
+  });
+});
diff --git a/compiler/test/videoSourceSelect.test.ts b/compiler/test/videoSourceSelect.test.ts
new file mode 100644
index 0000000..b7b6c27
--- /dev/null
+++ b/compiler/test/videoSourceSelect.test.ts
@@ -0,0 +1,66 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { selectVideoSourceIndex, type VideoSourceCandidate } from "../src/capture/capture.js";
+
+// Predicate builders for the injected matchMedia / canPlayType.
+const matchesAny = (matching: Set<string>) => (m: string) => matching.has(m);
+const canPlayAll = () => true;
+const canPlayNone = () => false;
+
+describe("selectVideoSourceIndex (video <source> resource-selection)", () => {
+  it("picks the first source whose media matches; missing media matches unconditionally", () => {
+    // Aspect-gated hero: landscape sources first, portrait after, plain fall-through last.
+    const sources: VideoSourceCandidate[] = [
+      { media: "(min-aspect-ratio: 21/9)", type: "video/webm" },
+      { media: "(min-aspect-ratio: 16/9)", type: "video/webm" },
+      { media: "(max-aspect-ratio: 4/5)", type: "video/webm" },
+      { media: null, type: "video/webm" }, // plain fall-through
+    ];
+    // Portrait viewport: only the max-aspect-ratio query matches → index 2.
+    assert.equal(
+      selectVideoSourceIndex(sources, matchesAny(new Set(["(max-aspect-ratio: 4/5)"])), canPlayAll),
+      2,
+    );
+    // Landscape/wide viewport: the min-aspect 16/9 query matches → index 1.
+    assert.equal(
+      selectVideoSourceIndex(sources, matchesAny(new Set(["(min-aspect-ratio: 16/9)"])), canPlayAll),
+      1,
+    );
+    // Nothing matches → falls through to the plain no-media source (index 3).
+    assert.equal(selectVideoSourceIndex(sources, matchesAny(new Set()), canPlayAll), 3);
+  });
+
+  it("skips a source whose type the UA cannot play", () => {
+    const sources: VideoSourceCandidate[] = [
+      { media: null, type: "video/webm" }, // unplayable here
+      { media: null, type: "video/mp4" },
+    ];
+    const canPlayMp4 = (t: string) => t === "video/mp4";
+    assert.equal(selectVideoSourceIndex(sources, matchesAny(new Set()), canPlayMp4), 1);
+  });
+
+  it("treats a missing/empty type as never disqualifying", () => {
+    const sources: VideoSourceCandidate[] = [
+      { media: null, type: "" },
+      { media: null },
+    ];
+    // canPlay is never consulted when type is absent, even if it would reject everything.
+    assert.equal(selectVideoSourceIndex(sources, matchesAny(new Set()), canPlayNone), 0);
+  });
+
+  it("returns -1 when no source is eligible", () => {
+    const sources: VideoSourceCandidate[] = [
+      { media: "(max-aspect-ratio: 4/5)", type: "video/webm" },
+    ];
+    assert.equal(selectVideoSourceIndex(sources, matchesAny(new Set()), canPlayNone), -1);
+    assert.equal(selectVideoSourceIndex([], matchesAny(new Set()), canPlayAll), -1);
+  });
+
+  it("is deterministic and first-match-wins in document order", () => {
+    const sources: VideoSourceCandidate[] = [
+      { media: "(min-width: 100px)", type: "video/mp4" },
+      { media: "(min-width: 100px)", type: "video/mp4" }, // also eligible, but later
+    ];
+    assert.equal(selectVideoSourceIndex(sources, matchesAny(new Set(["(min-width: 100px)"])), canPlayAll), 0);
+  });
+});
diff --git a/compiler/test/walker.test.ts b/compiler/test/walker.test.ts
index a288787..4172c04 100644
--- a/compiler/test/walker.test.ts
+++ b/compiler/test/walker.test.ts
@@ -317,3 +317,35 @@ describe("walker sizing probe: circular authored-height guard", () => {
     assert.equal(pct.sizing!.hAuto, false, "percentage fill is not content-sized");
   });
 });
+
+describe("walker text-wrap capture", () => {
+  let browser: Browser;
+  let page: Page;
+  before(async () => {
+    browser = await chromium.launch();
+    page = await browser.newPage({ viewport: { width: 1280, height: 800 } });
+  });
+  after(async () => {
+    await browser.close();
+  });
+
+  const capture = async (html: string) => {
+    await page.setContent(html);
+    await page.evaluate("globalThis.__name = globalThis.__name || ((fn) => fn);");
+    return page.evaluate(collectPage);
+  };
+
+  it("captures text-wrap:balance on a heading (modern line-balancing)", async () => {
+    // Real case: a hero heading authored `text-wrap:balance` wraps its two lines evenly; without
+    // capturing the prop the clone wraps it lopsidedly.
+    const snap = await capture(`<h1 style="text-wrap:balance">BUILT RUGGED. WORN DAILY.</h1>`);
+    const h1 = findByTag(snap.root, "h1")!;
+    assert.equal(h1.computed.textWrap, "balance", "text-wrap:balance is captured");
+  });
+
+  it("captures text-wrap:pretty", async () => {
+    const snap = await capture(`<p style="text-wrap:pretty">Some flowing paragraph text here.</p>`);
+    const p = findByTag(snap.root, "p")!;
+    assert.equal(p.computed.textWrap, "pretty", "text-wrap:pretty is captured");
+  });
+});

From 762855664c4b896ff307eb439167dc5147dcbd5d Mon Sep 17 00:00:00 2001
From: Samraaj Bath <samraaj100@gmail.com>
Date: Sat, 4 Jul 2026 02:41:00 -0700
Subject: [PATCH 12/24] Composed-tree shadow DOM capture, sized invisible
 spacers, track re-anchoring, block fill-width slides, javascript: href
 sanitization

- Walker serializes the composed (flattened) tree: open shadow roots walk
  as host children with <slot> replaced by its assigned light nodes (or
  fallback), so custom-element content (product cards, web components) is
  captured instead of arriving childless
- In-flow visibility:hidden nodes with a nonzero border box survive the
  prune as sized invisible placeholders - ghost spacers carry load-bearing
  geometry
- When pruning drops leading in-flow children of a horizontally-translated
  track, the baked translateX is re-anchored by their aggregate margin-box
  width (settled carousel tracks return to origin instead of pushing real
  content off-screen); animation-owned transforms unaffected
- Circular-shrink slide guard counts block-level fill children as
  width-deriving regardless of wAuto (block auto-width IS fill), pinning
  library-sized slide widths uniformly
- javascript: hrefs emit as "#" and the link gate normalizes both sides

382 tests pass (18 new), typecheck clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 compiler/src/capture/walker.ts       |  57 +++++++++++-
 compiler/src/generate/app.ts         |  19 ++--
 compiler/src/generate/css.ts         |  11 ++-
 compiler/src/normalize/ir.ts         | 117 +++++++++++++++++++++++-
 compiler/src/validate/gates.ts       |   6 +-
 compiler/test/codegenHygiene.test.ts |  32 +++++++
 compiler/test/css.test.ts            |  44 +++++++++
 compiler/test/gates.test.ts          |  20 ++++-
 compiler/test/irPrune.test.ts        | 130 +++++++++++++++++++++++++++
 compiler/test/walker.test.ts         |  86 ++++++++++++++++++
 10 files changed, 509 insertions(+), 13 deletions(-)

diff --git a/compiler/src/capture/walker.ts b/compiler/src/capture/walker.ts
index 818efaa..1ea6c0f 100644
--- a/compiler/src/capture/walker.ts
+++ b/compiler/src/capture/walker.ts
@@ -48,6 +48,14 @@ export type RawNode = {
   // libraries, FontFaceObserver): absolutely positioned, parked far off-screen, and non-painting.
   // Never user-visible; excluded from emission so it doesn't ship as page markup.
   probe?: boolean;
+  // This element hosts an OPEN shadow root: its serialized children are the composed (flattened)
+  // shadow tree — the shadowRoot's children with each <slot> replaced by its assigned light-DOM
+  // nodes — NOT the host's light-DOM children. Custom elements (`<product-info>`) render all their
+  // swatches/title/price inside this shadow tree, so a childNodes-only walk captured them empty.
+  shadowHost?: boolean;
+  // This node was serialized from inside a shadow tree (a shadowRoot descendant, or the shadow
+  // subtree of a slotted light node). Tagged so generation can emit it as ordinary light DOM.
+  inShadow?: boolean;
   sizing?: RawSizing;
   before?: RawStyle;
   after?: RawStyle;
@@ -316,7 +324,7 @@ export function collectPage(opts?: { maxNodes?: number } | void): PageSnapshot {
       || bbox.x >= OFFSCREEN_PROBE_PX + vpW || bbox.y >= OFFSCREEN_PROBE_PX + pageH;
   };
 
-  const serializeElement = (el: Element): RawNode | null => {
+  const serializeElement = (el: Element, inShadow = false): RawNode | null => {
     if (nodeCount >= MAX_NODES) { truncated = true; return null; }
     const tag = el.tagName.toLowerCase();
     nodeCount++;
@@ -445,6 +453,7 @@ export function collectPage(opts?: { maxNodes?: number } | void): PageSnapshot {
       bbox,
       visible: isVisible(el, cs, bbox),
       ...(isProbe(cs, bbox) ? { probe: true } : {}),
+      ...(inShadow ? { inShadow: true } : {}),
       ...(sizing ? { sizing } : {}),
       children: [],
     };
@@ -488,8 +497,28 @@ export function collectPage(opts?: { maxNodes?: number } | void): PageSnapshot {
     // code blocks with highlighted spans separated by newlines).
     const preserveWs = /^(pre|pre-wrap|break-spaces)/.test(cs.whiteSpace || "");
 
+    // Composed (flattened) child list — the tree the user actually sees, matching what
+    // getComputedStyle/getBoundingClientRect already report for every node:
+    //   - An open shadow HOST renders its shadow tree, not its light children: iterate the
+    //     shadowRoot's children and tag them (and the host) so generation emits them as light DOM.
+    //   - A <slot> is a placeholder for the light-DOM nodes distributed into it: replace it with its
+    //     assignedNodes (or its own fallback children when nothing is assigned). Assigned nodes are
+    //     the author's real light content, so they are NOT tagged inShadow — only genuine shadow
+    //     descendants are. Walking the shadow tree (never the host's raw light children) means a
+    //     slotted child is serialized once, at the slot position, with no double-emission.
+    const sr = (el as HTMLElement).shadowRoot; // open roots only; closed roots are null here
+    let childInShadow = inShadow;
+    let childNodes: Node[];
+    if (sr) {
+      node.shadowHost = true;
+      childInShadow = true;
+      childNodes = Array.from(sr.childNodes);
+    } else {
+      childNodes = Array.from(el.childNodes);
+    }
+
     // Recurse children (elements + text nodes), preserving order.
-    for (const child of Array.from(el.childNodes)) {
+    for (const child of childNodes) {
       if (child.nodeType === Node.TEXT_NODE) {
         const t = child.textContent || "";
         if (preserveWs && t.length > 0) {
@@ -509,8 +538,28 @@ export function collectPage(opts?: { maxNodes?: number } | void): PageSnapshot {
       }
       if (child.nodeType !== Node.ELEMENT_NODE) continue;
       const childEl = child as Element;
-      if (SKIP_TAGS.has(childEl.tagName.toLowerCase())) continue;
-      const sn = serializeElement(childEl);
+      const childTag = childEl.tagName.toLowerCase();
+      if (SKIP_TAGS.has(childTag)) continue;
+      // A slot nested deeper inside a shadow tree: expand its assigned light nodes in place. The
+      // assigned nodes are light DOM (author content), so they drop back to inShadow=false.
+      if (childTag === "slot" && childInShadow) {
+        const assigned = (childEl as HTMLSlotElement).assignedNodes({ flatten: true });
+        const slotKids = assigned.length ? assigned : Array.from(childEl.childNodes);
+        for (const sk of slotKids) {
+          if (sk.nodeType === Node.TEXT_NODE) {
+            const t = sk.textContent || "";
+            if (t.trim().length > 0) node.children.push({ text: t });
+            continue;
+          }
+          if (sk.nodeType !== Node.ELEMENT_NODE) continue;
+          const skEl = sk as Element;
+          if (SKIP_TAGS.has(skEl.tagName.toLowerCase())) continue;
+          const skn = serializeElement(skEl, assigned.length ? false : true);
+          if (skn) node.children.push(skn);
+        }
+        continue;
+      }
+      const sn = serializeElement(childEl, childInShadow);
       if (sn) node.children.push(sn);
     }
 
diff --git a/compiler/src/generate/app.ts b/compiler/src/generate/app.ts
index 5b5f021..e4c2361 100644
--- a/compiler/src/generate/app.ts
+++ b/compiler/src/generate/app.ts
@@ -369,11 +369,20 @@ export function propsList(node: IRNode, assetMap: Map<string, string>, sourceUrl
       if (kept.length === 0) continue;
       value = kept.join(", ");
     } else if (key === "href") {
-      // Preserve in-page anchors. For multi-route sites a linkRewrite maps internal
-      // links to the generated clone routes (and collapsed-collection links to their
-      // representative); otherwise absolutize so it never 404s inside the clone
-      // (external navigation is allowed by the rubric).
-      if (!value.startsWith("#")) value = ctx?.linkRewrite ? ctx.linkRewrite(value) : resolveUrl(value, sourceUrl);
+      // A `javascript:*` href (announcement bars, JS-driven buttons authored as links) is a
+      // script trigger, not a navigable URL. React refuses to render one: it rewrites the
+      // attribute to a long `javascript:throw new Error('React has blocked a javascript: URL…')`
+      // string, which no longer matches the source href in the link gate. The behaviour is
+      // script we don't reproduce anyway, so emit an inert `#` and keep the anchor navigable-inert.
+      if (/^\s*javascript:/i.test(value)) {
+        value = "#";
+      } else if (!value.startsWith("#")) {
+        // Preserve in-page anchors. For multi-route sites a linkRewrite maps internal
+        // links to the generated clone routes (and collapsed-collection links to their
+        // representative); otherwise absolutize so it never 404s inside the clone
+        // (external navigation is allowed by the rubric).
+        value = ctx?.linkRewrite ? ctx.linkRewrite(value) : resolveUrl(value, sourceUrl);
+      }
     }
 
     let reactName = isCustom ? key : (ATTR_RENAME[key] ?? key);
diff --git a/compiler/src/generate/css.ts b/compiler/src/generate/css.ts
index c0dc660..0140180 100644
--- a/compiler/src/generate/css.ts
+++ b/compiler/src/generate/css.ts
@@ -1034,7 +1034,16 @@ function isCircularShrinkSlide(node: IRNode, parentNode: IRNode | undefined, vie
       const cpos = ccs.position || "static";
       if (cpos === "absolute" || cpos === "fixed") continue;                // out of flow → no width contribution
       const csz = c.sizingByVp?.[vp];
-      if (csz && csz.wFill === true && csz.wAuto === false) { fillChildren++; continue; } // fills the slide → derives width from it
+      // A block-level in-flow box (block/flex/grid/table/list-item) takes its width FROM its
+      // container by definition: its `width:auto` computed size IS the fill size, so the probe
+      // reports wAuto AND wFill both true — indistinguishable from a genuine content-sized source.
+      // Such a child still DERIVES its width from the slide (it never establishes one), so it must
+      // count as a fill child, not veto the circular case. Only wFill matters for a block child;
+      // wAuto is redundant with it. Inline / inline-block children (whose auto width is genuinely
+      // content-derived and can size the slide) keep the strict wFill && !wAuto test.
+      const cDisp = ccs.display || "";
+      const blockLevel = /^(block|flex|grid|table|list-item|flow-root)$/.test(cDisp);
+      if (csz && csz.wFill === true && (blockLevel || csz.wAuto === false)) { fillChildren++; continue; } // fills/derives width from the slide
       return false;                                                         // a genuine in-flow width source → not circular
     }
     if (fillChildren === 0) return false;
diff --git a/compiler/src/normalize/ir.ts b/compiler/src/normalize/ir.ts
index 839a595..5842604 100644
--- a/compiler/src/normalize/ir.ts
+++ b/compiler/src/normalize/ir.ts
@@ -251,6 +251,54 @@ export function isIdentityTransform(value: string | undefined): boolean {
   return false;
 }
 
+/** Parse a CSS length to px (number), 0 for `auto`/empty/non-px. */
+function pfLen(v: string | undefined): number {
+  if (!v) return 0;
+  const n = parseFloat(v);
+  return Number.isFinite(n) ? n : 0;
+}
+
+/** The horizontal translate (matrix `e`) of a computed transform, or null if the transform is not a
+ *  pure-2D matrix/matrix3d with a definite tx (rotation/scale/skew or 3D perspective → null: we only
+ *  re-anchor plain horizontal track offsets). `matrix(a,b,c,d,e,f)` → e; `matrix3d(...)` → m41. */
+function translateXOf(value: string | undefined): number | null {
+  if (!value || value === "none") return null;
+  const m = /^matrix\(([^)]*)\)$/.exec(value.trim());
+  if (m) {
+    const n = m[1]!.split(",").map((s) => parseFloat(s.trim()));
+    if (n.length !== 6 || n.some((x) => !Number.isFinite(x))) return null;
+    if (n[1] !== 0 || n[2] !== 0) return null;               // has rotation/skew → not a plain slide
+    return n[4]!;
+  }
+  const m3 = /^matrix3d\(([^)]*)\)$/.exec(value.trim());
+  if (m3) {
+    const n = m3[1]!.split(",").map((s) => parseFloat(s.trim()));
+    if (n.length !== 16 || n.some((x) => !Number.isFinite(x))) return null;
+    // Require an otherwise-identity 3D matrix apart from the translate column (indices 12/13/14).
+    const idExceptTranslate = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, /*12*/ 0, /*13*/ 0, /*14*/ 0, 1];
+    for (let i = 0; i < 16; i++) { if (i === 12 || i === 13 || i === 14) continue; if (n[i] !== idExceptTranslate[i]) return null; }
+    return n[12]!;
+  }
+  return null;
+}
+
+/** Return `value` with its horizontal translate replaced by `tx` (keeps the rest of the matrix). */
+function setTranslateX(value: string, tx: number): string {
+  const m = /^matrix\(([^)]*)\)$/.exec(value.trim());
+  if (m) {
+    const n = m[1]!.split(",").map((s) => s.trim());
+    n[4] = String(tx);
+    return `matrix(${n.join(", ")})`;
+  }
+  const m3 = /^matrix3d\(([^)]*)\)$/.exec(value.trim());
+  if (m3) {
+    const n = m3[1]!.split(",").map((s) => s.trim());
+    n[12] = String(tx);
+    return `matrix3d(${n.join(", ")})`;
+  }
+  return value;
+}
+
 /**
  * Normalize per-viewport transform values so identity is represented uniformly as the literal
  * `none`. Two problems this closes, both in the per-viewport delta emission downstream:
@@ -506,6 +554,8 @@ export function buildIR(sourceDir: string, viewports: number[], opts?: { motion?
     // interactive panel so its whole (possibly display:none) subtree is retained.
     const keepAll = forced || preserveCaps.has(node.attrs["data-cid-cap"] ?? "");
     const keptChildren: IRChild[] = [];
+    // Per element child, in original order: was it kept? (for track-transform re-anchoring below.)
+    const elemKept: Array<{ child: IRNode; kept: boolean }> = [];
     let hasVisibleDescendant = false;
     let hasText = false;
     for (const c of node.children) {
@@ -522,16 +572,81 @@ export function buildIR(sourceDir: string, viewports: number[], opts?: { motion?
       if (keepAll) {
         prune(c, true);
         keptChildren.push(c);
+        elemKept.push({ child: c, kept: true });
         if (Object.values(c.visibleByVp).some(Boolean) || childHasVisible(c)) hasVisibleDescendant = true;
       } else if (prune(c, false) || keepSource) {
         keptChildren.push(c);
+        elemKept.push({ child: c, kept: true });
         if (Object.values(c.visibleByVp).some(Boolean) || childHasVisible(c)) hasVisibleDescendant = true;
+      } else {
+        elemKept.push({ child: c, kept: false });
       }
     }
     node.children = keptChildren;
+    reanchorTrackTransform(node, elemKept);
     if (keepAll) return true;
     const selfVisible = Object.values(node.visibleByVp).some(Boolean);
-    return selfVisible || hasVisibleDescendant || hasText || !!node.rawHTML;
+    return selfVisible || hasVisibleDescendant || hasText || !!node.rawHTML || isSizedInvisibleSpacer(node);
+  };
+  // An in-flow `visibility:hidden` box with a nonzero border box is LOAD-BEARING geometry: it is
+  // invisible (so `visibleByVp` is false and the visibility prune would drop it), but it still takes
+  // up its captured width/height in normal flow — a spacer/ghost column that reserves the row height
+  // its absolutely-positioned siblings paint into. Dropping it collapses the column and shifts
+  // everything below it up. Keep it as an empty sized placeholder (generation emits its w/h with
+  // `visibility:hidden` and no content). `display:none`-everywhere nodes (never in flow, zero box)
+  // and out-of-flow probes stay pruned; font-metric probes are already dropped before pruning.
+  const isSizedInvisibleSpacer = (node: IRNode): boolean => {
+    for (const vp of Object.keys(node.computedByVp).map(Number)) {
+      const cs = node.computedByVp[vp]; const bb = node.bboxByVp[vp];
+      if (!cs || !bb) continue;
+      if ((cs.display || "") === "none") continue;                    // not in flow here
+      const vis = cs.visibility || "visible";
+      if (vis !== "hidden" && vis !== "collapse") continue;           // only invisible-but-laid-out boxes
+      const pos = cs.position || "static";
+      if (pos !== "static" && pos !== "relative") continue;           // in-flow geometry only (not absolute/fixed)
+      if (bb.width > 0 && bb.height > 0) return true;                 // reserves real space
+    }
+    return false;
+  };
+  // Re-anchor a horizontally-translated TRACK container after pruning removed leading in-flow
+  // children. A settled loop carousel (Splide/Swiper/Slick) parks its track with a baked
+  // `translateX(-N)` and prepends invisible clone slides that occupy exactly [-N, 0]; the first REAL
+  // slide then paints at x=0. The visibility prune drops the off-screen clones but the baked
+  // translateX survives verbatim, so every kept slide sits N px offscreen-left (an empty band). When
+  // emission drops the leading in-flow children of such a translated track, subtract their aggregate
+  // outer width from the baked translateX per viewport so the first KEPT child lands where it was
+  // captured. NON-animated baked offsets only — animation-owned transforms are already neutralized to
+  // `none` upstream (neutralizeAnimatedTransforms), so a still-present translate here is a static bake.
+  const reanchorTrackTransform = (node: IRNode, elemKept: Array<{ child: IRNode; kept: boolean }>): void => {
+    if (elemKept.length === 0) return;
+    // Only act when a leading RUN of element children was dropped (the clone slides precede the reals).
+    const firstKeptIdx = elemKept.findIndex((e) => e.kept);
+    if (firstKeptIdx <= 0) return; // nothing dropped ahead of the first kept child (or nothing kept)
+    for (const vp of Object.keys(node.computedByVp).map(Number)) {
+      const cs = node.computedByVp[vp];
+      if (!cs || !cs.transform) continue;
+      const tx = translateXOf(cs.transform);
+      if (tx === null || tx === 0) continue; // no baked horizontal offset to re-anchor at this vp
+      // Aggregate the outer (margin-box) width of the dropped leading in-flow siblings at this vp.
+      let droppedW = 0;
+      for (let i = 0; i < firstKeptIdx; i++) {
+        const { child } = elemKept[i]!;
+        const ccs = child.computedByVp[vp]; const cb = child.bboxByVp[vp];
+        if (!ccs || !cb) continue;
+        if ((ccs.display || "") === "none") continue;
+        const cpos = ccs.position || "static";
+        if (cpos !== "static" && cpos !== "relative") continue; // out-of-flow slides don't advance the track
+        droppedW += cb.width + pfLen(ccs.marginLeft) + pfLen(ccs.marginRight);
+      }
+      if (droppedW === 0) continue;
+      // translateX is negative (track pulled left); dropping the leading clones that filled [tx, 0]
+      // means the reals shift right by droppedW → add it back. Re-anchor toward 0.
+      const next = tx + droppedW;
+      // Only re-anchor when it moves the track TOWARD the origin and doesn't overshoot past it — a
+      // guard so a partial mismatch can't push content the wrong way. Round to match capture precision.
+      if (Math.abs(next) >= Math.abs(tx)) continue;
+      cs.transform = setTranslateX(cs.transform, Math.round(next * 100) / 100);
+    }
   };
   const childHasVisible = (n: IRNode): boolean => {
     for (const c of n.children) {
diff --git a/compiler/src/validate/gates.ts b/compiler/src/validate/gates.ts
index 23c2ba8..533cb13 100644
--- a/compiler/src/validate/gates.ts
+++ b/compiler/src/validate/gates.ts
@@ -313,8 +313,12 @@ function isValidRetag(srcTag: string, genTag: string): boolean {
   return genTag === "div" && /^(ul|ol|menu|dl|p|h[1-6])$/.test(srcTag); // content-model → div
 }
 
-function normHref(href: string, origin: string): string {
+export function normHref(href: string, origin: string): string {
   if (!href) return "";
+  // A `javascript:*` href is a script trigger, not a navigable URL. Generation emits an inert `#`
+  // for it (React blocks the literal), so treat every javascript: href — on either side — as `#`
+  // and let the two sides match instead of failing on the un-reproducible script string.
+  if (/^\s*javascript:/i.test(href)) return "#";
   if (href.startsWith("#")) return href;
   try {
     const u = new URL(href, origin);
diff --git a/compiler/test/codegenHygiene.test.ts b/compiler/test/codegenHygiene.test.ts
index b84301f..0d447d7 100644
--- a/compiler/test/codegenHygiene.test.ts
+++ b/compiler/test/codegenHygiene.test.ts
@@ -11,6 +11,7 @@ import {
   PACKAGE_JSON_TW,
   PACKAGE_JSON_VITE,
   PACKAGE_JSON_VITE_TW,
+  propsList,
   type ComponentRegistry,
 } from "../src/generate/app.js";
 import { DITTO_WIRE_TSX, ACCORDION_TSX } from "../src/generate/interactive.js";
@@ -165,3 +166,34 @@ describe("lottie-web is declared when its import is emitted (fix 7)", () => {
     }
   });
 });
+
+// ---- FIX 5: javascript: hrefs are sanitized to an inert '#' ----
+// React refuses to render a `javascript:*` href verbatim — it rewrites it to a long
+// `javascript:throw new Error('React has blocked a javascript: URL…')` string that no longer matches
+// the source href in the link gate. Emit an inert `#` instead (the script behaviour isn't reproduced).
+describe("javascript: hrefs are emitted as an inert '#' (FIX 5)", () => {
+  const hrefOf = (n: IRNode): string | undefined => {
+    const p = propsList(n, new Map(), "https://example.test/").find(([k]) => k === "href");
+    return p ? JSON.parse(p[1]) : undefined;
+  };
+  it("rewrites a javascript: href to #", () => {
+    const a = node("n1", "a", computed());
+    a.attrs = { href: "Javascript:{}" };
+    assert.equal(hrefOf(a), "#", "a javascript: href is sanitized to #");
+  });
+  it("rewrites javascript:void(0) too (case-insensitive, with args)", () => {
+    const a = node("n1", "a", computed());
+    a.attrs = { href: "javascript:void(0)" };
+    assert.equal(hrefOf(a), "#");
+  });
+  it("leaves a normal in-page anchor href untouched", () => {
+    const a = node("n1", "a", computed());
+    a.attrs = { href: "#section" };
+    assert.equal(hrefOf(a), "#section", "a real fragment link is preserved");
+  });
+  it("leaves an ordinary external href resolved (not collapsed to #)", () => {
+    const a = node("n1", "a", computed());
+    a.attrs = { href: "https://example.test/products" };
+    assert.equal(hrefOf(a), "https://example.test/products");
+  });
+});
diff --git a/compiler/test/css.test.ts b/compiler/test/css.test.ts
index 237fe7c..b409c31 100644
--- a/compiler/test/css.test.ts
+++ b/compiler/test/css.test.ts
@@ -820,3 +820,47 @@ describe("generateCss text-wrap", () => {
     assert.ok(!/text-wrap/.test(baseRule(css, "n2")), `inherited child does not re-emit (got: ${baseRule(css, "n2")})`);
   });
 });
+
+// FIX 4 — a library-sized carousel slide (a shrink-0 flex item with an injected inline `width:Npx`)
+// whose only in-flow child is a display:block box. A block box's `width:auto` IS its fill width, so
+// the sizing probe reports the child wAuto AND wFill both true. The circular-slide detector must count
+// that block-level fill child as width-DERIVING (it never establishes a width) and pin the slide's
+// captured px — otherwise the guard misreads the child as a genuine content-width source, bails, and
+// the slide content-sizes to a different width (ragged carousel rails).
+describe("generateCss circular carousel slide with a block-level fill child (FIX 4)", () => {
+  // The slide's child is display:block: its auto width equals the fill width, so BOTH probe bits fire.
+  const blockFill = (): RawSizing => ({ wAuto: true, wFill: true, hAuto: true, hFill: true });
+  function slideRow() {
+    // Uniform 220px slides at every viewport (Splide's inline width) inside a flex track.
+    const mkSlide = (id: string, childId: string): IRNode => {
+      const child = xNode(childId, "div", {
+        375: { cs: { display: "block", position: "static" }, bbox: { x: 0, y: 0, width: 220, height: 357 }, sizing: blockFill() },
+        768: { cs: { display: "block", position: "static" }, bbox: { x: 0, y: 0, width: 220, height: 357 }, sizing: blockFill() },
+        1280: { cs: { display: "block", position: "static" }, bbox: { x: 0, y: 0, width: 220, height: 357 }, sizing: blockFill() },
+      }, [{ text: "Men's Tops & Shirts" } as IRChild]);
+      const slideCs = { display: "block", position: "static", flexShrink: "0", width: "220px" };
+      return xNode(id, "div", {
+        375: { cs: slideCs, bbox: { x: 0, y: 0, width: 220, height: 357 } },
+        768: { cs: slideCs, bbox: { x: 0, y: 0, width: 220, height: 357 } },
+        1280: { cs: slideCs, bbox: { x: 0, y: 0, width: 220, height: 357 } },
+      }, [child]);
+    };
+    const trackCs = { display: "flex", position: "static" };
+    const track = xNode("n1", "ul", {
+      375: { cs: trackCs, bbox: { x: 0, y: 0, width: 375, height: 357 } },
+      768: { cs: trackCs, bbox: { x: 0, y: 0, width: 768, height: 357 } },
+      1280: { cs: trackCs, bbox: { x: 0, y: 0, width: 1280, height: 357 } },
+    }, [mkSlide("n2", "n3"), mkSlide("n4", "n5")]);
+    return xNode("n0", "body", {
+      375: { bbox: { x: 0, y: 0, width: 375, height: 357 } },
+      768: { bbox: { x: 0, y: 0, width: 768, height: 357 } },
+      1280: { bbox: { x: 0, y: 0, width: 1280, height: 357 } },
+    }, [track]);
+  }
+
+  it("pins the slide's captured width even though its block child reports wAuto:true", () => {
+    const css = generateCss(xIr(slideRow()), new Map());
+    const slide = allRulesX(css, "n2");
+    assert.ok(/width:220px/.test(slide), `the library-sized slide must keep its 220px width, got: ${slide}`);
+  });
+});
diff --git a/compiler/test/gates.test.ts b/compiler/test/gates.test.ts
index 311bcda..5dd9258 100644
--- a/compiler/test/gates.test.ts
+++ b/compiler/test/gates.test.ts
@@ -1,6 +1,24 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { letterSpacingEquivalent } from "../src/validate/gates.js";
+import { letterSpacingEquivalent, normHref } from "../src/validate/gates.js";
+
+// FIX 5 — the link gate must not fail a javascript: source href against the clone's sanitized value.
+// Generation emits an inert `#` for a `javascript:*` href (React blocks the literal), so normHref
+// collapses every javascript: href — on either side — to `#`, letting the two sides match.
+describe("normHref collapses javascript: hrefs to # (FIX 5)", () => {
+  const origin = "https://example.test";
+  it("normalizes a javascript: source href to #", () => {
+    assert.equal(normHref("Javascript:{}", origin), "#");
+    assert.equal(normHref("javascript:void(0)", origin), "#");
+  });
+  it("makes a javascript: source match the emitted # value", () => {
+    assert.equal(normHref("javascript:{}", origin), normHref("#", origin), "source and clone agree");
+  });
+  it("still distinguishes a real fragment from a full URL", () => {
+    assert.equal(normHref("#top", origin), "#top");
+    assert.equal(normHref("https://example.test/x/", origin), "https://example.test/x");
+  });
+});
 
 // Chromium serializes a computed `letter-spacing: 0` back as the keyword `normal`. The emitter, after
 // snapping a sub-0.1px authored tracking to 0, ships `letter-spacing: 0px` — which the CLONE then
diff --git a/compiler/test/irPrune.test.ts b/compiler/test/irPrune.test.ts
index f65e4a0..f4f02a0 100644
--- a/compiler/test/irPrune.test.ts
+++ b/compiler/test/irPrune.test.ts
@@ -182,3 +182,133 @@ describe("neutralizeAnimatedTransforms (Defect C)", () => {
     assert.equal(byVp[375].transform, "matrix(1, 0, 0, 1, -100, 0)", "finite animations own a settled end state, not a perpetual phase");
   });
 });
+
+/** A RawNode with an explicit computed style and bbox (same at every viewport). Unlike `raw()` this
+ *  lets a test author invisible-but-laid-out boxes, transforms, margins, and positions directly. */
+function rawS(
+  tag: string,
+  computed: Record<string, string>,
+  bbox: { x: number; y: number; width: number; height: number },
+  children: RawChild[] = [],
+  visible = true,
+  attrs: Record<string, string> = {},
+): RawNode {
+  return { tag, attrs, computed, bbox, visible, children };
+}
+
+// FIX 2 — an in-flow `visibility:hidden` box with a nonzero border box is load-bearing geometry: it
+// reserves the row height its absolutely-positioned siblings paint into. It is invisible (so the plain
+// visibility prune would drop it), but dropping it collapses the column. It must survive as a sized
+// placeholder; a genuinely empty display:none-everywhere box must still prune.
+describe("IR prune keeps sized invisible (visibility:hidden) spacers (FIX 2)", () => {
+  it("keeps an in-flow visibility:hidden ghost column with a nonzero bbox", () => {
+    const ghost = rawS(
+      "div",
+      { display: "flex", position: "static", visibility: "hidden" },
+      { x: 0, y: 0, width: 650, height: 723 },
+      // its children are themselves invisible (they set no visibility:visible) — the box is a spacer
+      [rawS("img", { display: "block", position: "static", visibility: "hidden" }, { x: 0, y: 0, width: 650, height: 240 }, [], false)],
+      false,
+    );
+    // the real content is an absolutely-positioned sibling layered over the ghost's reserved space
+    const painted = rawS("img", { display: "block", position: "absolute", visibility: "visible" }, { x: 0, y: 0, width: 650, height: 723 }, [], true);
+    const column = rawS("div", { display: "block", position: "relative", visibility: "visible" }, { x: 0, y: 0, width: 650, height: 723 }, [ghost, painted], true);
+    const body = raw("body", {}, [column]);
+
+    const root = buildFixtureIR(body);
+    const kept = findByTag(root, "div");
+    assert.ok(kept, "the column survives");
+    // The ghost div (a second nested div) must still be present as a sized placeholder.
+    const divs: IRNode[] = [];
+    const collect = (n: IRNode): void => { if (n.tag === "div") divs.push(n); for (const c of n.children) if (!isTextChild(c)) collect(c as IRNode); };
+    collect(root);
+    // column + ghost = 2 divs (body is not a div)
+    assert.equal(divs.length, 2, "the visibility:hidden ghost column is retained, not pruned");
+    const ghostIR = divs.find((d) => d.computedByVp[1280]?.visibility === "hidden");
+    assert.ok(ghostIR, "the retained ghost carries visibility:hidden");
+    assert.ok(ghostIR!.bboxByVp[1280]!.height > 0, "the ghost keeps its load-bearing height");
+  });
+
+  it("still prunes a display:none-everywhere empty box (no resurrection)", () => {
+    const hidden = rawS("div", { display: "none", position: "static", visibility: "visible" }, { x: 0, y: 0, width: 0, height: 0 }, [], false);
+    const body = raw("body", {}, [rawS("section", { display: "block", position: "static", visibility: "visible" }, { x: 0, y: 0, width: 640, height: 100 }, [hidden], true)]);
+    const root = buildFixtureIR(body);
+    assert.equal(findByTag(root, "div"), null, "a display:none-everywhere box stays pruned");
+  });
+
+  it("does not keep an out-of-flow (absolute) visibility:hidden box as a spacer", () => {
+    // Absolute boxes take no space in flow, so an invisible absolute box is not load-bearing geometry.
+    const absHidden = rawS("div", { display: "block", position: "absolute", visibility: "hidden" }, { x: 0, y: 0, width: 300, height: 300 }, [], false);
+    const body = raw("body", {}, [rawS("section", { display: "block", position: "static", visibility: "visible" }, { x: 0, y: 0, width: 640, height: 100 }, [absHidden], true)]);
+    const root = buildFixtureIR(body);
+    assert.equal(findByTag(root, "div"), null, "an out-of-flow invisible box is not kept as a spacer");
+  });
+});
+
+// FIX 3 — a settled loop carousel parks its track with a baked translateX and prepends invisible clone
+// slides that occupy exactly [translateX, 0]; the first REAL slide paints at x=0. Pruning drops the
+// off-screen clones, but the baked translateX would survive verbatim and push every real slide
+// offscreen-left. Re-anchor the track's translateX by the aggregate outer width of the dropped leading
+// clones so the first kept slide lands at its captured position.
+describe("IR prune re-anchors a translated track after dropping leading clones (FIX 3)", () => {
+  it("re-anchors translateX toward 0 by the dropped leading clone width", () => {
+    // Three off-screen leading loop clones, each 200px wide (translateX = -600 = -(3×200)); two reals.
+    // The clones are OFF-SCREEN (visible:false via the off-screen test), NOT visibility:hidden — so
+    // they prune and the FIX-2 sized-invisible-spacer carve-out (which requires visibility:hidden) does
+    // not resurrect them. This mirrors a real settled Splide loop's leading clones.
+    const clone = (i: number): RawNode =>
+      rawS("li", { display: "block", position: "static", visibility: "visible" }, { x: -600 + i * 200, y: 0, width: 200, height: 100 }, [], false);
+    const real = (i: number): RawNode =>
+      rawS("li", { display: "block", position: "static", visibility: "visible" }, { x: i * 200, y: 0, width: 200, height: 100 }, [{ text: `real${i}` }], true);
+    const track = rawS(
+      "ul",
+      { display: "flex", position: "relative", visibility: "visible", transform: "matrix(1, 0, 0, 1, -600, 0)" },
+      { x: 0, y: 0, width: 1000, height: 100 },
+      [clone(0), clone(1), clone(2), real(0), real(1)],
+      true,
+    );
+    const body = raw("body", {}, [track]);
+    const root = buildFixtureIR(body);
+    const ul = findByTag(root, "ul")!;
+    // The clones are pruned (invisible everywhere), leaving the two real slides.
+    const slides = ul.children.filter((c) => !isTextChild(c));
+    assert.equal(slides.length, 2, "only the real slides survive");
+    // The baked -600 translate is re-anchored to 0 (−600 + 3×200).
+    assert.equal(ul.computedByVp[1280]!.transform, "matrix(1, 0, 0, 1, 0, 0)", "track translateX re-anchored to origin");
+    assert.equal(ul.computedByVp[375]!.transform, "matrix(1, 0, 0, 1, 0, 0)", "re-anchored at every viewport");
+  });
+
+  it("leaves a track untouched when no leading children are dropped", () => {
+    const real = (i: number): RawNode =>
+      rawS("li", { display: "block", position: "static", visibility: "visible" }, { x: i * 200, y: 0, width: 200, height: 100 }, [{ text: `real${i}` }], true);
+    const track = rawS(
+      "ul",
+      { display: "flex", position: "relative", visibility: "visible", transform: "matrix(1, 0, 0, 1, -120, 0)" },
+      { x: 0, y: 0, width: 400, height: 100 },
+      [real(0), real(1)],
+      true,
+    );
+    const body = raw("body", {}, [track]);
+    const root = buildFixtureIR(body);
+    const ul = findByTag(root, "ul")!;
+    assert.equal(ul.computedByVp[1280]!.transform, "matrix(1, 0, 0, 1, -120, 0)", "a track with no dropped leading children keeps its offset");
+  });
+
+  it("does not re-anchor when the dropped leading siblings are out of flow", () => {
+    const absClone = (i: number): RawNode =>
+      rawS("li", { display: "block", position: "absolute", visibility: "hidden" }, { x: -400 + i * 200, y: 0, width: 200, height: 100 }, [], false);
+    const real = (i: number): RawNode =>
+      rawS("li", { display: "block", position: "static", visibility: "visible" }, { x: i * 200, y: 0, width: 200, height: 100 }, [{ text: `real${i}` }], true);
+    const track = rawS(
+      "ul",
+      { display: "flex", position: "relative", visibility: "visible", transform: "matrix(1, 0, 0, 1, -80, 0)" },
+      { x: 0, y: 0, width: 400, height: 100 },
+      [absClone(0), absClone(1), real(0), real(1)],
+      true,
+    );
+    const body = raw("body", {}, [track]);
+    const root = buildFixtureIR(body);
+    const ul = findByTag(root, "ul")!;
+    assert.equal(ul.computedByVp[1280]!.transform, "matrix(1, 0, 0, 1, -80, 0)", "out-of-flow clones don't advance the track, so no re-anchor");
+  });
+});
diff --git a/compiler/test/walker.test.ts b/compiler/test/walker.test.ts
index 4172c04..d60277f 100644
--- a/compiler/test/walker.test.ts
+++ b/compiler/test/walker.test.ts
@@ -349,3 +349,89 @@ describe("walker text-wrap capture", () => {
     assert.equal(p.computed.textWrap, "pretty", "text-wrap:pretty is captured");
   });
 });
+
+describe("walker shadow-DOM composed-tree serialization (FIX 1)", () => {
+  let browser: Browser;
+  let page: Page;
+  before(async () => {
+    browser = await chromium.launch();
+    page = await browser.newPage({ viewport: { width: 1280, height: 800 } });
+  });
+  after(async () => {
+    await browser.close();
+  });
+
+  // Attach an OPEN shadow root to any host carrying data-shadow, injecting its data-shadow value as
+  // the shadow tree HTML. Runs in-page before collectPage so getComputedStyle/bbox see the composed tree.
+  const capture = async (html: string) => {
+    await page.setContent(html);
+    await page.evaluate(() => {
+      for (const host of Array.from(document.querySelectorAll("[data-shadow]"))) {
+        const markup = host.getAttribute("data-shadow") || "";
+        const sr = (host as HTMLElement).attachShadow({ mode: "open" });
+        sr.innerHTML = markup;
+      }
+    });
+    await page.evaluate("globalThis.__name = globalThis.__name || ((fn) => fn);");
+    return page.evaluate(collectPage);
+  };
+
+  it("serializes an open custom element's shadow tree as the host's children", async () => {
+    // A `<product-info>` web component renders its swatches/title/price INSIDE its shadow root; a
+    // childNodes-only walk captured it empty. The composed walk must surface the shadow content.
+    const snap = await capture(`
+      <product-info data-shadow="
+        <div class='pi-title'>Magnolia Shirt</div>
+        <span class='pi-price'>$78.00</span>
+      "></product-info>`);
+    const host = findByTag(snap.root, "product-info")!;
+    assert.ok(host, "the custom element host is present");
+    assert.equal(host.shadowHost, true, "the host is tagged as a shadow host");
+    assert.equal(textRun(host).replace(/\s+/g, " ").trim(), "Magnolia Shirt $78.00", "the shadow tree text is captured");
+    const title = findByClass(host, "pi-title")!;
+    assert.ok(title, "a shadow descendant node is serialized");
+    assert.equal(title.inShadow, true, "shadow descendants are tagged inShadow");
+    assert.ok(title.bbox.width > 0, "shadow nodes get real bboxes via getBoundingClientRect");
+  });
+
+  it("renders the FLATTENED tree: a <slot> is replaced by its assigned light-DOM nodes", async () => {
+    // The host's light child (the assigned node) renders at the slot position — once, and NOT tagged
+    // inShadow (it is the author's real content). Shadow chrome around the slot still appears.
+    const snap = await capture(`
+      <my-card data-shadow="
+        <div class='card-frame'><slot></slot></div>
+      "><h2 class='slotted'>Vintage Sunset T-Shirt</h2></my-card>`);
+    const host = findByTag(snap.root, "my-card")!;
+    const frame = findByClass(host, "card-frame")!;
+    assert.ok(frame, "the shadow frame around the slot is serialized");
+    assert.equal(frame.inShadow, true, "the shadow frame is tagged inShadow");
+    const slotted = findByClass(host, "slotted")!;
+    assert.ok(slotted, "the slotted light child renders at the slot position");
+    assert.equal(textRun(slotted).trim(), "Vintage Sunset T-Shirt");
+    assert.ok(!slotted.inShadow, "the slotted light child is NOT tagged inShadow (author content)");
+    // No double-serialization: exactly one node carries the slotted text.
+    let count = 0;
+    const countText = (n: RawNode): void => {
+      if (n.children.some((c) => isText(c) && c.text.includes("Vintage Sunset T-Shirt"))) count++;
+      for (const c of n.children) if (!isText(c)) countText(c as RawNode);
+    };
+    countText(host);
+    assert.equal(count, 1, "the slotted child is serialized exactly once");
+  });
+
+  it("uses <slot> fallback content when nothing is assigned", async () => {
+    const snap = await capture(`
+      <my-badge data-shadow="
+        <span class='badge'><slot>Default Label</slot></span>
+      "></my-badge>`);
+    const host = findByTag(snap.root, "my-badge")!;
+    assert.equal(textRun(host).replace(/\s+/g, " ").trim(), "Default Label", "unfilled slot falls back to its own content");
+  });
+
+  it("does not tag ordinary light-DOM nodes as shadow", async () => {
+    const snap = await capture(`<div class="plain"><p>light</p></div>`);
+    const plain = findByClass(snap.root, "plain")!;
+    assert.ok(!plain.shadowHost, "a plain div is not a shadow host");
+    assert.ok(!plain.inShadow, "plain light DOM is not tagged inShadow");
+  });
+});

From 144e7ab16bf93f3a404a98744c704cd4941789b2 Mon Sep 17 00:00:00 2001
From: Samraaj Bath <samraaj100@gmail.com>
Date: Sat, 4 Jul 2026 03:13:14 -0700
Subject: [PATCH 13/24] Clear the show-poster flag after per-viewport video
 source reload

v.load() resets the media element's show-poster flag; pause cancels
autoplay and the at-zero seek skip left nothing to clear it, so
screenshots after a source re-selection rendered the poster instead of
the new source's frame 0. Reloaded videos now force an epsilon seek
(awaiting seeked, which also serves as the readiness signal on slow
CDNs), and re-selection emits a video_source_reselected log event.

386 tests pass (4 new), typecheck clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 compiler/src/capture/capture.ts         | 92 +++++++++++++++++++++----
 compiler/test/videoSourceSelect.test.ts | 29 +++++++-
 2 files changed, 107 insertions(+), 14 deletions(-)

diff --git a/compiler/src/capture/capture.ts b/compiler/src/capture/capture.ts
index 6e74e9e..270c083 100644
--- a/compiler/src/capture/capture.ts
+++ b/compiler/src/capture/capture.ts
@@ -217,6 +217,26 @@ export function selectVideoSourceIndex(
   return -1;
 }
 
+/**
+ * Pure decision for the per-video seek in normalizeVideoTime, extracted so the reloaded-set /
+ * seek-target branch is unit-testable in Node (the in-page loop applies the same rule to real
+ * elements). Returns the seek to perform after the re-selection reload pass, or null to fast-skip.
+ *
+ * - A `reloaded` video sits at t=0 with the HTML element's show-poster flag freshly set. Seeking to
+ *   0 would be a no-op that fires no `seeked` and leaves the poster showing, so force a genuine seek
+ *   to a tiny epsilon to clear the flag and paint the new source's frame 0.
+ * - A non-reloaded video already at t≈0 needs nothing (skip). Otherwise seek it back to 0.
+ */
+export function planVideoSeek(
+  reloaded: boolean,
+  currentTime: number,
+): { target: number } | null {
+  const EPSILON = 1e-4;
+  if (reloaded) return { target: EPSILON };
+  if (Math.abs(currentTime) < 1e-3) return null;
+  return { target: 0 };
+}
+
 async function autoScroll(page: import("playwright").Page, vpHeight: number): Promise<void> {
   // Scroll through the page to trigger lazy-loaded images/backgrounds, then return
   // to the top so document-coordinate bboxes are measured from a settled layout.
@@ -850,9 +870,12 @@ async function captureScreenshot(
  * and — the common case — a no-op whenever the current selection is still the right one, so the fast
  * path never touches `video.load()`.
  */
-export async function normalizeVideoTime(page: import("playwright").Page): Promise<void> {
+export async function normalizeVideoTime(
+  page: import("playwright").Page,
+  log?: (event: Record<string, unknown>) => void,
+): Promise<void> {
   try {
-    await page.evaluate(async () => {
+    const reselections = await page.evaluate(async () => {
       const vids = Array.from(document.querySelectorAll("video"));
       const raf = () => new Promise<void>((r) => requestAnimationFrame(() => r()));
 
@@ -861,6 +884,17 @@ export async function normalizeVideoTime(page: import("playwright").Page): Promi
       // whose media matches (missing media matches unconditionally) and whose type is playable
       // (missing type is never disqualifying). Only reload when the winner differs from what is
       // currently loaded — the fast path leaves untouched videos alone.
+      //
+      // Track which videos we reloaded. A reload resets the element's *show-poster flag* to true and
+      // sets currentTime to 0; the follow-up pause() cancels the pending autoplay, so the one thing
+      // that would have cleared that flag (playback beginning) never happens. Left uncleared, the
+      // element renders its `poster` image — which for an aspect-gated hero is a frame of the WRONG
+      // variant — instead of the freshly-selected source's frame 0. A real seek is the other
+      // flag-clearing path, but the fast-skip below bails at t=0. So force a genuine seek (to a tiny
+      // epsilon, not to the already-current 0) on exactly the reloaded videos to clear the flag and
+      // present the new source's decoded frame. Non-reloaded videos keep the existing fast skip.
+      const reloaded = new WeakSet<HTMLVideoElement>();
+      const reselections: { from: string; to: string; readyState: number }[] = [];
       const reloadWaits: Promise<void>[] = [];
       for (const v of vids) {
         try {
@@ -878,34 +912,66 @@ export async function normalizeVideoTime(page: import("playwright").Page): Promi
           if (!winner || !winner.src) continue;
           // Compare resolved URLs; currentSrc is absolute, winner.src is already resolved.
           if (v.currentSrc === winner.src) continue; // no change — fast path, do not reload
+          const from = v.currentSrc;
+          const to = winner.src;
           v.load();
+          reloaded.add(v);
           reloadWaits.push(new Promise<void>((resolve) => {
             let settled = false;
-            const done = () => { if (settled) return; settled = true; v.removeEventListener("loadeddata", done); resolve(); };
+            const done = () => {
+              if (settled) return;
+              settled = true;
+              v.removeEventListener("loadeddata", done);
+              v.removeEventListener("seeked", done);
+              reselections.push({ from, to, readyState: v.readyState });
+              resolve();
+            };
             if (v.readyState >= 2 /* HAVE_CURRENT_DATA */) { done(); return; }
+            // A post-reload `seeked` implies a decoded frame is ready too, so treat it as an
+            // additional readiness signal: on slow CDNs the epsilon seek (below) can land its
+            // `seeked` before `loadeddata`, which unblocks the FIRST viewport instead of waiting
+            // out the 4s bound and shooting the poster.
             v.addEventListener("loadeddata", done, { once: true });
+            v.addEventListener("seeked", done, { once: true });
             setTimeout(done, 4000); // bound: a stalled reload resolves anyway so the shot never hangs
           }));
         } catch { /* a malformed <source>/media query must not block the others */ }
       }
-      if (reloadWaits.length) await Promise.all(reloadWaits);
 
       const waits: Promise<void>[] = [];
-      for (const v of vids) {
-        try { v.pause(); } catch { /* ignore */ }
-        // Seek to 0 only when not already there (a fresh seek to the current time may not fire `seeked`).
-        if (Math.abs(v.currentTime) < 1e-3) continue;
-        waits.push(new Promise<void>((resolve) => {
+      const seekTo = (v: HTMLVideoElement, t: number) =>
+        new Promise<void>((resolve) => {
           let settled = false;
           const done = () => { if (settled) return; settled = true; v.removeEventListener("seeked", done); resolve(); };
           v.addEventListener("seeked", done, { once: true });
-          try { v.currentTime = 0; } catch { done(); }
+          try { v.currentTime = t; } catch { done(); }
           setTimeout(done, 400); // bound: a stalled/unseekable video resolves anyway
-        }));
+        });
+      for (const v of vids) {
+        try { v.pause(); } catch { /* ignore */ }
+        if (reloaded.has(v)) {
+          // A just-reloaded video sits at t=0 with the show-poster flag set. Seek to a tiny epsilon
+          // (not 0, which is already the current time and would fire no `seeked`) to force a genuine
+          // seek: it clears the flag and paints the new source's frame 0. Start it eagerly so its
+          // `seeked` can also satisfy the reload wait above on slow networks.
+          waits.push(seekTo(v, 1e-4));
+          continue;
+        }
+        // Seek to 0 only when not already there (a fresh seek to the current time may not fire `seeked`).
+        if (Math.abs(v.currentTime) < 1e-3) continue;
+        waits.push(seekTo(v, 0));
       }
-      await Promise.all(waits);
+      // Await the reload settles and the seeks together; the reload wait can be released by an
+      // epsilon seek's `seeked`, so both sets must be in flight before we block on either.
+      await Promise.all([...reloadWaits, ...waits]);
       await raf(); await raf(); // let the decoded frame composite before the screenshot reads pixels
+      return reselections;
     });
+    if (log && reselections && reselections.length) {
+      for (const r of reselections) {
+        log({ event: "video_source_reselected", from: r.from, to: r.to, readyState: r.readyState });
+      }
+    }
   } catch { /* a page with no videos / an eval hiccup must never block the screenshot */ }
 }
 
@@ -1502,7 +1568,7 @@ export async function captureSite(opts: {
         // Normalize every video to frame 0 (paused) at THIS viewport before the shot — the clone is
         // always at frame 0, so pinning the source there too makes the two channels comparable
         // regardless of the playback time the viewport happened to catch.
-        await normalizeVideoTime(page);
+        await normalizeVideoTime(page, log);
         await captureScreenshot(page, join(screenshotsDir, `${vw}.png`), vw, log);
       }
 
diff --git a/compiler/test/videoSourceSelect.test.ts b/compiler/test/videoSourceSelect.test.ts
index b7b6c27..d144607 100644
--- a/compiler/test/videoSourceSelect.test.ts
+++ b/compiler/test/videoSourceSelect.test.ts
@@ -1,6 +1,6 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { selectVideoSourceIndex, type VideoSourceCandidate } from "../src/capture/capture.js";
+import { selectVideoSourceIndex, planVideoSeek, type VideoSourceCandidate } from "../src/capture/capture.js";
 
 // Predicate builders for the injected matchMedia / canPlayType.
 const matchesAny = (matching: Set<string>) => (m: string) => matching.has(m);
@@ -64,3 +64,30 @@ describe("selectVideoSourceIndex (video <source> resource-selection)", () => {
     assert.equal(selectVideoSourceIndex(sources, matchesAny(new Set(["(min-width: 100px)"])), canPlayAll), 0);
   });
 });
+
+describe("planVideoSeek (post-reselection seek decision)", () => {
+  it("forces an epsilon seek on a reloaded video even at t=0 (clears the show-poster flag)", () => {
+    // The core regression: a just-reloaded video is at t=0 with the poster flag set. Seeking to 0
+    // fires no `seeked` and leaves the poster showing; only a genuine seek to a nonzero epsilon
+    // clears the flag and paints the new source's frame 0.
+    const plan = planVideoSeek(true, 0);
+    assert.ok(plan, "reloaded video must seek");
+    assert.ok(plan!.target > 0, "reloaded seek target must be nonzero so `seeked` actually fires");
+    assert.ok(plan!.target < 1e-3, "epsilon must be well inside frame 0");
+  });
+
+  it("still forces the epsilon seek on a reloaded video that reports a small nonzero time", () => {
+    const plan = planVideoSeek(true, 5e-4);
+    assert.deepEqual(plan, { target: 1e-4 });
+  });
+
+  it("fast-skips a non-reloaded video already at frame 0", () => {
+    assert.equal(planVideoSeek(false, 0), null);
+    assert.equal(planVideoSeek(false, 5e-4), null); // within the 1e-3 skip band
+  });
+
+  it("seeks a non-reloaded playing video back to 0", () => {
+    assert.deepEqual(planVideoSeek(false, 3.2), { target: 0 });
+    assert.deepEqual(planVideoSeek(false, 1e-3), { target: 0 }); // exactly at the band edge → seek
+  });
+});

From 1d68f16f96d6396f4ee844162c0d7716dc8e3900 Mon Sep 17 00:00:00 2001
From: Samraaj Bath <samraaj100@gmail.com>
Date: Sat, 4 Jul 2026 03:46:31 -0700
Subject: [PATCH 14/24] Emission geometry wave: occupying off-screen items,
 height/width chain trust, subgrid, track-relative percentages, banded
 override precedence

- Off-viewport in-flow items (carousel slides beyond the right edge) keep
  their per-viewport geometry deltas - they occupy layout and set track
  cross-sizes even when not visible
- Height chains: single-viewport probe verdicts accepted for nodes that
  only paint at one band; un-probed picture/object-fit:cover children
  filling the parent count as height-deriving; a node whose own probe says
  authored-explicit keeps its height at emission (twin of the flow guard)
- Symmetric authored-width circular guard in the walker (height-only
  before), harvesting shadow-root adopted/style sheets for custom elements
- Auto margins only when width is genuinely content-constrained; gutter-
  inset full-width blocks keep literal margins
- grid-template-rows: subgrid never dropped; variant-only subgrid intent
  re-enters via partial-coverage escape; grid-item percentage widths bail
  to auto (they resolve against the track, not the container)
- Banded raw-prop detection counts non-raw band overrides so a banded
  bg-none reset isn't beaten by an inlined gradient

399 tests pass (13 new), typecheck clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 compiler/src/capture/walker.ts     |  76 +++++++++++-
 compiler/src/generate/css.ts       | 154 ++++++++++++++++++++---
 compiler/src/generate/tailwind.ts  |  29 ++++-
 compiler/test/bandingFixes.test.ts |  99 +++++++++++++++
 compiler/test/css.test.ts          | 191 +++++++++++++++++++++++++++++
 compiler/test/walker.test.ts       |  78 ++++++++++++
 6 files changed, 607 insertions(+), 20 deletions(-)
 create mode 100644 compiler/test/bandingFixes.test.ts

diff --git a/compiler/src/capture/walker.ts b/compiler/src/capture/walker.ts
index 1ea6c0f..4d523c9 100644
--- a/compiler/src/capture/walker.ts
+++ b/compiler/src/capture/walker.ts
@@ -410,8 +410,22 @@ export function collectPage(opts?: { maxNodes?: number } | void): PageSnapshot {
           hAuto = false;
           hFill = false;
         }
+        let wAuto = Math.abs(wa - r.width) <= 0.5;
+        let wFill = Math.abs(wf - r.width) <= 0.5;
+        // Circular-WIDTH guard (the mirror of the height guard above): an authored `width:24px` inside a
+        // SHRINK-TO-FIT parent (a color-swatch link in a span that shrink-wraps to it) makes BOTH
+        // `width:auto` and `width:100%` reproduce the box — the parent's width still holds while the
+        // child re-measures — so the raw verdict reads wAuto/wFill (drop) and the clone collapses the
+        // child to 0 content width (and the shrink-wrap span to its borders). When this element's own
+        // cascade/inline style declares an explicit definite width, trust it: the width is authored, so
+        // it is neither content-sized (wAuto) nor a parent fill (wFill). Only overrides when a probe
+        // actually reproduced — a genuine explicit width that auto already shrinks stays wAuto:false.
+        if ((wAuto || wFill) && r.width > 2 && authorsExplicitWidth(el, sw)) {
+          wAuto = false;
+          wFill = false;
+        }
         sizing = {
-          wAuto: Math.abs(wa - r.width) <= 0.5, wFill: Math.abs(wf - r.width) <= 0.5, hAuto,
+          wAuto, wFill, hAuto,
           hFill,
           wMin: Math.round(wmin * 100) / 100, wMax: Math.round(wmax * 100) / 100,
         };
@@ -579,6 +593,12 @@ export function collectPage(opts?: { maxNodes?: number } | void): PageSnapshot {
   // authored dimension gets dropped downstream. A declared explicit length is ground truth that
   // the height is load-bearing, so we trust the declaration over the reflow verdict.
   const explicitHeightSelectors: string[] = [];
+  // The WIDTH twin of explicitHeightSelectors: selectors that author an explicit definite `width`/
+  // `min-width` (px/rem/em/…, not auto/%/keyword). Consulted by the sizing probe to break a CIRCULAR
+  // width verdict — an authored `width:24px` inside a shrink-to-fit parent reproduces at both auto and
+  // 100% (the parent's width still holds), so the probe alone reads wAuto and the authored width gets
+  // dropped, collapsing the box in the clone.
+  const explicitWidthSelectors: string[] = [];
 
   const absUrl = (u: string): string => {
     try { return new URL(u, document.baseURI).href; } catch { return u; }
@@ -627,6 +647,22 @@ export function collectPage(opts?: { maxNodes?: number } | void): PageSnapshot {
     return false;
   };
 
+  // The WIDTH twin of authorsExplicitHeight: does this element author an explicit definite width via
+  // its own inline style (`inlineWidth`, already read by the probe) or any matched harvested rule?
+  // `isExplicitHeight` is unit-agnostic (it only rejects auto/%/keywords and matches definite lengths),
+  // so it doubles as the width predicate.
+  const authorsExplicitWidth = (el: Element, inlineWidth: string): boolean => {
+    if (isExplicitHeight(inlineWidth)) return true;
+    try {
+      const inlineMin = (el as HTMLElement).style?.getPropertyValue("min-width") || "";
+      if (isExplicitHeight(inlineMin)) return true;
+    } catch { /* ignore */ }
+    for (const sel of explicitWidthSelectors) {
+      try { if (el.matches(sel)) return true; } catch { /* invalid/unsupported selector */ }
+    }
+    return false;
+  };
+
   const readRules = (rules: CSSRuleList): void => {
     for (const rule of Array.from(rules)) {
       const type = rule.constructor.name;
@@ -657,6 +693,11 @@ export function collectPage(opts?: { maxNodes?: number } | void): PageSnapshot {
             isExplicitHeight(r.style.getPropertyValue("min-height")))) {
           explicitHeightSelectors.push(r.selectorText);
         }
+        if (r.selectorText && r.style &&
+          (isExplicitHeight(r.style.getPropertyValue("width")) ||
+            isExplicitHeight(r.style.getPropertyValue("min-width")))) {
+          explicitWidthSelectors.push(r.selectorText);
+        }
       } else if (type === "CSSMediaRule" || type === "CSSSupportsRule") {
         try { readRules((rule as CSSGroupingRule).cssRules); } catch { /* ignore */ }
       } else if (type === "CSSImportRule") {
@@ -676,6 +717,39 @@ export function collectPage(opts?: { maxNodes?: number } | void): PageSnapshot {
     }
   }
 
+  // Custom elements (web components) carry their styles INSIDE their open shadow root — via
+  // `adoptedStyleSheets` (constructable sheets) and/or `<style>`/`<link>` in the shadow tree
+  // (`shadowRoot.styleSheets`). Those sheets never appear in `document.styleSheets`, so an authored
+  // rule like `color-swatch a { width: 24px }` is invisible to the harvest above and the sizing probe
+  // can't see the explicit width. Walk every open shadow root (composed-tree sweep, matching the
+  // serializer) and read its sheets too — same `readRules` (font-faces, url()s, explicit width/height
+  // selectors). Closed roots return null and are skipped, exactly as elsewhere.
+  const shadowRoots: ShadowRoot[] = [];
+  const collectShadowRoots = (): void => {
+    const stack: Element[] = [];
+    const pushChildren = (parent: Element | Document | ShadowRoot): void => {
+      let c = parent.firstElementChild;
+      while (c) { stack.push(c); c = c.nextElementSibling; }
+    };
+    pushChildren(document);
+    // Depth-first over the composed element tree, descending into every open shadow root.
+    while (stack.length) {
+      const node = stack.pop()!;
+      const sr = (node as HTMLElement).shadowRoot;
+      if (sr) { shadowRoots.push(sr); pushChildren(sr); }
+      pushChildren(node);
+    }
+  };
+  try { collectShadowRoots(); } catch { /* ignore */ }
+  for (const sr of shadowRoots) {
+    const sheets: CSSStyleSheet[] = [];
+    try { sheets.push(...(sr.adoptedStyleSheets || [])); } catch { /* ignore */ }
+    try { sheets.push(...Array.from(sr.styleSheets || [])); } catch { /* ignore */ }
+    for (const sheet of sheets) {
+      try { readRules(sheet.cssRules); } catch { if ((sheet as CSSStyleSheet).href) cssUrlSet.add(absUrl((sheet as CSSStyleSheet).href!)); }
+    }
+  }
+
   // CSS custom properties declared on :root.
   try {
     const rootCs = window.getComputedStyle(document.documentElement);
diff --git a/compiler/src/generate/css.ts b/compiler/src/generate/css.ts
index 0140180..185cea1 100644
--- a/compiler/src/generate/css.ts
+++ b/compiler/src/generate/css.ts
@@ -1469,6 +1469,18 @@ function fluidPercentByVp(node: IRNode, parentNode: IRNode | undefined, viewport
     const flexGridItem = /(?:^|-)(?:flex|grid)$/.test(pdisp);
     const blockLevel = /^(block|flow-root|list-item|flex|grid|inline-block)$/.test(cs.display || "");
     if (!flexGridItem && !blockLevel) return null;
+    // A GRID item's `%` width resolves against its GRID AREA (its track span), NOT the grid
+    // container's content box. When the grid has more than one column track, the parent-content-box
+    // ratio computed below is against the wrong containing block — the browser would apply that % to
+    // the ~1-column track, collapsing the item (24.5% of 1240px emitted where % hits a 302px track →
+    // 74px column). We have no direct track-width evidence, so bail for a multi-column grid item and
+    // let it fall to its authored width (auto / source-intent). Single-column grids are safe: the one
+    // track spans the full content box, so the ratio base is correct.
+    const isGridItem = /(?:^|-)grid$/.test(pdisp);
+    if (isGridItem) {
+      const cols = parseTracks(pcs.gridTemplateColumns);
+      if (!cols || cols.length > 1) return null;
+    }
     const container = pb.width - pf(pcs.paddingLeft) - pf(pcs.paddingRight) - pf(pcs.borderLeftWidth) - pf(pcs.borderRightWidth);
     if (container <= 0) return null;
     const ratio = nb.width / container;
@@ -2034,6 +2046,31 @@ function flexRowHasSlack(container: IRNode, viewports: number[]): boolean {
   return checked >= 1;
 }
 
+/** Does an in-flow element CHILD derive its HEIGHT from its parent's box (fill it) at this viewport?
+ *  Two ways:
+ *   • the sizing probe measured `height:100%` reproduces and `height:auto` does NOT (hFill && !hAuto);
+ *   • the child is an UN-PROBED replaced element that soaks up the parent box height — a `<picture>`
+ *     (the probe skips it — walker's probe excludes replaced tags) or an object-fit:cover img/video —
+ *     whose border-box height ≈ the parent's CONTENT-box height. Such a child's extent equals the
+ *     parent's height only BECAUSE it fills it (object-fit:cover paints to any box, `<picture>` sizes
+ *     its inner img to the box), so it is NOT content evidence and must not explain away the parent's
+ *     authored height. Without this a `<picture h-full>` reads as real content, the authored parent
+ *     height is dropped, and the inner img re-derives from its selected source's natural aspect.
+ *  `parentContentH` is the parent's content-box height (border-box minus padding/border, top+bottom). */
+function childDerivesHeightFromParent(child: IRNode, vp: number, parentContentH: number): boolean {
+  const csz = child.sizingByVp?.[vp];
+  if (csz && csz.hFill === true && csz.hAuto === false) return true;
+  const ccs = child.computedByVp[vp]; const cb = child.bboxByVp[vp];
+  if (!ccs || !cb) return false;
+  const isPicture = child.tag === "picture";
+  const isCoverReplaced = REPLACED.has(child.tag) && /cover/.test(ccs.objectFit || "");
+  if (!isPicture && !isCoverReplaced) return false;
+  if (!(parentContentH > 0)) return false;
+  // Border-box height fills the parent content box (≤2px slop). An intrinsically-shorter media that
+  // merely SITS in a taller box (natural-aspect logo) fails this and is treated as real content.
+  return Math.abs(cb.height - parentContentH) <= Math.max(2, 0.01 * parentContentH);
+}
+
 /** Whether a node's height can FLOW (drop the baked px) — true when, at every sampled width, its
  *  border-box height is either content-driven (== the extent of its in-flow children + padding) or
  *  cross-axis STRETCH (a flex-row / grid item filling its container's content height). Both
@@ -2090,6 +2127,7 @@ function heightFlows(node: IRNode, parentNode: IRNode | undefined, viewports: nu
     // header). Dropping the height then lets the fill child re-derive from its aspect ratio and inflate
     // (a 240px hero → 720px @16/9). Do NOT flow such a box's height.
     let allInflowFill = true;
+    const nodeContentH = nb.height - pf(cs.paddingTop) - pf(cs.paddingBottom) - pf(cs.borderTopWidth) - pf(cs.borderBottomWidth);
     for (const c of node.children) {
       if (isTextChild(c)) continue;
       const ccs = c.computedByVp[vp]; const cb = c.bboxByVp[vp];
@@ -2097,8 +2135,7 @@ function heightFlows(node: IRNode, parentNode: IRNode | undefined, viewports: nu
       if (ccs.position === "absolute" || ccs.position === "fixed") continue;
       if ((ccs.float || "none") !== "none") continue;
       hasChild = true;
-      const csz = c.sizingByVp?.[vp];
-      if (!(csz && csz.hFill === true && csz.hAuto === false)) allInflowFill = false;
+      if (!childDerivesHeightFromParent(c, vp, nodeContentH)) allInflowFill = false;
       bottom = Math.max(bottom, cb.y + cb.height);
       bottomMargin = Math.max(bottomMargin, cb.y + cb.height + Math.max(0, pf(ccs.marginBottom)));
     }
@@ -2215,10 +2252,11 @@ function absoluteHeightFill(node: IRNode, parentNode: IRNode | undefined, viewpo
  *  aren't probed (the probe skips them), so this never fires on img/svg. */
 function heightProbeFills(node: IRNode, viewports: number[]): boolean {
   if (process.env.NO_HFILL) return false; // diagnostic toggle
-  let painted = 0;
+  let painted = 0; let paintedTotal = 0;
   for (const vp of viewports) {
     const cs = node.computedByVp[vp];
     if (!cs || !node.visibleByVp[vp] || (cs.display || "") === "none") continue;
+    paintedTotal++;
     const pos = cs.position || "static";
     if (pos !== "static" && pos !== "relative") return false;
     const s = node.sizingByVp?.[vp];
@@ -2226,7 +2264,11 @@ function heightProbeFills(node: IRNode, viewports: number[]): boolean {
     if (!s.hFill || s.hAuto) return false;         // must fill at 100% AND not be content-sized
     painted++;
   }
-  return painted >= 2;
+  // Normally require ≥2 painted viewports so the fill verdict is corroborated across widths. But a
+  // responsive-only variant (a `max-md:`-scoped node) is PAINTED at only one captured viewport — its
+  // single unanimous probe reading is the COMPLETE evidence set, not a lone sample, so accept it.
+  // The parent still confers a definite height (its own band-baked height), so 100% resolves safely.
+  return painted >= 2 || (painted === 1 && paintedTotal === 1);
 }
 
 /** Does this node confer a DEFINITE height to its children (so their height:100% resolves)? True when:
@@ -2399,6 +2441,17 @@ function declsForViewport(
   // collapsing is preserved.
   let explicitHeight = false;
   const nb = node.bboxByVp[vp];
+  // Probe ground truth, emission twin of the heightFlows keep (see the hAuto/hFill guard there):
+  // the sizing probe proved height:auto did NOT reproduce this box (hAuto:false) AND it is not a
+  // fill child of its own parent (hFill:false), so the captured px is AUTHORED and load-bearing.
+  // heightFlows refuses to FLOW such a box, but the emission gate below still needs a matching keep
+  // or the height is dropped when the fill-child evidence (the "taller than content" / all-inflow-fill
+  // tests) can't fire — an inline `<a>` child probes hAuto:true and content extent equals the box, so
+  // neither structural test detects the authored height. Trust the node's own probe.
+  {
+    const osz = node.sizingByVp?.[vp];
+    if (!noCollapse && !isLeaf && cs.height && cs.height !== "auto" && osz && osz.hAuto === false && osz.hFill === false) explicitHeight = true;
+  }
   if (!noCollapse && !isLeaf && cs.height && cs.height !== "auto" && nb) {
     const top = nb.y + (parseFloat(cs.paddingTop || "0") || 0) + (parseFloat(cs.borderTopWidth || "0") || 0);
     let contentBottom = top;       // includes trailing margins (for taller detection)
@@ -2409,6 +2462,7 @@ function declsForViewport(
     // height only BECAUSE they fill it — it is not content-derived evidence, so it must
     // not be allowed to "explain away" an authored height below.
     let allInflowFill = true;
+    const nodeContentH = nb.height - (parseFloat(cs.paddingTop || "0") || 0) - (parseFloat(cs.paddingBottom || "0") || 0) - (parseFloat(cs.borderTopWidth || "0") || 0) - (parseFloat(cs.borderBottomWidth || "0") || 0);
     for (const c of node.children) {
       if (isTextChild(c)) continue;
       const ccs = c.computedByVp[vp]; const cb = c.bboxByVp[vp];
@@ -2419,10 +2473,10 @@ function declsForViewport(
       if (ccs.position === "absolute" || ccs.position === "fixed") continue;
       if ((ccs.float || "none") !== "none") continue;
       inflowCount++;
-      const csz = c.sizingByVp?.[vp];
-      // A fill child: the probe measured height:100% reproduces AND auto does not (hFill && !hAuto).
-      // No probe data (older captures) ⇒ treat as real content (conservative: leave allInflowFill off).
-      if (!(csz && csz.hFill === true && csz.hAuto === false)) allInflowFill = false;
+      // A fill child derives its height from this box: probe hFill && !hAuto, OR an un-probed
+      // <picture>/object-fit:cover replaced child whose border-box == this box's content height.
+      // No probe data on a plain block child ⇒ treat as real content (leave allInflowFill off).
+      if (!childDerivesHeightFromParent(c, vp, nodeContentH)) allInflowFill = false;
       contentBottom = Math.max(contentBottom, cb.y + cb.height + (parseFloat(ccs.marginBottom || "0") || 0));
       borderBottom = Math.max(borderBottom, cb.y + cb.height);
     }
@@ -2563,6 +2617,14 @@ function declsForViewport(
     // emitted once below so it never bands per-viewport-px.
     if (prop === "gridTemplateColumns" && gridCols !== undefined) continue;
     // grid-template-rows likewise replaced by the fluid (1fr) template when one was inferred.
+    // NEVER drop a `subgrid` template: it is a STRUCTURAL keyword (the row tracks are inherited from
+    // the parent grid so both stacked layers share row sizing), not a frozen per-viewport px regime.
+    // `dropGridRows` exists to strip baked px row heights in reflow mode, but computed
+    // getComputedStyle reports the keyword literally ("subgrid [] …") — dropping it collapses the
+    // empty layer's row-1 to 0 and its media overlaps the text layer. Emit it (tailwind maps it to
+    // `grid-rows-subgrid`); the fluidGridRows path already refuses to touch subgrid nodes, so gridRows
+    // is undefined here and this keyword flows straight through.
+    if (prop === "gridTemplateRows" && /\bsubgrid\b/.test(value || "")) { out.set("grid-template-rows", "subgrid"); continue; }
     if (prop === "gridTemplateRows" && (gridRows !== undefined || dropGridRows)) continue;
     // fill-to-cap sets max-width to the recovered cap (above); don't let the source value re-emit it.
     if (prop === "maxWidth" && widthPlan.kind === "fillcap") continue;
@@ -2633,6 +2695,9 @@ function declsForViewport(
   // Centered max-width container: emit auto side margins so the browser centers
   // it at every width. getComputedStyle sometimes reports 0 for resolved auto
   // margins at wide viewports, so replaying px would left-align the clone.
+  // The fill-inset guard lives in the centering DECISION (centeredAtVp): a full-width block merely
+  // inset by a fixed gutter is no longer flagged centred, so its literal px margins are kept and it
+  // never bleeds full-bleed from a `margin:auto` that resolves to 0.
   if (isCentered) {
     out.set("margin-left", "auto");
     out.set("margin-right", "auto");
@@ -2744,6 +2809,31 @@ function marginsVaryAcrossVps(node: IRNode): boolean {
   return ms.length >= 2 && Math.max(...ms) - Math.min(...ms) > 1;
 }
 
+/** Does the box's WIDTH grow in near-lockstep with its container across viewports? Then it is a
+ *  full-width block INSET by a fixed gutter (an `mx-4 md:mx-8` section — box == container − 2·gutter),
+ *  NOT a centred content box (whose width stays roughly constant while the container grows and the
+ *  side margins absorb the widening slack). The two are indistinguishable at a SINGLE width (both show
+ *  equal side gaps), and the sizing probe reads BOTH as `wAuto:true` (auto reproduces the inset width).
+ *  The discriminator is the trajectory: a centred 600px box in a 375→1280 container barely widens
+ *  (Δbox ≪ Δcontainer), while a gutter-inset section tracks the container (Δbox ≈ Δcontainer). Used to
+ *  keep auto-margin centring OFF a width-dropped fill-inset block — where `margin:auto` resolves to 0
+ *  and blows it full-bleed — while still centring genuinely content-constrained blocks. */
+function widthTracksContainerFill(node: IRNode, parentNode: IRNode, viewports: number[]): boolean {
+  const bw: number[] = []; const cw: number[] = [];
+  for (const vp of viewports) {
+    const nb = node.bboxByVp[vp]; const pb = parentNode.bboxByVp[vp]; const pcs = parentNode.computedByVp[vp];
+    if (!nb || !pb || !node.visibleByVp[vp]) continue;
+    const content = pb.width - pf(pcs?.paddingLeft) - pf(pcs?.paddingRight) - pf(pcs?.borderLeftWidth) - pf(pcs?.borderRightWidth);
+    if (!(content > 0)) continue;
+    bw.push(nb.width); cw.push(content);
+  }
+  if (bw.length < 2) return false;
+  const dBox = Math.max(...bw) - Math.min(...bw);
+  const dCon = Math.max(...cw) - Math.min(...cw);
+  if (dCon <= 8) return false;                 // container barely varies → trajectory says nothing
+  return dBox / dCon > 0.5;                     // box widens ≥ half as fast as the container → tracks it
+}
+
 function centeredAtVp(node: IRNode, parentNode: IRNode, vp: number): boolean {
   const cs = node.computedByVp[vp];
   const nb = node.bboxByVp[vp];
@@ -2783,8 +2873,16 @@ function centeredAtVp(node: IRNode, parentNode: IRNode, vp: number): boolean {
   // px side margins, blowing a padded pill/section out to full-bleed. Equal literal margins are the
   // geometric TWIN of centering slack (both split the free space symmetrically), so this probe read
   // is the only reliable discriminator between them; when the box fills, keep the literal margins.
+  // A box the probe reads as a container-FILL (`width:100%` reproduces it) has no free space for auto
+  // margins to absorb. So does a full-width block merely INSET by a fixed gutter (`mx-4 md:mx-8`): the
+  // probe reads it `wAuto:true, wFill:false` (auto reproduces the inset width) and its symmetric
+  // margins vary per breakpoint — so it slips past `!fillsAtVp` and looks centred at any single width,
+  // yet its width TRACKS the container. Emitting `margin:auto` on it (after its width is dropped to
+  // auto) resolves the margins to 0 and blows it full-bleed. `widthTracksContainerFill` catches that
+  // trajectory; a genuinely centred content box (constant width, ballooning margins) does not track.
   const fillsAtVp = node.sizingByVp?.[vp]?.wFill === true;
-  if (ml > 0.5 && Math.abs(ml - mr) < 1 && nb.width < pb.width - 4 && marginsVaryAcrossVps(node) && !fillsAtVp) return true;
+  const gutterInset = widthTracksContainerFill(node, parentNode, Object.keys(node.computedByVp).map(Number));
+  if (ml > 0.5 && Math.abs(ml - mr) < 1 && nb.width < pb.width - 4 && marginsVaryAcrossVps(node) && !fillsAtVp && !gutterInset) return true;
   if (parentFlexGrid) return false;
   // Signal 2: bbox-centered within the parent content box with ~0 reported margins.
   if (Math.abs(ml) > 0.5 || Math.abs(mr) > 0.5) return false; // margins already explain position
@@ -3437,16 +3535,38 @@ export function collectNodeRules(ir: IR, assetMap: Map<string, string>, includeN
             if ((node.computedByVp[baseVp]?.display || "") !== "none") {
               nr.bands.push({ media: b.media, decls: new Map([["display", "none"]]) });
             }
+            continue;
           } else if (shownAtBase) {
-            // Hidden by an ancestor (or zero-size / opacity:0) but visible at base: geometry
-            // overrides are breakpoint noise — the ancestor's own hide (or the reveal replay,
-            // for scroll-reveal opacity) covers it. Emit only the hide the node itself carries.
-            const hide = new Map<string, string>();
-            if (pf(vpCs.opacity) === 0 && !animOwned.has("opacity")) hide.set("opacity", "0");
-            if (/^(hidden|collapse)$/.test(vpCs.visibility || "")) hide.set("visibility", "hidden");
-            if (hide.size) nr.bands.push({ media: b.media, decls: hide });
+            // The node is not painted here yet was not hidden by its own display:none / an
+            // ancestor's visibility (handled above). It can be (a) off-viewport / clipped — the
+            // walker marks a box invisible when `bbox.x >= vpW` — while still IN FLOW and
+            // OCCUPYING real layout space, or (b) genuinely suppressed (opacity:0 / visibility:hidden,
+            // typically a scroll-reveal or ancestor state that is breakpoint noise).
+            //
+            // Case (a) is load-bearing: an off-screen-right carousel slide is a display:block flex
+            // item that still sets its flex track's cross-size. The base rule bakes CANONICAL
+            // (desktop) geometry — a frozen desktop slide width/aspect inflates the mobile track
+            // (an off-screen `w-[285px]` slide dragging a 375px carousel to 532px). Same policy as
+            // the ownHidden / ancestor-hidden occupying-box paths above: fall through to the normal
+            // per-viewport delta so it sits at THIS width's measured geometry, not the baked canonical.
+            const bb = node.bboxByVp[b.vp];
+            const suppressed = pf(vpCs.opacity) === 0 || /^(hidden|collapse)$/.test(vpCs.visibility || "");
+            const inFlowHere = (vpCs.position || "static") === "static" || (vpCs.position || "static") === "relative";
+            if (!suppressed && inFlowHere && bb && (bb.width > 0 || bb.height > 0)) {
+              // Occupying, in-flow, merely off-viewport/clipped — fall through to the per-viewport delta.
+            } else {
+              // Suppressed (opacity:0 / visibility:hidden) but visible at base: geometry overrides are
+              // breakpoint noise — the ancestor's own hide (or the reveal replay, for scroll-reveal
+              // opacity) covers it. Emit only the hide the node itself carries.
+              const hide = new Map<string, string>();
+              if (pf(vpCs.opacity) === 0 && !animOwned.has("opacity")) hide.set("opacity", "0");
+              if (/^(hidden|collapse)$/.test(vpCs.visibility || "")) hide.set("visibility", "hidden");
+              if (hide.size) nr.bands.push({ media: b.media, decls: hide });
+              continue;
+            }
+          } else {
+            continue;
           }
-          continue;
         }
       }
       const centeredVp = stableCenter || (layoutParent ? centeredAtVp(node, layoutParent, b.vp) : false);
diff --git a/compiler/src/generate/tailwind.ts b/compiler/src/generate/tailwind.ts
index 6849ca8..23381b4 100644
--- a/compiler/src/generate/tailwind.ts
+++ b/compiler/src/generate/tailwind.ts
@@ -1000,7 +1000,28 @@ function sourceIntentUtilities(node: IRNode, parent: IRNode | undefined, viewpor
   const css: string[] = [];
   const bands = computeBands(viewports, canonical);
   for (const [axis, byVp] of perAxis) {
-    if (!viewports.every((vp) => byVp.has(vp))) continue; // avoid partial custom-class inference for now
+    if (!viewports.every((vp) => byVp.has(vp))) {
+      // Partial-coverage escape hatch for SUBGRID. `grid-rows-subgrid`/`grid-cols-subgrid` is a
+      // structural keyword authored as a variant-only utility (`max-lg:grid-rows-subgrid`, with the
+      // axis resolving to explicit tracks at ≥lg), so the map covers only a subset of viewports and
+      // the full-coverage bail below would throw it away. Subgrid is safe to band partially: emit it
+      // exactly at the covered viewports as banded variants (and as the base only when canonical is
+      // covered). Adding the axis lets the redundant computed-derived subgrid bands drop in favour of
+      // this authored intent. Other partial axes still bail (partial fluid inference is unsafe).
+      const subgridOnly = (axis === "grid-rows" || axis === "grid-cols") &&
+        [...byVp.values()].every((u) => /-subgrid$/.test(u));
+      if (!subgridOnly) continue;
+      if (!sourceAxisCompatible(node, parent, axis, byVp, viewports)) continue;
+      axes.add(axis);
+      const canon = byVp.get(canonical);
+      if (canon) utilities.push(canon);
+      for (const b of bands) {
+        if (!b.media) continue;
+        const v = byVp.get(b.vp);
+        if (v && v !== canon) utilities.push(prefixFor(b.media) + v);
+      }
+      continue;
+    }
     if (!sourceAxisCompatible(node, parent, axis, byVp, viewports)) continue;
     const base = byVp.get(canonical)!;
     axes.add(axis);
@@ -1204,7 +1225,11 @@ export function buildTailwind(ir: IR, assetMap: Map<string, string>, colorVar?:
     // one-off — emit it as an inline `style={{…}}` (exact, no Tailwind-escape mangling) so the node
     // needs no `[data-cid]` ditto.css rule and the shipped data-cid is stripped. If the prop IS
     // banded, it must stay in ditto.css: an inline style would out-specify the @media override.
-    const bandedRawProps = new Set<string>(bandRaws.flatMap((b) => [...b.raw.keys()]));
+    // Count EVERY band-touched prop (raw or not), not just the raw ones: a band that RESETS the prop
+    // to a non-raw value (e.g. `max-lg:bg-[none]` turning a gradient off on mobile) becomes a utility
+    // rather than a raw decl, so a raw-only set misses it — and inlining the base gradient then
+    // out-specifies the `@media` reset, painting the gradient where the source turned it off.
+    const bandedRawProps = new Set<string>(nr.bands.flatMap((b) => [...b.decls.keys()]));
     const inlineStyle = new Map<string, string>();
     for (const [p, v] of [...baseRaw]) {
       if (!bandedRawProps.has(p)) { inlineStyle.set(p, tokenizeColors(p, v)); baseRaw.delete(p); }
diff --git a/compiler/test/bandingFixes.test.ts b/compiler/test/bandingFixes.test.ts
new file mode 100644
index 0000000..1578ab8
--- /dev/null
+++ b/compiler/test/bandingFixes.test.ts
@@ -0,0 +1,99 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import type { IR, IRNode, IRChild, StyleMap, BBox } from "../src/normalize/ir.js";
+import { buildTailwind } from "../src/generate/tailwind.js";
+
+const VPS = [375, 1280];
+const CANONICAL = 1280;
+
+function computed(over: StyleMap = {}): StyleMap {
+  return { display: "block", position: "static", visibility: "visible", listStyleType: "disc", listStylePosition: "outside", ...over };
+}
+
+/** Per-viewport node: distinct computed style per width so a band delta is produced. */
+function pvNode(id: string, tag: string, byVp: Record<number, StyleMap>, children: IRChild[] = [], srcClass?: string): IRNode {
+  const computedByVp: Record<number, StyleMap> = {};
+  const bboxByVp: Record<number, BBox> = {};
+  const visibleByVp: Record<number, boolean> = {};
+  for (const vp of VPS) {
+    computedByVp[vp] = computed(byVp[vp]);
+    bboxByVp[vp] = { x: 0, y: 0, width: vp, height: 100 };
+    visibleByVp[vp] = true;
+  }
+  const n: IRNode = { id, tag, attrs: {}, visibleByVp, bboxByVp, computedByVp, children };
+  if (srcClass) n.srcClass = srcClass;
+  return n;
+}
+
+function irWith(root: IRNode): IR {
+  return {
+    doc: {
+      sourceUrl: "https://example.test/banding",
+      title: "Banding Fixture",
+      lang: "en",
+      charset: "UTF-8",
+      metaViewport: "width=device-width, initial-scale=1",
+      viewports: VPS,
+      sampleViewports: VPS,
+      canonicalViewport: CANONICAL,
+      perViewport: Object.fromEntries(VPS.map((vp) => [vp, { scrollHeight: 800, scrollWidth: vp, htmlBg: "rgb(255, 255, 255)", bodyBg: "rgb(255, 255, 255)", bodyColor: "rgb(0, 0, 0)", bodyFont: "Arial" }])),
+      nodeCount: 3,
+      keyframes: [],
+    },
+    root,
+  };
+}
+
+// C3 — a base RAW value (gradient) with a band that RESETS the same prop to a NON-raw value
+// (`background-image: none` → utility `bg-[none]`) must keep the base gradient in ditto.css, not
+// inline. An inline style out-specifies the @media reset, painting the gradient where the source
+// turned it off (the mobile shimmer-blob defect). The banded-props set must count ALL band-touched
+// props, not just the raw ones.
+describe("buildTailwind banded non-raw override keeps base gradient in ditto.css (C3)", () => {
+  it("does not inline a base gradient when a band resets background-image to none", () => {
+    const grad = "linear-gradient(90deg, rgb(1, 2, 3), rgb(4, 5, 6))";
+    // 1280 (canonical/base): gradient painted; 375 (mobile band): background-image none.
+    const el = pvNode("n1", "span", {
+      375: { backgroundImage: "none" },
+      1280: { backgroundImage: grad },
+    }, [{ text: "Grepping" } as IRChild]);
+    const root = pvNode("n0", "body", { 375: {}, 1280: {} }, [el]);
+    const tw = buildTailwind(irWith(root), new Map());
+    const inline = tw.styleOf.get("n1");
+    const inlineHasGrad = !!inline && [...inline.values()].some((v) => v.includes("gradient("));
+    assert.ok(!inlineHasGrad, `banded gradient must NOT be inlined, got inline: ${inline ? JSON.stringify([...inline]) : "none"}`);
+    // It must instead live in ditto.css (extraCss folded into pseudoCss) as a [data-cid] rule.
+    assert.ok(/\[data-cid="n1"\][\s\S]*gradient\(/.test(tw.pseudoCss), `base gradient must be a ditto.css rule, got:\n${tw.pseudoCss}`);
+  });
+
+  it("still inlines a base gradient with NO band touching background-image (unchanged path)", () => {
+    const grad = "linear-gradient(90deg, rgb(1, 2, 3), rgb(4, 5, 6))";
+    const el = pvNode("n1", "span", {
+      375: { backgroundImage: grad },
+      1280: { backgroundImage: grad },
+    }, [{ text: "static gradient" } as IRChild]);
+    const root = pvNode("n0", "body", { 375: {}, 1280: {} }, [el]);
+    const tw = buildTailwind(irWith(root), new Map());
+    const inline = tw.styleOf.get("n1");
+    const inlineHasGrad = !!inline && [...inline.values()].some((v) => v.includes("gradient("));
+    assert.ok(inlineHasGrad, `a truly static (un-banded) gradient is still inlined, got inline: ${inline ? JSON.stringify([...inline]) : "none"}`);
+  });
+});
+
+// C1 (tailwind intent side) — a variant-only `max-lg:grid-rows-subgrid` covers only a subset of
+// viewports (the axis resolves to explicit tracks at ≥lg). The partial-coverage bail must let subgrid
+// through as a banded variant instead of discarding it.
+describe("buildTailwind partial-coverage subgrid intent (C1)", () => {
+  it("emits grid-rows-subgrid from a variant-only source class", () => {
+    // Grid at both widths; subgrid computed at the mobile band (375) and explicit tracks at 1280.
+    // Source authored `max-lg:grid-rows-subgrid`.
+    const el = pvNode("n1", "div", {
+      375: { display: "grid", gridTemplateRows: "subgrid" },
+      1280: { display: "grid", gridTemplateRows: "340px 340px" },
+    }, [{ text: "card" } as IRChild], "max-lg:grid-rows-subgrid");
+    const root = pvNode("n0", "body", { 375: {}, 1280: {} }, [el]);
+    const tw = buildTailwind(irWith(root), new Map());
+    const cls = tw.classOf.get("n1") || "";
+    assert.ok(/grid-rows-subgrid/.test(cls), `subgrid must survive the partial-intent path, got class: "${cls}"`);
+  });
+});
diff --git a/compiler/test/css.test.ts b/compiler/test/css.test.ts
index b409c31..76c9468 100644
--- a/compiler/test/css.test.ts
+++ b/compiler/test/css.test.ts
@@ -864,3 +864,194 @@ describe("generateCss circular carousel slide with a block-level fill child (FIX
     assert.ok(/width:220px/.test(slide), `the library-sized slide must keep its 220px width, got: ${slide}`);
   });
 });
+
+// ===========================================================================
+// Emission-geometry fix wave (T1/T2/T3/T5, C1 css side, C2)
+// ===========================================================================
+
+// T5 — a FULL-WIDTH block merely inset by a fixed gutter (`mx-4 md:mx-8`: box == container − 2·gutter,
+// width TRACKS the container) must NOT be auto-centred. Its symmetric margins vary per breakpoint and
+// the probe reads wAuto (auto reproduces the inset width), so it slips past the fill guard — but
+// emitting margin:auto on a width-dropped block resolves the margins to 0 and blows it full-bleed.
+describe("generateCss auto-margin gutter-inset guard (T5)", () => {
+  const auto = (): RawSizing => ({ wAuto: true, wFill: false, hAuto: true, hFill: false });
+  it("keeps literal px margins on a full-width gutter-inset block (width tracks the container)", () => {
+    // mx-4 (16px) mobile, mx-8 (32px) desktop: box width == container − 2·gutter at every width, so it
+    // TRACKS the container (343→704→1216). Not a centred content box.
+    const child = xNode("n1", "div", {
+      375: { cs: { display: "block", marginLeft: "16px", marginRight: "16px", width: "343px" }, bbox: { x: 16, y: 0, width: 343, height: 40 }, sizing: auto() },
+      768: { cs: { display: "block", marginLeft: "32px", marginRight: "32px", width: "704px" }, bbox: { x: 32, y: 0, width: 704, height: 40 }, sizing: auto() },
+      1280: { cs: { display: "block", marginLeft: "32px", marginRight: "32px", width: "1216px" }, bbox: { x: 32, y: 0, width: 1216, height: 40 }, sizing: auto() },
+    });
+    const parent = xNode("n0", "body", {
+      375: { cs: { display: "block" }, bbox: { x: 0, y: 0, width: 375, height: 40 } },
+      768: { cs: { display: "block" }, bbox: { x: 0, y: 0, width: 768, height: 40 } },
+      1280: { cs: { display: "block" }, bbox: { x: 0, y: 0, width: 1280, height: 40 } },
+    }, [child]);
+    const css = generateCss(xIr(parent), new Map());
+    const all = allRulesX(css, "n1");
+    assert.ok(!/margin-left:auto/.test(all), `a gutter-inset full-width block must not be auto-centred, got: ${all}`);
+    assert.ok(/margin-left:16px|margin-left:32px/.test(all), `it must keep its literal px margins, got: ${all}`);
+  });
+});
+
+// T3 — an authored height whose OWN probe says hAuto:false && hFill:false is load-bearing. The
+// structural "taller than content" tests can't fire when an inline child's extent equals the box, so
+// emission must trust the node's own probe (the twin of the heightFlows keep) and emit the height.
+describe("generateCss authored-height kept via own probe (T3)", () => {
+  it("emits the height when the node's own probe is hAuto:false, hFill:false", () => {
+    const explicit = (): RawSizing => ({ wAuto: false, wFill: false, hAuto: false, hFill: false });
+    // Wrapper's only in-flow child is an inline <a> whose box equals the wrapper (content extent ==
+    // box height), so neither the taller-than-content nor overflow test can fire.
+    const link = xNode("n2", "a", {
+      375: { cs: { display: "inline", position: "static" }, bbox: { x: 0, y: 0, width: 220, height: 300 } },
+      768: { cs: { display: "inline", position: "static" }, bbox: { x: 0, y: 0, width: 220, height: 300 } },
+      1280: { cs: { display: "inline", position: "static" }, bbox: { x: 0, y: 0, width: 220, height: 300 } },
+    }, [{ text: "shop" } as IRChild]);
+    const wrapper = xNode("n1", "div", {
+      375: { cs: { display: "block", position: "static", height: "300px" }, bbox: { x: 0, y: 0, width: 220, height: 300 }, sizing: explicit() },
+      768: { cs: { display: "block", position: "static", height: "300px" }, bbox: { x: 0, y: 0, width: 220, height: 300 }, sizing: explicit() },
+      1280: { cs: { display: "block", position: "static", height: "300px" }, bbox: { x: 0, y: 0, width: 220, height: 300 }, sizing: explicit() },
+    }, [link]);
+    const parent = xNode("n0", "body", {
+      375: { bbox: { x: 0, y: 0, width: 375, height: 300 } },
+      768: { bbox: { x: 0, y: 0, width: 768, height: 300 } },
+      1280: { bbox: { x: 0, y: 0, width: 1280, height: 300 } },
+    }, [wrapper]);
+    const css = generateCss(xIr(parent), new Map());
+    const all = allRulesX(css, "n1");
+    assert.ok(/height:300px/.test(all), `authored height must survive on own-probe evidence, got: ${all}`);
+  });
+});
+
+// C1 (css side) — a computed `grid-template-rows: subgrid` is a STRUCTURAL keyword, not a baked px
+// regime. It must NEVER be dropped by the reflow-mode dropGridRows path (which strips px row tracks).
+describe("collectNodeRules never drops a subgrid rows template (C1)", () => {
+  function gridFixture() {
+    const layer = xNode("n2", "a", {
+      375: { cs: { display: "grid", position: "static", gridTemplateRows: "subgrid" }, bbox: { x: 0, y: 0, width: 375, height: 400 } },
+      768: { cs: { display: "grid", position: "static", gridTemplateRows: "subgrid" }, bbox: { x: 0, y: 0, width: 768, height: 400 } },
+      1280: { cs: { display: "grid", position: "static", gridTemplateRows: "subgrid" }, bbox: { x: 0, y: 0, width: 1280, height: 400 } },
+    });
+    const outer = xNode("n1", "div", {
+      375: { cs: { display: "grid", position: "static", gridTemplateRows: "139px 717px" }, bbox: { x: 0, y: 0, width: 375, height: 856 } },
+      768: { cs: { display: "grid", position: "static", gridTemplateRows: "139px 717px" }, bbox: { x: 0, y: 0, width: 768, height: 856 } },
+      1280: { cs: { display: "grid", position: "static", gridTemplateRows: "340px 340px" }, bbox: { x: 0, y: 0, width: 1280, height: 680 } },
+    }, [layer]);
+    return xNode("n0", "body", {
+      375: { bbox: { x: 0, y: 0, width: 375, height: 856 } },
+      768: { bbox: { x: 0, y: 0, width: 768, height: 856 } },
+      1280: { bbox: { x: 0, y: 0, width: 1280, height: 680 } },
+    }, [outer]);
+  }
+
+  it("emits grid-template-rows:subgrid even in reflow mode", () => {
+    const rules = collectNodeRules(xIr(gridFixture()), new Map(), undefined, undefined, undefined, true);
+    const nr = rules.get("n2");
+    assert.ok(nr, "subgrid layer rule must exist");
+    const all = [nr!.base.get("grid-template-rows"), ...nr!.bands.map((b) => b.decls.get("grid-template-rows"))].filter(Boolean).join(";");
+    assert.ok(/subgrid/.test(all), `subgrid keyword must survive reflow dropGridRows, got: ${all}`);
+  });
+});
+
+// C2 — a grid ITEM's `%` width resolves against its GRID AREA (track), not the grid container's
+// content box. For a multi-column grid the parent-content-box ratio is the wrong base, so the fluid
+// per-band percent path must BAIL (the item falls to auto/fixed) rather than emit a collapsing %.
+describe("generateCss grid-item percent width bails to track (C2)", () => {
+  function gridItemFixture() {
+    // 4-column grid: each track ~302px. The item's width == its track (varies with the container), so
+    // fluidPercentByVp would compute ~24.5% of the 1240px content box — wrong (browser applies it to
+    // the 302px track → 74px). Must not emit a percent width.
+    const item = xNode("n2", "div", {
+      375: { cs: { display: "block", position: "static" }, bbox: { x: 0, y: 0, width: 343, height: 108 } },
+      768: { cs: { display: "block", position: "static" }, bbox: { x: 0, y: 0, width: 176, height: 108 } },
+      1280: { cs: { display: "block", position: "static" }, bbox: { x: 0, y: 0, width: 302, height: 108 } },
+    }, [{ text: "changelog card" } as IRChild]);
+    const grid = xNode("n1", "div", {
+      375: { cs: { display: "grid", position: "static", gridTemplateColumns: "343px" }, bbox: { x: 0, y: 0, width: 375, height: 108 } },
+      768: { cs: { display: "grid", position: "static", gridTemplateColumns: "176px 176px 176px" }, bbox: { x: 0, y: 0, width: 768, height: 108 } },
+      1280: { cs: { display: "grid", position: "static", gridTemplateColumns: "302px 302px 302px 302px" }, bbox: { x: 0, y: 0, width: 1240, height: 108 } },
+    }, [item]);
+    return xNode("n0", "body", {
+      375: { bbox: { x: 0, y: 0, width: 375, height: 108 } },
+      768: { bbox: { x: 0, y: 0, width: 768, height: 108 } },
+      1280: { bbox: { x: 0, y: 0, width: 1280, height: 108 } },
+    }, [grid]);
+  }
+
+  it("does not emit a container-content-box percent width for a multi-column grid item", () => {
+    const css = generateCss(xIr(gridItemFixture()), new Map());
+    const all = allRulesX(css, "n2");
+    assert.ok(!/width:24\.5%|width:24%/.test(all), `grid item must not resolve % against the wrong containing block, got: ${all}`);
+  });
+});
+
+// T1 — an off-screen-right (invisible-by-vp) in-flow flex slide still OCCUPIES layout and sets its
+// track's cross-size. The base rule bakes canonical (desktop) geometry; without a per-viewport delta
+// the frozen desktop width inflates the mobile track. The band must carry the slide's measured
+// per-viewport geometry, not just a hide.
+describe("collectNodeRules off-screen in-flow slide per-viewport geometry (T1)", () => {
+  function carousel() {
+    // Slide is visible at 1280 (285px desktop) but off-screen-right at 375 (invisible-by-vp, measured
+    // 220px). It is in-flow (static), display:block, non-zero bbox at 375 — occupying.
+    const slide = xNode("n2", "li", {
+      375: { cs: { display: "block", position: "static", flexShrink: "0", width: "220px", opacity: "1" }, bbox: { x: 400, y: 0, width: 220, height: 300 }, visible: false },
+      768: { cs: { display: "block", position: "static", flexShrink: "0", width: "220px", opacity: "1" }, bbox: { x: 500, y: 0, width: 220, height: 300 }, visible: false },
+      1280: { cs: { display: "block", position: "static", flexShrink: "0", width: "285px", opacity: "1" }, bbox: { x: 0, y: 0, width: 285, height: 400 }, visible: true },
+    }, [{ text: "slide" } as IRChild]);
+    const track = xNode("n1", "ul", {
+      375: { cs: { display: "flex", position: "static" }, bbox: { x: 0, y: 0, width: 375, height: 300 } },
+      768: { cs: { display: "flex", position: "static" }, bbox: { x: 0, y: 0, width: 768, height: 300 } },
+      1280: { cs: { display: "flex", position: "static" }, bbox: { x: 0, y: 0, width: 1280, height: 400 } },
+    }, [slide]);
+    return xNode("n0", "body", {
+      375: { bbox: { x: 0, y: 0, width: 375, height: 300 } },
+      768: { bbox: { x: 0, y: 0, width: 768, height: 300 } },
+      1280: { bbox: { x: 0, y: 0, width: 1280, height: 400 } },
+    }, [track]);
+  }
+
+  it("emits a per-viewport width delta for the off-screen slide (not just a hide)", () => {
+    const rules = collectNodeRules(xIr(carousel()), new Map());
+    const nr = rules.get("n2");
+    assert.ok(nr, "slide rule must exist");
+    // The narrow band must carry the measured 220px width, overriding the baked 285px desktop base.
+    const narrowBand = nr!.bands.find((b) => /max-width/.test(b.media) && b.decls.has("width"));
+    assert.ok(narrowBand, `off-screen slide must get a per-viewport width delta, got bands: ${JSON.stringify(nr!.bands.map((b) => ({ m: b.media, w: b.decls.get("width") })))}`);
+    assert.equal(narrowBand!.decls.get("width"), "220px", "the band carries the measured narrow-vp width");
+  });
+});
+
+// T2 — an authored parent height whose only in-flow child is an UN-PROBED <picture>/object-fit:cover
+// replaced element that FILLS the box (border-box == parent content box) must be treated as a
+// height-deriving fill child (so the authored height is kept, not dropped as content-derived).
+describe("collectNodeRules picture fill child keeps authored height (T2)", () => {
+  function heroFixture() {
+    const explicitH = (): RawSizing => ({ wAuto: false, wFill: true, hAuto: false, hFill: false });
+    // <picture> is a replaced tag the probe skips → no sizing; its border-box == the wrapper content
+    // box at every vp. Height varies across vps so the flow path would otherwise try to drop it.
+    const picture = xNode("n2", "picture", {
+      375: { cs: { display: "block", position: "static" }, bbox: { x: 0, y: 0, width: 375, height: 560 } },
+      768: { cs: { display: "block", position: "static" }, bbox: { x: 0, y: 0, width: 768, height: 500 } },
+      1280: { cs: { display: "block", position: "static" }, bbox: { x: 0, y: 0, width: 1280, height: 480 } },
+    });
+    const wrapper = xNode("n1", "div", {
+      375: { cs: { display: "block", position: "static", height: "560px" }, bbox: { x: 0, y: 0, width: 375, height: 560 }, sizing: explicitH() },
+      768: { cs: { display: "block", position: "static", height: "500px" }, bbox: { x: 0, y: 0, width: 768, height: 500 }, sizing: explicitH() },
+      1280: { cs: { display: "block", position: "static", height: "480px" }, bbox: { x: 0, y: 0, width: 1280, height: 480 }, sizing: explicitH() },
+    }, [picture]);
+    return xNode("n0", "body", {
+      375: { bbox: { x: 0, y: 0, width: 375, height: 560 } },
+      768: { bbox: { x: 0, y: 0, width: 768, height: 500 } },
+      1280: { bbox: { x: 0, y: 0, width: 1280, height: 480 } },
+    }, [wrapper]);
+  }
+
+  it("keeps the wrapper's authored height when a <picture> child fills it", () => {
+    const rules = collectNodeRules(xIr(heroFixture()), new Map());
+    const nr = rules.get("n1");
+    assert.ok(nr, "wrapper rule must exist");
+    const all = [nr!.base.get("height"), ...nr!.bands.map((b) => b.decls.get("height"))].filter(Boolean).join(";");
+    assert.ok(/560px|500px|480px/.test(all), `authored height must survive with a picture fill child, got: ${all}`);
+  });
+});
diff --git a/compiler/test/walker.test.ts b/compiler/test/walker.test.ts
index d60277f..5bc48dd 100644
--- a/compiler/test/walker.test.ts
+++ b/compiler/test/walker.test.ts
@@ -318,6 +318,84 @@ describe("walker sizing probe: circular authored-height guard", () => {
   });
 });
 
+// T4 — symmetric circular-WIDTH guard: an authored `width:24px` inside a SHRINK-TO-FIT parent makes
+// both width:auto and width:100% reproduce the box (the parent's width still holds), so the raw probe
+// reads wAuto/wFill and the width is dropped — collapsing the swatch in the clone. When the element
+// authors an explicit definite width (cascade or inline), the probe must trust that and clear both.
+describe("walker sizing probe: circular authored-width guard (T4)", () => {
+  let browser: Browser;
+  let page: Page;
+  before(async () => {
+    browser = await chromium.launch();
+    page = await browser.newPage({ viewport: { width: 1280, height: 720 } });
+  });
+  after(async () => {
+    await browser.close();
+  });
+
+  const capture = async (html: string) => {
+    await page.setContent(html);
+    await page.evaluate("globalThis.__name = globalThis.__name || ((fn) => fn);");
+    return page.evaluate(collectPage);
+  };
+
+  it("keeps an explicit px width inside a shrink-wrap parent (cascade rule)", async () => {
+    // The wrapper is an inline-block that shrink-wraps to the swatch; width:auto on the swatch still
+    // reads 24px because the parent width holds → the raw verdict would be wAuto:true (dropped).
+    const snap = await capture(`
+      <style>
+        .wrapper { display: inline-block; border: 1px solid #000; }
+        .swatch { width: 24px; height: 24px; display: block; background: red; }
+      </style>
+      <span class="wrapper"><a class="swatch"></a></span>`);
+    const swatch = findByClass(snap.root, "swatch")!;
+    assert.ok(swatch.sizing, "swatch was probed");
+    assert.equal(swatch.sizing!.wAuto, false, "explicit 24px width is not content-sized (auto)");
+    assert.equal(swatch.sizing!.wFill, false, "explicit 24px width is authored, not a parent fill");
+  });
+
+  it("keeps an explicit width authored via inline style", async () => {
+    const snap = await capture(`
+      <span style="display:inline-block;border:1px solid #000;">
+        <a class="swatch2" style="width:24px;height:24px;display:block;background:blue;"></a>
+      </span>`);
+    const swatch = findByClass(snap.root, "swatch2")!;
+    assert.ok(swatch.sizing, "swatch was probed");
+    assert.equal(swatch.sizing!.wAuto, false, "inline explicit width is kept (not auto)");
+    assert.equal(swatch.sizing!.wFill, false, "inline explicit width is not a fill");
+  });
+
+  it("still detects a genuinely content-sized (auto) width as wAuto", async () => {
+    // No authored width: an inline-block sizing to its text must stay droppable (wAuto:true).
+    const snap = await capture(`
+      <div style="display:block;"><span class="cw" style="display:inline-block;">hello content</span></div>`);
+    const cw = findByClass(snap.root, "cw")!;
+    assert.ok(cw.sizing, "cw was probed");
+    assert.equal(cw.sizing!.wAuto, true, "content-sized width is still auto");
+  });
+
+  it("harvests an explicit-width rule from a custom element's SHADOW ROOT stylesheet", async () => {
+    // The width:24px rule lives inside the custom element's shadow root (a <style> in the shadow tree),
+    // never in document.styleSheets. Without walking shadow-root sheets the harvest misses it and the
+    // circular-width guard can't fire for the swatch link. Verify the shadow swatch keeps its width.
+    const snap = await capture(`
+      <script>
+        customElements.define('color-swatch', class extends HTMLElement {
+          constructor() {
+            super();
+            const r = this.attachShadow({ mode: 'open' });
+            r.innerHTML = '<style>.wrap{display:inline-block;border:1px solid #000}.pin{width:24px;height:24px;display:block;background:green}</style><span class="wrap"><a class="pin"></a></span>';
+          }
+        });
+      </script>
+      <color-swatch></color-swatch>`);
+    const pin = findByClass(snap.root, "pin")!;
+    assert.ok(pin.sizing, "shadow swatch was probed");
+    assert.equal(pin.sizing!.wAuto, false, "shadow-root explicit 24px width is kept (not auto)");
+    assert.equal(pin.sizing!.wFill, false, "shadow-root explicit width is not a fill");
+  });
+});
+
 describe("walker text-wrap capture", () => {
   let browser: Browser;
   let page: Page;

From 994d2bc21e3c1e73f9fa02114f1e6d92b2b7a27d Mon Sep 17 00:00:00 2001
From: Samraaj Bath <samraaj100@gmail.com>
Date: Sat, 4 Jul 2026 04:29:50 -0700
Subject: [PATCH 15/24] Band coverage for never-visible occupying items,
 page-height trust guard, font materialization integrity

- Items never visible at the canonical viewport (carousel slides off-screen
  at every captured width) now fall through to per-viewport geometry bands
  when they occupy layout, instead of freezing canonical geometry
- The explicit-height probe trust excludes body/html/main and any wrapper
  whose height matches the page scrollHeight - page-height nodes keep
  flowing, and the layout height gate stays meaningful
- @font-face and style-rule url() harvesting resolves against the OWNING
  stylesheet's href (walking @import nesting), not document.baseURI;
  font bytes are magic-byte validated at the storage choke point (HTML
  bodies from catch-all 200 routes are rejected); font-face dedup prefers
  the variant whose source actually resolved, deterministically

415 tests pass (16 new), typecheck clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 compiler/src/capture/capture.ts         |  26 ++++
 compiler/src/capture/walker.ts          |  52 ++++++--
 compiler/src/generate/css.ts            |  30 ++++-
 compiler/src/infer/fonts.ts             |  62 +++++++---
 compiler/test/css.test.ts               |  61 ++++++++++
 compiler/test/fontIntegrity.test.ts     | 152 ++++++++++++++++++++++++
 compiler/test/fontUrlResolution.test.ts | 136 +++++++++++++++++++++
 7 files changed, 491 insertions(+), 28 deletions(-)
 create mode 100644 compiler/test/fontIntegrity.test.ts
 create mode 100644 compiler/test/fontUrlResolution.test.ts

diff --git a/compiler/src/capture/capture.ts b/compiler/src/capture/capture.ts
index 270c083..010a2aa 100644
--- a/compiler/src/capture/capture.ts
+++ b/compiler/src/capture/capture.ts
@@ -182,6 +182,28 @@ export function looksLikeVideoFile(bytes: Buffer): boolean {
   return false;
 }
 
+/** Container-magic check for accepted font bytes, mirroring `looksLikeVideoFile`. A router that
+ *  answers 200+HTML for an unknown `/media/*` path (common on SPA hosts) otherwise gets stored as
+ *  a `.woff2`; the browser rejects it as a font and the whole page falls through to a system
+ *  fallback. Accept only the real font-container signatures — woff2 (`wOF2`), woff (`wOFF`),
+ *  OpenType/CFF (`OTTO`), TrueType (`\x00\x01\x00\x00` or `true`/`ttcf`), and EOT (the version
+ *  header at bytes 8..11 is `\x01\x00\x01\x00`/`\x02\x00\x01\x00`, so key EOT off its unique
+ *  0x504C signature at offset 34) — and explicitly reject an HTML/text body. */
+export function looksLikeFontFile(bytes: Buffer): boolean {
+  if (bytes.length < 4) return false;
+  const b0 = bytes[0]!, b1 = bytes[1]!, b2 = bytes[2]!, b3 = bytes[3]!;
+  // A leading `<` (`<!DOCTYPE`, `<html`, `<?xml`, `<svg`) is never a binary font container.
+  if (b0 === 0x3c) return false;
+  const tag = bytes.subarray(0, 4).toString("latin1");
+  if (tag === "wOF2" || tag === "wOFF") return true; // woff2 / woff
+  if (tag === "OTTO" || tag === "true" || tag === "ttcf") return true; // CFF OpenType / TrueType / TrueType collection
+  if (b0 === 0x00 && b1 === 0x01 && b2 === 0x00 && b3 === 0x00) return true; // TrueType sfnt (\x00\x01\x00\x00)
+  // EOT: a little-endian byte count precedes a version/flags header; its stable marker is the
+  // 0x504C ("LP") magic at byte offset 34.
+  if (bytes.length >= 36 && bytes[34] === 0x4c && bytes[35] === 0x50) return true;
+  return false;
+}
+
 /**
  * A `<source>` candidate for the HTML media resource-selection algorithm. `media`/`type` are the
  * raw attribute strings (null/undefined when absent, matching a missing attribute).
@@ -1047,6 +1069,10 @@ export async function captureSite(opts: {
     // page stored under first-stored-wins ships a corrupt file). Left unstored, the
     // asset surfaces in visual_assets_missing instead.
     if (type === "video" && !looksLikeVideoFile(bytes)) return;
+    // Same guard for fonts: a 200+HTML body (SPA router answering an unknown /media/* path) must not
+    // be stored as a .woff2. Left unstored, the face surfaces as failed, so the font graph can fall
+    // back to a correctly-resolved duplicate url instead of shipping an impostor the browser rejects.
+    if (type === "font" && !looksLikeFontFile(bytes)) return;
     const a = assetMap.get(url) ?? recordAsset(url, type, null, null, "network");
     if (a.storedAs) return;
     // A `.lottie` (dotLottie) asset is a ZIP archive, not bare lottie-web JSON. lottie-web's
diff --git a/compiler/src/capture/walker.ts b/compiler/src/capture/walker.ts
index 4d523c9..0cb039b 100644
--- a/compiler/src/capture/walker.ts
+++ b/compiler/src/capture/walker.ts
@@ -80,6 +80,10 @@ export type FontFace = {
   display?: string;
   unicodeRange?: string;
   stretch?: string;
+  // Url of the stylesheet this face was declared in (undefined for an inline <style>, or for faces
+  // parsed out-of-band where the base is already baked into `src`). The src descriptor's relative
+  // url()s resolve against this, not the document — see readRules and parseSrcUrls.
+  baseHref?: string;
 };
 
 export type PageSnapshot = {
@@ -600,17 +604,34 @@ export function collectPage(opts?: { maxNodes?: number } | void): PageSnapshot {
   // dropped, collapsing the box in the clone.
   const explicitWidthSelectors: string[] = [];
 
-  const absUrl = (u: string): string => {
-    try { return new URL(u, document.baseURI).href; } catch { return u; }
+  const absUrl = (u: string, base?: string): string => {
+    try { return new URL(u, base || document.baseURI).href; } catch { return u; }
   };
 
-  const harvestUrlsFromText = (text: string): void => {
+  // A relative url() inside a stylesheet resolves against THAT STYLESHEET'S url, not the document —
+  // `url("../media/x.woff2")` in `/a/b/css/sheet.css` points at `/a/b/media/x.woff2`, which is a
+  // different file from the document-relative `/media/x.woff2`. Resolving font/image srcs against
+  // `document.baseURI` fetches the wrong path (often the SPA router's 200+HTML shell), so a harvested
+  // face src must carry its owning sheet's base. Walk up through `@import` nesting (parentStyleSheet
+  // via ownerRule) to the nearest sheet that actually has an href; an inline `<style>` has none, so
+  // it correctly falls back to the document base.
+  const sheetBaseHref = (sheet: CSSStyleSheet | null | undefined): string | undefined => {
+    let s: CSSStyleSheet | null | undefined = sheet;
+    // Bound the walk defensively; @import chains are shallow in practice.
+    for (let i = 0; s && i < 32; i++) {
+      if (s.href) return s.href;
+      s = s.ownerRule?.parentStyleSheet ?? null;
+    }
+    return undefined;
+  };
+
+  const harvestUrlsFromText = (text: string, base?: string): void => {
     const re = /url\(\s*(['"]?)([^'")]+)\1\s*\)/g;
     let m: RegExpExecArray | null;
     while ((m = re.exec(text)) !== null) {
       const raw = m[2];
       if (!raw || raw.startsWith("data:")) continue;
-      cssUrlSet.add(absUrl(raw));
+      cssUrlSet.add(absUrl(raw, base));
     }
   };
 
@@ -663,7 +684,12 @@ export function collectPage(opts?: { maxNodes?: number } | void): PageSnapshot {
     return false;
   };
 
-  const readRules = (rules: CSSRuleList): void => {
+  // `base` is the url of the stylesheet these rules live in (undefined for an inline <style>, which
+  // resolves against the document). It is threaded so every harvested url() — @font-face src and
+  // ordinary style-rule url() alike — resolves relative to its OWNING sheet, not the page. The src
+  // string is left verbatim on the FontFace (parseSrcUrls re-absolutizes it downstream against the
+  // same base), but the base still drives the cssUrlSet entry that triggers the download.
+  const readRules = (rules: CSSRuleList, base?: string): void => {
     for (const rule of Array.from(rules)) {
       const type = rule.constructor.name;
       if (type === "CSSFontFaceRule") {
@@ -680,14 +706,15 @@ export function collectPage(opts?: { maxNodes?: number } | void): PageSnapshot {
             display: s.getPropertyValue("font-display") || undefined,
             unicodeRange: s.getPropertyValue("unicode-range") || undefined,
             stretch: s.getPropertyValue("font-stretch") || undefined,
+            baseHref: base,
           });
-          harvestUrlsFromText(src);
+          harvestUrlsFromText(src, base);
         }
       } else if (type === "CSSKeyframesRule") {
         keyframes.push((rule as CSSKeyframesRule).cssText);
       } else if (type === "CSSStyleRule") {
         const r = rule as CSSStyleRule;
-        if (r.style && r.style.cssText.includes("url(")) harvestUrlsFromText(r.style.cssText);
+        if (r.style && r.style.cssText.includes("url(")) harvestUrlsFromText(r.style.cssText, base);
         if (r.selectorText && r.style &&
           (isExplicitHeight(r.style.getPropertyValue("height")) ||
             isExplicitHeight(r.style.getPropertyValue("min-height")))) {
@@ -699,17 +726,20 @@ export function collectPage(opts?: { maxNodes?: number } | void): PageSnapshot {
           explicitWidthSelectors.push(r.selectorText);
         }
       } else if (type === "CSSMediaRule" || type === "CSSSupportsRule") {
-        try { readRules((rule as CSSGroupingRule).cssRules); } catch { /* ignore */ }
+        // Nested grouping rules live in the same sheet — keep the base.
+        try { readRules((rule as CSSGroupingRule).cssRules, base); } catch { /* ignore */ }
       } else if (type === "CSSImportRule") {
+        // The imported sheet is a separate file: its rules resolve against ITS url, falling back to
+        // the importing sheet's base only if the imported sheet reports none.
         const imp = rule as CSSImportRule;
-        try { if (imp.styleSheet) readRules(imp.styleSheet.cssRules); } catch { /* cross-origin */ }
+        try { if (imp.styleSheet) readRules(imp.styleSheet.cssRules, sheetBaseHref(imp.styleSheet) ?? base); } catch { /* cross-origin */ }
       }
     }
   };
 
   for (const sheet of Array.from(document.styleSheets)) {
     try {
-      readRules(sheet.cssRules);
+      readRules(sheet.cssRules, sheetBaseHref(sheet));
     } catch {
       // Cross-origin sheet — record its href so the capture layer can fetch the
       // raw text out-of-band and parse font-faces/urls from it.
@@ -746,7 +776,7 @@ export function collectPage(opts?: { maxNodes?: number } | void): PageSnapshot {
     try { sheets.push(...(sr.adoptedStyleSheets || [])); } catch { /* ignore */ }
     try { sheets.push(...Array.from(sr.styleSheets || [])); } catch { /* ignore */ }
     for (const sheet of sheets) {
-      try { readRules(sheet.cssRules); } catch { if ((sheet as CSSStyleSheet).href) cssUrlSet.add(absUrl((sheet as CSSStyleSheet).href!)); }
+      try { readRules(sheet.cssRules, sheetBaseHref(sheet)); } catch { if ((sheet as CSSStyleSheet).href) cssUrlSet.add(absUrl((sheet as CSSStyleSheet).href!)); }
     }
   }
 
diff --git a/compiler/src/generate/css.ts b/compiler/src/generate/css.ts
index 185cea1..bf9d8ac 100644
--- a/compiler/src/generate/css.ts
+++ b/compiler/src/generate/css.ts
@@ -2450,7 +2450,16 @@ function declsForViewport(
   // neither structural test detects the authored height. Trust the node's own probe.
   {
     const osz = node.sizingByVp?.[vp];
-    if (!noCollapse && !isLeaf && cs.height && cs.height !== "auto" && osz && osz.hAuto === false && osz.hFill === false) explicitHeight = true;
+    // Never trust this probe on a document-height wrapper. A root landmark (body/html/main) — or
+    // any node whose captured box IS the page's scroll height — probes hAuto:false/hFill:false as
+    // measurement noise (min-h-screen + the %-height re-measure chain at document level), not an
+    // authored height. Baking that px pins the whole page to a fixed height: combined with an
+    // `overflow:hidden` main it hard-clips any content-height drift, and it makes the layout gate's
+    // heightDelta tautologically zero (gate blindness). Such wrappers must keep flowing.
+    const isRootWrapper = tag === "body" || tag === "html" || tag === "main";
+    const isPageHeightBox = !!rootScrollHeight && !!nb && nb.height > 0 &&
+      Math.abs(nb.height - rootScrollHeight) <= rootScrollHeight * 0.02;
+    if (!noCollapse && !isLeaf && !isRootWrapper && !isPageHeightBox && cs.height && cs.height !== "auto" && osz && osz.hAuto === false && osz.hFill === false) explicitHeight = true;
   }
   if (!noCollapse && !isLeaf && cs.height && cs.height !== "auto" && nb) {
     const top = nb.y + (parseFloat(cs.paddingTop || "0") || 0) + (parseFloat(cs.borderTopWidth || "0") || 0);
@@ -3565,7 +3574,24 @@ export function collectNodeRules(ir: IR, assetMap: Map<string, string>, includeN
               continue;
             }
           } else {
-            continue;
+            // Not painted here, not display:none, not ancestor-hidden, and NOT visible at base —
+            // an item that is off-viewport/clipped at EVERY captured width, base included (the
+            // walker marks a box invisible when `bbox.x >= vpW`). A carousel slide 6–12 that lives
+            // off-screen right at 1280 (the canonical base) as well as at 375/768 lands here. It is
+            // the identical load-bearing case as the shownAtBase occupying arm above: a display:block
+            // flex item that still sets its flex track's cross-size, so freezing the base rule's
+            // canonical (desktop) geometry inflates the mobile track. Run the same occupying-box test —
+            // in-flow, unsuppressed, non-zero bbox at THIS width → fall through to the per-viewport
+            // delta so it carries this width's measured geometry. A genuinely suppressed
+            // (opacity:0 / visibility:hidden) or zero-box node keeps the current skip.
+            const bb = node.bboxByVp[b.vp];
+            const suppressed = pf(vpCs.opacity) === 0 || /^(hidden|collapse)$/.test(vpCs.visibility || "");
+            const inFlowHere = (vpCs.position || "static") === "static" || (vpCs.position || "static") === "relative";
+            if (!suppressed && inFlowHere && bb && (bb.width > 0 || bb.height > 0)) {
+              // Occupying, in-flow, off-viewport at every width — fall through to the per-viewport delta.
+            } else {
+              continue;
+            }
           }
         }
       }
diff --git a/compiler/src/infer/fonts.ts b/compiler/src/infer/fonts.ts
index 0271864..c2cfeb6 100644
--- a/compiler/src/infer/fonts.ts
+++ b/compiler/src/infer/fonts.ts
@@ -61,19 +61,14 @@ export function buildFontGraph(fontFaces: FontFace[], assetGraph: AssetGraph, so
     }
   }
 
-  const entries: FontEntry[] = [];
-  const cssBlocks: string[] = [];
-  const seen = new Set<string>();
-
-  for (const ff of fontFaces) {
-    const weight = (ff.weight || "400").trim();
-    const style = (ff.style || "normal").trim();
-    const display = (ff.display || "swap").trim();
-    const key = `${ff.family}|${weight}|${style}|${ff.unicodeRange ?? ""}`;
-    if (seen.has(key)) continue;
-    seen.add(key);
-
-    const srcs = parseSrcUrls(ff.src, sourceUrl);
+  // Resolve one face's src descriptor against the downloaded-asset graph. A face harvested from
+  // CSSOM carries the url of its owning sheet in `baseHref`; its relative src url()s must resolve
+  // against THAT, not the document, or `../media/x` clamps to the wrong path (commonly the SPA
+  // router's HTML shell). Faces parsed out-of-band already have absolute srcs baked in, so
+  // `baseHref` is absent and the document url is a harmless fallback.
+  const order = ["woff2", "woff", "truetype", "opentype", "embedded-opentype"];
+  const resolveFace = (ff: FontFace): { resolved: Array<{ localPath: string; format: string }>; dataUris: string[] } => {
+    const srcs = parseSrcUrls(ff.src, ff.baseHref || sourceUrl);
     const resolved: Array<{ localPath: string; format: string }> = [];
     const dataUris: string[] = [];
     for (const s of srcs) {
@@ -84,10 +79,47 @@ export function buildFontGraph(fontFaces: FontFace[], assetGraph: AssetGraph, so
         resolved.push({ localPath: entry.localPath, format: s.format || FORMAT_BY_EXT[ext] || "woff2" });
       }
     }
-
     // Prefer woff2 > woff > others for ordering.
-    const order = ["woff2", "woff", "truetype", "opentype", "embedded-opentype"];
     resolved.sort((a, b) => order.indexOf(a.format) - order.indexOf(b.format));
+    return { resolved, dataUris };
+  };
+
+  // Deduplicate faces by family|weight|style|unicodeRange. Two sources can supply the same face
+  // with DIFFERENT (correctly- vs wrongly-resolved) src urls — the CSSOM harvest and the css-text
+  // parse both land in `fontFaces`. Keeping the first-inserted face lets a src that resolves to
+  // nothing (a rejected impostor, or a mis-based path) win the slot, so choose validity-aware:
+  // the first face whose src resolves to a downloaded/data-uri source wins; only if NONE in the
+  // group resolves do we fall back to the first-seen face (recorded as unavailable). Ties (more
+  // than one resolving) keep insertion order — determinism preserved.
+  const chosen = new Map<string, { ff: FontFace; res: ReturnType<typeof resolveFace> }>();
+  const orderKeys: string[] = [];
+  for (const ff of fontFaces) {
+    const weight = (ff.weight || "400").trim();
+    const style = (ff.style || "normal").trim();
+    const key = `${ff.family}|${weight}|${style}|${ff.unicodeRange ?? ""}`;
+    const res = resolveFace(ff);
+    const resolves = res.resolved.length > 0 || res.dataUris.length > 0;
+    const prev = chosen.get(key);
+    if (!prev) {
+      chosen.set(key, { ff, res });
+      orderKeys.push(key);
+    } else if (resolves && !(prev.res.resolved.length > 0 || prev.res.dataUris.length > 0)) {
+      // Upgrade: the incumbent resolved to nothing, this candidate resolves — replace it in place
+      // (keeping its original emission position).
+      chosen.set(key, { ff, res });
+    }
+    // Otherwise keep the incumbent (first-resolving wins; ties hold insertion order).
+  }
+
+  const entries: FontEntry[] = [];
+  const cssBlocks: string[] = [];
+
+  for (const key of orderKeys) {
+    const { ff, res } = chosen.get(key)!;
+    const weight = (ff.weight || "400").trim();
+    const style = (ff.style || "normal").trim();
+    const display = (ff.display || "swap").trim();
+    const { resolved, dataUris } = res;
 
     if (resolved.length > 0 || dataUris.length > 0) {
       const srcParts: string[] = [];
diff --git a/compiler/test/css.test.ts b/compiler/test/css.test.ts
index 76c9468..294c97c 100644
--- a/compiler/test/css.test.ts
+++ b/compiler/test/css.test.ts
@@ -269,6 +269,31 @@ describe("generateCss hidden-node banded geometry", () => {
     assert.ok(mobile.includes("visibility:hidden"), `child should carry the hide, got: ${mobile}`);
     assert.ok(!mobile.includes("left:10px"), `ancestor-hidden child must not emit geometry, got: ${mobile}`);
   });
+
+  it("emits per-band geometry for an occupying slide off-viewport at EVERY width, base included", () => {
+    // A carousel slide 6–12: a shrink-0 flex item off-screen RIGHT at every captured width — 375,
+    // the 1280 canonical base, AND 1920 — so it is never ownHidden, never ancestor-hidden, and never
+    // visibleByVp[base]=true (the walker marks `bbox.x >= vpW` invisible). It is NOT suppressed
+    // (no opacity:0 / visibility:hidden) and stays IN FLOW, so it still sets its flex track's
+    // cross-size. Without a band the base's canonical desktop width freezes across every viewport and
+    // inflates the mobile track. The band must carry THIS width's measured geometry.
+    const slide = nodeAt("n2", "div", {
+      375: { cs: { display: "block", position: "static", opacity: "1", width: "220px" }, bbox: { x: 400, y: 0, width: 220, height: 432 }, visible: false },
+      1280: { cs: { display: "block", position: "static", opacity: "1", width: "285px" }, bbox: { x: 1500, y: 0, width: 285, height: 532 }, visible: false },
+      1920: { cs: { display: "block", position: "static", opacity: "1", width: "285px" }, bbox: { x: 2200, y: 0, width: 285, height: 532 }, visible: false },
+    });
+    const track = nodeAt("n1", "div", {
+      375: { cs: { display: "flex", position: "relative" }, bbox: { x: 0, y: 0, width: 375, height: 432 } },
+      1280: { cs: { display: "flex", position: "relative" }, bbox: { x: 0, y: 0, width: 1280, height: 532 } },
+      1920: { cs: { display: "flex", position: "relative" }, bbox: { x: 0, y: 0, width: 1920, height: 532 } },
+    }, [slide]);
+    const root = nodeAt("n0", "body", {}, [track]);
+    const css = generateCss(ir3(root), new Map());
+    assert.ok(baseRule(css, "n2").includes("width:285px"), `base bakes canonical width, got: ${baseRule(css, "n2")}`);
+    const mobile = bandRule(css, /max-width/, "n2");
+    assert.ok(mobile.includes("width:220px"), `mobile band must carry the measured 220px width, got: ${mobile}`);
+    assert.ok(!mobile.includes("display:none"), "an occupying off-viewport slide must stay in layout");
+  });
 });
 
 // Fix 1 — mobile nav chip-strip overlap. A horizontally-scrollable flex strip (overflow-x:auto
@@ -924,6 +949,42 @@ describe("generateCss authored-height kept via own probe (T3)", () => {
   });
 });
 
+// R2 — the own-probe height trust (T3) must NEVER bake a document-height wrapper. A body/html/main
+// landmark, or any node whose captured box IS the page scroll height, probes hAuto:false/hFill:false
+// as document-level re-measure noise (min-h-screen + %-height chain), not an authored height. Baking
+// it pins the page to a fixed height — which, under an overflow:hidden main, hard-clips content drift
+// and blinds the layout gate's heightDelta. Such wrappers must keep flowing (auto height).
+describe("generateCss own-probe height trust never bakes a page-height wrapper (R2)", () => {
+  const explicit = (): RawSizing => ({ wAuto: false, wFill: false, hAuto: false, hFill: false });
+  // xIr sets perViewport.scrollHeight = 800 at every viewport.
+  function pageWrapper(tag: string, h: number) {
+    // A non-leaf wrapper with an in-flow child, whose own probe reads authored (hAuto/hFill false).
+    const child = xNode("n2", "div", Object.fromEntries(XVPS.map((vp) => [vp, { cs: { display: "block", position: "static" }, bbox: { x: 0, y: 0, width: vp, height: h } }])));
+    const wrap = xNode("n1", tag, Object.fromEntries(XVPS.map((vp) => [vp, { cs: { display: "block", position: "static", height: `${h}px` }, bbox: { x: 0, y: 0, width: vp, height: h }, sizing: explicit() }])), [child]);
+    return xNode("n0", "body", Object.fromEntries(XVPS.map((vp) => [vp, { bbox: { x: 0, y: 0, width: vp, height: h } }])), [wrap]);
+  }
+
+  it("does NOT bake a <main> landmark height even when its own probe is authored", () => {
+    const css = generateCss(xIr(pageWrapper("main", 800)), new Map());
+    const all = allRulesX(css, "n1");
+    assert.ok(!/height:800px/.test(all), `main landmark must keep flowing, got: ${all}`);
+  });
+
+  it("does NOT bake a wrapper whose captured height IS the page scroll height (±2%)", () => {
+    // 792 is within 2% of the 800px scrollHeight — a page-height wrapper, not authored content.
+    const css = generateCss(xIr(pageWrapper("div", 792)), new Map());
+    const all = allRulesX(css, "n1");
+    assert.ok(!/height:792px/.test(all), `near-page-height wrapper must keep flowing, got: ${all}`);
+  });
+
+  it("still bakes a genuinely authored height well below the page height", () => {
+    // 300px is far from the 800px scrollHeight — a real authored box (the T3 case) still survives.
+    const css = generateCss(xIr(pageWrapper("div", 300)), new Map());
+    const all = allRulesX(css, "n1");
+    assert.ok(/height:300px/.test(all), `authored sub-page height must still survive, got: ${all}`);
+  });
+});
+
 // C1 (css side) — a computed `grid-template-rows: subgrid` is a STRUCTURAL keyword, not a baked px
 // regime. It must NEVER be dropped by the reflow-mode dropGridRows path (which strips px row tracks).
 describe("collectNodeRules never drops a subgrid rows template (C1)", () => {
diff --git a/compiler/test/fontIntegrity.test.ts b/compiler/test/fontIntegrity.test.ts
new file mode 100644
index 0000000..5d48d51
--- /dev/null
+++ b/compiler/test/fontIntegrity.test.ts
@@ -0,0 +1,152 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { looksLikeFontFile } from "../src/capture/capture.js";
+import { buildFontGraph } from "../src/infer/fonts.js";
+import type { FontFace } from "../src/capture/walker.js";
+import type { AssetGraph, AssetEntry } from "../src/infer/assets.js";
+
+// --- Magic-byte validator table -------------------------------------------------------------
+
+function head(tag: string, len = 64): Buffer {
+  return Buffer.concat([Buffer.from(tag, "latin1"), Buffer.alloc(Math.max(0, len - tag.length))]);
+}
+
+describe("looksLikeFontFile (font container magic)", () => {
+  it("accepts every real font-container signature", () => {
+    assert.equal(looksLikeFontFile(head("wOF2")), true, "woff2");
+    assert.equal(looksLikeFontFile(head("wOFF")), true, "woff");
+    assert.equal(looksLikeFontFile(head("OTTO")), true, "CFF OpenType (otf)");
+    assert.equal(looksLikeFontFile(head("true")), true, "TrueType 'true' sfnt");
+    assert.equal(looksLikeFontFile(head("ttcf")), true, "TrueType collection");
+    assert.equal(
+      looksLikeFontFile(Buffer.concat([Buffer.from([0x00, 0x01, 0x00, 0x00]), Buffer.alloc(60)])),
+      true,
+      "TrueType \\x00\\x01\\x00\\x00 sfnt (ttf)",
+    );
+    // EOT: 0x504C ("LP") marker at byte offset 34.
+    const eot = Buffer.alloc(80);
+    eot[34] = 0x4c;
+    eot[35] = 0x50;
+    assert.equal(looksLikeFontFile(eot), true, "eot");
+  });
+
+  it("rejects HTML/text impostor bodies (the SPA-router 200 shell)", () => {
+    assert.equal(looksLikeFontFile(Buffer.from("<!DOCTYPE html><html><head></head></html>")), false);
+    assert.equal(looksLikeFontFile(Buffer.from("<!doctype html>")), false);
+    assert.equal(looksLikeFontFile(Buffer.from("<html><body>not a font</body></html>")), false);
+    assert.equal(looksLikeFontFile(Buffer.from("<?xml version=\"1.0\"?>")), false);
+    assert.equal(looksLikeFontFile(Buffer.from("just some plain text body")), false);
+  });
+
+  it("rejects truncated/empty buffers", () => {
+    assert.equal(looksLikeFontFile(Buffer.alloc(0)), false);
+    assert.equal(looksLikeFontFile(Buffer.from([0x77, 0x4f])), false); // 2 bytes of "wO"
+  });
+});
+
+// --- Validity-aware first-insert preference in buildFontGraph -------------------------------
+
+function fontEntry(sourceUrl: string, localPath: string | null): AssetEntry {
+  return {
+    sourceUrl,
+    type: "font",
+    classification: localPath ? "downloaded" : "skipped",
+    localPath,
+    storedFile: localPath ? localPath.split("/").pop()! : null,
+    bytes: localPath ? 45_000 : 0,
+    reason: localPath ? null : "font_file_unavailable",
+    impact: null,
+    via: [],
+  };
+}
+
+function graphOf(entries: AssetEntry[]): AssetGraph {
+  const byUrl = new Map<string, AssetEntry>();
+  for (const e of entries) byUrl.set(e.sourceUrl, e);
+  return { entries, byUrl };
+}
+
+const DOC = "https://host.example/page";
+// The genuine subset lives under the css file's sibling media dir; only THIS url is downloaded.
+const GOOD_URL = "https://host.example/marketing-static/_next/static/media/good.woff2";
+// The wrongly-based (document-relative) url that the SPA router answered with HTML and that was
+// therefore rejected at store time — it never becomes a downloaded asset.
+const BAD_URL = "https://host.example/media/impostor.woff2";
+
+describe("buildFontGraph validity-aware preference (first-insert race)", () => {
+  it("prefers the face whose src resolves to a downloaded file even when it was inserted SECOND", () => {
+    const graph = graphOf([fontEntry(GOOD_URL, "/assets/cloned/fonts/good.woff2")]);
+    // Insertion order mirrors the real race: the mis-based CSSOM face lands first, the correctly
+    // based css-text face second. Only the good url is a downloaded asset.
+    const faces: FontFace[] = [
+      { family: "Gothic", weight: "400", style: "normal", src: `url("${BAD_URL}") format("woff2")` },
+      { family: "Gothic", weight: "400", style: "normal", src: `url("${GOOD_URL}") format("woff2")` },
+    ];
+    const { entries, css } = buildFontGraph(faces, graph, DOC);
+    const gothic = entries.filter((e) => e.family === "Gothic");
+    assert.equal(gothic.length, 1, "deduped to a single face");
+    assert.equal(gothic[0]!.status, "resolved");
+    assert.deepEqual(gothic[0]!.localPaths, ["/assets/cloned/fonts/good.woff2"]);
+    assert.match(css, /good\.woff2/);
+    assert.doesNotMatch(css, /impostor/);
+  });
+
+  it("keeps the FIRST face when neither resolves (fallback, ties hold order)", () => {
+    const graph = graphOf([]); // nothing downloaded
+    const faces: FontFace[] = [
+      { family: "Gothic", weight: "400", style: "normal", src: `url("${BAD_URL}") format("woff2")` },
+      { family: "Gothic", weight: "400", style: "normal", src: `url("${GOOD_URL}") format("woff2")` },
+    ];
+    const { entries } = buildFontGraph(faces, graph, DOC);
+    const gothic = entries.filter((e) => e.family === "Gothic");
+    assert.equal(gothic.length, 1);
+    assert.equal(gothic[0]!.status, "fallback");
+  });
+
+  it("keeps the FIRST resolving face when BOTH resolve (ties hold insertion order)", () => {
+    const alt = "https://host.example/marketing-static/_next/static/media/alt.woff2";
+    const graph = graphOf([
+      fontEntry(GOOD_URL, "/assets/cloned/fonts/good.woff2"),
+      fontEntry(alt, "/assets/cloned/fonts/alt.woff2"),
+    ]);
+    const faces: FontFace[] = [
+      { family: "Gothic", weight: "400", style: "normal", src: `url("${GOOD_URL}") format("woff2")` },
+      { family: "Gothic", weight: "400", style: "normal", src: `url("${alt}") format("woff2")` },
+    ];
+    const { entries } = buildFontGraph(faces, graph, DOC);
+    const gothic = entries.filter((e) => e.family === "Gothic");
+    assert.equal(gothic.length, 1);
+    assert.deepEqual(gothic[0]!.localPaths, ["/assets/cloned/fonts/good.woff2"], "first resolving wins");
+  });
+});
+
+// --- baseHref-driven relative resolution in buildFontGraph ----------------------------------
+
+describe("buildFontGraph resolves a face's relative src against its owning sheet (baseHref)", () => {
+  it("uses baseHref, not the document url, so ../media climbs from the css file", () => {
+    // The sheet lives at /marketing-static/_next/static/css/sheet.css; `../media/x` from THERE is
+    // /marketing-static/_next/static/media/x.woff2, which is what actually downloaded. Resolved
+    // against the document (/page) it would clamp to /marketing-static/_next/static/media only if
+    // the css path were the base — the point of baseHref.
+    const sheetUrl = "https://host.example/marketing-static/_next/static/css/sheet.css";
+    const resolved = "https://host.example/marketing-static/_next/static/media/x.woff2";
+    const graph = graphOf([fontEntry(resolved, "/assets/cloned/fonts/x.woff2")]);
+    const faces: FontFace[] = [
+      { family: "Gothic", weight: "400", style: "normal", src: 'url("../media/x.woff2") format("woff2")', baseHref: sheetUrl },
+    ];
+    const { entries } = buildFontGraph(faces, graph, DOC);
+    assert.equal(entries[0]!.status, "resolved");
+    assert.deepEqual(entries[0]!.localPaths, ["/assets/cloned/fonts/x.woff2"]);
+  });
+
+  it("falls back to the document url when baseHref is absent (inline <style> / out-of-band parse)", () => {
+    // An out-of-band parse bakes the absolute url into src, so document fallback is harmless.
+    const abs = "https://host.example/fonts/y.woff2";
+    const graph = graphOf([fontEntry(abs, "/assets/cloned/fonts/y.woff2")]);
+    const faces: FontFace[] = [
+      { family: "Mono", weight: "400", style: "normal", src: `url("${abs}") format("woff2")` },
+    ];
+    const { entries } = buildFontGraph(faces, graph, DOC);
+    assert.equal(entries[0]!.status, "resolved");
+  });
+});
diff --git a/compiler/test/fontUrlResolution.test.ts b/compiler/test/fontUrlResolution.test.ts
new file mode 100644
index 0000000..a57402a
--- /dev/null
+++ b/compiler/test/fontUrlResolution.test.ts
@@ -0,0 +1,136 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { createServer, type Server } from "node:http";
+import { chromium, type Browser, type Page } from "playwright";
+import { collectPage, type PageSnapshot } from "../src/capture/walker.js";
+
+// A relative url() inside a stylesheet must resolve against THAT sheet's url, not the document.
+// These tests serve real CSS files at a NESTED path so `../media/x` climbs differently depending
+// on the base: against the css file it lands under the nested dir, against the page it clamps to
+// the site root. We assert the harvested url (cssUrls) and the face's baseHref carry the sheet
+// base — the exact fix for the "HTML saved as woff2" font-materialization cluster.
+
+// The nested layout mirrors a real bundler output:
+//   /page                                      (document)
+//   /marketing-static/_next/static/css/x.css   (external sheet)
+//   /marketing-static/_next/static/media/f.woff2  ← where ../media/f.woff2 SHOULD resolve
+const CSS_PATH = "/marketing-static/_next/static/css/x.css";
+const EXPECTED_MEDIA = "/marketing-static/_next/static/media/f.woff2";
+// The WRONG (document-relative) resolution the old code produced:
+const WRONG_MEDIA = "/media/f.woff2";
+
+function serveText(body: string, type: string, res: import("node:http").ServerResponse): void {
+  res.writeHead(200, { "content-type": type });
+  res.end(body);
+}
+
+describe("font url() resolution against the owning stylesheet", () => {
+  let browser: Browser;
+  let page: Page;
+  let server: Server;
+  let origin = "";
+
+  before(async () => {
+    server = createServer((req, res) => {
+      const url = (req.url || "/").split("?")[0];
+      if (url === "/page") {
+        return serveText(
+          `<!doctype html><html><head><link rel="stylesheet" href="${CSS_PATH}"></head><body><p>hi</p></body></html>`,
+          "text/html",
+          res,
+        );
+      }
+      if (url === "/import-host") {
+        // A same-origin sheet that @imports the nested sheet; the imported sheet's own url must be
+        // the base for its faces, not the host sheet or the page.
+        return serveText(
+          `<!doctype html><html><head><link rel="stylesheet" href="/top.css"></head><body><p>hi</p></body></html>`,
+          "text/html",
+          res,
+        );
+      }
+      if (url === "/top.css") {
+        return serveText(`@import url("${CSS_PATH}");`, "text/css", res);
+      }
+      if (url === CSS_PATH) {
+        return serveText(
+          `@font-face{font-family:"Gothic";font-style:normal;font-weight:400;` +
+            `src:url("../media/f.woff2") format("woff2");}` +
+            `.hero{background:url("../media/bg.png")}`,
+          "text/css",
+          res,
+        );
+      }
+      res.writeHead(404).end();
+    });
+    await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));
+    const addr = server.address();
+    if (addr && typeof addr === "object") origin = `http://127.0.0.1:${addr.port}`;
+    browser = await chromium.launch();
+    page = await browser.newPage();
+  });
+
+  after(async () => {
+    await browser.close();
+    await new Promise<void>((r) => server.close(() => r()));
+  });
+
+  const snap = async (path: string): Promise<PageSnapshot> => {
+    await page.goto(`${origin}${path}`, { waitUntil: "networkidle" });
+    await page.evaluate("globalThis.__name = globalThis.__name || ((fn) => fn);");
+    return page.evaluate(collectPage) as Promise<PageSnapshot>;
+  };
+
+  it("resolves a font-face src against the external sheet's url, not the document", async () => {
+    const s = await snap("/page");
+    assert.ok(
+      s.cssUrls.includes(`${origin}${EXPECTED_MEDIA}`),
+      `expected sheet-relative ${EXPECTED_MEDIA} in cssUrls, got ${JSON.stringify(s.cssUrls)}`,
+    );
+    assert.ok(
+      !s.cssUrls.includes(`${origin}${WRONG_MEDIA}`),
+      "must NOT produce the document-relative (wrong) resolution",
+    );
+    const face = s.fontFaces.find((f) => f.family === "Gothic");
+    assert.ok(face, "font face captured");
+    assert.equal(face!.baseHref, `${origin}${CSS_PATH}`, "face carries its owning sheet's base");
+  });
+
+  it("resolves ordinary style-rule url() against the sheet too", async () => {
+    const s = await snap("/page");
+    assert.ok(
+      s.cssUrls.includes(`${origin}/marketing-static/_next/static/media/bg.png`),
+      `expected sheet-relative bg.png, got ${JSON.stringify(s.cssUrls)}`,
+    );
+  });
+
+  it("resolves an @import-nested sheet's face against the IMPORTED sheet's url", async () => {
+    const s = await snap("/import-host");
+    // top.css @imports x.css; the face lives in x.css, so ../media resolves from x.css's dir.
+    assert.ok(
+      s.cssUrls.includes(`${origin}${EXPECTED_MEDIA}`),
+      `@import base must be the imported sheet, got ${JSON.stringify(s.cssUrls)}`,
+    );
+    const face = s.fontFaces.find((f) => f.family === "Gothic");
+    assert.equal(face?.baseHref, `${origin}${CSS_PATH}`);
+  });
+
+  it("falls back to the document base for an inline <style> (no sheet href)", async () => {
+    await page.goto(`${origin}/page`, { waitUntil: "networkidle" });
+    await page.evaluate("globalThis.__name = globalThis.__name || ((fn) => fn);");
+    await page.evaluate(() => {
+      const st = document.createElement("style");
+      st.textContent =
+        '@font-face{font-family:"Inline";src:url("./inline/g.woff2") format("woff2")}';
+      document.head.appendChild(st);
+    });
+    const s = (await page.evaluate(collectPage)) as PageSnapshot;
+    // document base is /page → ./inline/g.woff2 resolves to /inline/g.woff2 (page-relative).
+    assert.ok(
+      s.cssUrls.includes(`${origin}/inline/g.woff2`),
+      `inline <style> resolves against the document, got ${JSON.stringify(s.cssUrls)}`,
+    );
+    const face = s.fontFaces.find((f) => f.family === "Inline");
+    assert.equal(face?.baseHref, undefined, "inline face has no sheet href");
+  });
+});

From ec4e4397ccb8457cffbe58fb88dd7b81fd196b7f Mon Sep 17 00:00:00 2001
From: Samraaj Bath <samraaj100@gmail.com>
Date: Sat, 4 Jul 2026 04:55:07 -0700
Subject: [PATCH 16/24] Trust geometry-corroborated authored fixed sizes; guard
 aspect-law width transfer

- Authored fixed h-/w- utilities from the source cascade, when the
  captured geometry corroborates them, suppress fill/flow re-derivation
  and emit as captured computed px per band (root-font-size independent) -
  fixes logo tiles collapsing to h-full and replaced-element sizes
  dropping to intrinsic
- aspectHeightLaw rejects ratios where the CSS aspect-ratio/max-height
  width transfer would clamp width below the captured box, falling back to
  per-band explicit dimensions

419 tests pass (4 new, each verified discriminating), typecheck clean,
double-regen byte-identical.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 compiler/src/generate/css.ts       | 126 +++++++++++++++++++++++++++--
 compiler/src/generate/tailwind.ts  |  68 +++++++++++++++-
 compiler/test/bandingFixes.test.ts |  39 +++++++++
 compiler/test/css.test.ts          |  94 +++++++++++++++++++++
 4 files changed, 318 insertions(+), 9 deletions(-)

diff --git a/compiler/src/generate/css.ts b/compiler/src/generate/css.ts
index bf9d8ac..f256e44 100644
--- a/compiler/src/generate/css.ts
+++ b/compiler/src/generate/css.ts
@@ -882,7 +882,15 @@ function aspectHeightLaw(node: IRNode, viewports: number[]): Record<number, stri
     let chosen: { value: string; ratio: number } | undefined;
     for (const r of ordered) {
       const predicted = Math.min(s.w / r.ratio, s.maxH);
-      if (Math.abs(predicted - s.h) <= Math.max(1.5, 0.01 * s.h)) { chosen = r; break; }
+      if (Math.abs(predicted - s.h) > Math.max(1.5, 0.01 * s.h)) continue;
+      // Aspect-ratio + max-height also transfers into a max-WIDTH: per CSS transferred sizing, a box
+      // with `aspect-ratio:R` and `max-height:M` cannot exceed `R × M` wide (the height cap back-computes
+      // a width cap). The height-only check above accepts any ratio that makes min(w/R, M) ≈ h at a
+      // clamped viewport, but a ratio whose transferred max-width (R × M) is narrower than the measured
+      // box would clamp the clone's width below the source (a 1.66:1 box forced square to its 420px cap).
+      // Require the measured width to fit under the transferred cap at every clamped sample.
+      if (Number.isFinite(s.maxH) && s.w > r.ratio * s.maxH + Math.max(1.5, 0.01 * s.w)) continue;
+      chosen = r; break;
     }
     if (!chosen) return null;
     out[s.vp] = chosen.value;
@@ -1169,6 +1177,100 @@ function sourceFixedSizeIntent(node: IRNode): boolean {
   return /(?:^|\s)(?:[a-z0-9-]+:)*size-(?!fit(?:\s|$))\S+/.test(node.srcClass || "");
 }
 
+// An authored, definite length unit (px/rem/em/…) — the same predicate the capture-side probe uses to
+// call a dimension "load-bearing". Rejects auto/%/keywords and viewport/container units (those are
+// fluid laws the width/height passes already recover); a bare number (`0`) is not definite. Used to
+// read the arbitrary-value inner of a `h-[…]` / `w-[…]` source utility.
+function isDefiniteAuthoredLength(inner: string): boolean {
+  const v = inner.trim().toLowerCase();
+  if (!v) return false;
+  if (/^(auto|min-content|max-content|fit-content|inherit|initial|unset|revert)$/.test(v)) return false;
+  if (/%|vw|vh|vmin|vmax|svw|lvw|dvw|svh|lvh|dvh|\bfr\b/.test(v)) return false;
+  return /(?:^|[\s(*/+-])[\d.]+(?:px|rem|em|cm|mm|in|pt|pc|ex|ch|q)\b/.test(v);
+}
+
+/** Does the SOURCE class author an explicit, definite fixed height on this axis — `h-[<len>]`,
+ *  `min-h-[<len>]`, or the token forms (`h-<n>`, `h-px`) — at one or more breakpoints, corroborated by
+ *  geometry? This is the emission-side twin of the capture probe's authored-height guard: a banded
+ *  authored fixed height (`h-[4rem] sm:h-[4.5rem] md:h-[6.25rem]`) can still probe hFill/hAuto when the
+ *  box is a grid/flex item whose fill child (or stretched track) reproduces the box height — the
+ *  fill↔content cycle — so the probe alone would drop the baked band to `h-full`/auto. When the source
+ *  authors a definite height AND every painted viewport has a definite computed height matching its
+ *  bbox (the authored value actually resolved to that px), trust the baked per-band px. Geometry
+ *  corroboration keeps this from firing on a fluid/percentage box that merely mentions a fixed h-token
+ *  under an inactive variant. */
+function sourceFixedHeightIntent(node: IRNode, viewports: number[]): boolean {
+  if (REPLACED.has(node.tag) || node.tag === "canvas" || node.tag.includes("-")) return false;
+  if (!authorsFixedAxis(node.srcClass, "h")) return false;
+  return fixedAxisGeometryHolds(node, "h", viewports);
+}
+
+/** The WIDTH twin of sourceFixedHeightIntent: the source authors a definite `w-[<len>]`/`min-w-[<len>]`
+ *  (or token) width, corroborated by a definite computed width == bbox at every painted viewport. A
+ *  banded authored fixed width on a shrink-0 item (a testimonial avatar `h-[2.5rem] w-[2.5rem] shrink-0`
+ *  whose img child fills it) probes wAuto/wFill and would otherwise be dropped, collapsing the box to
+ *  its child's intrinsic size. Trust the authored fixed width. */
+function sourceFixedWidthIntent(node: IRNode, viewports: number[]): boolean {
+  if (REPLACED.has(node.tag) || node.tag === "canvas" || node.tag.includes("-")) return false;
+  if (!authorsFixedAxis(node.srcClass, "w")) return false;
+  return fixedAxisGeometryHolds(node, "w", viewports);
+}
+
+// True when the source class authors a definite fixed length on the given axis at any breakpoint:
+// `h-[4rem]` / `min-w-[24px]` (arbitrary), `h-px`, or a numeric token `w-24` (Tailwind's spacing scale
+// is a fixed rem length). `full`/`auto`/`screen`/fraction/`min`/`max`/`fit`/`svh`… tokens are fluid and
+// excluded. Variant-prefixed forms count (banded authored heights), matching the source-intent parser.
+function authorsFixedAxis(srcClass: string | undefined, axis: "h" | "w"): boolean {
+  if (!srcClass) return false;
+  for (const raw of srcClass.split(/\s+/).filter(Boolean)) {
+    const colon = lastTopLevelColon(raw);
+    const core = colon >= 0 ? raw.slice(colon + 1) : raw;
+    const m = new RegExp(`^(?:min-)?${axis}-(.+)$`).exec(core);
+    if (!m) continue;
+    const val = m[1]!;
+    if (val.startsWith("[") && val.endsWith("]")) {
+      if (isDefiniteAuthoredLength(val.slice(1, -1))) return true;
+      continue;
+    }
+    if (val === "px") return true;                 // 1px
+    if (/^\d+(?:\.\d+)?$/.test(val)) return true;   // spacing-scale token (fixed rem)
+  }
+  return false;
+}
+
+// Index of the variant/core separating colon at bracket depth 0 (so `h-[calc(1px:2)]` is not split on
+// an interior colon), mirroring parseSourceClass in the tailwind emitter.
+function lastTopLevelColon(raw: string): number {
+  let depth = 0, last = -1;
+  for (let i = 0; i < raw.length; i++) {
+    const ch = raw[i]!;
+    if (ch === "[" || ch === "(") depth++;
+    else if (ch === "]" || ch === ")") depth = Math.max(0, depth - 1);
+    else if (ch === ":" && depth === 0) last = i;
+  }
+  return last;
+}
+
+// Geometry corroboration for an authored fixed height/width: at EVERY painted viewport the node has a
+// definite (px, non-auto) computed value on the axis that equals its measured bbox extent. This proves
+// the authored fixed length actually resolved to the captured box (so the baked per-band px is the
+// authored value), not a fluid/percentage box that merely carries a fixed token under an inactive
+// variant. Requires ≥1 painted sample.
+function fixedAxisGeometryHolds(node: IRNode, axis: "h" | "w", viewports: number[]): boolean {
+  let painted = 0;
+  for (const vp of viewports) {
+    const cs = node.computedByVp[vp]; const nb = node.bboxByVp[vp];
+    if (!cs || !nb || !node.visibleByVp[vp] || (cs.display || "") === "none") continue;
+    const val = axis === "h" ? cs.height : cs.width;
+    const ext = axis === "h" ? nb.height : nb.width;
+    if (!val || val === "auto" || !/px$/.test(val)) return false;
+    if (!(ext > 0)) return false;
+    if (Math.abs(pf(val) - ext) > Math.max(1.5, 0.01 * ext)) return false;
+    painted++;
+  }
+  return painted >= 1;
+}
+
 const ABSOLUTE_MEDIA_FILL_TAGS = new Set(["img", "picture", "video"]);
 
 /** An absolutely-positioned media layer authored as a full-cover background: `position:absolute;
@@ -2352,6 +2454,7 @@ function declsForViewport(
   dropViewportMaxWidth = false,
   nowrapText = false,
   keepIdentityTransform = false,
+  forceHeight = false,
 ): Map<string, string> {
   const cs = node.computedByVp[vp];
   const out = new Map<string, string>();
@@ -2439,7 +2542,11 @@ function declsForViewport(
   // absolutely-positioned children). Without emitting it the block collapses to
   // its content in the clone. Content-filled blocks stay auto so margin
   // collapsing is preserved.
-  let explicitHeight = false;
+  // `forceHeight`: the caller proved this node authors a geometry-corroborated fixed height
+  // (sourceFixedHeightIntent) but the box's own content extent can't re-derive it (a shrink-0 box whose
+  // child fills it — the avatar case), so none of the structural explicit-height tests below fire. Trust
+  // the authored value and emit the baked per-band px.
+  let explicitHeight = forceHeight;
   const nb = node.bboxByVp[vp];
   // Probe ground truth, emission twin of the heightFlows keep (see the hAuto/hFill guard there):
   // the sizing probe proved height:auto did NOT reproduce this box (hAuto:false) AND it is not a
@@ -3295,9 +3402,15 @@ export function collectNodeRules(ir: IR, assetMap: Map<string, string>, includeN
     // parent, varies) OR the sizing probe measured that height:100% reproduces and auto does not
     // (heightProbeFills — direct ground truth, also catches constant fillers; inert pre-probe captures).
     const sourceFixedSize = !isContents && sourceFixedSizeIntent(node);
+    // Authored, geometry-corroborated fixed height/width on this node's own source class (banded or
+    // not). These break the fill↔content probe cycle that otherwise drops a banded authored height to
+    // `h-full` (logo tiles) or a shrink-0 box's authored width/height to auto (testimonial avatars):
+    // trust the baked per-band px the capture measured, exactly as the capture-side authored guard does.
+    const sourceFixedHeight = !isContents && sourceFixedHeightIntent(node, sampleVps);
+    const sourceFixedWidth = !isContents && sourceFixedWidthIntent(node, sampleVps);
     const mediaCover = !isContents && absoluteMediaCoversParent(node, parentNode, sampleVps);
     const absHeightFill = !isContents && absoluteHeightFill(node, parentNode, sampleVps);
-    const buttonFixedHeight = !isContents && (fixedHeightButtonLike(node, sampleVps) || sourceFixedSize);
+    const buttonFixedHeight = !isContents && (fixedHeightButtonLike(node, sampleVps) || sourceFixedSize || sourceFixedHeight);
     const heightFill = !isContents && !buttonFixedHeight && (isHeightFill(node, parentNode, parentDefiniteHeight, sampleVps) || absHeightFill || mediaCover || heightProbeFills(node, sampleVps));
     // This node's own height-drop decision, computed here so it can also feed childDefiniteHeight (a
     // height we drop becomes `auto` → does not confer a definite containing block). Same OR'd signals
@@ -3356,7 +3469,7 @@ export function collectNodeRules(ir: IR, assetMap: Map<string, string>, includeN
     const fillCap = !isContents ? fillsToCapWidth(node, parentNode, sampleVps) : null;
     // A width that leaves interior free space positions its children (auto margins / justify) — it's
     // load-bearing, so the content-sized branches below must NOT drop it (would kill the spacing).
-    const buttonFixedWidth = !isContents && (fixedWidthButtonLike(node, sampleVps) || sourceFixedSize);
+    const buttonFixedWidth = !isContents && (fixedWidthButtonLike(node, sampleVps) || sourceFixedSize || sourceFixedWidth);
     const lockWidth = !isContents && !fillCap && (hasInteriorFreeSpaceX(node, sampleVps) || buttonFixedWidth);
     // Ground-truth sizing probe is the primary signal after authored capped fills:
     // `width:100%; max-width:X` can look "auto" in a clone probe because the retained cap still
@@ -3374,6 +3487,7 @@ export function collectNodeRules(ir: IR, assetMap: Map<string, string>, includeN
     const mixedFill = (!lockWidth && !isContents && !percentVp) ? mixedFillByVp(node, parentNode, sampleVps) : null;
     const widthPlan: WidthPlan =
       fillCap ? { kind: "fillcap", cap: fillCap }
+      : sourceFixedWidth ? { kind: "fixed" }
       : sourceFixedSize ? inferred.plan
       : circularSlide ? { kind: "fixed" }
       : fullWidthSlide ? { kind: "basisFull" }
@@ -3485,7 +3599,7 @@ export function collectNodeRules(ir: IR, assetMap: Map<string, string>, includeN
     // gated to a breakpoint owns the transform only where it runs, but freezes a mid-scroll offset
     // at the OTHER bands — suppress those frozen deltas at every width).
     const animOwned = animOwnedProps(node, [baseVp, ...bands.map((b) => b.vp)]);
-    const baseDecls = finalizeDecls(declsForViewport(node, parentNode?.computedByVp[baseVp], baseVp, assetMap, centeredBase, colorVar, ir.doc.perViewport[baseVp]?.scrollHeight, widthPlan, gridColsByVp?.get(baseVp), gridRowsByVp?.get(baseVp), flowH, dropInsets, leftPct, heightFill, geometry, dropGridRows, dropViewportMaxWidth, nowrapText, keepIdentityTransform), tokenResolver);
+    const baseDecls = finalizeDecls(declsForViewport(node, parentNode?.computedByVp[baseVp], baseVp, assetMap, centeredBase, colorVar, ir.doc.perViewport[baseVp]?.scrollHeight, widthPlan, gridColsByVp?.get(baseVp), gridRowsByVp?.get(baseVp), flowH, dropInsets, leftPct, heightFill, geometry, dropGridRows, dropViewportMaxWidth, nowrapText, keepIdentityTransform, sourceFixedHeight), tokenResolver);
     const nr: NodeRule = { base: baseDecls, bands: [] };
 
     // Per-band overrides (delta vs base), using the parent's value AT THAT viewport.
@@ -3596,7 +3710,7 @@ export function collectNodeRules(ir: IR, assetMap: Map<string, string>, includeN
         }
       }
       const centeredVp = stableCenter || (layoutParent ? centeredAtVp(node, layoutParent, b.vp) : false);
-      const vpDecls = finalizeDecls(declsForViewport(node, parentNode?.computedByVp[b.vp], b.vp, assetMap, centeredVp, colorVar, ir.doc.perViewport[b.vp]?.scrollHeight, widthPlan, gridColsByVp?.get(b.vp), gridRowsByVp?.get(b.vp), flowH, dropInsets, leftPct, heightFill, geometry, dropGridRows, dropViewportMaxWidth, nowrapText, keepIdentityTransform), tokenResolver);
+      const vpDecls = finalizeDecls(declsForViewport(node, parentNode?.computedByVp[b.vp], b.vp, assetMap, centeredVp, colorVar, ir.doc.perViewport[b.vp]?.scrollHeight, widthPlan, gridColsByVp?.get(b.vp), gridRowsByVp?.get(b.vp), flowH, dropInsets, leftPct, heightFill, geometry, dropGridRows, dropViewportMaxWidth, nowrapText, keepIdentityTransform, sourceFixedHeight), tokenResolver);
       const delta = new Map<string, string>();
       for (const [k, v] of vpDecls) if (baseDecls.get(k) !== v) delta.set(k, v);
       for (const [k] of baseDecls) if (!vpDecls.has(k)) delta.set(k, resetValue(k));
diff --git a/compiler/src/generate/tailwind.ts b/compiler/src/generate/tailwind.ts
index 23381b4..a300bed 100644
--- a/compiler/src/generate/tailwind.ts
+++ b/compiler/src/generate/tailwind.ts
@@ -762,6 +762,57 @@ function sourceFluidLengthSuffix(suffix: string): boolean {
   return /(%|vw|vh|svw|lvw|dvw|svh|lvh|dvh|fr|min-content|max-content|fit-content)/.test(inner);
 }
 
+// A FIXED, definite authored length suffix on a `w-`/`h-` utility: an arbitrary `[<px|rem|em|…>]`, the
+// `px` token (1px), or a numeric spacing-scale token (`24`, `2.5` → fixed rem). Unlike
+// sourceFluidLengthSuffix these do NOT re-derive from the container, so the source-intent pass must
+// re-emit them as the CAPTURED computed px (the clone's root font-size may differ from the source's, so
+// echoing `h-[4rem]` verbatim would mis-size), and only where geometry corroborates the resolved box.
+function sourceFixedLengthSuffix(suffix: string): boolean {
+  const inner = sourceArbitraryInner(suffix);
+  if (inner !== null) {
+    const v = inner.trim().toLowerCase();
+    if (/^var\(/.test(v)) return false;                                  // handled by the var-length path
+    if (/%|vw|vh|vmin|vmax|svw|lvw|dvw|svh|lvh|dvh|\bfr\b|min-content|max-content|fit-content/.test(v)) return false;
+    return /(?:^|[\s(*/+-])[\d.]+(?:px|rem|em|cm|mm|in|pt|pc|ex|ch|q)\b/.test(v);
+  }
+  if (suffix === "px") return true;
+  return /^\d+(?:\.\d+)?$/.test(suffix);
+}
+
+// A `w-`/`h-` utility carrying a fixed authored length (as recognised by sourceFixedLengthSuffix).
+function isFixedLengthUtil(util: string): boolean {
+  const m = /^([wh])-(.+)$/.exec(util);
+  return !!m && sourceFixedLengthSuffix(m[2]!);
+}
+
+// The captured computed px on this axis is definite and matches the measured bbox — i.e. the authored
+// fixed length resolved to the box the capture recorded. Geometry corroboration for a fixed w/h util.
+function fixedLengthResolvesToBox(node: IRNode, axis: "w" | "h", vp: number): boolean {
+  const cs = node.computedByVp[vp]; const b = node.bboxByVp[vp];
+  if (!cs || !b) return false;
+  const val = axis === "h" ? cs.height : cs.width;
+  const ext = axis === "h" ? b.height : b.width;
+  if (!val || val === "auto" || !/px$/.test(val)) return false;
+  if (!(ext > 0)) return false;
+  return Math.abs(pf(val) - ext) <= Math.max(1.5, 0.01 * ext);
+}
+
+// Rewrite a fixed-length `w-`/`h-` source utility to the node's CAPTURED computed px at a viewport,
+// preserving any variant prefix. `h-[4rem]` → `h-[60px]` (the source resolved 4rem against a 15px root;
+// the clone's root may differ, so bake the measured px). Returns the utility unchanged when it is not a
+// fixed-length util or the computed px is unavailable.
+function fixedLengthUtilAsPx(util: string, node: IRNode, vp: number): string {
+  const m = VARIANT_PREFIX.exec(util);
+  const prefix = m ? m[1]! : "";
+  const core = m ? m[2]! : util;
+  const sm = /^([wh])-(.+)$/.exec(core);
+  if (!sm || !sourceFixedLengthSuffix(sm[2]!)) return util;
+  const val = sm[1] === "h" ? node.computedByVp[vp]?.height : node.computedByVp[vp]?.width;
+  if (!val || !/px$/.test(val)) return util;
+  const px = Math.round(pf(val) * 100) / 100;
+  return `${prefix}${sm[1]}-[${px}px]`;
+}
+
 function sourceAspectUtility(core: string): string | null {
   let m = /^aspect-(\d+)\/(\d+)-box$/.exec(core);
   if (m) return m[1] === m[2] ? "aspect-square" : `aspect-[${m[1]}/${m[2]}]`;
@@ -793,7 +844,7 @@ function sourceAxisForCore(core0: string): { axis: SourceAxis; utility: string }
   const maxH = /^max-h-(.+)$/.exec(core);
   if (maxH && sourceFluidLengthSuffix(maxH[1]!)) return { axis: "max-h", utility: core };
   const size = /^([wh])-(.+)$/.exec(core);
-  if (size && sourceFluidLengthSuffix(size[2]!)) return { axis: size[1] as SourceAxis, utility: core };
+  if (size && (sourceFluidLengthSuffix(size[2]!) || sourceFixedLengthSuffix(size[2]!))) return { axis: size[1] as SourceAxis, utility: core };
   return null;
 }
 
@@ -957,6 +1008,12 @@ function sourceAxisCompatible(node: IRNode, parent: IRNode | undefined, axis: So
       if (axis === "h" && v === "h-full") return !!s?.hFill;
       if (axis === "h" && v === "h-auto") return !!s?.hAuto;
       if (axis === "h" && v && sourceVarName(v)) return /px$/.test(node.computedByVp[vp]?.height || "");
+      // A FIXED authored length (`h-[4rem]`, `w-24`, `h-px`) — the source-intent pass will re-emit it as
+      // the captured computed px. Compatible when that px is definite and equals the measured bbox extent
+      // at this viewport (the authored length actually resolved to the captured box). This recovers a
+      // banded authored fixed height/width the sizing probe dropped through the fill↔content cycle
+      // (h-full) or the content/fill drop (auto), without depending on the clone's root font-size.
+      if (v && isFixedLengthUtil(v)) return fixedLengthResolvesToBox(node, axis, vp);
       return false;
     });
   }
@@ -1023,13 +1080,18 @@ function sourceIntentUtilities(node: IRNode, parent: IRNode | undefined, viewpor
       continue;
     }
     if (!sourceAxisCompatible(node, parent, axis, byVp, viewports)) continue;
-    const base = byVp.get(canonical)!;
+    // A fixed-length w/h axis re-emits the CAPTURED computed px per band (root-font-size independent),
+    // not the source rem token; every other axis keeps its authored utility verbatim.
+    const asEmit = (vp: number): string =>
+      (axis === "w" || axis === "h") && isFixedLengthUtil(byVp.get(vp)!)
+        ? fixedLengthUtilAsPx(byVp.get(vp)!, node, vp) : byVp.get(vp)!;
+    const base = asEmit(canonical);
     axes.add(axis);
     if (axis === "aspect") axes.add("grid-rows");
     utilities.push(base);
     for (const b of bands) {
       if (!b.media) continue;
-      const v = byVp.get(b.vp)!;
+      const v = asEmit(b.vp);
       if (v !== base) utilities.push(prefixFor(b.media) + v);
     }
     css.push(...sourceIntentVarCss(node, axis, byVp, viewports, canonical));
diff --git a/compiler/test/bandingFixes.test.ts b/compiler/test/bandingFixes.test.ts
index 1578ab8..8689db5 100644
--- a/compiler/test/bandingFixes.test.ts
+++ b/compiler/test/bandingFixes.test.ts
@@ -97,3 +97,42 @@ describe("buildTailwind partial-coverage subgrid intent (C1)", () => {
     assert.ok(/grid-rows-subgrid/.test(cls), `subgrid must survive the partial-intent path, got class: "${cls}"`);
   });
 });
+
+// FIX 1 (source-intent side) — an authored banded FIXED height (`h-[4rem] md:h-[6.25rem]`) must be
+// recoverable through source intent even though sourceFluidLengthSuffix rejects fixed rem/px lengths.
+// The recovered value is re-emitted as the CAPTURED computed px (root-font-size independent), and the
+// generated `h-full`/`h-auto` on that axis is dropped in its favour.
+describe("buildTailwind recovers authored banded fixed height as computed px (FIX 1)", () => {
+  // A per-vp node with distinct computed height + matching bbox on each axis, so geometry corroborates.
+  function fixedHNode(id: string, tag: string, hByVp: Record<number, number>, srcClass: string): IRNode {
+    const computedByVp: Record<number, StyleMap> = {};
+    const bboxByVp: Record<number, BBox> = {};
+    const visibleByVp: Record<number, boolean> = {};
+    for (const vp of VPS) {
+      computedByVp[vp] = computed({ display: "flex", height: `${hByVp[vp]}px` });
+      bboxByVp[vp] = { x: 0, y: 0, width: vp, height: hByVp[vp]! };
+      visibleByVp[vp] = true;
+    }
+    const n: IRNode = { id, tag, attrs: {}, visibleByVp, bboxByVp, computedByVp, children: [] };
+    n.srcClass = srcClass;
+    // Probe reads the fill↔content cycle (a grid/flex item whose child fills it): hAuto:false but
+    // hFill:true, so the generator would otherwise emit h-full. Source intent must still recover.
+    n.sizingByVp = Object.fromEntries(VPS.map((vp) => [vp, { wAuto: false, wFill: true, hAuto: false, hFill: true }]));
+    return n;
+  }
+
+  it("emits banded computed px (h-[60px]/h-[100px]) and no h-full", () => {
+    // Source authors `h-[4rem]` (base) and `md:h-[6.25rem]`; the source root is 15px so 4rem→60px @375
+    // and 6.25rem→100px @1280. Emitted as px so the clone's root font-size can't mis-size it.
+    const el = fixedHNode("n1", "div", { 375: 60, 1280: 100 }, "flex h-[4rem] w-full md:h-[6.25rem]");
+    const root = pvNode("n0", "body", { 375: {}, 1280: {} }, [el]);
+    const tw = buildTailwind(irWith(root), new Map());
+    const cls = tw.classOf.get("n1") || "";
+    assert.ok(!/\bh-full\b/.test(cls), `authored fixed height must not stay h-full, got class: "${cls}"`);
+    // The captured px must appear (as an arbitrary px value or a clean rem token equivalent). Accept the
+    // px form or its 16px-root rem equivalent (100px→6.25rem, 60px→3.75rem) since the pretty-printer may
+    // fold clean px back to rem — both resolve to the captured px at the clone's 16px root.
+    assert.ok(/h-\[100px\]|h-\[6\.25rem\]/.test(cls), `desktop height (100px/6.25rem@16root) must appear, got class: "${cls}"`);
+    assert.ok(/h-\[60px\]|h-\[3\.75rem\]/.test(cls), `mobile height (60px/3.75rem@16root) must appear, got class: "${cls}"`);
+  });
+});
diff --git a/compiler/test/css.test.ts b/compiler/test/css.test.ts
index 294c97c..115fd86 100644
--- a/compiler/test/css.test.ts
+++ b/compiler/test/css.test.ts
@@ -985,6 +985,100 @@ describe("generateCss own-probe height trust never bakes a page-height wrapper (
   });
 });
 
+// FIX 1 — a banded AUTHORED fixed height (`h-[4rem] sm:h-[4.5rem] md:h-[6.25rem]`) on a grid/flex item
+// whose fill child reproduces the box height (the fill↔content cycle: hFill:true) must NOT collapse to
+// `height:100%`. The source authors a definite per-band height, geometry corroborates it (computed px ==
+// bbox at every vp), so the baked per-band px must survive instead of the probe's circular fill verdict.
+describe("generateCss authored banded fixed height survives the fill cycle (FIX 1)", () => {
+  const cycle = (): RawSizing => ({ wAuto: false, wFill: true, hAuto: false, hFill: true });
+  function tile(): IRNode {
+    // Inner filler: height:100% child (the fill side of the cycle).
+    const inner = xNode("n2", "span", Object.fromEntries(XVPS.map((vp) => [vp, {
+      cs: { display: "block", position: "static", height: "100%" },
+      bbox: { x: 0, y: 0, width: 100, height: vp === 375 ? 60 : vp === 768 ? 93.75 : 100 },
+    }])));
+    const t = xNode("n1", "div", {
+      375: { cs: { display: "flex", position: "static", height: "60px" }, bbox: { x: 0, y: 0, width: 100, height: 60 }, sizing: cycle() },
+      768: { cs: { display: "flex", position: "static", height: "93.75px" }, bbox: { x: 0, y: 0, width: 100, height: 93.75 }, sizing: cycle() },
+      1280: { cs: { display: "flex", position: "static", height: "100px" }, bbox: { x: 0, y: 0, width: 100, height: 100 }, sizing: cycle() },
+    }, [inner]);
+    t.srcClass = "px-2 flex h-[4rem] w-full items-center justify-center sm:h-[4.5rem] md:h-[6.25rem]";
+    // Grid parent that confers a definite height at every band, so isHeightFill/heightProbeFills would
+    // otherwise drop the tile to h-full.
+    return xNode("n0", "div", {
+      375: { cs: { display: "grid", position: "static", height: "60px" }, bbox: { x: 0, y: 0, width: 375, height: 60 } },
+      768: { cs: { display: "grid", position: "static", height: "93.75px" }, bbox: { x: 0, y: 0, width: 768, height: 93.75 } },
+      1280: { cs: { display: "grid", position: "static", height: "100px" }, bbox: { x: 0, y: 0, width: 1280, height: 100 } },
+    }, [t]);
+  }
+
+  it("keeps the baked per-band px height and never emits height:100%", () => {
+    const css = generateCss(xIr(tile()), new Map());
+    const all = allRulesX(css, "n1");
+    assert.ok(!/height:100%/.test(all), `authored fixed-height tile must not collapse to h-full, got: ${all}`);
+    assert.ok(/height:60px/.test(all), `375 band height (60px) must survive, got: ${all}`);
+    assert.ok(/height:93\.75px/.test(all), `768 band height (93.75px) must survive, got: ${all}`);
+    assert.ok(/height:100px/.test(all), `desktop band height (100px) must survive, got: ${all}`);
+  });
+});
+
+// FIX 3 — a testimonial-avatar wrapper authors a fixed square (`h-[2.5rem] w-[2.5rem] shrink-0`) whose
+// img child fills it, so the sizing probe reads hAuto/wAuto:true and would drop BOTH dimensions, letting
+// the box collapse to the img's intrinsic size. With geometry corroboration (computed px == bbox at
+// every vp), the authored fixed width AND height must be emitted.
+describe("generateCss authored fixed avatar size survives the content drop (FIX 3)", () => {
+  const drop = (): RawSizing => ({ wAuto: true, wFill: false, hAuto: true, hFill: false });
+  function avatar(): IRNode {
+    const img = xNode("n2", "img", Object.fromEntries(XVPS.map((vp) => [vp, {
+      cs: { display: "block", position: "static", height: "100%", width: "100%" },
+      bbox: { x: 0, y: 0, width: vp === 1280 ? 40 : 37.5, height: vp === 1280 ? 40 : 37.5 },
+    }])));
+    const a = xNode("n1", "div", {
+      375: { cs: { display: "block", position: "static", height: "37.5px", width: "37.5px" }, bbox: { x: 0, y: 0, width: 37.5, height: 37.5 }, sizing: drop() },
+      768: { cs: { display: "block", position: "static", height: "37.5px", width: "37.5px" }, bbox: { x: 0, y: 0, width: 37.5, height: 37.5 }, sizing: drop() },
+      1280: { cs: { display: "block", position: "static", height: "40px", width: "40px" }, bbox: { x: 0, y: 0, width: 40, height: 40 }, sizing: drop() },
+    }, [img]);
+    a.srcClass = "avatar-border-container h-[2.5rem] w-[2.5rem] shrink-0";
+    return xNode("n0", "div", Object.fromEntries(XVPS.map((vp) => [vp, { cs: { display: "flex", position: "static" }, bbox: { x: 0, y: 0, width: vp, height: 40 } }])), [a]);
+  }
+
+  it("emits both the authored fixed width and height per band", () => {
+    const css = generateCss(xIr(avatar()), new Map());
+    const all = allRulesX(css, "n1");
+    assert.ok(/width:37\.5px/.test(all), `narrow-band width (37.5px) must survive, got: ${all}`);
+    assert.ok(/height:37\.5px/.test(all), `narrow-band height (37.5px) must survive, got: ${all}`);
+    assert.ok(/width:40px/.test(all), `desktop width (40px) must survive, got: ${all}`);
+    assert.ok(/height:40px/.test(all), `desktop height (40px) must survive, got: ${all}`);
+  });
+});
+
+// FIX 2 — aspectHeightLaw must account for the aspect-ratio↔max-height WIDTH transfer. At a
+// max-height-clamped viewport, choosing a ratio also caps the width at ratio×maxH; a square ratio for a
+// 1.66:1 box (w=698, h=maxH=420) satisfies the height-only check but would clamp the clone's width to
+// 420. The law must reject that ratio (and fall back to explicit per-band dimensions) rather than emit a
+// wrong aspect-square.
+describe("generateCss aspectHeightLaw rejects width-clamping ratio transfer (FIX 2)", () => {
+  function photo(): IRNode {
+    // 375: genuinely square, unclamped (304.69²). 768: 1.66:1 but height clamped to max-h 420 (w=698).
+    // 1280: genuinely square, unclamped (372²). The 768 clamp must not license aspect-square.
+    // Single-row grid (grid-template-rows == content height) so singleFluidGridRow fires and the
+    // media/aspect pass runs.
+    const container = xNode("n1", "div", {
+      375: { cs: { display: "grid", position: "static", maxHeight: "420px", aspectRatio: "auto", gridTemplateRows: "304.69px" }, bbox: { x: 0, y: 0, width: 304.69, height: 304.69 } },
+      768: { cs: { display: "grid", position: "static", maxHeight: "420px", aspectRatio: "auto", gridTemplateRows: "420px" }, bbox: { x: 0, y: 0, width: 697.69, height: 420 } },
+      1280: { cs: { display: "grid", position: "static", maxHeight: "none", aspectRatio: "auto", gridTemplateRows: "371.66px" }, bbox: { x: 0, y: 0, width: 371.66, height: 371.66 } },
+    });
+    return xNode("n0", "div", Object.fromEntries(XVPS.map((vp) => [vp, { cs: { display: "block", position: "static" }, bbox: { x: 0, y: 0, width: vp, height: 500 } }])), [container]);
+  }
+
+  it("does not emit aspect-square for a box whose max-height clamp would shrink its width", () => {
+    const css = generateCss(xIr(photo()), new Map());
+    const all = allRulesX(css, "n1");
+    assert.ok(!/aspect-ratio:\s*1\s*\/\s*1/.test(all) && !/aspect-ratio:1\/1/.test(all),
+      `must not force aspect-square where the max-height transfer would clamp width, got: ${all}`);
+  });
+});
+
 // C1 (css side) — a computed `grid-template-rows: subgrid` is a STRUCTURAL keyword, not a baked px
 // regime. It must NEVER be dropped by the reflow-mode dropGridRows path (which strips px row tracks).
 describe("collectNodeRules never drops a subgrid rows template (C1)", () => {

From f16c3aa4e84a492fc5fac2589db463a92aac14c7 Mon Sep 17 00:00:00 2001
From: Samraaj Bath <samraaj100@gmail.com>
Date: Sat, 4 Jul 2026 05:33:06 -0700
Subject: [PATCH 17/24] Rotator classification: reject element-bearing
 containers, non-destructive runtime

A progressively-growing feed panel (rows injected after cap tagging)
passed the rotator leaf guard - which only rejected containers with
CAPPED children - and the rotator runtime's textContent writes then
flattened 51 statically-emitted descendants to one text node. Three
layers: emission drops rotators whose IR target has element children;
the capture leaf guard rejects any element child (capped or not); the
DittoMotion runtime saves/restores cloned child nodes via
replaceChildren so even a misclassified rotator can't destroy structure.

425 tests pass (6 new), typecheck clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 compiler/src/capture/motion.ts     |   7 +-
 compiler/src/generate/motion.ts    |  39 ++++++++-
 compiler/test/rotatorGuard.test.ts | 128 +++++++++++++++++++++++++++++
 3 files changed, 168 insertions(+), 6 deletions(-)
 create mode 100644 compiler/test/rotatorGuard.test.ts

diff --git a/compiler/src/capture/motion.ts b/compiler/src/capture/motion.ts
index c35b5b2..5edfe7f 100644
--- a/compiler/src/capture/motion.ts
+++ b/compiler/src/capture/motion.ts
@@ -482,8 +482,11 @@ export async function captureMotion(page: Page, opts?: { observeMs?: number; log
             const cap = el && (el as Element).getAttribute?.("data-cid-cap");
             if (!cap) continue;
             const elem = el as Element;
-            // only track small text-bearing elements (a rotating word/phrase, not a big block)
-            if (elem.querySelector("[data-cid-cap]")) continue; // has element children → not a leaf word
+            // only track small text-bearing elements (a rotating word/phrase, not a big block).
+            // Reject ANY element child, capped or not: rows injected at runtime (after cid-cap
+            // tagging, so uncapped) would otherwise defeat a capped-only check and let a
+            // multi-element panel pass as a "leaf word".
+            if (elem.firstElementChild) continue; // has element children → not a leaf word
             const txt = norm(elem.textContent || "");
             if (!txt || txt.length > 80) continue;
             const e = changes.get(cap) ?? { texts: [], times: [] };
diff --git a/compiler/src/generate/motion.ts b/compiler/src/generate/motion.ts
index 967e74f..4701a90 100644
--- a/compiler/src/generate/motion.ts
+++ b/compiler/src/generate/motion.ts
@@ -41,12 +41,31 @@ function capToCid(ir: IR): Map<string, string> {
   return m;
 }
 
+/** Map every IR node's cid → node, so an emission guard can inspect the resolved target. */
+function cidToNode(ir: IR): Map<string, IRNode> {
+  const m = new Map<string, IRNode>();
+  const walk = (n: IRNode): void => {
+    m.set(n.id, n);
+    for (const c of n.children) if (!isTextChild(c)) walk(c);
+  };
+  walk(ir.root);
+  return m;
+}
+
+/** True when an IR node has ≥1 element child. A genuine rotating word/phrase is a text leaf
+ *  (no element children); a container captured as a rotator would have the runtime flatten its
+ *  whole subtree to one text node, destroying every descendant element. */
+function hasElementChild(n: IRNode | undefined): boolean {
+  return !!n && n.children.some((c) => !isTextChild(c));
+}
+
 /** Resolve cap-keyed motion specs to cids that survived into this IR (optionally
  *  scoped by an include filter, for multi-route body/chrome splitting). Specs whose
  *  element was pruned are dropped (left static). */
 export function buildMotionSpec(ir: IR, motion: MotionCapture | undefined, include?: (cid: string) => boolean): MotionSpec {
   if (!motion) return { waapi: [], rotators: [], reveals: [], marquees: [] };
   const map = capToCid(ir);
+  const nodeByCid = cidToNode(ir);
   const ok = (cid: string | undefined): cid is string => !!cid && (!include || include(cid));
   const waapi: RTWaapi[] = [];
   for (const w of motion.waapi as WaapiAnim[]) {
@@ -58,6 +77,11 @@ export function buildMotionSpec(ir: IR, motion: MotionCapture | undefined, inclu
   for (const r of motion.rotators as RotatorSpec[]) {
     const cid = map.get(r.cap);
     if (!ok(cid)) continue;
+    // A rotator cycles the text of a single leaf word/phrase. If the resolved target has element
+    // children, capture misclassified a structural container (e.g. one whose rows were injected at
+    // runtime, uncapped, after cid-cap tagging) as a rotator. Emitting it would let the runtime
+    // flatten every descendant element to one text node; drop it so the static subtree survives.
+    if (hasElementChild(nodeByCid.get(cid))) continue;
     rotators.push({ cid, texts: r.texts, intervalMs: r.intervalMs });
   }
   const reveals: RTReveal[] = [];
@@ -157,7 +181,7 @@ export default function DittoMotion({ spec }: { spec: MotionSpec }) {
   useEffect(() => {
     if ((window as any).__dittoMotionStopped) return; // measurement mode — apply nothing
     const intervals: ReturnType<typeof setInterval>[] = [];
-    const rotators: Array<{ el: HTMLElement; original: string | null }> = [];
+    const rotators: Array<{ el: HTMLElement; original: Node[] }> = [];
     const anims: Animation[] = [];
     // per-reveal "show now" fns (also the cleanup); animate=false jumps to the settled frame
     const revealed: Array<(animate: boolean) => void> = [];
@@ -196,8 +220,15 @@ export default function DittoMotion({ spec }: { spec: MotionSpec }) {
     for (const r of spec.rotators) {
       const el = byCid(r.cid);
       if (!el || r.texts.length < 2) continue;
-      const original = el.textContent;
-      const start = r.texts.findIndex((t) => t === (original || "").replace(/\\s+/g, " ").trim());
+      // Defense in depth: a genuine rotating word is a text leaf. If the target has element
+      // children, it was misclassified (its subtree would be destroyed by a text write) — skip it
+      // so the static structure survives even if the emission guard was bypassed.
+      if (el.childElementCount > 0) continue;
+      // Save the ORIGINAL child nodes (cloned) rather than a flattened textContent string, so the
+      // settle/restore path rebuilds the exact subtree via replaceChildren — never a lossy text
+      // node. For a real text leaf this is just the single text node round-tripped intact.
+      const original = Array.from(el.childNodes).map((n) => n.cloneNode(true));
+      const start = r.texts.findIndex((t) => t === (el.textContent || "").replace(/\\s+/g, " ").trim());
       let i = start < 0 ? 0 : start;
       rotators.push({ el, original });
       intervals.push(setInterval(() => { i = (i + 1) % r.texts.length; el.textContent = r.texts[i]!; }, Math.max(400, r.intervalMs)));
@@ -274,7 +305,7 @@ export default function DittoMotion({ spec }: { spec: MotionSpec }) {
     const stopAll = () => {
       (window as any).__dittoMotionStopped = true;
       for (const id of intervals) clearInterval(id);
-      for (const r of rotators) r.el.textContent = r.original;
+      for (const r of rotators) r.el.replaceChildren(...r.original.map((n) => n.cloneNode(true)));
       for (const a of anims) { try { a.cancel(); } catch { /* ignore */ } }
       if (io) io.disconnect();
       if (forceTimer) clearTimeout(forceTimer);
diff --git a/compiler/test/rotatorGuard.test.ts b/compiler/test/rotatorGuard.test.ts
new file mode 100644
index 0000000..eed2b52
--- /dev/null
+++ b/compiler/test/rotatorGuard.test.ts
@@ -0,0 +1,128 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { chromium, type Browser, type Page } from "playwright";
+import type { IR, IRNode } from "../src/normalize/ir.js";
+import type { MotionCapture } from "../src/capture/motion.js";
+import { captureMotion } from "../src/capture/motion.js";
+import { buildMotionSpec, DITTO_MOTION_TSX } from "../src/generate/motion.js";
+
+// A rotator cycles the text of a single LEAF word/phrase. A container that bears element
+// children must never be treated as a rotator: the runtime replaces its content on each swap,
+// so classifying a structural panel as a rotator would flatten its whole subtree to one text
+// node. This regression guards all three defense layers against that misclassification.
+
+// ---- Minimal IR factory (only the fields buildMotionSpec reads: id, attrs, children) ----
+function node(id: string, cap: string | null, children: IRNode[] = [], text?: string): IRNode {
+  const kids = text !== undefined ? ([{ text }] as unknown as IRNode[]) : children;
+  return {
+    id,
+    tag: "div",
+    attrs: cap !== null ? { "data-cid-cap": cap } : {},
+    visibleByVp: {},
+    bboxByVp: {},
+    computedByVp: {},
+    children: kids,
+  } as unknown as IRNode;
+}
+
+function ir(root: IRNode): IR {
+  return { doc: { canonicalViewport: 1280 } as unknown as IR["doc"], root };
+}
+
+function motionWith(rotators: MotionCapture["rotators"]): MotionCapture {
+  return { waapi: [], rotators, reveals: [], marquees: [] };
+}
+
+describe("rotator misclassification guard — layer 1 (emission)", () => {
+  it("emits a rotator whose target is a genuine text leaf (no element children)", () => {
+    const tree = ir(node("n0", null, [node("n1", "5", [], "Design")]));
+    const spec = buildMotionSpec(tree, motionWith([{ cap: "5", texts: ["Design", "Build"], intervalMs: 900 }]));
+    assert.equal(spec.rotators.length, 1, "leaf rotator survives emission");
+    assert.equal(spec.rotators[0]!.cid, "n1");
+  });
+
+  it("DROPS a rotator whose target IR node has element children (structural container)", () => {
+    // n1 is capped and was classified as a rotator, but it holds real element rows (n2, n3).
+    const container = node("n1", "5", [
+      node("n2", null, [], "row one"),
+      node("n3", null, [], "row two"),
+    ]);
+    const tree = ir(node("n0", null, [container]));
+    const spec = buildMotionSpec(tree, motionWith([{ cap: "5", texts: ["a", "b"], intervalMs: 240 }]));
+    assert.equal(spec.rotators.length, 0, "element-bearing container is not emitted as a rotator");
+  });
+
+  it("keeps genuine leaf rotators while dropping a sibling container in the same spec", () => {
+    const tree = ir(node("n0", null, [
+      node("n1", "5", [], "Design"), // genuine leaf
+      node("n2", "6", [node("n3", null, [], "row")]), // container → dropped
+    ]));
+    const spec = buildMotionSpec(tree, motionWith([
+      { cap: "5", texts: ["Design", "Build"], intervalMs: 900 },
+      { cap: "6", texts: ["x", "y"], intervalMs: 240 },
+    ]));
+    assert.equal(spec.rotators.length, 1);
+    assert.equal(spec.rotators[0]!.cid, "n1");
+  });
+});
+
+describe("rotator misclassification guard — layer 3 (non-destructive runtime)", () => {
+  it("saves & restores the target's child NODES, never a flattened textContent string", () => {
+    // Save path: the original child nodes are cloned (structure preserved), not read as a string.
+    assert.match(DITTO_MOTION_TSX, /Array\.from\(el\.childNodes\)\.map\(\(n\) => n\.cloneNode\(true\)\)/);
+    // Restore path: rebuild via replaceChildren with cloned nodes — no `textContent = r.original`.
+    assert.match(DITTO_MOTION_TSX, /r\.el\.replaceChildren\(\.\.\.r\.original\.map\(\(n\) => n\.cloneNode\(true\)\)\)/);
+    assert.doesNotMatch(DITTO_MOTION_TSX, /r\.el\.textContent = r\.original/, "no lossy textContent restore remains");
+  });
+
+  it("refuses to install a rotator on an element that has element children at runtime", () => {
+    assert.match(DITTO_MOTION_TSX, /if \(el\.childElementCount > 0\) continue;/);
+  });
+});
+
+describe("rotator misclassification guard — layer 2 (capture leaf guard)", () => {
+  let browser: Browser;
+  let page: Page;
+  before(async () => {
+    browser = await chromium.launch();
+    page = await browser.newPage();
+  });
+  after(async () => {
+    await browser.close();
+  });
+
+  it("does not record an element-bearing container (runtime-injected uncapped rows) as a rotator", async () => {
+    // #panel is capped BEFORE its rows are injected (mirrors cid-cap tagging preceding the site's
+    // late row appends). Its rows are uncapped. #word is a genuine capped leaf cycling text.
+    await page.setContent(`<!doctype html><html><body>
+      <div id="panel" data-cid-cap="10"></div>
+      <span id="word" data-cid-cap="11">Design</span>
+      <script>
+        var glyphs = ["\\u2b22", "\\u2b21"], gi = 0;
+        var panel = document.getElementById("panel"), rows = 0;
+        // Append real (uncapped) element rows over time, and toggle a glyph inside them.
+        setInterval(function () {
+          if (rows < 4) {
+            var r = document.createElement("div");
+            r.className = "row";
+            r.innerHTML = '<span class="g">' + glyphs[gi % 2] + '</span> line ' + rows;
+            panel.appendChild(r); rows++;
+          } else {
+            gi++;
+            var gs = panel.querySelectorAll(".g");
+            for (var k = 0; k < gs.length; k++) gs[k].textContent = glyphs[gi % 2];
+          }
+        }, 120);
+        // #word: a genuine leaf whose text content cycles.
+        var words = ["Design", "Build", "Ship"], wi = 0, w = document.getElementById("word");
+        setInterval(function () { wi = (wi + 1) % words.length; w.textContent = words[wi]; }, 200);
+      </script>
+    </body></html>`);
+    // tsx/esbuild names the evaluated function; provide the helper it references in-page.
+    await page.evaluate("globalThis.__name = globalThis.__name || ((fn) => fn);");
+    const motion = await captureMotion(page, { observeMs: 1600 });
+    const caps = new Set(motion.rotators.map((r) => r.cap));
+    assert.ok(!caps.has("10"), "element-bearing panel is NOT recorded as a rotator");
+    assert.ok(caps.has("11"), "genuine leaf word IS recorded as a rotator");
+  });
+});

From 5b60ded62d1c0bf636de287f86d7c00f2c4ff47f Mon Sep 17 00:00:00 2001
From: Samraaj Bath <samraaj100@gmail.com>
Date: Sat, 4 Jul 2026 06:11:14 -0700
Subject: [PATCH 18/24] Grid plan equality guard, named-token px validation,
 breakpoint-ordered source variants, hidden-text diagnostic

- A grid-cols-N recipe plan may only override the authored template when
  computed tracks are near-equal - asymmetric sidebar templates
  (260px 1fr) keep their authored geometry
- Source-intent named tokens (max-w-md etc.) re-emit only when their
  Tailwind-4 value matches the captured computed px; mismatches (older
  token scales) emit the captured value instead
- Per-axis source-variant selection keeps the highest-min-width active
  variant instead of last-in-class-order, matching real Tailwind cascade
  (lg:grid-cols-3 no longer loses to a later md:grid-cols-2 at desktop) -
  latent since the initial commit
- New non-blocking textHiddenInClone metric in the dom gate: counts
  capture-visible text that renders hidden in the clone, so silent
  disappearances surface in reports

435 tests pass (10 new), typecheck clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 compiler/src/generate/app.ts             |  40 ++++++++-
 compiler/src/generate/tailwind.ts        | 108 +++++++++++++++++++++--
 compiler/src/validate/gates.ts           |  33 +++++++
 compiler/test/bandingFixes.test.ts       |  94 ++++++++++++++++++++
 compiler/test/gates.test.ts              |  80 ++++++++++++++++-
 compiler/test/recipeGridGeometry.test.ts |  36 ++++++++
 6 files changed, 384 insertions(+), 7 deletions(-)

diff --git a/compiler/src/generate/app.ts b/compiler/src/generate/app.ts
index e4c2361..13db98b 100644
--- a/compiler/src/generate/app.ts
+++ b/compiler/src/generate/app.ts
@@ -2496,6 +2496,36 @@ function computedTrackCount(value: string | undefined): number {
   return value.trim().split(/\s+/).filter(Boolean).length;
 }
 
+// Resolved px widths of the explicit column tracks in a computed `grid-template-columns` value. The
+// capture resolves the property to a used track list (`260px 1020px`), so each token is a definite
+// px length. Non-px tokens (`auto`, `min-content`, a leftover `1fr`) make the track set unquantifiable
+// and yield null — the plan then cannot claim the tracks are uniform.
+function computedTrackWidths(value: string | undefined): number[] | null {
+  if (!value || value === "none") return null;
+  const toks = value.trim().split(/\s+/).filter(Boolean);
+  const out: number[] = [];
+  for (const t of toks) {
+    const m = /^(-?\d*\.?\d+)px$/.exec(t);
+    if (!m) return null;
+    out.push(parseFloat(m[1]!));
+  }
+  return out.length ? out : null;
+}
+
+// A `grid-cols-N` plan rewrites the container to `repeat(N, minmax(0, 1fr))` — N EQUAL tracks. It is
+// only a faithful replacement for the authored template when the computed tracks actually are ~equal
+// width. An asymmetric template (`260px 1fr` → a 260/1020 sidebar layout) has the same track COUNT as
+// the heuristic column count but a different geometry; collapsing it to equal halves destroys the
+// authored layout, so such templates always keep their computed tracks.
+function tracksNearEqual(widths: number[]): boolean {
+  if (widths.length <= 1) return true;
+  const max = Math.max(...widths);
+  const min = Math.min(...widths);
+  if (!(max > 0)) return false;
+  // Tolerance: a couple of px (gap/rounding) or 2% of the widest track, whichever is larger.
+  return max - min <= Math.max(1.5, 0.02 * max);
+}
+
 // Track span of a grid item from its resolved `grid-column-start`/`grid-column-end`. A spanning
 // item (`span 2`, or an explicit line pair `1 / 3`) means row-length item-counting under-reports
 // the real track count, so the column-count heuristic is not trustworthy for this container.
@@ -2536,12 +2566,20 @@ export function recipeResponsiveClassCleaner(ir: IR, recipes: RecipeReport | und
     if (!parent) return false;
     const itemCids = (c.repeatedItems ?? []).map((i) => i.cid);
     for (const vp of regimeVps) {
-      const tracks = computedTrackCount(parent.computedByVp[vp]?.["gridTemplateColumns"]);
+      const gtc = parent.computedByVp[vp]?.["gridTemplateColumns"];
+      const tracks = computedTrackCount(gtc);
       // Only trust the heuristic where the computed grid actually is a track grid at this viewport.
       if (tracks === 0) continue;
       const regime = c.responsiveRegimes.find((r) => r.viewport === vp);
       const heuristicCols = regime?.columns ?? 0;
       if (heuristicCols > 0 && heuristicCols !== tracks) return false;
+      // A `grid-cols-N` plan means N EQUAL tracks. If the computed tracks are asymmetric (a sidebar
+      // template like `260px 1020px`), the count agrees but the geometry does not — collapsing to
+      // equal columns would destroy the authored layout. Keep the authored template in that case.
+      if (tracks >= 2) {
+        const widths = computedTrackWidths(gtc);
+        if (!widths || !tracksNearEqual(widths)) return false;
+      }
       for (const cid of itemCids) {
         if (computedColumnSpan(nodeByCid.get(cid)?.computedByVp[vp]) > 1) return false;
       }
diff --git a/compiler/src/generate/tailwind.ts b/compiler/src/generate/tailwind.ts
index a300bed..46af588 100644
--- a/compiler/src/generate/tailwind.ts
+++ b/compiler/src/generate/tailwind.ts
@@ -747,6 +747,25 @@ function sourceVariantActive(variant: string, vp: number): boolean {
   return true;
 }
 
+// Tailwind cascade specificity of an ACTIVE variant at a viewport: the effective min-width its media
+// query opens at, so a more-specific (higher) breakpoint wins over a lower one. Tailwind emits its
+// utilities sorted by breakpoint (min-width ascending), NOT by class-attribute order, so when both
+// `md:` and `lg:` apply at 1280 the `lg:` rule wins regardless of which appears first in the class
+// string. `min-[Npx]:` embeds N; a bare min breakpoint uses its threshold; `max-*` variants are
+// upper-bounded windows that a plain min variant out-specifies, so they score below any min. The
+// unprefixed base scores 0. Only meaningful for variants already known active at `vp`.
+function sourceVariantSpecificity(variant: string, vp: number): number {
+  if (!variant) return 0;
+  let score = 0;
+  for (const part of variant.split(":").filter(Boolean)) {
+    const minArb = /^min-\[(\d+)px\]$/.exec(part);
+    if (minArb) { score = Math.max(score, +minArb[1]!); continue; }
+    if (part in SOURCE_BP) { score = Math.max(score, SOURCE_BP[part]!); continue; }
+    // max-* windows are less specific than any min breakpoint; leave score as-is (a min wins).
+  }
+  return score;
+}
+
 function sourceArbitraryInner(suffix: string): string | null {
   return suffix.startsWith("[") && suffix.endsWith("]") ? suffix.slice(1, -1) : null;
 }
@@ -813,6 +832,67 @@ function fixedLengthUtilAsPx(util: string, node: IRNode, vp: number): string {
   return `${prefix}${sm[1]}-[${px}px]`;
 }
 
+// Tailwind v4's `max-w-*` / `w-*` / `h-*` / `max-h-*` NAMED size scale (the `--container-*` theme
+// values), in px at a 16px root. A source built on an OLDER Tailwind authored these names against a
+// DIFFERENT scale (e.g. v0–v2 `max-w-md` = 640px vs v4's 448px), so re-emitting the name verbatim
+// silently re-sizes the box. The source-intent pass validates the modern px below and falls back to
+// the captured computed px when they disagree.
+const CONTAINER_NAMED_PX: Record<string, number> = {
+  "3xs": 256, "2xs": 288, xs: 320, sm: 384, md: 448, lg: 512, xl: 576,
+  "2xl": 672, "3xl": 768, "4xl": 896, "5xl": 1024, "6xl": 1152, "7xl": 1280,
+};
+
+// The px a `w-`/`h-`/`max-w-`/`max-h-` NAMED or numeric-scale suffix resolves to under THIS clone's
+// Tailwind v4 (16px root). Covers the `--container-*` names (`md`→448) and the numeric spacing scale
+// (`24`→96px, `2.5`→10px). Returns null for relative/keyword/arbitrary suffixes (`full`, `1/2`,
+// `screen`, `[…]`, `prose`) — those re-derive from context and are not px-fixed, so they need no
+// value validation and are re-emitted verbatim.
+function namedLengthPx(suffix: string): number | null {
+  if (suffix in CONTAINER_NAMED_PX) return CONTAINER_NAMED_PX[suffix]!;
+  if (suffix === "px") return 1;
+  if (/^\d+(?:\.\d+)?$/.test(suffix)) return parseFloat(suffix) * 4; // spacing scale: n × 0.25rem
+  return null;
+}
+
+// A source utility on a length axis whose suffix is a NAMED/numeric-scale token (px-fixed under
+// v4) rather than a relative/keyword/arbitrary one. Only these need modern-value validation; e.g.
+// `max-w-md`, `w-24`, `h-px` — but not `max-w-full`, `w-1/2`, `h-[4rem]`.
+function namedScaleCore(core: string): { axis: "w" | "h" | "max-w" | "max-h"; px: number } | null {
+  const m = /^(max-w|max-h|w|h)-(.+)$/.exec(core);
+  if (!m) return null;
+  const px = namedLengthPx(m[2]!);
+  return px === null ? null : { axis: m[1] as "w" | "h" | "max-w" | "max-h", px };
+}
+
+// Captured computed px on the axis at a viewport, when definite (`…px`, not `auto`/`none`). The
+// property a length axis constrains: `max-width` / `max-height` / `width` / `height`.
+function computedAxisPx(node: IRNode, axis: SourceAxis, vp: number): number | null {
+  const cs = node.computedByVp[vp];
+  if (!cs) return null;
+  const raw = axis === "max-w" ? cs.maxWidth : axis === "max-h" ? cs.maxHeight
+    : axis === "w" ? cs.width : axis === "h" ? cs.height : undefined;
+  if (!raw || raw === "auto" || raw === "none" || !/px$/.test(raw)) return null;
+  return pf(raw);
+}
+
+// Re-emit a source length utility for one viewport. When the suffix is a NAMED/numeric-scale token
+// (px-fixed under v4) and its modern px does NOT match the captured computed px (within tolerance),
+// the authored name meant a different length on the source's older Tailwind — emit the captured px
+// as an arbitrary value instead of the mis-resolving name. Fluid/keyword/fixed-arbitrary suffixes
+// (and the already-handled fixed w/h path) pass through unchanged.
+function namedLengthUtilChecked(util: string, node: IRNode, axis: SourceAxis, vp: number): string {
+  const m = VARIANT_PREFIX.exec(util);
+  const prefix = m ? m[1]! : "";
+  const core = m ? m[2]! : util;
+  const named = namedScaleCore(core);
+  if (!named) return util;
+  const computed = computedAxisPx(node, axis, vp);
+  if (computed === null) return util; // no definite computed px to check against — keep authored name
+  if (Math.abs(named.px - computed) <= Math.max(1.5, 0.02 * computed)) return util; // modern value agrees
+  const rem = pxToRem(computed);
+  return `${prefix}${named.axis}-[${rem ?? computed + "px"}]`;
+}
+
 function sourceAspectUtility(core: string): string | null {
   let m = /^aspect-(\d+)\/(\d+)-box$/.exec(core);
   if (m) return m[1] === m[2] ? "aspect-square" : `aspect-[${m[1]}/${m[2]}]`;
@@ -1042,6 +1122,13 @@ function sourceIntentVarCss(node: IRNode, axis: SourceAxis, values: Map<number,
 
 function sourceIntentUtilities(node: IRNode, parent: IRNode | undefined, viewports: number[], canonical: number): SourceIntent {
   const perAxis = new Map<SourceAxis, Map<number, string>>();
+  // Per (axis, vp): the cascade specificity of the currently-chosen active token, so a later token in
+  // the class string can only override an earlier one when it is at least as specific. Tailwind sorts
+  // its emitted rules by breakpoint (min-width), so when both `md:` and `lg:` apply at a wide viewport
+  // the `lg:` value wins — regardless of the class-attribute order. Picking the LAST active token
+  // instead (class-string order) silently takes `md:grid-cols-2` at 1280 for `lg:grid-cols-3
+  // md:grid-cols-2`, dropping the desktop column count.
+  const specAt = new Map<SourceAxis, Map<number, number>>();
   for (const tok of parseSourceClass(node.srcClass)) {
     const parsed = sourceAxisForCore(tok.core);
     if (!parsed) continue;
@@ -1049,7 +1136,12 @@ function sourceIntentUtilities(node: IRNode, parent: IRNode | undefined, viewpor
       if (!sourceVariantActive(tok.variant, vp)) continue;
       let m = perAxis.get(parsed.axis);
       if (!m) { m = new Map<number, string>(); perAxis.set(parsed.axis, m); }
-      m.set(vp, parsed.utility);
+      let s = specAt.get(parsed.axis);
+      if (!s) { s = new Map<number, number>(); specAt.set(parsed.axis, s); }
+      const spec = sourceVariantSpecificity(tok.variant, vp);
+      // `>=` so a later token at EQUAL specificity still wins (matches source order for same-breakpoint
+      // duplicates), but a lower breakpoint can never displace a higher one already chosen.
+      if (!m.has(vp) || spec >= (s.get(vp) ?? -1)) { m.set(vp, parsed.utility); s.set(vp, spec); }
     }
   }
   const axes = new Set<SourceAxis>();
@@ -1081,10 +1173,16 @@ function sourceIntentUtilities(node: IRNode, parent: IRNode | undefined, viewpor
     }
     if (!sourceAxisCompatible(node, parent, axis, byVp, viewports)) continue;
     // A fixed-length w/h axis re-emits the CAPTURED computed px per band (root-font-size independent),
-    // not the source rem token; every other axis keeps its authored utility verbatim.
-    const asEmit = (vp: number): string =>
-      (axis === "w" || axis === "h") && isFixedLengthUtil(byVp.get(vp)!)
-        ? fixedLengthUtilAsPx(byVp.get(vp)!, node, vp) : byVp.get(vp)!;
+    // not the source rem token. A NAMED/numeric-scale length token (`max-w-md`, `w-24`) is re-emitted
+    // only when its modern Tailwind-v4 px matches the captured computed px; otherwise the authored
+    // name meant a different length on the source's older Tailwind and the captured px is emitted as an
+    // arbitrary value. Every other axis keeps its authored utility verbatim.
+    const asEmit = (vp: number): string => {
+      const u = byVp.get(vp)!;
+      if ((axis === "w" || axis === "h") && isFixedLengthUtil(u)) return fixedLengthUtilAsPx(u, node, vp);
+      if (axis === "w" || axis === "h" || axis === "max-w" || axis === "max-h") return namedLengthUtilChecked(u, node, axis, vp);
+      return u;
+    };
     const base = asEmit(canonical);
     axes.add(axis);
     if (axis === "aspect") axes.add("grid-rows");
diff --git a/compiler/src/validate/gates.ts b/compiler/src/validate/gates.ts
index 533cb13..d191378 100644
--- a/compiler/src/validate/gates.ts
+++ b/compiler/src/validate/gates.ts
@@ -86,6 +86,32 @@ function hasVisibleElementChild(node: IRNode, vp: number): boolean {
   return false;
 }
 
+/** A source text node that the capture painted VISIBLE but the clone rendered HIDDEN at the same
+ *  viewport is a high-signal regression: the words are in the markup yet fall in an invisible gen
+ *  subtree (off-viewport-shifted, banded-hidden, or width-frozen off-screen). Cheap to detect —
+ *  the gen node exists (matched by cid) but reports `visible === false`. Counts DISTINCT source
+ *  cids over the run (a node hidden at several viewports counts once) so the number reads as
+ *  "how many text nodes went dark", not "hidden-node×viewport". Non-blocking: reported as a metric
+ *  only. Pure + input-driven → deterministic. */
+export function countVisibleInCaptureHiddenInClone(
+  ir: IR,
+  genSnaps: Record<number, PageSnapshot>,
+  viewports: number[],
+): number {
+  const hiddenCids = new Set<string>();
+  for (const vp of viewports) {
+    if (!genSnaps[vp]) continue;
+    const gen = indexByCid(genSnaps[vp]!);
+    for (const s of collectSrcNodes(ir, vp)) {
+      if (!s.visible) continue;
+      if (normText(s.directText).length === 0) continue;
+      const g = gen.get(s.node.id);
+      if (g && !g.visible) hiddenCids.add(s.node.id);
+    }
+  }
+  return hiddenCids.size;
+}
+
 // ---------- Pollution gate (stage 2): is the captured page degenerate? ----------
 // A clone can pass every structural gate while faithfully reproducing the WRONG
 // page: an egress/bot wall, a near-empty shell, or a cookie/consent modal that was
@@ -278,6 +304,12 @@ export function gate3Dom(ir: IR, genSnaps: Record<number, PageSnapshot>, viewpor
     }
   }
 
+  // Non-blocking, high-signal diagnostic: source text the capture painted VISIBLE that the clone
+  // renders HIDDEN at the same viewport (off-screen-shifted / banded / width-frozen subtree). Does
+  // NOT gate pass — text presence already covers markup fidelity — but surfaces the "went dark"
+  // count so a banner/feed row vanishing is legible in the report instead of hiding inside a 99.x.
+  const textHiddenInClone = countVisibleInCaptureHiddenInClone(ir, genSnaps, viewports);
+
   const matchPct = totalVisible ? matched / totalVisible : 1;
   const textPct = textTotal ? textPresent / textTotal : 1;
   const linkPct = linksTotal ? linksOk / linksTotal : 1;
@@ -296,6 +328,7 @@ export function gate3Dom(ir: IR, genSnaps: Record<number, PageSnapshot>, viewpor
       nodeMatchPct: round4(matchPct), textPresentPct: round4(textPct),
       linkPct: round4(linkPct), mediaPct: round4(mediaPct),
       totalVisible, matched, textTotal, textPresent, linksTotal, mediaTotal, inventedText,
+      textHiddenInClone,
     },
     issues,
   };
diff --git a/compiler/test/bandingFixes.test.ts b/compiler/test/bandingFixes.test.ts
index 8689db5..4a452fa 100644
--- a/compiler/test/bandingFixes.test.ts
+++ b/compiler/test/bandingFixes.test.ts
@@ -136,3 +136,97 @@ describe("buildTailwind recovers authored banded fixed height as computed px (FI
     assert.ok(/h-\[60px\]|h-\[3\.75rem\]/.test(cls), `mobile height (60px/3.75rem@16root) must appear, got class: "${cls}"`);
   });
 });
+
+// FIX 2 (source-intent named-token validation) — a source built on an OLDER Tailwind authored
+// `max-w-md`, whose scale resolved `md` to 640px; the clone's Tailwind v4 resolves `max-w-md` to
+// 448px. Re-emitting the name verbatim silently re-sizes the box (640→448). The source-intent pass
+// must validate the modern named-token px against the captured computed px and, on mismatch, emit
+// the captured px as an arbitrary value instead of the mis-resolving name.
+describe("buildTailwind validates named length tokens against captured px (FIX 2)", () => {
+  // A max-width node whose computed maxWidth is `capPx` at every viewport, carrying `srcClass`.
+  function maxWNode(capPx: number, srcClass: string): IRNode {
+    const computedByVp: Record<number, StyleMap> = {};
+    const bboxByVp: Record<number, BBox> = {};
+    const visibleByVp: Record<number, boolean> = {};
+    for (const vp of VPS) {
+      computedByVp[vp] = computed({ maxWidth: `${capPx}px` });
+      bboxByVp[vp] = { x: 0, y: 0, width: Math.min(vp, capPx), height: 100 };
+      visibleByVp[vp] = true;
+    }
+    const n: IRNode = { id: "n1", tag: "div", attrs: {}, visibleByVp, bboxByVp, computedByVp, children: [{ text: "col" } as IRChild] };
+    n.srcClass = srcClass;
+    return n;
+  }
+
+  it("re-emits max-w-md as the captured px when the modern token value disagrees (640 ≠ 448)", () => {
+    // Modern max-w-md = 28rem = 448px, but the source computed a 640px cap → arbitrary px, not the name.
+    const el = maxWNode(640, "max-w-md");
+    const root = pvNode("n0", "body", { 375: {}, 1280: {} }, [el]);
+    const tw = buildTailwind(irWith(root), new Map());
+    const cls = tw.classOf.get("n1") || "";
+    assert.ok(!/\bmax-w-md\b/.test(cls), `mis-resolving max-w-md name must not survive, got class: "${cls}"`);
+    assert.ok(/max-w-\[640px\]|max-w-\[40rem\]/.test(cls), `captured 640px cap must be emitted arbitrarily, got class: "${cls}"`);
+  });
+
+  it("keeps max-w-lg verbatim when the modern token value matches the captured px (512 == 512)", () => {
+    // Modern max-w-lg = 32rem = 512px, and the source computed a 512px cap → the authored name is faithful.
+    const el = maxWNode(512, "max-w-lg");
+    const root = pvNode("n0", "body", { 375: {}, 1280: {} }, [el]);
+    const tw = buildTailwind(irWith(root), new Map());
+    const cls = tw.classOf.get("n1") || "";
+    assert.ok(/\bmax-w-lg\b/.test(cls), `matching max-w-lg name must survive, got class: "${cls}"`);
+    assert.ok(!/max-w-\[/.test(cls), `no arbitrary max-w should be emitted when the name matches, got class: "${cls}"`);
+  });
+});
+
+// FIX 3 (source-intent breakpoint specificity) — an authored gallery grid
+// `grid-cols-1 md:grid-cols-2 lg:grid-cols-3` (both `md:` and `lg:` are min-width variants, so BOTH
+// are active at 1280). Tailwind emits its rules sorted by breakpoint, so `lg:` wins there — the base
+// (canonical=1280) is grid-cols-3. Choosing the LAST active token in class-attribute order instead
+// (`… lg:grid-cols-3 md:grid-cols-2`) wrongly takes md's grid-cols-2 as base and drops the desktop
+// grid-cols-3 band entirely. The pass must pick the highest-min-width active variant per viewport.
+describe("buildTailwind source-intent picks the highest active breakpoint per viewport (FIX 3)", () => {
+  const GVPS = [375, 768, 1280, 1920];
+  function gridIr(srcClass: string): IR {
+    const gtc: Record<number, string> = {
+      375: "343px", 768: "348px 348px",
+      1280: "346.66px 346.66px 346.66px", 1920: "346.66px 346.66px 346.66px",
+    };
+    const gridW: Record<number, number> = { 375: 343, 768: 720, 1280: 1064, 1920: 1064 };
+    const mk = (id: string, byVp: Record<number, StyleMap>, w: Record<number, number>, kids: IRChild[] = [], sc?: string): IRNode => {
+      const computedByVp: Record<number, StyleMap> = {};
+      const bboxByVp: Record<number, BBox> = {};
+      const visibleByVp: Record<number, boolean> = {};
+      for (const vp of GVPS) {
+        computedByVp[vp] = computed(byVp[vp]);
+        bboxByVp[vp] = { x: 0, y: 0, width: w[vp]!, height: 100 };
+        visibleByVp[vp] = true;
+      }
+      const n: IRNode = { id, tag: "div", attrs: {}, visibleByVp, bboxByVp, computedByVp, children: kids };
+      if (sc) n.srcClass = sc;
+      return n;
+    };
+    const items = [0, 1, 2].map((i) => mk(`c${i}`, Object.fromEntries(GVPS.map((vp) => [vp, { display: "block" }])), Object.fromEntries(GVPS.map((vp) => [vp, 340])), [{ text: "x" } as IRChild]));
+    const grid = mk("n123", Object.fromEntries(GVPS.map((vp) => [vp, { display: "grid", gridTemplateColumns: gtc[vp], columnGap: "24px", rowGap: "24px", gap: "24px" }])), gridW, items, srcClass);
+    const root = mk("n0", Object.fromEntries(GVPS.map((vp) => [vp, {}])), Object.fromEntries(GVPS.map((vp) => [vp, vp])), [grid]);
+    return {
+      doc: {
+        sourceUrl: "https://example.test/grid", title: "Grid", lang: "en", charset: "UTF-8",
+        metaViewport: "width=device-width, initial-scale=1", viewports: GVPS, sampleViewports: GVPS, canonicalViewport: 1280,
+        perViewport: Object.fromEntries(GVPS.map((vp) => [vp, { scrollHeight: 800, scrollWidth: vp, htmlBg: "rgb(255, 255, 255)", bodyBg: "rgb(255, 255, 255)", bodyColor: "rgb(0, 0, 0)", bodyFont: "Arial" }])),
+        nodeCount: 5, keyframes: [],
+      },
+      root,
+    };
+  }
+
+  it("emits base grid-cols-3 (lg wins at 1280) even when md: follows lg: in the class string", () => {
+    const tw = buildTailwind(gridIr("grid grid-cols-1 gap-6 lg:grid-cols-3 md:grid-cols-2"), new Map());
+    const cls = tw.classOf.get("n123") || "";
+    const toks = cls.split(/\s+/);
+    assert.ok(toks.includes("grid-cols-3"), `desktop base must be grid-cols-3 (lg wins at 1280), got class: "${cls}"`);
+    assert.ok(!toks.some((t) => /(?:^|:)grid-cols-2$/.test(t) && !t.includes("md:max-lg:")), `md's grid-cols-2 must not become the base, got class: "${cls}"`);
+    assert.ok(toks.includes("md:max-lg:grid-cols-2"), `tablet band must be grid-cols-2, got class: "${cls}"`);
+    assert.ok(toks.includes("max-md:grid-cols-1"), `mobile band must be grid-cols-1, got class: "${cls}"`);
+  });
+});
diff --git a/compiler/test/gates.test.ts b/compiler/test/gates.test.ts
index 5dd9258..ef70c2e 100644
--- a/compiler/test/gates.test.ts
+++ b/compiler/test/gates.test.ts
@@ -1,6 +1,8 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { letterSpacingEquivalent, normHref } from "../src/validate/gates.js";
+import { letterSpacingEquivalent, normHref, countVisibleInCaptureHiddenInClone } from "../src/validate/gates.js";
+import type { IR, IRNode } from "../src/normalize/ir.js";
+import type { PageSnapshot } from "../src/capture/walker.js";
 
 // FIX 5 — the link gate must not fail a javascript: source href against the clone's sanitized value.
 // Generation emits an inert `#` for a `javascript:*` href (React blocks the literal), so normHref
@@ -54,3 +56,79 @@ describe("gate4 letterSpacing normal ↔ 0px normalization", () => {
     assert.ok(letterSpacingEquivalent(undefined, "0px"));
   });
 });
+
+// A capture-visible text node that the clone renders hidden (off-screen-shifted / banded /
+// width-frozen subtree) is the emil-banner / maxbo-feed regression class. The diagnostic counts
+// DISTINCT source cids whose gen counterpart exists but reports visible:false. Non-blocking; it
+// only has to be a faithful, deterministic count.
+describe("countVisibleInCaptureHiddenInClone diagnostic", () => {
+  // Minimal IR text leaf: `text` at every listed vp, visible per `vis`.
+  const leaf = (id: string, text: string, vis: Record<number, boolean>): IRNode => {
+    const vps = Object.keys(vis).map(Number);
+    const rec = <T,>(v: T): Record<number, T> => Object.fromEntries(vps.map((vp) => [vp, v]));
+    return {
+      id, tag: "a", attrs: {},
+      visibleByVp: vis,
+      bboxByVp: rec({ x: 0, y: 0, width: 100, height: 16 }),
+      computedByVp: rec({} as Record<string, string>),
+      children: [{ text }],
+    } as unknown as IRNode;
+  };
+  const makeIR = (leaves: IRNode[]): IR => ({
+    doc: {} as IR["doc"],
+    root: { id: "n0", tag: "body", attrs: {}, visibleByVp: {}, bboxByVp: {}, computedByVp: {}, children: leaves } as unknown as IRNode,
+  });
+  // Minimal clone snapshot: one node per (cid, visible) with matching direct text.
+  const snap = (nodes: Array<{ cid: string; text: string; visible: boolean }>): PageSnapshot => ({
+    root: {
+      tag: "body", attrs: { "data-cid": "n0" }, computed: {}, bbox: { x: 0, y: 0, width: 100, height: 100 }, visible: true,
+      children: nodes.map((n) => ({
+        tag: "a", attrs: { "data-cid": n.cid }, computed: {}, bbox: { x: 0, y: 0, width: 100, height: 16 },
+        visible: n.visible, children: [{ text: n.text }],
+      })),
+    },
+  } as unknown as PageSnapshot);
+
+  it("counts a source-visible text node the clone renders hidden", () => {
+    const ir = makeIR([leaf("n4", "Enrollment open!", { 375: true })]);
+    const gen = { 375: snap([{ cid: "n4", text: "Enrollment open!", visible: false }]) };
+    assert.equal(countVisibleInCaptureHiddenInClone(ir, gen, [375]), 1);
+  });
+
+  it("does NOT count a node visible in both source and clone", () => {
+    const ir = makeIR([leaf("n4", "Enrollment open!", { 375: true })]);
+    const gen = { 375: snap([{ cid: "n4", text: "Enrollment open!", visible: true }]) };
+    assert.equal(countVisibleInCaptureHiddenInClone(ir, gen, [375]), 0);
+  });
+
+  it("does NOT count a node the SOURCE itself hid (faithful hide)", () => {
+    // maxbo n192 @375: source already off-screen (visible:false) — the clone hiding it is correct.
+    const ir = makeIR([leaf("n192", "Avatar: Fire and Ash", { 375: false, 768: true })]);
+    const gen = {
+      375: snap([{ cid: "n192", text: "Avatar: Fire and Ash", visible: false }]),
+      768: snap([{ cid: "n192", text: "Avatar: Fire and Ash", visible: true }]),
+    };
+    assert.equal(countVisibleInCaptureHiddenInClone(ir, gen, [375, 768]), 0);
+  });
+
+  it("counts a node once even when hidden at several viewports (distinct cids)", () => {
+    const ir = makeIR([leaf("n4", "Enrollment open!", { 375: true, 768: true })]);
+    const gen = {
+      375: snap([{ cid: "n4", text: "Enrollment open!", visible: false }]),
+      768: snap([{ cid: "n4", text: "Enrollment open!", visible: false }]),
+    };
+    assert.equal(countVisibleInCaptureHiddenInClone(ir, gen, [375, 768]), 1);
+  });
+
+  it("ignores whitespace-only text nodes", () => {
+    const ir = makeIR([leaf("n5", "   ", { 375: true })]);
+    const gen = { 375: snap([{ cid: "n5", text: "   ", visible: false }]) };
+    assert.equal(countVisibleInCaptureHiddenInClone(ir, gen, [375]), 0);
+  });
+
+  it("does not count when the clone has no node for the cid (a different miss)", () => {
+    const ir = makeIR([leaf("n4", "Enrollment open!", { 375: true })]);
+    const gen = { 375: snap([]) };
+    assert.equal(countVisibleInCaptureHiddenInClone(ir, gen, [375]), 0);
+  });
+});
diff --git a/compiler/test/recipeGridGeometry.test.ts b/compiler/test/recipeGridGeometry.test.ts
index 9fa45e2..30e935c 100644
--- a/compiler/test/recipeGridGeometry.test.ts
+++ b/compiler/test/recipeGridGeometry.test.ts
@@ -127,6 +127,42 @@ describe("recipe grid geometry: computed tracks/spans are ground truth", () => {
     assert.equal(itemOut, "col-start-1 col-end-3 flex flex-col", "span-2 item className is unchanged");
   });
 
+  it("does not override an ASYMMETRIC 2-track sidebar grid with a grid-cols-2 plan", () => {
+    // A sidebar layout: `grid-template-columns: 260px 1020px` (authored `260px 1fr`). The item-count
+    // heuristic sees 2 items in one row → 2 columns, which agrees with the 2 computed tracks by COUNT.
+    // But `grid-cols-2` = two EQUAL 640px tracks, which destroys the 260/1020 geometry. The plan must be
+    // rejected and the authored template kept.
+    const sidebar = node("n2", "aside", {
+      768: { gridColumnStart: "auto", gridColumnEnd: "auto" },
+      1280: { gridColumnStart: "auto", gridColumnEnd: "auto" },
+    });
+    const main = node("n3", "div", {
+      768: { gridColumnStart: "auto", gridColumnEnd: "auto" },
+      1280: { gridColumnStart: "auto", gridColumnEnd: "auto" },
+    });
+    const parent = node("n1", "div", {
+      768: { display: "grid", gridTemplateColumns: "220px 500px" },
+      1280: { display: "grid", gridTemplateColumns: "260px 1020px" },
+    }, [sidebar, main]);
+    const ir = irWith(node("n0", "section", {}, [parent]));
+    const c = candidate({
+      itemParentCid: "n1",
+      itemCount: 2,
+      responsiveRegimes: [regime(768, 2, 2), regime(1280, 2, 2)],
+      repeatedItems: [
+        { cid: "n2", tag: "aside", textSample: "", mediaCount: 0, headingCount: 0, bbox: { x: 0, y: 0, width: 260, height: 300 } },
+        { cid: "n3", tag: "div", textSample: "", mediaCount: 0, headingCount: 1, bbox: { x: 276, y: 0, width: 1020, height: 300 } },
+      ],
+    });
+    const clean = recipeResponsiveClassCleaner(ir, report([c]), { tailwind: true });
+    // The emitter baked the authored asymmetric template as an arbitrary grid-template-columns utility.
+    const containerIn = "grid grid-cols-[260px_1020px] gap-6";
+    const out = clean("n1", containerIn)!.split(/\s+/);
+    assert.ok(out.includes("grid-cols-[260px_1020px]"), `authored asymmetric template must survive, got: ${out.join(" ")}`);
+    assert.ok(!out.some((t) => /(?:^|:)grid-cols-2$/.test(t)), `no equal-halves grid-cols-2 override, got: ${out.join(" ")}`);
+    assert.ok(!out.some((t) => /^(?:md|lg|2xl):grid-cols-/.test(t)), `no responsive grid-cols plan appended, got: ${out.join(" ")}`);
+  });
+
   it("still re-flows a genuinely uniform grid whose computed tracks match the heuristic", () => {
     // 2-track grid at 768, 3-track at 1280, no spanning items → heuristic agrees with computed.
     const item = (id: string): IRNode => node(id, "article", {

From fae44aab9317c5b0a1cc5cab9b23472c527830ae Mon Sep 17 00:00:00 2001
From: Samraaj Bath <samraaj100@gmail.com>
Date: Sat, 4 Jul 2026 06:21:07 -0700
Subject: [PATCH 19/24] Validation waits for webfonts before measuring; sticky
 wrappers keep fluid width

- The render walk and screenshots now await document.fonts.ready plus a
  bounded state-based poll until every declared face is terminal
  (loaded/error); pending families surface as a font_wait_warning event
  instead of skewing text metrics with fallback-font boxes
- position:sticky full-width wrappers share the static/relative
  fluid-fill branch (a sticky box fills its containing block like any
  in-flow box) instead of freezing at canonical px; fixed-width sticky
  rails still freeze

447 tests pass (12 new), typecheck clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 compiler/src/generate/css.ts      |   8 ++-
 compiler/src/validate/render.ts   | 101 ++++++++++++++++++++++++++++--
 compiler/src/validate/validate.ts |   3 +
 compiler/test/css.test.ts         |  60 ++++++++++++++++++
 compiler/test/serveRange.test.ts  |  50 ++++++++++++++-
 5 files changed, 215 insertions(+), 7 deletions(-)

diff --git a/compiler/src/generate/css.ts b/compiler/src/generate/css.ts
index f256e44..d6f87b0 100644
--- a/compiler/src/generate/css.ts
+++ b/compiler/src/generate/css.ts
@@ -244,9 +244,13 @@ function isFluidFullBleed(node: IRNode, parentNode: IRNode | undefined, viewport
     const pos = cs.position || "static";
     if (pos === "absolute" || pos === "fixed") {
       if (!(nearZero(cs.left) && nearZero(cs.right))) return false; // width is real unless both insets pin it
-    } else if (pos === "sticky") {
-      return false;
     } else {
+      // static | relative | sticky. A sticky box generates a normal in-flow box: its WIDTH fills the
+      // containing block exactly as static/relative does (position:sticky only shifts the box's offset
+      // while scrolling, never its resolved width). So a sticky wrapper that spans the viewport at
+      // every captured width was authored fluid (width:100%/auto) and must NOT freeze to the canonical
+      // px — frozen at 1280, a `justify-content:center` sticky banner pushes its inner content off a
+      // 375 viewport. Treat sticky identically to the static/relative fluid-fill branch.
       if (!(zeroOrAuto(cs.left) && zeroOrAuto(cs.right))) return false; // positioned breakout: width is real
       const pdisp = parentNode?.computedByVp[vp]?.display || "";
       if (/flex|grid/.test(pdisp)) return false; // flex/grid item: auto width ≠ fill
diff --git a/compiler/src/validate/render.ts b/compiler/src/validate/render.ts
index aabfa57..784ec36 100644
--- a/compiler/src/validate/render.ts
+++ b/compiler/src/validate/render.ts
@@ -260,8 +260,87 @@ export type RenderResult = {
   runtimeErrors: string[];
   httpStatus: number;
   failedResources: string[];
+  /** Non-fatal diagnostics: families the app declared via @font-face that never reached
+   *  `status:"loaded"` within the wait bound (their text was measured with a fallback face). */
+  fontWarnings: string[];
 };
 
+/** A single entry of `document.fonts` as reported in-page, reduced to the fields the
+ *  load decision needs. Serializable so the decision logic can be unit-tested outside a browser. */
+export type FontFaceStatus = { family: string; weight: string; style: string; status: string };
+
+/** Pure decision for the font-load wait: given the current `document.fonts` entries, return the
+ *  families that are DECLARED (an @font-face exists for them) but not yet `"loaded"`. A family is
+ *  considered pending while ANY of its faces is still `"unloaded"` or `"loading"`; a face that
+ *  `"error"`ed is treated as terminal (it will never load, so waiting longer is pointless — it is
+ *  not reported as pending). Empty return ⇒ every declared face has reached a terminal state and
+ *  the DOM may be measured. The check is state-based (not time-based), so the caller's poll is
+ *  deterministic: it ends the instant this returns empty, regardless of wall-clock timing. */
+export function pendingFontFamilies(faces: FontFaceStatus[]): string[] {
+  const pending = new Set<string>();
+  const terminalByFamily = new Map<string, boolean>();
+  for (const f of faces) {
+    const fam = f.family.replace(/^["']|["']$/g, "");
+    if (f.status === "loaded" || f.status === "error") {
+      if (!terminalByFamily.has(fam)) terminalByFamily.set(fam, true);
+    } else {
+      // "unloaded" | "loading" (or any non-terminal state) ⇒ this family is still pending.
+      pending.add(fam);
+      terminalByFamily.set(fam, false);
+    }
+  }
+  return [...pending].sort();
+}
+
+/** In-page: await `document.fonts.ready`, then poll (bounded) until every declared @font-face has
+ *  reached a terminal state (`loaded`/`error`). Returns the still-pending families when the bound
+ *  expired, or an empty array once all faces settled. Runs entirely inside the browser context so
+ *  it reads the live FontFaceSet. Bounded + state-based ⇒ deterministic (ends on state, never on a
+ *  fixed sleep). `capMs` is a hard ceiling so a hung/erroring font request can't stall the render. */
+async function awaitFontsLoaded(
+  page: import("playwright").Page,
+  opts?: { capMs?: number; pollMs?: number },
+): Promise<string[]> {
+  const capMs = opts?.capMs ?? 3000;
+  const pollMs = opts?.pollMs ?? 50;
+  try {
+    return await page.evaluate(
+      async ({ capMs, pollMs }) => {
+        const doc = document as Document;
+        const set = doc.fonts as unknown as { ready?: Promise<unknown>; forEach?: (cb: (f: FontFaceStatus) => void) => void } | undefined;
+        if (!set) return [];
+        const snapshot = (): { family: string; weight: string; style: string; status: string }[] => {
+          const out: { family: string; weight: string; style: string; status: string }[] = [];
+          set.forEach?.((f) => out.push({ family: f.family, weight: f.weight, style: f.style, status: f.status }));
+          return out;
+        };
+        const pending = (faces: { family: string; weight: string; style: string; status: string }[]): string[] => {
+          const p = new Set<string>();
+          for (const f of faces) {
+            const fam = f.family.replace(/^["']|["']$/g, "");
+            if (f.status !== "loaded" && f.status !== "error") p.add(fam);
+          }
+          return [...p].sort();
+        };
+        // First give the browser's own aggregate signal a chance (bounded — a hung request must not
+        // hold ready forever). Then poll the per-face states until all terminal or the cap expires.
+        await Promise.race([set.ready ?? Promise.resolve(), new Promise((r) => setTimeout(r, capMs))]);
+        const deadline = Date.now() + capMs;
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+          const left = pending(snapshot());
+          if (left.length === 0) return [];
+          if (Date.now() >= deadline) return left;
+          await new Promise((r) => setTimeout(r, pollMs));
+        }
+      },
+      { capMs, pollMs },
+    ) as string[];
+  } catch {
+    return []; // a page without a FontFaceSet (or an evaluate fault) never blocks the walk
+  }
+}
+
 /** Navigate with `waitUntil:"load"` then wait for a bounded window of network quiet, so
  *  validation NEVER hard-fails on media that trickles requests. `waitUntil:"networkidle"`
  *  is a hard timeout: an autoplaying long video (even chunked via 206) keeps issuing bounded
@@ -335,6 +414,7 @@ export async function renderApp(opts: {
       const vh = viewportHeight(vw);
       const ctx = await browser.newContext({ ignoreHTTPSErrors: true, viewport: { width: vw, height: vh }, deviceScaleFactor: 1 });
       const runtimeErrors: string[] = [];
+      const fontWarnings: string[] = [];
       const failedResources = new Set<string>();
       let httpStatus = 0;
       try {
@@ -345,7 +425,17 @@ export async function renderApp(opts: {
         page.on("requestfailed", (r) => failedResources.add(`failed ${r.url()}`));
         const resp = await gotoAndSettle(page, opts.url);
         if (resp) httpStatus = resp.status();
-        try { await page.evaluate(() => (document as Document).fonts?.ready); } catch { /* ignore */ }
+        // Webfonts must be APPLIED before the DOM walk and the screenshot: a rendered snapshot taken
+        // while the app's @font-face faces are still "unloaded" measures every text box in the
+        // fallback face (systematically narrower/wider glyphs → a bogus size delta attributed to the
+        // clone). Await document.fonts.ready AND poll (bounded, state-based) until every declared face
+        // is terminal, so this holds for both the walk below and the screenshot further down.
+        const pendingFonts = await awaitFontsLoaded(page);
+        if (pendingFonts.length) {
+          const msg = `font-wait: ${pendingFonts.length} @font-face families unloaded after wait bound at ${vw}px: ${pendingFonts.join(", ")}`;
+          fontWarnings.push(msg);
+          console.warn(`[render] ${msg}`);
+        }
         // Scroll to settle any lazy effects, then back to top.
         await page.evaluate(async () => {
           const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
@@ -389,18 +479,19 @@ export async function renderApp(opts: {
             await page.screenshot({ path: shotPath, fullPage: true, timeout: 90_000, animations: "disabled" });
           }
         } catch { /* ignore */ }
-        return { viewport: vw, snapshot, runtimeErrors, failedResources: [...failedResources], httpStatus };
+        return { viewport: vw, snapshot, runtimeErrors, fontWarnings, failedResources: [...failedResources], httpStatus };
       } finally {
         await ctx.close();
       }
     });
     const runtimeErrors = results.flatMap((r) => r.runtimeErrors);
+    const fontWarnings = results.flatMap((r) => r.fontWarnings);
     const failedResources = new Set(results.flatMap((r) => r.failedResources));
     for (const r of results) snapshots[r.viewport] = r.snapshot;
     const non200 = results.find((r) => r.httpStatus && r.httpStatus !== 200);
     const httpStatus = non200?.httpStatus ?? results.find((r) => r.httpStatus)?.httpStatus ?? 0;
     ensureDir(join(opts.renderedDir, "computed"));
-    return { snapshots, runtimeErrors, httpStatus, failedResources: [...failedResources] };
+    return { snapshots, runtimeErrors, httpStatus, failedResources: [...failedResources], fontWarnings };
   } finally {
     await browser.close();
   }
@@ -425,7 +516,9 @@ export async function measureProbeWidths(opts: { url: string; widths: number[] }
         const page = await ctx.newPage();
         await page.addInitScript(ESBUILD_SHIM);
         await gotoAndSettle(page, opts.url);
-        try { await page.evaluate(() => (document as Document).fonts?.ready); } catch { /* ignore */ }
+        // This probe walks the DOM and measures text boxes, so — exactly as renderApp does — webfonts
+        // must be applied first, else the probe reads fallback-font widths at the off-band widths.
+        await awaitFontsLoaded(page);
         await page.evaluate(() => {
           const win = window as unknown as { __dittoMotionStopped?: boolean; __dittoMotionStop?: () => void };
           try { win.__dittoMotionStopped = true; } catch { /* ignore */ }
diff --git a/compiler/src/validate/validate.ts b/compiler/src/validate/validate.ts
index 0be55b4..070df00 100644
--- a/compiler/src/validate/validate.ts
+++ b/compiler/src/validate/validate.ts
@@ -108,6 +108,9 @@ export async function validateRun(runDir: string, opts?: { harnessDir?: string;
     try {
       const r = await renderApp({ url: server.url + "/", viewports, renderedDir });
       snapshots = r.snapshots; runtimeErrors = r.runtimeErrors; httpStatus = r.httpStatus; failedResources = r.failedResources;
+      // Non-fatal: webfonts that never loaded before the render walk (text was measured in a fallback
+      // face). Surfaced as a warning event, NOT a runtime error, so it never fails gate 0.
+      if (r.fontWarnings.length) log({ event: "font_wait_warning", families: r.fontWarnings });
       probeSnaps = await measureProbeWidths({ url: server.url + "/", widths: probeWidthsFor(viewports) });
       if (capture.interaction) {
         interactionGate = await driveInteractionGate({ url: server.url + "/", viewports, ir, interaction: capture.interaction });
diff --git a/compiler/test/css.test.ts b/compiler/test/css.test.ts
index 115fd86..89e778a 100644
--- a/compiler/test/css.test.ts
+++ b/compiler/test/css.test.ts
@@ -1210,3 +1210,63 @@ describe("collectNodeRules picture fill child keeps authored height (T2)", () =>
     assert.ok(/560px|500px|480px/.test(all), `authored height must survive with a picture fill child, got: ${all}`);
   });
 });
+
+// A `position:sticky` full-width banner wrapper: its box spans the viewport at EVERY captured width
+// (375/768/1280), so it was authored fluid (width:100%/auto) — sticky only shifts the box's offset
+// while scrolling, never its resolved width. Freezing it to the canonical 1280px means at a 375
+// viewport its `justify-content:center` pushes the inner content off-screen. A viewport-tracking
+// sticky wrapper must emit no frozen width (→ fluid `width:auto`, resolving to the identical px at
+// every captured width, so gates 0–6 stay unmoved).
+describe("generateCss sticky full-width wrapper is viewport-tracking (no px freeze)", () => {
+  // Sticky banner directly under <body>; spans the full viewport width at every width, centred inner.
+  function stickyBanner() {
+    const inner = xNode("n2", "span", {
+      375: { cs: { display: "inline-block" }, bbox: { x: 120, y: 8, width: 135, height: 20 } },
+      768: { cs: { display: "inline-block" }, bbox: { x: 316, y: 8, width: 135, height: 20 } },
+      1280: { cs: { display: "inline-block" }, bbox: { x: 572, y: 8, width: 135, height: 20 } },
+    }, [{ text: "Enrollment is open" } as IRChild]);
+    const banner = xNode("n1", "div", {
+      375: { cs: { display: "flex", position: "sticky", justifyContent: "center", top: "0px", width: "375px" }, bbox: { x: 0, y: 0, width: 375, height: 36 } },
+      768: { cs: { display: "flex", position: "sticky", justifyContent: "center", top: "0px", width: "768px" }, bbox: { x: 0, y: 0, width: 768, height: 36 } },
+      1280: { cs: { display: "flex", position: "sticky", justifyContent: "center", top: "0px", width: "1280px" }, bbox: { x: 0, y: 0, width: 1280, height: 36 } },
+    }, [inner]);
+    return xNode("n0", "body", {
+      375: { bbox: { x: 0, y: 0, width: 375, height: 800 } },
+      768: { bbox: { x: 0, y: 0, width: 768, height: 800 } },
+      1280: { bbox: { x: 0, y: 0, width: 1280, height: 800 } },
+    }, [banner]);
+  }
+
+  it("does not freeze the sticky banner width to the canonical px", () => {
+    const css = generateCss(xIr(stickyBanner()), new Map());
+    const all = allRulesX(css, "n1");
+    assert.ok(!/width:1280px/.test(all), `sticky full-width banner must not freeze to canonical px, got: ${all}`);
+    assert.ok(!/width:768px/.test(all) && !/width:375px/.test(all), `no per-band px freeze either, got: ${all}`);
+  });
+
+  it("does not inject auto margins (fix drops the width only, not centring)", () => {
+    // The d3ec154 guard: mx-auto only for true auto-margin centring. A sticky banner centres its
+    // INNER content via justify-content, so the wrapper itself must not gain auto side margins.
+    const css = generateCss(xIr(stickyBanner()), new Map());
+    const all = allRulesX(css, "n1");
+    assert.ok(!/margin-left:auto/.test(all) && !/margin-right:auto/.test(all), `must not add auto margins, got: ${all}`);
+  });
+
+  it("still freezes a genuinely fixed-width sticky element (not viewport-spanning)", () => {
+    // A sticky sidebar rail whose width is a real fixed px (constant 280px, never == the viewport)
+    // must keep its baked width — the fluid-full-bleed detector only fires when the box spans the
+    // viewport at every width.
+    const rail = xNode("n1", "div", {
+      375: { cs: { display: "block", position: "sticky", top: "0px", width: "280px" }, bbox: { x: 0, y: 0, width: 280, height: 400 } },
+      768: { cs: { display: "block", position: "sticky", top: "0px", width: "280px" }, bbox: { x: 0, y: 0, width: 280, height: 400 } },
+      1280: { cs: { display: "block", position: "sticky", top: "0px", width: "280px" }, bbox: { x: 0, y: 0, width: 280, height: 400 } },
+    });
+    const root = xNode("n0", "body", {
+      375: { bbox: { x: 0, y: 0, width: 375, height: 800 } },
+      768: { bbox: { x: 0, y: 0, width: 768, height: 800 } },
+      1280: { bbox: { x: 0, y: 0, width: 1280, height: 800 } },
+    }, [rail]);
+    const css = generateCss(xIr(root), new Map());
+    assert.ok(/width:280px/.test(allRulesX(css, "n1")), `a fixed-width sticky rail keeps its px, got: ${allRulesX(css, "n1")}`);
+  });
+});
diff --git a/compiler/test/serveRange.test.ts b/compiler/test/serveRange.test.ts
index 6bb6ee0..fdcc6d9 100644
--- a/compiler/test/serveRange.test.ts
+++ b/compiler/test/serveRange.test.ts
@@ -3,7 +3,7 @@ import assert from "node:assert/strict";
 import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { serveStatic, parseRangeHeader } from "../src/validate/render.js";
+import { serveStatic, parseRangeHeader, pendingFontFamilies, type FontFaceStatus } from "../src/validate/render.js";
 
 // ---- Pure helper: parseRangeHeader ----
 describe("parseRangeHeader", () => {
@@ -52,6 +52,54 @@ describe("parseRangeHeader", () => {
   });
 });
 
+// ---- Pure helper: pendingFontFamilies (the font-load wait decision) ----
+// The render walk must run after webfonts are APPLIED, else text boxes measure the fallback face
+// (a systematic width delta wrongly attributed to the clone). This helper is the state-based (not
+// time-based) predicate the in-page poll ends on: it returns the DECLARED families not yet terminal.
+describe("pendingFontFamilies", () => {
+  const face = (family: string, status: string, weight = "400", style = "normal"): FontFaceStatus => ({ family, weight, style, status });
+
+  it("no faces declared → nothing pending", () => {
+    assert.deepEqual(pendingFontFamilies([]), []);
+  });
+
+  it("all faces loaded → nothing pending (walk may proceed)", () => {
+    assert.deepEqual(pendingFontFamilies([face("Avenir", "loaded"), face("Inter", "loaded")]), []);
+  });
+
+  it("an unloaded face makes its family pending", () => {
+    assert.deepEqual(pendingFontFamilies([face("Avenir", "unloaded")]), ["Avenir"]);
+  });
+
+  it("a loading face makes its family pending", () => {
+    assert.deepEqual(pendingFontFamilies([face("Avenir", "loading")]), ["Avenir"]);
+  });
+
+  it("errored faces are terminal — never reported pending (waiting longer is pointless)", () => {
+    assert.deepEqual(pendingFontFamilies([face("Avenir", "error")]), []);
+  });
+
+  it("a family with mixed weights is pending if ANY weight is not terminal", () => {
+    const faces = [face("Avenir", "loaded", "400"), face("Avenir", "loading", "700")];
+    assert.deepEqual(pendingFontFamilies(faces), ["Avenir"]);
+  });
+
+  it("a family whose faces are all terminal (loaded or errored) is not pending", () => {
+    const faces = [face("Avenir", "loaded", "400"), face("Avenir", "error", "700")];
+    assert.deepEqual(pendingFontFamilies(faces), []);
+  });
+
+  it("strips surrounding quotes from the reported family name and dedupes+sorts", () => {
+    const faces = [face('"Source Serif"', "unloaded"), face("Avenir", "loading"), face("Avenir", "unloaded")];
+    assert.deepEqual(pendingFontFamilies(faces), ["Avenir", "Source Serif"]);
+  });
+
+  it("only the unloaded families are returned when some are loaded", () => {
+    const faces = [face("Inter", "loaded"), face("Avenir", "unloaded"), face("JetBrains", "loaded")];
+    assert.deepEqual(pendingFontFamilies(faces), ["Avenir"]);
+  });
+});
+
 // ---- Integration: serveStatic answers real Range requests with 206/416 ----
 describe("serveStatic Range support (integration)", () => {
   let rootDir = "";

From 03743333c1109e31cc8998dea47858b28cc173b3 Mon Sep 17 00:00:00 2001
From: Samraaj Bath <samraaj100@gmail.com>
Date: Sat, 4 Jul 2026 07:03:21 -0700
Subject: [PATCH 20/24] Font-wait counts only actively-loading faces; excuse
 aborted fetches whose file exists

- Lazy-loading semantics: an @font-face never matched by rendered text
  stays "unloaded" forever - the readiness poll now waits only on faces
  in "loading" state, ending the instant fetches settle (removes ~3s of
  dead deadline per viewport on affected pages); unreferenced faces log
  per-face informationally instead of warning
- Asset gate counts a failure only for real HTTP >= 400 or a failed
  fetch whose target file is genuinely absent from the export - aborted
  srcset-candidate image fetches with valid files on disk are excused,
  matching the existing streaming-media treatment

458 tests pass (11 new), typecheck clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 compiler/src/validate/gates.ts    |  2 +-
 compiler/src/validate/render.ts   | 85 ++++++++++++++++++++-----------
 compiler/src/validate/validate.ts | 36 ++++++++++---
 compiler/test/gates.test.ts       | 56 +++++++++++++++++++-
 compiler/test/serveRange.test.ts  | 57 +++++++++++++++++----
 5 files changed, 188 insertions(+), 48 deletions(-)

diff --git a/compiler/src/validate/gates.ts b/compiler/src/validate/gates.ts
index d191378..9f9ed4f 100644
--- a/compiler/src/validate/gates.ts
+++ b/compiler/src/validate/gates.ts
@@ -222,7 +222,7 @@ export function gate2Assets(assetGraph: AssetGraph, fontGraph: FontGraph, gen: {
   if (zeroByte > 0) issues.push(`${zeroByte} zero-byte downloaded assets`);
   if (skippedNoReason > 0) issues.push(`${skippedNoReason} skipped assets without reason`);
   if (gen.remoteRefs.length > 0) issues.push(`${gen.remoteRefs.length} generated refs point to remote origin`);
-  if (gen.failed404.length > 0) issues.push(`${gen.failed404.length} generated asset refs 404`);
+  if (gen.failed404.length > 0) issues.push(`${gen.failed404.length} generated asset refs missing (HTTP >= 400 or file absent from export)`);
   const fontsResolvedOrFallback = fontGraph.entries.every((f) => f.status === "resolved" || (f.status === "fallback" && f.reason));
   if (!fontsResolvedOrFallback) issues.push("font declarations not resolved/fallback-recorded");
   return {
diff --git a/compiler/src/validate/render.ts b/compiler/src/validate/render.ts
index 784ec36..8c0d8fd 100644
--- a/compiler/src/validate/render.ts
+++ b/compiler/src/validate/render.ts
@@ -270,37 +270,47 @@ export type RenderResult = {
 export type FontFaceStatus = { family: string; weight: string; style: string; status: string };
 
 /** Pure decision for the font-load wait: given the current `document.fonts` entries, return the
- *  families that are DECLARED (an @font-face exists for them) but not yet `"loaded"`. A family is
- *  considered pending while ANY of its faces is still `"unloaded"` or `"loading"`; a face that
- *  `"error"`ed is treated as terminal (it will never load, so waiting longer is pointless — it is
- *  not reported as pending). Empty return ⇒ every declared face has reached a terminal state and
- *  the DOM may be measured. The check is state-based (not time-based), so the caller's poll is
- *  deterministic: it ends the instant this returns empty, regardless of wall-clock timing. */
+ *  families that are DECLARED (an @font-face exists for them) and still actively `"loading"`. Only
+ *  `"loading"` is pending: browsers lazy-load faces, so after `document.fonts.ready` a face the
+ *  rendered text actually needs is already fetching (`"loading"`), while a face left `"unloaded"`
+ *  is by definition unreferenced by any rendered text and will never load on its own — waiting on
+ *  it just burns the cap. `"loaded"`/`"error"` are terminal. Empty return ⇒ no face is still
+ *  fetching and the DOM may be measured. The check is state-based (not time-based), so the caller's
+ *  poll is deterministic: it ends the instant this returns empty, regardless of wall-clock timing. */
 export function pendingFontFamilies(faces: FontFaceStatus[]): string[] {
   const pending = new Set<string>();
-  const terminalByFamily = new Map<string, boolean>();
   for (const f of faces) {
     const fam = f.family.replace(/^["']|["']$/g, "");
-    if (f.status === "loaded" || f.status === "error") {
-      if (!terminalByFamily.has(fam)) terminalByFamily.set(fam, true);
-    } else {
-      // "unloaded" | "loading" (or any non-terminal state) ⇒ this family is still pending.
-      pending.add(fam);
-      terminalByFamily.set(fam, false);
-    }
+    // Only a face still actively fetching keeps its family pending; "unloaded" (unreferenced),
+    // "loaded", and "error" are all non-blocking.
+    if (f.status === "loading") pending.add(fam);
   }
   return [...pending].sort();
 }
 
-/** In-page: await `document.fonts.ready`, then poll (bounded) until every declared @font-face has
- *  reached a terminal state (`loaded`/`error`). Returns the still-pending families when the bound
- *  expired, or an empty array once all faces settled. Runs entirely inside the browser context so
- *  it reads the live FontFaceSet. Bounded + state-based ⇒ deterministic (ends on state, never on a
- *  fixed sleep). `capMs` is a hard ceiling so a hung/erroring font request can't stall the render. */
+/** Declared @font-face faces left `"unloaded"` after the wait bound: not fetched because no
+ *  rendered text resolves to them (unreferenced weight/style/unicode-subset siblings). Reported
+ *  per-face (family+weight+style) for an informational-only log — these are benign, never a
+ *  fidelity problem, since the text that IS measured renders in the face that actually loaded. */
+export function unreferencedFontFaces(faces: FontFaceStatus[]): FontFaceStatus[] {
+  return faces
+    .filter((f) => f.status === "unloaded")
+    .map((f) => ({ family: f.family.replace(/^["']|["']$/g, ""), weight: f.weight, style: f.style, status: f.status }))
+    .sort((a, b) => `${a.family} ${a.weight} ${a.style}`.localeCompare(`${b.family} ${b.weight} ${b.style}`));
+}
+
+/** In-page: await `document.fonts.ready`, then poll (bounded) until no declared @font-face is still
+ *  `"loading"`. Browsers lazy-load faces, so once ready has fired the faces the rendered text needs
+ *  are already fetching; the poll only waits on those. Returns `{ pending, unreferenced }`: `pending`
+ *  = families whose face was STILL `"loading"` when the bound expired (a genuinely stuck fetch, kept
+ *  as a warning); `unreferenced` = faces left `"unloaded"` (declared but no rendered text resolves to
+ *  them — benign, surfaced per-face for an informational log only). Runs entirely inside the browser
+ *  context so it reads the live FontFaceSet. Bounded + state-based ⇒ deterministic (ends on state,
+ *  never on a fixed sleep). `capMs` is a hard ceiling so a hung font request can't stall the render. */
 async function awaitFontsLoaded(
   page: import("playwright").Page,
   opts?: { capMs?: number; pollMs?: number },
-): Promise<string[]> {
+): Promise<{ pending: string[]; unreferenced: FontFaceStatus[] }> {
   const capMs = opts?.capMs ?? 3000;
   const pollMs = opts?.pollMs ?? 50;
   try {
@@ -308,36 +318,42 @@ async function awaitFontsLoaded(
       async ({ capMs, pollMs }) => {
         const doc = document as Document;
         const set = doc.fonts as unknown as { ready?: Promise<unknown>; forEach?: (cb: (f: FontFaceStatus) => void) => void } | undefined;
-        if (!set) return [];
+        if (!set) return { pending: [], unreferenced: [] };
         const snapshot = (): { family: string; weight: string; style: string; status: string }[] => {
           const out: { family: string; weight: string; style: string; status: string }[] = [];
           set.forEach?.((f) => out.push({ family: f.family, weight: f.weight, style: f.style, status: f.status }));
           return out;
         };
+        // Only a face still actively fetching is pending; "unloaded" is unreferenced (never fetched).
         const pending = (faces: { family: string; weight: string; style: string; status: string }[]): string[] => {
           const p = new Set<string>();
           for (const f of faces) {
-            const fam = f.family.replace(/^["']|["']$/g, "");
-            if (f.status !== "loaded" && f.status !== "error") p.add(fam);
+            if (f.status === "loading") p.add(f.family.replace(/^["']|["']$/g, ""));
           }
           return [...p].sort();
         };
         // First give the browser's own aggregate signal a chance (bounded — a hung request must not
-        // hold ready forever). Then poll the per-face states until all terminal or the cap expires.
+        // hold ready forever). Then poll the per-face states until none are loading or the cap expires.
         await Promise.race([set.ready ?? Promise.resolve(), new Promise((r) => setTimeout(r, capMs))]);
         const deadline = Date.now() + capMs;
         // eslint-disable-next-line no-constant-condition
         while (true) {
-          const left = pending(snapshot());
-          if (left.length === 0) return [];
-          if (Date.now() >= deadline) return left;
+          const faces = snapshot();
+          const left = pending(faces);
+          const done = left.length === 0 || Date.now() >= deadline;
+          if (done) {
+            const unreferenced = faces
+              .filter((f) => f.status === "unloaded")
+              .map((f) => ({ family: f.family.replace(/^["']|["']$/g, ""), weight: f.weight, style: f.style, status: f.status }));
+            return { pending: left, unreferenced };
+          }
           await new Promise((r) => setTimeout(r, pollMs));
         }
       },
       { capMs, pollMs },
-    ) as string[];
+    ) as { pending: string[]; unreferenced: FontFaceStatus[] };
   } catch {
-    return []; // a page without a FontFaceSet (or an evaluate fault) never blocks the walk
+    return { pending: [], unreferenced: [] }; // no FontFaceSet (or an evaluate fault) never blocks the walk
   }
 }
 
@@ -430,12 +446,19 @@ export async function renderApp(opts: {
         // fallback face (systematically narrower/wider glyphs → a bogus size delta attributed to the
         // clone). Await document.fonts.ready AND poll (bounded, state-based) until every declared face
         // is terminal, so this holds for both the walk below and the screenshot further down.
-        const pendingFonts = await awaitFontsLoaded(page);
+        const { pending: pendingFonts, unreferenced: unrefFaces } = await awaitFontsLoaded(page);
         if (pendingFonts.length) {
-          const msg = `font-wait: ${pendingFonts.length} @font-face families unloaded after wait bound at ${vw}px: ${pendingFonts.join(", ")}`;
+          const msg = `font-wait: ${pendingFonts.length} @font-face families still loading after wait bound at ${vw}px: ${pendingFonts.join(", ")}`;
           fontWarnings.push(msg);
           console.warn(`[render] ${msg}`);
         }
+        // Declared-but-unreferenced faces (no rendered text resolves to them) are benign — the
+        // browser never fetched them by design. Report them per-face (family+weight+style) as an
+        // informational log only; they are NOT a fidelity warning and never enter fontWarnings.
+        if (unrefFaces.length) {
+          const detail = unrefFaces.map((f) => `${f.family} ${f.weight} ${f.style}`).join(", ");
+          console.log(`[render] font-info: ${unrefFaces.length} declared-but-unreferenced faces at ${vw}px: ${detail}`);
+        }
         // Scroll to settle any lazy effects, then back to top.
         await page.evaluate(async () => {
           const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
diff --git a/compiler/src/validate/validate.ts b/compiler/src/validate/validate.ts
index 070df00..8f4c577 100644
--- a/compiler/src/validate/validate.ts
+++ b/compiler/src/validate/validate.ts
@@ -28,6 +28,21 @@ export function probeWidthsFor(viewports: number[]): number[] {
   const widest = sorted[sorted.length - 1] ?? 1920;
   return [...mids, Math.round(widest * 4 / 3)];
 }
+/** True if the URL of an aborted `/assets/` fetch resolves to a real file under the served export.
+ *  Mirrors `serveStatic`'s path mapping (path segment joined onto the served root, `..` stripped) so
+ *  an aborted srcset candidate whose file is present on disk is not mistaken for a 404. A URL we
+ *  cannot parse, or one whose file is absent, is treated as a genuine miss (returns false). */
+export function servedAssetExists(servedRoot: string, url: string): boolean {
+  let pathname: string;
+  try {
+    pathname = new URL(url).pathname;
+  } catch {
+    return false;
+  }
+  const rel = decodeURIComponent(pathname).replace(/^(\.\.[/\\])+/, "").replace(/^\/+/, "");
+  return existsSync(join(servedRoot, rel));
+}
+
 import { buildReport, reportToMarkdown, type Report } from "./report.js";
 import { readJSON, writeJSON, writeText, ensureDir, fileExists } from "../util/fsx.js";
 import type { CaptureResult } from "../capture/capture.js";
@@ -136,12 +151,21 @@ export async function validateRun(runDir: string, opts?: { harnessDir?: string;
       await server.close();
     }
   }
-  // Video/audio elements stream and their requests are aborted ("failed") when the
-  // render snapshot is taken before the stream finishes — the file is materialized,
-  // so this is not an asset failure. Only count non-streaming assets.
-  const assetFailed = failedResources.filter(
-    (f) => f.includes("/assets/") && !/\.(mp4|webm|mov|m4v|ogv|ogg|mp3|wav|m3u8)(\?|$)/i.test(f),
-  );
+  // A generated asset ref is only a real failure if the file it points to is genuinely
+  // missing from the served export. Two aborts are NOT failures even though Chromium logs
+  // them as "failed": (a) video/audio streams aborted when the render snapshot is taken
+  // before the stream finishes; (b) responsive-image <source srcset> candidates whose
+  // in-flight low-priority fetch is aborted when the page closes or the candidate is
+  // re-chosen — the image analogue of (a). So count an /assets/ entry only when it is a
+  // real HTTP >= 400 response, OR a "failed " (aborted) entry whose target file is actually
+  // absent from the served out/ dir. Genuine 404s (file missing) still fail.
+  const assetFailed = failedResources.filter((f) => {
+    if (!f.includes("/assets/")) return false;
+    if (/\.(mp4|webm|mov|m4v|ogv|ogg|mp3|wav|m3u8)(\?|$)/i.test(f)) return false; // streaming media (a)
+    if (!f.startsWith("failed ")) return true; // "<status> <url>" — a real >= 400 response, always count
+    // Aborted fetch (b): excuse it if the file exists under the served export, else it is a real miss.
+    return build.outDir ? !servedAssetExists(build.outDir, f.slice("failed ".length)) : true;
+  });
   const artifactsPresent = ["manifest.json", "sections.json", "tokens.json", "assets.json", "fonts.json"].every((f) => fileExists(join(generatedDir, f)));
   const gate0Issues: string[] = [];
   if (!build.ok) gate0Issues.push("build failed: " + build.stderr.split("\n").filter(Boolean).slice(-3).join(" | "));
diff --git a/compiler/test/gates.test.ts b/compiler/test/gates.test.ts
index ef70c2e..616b844 100644
--- a/compiler/test/gates.test.ts
+++ b/compiler/test/gates.test.ts
@@ -1,6 +1,12 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { letterSpacingEquivalent, normHref, countVisibleInCaptureHiddenInClone } from "../src/validate/gates.js";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { letterSpacingEquivalent, normHref, countVisibleInCaptureHiddenInClone, gate2Assets } from "../src/validate/gates.js";
+import { servedAssetExists } from "../src/validate/validate.js";
+import type { AssetGraph } from "../src/infer/assets.js";
+import type { FontGraph } from "../src/infer/fonts.js";
 import type { IR, IRNode } from "../src/normalize/ir.js";
 import type { PageSnapshot } from "../src/capture/walker.js";
 
@@ -132,3 +138,51 @@ describe("countVisibleInCaptureHiddenInClone diagnostic", () => {
     assert.equal(countVisibleInCaptureHiddenInClone(ir, gen, [375]), 0);
   });
 });
+
+// FIX 3 — an aborted srcset-candidate image fetch (requestfailed, file present on disk) must not be
+// counted as a "404" asset failure. servedAssetExists maps a failed URL to a file under the served
+// export exactly as serveStatic does; the assetFailed filter in validate.ts uses it to excuse
+// aborted fetches whose file exists, while genuine misses (>= 400, or file absent) still fail.
+describe("servedAssetExists (FIX 3 aborted-image excuse)", () => {
+  const root = mkdtempSync(join(tmpdir(), "served-out-"));
+  mkdirSync(join(root, "assets", "cloned", "images"), { recursive: true });
+  writeFileSync(join(root, "assets", "cloned", "images", "present.webp"), "RIFFxxxxWEBP");
+
+  it("resolves a URL to a present file under the served root", () => {
+    assert.equal(servedAssetExists(root, "http://127.0.0.1:5000/assets/cloned/images/present.webp"), true);
+  });
+
+  it("returns false when the file is absent from the served root (a genuine miss)", () => {
+    assert.equal(servedAssetExists(root, "http://127.0.0.1:5000/assets/cloned/images/absent.webp"), false);
+  });
+
+  it("ignores query strings when resolving to disk", () => {
+    assert.equal(servedAssetExists(root, "http://127.0.0.1:5000/assets/cloned/images/present.webp?206w"), true);
+  });
+
+  it("does not escape the served root via .. traversal", () => {
+    assert.equal(servedAssetExists(root, "http://127.0.0.1:5000/../../../etc/passwd"), false);
+  });
+
+  it("an unparseable URL is treated as a genuine miss", () => {
+    assert.equal(servedAssetExists(root, "not-a-url"), false);
+  });
+});
+
+describe("gate2Assets failed-asset message (FIX 3)", () => {
+  const emptyAssets: AssetGraph = { entries: [], byUrl: new Map() };
+  const emptyFonts: FontGraph = { entries: [], css: "" };
+
+  it("passes when no generated asset refs are missing", () => {
+    const r = gate2Assets(emptyAssets, emptyFonts, { remoteRefs: [], failed404: [] });
+    assert.equal(r.pass, true);
+    assert.equal(r.metrics.failed404, 0);
+  });
+
+  it("fails and reports missing refs (not '404') when a genuine miss is passed", () => {
+    const r = gate2Assets(emptyAssets, emptyFonts, { remoteRefs: [], failed404: ["failed http://127.0.0.1:5000/assets/cloned/images/absent.webp"] });
+    assert.equal(r.pass, false);
+    assert.equal(r.metrics.failed404, 1);
+    assert.ok(r.issues.some((i) => i.includes("generated asset refs missing")), `expected 'missing' wording, got: ${r.issues.join(" | ")}`);
+  });
+});
diff --git a/compiler/test/serveRange.test.ts b/compiler/test/serveRange.test.ts
index fdcc6d9..c5eb342 100644
--- a/compiler/test/serveRange.test.ts
+++ b/compiler/test/serveRange.test.ts
@@ -3,7 +3,7 @@ import assert from "node:assert/strict";
 import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { serveStatic, parseRangeHeader, pendingFontFamilies, type FontFaceStatus } from "../src/validate/render.js";
+import { serveStatic, parseRangeHeader, pendingFontFamilies, unreferencedFontFaces, type FontFaceStatus } from "../src/validate/render.js";
 
 // ---- Pure helper: parseRangeHeader ----
 describe("parseRangeHeader", () => {
@@ -55,7 +55,10 @@ describe("parseRangeHeader", () => {
 // ---- Pure helper: pendingFontFamilies (the font-load wait decision) ----
 // The render walk must run after webfonts are APPLIED, else text boxes measure the fallback face
 // (a systematic width delta wrongly attributed to the clone). This helper is the state-based (not
-// time-based) predicate the in-page poll ends on: it returns the DECLARED families not yet terminal.
+// time-based) predicate the in-page poll ends on: it returns the DECLARED families still actively
+// fetching. Browsers lazy-load faces, so after document.fonts.ready a face the rendered text needs
+// is already "loading"; a face left "unloaded" is unreferenced and will never load on its own —
+// waiting on it only burns the cap, so ONLY "loading" is pending.
 describe("pendingFontFamilies", () => {
   const face = (family: string, status: string, weight = "400", style = "normal"): FontFaceStatus => ({ family, weight, style, status });
 
@@ -67,8 +70,8 @@ describe("pendingFontFamilies", () => {
     assert.deepEqual(pendingFontFamilies([face("Avenir", "loaded"), face("Inter", "loaded")]), []);
   });
 
-  it("an unloaded face makes its family pending", () => {
-    assert.deepEqual(pendingFontFamilies([face("Avenir", "unloaded")]), ["Avenir"]);
+  it("an unloaded face is unreferenced (lazy-load) → NOT pending", () => {
+    assert.deepEqual(pendingFontFamilies([face("Avenir", "unloaded")]), []);
   });
 
   it("a loading face makes its family pending", () => {
@@ -79,27 +82,63 @@ describe("pendingFontFamilies", () => {
     assert.deepEqual(pendingFontFamilies([face("Avenir", "error")]), []);
   });
 
-  it("a family with mixed weights is pending if ANY weight is not terminal", () => {
+  it("a family is pending if ANY weight is still loading", () => {
     const faces = [face("Avenir", "loaded", "400"), face("Avenir", "loading", "700")];
     assert.deepEqual(pendingFontFamilies(faces), ["Avenir"]);
   });
 
+  it("a partially-used family (used face loaded, sibling faces unloaded) is NOT pending", () => {
+    // The real-world false positive this fix removes: a matched face loaded, unreferenced
+    // weight/style siblings stay "unloaded" — the walk may proceed without waiting on them.
+    const faces = [face("Avenir", "loaded", "400"), face("Avenir", "unloaded", "700"), face("Avenir", "unloaded", "400", "italic")];
+    assert.deepEqual(pendingFontFamilies(faces), []);
+  });
+
   it("a family whose faces are all terminal (loaded or errored) is not pending", () => {
     const faces = [face("Avenir", "loaded", "400"), face("Avenir", "error", "700")];
     assert.deepEqual(pendingFontFamilies(faces), []);
   });
 
-  it("strips surrounding quotes from the reported family name and dedupes+sorts", () => {
-    const faces = [face('"Source Serif"', "unloaded"), face("Avenir", "loading"), face("Avenir", "unloaded")];
+  it("strips surrounding quotes from the reported family name and dedupes+sorts (loading only)", () => {
+    const faces = [face('"Source Serif"', "loading"), face("Avenir", "loading"), face("Avenir", "unloaded")];
     assert.deepEqual(pendingFontFamilies(faces), ["Avenir", "Source Serif"]);
   });
 
-  it("only the unloaded families are returned when some are loaded", () => {
-    const faces = [face("Inter", "loaded"), face("Avenir", "unloaded"), face("JetBrains", "loaded")];
+  it("only the still-loading families are returned when some are loaded/unloaded", () => {
+    const faces = [face("Inter", "loaded"), face("Avenir", "loading"), face("JetBrains", "unloaded")];
     assert.deepEqual(pendingFontFamilies(faces), ["Avenir"]);
   });
 });
 
+// ---- Pure helper: unreferencedFontFaces (informational-only per-face report) ----
+// Faces left "unloaded" after the wait bound: declared but no rendered text resolves to them.
+// Reported per-face (family+weight+style) for an informational log; benign, never a fidelity issue.
+describe("unreferencedFontFaces", () => {
+  const face = (family: string, status: string, weight = "400", style = "normal"): FontFaceStatus => ({ family, weight, style, status });
+
+  it("returns only the unloaded faces (not loaded/loading/error)", () => {
+    const faces = [face("Avenir", "loaded"), face("Merriweather", "unloaded", "700"), face("Inter", "loading"), face("Gotham", "error")];
+    assert.deepEqual(unreferencedFontFaces(faces), [{ family: "Merriweather", weight: "700", style: "normal", status: "unloaded" }]);
+  });
+
+  it("reports per-face (family+weight+style), not collapsed per-family, and strips quotes + sorts", () => {
+    const faces = [
+      face('"Merriweather"', "unloaded", "700", "normal"),
+      face("Merriweather", "unloaded", "300", "italic"),
+      face("Avenir", "unloaded", "400", "normal"),
+    ];
+    assert.deepEqual(unreferencedFontFaces(faces), [
+      { family: "Avenir", weight: "400", style: "normal", status: "unloaded" },
+      { family: "Merriweather", weight: "300", style: "italic", status: "unloaded" },
+      { family: "Merriweather", weight: "700", style: "normal", status: "unloaded" },
+    ]);
+  });
+
+  it("no unloaded faces → empty", () => {
+    assert.deepEqual(unreferencedFontFaces([face("Avenir", "loaded"), face("Inter", "loading")]), []);
+  });
+});
+
 // ---- Integration: serveStatic answers real Range requests with 206/416 ----
 describe("serveStatic Range support (integration)", () => {
   let rootDir = "";

From 3f0757dc23be2b6292437c89bfb2e917d7e9c7b0 Mon Sep 17 00:00:00 2001
From: Samraaj Bath <samraaj100@gmail.com>
Date: Sat, 4 Jul 2026 07:14:34 -0700
Subject: [PATCH 21/24] Snap percent widths up for content-fit-sensitive boxes

Round-to-nearest 0.5% could land a nowrap flex row's width fractionally
below its intrinsic content width, wrapping it to two lines. When the
sizing probe shows a box painting at its max-content width with no slack,
the snap now ceils to the next step; all other boxes keep nearest
rounding, and the existing reproduce-verification still bails the plan on
any overshoot.

460 tests pass (2 new), typecheck clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 compiler/src/generate/css.ts | 21 +++++++++--
 compiler/test/css.test.ts    | 73 ++++++++++++++++++++++++++++++++++++
 2 files changed, 91 insertions(+), 3 deletions(-)

diff --git a/compiler/src/generate/css.ts b/compiler/src/generate/css.ts
index d6f87b0..92e3c58 100644
--- a/compiler/src/generate/css.ts
+++ b/compiler/src/generate/css.ts
@@ -1559,7 +1559,7 @@ function fillsToCapWidth(node: IRNode, parentNode: IRNode | undefined, viewports
  *  margins (those make the width load-bearing). */
 function fluidPercentByVp(node: IRNode, parentNode: IRNode | undefined, viewports: number[]): Record<number, string> | null {
   if (!parentNode || REPLACED.has(node.tag) || node.tag.includes("-")) return null;
-  type S = { vp: number; ratio: number; container: number; w: number; flexRow: boolean };
+  type S = { vp: number; ratio: number; container: number; w: number; flexRow: boolean; wMin?: number; wMax?: number };
   const samples: S[] = [];
   for (const vp of viewports) {
     const cs = node.computedByVp[vp]; const pcs = parentNode.computedByVp[vp];
@@ -1592,7 +1592,8 @@ function fluidPercentByVp(node: IRNode, parentNode: IRNode | undefined, viewport
     const ratio = nb.width / container;
     if (!(ratio > 0.04 && ratio < 1.02)) return null;                   // not a clean fraction of the container
     const flexRow = /(?:^|-)flex$/.test(pdisp) && /^(row|row-reverse)$/.test(pcs.flexDirection || "row");
-    samples.push({ vp, ratio, container, w: nb.width, flexRow });
+    const sz = node.sizingByVp?.[vp];
+    samples.push({ vp, ratio, container, w: nb.width, flexRow, wMin: sz?.wMin, wMax: sz?.wMax });
   }
   if (samples.length < 2) return null;
   const ws = samples.map((s) => s.w);
@@ -1618,7 +1619,21 @@ function fluidPercentByVp(node: IRNode, parentNode: IRNode | undefined, viewport
   // Each sample is a clean fraction that reproduces its captured px. Snap to 0.5% and verify.
   const out: Record<number, string> = {};
   for (const s of samples) {
-    const pct = Math.round(s.ratio * 200) / 2;                          // nearest 0.5%
+    // Default: nearest 0.5% (no geometry churn for ordinary boxes). But a CONTENT-FIT box — one sitting
+    // at its own max-content width (a nowrap pill: captured w ≈ wMax, and genuinely wrappable so wMin <
+    // wMax) — has NO slack: rounding the % DOWN emits a width below its intrinsic content, and the clone
+    // wraps it onto a second line (task #26: a 71.70% pill → 71.5% → 245.24px < 245.94px content → wrap,
+    // +23.5px section). For such a node snap UP (ceil to the 0.5% step) only when the nearest-rounded px
+    // falls below wMax by more than 0.25px, so the emitted width never lands short of the content it must
+    // hold. All other nodes keep round-to-nearest.
+    const nearest = Math.round(s.ratio * 200) / 2;
+    let pct = nearest;
+    const wMax = s.wMax, wMin = s.wMin;
+    const contentFit = wMax != null && wMin != null && wMin < wMax - 2 &&
+      Math.abs(s.w - wMax) <= Math.max(1.5, 0.01 * wMax);
+    if (contentFit && (nearest / 100) * s.container < wMax! - 0.25) {
+      pct = Math.ceil(s.ratio * 200) / 2;                               // snap UP to clear intrinsic content width
+    }
     if (Math.abs((pct / 100) * s.container - s.w) > Math.max(1.5, 0.01 * s.w)) return null;
     out[s.vp] = `${pct}%`;
   }
diff --git a/compiler/test/css.test.ts b/compiler/test/css.test.ts
index 89e778a..28d2a03 100644
--- a/compiler/test/css.test.ts
+++ b/compiler/test/css.test.ts
@@ -775,6 +775,79 @@ describe("generateCss content-sized flex row (probe veto for wrapping text)", ()
   });
 });
 
+describe("generateCss fluid percent snap-up for content-fit nowrap pill (task #26)", () => {
+  // A nowrap flex pill, sole child of a flex COLUMN, that paints at its own max-content width
+  // (bbox.width == wMax) at every viewport — a load-bearing % width that, rounded to the nearest
+  // 0.5%, lands BELOW the intrinsic content and wraps to a second line. Real evidence: a footer
+  // pill 245.94px in a 343px column at 375 (71.70% → 71.5% → 245.24px < 245.94 → wrap).
+  // Numbers below are the captured run's (375 / 768 / 1280).
+  // Per-vp pill widths mirror the real run: at 768 the column is narrower than the pill's content, so
+  // the pill shrinks to fill it (221.33 == container); at 375/1280 it sits at its max-content (245.94).
+  // A CONSTANT max-content across vps keeps contentSizedColumnItem from firing (its widths don't vary),
+  // so the width falls through to the fluid-percent (percentVp) path — exactly the real code path.
+  const wMax = 245.94;
+  function pillIn(colWidths: [number, number, number], wMinOrWMax: { wMin: number; wMax: number }) {
+    const pillW: Record<number, number> = { 375: 245.94, 768: 221.33, 1280: 245.94 };
+    const sz = (): RawSizing => ({ wAuto: false, wFill: false, hAuto: true, hFill: true, ...wMinOrWMax });
+    const pill = xNode("n1", "a", {
+      375: { cs: { display: "flex", whiteSpace: "nowrap" }, bbox: { x: 0, y: 0, width: pillW[375]!, height: 40 }, sizing: sz() },
+      768: { cs: { display: "flex", whiteSpace: "nowrap" }, bbox: { x: 0, y: 0, width: pillW[768]!, height: 40 }, sizing: sz() },
+      1280: { cs: { display: "flex", whiteSpace: "nowrap" }, bbox: { x: 0, y: 0, width: pillW[1280]!, height: 40 }, sizing: sz() },
+    }, [{ text: "Certified B Corporation" }]);
+    return xNode("n0", "body", {
+      375: { cs: { display: "flex", flexDirection: "column" }, bbox: { x: 0, y: 0, width: colWidths[0], height: 40 } },
+      768: { cs: { display: "flex", flexDirection: "column" }, bbox: { x: 0, y: 0, width: colWidths[1], height: 40 } },
+      1280: { cs: { display: "flex", flexDirection: "column" }, bbox: { x: 0, y: 0, width: colWidths[2], height: 40 } },
+    }, [pill]);
+  }
+
+  /** Collect every emitted `width:N%` for `id` across the base rule and all @media bands. */
+  function emittedPercents(css: string, id: string) {
+    const bodies: string[] = [];
+    // base rule
+    const base = css.match(new RegExp(`\\.c${id}\\{([^}]*)\\}`));
+    if (base) bodies.push(base[1]!);
+    // banded rules
+    for (const m of css.matchAll(/@media ([^{]+) \{\n([\s\S]*?)\n\}/g)) {
+      const r = m[2]!.match(new RegExp(`\\.c${id}\\{([^}]*)\\}`));
+      if (r) bodies.push(r[1]!);
+    }
+    const pcts: number[] = [];
+    for (const b of bodies) {
+      const w = b.match(/width:([\d.]+)%/);
+      if (w) pcts.push(parseFloat(w[1]!));
+    }
+    return { pcts, bodies };
+  }
+
+  it("snaps the percent UP so the emitted width never lands below the pill's content (no wrap)", () => {
+    // 245.94 in 343 → 71.70% (nearest 71.5% = 245.24 < wMax); in 392 → 62.74% (nearest 62.5% = 245.0 < wMax).
+    const css = generateCss(xIr(pillIn([343, 221.33, 392], { wMin: 189.72, wMax })), new Map());
+    const { pcts } = emittedPercents(css, "n1");
+    assert.ok(pcts.length > 0, `pill should carry a fluid width:%, got none`);
+    // Every emitted % must clear the content width against the vp where it applies. The two content-
+    // fit viewports are 343 (71.70% band) and 392 (62.74% band); resolve each candidate % and require
+    // at least the 343-container % ≥ 245.94.
+    const at343 = pcts.filter((p) => Math.abs((p / 100) * 343 - 245.94) <= 3);
+    assert.ok(at343.some((p) => (p / 100) * 343 >= 245.94 - 0.01),
+      `375 pill % must resolve ≥ 245.94px in a 343px column, got pcts=${pcts.join(",")} → ${at343.map((p) => ((p / 100) * 343).toFixed(2)).join(",")}px`);
+    // Nearest-rounding would have emitted 71.5% (= 245.24). Assert the fix bumped it up to 72%.
+    assert.ok(pcts.includes(72) || pcts.some((p) => (p / 100) * 343 >= 245.94),
+      `expected snap-UP to 72% (246.96px), got ${pcts.join(",")}`);
+  });
+
+  it("keeps round-to-NEAREST for an ordinary box comfortably inside its container (no churn)", () => {
+    // Same geometry but NOT content-fit: bbox 245.94 sits well below wMax (400), so there is slack —
+    // wrapping can't happen, and the default nearest rounding (71.5%) must be preserved.
+    const rootPill = pillIn([343, 221.33, 392], { wMin: 100, wMax: 400 });
+    const css2 = generateCss(xIr(rootPill), new Map());
+    const { pcts } = emittedPercents(css2, "n1");
+    // 71.70% and 62.74% both round to nearest (71.5%, 63.0%... actually 62.74→62.5) — assert 71.5 present.
+    assert.ok(pcts.includes(71.5), `an ordinary box must keep nearest rounding (71.5%), got ${pcts.join(",")}`);
+    assert.ok(!pcts.includes(72), `an ordinary box must NOT be bumped up to 72%, got ${pcts.join(",")}`);
+  });
+});
+
 // Defect C (generate side) — a CSS marquee (infinite `@keyframes` animation) gated to a breakpoint
 // (Webflow's `max-lg` logo/text tracks) is `animation:none` at the base but runs at the narrow band.
 // The per-band transform delta at the animated width is a FROZEN mid-scroll phase; it must be

From d56fbbe45e8d78319696a02b3e30dcf7df6939bd Mon Sep 17 00:00:00 2001
From: Samraaj Bath <samraaj100@gmail.com>
Date: Sat, 4 Jul 2026 07:26:55 -0700
Subject: [PATCH 22/24] Per-viewport DOM divergence: graft non-canonical-only
 children, drift stand-in policy

The IR's canonical tree came from one viewport, so DOM that exists only
at other widths (mobile-only pagination bullets, per-viewport product
sets) either vanished or left empty display:none shells.

- Unmatched children at non-canonical viewports graft into the IR at
  deterministic anchored positions with per-viewport data scoped to their
  source widths; emission gives them a base hide plus a reveal band
  (hidden max-[...]:block), capped per parent, invisible subtrees skipped
- Whole-set identity drift (a container serving disjoint same-family
  child sets per viewport) is detected by mutual mismatch; canonical
  content stands in at the drift viewport instead of an empty shell, and
  manifest.json records the divergence
- Per-item divergence resolves naturally via grafting: each viewport
  shows exactly its captured content, mutually exclusive by banding

468 tests pass (8 new), typecheck clean, double-build byte-identical.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 compiler/src/generate/css.ts        |  34 ++++-
 compiler/src/generate/manifest.ts   |   7 +
 compiler/src/normalize/ir.ts        | 175 +++++++++++++++++++++-
 compiler/test/viewportGraft.test.ts | 219 ++++++++++++++++++++++++++++
 4 files changed, 428 insertions(+), 7 deletions(-)
 create mode 100644 compiler/test/viewportGraft.test.ts

diff --git a/compiler/src/generate/css.ts b/compiler/src/generate/css.ts
index 92e3c58..650ed50 100644
--- a/compiler/src/generate/css.ts
+++ b/compiler/src/generate/css.ts
@@ -3375,7 +3375,7 @@ export function collectNodeRules(ir: IR, assetMap: Map<string, string>, includeN
   // per line so the line's free space — and thus sibling positions — is unchanged.
   const autoWidthFlex = new Set<string>();
 
-  const walk = (node: IRNode, parentNode: IRNode | undefined, parentFluid: boolean, layoutParent: IRNode | undefined, cbAncestor: IRNode | undefined, parentDefiniteHeight: boolean): void => {
+  const walk = (node: IRNode, parentNode: IRNode | undefined, parentFluid: boolean, layoutParent: IRNode | undefined, cbAncestor: IRNode | undefined, parentDefiniteHeight: boolean, standInVps: ReadonlySet<number> | null = null): void => {
     // Full-bleed fluidity propagates as a CONTIGUOUS chain from the root: a node is fluid
     // only if its containing block is also fluid — otherwise width:auto fills a fixed-width
     // ancestor instead of the viewport (a full-bleed row inside a fixed 1280 wrapper would
@@ -3618,7 +3618,23 @@ export function collectNodeRules(ir: IR, assetMap: Map<string, string>, includeN
     // gated to a breakpoint owns the transform only where it runs, but freezes a mid-scroll offset
     // at the OTHER bands — suppress those frozen deltas at every width).
     const animOwned = animOwnedProps(node, [baseVp, ...bands.map((b) => b.vp)]);
-    const baseDecls = finalizeDecls(declsForViewport(node, parentNode?.computedByVp[baseVp], baseVp, assetMap, centeredBase, colorVar, ir.doc.perViewport[baseVp]?.scrollHeight, widthPlan, gridColsByVp?.get(baseVp), gridRowsByVp?.get(baseVp), flowH, dropInsets, leftPct, heightFill, geometry, dropGridRows, dropViewportMaxWidth, nowrapText, keepIdentityTransform, sourceFixedHeight), tokenResolver);
+    let baseDecls = finalizeDecls(declsForViewport(node, parentNode?.computedByVp[baseVp], baseVp, assetMap, centeredBase, colorVar, ir.doc.perViewport[baseVp]?.scrollHeight, widthPlan, gridColsByVp?.get(baseVp), gridRowsByVp?.get(baseVp), flowH, dropInsets, leftPct, heightFill, geometry, dropGridRows, dropViewportMaxWidth, nowrapText, keepIdentityTransform, sourceFixedHeight), tokenResolver);
+    // A node GRAFTED into the IR from a non-canonical capture (it does not exist in the canonical
+    // DOM, so it has no computed style at the base viewport → declsForViewport yields nothing).
+    // Its base rule must take it out of layout entirely; each band where it WAS observed then
+    // emits its full per-viewport decls as the delta (display is always emitted, so the band
+    // override both reveals and lays it out — the inverse of the canonical-only display:none band).
+    const absentAtBase = !node.computedByVp[baseVp];
+    if (absentAtBase) baseDecls = new Map([["display", "none"]]);
+    // Viewports where this node STANDS IN for divergent source content (content-identity drift on
+    // an ancestor): it has no captured data there, but the drift policy shows the canonical subtree
+    // instead of an empty shell — so its per-band hide must be skipped at those widths, and the
+    // stand-in state propagates to its descendants (they lack per-viewport data there too).
+    let driftStandIn: Set<number> | null = standInVps ? new Set([...standInVps].filter((vp) => !node.computedByVp[vp])) : null;
+    for (const vp of parentNode?.childDriftVps ?? []) {
+      if (!node.computedByVp[vp]) (driftStandIn ??= new Set()).add(vp);
+    }
+    if (driftStandIn && driftStandIn.size === 0) driftStandIn = null;
     const nr: NodeRule = { base: baseDecls, bands: [] };
 
     // Per-band overrides (delta vs base), using the parent's value AT THAT viewport.
@@ -3626,7 +3642,17 @@ export function collectNodeRules(ir: IR, assetMap: Map<string, string>, includeN
       if (!b.media) continue;
       // Node was not in the observed DOM at this width (responsive conditional
       // rendering): hide it so the clone matches the source at this viewport.
-      if (!node.computedByVp[b.vp]) { nr.bands.push({ media: b.media, decls: new Map([["display", "none"]]) }); continue; }
+      if (!node.computedByVp[b.vp]) {
+        // Grafted node: the base rule is already display:none — no per-band hide needed.
+        if (absentAtBase) continue;
+        // Content-identity drift (an ancestor's children were a wholly different set at this
+        // width): banding every canonical child display:none would render an EMPTY shell where
+        // the source showed content. Faithful-at-canonical: skip the hide and let the base
+        // (canonical) subtree stand in for the divergent set (recorded in doc.contentDrift).
+        if (driftStandIn?.has(b.vp)) continue;
+        nr.bands.push({ media: b.media, decls: new Map([["display", "none"]]) });
+        continue;
+      }
       // The node isn't PAINTED at this width. HOW it is hidden decides what to emit, because only
       // `display:none` takes the box out of layout — a `visibility:hidden` box still occupies space
       // and can extend the scrollable area. The base rule bakes CANONICAL geometry unconditionally,
@@ -3772,7 +3798,7 @@ export function collectNodeRules(ir: IR, assetMap: Map<string, string>, includeN
     }
     rules.set(node.id, nr);
 
-    for (const c of node.children) if (!isTextChild(c)) walk(c, node, childFluid, childLayoutParent, childCb, childDefiniteHeight);
+    for (const c of node.children) if (!isTextChild(c)) walk(c, node, childFluid, childLayoutParent, childCb, childDefiniteHeight, driftStandIn);
   };
   // The root's containing block is the viewport-filling <html>, so it starts the fluid chain.
   walk(ir.root, undefined, true, undefined, undefined, false);
diff --git a/compiler/src/generate/manifest.ts b/compiler/src/generate/manifest.ts
index 2eb8071..5c65b48 100644
--- a/compiler/src/generate/manifest.ts
+++ b/compiler/src/generate/manifest.ts
@@ -56,6 +56,13 @@ export function buildManifest(args: {
       fallback: fontGraph.entries.filter((f) => f.status === "fallback").length,
     },
     components: { count: componentCount },
+    // Fidelity note: containers whose children were a DIFFERENT SET at some band viewport(s)
+    // (content-identity drift — the source deterministically served other content there). The
+    // clone shows the canonical-viewport children at those widths (faithful-at-canonical) instead
+    // of an empty shell; a perceptual delta against the source at those widths is expected.
+    divergence: {
+      contentDrift: (ir.doc.contentDrift ?? []).map((d) => ({ id: d.id, tag: d.tag, viewports: d.viewports })),
+    },
     // Stage 2: capture-sanity audit — what overlays were dismissed, whether any
     // still covered the page, video stills materialized, and per-viewport quiescence.
     capture: {
diff --git a/compiler/src/normalize/ir.ts b/compiler/src/normalize/ir.ts
index 5842604..8c72bcb 100644
--- a/compiler/src/normalize/ir.ts
+++ b/compiler/src/normalize/ir.ts
@@ -6,7 +6,10 @@ import type { InteractionCapture } from "../capture/interactions.js";
 /**
  * Normalized Render IR. Merges the per-viewport capture snapshots into a single
  * tree whose structure comes from the canonical (1280) capture; each node carries
- * per-viewport computed styles, bounding boxes, and visibility. This is the single
+ * per-viewport computed styles, bounding boxes, and visibility. Children that exist
+ * ONLY at non-canonical viewports are grafted in as siblings (visible only in their
+ * source bands); a container whose children are a wholly different set at some width
+ * is recorded as content drift instead (see childDriftVps). This is the single
  * source of truth for section/token inference, generation, and validation.
  */
 
@@ -40,6 +43,14 @@ export type IRNode = {
   // ::placeholder computed style (input/textarea with placeholder text) — emitted as a
   // `::placeholder` rule so form controls keep their authored placeholder color.
   placeholderByVp?: Record<number, StyleMap>;
+  // Band viewports where this container's element children were a DIFFERENT SET than the
+  // canonical capture's (mutual whole-set mismatch — the source deterministically served
+  // different content at that width, e.g. a rotator picking other items per breakpoint).
+  // Policy: FAITHFUL-AT-CANONICAL — emission shows the canonical children there (it skips
+  // the display:none band it would otherwise emit for a child with no counterpart) instead
+  // of rendering an empty shell; the other set is NOT grafted (no duplication). Surfaced in
+  // the manifest via doc.contentDrift.
+  childDriftVps?: number[];
   children: IRChild[];
 };
 
@@ -75,6 +86,11 @@ export type IRDoc = {
   // re-emit the keyframes that the per-node `animation-name` declarations reference —
   // without these the animation properties are inert (the half-plumbed pre-Stage-5 gap).
   keyframes: string[];
+  // Containers whose children diverged as a WHOLE SET at some band viewport(s) (see
+  // IRNode.childDriftVps). Recorded post-renumber so ids are final; carried into the
+  // generated manifest as a fidelity note ("the source served different content there").
+  // Omitted when no drift was detected.
+  contentDrift?: Array<{ id: string; tag: string; viewports: number[] }>;
 };
 
 export type IR = {
@@ -419,6 +435,39 @@ function alignChildren(canon: RawNode[], other: RawNode[]): (RawNode | undefined
   return out;
 }
 
+/** True when this raw node or any element descendant painted at its capture viewport. */
+function rawSubtreeVisible(n: RawNode): boolean {
+  if (n.visible) return true;
+  for (const c of elementChildren(n)) if (rawSubtreeVisible(c)) return true;
+  return false;
+}
+
+/** Most frequent tag in a sibling group (ties broken alphabetically — deterministic). */
+function dominantTag(nodes: RawNode[]): string {
+  const counts = new Map<string, number>();
+  for (const n of nodes) counts.set(n.tag, (counts.get(n.tag) ?? 0) + 1);
+  let best = "", bestC = -1;
+  for (const [t, c] of [...counts.entries()].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+    if (c > bestC) { best = t; bestC = c; }
+  }
+  return best;
+}
+
+// A sibling appearing ONLY at non-canonical viewport(s) is grafted into the IR (visible only in
+// its source band(s)). Cap per parent per viewport so a pathological capture (a virtualized list
+// re-keying hundreds of rows) can't balloon the tree; the whole-set drift path below covers the
+// legitimate large-mismatch case.
+const GRAFT_MAX_PER_VP = 24;
+// Whole-set content-identity drift: at least this many children UNMATCHED on BOTH sides before a
+// container is treated as "the source served different content at this width" (vs a couple of
+// responsive-only extras, which are grafted instead).
+const DRIFT_MIN_UNMATCHED = 3;
+
+/** A per-parent graft group: one non-canonical-only child, matched across the non-canonical
+ *  viewports it appears at. `rep` is the raw node from the LOWEST viewport (structural identity
+ *  for aligning later viewports into the group). */
+type GraftGroup = { rep: RawNode; rawByVp: Record<number, RawNode> };
+
 /** Capture-ids of recognized-pattern panels/regions to force-keep through pruning
  *  (they are display:none in the inactive/collapsed base state). Empty when no
  *  interactions were captured, so non-interactive runs prune exactly as before. */
@@ -449,6 +498,9 @@ export function buildIR(sourceDir: string, viewports: number[], opts?: { motion?
   }
   const canonical = viewports.includes(1280) ? 1280 : viewports[Math.floor(viewports.length / 2)]!;
   const canonSnap = snapshots[canonical]!;
+  // Deterministic iteration order for the cross-viewport graft grouping below.
+  const vpsAsc = [...viewports].sort((a, b) => a - b);
+  const bandVpSet = new Set(bandVps);
 
   // Stage 4: recognized interactive panels (tabs/accordion) are often display:none
   // at base (the inactive/collapsed state). Their subtrees must survive pruning so
@@ -519,25 +571,131 @@ export function buildIR(sourceDir: string, viewports: number[], opts?: { motion?
       const canonKids = elementChildren(raw);
       // Align this node's canonical element children to each viewport's children.
       const aligned: Record<number, (RawNode | undefined)[]> = {};
+      const kidsByVp: Record<number, RawNode[]> = {};
       for (const vw of viewports) {
         if (vw === canonical) continue;
         const m = matched[vw];
         const vwKids = m && m.tag === raw.tag ? elementChildren(m) : [];
+        kidsByVp[vw] = vwKids;
         aligned[vw] = alignChildren(canonKids, vwKids);
       }
+
+      // ---- Per-viewport DOM divergence (canonical-rooted subtrees only) ----
+      // Two inverse gaps closed here:
+      //  • GRAFT: a child that exists ONLY at non-canonical viewport(s) (destroyed/never built at
+      //    the canonical width) would otherwise never enter the IR — the clone then misses it at
+      //    the widths where the source shows it (e.g. mobile-only carousel pagination bullets).
+      //    Graft it as a sibling at its source position, carrying per-viewport data ONLY for the
+      //    viewports it appeared at; emission hides it at base and reveals it in its band(s).
+      //  • DRIFT: when a container's children at some viewport are a DIFFERENT SET on BOTH sides
+      //    (mutual whole-set mismatch — the source deterministically served other content there),
+      //    grafting would duplicate the component. Prefer faithful-at-canonical: record the drift
+      //    so emission shows the canonical children there instead of banding them all display:none
+      //    (an empty shell). Recorded in childDriftVps → doc.contentDrift → the manifest.
+      const driftVps = new Set<number>();
+      const graftsByAnchor = new Map<number, GraftGroup[]>();
+      if (matched[canonical]) {
+        for (const vw of vpsAsc) {
+          if (vw === canonical) continue;
+          const vwKids = kidsByVp[vw]!;
+          if (vwKids.length === 0) continue;
+          const matchedOther = new Set<RawNode>();
+          for (const mo of aligned[vw]!) if (mo) matchedOther.add(mo);
+          const unmatchedCanon = canonKids.filter((_, i) => !aligned[vw]![i]);
+          const unmatchedOther = vwKids.filter((k) => !matchedOther.has(k));
+          // Whole-set identity drift: many unmatched on BOTH sides, few matched, and both leftover
+          // groups are the same kind of element (same dominant tag — one component family serving
+          // different items, not a structurally different widget swapped in at this width).
+          if (
+            unmatchedCanon.length >= DRIFT_MIN_UNMATCHED &&
+            unmatchedOther.length >= DRIFT_MIN_UNMATCHED &&
+            matchedOther.size * 2 < Math.min(canonKids.length, vwKids.length) &&
+            dominantTag(unmatchedCanon) === dominantTag(unmatchedOther)
+          ) {
+            driftVps.add(vw);
+            continue; // faithful-at-canonical: do NOT graft the other set (no duplication)
+          }
+          if (unmatchedOther.length === 0 || unmatchedOther.length > GRAFT_MAX_PER_VP) continue;
+          // Graft position: each unmatched child anchors AFTER the last canonical child matched
+          // before it in this viewport's sibling order (-1 = before every canonical child).
+          const canonIdxOf = new Map<RawNode, number>();
+          aligned[vw]!.forEach((mo, i) => { if (mo) canonIdxOf.set(mo, i); });
+          let lastCanonIdx = -1;
+          const newByAnchor = new Map<number, RawNode[]>();
+          for (const k of vwKids) {
+            const ci = canonIdxOf.get(k);
+            if (ci !== undefined) { lastCanonIdx = ci; continue; }
+            let list = newByAnchor.get(lastCanonIdx);
+            if (!list) newByAnchor.set(lastCanonIdx, (list = []));
+            list.push(k);
+          }
+          // Merge this viewport's unmatched children into the anchor's existing graft groups by
+          // structural signature (the same node present at several widths becomes ONE graft with
+          // per-viewport data), preserving sibling order; leftovers open new groups in order.
+          for (const [anchor, newcomers] of [...newByAnchor.entries()].sort((a, b) => a[0] - b[0])) {
+            const groups = graftsByAnchor.get(anchor) ?? [];
+            const al = alignChildren(groups.map((g) => g.rep), newcomers);
+            const groupOfNew = new Map<RawNode, number>();
+            al.forEach((r, idx) => { if (r) groupOfNew.set(r, idx); });
+            const merged: GraftGroup[] = [];
+            let gi = 0;
+            for (const k of newcomers) {
+              const gIdx = groupOfNew.get(k);
+              if (gIdx !== undefined) {
+                while (gi <= gIdx) merged.push(groups[gi++]!);
+                groups[gIdx]!.rawByVp[vw] = k;
+              } else {
+                merged.push({ rep: k, rawByVp: { [vw]: k } });
+              }
+            }
+            while (gi < groups.length) merged.push(groups[gi++]!);
+            graftsByAnchor.set(anchor, merged);
+          }
+        }
+      }
+      // Materialize graft groups → IR nodes. Keep only groups that actually PAINT at a band
+      // viewport (a graft visible solely at a dense sample width could never be shown — bands are
+      // emitted only at the standard breakpoints — so it would be dead markup).
+      const graftedByAnchor = new Map<number, IRNode[]>();
+      for (const [anchor, groups] of [...graftsByAnchor.entries()].sort((a, b) => a[0] - b[0])) {
+        const out: IRNode[] = [];
+        for (const g of groups) {
+          const graftVps = Object.keys(g.rawByVp).map(Number).sort((a, b) => a - b);
+          if (!graftVps.some((vw) => bandVpSet.has(vw) && rawSubtreeVisible(g.rawByVp[vw]!))) continue;
+          const gm: Record<number, RawNode | undefined> = {};
+          for (const vw of viewports) gm[vw] = g.rawByVp[vw];
+          const gn = convert(g.rawByVp[graftVps[0]!]!, gm);
+          if (gn) out.push(gn);
+        }
+        if (out.length) graftedByAnchor.set(anchor, out);
+      }
+      if (driftVps.size) {
+        const bandDrift = [...driftVps].filter((v) => bandVpSet.has(v)).sort((a, b) => a - b);
+        if (bandDrift.length) node.childDriftVps = bandDrift;
+      }
+
       let ei = 0;
+      let pushedLeading = false;
+      const pushGrafts = (anchor: number): void => {
+        for (const gn of graftedByAnchor.get(anchor) ?? []) node.children.push(gn);
+      };
       for (const c of raw.children) {
         if ((c as IRTextNode).text !== undefined) {
           node.children.push({ text: (c as IRTextNode).text });
           continue;
         }
+        if (!pushedLeading) { pushGrafts(-1); pushedLeading = true; }
         const child = c as RawNode;
         const childMatched: Record<number, RawNode | undefined> = {};
-        for (const vw of viewports) childMatched[vw] = vw === canonical ? child : aligned[vw]![ei];
-        ei++;
+        // A grafted subtree has no canonical counterpart: its own children must not be treated as
+        // canonical-matched either (they carry data only at the graft's source viewports).
+        for (const vw of viewports) childMatched[vw] = vw === canonical ? (matched[canonical] ? child : undefined) : aligned[vw]![ei];
         const converted = convert(child, childMatched);
         if (converted) node.children.push(converted);
+        pushGrafts(ei);
+        ei++;
       }
+      if (!pushedLeading) pushGrafts(-1);
     }
     return node;
   };
@@ -667,6 +825,16 @@ export function buildIR(sourceDir: string, viewports: number[], opts?: { motion?
   };
   renumber(root);
 
+  // Content-identity drift notes (containers whose children were a different set at some band
+  // viewport — see childDriftVps). Collected AFTER renumbering so the recorded ids are final;
+  // deterministic (pre-order walk of the pruned tree).
+  const contentDrift: NonNullable<IRDoc["contentDrift"]> = [];
+  const collectDrift = (n: IRNode): void => {
+    if (n.childDriftVps?.length) contentDrift.push({ id: n.id, tag: n.tag, viewports: [...n.childDriftVps] });
+    for (const c of n.children) if (!isTextChild(c)) collectDrift(c);
+  };
+  collectDrift(root);
+
   const perViewport: IRDoc["perViewport"] = {};
   for (const vw of viewports) {
     const d = snapshots[vw]!.doc;
@@ -696,6 +864,7 @@ export function buildIR(sourceDir: string, viewports: number[], opts?: { motion?
     // benchmark + all multi-page, which don't capture motion) ⇒ none emitted, so the
     // clone stays byte-identical to the pre-Stage-5 frozen output.
     keyframes: opts?.motion ? [...new Set(canonSnap.keyframes ?? [])].sort() : [],
+    ...(contentDrift.length ? { contentDrift } : {}),
   };
 
   // Repair transient root scroll-locks. A site that locks scrolling during an intro
diff --git a/compiler/test/viewportGraft.test.ts b/compiler/test/viewportGraft.test.ts
new file mode 100644
index 0000000..c55cf98
--- /dev/null
+++ b/compiler/test/viewportGraft.test.ts
@@ -0,0 +1,219 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { RawNode, RawChild } from "../src/capture/walker.js";
+import { buildIR, isTextChild, type IR, type IRNode } from "../src/normalize/ir.js";
+import { collectNodeRules } from "../src/generate/css.js";
+
+// Per-viewport DOM divergence handling:
+//  • GRAFT — a child that exists ONLY at non-canonical viewports enters the IR as a sibling at
+//    its source position, carrying per-viewport data only for the widths it appeared at, and is
+//    emitted display:none at base + revealed in its band(s).
+//  • DRIFT — a container whose children are a wholly DIFFERENT SET at some viewport (content
+//    identity drift) is NOT grafted (no duplication); the canonical children stand in at that
+//    width (the display:none banding is skipped) and the divergence is recorded in
+//    doc.contentDrift for the manifest.
+
+function raw(tag: string, attrs: Record<string, string> = {}, children: RawChild[] = [], visible = true, computedOver: Record<string, string> = {}): RawNode {
+  return {
+    tag, attrs,
+    computed: { display: visible ? "block" : "none", position: "static", visibility: "visible", ...computedOver },
+    bbox: { x: 0, y: 0, width: visible ? 640 : 0, height: visible ? 360 : 0 },
+    visible,
+    children,
+  };
+}
+
+function snapshot(vp: number, root: RawNode): object {
+  return {
+    doc: {
+      url: "https://example.test/page", title: "Fixture",
+      head: { description: "", canonical: "", ogTitle: "", ogDescription: "", ogImage: "", ogType: "", ogSiteName: "", twitterCard: "", themeColor: "" },
+      lang: "en", charset: "UTF-8", viewportWidth: vp, viewportHeight: 800,
+      scrollWidth: vp, scrollHeight: 800, htmlBg: "rgb(255, 255, 255)", bodyBg: "rgb(255, 255, 255)",
+      bodyColor: "rgb(0, 0, 0)", bodyFont: "Arial", metaViewport: "width=device-width, initial-scale=1",
+      nodeCount: 10, truncated: false,
+    },
+    root, cssVars: {}, fontFaces: [], cssUrls: [], domAssets: [], keyframes: [],
+  };
+}
+
+/** Build an IR from a DIFFERENT raw body tree per viewport. */
+function buildDivergentIR(rootByVp: Record<number, RawNode>): IR {
+  const vps = Object.keys(rootByVp).map(Number).sort((a, b) => a - b);
+  const sourceDir = mkdtempSync(join(tmpdir(), "ditto-ir-graft-"));
+  mkdirSync(join(sourceDir, "capture"), { recursive: true });
+  for (const vp of vps) {
+    writeFileSync(join(sourceDir, "capture", `dom-${vp}.json`), JSON.stringify(snapshot(vp, rootByVp[vp]!)));
+  }
+  return buildIR(sourceDir, vps);
+}
+
+function findByTag(node: IRNode, tag: string): IRNode | null {
+  if (node.tag === tag) return node;
+  for (const c of node.children) {
+    if (isTextChild(c)) continue;
+    const hit = findByTag(c, tag);
+    if (hit) return hit;
+  }
+  return null;
+}
+
+function elemChildren(node: IRNode): IRNode[] {
+  return node.children.filter((c): c is IRNode => !isTextChild(c));
+}
+
+// ---- fixtures ----
+
+/** Carousel whose pagination (ul + 3 bullet li) exists ONLY below the canonical width. */
+function carouselFixture(): { small: RawNode; large: RawNode } {
+  const track = (): RawNode => raw("div", { id: "track" });
+  const pagination = (): RawNode =>
+    raw("ul", { id: "pagination" }, [
+      raw("li", {}, [raw("button", { type: "button" }, [{ text: "1" }])]),
+      raw("li", {}, [raw("button", { type: "button" }, [{ text: "2" }])]),
+      raw("li", {}, [raw("button", { type: "button" }, [{ text: "3" }])]),
+    ]);
+  const small = raw("body", {}, [raw("section", { id: "carousel" }, [track(), pagination()])]);
+  const large = raw("body", {}, [raw("section", { id: "carousel" }, [track()])]);
+  return { small, large };
+}
+
+/** Container serving a DIFFERENT item set per viewport (content identity drift). */
+function driftFixture(): { small: RawNode; large: RawNode } {
+  const item = (id: string): RawNode => raw("li", { id }, [raw("span", {}, [{ text: `Item ${id}` }])]);
+  const small = raw("body", {}, [raw("ul", { id: "rotator" }, [item("b1"), item("b2"), item("b3"), item("b4")])]);
+  const large = raw("body", {}, [raw("ul", { id: "rotator" }, [item("a1"), item("a2"), item("a3"), item("a4")])]);
+  return { small, large };
+}
+
+describe("IR grafts non-canonical-only children", () => {
+  it("grafts a subtree present only at 375 into the canonical tree at its source position", () => {
+    const { small, large } = carouselFixture();
+    const ir = buildDivergentIR({ 375: small, 1280: large });
+
+    const section = findByTag(ir.root, "section")!;
+    const kids = elemChildren(section);
+    assert.deepEqual(kids.map((k) => k.tag), ["div", "ul"], "pagination grafted after the matched track");
+
+    const ul = kids[1]!;
+    assert.equal(ul.attrs.id, "pagination");
+    // Per-viewport data ONLY at the source viewport — nothing invented at canonical.
+    assert.deepEqual(Object.keys(ul.computedByVp), ["375"]);
+    assert.equal(ul.visibleByVp[375], true);
+    assert.equal(ul.computedByVp[1280], undefined);
+    assert.equal(ul.bboxByVp[1280], undefined);
+    // The grafted subtree's descendants carry the same viewport-scoped data.
+    const bullets = elemChildren(ul);
+    assert.equal(bullets.length, 3);
+    for (const li of bullets) {
+      assert.deepEqual(Object.keys(li.computedByVp), ["375"]);
+      const btn = elemChildren(li)[0]!;
+      assert.equal(btn.tag, "button");
+      assert.deepEqual(Object.keys(btn.computedByVp), ["375"]);
+    }
+    // No drift recorded — this is an additive responsive difference, not a set swap.
+    assert.equal(section.childDriftVps, undefined);
+    assert.equal(ir.doc.contentDrift, undefined);
+  });
+
+  it("merges the same non-canonical-only child across several viewports into ONE grafted node", () => {
+    const { small, large } = carouselFixture();
+    const ir = buildDivergentIR({ 375: small, 768: structuredClone(small), 1280: large });
+
+    const section = findByTag(ir.root, "section")!;
+    const uls = elemChildren(section).filter((k) => k.tag === "ul");
+    assert.equal(uls.length, 1, "one grafted node, not one per viewport");
+    assert.deepEqual(Object.keys(uls[0]!.computedByVp).map(Number).sort((a, b) => a - b), [375, 768]);
+  });
+
+  it("is deterministic: two builds from the same capture are byte-identical", () => {
+    const { small, large } = carouselFixture();
+    const a = buildDivergentIR({ 375: small, 1280: large });
+    const b = buildDivergentIR({ 375: structuredClone(small), 1280: structuredClone(large) });
+    assert.equal(JSON.stringify(a), JSON.stringify(b));
+  });
+
+  it("does not graft a child that never paints at any band viewport", () => {
+    const { small, large } = carouselFixture();
+    // Make the whole pagination subtree invisible at 375.
+    const section = small.children[0] as RawNode;
+    const pag = (section.children as RawNode[]).find((c) => c.tag === "ul")!;
+    const markInvisible = (n: RawNode): void => {
+      n.visible = false; n.computed.display = "none"; n.bbox = { x: 0, y: 0, width: 0, height: 0 };
+      for (const c of n.children) if ((c as RawNode).tag) markInvisible(c as RawNode);
+    };
+    markInvisible(pag);
+    const ir = buildDivergentIR({ 375: small, 1280: large });
+    assert.equal(findByTag(ir.root, "ul"), null, "invisible-everywhere subtree is not grafted");
+  });
+});
+
+describe("IR whole-set content drift falls back to faithful-at-canonical", () => {
+  it("records drift instead of grafting when both sides mutually mismatch", () => {
+    const { small, large } = driftFixture();
+    const ir = buildDivergentIR({ 375: small, 1280: large });
+
+    const rotator = findByTag(ir.root, "ul")!;
+    const kids = elemChildren(rotator);
+    // Canonical set only — the divergent 375 set is NOT grafted (no duplication).
+    assert.deepEqual(kids.map((k) => k.attrs.id), ["a1", "a2", "a3", "a4"]);
+    assert.deepEqual(rotator.childDriftVps, [375]);
+    // Canonical children carry no invented data at the drift viewport.
+    for (const k of kids) assert.equal(k.computedByVp[375], undefined);
+    // Surfaced for the manifest, with the final (post-renumber) id.
+    assert.deepEqual(ir.doc.contentDrift, [{ id: rotator.id, tag: "ul", viewports: [375] }]);
+  });
+
+  it("does not misread an additive difference as drift", () => {
+    // Canonical set fully matches at 375; 375 merely has extras → graft path, no drift.
+    const item = (id: string): RawNode => raw("li", { id });
+    const small = raw("body", {}, [raw("ul", { id: "list" }, [item("x1"), item("x2"), item("e1"), item("e2"), item("e3")])]);
+    const large = raw("body", {}, [raw("ul", { id: "list" }, [item("x1"), item("x2")])]);
+    const ir = buildDivergentIR({ 375: small, 1280: large });
+    const list = findByTag(ir.root, "ul")!;
+    assert.equal(list.childDriftVps, undefined);
+    assert.deepEqual(elemChildren(list).map((k) => k.attrs.id), ["x1", "x2", "e1", "e2", "e3"]);
+    assert.deepEqual(Object.keys(elemChildren(list)[2]!.computedByVp), ["375"]);
+  });
+});
+
+describe("emission of grafted and drift nodes", () => {
+  it("emits a grafted node as display:none at base with a full reveal band at its viewport", () => {
+    const { small, large } = carouselFixture();
+    const ir = buildDivergentIR({ 375: small, 1280: large });
+    const ul = findByTag(ir.root, "ul")!;
+    const rules = collectNodeRules(ir, new Map());
+    const nr = rules.get(ul.id)!;
+    assert.deepEqual([...nr.base.entries()], [["display", "none"]], "hidden at the canonical base");
+    assert.equal(nr.bands.length, 1, "exactly one band: the reveal at its source viewport");
+    const band = nr.bands[0]!;
+    assert.match(band.media, /max-width/);
+    assert.equal(band.decls.get("display"), "block", "the band reveals AND lays out the node");
+  });
+
+  it("skips the display:none band for drift stand-ins (and their descendants), keeps it otherwise", () => {
+    const { small, large } = driftFixture();
+    // Control: a genuinely canonical-only sibling (absent at 375, NOT under a drift container)
+    // must still be banded display:none at 375.
+    (large.children as RawNode[]).push(raw("aside", { id: "desktop-only" }, [{ text: "Desktop" }]));
+    const ir = buildDivergentIR({ 375: small, 1280: large });
+    const rules = collectNodeRules(ir, new Map());
+
+    const rotator = findByTag(ir.root, "ul")!;
+    for (const li of elemChildren(rotator)) {
+      const nr = rules.get(li.id)!;
+      assert.equal(nr.bands.some((b) => b.decls.get("display") === "none"), false, `stand-in ${li.attrs.id} not hidden at the drift viewport`);
+      // Descendants of the stand-in subtree are not hidden either.
+      const span = elemChildren(li)[0]!;
+      const snr = rules.get(span.id)!;
+      assert.equal(snr.bands.some((b) => b.decls.get("display") === "none"), false, "stand-in descendant not hidden");
+    }
+
+    const aside = findByTag(ir.root, "aside")!;
+    const anr = rules.get(aside.id)!;
+    assert.equal(anr.bands.some((b) => b.decls.get("display") === "none"), true, "unrelated canonical-only node still hidden per band");
+  });
+});

From 22d0bf19e927c0e28477b82d6b5c278ba142e9a2 Mon Sep 17 00:00:00 2001
From: Samraaj Bath <samraaj100@gmail.com>
Date: Sat, 4 Jul 2026 11:23:15 -0700
Subject: [PATCH 23/24] Rebase viewport-relative positioning when grafting
 iframe subtrees

A grafted frame's position:fixed children re-resolved against the MAIN
page viewport and escaped the frame box's overflow clip (fixed ignores
overflow ancestors) - a full-viewport backdrop inside an embedded iframe
could paint across the entire page. Grafted subtrees now demote
fixed->absolute and sticky->relative, and a static graft host is promoted
to relative so demoted absolutes anchor and clip inside the frame box.

472 tests pass (4 new), typecheck clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 compiler/src/capture/graft.ts     | 22 +++++++++++++-
 compiler/test/iframeGraft.test.ts | 48 +++++++++++++++++++++++++++++++
 2 files changed, 69 insertions(+), 1 deletion(-)

diff --git a/compiler/src/capture/graft.ts b/compiler/src/capture/graft.ts
index 88b1406..746f0d8 100644
--- a/compiler/src/capture/graft.ts
+++ b/compiler/src/capture/graft.ts
@@ -171,6 +171,21 @@ export function graftFrameIntoSnapshot(
       x: Math.round((n.bbox.x + frame.contentX) * 100) / 100,
       y: Math.round((n.bbox.y + frame.contentY) * 100) / 100,
     };
+    // Rebase viewport-relative positioning into the frame's box. Inside a real iframe,
+    // `position: fixed` pins to the FRAME's viewport (its content box) and `sticky` scrolls
+    // against the FRAME's scroll container. Grafted in as plain <div> children, those
+    // containing blocks no longer exist, so `fixed` would resolve against the MAIN page
+    // viewport — escaping the iframe's clip box (fixed ignores `overflow:hidden` ancestors)
+    // and painting frame chrome (e.g. a `fixed inset-0 z-[-1]` dark backdrop) across the
+    // whole clone. Demote to box-relative positioning: `fixed`→`absolute` (contained and
+    // clipped by the host div, whose bboxes are already rebased to page coords) and
+    // `sticky`→`relative` (stays in flow instead of sticking to the page scroll). The host
+    // is made a containing block below so these absolutes anchor to the frame box.
+    if (n.computed) {
+      const pos = n.computed.position;
+      if (pos === "fixed") n.computed = { ...n.computed, position: "absolute" };
+      else if (pos === "sticky") n.computed = { ...n.computed, position: "relative" };
+    }
     const a = n.attrs ?? {};
     delete a["data-cid-cap"]; // capture-ids belong to the main document only
     if (a.id) a.id = prefix + a.id;
@@ -190,8 +205,13 @@ export function graftFrameIntoSnapshot(
 
   host.children = [wrapper];
   // A real frame viewport clips its document; the replacement <div> must too, at every
-  // captured viewport (each per-viewport snapshot is grafted independently).
+  // captured viewport (each per-viewport snapshot is grafted independently). It must also
+  // be a containing block: `visit` demoted the frame's `position: fixed` chrome (which was
+  // pinned to the frame viewport) to `absolute`, and those absolutes must anchor to — and
+  // be clipped by — this box, not some positioned ancestor further up the page. A `static`
+  // host wouldn't establish that containing block, so promote it to `relative`.
   host.computed = { ...host.computed, overflow: "hidden", overflowX: "hidden", overflowY: "hidden" };
+  if ((host.computed.position || "static") === "static") host.computed.position = "relative";
   // An iframe is a REPLACED element: `display:inline` (the default) still honors its
   // width/height. The <div> that replaces it at generation is not — inline would collapse
   // the box — so translate to the behavior-equivalent inline-block.
diff --git a/compiler/test/iframeGraft.test.ts b/compiler/test/iframeGraft.test.ts
index 85f7b37..dc5cbe2 100644
--- a/compiler/test/iframeGraft.test.ts
+++ b/compiler/test/iframeGraft.test.ts
@@ -163,6 +163,54 @@ describe("graftFrameIntoSnapshot", () => {
     graftFrameIntoSnapshot(host, { idx: 0, contentX: 40, contentY: 30 }, frame);
     assert.ok(host.keyframes.includes("@keyframes spin { to { transform: rotate(360deg); } }"));
   });
+
+  // A frame's `position: fixed` chrome pins to the FRAME viewport, not the page's. Grafted
+  // as plain DOM, `fixed` would resolve against the main page viewport and escape the
+  // iframe's clip box — the observed regression: a gallery embed's
+  // `fixed inset-0 z-[-1]` dark backdrop painted the whole clone dark. It must be demoted
+  // to `absolute` so the host box contains and clips it.
+  it("demotes frame `position: fixed` to `absolute` so it stays inside the iframe box", () => {
+    const backdrop = raw("div", { class: "backdrop" }, [], {
+      computed: { display: "block", position: "fixed" },
+      bbox: { x: 0, y: 0, width: 320, height: 160 },
+    });
+    const frame = pageSnap(raw("body", {}, [backdrop]), "https://frame.test/embed");
+    const host = mkHost();
+    graftFrameIntoSnapshot(host, { idx: 0, contentX: 40, contentY: 30 }, frame);
+    const wrapper = findFrameNode(host.root, 0)!.children[0] as RawNode;
+    const grafted = wrapper.children[0] as RawNode;
+    assert.equal(grafted.computed.position, "absolute");
+  });
+
+  it("demotes frame `position: sticky` to `relative` (no sticking to the page scroll)", () => {
+    const bar = raw("div", { class: "sticky-bar" }, [], {
+      computed: { display: "block", position: "sticky" },
+      bbox: { x: 0, y: 0, width: 320, height: 40 },
+    });
+    const frame = pageSnap(raw("body", {}, [bar]), "https://frame.test/embed");
+    const host = mkHost();
+    graftFrameIntoSnapshot(host, { idx: 0, contentX: 40, contentY: 30 }, frame);
+    const wrapper = findFrameNode(host.root, 0)!.children[0] as RawNode;
+    const grafted = wrapper.children[0] as RawNode;
+    assert.equal(grafted.computed.position, "relative");
+  });
+
+  it("promotes a `static` host to `relative` so demoted absolutes anchor to the frame box", () => {
+    const host = mkHost(); // iframe host computed.position defaults to "static"
+    graftFrameIntoSnapshot(host, { idx: 0, contentX: 40, contentY: 30 }, mkFrame());
+    assert.equal(findFrameNode(host.root, 0)!.computed.position, "relative");
+  });
+
+  it("leaves an already-positioned host's position untouched", () => {
+    const host = pageSnap(raw("body", {}, [
+      raw("iframe", { "data-ditto-frame": "0", src: "https://frame.test/embed" }, [], {
+        computed: { display: "block", position: "absolute" },
+        bbox: { x: 40, y: 30, width: 320, height: 160 },
+      }),
+    ]));
+    graftFrameIntoSnapshot(host, { idx: 0, contentX: 40, contentY: 30 }, mkFrame());
+    assert.equal(findFrameNode(host.root, 0)!.computed.position, "absolute");
+  });
 });
 
 // ---- Cross-origin integration: capture → snapshot graft → IR → generated tag ----

From c49d5b6ab780a23d80db19c2729fbc4e452124fc Mon Sep 17 00:00:00 2001
From: Samraaj Bath <samraaj100@gmail.com>
Date: Sat, 4 Jul 2026 12:42:11 -0700
Subject: [PATCH 24/24] Recover viewport-relative min-heights and
 capped-container centering at emission

- viewportMinHeightLaw: a box authored min-h-screen / min-h-[calc(100vh -
  Cpx)] had its per-viewport px baked at capture, leaving whitespace (or
  overflow) at window heights between captured viewports; when the source
  class list corroborates a vh token and per-regime offsets agree, emit
  the authored law (100vh / calc(100vh - Cpx)) instead of frozen px
- isCappedCenteredContainer: max-width-capped centered content columns
  emit mx-auto (including as flex/grid items, where auto margins center
  along the main axis) so pages stay centered at non-captured window
  widths instead of pinning left at frozen px
- Circular-slide guard skips fluid full-bleed sections so
  viewport-spanning shrink-0 items keep fluid width

476 tests pass (4 new, with corroboration-guard negatives), typecheck clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 compiler/src/generate/css.ts | 153 ++++++++++++++++++++++++++++++++++-
 compiler/test/css.test.ts    | 102 +++++++++++++++++++++++
 2 files changed, 251 insertions(+), 4 deletions(-)

diff --git a/compiler/src/generate/css.ts b/compiler/src/generate/css.ts
index 650ed50..74eb531 100644
--- a/compiler/src/generate/css.ts
+++ b/compiler/src/generate/css.ts
@@ -318,6 +318,7 @@ const viewportHeightFor = (vp: number): number => CAPTURE_VIEWPORT_HEIGHTS[vp] ?
 type GeometryPlan = {
   heightByVp?: Record<number, string>;
   aspectByVp?: Record<number, string>;
+  minHeightByVp?: Record<number, string>;
   leftByVp?: Record<number, string>;
   topByVp?: Record<number, string>;
 };
@@ -813,6 +814,69 @@ function singleFluidGridRow(node: IRNode, viewports: number[]): Map<number, stri
   return painted >= 2 ? result : null;
 }
 
+/** A box authored with a viewport-relative min-height (e.g. `min-h-screen` or
+ * `min-h-[calc(100vh - Cpx)]`) whose per-viewport px is baked at capture, freezing a full-screen
+ * hero to one window height. The engine only sees the resolved px, so we recover the authored law
+ * `calc(100vh - Cpx)` (constant offset C, k=1) from samples spanning DIFFERENT viewport heights and
+ * re-emit it as a viewport unit. Gated by an authored vh-token corroboration so a content-driven
+ * min-height can't be mistaken for a viewport law. */
+function viewportMinHeightLaw(node: IRNode, viewports: number[]): Record<number, string> | null {
+  // Authored corroboration: only recover a viewport law when the source class carries a
+  // viewport-relative min-height intent. Without srcClass we can't distinguish it from a fixed box.
+  const src = node.srcClass || "";
+  if (!src) return null;
+  const hasVhIntent =
+    /\b\d*\.?\d*(?:vh|dvh|svh|lvh)\b/.test(src) ||
+    src.includes("100vh") || src.includes("min-h-screen") ||
+    src.includes("min-h-[100vh") || src.includes("calc(100vh");
+  if (!hasVhIntent) return null;
+
+  const samples: Array<{ vp: number; mh: number; vh: number }> = [];
+  for (const vp of viewports) {
+    const cs = node.computedByVp[vp]; const nb = node.bboxByVp[vp];
+    if (!cs || !nb || !node.visibleByVp[vp] || (cs.display || "") === "none") continue;
+    const mhRaw = cs.minHeight;
+    if (!mhRaw || !mhRaw.endsWith("px")) continue;
+    const mh = pf(mhRaw);
+    if (!(mh >= 120)) continue; // avoid tiny content boxes
+    samples.push({ vp, mh, vh: viewportHeightFor(vp) });
+  }
+  if (samples.length < 2) return null;
+  // The law must be DETERMINED: at least two samples whose viewport heights actually differ.
+  // If every sample shares one viewport height, a fixed px is indistinguishable from `100vh`.
+  const vhs = samples.map((s) => s.vh);
+  if (Math.max(...vhs) - Math.min(...vhs) <= 1) return null;
+
+  // Per-sample offset C_i = vh_i - mh_i, checked against the SAME viewport's own captured height (an
+  // exact per-sample identity, not an extrapolation). Responsive heroes are commonly authored as a
+  // BREAKPOINT-SPLIT law — `min-h-[100vh] md:min-h-[calc(100vh - Cpx)]` — so C is a per-regime
+  // constant, NOT globally constant: the mobile band has C≈0 (`100vh`) while the desktop bands share
+  // one positive C (`calc(100vh - Cpx)`). We allow that split but keep each regime determined:
+  //   - each C_i must be a modest subtraction (0 <= C_i <= 0.5·vh_i), else the box isn't viewport-fit;
+  //   - the NON-ZERO offsets must all agree within 1.5px (one determined desktop offset, k=1) — a
+  //     spread of distinct positive C's is ambiguous, so bail rather than freeze a wrong law.
+  const offsets = samples.map((s) => ({ vp: s.vp, c: s.vh - s.mh, vh: s.vh }));
+  for (const o of offsets) {
+    if (o.c < -1.5) return null;              // an addition, not a viewport-fit subtraction
+    if (o.c > 0.5 * o.vh) return null;        // too large an offset to be a full-screen hero
+  }
+  const nonZero = offsets.filter((o) => o.c > 1.5).map((o) => o.c);
+  let deskC = 0;
+  if (nonZero.length) {
+    // A non-zero offset regime must be CORROBORATED: a lone desktop sample with a unique positive C is
+    // indistinguishable from a genuinely fixed px min-height (e.g. `min-h-[100vh] md:min-h-[500px]`), so
+    // require >= 2 desktop samples that agree on one C (within 1.5px). A C≈0 (`100vh`) band is an exact
+    // per-sample viewport identity and needs no such corroboration.
+    if (nonZero.length < 2) return null;
+    const mean = nonZero.reduce((a, b) => a + b, 0) / nonZero.length;
+    if (nonZero.some((c) => Math.abs(c - mean) > 1.5)) return null; // desktop offsets disagree
+    deskC = Math.round(mean);
+  }
+  const out: Record<number, string> = {};
+  for (const o of offsets) out[o.vp] = o.c <= 1.5 ? "100vh" : `calc(100vh - ${deskC}px)`;
+  return out;
+}
+
 /** A large structural/media box whose captured height is a viewport-height expression with a lower
  * and/or upper clamp. Cursor's demo frames are the canonical example: every sampled height equals
  * `clamp(MIN, 70vh, MAX)`, but the engine only sees the resolved px row height. */
@@ -1025,6 +1089,22 @@ function isFlexFillItem(node: IRNode, parentNode: IRNode | undefined, viewports:
  *  genuine circular collapse, never on a normal content-sized shrink-0 item. */
 function isCircularShrinkSlide(node: IRNode, parentNode: IRNode | undefined, viewports: number[]): boolean {
   if (!parentNode || REPLACED.has(node.tag) || node.tag.includes("-")) return false;
+  // A box that spans the full viewport at ≥2 distinct widths with no horizontal margins has a real
+  // width source (it fills a fluid container / was authored width:100%) — it is NOT a circular-collapse
+  // slide. `width:100%`/`auto` gives its fill-children a valid definite basis, so there is nothing to
+  // collapse. Same "proven fluid" bar (samples >= 2 distinct widths) used by isFluidFullBleed /
+  // isFluidFillItem above; freezing such a full-bleed section to captured px is exactly the misfire.
+  const nearZero = (v: string | undefined): boolean => v != null && v !== "auto" && Math.abs(parseFloat(v)) <= 1.5;
+  let fluidSpan = 0;
+  for (const vp of viewports) {
+    const cs = node.computedByVp[vp]; const bb = node.bboxByVp[vp];
+    if (!cs || !bb || !node.visibleByVp[vp] || (cs.display || "") === "none" || !(bb.width > 0)) continue;
+    if (Math.abs(bb.x) > 1.5) continue;                  // must start at the left edge
+    if (Math.abs(bb.width - vp) > 1.5) continue;         // must span the full viewport
+    if (!nearZero(cs.marginLeft) || !nearZero(cs.marginRight)) continue; // margins make the width load-bearing
+    fluidSpan++;
+  }
+  if (fluidSpan >= 2) return false;                       // proven fluid full-bleed, not a circular slide
   let painted = 0;
   for (const vp of viewports) {
     const cs = node.computedByVp[vp]; const pcs = parentNode.computedByVp[vp]; const nb = node.bboxByVp[vp];
@@ -2693,8 +2773,13 @@ function declsForViewport(
   } else if (cs.height && cs.height !== "auto" && !isTableWithCaption && !rootUnclamp && !dropHeight && (!isInlineOnly || REPLACED.has(tag)) && (noCollapse || isLeaf || explicitHeight)) {
     out.set("height", cs.height);
   }
+  const plannedMinHeight = geometry.minHeightByVp?.[vp];
   if (cs.minHeight && cs.minHeight !== "0px" && cs.minHeight !== "auto") {
-    out.set("min-height", isViewportHeight(cs.minHeight, vp) ? "100vh" : cs.minHeight);
+    if (plannedMinHeight) {
+      out.set("min-height", plannedMinHeight);
+    } else {
+      out.set("min-height", isViewportHeight(cs.minHeight, vp) ? "100vh" : cs.minHeight);
+    }
   }
 
   // borders (complete triple per side, only when width > 0). When all four sides are
@@ -3085,6 +3170,59 @@ function hasPxMaxWidthCap(node: IRNode, viewports: number[]): boolean {
   return max > 0 && max - min <= Math.max(2, max * 0.02);
 }
 
+/** A centred max-width container that also qualifies when it is a FLEX/GRID ITEM (which
+ *  `planWidth` case (a) and `centeredAtVp` both bail on — a flex/grid item is normally positioned by
+ *  the parent layout). The pattern: `width:100%; max-width:W; margin:0 auto` — the box fills its
+ *  container below the cap and centres (symmetric free space) above it. `margin:auto` centres a
+ *  flex/grid item along the main axis exactly as it centres a block, so emitting `mx-auto` is correct
+ *  here too; freezing the captured side margins (which vary per width — 32/47/67/324px) instead
+ *  left-aligns the box at any non-captured width.
+ *
+ *  This is SAFE (unlike the width-dropped fill-inset case `centeredAtVp` guards against, where
+ *  `margin:auto` resolves to 0 and blows the box full-bleed) precisely because a px `max-width` cap
+ *  is RETAINED at every band: the cap holds the width, so `margin:auto` can only absorb the centring
+ *  slack, never over-widen. The `max-width` cap may VARY per viewport (a fluid
+ *  `min(Wpx, 100% − 2·gutter)` resolves to a different px per width) — we accept per-band caps and let
+ *  the normal `max-width` emission carry them, mirroring `planWidth` case (a)'s documented reasoning.
+ *
+ *  Every guard holds over the painted samples (≥2), and centring must be OBSERVED (symmetric positive
+ *  free space with equal margins) at ≥1 band where the container exceeds the cap: */
+function isCappedCenteredContainer(node: IRNode, parentNode: IRNode | undefined, viewports: number[]): boolean {
+  if (!parentNode || REPLACED.has(node.tag) || node.tag.includes("-")) return false;
+  let painted = 0;
+  let sawCenter = false;
+  for (const vp of viewports) {
+    const cs = node.computedByVp[vp]; const pcs = parentNode.computedByVp[vp];
+    const nb = node.bboxByVp[vp]; const pb = parentNode.bboxByVp[vp];
+    if (!cs || !pcs || !nb || !pb || !node.visibleByVp[vp] || (cs.display || "") === "none" || !(nb.width > 0)) continue;
+    // Block-LEVEL box (block/list-item/flow-root/table, or a grid/flex CONTAINER — all margin-auto
+    // centreable), in normal flow, border-box. Inline-level boxes centre via text-align, not margins.
+    if (!/^(block|list-item|flow-root|table|grid|flex)$/.test(cs.display || "")) return false;
+    const pos = cs.position || "static";
+    if (pos !== "static" && pos !== "relative") return false;
+    if ((cs.float || "none") !== "none") return false;
+    if ((cs.boxSizing || "border-box") === "content-box") return false;
+    const maxW = cs.maxWidth || "";
+    if (!maxW.endsWith("px")) return false;               // must carry a px max-width cap at every band
+    const cap = pf(maxW);
+    if (!(cap > 0)) return false;
+    const content = pb.width - pf(pcs.paddingLeft) - pf(pcs.paddingRight) - pf(pcs.borderLeftWidth) - pf(pcs.borderRightWidth);
+    if (!(content > 0)) return false;
+    // The box sits at min(containerContent, cap): it fills the container below the cap and plateaus at
+    // the cap above it — the exact `width:100%; max-width:W` trajectory (NOT a fixed or content width).
+    if (Math.abs(nb.width - Math.min(content, cap)) > Math.max(1.5, 0.01 * nb.width)) return false;
+    const ml = pf(cs.marginLeft); const mr = pf(cs.marginRight);
+    // Where the container exceeds the cap there is room to centre — the box MUST be centred there
+    // (symmetric positive side margins), else it is left/right-aligned and margin:auto would move it.
+    if (content > cap + 4) {
+      if (ml > 1 && mr > 1 && Math.abs(ml - mr) <= 1.5) sawCenter = true;
+      else return false;
+    }
+    painted++;
+  }
+  return painted >= 2 && sawCenter;
+}
+
 function hasElementChild(node: IRNode): boolean {
   for (const c of node.children) if (!isTextChild(c)) return true;
   return false;
@@ -3546,7 +3684,11 @@ export function collectNodeRules(ir: IR, assetMap: Map<string, string>, includeN
     const stableCenter =
       centerAlways ||
       sourceMarginAutoIntent(node) ||
-      ((!!fillCap || hasPxMaxWidthCap(node, sampleVps)) && centeredAtAnySample);
+      ((!!fillCap || hasPxMaxWidthCap(node, sampleVps)) && centeredAtAnySample) ||
+      // A centred max-width container that is a flex/grid ITEM (which centerAlways / centeredAtVp bail
+      // on): `width:100%; max-width:W; margin:0 auto`. Safe because the px max-width cap is retained,
+      // so mx-auto only absorbs the centring slack. Handles per-viewport-varying caps.
+      isCappedCenteredContainer(node, parentNode, sampleVps);
     // Fluid grid-template-columns (fr), per-viewport (the column count may change across breakpoints).
     const gridColsByVp = fluidGridColumns(node, sampleVps);
     // Large one-row media grids need a definite height/aspect law before the single `1fr` row is
@@ -3558,8 +3700,11 @@ export function collectNodeRules(ir: IR, assetMap: Map<string, string>, includeN
     const mediaGeometry = lottieHeight ? { heightByVp: lottieHeight } : singleRowsByVp ? mediaHeightGeometry(node, sampleVps) : {};
     const leftClampByVp = !isContents ? centeredInsetClamp(node, cbAncestor, sampleVps, "x") : null;
     const topClampByVp = !isContents ? centeredInsetClamp(node, cbAncestor, sampleVps, "y") : null;
-    const geometry: GeometryPlan = (mediaGeometry.heightByVp || mediaGeometry.aspectByVp || leftClampByVp || topClampByVp)
-      ? { ...mediaGeometry, ...(leftClampByVp ? { leftByVp: leftClampByVp } : {}), ...(topClampByVp ? { topByVp: topClampByVp } : {}) }
+    // Recover an authored viewport-relative min-height (`100vh`/`calc(100vh - Cpx)`) so a full-screen
+    // hero refills the window instead of freezing to the captured px at each band.
+    const minHeightByVp = !isContents ? viewportMinHeightLaw(node, sampleVps) : null;
+    const geometry: GeometryPlan = (mediaGeometry.heightByVp || mediaGeometry.aspectByVp || minHeightByVp || leftClampByVp || topClampByVp)
+      ? { ...mediaGeometry, ...(minHeightByVp ? { minHeightByVp } : {}), ...(leftClampByVp ? { leftByVp: leftClampByVp } : {}), ...(topClampByVp ? { topByVp: topClampByVp } : {}) }
       : GEOMETRY_NONE;
     // Fluid grid-template-rows (1fr) for equal, responsive, content-height-filling row regimes.
     const gridRowsByVp = fluidGridRows(node, sampleVps) ?? ((geometry.heightByVp || geometry.aspectByVp) ? singleRowsByVp : null);
diff --git a/compiler/test/css.test.ts b/compiler/test/css.test.ts
index 28d2a03..9458cb1 100644
--- a/compiler/test/css.test.ts
+++ b/compiler/test/css.test.ts
@@ -475,6 +475,29 @@ describe("generateCss literal-margin vs auto-centring", () => {
     const mobile = xBandRule(css, /^\(max-width/, "n1");
     assert.ok(/max-width:311px/.test(mobile), `mobile band carries its own fluid cap, got: ${mobile}`);
   });
+
+  // Same centred `width:100%; max-width:min(Wpx, …); margin:0 auto` container, but it is a FLEX ITEM
+  // (its parent is display:flex). planWidth case (a) and centeredAtVp both bail on flex/grid items, so
+  // without isCappedCenteredContainer it would freeze its captured per-band side margins (32/47/67px)
+  // and left-align at every non-captured width. margin:auto centres a flex item correctly, and the
+  // retained per-band max-width cap keeps it safe (auto only absorbs the centring slack).
+  it("auto-centres a fluid-max-width container that is a FLEX ITEM (parent is flex)", () => {
+    const child = xNode("n1", "div", {
+      375: { cs: { display: "block", boxSizing: "border-box", maxWidth: "311px", marginLeft: "32px", marginRight: "32px", width: "311px" }, bbox: { x: 32, y: 0, width: 311, height: 200 } },
+      768: { cs: { display: "block", boxSizing: "border-box", maxWidth: "673.2px", marginLeft: "47.4px", marginRight: "47.4px", width: "673.2px" }, bbox: { x: 47.4, y: 0, width: 673.2, height: 200 } },
+      1280: { cs: { display: "block", boxSizing: "border-box", maxWidth: "1145.08px", marginLeft: "67.46px", marginRight: "67.46px", width: "1145.08px" }, bbox: { x: 67.46, y: 0, width: 1145.08, height: 200 } },
+    });
+    const parent = xNode("n0", "body", {
+      375: { cs: { display: "flex", flexDirection: "column" }, bbox: { x: 0, y: 0, width: 375, height: 200 } },
+      768: { cs: { display: "flex", flexDirection: "column" }, bbox: { x: 0, y: 0, width: 768, height: 200 } },
+      1280: { cs: { display: "flex", flexDirection: "column" }, bbox: { x: 0, y: 0, width: 1280, height: 200 } },
+    }, [child]);
+    const css = generateCss(xIr(parent), new Map());
+    const all = allRulesX(css, "n1");
+    assert.ok(/margin-left:auto/.test(all), `flex-item fluid-cap centred container must auto-centre, got: ${all}`);
+    assert.ok(!/margin-left:32px|margin-left:47|margin-left:0?67/.test(all), `must NOT bake literal per-band left margins, got: ${all}`);
+    assert.ok(baseRule(css, "n1").includes("max-width:1145.08px"), `base carries the canonical cap, got: ${baseRule(css, "n1")}`);
+  });
 });
 
 // BUG C — a single-line text leaf whose unwrapped width nearly fills its column at every width gets
@@ -963,6 +986,51 @@ describe("generateCss circular carousel slide with a block-level fill child (FIX
   });
 });
 
+// FIX 4b — the circular-slide detector must NOT misfire on a genuine fluid full-bleed section. A
+// `shrink-0` flex/grid item whose box spans the FULL viewport at ≥2 distinct captured widths (x≈0,
+// width≈vp) with zero horizontal margins provably HAS a width source (it fills a fluid container /
+// was authored width:100%) — there is no circular collapse, so it must emit a fluid width, not freeze
+// to per-breakpoint captured px (w-320/w-192/w-480). Same "proven fluid" bar (≥2 distinct widths).
+describe("generateCss circular-slide guard skips fluid full-bleed section (FIX 4b)", () => {
+  const blockFill = (): RawSizing => ({ wAuto: true, wFill: true, hAuto: true, hFill: true });
+  function fullBleedSection() {
+    // A shrink-0 flex item whose bbox tracks the viewport (375/768/1280) with zero horizontal margins:
+    // a fluid full-bleed section, NOT a fixed-width carousel slide. Its block child fills it.
+    const child = xNode("n2", "div", {
+      375: { cs: { display: "block", position: "static" }, bbox: { x: 0, y: 0, width: 375, height: 80 }, sizing: blockFill() },
+      768: { cs: { display: "block", position: "static" }, bbox: { x: 0, y: 0, width: 768, height: 80 }, sizing: blockFill() },
+      1280: { cs: { display: "block", position: "static" }, bbox: { x: 0, y: 0, width: 1280, height: 80 }, sizing: blockFill() },
+    }, [{ text: "Full bleed" } as IRChild]);
+    // flex-shrink:0 item; its captured px equals the viewport at each width (what the library/probe saw).
+    // boxSizing:content-box keeps isFillsContainerWidth/isFullWidthShrinkSlide (border-box only) off, so
+    // WITHOUT the guard the circular-slide detector wins and freezes these per-breakpoint px.
+    const secCs = (w: number) => ({ display: "block", position: "static", flexShrink: "0", boxSizing: "content-box", marginLeft: "0px", marginRight: "0px", width: `${w}px` });
+    const section = xNode("n1", "nav", {
+      375: { cs: secCs(375), bbox: { x: 0, y: 0, width: 375, height: 80 } },
+      768: { cs: secCs(768), bbox: { x: 0, y: 0, width: 768, height: 80 } },
+      1280: { cs: secCs(1280), bbox: { x: 0, y: 0, width: 1280, height: 80 } },
+    }, [child]);
+    // A flex track with symmetric padding: its CONTENT width is narrower than the full-viewport section,
+    // so the "fills the flex container content" detectors (isFillsContainerWidth / isFullWidthShrinkSlide)
+    // do NOT fire — leaving the circular-slide detector as the width-plan winner it must be guarded from.
+    const trackCs = { display: "flex", position: "static", paddingLeft: "24px", paddingRight: "24px" };
+    return xNode("n0", "body", {
+      375: { cs: trackCs, bbox: { x: 0, y: 0, width: 375, height: 80 } },
+      768: { cs: trackCs, bbox: { x: 0, y: 0, width: 768, height: 80 } },
+      1280: { cs: trackCs, bbox: { x: 0, y: 0, width: 1280, height: 80 } },
+    }, [section]);
+  }
+
+  it("emits a fluid width for a full-viewport-span shrink-0 flex item, not frozen per-breakpoint px", () => {
+    const css = generateCss(xIr(fullBleedSection()), new Map());
+    const section = allRulesX(css, "n1");
+    assert.ok(!/width:375px|width:768px|width:1280px/.test(section), `a fluid full-bleed section must not freeze to captured px, got: ${section}`);
+    // A fluid outcome is either an explicit fluid width (width:100%/auto) OR no width at all — the block
+    // default resolves to auto and fills the container. Any FIXED px width would be the frozen misfire.
+    assert.ok(!/width:\d/.test(section) || /width:100%|width:auto/.test(section), `a fluid full-bleed section must emit a fluid width (or none), got: ${section}`);
+  });
+});
+
 // ===========================================================================
 // Emission-geometry fix wave (T1/T2/T3/T5, C1 css side, C2)
 // ===========================================================================
@@ -1152,6 +1220,40 @@ describe("generateCss aspectHeightLaw rejects width-clamping ratio transfer (FIX
   });
 });
 
+// FIX 4 — a full-screen hero authored `min-h-[100vh] md:min-h-[calc(100vh - 137px)]` gets its
+// per-viewport min-height baked to px at capture, freezing the hero to one window height and leaving
+// whitespace at other heights. With an authored vh-token corroboration, the constant-offset law
+// `calc(100vh - 137px)` (k=1) must be recovered from samples spanning DIFFERENT viewport heights and
+// re-emitted, instead of the frozen px. XVPS heights are 812/1024/800, so C=137 → 675/887/663px.
+describe("generateCss recovers a viewport-relative min-height law (FIX 4)", () => {
+  function hero(src: string | undefined): IRNode {
+    const n = xNode("n1", "section", {
+      375: { cs: { display: "flex", position: "static", minHeight: "675px" }, bbox: { x: 0, y: 0, width: 375, height: 675 } },
+      768: { cs: { display: "flex", position: "static", minHeight: "887px" }, bbox: { x: 0, y: 0, width: 768, height: 887 } },
+      1280: { cs: { display: "flex", position: "static", minHeight: "663px" }, bbox: { x: 0, y: 0, width: 1280, height: 663 } },
+    });
+    if (src !== undefined) n.srcClass = src;
+    return xNode("n0", "body", Object.fromEntries(XVPS.map((vp) => [vp, { cs: { display: "block", position: "static" }, bbox: { x: 0, y: 0, width: vp, height: 900 } }])), [n]);
+  }
+
+  it("emits calc(100vh - 137px) and drops the frozen px when srcClass carries a vh token", () => {
+    const css = generateCss(xIr(hero("flex min-h-[100vh] md:min-h-[calc(100vh_-_137px)]")), new Map());
+    const all = allRulesX(css, "n1");
+    assert.ok(/min-height:calc\(100vh - 137px\)/.test(all), `hero min-height must become the viewport law, got: ${all}`);
+    assert.ok(!/min-height:663px/.test(all), `desktop min-height must not stay frozen px, got: ${all}`);
+    assert.ok(!/min-height:887px/.test(all), `768 min-height must not stay frozen px, got: ${all}`);
+    assert.ok(!/min-height:675px/.test(all), `375 min-height must not stay frozen px, got: ${all}`);
+  });
+
+  it("keeps the baked px when srcClass has NO viewport-relative token (corroboration guard)", () => {
+    const css = generateCss(xIr(hero("flex min-h-[675px] md:min-h-[663px]")), new Map());
+    const all = allRulesX(css, "n1");
+    assert.ok(!/calc\(100vh/.test(all), `a content-driven min-height must not be mistaken for a vh law, got: ${all}`);
+    assert.ok(/min-height:663px/.test(all) || /min-height:675px/.test(all) || /min-height:887px/.test(all),
+      `without a vh token the baked px min-height must survive, got: ${all}`);
+  });
+});
+
 // C1 (css side) — a computed `grid-template-rows: subgrid` is a STRUCTURAL keyword, not a baked px
 // regime. It must NEVER be dropped by the reflow-mode dropGridRows path (which strips px row tracks).
 describe("collectNodeRules never drops a subgrid rows template (C1)", () => {