Skip to content

Commit 6266708

Browse files
committed
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
1 parent 6335934 commit 6266708

19 files changed

Lines changed: 481 additions & 779 deletions

‎.env.example‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# No environment variables required for basic usage.
2-
# Run `pnpm dev` to start the studio, `npx hyperframes render` to render video.
2+
# Run `bun run dev` to start the studio, `npx hyperframes render` to render video.
33

44
# Optional integrations:
5-
# ANTHROPIC_API_KEY= # For AI-assisted composition via MCP
5+
# GEMINI_API_KEY= # AI image captioning during website capture (https://aistudio.google.com/apikey)

‎.gitignore‎

Lines changed: 7 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -64,26 +64,11 @@ skills-lock.json
6464
skills/hyperframes-animation-map/
6565
skills/hyperframes-contrast/
6666

67-
# Capture outputs (new captures go to captures/ by default)
67+
# Capture outputs
6868
captures/
69-
notion-promo/
70-
notion-com-capture/
71-
72-
# Existing test captures at repo root (legacy)
73-
notion-demo/
74-
notion-ai-agents/
75-
stripe-launch/
76-
stripe-investor/
77-
stripe-website/
78-
linear-ad/
79-
soulscape-demo/
80-
soulscape-film/
81-
midjourney/
82-
vercel-tour/
83-
figma-ad/
84-
arc-browser/
85-
raycast-demo/
86-
rive-demo/
87-
lusion-brand/
88-
motion-zajno/
89-
notion/
69+
# Legacy test captures at repo root (use captures/ instead)
70+
*-capture/
71+
*-demo/
72+
*-ad/
73+
*-tour/
74+
*-brand/

‎bun.lock‎

Lines changed: 3 additions & 18 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -28,10 +28,6 @@
2828
"generate:previews": "tsx scripts/generate-template-previews.ts",
2929
"prepare": "test -d .git && lefthook install || true"
3030
},
31-
"dependencies": {
32-
"patchright": "^1.59.3",
33-
"purgecss": "^8.0.0"
34-
},
3531
"devDependencies": {
3632
"@commitlint/cli": "^20.5.0",
3733
"@commitlint/config-conventional": "^20.5.0",

‎packages/cli/package.json‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,6 @@
2525
"typecheck": "tsc --noEmit"
2626
},
2727
"dependencies": {
28-
"@google/genai": "^1.50.0",
2928
"@hono/node-server": "^1.8.0",
3029
"@puppeteer/browsers": "^2.13.0",
3130
"adm-zip": "^0.5.16",
@@ -36,7 +35,6 @@
3635
"hono": "^4.0.0",
3736
"mime-types": "^3.0.2",
3837
"open": "^10.0.0",
39-
"playwright": "^1.59.1",
4038
"postcss": "^8.5.8",
4139
"prettier": "^3.8.1",
4240
"puppeteer-core": "^24.39.1",
@@ -57,6 +55,9 @@
5755
"typescript": "^5.0.0",
5856
"vitest": "^3.2.4"
5957
},
58+
"optionalDependencies": {
59+
"@google/genai": "^1.50.0"
60+
},
6061
"engines": {
6162
"node": ">=22"
6263
}

‎packages/cli/src/capture/agentPromptGenerator.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ function buildPrompt(
4848
const title = tokens.title || hostname;
4949
const cues = detectImplementationCues(tokens, animations);
5050

51-
const colorSummary = tokens.colors.slice(0, 6).join(", ");
51+
const colorSummary = tokens.colors.slice(0, 10).join(", ");
5252
const fontSummary = tokens.fonts.join(", ") || "none detected";
5353
const sectionCount = tokens.sections?.length ?? 0;
5454
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
7575
7676
| File | Contents |
7777
|------|----------|
78-
${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 |" : ""}
78+
${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. |" : ""}
7979
| \`extracted/tokens.json\` | Design tokens: ${tokens.colors.length} colors, ${tokens.fonts.length} fonts, ${headingCount} headings, ${ctaCount} CTAs, ${sectionCount} sections |
8080
| \`extracted/visible-text.txt\` | All visible text content in DOM order — use exact strings, never paraphrase |
8181
| \`extracted/assets-catalog.json\` | Every asset URL (images, fonts, videos, icons) with HTML context |

‎packages/cli/src/capture/assetDownloader.ts‎

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -198,10 +198,39 @@ export async function downloadAndRewriteFonts(css: string, outputDir: string): P
198198

199199
if (fontUrls.size === 0) return css;
200200

201+
// Limit font downloads to avoid bloat. Google Fonts serves 20+ unicode-range
202+
// subsets per weight — we only need a few per family for video production.
203+
const MAX_FONTS_PER_FAMILY = 6;
204+
const MAX_TOTAL_FONTS = 30;
205+
const familyCounts = new Map<string, number>();
206+
207+
// Extract font-family from the @font-face rule containing each URL
208+
const getFamilyForUrl = (url: string): string => {
209+
const idx = css.indexOf(url);
210+
if (idx === -1) return "_unknown";
211+
const blockStart = css.lastIndexOf("@font-face", idx);
212+
if (blockStart === -1) return "_unknown";
213+
const blockSlice = css.slice(blockStart, idx);
214+
const familyMatch = blockSlice.match(/font-family\s*:\s*['"]?([^'";}\n]+)/i);
215+
return familyMatch?.[1] ? familyMatch[1].trim().toLowerCase() : "_unknown";
216+
};
217+
218+
// Prioritize Latin subsets over CJK/Arabic/etc unicode ranges
219+
const sortedUrls = Array.from(fontUrls).sort((a, b) => {
220+
const aLatin = /latin|[A-Za-z0-9]{10,}\.woff/.test(a) ? 0 : 1;
221+
const bLatin = /latin|[A-Za-z0-9]{10,}\.woff/.test(b) ? 0 : 1;
222+
return aLatin - bLatin;
223+
});
224+
201225
let rewritten = css;
202226
let count = 0;
203227

204-
for (const fontUrl of fontUrls) {
228+
for (const fontUrl of sortedUrls) {
229+
if (count >= MAX_TOTAL_FONTS) break;
230+
const family = getFamilyForUrl(fontUrl);
231+
const familyCount = familyCounts.get(family) || 0;
232+
if (familyCount >= MAX_FONTS_PER_FAMILY) continue;
233+
205234
try {
206235
const urlObj = new URL(fontUrl);
207236
const filename = urlObj.pathname.split("/").pop() || `font-${count}.woff2`;
@@ -212,6 +241,7 @@ export async function downloadAndRewriteFonts(css: string, outputDir: string): P
212241
if (buffer) {
213242
writeFileSync(localPath, buffer);
214243
rewritten = rewritten.split(fontUrl).join(relativePath);
244+
familyCounts.set(family, familyCount + 1);
215245
count++;
216246
}
217247
} catch {

‎packages/cli/src/capture/htmlExtractor.ts‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -59,13 +59,16 @@ export async function extractHtml(
5959
});
6060
// Add the CSS as a <style> tag in <head> via Puppeteer's addStyleTag
6161
await page.addStyleTag({ content: css });
62-
// Remove the original <link> tag
63-
await page.evaluate(`(() => {
64-
var links = document.querySelectorAll('link[rel="stylesheet"]');
65-
for (var i = 0; i < links.length; i++) {
66-
if (links[i].href === "${href}") { links[i].remove(); break; }
62+
// Remove the original <link> tag (use parameterized evaluate to avoid injection)
63+
await page.evaluate((targetHref: string) => {
64+
const links = document.querySelectorAll('link[rel="stylesheet"]');
65+
for (const link of links) {
66+
if ((link as HTMLLinkElement).href === targetHref) {
67+
link.remove();
68+
break;
69+
}
6770
}
68-
})()`);
71+
}, href);
6972
} catch {
7073
/* network error — skip */
7174
}

‎packages/cli/src/capture/index.ts‎

Lines changed: 79 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,37 @@ export async function captureWebsite(
4646
onProgress?.(stage, detail);
4747
};
4848

49+
// Load .env file from repo root if it exists (for GEMINI_API_KEY, etc.)
50+
try {
51+
const { readFileSync: readEnv } = await import("node:fs");
52+
const { resolve: resolvePath } = await import("node:path");
53+
// Walk up from outputDir to find .env in repo root
54+
let dir = resolvePath(outputDir);
55+
for (let i = 0; i < 5; i++) {
56+
const envPath = resolvePath(dir, ".env");
57+
try {
58+
const envContent = readEnv(envPath, "utf-8");
59+
for (const line of envContent.split("\n")) {
60+
const trimmed = line.trim();
61+
if (!trimmed || trimmed.startsWith("#")) continue;
62+
const eq = trimmed.indexOf("=");
63+
if (eq === -1) continue;
64+
const key = trimmed.slice(0, eq).trim();
65+
const val = trimmed
66+
.slice(eq + 1)
67+
.trim()
68+
.replace(/^["']|["']$/g, "");
69+
if (!process.env[key]) process.env[key] = val;
70+
}
71+
break;
72+
} catch {
73+
dir = resolvePath(dir, "..");
74+
}
75+
}
76+
} catch {
77+
/* .env loading is best-effort */
78+
}
79+
4980
// Create output directories
5081
mkdirSync(join(outputDir, "extracted"), { recursive: true });
5182
mkdirSync(join(outputDir, "screenshots"), { recursive: true });
@@ -172,6 +203,30 @@ export async function captureWebsite(
172203
await page1.goto(url, { waitUntil: "networkidle0", timeout });
173204
await new Promise((r) => setTimeout(r, settleTime));
174205

206+
// Check if the page loaded real content or an anti-bot challenge
207+
const pageContentCheck = (await page1.evaluate(`(() => {
208+
var text = (document.body.innerText || "").trim();
209+
var title = document.title || "";
210+
var isChallenged = /cloudflare|just a moment|checking your browser|access denied|blocked|captcha|verify you are human/i.test(text + " " + title);
211+
return { textLength: text.length, title: title, isChallenged: isChallenged };
212+
})()`)) as { textLength: number; title: string; isChallenged: boolean };
213+
214+
if (pageContentCheck.isChallenged || pageContentCheck.textLength < 200) {
215+
const reason = pageContentCheck.isChallenged
216+
? "Anti-bot protection detected (Cloudflare challenge or similar)"
217+
: "Page has very little text content (" +
218+
pageContentCheck.textLength +
219+
" chars) — may be blocked or a client-rendered SPA that needs more time";
220+
warnings.push(reason);
221+
progress("warn", reason);
222+
// Write a BLOCKED.md file so the user/agent knows what happened
223+
writeFileSync(
224+
join(outputDir, "BLOCKED.md"),
225+
`# 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`,
226+
"utf-8",
227+
);
228+
}
229+
175230
// Scroll through page to trigger lazy-loaded images and Lottie animations
176231
await page1.evaluate(`(async () => {
177232
var h = document.body.scrollHeight;
@@ -408,20 +463,12 @@ a.addEventListener('DOMLoaded',function(){a.goToAndStop(${midFrame},true);window
408463
progress("animations", "Cataloging animations...");
409464
animationCatalog = await collectAnimationCatalog(page1, cdpAnims, cdp);
410465

411-
// Capture per-section viewport screenshots (1920x1080 each — readable by AI vision)
412-
progress("screenshots", "Capturing viewport screenshots...");
413-
const { captureScreenshots, captureFullPageScreenshot } =
414-
await import("./screenshotCapture.js");
415-
const sectionScreenshots = await captureScreenshots(page1, outputDir, { maxScreenshots: 24 });
416-
progress("screenshots", `${sectionScreenshots.length} section screenshots captured`);
417-
418-
// Also capture full-page screenshot + scroll-position screenshots
419-
progress("screenshots", "Capturing full-page screenshot...");
420-
const fullPageScreenshot = await captureFullPageScreenshot(page1, outputDir, url);
421-
const screenshots: string[] = [...sectionScreenshots];
422-
if (fullPageScreenshot) {
423-
screenshots.push(fullPageScreenshot);
424-
}
466+
// Capture scroll-position viewport screenshots (1920x1080 at 10 scroll depths)
467+
// These show the page in its natural state — sticky headers, scroll animations fired.
468+
progress("screenshots", "Capturing scroll screenshots...");
469+
const { captureScrollScreenshots } = await import("./screenshotCapture.js");
470+
const screenshots = await captureScrollScreenshots(page1, outputDir);
471+
progress("screenshots", `${screenshots.length} scroll screenshots captured`);
425472

426473
// Strip framework scripts from the extracted body — keep visual library scripts
427474
// IMPORTANT: Use non-greedy matching within individual script tags only
@@ -574,23 +621,25 @@ a.addEventListener('DOMLoaded',function(){a.goToAndStop(${midFrame},true);window
574621
// Scroll to the video element so it's in the viewport
575622
await page1.evaluate(`window.scrollTo(0, ${Math.max(0, v.top - 100)})`);
576623
await new Promise((r) => setTimeout(r, 300));
577-
// Re-measure viewport-relative position after scroll
578-
const clipY = v.top - Math.max(0, v.top - 100);
579-
await page1.evaluate(`(() => {
580-
var vids = Array.from(document.querySelectorAll('video'));
581-
vids.forEach(function(v) {
582-
if ((v.src || v.currentSrc).includes(${JSON.stringify(v.filename)})) {
583-
try { v.play(); v.pause(); } catch(e) {}
584-
}
585-
});
586-
})()`);
624+
// Re-measure position after scroll (layout may have shifted)
625+
const rect = (await page1.evaluate((fn) => {
626+
const vid = [...document.querySelectorAll("video")].find((x) =>
627+
(x.src || x.currentSrc || "").includes(fn),
628+
);
629+
if (!vid) return null;
630+
// Seek to 0.1s and wait for a frame to decode
631+
vid.currentTime = 0.1;
632+
return vid.getBoundingClientRect().toJSON();
633+
}, v.filename)) as { x: number; y: number; width: number; height: number } | null;
634+
if (!rect || rect.width < 10) continue;
635+
await new Promise((r) => setTimeout(r, 200)); // let decoder settle
587636
await page1.screenshot({
588637
path: previewPath,
589638
clip: {
590-
x: Math.max(0, v.left),
591-
y: Math.max(0, clipY),
592-
width: Math.min(v.width, 1920),
593-
height: Math.min(v.height, 1080),
639+
x: Math.max(0, rect.x),
640+
y: Math.max(0, rect.y),
641+
width: Math.min(rect.width, 1920),
642+
height: Math.min(rect.height, 1080),
594643
},
595644
});
596645
} catch {
@@ -858,7 +907,7 @@ a.addEventListener('DOMLoaded',function(){a.goToAndStop(${midFrame},true);window
858907
],
859908
},
860909
],
861-
config: { maxOutputTokens: 100 },
910+
config: { maxOutputTokens: 300 },
862911
});
863912
return { file, caption: response.text?.trim() || "" };
864913
}),
@@ -1093,7 +1142,7 @@ a.addEventListener('DOMLoaded',function(){a.goToAndStop(${midFrame},true);window
10931142
url,
10941143
tokens,
10951144
animationCatalog,
1096-
!!fullPageScreenshot,
1145+
screenshots.length > 0,
10971146
discoveredLotties.length > 0,
10981147
existsSync(join(outputDir, "extracted", "shaders.json")),
10991148
catalogedAssets,

0 commit comments

Comments
 (0)