mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-08-31 02:41:44 +00:00
feat: website capture pipeline + 7-step video production skill (#284)
* feat(cli): add website capture with AI-powered DESIGN.md generation
Adds `hyperframes capture <url>` command that extracts a complete design
system from any website, producing AI-agent-ready output:
- Full-page screenshot (lazy-load aware, nav at top)
- AI-generated DESIGN.md via Claude API (colors, typography, elevation,
components, do's/don'ts) with programmatic asset catalog (136+ assets
with HTML context annotations like img[src], css url(), link[rel=preload])
- CSS-purged compositions (87% size reduction via PurgeCSS)
- HTML-prettified compositions (one-tag-per-line for AI readability)
- CLAUDE.md + .cursorrules auto-generated for AI agent instructions
- Asset deduplication (srcset variants) and tracking pixel filtering
* feat(cli): add gemini 3.1 pro, playwright screenshots, replica refinement
- switch to gemini 3.1 pro (gemini-3.1-pro-preview) with claude fallback
- playwright for full-page screenshots (fixes puppeteer gradient/fixed bugs)
- replica refinement loop: generate, screenshot, compare, fix
- extract inline svgs (50 max, 10kb each) to assets/svgs/
- extract visible text in dom order for content accuracy
- detect js libraries (gsap, three.js, scrolltrigger) via globals
- improved asset catalog grouping and naming
- reverse-engineered aura system prompt documentation
- comprehensive session handoff doc
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: update session handoff with slack research findings
- key finding: team already wants DESIGN.md integration (James, Bin, Vance)
- skills quality matters enormously - must invoke /hyperframes-compose
- eval infrastructure exists (Abhay's dashboards, Teodora's 78-criteria guide)
- templates at templates/ need study before finalizing skill
- session handoff updated with critical next steps
* refactor(cli): simplify capture pipeline, remove replica generator
* feat(capture): add Lottie detection and WebGL shader extraction
Captures Lottie animations via network interception and WebGL shader
source via gl.shaderSource hooking during site crawl. Updates
website-to-hyperframes skill with asset planning guidance, Lottie/shader
reading instructions, and stronger creative direction for scene planning.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* refactor(capture): clean pipeline + shader-first creative workflow
Capture pipeline:
- Remove dead deps (puppeteer-extra, stealth plugin, duplicate devDeps)
- Remove duplicate generateAgentPrompt() call (first lied about DESIGN.md)
- Remove dead canvas-to-image code in htmlExtractor (post canvas removal)
- Parallelize image downloads (batches of 5 via Promise.allSettled)
- Fix pre-existing TS error (match[1] guard in font downloader)
- Default capture output to captures/<hostname>
Skill creative overhaul:
- Add shader transition selection to creative director step (Step 4)
- Add shader wiring instructions to engineer step (Step 5)
- Replace 4-line energy modifiers with visual vocabulary table
- Strip rigid scene-by-scene templates from video-recipes.md
- Strip example fill data from scene plan tables
- Add "read transition refs before planning" instruction
- Add creative ambition language ("how the hell did they make this")
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: add skill architecture redesign spec
Comprehensive redesign of website-to-hyperframes skill and capture
pipeline based on code review findings and Claude Code architecture
research. Key changes: remove AI auto-generation, restructure skill
into phases, embed shader boilerplate in scaffold, fix color format.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: add implementation plan for skill architecture redesign
13-task plan covering: capture pipeline cleanup (remove AI generation,
fix colors to HEX, add asset descriptions, shader-ready scaffold),
skill restructuring (4 phases with artifact gates), and compose skill
Visual Identity Gate upgrade.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* refactor(capture): remove AI auto-generation and SDK dependencies
* fix(capture): convert extracted colors to HEX format
* refactor(capture): remove AI key path, add asset descriptions generator
* refactor(capture): update agent prompt, remove hasDesignMd, add asset descriptions
* feat(capture): pre-wire shader transitions in index.html scaffold
* chore: remove duplicate visual-styles.md (canonical is in hyperframes/)
* refactor(skill): rewrite website-to-hyperframes as phase-based orchestrator
* feat(skill): add Phase 1 understand reference
* feat(skill): add Phase 2 design reference with full DESIGN.md schema
* feat(skill): add Phase 3 creative direction reference
* feat(skill): add Phase 4 build reference with inline shader example
* feat(skill): upgrade Visual Identity Gate to produce full DESIGN.md
* docs: update CLAUDE.md skill references for phase-based workflow
* fix: address code review findings
- Remove orphaned `false` argument in generateAgentPrompt call (critical:
was shifting hasLottie, hasShaders, catalogedAssets parameters)
- Add HSL color handling in rgbToHex via temp element resolution
- Remove build artifact commit section from phase-4-build.md
- Fix __GSAP_TIMELINE reference to __timelines
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(capture): regex double-escape + simplify scaffold + fix asset descriptions
- Double-escape regex in tokenExtractor template literal (\s→\\s, \d→\\d, \(→\\()
so browser receives valid regex patterns via page.evaluate()
- Simplify index.html scaffold: scene slots + audio + timeline + comment pointing
to shader-setup.md reference (no broken inline shader boilerplate)
- Fix asset descriptions: use CatalogedAsset.contexts/notes instead of
nonexistent htmlContext field
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: code review — 16 bugs, 7-step skill rewrite, cleanup
Code fixes:
- snapshot.ts: path traversal guard, browser leak (try/finally), div-by-zero
for --frames 1, port bind error handling, rAF-based render settle
- index.ts: remove invalid thinkingConfig for gemini-2.5-flash, fix Gemini
batch/rate-limit comments, fix video preview viewport y-coordinate
- tokenExtractor.ts: remove dead seen[si] dedup code
- gsap.ts: index ALL classes for inline-style transform conflict detection
Skill architecture rewrite (4-phase → 7-step):
- Replace phase-1 through phase-4 with step-1 through step-7
- Add techniques.md (10 visual techniques with code patterns)
- Fix /hyperframes-compose → /hyperframes (skill doesn't exist)
- Fix captures/arc-browser reference → shader-setup.md (file doesn't exist)
- Fix step-7 hardcoded captures/stripe path
- Document Gemini API free/paid rate limits in step-1
Cleanup:
- CLAUDE.md: restore from Stripe-capture overwrite, update 4-phase → 7-step
- .gitignore: add PR #267 skills (hyperframes-animation-map, hyperframes-contrast)
- Delete old phase-*.md, animation-recreation.md, tts-integration.md
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* chore: remove dev artifacts, research docs, wrong lockfiles
Remove files that shouldn't ship in this PR:
- docs/research/ (aura analysis, prompt catalogs)
- docs/session-*.md, docs/SESSION-HANDOFF.md (dev notes)
- docs/superpowers/ planning and spec docs
- pnpm-lock.yaml at root and cli (repo uses bun, not pnpm)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(CLAUDE.md): align with main — slim format, add website-to-hyperframes mention
Main PR #283 removed the full skills table from CLAUDE.md and moved it
to AGENTS.md. Align with that decision: use main's slim dev-focused
format, fix pnpm→bun references, add one-line /website-to-hyperframes
pointer.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(cli): add capture command to help groups
The capture command was registered in cli.ts but missing from
the help groups, so it wouldn't appear in `hyperframes --help`.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* style: format skill reference files (oxfmt)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: regenerate bun.lock after rebase
The lockfile was stale after rebasing onto main — bun install
--frozen-lockfile failed in CI because new dependencies (google/genai,
patchright, purgecss) weren't reflected in the lockfile.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* 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
* fix: address PR review comments + improve capture quality
Review round 2 fixes (jrusso1020 + vanceingalls):
- verify/index.ts: add path traversal guard (relative + isAbsolute)
- verify/index.ts: fix sections[i] undefined typecheck error (CI green)
- index.ts: escape Lottie JSON with \u003c to prevent </script> breakout
- step-4-storyboard: fix technique count contradiction (2-3 per beat, not
across whole video)
- step-6-build: perspective tilt uses gsap.set() instead of CSS transform
(avoids GSAP overwrite conflict)
- step-1-capture: reorder — command first, Gemini note after (zero-config
is the default path, API key is optional enhancement)
- step-7-validate: add tsx fallback for snapshot command
- step-3-script: vary hook patterns, don't default to number every time
- assetDownloader: exempt SVGs from 10KB minimum filter (company logos
like Hubspot/Intel/DHL are 2-6KB; HeyGen capture: 13→75 assets)
Note: adm-zip was NOT removed (reviewer #3) — it's still in
packages/cli/package.json:30. The root package.json had patchright
and purgecss removed, not adm-zip.
Note: ANTHROPIC_API_KEY not restored in .env.example — grep confirms
zero references in the entire codebase. The @anthropic-ai/sdk dependency
was removed earlier in this branch.
* refactor(capture): split index.ts (1175 to 566 lines) into modules
Mechanical extraction, zero logic changes.
New files:
- mediaCapture.ts (345 lines): Lottie preview, video manifest/screenshots
- contentExtractor.ts (314 lines): library detection, text, Gemini, asset descriptions
- scaffolding.ts (135 lines): .env loading, project scaffold generation
Also fixes false-positive BLOCKED.md with structural Cloudflare detection.
Tested on 20 websites, pre/post output identical.
* chore(capture): remove --split flow (splitter, verify, cssPurger, purgecss)
The --split feature auto-generates compositions from captured HTML — a
different approach from the /website-to-hyperframes skill workflow where
agents build compositions from scratch using the storyboard.
No skill file, no step reference, and no test session ever used --split.
Removes 923 lines of unused code + purgecss dependency.
Backed up to ~/Desktop/capture-split-backup/ for reference.
* fix(security): add ssrf protection, lottie injection fix, oom guard
- assetDownloader: add isPrivateUrl() guard blocking private IP ranges
(127.x, 10.x, 172.16-31.x, 192.168.x, 169.254.x), cloud metadata
endpoints, localhost, and non-HTTP schemes
- mediaCapture: fix Lottie JSON injection by loading shell HTML first
then passing animation data via parameterized page.evaluate()
- index.ts: check Content-Length header before response.buffer() in
Lottie network interception to avoid OOM on multi-GB responses
* fix(capture): security fixes, timeout, sub-agent dispatch instructions
Security (from miguel-heygen review):
- assetDownloader: export isPrivateUrl() SSRF guard
- htmlExtractor: add isPrivateUrl check before CSS fetch
- mediaCapture: add isPrivateUrl check before Lottie fetch
- mediaCapture: fix previewPage leak (try/finally)
- mediaCapture: skip Lottie files > 2MB for preview (CDP limit)
- contentExtractor: skip images > 4MB for Gemini captioning
- index.ts: check Content-Length before response.buffer() (OOM guard)
- snapshot.ts: register error handler before server.listen()
Capture improvements:
- Default timeout 30s to 120s (Shopify needs ~90s for Cloudflare)
- step-6-build: sub-agent dispatch template with explicit rules:
pass file PATHS not contents, use local fonts not Google Fonts,
verify ../assets/ references after each beat
* fix(capture): catalog before DOM mutation, networkidle2, faster Gemini
Critical: asset cataloger now runs BEFORE extractHtml which converts img
src to data URLs. Framer sites like heykuba.com went from 2 to 78 images.
- networkidle2 instead of networkidle0 (unblocks SPAs with WebSockets)
- Lazy-load wait: scroll to bottom, wait for img.complete
- CSS background-image cataloging for Framer/Webflow
- SVG naming: checks class, id, parent, inner text (not just aria-label)
- Gemini batch 5->20, pause 12s->2s (paid tier: 2000 RPM, ~0.001/img)
- maxOutputTokens 300->500, descriptions sorted captioned-first
- Remove tsx fallback from step-1 (reviewer nit, published CLI has it)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ular Kimsanov
GitHub
parent
ebc12f7dc9
commit
87f4c77e2f
@ -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 (~$0.001/image, https://aistudio.google.com/apikey)
|
||||
|
||||
22
.gitignore
vendored
22
.gitignore
vendored
@ -47,6 +47,28 @@ packages/producer/src/services/fontData.generated.ts
|
||||
|
||||
# Test artifacts
|
||||
my-video/
|
||||
examples/
|
||||
packages/studio/data/
|
||||
.desloppify/
|
||||
.worktrees/
|
||||
|
||||
# Playwright MCP browser cache
|
||||
.playwright-mcp/
|
||||
|
||||
# Installed skills (user-specific)
|
||||
.agents/
|
||||
.claude/skills/
|
||||
skills-lock.json
|
||||
|
||||
# Skills from other PRs (not managed here)
|
||||
skills/hyperframes-animation-map/
|
||||
skills/hyperframes-contrast/
|
||||
|
||||
# Capture outputs
|
||||
captures/
|
||||
# Legacy test captures at repo root (use captures/ instead)
|
||||
*-capture/
|
||||
*-demo/
|
||||
*-ad/
|
||||
*-tour/
|
||||
*-brand/
|
||||
|
||||
@ -47,4 +47,4 @@ When adding a new CLI command:
|
||||
|
||||
## Skills
|
||||
|
||||
Composition authoring (not repo development) is guided by skills installed via `npx skills add heygen-com/hyperframes`. See `skills/` for source. Invoke `/hyperframes`, `/hyperframes-cli`, or `/gsap` when authoring compositions.
|
||||
Composition authoring (not repo development) is guided by skills installed via `npx skills add heygen-com/hyperframes`. See `skills/` for source. Invoke `/hyperframes`, `/hyperframes-cli`, or `/gsap` when authoring compositions. When a user provides a website URL and wants a video, invoke `/website-to-hyperframes` — it runs the full 7-step capture-to-video pipeline.
|
||||
|
||||
84
bun.lock
84
bun.lock
@ -7,7 +7,7 @@
|
||||
"devDependencies": {
|
||||
"@commitlint/cli": "^20.5.0",
|
||||
"@commitlint/config-conventional": "^20.5.0",
|
||||
"@hyperframes/player": "^0.3.0",
|
||||
"@hyperframes/player": "workspace:*",
|
||||
"@types/node": "^25.0.10",
|
||||
"concurrently": "^8.2.0",
|
||||
"happy-dom": "^20.9.0",
|
||||
@ -37,27 +37,27 @@
|
||||
"mime-types": "^3.0.2",
|
||||
"open": "^10.0.0",
|
||||
"postcss": "^8.5.8",
|
||||
"prettier": "^3.8.1",
|
||||
"puppeteer-core": "^24.39.1",
|
||||
},
|
||||
"devDependencies": {
|
||||
"@clack/prompts": "^1.1.0",
|
||||
"@hono/node-server": "^1.0.0",
|
||||
"@hyperframes/core": "workspace:*",
|
||||
"@hyperframes/engine": "workspace:*",
|
||||
"@hyperframes/producer": "workspace:*",
|
||||
"@types/adm-zip": "^0.5.7",
|
||||
"@types/mime-types": "^3.0.1",
|
||||
"@types/node": "^22.0.0",
|
||||
"adm-zip": "^0.5.16",
|
||||
"hono": "^4.0.0",
|
||||
"linkedom": "^0.18.12",
|
||||
"mime-types": "^3.0.2",
|
||||
"picocolors": "^1.1.1",
|
||||
"tsup": "^8.0.0",
|
||||
"tsx": "^4.0.0",
|
||||
"typescript": "^5.0.0",
|
||||
"vitest": "^3.2.4",
|
||||
},
|
||||
"optionalDependencies": {
|
||||
"@google/genai": "^1.50.0",
|
||||
},
|
||||
},
|
||||
"packages/core": {
|
||||
"name": "@hyperframes/core",
|
||||
@ -429,6 +429,8 @@
|
||||
|
||||
"@fontsource/space-mono": ["@fontsource/space-mono@5.2.9", "", {}, "sha512-b61faFOHEISQ/pD25G+cfGY9o/WW6lRv6hBQQfpWvEJ4y1V+S4gmth95EVyBE2VL3qDYHeVQ8nBzrplzdXTDDg=="],
|
||||
|
||||
"@google/genai": ["@google/genai@1.50.1", "", { "dependencies": { "google-auth-library": "^10.3.0", "p-retry": "^4.6.2", "protobufjs": "^7.5.4", "ws": "^8.18.0" }, "peerDependencies": { "@modelcontextprotocol/sdk": "^1.25.2" }, "optionalPeers": ["@modelcontextprotocol/sdk"] }, "sha512-YbkX7H9+1Pt8wOt7DDREy8XSoiL6fRDzZQRyaVBarFf8MR3zHGqVdvM4cLbDXqPhxqvegZShgfxb8kw9C7YhAQ=="],
|
||||
|
||||
"@hono/node-server": ["@hono/node-server@1.19.11", "", { "peerDependencies": { "hono": "4.12.8" } }, "sha512-dr8/3zEaB+p0D2n/IUrlPF1HZm586qgJNXK1a9fhg/PzdtkK7Ksd5l312tJX2yBuALqDYBlG20QEbayqPyxn+g=="],
|
||||
|
||||
"@hyperframes/cli": ["@hyperframes/cli@workspace:packages/cli"],
|
||||
@ -643,6 +645,26 @@
|
||||
|
||||
"@pkgjs/parseargs": ["@pkgjs/parseargs@0.11.0", "", {}, "sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg=="],
|
||||
|
||||
"@protobufjs/aspromise": ["@protobufjs/aspromise@1.1.2", "", {}, "sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ=="],
|
||||
|
||||
"@protobufjs/base64": ["@protobufjs/base64@1.1.2", "", {}, "sha512-AZkcAA5vnN/v4PDqKyMR5lx7hZttPDgClv83E//FMNhR2TMcLUhfRUBHCmSl0oi9zMgDDqRUJkSxO3wm85+XLg=="],
|
||||
|
||||
"@protobufjs/codegen": ["@protobufjs/codegen@2.0.4", "", {}, "sha512-YyFaikqM5sH0ziFZCN3xDC7zeGaB/d0IUb9CATugHWbd1FRFwWwt4ld4OYMPWu5a3Xe01mGAULCdqhMlPl29Jg=="],
|
||||
|
||||
"@protobufjs/eventemitter": ["@protobufjs/eventemitter@1.1.0", "", {}, "sha512-j9ednRT81vYJ9OfVuXG6ERSTdEL1xVsNgqpkxMsbIabzSo3goCjDIveeGv5d03om39ML71RdmrGNjG5SReBP/Q=="],
|
||||
|
||||
"@protobufjs/fetch": ["@protobufjs/fetch@1.1.0", "", { "dependencies": { "@protobufjs/aspromise": "^1.1.1", "@protobufjs/inquire": "^1.1.0" } }, "sha512-lljVXpqXebpsijW71PZaCYeIcE5on1w5DlQy5WH6GLbFryLUrBD4932W/E2BSpfRJWseIL4v/KPgBFxDOIdKpQ=="],
|
||||
|
||||
"@protobufjs/float": ["@protobufjs/float@1.0.2", "", {}, "sha512-Ddb+kVXlXst9d+R9PfTIxh1EdNkgoRe5tOX6t01f1lYWOvJnSPDBlG241QLzcyPdoNTsblLUdujGSE4RzrTZGQ=="],
|
||||
|
||||
"@protobufjs/inquire": ["@protobufjs/inquire@1.1.0", "", {}, "sha512-kdSefcPdruJiFMVSbn801t4vFK7KB/5gd2fYvrxhuJYg8ILrmn9SKSX2tZdV6V+ksulWqS7aXjBcRXl3wHoD9Q=="],
|
||||
|
||||
"@protobufjs/path": ["@protobufjs/path@1.1.2", "", {}, "sha512-6JOcJ5Tm08dOHAbdR3GrvP+yUUfkjG5ePsHYczMFLq3ZmMkAD98cDgcT2iA1lJ9NVwFd4tH/iSSoe44YWkltEA=="],
|
||||
|
||||
"@protobufjs/pool": ["@protobufjs/pool@1.1.0", "", {}, "sha512-0kELaGSIDBKvcgS4zkjz1PeddatrjYcmMWOlAuAPwAeccUrPHdUqo/J6LiymHHEiJT5NrF1UVwxY14f+fy4WQw=="],
|
||||
|
||||
"@protobufjs/utf8": ["@protobufjs/utf8@1.1.0", "", {}, "sha512-Vvn3zZrhQZkkBE8LSuW3em98c0FwgO4nxzv6OdSxPKJIEKY2bGbHn+mhGIPerzI4twdxaP8/0+06HBpwf345Lw=="],
|
||||
|
||||
"@puppeteer/browsers": ["@puppeteer/browsers@2.13.0", "", { "dependencies": { "debug": "4.4.3", "extract-zip": "2.0.1", "progress": "2.0.3", "proxy-agent": "6.5.0", "semver": "7.7.4", "tar-fs": "3.1.2", "yargs": "17.7.2" }, "bin": { "browsers": "lib/cjs/main-cli.js" } }, "sha512-46BZJYJjc/WwmKjsvDFykHtXrtomsCIrwYQPOP7VfMJoZY2bsDF9oROBABR3paDjDcmkUye1Pb1BqdcdiipaWA=="],
|
||||
|
||||
"@rolldown/pluginutils": ["@rolldown/pluginutils@1.0.0-beta.27", "", {}, "sha512-+d0F4MKMCbeVUJwG96uQ4SgAznZNSq93I3V+9NHA4OpvqG8mRCpGdKmK8l/dl02h2CCDHwW2FqilnTyDcAnqjA=="],
|
||||
@ -731,6 +753,8 @@
|
||||
|
||||
"@types/react-dom": ["@types/react-dom@19.2.3", "", { "peerDependencies": { "@types/react": "19.2.14" } }, "sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ=="],
|
||||
|
||||
"@types/retry": ["@types/retry@0.12.0", "", {}, "sha512-wWKOClTTiizcZhXnPY4wikVAwmdYHp8q6DmC+EJUzAMsycb7HB32Kh9RN4+0gExjmPmZSAQjgURXIGATPegAvA=="],
|
||||
|
||||
"@types/tough-cookie": ["@types/tough-cookie@4.0.5", "", {}, "sha512-/Ad8+nIOV7Rl++6f1BdKxFSMgmoqEoYbHRpPcx3JEfv8VRsQe9Z4mCXeJBzxs7mbHY/XOZZuXlRNfhpVPbs6ZA=="],
|
||||
|
||||
"@types/whatwg-mimetype": ["@types/whatwg-mimetype@3.0.2", "", {}, "sha512-c2AKvDT8ToxLIOUlN51gTiHXflsfIFisS4pO7pDPoKouJCESkhZnEy623gwP9laCy5lnLDAw1vAzu2vM2YLOrA=="],
|
||||
@ -805,12 +829,16 @@
|
||||
|
||||
"base64-arraybuffer": ["base64-arraybuffer@1.0.2", "", {}, "sha512-I3yl4r9QB5ZRY3XuJVEPfc2XhZO6YweFPI+UovAzn+8/hb3oJ6lnysaFcjVpkCPfVWFUDvoZ8kmVDP7WyRtYtQ=="],
|
||||
|
||||
"base64-js": ["base64-js@1.5.1", "", {}, "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA=="],
|
||||
|
||||
"baseline-browser-mapping": ["baseline-browser-mapping@2.10.9", "", { "bin": { "baseline-browser-mapping": "dist/cli.cjs" } }, "sha512-OZd0e2mU11ClX8+IdXe3r0dbqMEznRiT4TfbhYIbcRPZkqJ7Qwer8ij3GZAmLsRKa+II9V1v5czCkvmHH3XZBg=="],
|
||||
|
||||
"basic-ftp": ["basic-ftp@5.2.0", "", {}, "sha512-VoMINM2rqJwJgfdHq6RiUudKt2BV+FY5ZFezP/ypmwayk68+NzzAQy4XXLlqsGD4MCzq3DrmNFD/uUmBJuGoXw=="],
|
||||
|
||||
"bidi-js": ["bidi-js@1.0.3", "", { "dependencies": { "require-from-string": "2.0.2" } }, "sha512-RKshQI1R3YQ+n9YJz2QQ147P66ELpa1FQEg20Dk8oW9t2KgLbpDLLp9aGZ7y8WHSshDknG0bknqGw5/tyCs5tw=="],
|
||||
|
||||
"bignumber.js": ["bignumber.js@9.3.1", "", {}, "sha512-Ko0uX15oIUS7wJ3Rb30Fs6SkVbLmPBAKdlm7q9+ak9bbIeFf0MwuBsQV6z7+X768/cHsfg+WlysDWJcmthjsjQ=="],
|
||||
|
||||
"binary-extensions": ["binary-extensions@2.3.0", "", {}, "sha512-Ceh+7ox5qe7LJuLHoY0feh3pHuUDHAcRUeyL2VYghZwfpkNIy/+8Ocg0a3UuSoYzavmylwuLWQOf3hl0jjMMIw=="],
|
||||
|
||||
"boolbase": ["boolbase@1.0.0", "", {}, "sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww=="],
|
||||
@ -823,6 +851,8 @@
|
||||
|
||||
"buffer-crc32": ["buffer-crc32@0.2.13", "", {}, "sha512-VO9Ht/+p3SN7SKWqcrgEzjGbRSJYTx+Q1pTQC0wrWqHx0vpJraQ6GtHx8tvcg1rlK1byhU5gccxgOgj7B0TDkQ=="],
|
||||
|
||||
"buffer-equal-constant-time": ["buffer-equal-constant-time@1.0.1", "", {}, "sha512-zRpUiDwd/xk6ADqPMATG8vc9VPrkck7T07OIx0gnjmJAnHnTVXNQG3vfvWNuiZIkwu9KrKdA1iJKfsfTVxE6NA=="],
|
||||
|
||||
"bundle-name": ["bundle-name@4.1.0", "", { "dependencies": { "run-applescript": "7.1.0" } }, "sha512-tjwM5exMg6BGRI+kNmTntNsvdZS1X8BFYS6tnJ2hdH0kVxM6/eVZ2xy+FqStSWvYmtfFMDLIxurorHwDKfDz5Q=="],
|
||||
|
||||
"bundle-require": ["bundle-require@5.1.0", "", { "dependencies": { "load-tsconfig": "0.2.5" }, "peerDependencies": { "esbuild": "0.27.4" } }, "sha512-3WrrOuZiyaaZPWiEt4G3+IffISVC9HYlWueJEBWED4ZH4aIAC2PnkdnuRrR94M+w6yGWn4AglWtJtBI8YqvgoA=="],
|
||||
@ -897,7 +927,7 @@
|
||||
|
||||
"csstype": ["csstype@3.2.3", "", {}, "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ=="],
|
||||
|
||||
"data-uri-to-buffer": ["data-uri-to-buffer@6.0.2", "", {}, "sha512-7hvf7/GW8e86rW0ptuwS3OcBGDjIi6SZva7hCyWC0yYry2cOPmLIjXAUHI6DK2HsnwJd9ifmt57i8eV2n4YNpw=="],
|
||||
"data-uri-to-buffer": ["data-uri-to-buffer@4.0.1", "", {}, "sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A=="],
|
||||
|
||||
"data-urls": ["data-urls@7.0.0", "", { "dependencies": { "whatwg-mimetype": "5.0.0", "whatwg-url": "16.0.1" } }, "sha512-23XHcCF+coGYevirZceTVD7NdJOqVn+49IHyxgszm+JIiHLoB2TkmPtsYkNWT1pvRSGkc35L6NHs0yHkN2SumA=="],
|
||||
|
||||
@ -935,6 +965,8 @@
|
||||
|
||||
"eastasianwidth": ["eastasianwidth@0.2.0", "", {}, "sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA=="],
|
||||
|
||||
"ecdsa-sig-formatter": ["ecdsa-sig-formatter@1.0.11", "", { "dependencies": { "safe-buffer": "^5.0.1" } }, "sha512-nagl3RYrbNv6kQkeJIpt6NJZy8twLB/2vtz6yN9Z4vRKHN4/QZJIEbqohALSgwKdnksuY3k5Addp5lg8sVoVcQ=="],
|
||||
|
||||
"electron-to-chromium": ["electron-to-chromium@1.5.321", "", {}, "sha512-L2C7Q279W2D/J4PLZLk7sebOILDSWos7bMsMNN06rK482umHUrh/3lM8G7IlHFOYip2oAg5nha1rCMxr/rs6ZQ=="],
|
||||
|
||||
"emoji-regex": ["emoji-regex@8.0.0", "", {}, "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A=="],
|
||||
@ -967,6 +999,8 @@
|
||||
|
||||
"expect-type": ["expect-type@1.3.0", "", {}, "sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA=="],
|
||||
|
||||
"extend": ["extend@3.0.2", "", {}, "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g=="],
|
||||
|
||||
"extract-zip": ["extract-zip@2.0.1", "", { "dependencies": { "debug": "4.4.3", "get-stream": "5.2.0", "yauzl": "2.10.0" }, "optionalDependencies": { "@types/yauzl": "2.10.3" }, "bin": { "extract-zip": "cli.js" } }, "sha512-GDhU9ntwuKyGXdZBUgTIe+vXnWj0fppUEtMDL0+idd5Sta8TGpHssn/eusA9mrPr9qNDym6SxAYZjNvCn/9RBg=="],
|
||||
|
||||
"fast-deep-equal": ["fast-deep-equal@3.1.3", "", {}, "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q=="],
|
||||
@ -985,6 +1019,8 @@
|
||||
|
||||
"fdir": ["fdir@6.5.0", "", { "optionalDependencies": { "picomatch": "4.0.3" } }, "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg=="],
|
||||
|
||||
"fetch-blob": ["fetch-blob@3.2.0", "", { "dependencies": { "node-domexception": "^1.0.0", "web-streams-polyfill": "^3.0.3" } }, "sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ=="],
|
||||
|
||||
"fill-range": ["fill-range@7.1.1", "", { "dependencies": { "to-regex-range": "5.0.1" } }, "sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg=="],
|
||||
|
||||
"fix-dts-default-cjs-exports": ["fix-dts-default-cjs-exports@1.0.1", "", { "dependencies": { "magic-string": "0.30.21", "mlly": "1.8.2", "rollup": "4.59.0" } }, "sha512-pVIECanWFC61Hzl2+oOCtoJ3F17kglZC/6N94eRWycFgBH35hHx0Li604ZIzhseh97mf2p0cv7vVrOZGoqhlEg=="],
|
||||
@ -993,6 +1029,8 @@
|
||||
|
||||
"formatly": ["formatly@0.3.0", "", { "dependencies": { "fd-package-json": "2.0.0" }, "bin": { "formatly": "bin/index.mjs" } }, "sha512-9XNj/o4wrRFyhSMJOvsuyMwy8aUfBaZ1VrqHVfohyXf0Sw0e+yfKG+xZaY3arGCOMdwFsqObtzVOc1gU9KiT9w=="],
|
||||
|
||||
"formdata-polyfill": ["formdata-polyfill@4.0.10", "", { "dependencies": { "fetch-blob": "^3.1.2" } }, "sha512-buewHzMvYL29jdeQTVILecSaZKnt/RJWjoZCF5OW60Z67/GmSLBkOFM7qh1PI3zFNtJbaZL5eQu1vLfazOwj4g=="],
|
||||
|
||||
"fraction.js": ["fraction.js@5.3.4", "", {}, "sha512-1X1NTtiJphryn/uLQz3whtY6jK3fTqoE3ohKs0tT+Ujr1W59oopxmoEh7Lu5p6vBaPbgoM0bzveAW4Qi5RyWDQ=="],
|
||||
|
||||
"framer-motion": ["framer-motion@12.38.0", "", { "dependencies": { "motion-dom": "^12.38.0", "motion-utils": "^12.36.0", "tslib": "^2.4.0" }, "peerDependencies": { "@emotion/is-prop-valid": "*", "react": "^18.0.0 || ^19.0.0", "react-dom": "^18.0.0 || ^19.0.0" }, "optionalPeers": ["@emotion/is-prop-valid", "react", "react-dom"] }, "sha512-rFYkY/pigbcswl1XQSb7q424kSTQ8q6eAC+YUsSKooHQYuLdzdHjrt6uxUC+PRAO++q5IS7+TamgIw1AphxR+g=="],
|
||||
@ -1001,6 +1039,10 @@
|
||||
|
||||
"function-bind": ["function-bind@1.1.2", "", {}, "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA=="],
|
||||
|
||||
"gaxios": ["gaxios@7.1.4", "", { "dependencies": { "extend": "^3.0.2", "https-proxy-agent": "^7.0.1", "node-fetch": "^3.3.2" } }, "sha512-bTIgTsM2bWn3XklZISBTQX7ZSddGW+IO3bMdGaemHZ3tbqExMENHLx6kKZ/KlejgrMtj8q7wBItt51yegqalrA=="],
|
||||
|
||||
"gcp-metadata": ["gcp-metadata@8.1.2", "", { "dependencies": { "gaxios": "^7.0.0", "google-logging-utils": "^1.0.0", "json-bigint": "^1.0.0" } }, "sha512-zV/5HKTfCeKWnxG0Dmrw51hEWFGfcF2xiXqcA3+J90WDuP0SvoiSO5ORvcBsifmx/FoIjgQN3oNOGaQ5PhLFkg=="],
|
||||
|
||||
"gensync": ["gensync@1.0.0-beta.2", "", {}, "sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg=="],
|
||||
|
||||
"get-caller-file": ["get-caller-file@2.0.5", "", {}, "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg=="],
|
||||
@ -1021,6 +1063,10 @@
|
||||
|
||||
"global-directory": ["global-directory@4.0.1", "", { "dependencies": { "ini": "4.1.1" } }, "sha512-wHTUcDUoZ1H5/0iVqEudYW4/kAlN5cZ3j/bXn0Dpbizl9iaUVeWSHqiOjsgk6OW2bkLclbBjzewBz6weQ1zA2Q=="],
|
||||
|
||||
"google-auth-library": ["google-auth-library@10.6.2", "", { "dependencies": { "base64-js": "^1.3.0", "ecdsa-sig-formatter": "^1.0.11", "gaxios": "^7.1.4", "gcp-metadata": "8.1.2", "google-logging-utils": "1.1.3", "jws": "^4.0.0" } }, "sha512-e27Z6EThmVNNvtYASwQxose/G57rkRuaRbQyxM2bvYLLX/GqWZ5chWq2EBoUchJbCc57eC9ArzO5wMsEmWftCw=="],
|
||||
|
||||
"google-logging-utils": ["google-logging-utils@1.1.3", "", {}, "sha512-eAmLkjDjAFCVXg7A1unxHsLf961m6y17QFqXqAXGj/gVkKFrEICfStRfwUlGNfeCEjNRa32JEWOUTlYXPyyKvA=="],
|
||||
|
||||
"happy-dom": ["happy-dom@20.9.0", "", { "dependencies": { "@types/node": ">=20.0.0", "@types/whatwg-mimetype": "^3.0.2", "@types/ws": "^8.18.1", "entities": "^7.0.1", "whatwg-mimetype": "^3.0.0", "ws": "^8.18.3" } }, "sha512-GZZ9mKe8r646NUAf/zemnGbjYh4Bt8/MqASJY+pSm5ZDtc3YQox+4gsLI7yi1hba6o+eCsGxpHn5+iEVn31/FQ=="],
|
||||
|
||||
"has-flag": ["has-flag@4.0.0", "", {}, "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ=="],
|
||||
@ -1099,12 +1145,18 @@
|
||||
|
||||
"jsesc": ["jsesc@3.1.0", "", { "bin": { "jsesc": "bin/jsesc" } }, "sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA=="],
|
||||
|
||||
"json-bigint": ["json-bigint@1.0.0", "", { "dependencies": { "bignumber.js": "^9.0.0" } }, "sha512-SiPv/8VpZuWbvLSMtTDU8hEfrZWg/mH/nV/b4o0CYbSxu1UIQPLdwKOCIyLQX+VIPO5vrLX3i8qtqFyhdPSUSQ=="],
|
||||
|
||||
"json-parse-even-better-errors": ["json-parse-even-better-errors@2.3.1", "", {}, "sha512-xyFwyhro/JEof6Ghe2iz2NcXoj2sloNsWr/XsERDK/oiPCfaNhl5ONfp+jQdAZRQQ0IJWNzH9zIZF7li91kh2w=="],
|
||||
|
||||
"json-schema-traverse": ["json-schema-traverse@1.0.0", "", {}, "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug=="],
|
||||
|
||||
"json5": ["json5@2.2.3", "", { "bin": { "json5": "lib/cli.js" } }, "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg=="],
|
||||
|
||||
"jwa": ["jwa@2.0.1", "", { "dependencies": { "buffer-equal-constant-time": "^1.0.1", "ecdsa-sig-formatter": "1.0.11", "safe-buffer": "^5.0.1" } }, "sha512-hRF04fqJIP8Abbkq5NKGN0Bbr3JxlQ+qhZufXVr0DvujKy93ZCbXZMHDL4EOtodSbCWxOqR8MS1tXA5hwqCXDg=="],
|
||||
|
||||
"jws": ["jws@4.0.1", "", { "dependencies": { "jwa": "^2.0.1", "safe-buffer": "^5.0.1" } }, "sha512-EKI/M/yqPncGUUh44xz0PxSidXFr/+r0pA70+gIYhjv+et7yxM+s29Y+VGDkovRofQem0fs7Uvf4+YmAdyRduA=="],
|
||||
|
||||
"knip": ["knip@6.0.3", "", { "dependencies": { "@nodelib/fs.walk": "1.2.8", "fast-glob": "3.3.3", "formatly": "0.3.0", "get-tsconfig": "4.13.7", "jiti": "2.6.1", "minimist": "1.2.8", "oxc-parser": "0.120.0", "oxc-resolver": "11.19.1", "picocolors": "1.1.1", "picomatch": "4.0.3", "smol-toml": "1.6.1", "strip-json-comments": "5.0.3", "unbash": "2.2.0", "yaml": "2.8.3", "zod": "4.3.6" }, "bin": { "knip": "bin/knip.js", "knip-bun": "bin/knip-bun.js" } }, "sha512-6Ai+Iv41dVpBYH6mReFejhniWq4eiaKrBw4kghqz2Ew5psQMYEqYxJtXLdj/7vRJ3nVaHpakhYUCKO8p3ftNsQ=="],
|
||||
|
||||
"lefthook": ["lefthook@2.1.4", "", { "optionalDependencies": { "lefthook-darwin-arm64": "2.1.4", "lefthook-darwin-x64": "2.1.4", "lefthook-freebsd-arm64": "2.1.4", "lefthook-freebsd-x64": "2.1.4", "lefthook-linux-arm64": "2.1.4", "lefthook-linux-x64": "2.1.4", "lefthook-openbsd-arm64": "2.1.4", "lefthook-openbsd-x64": "2.1.4", "lefthook-windows-arm64": "2.1.4", "lefthook-windows-x64": "2.1.4" }, "bin": { "lefthook": "bin/index.js" } }, "sha512-JNfJ5gAn0KADvJ1I6/xMcx70+/6TL6U9gqGkKvPw5RNMfatC7jIg0Evl97HN846xmfz959BV70l8r3QsBJk30w=="],
|
||||
@ -1151,6 +1203,8 @@
|
||||
|
||||
"lodash.upperfirst": ["lodash.upperfirst@4.3.1", "", {}, "sha512-sReKOYJIJf74dhJONhU4e0/shzi1trVbSWDOhKYE5XV2O+H7Sb2Dihwuc7xWxVl+DgFPyTqIN3zMfT9cq5iWDg=="],
|
||||
|
||||
"long": ["long@5.3.2", "", {}, "sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA=="],
|
||||
|
||||
"loose-envify": ["loose-envify@1.4.0", "", { "dependencies": { "js-tokens": "4.0.0" }, "bin": { "loose-envify": "cli.js" } }, "sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q=="],
|
||||
|
||||
"loupe": ["loupe@3.2.1", "", {}, "sha512-CdzqowRJCeLU72bHvWqwRBBlLcMEtIvGrlvef74kMnV2AolS9Y8xUv1I0U/MNAWMhBlKIoyuEgoJ0t/bbwHbLQ=="],
|
||||
@ -1199,6 +1253,10 @@
|
||||
|
||||
"netmask": ["netmask@2.0.2", "", {}, "sha512-dBpDMdxv9Irdq66304OLfEmQ9tbNRFnFTuZiLo+bD+r332bBmMJ8GBLXklIXXgxd3+v9+KUnZaUR5PJMa75Gsg=="],
|
||||
|
||||
"node-domexception": ["node-domexception@1.0.0", "", {}, "sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ=="],
|
||||
|
||||
"node-fetch": ["node-fetch@3.3.2", "", { "dependencies": { "data-uri-to-buffer": "^4.0.0", "fetch-blob": "^3.1.4", "formdata-polyfill": "^4.0.10" } }, "sha512-dRB78srN/l6gqWulah9SrxeYnxeddIG30+GOqK/9OlLVyLg3HPnr6SqOWTWOXKRwC2eGYCkZ59NNuSgvSrpgOA=="],
|
||||
|
||||
"node-releases": ["node-releases@2.0.36", "", {}, "sha512-TdC8FSgHz8Mwtw9g5L4gR/Sh9XhSP/0DEkQxfEFXOpiul5IiHgHan2VhYYb6agDSfp4KuvltmGApc8HMgUrIkA=="],
|
||||
|
||||
"normalize-path": ["normalize-path@3.0.0", "", {}, "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA=="],
|
||||
@ -1221,6 +1279,8 @@
|
||||
|
||||
"oxlint": ["oxlint@1.56.0", "", { "optionalDependencies": { "@oxlint/binding-android-arm-eabi": "1.56.0", "@oxlint/binding-android-arm64": "1.56.0", "@oxlint/binding-darwin-arm64": "1.56.0", "@oxlint/binding-darwin-x64": "1.56.0", "@oxlint/binding-freebsd-x64": "1.56.0", "@oxlint/binding-linux-arm-gnueabihf": "1.56.0", "@oxlint/binding-linux-arm-musleabihf": "1.56.0", "@oxlint/binding-linux-arm64-gnu": "1.56.0", "@oxlint/binding-linux-arm64-musl": "1.56.0", "@oxlint/binding-linux-ppc64-gnu": "1.56.0", "@oxlint/binding-linux-riscv64-gnu": "1.56.0", "@oxlint/binding-linux-riscv64-musl": "1.56.0", "@oxlint/binding-linux-s390x-gnu": "1.56.0", "@oxlint/binding-linux-x64-gnu": "1.56.0", "@oxlint/binding-linux-x64-musl": "1.56.0", "@oxlint/binding-openharmony-arm64": "1.56.0", "@oxlint/binding-win32-arm64-msvc": "1.56.0", "@oxlint/binding-win32-ia32-msvc": "1.56.0", "@oxlint/binding-win32-x64-msvc": "1.56.0" }, "bin": { "oxlint": "bin/oxlint" } }, "sha512-Q+5Mj5PVaH/R6/fhMMFzw4dT+KPB+kQW4kaL8FOIq7tfhlnEVp6+3lcWqFruuTNlUo9srZUW3qH7Id4pskeR6g=="],
|
||||
|
||||
"p-retry": ["p-retry@4.6.2", "", { "dependencies": { "@types/retry": "0.12.0", "retry": "^0.13.1" } }, "sha512-312Id396EbJdvRONlngUx0NydfrIQ5lsYu0znKVUzVvArzEIt08V1qhtyESbGVd1FGX7UKtiFp5uwKZdM8wIuQ=="],
|
||||
|
||||
"pac-proxy-agent": ["pac-proxy-agent@7.2.0", "", { "dependencies": { "@tootallnate/quickjs-emscripten": "0.23.0", "agent-base": "7.1.4", "debug": "4.4.3", "get-uri": "6.0.5", "http-proxy-agent": "7.0.2", "https-proxy-agent": "7.0.6", "pac-resolver": "7.0.1", "socks-proxy-agent": "8.0.5" } }, "sha512-TEB8ESquiLMc0lV8vcd5Ql/JAKAoyzHFXaStwjkzpOpC5Yv+pIzLfHvjTSdf3vpa2bMiUQrg9i6276yn8666aA=="],
|
||||
|
||||
"pac-resolver": ["pac-resolver@7.0.1", "", { "dependencies": { "degenerator": "5.0.1", "netmask": "2.0.2" } }, "sha512-5NPgf87AT2STgwa2ntRMr45jTKrYBGkVU36yT0ig/n/GMAa3oPqhZfIQ2kMEimReg0+t9kZViDVZ83qfVUlckg=="],
|
||||
@ -1269,8 +1329,12 @@
|
||||
|
||||
"postcss-value-parser": ["postcss-value-parser@4.2.0", "", {}, "sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ=="],
|
||||
|
||||
"prettier": ["prettier@3.8.1", "", { "bin": { "prettier": "bin/prettier.cjs" } }, "sha512-UOnG6LftzbdaHZcKoPFtOcCKztrQ57WkHDeRD9t/PTQtmT0NHSeWWepj6pS0z/N7+08BHFDQVUrfmfMRcZwbMg=="],
|
||||
|
||||
"progress": ["progress@2.0.3", "", {}, "sha512-7PiHtLll5LdnKIMw100I+8xJXR5gW2QwWYkT6iJva0bXitZKa/XMrSbdmg3r2Xnaidz9Qumd0VPaMrZlF9V9sA=="],
|
||||
|
||||
"protobufjs": ["protobufjs@7.5.4", "", { "dependencies": { "@protobufjs/aspromise": "^1.1.2", "@protobufjs/base64": "^1.1.2", "@protobufjs/codegen": "^2.0.4", "@protobufjs/eventemitter": "^1.1.0", "@protobufjs/fetch": "^1.1.0", "@protobufjs/float": "^1.0.2", "@protobufjs/inquire": "^1.1.0", "@protobufjs/path": "^1.1.2", "@protobufjs/pool": "^1.1.0", "@protobufjs/utf8": "^1.1.0", "@types/node": ">=13.7.0", "long": "^5.0.0" } }, "sha512-CvexbZtbov6jW2eXAvLukXjXUW1TzFaivC46BpWc/3BpcCysb5Vffu+B3XHMm8lVEuy2Mm4XGex8hBSg1yapPg=="],
|
||||
|
||||
"proxy-agent": ["proxy-agent@6.5.0", "", { "dependencies": { "agent-base": "7.1.4", "debug": "4.4.3", "http-proxy-agent": "7.0.2", "https-proxy-agent": "7.0.6", "lru-cache": "7.18.3", "pac-proxy-agent": "7.2.0", "proxy-from-env": "1.1.0", "socks-proxy-agent": "8.0.5" } }, "sha512-TmatMXdr2KlRiA2CyDu8GqR8EjahTG3aY3nXjdzFyoZbmB8hrBsTyMezhULIXKnC0jpfjlmiZ3+EaCzoInSu/A=="],
|
||||
|
||||
"proxy-from-env": ["proxy-from-env@1.1.0", "", {}, "sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg=="],
|
||||
@ -1305,6 +1369,8 @@
|
||||
|
||||
"resolve-pkg-maps": ["resolve-pkg-maps@1.0.0", "", {}, "sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw=="],
|
||||
|
||||
"retry": ["retry@0.13.1", "", {}, "sha512-XQBQ3I8W1Cge0Seh+6gjj03LbmRFWuoszgK9ooCpwYIrhhoO80pfq4cUkU5DkknwfOfFteRwlZ56PYOGYyFWdg=="],
|
||||
|
||||
"reusify": ["reusify@1.1.0", "", {}, "sha512-g6QUff04oZpHs0eG5p83rFLhHeV00ug/Yf9nZM6fLeUrPguBTkTQOdpAWWspMh55TZfVQDPaN3NQJfbVRAxdIw=="],
|
||||
|
||||
"rollup": ["rollup@4.59.0", "", { "dependencies": { "@types/estree": "1.0.8" }, "optionalDependencies": { "@rollup/rollup-android-arm-eabi": "4.59.0", "@rollup/rollup-android-arm64": "4.59.0", "@rollup/rollup-darwin-arm64": "4.59.0", "@rollup/rollup-darwin-x64": "4.59.0", "@rollup/rollup-freebsd-arm64": "4.59.0", "@rollup/rollup-freebsd-x64": "4.59.0", "@rollup/rollup-linux-arm-gnueabihf": "4.59.0", "@rollup/rollup-linux-arm-musleabihf": "4.59.0", "@rollup/rollup-linux-arm64-gnu": "4.59.0", "@rollup/rollup-linux-arm64-musl": "4.59.0", "@rollup/rollup-linux-loong64-gnu": "4.59.0", "@rollup/rollup-linux-loong64-musl": "4.59.0", "@rollup/rollup-linux-ppc64-gnu": "4.59.0", "@rollup/rollup-linux-ppc64-musl": "4.59.0", "@rollup/rollup-linux-riscv64-gnu": "4.59.0", "@rollup/rollup-linux-riscv64-musl": "4.59.0", "@rollup/rollup-linux-s390x-gnu": "4.59.0", "@rollup/rollup-linux-x64-gnu": "4.59.0", "@rollup/rollup-linux-x64-musl": "4.59.0", "@rollup/rollup-openbsd-x64": "4.59.0", "@rollup/rollup-openharmony-arm64": "4.59.0", "@rollup/rollup-win32-arm64-msvc": "4.59.0", "@rollup/rollup-win32-ia32-msvc": "4.59.0", "@rollup/rollup-win32-x64-gnu": "4.59.0", "@rollup/rollup-win32-x64-msvc": "4.59.0", "fsevents": "2.3.3" }, "bin": { "rollup": "dist/bin/rollup" } }, "sha512-2oMpl67a3zCH9H79LeMcbDhXW/UmWG/y2zuqnF2jQq5uq9TbM9TVyXvA4+t+ne2IIkBdrLpAaRQAvo7YI/Yyeg=="],
|
||||
@ -1315,6 +1381,8 @@
|
||||
|
||||
"rxjs": ["rxjs@7.8.2", "", { "dependencies": { "tslib": "2.8.1" } }, "sha512-dhKf903U/PQZY6boNNtAGdWbG85WAbjT/1xYoZIC7FAY0yWapOBQVsVrDl58W86//e1VpMNBtRV4MaXfdMySFA=="],
|
||||
|
||||
"safe-buffer": ["safe-buffer@5.2.1", "", {}, "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ=="],
|
||||
|
||||
"saxes": ["saxes@6.0.0", "", { "dependencies": { "xmlchars": "2.2.0" } }, "sha512-xAg7SOnEhrm5zI3puOOKyy1OMcMlIJZYNJY7xLBwSze0UjhPLnWfj2GF2EpT0jmzaJKIWKHLsaSSajf35bcYnA=="],
|
||||
|
||||
"scheduler": ["scheduler@0.23.2", "", { "dependencies": { "loose-envify": "1.4.0" } }, "sha512-UOShsPwz7NrMUqhR6t0hWjFduvOzbtv7toDH1/hIrfRNIDBnnBWd0CwJTGvTpngVlmwGCdP9/Zl/tVrDqcuYzQ=="],
|
||||
@ -1457,6 +1525,8 @@
|
||||
|
||||
"walk-up-path": ["walk-up-path@4.0.0", "", {}, "sha512-3hu+tD8YzSLGuFYtPRb48vdhKMi0KQV5sn+uWr8+7dMEq/2G/dtLrdDinkLjqq5TIbIBjYJ4Ax/n3YiaW7QM8A=="],
|
||||
|
||||
"web-streams-polyfill": ["web-streams-polyfill@3.3.3", "", {}, "sha512-d2JWLCivmZYTSIoge9MsgFCZrt571BikcWGYkjC1khllbTeDlGqZ2D8vD8E/lJa8WGWbb7Plm8/XJYV7IJHZZw=="],
|
||||
|
||||
"webdriver-bidi-protocol": ["webdriver-bidi-protocol@0.4.1", "", {}, "sha512-ARrjNjtWRRs2w4Tk7nqrf2gBI0QXWuOmMCx2hU+1jUt6d00MjMxURrhxhGbrsoiZKJrhTSTzbIrc554iKI10qw=="],
|
||||
|
||||
"webidl-conversions": ["webidl-conversions@8.0.1", "", {}, "sha512-BMhLD/Sw+GbJC21C/UgyaZX41nPt8bUTg+jWyDeg7e7YN4xOM05YPSIXceACnXVtqyEw/LMClUQMtMZ+PGGpqQ=="],
|
||||
@ -1551,6 +1621,8 @@
|
||||
|
||||
"fast-glob/glob-parent": ["glob-parent@5.1.2", "", { "dependencies": { "is-glob": "4.0.3" } }, "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow=="],
|
||||
|
||||
"get-uri/data-uri-to-buffer": ["data-uri-to-buffer@6.0.2", "", {}, "sha512-7hvf7/GW8e86rW0ptuwS3OcBGDjIi6SZva7hCyWC0yYry2cOPmLIjXAUHI6DK2HsnwJd9ifmt57i8eV2n4YNpw=="],
|
||||
|
||||
"glob/minimatch": ["minimatch@9.0.9", "", { "dependencies": { "brace-expansion": "2.0.2" } }, "sha512-OBwBN9AL4dqmETlpS2zasx+vTeWclWzkblfZk7KTA5j3jeOONz/tRCnZomUyvNg83wL5Zv9Ss6HMJXAgL8R2Yg=="],
|
||||
|
||||
"import-fresh/resolve-from": ["resolve-from@4.0.0", "", {}, "sha512-pb/MYmXstAkysRFx8piNI1tGFNQIFA3vkE3Gq4EuA1dF6gHp/+vgZqsCGJapvy8N3Q+4o7FwvquPJcnZ7RYy4g=="],
|
||||
|
||||
@ -36,27 +36,27 @@
|
||||
"mime-types": "^3.0.2",
|
||||
"open": "^10.0.0",
|
||||
"postcss": "^8.5.8",
|
||||
"prettier": "^3.8.1",
|
||||
"puppeteer-core": "^24.39.1"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@clack/prompts": "^1.1.0",
|
||||
"@hono/node-server": "^1.0.0",
|
||||
"@hyperframes/core": "workspace:*",
|
||||
"@hyperframes/engine": "workspace:*",
|
||||
"@hyperframes/producer": "workspace:*",
|
||||
"@types/adm-zip": "^0.5.7",
|
||||
"@types/mime-types": "^3.0.1",
|
||||
"@types/node": "^22.0.0",
|
||||
"adm-zip": "^0.5.16",
|
||||
"hono": "^4.0.0",
|
||||
"linkedom": "^0.18.12",
|
||||
"mime-types": "^3.0.2",
|
||||
"picocolors": "^1.1.1",
|
||||
"tsup": "^8.0.0",
|
||||
"tsx": "^4.0.0",
|
||||
"typescript": "^5.0.0",
|
||||
"vitest": "^3.2.4"
|
||||
},
|
||||
"optionalDependencies": {
|
||||
"@google/genai": "^1.50.0"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=22"
|
||||
}
|
||||
|
||||
159
packages/cli/src/capture/agentPromptGenerator.ts
Normal file
159
packages/cli/src/capture/agentPromptGenerator.ts
Normal file
@ -0,0 +1,159 @@
|
||||
/**
|
||||
* Generate CLAUDE.md (and .cursorrules) for captured website projects.
|
||||
*
|
||||
* This file generates a DATA INVENTORY that tells the AI agent what files
|
||||
* exist and what they contain. The actual workflow lives in the
|
||||
* /website-to-hyperframes skill — this file points agents there.
|
||||
*/
|
||||
|
||||
import { writeFileSync } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
import type { DesignTokens } from "./types.js";
|
||||
import type { AnimationCatalog } from "./animationCataloger.js";
|
||||
import type { CatalogedAsset } from "./assetCataloger.js";
|
||||
|
||||
export function generateAgentPrompt(
|
||||
outputDir: string,
|
||||
url: string,
|
||||
tokens: DesignTokens,
|
||||
animations: AnimationCatalog | undefined,
|
||||
hasScreenshot: boolean,
|
||||
hasLottie?: boolean,
|
||||
hasShaders?: boolean,
|
||||
catalogedAssets?: CatalogedAsset[],
|
||||
): void {
|
||||
const prompt = buildPrompt(
|
||||
url,
|
||||
tokens,
|
||||
animations,
|
||||
hasScreenshot,
|
||||
hasLottie,
|
||||
hasShaders,
|
||||
catalogedAssets,
|
||||
);
|
||||
writeFileSync(join(outputDir, "CLAUDE.md"), prompt, "utf-8");
|
||||
writeFileSync(join(outputDir, ".cursorrules"), prompt, "utf-8");
|
||||
}
|
||||
|
||||
function buildPrompt(
|
||||
url: string,
|
||||
tokens: DesignTokens,
|
||||
animations: AnimationCatalog | undefined,
|
||||
hasScreenshot: boolean,
|
||||
hasLottie?: boolean,
|
||||
hasShaders?: boolean,
|
||||
catalogedAssets?: CatalogedAsset[],
|
||||
): string {
|
||||
const hostname = new URL(url).hostname.replace(/^www\./, "");
|
||||
const title = tokens.title || hostname;
|
||||
const cues = detectImplementationCues(tokens, animations);
|
||||
|
||||
const colorSummary = tokens.colors.slice(0, 10).join(", ");
|
||||
const fontSummary = tokens.fonts.join(", ") || "none detected";
|
||||
const sectionCount = tokens.sections?.length ?? 0;
|
||||
const headingCount = tokens.headings?.length ?? 0;
|
||||
const ctaCount = tokens.ctas?.length ?? 0;
|
||||
|
||||
const videoUrls = catalogedAssets
|
||||
? catalogedAssets
|
||||
.filter((a) => a.type === "Video" && a.url.startsWith("http"))
|
||||
.map((a) => a.url)
|
||||
.filter((u, i, arr) => arr.indexOf(u) === i) // deduplicate
|
||||
: [];
|
||||
|
||||
return `# ${title} — Captured Website
|
||||
|
||||
Source: ${url}
|
||||
|
||||
## How to Create a Video
|
||||
|
||||
Invoke the \`/website-to-hyperframes\` skill. It walks you through the full workflow: read data → create DESIGN.md → plan video → build compositions → lint/validate/preview.
|
||||
|
||||
If you don't have the skill installed, run: \`npx skills add heygen-com/hyperframes\`
|
||||
|
||||
## What's in This Capture
|
||||
|
||||
| File | Contents |
|
||||
|------|----------|
|
||||
${hasScreenshot ? "| `screenshots/scroll-*.png` | Viewport screenshots covering the full page (1920x1080 each, 30% overlap). **View scroll-000.png FIRST** (hero section), then scan through the rest to understand the full page. |" : ""}
|
||||
| \`extracted/tokens.json\` | Design tokens: ${tokens.colors.length} colors, ${tokens.fonts.length} fonts, ${headingCount} headings, ${ctaCount} CTAs, ${sectionCount} sections |
|
||||
| \`extracted/visible-text.txt\` | All visible text content in DOM order — use exact strings, never paraphrase |
|
||||
| \`extracted/assets-catalog.json\` | Every asset URL (images, fonts, videos, icons) with HTML context |
|
||||
| \`extracted/animations.json\` | Animation catalog: ${animations?.summary?.webAnimations ?? 0} web animations, ${animations?.summary?.scrollTargets ?? 0} scroll triggers, ${animations?.summary?.canvases ?? 0} canvases |
|
||||
| \`assets/svgs/\` | Extracted inline SVGs (logos, icons, illustrations) |
|
||||
| \`assets/\` | Downloaded images and font files — **Read every image file to see what it contains** |
|
||||
${hasLottie ? "| `extracted/lottie-manifest.json` | Lottie animations found on this site — read this to see what animations are available (name, dimensions, duration). Embed via `lottie.loadAnimation({ path: 'assets/lottie/animation-0.json' })`. Do NOT read the raw JSON files — they are machine data. |" : ""}
|
||||
${videoUrls.length > 0 ? "| `extracted/video-manifest.json` | Video manifest: every `<video>` element with its URL, surrounding heading/caption context, and a preview screenshot. **Read this + view each preview image** to understand what each video shows before using it. |" : ""}
|
||||
${hasShaders ? "| `extracted/shaders.json` | Captured WebGL shader source code (GLSL vertex + fragment shaders) |" : ""}
|
||||
| \`extracted/asset-descriptions.md\` | One-line description of every downloaded asset — read this first |
|
||||
|
||||
> **DESIGN.md does not exist yet.** It will be created when you run the \`/website-to-hyperframes\` workflow. Do not write compositions without it.
|
||||
|
||||
## Brand Summary
|
||||
|
||||
- **Colors**: ${colorSummary || "see tokens.json"}
|
||||
- **Fonts**: ${fontSummary}
|
||||
- **Sections**: ${sectionCount} page sections detected
|
||||
- **Headings**: ${headingCount} headings extracted
|
||||
- **CTAs**: ${ctaCount} calls-to-action found
|
||||
${
|
||||
cues.length > 0
|
||||
? `
|
||||
## Source Patterns Detected
|
||||
|
||||
${cues.map((c) => `- ${c}`).join("\n")}
|
||||
`
|
||||
: ""
|
||||
}
|
||||
## Example Prompts
|
||||
|
||||
Try asking:
|
||||
|
||||
- "Make me a 15-second social ad from this capture"
|
||||
- "Create a 30-second product tour video"
|
||||
- "Turn this into a vertical Instagram reel"
|
||||
- "Build a feature announcement video highlighting the top 3 features"
|
||||
`;
|
||||
}
|
||||
|
||||
function detectImplementationCues(
|
||||
tokens: DesignTokens,
|
||||
animations: AnimationCatalog | undefined,
|
||||
): string[] {
|
||||
const cues: string[] = [];
|
||||
|
||||
if (Object.keys(tokens.cssVariables).length > 10) {
|
||||
cues.push(
|
||||
"CSS custom properties used extensively — preserve design tokens for colors, spacing, and typography.",
|
||||
);
|
||||
}
|
||||
|
||||
if (tokens.fonts.length > 0) {
|
||||
cues.push(
|
||||
`Typography: ${tokens.fonts.join(", ")}. Match these exact font families and weights.`,
|
||||
);
|
||||
}
|
||||
|
||||
if (animations?.summary) {
|
||||
if (animations.summary.scrollTargets > 20) {
|
||||
cues.push(`${animations.summary.scrollTargets} scroll-triggered animations detected.`);
|
||||
}
|
||||
if (animations.summary.webAnimations > 5) {
|
||||
cues.push(`${animations.summary.webAnimations} active Web Animations detected.`);
|
||||
}
|
||||
if (animations.summary.canvases > 0) {
|
||||
cues.push(`${animations.summary.canvases} Canvas/WebGL elements detected.`);
|
||||
}
|
||||
}
|
||||
|
||||
const hasMarquee = animations?.cssDeclarations?.some(
|
||||
(d) =>
|
||||
d.animation?.name?.toLowerCase().includes("marquee") ||
|
||||
d.animation?.name?.toLowerCase().includes("scroll"),
|
||||
);
|
||||
if (hasMarquee) {
|
||||
cues.push("Marquee/ticker animation present — preserve continuous scrolling behavior.");
|
||||
}
|
||||
|
||||
return cues;
|
||||
}
|
||||
232
packages/cli/src/capture/animationCataloger.ts
Normal file
232
packages/cli/src/capture/animationCataloger.ts
Normal file
@ -0,0 +1,232 @@
|
||||
/**
|
||||
* Catalog all animations on a rendered page.
|
||||
*
|
||||
* Captures:
|
||||
* 1. Web Animations API — active animations with full keyframes + timing
|
||||
* 2. CSS animation/transition declarations via getComputedStyle
|
||||
* 3. IntersectionObserver targets (scroll-triggered elements)
|
||||
* 4. CDP Animation domain events
|
||||
*
|
||||
* The catalog is saved as animations.json and gives Claude Code
|
||||
* everything needed to recreate animations in GSAP.
|
||||
*
|
||||
* NOTE: Must be used on a page with ALL scripts running (not stripped).
|
||||
* Call setupAnimationCapture() BEFORE page.goto() for IO patching.
|
||||
* Call collectAnimationCatalog() AFTER page has loaded and settled.
|
||||
*/
|
||||
|
||||
import type { Page, CDPSession } from "puppeteer-core";
|
||||
|
||||
export interface AnimationCatalog {
|
||||
/** Active animations via document.getAnimations() — includes keyframes */
|
||||
webAnimations: WebAnimationEntry[];
|
||||
/** Elements with CSS animation/transition properties declared */
|
||||
cssDeclarations: CssAnimationEntry[];
|
||||
/** Elements being watched by IntersectionObserver (scroll triggers) */
|
||||
scrollTargets: ScrollTarget[];
|
||||
/** CDP Animation domain events captured during page lifecycle */
|
||||
cdpAnimations: CdpAnimationEntry[];
|
||||
/** Total counts summary */
|
||||
summary: {
|
||||
webAnimations: number;
|
||||
cssDeclarations: number;
|
||||
scrollTargets: number;
|
||||
cdpAnimations: number;
|
||||
canvases: number;
|
||||
};
|
||||
}
|
||||
|
||||
export interface WebAnimationEntry {
|
||||
type: string;
|
||||
playState: string;
|
||||
animationName?: string;
|
||||
targetSelector?: string;
|
||||
targetRect?: { x: number; y: number; width: number; height: number };
|
||||
keyframes?: Array<Record<string, string | number | null>>;
|
||||
timing?: {
|
||||
duration: number;
|
||||
delay: number;
|
||||
iterations: number;
|
||||
easing: string;
|
||||
direction: string;
|
||||
};
|
||||
}
|
||||
|
||||
export interface CssAnimationEntry {
|
||||
selector: string;
|
||||
animation?: { name: string; duration: string; easing: string };
|
||||
transition?: { property: string; duration: string };
|
||||
}
|
||||
|
||||
export interface ScrollTarget {
|
||||
selector: string;
|
||||
rect: { top: number; height: number; width: number };
|
||||
}
|
||||
|
||||
export interface CdpAnimationEntry {
|
||||
id: string;
|
||||
name: string;
|
||||
type: string;
|
||||
duration?: number;
|
||||
delay?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Set up animation capture hooks BEFORE navigating to the page.
|
||||
* This patches IntersectionObserver to track scroll-triggered elements.
|
||||
*/
|
||||
export async function setupAnimationCapture(page: Page): Promise<void> {
|
||||
await page.evaluateOnNewDocument(`
|
||||
window.__hf_io_targets = [];
|
||||
var OrigIO = window.IntersectionObserver;
|
||||
window.IntersectionObserver = function(callback, options) {
|
||||
var observer = new OrigIO(callback, options);
|
||||
var origObserve = observer.observe.bind(observer);
|
||||
observer.observe = function(target) {
|
||||
var sel = target.id ? '#' + target.id : target.tagName.toLowerCase();
|
||||
if (target.className && typeof target.className === 'string') {
|
||||
var cls = Array.from(target.classList).slice(0, 2).join('.');
|
||||
if (cls) sel += '.' + cls;
|
||||
}
|
||||
try {
|
||||
var rect = target.getBoundingClientRect();
|
||||
window.__hf_io_targets.push({
|
||||
selector: sel,
|
||||
rect: { top: Math.round(rect.top + window.scrollY), height: Math.round(rect.height), width: Math.round(rect.width) }
|
||||
});
|
||||
} catch(e) {}
|
||||
return origObserve(target);
|
||||
};
|
||||
return observer;
|
||||
};
|
||||
window.IntersectionObserver.prototype = OrigIO.prototype;
|
||||
`);
|
||||
}
|
||||
|
||||
/**
|
||||
* Start CDP Animation domain listener.
|
||||
* Returns the CDPSession and a reference to the captured array.
|
||||
*/
|
||||
export async function startCdpAnimationCapture(
|
||||
page: Page,
|
||||
): Promise<{ cdp: CDPSession; animations: CdpAnimationEntry[] }> {
|
||||
const cdp = await page.createCDPSession();
|
||||
await cdp.send("Animation.enable");
|
||||
const animations: CdpAnimationEntry[] = [];
|
||||
|
||||
cdp.on("Animation.animationStarted", (event: any) => {
|
||||
animations.push({
|
||||
id: event.animation.id,
|
||||
name: event.animation.name || "",
|
||||
type: event.animation.type,
|
||||
duration: event.animation.source?.duration,
|
||||
delay: event.animation.source?.delay,
|
||||
});
|
||||
});
|
||||
|
||||
return { cdp, animations };
|
||||
}
|
||||
|
||||
/**
|
||||
* Collect the full animation catalog after page has loaded and settled.
|
||||
* Should be called after scrolling through the page to trigger all animations.
|
||||
*/
|
||||
export async function collectAnimationCatalog(
|
||||
page: Page,
|
||||
cdpAnimations: CdpAnimationEntry[],
|
||||
cdp: CDPSession,
|
||||
): Promise<AnimationCatalog> {
|
||||
// Scroll through page to trigger scroll-based animations
|
||||
await page.evaluate(`(async () => {
|
||||
var height = document.body.scrollHeight;
|
||||
for (var y = 0; y < height; y += window.innerHeight * 0.5) {
|
||||
window.scrollTo(0, y);
|
||||
await new Promise(function(r) { setTimeout(r, 400); });
|
||||
}
|
||||
window.scrollTo(0, 0);
|
||||
await new Promise(function(r) { setTimeout(r, 1000); });
|
||||
})()`);
|
||||
|
||||
// Collect from Web Animations API + computed styles + IO targets
|
||||
const result = (await page.evaluate(`(() => {
|
||||
var webAnimations = [];
|
||||
var cssDeclarations = [];
|
||||
|
||||
// 1. Web Animations API
|
||||
try {
|
||||
var anims = document.getAnimations();
|
||||
webAnimations = anims.map(function(anim) {
|
||||
var r = { type: anim.constructor.name, playState: anim.playState, animationName: anim.animationName || null };
|
||||
var effect = anim.effect;
|
||||
if (effect && effect.target) {
|
||||
var t = effect.target;
|
||||
r.targetSelector = t.id ? '#' + t.id : t.tagName.toLowerCase();
|
||||
if (t.className && typeof t.className === 'string') {
|
||||
var cls = Array.from(t.classList).slice(0, 3).join('.');
|
||||
if (cls) r.targetSelector += '.' + cls;
|
||||
}
|
||||
try { r.targetRect = t.getBoundingClientRect().toJSON(); } catch(e) {}
|
||||
}
|
||||
if (effect && typeof effect.getKeyframes === 'function') {
|
||||
try { r.keyframes = effect.getKeyframes(); } catch(e) {}
|
||||
}
|
||||
if (effect && typeof effect.getComputedTiming === 'function') {
|
||||
try {
|
||||
var timing = effect.getComputedTiming();
|
||||
r.timing = { duration: timing.duration, delay: timing.delay, iterations: timing.iterations, easing: timing.easing, direction: timing.direction };
|
||||
} catch(e) {}
|
||||
}
|
||||
return r;
|
||||
});
|
||||
} catch(e) {}
|
||||
|
||||
// 2. CSS animation/transition scan
|
||||
var allEls = document.querySelectorAll('*');
|
||||
for (var i = 0; i < allEls.length && i < 5000; i++) {
|
||||
var el = allEls[i];
|
||||
try {
|
||||
var cs = getComputedStyle(el);
|
||||
var hasAnim = cs.animationName && cs.animationName !== 'none';
|
||||
var hasTrans = cs.transitionProperty && cs.transitionProperty !== 'all' && cs.transitionProperty !== 'none' && cs.transitionDuration !== '0s';
|
||||
if (hasAnim || hasTrans) {
|
||||
var sel = el.id ? '#' + el.id : el.tagName.toLowerCase();
|
||||
if (el.className && typeof el.className === 'string') {
|
||||
var cls = Array.from(el.classList).slice(0, 2).join('.');
|
||||
if (cls) sel += '.' + cls;
|
||||
}
|
||||
var entry = { selector: sel };
|
||||
if (hasAnim) entry.animation = { name: cs.animationName, duration: cs.animationDuration, easing: cs.animationTimingFunction };
|
||||
if (hasTrans) entry.transition = { property: cs.transitionProperty, duration: cs.transitionDuration };
|
||||
cssDeclarations.push(entry);
|
||||
}
|
||||
} catch(e) {}
|
||||
}
|
||||
|
||||
// 3. IO targets (collected by monkey-patch)
|
||||
var scrollTargets = (window.__hf_io_targets || []).map(function(t) {
|
||||
return { selector: t.selector, rect: t.rect };
|
||||
});
|
||||
|
||||
// 4. Canvas summary
|
||||
var canvasCount = document.querySelectorAll('canvas').length;
|
||||
|
||||
return { webAnimations: webAnimations, cssDeclarations: cssDeclarations, scrollTargets: scrollTargets, canvasCount: canvasCount };
|
||||
})()`)) as any;
|
||||
|
||||
// Stop CDP listener
|
||||
await cdp.send("Animation.disable");
|
||||
|
||||
return {
|
||||
webAnimations: result.webAnimations,
|
||||
cssDeclarations: result.cssDeclarations,
|
||||
scrollTargets: result.scrollTargets,
|
||||
cdpAnimations,
|
||||
summary: {
|
||||
webAnimations: result.webAnimations.length,
|
||||
cssDeclarations: result.cssDeclarations.length,
|
||||
scrollTargets: result.scrollTargets.length,
|
||||
cdpAnimations: cdpAnimations.length,
|
||||
canvases: result.canvasCount,
|
||||
},
|
||||
};
|
||||
}
|
||||
363
packages/cli/src/capture/assetCataloger.ts
Normal file
363
packages/cli/src/capture/assetCataloger.ts
Normal file
@ -0,0 +1,363 @@
|
||||
/**
|
||||
* Comprehensive asset cataloger.
|
||||
*
|
||||
* Scans rendered HTML and CSS for every referenced asset (images, videos,
|
||||
* fonts, icons, stylesheets, backgrounds) and records the HTML context
|
||||
* where each was found (e.g., img[src], css url(), link[rel=preload]).
|
||||
*
|
||||
* This is the programmatic Part 1 of DESIGN.md generation — deterministic
|
||||
* extraction, no AI involved.
|
||||
*/
|
||||
|
||||
import type { Page } from "puppeteer-core";
|
||||
|
||||
export interface CatalogedAsset {
|
||||
url: string;
|
||||
type: "Image" | "Video" | "Font" | "Icon" | "Background" | "Other";
|
||||
contexts: string[];
|
||||
notes?: string;
|
||||
/** Alt text, figcaption, or aria-label */
|
||||
description?: string;
|
||||
/** Nearest heading (h1-h4) text */
|
||||
nearestHeading?: string;
|
||||
/** Parent section/container class names */
|
||||
sectionClasses?: string;
|
||||
/** Whether the image is above the fold (visible without scrolling) */
|
||||
aboveFold?: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Extract all referenced assets from the rendered page with their HTML contexts.
|
||||
*/
|
||||
export async function catalogAssets(page: Page): Promise<CatalogedAsset[]> {
|
||||
const assets = await page.evaluate(`(() => {
|
||||
var assetMap = {};
|
||||
|
||||
// Extract rich DOM context from any element (heading, section, position)
|
||||
function getElementContext(el) {
|
||||
var ctx = {};
|
||||
// Alt text, aria-label, figcaption
|
||||
var desc = el.alt || el.getAttribute('aria-label') || el.getAttribute('title') || '';
|
||||
var fig = el.closest('figure');
|
||||
if (fig) {
|
||||
var cap = fig.querySelector('figcaption');
|
||||
if (cap) desc = desc || cap.textContent.trim().slice(0, 100);
|
||||
}
|
||||
var ariaBy = el.getAttribute('aria-describedby');
|
||||
if (ariaBy) {
|
||||
var descEl = document.getElementById(ariaBy);
|
||||
if (descEl) desc = desc || descEl.textContent.trim().slice(0, 100);
|
||||
}
|
||||
if (desc) ctx.description = desc.slice(0, 150);
|
||||
// Nearest heading
|
||||
var section = el.closest('section, article, header, footer, main, [class*="hero"], [class*="banner"], [class*="feature"]');
|
||||
if (section) {
|
||||
var heading = section.querySelector('h1, h2, h3, h4');
|
||||
if (heading) ctx.nearestHeading = heading.textContent.trim().slice(0, 80);
|
||||
ctx.sectionClasses = (section.className || '').toString().slice(0, 120);
|
||||
}
|
||||
// Above fold?
|
||||
try {
|
||||
var rect = el.getBoundingClientRect();
|
||||
ctx.aboveFold = rect.top < window.innerHeight;
|
||||
} catch(e) {}
|
||||
return ctx;
|
||||
}
|
||||
|
||||
function add(url, type, context, notes, richCtx) {
|
||||
if (!url || url === '' || url.startsWith('data:') || url.startsWith('blob:') || url === 'about:blank') return;
|
||||
// Normalize URL
|
||||
try { url = new URL(url, document.baseURI).href; } catch(e) { return; }
|
||||
// Skip tiny inline data URIs but keep base64 SVGs
|
||||
if (url.length > 50000) return;
|
||||
// Filter tracking pixels and analytics
|
||||
var lurl = url.toLowerCase();
|
||||
if (lurl.indexOf('analytics.') > -1 || lurl.indexOf('adsct') > -1 || lurl.indexOf('pixel.') > -1 || lurl.indexOf('tracking.') > -1 || lurl.indexOf('pdscrb.') > -1 || lurl.indexOf('doubleclick') > -1 || lurl.indexOf('googlesyndication') > -1 || lurl.indexOf('facebook.com/tr') > -1 || lurl.indexOf('bat.bing') > -1 || lurl.indexOf('clarity.ms') > -1) return;
|
||||
if (lurl.indexOf('bci=') > -1 && lurl.indexOf('twpid=') > -1) return;
|
||||
if (lurl.indexOf('cachebust=') > -1 || lurl.indexOf('event_id=') > -1) return;
|
||||
// Filter CSS fragment references to SVG filter IDs (not real downloadable assets)
|
||||
if (url.indexOf('.css#') > -1) return;
|
||||
if (url.indexOf('.css%23') > -1) return;
|
||||
// Filter same-page fragment references like "https://site.com/#clip-1"
|
||||
try { var parsed = new URL(url); if (parsed.hash && parsed.pathname.length <= 1) return; } catch(e2) {}
|
||||
|
||||
if (!assetMap[url]) {
|
||||
assetMap[url] = { url: url, type: type, contexts: [], notes: null };
|
||||
}
|
||||
var entry = assetMap[url];
|
||||
if (entry.contexts.indexOf(context) === -1) {
|
||||
entry.contexts.push(context);
|
||||
}
|
||||
if (notes && !entry.notes) {
|
||||
entry.notes = notes;
|
||||
}
|
||||
// Merge rich context (first one wins)
|
||||
if (richCtx) {
|
||||
if (richCtx.description && !entry.description) entry.description = richCtx.description;
|
||||
if (richCtx.nearestHeading && !entry.nearestHeading) entry.nearestHeading = richCtx.nearestHeading;
|
||||
if (richCtx.sectionClasses && !entry.sectionClasses) entry.sectionClasses = richCtx.sectionClasses;
|
||||
if (richCtx.aboveFold !== undefined && entry.aboveFold === undefined) entry.aboveFold = richCtx.aboveFold;
|
||||
}
|
||||
}
|
||||
|
||||
// ── Images: <img src="..."> and <img srcset="..."> ──
|
||||
document.querySelectorAll('img[src]').forEach(function(img) {
|
||||
var notes = img.alt || img.getAttribute('aria-label') || null;
|
||||
var ctx = getElementContext(img);
|
||||
add(img.src, 'Image', 'img[src]', notes, ctx);
|
||||
if (img.srcset) {
|
||||
img.srcset.split(',').forEach(function(entry) {
|
||||
var u = entry.trim().split(/\\s+/)[0];
|
||||
if (u) add(u, 'Image', 'img[srcset]', notes, ctx);
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
// ── Lazy-loaded images: data-src, data-lazy-src, data-original ──
|
||||
document.querySelectorAll('img[data-src], img[data-lazy-src], img[data-original], [data-background-image]').forEach(function(el) {
|
||||
var dataSrc = el.getAttribute('data-src') || el.getAttribute('data-lazy-src') || el.getAttribute('data-original') || el.getAttribute('data-background-image');
|
||||
if (dataSrc) add(dataSrc, 'Image', 'data-src', el.alt || el.getAttribute('aria-label') || null, getElementContext(el));
|
||||
});
|
||||
|
||||
// ── CSS background-image on divs (Framer, Webflow, etc.) ──
|
||||
document.querySelectorAll('div, section, [class*="hero"], [class*="card"], [class*="image"], [data-framer-background]').forEach(function(el) {
|
||||
var bg = getComputedStyle(el).backgroundImage;
|
||||
if (bg && bg !== 'none') {
|
||||
var match = bg.match(/url\\(["']?(https?:\\/\\/[^"')]+)["']?\\)/);
|
||||
if (match && match[1]) {
|
||||
add(match[1], 'Background', 'css url()', el.getAttribute('aria-label') || null, getElementContext(el));
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
// ── Picture sources: <source srcset="..."> ──
|
||||
document.querySelectorAll('source[srcset]').forEach(function(src) {
|
||||
src.srcset.split(',').forEach(function(entry) {
|
||||
var u = entry.trim().split(/\\s+/)[0];
|
||||
if (u) add(u, 'Image', 'source[srcset]', null);
|
||||
});
|
||||
});
|
||||
|
||||
// ── Videos: <video src="..."> and <video poster="..."> ──
|
||||
document.querySelectorAll('video[src]').forEach(function(v) {
|
||||
add(v.src, 'Video', 'video[src]', null);
|
||||
});
|
||||
document.querySelectorAll('video source[src]').forEach(function(s) {
|
||||
add(s.src, 'Video', 'video source[src]', null);
|
||||
});
|
||||
document.querySelectorAll('video[poster]').forEach(function(v) {
|
||||
add(v.poster, 'Image', 'video[poster]', null);
|
||||
});
|
||||
|
||||
// ── Links: preload, icon, apple-touch-icon, stylesheet ──
|
||||
document.querySelectorAll('link[rel]').forEach(function(link) {
|
||||
var rel = link.rel.toLowerCase();
|
||||
var href = link.href;
|
||||
if (!href) return;
|
||||
|
||||
if (rel.includes('preload')) {
|
||||
var asType = link.getAttribute('as') || '';
|
||||
if (asType === 'font') add(href, 'Font', 'link[rel="preload"]', null);
|
||||
else if (asType === 'image') add(href, 'Image', 'link[rel="preload"]', null);
|
||||
else if (asType === 'video') add(href, 'Video', 'link[rel="preload"]', null);
|
||||
else if (asType === 'style') add(href, 'Other', 'link[rel="preload"]', null);
|
||||
else add(href, 'Other', 'link[rel="preload"]', null);
|
||||
}
|
||||
if (rel.includes('icon')) add(href, 'Icon', 'link[rel="' + rel + '"]', null);
|
||||
if (rel === 'apple-touch-icon') add(href, 'Icon', 'link[rel="apple-touch-icon"]', null);
|
||||
});
|
||||
|
||||
// ── Meta: og:image, twitter:image ──
|
||||
document.querySelectorAll('meta[property="og:image"], meta[content][name="twitter:image"]').forEach(function(m) {
|
||||
var content = m.getAttribute('content');
|
||||
if (content) {
|
||||
var prop = m.getAttribute('property') || m.getAttribute('name') || '';
|
||||
add(content, 'Image', 'meta[' + prop + ']', null);
|
||||
}
|
||||
});
|
||||
|
||||
// ── CSS url() references from all stylesheets ──
|
||||
try {
|
||||
for (var i = 0; i < document.styleSheets.length; i++) {
|
||||
try {
|
||||
var sheet = document.styleSheets[i];
|
||||
var rules = sheet.cssRules || sheet.rules;
|
||||
if (!rules) continue;
|
||||
for (var j = 0; j < rules.length; j++) {
|
||||
var rule = rules[j];
|
||||
var cssText = rule.cssText || '';
|
||||
var urlMatches = cssText.match(/url\\(["']?([^"')]+)["']?\\)/g);
|
||||
if (urlMatches) {
|
||||
urlMatches.forEach(function(m) {
|
||||
var u = m.replace(/url\\(["']?/, '').replace(/["']?\\)/, '');
|
||||
if (u.startsWith('data:')) return;
|
||||
// Classify by file extension
|
||||
if (/\\.(woff2?|ttf|otf|eot)$/i.test(u)) {
|
||||
add(u, 'Font', 'css url()', null);
|
||||
} else if (/\\.(png|jpg|jpeg|gif|webp|avif|svg)$/i.test(u)) {
|
||||
add(u, 'Background', 'css url()', null);
|
||||
} else {
|
||||
add(u, 'Other', 'css url()', null);
|
||||
}
|
||||
});
|
||||
}
|
||||
}
|
||||
} catch(e) { /* cross-origin stylesheet */ }
|
||||
}
|
||||
} catch(e) {}
|
||||
|
||||
// ── Inline style url() references ──
|
||||
document.querySelectorAll('[style]').forEach(function(el) {
|
||||
var style = el.getAttribute('style') || '';
|
||||
var urlMatches = style.match(/url\\(["']?([^"')]+)["']?\\)/g);
|
||||
if (urlMatches) {
|
||||
urlMatches.forEach(function(m) {
|
||||
var u = m.replace(/url\\(["']?/, '').replace(/["']?\\)/, '');
|
||||
if (u.startsWith('data:')) return;
|
||||
if (/\\.(woff2?|ttf|otf|eot)$/i.test(u)) {
|
||||
add(u, 'Font', 'html inline style url()', null);
|
||||
} else {
|
||||
add(u, 'Other', 'html inline style url()', null);
|
||||
}
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
return Object.values(assetMap);
|
||||
})()`);
|
||||
|
||||
const raw = (assets as CatalogedAsset[]) || [];
|
||||
|
||||
// Deduplicate srcset resolution variants — keep highest resolution per base URL
|
||||
return deduplicateSrcsetVariants(raw);
|
||||
}
|
||||
|
||||
/**
|
||||
* Deduplicate Next.js image variants (same image at different w= sizes).
|
||||
* Keeps the highest resolution version and merges contexts.
|
||||
*/
|
||||
function deduplicateSrcsetVariants(assets: CatalogedAsset[]): CatalogedAsset[] {
|
||||
const byBase = new Map<string, CatalogedAsset>();
|
||||
|
||||
for (const a of assets) {
|
||||
// Extract base URL by stripping w= and q= params from _next/image URLs
|
||||
let baseKey = a.url;
|
||||
try {
|
||||
const u = new URL(a.url);
|
||||
if (u.pathname.includes("_next/image") || u.searchParams.has("w")) {
|
||||
u.searchParams.delete("w");
|
||||
u.searchParams.delete("q");
|
||||
baseKey = u.toString();
|
||||
}
|
||||
} catch {
|
||||
/* not a valid URL, keep as-is */
|
||||
}
|
||||
|
||||
const existing = byBase.get(baseKey);
|
||||
if (existing) {
|
||||
// Merge contexts
|
||||
for (const ctx of a.contexts) {
|
||||
if (!existing.contexts.includes(ctx)) {
|
||||
existing.contexts.push(ctx);
|
||||
}
|
||||
}
|
||||
// Keep notes from whichever has them
|
||||
if (a.notes && !existing.notes) {
|
||||
existing.notes = a.notes;
|
||||
}
|
||||
// Keep the URL with highest w= value (largest image)
|
||||
const existingW = getWidthParam(existing.url);
|
||||
const newW = getWidthParam(a.url);
|
||||
if (newW > existingW) {
|
||||
existing.url = a.url;
|
||||
}
|
||||
} else {
|
||||
byBase.set(baseKey, { ...a, contexts: [...a.contexts] });
|
||||
}
|
||||
}
|
||||
|
||||
return [...byBase.values()];
|
||||
}
|
||||
|
||||
function getWidthParam(url: string): number {
|
||||
try {
|
||||
const u = new URL(url);
|
||||
const w = u.searchParams.get("w");
|
||||
return w ? parseInt(w) : 0;
|
||||
} catch {
|
||||
return 0;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Format cataloged assets as markdown for the DESIGN.md Assets section.
|
||||
* Matches Aura.build's format: grouped by type, named from file paths.
|
||||
*/
|
||||
export function formatAssetCatalog(assets: CatalogedAsset[]): string {
|
||||
if (assets.length === 0) return "No assets detected.\n";
|
||||
|
||||
// Group by type
|
||||
const groups: Record<string, CatalogedAsset[]> = {};
|
||||
for (const a of assets) {
|
||||
const group = a.type;
|
||||
if (!groups[group]) groups[group] = [];
|
||||
groups[group]!.push(a);
|
||||
}
|
||||
|
||||
const lines: string[] = [];
|
||||
|
||||
// Output in order: Fonts, Images, Videos, Icons, Background, Other
|
||||
const order: CatalogedAsset["type"][] = ["Font", "Image", "Video", "Icon", "Background", "Other"];
|
||||
for (const type of order) {
|
||||
const group = groups[type];
|
||||
if (!group || group.length === 0) continue;
|
||||
|
||||
const sectionName =
|
||||
type === "Font"
|
||||
? "Fonts"
|
||||
: type === "Image"
|
||||
? "Images"
|
||||
: type === "Video"
|
||||
? "Videos"
|
||||
: type === "Icon"
|
||||
? "Icons"
|
||||
: type === "Background"
|
||||
? "Backgrounds"
|
||||
: "Other";
|
||||
lines.push(`### ${sectionName}`);
|
||||
|
||||
for (const a of group) {
|
||||
const name = a.notes || deriveAssetName(a.url);
|
||||
const contexts = a.contexts.join(", ");
|
||||
lines.push(`- **${name}**: ${a.url} — contexts: ${contexts}`);
|
||||
}
|
||||
lines.push("");
|
||||
}
|
||||
|
||||
return lines.join("\n");
|
||||
}
|
||||
|
||||
/**
|
||||
* Derive a human-readable name from a URL's file path.
|
||||
* E.g., "ConnectBentoBackground.jpg" → "Connect Bento Background"
|
||||
*/
|
||||
function deriveAssetName(url: string): string {
|
||||
try {
|
||||
const u = new URL(url);
|
||||
const path = u.pathname;
|
||||
// Get filename without extension
|
||||
const filename = path.split("/").pop() || "";
|
||||
const nameWithoutExt = filename.replace(/\.[^.]+$/, "");
|
||||
// Remove hash suffixes (e.g., "Sohne.cb178166" → "Sohne")
|
||||
const cleaned = nameWithoutExt.replace(/\.[a-f0-9]{6,}$/, "");
|
||||
// Convert camelCase/PascalCase to spaces
|
||||
const spaced = cleaned
|
||||
.replace(/([a-z])([A-Z])/g, "$1 $2")
|
||||
.replace(/[-_]/g, " ")
|
||||
.replace(/\s+/g, " ")
|
||||
.trim();
|
||||
return spaced || filename;
|
||||
} catch {
|
||||
return "Asset";
|
||||
}
|
||||
}
|
||||
311
packages/cli/src/capture/assetDownloader.ts
Normal file
311
packages/cli/src/capture/assetDownloader.ts
Normal file
@ -0,0 +1,311 @@
|
||||
/**
|
||||
* Download assets (SVGs, images, favicon, video posters) from extracted tokens + asset catalog.
|
||||
*
|
||||
* Single-pass approach: uses the asset catalog (which already deduplicates srcset variants
|
||||
* and keeps the highest resolution) as the primary source for images. This avoids downloading
|
||||
* the same image twice at different resolutions.
|
||||
*/
|
||||
|
||||
import { writeFileSync, mkdirSync } from "node:fs";
|
||||
import { join, extname } from "node:path";
|
||||
import type { DesignTokens, DownloadedAsset } from "./types.js";
|
||||
import type { CatalogedAsset } from "./assetCataloger.js";
|
||||
|
||||
export async function downloadAssets(
|
||||
tokens: DesignTokens,
|
||||
outputDir: string,
|
||||
catalogedAssets?: CatalogedAsset[],
|
||||
): Promise<DownloadedAsset[]> {
|
||||
const assetsDir = join(outputDir, "assets");
|
||||
mkdirSync(assetsDir, { recursive: true });
|
||||
|
||||
const assets: DownloadedAsset[] = [];
|
||||
const downloadedUrls = new Set<string>();
|
||||
|
||||
// 1. ALL inline SVGs — save as files (logos get priority naming)
|
||||
mkdirSync(join(outputDir, "assets", "svgs"), { recursive: true });
|
||||
for (let i = 0; i < tokens.svgs.length && i < 30; i++) {
|
||||
const svg = tokens.svgs[i]!;
|
||||
if (!svg.outerHTML || svg.outerHTML.length < 50) continue;
|
||||
const label = svg.label?.replace(/[^a-zA-Z0-9-_ ]/g, "").trim();
|
||||
const name = label ? slugify(label) + ".svg" : svg.isLogo ? `logo-${i}.svg` : `icon-${i}.svg`;
|
||||
const localPath = `assets/svgs/${name}`;
|
||||
try {
|
||||
writeFileSync(join(outputDir, localPath), svg.outerHTML, "utf-8");
|
||||
assets.push({ url: "", localPath, type: "svg" });
|
||||
} catch {
|
||||
/* skip */
|
||||
}
|
||||
}
|
||||
|
||||
// 2. Favicon
|
||||
for (const icon of tokens.icons) {
|
||||
if (!icon.href) continue;
|
||||
try {
|
||||
const ext = extname(new URL(icon.href).pathname) || ".ico";
|
||||
const name = `favicon${ext}`;
|
||||
const localPath = `assets/${name}`;
|
||||
const buffer = await fetchBuffer(icon.href);
|
||||
if (buffer) {
|
||||
writeFileSync(join(outputDir, localPath), buffer);
|
||||
assets.push({ url: icon.href, localPath, type: "favicon" });
|
||||
break;
|
||||
}
|
||||
} catch {
|
||||
/* skip */
|
||||
}
|
||||
}
|
||||
|
||||
// 3. Images — use the catalog as the single source of truth (highest resolution, deduplicated)
|
||||
// If no catalog available, fall back to tokens.images
|
||||
const imageUrls: { url: string; isPoster: boolean }[] = [];
|
||||
|
||||
if (catalogedAssets && catalogedAssets.length > 0) {
|
||||
// Use catalog — already deduplicated with highest-res srcset variants
|
||||
for (const a of catalogedAssets) {
|
||||
if (a.type !== "Image" && a.type !== "Background") continue;
|
||||
if (!a.url.startsWith("http")) continue;
|
||||
// Skip junk
|
||||
if (a.url.includes("pixel") || a.url.includes("beacon") || a.url.includes("analytics"))
|
||||
continue;
|
||||
if (a.url.includes("/favicon")) continue;
|
||||
// Download images from standard img/video contexts + CSS backgrounds (for hero sections, feature illustrations)
|
||||
const hasGoodContext = a.contexts.some(
|
||||
(c) =>
|
||||
c === "img[src]" ||
|
||||
c === "img[srcset]" ||
|
||||
c === "video[poster]" ||
|
||||
c === "source[srcset]" ||
|
||||
c === "data-src" ||
|
||||
c === "css url()",
|
||||
);
|
||||
if (!hasGoodContext) continue;
|
||||
const isPoster = a.contexts.includes("video[poster]");
|
||||
imageUrls.push({ url: a.url, isPoster });
|
||||
}
|
||||
} else {
|
||||
// Fallback: use tokens.images
|
||||
for (const img of tokens.images) {
|
||||
if (img.width > 200 && img.src.startsWith("http")) {
|
||||
imageUrls.push({ url: img.src, isPoster: false });
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Download all images (no arbitrary cap) — Claude Code needs to see every asset to use them creatively.
|
||||
// The 10KB minimum size filter handles tracking pixels and tiny icons.
|
||||
// Pre-filter to deduplicate before downloading.
|
||||
const toDownload: { url: string; isPoster: boolean; normalized: string }[] = [];
|
||||
for (const { url, isPoster } of imageUrls) {
|
||||
const normalized = normalizeUrl(url);
|
||||
if (downloadedUrls.has(normalized)) continue;
|
||||
downloadedUrls.add(normalized); // Reserve to prevent duplicates in parallel batches
|
||||
toDownload.push({ url, isPoster, normalized });
|
||||
}
|
||||
|
||||
// Download in parallel batches of 5
|
||||
const BATCH_SIZE = 5;
|
||||
let imgIdx = 0;
|
||||
for (let i = 0; i < toDownload.length; i += BATCH_SIZE) {
|
||||
const batch = toDownload.slice(i, i + BATCH_SIZE);
|
||||
const results = await Promise.allSettled(
|
||||
batch.map(async ({ url, isPoster }) => {
|
||||
const parsedUrl = new URL(url);
|
||||
const pathExt = extname(parsedUrl.pathname);
|
||||
const ext = pathExt && pathExt.length <= 5 ? pathExt : ".jpg";
|
||||
const buffer = await fetchBuffer(url);
|
||||
if (!buffer) return null;
|
||||
// SVGs are inherently small — don't apply the 10KB minimum to them
|
||||
const isSvg = ext === ".svg" || url.includes(".svg");
|
||||
const minSize = isSvg ? 200 : 10000;
|
||||
if (buffer.length < minSize) return null;
|
||||
return { url, isPoster, parsedUrl, ext, buffer };
|
||||
}),
|
||||
);
|
||||
for (const result of results) {
|
||||
if (result.status !== "fulfilled" || !result.value) continue;
|
||||
const { url, isPoster, parsedUrl, ext, buffer } = result.value;
|
||||
try {
|
||||
const prefix = isPoster ? "poster" : "image";
|
||||
const rawName =
|
||||
parsedUrl.pathname
|
||||
.split("/")
|
||||
.pop()
|
||||
?.replace(/\.[^.]+$/, "") || "";
|
||||
const isMeaningful =
|
||||
rawName.length > 2 &&
|
||||
rawName.length < 50 &&
|
||||
!/^[a-f0-9]{8,}$/i.test(rawName) &&
|
||||
!/^\d+$/.test(rawName) &&
|
||||
!rawName.includes("_next") &&
|
||||
!rawName.includes("?");
|
||||
const slug = isMeaningful ? slugify(rawName) : `${prefix}-${imgIdx}`;
|
||||
const name = `${slug}${ext}`;
|
||||
const localPath = `assets/${name}`;
|
||||
writeFileSync(join(outputDir, localPath), buffer);
|
||||
assets.push({ url, localPath, type: "image" });
|
||||
imgIdx++;
|
||||
} catch {
|
||||
/* skip */
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 4. OG image (if not already downloaded)
|
||||
if (tokens.ogImage && !downloadedUrls.has(normalizeUrl(tokens.ogImage))) {
|
||||
try {
|
||||
const ext = extname(new URL(tokens.ogImage).pathname) || ".jpg";
|
||||
const localPath = `assets/og-image${ext}`;
|
||||
const buffer = await fetchBuffer(tokens.ogImage);
|
||||
if (buffer && buffer.length > 5000) {
|
||||
writeFileSync(join(outputDir, localPath), buffer);
|
||||
assets.push({ url: tokens.ogImage, localPath, type: "image" });
|
||||
}
|
||||
} catch {
|
||||
/* skip */
|
||||
}
|
||||
}
|
||||
|
||||
return assets;
|
||||
}
|
||||
|
||||
/** Normalize URL for deduplication — unwrap Next.js image proxy, strip w/q params */
|
||||
function normalizeUrl(u: string): string {
|
||||
try {
|
||||
const parsed = new URL(u);
|
||||
if (parsed.pathname.includes("_next/image") && parsed.searchParams.has("url")) {
|
||||
return decodeURIComponent(parsed.searchParams.get("url")!);
|
||||
}
|
||||
parsed.searchParams.delete("w");
|
||||
parsed.searchParams.delete("q");
|
||||
parsed.searchParams.delete("dpr");
|
||||
return parsed.toString();
|
||||
} catch {
|
||||
return u;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Download fonts referenced in CSS and rewrite URLs to local paths.
|
||||
* Returns the modified CSS string with local font paths.
|
||||
*/
|
||||
export async function downloadAndRewriteFonts(css: string, outputDir: string): Promise<string> {
|
||||
const assetsDir = join(outputDir, "assets", "fonts");
|
||||
mkdirSync(assetsDir, { recursive: true });
|
||||
|
||||
const fontUrlRegex = /url\(['"]?(https?:\/\/[^'")\s]+\.(?:woff2?|ttf|otf)[^'")\s]*?)['"]?\)/g;
|
||||
const fontUrls = new Set<string>();
|
||||
let match;
|
||||
while ((match = fontUrlRegex.exec(css)) !== null) {
|
||||
if (match[1]) fontUrls.add(match[1]);
|
||||
}
|
||||
|
||||
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 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`;
|
||||
const localPath = join(assetsDir, filename);
|
||||
const relativePath = `assets/fonts/${filename}`;
|
||||
|
||||
const buffer = await fetchBuffer(fontUrl);
|
||||
if (buffer) {
|
||||
writeFileSync(localPath, buffer);
|
||||
rewritten = rewritten.split(fontUrl).join(relativePath);
|
||||
familyCounts.set(family, familyCount + 1);
|
||||
count++;
|
||||
}
|
||||
} catch {
|
||||
/* skip */
|
||||
}
|
||||
}
|
||||
|
||||
return rewritten;
|
||||
}
|
||||
|
||||
/** Block requests to private/internal IP ranges to prevent SSRF */
|
||||
export function isPrivateUrl(url: string): boolean {
|
||||
try {
|
||||
const { hostname } = new URL(url);
|
||||
// Block cloud metadata, localhost, and private IP ranges
|
||||
if (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]") return true;
|
||||
if (hostname === "169.254.169.254") return true; // AWS/GCP metadata
|
||||
if (hostname.endsWith(".internal") || hostname.endsWith(".local")) return true;
|
||||
// IPv4 private ranges
|
||||
const parts = hostname.split(".").map(Number);
|
||||
if (parts.length === 4 && parts.every((p) => !isNaN(p))) {
|
||||
if (parts[0] === 10) return true; // 10.0.0.0/8
|
||||
if (parts[0] === 172 && parts[1]! >= 16 && parts[1]! <= 31) return true; // 172.16.0.0/12
|
||||
if (parts[0] === 192 && parts[1] === 168) return true; // 192.168.0.0/16
|
||||
if (parts[0] === 169 && parts[1] === 254) return true; // 169.254.0.0/16 (link-local)
|
||||
}
|
||||
// Block non-HTTP(S) schemes
|
||||
const scheme = new URL(url).protocol;
|
||||
if (scheme !== "http:" && scheme !== "https:") return true;
|
||||
return false;
|
||||
} catch {
|
||||
return true; // reject unparseable URLs
|
||||
}
|
||||
}
|
||||
|
||||
async function fetchBuffer(url: string): Promise<Buffer | null> {
|
||||
try {
|
||||
if (isPrivateUrl(url)) return null;
|
||||
const res = await fetch(url, {
|
||||
signal: AbortSignal.timeout(10000),
|
||||
headers: { "User-Agent": "HyperFrames/1.0" },
|
||||
redirect: "follow",
|
||||
});
|
||||
if (!res.ok) return null;
|
||||
// Reject XML/HTML error pages disguised as 200 OK (common with S3/CloudFront)
|
||||
const ct = res.headers.get("content-type") || "";
|
||||
if (ct.includes("text/xml") || ct.includes("text/html") || ct.includes("application/xml")) {
|
||||
return null;
|
||||
}
|
||||
const ab = await res.arrayBuffer();
|
||||
return Buffer.from(ab);
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function slugify(text: string): string {
|
||||
return text
|
||||
.toLowerCase()
|
||||
.replace(/[^a-z0-9]+/g, "-")
|
||||
.replace(/^-|-$/g, "")
|
||||
.slice(0, 40);
|
||||
}
|
||||
316
packages/cli/src/capture/contentExtractor.ts
Normal file
316
packages/cli/src/capture/contentExtractor.ts
Normal file
@ -0,0 +1,316 @@
|
||||
/**
|
||||
* Content extraction helpers for the website capture pipeline.
|
||||
*
|
||||
* Handles library detection, visible text extraction, Gemini captioning,
|
||||
* and asset description generation.
|
||||
*
|
||||
* All page.evaluate() calls use string expressions to avoid
|
||||
* tsx/esbuild __name injection (see esbuild issue #1031).
|
||||
*/
|
||||
|
||||
import type { Page } from "puppeteer-core";
|
||||
import { readdirSync, statSync, readFileSync } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
import type { CatalogedAsset } from "./assetCataloger.js";
|
||||
import type { DesignTokens } from "./types.js";
|
||||
|
||||
/**
|
||||
* Detect JS libraries via window globals, DOM fingerprints, script URLs,
|
||||
* and WebGL shader analysis.
|
||||
*
|
||||
* Returns a deduplicated list of detected library names.
|
||||
*/
|
||||
export async function detectLibraries(
|
||||
page: Page,
|
||||
capturedShaders?: Array<{ type: string; source: string }>,
|
||||
): Promise<string[]> {
|
||||
let detectedLibraries: string[] = [];
|
||||
try {
|
||||
detectedLibraries = (await page.evaluate(`(() => {
|
||||
var libs = [];
|
||||
function add(name) { if (libs.indexOf(name) === -1) libs.push(name); }
|
||||
|
||||
// 1. Window globals (works for CDN-loaded / non-bundled libraries)
|
||||
if (typeof window.gsap !== 'undefined' || typeof window.TweenMax !== 'undefined') add('GSAP');
|
||||
if (typeof window.ScrollTrigger !== 'undefined') add('GSAP ScrollTrigger');
|
||||
if (typeof window.THREE !== 'undefined') add('Three.js');
|
||||
if (typeof window.PIXI !== 'undefined') add('PixiJS');
|
||||
if (typeof window.BABYLON !== 'undefined') add('Babylon.js');
|
||||
if (typeof window.Lottie !== 'undefined' || typeof window.lottie !== 'undefined') add('Lottie');
|
||||
if (typeof window.__NEXT_DATA__ !== 'undefined') add('Next.js');
|
||||
if (typeof window.__NUXT__ !== 'undefined') add('Nuxt');
|
||||
if (typeof window.Webflow !== 'undefined') add('Webflow');
|
||||
|
||||
// 2. DOM fingerprints (survive bundling — most reliable for modern sites)
|
||||
// Three.js sets data-engine on every canvas it creates
|
||||
var threeCanvas = document.querySelector('canvas[data-engine*="three"]');
|
||||
if (threeCanvas) add('Three.js (' + (threeCanvas.getAttribute('data-engine') || '') + ')');
|
||||
// Babylon.js also sets data-engine
|
||||
var babylonCanvas = document.querySelector('canvas[data-engine*="Babylon"]');
|
||||
if (babylonCanvas) add('Babylon.js');
|
||||
// Lottie web components
|
||||
if (document.querySelector('dotlottie-wc, lottie-player, dotlottie-player')) add('Lottie');
|
||||
// Rive
|
||||
if (document.querySelector('canvas[class*="rive"], rive-canvas')) add('Rive');
|
||||
// React/Next.js
|
||||
if (document.getElementById('__next')) add('Next.js');
|
||||
if (document.getElementById('__nuxt')) add('Nuxt');
|
||||
if (document.querySelector('[data-reactroot], [data-react-helmet]')) add('React');
|
||||
// Svelte
|
||||
if (document.querySelector('[class*="svelte-"]')) add('Svelte');
|
||||
// Tailwind (utility class detection)
|
||||
if (document.querySelector('[class*="flex "], [class*="grid "], [class*="px-"], [class*="py-"]')) add('Tailwind CSS');
|
||||
// Framer Motion
|
||||
if (document.querySelector('[style*="--framer-"], [data-framer-component-type]')) add('Framer Motion');
|
||||
|
||||
// 3. Script URL patterns
|
||||
document.querySelectorAll('script[src]').forEach(function(s) {
|
||||
var src = s.src.toLowerCase();
|
||||
if (src.includes('gsap') || src.includes('tweenmax') || src.includes('greensock')) add('GSAP');
|
||||
if (src.includes('scrolltrigger')) add('GSAP ScrollTrigger');
|
||||
if (src.includes('three.module') || src.includes('three.min')) add('Three.js');
|
||||
if (src.includes('pixi')) add('PixiJS');
|
||||
if (src.includes('lottie') || src.includes('bodymovin')) add('Lottie');
|
||||
if (src.includes('framer-motion')) add('Framer Motion');
|
||||
if (src.includes('anime.min') || src.includes('animejs')) add('Anime.js');
|
||||
if (src.includes('matter.min') || src.includes('matter-js')) add('Matter.js');
|
||||
if (src.includes('lenis')) add('Lenis (smooth scroll)');
|
||||
});
|
||||
|
||||
return libs;
|
||||
})()`)) as string[];
|
||||
} catch {
|
||||
// Non-blocking
|
||||
}
|
||||
|
||||
// 4. Shader fingerprinting — infer WebGL framework from captured GLSL
|
||||
try {
|
||||
const shaders = capturedShaders || [];
|
||||
if (shaders.length > 0) {
|
||||
const allSource = shaders.map((s) => s.source).join("\n");
|
||||
const add = (name: string) => {
|
||||
if (!detectedLibraries.includes(name)) detectedLibraries.push(name);
|
||||
};
|
||||
add("WebGL");
|
||||
// Three.js shader fingerprints (built-in uniforms that survive bundling)
|
||||
if (allSource.includes("modelViewMatrix") && allSource.includes("projectionMatrix"))
|
||||
add("Three.js (confirmed via shaders)");
|
||||
// PixiJS shader fingerprints
|
||||
else if (
|
||||
allSource.includes("vTextureCoord") &&
|
||||
allSource.includes("uSampler") &&
|
||||
!allSource.includes("modelViewMatrix")
|
||||
)
|
||||
add("PixiJS (confirmed via shaders)");
|
||||
// Babylon.js shader fingerprints
|
||||
else if (allSource.includes("viewProjection") && allSource.includes("world"))
|
||||
add("Babylon.js (confirmed via shaders)");
|
||||
}
|
||||
} catch {
|
||||
/* non-blocking */
|
||||
}
|
||||
|
||||
return detectedLibraries;
|
||||
}
|
||||
|
||||
/**
|
||||
* Extract all visible text from the page in DOM order using a TreeWalker.
|
||||
* Truncates to ~30K chars to avoid blowing up downstream prompts.
|
||||
*/
|
||||
export async function extractVisibleText(page: Page): Promise<string> {
|
||||
let visibleTextContent = "";
|
||||
try {
|
||||
visibleTextContent = (await page.evaluate(`(() => {
|
||||
var walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT, null);
|
||||
var texts = [];
|
||||
var node;
|
||||
while (node = walker.nextNode()) {
|
||||
var text = (node.textContent || '').trim();
|
||||
if (text.length < 3) continue;
|
||||
var el = node.parentElement;
|
||||
if (!el) continue;
|
||||
var style = getComputedStyle(el);
|
||||
if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0') continue;
|
||||
var tag = el.tagName.toLowerCase();
|
||||
if (tag === 'script' || tag === 'style' || tag === 'noscript') continue;
|
||||
texts.push(text);
|
||||
}
|
||||
return texts.join('\\n');
|
||||
})()`)) as string;
|
||||
// Truncate to ~30K chars to avoid blowing up the prompt
|
||||
if (visibleTextContent.length > 30000) {
|
||||
visibleTextContent = visibleTextContent.slice(0, 30000) + "\n[...truncated]";
|
||||
}
|
||||
} catch {
|
||||
// Non-blocking
|
||||
}
|
||||
return visibleTextContent;
|
||||
}
|
||||
|
||||
/**
|
||||
* Caption downloaded images using Gemini vision API.
|
||||
*
|
||||
* Batches requests to stay under free-tier rate limits.
|
||||
* Returns a map of filename -> caption string.
|
||||
*/
|
||||
export async function captionImagesWithGemini(
|
||||
outputDir: string,
|
||||
progress: (stage: string, detail?: string) => void,
|
||||
warnings: string[],
|
||||
): Promise<Record<string, string>> {
|
||||
const geminiCaptions: Record<string, string> = {};
|
||||
const geminiKey = process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;
|
||||
if (!geminiKey) return geminiCaptions;
|
||||
|
||||
progress("design", "Captioning images with Gemini vision...");
|
||||
try {
|
||||
const { GoogleGenAI } = await import("@google/genai");
|
||||
const ai = new GoogleGenAI({ apiKey: geminiKey });
|
||||
const imageFiles = readdirSync(join(outputDir, "assets")).filter((f: string) =>
|
||||
/\.(png|jpg|jpeg|webp|gif)$/i.test(f),
|
||||
);
|
||||
|
||||
// Caption in parallel batches via Gemini vision API.
|
||||
// Free tier: 5 RPM → batch 5, 12s pause (~$0 but slow)
|
||||
// Paid tier: 2000 RPM → batch 20, 1s pause (~$0.001/image, fast)
|
||||
// We try a larger batch first; if rate-limited, fall back to smaller batches.
|
||||
const model = "gemini-2.5-flash";
|
||||
const BATCH_SIZE = 20;
|
||||
for (let i = 0; i < imageFiles.length; i += BATCH_SIZE) {
|
||||
const batch = imageFiles.slice(i, i + BATCH_SIZE);
|
||||
const results = await Promise.allSettled(
|
||||
batch.map(async (file: string) => {
|
||||
const filePath = join(outputDir, "assets", file);
|
||||
const stat = statSync(filePath);
|
||||
if (stat.size > 4_000_000) return { file, caption: "" }; // skip images > 4 MB (Gemini inline limit)
|
||||
const buffer = readFileSync(filePath);
|
||||
const base64 = buffer.toString("base64");
|
||||
const ext = file.split(".").pop()?.toLowerCase() || "png";
|
||||
const mimeType = ext === "jpg" ? "image/jpeg" : `image/${ext}`;
|
||||
const response = await ai.models.generateContent({
|
||||
model,
|
||||
contents: [
|
||||
{
|
||||
role: "user",
|
||||
parts: [
|
||||
{ inlineData: { mimeType, data: base64 } },
|
||||
{
|
||||
text: "Describe this website image in ONE short sentence for a video storyboard. Focus on: what it shows, dominant colors, whether background is light or dark. Be factual, not creative.",
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
config: { maxOutputTokens: 500 },
|
||||
});
|
||||
return { file, caption: response.text?.trim() || "" };
|
||||
}),
|
||||
);
|
||||
for (const result of results) {
|
||||
if (result.status === "fulfilled" && result.value.caption) {
|
||||
geminiCaptions[result.value.file] = result.value.caption;
|
||||
}
|
||||
}
|
||||
// Pace requests to stay under free tier rate limits (5 RPM for gemini-2.5-flash)
|
||||
if (i + BATCH_SIZE < imageFiles.length) {
|
||||
await new Promise((r) => setTimeout(r, 2000)); // 2s pause between batches — paid tier handles 2000 RPM, free tier retries via Promise.allSettled
|
||||
}
|
||||
progress(
|
||||
"design",
|
||||
`Captioned ${Math.min(i + BATCH_SIZE, imageFiles.length)}/${imageFiles.length} images...`,
|
||||
);
|
||||
}
|
||||
progress("design", `${Object.keys(geminiCaptions).length} images captioned with Gemini`);
|
||||
} catch (err) {
|
||||
warnings.push(`Gemini captioning failed: ${err}`);
|
||||
}
|
||||
|
||||
return geminiCaptions;
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate asset-descriptions.md — one-line descriptions for each downloaded asset.
|
||||
*
|
||||
* Returns the description lines (without the markdown header).
|
||||
*/
|
||||
export function generateAssetDescriptions(
|
||||
outputDir: string,
|
||||
tokens: DesignTokens,
|
||||
catalogedAssets: CatalogedAsset[],
|
||||
geminiCaptions: Record<string, string>,
|
||||
): string[] {
|
||||
// Sort: Gemini-captioned images first (richest descriptions), then uncaptioned, then SVGs, then fonts
|
||||
const captionedLines: string[] = [];
|
||||
const uncaptionedLines: string[] = [];
|
||||
const svgLines: string[] = [];
|
||||
const fontLines: string[] = [];
|
||||
|
||||
// Describe downloaded images
|
||||
const assetsPath = join(outputDir, "assets");
|
||||
try {
|
||||
for (const file of readdirSync(assetsPath)) {
|
||||
if (file === "svgs" || file === "fonts" || file === "lottie" || file === "videos") continue;
|
||||
const filePath = join(assetsPath, file);
|
||||
const stat = statSync(filePath);
|
||||
if (!stat.isFile()) continue;
|
||||
const sizeKb = Math.round(stat.size / 1024);
|
||||
const catalogMatch = catalogedAssets.find(
|
||||
(a) => a.url && file.includes(a.url.split("/").pop()?.split("?")[0]?.slice(0, 20) || "___"),
|
||||
);
|
||||
const desc = catalogMatch?.description || catalogMatch?.notes || "";
|
||||
const heading = catalogMatch?.nearestHeading || "";
|
||||
const section = catalogMatch?.sectionClasses || "";
|
||||
const aboveFold = catalogMatch?.aboveFold ? "above fold" : "";
|
||||
const geminiCaption = geminiCaptions[file];
|
||||
const cleanName = file.replace(/\.[^.]+$/, "").replace(/[-_]/g, " ");
|
||||
const parts = [`${file} — ${sizeKb}KB`];
|
||||
if (geminiCaption) {
|
||||
parts.push(geminiCaption);
|
||||
captionedLines.push(parts.join(", "));
|
||||
} else {
|
||||
if (desc) parts.push(`"${desc.slice(0, 80)}"`);
|
||||
if (heading) parts.push(`section: "${heading.slice(0, 60)}"`);
|
||||
else if (section) parts.push(`in: ${section.split(" ").slice(0, 3).join(" ")}`);
|
||||
if (aboveFold) parts.push(aboveFold);
|
||||
if (!desc && !heading) parts.push(cleanName);
|
||||
uncaptionedLines.push(parts.join(", "));
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
/* no assets dir */
|
||||
}
|
||||
|
||||
// Describe SVGs
|
||||
try {
|
||||
const svgsPath = join(assetsPath, "svgs");
|
||||
for (const file of readdirSync(svgsPath)) {
|
||||
if (!file.endsWith(".svg")) continue;
|
||||
const svgMatch = tokens.svgs.find(
|
||||
(s) =>
|
||||
s.label &&
|
||||
file.includes(
|
||||
s.label
|
||||
.toLowerCase()
|
||||
.replace(/[^a-z0-9]/g, "-")
|
||||
.slice(0, 15),
|
||||
),
|
||||
);
|
||||
const label = svgMatch?.label || file.replace(".svg", "").replace(/-/g, " ");
|
||||
const isLogo = svgMatch?.isLogo || file.includes("logo");
|
||||
svgLines.push(`svgs/${file} — ${isLogo ? "logo: " : "icon: "}${label}`);
|
||||
}
|
||||
} catch {
|
||||
/* no svgs dir */
|
||||
}
|
||||
|
||||
// Describe fonts
|
||||
try {
|
||||
const fontsPath = join(assetsPath, "fonts");
|
||||
for (const file of readdirSync(fontsPath)) {
|
||||
fontLines.push(`fonts/${file} — font file`);
|
||||
}
|
||||
} catch {
|
||||
/* no fonts dir */
|
||||
}
|
||||
|
||||
return [...captionedLines, ...uncaptionedLines, ...svgLines, ...fontLines];
|
||||
}
|
||||
242
packages/cli/src/capture/htmlExtractor.ts
Normal file
242
packages/cli/src/capture/htmlExtractor.ts
Normal file
@ -0,0 +1,242 @@
|
||||
/**
|
||||
* Extract full-page HTML from a website using Puppeteer CDP.
|
||||
*
|
||||
* All page.evaluate() calls use string expressions to avoid
|
||||
* tsx/esbuild __name injection (see esbuild issue #1031).
|
||||
*/
|
||||
|
||||
import type { Page } from "puppeteer-core";
|
||||
import type { ExtractedHtml } from "./types.js";
|
||||
import { isPrivateUrl } from "./assetDownloader.js";
|
||||
|
||||
const DEFAULT_SETTLE_TIME = 3000;
|
||||
|
||||
export async function extractHtml(
|
||||
page: Page,
|
||||
opts: { settleTime?: number } = {},
|
||||
): Promise<ExtractedHtml> {
|
||||
const settleTime = opts.settleTime ?? DEFAULT_SETTLE_TIME;
|
||||
|
||||
// Step 1: Trigger lazy loading by scrolling through the page
|
||||
await page.evaluate(`(async () => {
|
||||
var pageHeight = document.body.scrollHeight;
|
||||
var viewportH = window.innerHeight;
|
||||
var step = Math.floor(viewportH * 0.7);
|
||||
for (var y = 0; y < pageHeight + viewportH; y += step) {
|
||||
window.scrollTo(0, y);
|
||||
await new Promise(function(r) { setTimeout(r, 200); });
|
||||
}
|
||||
window.scrollTo(0, pageHeight);
|
||||
await new Promise(function(r) { setTimeout(r, 300); });
|
||||
window.scrollTo(0, 0);
|
||||
await new Promise(function(r) { setTimeout(r, 300); });
|
||||
})()`);
|
||||
|
||||
// Re-measure after lazy load
|
||||
await new Promise((r) => setTimeout(r, settleTime));
|
||||
|
||||
// Step 2: Inline external stylesheets
|
||||
// Fetch CSS from Node.js (bypasses CORS) then inject into page
|
||||
const stylesheetUrls = (await page.evaluate(`(() => {
|
||||
return Array.from(document.querySelectorAll('link[rel="stylesheet"][href]')).map(function(l) { return l.href; });
|
||||
})()`)) as string[];
|
||||
|
||||
for (const href of stylesheetUrls) {
|
||||
try {
|
||||
if (isPrivateUrl(href)) continue;
|
||||
const res = await fetch(href, {
|
||||
signal: AbortSignal.timeout(10000),
|
||||
headers: { "User-Agent": "Mozilla/5.0" },
|
||||
});
|
||||
if (!res.ok) continue;
|
||||
let css = await res.text();
|
||||
// Fix relative url() references
|
||||
css = css.replace(/url\(\s*['"]?([^'")\s]+)['"]?\s*\)/g, (match: string, url: string) => {
|
||||
if (url.startsWith("data:") || url.startsWith("http") || url.startsWith("//")) return match;
|
||||
try {
|
||||
return `url('${new URL(url, href).href}')`;
|
||||
} catch {
|
||||
return match;
|
||||
}
|
||||
});
|
||||
// Add the CSS as a <style> tag in <head> via Puppeteer's addStyleTag
|
||||
await page.addStyleTag({ content: css });
|
||||
// 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 */
|
||||
}
|
||||
}
|
||||
|
||||
// Step 3: Make URLs absolute and fix HTML entity encoding in src attributes
|
||||
await page.evaluate(`(() => {
|
||||
document.querySelectorAll("img[src]").forEach(function(el) {
|
||||
try {
|
||||
// getAttribute returns the raw HTML attribute (with &)
|
||||
// .src returns the resolved URL (with &) — use .src for the correct value
|
||||
var resolved = el.src;
|
||||
if (resolved) el.setAttribute("src", resolved);
|
||||
} catch(e) {}
|
||||
});
|
||||
// Fix srcset attributes too (Next.js image optimization)
|
||||
document.querySelectorAll("img[srcset]").forEach(function(el) {
|
||||
try {
|
||||
var srcset = el.getAttribute("srcset") || "";
|
||||
// Decode & entities in srcset
|
||||
srcset = srcset.replace(/&/g, "&");
|
||||
el.setAttribute("srcset", srcset);
|
||||
} catch(e) {}
|
||||
});
|
||||
document.querySelectorAll('[style*="url("]').forEach(function(el) {
|
||||
el.style.cssText = el.style.cssText.replace(/url\\(['"]?([^'"\\)\\s]+)['"]?\\)/g, function(_, url) {
|
||||
try { return "url('" + new URL(url, location.href).href + "')"; } catch(e) { return "url('" + url + "')"; }
|
||||
});
|
||||
});
|
||||
})()`);
|
||||
|
||||
// Step 3b: Convert cross-origin images to data URLs
|
||||
// Some CDNs (Contentful, etc.) block direct access but images are already
|
||||
// loaded in the browser. We convert loaded images to data URLs via canvas.
|
||||
await page.evaluate(`(async () => {
|
||||
var imgs = Array.from(document.querySelectorAll("img"));
|
||||
for (var i = 0; i < imgs.length; i++) {
|
||||
var img = imgs[i];
|
||||
try {
|
||||
if (!img.src || img.src.startsWith("data:")) continue;
|
||||
if (img.naturalWidth < 10 || img.naturalHeight < 10) continue;
|
||||
// Only convert cross-origin images (same-origin ones will load fine)
|
||||
var imgUrl = new URL(img.src);
|
||||
if (imgUrl.origin === location.origin) continue;
|
||||
// Try to draw to canvas — will fail if CORS blocks it
|
||||
var canvas = document.createElement("canvas");
|
||||
canvas.width = img.naturalWidth;
|
||||
canvas.height = img.naturalHeight;
|
||||
var ctx = canvas.getContext("2d");
|
||||
ctx.drawImage(img, 0, 0);
|
||||
var dataUrl = canvas.toDataURL("image/png");
|
||||
if (dataUrl.length > 100) {
|
||||
img.setAttribute("src", dataUrl);
|
||||
img.removeAttribute("srcset");
|
||||
}
|
||||
} catch(e) {
|
||||
// Canvas CORS failed — try fetch + blob as fallback
|
||||
try {
|
||||
var resp = await fetch(img.src, { mode: "cors" });
|
||||
if (resp.ok) {
|
||||
var blob = await resp.blob();
|
||||
var reader = new FileReader();
|
||||
var dataUrl2 = await new Promise(function(resolve) {
|
||||
reader.onloadend = function() { resolve(reader.result); };
|
||||
reader.readAsDataURL(blob);
|
||||
});
|
||||
if (dataUrl2 && typeof dataUrl2 === "string" && dataUrl2.length > 100) {
|
||||
img.setAttribute("src", dataUrl2);
|
||||
img.removeAttribute("srcset");
|
||||
}
|
||||
}
|
||||
} catch(e2) {
|
||||
// Both methods failed — image stays as original URL
|
||||
}
|
||||
}
|
||||
}
|
||||
})()`);
|
||||
|
||||
// Step 4: Extract everything
|
||||
const result = (await page.evaluate(`(() => {
|
||||
// Capture styles AND scripts from head separately then combine
|
||||
// Scripts include Three.js, animation libraries that we want to preserve
|
||||
var styles = Array.from(document.head.querySelectorAll("style")).map(function(s) { return s.outerHTML; }).join("\\n");
|
||||
var scripts = Array.from(document.head.querySelectorAll("script")).map(function(s) { return s.outerHTML; }).join("\\n");
|
||||
var headHtml = styles + "\\n" + scripts;
|
||||
var bodyHtml = document.body.innerHTML;
|
||||
|
||||
var cssomRules = [];
|
||||
for (var i = 0; i < document.styleSheets.length; i++) {
|
||||
var sheet = document.styleSheets[i];
|
||||
try {
|
||||
var ownerNode = sheet.ownerNode;
|
||||
if (ownerNode && ownerNode.textContent && ownerNode.textContent.trim()) continue;
|
||||
if (sheet.href) continue;
|
||||
for (var j = 0; j < sheet.cssRules.length; j++) {
|
||||
cssomRules.push(sheet.cssRules[j].cssText);
|
||||
}
|
||||
} catch(e) {}
|
||||
}
|
||||
|
||||
var htmlEl = document.documentElement;
|
||||
var attrParts = [];
|
||||
for (var i = 0; i < htmlEl.attributes.length; i++) {
|
||||
var attr = htmlEl.attributes[i];
|
||||
if (attr.name === "lang" || attr.name === "class" || attr.name === "style" || attr.name === "dir" || attr.name.startsWith("data-")) {
|
||||
attrParts.push(attr.name + '="' + attr.value.replace(/"/g, """) + '"');
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
headHtml: headHtml,
|
||||
bodyHtml: bodyHtml,
|
||||
cssomRules: cssomRules.join("\\n"),
|
||||
htmlAttrs: attrParts.join(" "),
|
||||
viewportWidth: Math.max(window.innerWidth, document.documentElement.scrollWidth),
|
||||
viewportHeight: window.innerHeight,
|
||||
fullPageHeight: document.body.scrollHeight
|
||||
};
|
||||
})()`)) as ExtractedHtml;
|
||||
|
||||
// Post-process in Node.js (more reliable than browser-side fixing):
|
||||
// 1. Decode & in image src/srcset attributes
|
||||
// 2. Make relative image URLs absolute using the page's origin
|
||||
const pageOrigin = new URL(page.url()).origin;
|
||||
|
||||
result.bodyHtml = result.bodyHtml.replace(
|
||||
/(<img\b[^>]*\bsrc=")([^"]*?)(")/g,
|
||||
(_match: string, pre: string, url: string, post: string) => {
|
||||
let fixed = url.replace(/&/g, "&");
|
||||
// Make relative URLs absolute
|
||||
if (fixed.startsWith("/") && !fixed.startsWith("//")) {
|
||||
fixed = pageOrigin + fixed;
|
||||
}
|
||||
return pre + fixed + post;
|
||||
},
|
||||
);
|
||||
result.bodyHtml = result.bodyHtml.replace(
|
||||
/(<img\b[^>]*\bsrcset=")([^"]*?)(")/g,
|
||||
(_match: string, pre: string, urls: string, post: string) => {
|
||||
const fixed = urls
|
||||
.replace(/&/g, "&")
|
||||
.replace(
|
||||
/(^|,\s*)(\/[^\s,]+)/g,
|
||||
(_m: string, sep: string, path: string) => sep + pageOrigin + path,
|
||||
);
|
||||
return pre + fixed + post;
|
||||
},
|
||||
);
|
||||
|
||||
// Also fix video src/poster URLs
|
||||
result.bodyHtml = result.bodyHtml.replace(
|
||||
/(<video\b[^>]*\bsrc=")([^"]*?)(")/g,
|
||||
(_match: string, pre: string, url: string, post: string) => {
|
||||
let fixed = url.replace(/&/g, "&");
|
||||
if (fixed.startsWith("/") && !fixed.startsWith("//")) fixed = pageOrigin + fixed;
|
||||
return pre + fixed + post;
|
||||
},
|
||||
);
|
||||
result.bodyHtml = result.bodyHtml.replace(
|
||||
/(<video\b[^>]*\bposter=")([^"]*?)(")/g,
|
||||
(_match: string, pre: string, url: string, post: string) => {
|
||||
let fixed = url.replace(/&/g, "&");
|
||||
if (fixed.startsWith("/") && !fixed.startsWith("//")) fixed = pageOrigin + fixed;
|
||||
return pre + fixed + post;
|
||||
},
|
||||
);
|
||||
|
||||
return result;
|
||||
}
|
||||
525
packages/cli/src/capture/index.ts
Normal file
525
packages/cli/src/capture/index.ts
Normal file
@ -0,0 +1,525 @@
|
||||
/**
|
||||
* Website capture orchestrator.
|
||||
*
|
||||
* Two-pass capture approach:
|
||||
* Pass 1: Full page load (all JS) → catalog animations + snapshot canvases
|
||||
* Pass 2: Framework scripts blocked → extract stable HTML/CSS
|
||||
*
|
||||
* This ensures we get both:
|
||||
* - Rich animation metadata for Claude Code to recreate
|
||||
* - Stable, renderable HTML that won't crash in Puppeteer
|
||||
*/
|
||||
|
||||
import { mkdirSync, writeFileSync, existsSync } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
import { extractHtml } from "./htmlExtractor.js";
|
||||
// captureScreenshots removed — full-page screenshot replaces per-section shots
|
||||
import { extractTokens } from "./tokenExtractor.js";
|
||||
import { downloadAssets, downloadAndRewriteFonts } from "./assetDownloader.js";
|
||||
// briefGenerator.ts, visual-style, capture-summary removed — DESIGN.md replaces them
|
||||
import {
|
||||
setupAnimationCapture,
|
||||
startCdpAnimationCapture,
|
||||
collectAnimationCatalog,
|
||||
} from "./animationCataloger.js";
|
||||
import {
|
||||
saveLottieAnimations,
|
||||
renderLottiePreviews,
|
||||
captureVideoManifest,
|
||||
} from "./mediaCapture.js";
|
||||
import type { DiscoveredLottie } from "./mediaCapture.js";
|
||||
import {
|
||||
detectLibraries,
|
||||
extractVisibleText,
|
||||
captionImagesWithGemini,
|
||||
generateAssetDescriptions,
|
||||
} from "./contentExtractor.js";
|
||||
import { loadEnvFile, generateProjectScaffold } from "./scaffolding.js";
|
||||
import type { CaptureOptions, CaptureResult } from "./types.js";
|
||||
|
||||
export type { CaptureOptions, CaptureResult } from "./types.js";
|
||||
|
||||
export async function captureWebsite(
|
||||
opts: CaptureOptions,
|
||||
onProgress?: (stage: string, detail?: string) => void,
|
||||
): Promise<CaptureResult> {
|
||||
const {
|
||||
url,
|
||||
outputDir,
|
||||
viewportWidth = 1920,
|
||||
viewportHeight = 1080,
|
||||
timeout = 120000,
|
||||
settleTime = 3000,
|
||||
maxScreenshots: _maxScreenshots = 24,
|
||||
skipAssets = false,
|
||||
} = opts;
|
||||
|
||||
const warnings: string[] = [];
|
||||
const progress = (stage: string, detail?: string) => {
|
||||
onProgress?.(stage, detail);
|
||||
};
|
||||
|
||||
// Load .env file from repo root if it exists (for GEMINI_API_KEY, etc.)
|
||||
loadEnvFile(outputDir);
|
||||
|
||||
// Create output directories
|
||||
mkdirSync(join(outputDir, "extracted"), { recursive: true });
|
||||
mkdirSync(join(outputDir, "screenshots"), { recursive: true });
|
||||
mkdirSync(join(outputDir, "assets"), { recursive: true });
|
||||
|
||||
// Launch browser
|
||||
progress("browser", "Launching headless Chrome...");
|
||||
const { ensureBrowser } = await import("../browser/manager.js");
|
||||
const browser = await ensureBrowser();
|
||||
const puppeteer = await import("puppeteer-core");
|
||||
const chromeBrowser = await puppeteer.default.launch({
|
||||
headless: true,
|
||||
executablePath: browser.executablePath,
|
||||
args: [
|
||||
"--no-sandbox",
|
||||
"--disable-dev-shm-usage",
|
||||
"--enable-webgl",
|
||||
"--ignore-gpu-blocklist",
|
||||
"--use-gl=angle",
|
||||
"--use-angle=swiftshader",
|
||||
"--disable-blink-features=AutomationControlled",
|
||||
"--disable-background-timer-throttling",
|
||||
"--disable-renderer-backgrounding",
|
||||
`--window-size=${viewportWidth},${viewportHeight}`,
|
||||
],
|
||||
});
|
||||
|
||||
let animationCatalog: CaptureResult["animationCatalog"];
|
||||
|
||||
try {
|
||||
// ═══════════════════════════════════════════════════════════════
|
||||
// PASS 1: Full page load — all JS runs
|
||||
// Goal: Catalog animations + take screenshots (with JS rendering)
|
||||
// ═══════════════════════════════════════════════════════════════
|
||||
|
||||
progress("animations", "Cataloging animations (full JS)...");
|
||||
|
||||
const page1 = await chromeBrowser.newPage();
|
||||
await page1.setViewport({ width: viewportWidth, height: viewportHeight });
|
||||
await page1.setUserAgent(
|
||||
"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",
|
||||
);
|
||||
|
||||
// Set up hooks BEFORE navigation
|
||||
await setupAnimationCapture(page1);
|
||||
const { cdp, animations: cdpAnims } = await startCdpAnimationCapture(page1);
|
||||
|
||||
// Hook WebGL to capture shader source code (GLSL)
|
||||
// Captured shaders inform Claude Code about the site's visual effects
|
||||
// and enable reliable library detection (Three.js/PixiJS/Babylon.js uniforms survive bundling)
|
||||
await page1.evaluateOnNewDocument(`
|
||||
var origGetContext = HTMLCanvasElement.prototype.getContext;
|
||||
window.__capturedShaders = [];
|
||||
HTMLCanvasElement.prototype.getContext = function(type, attrs) {
|
||||
var ctx = origGetContext.call(this, type, attrs);
|
||||
if (ctx && (type === 'webgl' || type === 'webgl2' || type === 'experimental-webgl')) {
|
||||
if (ctx.shaderSource && !ctx.__hfHooked) {
|
||||
var origShaderSource = ctx.shaderSource.bind(ctx);
|
||||
ctx.shaderSource = function(shader, source) {
|
||||
try {
|
||||
var shaderType = ctx.getShaderParameter(shader, ctx.SHADER_TYPE);
|
||||
window.__capturedShaders.push({
|
||||
type: shaderType === ctx.VERTEX_SHADER ? 'vertex' : 'fragment',
|
||||
source: source.slice(0, 5000)
|
||||
});
|
||||
} catch(e) {}
|
||||
return origShaderSource(shader, source);
|
||||
};
|
||||
ctx.__hfHooked = true;
|
||||
}
|
||||
}
|
||||
return ctx;
|
||||
};
|
||||
`);
|
||||
|
||||
// Intercept network responses to detect Lottie JSON files
|
||||
const discoveredLotties: DiscoveredLottie[] = [];
|
||||
page1.on("response", async (response) => {
|
||||
try {
|
||||
const responseUrl = response.url();
|
||||
const contentType = response.headers()["content-type"] || "";
|
||||
const isJsonUrl = responseUrl.endsWith(".json");
|
||||
const isLottieUrl = responseUrl.endsWith(".lottie");
|
||||
const isJson =
|
||||
contentType.includes("application/json") || contentType.includes("text/plain");
|
||||
|
||||
if (isLottieUrl) {
|
||||
discoveredLotties.push({ url: responseUrl });
|
||||
return;
|
||||
}
|
||||
|
||||
if (isJsonUrl || isJson) {
|
||||
// Check Content-Length before downloading to avoid OOM on huge responses
|
||||
const cl = parseInt(response.headers()["content-length"] || "0", 10);
|
||||
if (cl > 5_000_000) return;
|
||||
const buffer = await response.buffer();
|
||||
if (buffer.length < 100 || buffer.length > 5_000_000) return; // Skip tiny or huge
|
||||
const text = buffer.toString("utf-8");
|
||||
const json = JSON.parse(text);
|
||||
// Validate Lottie structure: must have version, in/out points, layers, dimensions, framerate
|
||||
if (
|
||||
json &&
|
||||
typeof json === "object" &&
|
||||
["v", "ip", "op", "layers", "w", "h", "fr"].every((k: string) => k in json)
|
||||
) {
|
||||
discoveredLotties.push({
|
||||
url: responseUrl,
|
||||
data: json,
|
||||
dimensions: { w: json.w, h: json.h },
|
||||
frameRate: json.fr,
|
||||
});
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
/* not JSON or parse error — skip */
|
||||
}
|
||||
});
|
||||
|
||||
// Use networkidle2 (allows 2 ongoing connections) instead of networkidle0 —
|
||||
// modern SPAs often have persistent WebSocket/analytics connections that
|
||||
// prevent networkidle0 from ever resolving.
|
||||
await page1.goto(url, { waitUntil: "networkidle2", timeout });
|
||||
await new Promise((r) => setTimeout(r, settleTime));
|
||||
|
||||
// Check if the page loaded real content or an anti-bot challenge
|
||||
// Use structural detection (DOM elements + cookies), not text regex matching —
|
||||
// text matching causes false positives on sites that mention "blocked" or "verify" in copy
|
||||
const pageContentCheck = (await page1.evaluate(`(() => {
|
||||
var text = (document.body.innerText || "").trim();
|
||||
var title = document.title || "";
|
||||
// Structural: Cloudflare Turnstile widget or challenge iframe
|
||||
var hasCfTurnstile = !!document.querySelector('.cf-turnstile, [data-sitekey], iframe[src*="challenges.cloudflare.com"], #challenge-running, #challenge-form');
|
||||
// Structural: page is almost empty (challenge pages have minimal DOM)
|
||||
var bodyChildCount = document.body.children.length;
|
||||
var isMinimalDom = bodyChildCount <= 5 && text.length < 500;
|
||||
// Title-based: only check title on near-empty pages
|
||||
var hasChallengeTitle = isMinimalDom && /just a moment|attention required|access denied/i.test(title);
|
||||
var isChallenged = hasCfTurnstile || hasChallengeTitle;
|
||||
return { textLength: text.length, title: title, isChallenged: isChallenged, bodyChildCount: bodyChildCount };
|
||||
})()`)) as { textLength: number; title: string; isChallenged: boolean; bodyChildCount: number };
|
||||
|
||||
if (pageContentCheck.isChallenged || pageContentCheck.textLength < 100) {
|
||||
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);
|
||||
}
|
||||
|
||||
// Scroll through page to trigger lazy-loaded images and Lottie animations
|
||||
// Framer and other modern sites use IntersectionObserver — images only load
|
||||
// when scrolled into view. We scroll the full page, then wait for all images
|
||||
// to finish loading before proceeding.
|
||||
await page1.evaluate(`(async () => {
|
||||
var h = document.body.scrollHeight;
|
||||
for (var y = 0; y < h; y += window.innerHeight * 0.7) {
|
||||
window.scrollTo(0, y);
|
||||
await new Promise(function(r) { setTimeout(r, 400); });
|
||||
}
|
||||
// Scroll to very bottom to catch footer lazy-loads
|
||||
window.scrollTo(0, document.body.scrollHeight);
|
||||
await new Promise(function(r) { setTimeout(r, 800); });
|
||||
// Wait for all images to finish loading
|
||||
var imgs = Array.from(document.querySelectorAll('img'));
|
||||
var pending = imgs.filter(function(img) { return !img.complete; });
|
||||
if (pending.length > 0) {
|
||||
await Promise.race([
|
||||
Promise.all(pending.map(function(img) {
|
||||
return new Promise(function(r) { img.onload = r; img.onerror = r; });
|
||||
})),
|
||||
new Promise(function(r) { setTimeout(r, 5000); })
|
||||
]);
|
||||
}
|
||||
window.scrollTo(0, 0);
|
||||
await new Promise(function(r) { setTimeout(r, 500); });
|
||||
})()`);
|
||||
|
||||
await page1.evaluate(`window.scrollTo(0, 0)`);
|
||||
await new Promise((r) => setTimeout(r, 300));
|
||||
|
||||
// Save discovered Lottie animations
|
||||
// Also scan DOM for Lottie web components not caught by network interception
|
||||
try {
|
||||
const domLotties = await page1.evaluate(`(() => {
|
||||
var urls = [];
|
||||
document.querySelectorAll('dotlottie-wc, lottie-player, dotlottie-player').forEach(function(el) {
|
||||
var src = el.getAttribute('src');
|
||||
if (src) urls.push(src);
|
||||
});
|
||||
// Also check lottie-web registered animations
|
||||
if (window.lottie && window.lottie.getRegisteredAnimations) {
|
||||
window.lottie.getRegisteredAnimations().forEach(function(anim) {
|
||||
if (anim.path) urls.push(anim.path);
|
||||
});
|
||||
}
|
||||
return urls;
|
||||
})()`);
|
||||
if (Array.isArray(domLotties)) {
|
||||
for (const lottieUrl of domLotties) {
|
||||
if (
|
||||
typeof lottieUrl === "string" &&
|
||||
!discoveredLotties.some((l) => l.url === lottieUrl)
|
||||
) {
|
||||
discoveredLotties.push({ url: lottieUrl });
|
||||
}
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
/* DOM scan failed — non-critical */
|
||||
}
|
||||
|
||||
if (discoveredLotties.length > 0) {
|
||||
const lottieDir = join(outputDir, "assets", "lottie");
|
||||
mkdirSync(lottieDir, { recursive: true });
|
||||
const savedCount = await saveLottieAnimations(discoveredLotties, lottieDir);
|
||||
// Generate manifest + preview thumbnails so the agent can SEE what each animation is
|
||||
if (savedCount > 0) {
|
||||
await renderLottiePreviews(chromeBrowser, lottieDir, outputDir);
|
||||
progress("lottie", `${savedCount} Lottie animation(s) saved`);
|
||||
}
|
||||
}
|
||||
|
||||
// Save captured WebGL shaders (useful context for shader transitions + library detection)
|
||||
let capturedShaders: Array<{ type: string; source: string }> | undefined;
|
||||
try {
|
||||
const shaders = await page1.evaluate(`window.__capturedShaders || []`);
|
||||
if (Array.isArray(shaders) && shaders.length > 0) {
|
||||
const seen = new Set<string>();
|
||||
const unique = (shaders as Array<{ type: string; source: string }>).filter((s) => {
|
||||
if (seen.has(s.source)) return false;
|
||||
seen.add(s.source);
|
||||
return true;
|
||||
});
|
||||
capturedShaders = unique;
|
||||
writeFileSync(
|
||||
join(outputDir, "extracted", "shaders.json"),
|
||||
JSON.stringify(unique, null, 2),
|
||||
"utf-8",
|
||||
);
|
||||
progress("shaders", `${unique.length} WebGL shader(s) captured`);
|
||||
}
|
||||
} catch {
|
||||
/* shader extraction failed — non-critical */
|
||||
}
|
||||
|
||||
// ── READ-ONLY phase: extract data from the live DOM before any mutations ──
|
||||
// extractHtml (below) converts image src to data URLs and removes scripts —
|
||||
// all read-only operations must run BEFORE it to see the original DOM.
|
||||
|
||||
// Extract design tokens
|
||||
progress("tokens", "Extracting design tokens...");
|
||||
const tokens = await extractTokens(page1);
|
||||
writeFileSync(
|
||||
join(outputDir, "extracted", "tokens.json"),
|
||||
JSON.stringify(tokens, null, 2),
|
||||
"utf-8",
|
||||
);
|
||||
|
||||
// Collect animation catalog
|
||||
progress("animations", "Cataloging animations...");
|
||||
animationCatalog = await collectAnimationCatalog(page1, cdpAnims, cdp);
|
||||
|
||||
// Capture scroll-position viewport screenshots
|
||||
progress("screenshots", "Capturing scroll screenshots...");
|
||||
const { captureScrollScreenshots } = await import("./screenshotCapture.js");
|
||||
const screenshots = await captureScrollScreenshots(page1, outputDir);
|
||||
progress("screenshots", `${screenshots.length} scroll screenshots captured`);
|
||||
|
||||
// Catalog all assets (must run before extractHtml which converts img src to data URLs)
|
||||
progress("design", "Cataloging assets...");
|
||||
let catalogedAssets: import("./assetCataloger.js").CatalogedAsset[] = [];
|
||||
try {
|
||||
const { catalogAssets } = await import("./assetCataloger.js");
|
||||
catalogedAssets = await catalogAssets(page1);
|
||||
progress("design", `${catalogedAssets.length} assets cataloged`);
|
||||
} catch (err) {
|
||||
warnings.push(`Asset cataloging failed: ${err}`);
|
||||
}
|
||||
|
||||
// ── MUTATION phase: extractHtml modifies the live DOM (converts images to data URLs) ──
|
||||
progress("extract", "Extracting HTML & CSS...");
|
||||
const extracted = await extractHtml(page1, { settleTime: 1000 });
|
||||
|
||||
// Strip framework scripts from the extracted body — keep visual library scripts
|
||||
// IMPORTANT: Use non-greedy matching within individual script tags only
|
||||
extracted.bodyHtml = extracted.bodyHtml
|
||||
// Remove __NEXT_DATA__ (has its own ID so safe to target)
|
||||
.replace(/<script\s+id="__NEXT_DATA__"[^>]*>[\s\S]*?<\/script>/gi, "")
|
||||
// Remove React hydration markers
|
||||
.replace(/\s*data-reactroot="[^"]*"/g, "")
|
||||
.replace(/\s*data-reactroot/g, "");
|
||||
|
||||
// Remove Next.js bootstrap scripts individually (match each script tag separately)
|
||||
extracted.bodyHtml = extracted.bodyHtml.replace(
|
||||
/<script\b[^>]*>([\s\S]*?)<\/script>/gi,
|
||||
(match: string, content: string) => {
|
||||
// Only remove if this specific script contains Next.js bootstrap code
|
||||
if (
|
||||
content.includes("__next_f") ||
|
||||
content.includes("self.__next_f") ||
|
||||
content.includes("__NEXT_LOADED_PAGES__") ||
|
||||
content.includes("_N_E") ||
|
||||
content.includes("__NEXT_P")
|
||||
) {
|
||||
return "";
|
||||
}
|
||||
return match;
|
||||
},
|
||||
);
|
||||
|
||||
// Strip framework script tags from head (keep styles + visual library scripts)
|
||||
const FRAMEWORK_SRC_PATTERNS = [
|
||||
/_next\/static\/chunks\/(main|framework|webpack|pages\/)/,
|
||||
/_next\/static\/chunks\/app\//,
|
||||
/_buildManifest\.js/,
|
||||
/_ssgManifest\.js/,
|
||||
];
|
||||
extracted.headHtml = extracted.headHtml.replace(
|
||||
/<script[^>]*src="([^"]*)"[^>]*><\/script>/gi,
|
||||
(match: string, src: string) => {
|
||||
if (FRAMEWORK_SRC_PATTERNS.some((p) => p.test(src))) return "";
|
||||
return match;
|
||||
},
|
||||
);
|
||||
|
||||
// Generate video manifest — screenshot each <video> element + extract surrounding context
|
||||
// so Claude Code can SEE what each video shows and WHERE it was used on the page.
|
||||
try {
|
||||
await captureVideoManifest(page1, outputDir, progress);
|
||||
} catch {
|
||||
/* non-blocking — video manifest is best-effort */
|
||||
}
|
||||
|
||||
// Detect JS libraries via globals, DOM fingerprints, script URLs, and shaders
|
||||
const detectedLibraries = await detectLibraries(page1, capturedShaders);
|
||||
|
||||
// Extract all visible text in DOM order
|
||||
const visibleTextContent = await extractVisibleText(page1);
|
||||
|
||||
await page1.close();
|
||||
|
||||
// Download fonts and rewrite URLs to local paths
|
||||
extracted.headHtml = await downloadAndRewriteFonts(extracted.headHtml, outputDir);
|
||||
|
||||
// Save animation catalog — lean version for the agent (not 745 raw CSS declarations)
|
||||
if (animationCatalog) {
|
||||
// Extract just what's useful: counts, named animations, a few representative keyframed entries
|
||||
const uniqueAnimNames = new Set<string>();
|
||||
for (const d of animationCatalog.cssDeclarations || []) {
|
||||
if (d.animation?.name) uniqueAnimNames.add(d.animation.name);
|
||||
}
|
||||
|
||||
// Keep up to 10 Web Animations that have actual keyframe data (most useful for recreation)
|
||||
const representativeAnims = (animationCatalog.webAnimations || [])
|
||||
.filter((a) => a.keyframes && a.keyframes.length > 0)
|
||||
.slice(0, 10);
|
||||
|
||||
const leanCatalog = {
|
||||
summary: animationCatalog.summary,
|
||||
namedAnimations: Array.from(uniqueAnimNames),
|
||||
scrollTriggeredElements: (animationCatalog.scrollTargets || []).length,
|
||||
representativeAnimations: representativeAnims,
|
||||
};
|
||||
|
||||
writeFileSync(
|
||||
join(outputDir, "extracted", "animations.json"),
|
||||
JSON.stringify(leanCatalog, null, 2),
|
||||
"utf-8",
|
||||
);
|
||||
}
|
||||
|
||||
// Download assets — single pass using the catalog for best image quality
|
||||
let assets: CaptureResult["assets"] = [];
|
||||
if (!skipAssets) {
|
||||
progress("assets", "Downloading assets...");
|
||||
assets = await downloadAssets(tokens, outputDir, catalogedAssets);
|
||||
}
|
||||
|
||||
// Save visible text content for AI agent to use
|
||||
if (visibleTextContent) {
|
||||
writeFileSync(join(outputDir, "extracted", "visible-text.txt"), visibleTextContent, "utf-8");
|
||||
}
|
||||
|
||||
// Save cataloged assets as JSON for AI agent
|
||||
if (catalogedAssets.length > 0) {
|
||||
writeFileSync(
|
||||
join(outputDir, "extracted", "assets-catalog.json"),
|
||||
JSON.stringify(catalogedAssets, null, 2),
|
||||
"utf-8",
|
||||
);
|
||||
}
|
||||
|
||||
// Save detected libraries
|
||||
if (detectedLibraries.length > 0) {
|
||||
writeFileSync(
|
||||
join(outputDir, "extracted", "detected-libraries.json"),
|
||||
JSON.stringify(detectedLibraries, null, 2),
|
||||
"utf-8",
|
||||
);
|
||||
}
|
||||
|
||||
// AI-powered image captioning via Gemini (optional — enriches asset descriptions)
|
||||
const geminiCaptions = await captionImagesWithGemini(outputDir, progress, warnings);
|
||||
|
||||
// Generate asset descriptions for the AI agent
|
||||
progress("design", "Generating asset descriptions...");
|
||||
try {
|
||||
const lines = generateAssetDescriptions(outputDir, tokens, catalogedAssets, geminiCaptions);
|
||||
|
||||
if (lines.length > 0) {
|
||||
writeFileSync(
|
||||
join(outputDir, "extracted", "asset-descriptions.md"),
|
||||
"# Asset Descriptions\n\nOne line per file. Read this instead of opening every image individually.\n\n" +
|
||||
lines.map((l) => "- " + l).join("\n") +
|
||||
"\n",
|
||||
"utf-8",
|
||||
);
|
||||
progress("design", `${lines.length} asset descriptions written`);
|
||||
}
|
||||
} catch {
|
||||
/* non-critical */
|
||||
}
|
||||
|
||||
progress("design", "DESIGN.md will be created by your AI agent");
|
||||
|
||||
// Generate project scaffold (index.html, meta.json, CLAUDE.md)
|
||||
await generateProjectScaffold(
|
||||
outputDir,
|
||||
url,
|
||||
tokens,
|
||||
animationCatalog,
|
||||
screenshots.length > 0,
|
||||
discoveredLotties.length > 0,
|
||||
existsSync(join(outputDir, "extracted", "shaders.json")),
|
||||
catalogedAssets,
|
||||
progress,
|
||||
warnings,
|
||||
);
|
||||
|
||||
progress("done", "Capture complete");
|
||||
|
||||
return {
|
||||
ok: true,
|
||||
projectDir: outputDir,
|
||||
url,
|
||||
title: tokens.title,
|
||||
extracted,
|
||||
screenshots,
|
||||
tokens,
|
||||
assets,
|
||||
animationCatalog,
|
||||
warnings,
|
||||
};
|
||||
} finally {
|
||||
await chromeBrowser.close();
|
||||
}
|
||||
}
|
||||
|
||||
// visual-style.md and capture-summary.md generators removed — DESIGN.md replaces them
|
||||
370
packages/cli/src/capture/mediaCapture.ts
Normal file
370
packages/cli/src/capture/mediaCapture.ts
Normal file
@ -0,0 +1,370 @@
|
||||
/**
|
||||
* Media capture helpers for the website capture pipeline.
|
||||
*
|
||||
* Handles Lottie animation preview rendering and video element manifest capture.
|
||||
*
|
||||
* All page.evaluate() calls use string expressions to avoid
|
||||
* tsx/esbuild __name injection (see esbuild issue #1031).
|
||||
*/
|
||||
|
||||
import type { Browser, Page } from "puppeteer-core";
|
||||
import { mkdirSync, writeFileSync, readdirSync, readFileSync, statSync } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
import { isPrivateUrl } from "./assetDownloader.js";
|
||||
|
||||
/** Discovered Lottie item from network interception or DOM scan. */
|
||||
export interface DiscoveredLottie {
|
||||
url: string;
|
||||
data?: unknown;
|
||||
dimensions?: { w: number; h: number };
|
||||
frameRate?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Download and save discovered Lottie animations to disk.
|
||||
*
|
||||
* Handles both plain JSON and dotLottie (.lottie ZIP) formats.
|
||||
* Deduplicates by content hash. Returns the count of saved files.
|
||||
*/
|
||||
export async function saveLottieAnimations(
|
||||
discoveredLotties: DiscoveredLottie[],
|
||||
lottieDir: string,
|
||||
): Promise<number> {
|
||||
let savedCount = 0;
|
||||
const savedHashes = new Set<string>(); // Deduplicate by content
|
||||
|
||||
for (let li = 0; li < discoveredLotties.length && li < 10; li++) {
|
||||
const lottieItem = discoveredLotties[li]!;
|
||||
try {
|
||||
let jsonData: string | undefined;
|
||||
|
||||
if (lottieItem.data) {
|
||||
// Already have the JSON data from network interception
|
||||
jsonData = JSON.stringify(lottieItem.data);
|
||||
} else if (lottieItem.url) {
|
||||
// SSRF guard — don't fetch private/internal URLs
|
||||
if (isPrivateUrl(lottieItem.url)) continue;
|
||||
// Download the file
|
||||
const res = await fetch(lottieItem.url, {
|
||||
signal: AbortSignal.timeout(10000),
|
||||
headers: { "User-Agent": "HyperFrames/1.0" },
|
||||
});
|
||||
if (!res.ok) continue;
|
||||
const buf = Buffer.from(await res.arrayBuffer());
|
||||
|
||||
if (lottieItem.url.endsWith(".lottie")) {
|
||||
// dotLottie is a ZIP — extract the animation JSON
|
||||
try {
|
||||
const AdmZip = (await import("adm-zip")).default;
|
||||
const zip = new AdmZip(buf);
|
||||
const entries = zip.getEntries();
|
||||
// Look for animation JSON in both v1 (animations/) and v2 (a/) paths
|
||||
const animEntry = entries.find(
|
||||
(e) =>
|
||||
(e.entryName.startsWith("a/") || e.entryName.startsWith("animations/")) &&
|
||||
e.entryName.endsWith(".json"),
|
||||
);
|
||||
if (animEntry) {
|
||||
jsonData = animEntry.getData().toString("utf-8");
|
||||
}
|
||||
} catch {
|
||||
// adm-zip not available or extraction failed — save raw .lottie
|
||||
const hash = buf.toString("base64").slice(0, 100);
|
||||
if (savedHashes.has(hash)) continue;
|
||||
savedHashes.add(hash);
|
||||
writeFileSync(join(lottieDir, `animation-${savedCount}.lottie`), buf);
|
||||
savedCount++;
|
||||
continue;
|
||||
}
|
||||
} else {
|
||||
// Plain JSON file
|
||||
jsonData = buf.toString("utf-8");
|
||||
}
|
||||
}
|
||||
|
||||
if (jsonData) {
|
||||
// Deduplicate by content hash (first 100 chars of stringified JSON)
|
||||
const hash = jsonData.slice(0, 200);
|
||||
if (savedHashes.has(hash)) continue;
|
||||
savedHashes.add(hash);
|
||||
|
||||
// Validate it's actually Lottie
|
||||
try {
|
||||
const parsed = JSON.parse(jsonData);
|
||||
if (!parsed.layers || !parsed.w) continue;
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
|
||||
writeFileSync(join(lottieDir, `animation-${savedCount}.json`), jsonData, "utf-8");
|
||||
savedCount++;
|
||||
}
|
||||
} catch {
|
||||
/* skip */
|
||||
}
|
||||
}
|
||||
return savedCount;
|
||||
}
|
||||
|
||||
/**
|
||||
* Render preview thumbnails for saved Lottie animation JSON files.
|
||||
*
|
||||
* Opens each Lottie JSON in a headless Chrome page via lottie-web,
|
||||
* seeks to ~30% through the animation, and takes a transparent screenshot.
|
||||
* Writes a lottie-manifest.json with metadata + preview paths.
|
||||
*/
|
||||
export async function renderLottiePreviews(
|
||||
chromeBrowser: Browser,
|
||||
lottieDir: string,
|
||||
outputDir: string,
|
||||
): Promise<void> {
|
||||
const manifest: Array<{
|
||||
file: string;
|
||||
preview: string;
|
||||
name: string;
|
||||
width: number;
|
||||
height: number;
|
||||
duration: number;
|
||||
frameRate: number;
|
||||
layers: number;
|
||||
}> = [];
|
||||
const previewDir = join(lottieDir, "previews");
|
||||
mkdirSync(previewDir, { recursive: true });
|
||||
|
||||
for (const file of readdirSync(lottieDir)) {
|
||||
if (!file.endsWith(".json")) continue;
|
||||
try {
|
||||
const raw = JSON.parse(readFileSync(join(lottieDir, file), "utf-8"));
|
||||
const fr = raw.fr || 30;
|
||||
const dur = ((raw.op || 0) - (raw.ip || 0)) / fr;
|
||||
const previewName = file.replace(".json", "-preview.png");
|
||||
|
||||
// Render a mid-frame thumbnail using Puppeteer + lottie-web
|
||||
// Skip huge Lottie files for preview (CDP has a ~256MB message limit)
|
||||
const fileSize = statSync(join(lottieDir, file)).size;
|
||||
if (fileSize > 2_000_000) continue;
|
||||
|
||||
let previewPage;
|
||||
try {
|
||||
previewPage = await chromeBrowser.newPage();
|
||||
await previewPage.setViewport({ width: 400, height: 400 });
|
||||
const animData = JSON.parse(readFileSync(join(lottieDir, file), "utf-8"));
|
||||
const midFrame = Math.floor(((raw.op || 0) - (raw.ip || 0)) * 0.3);
|
||||
// Load the shell page first (no untrusted data in the HTML)
|
||||
await previewPage.setContent(
|
||||
`<!DOCTYPE html>
|
||||
<html><head>
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/lottie-web/5.12.2/lottie.min.js"></script>
|
||||
<style>*{margin:0;padding:0;background:transparent}#c{width:400px;height:400px}</style>
|
||||
</head><body><div id="c"></div></body></html>`,
|
||||
{ waitUntil: "networkidle0", timeout: 10000 },
|
||||
);
|
||||
// Pass animation data safely via parameterized evaluate (no string interpolation)
|
||||
await previewPage.evaluate(
|
||||
(data: unknown, frame: number) => {
|
||||
const a = (window as any).lottie.loadAnimation({
|
||||
container: document.getElementById("c"),
|
||||
renderer: "svg",
|
||||
loop: false,
|
||||
autoplay: false,
|
||||
animationData: data,
|
||||
});
|
||||
a.addEventListener("DOMLoaded", () => {
|
||||
a.goToAndStop(frame, true);
|
||||
(window as any).__READY = true;
|
||||
});
|
||||
},
|
||||
animData,
|
||||
midFrame,
|
||||
);
|
||||
await previewPage
|
||||
.waitForFunction(() => (window as any).__READY === true, { timeout: 5000 })
|
||||
.catch(() => {});
|
||||
await previewPage.screenshot({
|
||||
path: join(previewDir, previewName),
|
||||
type: "png",
|
||||
omitBackground: true,
|
||||
});
|
||||
} catch {
|
||||
/* preview rendering failed — non-critical */
|
||||
} finally {
|
||||
await previewPage?.close().catch(() => {});
|
||||
}
|
||||
|
||||
manifest.push({
|
||||
file: `assets/lottie/${file}`,
|
||||
preview: `assets/lottie/previews/${previewName}`,
|
||||
name: raw.nm || file,
|
||||
width: raw.w || 0,
|
||||
height: raw.h || 0,
|
||||
duration: Math.round(dur * 10) / 10,
|
||||
frameRate: fr,
|
||||
layers: (raw.layers || []).length,
|
||||
});
|
||||
} catch {
|
||||
/* skip */
|
||||
}
|
||||
}
|
||||
if (manifest.length > 0) {
|
||||
writeFileSync(
|
||||
join(outputDir, "extracted", "lottie-manifest.json"),
|
||||
JSON.stringify(manifest, null, 2),
|
||||
"utf-8",
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Capture video element manifest — screenshot each <video> element and
|
||||
* extract surrounding context (heading, caption, aria-label).
|
||||
*
|
||||
* Writes video-manifest.json and preview screenshots to assets/videos/previews/.
|
||||
*/
|
||||
export async function captureVideoManifest(
|
||||
page: Page,
|
||||
outputDir: string,
|
||||
progress: (stage: string, detail?: string) => void,
|
||||
): Promise<void> {
|
||||
const videoElements = (await page.evaluate(`(() => {
|
||||
var videos = Array.from(document.querySelectorAll('video'));
|
||||
return videos.map(function(v) {
|
||||
var src = v.src || v.currentSrc || (v.querySelector('source') ? v.querySelector('source').src : '');
|
||||
if (!src || !src.startsWith('http')) return null;
|
||||
|
||||
// Get bounding box for screenshot
|
||||
var rect = v.getBoundingClientRect();
|
||||
if (rect.width < 10 || rect.height < 10) return null;
|
||||
|
||||
// Nearest heading above the video
|
||||
var heading = '';
|
||||
var el = v;
|
||||
for (var i = 0; i < 8; i++) {
|
||||
el = el.parentElement;
|
||||
if (!el) break;
|
||||
var h = el.querySelector('h1,h2,h3,h4');
|
||||
if (h) { heading = h.textContent.trim().slice(0, 100); break; }
|
||||
}
|
||||
|
||||
// Nearest paragraph/caption text
|
||||
var caption = '';
|
||||
el = v;
|
||||
for (var j = 0; j < 5; j++) {
|
||||
el = el.parentElement;
|
||||
if (!el) break;
|
||||
var p = el.querySelector('p,figcaption,[class*="caption"],[class*="desc"]');
|
||||
if (p) { caption = p.textContent.trim().slice(0, 200); break; }
|
||||
}
|
||||
|
||||
// aria-label on video or wrapper
|
||||
var ariaLabel = v.getAttribute('aria-label') || v.getAttribute('title') || '';
|
||||
var wrapper = v.parentElement;
|
||||
if (!ariaLabel && wrapper) ariaLabel = wrapper.getAttribute('aria-label') || '';
|
||||
|
||||
return {
|
||||
src: src,
|
||||
width: Math.round(rect.width),
|
||||
height: Math.round(rect.height),
|
||||
top: Math.round(rect.top),
|
||||
left: Math.round(rect.left),
|
||||
heading: heading,
|
||||
caption: caption,
|
||||
ariaLabel: ariaLabel,
|
||||
filename: src.split('/').pop().split('?')[0],
|
||||
};
|
||||
}).filter(Boolean);
|
||||
})()`)) as Array<{
|
||||
src: string;
|
||||
width: number;
|
||||
height: number;
|
||||
top: number;
|
||||
left: number;
|
||||
heading: string;
|
||||
caption: string;
|
||||
ariaLabel: string;
|
||||
filename: string;
|
||||
}>;
|
||||
|
||||
// Deduplicate by src
|
||||
const seenSrcs = new Set<string>();
|
||||
const uniqueVideos = videoElements.filter((v) => {
|
||||
if (seenSrcs.has(v.src)) return false;
|
||||
seenSrcs.add(v.src);
|
||||
return true;
|
||||
});
|
||||
|
||||
if (uniqueVideos.length > 0) {
|
||||
const videoManifestDir = join(outputDir, "assets", "videos");
|
||||
mkdirSync(videoManifestDir, { recursive: true });
|
||||
const previewDir = join(videoManifestDir, "previews");
|
||||
mkdirSync(previewDir, { recursive: true });
|
||||
|
||||
const videoManifest: Array<{
|
||||
index: number;
|
||||
url: string;
|
||||
filename: string;
|
||||
width: number;
|
||||
height: number;
|
||||
heading: string;
|
||||
caption: string;
|
||||
ariaLabel: string;
|
||||
preview: string;
|
||||
}> = [];
|
||||
|
||||
for (let vi = 0; vi < uniqueVideos.length && vi < 20; vi++) {
|
||||
const v = uniqueVideos[vi]!;
|
||||
const previewName = `video-${vi}-preview.png`;
|
||||
const previewPath = join(previewDir, previewName);
|
||||
|
||||
// Screenshot the video element to get a visible frame
|
||||
try {
|
||||
// Scroll to the video element so it's in the viewport
|
||||
await page.evaluate(`window.scrollTo(0, ${Math.max(0, v.top - 100)})`);
|
||||
await new Promise((r) => setTimeout(r, 300));
|
||||
// Re-measure position after scroll (layout may have shifted)
|
||||
const rect = (await page.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 page.screenshot({
|
||||
path: previewPath,
|
||||
clip: {
|
||||
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 {
|
||||
/* preview failed — non-critical */
|
||||
}
|
||||
|
||||
videoManifest.push({
|
||||
index: vi,
|
||||
url: v.src,
|
||||
filename: v.filename,
|
||||
width: v.width,
|
||||
height: v.height,
|
||||
heading: v.heading,
|
||||
caption: v.caption,
|
||||
ariaLabel: v.ariaLabel,
|
||||
preview: `assets/videos/previews/${previewName}`,
|
||||
});
|
||||
}
|
||||
|
||||
if (videoManifest.length > 0) {
|
||||
writeFileSync(
|
||||
join(outputDir, "extracted", "video-manifest.json"),
|
||||
JSON.stringify(videoManifest, null, 2),
|
||||
"utf-8",
|
||||
);
|
||||
progress("design", `${videoManifest.length} video previews captured`);
|
||||
}
|
||||
}
|
||||
}
|
||||
135
packages/cli/src/capture/scaffolding.ts
Normal file
135
packages/cli/src/capture/scaffolding.ts
Normal file
@ -0,0 +1,135 @@
|
||||
/**
|
||||
* Project scaffolding helpers for the website capture pipeline.
|
||||
*
|
||||
* Handles .env file loading and HyperFrames project scaffold generation
|
||||
* (index.html, meta.json, CLAUDE.md).
|
||||
*/
|
||||
|
||||
import { existsSync, writeFileSync, readFileSync } from "node:fs";
|
||||
import { join, resolve } from "node:path";
|
||||
import type { CatalogedAsset } from "./assetCataloger.js";
|
||||
import type { CaptureResult, DesignTokens } from "./types.js";
|
||||
|
||||
/**
|
||||
* Load .env file by walking up from startDir (up to 5 levels).
|
||||
* Sets process.env keys that are not already set. Best-effort — never throws.
|
||||
*/
|
||||
export function loadEnvFile(startDir: string): void {
|
||||
try {
|
||||
let dir = resolve(startDir);
|
||||
for (let i = 0; i < 5; i++) {
|
||||
const envPath = resolve(dir, ".env");
|
||||
try {
|
||||
const envContent = readFileSync(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 = resolve(dir, "..");
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
/* .env loading is best-effort */
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate the project scaffold files: index.html, meta.json, and CLAUDE.md.
|
||||
*
|
||||
* Only creates files that don't already exist (index.html, meta.json).
|
||||
* Always generates CLAUDE.md via agentPromptGenerator.
|
||||
*/
|
||||
export async function generateProjectScaffold(
|
||||
outputDir: string,
|
||||
url: string,
|
||||
tokens: DesignTokens,
|
||||
animationCatalog: CaptureResult["animationCatalog"],
|
||||
hasScreenshots: boolean,
|
||||
hasLotties: boolean,
|
||||
hasShaders: boolean,
|
||||
catalogedAssets: CatalogedAsset[],
|
||||
progress: (stage: string, detail?: string) => void,
|
||||
warnings: string[],
|
||||
): Promise<void> {
|
||||
// Ensure capture output is a valid HyperFrames project (index.html + meta.json)
|
||||
const indexPath = join(outputDir, "index.html");
|
||||
const metaPath = join(outputDir, "meta.json");
|
||||
if (!existsSync(indexPath)) {
|
||||
writeFileSync(
|
||||
indexPath,
|
||||
`<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8" />
|
||||
<meta name="viewport" content="width=1920, height=1080" />
|
||||
<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
|
||||
<style>
|
||||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||||
html, body { margin: 0; width: 1920px; height: 1080px; overflow: hidden; background: #000; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<!-- Root composition wrapper — AGENT: update data-duration to match total video length -->
|
||||
<div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="28">
|
||||
|
||||
<!-- SCENE SLOTS — AGENT: adjust count, durations, and IDs to match your scene plan -->
|
||||
<div id="scene-1" data-composition-src="compositions/scene-1.html" data-start="0" data-duration="7" data-track-index="1" data-width="1920" data-height="1080"></div>
|
||||
<div id="scene-2" data-composition-src="compositions/scene-2.html" data-start="7" data-duration="7" data-track-index="1" data-width="1920" data-height="1080"></div>
|
||||
<div id="scene-3" data-composition-src="compositions/scene-3.html" data-start="14" data-duration="7" data-track-index="1" data-width="1920" data-height="1080"></div>
|
||||
<div id="scene-4" data-composition-src="compositions/scene-4.html" data-start="21" data-duration="7" data-track-index="1" data-width="1920" data-height="1080"></div>
|
||||
|
||||
<!-- NARRATION — AGENT: update src after generating TTS -->
|
||||
<audio id="narration" data-start="0" data-duration="28" data-track-index="0" data-volume="1" src="narration.wav"></audio>
|
||||
|
||||
<!-- CAPTIONS (optional — only add if user requests captions/subtitles) -->
|
||||
|
||||
</div>
|
||||
|
||||
<script>
|
||||
window.__timelines = window.__timelines || {};
|
||||
var tl = gsap.timeline({ paused: true });
|
||||
window.__timelines["main"] = tl;
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
`,
|
||||
"utf-8",
|
||||
);
|
||||
}
|
||||
if (!existsSync(metaPath)) {
|
||||
const hostname = new URL(url).hostname.replace(/^www\./, "");
|
||||
writeFileSync(
|
||||
metaPath,
|
||||
JSON.stringify({ id: hostname + "-video", name: tokens.title || hostname }, null, 2),
|
||||
"utf-8",
|
||||
);
|
||||
}
|
||||
|
||||
// Generate CLAUDE.md + .cursorrules (AI agent instructions — always, regardless of API keys)
|
||||
try {
|
||||
const { generateAgentPrompt } = await import("./agentPromptGenerator.js");
|
||||
generateAgentPrompt(
|
||||
outputDir,
|
||||
url,
|
||||
tokens,
|
||||
animationCatalog,
|
||||
hasScreenshots,
|
||||
hasLotties,
|
||||
hasShaders,
|
||||
catalogedAssets,
|
||||
);
|
||||
progress("agent", "CLAUDE.md generated");
|
||||
} catch (err) {
|
||||
warnings.push(`CLAUDE.md generation failed: ${err}`);
|
||||
}
|
||||
}
|
||||
82
packages/cli/src/capture/screenshotCapture.ts
Normal file
82
packages/cli/src/capture/screenshotCapture.ts
Normal file
@ -0,0 +1,82 @@
|
||||
/**
|
||||
* Screenshot capture for the website capture pipeline.
|
||||
*
|
||||
* All page.evaluate() calls use string expressions to avoid
|
||||
* tsx/esbuild __name injection (see esbuild issue #1031).
|
||||
*/
|
||||
|
||||
import type { Page } from "puppeteer-core";
|
||||
import { writeFileSync, mkdirSync } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
|
||||
/**
|
||||
* 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 });
|
||||
|
||||
const MAX_SCREENSHOTS = 20;
|
||||
const filePaths: string[] = [];
|
||||
|
||||
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;
|
||||
|
||||
// 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);
|
||||
}
|
||||
|
||||
// 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 */
|
||||
}
|
||||
|
||||
return filePaths;
|
||||
}
|
||||
355
packages/cli/src/capture/tokenExtractor.ts
Normal file
355
packages/cli/src/capture/tokenExtractor.ts
Normal file
@ -0,0 +1,355 @@
|
||||
/**
|
||||
* Extract design tokens from a rendered page.
|
||||
*
|
||||
* All page.evaluate() calls use string expressions to avoid
|
||||
* tsx/esbuild __name injection (see esbuild issue #1031).
|
||||
*/
|
||||
|
||||
import type { Page } from "puppeteer-core";
|
||||
import type { DesignTokens } from "./types.js";
|
||||
|
||||
// The entire extraction runs as a single string-based evaluate
|
||||
// to avoid tsx __name injection into the browser context.
|
||||
const EXTRACT_SCRIPT = `(() => {
|
||||
var isVisible = (el) => {
|
||||
var s = getComputedStyle(el);
|
||||
return s.display !== "none" && s.visibility !== "hidden" && s.opacity !== "0" && el.getBoundingClientRect().height > 0;
|
||||
};
|
||||
|
||||
// 1. CSS custom properties from :root
|
||||
var cssVariables = {};
|
||||
for (var i = 0; i < document.styleSheets.length; i++) {
|
||||
try {
|
||||
var rules = document.styleSheets[i].cssRules;
|
||||
for (var j = 0; j < rules.length; j++) {
|
||||
if (rules[j].selectorText === ":root") {
|
||||
for (var k = 0; k < rules[j].style.length; k++) {
|
||||
var prop = rules[j].style[k];
|
||||
if (prop.startsWith("--")) {
|
||||
cssVariables[prop] = rules[j].style.getPropertyValue(prop).trim();
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
} catch(e) {}
|
||||
}
|
||||
|
||||
// 2. Meta
|
||||
var title = document.title || "";
|
||||
var descEl = document.querySelector('meta[name="description"]') || document.querySelector('meta[property="og:description"]');
|
||||
var description = descEl ? descEl.content : "";
|
||||
var ogImgEl = document.querySelector('meta[property="og:image"]');
|
||||
var ogImage = ogImgEl ? ogImgEl.content : undefined;
|
||||
|
||||
// 3. Fonts
|
||||
var fontSet = {};
|
||||
var fontSamples = [document.body, document.querySelector("h1"), document.querySelector("h2"), document.querySelector("p"), document.querySelector("button")].filter(Boolean);
|
||||
for (var fi = 0; fi < fontSamples.length; fi++) {
|
||||
var family = getComputedStyle(fontSamples[fi]).fontFamily.split(",")[0].replace(/['"]/g, "").trim();
|
||||
if (family && ["serif","sans-serif","monospace","cursive"].indexOf(family) === -1) fontSet[family] = true;
|
||||
}
|
||||
|
||||
// 4. Colors — hybrid: DOM computed styles + visual pixel sampling
|
||||
var colorSet = {};
|
||||
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) + (weight || 1);
|
||||
}
|
||||
function rgbToHex(color) {
|
||||
if (!color) return null;
|
||||
if (color.startsWith('#')) return (color.length === 4
|
||||
? '#' + color[1]+color[1] + color[2]+color[2] + color[3]+color[3]
|
||||
: color).toUpperCase();
|
||||
var m = color.match(/rgba?\\(\\s*(\\d+)\\s*,\\s*(\\d+)\\s*,\\s*(\\d+)/);
|
||||
if (!m) {
|
||||
// Handle color(srgb ...) format
|
||||
var cm = color.match(/color\\(srgb\\s+([\\d.]+)\\s+([\\d.]+)\\s+([\\d.]+)/);
|
||||
if (cm) {
|
||||
m = [null, Math.round(parseFloat(cm[1])*255), Math.round(parseFloat(cm[2])*255), Math.round(parseFloat(cm[3])*255)];
|
||||
} else {
|
||||
// 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);
|
||||
if (resolved !== color) return rgbToHex(resolved);
|
||||
return null;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
}
|
||||
return '#' + ((1<<24) + (parseInt(m[1])<<16) + (parseInt(m[2])<<8) + parseInt(m[3])).toString(16).slice(1).toUpperCase();
|
||||
}
|
||||
|
||||
// 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, " +
|
||||
"a, button, [role='button'], " +
|
||||
"[class*='hero'], [class*='cta'], [class*='btn'], [class*='card'], " +
|
||||
"[class*='badge'], [class*='tag'], [class*='accent'], [class*='highlight']"
|
||||
)).slice(0, 200);
|
||||
for (var ci = 0; ci < colorCandidates.length; ci++) {
|
||||
try {
|
||||
var cs = getComputedStyle(colorCandidates[ci]);
|
||||
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) {}
|
||||
}
|
||||
|
||||
// 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 && /^(#|rgb|hsl|oklch|oklab|lch|lab|color)/.test(val)) {
|
||||
addColor(val);
|
||||
}
|
||||
}
|
||||
|
||||
// 5. Headings
|
||||
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.innerText || h.textContent || "").trim().replace(/\\s+/g, ' ').slice(0, 200), fontSize: s.fontSize, fontWeight: s.fontWeight, color: rgbToHex(s.color) || s.color };
|
||||
});
|
||||
|
||||
// 6. Paragraphs
|
||||
var paragraphs = Array.from(document.querySelectorAll("p")).slice(0, 10).map(function(p) { return (p.textContent || "").trim().slice(0, 300); }).filter(function(t) { return t.length > 20; });
|
||||
|
||||
// 7. CTAs — match by class AND by text content patterns
|
||||
// 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
|
||||
var svgEls = Array.from(document.querySelectorAll("svg"));
|
||||
var svgs = svgEls.map(function(svg) {
|
||||
var label = svg.getAttribute("aria-label") || svg.getAttribute("title") || svg.getAttribute("alt");
|
||||
// Try harder to find a name: check class, id, parent context, inner text
|
||||
if (!label) {
|
||||
// Extract meaningful class name, skipping utility classes (tailwind, size, color)
|
||||
var svgClasses = (svg.getAttribute("class") || "").split(/\\s+/);
|
||||
var utilityPattern = /^(w-|h-|p-|m-|text-|bg-|border-|flex|grid|block|hidden|inline|absolute|relative|transition|duration|rotate|scale|opacity|group|sm:|md:|lg:|xl:)/;
|
||||
for (var ci = 0; ci < svgClasses.length; ci++) {
|
||||
var cls = svgClasses[ci];
|
||||
if (cls.length > 3 && cls.length < 40 && !utilityPattern.test(cls) && cls !== "lucide") {
|
||||
label = cls;
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
if (!label) {
|
||||
var svgId = svg.getAttribute("id") || "";
|
||||
if (svgId && svgId.length > 2 && svgId.length < 40) label = svgId;
|
||||
}
|
||||
if (!label) {
|
||||
// Check parent element for clues
|
||||
var parent = svg.closest("[class*='icon'], [class*='logo'], [class*='nav'], [class*='btn'], [class*='social']");
|
||||
if (parent) {
|
||||
var parentClass = (parent.getAttribute("class") || "").split(" ").find(function(c) { return c.length > 3 && c.length < 30; });
|
||||
if (parentClass) label = parentClass;
|
||||
}
|
||||
}
|
||||
if (!label) {
|
||||
// Check for text content inside the SVG (e.g. <text>NeetCode</text>)
|
||||
var textEl = svg.querySelector("text");
|
||||
if (textEl && textEl.textContent && textEl.textContent.trim().length > 1 && textEl.textContent.trim().length < 30) {
|
||||
label = textEl.textContent.trim();
|
||||
}
|
||||
}
|
||||
var w = svg.getAttribute("width");
|
||||
// Keep SVGs that have a label OR are at least 16px wide OR are inside a logo/brand context
|
||||
var inLogoContext = svg.closest('[class*="logo"], [class*="brand"], [class*="partner"], [class*="customer"], [class*="marquee"]') !== null;
|
||||
if (!label && !inLogoContext && (!w || parseInt(w) < 16)) return null;
|
||||
return {
|
||||
label: label || undefined,
|
||||
viewBox: svg.getAttribute("viewBox") || undefined,
|
||||
outerHTML: svg.outerHTML.slice(0, 10000),
|
||||
isLogo: (label && label.toLowerCase().indexOf("logo") !== -1) || svg.closest('[class*="logo"], [class*="brand"], [class*="home"], [class*="marquee"], [class*="partner"], [class*="customer"]') !== null
|
||||
};
|
||||
}).filter(Boolean).slice(0, 50);
|
||||
|
||||
// 9. Images
|
||||
var imgEls = Array.from(document.querySelectorAll("img[src]")).filter(function(img) { return img.naturalWidth > 200 && isVisible(img); }).slice(0, 15);
|
||||
var images = imgEls.map(function(img) { return { src: img.src, alt: img.alt || "", width: img.naturalWidth, height: img.naturalHeight }; });
|
||||
|
||||
// 10. Icons
|
||||
var iconEls = Array.from(document.querySelectorAll('link[rel*="icon"], link[rel="apple-touch-icon"]'));
|
||||
var icons = iconEls.map(function(l) { return { rel: l.rel, href: l.href }; });
|
||||
|
||||
// 11. Sections — find large visual blocks regardless of HTML tag
|
||||
var sectionResults = [];
|
||||
// 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.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";
|
||||
else if (el.tagName === "FOOTER" || classes.indexOf("footer") !== -1) type = "footer";
|
||||
else if (classes.indexOf("cta") !== -1) type = "cta";
|
||||
else if (classes.indexOf("logo") !== -1 || classes.indexOf("customer") !== -1) type = "logos";
|
||||
else if (classes.indexOf("testimonial") !== -1 || classes.indexOf("quote") !== -1) type = "testimonials";
|
||||
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;
|
||||
// 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; });
|
||||
var filtered = sectionResults.filter(function(s, i) { return i === 0 || Math.abs(s.y - sectionResults[i-1].y) > 100; });
|
||||
|
||||
return {
|
||||
title: title, description: description, ogImage: ogImage,
|
||||
cssVariables: cssVariables, fonts: Object.keys(fontSet), colors: Object.keys(colorSet).sort(function(a,b) { return colorSet[b] - colorSet[a]; }).slice(0, 20),
|
||||
headings: headings, paragraphs: paragraphs, ctas: ctas,
|
||||
svgs: svgs, images: images, icons: icons, sections: filtered
|
||||
};
|
||||
})()`;
|
||||
|
||||
export async function extractTokens(page: Page): Promise<DesignTokens> {
|
||||
return page.evaluate(EXTRACT_SCRIPT) as Promise<DesignTokens>;
|
||||
}
|
||||
136
packages/cli/src/capture/types.ts
Normal file
136
packages/cli/src/capture/types.ts
Normal file
@ -0,0 +1,136 @@
|
||||
/**
|
||||
* Types for the website capture pipeline.
|
||||
*
|
||||
* Phase 1: Capture — Extract HTML, CSS, screenshots, tokens, assets from a URL
|
||||
* Phase 2: Split — Decompose into per-section sub-compositions
|
||||
* Phase 3: Verify — Validate each section renders correctly
|
||||
* Phase 4: Scaffold — Assemble standard HyperFrames project
|
||||
*/
|
||||
|
||||
// ── Phase 1: Capture ────────────────────────────────────────────────────────
|
||||
|
||||
export interface CaptureOptions {
|
||||
/** URL to capture */
|
||||
url: string;
|
||||
/** Output directory */
|
||||
outputDir: string;
|
||||
/** Viewport width (default: 1920) */
|
||||
viewportWidth?: number;
|
||||
/** Viewport height (default: 1080) */
|
||||
viewportHeight?: number;
|
||||
/** Page load timeout in ms (default: 120000) */
|
||||
timeout?: number;
|
||||
/** Extra wait after load for JS to settle (default: 3000) */
|
||||
settleTime?: number;
|
||||
/** Maximum screenshots to take (default: 24) */
|
||||
maxScreenshots?: number;
|
||||
/** Skip asset downloads */
|
||||
skipAssets?: boolean;
|
||||
/** Output JSON for programmatic use */
|
||||
json?: boolean;
|
||||
}
|
||||
|
||||
export interface CaptureResult {
|
||||
/** Whether capture completed successfully */
|
||||
ok: boolean;
|
||||
/** Project output directory */
|
||||
projectDir: string;
|
||||
/** Source URL */
|
||||
url: string;
|
||||
/** Page title */
|
||||
title: string;
|
||||
/** Extracted HTML data */
|
||||
extracted: ExtractedHtml;
|
||||
/** Screenshot file paths (relative to projectDir) */
|
||||
screenshots: string[];
|
||||
/** Design tokens extracted from the page */
|
||||
tokens: DesignTokens;
|
||||
/** Downloaded asset paths (relative to projectDir) */
|
||||
assets: DownloadedAsset[];
|
||||
/** Animation catalog (captured during full-JS page load) */
|
||||
animationCatalog?: import("./animationCataloger.js").AnimationCatalog;
|
||||
/** Errors/warnings encountered during capture */
|
||||
warnings: string[];
|
||||
}
|
||||
|
||||
export interface ExtractedHtml {
|
||||
/** All <style> tags from <head> (after stylesheet inlining) */
|
||||
headHtml: string;
|
||||
/** Full document.body.innerHTML */
|
||||
bodyHtml: string;
|
||||
/** CSS-in-JS rules from document.styleSheets (CSSOM) */
|
||||
cssomRules: string;
|
||||
/** <html> element attributes (class, data-theme, style, lang) */
|
||||
htmlAttrs: string;
|
||||
/** Original viewport width during capture */
|
||||
viewportWidth: number;
|
||||
/** Original viewport height during capture */
|
||||
viewportHeight: number;
|
||||
/** Full page scroll height */
|
||||
fullPageHeight: number;
|
||||
}
|
||||
|
||||
// ── Design Tokens ───────────────────────────────────────────────────────────
|
||||
|
||||
export interface DesignTokens {
|
||||
/** Page title */
|
||||
title: string;
|
||||
/** Meta description */
|
||||
description: string;
|
||||
/** OG image URL */
|
||||
ogImage?: string;
|
||||
/** CSS custom properties from :root */
|
||||
cssVariables: Record<string, string>;
|
||||
/** Font families in use */
|
||||
fonts: string[];
|
||||
/** Extracted colors (background, text, accent) */
|
||||
colors: string[];
|
||||
/** Headings with text and basic styles */
|
||||
headings: Array<{
|
||||
level: number;
|
||||
text: string;
|
||||
fontSize: string;
|
||||
fontWeight: string;
|
||||
color: string;
|
||||
}>;
|
||||
/** Paragraph text (first 10) */
|
||||
paragraphs: string[];
|
||||
/** CTA button/link text */
|
||||
ctas: Array<{ text: string; href?: string }>;
|
||||
/** SVG elements with labels */
|
||||
svgs: Array<{
|
||||
label?: string;
|
||||
viewBox?: string;
|
||||
outerHTML: string;
|
||||
isLogo: boolean;
|
||||
}>;
|
||||
/** Large images on the page */
|
||||
images: Array<{
|
||||
src: string;
|
||||
alt: string;
|
||||
width: number;
|
||||
height: number;
|
||||
}>;
|
||||
/** Favicon/icon URLs */
|
||||
icons: Array<{ rel: string; href: string }>;
|
||||
/** Detected page sections with bounding rects */
|
||||
sections: Array<{
|
||||
selector: string;
|
||||
type: string;
|
||||
y: number;
|
||||
height: number;
|
||||
heading: string;
|
||||
backgroundColor?: string;
|
||||
}>;
|
||||
}
|
||||
|
||||
// ── Assets ──────────────────────────────────────────────────────────────────
|
||||
|
||||
export interface DownloadedAsset {
|
||||
/** Original URL */
|
||||
url: string;
|
||||
/** Local file path (relative to projectDir) */
|
||||
localPath: string;
|
||||
/** Asset type */
|
||||
type: "svg" | "image" | "favicon";
|
||||
}
|
||||
@ -43,6 +43,8 @@ const subCommands = {
|
||||
skills: () => import("./commands/skills.js").then((m) => m.default),
|
||||
telemetry: () => import("./commands/telemetry.js").then((m) => m.default),
|
||||
validate: () => import("./commands/validate.js").then((m) => m.default),
|
||||
snapshot: () => import("./commands/snapshot.js").then((m) => m.default),
|
||||
capture: () => import("./commands/capture.js").then((m) => m.default),
|
||||
};
|
||||
|
||||
const main = defineCommand({
|
||||
|
||||
169
packages/cli/src/commands/capture.ts
Normal file
169
packages/cli/src/commands/capture.ts
Normal file
@ -0,0 +1,169 @@
|
||||
import { defineCommand } from "citty";
|
||||
import { resolve } from "node:path";
|
||||
import type { Example } from "./_examples.js";
|
||||
|
||||
export const examples: Example[] = [
|
||||
["Capture a website", "hyperframes capture https://stripe.com"],
|
||||
["Capture to a specific directory", "hyperframes capture https://linear.app -o linear-video"],
|
||||
["JSON output for AI agents", "hyperframes capture https://example.com --json"],
|
||||
];
|
||||
|
||||
export default defineCommand({
|
||||
meta: {
|
||||
name: "capture",
|
||||
description: "Capture a website as editable HyperFrames components",
|
||||
},
|
||||
args: {
|
||||
url: {
|
||||
type: "positional",
|
||||
description: "Website URL to capture",
|
||||
required: true,
|
||||
},
|
||||
output: {
|
||||
type: "string",
|
||||
description: "Output directory name",
|
||||
alias: "o",
|
||||
},
|
||||
"skip-assets": {
|
||||
type: "boolean",
|
||||
description: "Skip downloading assets (images, SVGs)",
|
||||
default: false,
|
||||
},
|
||||
"max-screenshots": {
|
||||
type: "string",
|
||||
description: "Maximum screenshots to capture (default: 24)",
|
||||
},
|
||||
timeout: {
|
||||
type: "string",
|
||||
description: "Page load timeout in ms (default: 120000)",
|
||||
},
|
||||
json: {
|
||||
type: "boolean",
|
||||
description: "Output JSON (for AI agents / programmatic use)",
|
||||
default: false,
|
||||
},
|
||||
},
|
||||
async run({ args }) {
|
||||
const url = args.url as string;
|
||||
|
||||
// Validate URL
|
||||
try {
|
||||
new URL(url);
|
||||
} catch {
|
||||
console.error(`Invalid URL: ${url}`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// Determine output directory — default to captures/<hostname> to keep repo root clean
|
||||
let outputName = args.output as string | undefined;
|
||||
if (!outputName) {
|
||||
const hostname = new URL(url).hostname.replace(/^www\./, "");
|
||||
outputName = `captures/${hostname.replace(/\./g, "-")}`;
|
||||
}
|
||||
const outputDir = resolve(outputName);
|
||||
|
||||
const isJson = args.json as boolean;
|
||||
|
||||
if (!isJson) {
|
||||
const { c } = await import("../ui/colors.js");
|
||||
console.log();
|
||||
console.log(c.dim("◆") + " Capturing " + c.bold(url));
|
||||
console.log();
|
||||
}
|
||||
|
||||
const { captureWebsite } = await import("../capture/index.js");
|
||||
|
||||
try {
|
||||
const result = await captureWebsite(
|
||||
{
|
||||
url,
|
||||
outputDir,
|
||||
skipAssets: args["skip-assets"] as boolean,
|
||||
maxScreenshots: args["max-screenshots"]
|
||||
? parseInt(args["max-screenshots"] as string)
|
||||
: undefined,
|
||||
timeout: args.timeout ? parseInt(args.timeout as string) : undefined,
|
||||
json: isJson,
|
||||
},
|
||||
isJson
|
||||
? undefined
|
||||
: (stage: string, detail?: string) => {
|
||||
const stages: Record<string, string> = {
|
||||
browser: " Launching browser...",
|
||||
navigate: " Loading page...",
|
||||
extract: " Extracting HTML & CSS...",
|
||||
tokens: " Extracting design tokens...",
|
||||
screenshots: " Capturing screenshots...",
|
||||
assets: " Downloading assets...",
|
||||
style: " Generating visual style...",
|
||||
done: " Done",
|
||||
};
|
||||
const label = stages[stage] || ` ${stage}`;
|
||||
console.log(detail ? `${label} ${detail}` : label);
|
||||
},
|
||||
);
|
||||
|
||||
if (isJson) {
|
||||
// Output structured JSON for Claude Code / programmatic use
|
||||
console.log(
|
||||
JSON.stringify(
|
||||
{
|
||||
ok: result.ok,
|
||||
projectDir: result.projectDir,
|
||||
url: result.url,
|
||||
title: result.title,
|
||||
screenshots: result.screenshots.length,
|
||||
assets: result.assets.length,
|
||||
detectedSections: result.tokens.sections.length,
|
||||
fonts: result.tokens.fonts,
|
||||
animations: result.animationCatalog?.summary,
|
||||
warnings: result.warnings,
|
||||
},
|
||||
null,
|
||||
2,
|
||||
),
|
||||
);
|
||||
} else {
|
||||
const { c } = await import("../ui/colors.js");
|
||||
console.log();
|
||||
console.log(c.success("◇") + ` Captured ${c.bold(result.title)} → ${c.dim(outputDir)}`);
|
||||
console.log();
|
||||
console.log(` ${c.dim("Screenshots:")} ${result.screenshots.length}`);
|
||||
console.log(` ${c.dim("Assets:")} ${result.assets.length}`);
|
||||
console.log(` ${c.dim("Sections:")} ${result.tokens.sections.length}`);
|
||||
console.log(` ${c.dim("Fonts:")} ${result.tokens.fonts.join(", ")}`);
|
||||
if (result.warnings.length > 0) {
|
||||
console.log();
|
||||
for (const w of result.warnings) {
|
||||
console.log(` ${c.warn("⚠")} ${w}`);
|
||||
}
|
||||
}
|
||||
console.log();
|
||||
}
|
||||
} catch (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: ${errMsg}\n`);
|
||||
}
|
||||
process.exit(1);
|
||||
}
|
||||
},
|
||||
});
|
||||
284
packages/cli/src/commands/snapshot.ts
Normal file
284
packages/cli/src/commands/snapshot.ts
Normal file
@ -0,0 +1,284 @@
|
||||
import { defineCommand } from "citty";
|
||||
import { existsSync, readFileSync, mkdirSync } from "node:fs";
|
||||
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";
|
||||
import type { Example } from "./_examples.js";
|
||||
|
||||
const __filename = fileURLToPath(import.meta.url);
|
||||
const __dirname = dirname(__filename);
|
||||
|
||||
export const examples: Example[] = [
|
||||
["Capture 5 key frames from a composition", "snapshot captures/stripe"],
|
||||
["Capture 10 evenly-spaced frames", "snapshot captures/stripe --frames 10"],
|
||||
];
|
||||
|
||||
/**
|
||||
* Render key frames from a composition as PNG screenshots.
|
||||
* The agent can Read these to verify its output visually.
|
||||
*/
|
||||
async function captureSnapshots(
|
||||
projectDir: string,
|
||||
opts: { frames?: number; timeout?: number; at?: number[] },
|
||||
): Promise<string[]> {
|
||||
const { bundleToSingleHtml } = await import("@hyperframes/core/compiler");
|
||||
const { ensureBrowser } = await import("../browser/manager.js");
|
||||
|
||||
const numFrames = opts.frames ?? 5;
|
||||
|
||||
// 1. Bundle
|
||||
let html = await bundleToSingleHtml(projectDir);
|
||||
|
||||
// Inject local runtime if available
|
||||
const runtimePath = resolve(
|
||||
__dirname,
|
||||
"..",
|
||||
"..",
|
||||
"..",
|
||||
"core",
|
||||
"dist",
|
||||
"hyperframe.runtime.iife.js",
|
||||
);
|
||||
if (existsSync(runtimePath)) {
|
||||
const runtimeSource = readFileSync(runtimePath, "utf-8");
|
||||
html = html.replace(
|
||||
/<script[^>]*data-hyperframes-preview-runtime[^>]*src="[^"]*"[^>]*><\/script>/,
|
||||
() => `<script data-hyperframes-preview-runtime="1">${runtimeSource}</script>`,
|
||||
);
|
||||
}
|
||||
|
||||
// 2. Start minimal file server
|
||||
const { createServer } = await import("node:http");
|
||||
const { getMimeType } = await import("@hyperframes/core/studio-api");
|
||||
|
||||
const server = createServer((req, res) => {
|
||||
const url = req.url ?? "/";
|
||||
if (url === "/" || url === "/index.html") {
|
||||
res.writeHead(200, { "Content-Type": "text/html" });
|
||||
res.end(html);
|
||||
return;
|
||||
}
|
||||
const filePath = resolve(projectDir, decodeURIComponent(url).replace(/^\//, ""));
|
||||
const rel = relative(projectDir, filePath);
|
||||
if (rel.startsWith("..") || isAbsolute(rel)) {
|
||||
res.writeHead(403);
|
||||
res.end();
|
||||
return;
|
||||
}
|
||||
if (existsSync(filePath)) {
|
||||
res.writeHead(200, { "Content-Type": getMimeType(filePath) });
|
||||
res.end(readFileSync(filePath));
|
||||
return;
|
||||
}
|
||||
res.writeHead(404);
|
||||
res.end();
|
||||
});
|
||||
|
||||
const port = await new Promise<number>((resolvePort, rejectPort) => {
|
||||
server.on("error", rejectPort); // register before listen to catch sync bind errors
|
||||
server.listen(0, () => {
|
||||
const addr = server.address();
|
||||
const p = typeof addr === "object" && addr ? addr.port : 0;
|
||||
if (!p) rejectPort(new Error("Failed to bind local HTTP server"));
|
||||
else resolvePort(p);
|
||||
});
|
||||
});
|
||||
|
||||
const savedPaths: string[] = [];
|
||||
|
||||
try {
|
||||
// 3. Launch headless Chrome
|
||||
const browser = await ensureBrowser();
|
||||
const puppeteer = await import("puppeteer-core");
|
||||
const chromeBrowser = await puppeteer.default.launch({
|
||||
headless: true,
|
||||
executablePath: browser.executablePath,
|
||||
args: [
|
||||
"--no-sandbox",
|
||||
"--disable-gpu",
|
||||
"--disable-dev-shm-usage",
|
||||
"--enable-webgl",
|
||||
"--use-gl=angle",
|
||||
"--use-angle=swiftshader",
|
||||
],
|
||||
});
|
||||
|
||||
try {
|
||||
const page = await chromeBrowser.newPage();
|
||||
await page.setViewport({ width: 1920, height: 1080 });
|
||||
|
||||
await page.goto(`http://127.0.0.1:${port}/`, {
|
||||
waitUntil: "domcontentloaded",
|
||||
timeout: 10000,
|
||||
});
|
||||
|
||||
// Wait for runtime to initialize and sub-compositions to load
|
||||
const timeoutMs = opts.timeout ?? 5000;
|
||||
await page
|
||||
.waitForFunction(() => !!(window as any).__timelines || !!(window as any).__playerReady, {
|
||||
timeout: timeoutMs,
|
||||
})
|
||||
.catch(() => {});
|
||||
|
||||
// Wait for sub-compositions to be mounted by the runtime
|
||||
// (they're fetched and injected asynchronously via data-composition-src)
|
||||
await page
|
||||
.waitForFunction(
|
||||
() => {
|
||||
const tls = (window as any).__timelines;
|
||||
if (!tls) return false;
|
||||
const keys = Object.keys(tls);
|
||||
// Wait until at least one sub-composition timeline is registered
|
||||
// (not counting "main" or empty registrations)
|
||||
return keys.length >= 2 || keys.some((k) => k !== "main");
|
||||
},
|
||||
{ timeout: timeoutMs },
|
||||
)
|
||||
.catch(() => {});
|
||||
|
||||
// Extra settle time for media, fonts, and animations to initialize
|
||||
await new Promise((r) => setTimeout(r, 1500));
|
||||
|
||||
// Get composition duration
|
||||
const duration = await page.evaluate(() => {
|
||||
const win = window as any;
|
||||
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) {
|
||||
const d = tls[key]?.duration;
|
||||
if (d != null) return typeof d === "function" ? d() : d;
|
||||
}
|
||||
}
|
||||
return 0;
|
||||
});
|
||||
|
||||
if (duration <= 0 && !opts.at?.length) {
|
||||
return [];
|
||||
}
|
||||
|
||||
// Calculate seek positions — explicit timestamps or evenly spaced
|
||||
const positions: number[] = opts.at?.length
|
||||
? opts.at
|
||||
: numFrames === 1
|
||||
? [duration / 2]
|
||||
: Array.from({ length: numFrames }, (_, i) => (i / (numFrames - 1)) * duration);
|
||||
|
||||
// Create output directory
|
||||
const snapshotDir = join(projectDir, "snapshots");
|
||||
mkdirSync(snapshotDir, { recursive: true });
|
||||
|
||||
// Seek and capture each frame
|
||||
for (let i = 0; i < positions.length; i++) {
|
||||
const time = positions[i]!;
|
||||
|
||||
await page.evaluate((t: number) => {
|
||||
const win = window as any;
|
||||
if (win.__player?.seek) {
|
||||
win.__player.seek(t);
|
||||
} else {
|
||||
const tls = win.__timelines;
|
||||
if (tls) {
|
||||
for (const key in tls) {
|
||||
if (tls[key]?.seek) {
|
||||
tls[key].pause();
|
||||
tls[key].seek(t);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}, time);
|
||||
|
||||
// Wait for rendering to settle after seek
|
||||
await page.evaluate(
|
||||
() =>
|
||||
new Promise<void>((r) => requestAnimationFrame(() => requestAnimationFrame(() => r()))),
|
||||
);
|
||||
await new Promise((r) => setTimeout(r, 200));
|
||||
|
||||
const timeLabel = opts.at?.length
|
||||
? `${time.toFixed(1)}s`
|
||||
: `${Math.round((time / duration) * 100)}pct`;
|
||||
const filename = `frame-${String(i).padStart(2, "0")}-at-${timeLabel}.png`;
|
||||
const framePath = join(snapshotDir, filename);
|
||||
|
||||
await page.screenshot({ path: framePath, type: "png" });
|
||||
savedPaths.push(`snapshots/${filename}`);
|
||||
}
|
||||
} finally {
|
||||
await chromeBrowser.close();
|
||||
}
|
||||
} finally {
|
||||
server.close();
|
||||
}
|
||||
|
||||
return savedPaths;
|
||||
}
|
||||
|
||||
export default defineCommand({
|
||||
meta: {
|
||||
name: "snapshot",
|
||||
description: "Capture key frames from a composition as PNG screenshots for visual verification",
|
||||
},
|
||||
args: {
|
||||
dir: {
|
||||
type: "positional",
|
||||
description: "Project directory",
|
||||
required: false,
|
||||
},
|
||||
frames: {
|
||||
type: "string",
|
||||
description: "Number of evenly-spaced frames to capture (default: 5)",
|
||||
default: "5",
|
||||
},
|
||||
at: {
|
||||
type: "string",
|
||||
description: "Comma-separated timestamps in seconds (e.g., --at 3.0,10.5,18.0)",
|
||||
},
|
||||
timeout: {
|
||||
type: "string",
|
||||
description: "Ms to wait for runtime to initialize (default: 5000)",
|
||||
default: "5000",
|
||||
},
|
||||
},
|
||||
async run({ args }) {
|
||||
const project = resolveProject(args.dir);
|
||||
const frames = parseInt(args.frames as string, 10) || 5;
|
||||
const timeout = parseInt(args.timeout as string, 10) || 5000;
|
||||
const atTimestamps = args.at
|
||||
? String(args.at)
|
||||
.split(",")
|
||||
.map((s) => parseFloat(s.trim()))
|
||||
.filter((n) => !isNaN(n))
|
||||
: undefined;
|
||||
|
||||
const label = atTimestamps
|
||||
? `${atTimestamps.length} frames at [${atTimestamps.map((t) => t.toFixed(1) + "s").join(", ")}]`
|
||||
: `${frames} frames`;
|
||||
console.log(`${c.accent("◆")} Capturing ${label} from ${c.accent(project.name)}`);
|
||||
|
||||
try {
|
||||
const paths = await captureSnapshots(project.dir, { frames, timeout, at: atTimestamps });
|
||||
|
||||
if (paths.length === 0) {
|
||||
console.log(
|
||||
`\n${c.error("✗")} Could not determine composition duration — no frames captured`,
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
console.log(`\n${c.success("◇")} ${paths.length} snapshots saved to snapshots/`);
|
||||
for (const p of paths) {
|
||||
console.log(` ${p}`);
|
||||
}
|
||||
} catch (err) {
|
||||
const msg = err instanceof Error ? err.message : String(err);
|
||||
console.error(`\n${c.error("✗")} Snapshot failed: ${msg}`);
|
||||
process.exit(1);
|
||||
}
|
||||
},
|
||||
});
|
||||
@ -21,6 +21,7 @@ const GROUPS: Group[] = [
|
||||
commands: [
|
||||
["init", "Scaffold a new composition project"],
|
||||
["add", "Install a block or component from the registry"],
|
||||
["capture", "Capture a website for video production"],
|
||||
["catalog", "Browse and install blocks and components"],
|
||||
["preview", "Start the studio for previewing compositions"],
|
||||
["render", "Render a composition to MP4 or WebM"],
|
||||
@ -30,6 +31,7 @@ const GROUPS: Group[] = [
|
||||
title: "Project",
|
||||
commands: [
|
||||
["lint", "Validate a composition for common mistakes"],
|
||||
["snapshot", "Capture key frames as PNG screenshots for visual verification"],
|
||||
["info", "Print project metadata"],
|
||||
["compositions", "List all compositions in a project"],
|
||||
["docs", "View inline documentation in the terminal"],
|
||||
|
||||
@ -128,7 +128,8 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
|
||||
'data-hyperframes-preview-runtime="1" src="/api/runtime.js"',
|
||||
);
|
||||
return html;
|
||||
} catch {
|
||||
} catch (err) {
|
||||
console.error("[studio] Bundle failed:", err);
|
||||
return null;
|
||||
}
|
||||
},
|
||||
|
||||
@ -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>
|
||||
|
||||
@ -326,11 +326,12 @@ export const gsapRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
|
||||
},
|
||||
|
||||
// gsap_css_transform_conflict
|
||||
({ styles, scripts }) => {
|
||||
({ styles, scripts, tags }) => {
|
||||
const findings: HyperframeLintFinding[] = [];
|
||||
const cssTranslateSelectors = new Map<string, string>();
|
||||
const cssScaleSelectors = new Map<string, string>();
|
||||
|
||||
// Check <style> blocks for transform rules
|
||||
for (const style of styles) {
|
||||
for (const [, selector, body] of style.content.matchAll(
|
||||
/([#.][a-zA-Z0-9_-]+)\s*\{([^}]+)\}/g,
|
||||
@ -345,6 +346,28 @@ export const gsapRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
|
||||
}
|
||||
}
|
||||
|
||||
// Also check inline style="..." attributes on tags
|
||||
for (const tag of tags) {
|
||||
const inlineStyle = readAttr(tag.raw, "style");
|
||||
if (!inlineStyle) continue;
|
||||
const tMatch = inlineStyle.match(/transform\s*:\s*([^;]+)/);
|
||||
if (!tMatch || !tMatch[1]) continue;
|
||||
const transformVal = tMatch[1].trim();
|
||||
// Derive selectors from the tag's id and all classes
|
||||
const id = readAttr(tag.raw, "id");
|
||||
const classes = readAttr(tag.raw, "class")?.split(/\s+/).filter(Boolean) ?? [];
|
||||
const selectors: string[] = [];
|
||||
if (id) selectors.push(`#${id}`);
|
||||
for (const cls of classes) selectors.push(`.${cls}`);
|
||||
if (selectors.length === 0) continue;
|
||||
for (const sel of selectors) {
|
||||
if (/translate/i.test(transformVal) && !cssTranslateSelectors.has(sel))
|
||||
cssTranslateSelectors.set(sel, transformVal);
|
||||
if (/scale/i.test(transformVal) && !cssScaleSelectors.has(sel))
|
||||
cssScaleSelectors.set(sel, transformVal);
|
||||
}
|
||||
}
|
||||
|
||||
if (cssTranslateSelectors.size === 0 && cssScaleSelectors.size === 0) return findings;
|
||||
|
||||
for (const script of scripts) {
|
||||
|
||||
@ -19,7 +19,26 @@ Before writing HTML, think at a high level:
|
||||
|
||||
For small edits (fix a color, adjust timing, add one element), skip straight to the rules.
|
||||
|
||||
When no `visual-style.md` or animation direction is provided, follow [house-style.md](./house-style.md) for motion defaults, sizing, and color palettes.
|
||||
### Visual Identity Gate
|
||||
|
||||
<HARD-GATE>
|
||||
Before writing ANY composition HTML, you MUST have a visual identity defined. Do NOT write compositions with default or generic colors.
|
||||
|
||||
Check in this order:
|
||||
|
||||
1. **DESIGN.md exists in the project?** → Read it. Use its exact colors, fonts, motion rules, and "What NOT to Do" constraints.
|
||||
2. **visual-style.md exists?** → Read it. Apply its `style_prompt_full` and structured fields. (Note: `visual-style.md` is a project-specific file. `visual-styles.md` is the style library with 8 named presets — different files.)
|
||||
3. **User named a style** (e.g., "Swiss Pulse", "dark and techy", "luxury brand")? → Read [visual-styles.md](./visual-styles.md) for the 8 named presets. Generate a minimal DESIGN.md with: `## Style Prompt` (one paragraph), `## Colors` (3-5 hex values with roles), `## Typography` (1-2 font families), `## What NOT to Do` (3-5 anti-patterns).
|
||||
4. **None of the above?** → Ask 3 questions before writing any HTML:
|
||||
- What's the mood? (explosive / cinematic / fluid / technical / chaotic / warm)
|
||||
- Light or dark canvas?
|
||||
- Any specific brand colors, fonts, or visual references?
|
||||
Then generate a minimal DESIGN.md from the answers.
|
||||
|
||||
Every composition must trace its palette and typography back to a DESIGN.md, visual-style.md, or explicit user direction. If you're reaching for `#333`, `#3b82f6`, or `Roboto` — you skipped this step.
|
||||
</HARD-GATE>
|
||||
|
||||
For motion defaults, sizing, entrance patterns, and easing — follow [house-style.md](./house-style.md). The house style handles HOW things move. The DESIGN.md handles WHAT things look like.
|
||||
|
||||
## Layout Before Animation
|
||||
|
||||
@ -314,6 +333,7 @@ Skip on small edits (fixing a color, adjusting one duration). Run on new composi
|
||||
- **[references/css-patterns.md](references/css-patterns.md)** — CSS+GSAP marker highlighting: highlight, circle, burst, scribble, sketchout. Deterministic, fully seekable. Read when adding visual emphasis to text.
|
||||
- **[references/typography.md](references/typography.md)** — Typography: font pairing, OpenType features, dark-background adjustments, font discovery script. **Always read** — every composition has text.
|
||||
- **[references/motion-principles.md](references/motion-principles.md)** — Motion design principles: easing as emotion, timing as weight, choreography as hierarchy, scene pacing, ambient motion, anti-patterns. Read when choreographing GSAP animations.
|
||||
- **[visual-styles.md](visual-styles.md)** — 8 named visual styles (Swiss Pulse, Velvet Standard, Deconstructed, Maximalist Type, Data Drift, Soft Signal, Folk Frequency, Shadow Cut) with hex palettes, GSAP easing signatures, and shader pairings. Read when user names a style or when generating DESIGN.md.
|
||||
- **[house-style.md](house-style.md)** — Default motion, sizing, and color palettes when no style is specified.
|
||||
- **[patterns.md](patterns.md)** — PiP, title cards, slide show patterns.
|
||||
- **[data-in-motion.md](data-in-motion.md)** — Data, stats, and infographic patterns.
|
||||
|
||||
211
skills/hyperframes/visual-styles.md
Normal file
211
skills/hyperframes/visual-styles.md
Normal file
@ -0,0 +1,211 @@
|
||||
# Visual Style Library
|
||||
|
||||
Named visual identities for HyperFrames videos. Each style is grounded in a real graphic design tradition. Use them to give your video a specific visual personality, not just generic "clean" or "bold."
|
||||
|
||||
**How to pick:** Match mood first, content second. Ask: _"What should the viewer FEEL?"_
|
||||
|
||||
**How to use:** Reference the style in your scene plan. Translate the style's principles into concrete composition decisions — palette choice, font selection, entrance patterns, transition type, ambient motion feel.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Style | Mood | Best for | Primary shader |
|
||||
| --------------- | --------------------- | ---------------------------------- | --------------------------------- |
|
||||
| Swiss Pulse | Clinical, precise | SaaS, data, dev tools, metrics | Cinematic Zoom or SDF Iris |
|
||||
| Velvet Standard | Premium, timeless | Luxury, enterprise, keynotes | Cross-Warp Morph |
|
||||
| Deconstructed | Industrial, raw | Tech launches, security, punk | Glitch or Whip Pan |
|
||||
| Maximalist Type | Loud, kinetic | Big announcements, launches | Ridged Burn |
|
||||
| Data Drift | Futuristic, immersive | AI, ML, cutting-edge tech | Gravitational Lens or Domain Warp |
|
||||
| Soft Signal | Intimate, warm | Wellness, personal stories, brand | Thermal Distortion |
|
||||
| Folk Frequency | Cultural, vivid | Consumer apps, food, communities | Swirl Vortex or Ripple Waves |
|
||||
| Shadow Cut | Dark, cinematic | Dramatic reveals, security, exposé | Domain Warp |
|
||||
|
||||
---
|
||||
|
||||
## 1. Swiss Pulse — Josef Müller-Brockmann
|
||||
|
||||
**Mood:** Clinical, precise | **Best for:** SaaS dashboards, developer tools, APIs, metrics
|
||||
|
||||
- Black (`#1a1a1a`), white, ONE accent — electric blue (`#0066FF`) or amber (`#FFB300`)
|
||||
- Helvetica or Inter Bold for headlines, Regular for labels. Numbers large (80–120px)
|
||||
- Grid-locked compositions. Every element snaps to an invisible 12-column grid
|
||||
- Animated counters count up from 0. Hard cuts, no decorative transitions
|
||||
- Transitions: Cinematic Zoom or SDF Iris (precise, geometric)
|
||||
|
||||
**GSAP signature:** `expo.out`, `power4.out`. Entries are fast and snap into place. Nothing floats.
|
||||
|
||||
```
|
||||
Swiss Pulse: Black/white + one electric accent. Grid-locked compositions.
|
||||
Numbers dominate the frame at 80-120px. Counter animations from 0.
|
||||
Hard cuts or geometric transitions. Nothing decorative.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Velvet Standard — Massimo Vignelli
|
||||
|
||||
**Mood:** Premium, timeless | **Best for:** Luxury products, enterprise software, keynotes, investor decks
|
||||
|
||||
- Black, white, ONE rich accent — deep navy (`#1a237e`) or gold (`#c9a84c`)
|
||||
- Thin sans-serif, ALL CAPS, wide letter-spacing (`0.15em+`)
|
||||
- Generous negative space. Symmetrical, centered, architectural precision
|
||||
- Slow, deliberate. Sequential reveals with long holds. No frantic motion
|
||||
- Transitions: Cross-Warp Morph (elegant, organic flow between scenes)
|
||||
|
||||
**GSAP signature:** `sine.inOut`, `power1`. Nothing snaps — everything glides with intention.
|
||||
|
||||
```
|
||||
Velvet Standard: Black, white, one rich accent. Thin ALL CAPS type with wide tracking.
|
||||
Generous negative space. Sequential reveals, long holds.
|
||||
Cross-Warp Morph transitions. Slow and deliberate — luxury takes its time.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Deconstructed — Neville Brody
|
||||
|
||||
**Mood:** Industrial, raw | **Best for:** Tech news, developer launches, security products, punk-energy reveals
|
||||
|
||||
- Dark grey (`#1a1a1a`), rust orange (`#D4501E`), raw white (`#f0f0f0`)
|
||||
- Type at angles, overlapping edges, escaping frames. Bold industrial weight
|
||||
- Gritty textures: scan-line effects, glitch artifacts baked into the design
|
||||
- Text SLAMS and SHATTERS. Letters scramble then snap to final position
|
||||
- Transitions: Glitch shader or Whip Pan (breaks the rules, feels aggressive)
|
||||
|
||||
**GSAP signature:** `back.out(2.5)`, `steps(8)`, `elastic.out(1.2, 0.4)`. Intentional irregularity.
|
||||
|
||||
```
|
||||
Deconstructed: Dark grey #1a1a1a + rust orange #D4501E. Type at angles, escaping frames.
|
||||
Scan-line glitch overlays. Text SLAMS and scrambles into place.
|
||||
Glitch shader transitions. Industrial and raw — nothing should feel polished.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Maximalist Type — Paula Scher
|
||||
|
||||
**Mood:** Loud, kinetic | **Best for:** Big product launches, milestone announcements, high-energy hype videos
|
||||
|
||||
- Bold saturated: red (`#E63946`), yellow (`#FFD60A`), black, white — maximum contrast
|
||||
- Text IS the visual. Overlapping type layers at different scales and angles, filling 50–80% of frame
|
||||
- Everything is kinetic: slamming, sliding, scaling. 2–3 second rapid-fire scenes
|
||||
- Text layered OVER footage — never empty backgrounds
|
||||
- Transitions: Ridged Burn (explosive, dramatic, impossible to ignore)
|
||||
|
||||
**GSAP signature:** `expo.out`, `back.out(1.8)`. Fast arrivals, hard stops.
|
||||
|
||||
```
|
||||
Maximalist Type: Red, yellow, black, white — max contrast. Text IS the visual.
|
||||
Overlapping at different scales, 50-80% of frame. Everything in motion.
|
||||
Ridged Burn transitions. No static moments — kinetic energy throughout.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Data Drift — Refik Anadol
|
||||
|
||||
**Mood:** Futuristic, immersive | **Best for:** AI products, ML platforms, data companies, speculative tech
|
||||
|
||||
- Iridescent: deep black (`#0a0a0a`), electric purple (`#7c3aed`), cyan (`#06b6d4`)
|
||||
- Thin futuristic sans-serif — floating, weightless, minimal
|
||||
- Fluid morphing compositions. Extreme scale shifts (micro → macro)
|
||||
- Particles coalesce into numbers. Light traces data paths through the frame
|
||||
- Transitions: Gravitational Lens or Domain Warp (otherworldly distortion)
|
||||
|
||||
**GSAP signature:** `sine.inOut`, `power2.out`. Smooth, continuous, organic. Nothing hard.
|
||||
|
||||
```
|
||||
Data Drift: Deep black #0a0a0a with electric purple #7c3aed and cyan #06b6d4.
|
||||
Thin futuristic type, minimal text. Particles coalesce into numbers.
|
||||
Gravitational Lens or Domain Warp transitions. Fluid, immersive, otherworldly.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Soft Signal — Stefan Sagmeister
|
||||
|
||||
**Mood:** Intimate, warm | **Best for:** Wellness brands, personal stories, lifestyle products, human-centered apps
|
||||
|
||||
- Warm amber (`#F5A623`), cream (`#FFF8EC`), dusty rose (`#C4A3A3`), sage green (`#8FAF8C`)
|
||||
- Handwritten-style or humanist serif fonts. Personal, lowercase, delicate
|
||||
- Close-up framing feel: single element fills the frame. Nothing feels corporate
|
||||
- Slow drifts and floats, never snaps. Soft organic motion throughout
|
||||
- Transitions: Thermal Distortion (warm, flowing, like heat shimmer)
|
||||
|
||||
**GSAP signature:** `sine.inOut`, `power1.inOut`. Everything breathes.
|
||||
|
||||
```
|
||||
Soft Signal: Warm amber, cream, dusty rose, sage green. Humanist or handwritten type.
|
||||
Single elements fill the frame — intimate, never corporate.
|
||||
Slow drifts and floats throughout. Thermal Distortion transitions.
|
||||
Nothing should feel hurried or polished.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Folk Frequency — Eduardo Terrazas
|
||||
|
||||
**Mood:** Cultural, vivid | **Best for:** Consumer apps, food platforms, community products, festive launches
|
||||
|
||||
- Vivid folk: hot pink (`#FF1493`), cobalt blue (`#0047AB`), sun yellow (`#FFE000`), emerald (`#009B77`)
|
||||
- Bold warm rounded type. Pattern and repetition — folk art rhythm and density
|
||||
- Layered compositions with rich visual texture. Every frame feels handcrafted
|
||||
- Colorful motion: elements bounce, pop, and spin into place with joy
|
||||
- Transitions: Swirl Vortex or Ripple Waves (hypnotic, celebratory)
|
||||
|
||||
**GSAP signature:** `back.out(1.6)`, `elastic.out(1, 0.5)`. Overshoots feel intentional.
|
||||
|
||||
```
|
||||
Folk Frequency: Hot pink #FF1493, cobalt blue, sun yellow, emerald. Bold rounded type.
|
||||
Pattern and repetition throughout. Layered, dense, handcrafted feeling.
|
||||
Swirl Vortex or Ripple Waves transitions. Joyful, celebratory energy.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Shadow Cut — Hans Hillmann
|
||||
|
||||
**Mood:** Dark, cinematic | **Best for:** Security products, dramatic reveals, investigative content, intense launches
|
||||
|
||||
- Near-monochrome: deep blacks (`#0a0a0a`), cold greys (`#3a3a3a`), stark white + blood red (`#C1121F`) or toxic green (`#39FF14`)
|
||||
- Sharp angular text like film noir title cards. Heavy contrast, no softness
|
||||
- Heavy shadow — elements emerge from darkness. Reveal is the narrative
|
||||
- Slow creeping push-ins, dramatic scale reveals, silence before the hit
|
||||
- Transitions: Domain Warp (dissolves reality itself before revealing the next scene)
|
||||
|
||||
**GSAP signature:** `power4.in` for exits, `power3.out` for dramatic reveals. The pause before the hit matters.
|
||||
|
||||
```
|
||||
Shadow Cut: Deep blacks #0a0a0a, cold greys, stark white + one accent (blood red or toxic green).
|
||||
Sharp angular type, film noir aesthetic. Elements emerge from darkness.
|
||||
Slow creeping push-ins. Domain Warp transitions. The reveal IS the story.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Mood → Style Guide
|
||||
|
||||
| If the content feels... | Use... |
|
||||
| ---------------------------------- | --------------- |
|
||||
| Data-driven, analytical, technical | Swiss Pulse |
|
||||
| Premium, enterprise, luxury | Velvet Standard |
|
||||
| Raw, punk, aggressive, rebellious | Deconstructed |
|
||||
| Hype, loud, high-energy launch | Maximalist Type |
|
||||
| AI, ML, speculative, futuristic | Data Drift |
|
||||
| Human, warm, personal, wellness | Soft Signal |
|
||||
| Cultural, fun, consumer, festive | Folk Frequency |
|
||||
| Dark, dramatic, intense, cinematic | Shadow Cut |
|
||||
|
||||
---
|
||||
|
||||
## Creating Custom Styles
|
||||
|
||||
These 8 styles are examples — not constraints. Create your own by:
|
||||
|
||||
1. **Name it** after a designer, art movement, or cultural reference
|
||||
2. **Palette**: 2-3 colors max. Declare explicit hex values
|
||||
3. **Typography**: One family, two weights. State the role of each
|
||||
4. **Motion rules**: How fast? Snappy or fluid? Overshoot or precision?
|
||||
5. **Transition**: Which shader matches the energy?
|
||||
6. **What NOT to do**: 2-3 explicit anti-patterns for this style
|
||||
|
||||
The pattern: **named style → palette → typography → motion rules → transition → avoids.**
|
||||
121
skills/website-to-hyperframes/SKILL.md
Normal file
121
skills/website-to-hyperframes/SKILL.md
Normal file
@ -0,0 +1,121 @@
|
||||
---
|
||||
name: website-to-hyperframes
|
||||
description: |
|
||||
Capture a website and create a HyperFrames video from it. Use when: (1) a user provides a URL and wants a video, (2) someone says "capture this site", "turn this into a video", "make a promo from my site", (3) the user wants a social ad, product tour, or any video based on an existing website, (4) the user shares a link and asks for any kind of video content. Even if the user just pastes a URL — this is the skill to use.
|
||||
---
|
||||
|
||||
# Website to HyperFrames
|
||||
|
||||
Capture a website, then produce a professional video from it.
|
||||
|
||||
Users say things like:
|
||||
|
||||
- "Capture https://... and make me a 25-second product launch video"
|
||||
- "Turn this website into a 15-second social ad for Instagram"
|
||||
- "Create a 30-second product tour from https://..."
|
||||
|
||||
The workflow has 7 steps. Each produces an artifact that gates the next.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Capture & Understand
|
||||
|
||||
**Read:** [references/step-1-capture.md](references/step-1-capture.md)
|
||||
|
||||
Run the capture, read the extracted data, and build a working summary using the write-down-and-forget method.
|
||||
|
||||
**Gate:** Print your site summary (name, top colors, fonts, key assets, one-sentence vibe).
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Write DESIGN.md
|
||||
|
||||
**Read:** [references/step-2-design.md](references/step-2-design.md)
|
||||
|
||||
Write a simple brand reference for the captured website. 6 sections, ~90 lines. This is a cheat sheet, not the creative plan — that comes in Step 4.
|
||||
|
||||
**Gate:** `DESIGN.md` exists in the project directory.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Write SCRIPT
|
||||
|
||||
**Read:** [references/step-3-script.md](references/step-3-script.md)
|
||||
|
||||
Write the narration script. The story backbone. Scene durations come from the narration, not from guessing.
|
||||
|
||||
**Gate:** `SCRIPT.md` exists in the project directory.
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Write STORYBOARD
|
||||
|
||||
**Read:** [references/step-4-storyboard.md](references/step-4-storyboard.md)
|
||||
|
||||
Write per-beat creative direction: mood, camera, animations, transitions, assets, depth layers, SFX. This is the creative north star — the document the engineer follows to build each composition.
|
||||
|
||||
**Gate:** `STORYBOARD.md` exists with beat-by-beat direction and an asset audit table.
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Generate VO + Map Timing
|
||||
|
||||
**Read:** [references/step-5-vo.md](references/step-5-vo.md)
|
||||
|
||||
Generate TTS audio, transcribe for word-level timestamps, and map timestamps to beats. Update STORYBOARD.md with real durations.
|
||||
|
||||
**Gate:** `narration.wav` (or .mp3) + `transcript.json` exist. Beat timings in STORYBOARD.md updated.
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Build Compositions
|
||||
|
||||
**Read:** The `/hyperframes` skill (invoke it — every rule matters)
|
||||
**Read:** [references/step-6-build.md](references/step-6-build.md)
|
||||
|
||||
Build each composition following the storyboard. After each one: self-review for layout, asset placement, and animation quality.
|
||||
|
||||
**Gate:** Every composition has been self-reviewed. No overlapping elements, no misplaced assets, no static images without motion.
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Validate & Deliver
|
||||
|
||||
**Read:** [references/step-7-validate.md](references/step-7-validate.md)
|
||||
|
||||
Lint, validate, preview. Create a HANDOFF.md for multi-session continuity.
|
||||
|
||||
**Gate:** `npx hyperframes lint` and `npx hyperframes validate` pass with zero errors.
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Video Types
|
||||
|
||||
| Type | Duration | Beats | Narration |
|
||||
| --------------------- | -------- | ----- | ---------------------- |
|
||||
| Social ad (IG/TikTok) | 10-15s | 3-4 | Optional hook sentence |
|
||||
| Product demo | 30-60s | 5-8 | Full narration |
|
||||
| Feature announcement | 15-30s | 3-5 | Full narration |
|
||||
| Brand reel | 20-45s | 4-6 | Optional, music focus |
|
||||
| Launch teaser | 10-20s | 2-4 | Minimal, high energy |
|
||||
|
||||
### Format
|
||||
|
||||
- **Landscape**: 1920x1080 (default)
|
||||
- **Portrait**: 1080x1920 (Instagram Stories, TikTok)
|
||||
- **Square**: 1080x1080 (Instagram feed)
|
||||
|
||||
### Reference Files
|
||||
|
||||
| File | When to read |
|
||||
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [step-1-capture.md](references/step-1-capture.md) | Step 1 — reading captured data |
|
||||
| [step-2-design.md](references/step-2-design.md) | Step 2 — writing DESIGN.md |
|
||||
| [step-3-script.md](references/step-3-script.md) | Step 3 — writing the narration script |
|
||||
| [step-4-storyboard.md](references/step-4-storyboard.md) | Step 4 — per-beat creative direction |
|
||||
| [step-5-vo.md](references/step-5-vo.md) | Step 5 — TTS, transcription, timing |
|
||||
| [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) |
|
||||
66
skills/website-to-hyperframes/references/step-1-capture.md
Normal file
66
skills/website-to-hyperframes/references/step-1-capture.md
Normal file
@ -0,0 +1,66 @@
|
||||
# Step 1: Capture & Understand
|
||||
|
||||
## Run the capture
|
||||
|
||||
```bash
|
||||
npx hyperframes capture <URL> -o captures/<project-name>
|
||||
```
|
||||
|
||||
No API keys required. The capture extracts design tokens, screenshots, fonts, and assets with DOM-context descriptions automatically.
|
||||
|
||||
**Optional:** Set `GEMINI_API_KEY` (or `GOOGLE_API_KEY`) in a `.env` file at the repo root for richer AI-powered image descriptions via Gemini 2.5 Flash vision. Free tier: 5 RPM; paid tier removes the bottleneck.
|
||||
|
||||
Wait for it to complete. Print how many screenshots, assets, sections, and fonts were extracted.
|
||||
|
||||
## Read and summarize
|
||||
|
||||
Read each file below. After reading each one, **write a 1-2 sentence summary** of what you learned. These summaries are your working memory — the raw file content may be cleared from context later.
|
||||
|
||||
### Must read (do not skip)
|
||||
|
||||
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 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.
|
||||
|
||||
3. **`extracted/visible-text.txt`** — Note the site's headline, tagline, key selling points, and any notable statistics or social proof.
|
||||
|
||||
4. **`extracted/asset-descriptions.md`** — One-line-per-file summary of all downloaded assets. Note which assets are most visually striking or useful for video (hero images, logos, product screenshots).
|
||||
|
||||
### Read if they exist
|
||||
|
||||
5. **`extracted/animations.json`** — Note if the site uses scroll-triggered animations, marquees, canvas/WebGL, or named CSS animations.
|
||||
|
||||
6. **`extracted/lottie-manifest.json`** — View each preview image at `assets/lottie/previews/` to see what the animations look like.
|
||||
|
||||
7. **`extracted/video-manifest.json`** — View each preview at `assets/videos/previews/` to see what each video shows.
|
||||
|
||||
8. **`extracted/shaders.json`** — If present, this contains the actual GLSL shader code that powers the site's WebGL visual effects (gradient waves, particle systems, noise fields). Read the fragment shaders to extract: color values used in gradients, noise algorithms, blend functions. You can recreate similar effects in your compositions using Canvas 2D or by embedding the shader patterns with a `<canvas>` + WebGL context. See the Canvas 2D and procedural art patterns in `techniques.md`.
|
||||
|
||||
### On-demand (read when building scenes)
|
||||
|
||||
9. **Individual images in `assets/`** — Use `asset-descriptions.md` as your index. View specific images when you need them for a beat.
|
||||
|
||||
10. **`extracted/assets-catalog.json`** — Use to find remote URLs when you need an asset that wasn't downloaded.
|
||||
|
||||
### For rich captures (30+ images)
|
||||
|
||||
Launch a sub-agent to view all images and SVGs:
|
||||
|
||||
> "Read every image in assets/ and every SVG in assets/svgs/. For each, write one line: filename — what it shows, dominant colors, approximate size. Return the complete catalog."
|
||||
|
||||
Use the sub-agent's catalog as your asset reference for the rest of the workflow.
|
||||
|
||||
## Gate
|
||||
|
||||
Print your site summary before proceeding to Step 2:
|
||||
|
||||
- **Site:** [name]
|
||||
- **Colors:** [top 3-5 HEX values with roles]
|
||||
- **Fonts:** [font families]
|
||||
- **Sections:** [count] sections, [count] headings, [count] CTAs
|
||||
- **Key assets:** [3-5 most useful assets for video]
|
||||
- **Vibe:** [one sentence describing the visual identity]
|
||||
128
skills/website-to-hyperframes/references/step-2-design.md
Normal file
128
skills/website-to-hyperframes/references/step-2-design.md
Normal file
@ -0,0 +1,128 @@
|
||||
# Step 2: Write DESIGN.md
|
||||
|
||||
DESIGN.md is a **brand cheat sheet** for the captured website. It encodes the visual identity so you can reference exact colors, fonts, and patterns while writing the storyboard and compositions.
|
||||
|
||||
DESIGN.md is NOT the creative plan. The STORYBOARD (Step 4) drives creative direction. DESIGN.md is a reference you consult, not a document you follow slavishly.
|
||||
|
||||
## The 6 Sections
|
||||
|
||||
### `## Overview`
|
||||
|
||||
3-4 sentences. Describe the visual identity factually: layout patterns (bento grid, logo wall, hero section), color strategy, typography tone, overall feel. Be precise, not poetic.
|
||||
|
||||
### `## Colors`
|
||||
|
||||
5-10 key colors with HEX values from tokens.json and their roles:
|
||||
|
||||
```
|
||||
- **Primary Surface**: `#020204` — deep black background
|
||||
- **Primary Content**: `#FFFFFF` — high-purity white for text and borders
|
||||
- **Accent Warm**: `#FB923C` — orange for CTAs and highlights
|
||||
```
|
||||
|
||||
Include semantic colors if the site uses color to differentiate product areas.
|
||||
|
||||
### `## Typography`
|
||||
|
||||
Font families with weights, roles, and any distinctive usage:
|
||||
|
||||
```
|
||||
- **Serif**: Cormorant Garamond (Italic). Major headings, brand identity.
|
||||
- **Monospace**: Geist Mono. Subheaders, labels, terminal readouts. High tracking (0.1-0.3em), all-caps.
|
||||
- **Sans-Serif**: Inter. Body copy, interface elements. Small sizes (9-14px).
|
||||
```
|
||||
|
||||
Include sizing hierarchy if notable (hero: 64px, section: 32px, body: 16px).
|
||||
|
||||
### `## Elevation`
|
||||
|
||||
One paragraph on depth strategy: Does the site use borders, shadows, glassmorphism, or flat color shifts? Reference specific patterns (e.g., "1px borders at white/10 opacity" or "layered backdrop-blur with thin borders").
|
||||
|
||||
### `## Components`
|
||||
|
||||
Name every notable UI component you see in the screenshot. Be specific:
|
||||
|
||||
- "Cinematic Accordion" not "Cards"
|
||||
- "Logo Marquee" not "Scrolling section"
|
||||
- "Glass Cards with grain overlay" not "Content containers"
|
||||
|
||||
For each, note the distinctive visual treatment (border-radius, spacing, hover behavior).
|
||||
|
||||
### `## Do's and Don'ts`
|
||||
|
||||
3-5 rules each, derived from what the site actually does and doesn't do:
|
||||
|
||||
```
|
||||
### Do's
|
||||
- Use thin subtle borders (white/10) to separate sections
|
||||
- Keep imagery desaturated with dark gradients for text readability
|
||||
|
||||
### Don'ts
|
||||
- Do not use bright solid background colors — stay in "The Void"
|
||||
- Do not use standard drop shadows — use radial glow or bloom effects
|
||||
- Do not use sharp high-speed animations — all motion should be fluid
|
||||
```
|
||||
|
||||
## Rules
|
||||
|
||||
- Use **exact HEX values** from tokens.json. Do not approximate.
|
||||
- Name components by what you see in the screenshot, not generic terms.
|
||||
- Keep it under 100 lines. This is a cheat sheet, not a design system document.
|
||||
- No "Style Prompt" section — the storyboard handles creative direction.
|
||||
- No "Assets" section — `asset-descriptions.md` already covers this.
|
||||
- No "Motion" section — the storyboard specifies motion per-beat.
|
||||
|
||||
## Example
|
||||
|
||||
This is a real DESIGN.md from a production capture (Soulscape 2026):
|
||||
|
||||
```markdown
|
||||
# Design System
|
||||
|
||||
## Overview
|
||||
|
||||
Soulscape 2026 is a cinematic, "high-signal" digital experience that positions itself as the vanguard of AI filmmaking. The visual personality is dark, technical, and premium, characterized by high-contrast "Flare" on "Void" (white on black) aesthetics. The layout is dense but organized, utilizing heavy horizontal layering and border-defined sections to evoke a wide-screen cinematic feel. Motion is a core tenet, with atmospheric grain overlays, shifting light leaks, and slow-moving marquees creating constant, breathing texture.
|
||||
|
||||
## Colors
|
||||
|
||||
- **Primary Surface**: `#020204` (Void) - Deep black for the entire background.
|
||||
- **Primary Content**: `#FFFFFF` (Flare) - High-purity white for typography and primary borders.
|
||||
- **Accent 1 (Warm)**: `#FB923C` - Orange for industry/executive tiers and primary CTAs.
|
||||
- **Accent 2 (Cool)**: `#60A5FA` - Blue for creative voices and summit-focused components.
|
||||
- **Subtle Overlays**: `rgba(255, 255, 255, 0.02)` to `0.08` for glass backgrounds.
|
||||
|
||||
## Typography
|
||||
|
||||
- **Serif**: Cormorant Garamond (Italic). Major headings and "Soul" brand identity. Classical cinematic contrast.
|
||||
- **Monospace**: Geist Mono. Subheaders, labels, terminal readouts. High tracking (0.1-0.3em), all-caps.
|
||||
- **Sans-Serif**: Inter. Body copy and interface elements. Small sizes (9-14px).
|
||||
|
||||
## Elevation
|
||||
|
||||
- **Glassmorphism**: Components use backdrop-filter blur(10px) with thin borders (1px solid rgba(255, 255, 255, 0.08)).
|
||||
- **Layering**: Depth via fixed global grain-overlay and localized light-leak gradients rather than box-shadows.
|
||||
- **Interaction**: Hover triggers subtle translateY(-5px) and increased border opacity.
|
||||
|
||||
## Components
|
||||
|
||||
- **Cinematic Accordion**: Expanding horizontal/vertical card system where panels expand from compressed state to reveal full-bleed imagery and large serif typography.
|
||||
- **HUD Explorer**: Floating mobile navigation trigger styled as a "Lens" with pulsing glow and terminal readouts.
|
||||
- **Slow Marquees**: Continuous horizontal tickers for partner logos and veteran listings.
|
||||
- **Glass Cards**: Content containers with subtle gradients, rounded corners (2.5rem), and high-contrast iconography.
|
||||
- **Grain & Flicker**: Global CSS noise filters and holographic flicker animations on UI labels.
|
||||
|
||||
## Do's and Don'ts
|
||||
|
||||
### Do's
|
||||
|
||||
- Use thin subtle borders (white/10) to separate sections rather than solid color changes.
|
||||
- Maintain high letter-spacing on all Geist Mono labels.
|
||||
- Use serif italics for emotional or visionary statements.
|
||||
- Keep imagery desaturated or stylized with dark gradients for readability.
|
||||
|
||||
### Don'ts
|
||||
|
||||
- Do not use bright solid background colors — the page must remain in "The Void."
|
||||
- Do not use standard drop shadows — use radial glow or bloom effects instead.
|
||||
- Do not use sharp high-speed animations — all motion should be fluid and breathing.
|
||||
```
|
||||
96
skills/website-to-hyperframes/references/step-3-script.md
Normal file
96
skills/website-to-hyperframes/references/step-3-script.md
Normal file
@ -0,0 +1,96 @@
|
||||
# Step 3: Write the Narration Script
|
||||
|
||||
**Before writing, re-read DESIGN.md** — specifically the Overview and Components sections. The script should reference real product features, real stats, and real components that the website highlights. Use exact numbers from `extracted/visible-text.txt`.
|
||||
|
||||
The script is the backbone. Everything downstream — scene durations, animation timing, beat pacing — comes from the narration. Write it before the storyboard.
|
||||
|
||||
Save as `SCRIPT.md` in the project directory.
|
||||
|
||||
## Pacing
|
||||
|
||||
- **2.5 words per second** is natural speaking pace
|
||||
- 15s = ~37 words. 30s = ~75 words. 60s = ~150 words
|
||||
- Leave room for pauses. Silence between sentences is a feature, not dead air
|
||||
- The script should feel SHORTER than the video — visual breathing room matters
|
||||
|
||||
## Tone
|
||||
|
||||
Write like a person, not a brochure:
|
||||
|
||||
- Use contractions: "it's", "you'll", "that's", "we've"
|
||||
- Vary sentence length — short punchy phrases mixed with longer flowing ones
|
||||
- Read it out loud. If it sounds robotic, rewrite it
|
||||
- Avoid jargon unless the audience expects it
|
||||
|
||||
## Number Pronunciation
|
||||
|
||||
Write what you want the voice to say. TTS reads literally.
|
||||
|
||||
| On the website | Write in script as |
|
||||
| -------------- | --------------------------------- |
|
||||
| 135+ | more than one hundred thirty five |
|
||||
| $1.9T | nearly two trillion dollars |
|
||||
| 99.999% | ninety nine point nine percent |
|
||||
| 200M+ | over two hundred million |
|
||||
| 10x | ten times |
|
||||
| API | A P I |
|
||||
| stripe.com | stripe dot com |
|
||||
|
||||
The visual can show the exact figure while the voice rounds it.
|
||||
|
||||
## Structure
|
||||
|
||||
For product videos from a website capture:
|
||||
|
||||
1. **Hook** — what's surprising or impressive about this product? A bold claim, a provocative question, a contrast, or a striking number. This is the opening line. **Vary the hook type** — don't default to a stat every time.
|
||||
2. **Story** — what does the product do? Who uses it? Keep it concrete.
|
||||
3. **Proof** — stats, customer names, social proof. Real numbers from the website.
|
||||
4. **CTA** — what should the viewer do? "Start building at stripe dot com."
|
||||
|
||||
Not every video needs all four. A 15-second social ad might be Hook + Proof + CTA. A 60-second product tour uses all four with more Story.
|
||||
|
||||
## The Opening Line
|
||||
|
||||
The most important sentence in the video. It must create tension, curiosity, or surprise in the first 3 seconds.
|
||||
|
||||
Patterns that work:
|
||||
|
||||
- **A bold claim**: "The financial infrastructure that powers the internet economy."
|
||||
- **A question that provokes**: "What if your database could think?"
|
||||
- **A contrast**: "Your AI agent already knows how to make videos. It just needs the right format."
|
||||
- **A number that shocks**: "Nearly two trillion dollars." (Use sparingly — not every video should open with a stat.)
|
||||
|
||||
If the opening is generic ("Welcome to Stripe" / "Introducing our product"), start over.
|
||||
|
||||
## Example
|
||||
|
||||
From a 62-second product launch video (team reference):
|
||||
|
||||
```
|
||||
Your AI agent already knows how to make videos.
|
||||
It just needs the right format.
|
||||
|
||||
This is Hyperframes. An open source framework. HTML in, video out.
|
||||
|
||||
A div is a keyframe. Data attributes are your timeline.
|
||||
CSS is your look. G-Sap is your animation engine.
|
||||
|
||||
Anything a browser can render can be a frame in your video.
|
||||
|
||||
CSS animations. G-Sap. Lottie. Shaders. Three.js.
|
||||
|
||||
Drop in music, sound effects, footage — it all composes together.
|
||||
|
||||
No new framework for the agent to learn.
|
||||
Just HTML.
|
||||
|
||||
The agent writes it. The renderer captures every frame as MP4.
|
||||
It's deterministic. Identical outputs, every time.
|
||||
|
||||
Give your agent the CLI. Tell it what to make.
|
||||
Watch it build.
|
||||
|
||||
Hyperframes. Go make something.
|
||||
```
|
||||
|
||||
Note: ~140 words for 62 seconds — that's 2.3 words/sec, leaving room for pauses and visual breathing.
|
||||
222
skills/website-to-hyperframes/references/step-4-storyboard.md
Normal file
222
skills/website-to-hyperframes/references/step-4-storyboard.md
Normal file
@ -0,0 +1,222 @@
|
||||
# Step 4: Write the Storyboard
|
||||
|
||||
**Before writing anything, fully re-read these files:**
|
||||
|
||||
- **DESIGN.md** — your color palette, font rules, components, Do's/Don'ts. Every creative decision must be grounded in this brand identity. If it says "white backgrounds with purple accent" — plan light scenes, not dark moody ones.
|
||||
- **`extracted/asset-descriptions.md`** — read EVERY line. This is your menu of available visuals. Each line describes what the image actually shows (e.g., "translucent ribbons in orange, pink, and purple on white background" or "a high-speed train under a dark starry sky"). Use these descriptions to decide which assets belong in which beat. Assets you don't understand from the description — view them directly before assigning.
|
||||
- **[techniques.md](techniques.md)** — 10 visual techniques (SVG path drawing, Canvas 2D art, CSS 3D, per-word typography, Lottie, video compositing, typing effect, variable fonts, MotionPath, velocity transitions). Pick 2-3 per beat and specify them in the storyboard.
|
||||
|
||||
The storyboard is the creative north star. It tells the engineer exactly what to build for each beat — mood, camera, animations, transitions, assets, sound. Write it as if you're briefing a motion designer who's never seen the website.
|
||||
|
||||
Save as `STORYBOARD.md` in the project directory.
|
||||
|
||||
---
|
||||
|
||||
## Global Direction
|
||||
|
||||
Every STORYBOARD.md starts with global settings:
|
||||
|
||||
```markdown
|
||||
**Format:** 1920×1080
|
||||
**Audio:** [TTS provider] voiceover + underscore + SFX
|
||||
**VO direction:** [voice character — e.g., "mid-age male, calm confident delivery,
|
||||
Apple keynote register — economy of words, silence between sentences is a feature"]
|
||||
**Style basis:** DESIGN.md (brand colors, fonts, components from the captured site)
|
||||
```
|
||||
|
||||
**Global guardrails** (adapt to the brand):
|
||||
|
||||
- Push color presence. Muted is fine, flat is not. Every beat should have at least one color that pulls your eye.
|
||||
- Motion should be visible and intentional. Err toward more movement than feels safe — subtle reads as static at 30fps.
|
||||
- Use as many captured assets as the creative vision allows. Scatter framework icons around a dashboard. Layer enterprise photos behind stats. Use product screenshots as floating cards. The assets exist — use them generously.
|
||||
- Aim for 8-10 visual elements per beat, not 2-3. A great beat has: background texture, midground content, foreground accents, floating decorative elements, animated icons, SVG path drawings, particle effects, typographic details. It should feel DENSE and alive.
|
||||
- Use at least 2-3 different techniques from techniques.md per beat — not across the whole video, per beat. Don't default to basic fade/scale/opacity — mix in SVG path drawing, CSS 3D transforms, typing effects, counter animations, canvas procedural art. Each beat should feel like its own visual world.
|
||||
|
||||
**Underscore/music direction** (if applicable):
|
||||
|
||||
- Describe the mood, reference artists, when it swells or drops
|
||||
- Example: "Minimal electronic. Warm sustained pad already playing when the video starts. Sits underneath everything, never competing with VO. Swells gently during the flex section, drops to near-nothing for the comparison, resolves on a final chord."
|
||||
|
||||
---
|
||||
|
||||
## Asset Audit
|
||||
|
||||
Before writing any beats, audit every captured asset. Print this table:
|
||||
|
||||
| Asset | Type | Assign to Beat | Role |
|
||||
| ------------------------------ | ---------- | -------------- | ------------------------------------- |
|
||||
| wave-fallback-desktop.png | Hero image | Beat 1 | Full-bleed animated background |
|
||||
| enterprise-accordion-hertz.png | Photo | Beat 3 | Enterprise credibility, Ken Burns pan |
|
||||
| stripe-logo.svg | SVG | Beat 1, Beat 5 | Brand mark opener + closer |
|
||||
| datavizstatic3x.png | Data viz | Beat 3 | Supporting visual behind stats |
|
||||
| icon-3.svg | Icon | SKIP | Decorative, too small |
|
||||
|
||||
**Minimum utilization:**
|
||||
|
||||
- At least 50% of product screenshots and hero images must appear
|
||||
- Brand logo appears in the first AND last beat
|
||||
- The site's signature visual (gradient wave, hero illustration, key product UI) must appear — it's the most recognizable brand element
|
||||
- Maximum 2 consecutive text-only beats. The 3rd must contain a visual asset
|
||||
- Opening beat must contain a visual asset, not text-only
|
||||
|
||||
---
|
||||
|
||||
## Per-Beat Direction
|
||||
|
||||
Each beat is a WORLD, not a layout. Before writing CSS specs and GSAP instructions, describe what the viewer EXPERIENCES. The difference between a great storyboard and a mediocre one:
|
||||
|
||||
**Mediocre:** "Dark navy background. '$1.9T' in white, 280px. Logo top-left. Wave image bottom-right."
|
||||
**Great:** "Camera is already mid-flight over a vast dark canvas. The gradient wave sweeps across the frame like aurora borealis — alive, shifting. '$1.9T' SLAMS into existence with such force the wave ripples in response. This isn't a slide — it's a moment."
|
||||
|
||||
The first describes pixels. The second describes an experience. Write the second, then figure out the pixels.
|
||||
|
||||
Each beat should have:
|
||||
|
||||
### Concept
|
||||
|
||||
The big idea for this beat in 2-3 sentences. What visual WORLD are we in? What metaphor drives it? What should the viewer FEEL? This is the most important part — everything else flows from it.
|
||||
|
||||
### VO cue
|
||||
|
||||
Which narration line plays over this beat.
|
||||
|
||||
### Visual description
|
||||
|
||||
What the viewer sees — described cinematically, not as CSS specs. Use camera language (pan, zoom, drift, settle). Describe at least 5 visual elements, not just text + background. Think in layers — what's moving in the foreground, midground, background simultaneously?
|
||||
|
||||
### Mood direction
|
||||
|
||||
Cultural and design references, not hex codes:
|
||||
|
||||
- "Geometric, rhythmic, precise. Think Josef Albers or Bauhaus color studies."
|
||||
- "Warm workspace. Nice notebook energy, not technical blueprint."
|
||||
- "Cinematic title sequence. The kind of opening where you lean forward."
|
||||
|
||||
### Assets
|
||||
|
||||
Which captured files to use, referenced by filename:
|
||||
|
||||
- "Background: `assets/wave-fallback-desktop.png` — full-bleed, slow zoom 1→1.04 over beat duration"
|
||||
- "Logo: `assets/svgs/stripe-logo.svg` — centered, fades in at 0.5s"
|
||||
- "Enterprise photo: `assets/enterprise-accordion-hertz.png` — Ken Burns pan, 70% opacity overlay"
|
||||
|
||||
### Animation choreography
|
||||
|
||||
Specific motion verbs per element — not "it animates in" but HOW:
|
||||
|
||||
| Energy | Verbs | Example |
|
||||
| ------------- | --------------------------------------------- | ------------------------------------- |
|
||||
| High impact | SLAMS, CRASHES, PUNCHES, STAMPS, SHATTERS | "$1.9T" SLAMS in from left at -5° |
|
||||
| Medium energy | CASCADE, SLIDES, DROPS, FILLS, DRAWS | Three cards CASCADE in staggered 0.3s |
|
||||
| Low energy | types on, FLOATS, morphs, COUNTS UP, fades in | Counter COUNTS UP from 0 to 135K |
|
||||
|
||||
Every element gets a verb. If you can't name the verb, the element is not yet designed.
|
||||
|
||||
### Transition
|
||||
|
||||
How this beat hands off to the next. Specify the type and parameters.
|
||||
|
||||
**CSS transitions** (choose from `skills/hyperframes/references/transitions/catalog.md`):
|
||||
|
||||
- Velocity-matched upward: exit `y:-150, blur:30px, 0.33s power2.in` → entry `y:150→0, blur:30px→0, 1.0s power2.out`
|
||||
- Whip pan: exit `x:-400, blur:24px, 0.3s power3.in` → entry `x:400→0, blur:24px→0, 0.3s power3.out`
|
||||
- Blur through: exit `blur:20px, 0.3s` → entry `blur:20px→0, 0.25s power3.out`
|
||||
- Zoom through: exit `scale:1→1.2, blur:20px, 0.2s power3.in` → entry `scale:0.75→1, blur:20px→0, 0.5s expo.out`
|
||||
- Hard cut / smash cut (for rapid-fire sequences)
|
||||
|
||||
**Shader transitions** (choose from `skills/hyperframes/references/transitions/shader-transitions.md`):
|
||||
|
||||
- Cross-Warp Morph (organic, versatile) — 0.5-0.8s, power2.inOut
|
||||
- Cinematic Zoom (professional momentum) — 0.4-0.6s, power2.inOut
|
||||
- Gravitational Lens (otherworldly) — 0.6-1.0s, power2.inOut
|
||||
- Glitch (aggressive, high energy) — 0.3-0.5s
|
||||
- See `skills/hyperframes/references/transitions/shader-setup.md` for the full WebGL boilerplate
|
||||
|
||||
**How velocity-matched CSS transitions work:**
|
||||
Exit the outgoing beat with an accelerating ease (power2.in or power3.in) plus a blur ramp. Enter the incoming beat with a decelerating ease (power2.out or power3.out) plus blur clear. The fastest point of both easing curves meets at the cut — the viewer perceives continuous camera motion, not two discrete animations. Match exit velocity to entry velocity within ~5% tolerance.
|
||||
|
||||
### Depth layers
|
||||
|
||||
What's in foreground, midground, and background. Every beat should have at least 2 layers:
|
||||
|
||||
- "BG: dark navy fill + subtle radial glow. MG: stat cards with drop shadow. FG: brand logo bottom-right."
|
||||
|
||||
### SFX cues
|
||||
|
||||
What sounds at what moment:
|
||||
|
||||
- "On the capture pulse — a soft, warm analog shutter click."
|
||||
- "Left side carries a faint low drone. On fold: drone cuts. Silence. Then a single clean chime."
|
||||
|
||||
---
|
||||
|
||||
## Production Architecture
|
||||
|
||||
Include this file tree at the bottom of the storyboard:
|
||||
|
||||
```
|
||||
project/
|
||||
├── index.html root — VO + underscore + beat orchestration
|
||||
├── DESIGN.md brand reference (from Step 2)
|
||||
├── SCRIPT.md narration text (from Step 3)
|
||||
├── STORYBOARD.md THIS FILE — creative north star
|
||||
├── transcript.json word-level timestamps (from Step 5)
|
||||
├── narration.wav TTS audio (from Step 5)
|
||||
├── captures/<name>/ captured website data
|
||||
└── compositions/
|
||||
├── beat-1-hook.html
|
||||
├── beat-2-features.html
|
||||
├── ...
|
||||
└── captions.html
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example: Beat-by-Beat Format
|
||||
|
||||
Here are three beats from a production storyboard showing the level of detail expected.
|
||||
|
||||
### BEAT 1 — COLD OPEN (0:00–0:05)
|
||||
|
||||
**VO:** "Your AI agent already knows how to make videos."
|
||||
|
||||
**Concept:** We're already in motion when the video starts. No title card, no fade from black. We're mid-flight over an infinite creative workspace — dozens of living compositions scattered below us like a city seen from a drone. Each one is alive, running a different animation. The message is clear before any words: this tool makes videos. Lots of them.
|
||||
|
||||
**Visual:** Slow smooth diagonal drift over a vast canvas (3600×2200px plane). Scattered across it: 25 composition cards at organic angles (±5-15° rotation), soft shadows, thin borders. Each card contains a DIFFERENT running animation — kinetic type, gradient morph, data viz, particle system, logo assembly, SVG drawing, shader noise, 3D rotating object. Depth-of-field: close cards slightly blurred, focal sweet-spot in mid-distance, far cards smaller and desaturated.
|
||||
|
||||
**Camera:** Diagonal drift top-left to bottom-right, slight 2-3° rotation over 5s. power1.inOut ease. Zoom accelerates in final second as we approach one specific card.
|
||||
|
||||
**Assets:** Product screenshots and logo on cards. Each card is a mini-composition with its own animation.
|
||||
|
||||
**SFX:** Ambient warmth pad already playing. Faint textured hum — overhearing creative activity from a distance.
|
||||
|
||||
---
|
||||
|
||||
### BEAT 5 — THE THESIS (0:20–0:24)
|
||||
|
||||
**VO:** "Anything a browser can render can be a frame in your video."
|
||||
|
||||
**Mood:** Big statement. This sentence gets its own canvas. Clean, spacious, typographic.
|
||||
|
||||
**Visual:** Words appear as staggered kinetic typography. "Anything a browser can render" — distinctive serif, gentle fade + rise (y: 24px → 0, opacity 0 → 1, 0.4s, power2.out). Held beat — one second of stillness. "can be a frame in your video." appears below. As the final word lands, the entire text pulses once — a brief warm flash, subtle scale bump to 101%.
|
||||
|
||||
**Transition OUT:** Whip pan left — x:-400, blur:24px, opacity:0.4, 0.3s power3.in
|
||||
|
||||
**SFX:** Silence under the first line. On the capture pulse — a soft analog shutter click.
|
||||
|
||||
---
|
||||
|
||||
### BEAT 7 — THE CONTRAST (0:38–0:44)
|
||||
|
||||
**VO:** "No new framework for the agent to learn. Just HTML."
|
||||
|
||||
**Mood:** Clean comparison. Light base. Two worlds side by side.
|
||||
|
||||
**Visual:** Left half: dense code, small, compressed, overwhelming. Scrolls slowly upward. Slightly desaturated. Right half: spacious HTML, syntax-highlighted, generous line spacing, inviting. On "Just HTML." — the left side folds inward along its center line, like a book closing. The right side expands to fill the frame. Warm glow rises behind it.
|
||||
|
||||
**Transition IN:** Zoom through — scale 0.75→1, blur 20px→0, 0.5s expo.out
|
||||
**Transition OUT:** Velocity-matched upward — y:-150, blur:30px, 0.33s power2.in
|
||||
|
||||
**Assets:** Real framework code on the left (actual content, not lorem ipsum). Real HyperFrames HTML on the right.
|
||||
|
||||
**SFX:** Left side carries a faint low drone. On fold: drone cuts. Silence. Then a single clean chime as the right side expands.
|
||||
40
skills/website-to-hyperframes/references/step-5-vo.md
Normal file
40
skills/website-to-hyperframes/references/step-5-vo.md
Normal file
@ -0,0 +1,40 @@
|
||||
# Step 5: Generate VO + Map Timing
|
||||
|
||||
## Audition voices
|
||||
|
||||
Never use the first voice you find. Audition 2-3 voices with the first sentence of SCRIPT.md:
|
||||
|
||||
- **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?
|
||||
|
||||
## Generate full narration
|
||||
|
||||
Generate the full script as `narration.wav` (or `.mp3`) in the project directory.
|
||||
|
||||
## Transcribe for word-level timestamps
|
||||
|
||||
```bash
|
||||
npx hyperframes transcribe narration.wav
|
||||
```
|
||||
|
||||
Produces `transcript.json` with `[{ text, start, end }]` for every word. These timestamps are the source of truth for all beat durations.
|
||||
|
||||
## Map timestamps to beats
|
||||
|
||||
Go through STORYBOARD.md beat by beat. For each beat:
|
||||
|
||||
1. Find the first word of that beat's VO cue in `transcript.json`
|
||||
2. Find the last word of that beat's VO cue
|
||||
3. Set `beat.start = firstWord.start`, `beat.end = lastWord.end`
|
||||
4. Add 0.3-0.5s padding at the end for visual breathing room
|
||||
|
||||
Update STORYBOARD.md with real durations. Replace estimated times (e.g., "0:00-0:05") with actual timestamps (e.g., "0.00-3.21s").
|
||||
|
||||
Beat boundaries land on word onsets — hard cuts to the VO.
|
||||
|
||||
## Update index.html
|
||||
|
||||
Update each scene slot's `data-start` and `data-duration` to match the real beat timings from the transcript. Also update the total composition duration and audio element duration.
|
||||
162
skills/website-to-hyperframes/references/step-6-build.md
Normal file
162
skills/website-to-hyperframes/references/step-6-build.md
Normal file
@ -0,0 +1,162 @@
|
||||
# Step 6: Build Compositions
|
||||
|
||||
**Before building, fully re-read these files:**
|
||||
|
||||
- **DESIGN.md** — your color palette, fonts, components, and Do's/Don'ts. Every composition must use EXACT hex colors and font families from this file. If it says "white backgrounds" — use white, not dark.
|
||||
- **STORYBOARD.md** — the beat-by-beat plan you're executing. Each beat specifies assets, animations, transitions, and which techniques to use.
|
||||
- **`extracted/asset-descriptions.md`** — when the storyboard assigns an asset to a beat, re-read the description to understand what it shows and how to position/style it correctly.
|
||||
- **[techniques.md](techniques.md)** — code patterns for the 10 visual techniques. When the storyboard says "SVG path drawing" or "per-word kinetic typography" — read the code pattern from this file and adapt it.
|
||||
- **transcript.json** — word-level timestamps that drive scene durations.
|
||||
|
||||
**Split the work: spawn a sub-agent for each beat.** By this step your context is full of captured data, DESIGN.md, SCRIPT, STORYBOARD, and transcript. Building compositions on top of all that means the detailed rules below compete with thousands of tokens of prior work. Each sub-agent gets a fresh context focused on one beat — dramatically better output.
|
||||
|
||||
**How to dispatch each sub-agent:**
|
||||
|
||||
Pass file PATHS, not file contents. The #1 failure mode is reading an asset file and pasting its SVG/image data into the sub-agent prompt. The sub-agent then uses inline content instead of referencing the file on disk. Same with fonts — pass the local woff2 path, don't substitute Google Fonts.
|
||||
|
||||
```
|
||||
Build the composition for beat 1. Save to compositions/beat-1-hook.html.
|
||||
|
||||
STORYBOARD for this beat:
|
||||
[paste the beat section from STORYBOARD.md]
|
||||
|
||||
ASSETS — reference by path, do NOT read/inline the file contents:
|
||||
- Logo: <img src="../assets/favicon.svg"> (top-left, 40x40px)
|
||||
- Hero image: <img src="../assets/hero-bg.png"> (full-bleed background)
|
||||
- Noise texture: ../assets/noise.png (full-frame overlay, 3% opacity)
|
||||
|
||||
FONTS — use @font-face with the captured font files, NOT Google Fonts:
|
||||
@font-face { font-family: 'BrandFont'; src: url('../assets/fonts/BrandFont-Regular.woff2'); }
|
||||
|
||||
Read DESIGN.md for exact colors and Do's/Don'ts.
|
||||
Read techniques.md for animation code patterns.
|
||||
Invoke /hyperframes for composition structure rules.
|
||||
```
|
||||
|
||||
After each sub-agent finishes, verify the composition references `../assets/` — if it used inline SVGs or Google Fonts instead of the captured files, fix it before moving on.
|
||||
|
||||
Invoke the `/hyperframes` skill first — it has the rules for data attributes, timeline contracts, deterministic rendering, and layout. Everything below supplements those rules, not replaces them.
|
||||
|
||||
---
|
||||
|
||||
## Per-Composition Process
|
||||
|
||||
For each beat in the storyboard:
|
||||
|
||||
### 1. Read the beat's storyboard section
|
||||
|
||||
Know the mood, visual description, assets, animation choreography, transition, and SFX before writing any HTML.
|
||||
|
||||
### 2. Build the static end-state first
|
||||
|
||||
Position every element where it should be at its **most visible moment** — the frame where everything is fully entered and correctly placed. Write this as static HTML+CSS. No GSAP yet.
|
||||
|
||||
This is the "Layout Before Animation" principle from the compose skill. The CSS position is the ground truth. Animations describe the journey to and from it.
|
||||
|
||||
### 3. Verify the static layout
|
||||
|
||||
Look at it. Check:
|
||||
|
||||
- Are elements where the storyboard says they should be?
|
||||
- Are depth layers present (foreground / midground / background)?
|
||||
- Do any elements overlap unintentionally?
|
||||
- Are assets sized correctly? (hero images should fill 50-70% of frame, not sit at 100x100px)
|
||||
|
||||
### 4. Add entrance animations
|
||||
|
||||
Use `gsap.from()` — animate FROM offscreen/invisible TO the CSS position. The CSS position is where the element ends up.
|
||||
|
||||
### 5. Add mid-scene activity
|
||||
|
||||
Every visible element must have continuous motion. A still image on a still background is a JPEG with a progress bar.
|
||||
|
||||
| Element type | Mid-scene activity |
|
||||
| ---------------------- | ------------------------------------------------ |
|
||||
| Image / screenshot | Slow zoom (scale 1→1.03), slow pan, or Ken Burns |
|
||||
| Stat / number | Counter animates from 0 to target |
|
||||
| Logo grid | Subtle shimmer sweep, or gentle scale pulse |
|
||||
| Any persistent element | Subtle float (y ±4-6px, sine.inOut, yoyo) |
|
||||
|
||||
### 6. Add exit / transition
|
||||
|
||||
Check the storyboard's transition specification for this beat:
|
||||
|
||||
- **CSS transition**: implement the exit animation (e.g., `y:-150, blur:30px, 0.33s power2.in`). The next composition handles its own entry.
|
||||
- **Shader transition**: no exit animation needed — the shader handles the blend. Read `skills/hyperframes/references/transitions/shader-setup.md` for the full WebGL boilerplate and `skills/hyperframes/references/transitions/shader-transitions.md` for the fragment shader. Copy the FULL boilerplate — a simplified version produces black screens.
|
||||
- **Hard cut**: no exit animation. The scene simply ends.
|
||||
|
||||
For all CSS transition types and their GSAP implementations, read `skills/hyperframes/references/transitions/catalog.md`.
|
||||
|
||||
### 7. Asset cross-reference
|
||||
|
||||
Before self-review, verify you actually used the assets you planned to:
|
||||
|
||||
1. Open STORYBOARD.md and find this beat's asset assignments
|
||||
2. List every asset that was assigned to this beat
|
||||
3. Search the composition HTML for each filename (e.g., grep for "wave-fallback-desktop")
|
||||
4. If any assigned asset is missing from the HTML, add it now
|
||||
5. Check for the inline anti-pattern: if the HTML contains `<svg xmlns=` or `data:image/` but no `../assets/` references, the assets were inlined instead of referenced. Replace inline content with `<img src="../assets/filename.svg">`
|
||||
6. Check fonts: if the HTML uses `fonts.googleapis.com` but there are captured fonts in `assets/fonts/`, replace with `@font-face` pointing to the local files
|
||||
|
||||
This step catches the two most common failures: compositions ending up text-only, and assets being inlined instead of file-referenced.
|
||||
|
||||
### 8. Self-review
|
||||
|
||||
After building the composition, check WITH ACTUAL CODE:
|
||||
|
||||
- [ ] Asset cross-reference passed (step 7 above — every assigned asset is in the HTML)
|
||||
- [ ] Elements are where the storyboard says they should be (no misplacement)
|
||||
- [ ] No overlapping text (text covering text is always ugly)
|
||||
- [ ] Depth layers present (2+ layers minimum)
|
||||
- [ ] Every visible element has mid-scene activity (not just entrance + exit)
|
||||
- [ ] Font sizes above minimum (20px body text, 16px labels — sub-14px is unreadable after encoding)
|
||||
- [ ] No full-screen dark linear gradients (H.264 creates visible banding — use solid + localized radial glows)
|
||||
- [ ] Timeline registered: `window.__timelines["comp-id"] = tl`
|
||||
- [ ] Colors match DESIGN.md exactly (paste the HEX value, don't approximate)
|
||||
|
||||
**If `skills/hyperframes-animation-map/` is installed**, run it:
|
||||
|
||||
```bash
|
||||
node skills/hyperframes-animation-map/scripts/animation-map.mjs <composition-dir>
|
||||
```
|
||||
|
||||
Read the summaries. Fix every flag: offscreen, collision, invisible, pacing issues.
|
||||
|
||||
### 9. Move to the next composition
|
||||
|
||||
---
|
||||
|
||||
## Asset Presentation
|
||||
|
||||
Never embed a raw flat image. Every image must have motion treatment:
|
||||
|
||||
- **Perspective tilt**: use `gsap.set(el, { transformPerspective: 1200, rotationY: -8 })` + `box-shadow` — creates depth. Do NOT use CSS `transform: perspective(...)` as GSAP will overwrite it.
|
||||
- **Slow zoom (Ken Burns)**: GSAP `scale: 1` → `1.04` over beat duration — makes photos cinematic
|
||||
- **Device frame**: Wrap in a laptop/phone shape using CSS `border-radius` and `box-shadow`
|
||||
- **Floating UI**: Extract a key element and animate it at a different z-depth for parallax
|
||||
- **Scroll reveal**: Clip the image to a viewport window and animate `y` position
|
||||
|
||||
---
|
||||
|
||||
## Audio Wiring
|
||||
|
||||
In the root `index.html`:
|
||||
|
||||
- **Narration**: `<audio id="narration" src="narration.wav" data-start="0" data-duration="..." data-track-index="0" data-volume="1">`
|
||||
- **Underscore/music** (if storyboard specifies): `<audio id="underscore" src="underscore.mp3" data-start="0" data-duration="..." data-track-index="3" data-volume="0.15">`
|
||||
- **SFX** (if storyboard specifies): individual `<audio>` elements at specific `data-start` timestamps
|
||||
- **Captions** (optional — only if user requests): sub-composition on a parallel track. Skip unless explicitly asked for.
|
||||
|
||||
---
|
||||
|
||||
## Critical Rules
|
||||
|
||||
These exist because the capture engine is deterministic. Violations produce broken output.
|
||||
|
||||
- **No `repeat: -1`** — calculate exact repeats from beat duration
|
||||
- **No `Math.random()`** — use a seeded PRNG (mulberry32)
|
||||
- **Register every timeline**: `window.__timelines["comp-id"] = tl`
|
||||
- **Synchronous timeline construction** — no async/await wrapping timeline code
|
||||
- **Never use ANY CSS `transform` for centering** — not `translate(-50%, -50%)`, not `translateX(-50%)`, not `translateY(-50%)`. GSAP animates the `transform` property, which overwrites ALL CSS transforms including centering. The element flies offscreen. Use flexbox centering instead: `display:flex; align-items:center; justify-content:center` on a wrapper div. The linter catches this (`gsap_css_transform_conflict`) but only if you run it.
|
||||
- **Minimum font sizes**: 20px body, 16px labels
|
||||
- **No full-screen dark linear gradients** — H.264 banding
|
||||
109
skills/website-to-hyperframes/references/step-7-validate.md
Normal file
109
skills/website-to-hyperframes/references/step-7-validate.md
Normal file
@ -0,0 +1,109 @@
|
||||
# Step 7: Validate & Deliver
|
||||
|
||||
## Lint + Validate
|
||||
|
||||
Run in sequence. Fix all errors before proceeding to the next command.
|
||||
|
||||
```bash
|
||||
npx hyperframes lint
|
||||
npx hyperframes validate
|
||||
```
|
||||
|
||||
`lint` checks HTML structure statically — missing attributes, timeline registration, tween conflicts, CSS transform + GSAP conflicts (including inline styles).
|
||||
`validate` loads the composition in headless Chrome and catches runtime JS errors, missing assets, and failed network requests.
|
||||
|
||||
## Visual Verification (snapshot)
|
||||
|
||||
After lint and validate pass, capture snapshot frames to SEE your own output:
|
||||
|
||||
```bash
|
||||
npx hyperframes snapshot <project-dir> --at <beat-midpoints>
|
||||
```
|
||||
|
||||
If the snapshot command isn't available, fall back to:
|
||||
|
||||
```bash
|
||||
npx tsx packages/cli/src/cli.ts snapshot <project-dir> --at <beat-midpoints>
|
||||
```
|
||||
|
||||
Calculate the midpoint of each beat from your STORYBOARD.md timings. For a 4-beat video with beats at 0-5.8s, 5.8-15.0s, 15.0-22.5s, 22.5-25.3s:
|
||||
|
||||
```bash
|
||||
npx hyperframes snapshot <project-dir> --at 2.9,10.4,18.7,23.9
|
||||
```
|
||||
|
||||
This renders one frame per beat at the moment when content is most visible. Use timestamps where the most content is on screen — usually 60-70% into each beat, after entrances finish but before exits start.
|
||||
|
||||
**View every snapshot image carefully.** Don't glance and move on. For each frame, check:
|
||||
|
||||
**Visibility:**
|
||||
|
||||
- Is there visible content? All-white or all-black frames mean compositions aren't rendering.
|
||||
- Can you read ALL text? White text on white/light background is invisible. Dark text on dark background is invisible. Every text element needs contrast against what's directly behind it.
|
||||
- Are images and assets showing? Empty space where an image should be means a path issue or missing file.
|
||||
|
||||
**Positioning and layout:**
|
||||
|
||||
- Do background images fill the entire frame? If an image only covers half the screen, the `object-fit`, `width`, `height`, or position values are wrong.
|
||||
- Are elements where the storyboard says they should be? Compare the snapshot to the beat description.
|
||||
- Is there too much empty/dead space? If more than 40% of the frame is a flat solid color with nothing on it, the composition is sparse.
|
||||
- Are elements overlapping incorrectly? Text over text, or content bleeding off the edges?
|
||||
|
||||
**Visual quality:**
|
||||
|
||||
- Are overlays too heavy? If a background image is barely visible through a dark overlay, reduce the overlay opacity.
|
||||
- Is the visual hierarchy clear? One dominant element per frame, supporting elements secondary.
|
||||
- Do the colors match DESIGN.md? Check actual rendered colors against what was planned.
|
||||
|
||||
**Code vs. rendered verification:**
|
||||
|
||||
- For each beat, check: does the snapshot show the assets you referenced in the HTML? If a composition has `<img src="...wave.png">` but the snapshot shows no wave — the image isn't loading, the path is wrong, or it's hidden behind another element.
|
||||
- If a snapshot shows nothing at a timestamp, try a slightly different time (1-2 seconds later). Compositions may still be in entrance animations.
|
||||
- The snapshot command is fast — run it multiple times at different timestamps if needed.
|
||||
|
||||
If any frame has issues, go back to Step 6 and fix that composition before proceeding.
|
||||
|
||||
## Preview
|
||||
|
||||
```bash
|
||||
npx hyperframes preview
|
||||
```
|
||||
|
||||
Open the studio in a browser. Scrub through every beat.
|
||||
|
||||
## Create HANDOFF.md
|
||||
|
||||
Write a `HANDOFF.md` for multi-session continuity:
|
||||
|
||||
```markdown
|
||||
# Handoff — [Project Name]
|
||||
|
||||
**Date:** [today]
|
||||
**Preview:** `npx hyperframes preview`
|
||||
|
||||
## What's Built
|
||||
|
||||
| Beat | File | Dur | Status | Notes |
|
||||
| ---- | -------------------- | ---- | ------ | ----- |
|
||||
| 1 | beat-1-hook.html | 5.2s | Built | ... |
|
||||
| 2 | beat-2-features.html | 6.8s | Built | ... |
|
||||
|
||||
## Audio
|
||||
|
||||
| Asset | Status | Notes |
|
||||
| --------------- | ------ | ------------------------------------ |
|
||||
| narration.wav | Done | [provider], [voice name], [duration] |
|
||||
| transcript.json | Done | [word count] words, [duration] |
|
||||
|
||||
## What Needs Work
|
||||
|
||||
- [any known issues, polish requests, missing SFX]
|
||||
|
||||
## Commands
|
||||
|
||||
npx hyperframes preview
|
||||
npx hyperframes lint
|
||||
npx hyperframes validate
|
||||
npx hyperframes snapshot <project-dir> --at <beat-midpoints>
|
||||
npx hyperframes render --output renders/final.mp4
|
||||
```
|
||||
341
skills/website-to-hyperframes/references/techniques.md
Normal file
341
skills/website-to-hyperframes/references/techniques.md
Normal file
@ -0,0 +1,341 @@
|
||||
# Visual Techniques Reference
|
||||
|
||||
10 proven techniques from production HyperFrames videos. Use these in your storyboard and compositions to create visually rich, professional output. Each technique includes a minimal code pattern you can adapt.
|
||||
|
||||
These are NOT advanced — they're standard motion design patterns that every composition should use at least 2-3 of.
|
||||
|
||||
---
|
||||
|
||||
## 1. SVG Path Drawing
|
||||
|
||||
A path draws itself in real-time, like someone tracing with a pen. Use for revealing diagrams, arrows, connector lines, or brand marks.
|
||||
|
||||
```html
|
||||
<svg viewBox="0 0 400 200">
|
||||
<path
|
||||
class="draw-path"
|
||||
d="M 50 100 L 200 50 L 350 100"
|
||||
stroke="#c84f1c"
|
||||
stroke-width="4"
|
||||
fill="none"
|
||||
stroke-linecap="round"
|
||||
/>
|
||||
</svg>
|
||||
<style>
|
||||
.draw-path {
|
||||
stroke-dasharray: 280;
|
||||
stroke-dashoffset: 280;
|
||||
}
|
||||
</style>
|
||||
<script>
|
||||
tl.to(".draw-path", { strokeDashoffset: 0, duration: 0.7, ease: "power2.out" }, 0.5);
|
||||
</script>
|
||||
```
|
||||
|
||||
Use `path.getTotalLength()` to calculate the dasharray value dynamically.
|
||||
|
||||
---
|
||||
|
||||
## 2. Canvas 2D Procedural Art
|
||||
|
||||
Animated noise, particle fields, data visualizations — anything that evolves frame-by-frame. Drive it with a GSAP proxy.
|
||||
|
||||
```html
|
||||
<canvas id="proc-canvas" width="1920" height="1080"></canvas>
|
||||
<script>
|
||||
var canvas = document.getElementById("proc-canvas");
|
||||
var ctx = canvas.getContext("2d");
|
||||
|
||||
function hash(x, y) {
|
||||
var n = x * 374761393 + y * 668265263;
|
||||
n = (n ^ (n >> 13)) * 1274126177;
|
||||
return ((n ^ (n >> 16)) & 0x7fffffff) / 0x7fffffff;
|
||||
}
|
||||
|
||||
function drawFrame(t) {
|
||||
ctx.fillStyle = "#0a0a0a";
|
||||
ctx.fillRect(0, 0, 1920, 1080);
|
||||
for (var i = 0; i < 200; i++) {
|
||||
var x = hash(i, 0) * 1920;
|
||||
var y = hash(i, 1) * 1080;
|
||||
var brightness = hash(i, Math.floor(t * 10)) * 255;
|
||||
ctx.fillStyle = "rgba(255, 255, 255, " + brightness / 255 + ")";
|
||||
ctx.beginPath();
|
||||
ctx.arc(x, y, 2, 0, Math.PI * 2);
|
||||
ctx.fill();
|
||||
}
|
||||
}
|
||||
|
||||
var proxy = { time: 0 };
|
||||
tl.to(
|
||||
proxy,
|
||||
{
|
||||
time: 5,
|
||||
duration: 5,
|
||||
ease: "none",
|
||||
onUpdate: function () {
|
||||
drawFrame(proxy.time);
|
||||
},
|
||||
},
|
||||
0,
|
||||
);
|
||||
</script>
|
||||
```
|
||||
|
||||
The `hash()` function is deterministic — same frame renders identically every time.
|
||||
|
||||
---
|
||||
|
||||
## 3. CSS 3D Transforms
|
||||
|
||||
Perspective rotations create depth. Use for product showcases, card flips, architectural reveals.
|
||||
|
||||
```html
|
||||
<div class="stage" style="perspective: 900px;">
|
||||
<div class="card-3d" style="transform-style: preserve-3d;">
|
||||
<div class="face front">Product</div>
|
||||
<div class="face back" style="transform: rotateY(180deg);">Details</div>
|
||||
</div>
|
||||
</div>
|
||||
<script>
|
||||
tl.to(".card-3d", { rotationY: 360, rotationX: 15, duration: 1.2, ease: "sine.inOut" }, 0);
|
||||
</script>
|
||||
```
|
||||
|
||||
Always set `perspective` on the parent, `transform-style: preserve-3d` on the animated element.
|
||||
|
||||
---
|
||||
|
||||
## 4. Per-Word Kinetic Typography
|
||||
|
||||
Words appear one-by-one, synced to transcript.json timestamps. The core technique for narration-driven videos.
|
||||
|
||||
```html
|
||||
<div class="headline">
|
||||
<span class="word w-0">Anything</span>
|
||||
<span class="word w-1">a</span>
|
||||
<span class="word w-2">browser</span>
|
||||
<span class="word w-3">can</span>
|
||||
<span class="word w-4">render</span>
|
||||
</div>
|
||||
<style>
|
||||
.word {
|
||||
display: inline-block;
|
||||
opacity: 0;
|
||||
margin: 0 0.12em;
|
||||
}
|
||||
</style>
|
||||
<script>
|
||||
// Word onset times from transcript.json (seconds relative to beat start)
|
||||
var timings = [0.0, 0.23, 0.28, 0.63, 0.78];
|
||||
var slides = [80, 60, 50, 25, 12]; // horizontal slide decay (px)
|
||||
|
||||
document.querySelectorAll(".word").forEach(function (word, i) {
|
||||
tl.from(
|
||||
word,
|
||||
{
|
||||
x: slides[i],
|
||||
y: 14,
|
||||
opacity: 0,
|
||||
duration: 0.35,
|
||||
ease: "power2.out",
|
||||
},
|
||||
timings[i],
|
||||
);
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
The slide distance DECAYS per word (80→12px) — mimics a camera settling.
|
||||
|
||||
---
|
||||
|
||||
## 5. Lottie Animation
|
||||
|
||||
Vector animations that play inside a composition. Use for logos, character animations, icons.
|
||||
|
||||
```html
|
||||
<script src="https://cdn.jsdelivr.net/npm/@dotlottie/player-component@2.7.12/dist/dotlottie-player.js"></script>
|
||||
<dotlottie-player
|
||||
class="lottie"
|
||||
src="../assets/lottie/animation-0.json"
|
||||
autoplay
|
||||
loop
|
||||
speed="1.5"
|
||||
style="width:500px;height:500px;"
|
||||
>
|
||||
</dotlottie-player>
|
||||
<script>
|
||||
gsap.set(".lottie", { scale: 0.3, opacity: 0 });
|
||||
tl.to(".lottie", { scale: 1, opacity: 1, duration: 0.35, ease: "back.out(1.6)" }, 0.2);
|
||||
</script>
|
||||
```
|
||||
|
||||
Or use lottie-web for more control:
|
||||
|
||||
```javascript
|
||||
var anim = lottie.loadAnimation({
|
||||
container: document.getElementById("anim"),
|
||||
renderer: "svg",
|
||||
loop: false,
|
||||
autoplay: false,
|
||||
path: "../assets/lottie/animation-0.json",
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Video Compositing
|
||||
|
||||
Embed real video footage inside compositions. Videos must be `muted` with `playsinline`.
|
||||
|
||||
```html
|
||||
<div class="video-frame" style="width:680px;height:840px;border-radius:16px;overflow:hidden;">
|
||||
<video
|
||||
id="footage"
|
||||
src="../assets/videos/clip.mp4"
|
||||
muted
|
||||
playsinline
|
||||
style="width:100%;height:100%;object-fit:cover;"
|
||||
></video>
|
||||
</div>
|
||||
<script>
|
||||
// Video playback is controlled by the framework — don't call play() manually
|
||||
tl.from(".video-frame", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.out" }, 0);
|
||||
</script>
|
||||
```
|
||||
|
||||
The HyperFrames runtime handles video seeking and playback.
|
||||
|
||||
---
|
||||
|
||||
## 7. Character-by-Character Typing
|
||||
|
||||
Terminal typing effect using `tl.call()` to update text content character by character.
|
||||
|
||||
```html
|
||||
<div class="terminal-line">
|
||||
<span class="prompt">❯</span>
|
||||
<span class="typed" id="typed-text"></span>
|
||||
<span class="cursor" style="width:11px;height:22px;background:#333;display:inline-block;"></span>
|
||||
</div>
|
||||
<script>
|
||||
var CMD = "npx hyperframes init";
|
||||
var typed = document.getElementById("typed-text");
|
||||
|
||||
// Cursor blinks
|
||||
tl.to(".cursor", { opacity: 0, duration: 0.12, yoyo: true, repeat: 20, ease: "steps(1)" }, 0);
|
||||
|
||||
// Type each character
|
||||
for (var i = 0; i < CMD.length; i++) {
|
||||
(function (idx) {
|
||||
tl.call(
|
||||
function () {
|
||||
typed.textContent = CMD.substring(0, idx + 1);
|
||||
},
|
||||
null,
|
||||
(idx / CMD.length) * 0.9,
|
||||
);
|
||||
})(i);
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
Use `ease: "steps(1)"` for cursor blink — creates discrete on/off.
|
||||
|
||||
---
|
||||
|
||||
## 8. Variable Font Axis Animation
|
||||
|
||||
Animate font-variation-settings to reshape glyphs in real-time. Works with variable fonts that have axes like optical size (opsz), weight (wght), softness (SOFT).
|
||||
|
||||
```html
|
||||
<style>
|
||||
@import url("https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,100..900&display=block");
|
||||
.wordmark {
|
||||
--opsz: 144;
|
||||
--wght: 440;
|
||||
font-family: "Fraunces", serif;
|
||||
font-variation-settings:
|
||||
"opsz" var(--opsz),
|
||||
"wght" var(--wght);
|
||||
font-size: 200px;
|
||||
}
|
||||
</style>
|
||||
<script>
|
||||
tl.to(".wordmark", { "--opsz": 72, "--wght": 300, duration: 0.45, ease: "power2.out" }, 0);
|
||||
</script>
|
||||
```
|
||||
|
||||
The glyph subtly reshapes as axes animate — optical size adjusts detail, weight changes thickness.
|
||||
|
||||
---
|
||||
|
||||
## 9. GSAP MotionPathPlugin
|
||||
|
||||
Animate an element along an arbitrary SVG path. Use for sliders following curves, particles along trajectories, guided reveals.
|
||||
|
||||
```html
|
||||
<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/MotionPathPlugin.min.js"></script>
|
||||
<div class="dot" style="width:20px;height:20px;background:#2a8a7c;border-radius:50%;"></div>
|
||||
<script>
|
||||
gsap.registerPlugin(MotionPathPlugin);
|
||||
tl.to(
|
||||
".dot",
|
||||
{
|
||||
motionPath: { path: "M 12 300 C 280 280 520 80 820 50 S 1200 48 1308 38" },
|
||||
duration: 1.5,
|
||||
ease: "power2.out",
|
||||
},
|
||||
0,
|
||||
);
|
||||
</script>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Velocity-Matched Transitions
|
||||
|
||||
Exit one beat and enter the next with matched velocities — creates perceived continuous motion.
|
||||
|
||||
```javascript
|
||||
// EXIT (in outgoing composition): accelerating with blur
|
||||
tl.to(
|
||||
".content",
|
||||
{
|
||||
y: -150,
|
||||
filter: "blur(30px)",
|
||||
opacity: 0,
|
||||
duration: 0.33,
|
||||
ease: "power2.in", // accelerates
|
||||
},
|
||||
beatDuration - 0.33,
|
||||
);
|
||||
|
||||
// ENTRY (in incoming composition): decelerating from blur
|
||||
gsap.set(".content", { y: 150, filter: "blur(30px)" });
|
||||
tl.to(
|
||||
".content",
|
||||
{
|
||||
y: 0,
|
||||
filter: "blur(0px)",
|
||||
duration: 1.0,
|
||||
ease: "power2.out", // decelerates
|
||||
},
|
||||
0,
|
||||
);
|
||||
```
|
||||
|
||||
The fastest point of both curves meets at the cut — the viewer perceives smooth camera motion. Match ease families: `.in` for exits, `.out` for entries.
|
||||
|
||||
---
|
||||
|
||||
## When to Use What
|
||||
|
||||
| Video energy | Techniques to combine |
|
||||
| ------------------------------ | --------------------------------------------------------------- |
|
||||
| High impact (launches, promos) | Per-word typography + velocity transitions + counter animations |
|
||||
| Cinematic (tours, stories) | SVG path drawing + video compositing + 3D transforms |
|
||||
| Technical (dev tools, APIs) | Character typing + Canvas 2D procedural + MotionPath |
|
||||
| Premium (luxury, enterprise) | Variable font animation + Lottie + slow velocity transitions |
|
||||
| Data-driven (stats, metrics) | Canvas 2D procedural + counter animations + SVG path drawing |
|
||||
Loading…
x
Reference in New Issue
Block a user