dsh-hyperframes 0.1.1 → 0.3.0

package/skills/website-to-hyperframes/references/step-1-capture.md

@@ -1,74 +0,0 @@
-# Step 1: Capture & Understand
-
-## Run the capture
-
-Create a project directory for your video, then capture the website into a `capture/` subfolder within it:
-
-```bash
-npx hyperframes capture <URL> -o <project-dir>/capture
-```
-
-Example: `npx hyperframes capture https://stripe.com -o videos/stripe-launch/capture`
-
-Keeping the capture artifacts (`screenshots/`, `assets/`, `extracted/`, `AGENTS.md`) in a dedicated `capture/` subfolder keeps them isolated from the later build files (`SCRIPT.md`, `STORYBOARD.md`, `DESIGN.md`, `compositions/`, `index.html`, `narration.wav`, `transcript.json`, `renders/`, `snapshots/`), which all live at `<project-dir>/` root.
-
-For exploratory captures that aren't becoming a video yet, `-o captures/<name>` at the repo root is fine — the isolation convention only matters when you're building a video on top of the capture.
-
-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 3.1 Flash Lite vision (~$0.001/image).
-
-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:
-   - `capture/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. **`capture/extracted/tokens.json`** — Note the top 5-7 colors (HEX), all font families with their weights (e.g. `Inter (400,700)` or `Sohne (100-900 variable)`), number of sections, and number of headings/CTAs.
-
-3. **`capture/extracted/visible-text.txt`** — Each line is prefixed with the HTML tag: `[h1] Heading`, `[p] Body text`, `[a] Link text`. Use these tags to understand hierarchy — headings are key messages, paragraphs are supporting copy. Strip the `[tag]` prefix when quoting text in the script.
-
-4. **`capture/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. **`capture/extracted/animations.json`** — Note if the site uses scroll-triggered animations, marquees, canvas/WebGL, or named CSS animations.
-
-6. **`capture/extracted/lottie-manifest.json`** — View each preview image at `capture/assets/lottie/previews/` to see what the animations look like.
-
-7. **`capture/extracted/video-manifest.json`** — View each preview at `capture/assets/videos/previews/` to see what each video shows.
-
-8. **`capture/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 `capture/assets/`** — Use `capture/extracted/asset-descriptions.md` as your index. View specific images when you need them for a beat.
-
-10. **`capture/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 capture/assets/ and every SVG in capture/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]

package/skills/website-to-hyperframes/references/step-2-design.md

@@ -1,178 +0,0 @@
-# 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 `capture/extracted/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 `capture/extracted/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 — `capture/extracted/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.
-```
-
-Here is a contrasting example from a light, corporate brand to show the range:
-
-```markdown
-# Design System
-
-## Overview
-
-Stripe's visual personality is defined by high-precision, technical sophistication, and a fluid, forward-moving motion language. The layout is dense but expertly balanced, utilizing a "canary" grid system that favors high-density data visualizations and modular bento-style layouts. The tone is authoritative and innovative, characterized by smooth CSS animations, complex SVG graphics that mimic UI dashboards, and the iconic "hero wave" background that uses layered gradients to create depth and movement.
-
-## Colors
-
-- **Brand Primary**: #635bff (The signature Stripe Blurple)
-- **Text Solid**: #0a2540 (Deep navy for primary headings)
-- **Text Soft**: #424770 (Subdued slate for descriptions and secondary text)
-- **Surface Background**: #ffffff (White primary surface)
-- **Surface Subdued**: #f6f9fc (Light gray for section contrast)
-- **Accent Green**: #212d45 (Used in high-converting success UI graphics)
-- **Accent Orange**: #ff6118 (Used for specific product highlights like Connect)
-- **Accent Yellow**: #fc5 (Warm highlight used in bento cards)
-- **Border Quiet**: #e6ebf1 (Soft borders for cards and dividers)
-
-## Typography
-
-- **Primary Font**: Sohne (sohne-var), a custom neo-grotesque that balances technical precision with approachability. Used across all headers and body copy.
-- **Monospace Font**: SourceCodePro-Medium, specifically for code snippets, tabular data, and technical UI identifiers.
-- **Heading Scale**: hds-heading--xxl ~3rem, hds-heading--lg ~1.5rem, hds-heading--md ~1.125rem
-- **Body Scale**: Standard body text centers around 1rem (16px) with a line-height of 1.5-1.6.
-
-## Elevation
-
-- **Shadows**: Multi-layered shadow system (e.g., 0 30px 60px -12px rgba(50,50,93,0.25)). Shadows are diffused and deep for a floating effect.
-- **Borders**: Heavy use of 1px solid borders to define bento grid boundaries instead of shadows in flat sections.
-- **Glass/Layering**: Navigation overlays use backdrop-filter blur(5px) with translucent white background.
-
-## Components
-
-- **Navigation Popover**: Animated dropdown spanning page margin with multi-column bento layouts.
-- **Bento Cards**: Interactive grid-aligned containers with gradient hover effects that follow the cursor.
-- **Customer Marquee**: Seamless horizontal scrolling loop of flat-colored SVG logos.
-- **UI Graphics**: Custom HTML/CSS representations of the Stripe Dashboard with tabular numbers and mini-charts.
-- **CTA Buttons**: Rounded-pill shapes with subtle scale transforms on hover.
-
-## Do's and Don'ts
-
-- **Do**: Use smooth cubic-bezier(.25, 1, .5, 1) transitions for all hover states and entering animations.
-- **Do**: Maintain strict vertical alignment between iconography and text labels.
-- **Don't**: Use sharp-cornered cards; always apply a border-radius.
-- **Don't**: Over-saturate backgrounds; stick to white or #f6f9fc and let brand assets provide color pop.
-```

package/skills/website-to-hyperframes/references/step-4-storyboard.md

@@ -1,246 +0,0 @@
-# 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.
-- **`capture/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)** — 11 visual techniques (SVG path drawing, Canvas 2D art, CSS 3D, per-word typography, Lottie, video compositing, typing effect, variable fonts, MotionPath, velocity transitions, audio-reactive). 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: `capture/assets/wave-fallback-desktop.png` — full-bleed, slow zoom 1→1.04 over beat duration"
-- "Logo: `capture/assets/svgs/stripe-logo.svg` — centered, fades in at 0.5s"
-- "Enterprise photo: `capture/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.
-
-**When to pick which:**
-
-| Choose shader transition for                                                    | Choose CSS transition for                                                           | Choose hard cut for                                            |
-| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------- |
-| Reveals, big reaction shots, product/logo unveils, energy shifts, "wow" moments | Continuous camera-motion beats where the scene feels like one move broken into cuts | Rapid-fire lists, percussive edits on the beat, comedic timing |
-| Any moment the music/VO punctuates with a downbeat or SFX hit                   | Beats that ease from one composition into the next with shared motion vocabulary    | Sequences of 3+ quick tempo-matched switches                   |
-| Brand moments where the transition itself _is_ the visual                       | Minimal/editorial pacing                                                            | Anytime a 0.3-0.8s transition would feel too slow              |
-
-Rule of thumb: if the beat is the _centerpiece_ of the video, shader-transition into it. If the beat is connective tissue, CSS-transition. A brand reel of 5-7 beats usually wants 1-2 shader transitions (the hero reveal + the CTA) and the rest CSS or hard cuts — too many shader transitions flatten their impact.
-
-**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 `packages/shader-transitions/README.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 `packages/shader-transitions/README.md` for the full API, available shaders, and setup
-
-**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)
-├── capture/                      captured website data (from Step 1)
-│   ├── screenshots/
-│   ├── assets/
-│   │   ├── svgs/
-│   │   ├── fonts/
-│   │   ├── lottie/
-│   │   └── videos/
-│   ├── extracted/
-│   │   ├── tokens.json
-│   │   ├── visible-text.txt
-│   │   ├── asset-descriptions.md
-│   │   ├── animations.json
-│   │   ├── assets-catalog.json
-│   │   └── detected-libraries.json
-│   └── AGENTS.md
-└── 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.

package/skills/website-to-hyperframes/references/step-5-vo.md

@@ -1,42 +0,0 @@
-# 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.
-
-**Also save the exact spoken text** — with pronunciation substitutions applied (e.g., `API` → `A P I`, `$2T` → `two trillion`) — as `narration.txt` in the same directory. This is the string passed to TTS, distinct from `SCRIPT.md` which is the human-readable creative doc. Having `narration.txt` makes it trivial to regenerate the audio later with a different voice without re-deriving the substitutions. Name it exactly `narration.txt`.
-
-## 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.