fix: address PR review comments + improve capture quality

Review fixes (16 comments from jrusso1020 + vanceingalls):
- screenshotCapture: remove Playwright dep, use Puppeteer for all screenshots
- screenshotCapture: dynamic screenshot count based on page height (30% overlap)
- snapshot.ts: fix duration() function-vs-property bug, cross-platform path guard
- htmlExtractor: fix code injection via parameterized evaluate
- index.ts: video preview re-measures position after scroll, .env file loading
- capture.ts: BLOCKED.md on timeout failures
- gsap.ts: 5 inline-style lint tests added (all pass)
- Remove Playwright, patchright deps; @google/genai to optionalDependencies
- Gitignore: generic patterns instead of 20 hardcoded directories
- Remove asset-sourcing.md, video-recipes.md (unused, duplicated guidance)

Capture quality improvements (tested on 10+ websites):
- Color extraction: canvas-based oklch/lab resolver, pixel sampling via
  elementFromPoint, broad sweep for accent colors, gradient/shadow extraction
- Section detection: broadened selectors for div-based layouts, height cap
  to skip page-level wrappers, parent bg walkup for dark sites
- Font downloads: cap 6 per family / 30 total (Cal.com: 306→30)
- CTA detection: text pattern matching + nav context filtering
- Heading text: innerText with whitespace normalization
- Gemini captioning: maxOutputTokens 100→300, .env auto-loading
- .env.example updated with GEMINI_API_KEY docs
- TTS ranking: Kokoro first with Python 3.10+ note
This commit is contained in:
ularkim
2026-04-15 21:15:05 -04:00
parent 6335934cc9
commit 626670801f
19 changed files with 486 additions and 784 deletions
+2 -2
View File
@@ -1,5 +1,5 @@
# No environment variables required for basic usage.
# Run `pnpm dev` to start the studio, `npx hyperframes render` to render video.
# Run `bun run dev` to start the studio, `npx hyperframes render` to render video.
# Optional integrations:
# ANTHROPIC_API_KEY= # For AI-assisted composition via MCP
# GEMINI_API_KEY= # AI image captioning during website capture (https://aistudio.google.com/apikey)
+7 -22
View File
@@ -64,26 +64,11 @@ skills-lock.json
skills/hyperframes-animation-map/
skills/hyperframes-contrast/
# Capture outputs (new captures go to captures/ by default)
# Capture outputs
captures/
notion-promo/
notion-com-capture/
# Existing test captures at repo root (legacy)
notion-demo/
notion-ai-agents/
stripe-launch/
stripe-investor/
stripe-website/
linear-ad/
soulscape-demo/
soulscape-film/
midjourney/
vercel-tour/
figma-ad/
arc-browser/
raycast-demo/
rive-demo/
lusion-brand/
motion-zajno/
notion/
# Legacy test captures at repo root (use captures/ instead)
*-capture/
*-demo/
*-ad/
*-tour/
*-brand/
+3 -18
View File
@@ -4,10 +4,6 @@
"workspaces": {
"": {
"name": "hyperframes-monorepo",
"dependencies": {
"patchright": "^1.59.3",
"purgecss": "^8.0.0",
},
"devDependencies": {
"@commitlint/cli": "^20.5.0",
"@commitlint/config-conventional": "^20.5.0",
@@ -30,7 +26,6 @@
"hyperframes": "./dist/cli.js",
},
"dependencies": {
"@google/genai": "^1.50.0",
"@hono/node-server": "^1.8.0",
"@puppeteer/browsers": "^2.13.0",
"adm-zip": "^0.5.16",
@@ -41,7 +36,6 @@
"hono": "^4.0.0",
"mime-types": "^3.0.2",
"open": "^10.0.0",
"playwright": "^1.59.1",
"postcss": "^8.5.8",
"prettier": "^3.8.1",
"puppeteer-core": "^24.39.1",
@@ -62,6 +56,9 @@
"typescript": "^5.0.0",
"vitest": "^3.2.4",
},
"optionalDependencies": {
"@google/genai": "^1.50.0",
},
},
"packages/core": {
"name": "@hyperframes/core",
@@ -1297,10 +1294,6 @@
"parse5": ["parse5@7.3.0", "", { "dependencies": { "entities": "6.0.1" } }, "sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw=="],
"patchright": ["patchright@1.59.3", "", { "dependencies": { "patchright-core": "v1.59.3" }, "optionalDependencies": { "fsevents": "2.3.2" }, "bin": { "patchright": "cli.js" } }, "sha512-0i/6bXgv0rGz5khInk8nHb2sX9RbAu/whRUJDL3zvP5j0ovX9ITHF+o/3XlBu0UJ092YvQjO+8pGPEOnzHeeBA=="],
"patchright-core": ["patchright-core@1.59.3", "", { "bin": { "patchright-core": "cli.js" } }, "sha512-EXq8a3nOoiubBtM77W9vYJDP/nFBuGaQK5CAzkaCr9/PTU5DPT1PDW0mDLdeX0P7bzSUgXEHiogHlC4zK2qSzw=="],
"path-key": ["path-key@3.1.1", "", {}, "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q=="],
"path-parse": ["path-parse@1.0.7", "", {}, "sha512-LDJzPVEEEPR+y48z93A0Ed0yXb8pAByGWo/k5YYdYgpY2/2EsOsksJrq7lOHxryrVOn1ejG6oAp8ahvOIQD8sw=="],
@@ -1323,10 +1316,6 @@
"pkg-types": ["pkg-types@1.3.1", "", { "dependencies": { "confbox": "0.1.8", "mlly": "1.8.2", "pathe": "2.0.3" } }, "sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ=="],
"playwright": ["playwright@1.59.1", "", { "dependencies": { "playwright-core": "1.59.1" }, "optionalDependencies": { "fsevents": "2.3.2" }, "bin": { "playwright": "cli.js" } }, "sha512-C8oWjPR3F81yljW9o5OxcWzfh6avkVwDD2VYdwIGqTkl+OGFISgypqzfu7dOe4QNLL2aqcWBmI3PMtLIK233lw=="],
"playwright-core": ["playwright-core@1.59.1", "", { "bin": { "playwright-core": "cli.js" } }, "sha512-HBV/RJg81z5BiiZ9yPzIiClYV/QMsDCKUyogwH9p3MCP6IYjUFu/MActgYAvK0oWyV9NlwM3GLBjADyWgydVyg=="],
"postcss": ["postcss@8.5.8", "", { "dependencies": { "nanoid": "3.3.11", "picocolors": "1.1.1", "source-map-js": "1.2.1" } }, "sha512-OW/rX8O/jXnm82Ey1k44pObPtdblfiuWnrd8X7GJ7emImCOstunGbXUpp7HdBrFQX6rJzn3sPT397Wp5aCwCHg=="],
"postcss-import": ["postcss-import@15.1.0", "", { "dependencies": { "postcss-value-parser": "4.2.0", "read-cache": "1.0.0", "resolve": "1.22.11" }, "peerDependencies": { "postcss": "8.5.8" } }, "sha512-hpr+J05B2FVYUAXHeK1YyI267J/dDDhMU6B6civm8hSY1jYJnBXxzKDKDswzJmtLHryrjhnDjqqp/49t8FALew=="],
@@ -1655,12 +1644,8 @@
"parse5/entities": ["entities@6.0.1", "", {}, "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g=="],
"patchright/fsevents": ["fsevents@2.3.2", "", { "os": "darwin" }, "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA=="],
"path-scurry/lru-cache": ["lru-cache@10.4.3", "", {}, "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ=="],
"playwright/fsevents": ["fsevents@2.3.2", "", { "os": "darwin" }, "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA=="],
"postcss-load-config/jiti": ["jiti@1.21.7", "", { "bin": { "jiti": "bin/jiti.js" } }, "sha512-/imKNG4EbWNrVjoNC/1H5/9GFy+tqjGBHCaSsN+P2RnPqjsLmv6UD3Ej+Kj8nBWaRAwyk7kK5ZUc+OEatnTR3A=="],
"postcss-nested/postcss-selector-parser": ["postcss-selector-parser@6.1.2", "", { "dependencies": { "cssesc": "3.0.0", "util-deprecate": "1.0.2" } }, "sha512-Q8qQfPiZ+THO/3ZrOrO0cJJKfpYCagtMUkXbnEfmgUjwXg6z/WBeOyS9APBBPCTSiDV+s4SwQGu8yFsiMRIudg=="],
-4
View File
@@ -28,10 +28,6 @@
"generate:previews": "tsx scripts/generate-template-previews.ts",
"prepare": "test -d .git && lefthook install || true"
},
"dependencies": {
"patchright": "^1.59.3",
"purgecss": "^8.0.0"
},
"devDependencies": {
"@commitlint/cli": "^20.5.0",
"@commitlint/config-conventional": "^20.5.0",
+3 -2
View File
@@ -25,7 +25,6 @@
"typecheck": "tsc --noEmit"
},
"dependencies": {
"@google/genai": "^1.50.0",
"@hono/node-server": "^1.8.0",
"@puppeteer/browsers": "^2.13.0",
"adm-zip": "^0.5.16",
@@ -36,7 +35,6 @@
"hono": "^4.0.0",
"mime-types": "^3.0.2",
"open": "^10.0.0",
"playwright": "^1.59.1",
"postcss": "^8.5.8",
"prettier": "^3.8.1",
"puppeteer-core": "^24.39.1",
@@ -57,6 +55,9 @@
"typescript": "^5.0.0",
"vitest": "^3.2.4"
},
"optionalDependencies": {
"@google/genai": "^1.50.0"
},
"engines": {
"node": ">=22"
}
@@ -48,7 +48,7 @@ function buildPrompt(
const title = tokens.title || hostname;
const cues = detectImplementationCues(tokens, animations);
const colorSummary = tokens.colors.slice(0, 6).join(", ");
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;
@@ -75,7 +75,7 @@ If you don't have the skill installed, run: \`npx skills add heygen-com/hyperfra
| File | Contents |
|------|----------|
${hasScreenshot ? "| `screenshots/full-page.png` | Full-page screenshot (very tall — hard to read details, use scroll screenshots instead) |\n| `screenshots/scroll-0.png` | Hero section at 1920x1080 — **VIEW THIS FIRST** to understand the site's look and feel |\n| `screenshots/scroll-25.png` | Page at 25% scroll — 1920x1080 readable viewport |\n| `screenshots/scroll-50.png` | Page at 50% scroll — 1920x1080 readable viewport |\n| `screenshots/scroll-75.png` | Page at 75% scroll — 1920x1080 readable viewport |\n| `screenshots/scroll-100.png` | Page bottom at 1920x1080 — footer and final sections |" : ""}
${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 |
+31 -1
View File
@@ -198,10 +198,39 @@ export async function downloadAndRewriteFonts(css: string, outputDir: string): P
if (fontUrls.size === 0) return css;
// Limit font downloads to avoid bloat. Google Fonts serves 20+ unicode-range
// subsets per weight — we only need a few per family for video production.
const MAX_FONTS_PER_FAMILY = 6;
const MAX_TOTAL_FONTS = 30;
const familyCounts = new Map<string, number>();
// Extract font-family from the @font-face rule containing each URL
const getFamilyForUrl = (url: string): string => {
const idx = css.indexOf(url);
if (idx === -1) return "_unknown";
const blockStart = css.lastIndexOf("@font-face", idx);
if (blockStart === -1) return "_unknown";
const blockSlice = css.slice(blockStart, idx);
const familyMatch = blockSlice.match(/font-family\s*:\s*['"]?([^'";}\n]+)/i);
return familyMatch?.[1] ? familyMatch[1].trim().toLowerCase() : "_unknown";
};
// Prioritize Latin subsets over CJK/Arabic/etc unicode ranges
const sortedUrls = Array.from(fontUrls).sort((a, b) => {
const aLatin = /latin|[A-Za-z0-9]{10,}\.woff/.test(a) ? 0 : 1;
const bLatin = /latin|[A-Za-z0-9]{10,}\.woff/.test(b) ? 0 : 1;
return aLatin - bLatin;
});
let rewritten = css;
let count = 0;
for (const fontUrl of fontUrls) {
for (const fontUrl of sortedUrls) {
if (count >= MAX_TOTAL_FONTS) break;
const family = getFamilyForUrl(fontUrl);
const familyCount = familyCounts.get(family) || 0;
if (familyCount >= MAX_FONTS_PER_FAMILY) continue;
try {
const urlObj = new URL(fontUrl);
const filename = urlObj.pathname.split("/").pop() || `font-${count}.woff2`;
@@ -212,6 +241,7 @@ export async function downloadAndRewriteFonts(css: string, outputDir: string): P
if (buffer) {
writeFileSync(localPath, buffer);
rewritten = rewritten.split(fontUrl).join(relativePath);
familyCounts.set(family, familyCount + 1);
count++;
}
} catch {
+9 -6
View File
@@ -59,13 +59,16 @@ export async function extractHtml(
});
// Add the CSS as a <style> tag in <head> via Puppeteer's addStyleTag
await page.addStyleTag({ content: css });
// Remove the original <link> tag
await page.evaluate(`(() => {
var links = document.querySelectorAll('link[rel="stylesheet"]');
for (var i = 0; i < links.length; i++) {
if (links[i].href === "${href}") { links[i].remove(); break; }
// Remove the original <link> tag (use parameterized evaluate to avoid injection)
await page.evaluate((targetHref: string) => {
const links = document.querySelectorAll('link[rel="stylesheet"]');
for (const link of links) {
if ((link as HTMLLinkElement).href === targetHref) {
link.remove();
break;
}
}
})()`);
}, href);
} catch {
/* network error — skip */
}
+79 -30
View File
@@ -46,6 +46,37 @@ export async function captureWebsite(
onProgress?.(stage, detail);
};
// Load .env file from repo root if it exists (for GEMINI_API_KEY, etc.)
try {
const { readFileSync: readEnv } = await import("node:fs");
const { resolve: resolvePath } = await import("node:path");
// Walk up from outputDir to find .env in repo root
let dir = resolvePath(outputDir);
for (let i = 0; i < 5; i++) {
const envPath = resolvePath(dir, ".env");
try {
const envContent = readEnv(envPath, "utf-8");
for (const line of envContent.split("\n")) {
const trimmed = line.trim();
if (!trimmed || trimmed.startsWith("#")) continue;
const eq = trimmed.indexOf("=");
if (eq === -1) continue;
const key = trimmed.slice(0, eq).trim();
const val = trimmed
.slice(eq + 1)
.trim()
.replace(/^["']|["']$/g, "");
if (!process.env[key]) process.env[key] = val;
}
break;
} catch {
dir = resolvePath(dir, "..");
}
}
} catch {
/* .env loading is best-effort */
}
// Create output directories
mkdirSync(join(outputDir, "extracted"), { recursive: true });
mkdirSync(join(outputDir, "screenshots"), { recursive: true });
@@ -172,6 +203,30 @@ export async function captureWebsite(
await page1.goto(url, { waitUntil: "networkidle0", timeout });
await new Promise((r) => setTimeout(r, settleTime));
// Check if the page loaded real content or an anti-bot challenge
const pageContentCheck = (await page1.evaluate(`(() => {
var text = (document.body.innerText || "").trim();
var title = document.title || "";
var isChallenged = /cloudflare|just a moment|checking your browser|access denied|blocked|captcha|verify you are human/i.test(text + " " + title);
return { textLength: text.length, title: title, isChallenged: isChallenged };
})()`)) as { textLength: number; title: string; isChallenged: boolean };
if (pageContentCheck.isChallenged || pageContentCheck.textLength < 200) {
const reason = pageContentCheck.isChallenged
? "Anti-bot protection detected (Cloudflare challenge or similar)"
: "Page has very little text content (" +
pageContentCheck.textLength +
" chars) — may be blocked or a client-rendered SPA that needs more time";
warnings.push(reason);
progress("warn", reason);
// Write a BLOCKED.md file so the user/agent knows what happened
writeFileSync(
join(outputDir, "BLOCKED.md"),
`# Capture Warning\n\n${reason}\n\nThe page at ${url} may not have been captured correctly.\n\n## What to try\n\n- Re-run with a longer timeout: \`--timeout 60000\`\n- The site may require authentication or block headless browsers\n- Try capturing from a different URL on the same domain\n`,
"utf-8",
);
}
// Scroll through page to trigger lazy-loaded images and Lottie animations
await page1.evaluate(`(async () => {
var h = document.body.scrollHeight;
@@ -408,20 +463,12 @@ a.addEventListener('DOMLoaded',function(){a.goToAndStop(${midFrame},true);window
progress("animations", "Cataloging animations...");
animationCatalog = await collectAnimationCatalog(page1, cdpAnims, cdp);
// Capture per-section viewport screenshots (1920x1080 each — readable by AI vision)
progress("screenshots", "Capturing viewport screenshots...");
const { captureScreenshots, captureFullPageScreenshot } =
await import("./screenshotCapture.js");
const sectionScreenshots = await captureScreenshots(page1, outputDir, { maxScreenshots: 24 });
progress("screenshots", `${sectionScreenshots.length} section screenshots captured`);
// Also capture full-page screenshot + scroll-position screenshots
progress("screenshots", "Capturing full-page screenshot...");
const fullPageScreenshot = await captureFullPageScreenshot(page1, outputDir, url);
const screenshots: string[] = [...sectionScreenshots];
if (fullPageScreenshot) {
screenshots.push(fullPageScreenshot);
}
// Capture scroll-position viewport screenshots (1920x1080 at 10 scroll depths)
// These show the page in its natural state — sticky headers, scroll animations fired.
progress("screenshots", "Capturing scroll screenshots...");
const { captureScrollScreenshots } = await import("./screenshotCapture.js");
const screenshots = await captureScrollScreenshots(page1, outputDir);
progress("screenshots", `${screenshots.length} scroll screenshots captured`);
// Strip framework scripts from the extracted body — keep visual library scripts
// IMPORTANT: Use non-greedy matching within individual script tags only
@@ -574,23 +621,25 @@ a.addEventListener('DOMLoaded',function(){a.goToAndStop(${midFrame},true);window
// Scroll to the video element so it's in the viewport
await page1.evaluate(`window.scrollTo(0, ${Math.max(0, v.top - 100)})`);
await new Promise((r) => setTimeout(r, 300));
// Re-measure viewport-relative position after scroll
const clipY = v.top - Math.max(0, v.top - 100);
await page1.evaluate(`(() => {
var vids = Array.from(document.querySelectorAll('video'));
vids.forEach(function(v) {
if ((v.src || v.currentSrc).includes(${JSON.stringify(v.filename)})) {
try { v.play(); v.pause(); } catch(e) {}
}
});
})()`);
// Re-measure position after scroll (layout may have shifted)
const rect = (await page1.evaluate((fn) => {
const vid = [...document.querySelectorAll("video")].find((x) =>
(x.src || x.currentSrc || "").includes(fn),
);
if (!vid) return null;
// Seek to 0.1s and wait for a frame to decode
vid.currentTime = 0.1;
return vid.getBoundingClientRect().toJSON();
}, v.filename)) as { x: number; y: number; width: number; height: number } | null;
if (!rect || rect.width < 10) continue;
await new Promise((r) => setTimeout(r, 200)); // let decoder settle
await page1.screenshot({
path: previewPath,
clip: {
x: Math.max(0, v.left),
y: Math.max(0, clipY),
width: Math.min(v.width, 1920),
height: Math.min(v.height, 1080),
x: Math.max(0, rect.x),
y: Math.max(0, rect.y),
width: Math.min(rect.width, 1920),
height: Math.min(rect.height, 1080),
},
});
} catch {
@@ -858,7 +907,7 @@ a.addEventListener('DOMLoaded',function(){a.goToAndStop(${midFrame},true);window
],
},
],
config: { maxOutputTokens: 100 },
config: { maxOutputTokens: 300 },
});
return { file, caption: response.text?.trim() || "" };
}),
@@ -1093,7 +1142,7 @@ a.addEventListener('DOMLoaded',function(){a.goToAndStop(${midFrame},true);window
url,
tokens,
animationCatalog,
!!fullPageScreenshot,
screenshots.length > 0,
discoveredLotties.length > 0,
existsSync(join(outputDir, "extracted", "shaders.json")),
catalogedAssets,
+61 -163
View File
@@ -1,5 +1,5 @@
/**
* Full-page screenshot capture.
* Screenshot capture for the website capture pipeline.
*
* All page.evaluate() calls use string expressions to avoid
* tsx/esbuild __name injection (see esbuild issue #1031).
@@ -9,176 +9,74 @@ import type { Page } from "puppeteer-core";
import { writeFileSync, mkdirSync } from "node:fs";
import { join } from "node:path";
const SCROLL_PAD = 200;
export async function captureScreenshots(
page: Page,
outputDir: string,
opts: { maxScreenshots?: number } = {},
): Promise<string[]> {
const maxScreenshots = opts.maxScreenshots ?? 24;
/**
* Capture viewport screenshots covering the entire page height.
*
* Scrolls down the page in viewport-sized steps (with slight overlap),
* taking a 1920x1080 screenshot at each position. The number of screenshots
* depends on the page height — short pages get fewer, long pages get more.
* Capped at 20 to avoid excessive output on extremely long pages.
*
* Unlike the old section-tiling approach, this does NOT disable sticky/fixed
* elements — screenshots show the page in its natural browsing state with
* scroll-triggered animations fired.
*/
export async function captureScrollScreenshots(page: Page, outputDir: string): Promise<string[]> {
const screenshotsDir = join(outputDir, "screenshots");
mkdirSync(screenshotsDir, { recursive: true });
// Step 1: Calculate capture positions
const positions = (await page.evaluate(`(() => {
var de = document.documentElement;
var body = document.body;
var fullHeight = Math.max(de.clientHeight, body.scrollHeight, de.scrollHeight, body.offsetHeight, de.offsetHeight);
var viewportH = window.innerHeight;
var yDelta = viewportH - (viewportH > ${SCROLL_PAD} ? ${SCROLL_PAD} : 0);
var positions = [];
for (var y = 0; y < fullHeight; y += yDelta) positions.push(y);
var lastPos = fullHeight - viewportH;
if (lastPos > 0 && (positions.length === 0 || positions[positions.length - 1] < lastPos - 10)) positions.push(lastPos);
if (positions.length > ${maxScreenshots}) {
var sampled = [positions[0]];
var stride = (positions.length - 1) / (${maxScreenshots} - 1);
for (var i = 1; i < ${maxScreenshots} - 1; i++) sampled.push(positions[Math.round(i * stride)]);
sampled.push(positions[positions.length - 1]);
return sampled;
}
return positions;
})()`)) as number[];
// Step 2: Disable fixed/sticky elements
await page.evaluate(`(() => {
var style = document.createElement("style");
style.id = "__hf_capture_style";
style.textContent = "*, *::before, *::after { transition-duration: 0s !important; animation-duration: 0s !important; }";
document.head.appendChild(style);
document.querySelectorAll("*").forEach(function(el) {
var cs = getComputedStyle(el);
if (cs.position === "fixed" || cs.position === "sticky") {
el.dataset.hfOrigPos = cs.position;
el.style.setProperty("position", "absolute", "important");
}
});
})()`);
// Step 3: Capture each position
await page.evaluate(`window.scrollTo(0, 0)`);
await new Promise((r) => setTimeout(r, 200));
const MAX_SCREENSHOTS = 20;
const filePaths: string[] = [];
for (let i = 0; i < positions.length; i++) {
await page.evaluate(`window.scrollTo(0, ${positions[i]})`);
await new Promise((r) => setTimeout(r, 350));
try {
const scrollHeight = (await page.evaluate(
`Math.max(document.body.scrollHeight, document.documentElement.scrollHeight)`,
)) as number;
const viewportHeight = (await page.evaluate(`window.innerHeight`)) as number;
const filename = `section-${String(i).padStart(2, "0")}.png`;
const filePath = join(screenshotsDir, filename);
// Calculate scroll positions: step by 70% of viewport (30% overlap between shots)
const step = Math.floor(viewportHeight * 0.7);
const positions: number[] = [0];
for (let y = step; y < scrollHeight - viewportHeight; y += step) {
positions.push(y);
}
// Always include the bottom of the page
const lastPos = Math.max(0, scrollHeight - viewportHeight);
if (positions[positions.length - 1] !== lastPos) {
positions.push(lastPos);
}
const buffer = await page.screenshot({ type: "png" });
writeFileSync(filePath, buffer);
filePaths.push(`screenshots/${filename}`);
// Downsample if too many positions
let finalPositions = positions;
if (positions.length > MAX_SCREENSHOTS) {
finalPositions = [positions[0]!];
const stride = (positions.length - 1) / (MAX_SCREENSHOTS - 1);
for (let i = 1; i < MAX_SCREENSHOTS - 1; i++) {
finalPositions.push(positions[Math.round(i * stride)]!);
}
finalPositions.push(positions[positions.length - 1]!);
}
for (let i = 0; i < finalPositions.length; i++) {
await page.evaluate(`window.scrollTo(0, ${finalPositions[i]})`);
await new Promise((r) => setTimeout(r, 400));
const pct = Math.round(
(finalPositions[i]! / Math.max(1, scrollHeight - viewportHeight)) * 100,
);
const filename = `scroll-${String(Math.min(pct, 100)).padStart(3, "0")}.png`;
const filePath = join(screenshotsDir, filename);
const buffer = await page.screenshot({ type: "png" });
writeFileSync(filePath, buffer);
filePaths.push(`screenshots/${filename}`);
}
// Reset scroll
await page.evaluate(`window.scrollTo(0, 0)`);
await new Promise((r) => setTimeout(r, 200));
} catch {
/* scroll screenshots are non-critical */
}
// Step 4: Restore
await page.evaluate(`(() => {
var style = document.getElementById("__hf_capture_style");
if (style) style.remove();
document.querySelectorAll("[data-hf-orig-pos]").forEach(function(el) {
el.style.removeProperty("position");
delete el.dataset.hfOrigPos;
});
window.scrollTo(0, 0);
})()`);
return filePaths;
}
/**
* Capture a full-page screenshot using Playwright.
*
* Playwright uses CDP Page.getLayoutMetrics + captureBeyondViewport
* WITHOUT resizing the viewport — this preserves position:fixed,
* vh units, and CSS stacking contexts that Puppeteer's fullPage breaks.
*
* We use a separate Playwright browser instance for just the screenshot,
* since the main capture pipeline uses Puppeteer.
*/
export async function captureFullPageScreenshot(
_page: Page,
outputDir: string,
url?: string,
): Promise<string | undefined> {
const screenshotsDir = join(outputDir, "screenshots");
mkdirSync(screenshotsDir, { recursive: true });
if (!url) return undefined;
try {
const { chromium } = await import("playwright");
const browser = await chromium.launch({
headless: true,
args: ["--disable-blink-features=AutomationControlled"],
});
const context = await browser.newContext({
viewport: { width: 1920, height: 1080 },
userAgent:
"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
});
const pwPage = await context.newPage();
// Mask automation signals
await pwPage.addInitScript(() => {
Object.defineProperty(navigator, "webdriver", { get: () => false });
});
await pwPage.goto(url, { waitUntil: "networkidle", timeout: 60000 });
// Scroll through to trigger lazy loading
await pwPage.evaluate(async () => {
const step = Math.floor(window.innerHeight * 0.7);
const limit = Math.min(document.body.scrollHeight, 50000);
for (let y = 0; y < limit; y += step) {
window.scrollTo(0, y);
await new Promise((r) => setTimeout(r, 200));
}
window.scrollTo(0, document.body.scrollHeight);
await new Promise((r) => setTimeout(r, 500));
window.scrollTo(0, 0);
await new Promise((r) => setTimeout(r, 300));
});
// Wait for images
await pwPage
.waitForFunction(
() => Array.from(document.querySelectorAll("img")).every((img) => img.complete),
{ timeout: 10000 },
)
.catch(() => {});
// Freeze animations
await pwPage.addStyleTag({
content:
"*, *::before, *::after { transition-duration: 0s !important; animation-duration: 0s !important; }",
});
await pwPage.waitForTimeout(200);
const filename = "full-page.png";
const filePath = join(screenshotsDir, filename);
await pwPage.screenshot({ path: filePath, fullPage: true, type: "png" });
// Multi-scroll-position viewport screenshots (captures scroll-driven animation states)
try {
const scrollHeight = await pwPage.evaluate(() => document.body.scrollHeight);
const positions = [0, 0.25, 0.5, 0.75, 1.0];
for (let i = 0; i < positions.length; i++) {
const y = Math.floor(scrollHeight * positions[i]!);
await pwPage.evaluate((scrollY: number) => window.scrollTo(0, scrollY), y);
await pwPage.waitForTimeout(400); // Wait for scroll-triggered animations to settle
const scrollFile = join(screenshotsDir, `scroll-${Math.round(positions[i]! * 100)}.png`);
await pwPage.screenshot({ path: scrollFile, fullPage: false, type: "png" });
}
} catch {
/* scroll screenshots are optional — don't fail the capture */
}
await browser.close();
return `screenshots/${filename}`;
} catch {
return undefined;
}
}
+158 -22
View File
@@ -49,18 +49,18 @@ const EXTRACT_SCRIPT = `(() => {
if (family && ["serif","sans-serif","monospace","cursive"].indexOf(family) === -1) fontSet[family] = true;
}
// 4. Colors — sample broadly across the page
// 4. Colors — hybrid: DOM computed styles + visual pixel sampling
var colorSet = {};
function addColor(c) {
if (!c || c === "rgba(0, 0, 0, 0)" || c === "transparent" || c === "inherit" || c === "initial") return;
function addColor(c, weight) {
if (!c || c === "rgba(0, 0, 0, 0)" || c === "transparent" || c === "inherit" || c === "initial" || c === "currentcolor") return;
var hex = rgbToHex(c);
if (hex) colorSet[hex] = (colorSet[hex] || 0) + 1;
if (hex) colorSet[hex] = (colorSet[hex] || 0) + (weight || 1);
}
function rgbToHex(color) {
if (!color) return null;
if (color.startsWith('#')) return color.length === 4
if (color.startsWith('#')) return (color.length === 4
? '#' + color[1]+color[1] + color[2]+color[2] + color[3]+color[3]
: color;
: color).toUpperCase();
var m = color.match(/rgba?\\(\\s*(\\d+)\\s*,\\s*(\\d+)\\s*,\\s*(\\d+)/);
if (!m) {
// Handle color(srgb ...) format
@@ -68,22 +68,37 @@ const EXTRACT_SCRIPT = `(() => {
if (cm) {
m = [null, Math.round(parseFloat(cm[1])*255), Math.round(parseFloat(cm[2])*255), Math.round(parseFloat(cm[3])*255)];
} else {
// Handle hsl()/hsla() by resolving through a temp element
var hm = color.match(/hsla?\\(/);
if (hm) {
// Handle modern color functions (oklch, oklab, lch, lab, hsl, color-mix)
// Use a 1x1 canvas to resolve ANY CSS color to RGB — this works even when
// getComputedStyle returns the color in its original color space (Chrome 131+)
if (/oklch|oklab|lch|lab|hsla?|color-mix|color\\(/.test(color)) {
try {
var cvs = document.createElement('canvas');
cvs.width = 1; cvs.height = 1;
var ctx2d = cvs.getContext('2d');
if (ctx2d) {
ctx2d.fillStyle = color;
ctx2d.fillRect(0, 0, 1, 1);
var px = ctx2d.getImageData(0, 0, 1, 1).data;
if (px[3] > 0) return '#' + ((1<<24) + (px[0]<<16) + (px[1]<<8) + px[2]).toString(16).slice(1).toUpperCase();
}
} catch(e2) {}
// Fallback: temp element approach
var tmp = document.createElement('div');
tmp.style.color = color;
document.body.appendChild(tmp);
var resolved = getComputedStyle(tmp).color;
document.body.removeChild(tmp);
return rgbToHex(resolved);
if (resolved !== color) return rgbToHex(resolved);
return null;
}
return color;
return null;
}
}
return '#' + ((1<<24) + (parseInt(m[1])<<16) + (parseInt(m[2])<<8) + parseInt(m[3])).toString(16).slice(1).toUpperCase();
}
// Sample all sections, headings, buttons, links, and elements with explicit backgrounds
// 4a. Sample DOM elements (text colors, borders, branded elements)
var colorCandidates = Array.from(document.querySelectorAll(
"body, header, nav, main, footer, section, " +
"h1, h2, h3, h4, h5, h6, " +
@@ -97,14 +112,87 @@ const EXTRACT_SCRIPT = `(() => {
addColor(cs.backgroundColor);
addColor(cs.color);
addColor(cs.borderColor);
addColor(cs.outlineColor);
// Extract colors from gradients in background-image
var bgImg = cs.backgroundImage;
if (bgImg && bgImg !== 'none') {
var gradColors = bgImg.match(/(?:#[0-9a-fA-F]{3,8}|rgba?\\([^)]+\\)|oklch\\([^)]+\\)|oklab\\([^)]+\\)|hsla?\\([^)]+\\)|lab\\([^)]+\\))/g);
if (gradColors) gradColors.forEach(function(gc) { addColor(gc); });
}
// Extract colors from box-shadow
var shadow = cs.boxShadow;
if (shadow && shadow !== 'none') {
var shadowColors = shadow.match(/(?:#[0-9a-fA-F]{3,8}|rgba?\\([^)]+\\))/g);
if (shadowColors) shadowColors.forEach(function(sc) { addColor(sc); });
}
} catch(e) {}
}
// Resolve CSS custom properties from :root to actual color values
// 4b. Explicitly sample html/body backgrounds (the dominant canvas color)
// These often define the site's light/dark character
try {
var htmlBg = getComputedStyle(document.documentElement).backgroundColor;
var bodyBg = getComputedStyle(document.body).backgroundColor;
addColor(htmlBg, 10);
addColor(bodyBg, 10);
// Also check the background shorthand which may contain gradients
var bodyBgFull = getComputedStyle(document.body).background;
var gradColors = bodyBgFull.match(/(?:#[0-9a-fA-F]{3,8}|rgba?\\([^)]+\\)|oklch\\([^)]+\\)|hsla?\\([^)]+\\))/g);
if (gradColors) gradColors.forEach(function(gc) { addColor(gc, 8); });
} catch(e) {}
// 4c. Visual pixel sampling — sample what the user actually SEES
// Walk a grid of points across the viewport and read background + text color
var vpW = window.innerWidth;
var vpH = window.innerHeight;
var gridCols = 6;
var gridRows = 5;
for (var gy = 0; gy < gridRows; gy++) {
for (var gx = 0; gx < gridCols; gx++) {
try {
var px = Math.round((gx + 0.5) * vpW / gridCols);
var py = Math.round((gy + 0.5) * vpH / gridRows);
var elAt = document.elementFromPoint(px, py);
if (elAt) {
var elStyle = getComputedStyle(elAt);
addColor(elStyle.color, 2);
var bgc = elStyle.backgroundColor;
// Walk up parents until we find a non-transparent background
var bgWalker = elAt;
while (bgWalker && (!bgc || bgc === "rgba(0, 0, 0, 0)" || bgc === "transparent")) {
bgWalker = bgWalker.parentElement;
if (bgWalker) bgc = getComputedStyle(bgWalker).backgroundColor;
}
addColor(bgc, 3);
}
} catch(e) {}
}
}
// 4c2. Broad sweep — find ANY element with a non-white/non-transparent background
// This catches colored blocks that the grid might miss (code blocks, banners, cards)
var allEls = document.querySelectorAll('*');
var colorSweepCount = 0;
for (var si = 0; si < allEls.length && colorSweepCount < 500; si++) {
try {
var elCs = getComputedStyle(allEls[si]);
var elBg = elCs.backgroundColor;
if (elBg && elBg !== "rgba(0, 0, 0, 0)" && elBg !== "transparent") {
var hex = rgbToHex(elBg);
if (hex && hex !== "#FFFFFF" && hex !== "#000000") {
addColor(elBg, 1);
}
}
colorSweepCount++;
} catch(e) {}
}
// 4d. Resolve CSS custom properties from :root to actual color values
var rootStyle = getComputedStyle(document.documentElement);
var rootProps = Object.keys(cssVariables);
for (var ri = 0; ri < rootProps.length; ri++) {
var val = rootStyle.getPropertyValue(rootProps[ri]).trim();
if (val && (val.startsWith("#") || val.startsWith("rgb") || val.startsWith("hsl"))) {
if (val && /^(#|rgb|hsl|oklch|oklab|lch|lab|color)/.test(val)) {
addColor(val);
}
}
@@ -113,14 +201,33 @@ const EXTRACT_SCRIPT = `(() => {
var headingEls = Array.from(document.querySelectorAll("h1, h2, h3, h4")).slice(0, 20);
var headings = headingEls.filter(isVisible).map(function(h) {
var s = getComputedStyle(h);
return { level: parseInt(h.tagName[1]), text: (h.textContent || "").trim().slice(0, 200), fontSize: s.fontSize, fontWeight: s.fontWeight, color: rgbToHex(s.color) || s.color };
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
var ctaEls = Array.from(document.querySelectorAll('a[class*="btn"], a[class*="button"], button[class*="primary"], [role="button"], a[class*="cta"]')).slice(0, 10);
// 7. 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));
// Filter out nav links (common false positives)
ctaEls = ctaEls.filter(function(el) {
return !el.closest('nav, [role="navigation"], [class*="nav"], [class*="menu"], [class*="dropdown"]');
});
// Also find links/buttons by text content (catches CTAs without class hints)
// Require short text (real CTAs are concise) and exclude nav context
var ctaTextPatterns = /^(get started|sign up|start free|try (it )?free|start (a )?trial|book a demo|request (a )?demo|contact (us|sales)|start for free|create account|register now)$/i;
var allButtons = Array.from(document.querySelectorAll('a, button'));
for (var bi = 0; bi < allButtons.length && ctaEls.length < 20; bi++) {
var btnText = (allButtons[bi].textContent || "").trim();
if (btnText.length > 30) continue;
if (allButtons[bi].closest('nav, [role="navigation"], [class*="nav"], [class*="menu"]')) continue;
if (ctaTextPatterns.test(btnText) && ctaEls.indexOf(allButtons[bi]) === -1) {
ctaEls.push(allButtons[bi]);
}
}
ctaEls = ctaEls.slice(0, 10);
var ctas = ctaEls.filter(isVisible).map(function(c) { return { text: (c.textContent || "").trim().slice(0, 60), href: c.href || undefined }; }).filter(function(c) { return c.text.length > 1; });
// 8. SVGs
@@ -147,16 +254,33 @@ const EXTRACT_SCRIPT = `(() => {
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
// 11. Sections — find large visual blocks regardless of HTML tag
var sectionResults = [];
var candidates = Array.from(document.querySelectorAll('section, main > div, main > section, [class*="hero"], [class*="Hero"], footer'));
// Start with semantic elements, then fall back to large direct children of body/main
var candidates = Array.from(document.querySelectorAll(
'section, main > div, main > section, article, ' +
'body > div > div, body > main > div, body > div, ' +
'[class*="hero"], [class*="Hero"], [class*="section"], [class*="Section"], ' +
'[class*="container"], [class*="wrapper"], [class*="block"], ' +
'[id*="section"], [id*="hero"], footer, [role="region"], [role="banner"]'
));
// Deduplicate (a div can match multiple selectors)
var seenEls = new Set();
candidates = candidates.filter(function(el) {
if (seenEls.has(el)) return false;
seenEls.add(el);
return true;
});
for (var si = 0; si < candidates.length; si++) {
var el = candidates[si];
var rect = el.getBoundingClientRect();
if (rect.height < 200 || rect.width < 400 || !isVisible(el)) continue;
// Skip page-level wrappers (a single div wrapping the entire page is not a section)
var pageHeight = document.body.scrollHeight || document.documentElement.scrollHeight;
if (rect.height > pageHeight * 0.8) continue;
var y = rect.top + window.scrollY;
var heading = el.querySelector("h1, h2, h3, h4");
var headingText = heading ? (heading.textContent || "").trim().slice(0, 80) : "";
var headingText = heading ? (heading.innerText || heading.textContent || "").trim().replace(/\\s+/g, ' ').slice(0, 80) : "";
var classes = (el.className || "").toString().toLowerCase();
var type = "content";
if (y < 200 || classes.indexOf("hero") !== -1) type = "hero";
@@ -167,8 +291,20 @@ const EXTRACT_SCRIPT = `(() => {
else if (classes.indexOf("feature") !== -1 || classes.indexOf("section") !== -1) type = "features";
var selector = el.id ? "#" + el.id : el.tagName.toLowerCase();
var sectionBg = getComputedStyle(el).backgroundColor;
if (!sectionBg || sectionBg === "rgba(0, 0, 0, 0)" || sectionBg === "transparent") sectionBg = "#FFFFFF";
else sectionBg = rgbToHex(sectionBg) || sectionBg;
// Walk up DOM to find nearest non-transparent background (don't default to white)
if (!sectionBg || sectionBg === "rgba(0, 0, 0, 0)" || sectionBg === "transparent") {
var bgWalker = el.parentElement;
while (bgWalker) {
var parentBg = getComputedStyle(bgWalker).backgroundColor;
if (parentBg && parentBg !== "rgba(0, 0, 0, 0)" && parentBg !== "transparent") {
sectionBg = parentBg;
break;
}
bgWalker = bgWalker.parentElement;
}
if (!sectionBg || sectionBg === "rgba(0, 0, 0, 0)" || sectionBg === "transparent") sectionBg = "#FFFFFF";
}
sectionBg = rgbToHex(sectionBg) || sectionBg;
sectionResults.push({ selector: selector, type: type, y: Math.round(y), height: Math.round(rect.height), heading: headingText, backgroundColor: sectionBg });
}
sectionResults.sort(function(a, b) { return a.y - b.y; });
+19 -7
View File
@@ -160,15 +160,27 @@ export default defineCommand({
console.log();
}
} catch (err) {
if (isJson) {
console.log(
JSON.stringify({
ok: false,
error: err instanceof Error ? err.message : String(err),
}),
const errMsg = err instanceof Error ? err.message : String(err);
// Write BLOCKED.md so the user/agent knows the capture failed
try {
const { mkdirSync, writeFileSync } = await import("node:fs");
mkdirSync(outputDir, { recursive: true });
const isTimeout = /timeout|timed out/i.test(errMsg);
const reason = isTimeout
? "Page navigation timed out — the site may be blocking headless browsers or requires authentication."
: `Capture failed: ${errMsg}`;
writeFileSync(
`${outputDir}/BLOCKED.md`,
`# Capture Failed\n\n${reason}\n\nURL: ${url}\n\n## What to try\n\n- Re-run with a longer timeout: \`--timeout 60000\`\n- The site may block headless browsers (anti-bot protection)\n- Try capturing a different page on the same domain\n`,
"utf-8",
);
} catch {
/* best-effort */
}
if (isJson) {
console.log(JSON.stringify({ ok: false, error: errMsg }));
} else {
console.error(`\n ✗ Capture failed: ${err}\n`);
console.error(`\n ✗ Capture failed: ${errMsg}\n`);
}
process.exit(1);
}
+7 -4
View File
@@ -1,6 +1,6 @@
import { defineCommand } from "citty";
import { existsSync, readFileSync, mkdirSync } from "node:fs";
import { resolve, join, dirname } from "node:path";
import { resolve, join, dirname, relative, isAbsolute } from "node:path";
import { fileURLToPath } from "node:url";
import { resolveProject } from "../utils/project.js";
import { c } from "../ui/colors.js";
@@ -60,7 +60,8 @@ async function captureSnapshots(
return;
}
const filePath = resolve(projectDir, decodeURIComponent(url).replace(/^\//, ""));
if (!filePath.startsWith(projectDir + "/") && filePath !== projectDir) {
const rel = relative(projectDir, filePath);
if (rel.startsWith("..") || isAbsolute(rel)) {
res.writeHead(403);
res.end();
return;
@@ -142,13 +143,15 @@ async function captureSnapshots(
// Get composition duration
const duration = await page.evaluate(() => {
const win = window as any;
if (win.__player?.duration) return win.__player.duration;
const pd = win.__player?.duration;
if (pd != null) return typeof pd === "function" ? pd() : pd;
const root = document.querySelector("[data-composition-id][data-duration]");
if (root) return parseFloat(root.getAttribute("data-duration") ?? "0");
const tls = win.__timelines;
if (tls) {
for (const key in tls) {
if (tls[key]?.duration) return tls[key].duration();
const d = tls[key]?.duration;
if (d != null) return typeof d === "function" ? d() : d;
}
}
return 0;
+98
View File
@@ -322,6 +322,104 @@ describe("GSAP rules", () => {
expect(conflicts[0]?.message).toMatch(/x\/scale|scale\/x/);
});
// --- Inline style transform detection tests ---
it("warns when inline style transform: translateX conflicts with GSAP x", () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<div id="centered" style="position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%);">Text</div>
</div>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
tl.to("#centered", { x: 0, y: 0, opacity: 1, duration: 0.4 }, 0.5);
window.__timelines["c1"] = tl;
</script>
</body></html>`;
const result = lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "gsap_css_transform_conflict");
expect(finding).toBeDefined();
expect(finding?.selector).toBe("#centered");
});
it("warns when inline style transform: scale conflicts with GSAP scale", () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<div id="box" style="transform: scale(0.9);">Box</div>
</div>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
tl.to("#box", { scale: 1, duration: 0.5 }, 1.0);
window.__timelines["c1"] = tl;
</script>
</body></html>`;
const result = lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "gsap_css_transform_conflict");
expect(finding).toBeDefined();
expect(finding?.selector).toBe("#box");
});
it("does not false-positive on inline transform: rotate when GSAP uses rotation", () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<div id="spinner" style="transform: rotate(12deg);">Icon</div>
</div>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
tl.to("#spinner", { rotation: 360, duration: 1 }, 0);
window.__timelines["c1"] = tl;
</script>
</body></html>`;
const result = lintHyperframeHtml(html);
// rotation doesn't conflict with rotate() — GSAP handles rotation separately
const finding = result.findings.find((f) => f.code === "gsap_css_transform_conflict");
expect(finding).toBeUndefined();
});
it("detects conflict via class selector when element has multiple classes", () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<div class="card hero" style="transform: translateX(-50%);">Card</div>
</div>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
tl.to(".hero", { x: 100, duration: 0.4 }, 0.5);
window.__timelines["c1"] = tl;
</script>
</body></html>`;
const result = lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "gsap_css_transform_conflict");
expect(finding).toBeDefined();
});
it("handles both style block and inline style on same selector without crash", () => {
const html = `
<html><body>
<div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<div id="dual" style="transform: scale(0.5);">Dual</div>
</div>
<style>
#dual { transform: translateY(-50%); }
</style>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
tl.to("#dual", { y: 0, scale: 1, duration: 0.5 }, 0);
window.__timelines["c1"] = tl;
</script>
</body></html>`;
const result = lintHyperframeHtml(html);
const conflicts = result.findings.filter((f) => f.code === "gsap_css_transform_conflict");
expect(conflicts.length).toBeGreaterThanOrEqual(1);
});
it("reports error when GSAP is used without a GSAP script tag", () => {
const html = `
<html><body>
-2
View File
@@ -119,5 +119,3 @@ Lint, validate, preview. Create a HANDOFF.md for multi-session continuity.
| [step-6-build.md](references/step-6-build.md) | Step 6 — building compositions with self-review |
| [step-7-validate.md](references/step-7-validate.md) | Step 7 — lint, validate, preview, handoff |
| [techniques.md](references/techniques.md) | Steps 4 & 6 — 10 visual techniques with code patterns (SVG drawing, Canvas 2D, 3D, typography, Lottie, video, typing, variable fonts, MotionPath, transitions) |
| [asset-sourcing.md](references/asset-sourcing.md) | When you need logos, icons, or photos not in the capture |
| [video-recipes.md](references/video-recipes.md) | Scene patterns, 5-layer system, mid-scene activity |
@@ -1,141 +0,0 @@
# Asset Sourcing Guide
How to find and download free assets when the capture doesn't have what you need, or when there's no capture at all.
**Rule:** Only source assets when the video plan references something that doesn't exist in `assets/`. Don't speculatively download 30 images "just in case."
## Brand Logos (SVG)
**Simple Icons** — 3000+ brand logos, SVG, CC0 license, no rate limit.
```bash
# Download by brand name (lowercase, no spaces)
curl -o assets/svgs/stripe.svg "https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/stripe.svg"
curl -o assets/svgs/vercel.svg "https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/vercel.svg"
curl -o assets/svgs/github.svg "https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/github.svg"
```
Brand names: use the slug from [simpleicons.org](https://simpleicons.org). Common ones: `stripe`, `vercel`, `notion`, `figma`, `slack`, `discord`, `github`, `linear`, `openai`, `anthropic`, `google`, `apple`, `microsoft`, `amazon`, `netflix`, `spotify`, `airbnb`, `uber`, `coinbase`, `shopify`.
These SVGs are monochrome (single path). To use with brand colors, set `fill` in CSS or inline:
```html
<img src="../assets/svgs/stripe.svg" style="height:32px;filter:brightness(0) invert(1);" />
<!-- Or inline and set fill -->
```
## Company Logos (PNG)
**Clearbit Logo API** — Any company's logo by domain. No API key. PNG format.
```bash
curl -o assets/logo-stripe.png "https://logo.clearbit.com/stripe.com"
curl -o assets/logo-linear.png "https://logo.clearbit.com/linear.app"
curl -o assets/logo-notion.png "https://logo.clearbit.com/notion.so"
```
Returns the company's actual logo (usually with transparency). Size varies. Use when you need a full-color logo, not just the icon.
## Icons (SVG)
**Lucide** — 5000+ open-source icons, SVG, ISC license. Consistent 24x24 viewBox, 2px stroke.
```bash
# Download by icon name (kebab-case)
curl -o assets/svgs/icon-chart.svg "https://cdn.jsdelivr.net/npm/lucide-static@latest/icons/bar-chart-3.svg"
curl -o assets/svgs/icon-shield.svg "https://cdn.jsdelivr.net/npm/lucide-static@latest/icons/shield-check.svg"
curl -o assets/svgs/icon-zap.svg "https://cdn.jsdelivr.net/npm/lucide-static@latest/icons/zap.svg"
curl -o assets/svgs/icon-globe.svg "https://cdn.jsdelivr.net/npm/lucide-static@latest/icons/globe.svg"
```
Common categories:
- **Business:** `briefcase`, `building-2`, `users`, `trending-up`, `dollar-sign`, `credit-card`
- **Tech:** `code-2`, `terminal`, `database`, `server`, `cpu`, `wifi`, `smartphone`
- **UI:** `check-circle`, `x-circle`, `alert-triangle`, `info`, `search`, `settings`, `menu`
- **Media:** `play`, `pause`, `volume-2`, `camera`, `image`, `film`, `music`
- **Communication:** `mail`, `message-circle`, `phone`, `send`, `at-sign`
- **Data:** `bar-chart-3`, `pie-chart`, `activity`, `line-chart`, `table`
- **Security:** `shield-check`, `lock`, `key`, `fingerprint`, `eye`, `eye-off`
- **Arrows:** `arrow-right`, `arrow-up-right`, `chevron-right`, `move`, `maximize-2`
Browse all at [lucide.dev/icons](https://lucide.dev/icons).
Lucide SVGs use `stroke="currentColor"`. Style with CSS:
```html
<img
src="../assets/svgs/icon-zap.svg"
style="width:48px;height:48px;filter:brightness(0) invert(1);"
/>
```
Or for inline SVGs, set `stroke` directly.
## Photos (Unsplash)
**Unsplash** — Free high-quality photos. Direct image URLs work without an API key.
For direct downloads (no API key needed), use the image CDN URL:
```bash
# Download by photo ID (find IDs by browsing unsplash.com)
curl -L -o assets/photo-hero.jpg "https://images.unsplash.com/photo-{photo-id}?w=1920&q=80"
# Example with a real photo ID
curl -L -o assets/photo-office.jpg "https://images.unsplash.com/photo-1497366216548-37526070297c?w=1920&q=80"
```
For search (needs UNSPLASH_ACCESS_KEY env var):
```bash
# Search and get URLs
curl -s "https://api.unsplash.com/search/photos?query=fintech+dashboard&per_page=5" \
-H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}" | jq '.results[].urls.regular'
```
**If no API key is available**, browse unsplash.com manually for a photo ID, or use a CSS gradient / solid color background. Don't block the video on missing photos — a well-designed composition with no photo beats a bad photo.
**Attribution:** Unsplash photos are free but appreciate attribution. Add a comment in the HTML: `<!-- Photo: unsplash.com/photos/{id} by {photographer} -->`.
## When to Source
| Situation | Action |
| --------------------------------------------------- | -------------------------------------- |
| Video plan mentions "logo wall" or "customer logos" | Source brand SVGs from Simple Icons |
| Scene needs a specific company's logo | Source from Clearbit by domain |
| Scene references icons (features, benefits, stats) | Source from Lucide by keyword |
| Hero scene needs a photo and none exists | Source from Unsplash or use CSS art |
| Capture already has the asset in `assets/` | Use the local file — don't re-download |
| Asset is decorative and optional | Skip it — ship without and iterate |
## Naming Convention
```
assets/
├── svgs/
│ ├── stripe.svg ← brand logos (name = brand slug)
│ ├── icon-chart.svg ← icons (prefix with icon-)
│ └── logo-company.svg ← company logos
├── photo-hero.jpg ← photos (prefix with photo-)
├── logo-stripe.png ← Clearbit logos (prefix with logo-)
└── ...
```
## In Compositions
```html
<!-- Local brand SVG -->
<img src="../assets/svgs/stripe.svg" crossorigin="anonymous" style="height:28px;" />
<!-- Clearbit logo -->
<img src="../assets/logo-stripe.png" crossorigin="anonymous" style="height:40px;" />
<!-- Lucide icon -->
<img src="../assets/svgs/icon-zap.svg" crossorigin="anonymous" style="width:32px;height:32px;" />
<!-- Remote Clearbit (works without download, but prefer local) -->
<img src="https://logo.clearbit.com/stripe.com" crossorigin="anonymous" style="height:40px;" />
```
Always add `crossorigin="anonymous"` to external or downloaded assets.
@@ -22,14 +22,11 @@ Read each file below. After reading each one, **write a 1-2 sentence summary** o
### Must read (do not skip)
1. **View the scroll screenshots** (NOT the full-page.png — it's too tall and compressed to read). View these in order:
- `screenshots/scroll-0.png` — the hero section at full 1920x1080 resolution. This is the most important image. Describe: is the background light or dark? What's the dominant visual element? What colors jump out?
- `screenshots/scroll-25.png` — the page at 25% scroll depth
- `screenshots/scroll-50.png` — the page at 50% scroll depth
- `screenshots/scroll-75.png` — the page at 75% scroll depth
- `screenshots/scroll-100.png` — the footer area
1. **View the scroll screenshots** — viewport-sized captures covering the full page height (the number depends on the page length). Start with:
- `screenshots/scroll-000.png` — the hero section at full 1920x1080 resolution. This is the most important image. Describe: is the background light or dark? What's the dominant visual element? What colors jump out?
- Then scan through the rest to see the full page. Each screenshot overlaps the previous by ~30%.
After viewing all five, write 3-4 sentences describing the site's visual mood, layout patterns, color strategy, and overall feel.
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.
@@ -4,9 +4,9 @@
Never use the first voice you find. Audition 2-3 voices with the first sentence of SCRIPT.md:
- **ElevenLabs** (recommended — widest voice selection, most natural output) — `mcp__elevenlabs__search_voices` to browse, `mcp__elevenlabs__text_to_speech` to generate. Does not return timestamps — transcribe separately after.
- **HeyGen TTS** (alternative — returns word timestamps automatically) — `mcp__claude_ai_HeyGen__text_to_speech`. Use `mcp__claude_ai_HeyGen__list_audio_voices` to browse. Look for relaxed, confident voices.
- **Kokoro** (offline last resort — has Python dependency issues on many systems) — `npx hyperframes tts SCRIPT.md --voice af_nova --output narration.wav`. Only try this if ElevenLabs and HeyGen are unavailable.
- **Kokoro** (try first — free, no API key) — `npx hyperframes tts SCRIPT.md --voice af_nova --output narration.wav`. Runs locally on CPU. Requires Python 3.10+ (macOS system Python 3.9 won't work — if it fails with an onnxruntime error, move to the next option).
- **ElevenLabs** (best voice quality, widest selection) — `mcp__elevenlabs__search_voices` to browse, `mcp__elevenlabs__text_to_speech` to generate. Does not return timestamps — transcribe separately after.
- **HeyGen TTS** (returns word timestamps automatically — saves a transcribe step) — `mcp__claude_ai_HeyGen__text_to_speech`. Use when you want timestamps without a separate transcription pass.
Pick the voice that sounds most natural and conversational. Listen for pacing — does it breathe between sentences? Does it sound like a person or a robot?
@@ -1,348 +0,0 @@
# Video Reference Patterns
Technical patterns and creative tools for building compositions. These are building blocks — not templates. The video's structure should come from the creative director step (Step 4), driven by the brand and content.
## Architecture
**Every scene = a separate sub-composition file** in `compositions/`. Root `index.html` loads each scene on the same track with sequential `data-start` values.
```
project/
├── index.html ← root: loads scenes + transitions + audio
└── compositions/
├── scene1.html
├── scene2.html
├── scene3.html
└── captions.html ← word-level captions overlay
```
## Scene Transitions
### With Shader Transitions (recommended for 15s+ videos)
When using shader transitions, scenes DON'T fade to/from black. The shader handles the visual blend between scenes. This means:
- Each scene starts at **full opacity** (no fade-in from black)
- Each scene ends at **full opacity** (no fade-out to black)
- Scene GSAP timelines only handle entrances for internal elements + mid-scene activity
- No exit animations needed — the shader dissolves this scene into the next
```javascript
// Scene with shader transitions — NO fade in/out of the background
var dur = 5;
var tl = gsap.timeline({ paused: true });
// Background is immediately visible (scene texture needs content to capture)
gsap.set("#scene-bg", { opacity: 1 });
// === ELEMENTS ENTER ===
tl.fromTo(
"#headline",
{ opacity: 0, y: 30 },
{ opacity: 1, y: 0, duration: 0.5, ease: "expo.out" },
0.1,
);
tl.fromTo(
"#hero-img",
{ opacity: 0, scale: 1.1 },
{ opacity: 1, scale: 1, duration: 0.6, ease: "power3.out" },
0.2,
);
// === MID-SCENE ACTIVITY (keep it alive — required) ===
tl.to("#hero-img", { scale: 1.03, duration: dur, ease: "sine.inOut" }, 0);
// === NO EXIT — shader transition handles the handoff to next scene ===
```
The root `index.html` orchestrates transitions between scenes:
1. Show scene 1 (via passthrough shader rendering scene texture)
2. At transition point: `beginTrans(shaderProg, "scene1", "scene2")`
3. GSAP tweens `trans.progress` from 0→1 over transition duration (0.3-0.8s)
4. `endTrans("scene2")` — now showing scene 2
Read `references/transitions/shader-setup.md` for the complete WebGL boilerplate and `references/transitions/shader-transitions.md` for the 14 available fragment shaders.
### Without Shader Transitions (simple fade cuts)
For very short videos (<10s) or when minimal simplicity is the creative intent, use the fade-to-black pattern:
```javascript
var dur = 5;
var tl = gsap.timeline({ paused: true });
// === ENTRANCE (first 0.3s) ===
tl.fromTo("#scene-bg", { opacity: 0 }, { opacity: 1, duration: 0.3, ease: "power2.out" }, 0);
tl.fromTo(
"#headline",
{ opacity: 0, y: 30 },
{ opacity: 1, y: 0, duration: 0.5, ease: "expo.out" },
0.15,
);
// === MAIN CONTENT (middle) ===
// ... your animations here ...
// === EXIT (last 0.3s) ===
tl.to("#headline", { opacity: 0, duration: 0.2, ease: "power1.in" }, dur - 0.35);
tl.to("#scene-bg", { opacity: 0, duration: 0.3, ease: "power2.in" }, dur - 0.3);
```
Root `body { background: #000 }` ensures the gap between scenes is black.
## Scene Composition: 5-Layer System
Every scene should be composed in layers. This is the difference between a flat slide and a cinematic frame:
| Layer | Purpose | Examples |
| ----------------- | ------------------------------------------- | ---------------------------------------------------------------------- |
| **L1 Background** | Sets the visual world | Solid color, gradient, texture, slow-moving particles, CSS noise |
| **L2 Hero** | The dominant visual — fills 50-70% of frame | Large headline, key stat, hero image with Ken Burns, Lottie animation |
| **L3 Supporting** | Context and depth | Secondary text, smaller stats, caption, sub-headline |
| **L4 Info bar** | Label, source, or accent | Bottom-third text, ticker, brand logo placement, category tag |
| **L5 Effects** | Energy and texture | Grain overlay, glitch artifact, scan lines, gradient sweep, light leak |
**Every B-roll scene: aim for 4+ layers.** Every element in every layer must move.
```html
<!-- Example: 5-layer stat reveal scene -->
<!-- L1: Background with subtle grain -->
<div id="bg" style="position:absolute;width:100%;height:100%;background:#0a0a0a;">
<canvas id="grain" style="position:absolute;width:100%;height:100%;opacity:0.04;"></canvas>
</div>
<!-- L2: Hero stat (massive) -->
<div
id="hero-stat"
style="position:absolute;top:280px;left:50%;transform:translateX(-50%);
font-size:200px;font-weight:900;color:#fff;opacity:0;"
>
$1.9T
</div>
<!-- L3: Supporting label -->
<div
id="label"
style="position:absolute;top:520px;left:50%;transform:translateX(-50%);
font-size:28px;color:#aaa;opacity:0;letter-spacing:0.2em;text-transform:uppercase;"
>
global transactions in 2024
</div>
<!-- L4: Brand strip -->
<div id="brand" style="position:absolute;bottom:120px;left:80px;opacity:0;">
<img src="../assets/svgs/logo.svg" style="height:32px;" />
</div>
<!-- L5: Gradient sweep effect -->
<div
id="sweep"
style="position:absolute;top:0;left:-100%;width:40%;height:100%;
background:linear-gradient(90deg,transparent,rgba(255,255,255,0.03),transparent);"
></div>
```
```javascript
var tl = gsap.timeline({ paused: true });
// L1: Background is immediately visible
gsap.set("#bg", { opacity: 1 });
// Grain (L5): generate deterministic noise
(function () {
var canvas = document.getElementById("grain");
var ctx = canvas.getContext("2d");
canvas.width = 1920;
canvas.height = 1080;
// Seeded PRNG for deterministic noise (same frame = same grain pattern)
var seed = 42;
function rand() {
seed = (seed * 1664525 + 1013904223) & 0xffffffff;
return (seed >>> 0) / 0xffffffff;
}
var img = ctx.createImageData(1920, 1080);
for (var i = 0; i < img.data.length; i += 4) {
var v = Math.floor(rand() * 255);
img.data[i] = img.data[i + 1] = img.data[i + 2] = v;
img.data[i + 3] = 255;
}
ctx.putImageData(img, 0, 0);
})();
// L5 sweep: continuous slow pan across the frame
tl.to("#sweep", { left: "110%", duration: 3, ease: "none" }, 0);
// L2: Hero stat slams in
tl.fromTo(
"#hero-stat",
{ opacity: 0, scale: 0.8 },
{ opacity: 1, scale: 1, duration: 0.5, ease: "expo.out" },
0.2,
);
// L3: Label fades + slides up
tl.fromTo(
"#label",
{ opacity: 0, y: 12 },
{ opacity: 1, y: 0, duration: 0.4, ease: "power2.out" },
0.5,
);
// L4: Brand mark fades in
tl.fromTo("#brand", { opacity: 0 }, { opacity: 0.7, duration: 0.4 }, 0.7);
// L2: Mid-scene — stat breathes
tl.to("#hero-stat", { scale: 1.02, duration: 4, ease: "sine.inOut", yoyo: true, repeat: 1 }, 0.7);
```
## Caption Safe Zone
**Bottom 120px is reserved for captions.** No scene content below y=960px. The captions sub-composition sits on track 2 as a full-duration overlay occupying this space.
## Elements Must DO Something (Not Just Sit There)
**The #1 difference between a video and a slideshow is continuous motion.** Every visible element should have mid-scene activity — not just an entrance and exit.
### Mid-Scene Activity Ideas
Every element MUST have at least one continuous animation during its hold phase:
| Element type | Mid-scene activity |
| ---------------------- | --------------------------------------------------------------------------------- |
| Image / screenshot | Slow zoom (scale 1→1.03 over scene duration), or slow pan (x drift), or Ken Burns |
| Stat / number | Counter animates from 0 to target with `onUpdate` callback |
| Code block | Lines reveal one by one with stagger, cursor blinks |
| Chart / bars | Bars grow to target heights with elastic ease, values tick up alongside |
| Logo grid | Subtle shimmer sweep across each, or gentle scale pulse (1→1.02→1) |
| Progress / fill | Fills from 0% to target, percentage text updates live |
| Any persistent element | Subtle float (y ±4-6px, sine.inOut, yoyo) or glow pulse |
### Counter Animation Pattern
```javascript
var obj = { val: 0 };
var statEl = document.querySelector("#stat-num");
tl.to(
obj,
{
val: 135,
duration: 1.5,
ease: "power2.out",
onUpdate: function () {
statEl.textContent = Math.round(obj.val) + "+";
},
},
0.5,
);
```
### Floating/Breathing Pattern
```javascript
// Subtle float — makes static elements feel alive
// Never use repeat: -1 — infinite loops break the capture engine.
// Calculate repeats from scene duration:
var sceneDur = 5; // match your data-duration
tl.to(
"#card",
{ y: "-=6", duration: 2, ease: "sine.inOut", yoyo: true, repeat: Math.ceil(sceneDur / 2) - 1 },
0,
);
```
### Line-by-Line Reveal Pattern
```javascript
tl.fromTo(
".code-line",
{ opacity: 0, y: 8 },
{ opacity: 1, y: 0, duration: 0.3, stagger: 0.4, ease: "power2.out" },
0.5,
);
// Blinking cursor — never use repeat: -1
var cursorStart = 2.5;
var cursorCycle = 1;
tl.fromTo(
"#cursor",
{ opacity: 1 },
{
opacity: 0,
duration: 0.5,
repeat: Math.ceil((sceneDur - cursorStart) / cursorCycle) - 1,
yoyo: true,
},
cursorStart,
);
```
## Visual Enhancement Tools
These separate "AI-generated video" from "actually good video." Use 1-2 per composition.
### Rough.js — Hand-Drawn Elements
```html
<script src="https://cdn.jsdelivr.net/npm/roughjs@4.6.6/bundled/rough.min.js"></script>
<svg
id="rough-canvas"
width="1920"
height="1080"
style="position:absolute;top:0;left:0;pointer-events:none"
></svg>
```
```javascript
var rc = rough.svg(document.getElementById("rough-canvas"));
var node = rc.circle(960, 400, 200, {
stroke: "#635BFF",
strokeWidth: 3,
roughness: 1.2,
bowing: 2,
fill: "none",
});
document.getElementById("rough-canvas").appendChild(node);
var paths = node.querySelectorAll("path");
paths.forEach(function (p) {
var len = p.getTotalLength();
p.style.strokeDasharray = len;
p.style.strokeDashoffset = len;
});
tl.to(paths, { strokeDashoffset: 0, duration: 0.8, ease: "power2.out", stagger: 0.1 }, 2.0);
```
Shapes: `rc.circle()`, `rc.rectangle()`, `rc.line()`, `rc.arc()`. Roughness: 0.8 = clean, 1.2 = hand-drawn, 2.0 = sketchy.
### Marker-Highlight — Text Emphasis
Five modes: `highlight` (marker sweep), `circle` (drawn around word), `burst` (radiating lines), `scribble` (cross-out), `sketchout` (rough rectangle). See `/hyperframes` skill's marker-highlight reference.
```javascript
tl.call(
function () {
highlighter.clearMarks();
highlighter.reanimateMark("stat-highlight");
},
null,
3.0,
);
```
### SVG Stroke Animation — Path Drawing
```javascript
var path = document.querySelector("#logo-path");
var length = path.getTotalLength();
path.style.strokeDasharray = length;
path.style.strokeDashoffset = length;
tl.to(path.style, { strokeDashoffset: 0, duration: 1.5, ease: "power2.out" }, 0.5);
```
## Using Captured Assets
- **SVG logos** → embed inline, animate with GSAP (fill, stroke, scale, path drawing)
- **Images** → use as hero visuals, backgrounds (with slow zoom), or layered elements
- **Fonts** (`assets/fonts/`) → load via @font-face, match exact weights from DESIGN.md
- **Lottie** (`assets/lottie/`) → embed via lottie.loadAnimation, seekable
- **Remote URLs** from assets-catalog.json → product screenshots, hero images load directly in compositions