mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 19:36:04 +00:00
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:
+2
-2
@@ -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
@@ -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/
|
||||
|
||||
@@ -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=="],
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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 {
|
||||
|
||||
@@ -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 */
|
||||
}
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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; });
|
||||
|
||||
@@ -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);
|
||||
}
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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>
|
||||
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user