diff --git a/docs/session-context-fresh.md b/docs/session-context-fresh.md new file mode 100644 index 0000000000..786356a370 --- /dev/null +++ b/docs/session-context-fresh.md @@ -0,0 +1,70 @@ +# Context for New Session + +## The Project + +HyperFrames is an open-source video rendering framework: write HTML, render video. The branch `feat/website-capture-design-md` adds a website capture pipeline and skill system for turning URLs into videos. + +## What Exists on This Branch + +### Capture Pipeline (`packages/cli/src/capture/`) +`npx hyperframes capture ` extracts a website's design system — colors, fonts, assets, animations, Lottie, WebGL shaders — into a structured folder with screenshots, tokens.json, assets/, and extracted data. + +### Skills (AI Agent Instructions) + +**`skills/website-to-hyperframes/SKILL.md`** — 6-step workflow: +1. Capture the website +2. Read ALL captured data +3. Create DESIGN.md (brand identity doc) +4. Plan the video (Creative Director role) +5. Build compositions (Engineer role) +6. Lint, validate, preview + +**`skills/hyperframes/SKILL.md`** — Compose skill for writing HTML video compositions. Has rules for data attributes, GSAP timelines, deterministic rendering. + +**Reference files:** +- `references/visual-styles.md` — 8 named visual styles with hex palettes, GSAP easing, shader pairings +- `references/asset-sourcing.md` — How to source brand logos, icons, photos from free APIs +- `references/video-recipes.md` — Scene patterns, 5-layer composition system, transition patterns +- `references/transitions/shader-setup.md` — WebGL boilerplate for 14 GLSL shader transitions +- `references/transitions/shader-transitions.md` — 14 fragment shaders (domain warp, ridged burn, gravitational lens, etc.) + +### 28 Existing Captures +`captures/` has linear, perplexity, arc-browser, stripe-website, notion, framer, midjourney, resend, vercel-tour, and more — each with screenshots, tokens, assets, visible text. + +## Git State +- Rebased on latest `origin/main` (v0.3.0) +- 6 commits + 10 staged files (not yet committed) +- ~49 unstaged test/template files that are NOT our changes — discard with `git checkout -- packages/producer/tests/ templates/` + +## 4 Test Runs Were Completed + +Each in a fresh Claude Code session with a single prompt: + +1. **Linear capture → 24s launch video** +2. **"Make a 20s video about AI agents replacing jobs"** (no URL, from scratch) +3. **"Make a 20s video showcasing Stripe's payment platform"** (brand-specific) +4. **"Make a 15s Data Drift style video about quantum computing"** (named visual style) + +The conversation logs are the 4 most recent JSONL files in: +`/Users/ularkimsanov/.claude/projects/-Users-ularkimsanov-Desktop-hyperframes-3/` + +## What To Do + +Review the entire skill system, the 4 test conversation logs, and the resulting compositions. Assess: + +- What is the skill system doing well? +- What is it doing poorly? +- What specific changes would improve output quality? +- Are there structural issues (not just instruction wording) that need addressing? + +Look at the actual HTML compositions produced, the DESIGN.md files, the narration scripts, and the index.html files. Judge the output quality honestly. + +## Key Files +- `skills/website-to-hyperframes/SKILL.md` +- `skills/hyperframes/SKILL.md` +- `skills/hyperframes/house-style.md` +- `skills/hyperframes/references/transitions/shader-setup.md` +- `skills/hyperframes/references/transitions/shader-transitions.md` +- `skills/website-to-hyperframes/references/visual-styles.md` +- `skills/website-to-hyperframes/references/video-recipes.md` +- `skills/website-to-hyperframes/references/asset-sourcing.md` diff --git a/docs/session-handoff-2026-04-13.md b/docs/session-handoff-2026-04-13.md new file mode 100644 index 0000000000..7584932b31 --- /dev/null +++ b/docs/session-handoff-2026-04-13.md @@ -0,0 +1,105 @@ +# Session Handoff — April 13, 2026 + +## What This Branch Is + +`feat/website-capture-design-md` — Website capture pipeline + skill system for turning URLs into HyperFrames videos. Rebased on latest main (v0.3.0, 28 commits ahead). Not yet pushed or PR'd. + +## What Was Built (All Working) + +### Capture Pipeline (`packages/cli/src/capture/`) +- `npx hyperframes capture ` — extracts design tokens, assets, screenshots, animations, Lottie, shaders, video manifest +- Two-pass strategy: Pass 1 (full JS) captures WebGL/Lottie/animations, Pass 2 (stable HTML) extracts tokens +- Downloads SVGs, images, fonts, favicons with deduplication and batch parallelism +- Generates `CLAUDE.md` per capture with brand summary and example prompts +- Bug fix needed: `assetDownloader.ts` `fetchBuffer()` — added content-type check to reject XML error responses saved as images (staged but not committed) + +### Website-to-HyperFrames Skill (`skills/website-to-hyperframes/`) +Full 6-step pipeline: Capture → Read ALL data → Create DESIGN.md → Plan video (Creative Director) → Build compositions (Engineer) → Lint/validate/preview. + +### Compose Skill Improvements (`skills/hyperframes/SKILL.md`) +- Added `` Visual Identity Gate — requires DESIGN.md or visual-style.md before ANY HTML writing +- 4-step cascade: existing DESIGN.md → visual-style.md → named style → ask 3 questions +- **TEST RESULT: 4/4 tests created DESIGN.md before HTML. This works.** + +### New Reference Files +- `references/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, shader pairings +- `references/asset-sourcing.md` — How to source brand logos (Simple Icons), company logos (Clearbit), icons (Lucide), photos (Unsplash) with exact curl commands +- `references/video-recipes.md` — 5-layer composition system (L1-L5), shader-first transition pattern, seeded PRNG grain, motion vocabulary + +### DESIGN.md Format +Added sections: `## Style Prompt` (standalone AI-readable paragraph), `## Motion`, `## What NOT to Do` (explicit anti-patterns). Tested and working across all captures. + +## What Failed — Shader Transitions + +### The Problem +HyperFrames has 14 GLSL shader transitions (domain warp, ridged burn, gravitational lens, etc.) that are a massive visual differentiator. But Claude Code never uses them — every test video uses CSS fade-to-black between scenes. + +### What We Tried +1. **Session 1:** Added energy→shader table, verbal commitment requirement ("I will use [shader name]"), shader wiring instructions in Step 5. **Result: 1/3 used shaders** (Arc did, Linear and Perplexity didn't). +2. **Session 2:** Added superpowers-style enforcement — `` tags, Red Flags table (6 rationalizations), self-verification checklist (5 checkboxes). **Result: 0/3 used shaders.** Three different failure modes: + - Linear: Named "Cinematic Zoom" but wrote CSS clip-path instead — treated verbal commitment as checkbox + - Stripe: Falsely claimed "shader reference files are not available in the installed skill" — never tried to read them + - Data Drift: Searched for visual-styles.md in wrong directory, gave up, improvised + +### Why Instructions Don't Work For This +The shader transition system requires ~200 lines of WebGL boilerplate (texture capture, shader compilation, state machine, GSAP integration). The agent has to: +1. Read shader-setup.md (200+ lines) +2. Read shader-transitions.md (pick a fragment shader) +3. Hold all of that in working memory +4. Write it from scratch into index.html +5. While ALSO managing scenes, narration, captions, fonts, assets, timing + +The agent takes the easy path every time: CSS fades (3 lines vs 200). + +### What Might Actually Work (Untested) +- **Option A: Inline the shader boilerplate** directly in the SKILL.md as a copy-paste code block instead of referencing a separate file. The agent can't skip code that's right in front of it. +- **Option B: Template file** — `index-template-with-shaders.html` with WebGL pre-wired. Agent fills in scene IDs and picks a fragment shader. +- **Option C: Engine feature** — `data-transition="cinematic-zoom"` as a framework attribute. Engine handles WebGL internally. This is the long-term answer but requires real engineering in `packages/engine`. + +### Key Insight From Testing +Instructions work when they're **structurally useful** to the agent (DESIGN.md helps it write better HTML → 4/4 compliance). Instructions fail when they add **extra work** the agent can shortcut (shader WebGL boilerplate → 0/3 compliance). + +## Git State + +- Branch: `feat/website-capture-design-md` +- Rebased on latest `origin/main` (v0.3.0) +- 6 commits + 10 staged files (not committed) +- Staged files: + - `skills/hyperframes/SKILL.md` (DESIGN.md hard gate + visual-styles.md reference) + - `skills/hyperframes/visual-styles.md` (NEW) + - `skills/website-to-hyperframes/SKILL.md` (shader enforcement — may want to remove the failed enforcement parts) + - `skills/website-to-hyperframes/references/asset-sourcing.md` (NEW) + - `skills/website-to-hyperframes/references/visual-styles.md` (NEW) + - `skills/website-to-hyperframes/references/video-recipes.md` (5-layer system) + - `packages/cli/src/capture/index.ts` (capture pipeline) + - `packages/cli/src/capture/agentPromptGenerator.ts` (capture pipeline) + - `packages/cli/src/capture/assetDownloader.ts` (capture pipeline + content-type fix) + - `docs/superpowers/specs/2026-04-13-preproduction-enforcement-design.md` (design spec) +- ~49 unstaged test/template files — NOT ours, caused by a bug where `npx hyperframes preview` overwrites TRANSCRIPT arrays in test fixtures. Discard with `git checkout -- packages/producer/tests/ templates/` + +## Existing Captures Available for Testing + +28 captures in `captures/` including: linear, perplexity, arc-browser, stripe-website, notion, framer, midjourney, resend, vercel-tour, and more. Each has screenshots, tokens.json, assets, visible-text.txt. + +## Installed Skills & Tools +- Superpowers v5.0.7 (brainstorming, TDD, debugging, code review, etc.) +- GSAP skills (core, timeline, plugins, performance, scrolltrigger, utils) +- HeyGen skills (create-video, visual-style, avatar-video, TTS, etc.) +- Remotion best practices (38 rule files at `.agents/skills/remotion-best-practices/`) +- ElevenLabs MCP (TTS) +- Playwright MCP (browser automation) + +## Key Files to Read +- `skills/website-to-hyperframes/SKILL.md` — the main workflow +- `skills/hyperframes/SKILL.md` — compose skill with DESIGN.md gate +- `skills/hyperframes/house-style.md` — motion defaults, anti-defaults table +- `skills/hyperframes/references/transitions/shader-setup.md` — the WebGL boilerplate that agents won't read +- `skills/hyperframes/references/transitions/shader-transitions.md` — 14 fragment shaders +- `.claude/projects/-Users-ularkimsanov-Desktop-hyperframes-3/memory/MEMORY.md` — persistent memory index + +## What To Do Next + +1. **Commit what works** — DESIGN.md gate, visual styles, asset sourcing, video recipes, capture pipeline. These are proven wins. +2. **Solve shader transitions** — try Option A (inline boilerplate in skill) or Option B (template file). Test with subagents or fresh sessions. +3. **Fix the transcript overwrite bug** — `npx hyperframes preview` is mutating test fixtures and templates. +4. **Test non-capture videos** — the DESIGN.md gate works but named styles (like "Data Drift") fail because the agent can't find visual-styles.md. The file path needs to be more prominent in the compose skill. diff --git a/docs/superpowers/specs/2026-04-13-preproduction-enforcement-design.md b/docs/superpowers/specs/2026-04-13-preproduction-enforcement-design.md new file mode 100644 index 0000000000..6f634d96e8 --- /dev/null +++ b/docs/superpowers/specs/2026-04-13-preproduction-enforcement-design.md @@ -0,0 +1,93 @@ +# Phase 1: Pre-Production + Shader Enforcement + +**Date:** 2026-04-13 +**Status:** Approved +**Scope:** Skill/documentation changes only. Zero engine or CLI code. + +## Problem + +1. **2/3 test videos skipped shader transitions** despite SKILL.md instructions. The instruction was a suggestion, not an enforced gate. Claude verbally committed to a shader in Step 4 then wrote CSS fades in Step 5. + +2. **Non-capture videos have no visual identity.** When there's no website capture, Claude picks generic defaults (blue, gray, Roboto). The compose skill acknowledges `visual-style.md` exists but has no mechanism to require one. + +3. **Non-capture videos have no assets.** Without a capture, Claude can only generate CSS shapes and inline SVGs. No photos, no brand logos, no icons. + +## Deliverables + +### 1. Asset Sourcing Reference (`asset-sourcing.md`) + +**File:** `skills/website-to-hyperframes/references/asset-sourcing.md` + +Teaches Claude how to find and download free assets from known-good sources: + +| Asset type | Source | URL pattern | License | +|-----------|--------|-------------|---------| +| Brand logos (SVG) | Simple Icons | `cdn.jsdelivr.net/npm/simple-icons@latest/icons/{name}.svg` | CC0 | +| Company logos (PNG) | Clearbit | `logo.clearbit.com/{domain}` | Free | +| Icons (SVG) | Lucide | `cdn.jsdelivr.net/npm/lucide-static@latest/icons/{name}.svg` | ISC | +| Photos | Unsplash | `api.unsplash.com/search/photos?query={q}` | Free (attribution) | + +Includes: when to source vs skip, curl patterns, naming conventions, manifest format. + +Also wired into SKILL.md Reference Files table. + +### 2. Universal DESIGN.md Gate in Compose Skill + +**File:** `skills/hyperframes-compose/SKILL.md` (the global compose skill) + +Add a `` before any HTML writing that enforces: + +``` +1. DESIGN.md exists? → Use it. +2. visual-style.md exists? → Use it. +3. User named a style? → Generate DESIGN.md from visual-styles.md. +4. None? → Ask 3 questions, generate minimal DESIGN.md. +``` + +Every composition must trace its palette back to a defined source. No generic defaults. + +### 3. Shader Transition Enforcement + +**File:** `skills/website-to-hyperframes/SKILL.md` + +Three superpowers-inspired enforcement mechanisms: + +**A. Red Flags table** (Step 4) — 5 common rationalizations with reality checks: +- "CSS fades are simpler" → Shaders are the default +- "I'll add shaders later" → Later never comes +- "Separate files are cleaner" → Shaders need root index.html +- "Video is short" → Under 10s is the ONLY exception +- "It's complex" → Boilerplate is copy-paste from shader-setup.md + +**B. Hard gate** (Step 5) — Before writing index.html, verify: +- Shader named in Step 4 +- shader-setup.md read +- Fragment shader code read + +**C. Self-verification checklist** (Step 6) — Before claiming done: +- [ ] index.html contains `` +- [ ] index.html contains `gl.createShader` +- [ ] index.html contains `beginTrans` and `endTrans` +- [ ] Scenes do NOT fade to/from black + +## Files Changed + +| File | Change type | +|------|------------| +| `skills/website-to-hyperframes/references/asset-sourcing.md` | NEW | +| `skills/website-to-hyperframes/SKILL.md` | EDIT (red flags + hard gate + verification) | +| `skills/hyperframes-compose/SKILL.md` | EDIT (DESIGN.md hard gate) | + +## Success Criteria + +Re-run 3 test captures. Expect: +- 3/3 use shader transitions (was 1/3) +- 3/3 have DESIGN.md with Style Prompt (was 3/3, maintain) +- Non-capture videos also get DESIGN.md before any HTML + +## What This Does NOT Change + +- Compose skill HTML rules (data attributes, templates, GSAP) +- Capture pipeline (no code changes) +- Engine or producer (no code changes) +- house-style.md (still the fallback for motion defaults) diff --git a/docs/superpowers/specs/2026-04-13-skill-architecture-redesign.md b/docs/superpowers/specs/2026-04-13-skill-architecture-redesign.md new file mode 100644 index 0000000000..14187ecd98 --- /dev/null +++ b/docs/superpowers/specs/2026-04-13-skill-architecture-redesign.md @@ -0,0 +1,305 @@ +# Skill Architecture Redesign — Website-to-HyperFrames + Compose + +**Date:** 2026-04-13 +**Status:** Approved +**Goal:** A fresh Claude Code session, given a one-line prompt, produces professional-quality video with shader transitions, real assets, synced narration, and purposeful motion — whether starting from a URL or from scratch. + +--- + +## Problem Statement + +The current system produces mediocre output. Root causes identified through comprehensive code review: + +1. **Split-brain DESIGN.md schema.** The auto-generator (`designMdGenerator.ts`) produces DESIGN.md missing 3 critical sections (Style Prompt, Motion, What NOT to Do) that the skill depends on. Two different systems disagree on what DESIGN.md contains. + +2. **Instruction decay.** The 450-line monolithic SKILL.md causes Lost-in-the-Middle attention collapse. Shader instructions (the biggest visual differentiator) sit in the middle of a long document and are ignored in 100% of existing compositions. + +3. **Context overflow.** "Read ALL files, do not skip any" triggers 100+ tool calls. By the time the agent finishes viewing 42 images, the first 10 are compressed out of context. + +4. **RGB/HEX mismatch.** Token extractor outputs `rgb()` format but every downstream consumer expects `#HEX`. + +5. **Shader transitions require building from scratch.** The agent must read 900+ lines of reference material across 3 files to wire a shader. 0% compliance rate. + +6. **No path for "from scratch" videos.** The hyperframes compose skill's Visual Identity Gate handles URL-based captures well but produces a minimal 4-field DESIGN.md for non-URL prompts. + +--- + +## Design + +### Part 1: Remove AI Auto-Generation from Capture Pipeline + +The capture pipeline becomes a pure data extractor. All intelligence lives in the agent session. + +#### Files to delete +- `packages/cli/src/capture/designMdGenerator.ts` + +#### Dependencies to remove from `packages/cli/package.json` +- `@anthropic-ai/sdk` +- `@google/genai` + +#### Changes to `packages/cli/src/capture/index.ts` +- Remove the AI key check block (lines 822-853). Replace with: + ```typescript + progress("design", "DESIGN.md will be created by your AI agent"); + ``` +- Remove `hasDesignMd` variable and its usage in `generateAgentPrompt()` call +- Remove the font paths collection block (lines 787-797) — only needed for the AI generator + +#### Changes to `packages/cli/src/capture/agentPromptGenerator.ts` +- Remove `hasDesignMd` parameter from `generateAgentPrompt()` and `buildPrompt()` +- Remove the conditional DESIGN.md row from the table +- Convert colors to HEX in the Brand Summary section (use a simple rgb-to-hex converter) +- The CLAUDE.md it generates should always say "DESIGN.md will be created when you run the workflow" + +#### Changes to `packages/cli/src/capture/tokenExtractor.ts` +- Convert all extracted colors from `rgb()`/`rgba()` to `#HEX` format at extraction time +- Add a `rgbToHex()` utility function + +#### New: Generate `extracted/asset-descriptions.md` during capture +- After asset download completes in `index.ts`, generate a one-line-per-file summary +- Source data: filename, file size, image dimensions (from buffer), HTML context from `assets-catalog.json` +- Format: `image-0.png — 1920x600, hero section, found in
"Financial Infrastructure"` +- For SVGs: `svgs/logo.svg — brand wordmark, 400x100 viewBox, found in