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.
The property delegation on window.__player used Object.defineProperty
with only a getter, causing "Cannot set property renderSeek which has
only a getter" when Studio's motion-wrapping code tried to reassign
__player.renderSeek with a wrapped version. This cascaded into an
infinite error loop making the timeline unusable.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The postMessage state path set `_currentTime` without clamping, while the
direct timeline path already used `Math.min(currentTime, _duration)`. A
final-frame state message with a frame count slightly past the end would
set `_currentTime > _duration`, causing the progress bar (position:
absolute, no overflow guard) to bleed out of the scrubber track and
visually cover the volume button, and the time display to show values
like "0:05 / 0:04".
- Clamp `_currentTime` in `_onMessage` to match the direct timeline path
- Clamp defensively in `updateTime` so the display layer never overflows
- Add `overflow: hidden` + `min-width: 0` to `.hfp-scrubber` as a CSS
safety net; remove now-redundant `border-radius` from `.hfp-progress`
(parent `overflow: hidden` handles clipping to the rounded shape)
- Apply the same `overflow: hidden` fix to `.hfp-volume-slider` for
consistency; remove redundant `border-radius` from `.hfp-volume-fill`
- Add regression test covering the postMessage over-duration case
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Add mintlify docs page for contributing blocks/components to the
registry catalog. Rename skill from contribute to contribute-catalog
for clearer intent.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Narrow description to disambiguate from hyperframes-registry (install)
and hyperframes (in-project authoring) skills
- Add "adjust" comments on dimensions/duration defaults so agents don't
blindly copy 1920x1080/10s for all composition shapes
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>