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>
2026-07-04 02:22:15 -07:00
parent db0054e43b
commit 6e4921884c
16 changed files with 968 additions and 54 deletions
@@ -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 */ }
@@ -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 });

@@ -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;
    }

@@ -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
@@ -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__" },
@@ -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}`;
@@ -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})`;
  };
@@ -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);
  }
@@ -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;