Three non-obvious HyperFrames (HTML-to-MP4) behaviors that cost real debugging time: WebGL shader transitions silently degrade to plain playback, audio is authored as clip elements (no render flag), and init re-installs skills despite --skip-skills.
Discovered while auditing a HyperFrames-based short-form video pipeline (hyperframes 0.7.10, global npm install).
1. Shader transitions fail silent. @hyperframes/shader-transitions (14 GLSL transitions: domain-warp, sdf-iris, whip-pan, flash-through-white, glitch, cinematic-zoom, light-leak, chromatic-split, ripple-waves, gravitational-lens, swirl-vortex, thermal-distortion, cross-warp-morph, ridged-burn) falls back to plain playback when WebGL is unavailable in the render browser — no error, no lint, the video just renders with hard cuts/crossfades instead. Headless capture may run SwiftShader or no GL at all depending on --browser-gpu/--no-browser-gpu. Verification technique: npx hyperframes snapshot --at <each transition midpoint> and visually confirm the mid-frame shows warp/iris/pan distortion rather than a crossfade. Budget a CSS-transition fallback (clip-path wipes, blur crossfade) for GPU-less environments.
2. Audio is composition-level, not CLI-level. There is no render-time audio flag; the renderer muxes whatever <audio> elements exist in the composition HTML: direct children of the composition root with data-start/data-duration/data-track-index/data-volume (<video> must stay muted; sound rides separate <audio> elements). Volume fades/ducking = tweening volume on the GSAP timeline; the runtime probes volume keyframes and applies them identically in preview and render. Gotcha: the duplicate_audio_track lint fires when two concurrent sounds share a track index — the fix is distinct data-track-index values per overlapping sound, NOT deleting the audio element (observed an agent 'fix' the lint by shipping a silent video).
3. init --skip-skills doesn't skip. As of 0.7.10, npx hyperframes init checks installed skills against the GitHub repo and re-installs the full 21-skill set even with --skip-skills; the only effective opt-out is the env var HYPERFRAMES_SKIP_SKILLS=1. Relevant if you maintain locally patched skill copies or want hermetic CI.