Files
hyperframes/docs/SESSION-HANDOFF.md
T
ularkim dd986423e1 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
2026-04-15 14:04:55 -04:00

133 lines
5.8 KiB
Markdown

# Session Handoff — Website Capture & Video Creation Pipeline
> Last updated: 2026-04-08
> Branch: `feat/website-capture-design-md`
> Latest commit: b0308cf
## START HERE
Before doing ANYTHING, read these in order:
1. **This file** — understand what was built and what needs validation
2. **`Hyperframes-100-Test-Prompts-v3.pdf`** and **`Hyperframes-Evaluation-Guide.pdf`** — understand what GOOD HyperFrames output looks like (check ~/Downloads/ or root)
3. **`skills/website-to-hyperframes/SKILL.md`** — the skill that drives the workflow (WAS REWRITTEN but NOT VALIDATED)
4. **`skills/website-to-hyperframes/references/`** — 4 reference files (PRE-EXISTING, may be outdated)
5. **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:
```bash
# 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:
1. Does Step 1 (capture) work reliably?
2. Does Step 2 (read all data) actually happen — does the AI read every file?
3. Does Step 3 (create DESIGN.md) produce good output when the AI writes it vs the API?
4. Does Step 4 (plan video) produce sensible scene plans?
5. Does Step 5 (build compositions) follow HyperFrames rules correctly?
6. 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 GSAP
- `references/video-recipes.md` — scene patterns, product promo, social clip templates
- `references/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