From 92a5ef419b01d1462722032466c92491ef1ed243 Mon Sep 17 00:00:00 2001
From: ukimsanov <ular.kimsanov@heygen.com>
Date: Sat, 18 Apr 2026 18:48:37 -0400
Subject: [PATCH] feat(capture): improve capture quality + clean up CLAUDE.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Capture improvements:
- Font weights via document.fonts API + DOM sampling (variable font detection)
- Section background-image extraction (no more false #FFFFFF on hero photos)
- Detected libraries surfaced in CLAUDE.md brand summary
- Structured visible-text.txt with [tag] prefixes, cookie/nav noise filtered
- tokens.json cleaned: removed images/paragraphs/icons (duplicated elsewhere),
  filtered sections to heading-only, trimmed cssVariables to design-relevant
- Removed redundant scroll pass in htmlExtractor (2-5s faster per capture)
- Font cap at 20 families, Placeholder/Fallback fonts filtered

CLAUDE.md rewrite:
- Removed prescriptive tone ("use exact strings" → "rephrase freely")
- Removed fluff sections (How to Create, DESIGN.md warning, Example Prompts,
  Source Patterns)
- asset-descriptions.md promoted to first data row
- Removed assets-catalog.json from inventory

Skill fixes:
- Dead shader refs → point to packages/shader-transitions/README.md
- Google Fonts import in techniques.md → local @font-face placeholder
- Added Stripe DESIGN.md as light-brand example
- Removed HANDOFF.md generation from step-7
- Updated step-1 for new font weight + visible-text formats
---
 .../cli/src/capture/agentPromptGenerator.ts   | 160 +++++++-----------
 packages/cli/src/capture/assetDownloader.ts   |  16 +-
 packages/cli/src/capture/contentExtractor.ts  |   8 +-
 packages/cli/src/capture/htmlExtractor.ts     |  19 +--
 packages/cli/src/capture/index.ts             |   9 +-
 packages/cli/src/capture/scaffolding.ts       |   2 +
 packages/cli/src/capture/tokenExtractor.ts    | 100 ++++++++---
 packages/cli/src/capture/types.ts             |  23 ++-
 packages/cli/src/commands/capture.ts          |  15 +-
 .../references/step-1-capture.md              |   4 +-
 .../references/step-2-design.md               |  50 ++++++
 .../references/step-4-storyboard.md           |   4 +-
 .../references/step-6-build.md                |   2 +-
 .../references/step-7-validate.md             |  37 ----
 .../references/techniques.md                  |  10 +-
 15 files changed, 249 insertions(+), 210 deletions(-)

diff --git a/packages/cli/src/capture/agentPromptGenerator.ts b/packages/cli/src/capture/agentPromptGenerator.ts
index 9df7f38dd..fb977d5c1 100644
--- a/packages/cli/src/capture/agentPromptGenerator.ts
+++ b/packages/cli/src/capture/agentPromptGenerator.ts
@@ -20,7 +20,8 @@ export function generateAgentPrompt(
   hasScreenshot: boolean,
   hasLottie?: boolean,
   hasShaders?: boolean,
-  catalogedAssets?: CatalogedAsset[],
+  _catalogedAssets?: CatalogedAsset[],
+  detectedLibraries?: string[],
 ): void {
   const prompt = buildPrompt(
     url,
@@ -29,7 +30,7 @@ export function generateAgentPrompt(
     hasScreenshot,
     hasLottie,
     hasShaders,
-    catalogedAssets,
+    detectedLibraries,
   );
   writeFileSync(join(outputDir, "CLAUDE.md"), prompt, "utf-8");
   writeFileSync(join(outputDir, ".cursorrules"), prompt, "utf-8");
@@ -38,122 +39,81 @@ export function generateAgentPrompt(
 function buildPrompt(
   url: string,
   tokens: DesignTokens,
-  animations: AnimationCatalog | undefined,
+  _animations: AnimationCatalog | undefined,
   hasScreenshot: boolean,
   hasLottie?: boolean,
   hasShaders?: boolean,
-  catalogedAssets?: CatalogedAsset[],
+  detectedLibraries?: string[],
 ): string {
-  const hostname = new URL(url).hostname.replace(/^www\./, "");
-  const title = tokens.title || hostname;
-  const cues = detectImplementationCues(tokens, animations);
+  const title = tokens.title || new URL(url).hostname.replace(/^www\./, "");
 
   const colorSummary = tokens.colors.slice(0, 10).join(", ");
-  const fontSummary = tokens.fonts.join(", ") || "none detected";
-  const sectionCount = tokens.sections?.length ?? 0;
-  const headingCount = tokens.headings?.length ?? 0;
-  const ctaCount = tokens.ctas?.length ?? 0;
+  const fontSummary =
+    tokens.fonts
+      .map(
+        (f) =>
+          f.family +
+          (f.variable && f.weightRange
+            ? ` (${f.weightRange[0]}-${f.weightRange[1]} variable)`
+            : f.weights.length > 0
+              ? ` (${f.weights.join(",")})`
+              : ""),
+      )
+      .join(", ") || "none detected";
 
-  const videoUrls = catalogedAssets
-    ? catalogedAssets
-        .filter((a) => a.type === "Video" && a.url.startsWith("http"))
-        .map((a) => a.url)
-        .filter((u, i, arr) => arr.indexOf(u) === i) // deduplicate
-    : [];
+  // Build the data inventory table rows
+  const tableRows: string[] = [];
+  if (hasScreenshot) {
+    tableRows.push(
+      "| `screenshots/scroll-*.png` | Viewport screenshots of the full page. Start with `scroll-000.png` (hero). |",
+    );
+  }
+  tableRows.push(
+    "| `extracted/asset-descriptions.md` | One-line description of every downloaded asset. **Read this first.** |",
+  );
+  tableRows.push(
+    `| \`extracted/tokens.json\` | Design tokens: ${tokens.colors.length} colors, ${tokens.fonts.length} fonts, ${tokens.headings?.length ?? 0} headings, ${tokens.ctas?.length ?? 0} CTAs |`,
+  );
+  tableRows.push(
+    "| `extracted/visible-text.txt` | Page text in DOM order, prefixed with HTML tag (`[h1]`, `[p]`, `[a]`). Use as context — rephrase freely. |",
+  );
+  if (hasLottie) {
+    tableRows.push(
+      "| `extracted/lottie-manifest.json` | Lottie animations with previews at `assets/lottie/previews/`. |",
+    );
+  }
+  if (hasShaders) {
+    tableRows.push("| `extracted/shaders.json` | WebGL shader source (GLSL). |");
+  }
+  if (detectedLibraries && detectedLibraries.length > 0) {
+    tableRows.push(
+      `| \`extracted/detected-libraries.json\` | Libraries: ${detectedLibraries.join(", ")} |`,
+    );
+  }
+  tableRows.push("| `assets/` | Downloaded images, SVGs, and font files. |");
 
-  return `# ${title} — Captured Website
+  // Brand summary — just the essentials
+  const brandLines: string[] = [];
+  brandLines.push(`- **Colors**: ${colorSummary || "see tokens.json"}`);
+  brandLines.push(`- **Fonts**: ${fontSummary}`);
+  if (detectedLibraries && detectedLibraries.length > 0) {
+    brandLines.push(`- **Built with**: ${detectedLibraries.join(", ")}`);
+  }
+
+  return `# ${title}
 
 Source: ${url}
 
-## How to Create a Video
-
-Invoke the \`/website-to-hyperframes\` skill. It walks you through the full workflow: read data → create DESIGN.md → plan video → build compositions → lint/validate/preview.
-
-If you don't have the skill installed, run: \`npx skills add heygen-com/hyperframes\`
+To create a video from this capture, use the \`/website-to-hyperframes\` skill.
 
 ## What's in This Capture
 
 | File | Contents |
 |------|----------|
-${hasScreenshot ? "| `screenshots/scroll-*.png` | Viewport screenshots covering the full page (1920x1080 each, 30% overlap). **View scroll-000.png FIRST** (hero section), then scan through the rest to understand the full page. |" : ""}
-| \`extracted/tokens.json\` | Design tokens: ${tokens.colors.length} colors, ${tokens.fonts.length} fonts, ${headingCount} headings, ${ctaCount} CTAs, ${sectionCount} sections |
-| \`extracted/visible-text.txt\` | All visible text content in DOM order — use exact strings, never paraphrase |
-| \`extracted/assets-catalog.json\` | Every asset URL (images, fonts, videos, icons) with HTML context |
-| \`extracted/animations.json\` | Animation catalog: ${animations?.summary?.webAnimations ?? 0} web animations, ${animations?.summary?.scrollTargets ?? 0} scroll triggers, ${animations?.summary?.canvases ?? 0} canvases |
-| \`assets/svgs/\` | Extracted inline SVGs (logos, icons, illustrations) |
-| \`assets/\` | Downloaded images and font files — **Read every image file to see what it contains** |
-${hasLottie ? "| `extracted/lottie-manifest.json` | Lottie animations found on this site — read this to see what animations are available (name, dimensions, duration). Embed via `lottie.loadAnimation({ path: 'assets/lottie/animation-0.json' })`. Do NOT read the raw JSON files — they are machine data. |" : ""}
-${videoUrls.length > 0 ? "| `extracted/video-manifest.json` | Video manifest: every `<video>` element with its URL, surrounding heading/caption context, and a preview screenshot. **Read this + view each preview image** to understand what each video shows before using it. |" : ""}
-${hasShaders ? "| `extracted/shaders.json` | Captured WebGL shader source code (GLSL vertex + fragment shaders) |" : ""}
-| \`extracted/asset-descriptions.md\` | One-line description of every downloaded asset — read this first |
-
-> **DESIGN.md does not exist yet.** It will be created when you run the \`/website-to-hyperframes\` workflow. Do not write compositions without it.
+${tableRows.join("\n")}
 
 ## Brand Summary
 
-- **Colors**: ${colorSummary || "see tokens.json"}
-- **Fonts**: ${fontSummary}
-- **Sections**: ${sectionCount} page sections detected
-- **Headings**: ${headingCount} headings extracted
-- **CTAs**: ${ctaCount} calls-to-action found
-${
-  cues.length > 0
-    ? `
-## Source Patterns Detected
-
-${cues.map((c) => `- ${c}`).join("\n")}
-`
-    : ""
-}
-## Example Prompts
-
-Try asking:
-
-- "Make me a 15-second social ad from this capture"
-- "Create a 30-second product tour video"
-- "Turn this into a vertical Instagram reel"
-- "Build a feature announcement video highlighting the top 3 features"
+${brandLines.join("\n")}
 `;
 }
-
-function detectImplementationCues(
-  tokens: DesignTokens,
-  animations: AnimationCatalog | undefined,
-): string[] {
-  const cues: string[] = [];
-
-  if (Object.keys(tokens.cssVariables).length > 10) {
-    cues.push(
-      "CSS custom properties used extensively — preserve design tokens for colors, spacing, and typography.",
-    );
-  }
-
-  if (tokens.fonts.length > 0) {
-    cues.push(
-      `Typography: ${tokens.fonts.join(", ")}. Match these exact font families and weights.`,
-    );
-  }
-
-  if (animations?.summary) {
-    if (animations.summary.scrollTargets > 20) {
-      cues.push(`${animations.summary.scrollTargets} scroll-triggered animations detected.`);
-    }
-    if (animations.summary.webAnimations > 5) {
-      cues.push(`${animations.summary.webAnimations} active Web Animations detected.`);
-    }
-    if (animations.summary.canvases > 0) {
-      cues.push(`${animations.summary.canvases} Canvas/WebGL elements detected.`);
-    }
-  }
-
-  const hasMarquee = animations?.cssDeclarations?.some(
-    (d) =>
-      d.animation?.name?.toLowerCase().includes("marquee") ||
-      d.animation?.name?.toLowerCase().includes("scroll"),
-  );
-  if (hasMarquee) {
-    cues.push("Marquee/ticker animation present — preserve continuous scrolling behavior.");
-  }
-
-  return cues;
-}
diff --git a/packages/cli/src/capture/assetDownloader.ts b/packages/cli/src/capture/assetDownloader.ts
index 3ce644eca..6acf11373 100644
--- a/packages/cli/src/capture/assetDownloader.ts
+++ b/packages/cli/src/capture/assetDownloader.ts
@@ -1,9 +1,8 @@
 /**
  * Download assets (SVGs, images, favicon, video posters) from extracted tokens + asset catalog.
  *
- * Single-pass approach: uses the asset catalog (which already deduplicates srcset variants
- * and keeps the highest resolution) as the primary source for images. This avoids downloading
- * the same image twice at different resolutions.
+ * Uses the asset catalog (which already deduplicates srcset variants and keeps the highest
+ * resolution) as the single source of truth for images. Favicon links are passed separately.
  */
 
 import { writeFileSync, mkdirSync } from "node:fs";
@@ -15,6 +14,7 @@ export async function downloadAssets(
   tokens: DesignTokens,
   outputDir: string,
   catalogedAssets?: CatalogedAsset[],
+  faviconLinks?: Array<{ rel: string; href: string }>,
 ): Promise<DownloadedAsset[]> {
   const assetsDir = join(outputDir, "assets");
   mkdirSync(assetsDir, { recursive: true });
@@ -39,7 +39,7 @@ export async function downloadAssets(
   }
 
   // 2. Favicon
-  for (const icon of tokens.icons) {
+  for (const icon of faviconLinks || []) {
     if (!icon.href) continue;
     try {
       const ext = extname(new URL(icon.href).pathname) || ".ico";
@@ -57,7 +57,6 @@ export async function downloadAssets(
   }
 
   // 3. Images — use the catalog as the single source of truth (highest resolution, deduplicated)
-  //    If no catalog available, fall back to tokens.images
   const imageUrls: { url: string; isPoster: boolean }[] = [];
 
   if (catalogedAssets && catalogedAssets.length > 0) {
@@ -83,13 +82,6 @@ export async function downloadAssets(
       const isPoster = a.contexts.includes("video[poster]");
       imageUrls.push({ url: a.url, isPoster });
     }
-  } else {
-    // Fallback: use tokens.images
-    for (const img of tokens.images) {
-      if (img.width > 200 && img.src.startsWith("http")) {
-        imageUrls.push({ url: img.src, isPoster: false });
-      }
-    }
   }
 
   // Download all images (no arbitrary cap) — Claude Code needs to see every asset to use them creatively.
diff --git a/packages/cli/src/capture/contentExtractor.ts b/packages/cli/src/capture/contentExtractor.ts
index f376944f3..1af165cc5 100644
--- a/packages/cli/src/capture/contentExtractor.ts
+++ b/packages/cli/src/capture/contentExtractor.ts
@@ -121,6 +121,7 @@ export async function extractVisibleText(page: Page): Promise<string> {
   let visibleTextContent = "";
   try {
     visibleTextContent = (await page.evaluate(`(() => {
+      var cookieRe = /^(accept|cookie|privacy|that's fine|got it|i agree|reject all|accept all|manage cookies|consent)$/i;
       var walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT, null);
       var texts = [];
       var node;
@@ -133,7 +134,12 @@ export async function extractVisibleText(page: Page): Promise<string> {
         if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0') continue;
         var tag = el.tagName.toLowerCase();
         if (tag === 'script' || tag === 'style' || tag === 'noscript') continue;
-        texts.push(text);
+        // Skip short text inside nav/footer (catches nav links, cookie consent)
+        var inNavOrFooter = el.closest('nav, footer, [role="navigation"]');
+        if (inNavOrFooter && text.length < 20) continue;
+        // Skip common cookie/consent patterns
+        if (cookieRe.test(text)) continue;
+        texts.push('[' + tag + '] ' + text);
       }
       return texts.join('\\n');
     })()`)) as string;
diff --git a/packages/cli/src/capture/htmlExtractor.ts b/packages/cli/src/capture/htmlExtractor.ts
index 6a6a40674..28ebf96a0 100644
--- a/packages/cli/src/capture/htmlExtractor.ts
+++ b/packages/cli/src/capture/htmlExtractor.ts
@@ -17,22 +17,9 @@ export async function extractHtml(
 ): Promise<ExtractedHtml> {
   const settleTime = opts.settleTime ?? DEFAULT_SETTLE_TIME;
 
-  // Step 1: Trigger lazy loading by scrolling through the page
-  await page.evaluate(`(async () => {
-    var pageHeight = document.body.scrollHeight;
-    var viewportH = window.innerHeight;
-    var step = Math.floor(viewportH * 0.7);
-    for (var y = 0; y < pageHeight + viewportH; y += step) {
-      window.scrollTo(0, y);
-      await new Promise(function(r) { setTimeout(r, 200); });
-    }
-    window.scrollTo(0, pageHeight);
-    await new Promise(function(r) { setTimeout(r, 300); });
-    window.scrollTo(0, 0);
-    await new Promise(function(r) { setTimeout(r, 300); });
-  })()`);
-
-  // Re-measure after lazy load
+  // Lazy-load scroll removed — index.ts already scrolls before calling extractHtml.
+  // Images are loaded by the time we get here.
+  // Settle wait kept as buffer before DOM extraction.
   await new Promise((r) => setTimeout(r, settleTime));
 
   // Step 2: Inline external stylesheets
diff --git a/packages/cli/src/capture/index.ts b/packages/cli/src/capture/index.ts
index aaf599832..81795bd56 100644
--- a/packages/cli/src/capture/index.ts
+++ b/packages/cli/src/capture/index.ts
@@ -403,6 +403,12 @@ export async function captureWebsite(
     // Extract all visible text in DOM order
     const visibleTextContent = await extractVisibleText(page1);
 
+    // Extract favicon links before closing page (removed from tokens to reduce noise)
+    const faviconLinks = (await page1.evaluate(`(() => {
+      var iconEls = Array.from(document.querySelectorAll('link[rel*="icon"], link[rel="apple-touch-icon"]'));
+      return iconEls.map(function(l) { return { rel: l.rel, href: l.href }; });
+    })()`)) as Array<{ rel: string; href: string }>;
+
     await page1.close();
 
     // Download fonts and rewrite URLs to local paths
@@ -439,7 +445,7 @@ export async function captureWebsite(
     let assets: CaptureResult["assets"] = [];
     if (!skipAssets) {
       progress("assets", "Downloading assets...");
-      assets = await downloadAssets(tokens, outputDir, catalogedAssets);
+      assets = await downloadAssets(tokens, outputDir, catalogedAssets, faviconLinks);
     }
 
     // Save visible text content for AI agent to use
@@ -501,6 +507,7 @@ export async function captureWebsite(
       catalogedAssets,
       progress,
       warnings,
+      detectedLibraries,
     );
 
     progress("done", "Capture complete");
diff --git a/packages/cli/src/capture/scaffolding.ts b/packages/cli/src/capture/scaffolding.ts
index e0db0fea8..55ae55f12 100644
--- a/packages/cli/src/capture/scaffolding.ts
+++ b/packages/cli/src/capture/scaffolding.ts
@@ -60,6 +60,7 @@ export async function generateProjectScaffold(
   catalogedAssets: CatalogedAsset[],
   progress: (stage: string, detail?: string) => void,
   warnings: string[],
+  detectedLibraries?: string[],
 ): Promise<void> {
   // Capture output is a DATA folder, not a video project.
   // The agent builds index.html + compositions/ during step 6.
@@ -89,6 +90,7 @@ export async function generateProjectScaffold(
       hasLotties,
       hasShaders,
       catalogedAssets,
+      detectedLibraries,
     );
     progress("agent", "CLAUDE.md generated");
   } catch (err) {
diff --git a/packages/cli/src/capture/tokenExtractor.ts b/packages/cli/src/capture/tokenExtractor.ts
index f07586d26..0993fcf07 100644
--- a/packages/cli/src/capture/tokenExtractor.ts
+++ b/packages/cli/src/capture/tokenExtractor.ts
@@ -41,12 +41,49 @@ const EXTRACT_SCRIPT = `(() => {
   var ogImgEl = document.querySelector('meta[property="og:image"]');
   var ogImage = ogImgEl ? ogImgEl.content : undefined;
 
-  // 3. Fonts
-  var fontSet = {};
-  var fontSamples = [document.body, document.querySelector("h1"), document.querySelector("h2"), document.querySelector("p"), document.querySelector("button")].filter(Boolean);
-  for (var fi = 0; fi < fontSamples.length; fi++) {
-    var family = getComputedStyle(fontSamples[fi]).fontFamily.split(",")[0].replace(/['"]/g, "").trim();
-    if (family && ["serif","sans-serif","monospace","cursive"].indexOf(family) === -1) fontSet[family] = true;
+  // 3. Fonts — enumerate loaded FontFaces + supplement with DOM sampling
+  var fontMap = {};
+  function ensureFont(name) {
+    if (!fontMap[name]) fontMap[name] = { family: name, weights: [], variable: false, weightRange: undefined };
+    return fontMap[name];
+  }
+  function addWeight(entry, w) {
+    var n = parseInt(w, 10);
+    if (!isNaN(n) && entry.weights.indexOf(n) === -1) entry.weights.push(n);
+  }
+  var genericFonts = ["serif","sans-serif","monospace","cursive","system-ui","ui-serif","ui-sans-serif","ui-monospace","ui-rounded","emoji","math","fangsong"];
+  try {
+    document.fonts.forEach(function(face) {
+      var name = face.family.replace(/['"]/g, "").trim();
+      if (!name || genericFonts.indexOf(name.toLowerCase()) !== -1) return;
+      // Skip placeholder/fallback fonts (Framer loads hundreds of these)
+      if (name.indexOf("Placeholder") !== -1 || name.indexOf("Fallback") !== -1) return;
+      var entry = ensureFont(name);
+      var w = (face.weight || "").trim();
+      if (w.indexOf(" ") !== -1) {
+        var parts = w.split(" ");
+        var lo = parseInt(parts[0], 10);
+        var hi = parseInt(parts[1], 10);
+        if (!isNaN(lo) && !isNaN(hi)) {
+          entry.variable = true;
+          entry.weightRange = [lo, hi];
+        }
+      } else {
+        addWeight(entry, w);
+      }
+    });
+  } catch(e) {}
+  // Supplement with DOM sampling
+  var domSamples = Array.from(document.querySelectorAll("h1,h2,h3,h4,h5,h6,p,a,button,span,li,strong,b")).slice(0, 100);
+  for (var fi = 0; fi < domSamples.length; fi++) {
+    try {
+      var cs = getComputedStyle(domSamples[fi]);
+      var family = cs.fontFamily.split(",")[0].replace(/['"]/g, "").trim();
+      if (family && genericFonts.indexOf(family.toLowerCase()) === -1) {
+        var entry = ensureFont(family);
+        addWeight(entry, cs.fontWeight);
+      }
+    } catch(e) {}
   }
 
   // 4. Colors — hybrid: DOM computed styles + visual pixel sampling
@@ -204,10 +241,7 @@ const EXTRACT_SCRIPT = `(() => {
     return { level: parseInt(h.tagName[1]), text: (h.innerText || h.textContent || "").trim().replace(/\\s+/g, ' ').slice(0, 200), fontSize: s.fontSize, fontWeight: s.fontWeight, color: rgbToHex(s.color) || s.color };
   });
 
-  // 6. Paragraphs
-  var paragraphs = Array.from(document.querySelectorAll("p")).slice(0, 10).map(function(p) { return (p.textContent || "").trim().slice(0, 300); }).filter(function(t) { return t.length > 20; });
-
-  // 7. CTAs — match by class AND by text content patterns
+  // 6. CTAs — match by class AND by text content patterns
   // Conservative class selectors (avoid nav links with "action" or "start" in class)
   var ctaSelectors = 'a[class*="btn"], a[class*="button"], a[class*="cta"], button[class*="primary"], button[class*="cta"], [role="button"]';
   var ctaEls = Array.from(document.querySelectorAll(ctaSelectors));
@@ -278,15 +312,7 @@ const EXTRACT_SCRIPT = `(() => {
     };
   }).filter(Boolean).slice(0, 50);
 
-  // 9. Images
-  var imgEls = Array.from(document.querySelectorAll("img[src]")).filter(function(img) { return img.naturalWidth > 200 && isVisible(img); }).slice(0, 15);
-  var images = imgEls.map(function(img) { return { src: img.src, alt: img.alt || "", width: img.naturalWidth, height: img.naturalHeight }; });
-
-  // 10. Icons
-  var iconEls = Array.from(document.querySelectorAll('link[rel*="icon"], link[rel="apple-touch-icon"]'));
-  var icons = iconEls.map(function(l) { return { rel: l.rel, href: l.href }; });
-
-  // 11. Sections — find large visual blocks regardless of HTML tag
+  // 9. Sections — find large visual blocks regardless of HTML tag
   var sectionResults = [];
   // Start with semantic elements, then fall back to large direct children of body/main
   var candidates = Array.from(document.querySelectorAll(
@@ -336,17 +362,45 @@ const EXTRACT_SCRIPT = `(() => {
       }
       if (!sectionBg || sectionBg === "rgba(0, 0, 0, 0)" || sectionBg === "transparent") sectionBg = "#FFFFFF";
     }
+    // Check for background-image when color is transparent/default white
+    var sectionBgImage = undefined;
+    var rawBgImg = getComputedStyle(el).backgroundImage;
+    if (rawBgImg && rawBgImg !== "none" && rawBgImg.indexOf("url(") !== -1) {
+      var start = rawBgImg.indexOf("url(") + 4;
+      var end = rawBgImg.indexOf(")", start);
+      if (end > start) {
+        sectionBgImage = rawBgImg.slice(start, end).replace(/['"]/g, "");
+      }
+    }
     sectionBg = rgbToHex(sectionBg) || sectionBg;
-    sectionResults.push({ selector: selector, type: type, y: Math.round(y), height: Math.round(rect.height), heading: headingText, backgroundColor: sectionBg });
+    var sectionEntry = { selector: selector, type: type, y: Math.round(y), height: Math.round(rect.height), heading: headingText, backgroundColor: sectionBg };
+    if (sectionBgImage) sectionEntry.backgroundImage = sectionBgImage;
+    sectionResults.push(sectionEntry);
   }
   sectionResults.sort(function(a, b) { return a.y - b.y; });
   var filtered = sectionResults.filter(function(s, i) { return i === 0 || Math.abs(s.y - sectionResults[i-1].y) > 100; });
 
+  // Filter cssVariables — keep only color-like values or design-relevant names
+  var colorValueRe = /^(#|rgb|hsl|oklch|oklab|lch|lab|color)/i;
+  var designNameRe = /(color|bg|background|border|text|font|radius|shadow)/i;
+  var filteredVars = {};
+  var varKeys = Object.keys(cssVariables);
+  for (var vi = 0; vi < varKeys.length; vi++) {
+    var varName = varKeys[vi];
+    var varVal = cssVariables[varName];
+    if (colorValueRe.test(varVal) || designNameRe.test(varName)) {
+      filteredVars[varName] = varVal;
+    }
+  }
+
+  // Filter sections — only keep those with a non-empty heading
+  var filteredSections = filtered.filter(function(s) { return s.heading && s.heading.length > 0; });
+
   return {
     title: title, description: description, ogImage: ogImage,
-    cssVariables: cssVariables, fonts: Object.keys(fontSet), colors: Object.keys(colorSet).sort(function(a,b) { return colorSet[b] - colorSet[a]; }).slice(0, 20),
-    headings: headings, paragraphs: paragraphs, ctas: ctas,
-    svgs: svgs, images: images, icons: icons, sections: filtered
+    cssVariables: filteredVars, fonts: Object.keys(fontMap).map(function(k) { var f = fontMap[k]; f.weights.sort(function(a,b){return a-b;}); return f; }).filter(function(f) { return f.weights.length > 0 || f.variable; }).slice(0, 20), colors: Object.keys(colorSet).sort(function(a,b) { return colorSet[b] - colorSet[a]; }).slice(0, 20),
+    headings: headings, ctas: ctas,
+    svgs: svgs, sections: filteredSections
   };
 })()`;
 
diff --git a/packages/cli/src/capture/types.ts b/packages/cli/src/capture/types.ts
index 2d7dcbbc2..102aa7cec 100644
--- a/packages/cli/src/capture/types.ts
+++ b/packages/cli/src/capture/types.ts
@@ -72,6 +72,13 @@ export interface ExtractedHtml {
 
 // ── Design Tokens ───────────────────────────────────────────────────────────
 
+export interface FontToken {
+  family: string;
+  weights: number[];
+  variable?: boolean;
+  weightRange?: [number, number];
+}
+
 export interface DesignTokens {
   /** Page title */
   title: string;
@@ -81,8 +88,8 @@ export interface DesignTokens {
   ogImage?: string;
   /** CSS custom properties from :root */
   cssVariables: Record<string, string>;
-  /** Font families in use */
-  fonts: string[];
+  /** Font families in use (with weights) */
+  fonts: FontToken[];
   /** Extracted colors (background, text, accent) */
   colors: string[];
   /** Headings with text and basic styles */
@@ -93,8 +100,6 @@ export interface DesignTokens {
     fontWeight: string;
     color: string;
   }>;
-  /** Paragraph text (first 10) */
-  paragraphs: string[];
   /** CTA button/link text */
   ctas: Array<{ text: string; href?: string }>;
   /** SVG elements with labels */
@@ -104,15 +109,6 @@ export interface DesignTokens {
     outerHTML: string;
     isLogo: boolean;
   }>;
-  /** Large images on the page */
-  images: Array<{
-    src: string;
-    alt: string;
-    width: number;
-    height: number;
-  }>;
-  /** Favicon/icon URLs */
-  icons: Array<{ rel: string; href: string }>;
   /** Detected page sections with bounding rects */
   sections: Array<{
     selector: string;
@@ -121,6 +117,7 @@ export interface DesignTokens {
     height: number;
     heading: string;
     backgroundColor?: string;
+    backgroundImage?: string;
   }>;
 }
 
diff --git a/packages/cli/src/commands/capture.ts b/packages/cli/src/commands/capture.ts
index c8a1d55f6..71867b6ca 100644
--- a/packages/cli/src/commands/capture.ts
+++ b/packages/cli/src/commands/capture.ts
@@ -131,7 +131,20 @@ export default defineCommand({
         console.log(`  ${c.dim("Screenshots:")} ${result.screenshots.length}`);
         console.log(`  ${c.dim("Assets:")} ${result.assets.length}`);
         console.log(`  ${c.dim("Sections:")} ${result.tokens.sections.length}`);
-        console.log(`  ${c.dim("Fonts:")} ${result.tokens.fonts.join(", ")}`);
+        console.log(
+          `  ${c.dim("Fonts:")} ${result.tokens.fonts
+            .map(function (f) {
+              return (
+                f.family +
+                " (" +
+                (f.variable && f.weightRange
+                  ? f.weightRange[0] + "-" + f.weightRange[1] + " variable"
+                  : f.weights.join(",")) +
+                ")"
+              );
+            })
+            .join(", ")}`,
+        );
         if (result.warnings.length > 0) {
           console.log();
           for (const w of result.warnings) {
diff --git a/skills/website-to-hyperframes/references/step-1-capture.md b/skills/website-to-hyperframes/references/step-1-capture.md
index bfe6cbb27..4f6e89f21 100644
--- a/skills/website-to-hyperframes/references/step-1-capture.md
+++ b/skills/website-to-hyperframes/references/step-1-capture.md
@@ -24,9 +24,9 @@ Read each file below. After reading each one, **write a 1-2 sentence summary** o
 
    After viewing them, write 3-4 sentences describing the site's visual mood, layout patterns, color strategy, and overall feel.
 
-2. **`extracted/tokens.json`** — Note the top 5-7 colors (HEX), all font families, number of sections, and number of headings/CTAs.
+2. **`extracted/tokens.json`** — Note the top 5-7 colors (HEX), all font families with their weights (e.g. `Inter (400,700)` or `Sohne (100-900 variable)`), number of sections, and number of headings/CTAs.
 
-3. **`extracted/visible-text.txt`** — Note the site's headline, tagline, key selling points, and any notable statistics or social proof.
+3. **`extracted/visible-text.txt`** — Each line is prefixed with the HTML tag: `[h1] Heading`, `[p] Body text`, `[a] Link text`. Use these tags to understand hierarchy — headings are key messages, paragraphs are supporting copy. Strip the `[tag]` prefix when quoting text in the script.
 
 4. **`extracted/asset-descriptions.md`** — One-line-per-file summary of all downloaded assets. Note which assets are most visually striking or useful for video (hero images, logos, product screenshots).
 
diff --git a/skills/website-to-hyperframes/references/step-2-design.md b/skills/website-to-hyperframes/references/step-2-design.md
index f4fc65511..8b07ff62b 100644
--- a/skills/website-to-hyperframes/references/step-2-design.md
+++ b/skills/website-to-hyperframes/references/step-2-design.md
@@ -126,3 +126,53 @@ Soulscape 2026 is a cinematic, "high-signal" digital experience that positions i
 - Do not use standard drop shadows — use radial glow or bloom effects instead.
 - Do not use sharp high-speed animations — all motion should be fluid and breathing.
 ```
+
+Here is a contrasting example from a light, corporate brand to show the range:
+
+```markdown
+# Design System
+
+## Overview
+
+Stripe's visual personality is defined by high-precision, technical sophistication, and a fluid, forward-moving motion language. The layout is dense but expertly balanced, utilizing a "canary" grid system that favors high-density data visualizations and modular bento-style layouts. The tone is authoritative and innovative, characterized by smooth CSS animations, complex SVG graphics that mimic UI dashboards, and the iconic "hero wave" background that uses layered gradients to create depth and movement.
+
+## Colors
+
+- **Brand Primary**: #635bff (The signature Stripe Blurple)
+- **Text Solid**: #0a2540 (Deep navy for primary headings)
+- **Text Soft**: #424770 (Subdued slate for descriptions and secondary text)
+- **Surface Background**: #ffffff (White primary surface)
+- **Surface Subdued**: #f6f9fc (Light gray for section contrast)
+- **Accent Green**: #212d45 (Used in high-converting success UI graphics)
+- **Accent Orange**: #ff6118 (Used for specific product highlights like Connect)
+- **Accent Yellow**: #fc5 (Warm highlight used in bento cards)
+- **Border Quiet**: #e6ebf1 (Soft borders for cards and dividers)
+
+## Typography
+
+- **Primary Font**: Sohne (sohne-var), a custom neo-grotesque that balances technical precision with approachability. Used across all headers and body copy.
+- **Monospace Font**: SourceCodePro-Medium, specifically for code snippets, tabular data, and technical UI identifiers.
+- **Heading Scale**: hds-heading--xxl ~3rem, hds-heading--lg ~1.5rem, hds-heading--md ~1.125rem
+- **Body Scale**: Standard body text centers around 1rem (16px) with a line-height of 1.5-1.6.
+
+## Elevation
+
+- **Shadows**: Multi-layered shadow system (e.g., 0 30px 60px -12px rgba(50,50,93,0.25)). Shadows are diffused and deep for a floating effect.
+- **Borders**: Heavy use of 1px solid borders to define bento grid boundaries instead of shadows in flat sections.
+- **Glass/Layering**: Navigation overlays use backdrop-filter blur(5px) with translucent white background.
+
+## Components
+
+- **Navigation Popover**: Animated dropdown spanning page margin with multi-column bento layouts.
+- **Bento Cards**: Interactive grid-aligned containers with gradient hover effects that follow the cursor.
+- **Customer Marquee**: Seamless horizontal scrolling loop of flat-colored SVG logos.
+- **UI Graphics**: Custom HTML/CSS representations of the Stripe Dashboard with tabular numbers and mini-charts.
+- **CTA Buttons**: Rounded-pill shapes with subtle scale transforms on hover.
+
+## Do's and Don'ts
+
+- **Do**: Use smooth cubic-bezier(.25, 1, .5, 1) transitions for all hover states and entering animations.
+- **Do**: Maintain strict vertical alignment between iconography and text labels.
+- **Don't**: Use sharp-cornered cards; always apply a border-radius.
+- **Don't**: Over-saturate backgrounds; stick to white or #f6f9fc and let brand assets provide color pop.
+```
diff --git a/skills/website-to-hyperframes/references/step-4-storyboard.md b/skills/website-to-hyperframes/references/step-4-storyboard.md
index 0579c949b..25f1b5968 100644
--- a/skills/website-to-hyperframes/references/step-4-storyboard.md
+++ b/skills/website-to-hyperframes/references/step-4-storyboard.md
@@ -124,13 +124,13 @@ How this beat hands off to the next. Specify the type and parameters.
 - Zoom through: exit `scale:1→1.2, blur:20px, 0.2s power3.in` → entry `scale:0.75→1, blur:20px→0, 0.5s expo.out`
 - Hard cut / smash cut (for rapid-fire sequences)
 
-**Shader transitions** (choose from `skills/hyperframes/references/transitions/shader-transitions.md`):
+**Shader transitions** (choose from `packages/shader-transitions/README.md`):
 
 - Cross-Warp Morph (organic, versatile) — 0.5-0.8s, power2.inOut
 - Cinematic Zoom (professional momentum) — 0.4-0.6s, power2.inOut
 - Gravitational Lens (otherworldly) — 0.6-1.0s, power2.inOut
 - Glitch (aggressive, high energy) — 0.3-0.5s
-- See `skills/hyperframes/references/transitions/shader-setup.md` for the full WebGL boilerplate
+- See `packages/shader-transitions/README.md` for the full API, available shaders, and setup
 
 **How velocity-matched CSS transitions work:**
 Exit the outgoing beat with an accelerating ease (power2.in or power3.in) plus a blur ramp. Enter the incoming beat with a decelerating ease (power2.out or power3.out) plus blur clear. The fastest point of both easing curves meets at the cut — the viewer perceives continuous camera motion, not two discrete animations. Match exit velocity to entry velocity within ~5% tolerance.
diff --git a/skills/website-to-hyperframes/references/step-6-build.md b/skills/website-to-hyperframes/references/step-6-build.md
index be8a2d498..2ec797dc9 100644
--- a/skills/website-to-hyperframes/references/step-6-build.md
+++ b/skills/website-to-hyperframes/references/step-6-build.md
@@ -82,7 +82,7 @@ Every visible element must have continuous motion. A still image on a still back
 Check the storyboard's transition specification for this beat:
 
 - **CSS transition**: implement the exit animation (e.g., `y:-150, blur:30px, 0.33s power2.in`). The next composition handles its own entry.
-- **Shader transition**: no exit animation needed — the shader handles the blend. Read `skills/hyperframes/references/transitions/shader-setup.md` for the full WebGL boilerplate and `skills/hyperframes/references/transitions/shader-transitions.md` for the fragment shader. Copy the FULL boilerplate — a simplified version produces black screens.
+- **Shader transition**: no exit animation needed — the shader handles the blend. Read `packages/shader-transitions/README.md` for the API, available shaders, and setup. The package handles WebGL init, capture, and GSAP integration — do not copy raw GLSL manually.
 - **Hard cut**: no exit animation. The scene simply ends.
 
 For all CSS transition types and their GSAP implementations, read `skills/hyperframes/references/transitions/catalog.md`.
diff --git a/skills/website-to-hyperframes/references/step-7-validate.md b/skills/website-to-hyperframes/references/step-7-validate.md
index fa094c1f4..428781ddc 100644
--- a/skills/website-to-hyperframes/references/step-7-validate.md
+++ b/skills/website-to-hyperframes/references/step-7-validate.md
@@ -70,40 +70,3 @@ npx hyperframes preview
 ```
 
 Open the studio in a browser. Scrub through every beat.
-
-## Create HANDOFF.md
-
-Write a `HANDOFF.md` for multi-session continuity:
-
-```markdown
-# Handoff — [Project Name]
-
-**Date:** [today]
-**Preview:** `npx hyperframes preview`
-
-## What's Built
-
-| Beat | File                 | Dur  | Status | Notes |
-| ---- | -------------------- | ---- | ------ | ----- |
-| 1    | beat-1-hook.html     | 5.2s | Built  | ...   |
-| 2    | beat-2-features.html | 6.8s | Built  | ...   |
-
-## Audio
-
-| Asset           | Status | Notes                                |
-| --------------- | ------ | ------------------------------------ |
-| narration.wav   | Done   | [provider], [voice name], [duration] |
-| transcript.json | Done   | [word count] words, [duration]       |
-
-## What Needs Work
-
-- [any known issues, polish requests, missing SFX]
-
-## Commands
-
-npx hyperframes preview
-npx hyperframes lint
-npx hyperframes validate
-npx hyperframes snapshot <project-dir> --at <beat-midpoints>
-npx hyperframes render --output renders/final.mp4
-```
diff --git a/skills/website-to-hyperframes/references/techniques.md b/skills/website-to-hyperframes/references/techniques.md
index f380dff8c..f3576e7f2 100644
--- a/skills/website-to-hyperframes/references/techniques.md
+++ b/skills/website-to-hyperframes/references/techniques.md
@@ -251,7 +251,15 @@ Animate font-variation-settings to reshape glyphs in real-time. Works with varia
 
 ```html
 <style>
-  @import url("https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,100..900&display=block");
+  /* Load the captured local variable font — do NOT use Google Fonts @import.
+     Replace this placeholder with an @font-face pointing to assets/fonts/. */
+  @font-face {
+    font-family: "Fraunces";
+    src: url("../assets/fonts/Fraunces-Variable.woff2") format("woff2");
+    font-weight: 100 900;
+    font-style: normal;
+    font-display: block;
+  }
   .wordmark {
     --opsz: 144;
     --wght: 440;