Mined launch-video, launch-video-2, and claude-design-hyperframes-video
projects for production-grade compositions and lifted 6 of them into the
examples library as the BAR scenes for previously-empty sections.
Lifts (all PASS QC via contact sheet review):
Section 03 easing-variety
scene-01-css-animation-grid ← launch-video/compositions/flex-css.html
6x3 grid of pure-CSS animations: spinners, pulses, morphs, waves,
orbits, gradient cycles, flip cards, bars, bounces. Duration extended
from 1.71s to 3.5s so snapshot intervals catch distinct motion states.
Section 07 html-in-canvas
scene-01-webgl-shader ← launch-video/compositions/flex-shader.html
WebGL fragment shader with domain-warp FBM noise + cosine palette.
Canvas 2D fallback UPGRADED from static gradient to animated multi-stop
radial + iridescent linear sweep so the fallback is also a good pattern
to copy.
Section 08 svg-and-path
scene-01-vinyl-record ← launch-video/compositions/flex-music.html
SVG vinyl record (7 concentric grooves, label, shine, tonearm
pivot/shaft/cartridge/stylus). Duration extended 0.58s → 3s for visible
spin across snapshot intervals.
Section 11 3d-and-parallax
scene-01-css-3d-torus ← launch-video/compositions/flex-threejs.html
16-segment orbital ring of pastel rounded squares rotating through 3D
space via transform-style: preserve-3d + perspective. Pure CSS, no
Three.js library required despite the source's filename.
Section 12 combined-vignettes
scene-01-techniques-grid ← claude-design-hyperframes-video/compositions/grid.html
GOLD: 6x4 grid of 24 cells, each running a different visual technique
(clock, rings, stripes, 3D cube, dot grid, QR, stock chart, blob morph,
particle vortex, glowing orb, spirograph, DNA helix, neural network,
burst rays, kinetic MOTION word, glitch SYSTEM->RENDER text, sine waves,
code editor, spinners, binary rain, maze, audio bars, neon globe,
weather card). Single highest-density technique reference in the library.
Rebranded CLAUDE -> MOTION and DESIGN -> RENDER. Source's innerHTML build
replaced with createElementNS for security-hook compliance.
Section 01 typography (bonus scene)
scene-11-orbital-title ← claude-design-hyperframes-video/compositions/letters.html
KINETIC TYPE Fraunces serif title with per-character alternating-side
entrance + SVG accent line stroke draw + orbital ring rotation + radial
glow breathing + 4-segment type-on tagline. Rebranded HYPER FRAMES ->
KINETIC TYPE and HTML in. Video out. -> Code in. Motion out. (same char
counts so stagger math is unchanged). Source's onUpdate-driven tagline
refactored to pre-rendered char spans with autoAlpha stagger to fix
seek determinism.
Conversion process per scene: standalone HTML5 wrapper added (was a
<template> sub-composition), composition id renamed everywhere, scene-label
added at bottom-left, project-specific branding stripped, GSAP CDN linked,
data-start/data-duration added on root. Each lift was lint-clean (0 errors)
and snapshot-verified across 6-8 frames.
Library state after this batch:
Section 01 typography: 11 scenes
Section 03 easing-variety: 1 scene
Section 04 composed-ui: 8 scenes
Section 07 html-in-canvas: 1 scene
Section 08 svg-and-path: 1 scene
Section 11 3d-and-parallax: 1 scene
Section 12 combined-vignettes: 1 scene
Total: 24 production-grade scenes across 7 sections.
Sections 02, 05, 06, 09, 10, 13 still empty. Future sessions can lift
anatomy.html and engine.html (launch-video) into section 09 counters,
flex-gsap.html into section 10 particles, and continue filling out the
library.
Make the example library load-bearing in 4 places:
1. SKILL.md — new 'Step -1: Study the Example Library' BEFORE Step 0.
Mandatory: read examples/README.md + at least 3 scene HTMLs before
planning. Names which scenes are 'the bars' (04-composed-ui scene 01
kanban + scene 02 chat). Non-negotiable rule: if you'd reach for a
product screenshot of an interface as a primary visual, STOP and
build that UI from divs using the matching example scene.
2. step-3-storyboard.md — Technique-pick checklist after the pacing
table. Every beat must name 2-4 techniques AND cite the matching
example scene path. Beats with <2 cited techniques must be redesigned.
Forbidden: 'show the kanban' as a beat with no scene citation.
3. step-5-build.md — Copy-closest mandate added to the build section.
Concrete map from beat type to example scene path. Do not write
any beat from scratch; there is always a closer example.
4. beat-builder-guide.md — Example scene moved to the #1 mandatory
read for every beat. Sub-agents copy the cited scene's index.html
to compositions/beat-N-name.html and mutate, not write from scratch.
Specific call-out: if the beat has narration, also study
examples/04-composed-ui/scene-02-chat-with-typing — the canonical
narration-sync pattern (every meaningful phrase = one visual event).
This is the lever HANDOFF Recommendation 2 named: agents pattern-match
to what they study, not to skill prose. With 18 production-grade scenes
in the library and the workflow now requiring agents to copy them as
starting points, the screenshot+Ken-Burns default has somewhere better
to go.
The highest-leverage section in the library. Every scene demonstrates a
product UI element built from divs + GSAP — zero screenshots, zero
captured assets. Directly addresses the 'every agent screenshots the
kanban / chat / dashboard / terminal' failure mode from the 11 eval runs.
Section 04 scenes (all PASS QC):
01 kanban-board — 3-column kanban with cards entering staggered,
drag-from-Todo-to-In-Progress with shadow ramp,
column count chip pulse on drop
02 chat-with-typing — chat panel with 3 messages, reaction emoji
burst, typing indicator (3 bouncing dots),
self-reply slide-in. Every visual event lands
at a narration anchor timestamp. THE
narration-sync gold standard.
03 terminal-typeon — terminal window with multi-line command +
output type-on (steps(1) ease), green exit
badge with elastic settle + floor glow.
04 command-palette — Cmd+K modal with backdrop blur, keystroke
entry, real-time filter, focus ring on top
result, dismiss + action toast + new activity.
05 dashboard-counters — 4 KPI cards, counter 0→128K via deterministic
tl.set(textContent), sparkline stroke-dashoffset
draw, donut fill 0→87%, multi-stat ticks,
live mode with status pulses.
06 file-tree-reveal — VS Code-style file tree, folders expand
progressively, selection bar slides into
place, editor opens parse.ts with syntax
colors, git modified badges pulse.
07 code-editor-typing — multi-line type-on with per-span syntax colors,
red error squiggle + tooltip + status bar
flip, fix typed via tl.set(textContent),
status returns to blue.
08 calendar-events — weekly grid with today highlighted, 6 events
slide in staggered, 'happening now' event
pulses, popover slides up with attendees,
red 'now' time indicator drifts.
Authored by hand: scenes 01 and 02 (the bars). Scenes 03-08 dispatched
to parallel sub-agents using scenes 01-02 as templates; every return was
visually QC'd via contact-sheet review before being marked PASS in the
section README.
First slice of the HyperFrames Capability Showcase library at
skills/website-to-hyperframes/examples/. Each scene is a self-contained
mini-project (index.html in its own directory) that lints, snapshots, and
renders standalone.
Section 01 (typography) — 10 production-grade scenes, all PASS QC:
01 soft-blur-in — Apple keynote per-character reveal
02 typewriter-mechanical — stepped per-char terminal type-on
03 kinetic-center-build — words push in right-to-left, lock center
04 line-reveal-staggered — editorial mask-reveal-up with Fraunces italic
05 stagger-wave — center-out vs edges-in stagger origins
06 variable-font-weight-shift — wght 100→900 animation via @property
07 shared-axis-crossfade — Material Design Z-axis depth transition
08 glitch-rgb-split — RGB channel offset with mechanical jitter
09 scramble-decrypt — per-char intermediate substitution decrypt
10 per-word-emphasis — per-word crossfade + hand-drawn marker
Plus catalog + shared assets:
- examples/README.md — top-level index + lookup by technique
- 01-typography/README.md — section spec + QC log per scene
- _shared/hyper-shader-local.js — copied from packages/shader-transitions/dist/
- _shared/shared-styles.css — design tokens
- _shared/easing-glossary.md — single source of truth for easings
Authoring conventions are documented in examples/README.md so future scenes
follow the same shape: full HTML doc, GSAP CDN, CustomEase, data-composition-id/
start/duration/width/height on root, scene-label at bottom-left, continuous
motion (no static periods >1.5s), easing variety (3+ different easings).
.gitignore: fixed bare 'examples/' rule (matched anywhere) to '/examples/'
(root-only), and added rule to skip snapshot artifacts inside the library.
The #1 quality problem: agents write entrance tweens in the first 1-2 seconds
of a beat, then nothing happens for the remaining duration. A 13-second beat
with 6 tweens = 11 seconds of static content.
step-3: Animation Sequence section now explicitly requires events spanning
the FULL beat duration. Nothing unchanged for more than ~2 seconds.
beat-builder-guide: "Continuous motion" added as the first and most important
rule — above all technical rules. Ken Burns drift, parallax, breathing,
secondary elements appearing mid-beat.
snapshot: report loaded vs failed fonts via document.fonts API
step-3: pacing is FIRST decision at top of file
step-2 + SKILL.md: no more creative summary confirmation
step-5: sub-agent prompt includes explicit snapshot + lint commands
step-3: distinguish product assets from decorative assets — product
screenshots show what the product does, decorative images can be backgrounds
but shouldn't be the beat content. Never use contact sheets or scroll
screenshots in the video (they have grid labels baked in).
step-2: remove Creative Direction Summary confirmation — agents were
rephrasing the user's prompt and asking "does this match?" The storyboard's
Global Direction section already captures the same info. Proceed directly
to Step 3.
HeyGen TTS v3 API verified: response shape { "data": { "audio_url",
"duration", "word_timestamps" } } is correctly documented.
Sub-agents now read beat-builder-guide.md directly instead of relying on the
main agent to paste rules into the prompt (which truncated easing, validation,
and file references). The guide has:
- Full reference table: capabilities.md, techniques.md, text-effects.md,
html-in-canvas-patterns.md, transitions/, css-patterns.md, audio-reactive.md,
captions.md, typography.md, motion-principles.md, dynamic-techniques.md,
video-composition.md + all loadable skills (gsap, animate-text, lottie, three, etc.)
- Build → lint → snapshot → verify → report workflow
- Rules, easing vocabulary, composition template
- Self-verification: sub-agents snapshot their own beats and fix issues before reporting
Step-5 template simplified: just paste beat spec + brand values + asset paths,
tell sub-agent to read beat-builder-guide.md. No more 90-line inline rules block.
SKILL.md: sub-agent mode on by default, "no sub-agents" option for sequential build.
The easing table was after the RULES section in step-5. Sub-agent prompts
paste ═══ RULES ═══ through the end of rules but stop before the easing
section. Result: 0/4 v8 agents used any non-default easing.
Fix: condensed easing guidance into a single RULES bullet that gets pasted
into every sub-agent prompt. power4.out for snap, back.out(1.7) for impact,
expo.out for soft land, elastic.out for bounce, expo.inOut for dramatic.
step-2-brief.md previously said "Do NOT skip this step" and forced agents to
ask all 5 questions even when the user's prompt already specified video type,
style, and specific scenes. Now: parse the prompt first, skip questions that
are already answered, only ask about gaps.
cli: auto-load .env from CWD so GEMINI_API_KEY/HEYGEN_API_KEY work without
source .env — agents no longer need to manually export keys
snapshot: rename frames to seconds (e.g. frame-00-at-4.2s) instead of
pct (frame-00-at-20pct) — more useful when comparing against storyboard
screenshotCapture: dismiss marketing banners, cookie consents, and
modals before scrolling — prevents popups contaminating screenshots
step-6: replace verbose manual review instructions with:
- required reads: descriptions.md AND contact-sheet.jpg (both)
- critic sub-agent prompt for honest constructive quality assessment
before showing anything to the user
Both commands have critical fixes only in the local build:
- capture: paginated contact sheets, SVG root scan
- snapshot: sub-comp wait, local-time seek, Gemini descriptions
Published npx hyperframes 0.6.6 missing all of these.
Added warnings to step-0 and step-6 so agents cannot miss it.
Catches ../capture/ in sub-composition files — the most persistent
sub-agent mistake across v1-v4 (100% failure rate on framer, 4+ rounds).
Documentation rules in sub-agent prompts were not sufficient.
The rule fires as a hard error so lint fails until paths are corrected.
../capture/ works on disk but breaks in Studio and renders (Studio rewrites
base URLs to the project root). Must use capture/ not ../capture/.
Verified: fires correctly on compositions with ../capture/ paths.
snapshot: add --describe flag (default on) for Gemini vision analysis
- describes every frame with the default prompt or a custom question
- auto-resizes 1920x1080 PNGs via sharp to stay under Gemini 4MB limit
- writes snapshots/descriptions.md for agents to compare against storyboard
- errors visible in descriptions.md instead of silently swallowed
- silent skip when GEMINI_API_KEY not set
step-5: block-name vs shader-name, css centering, last-scene workaround
step-4: kokoro ssml tags read as literal text
skill: autonomous mode when user signals skip collaborative gates
step-6: document --describe usage and descriptions.md workflow
Bug 1: snapshot fired before all sub-compositions loaded
- Old: resolved when keys.length >= 2 (first sub-comp registered)
- Fix: wait until all data-composition-src hosts have timelines
- Verified: beats 2-4 now visible in huly-promo v4 snapshots
Bug 2: sub-comp timelines seeked to global time, not local time
- Old: tls[key].seek(globalTime) — with exit animations, global t=29
clamps to GSAP end (t=7), elements at opacity:0 from exit fade
- Fix: seek to global_t - host.data_start (correct local time)
- Verified: beat-5 (starts at t=26.7) seeked to local t=2.3 at
global t=29 — 'Join the Movement' now visible in snapshots
Both bugs confirmed via render vs snapshot comparison before fixing.
Also fix HeyGen v3 API docs: response is data.audio_url not audio_url
directly; word_timestamps uses 'word' key not 'text' — normalize before
saving as transcript.json
skill/SKILL.md: remove Step 5.5 Self-Critique (agents couldn't verify
visuals via snapshots anyway; step was theoretical without visual feedback)
step-1-design.md: 9 sections → 8
- remove Responsive Behavior section (video is fixed 1920x1080)
- remove Inputs/Forms, Navigation, Links from Component Stylings
(these are never used in video compositions)
- rename and keep Agent Prompt Guide (most-consulted section per docs)
- remove 200-400 line target (was driving padding)
step-3-storyboard.md: remove Implementation References per-beat block
- was the most verbose part of the storyboard template
- sub-agent template in step-5 already handles targeted file reads
- agents were filling it mechanically without adding value
evidence: v2+v3 agents reporting 40% of session time spent reading docs;
storyboard writing cited as second biggest time sink
snapshot: auto-clear png/jpg files before each run so old frames don't
mix into contact sheets (confirmed issue from loom v3 agent report)
step-4-vo: update HeyGen TTS to v3 API (current; v1/v2 deprecated Oct 2026)
- list voices: GET /v3/voices?engine=starfish, response is data[] direct list
- generate: POST /v3/voices/speech, returns audio_url + word_timestamps
- HeyGen v3 no longer needs separate transcription step
- v2 data.voices shape documented as legacy
step-5-build RULES: add HyperShader+beat timing rules from v3 findings
- timeline:tl pattern breaks scrubber — let HyperShader create timeline
- proxy+onUpdate doesn't fire in seek mode — use discrete tl.set() calls
- shader name validation: check ls registry/blocks/ before writing
step-3-storyboard: add Beat Timing section to each beat template
- agents specify transition-in time + GSAP duration so step-5 can set
data-start and data-duration without guessing
root cause verified from arc-launch v3 render analysis:
- all beats had data-start=0 and data-duration=26 (total video length)
- engine seeks each beat's sub-composition to global_time - data_start
- with data-start=0, beat-2 (BEAT=5.5s GSAP) is seeked to global_t=7
- gsap timeline exhausted at t=5.5, engine marks sub-comp invisible
- content disappears exactly at each beat's GSAP timeline end
fix verified: sequential data-start per transition point + data-duration
matching each beat's GSAP duration → all beats render correctly
added concrete code example to step-5-build.md with explanation
step-3: sfx placement rules grounded in audio production standards
- impact sounds: trigger at visual moment, let decay tail bleed (J-Cut)
- riser/build-up: trigger at climax_time - sfx_duration so peak lands on moment
- data-duration must equal manifest duration, never trimmed to fit beat time
- volume under narration: 0.2-0.3 max (no auto-ducking in HyperFrames)
- vo start timing: explicit storyboard decision, document in Global Direction
step-5: asset path rule as first sub-agent rule, impossible to miss
- @font-face: paste declaration into sub-agent prompt explicitly
- Inter Variable -> Inter (compiler only maps base name)
- querySelector null guard: getElementById for elements inside beat hosts
- wcag gradient false positive: data-layout-ignore for decorative elements
- captions stacking: initial opacity:0, one group visible, verify with snapshot
step-4: kokoro pronunciation guidance
- known failure patterns: Vercel, WorkOS, One API
- phonetic substitution workflow: test first sentence, fix in narration.txt
snapshot: fix two shader pre-render wait failure modes
- Cold cache: overlay stays in DOM as display:none after hiding,
element-absence check never resolved, always timed out at 60s
- Warm cache: IndexedDB hydration runs without overlay, absence check
resolved instantly while prewarming was still in progress
- Fix: primary signal is window.__hf.shaderTransitions[].ready;
overlay display:none is fallback for older builds
- Verified: huly-promo snapshots show composition content, not loader
shader-transitions: optional shader field for CSS crossfade mixing
- TransitionConfig.shader is now optional (ShaderName | undefined)
- Omitting shader = smooth CSS opacity crossfade via fallback path
- CSS-only transitions skip program compilation and prewarming
- HfTransitionMeta.shader made optional in engine/src/types.ts
- Verified: mixed CSS + WebGL composition renders all three beats correctly
step-3-storyboard: SFX assigned here with exact files, not in Step 5
- Agent reads sfx/manifest.json and assigns exact filenames per moment
- Less-is-more: most beats need zero SFX, one max per beat
- Removed duplicate HTML-in-Canvas API detail (build concern, not storyboard)
step-5-build: implement storyboard SFX exactly, zero creative decisions
step-4-vo: required timing reconciliation gate before Step 5
- Compare real audio vs planned total; if delta >15% rescale or trim
- Hard cap on CTA hold: 2-3s after last word, not extended dead silence
- HANDOFF.md: 747-line context doc for the May 15-16 pipeline quality session
(git state, all skill changes, eval arena, video locations, key discoveries)
- AGENT-FEEDBACK-V2.md: 7-agent post-run friction report with priority action
items (P0: HyperShader CSS crossfade bug, snapshot loading-screen blindspot)
- CLAUDE.md: add READ HANDOFF.md FIRST notice at top for new sessions
Old step files from before the pipeline v2 restructure were still tracked
alongside the new versions, causing agents to see a conflicting dual pipeline.
Removed: step-1-capture, step-4-storyboard, step-5-vo, step-6-build,
step-7-validate, composition-guide, generate-skeleton.mjs
- contactSheet.ts (new): paginated grids for all asset types
- fit:contain replaces fit:cover — no more aspect-ratio cropping
- SVG scanner covers both assets/svgs/ and assets/ root directories
- agentPromptGenerator: semantic color role labels + dynamic page listing
- snapshot.ts: updated for string[] return from contact sheet functions
Generates pre-valid index.html + composition templates from STORYBOARD.md.
Bakes in: position:absolute, HyperShader wiring, autoAlpha toggles,
SFX placement from manifest, narration audio, grain overlays, scene
visibility management.
Sub-agents only fill creative content — no pipeline mechanics to learn.
Follows the claude-design-hyperframes.md pattern: code handles structure,
AI handles creativity.
Tested: passes lint with 0 errors on first generation.
Snapshot: HyperShader shows a loading overlay ([data-hyper-shader-loading])
while pre-rendering transition frames. Snapshots taken during loading show
"Preparing scene transitions" instead of content. Now waits up to 60s for
the overlay to disappear before capturing.
SVG captioning: Gemini captions for svgs/ subdirectory were generated but
never used in asset-descriptions.md. The generateAssetDescriptions function
had a separate code path for svgs/ that used bare "icon:" labels instead
of checking geminiCaptions. Now checks geminiCaptions first.
CTA beats are consistently under-animated (13 GSAP calls for 8-second
duration in v3 tests). Added explicit guidance: treat CTA with same
animation density as feature beats, minimum 15 GSAP calls, logo entrance
as an event not a fade.
Also clarified that beat count is agent's decision based on content —
no fixed number.
Created manifest.json for all 19 SFX files with exact duration from
ffprobe and Gemini audio analysis description. Updated Step 6 to
reference manifest instead of generic moment-type table.
Root cause of snapshot seeking bug: without position:absolute, beat divs
stack vertically in normal flow. The runtime sets visibility:hidden/visible
to toggle beats, but this only works when beats overlap in the same frame.
Verified: with position:absolute + local CLI, snapshots at t=15 correctly
show beat-4 content instead of beat-1 stuck at every timestamp.
Tested and confirmed: shader transitions work with sub-composition
pipelines. The pattern:
1. Add class="scene" to beat host divs in index.html
2. Load shader-transitions CDN script
3. Call HyperShader.init() with host div IDs and transition configs
4. Engine detects window.__hf.transitions and composites with shaders
Verified with minimal test: cross-warp-morph between two sub-compositions
rendered successfully (layered composite, 180 frames, SDR).
1. Capabilities Discovery: replace descriptive guidance with executable
commands (npx hyperframes list, ls registry/blocks/). Agent was told
to "check" but never ran the commands — now it has exact bash to run
and paste results.
2. SFX decoupled from storyboard: removed SFX listing from Step 4
Capabilities Audit. SFX are now wired in Step 6 Audio Wiring only,
matched to the storyboard's creative moments. Prevents creative
direction from revolving around the SFX inventory.
3. Font @font-face: rewritten to explain the auto-resolve system.
Common fonts (Inter, Roboto, etc.) skip @font-face. Brand fonts
use tokens.json for family mapping. Hashed filenames = Google Fonts
subsets that auto-resolve. Prevents agents from giving up on hashed
filenames.
4. SFX wiring table: added moment-type → SFX mapping so agents match
sound to emotion instead of listing files arbitrarily.
The producer's deterministicFonts.ts pre-bundles 18 font families as
data URIs (Inter, Roboto, JetBrains Mono, etc.). The lint rule was
falsely flagging these as missing @font-face. Now only warns for fonts
not in the pre-bundled FONT_ALIASES list — brand-specific fonts like
GT Walsheim or Aeonik that the producer genuinely can't resolve.
Fonts available via Google Fonts (Path 2) still trigger warnings since
they require network access at render time and may fail in sandboxed
environments.
The vision API rejects image/svg+xml, so SVGs were silently skipped during
Gemini captioning — leaving 97% of icons/logos undescribed. This caused
asset utilization as low as 3.8% on SVG-heavy sites (Huly, Raycast).
Now sends SVG source code as text to Gemini, which reads the XML structure
and describes what it renders. Truncates SVGs >10KB to keep token costs low.
Tested on Huly: 2/52 → 37/52 assets described (3.8% → 71%).
- Fix technique count: "10" → "11" in techniques.md and step-6 (was out of sync)
- Fix VFX registry names: npx hyperframes add --tag html-in-canvas (not bare name)
- Fix step-5 sequencing: remove "update index.html" before it exists in step-6
- Fix shader transitions: inline available shader names instead of repo-only path
- Fix launch-video-2 reference: replace inaccessible file path with inline metrics
- Upgrade Gemini API key from "optional" to recommended with user prompt
Two new lint rules that catch the #1 composition quality failure:
- google_fonts_import: warns on fonts.googleapis.com in <link> or @import
- font_family_without_font_face: warns when font-family CSS has no matching @font-face
Verified against 3 baseline sites (framer, raycast, workos) — correctly detects
all font loading failures found in manual A/B testing.