- 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
5.8 KiB
Session Handoff — Website Capture & Video Creation Pipeline
Last updated: 2026-04-08 Branch:
feat/website-capture-design-mdLatest commit: b0308cf
START HERE
Before doing ANYTHING, read these in order:
- This file — understand what was built and what needs validation
Hyperframes-100-Test-Prompts-v3.pdfandHyperframes-Evaluation-Guide.pdf— understand what GOOD HyperFrames output looks like (check ~/Downloads/ or root)skills/website-to-hyperframes/SKILL.md— the skill that drives the workflow (WAS REWRITTEN but NOT VALIDATED)skills/website-to-hyperframes/references/— 4 reference files (PRE-EXISTING, may be outdated)- Templates at
templates/— see how real HyperFrames projects are structured
What Was Built
Core: hyperframes capture <url>
Extracts everything from a website into an AI-agent-ready project folder:
# Default (no API key needed):
hyperframes capture https://stripe.com -o stripe-video
# With AI-generated DESIGN.md + replica:
GEMINI_API_KEY="..." hyperframes capture https://stripe.com -o stripe-video
# With per-section compositions:
hyperframes capture https://stripe.com -o stripe-video --split
Output files:
| File | Purpose |
|---|---|
CLAUDE.md / .cursorrules |
AI agent instructions (auto-read) |
screenshots/full-page.png |
Full-page screenshot (via Playwright) |
extracted/tokens.json |
Colors, fonts, headings, CTAs, sections, CSS vars |
extracted/visible-text.txt |
All visible text in DOM order |
extracted/assets-catalog.json |
Every asset URL with HTML context |
extracted/animations.json |
Animation catalog |
assets/ |
Downloaded fonts, images, favicon |
assets/svgs/ |
Extracted inline SVGs |
index.html + meta.json |
Valid HyperFrames project skeleton |
DESIGN.md |
(if API key set) AI-generated design system |
replica.html |
(if API key set) Clean Tailwind recreation |
Pipeline files:
| File | Purpose |
|---|---|
packages/cli/src/capture/index.ts |
Pipeline orchestrator |
packages/cli/src/capture/tokenExtractor.ts |
Design tokens |
packages/cli/src/capture/animationCataloger.ts |
Animations |
packages/cli/src/capture/assetCataloger.ts |
Asset URLs with contexts |
packages/cli/src/capture/assetDownloader.ts |
Download assets + save SVGs |
packages/cli/src/capture/screenshotCapture.ts |
Playwright full-page screenshot |
packages/cli/src/capture/agentPromptGenerator.ts |
CLAUDE.md generation |
packages/cli/src/capture/designMdGenerator.ts |
AI DESIGN.md (optional) |
packages/cli/src/capture/replicaGenerator.ts |
AI replica + refinement (optional) |
packages/cli/src/capture/cssPurger.ts |
CSS purge for compositions |
packages/cli/src/capture/htmlExtractor.ts |
Raw HTML extraction |
packages/cli/src/capture/types.ts |
TypeScript types |
packages/cli/src/commands/capture.ts |
CLI command |
Research:
| File | Contents |
|---|---|
docs/research/aura-build-and-design-systems.md |
Aura.build analysis |
docs/research/reverse-engineered-aura-system-prompt.md |
Aura system instructions |
docs/research/aura-prompt-comparison.md |
Aura prompt variants |
docs/research/aura-examples/stripe-DESIGN.md |
Aura's Stripe output |
docs/research/video-prompt-catalog.md |
Video prompt library |
CRITICAL: What Needs Validation
1. The website-to-hyperframes skill
The SKILL.md was completely rewritten to match the new capture pipeline, but it has NOT been tested end-to-end. The 6-step workflow needs validation:
- Does Step 1 (capture) work reliably?
- Does Step 2 (read all data) actually happen — does the AI read every file?
- Does Step 3 (create DESIGN.md) produce good output when the AI writes it vs the API?
- Does Step 4 (plan video) produce sensible scene plans?
- Does Step 5 (build compositions) follow HyperFrames rules correctly?
- Does Step 6 (lint/validate/preview) catch issues?
2. The skill references
These 4 files were PRE-EXISTING (not written this session):
references/animation-recreation.md— converting source animations to GSAPreferences/video-recipes.md— scene patterns, product promo, social clip templatesreferences/section-refinement.md— building from screenshot + tokens (UPDATED this session)references/tts-integration.md— adding narration and captions
Question: are these helpful or do they confuse the AI? Need to:
- Read each one critically
- Check if they contradict the SKILL.md
- Check if they reference old files (capture-brief.md, visual-style.md)
- Decide: keep, update, or remove each
3. HyperFrames best practices
This session focused on CAPTURE but didn't deeply study how HyperFrames creates the best videos. Before testing the full workflow, read:
- Test prompts PDF (what good prompts look like)
- Evaluation guide (what good output looks like)
- Showcase HTML (real examples)
- Templates in
templates/directory - Git history for successful HyperFrames projects
4. SVG usage in replicas
Inline SVGs are extracted and saved to assets/svgs/ but the AI replica generator can't use them (local paths, not URLs). The local AI agent (Claude Code) CAN read them. This needs testing with the actual workflow.
Environment
| Variable | Purpose |
|---|---|
GEMINI_API_KEY |
Gemini 3.1 Pro (optional) |
ANTHROPIC_API_KEY |
Claude Sonnet (optional fallback) |
Model IDs: gemini-3.1-pro-preview, claude-sonnet-4-20250514
User Preferences
- DESIGN.md must be AI-generated prose, not template filling
- Always verify by actually reading outputs
- Research thoroughly before implementing
- Match Aura.build quality as benchmark
- AI API calls should be optional — the user's AI agent is enough
- Don't add unnecessary complexity
- Test everything end-to-end before declaring it done