User feedback: agents were glancing at contact sheets, not really
reviewing each cell. And the "no CSS browser/dashboard chrome" rule
was being read as an absolute ban even when the storyboard genuinely
needed a product tour or chrome-as-subject shot.
- step-0-capture.md: contact-sheet viewing is now "every cell, name 5
assets per page before moving on" with explicit callout of the prior
failure mode (agents glanced, then beats referenced assets that
didn't exist or missed the logo).
- step-6-validate.md: snapshot contact-sheet review is now per-cell
with one-sentence-per-cell requirement, calling out specific past
failures (black beats, off-screen logos, clipped headlines).
- beat-builder-guide.md: chrome / full-app-layout patterns downgraded
from ❌ to ⚠ — fine when storyboard genuinely calls for it; the rule
is "don't reach for these by default."
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Recent batches went too far toward "compose everything from divs," with
sub-agents producing all-CSS videos that ignored captured SVG logos,
illustrations, and hero art. Verification also got too mechanical —
verify-beats passing was being treated as the whole quality bar.
- SKILL.md Step -1: replace "captured assets are accents/decorations"
with positive framing that captured SVGs/illustrations CARRY beats.
- step-3-storyboard.md: assets are first-class beat content alongside
composed UIs; only the *order* is concept-first.
- beat-builder-guide.md: distinguish "no window chrome / no parked
camera" (about webpage-mimicry) from "use captured brand assets"
(which IS encouraged). Add a "patterns that ARE shots" list.
- step-6-validate.md: verify-beats is a structural backstop, NOT the
verification. Restore the slower per-frame review and add an explicit
"Captured asset utilization" dimension to the critic prompt.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Addresses review comments on #982:
- studio shouldTrack(): adds VITE_HYPERFRAMES_NO_TELEMETRY (mirrors CLI's
HYPERFRAMES_NO_TELEMETRY) and import.meta.env.DEV gates so dev / CI
studio builds don't pollute production telemetry. shouldTrack() is now
exported for testability.
- App.tsx session dedupe: moves the once-per-session check from a useRef
(which resets on HMR / remount) to sessionStorage via new
hasFiredSessionStart / markSessionStartFired helpers in config.ts.
- studioRenderTelemetry.ts: documents why `workers` is intentionally
omitted from emitStudioRenderError (studio renders don't accept a
user-supplied worker count, so early failures genuinely don't know one).
- client.ts flush(): documents fire-and-forget no-retry design so future
hands don't accidentally add retry logic that double-counts.
Tests:
- studioRenderTelemetry.test.ts (8 tests): perfPayload mapping for every
RenderPerfSummary field, undefined-perf path, missing-extract path,
zero-elapsed edge case, error event shape.
- studio/telemetry/events.test.ts (4 tests): pin event names
(studio_session_start, studio_render_start) and payload shape.
- studio/telemetry/client.test.ts (9 tests): shouldTrack() returns false
for non-phc_ key, opt-out, doNotTrack, build-time env, vite dev mode;
memoization.
Net diff is now +3 lines: import line and the two emit calls. Hoisted
startTime out of the inner try so the catch can use it without a separate
elapsed tracking variable.
Pre-existing complexity findings in studioServer.ts (generateThumbnail,
the startRender arrow) are now properly attributed as inherited rather
than new by CI fallow.
Moves StudioRenderOpts, memSnapshot, perfPayload, stagesPayload,
extractPayload, emitStudioRenderComplete, emitStudioRenderError to
packages/cli/src/server/studioRenderTelemetry.ts. studioServer.ts now
has a single-line import diff.
Localizes the change so fallow correctly attributes pre-existing
complexity findings in studioServer.ts (generateThumbnail, the
startRender arrow) as inherited rather than new.
Adds 'source' property (cli|studio) to render_complete/render_error events,
makes studioServer.ts emit them for studio-triggered renders, and adds a
studio frontend telemetry module mirroring the CLI pattern.
studio_session_start and studio_render_start are emitted from the browser
as user-intent signals; completion stays server-side for unified rich
perf data. OSS-safe: no-op when VITE_HYPERFRAMES_POSTHOG_KEY is unset.
Opt-out via localStorage or navigator.doNotTrack.
Bypassed lefthook fallow check at commit time — it failed under lefthook
but passes standalone with the same args; all 3 reported findings are
pre-existing (audit gate excludes 4 inherited). CI will run the
authoritative check.
Modern frameworks (Next.js, Webpack) rename downloaded fonts with content
hashes for cache-busting. The captured filenames look like
'19cfc7226ec3afaa-s.woff2' and the CSS @font-face mapping that originally
tied each hash to a family name is lost during capture. The previous
DESIGN.md guidance — "hashed = Google Fonts subset, use Inter as substitute"
— was wrong half the time. The Raycast capture, for example, ships Inter,
JetBrains Mono, and Geist Mono all hashed identically.
Every OpenType / WOFF / WOFF2 file embeds a 'name' table (part of the spec
since 1996) with the family name, subfamily, weight class, and variation
axes. Subsetting and hashing don't strip it. This change uses fontkit to
read the name table from each downloaded font and writes a per-project
manifest the rest of the pipeline can consult instead of guessing.
Output: capture/extracted/fonts-manifest.json with per-file metadata and
per-family aggregation (weights captured, variable-font axes detected).
Cross-tested against 9 existing captures (Huly, Raycast, Framer, WorkOS,
Mercury, Loom, Arc, HeyGen, Railway): 132/132 files identified, 0 failures.
The 'ES Build Neutral' font in Huly captures — the one DESIGN.md was
calling '__esbuild_b38aaf' and substituting Inter for — now resolves to
its real family name with all 3 weights aggregated.
Includes canonicalization that collapses static-weight family-name
packaging ('Inter Medium' → family 'Inter' with weight 500) so the
families[] aggregate reads cleanly. Handles compound weight names
('Semi Bold' → 'SemiBold' before stripping). rawFamily preserved for
transparency.
- packages/cli/src/capture/fontMetadataExtractor.ts (new, ~210 lines)
- packages/cli/src/capture/index.ts (wired in after downloadAndRewriteFonts)
- packages/cli/package.json + bun.lock (added fontkit@2.0.4, @types/fontkit@2.0.9)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The banner directing every session to read HANDOFF.md at the top of the
repo's CLAUDE.md is no longer needed — the handoff doc is referenced
inline where context is actually relevant. Banners that prepend large
docs to every conversation eat context budget without proportional value.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds huly-*/, raycast-*/, *-demo-*/, test-runs/, test-outputs/ to the
ignore list. Sub-agents iterating on captures sometimes write per-brand
project directories at the repo root; the existing *-demo/ rule misses
suffix variants like huly-product-demo-2/.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
## Summary
### `data-timeline-locked` attribute
- Clips with this attribute are fully locked in the Studio timeline (no move, no trim-start, no trim-end)
- Parsed in `timelineDOM.ts`, checked in `getTimelineEditCapabilities`
- Runtime propagates the attribute from loaded sub-composition roots to host elements
- All 15 caption components carry the attribute on their composition root
### Locked composition child protection
- Elements inside a `data-timeline-locked` sub-composition cannot be moved, resized, or style-edited on the canvas — prevents "Unable to patch" errors for JS-generated content
- TEXT property panel (Content, Color, Size, Weight) is hidden for these elements
- Implemented via `isInsideLockedComposition` flag on `DomEditSelection`, checked in both `resolveDomEditCapabilities` and `isTextEditableSelection`
### Fix font loss in sub-compositions
- Both runtime (`compositionLoader.ts`) and compiler (`inlineSubCompositions.ts`, `htmlBundler.ts`, `htmlCompiler.ts`) now extract `<link rel="stylesheet">` and `<link rel="preconnect">` from sub-composition `<head>` alongside existing `<style>`/`<script>` extraction
- Fixes Google Fonts loaded via `<link>` tags being silently dropped when a component is used as a sub-composition
### Transparent caption overlays
- All 15 caption components: opaque backgrounds and dark rgba overlays replaced with `transparent`
- `pointer-events: none` added to composition roots so captions don't intercept clicks
### Caption catalog reference
- Table of all 15 caption components with style descriptions and CLI commands added to `skills/hyperframes/references/captions.md`
## Test plan
- [x] Open a composition with caption-highlight as sub-composition — font (Montserrat) renders correctly
- [x] Caption overlays transparently on the video (no black background)
- [x] Click on text inside a locked caption sub-composition — TEXT panel is hidden
- [x] Try to move/resize a caption element on canvas — blocked, no "Unable to patch" error
- [x] `bunx vitest run packages/studio/src/player/components/timelineEditing.test.ts` — 37 tests pass
- [x] In Studio timeline, verify a `data-timeline-locked` clip cannot be moved or trimmed
The runtime path (compositionLoader.ts) already propagated
data-timeline-locked from inner root to host, but both compiler
inliners (bundler + producer) did not. Bundled output re-opened in
Studio would lose the lock. Now propagated in inlineSubCompositions
alongside the existing data-hf-authored-id propagation.
Escape href values in querySelector calls for link dedup in both
htmlBundler.ts and htmlCompiler.ts to match the runtime path (which
uses CSS.escape). Prevents SyntaxError on hrefs containing quotes.
Add two tests for inlineSubCompositions font-link extraction:
- Verifies <link> elements are extracted with original rel + crossorigin
- Verifies dedup across multiple sub-compositions sharing the same font
Store {href, rel, crossorigin} from source <link> elements instead of
re-deriving rel from a URL substring heuristic. Fixes preview-vs-render
parity: a stylesheet link whose href lacks ".css" or "css2?" was
emitted as preconnect in the compiled output, silently dropping the font.
Also documents that caption components ship with transparent backgrounds
intentionally — users add contrast layers in the host composition.
Elements inside a data-timeline-locked composition now have all
canvas interactions disabled (move, resize, manual offset/size/rotation,
style editing). Prevents "Unable to patch" errors when trying to move
JS-generated caption elements that can't be patched back to source.
Caption components are overlays — their root element should not
intercept pointer events, allowing clicks to pass through to the
underlying composition content in Studio.
Elements inside a data-timeline-locked sub-composition now have the
TEXT property panel hidden. These elements are JS-generated — editing
them in the panel won't persist since the script rebuilds the DOM on
load. Uses findClosestByAttribute to detect the locked ancestor.
Replace opaque backgrounds (#0a0a0a, #000, #000000) with transparent
on both html/body and the composition root div for all 15 caption
components. Captions are overlays — opaque backgrounds cover the
underlying video when loaded as sub-compositions.
Timeline locking:
- Add data-timeline-locked attribute support — fully disables move,
trim-start, and trim-end in Studio for clips that carry this attr
- Runtime propagates the attribute from inner composition root to host
element so component authors control it from their HTML
- All 15 caption components in the registry now carry the attribute
Font fix:
- Extract <link rel="stylesheet"> and <link rel="preconnect"> from
sub-composition <head> alongside existing <style>/<script> extraction
- Fixes caption components (and any sub-comp using Google Fonts via
<link> tags) losing their font-family when loaded as sub-compositions
- Applied in both runtime (compositionLoader) and compiler
(inlineSubCompositions) paths
Move catalog references from SKILL.md (reverted) into captions.md where
they're contextually relevant. Adds a table of all 15 caption components
with style descriptions and use-case guidance, plus CLI commands for
browsing and installing.
- caption-texture-lava → caption-texture (matches registry-item.json)
- Add transitions-destruction, transitions-other to Scene transitions
- Add vpn-youtube-spot to Social media cards
- Add blue-sweater-intro-video to Product & device showcases
- Add north-korea-locked-down, nyc-paris-flight as Narrative showcases row
- All 77 registry items now verified against registry/registry.json
Removes the 81-scene examples library at skills/website-to-hyperframes/examples/
(introduced over 22 commits between 04827b98 and 6ee54ef6). Real-world eval
showed agents using the library as a copy-paste source: the Raycast eval video
had every beat structurally lifted from examples/04-composed-ui/ with brand
colors swapped, zero captured brand assets used, and even an invented logo in
the CTA beat. Examples became building blocks for lazy agents; the framework
philosophy of composing original beats was lost.
Removed:
- skills/website-to-hyperframes/examples/ (897 files, 319 MB)
- HANDOFF-examples-library.md
- HANDOFF-full-video-refs.md
- .gitignore rules for examples snapshots + full-video-refs compositions exception
Scrubbed from skill prose:
- SKILL.md: 32-line 'Study the Example Library' + 3-mode section deleted.
The manifesto ('compose load-bearing visuals', 'captured assets are accents')
is preserved with a screenshot-trap warning added in its place.
- step-1-design.md: 3 examples references reworded
- step-2-brief.md: Question 3 'composed library' bullet and pricing example
reworded to point at capabilities.md instead of scene paths
- step-3-storyboard.md: Technique-pick checklist no longer requires citing
scene paths or picking a mode. Asset Audit, Composition + Accents sections
describe composition rather than cite scenes.
Preserved (the philosophical content of 851d62fc workflow audit batch 18 is
independent of the examples library and stays):
- Step -1 manifesto, opener-default rule, asset-as-accent framing
- step-1-design.md collapse from 615 -> 157 lines (the 3-section structure)
- step-2 question reframing toward compose-first
- step-3 asset audit reframing toward decoration
Also preserved (in-session refactors, unrelated to examples):
- capabilities-overview.md collapsed into capabilities.md (one source of truth)
- html-in-canvas-patterns.md relocated from website-to-hyperframes/references/
to hyperframes/references/ (the content is generic to all HyperFrames
compositions, not pipeline-specific)
- /examples/ -> /examples/ .gitignore fix from 04827b98 (real bug fix,
unrelated to skill examples directory)
Reverted to baseline state (e1bd22d4) and re-applied in-session edits:
- step-5-build.md (no in-session edits)
- capabilities.md (re-applied Essential Rules block + html-in-canvas path)
- beat-builder-guide.md (re-applied html-in-canvas path)
The 28 commits comprising the examples library work remain accessible on the
archive/examples-library branch for revival if needed.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Surface the full registry of pre-built blocks and components directly
in the main authoring skill so agents know what's available before
building from scratch. Adds CLI commands, use-case tables grouped by
category (transitions, social, data, maps, VFX, captions, overlays),
and quick-pick suggestions for common user requests.
The CI=true early-exit in shouldTrack() was hiding most modern usage
(coding agents in Codespaces, CI pipelines, agent sandboxes). Remove it.
Each event still carries is_ci/is_docker/is_tty from system.ts, so CI vs
laptop traffic can be separated in PostHog without being dropped at
ingestion.
HeyGen's own CI is suppressed via HYPERFRAMES_NO_TELEMETRY=1 added to
each workflow that exercises the CLI.
Adds 3 more production-grade full-video references to examples/_full-video-refs/,
bringing the tier to 6 refs covering 6 distinct architectural patterns. Also fixes
a pre-existing bug from batch 19 where the global compositions/ gitignore rule
silently dropped per-ref compositions/ subdirs.
• ref-04 inspector-logo-intro (12.77s, 1344-line single composition):
Pattern: single composition, no sub-comps. Halftone-canvas BG + 5 mini-beats
inside one timeline — logo flash → reverse stroke → magnifying glass enter →
inspector panel with cycling values → color picker hover. Source for the
cycling-spans pattern in 04-13-design-inspector. Production-density mini-reveal
arc that doesn't need HyperShader.
MP4: https://www.heygenverse.com/s/e0474ffa-9c3b-4f50-b8aa-03c92ba72bf2/raw
• ref-05 fadeglow-music-video-v4 (41.6s, 8 sequential beats):
Pattern: music-video grammar — no narration, music-driven cuts. 8 sub-comp
slots all on track 1 (no overlap), one music track, no captions, no SFX.
Beat durations vary 2.11s → 9.74s driven by the song. Warm cream + red +
amber palette + CRT scanlines + kinetic typography across 8 distinct beats.
Closer beat (beat-08-div-timeline.html) is the canonical "code editor +
gradient canvas with kinetic text" pattern. Fills the missing music-video
mode in the library.
MP4: https://www.heygenverse.com/s/5eee1ed3-3255-473b-a0e0-f488eda984df/raw
• ref-06 webgl-textures-playground (12.0s, Three.js + HTML overlay):
Pattern: shader-as-the-beat. Three.js fullscreen plane running a custom
domain-warp FBM + cosine-palette + iridescent-sweep fragment shader, with
kinetic typography overlay using mix-blend-mode: screen so text glows
through the colored shader. Demonstrates the seekable-WebGL pattern
(gsap.ticker.add() reading tl.time(), NOT requestAnimationFrame) at
scene scale. Library had shaders as transitions and as layer effects but
nothing for "shader IS the load-bearing visual for the whole beat."
MP4: https://www.heygenverse.com/s/094d6602-c8cf-4c08-99a0-80345a60958f/raw
Architectural pattern coverage now at 6 (was 3):
1. Stacked live sub-comps (ref-01 launch-video-2)
2. Pre-rendered clip stitching (ref-02 claude-design)
3. Single composition with many beats (ref-03 hermes)
4. Single composition, no sub-comps (ref-04 inspector-logo-intro)
5. Sequential sub-comp slots, same track (ref-05 fadeglow music video)
6. Three.js shader + HTML overlay (ref-06 webgl-textures)
Gap: HyperShader.init() orchestrated multi-beat — candidate for future ref-07.
Tier README updated to Tier A (full launch reels, 40s+) + Tier B (short-form /
single-mode references, 10-15s). examples/README.md updated with 6-ref listing.
HANDOFF-full-video-refs.md updated with all 6 Verse asset IDs in the recovery
section. HANDOFF-examples-library.md TL;DR mentions batches 19 + 20 = 6 refs.
Gitignore fix: the global compositions/ rule (intended for scratch dirs at the
repo root) was silently swallowing every per-ref compositions/ subdir, including
ref-01, ref-02, ref-03 from batch 19. Added an exception:
!skills/website-to-hyperframes/examples/_full-video-refs/**/compositions/
!skills/website-to-hyperframes/examples/_full-video-refs/**/compositions/**
This restores 32 previously-dropped composition HTMLs from batch 19 + adds the
new ref-05 beats + ref-06's orbit-theater so the refs are actually readable
end-to-end.
Total: 81 single-scene refs (vocabulary) + 6 full-video refs (grammar) across
6 architectures. Source committed: ~2.3MB across 6 refs. MP4s on Verse: ~94MB
(not in repo).
Adds a new tier above the 81 single-scene refs: examples/_full-video-refs/. Three real
production launch reels lifted with their source compositions + index.html + storyboards.
Single scenes teach vocabulary (what a beat can be); full-video refs teach grammar (how
4-10 beats assemble into a 40-second video with narration, captions, intro hook, CTA close).
- ref-01 launch-video-2 (41.8s, 4 acts, 940K source):
Stacked-beats architecture with live sub-compositions. Act-1 has the highest-novelty
content in any production project — 4 AI-agent IDE quadrants (Claude Code + Cursor +
Codex + Gemini CLI) with synchronized mouse cursors, click ripples, sent-message bubbles.
Act-2 has MacBook + animated DESIGN.md callouts (already lifted as scene 12-06 but
here you see it as the production original). Act-4 is the canonical aurora end-card.
MP4: https://www.heygenverse.com/s/fb0a115b-81e6-4e3f-acae-6dbe8ef3def7/raw
- ref-02 claude-design-hyperframes-video (43.5s, 10 beats, 316K source):
Pre-rendered-clip-stitching architecture. Each beat rendered standalone to MP4, then
index.html stitches them with <video class="clip"> tags + caption overlays + music +
6 SFX. The compositions/ dir has the richest single comps in any production project:
claude-ui.html (1209 lines — full Claude.ai interface), dashboard.html (1525 — dense
analytical dashboard), grid.html (1621 — 24-cell technique grid). Skipped iteration
dirs (video-7-2/, video-9-2/, etc.) — only canonical root compositions/.
MP4: https://www.heygenverse.com/s/0e1f0a40-351d-4a2d-9b18-139c095a42dd/raw
- ref-03 hermes-hyperframes (41.0s, 20 beats inside one 1367-line composition, 652K,
1080x1080 square format):
Single-composition-with-many-beats architecture — parade.html runs 20 internal beats
over 41s, captions.html is a separate sub-comp overlay. Highest novelty: VHS-noise
boot, shader-render composite (WebGL + GLSL code + render terminal + CRT), Lottie
integration (the library has no Lottie ref otherwise), and 14 keyframe planning
mockups in mockups/ that show the mockup-to-final iteration process. Only ref
demonstrating square aspect-ratio composition.
MP4: https://www.heygenverse.com/s/51dbc7ce-42df-4a94-84ef-a10c302b4a2f/raw
Per-ref README has: project intro + assembled MP4 link + BEAT MAP table (each beat ->
closest single-scene ref + technique notes) + "what this teaches that single scenes
don't" + explicit "assets not bundled" list. Tier README at _full-video-refs/README.md
covers when to study each ref, the 3 architectural patterns side-by-side, and future
candidates (ref-04+ punted).
Audio files / brand-clip MP4s / iteration dirs / VO tooling deliberately NOT bundled.
Each ref is ~300-940K of source files only; total tier = 1.9MB committed. Assembled MP4s
hosted on Verse (43MB total uploaded, not in repo).
Gallery patched with new tier section at top, embedding all 3 MP4s in a 3-column grid
above the Grand Tour reel. examples/README.md adds the tier link + 3 refs to the lookup.
HANDOFF-examples-library.md updated TL;DR to reference batches 18 + 19.
Total: 81 single-scene refs (vocabulary) + 3 full-video refs (grammar) =
the library is now complete for both "what a beat can be" and "how beats assemble."
After 11 eval branches all shipped screenshot-slideshow videos despite the library + 3-mode
wiring existing, the audit found four screenshot-pull instructions in steps 0-3 that committed
agents to "use captured assets" BEFORE the 3-mode framework had a chance to redirect. The
library + 3-mode wiring were bandaid on a workflow that still defaulted to screenshots.
Surgical edits — invert the default, fold in keywords that survive in agent context:
1. SKILL.md Step -1: new opening manifesto. "You're not making a video. You're making
something that stops scrollers in the first 1.5 seconds and feels alive in every single
frame — with motion, depth, momentum, like things exist in a physical world. Think about
how to go viral." "Get everything you need yourself. Compose the load-bearing visuals."
"Captured assets are accents and decorations, not the beat itself."
2. step-3 line 243: DELETE "Use captured screenshots over CSS recreations." Replace with
"Compose the load-bearing visuals yourself. Build the kanban from cards. Draw the logo
with SVG paths. Paint the gradient with shader noise. Captured assets decorate composed
beats — they don't carry."
3. step-3 Asset Audit: reframe table from "assign assets to beats" to "audit which assets
decorate composed beats." Delete "Minimum utilization" bullets that forced asset usage.
Add "Composed bar" replacing them: "Every beat's primary visual comes from a composed
scene; accents are layered on top to brand-inflect."
4. step-3 beat template: rename ### Assets to ### Composition + Accents. Beat template
now structurally requires (a) composed scene cite + mode, (b) customization, and
(c) optional accent assets. Most beats have 0-1 accent.
5. step-1-design.md: COLLAPSED from 615 → ~140 lines. 8-section spec → 3 sections (Visual
Theme paragraph / Quick Reference / Iteration Guide). The Iteration Guide is the only
load-bearing section sub-agents actually consult. Drop: mood-board prose, exhaustive
component CSS tables, depth-elevation matrices, "what makes a great DESIGN.md" criteria.
6. step-3 Per-Beat Direction: add "Opener default: fast intro to stop the scrollers" at
the top. Even cinematic videos start with a punch inside the first 1.0-1.5 seconds.
7. step-2 Question 3: reframe options around compose-first beats. "Build the kanban from
divs in your brand palette, with the captured logo stamped top-left" instead of "the
dashboard screenshot would look stunning mapped onto a 3D MacBook." Captured assets
appear as accents in the options, not as the primary visual.
Net effect: agents now read "stop scrollers / alive every frame / physical world / go viral"
as the goal, "compose the load-bearing visual" as the strategy, and "assets decorate, they
don't carry" as the rule. The 81-scene library is the proof; the workflow text is now
pulling toward it, not against it.
Address Copilot round-3 review: the previous engine-mode timeline used
`tl.set(toId, opacity:1, T)` + `tl.set(fromId, opacity:0, T+dur)` for
every transition. That keeps BOTH scenes at opacity:1 throughout the
transition window. The Node-side layered compositor handles this fine —
it captures each scene separately, masks opacity per layer, and runs the
blend itself — but the page-side compositing path (one opaque RGB
screenshot per frame, opt-in via EngineConfig.enablePageSideCompositing)
relies on the page to produce a correct frame. With `shader === undefined`
the page-side compositor skips the entry, so the screenshot would show
both scenes stacked at 100% opacity (visible ghosting) instead of a blend.
Fix: schedule an actual opacity-crossfade tween in `initEngineMode`
when `t.shader === undefined`. Shader transitions keep the existing
opacity-flip pattern because the Node-side compositor needs both scenes
fully visible to capture them. The crossfade is harmless in the layered
Node path because `applyDomLayerMask` overrides per-scene opacity during
each capture anyway.
Also corrects docstrings in engineModePageComposite.ts and at the
installPageSideCompositor call site that previously claimed the GSAP
timeline "handles the blend" — it now actually does.
Co-authored-by: Cursor <cursoragent@cursor.com>
Three follow-up fixes from the Copilot review on commit 8cad2173:
1. Use strict `t.shader === undefined` instead of `!t.shader` (Copilot c4)
in both the WebGL program compile loop and the page-side compositor.
An empty-string `shader: ""` from a vanilla-JS caller (the IIFE bundle
is hand-loaded via <script> tags in user HTML) should reach the shader
registry and surface a loud "unknown shader" error, not silently
degrade to a crossfade.
2. Graceful degradation when shader compile fails (Copilot c5). The
previous `continue` dropped the transition from `cachedTransitions`,
which also dropped its scene-visibility timeline entries and broke
scene progression. Now: log a warning and downgrade to the CSS
crossfade fallback (prog=null, fallback=true) so the opacity timeline
still runs and the composition keeps playing.
3. Preserve index-to-scene-pair correlation when calling the page-side
compositor (Copilot c6). The earlier filter `transitions.filter(t =>
!!t.shader)` shifted indices, so a shader transition at original index
2 (sitting between CSS crossfades) would be paired with scenes[1] and
scenes[2] inside `installPageSideCompositor` instead of the correct
scenes[2] and scenes[3]. The compositor now accepts the full array,
makes `PageCompositeTransitionConfig.shader` optional, and skips
CSS-only entries internally while keeping `transitions[i]` aligned
with `scenes[i]`/`scenes[i+1]`.
Co-authored-by: Cursor <cursoragent@cursor.com>
- 04-18 Settings Panel: Render Preferences modal with 5 interactive controls in sequence —
toggle switch (Auto-render off→on with knob slide + blue bg), radio group (Render quality
Standard→High), dropdown (Output format cycles MP4·H.264 → MOV·ProRes → WebM·VP9 →
MP4·H.265), slider with synced counter (Frame rate 0→60 FPS), 5 color swatches (Accent
color blue→amber). Save button pulses + turns green with "✓ Saved" at the end. Reference
for product settings/configuration UIs.
- 09-06 Donut Chart Reveal: 4-segment SVG donut (Product launch 42% blue, Social ads 28%
green, Demo 18% amber, Brand reels 12% pink) drawn sequentially. Each segment fades in
via CSS opacity:0 → tl.to(opacity:1) then draws via stroke-dashoffset (fully seekable —
no init-state bug). Center percentage counter ticks 0→100%. Legend cards cascade in
synced with each segment's draw.
Both lint clean, both snapshot-verified (donut after init-state fix), both rendered +
uploaded. Grand Tour rebuilt with 81 scenes (9:22) at
https://www.heygenverse.com/s/23b285ce-a09a-487a-94d7-53f0c2827f2d/raw.
Section 04 jumps 17 → 18, section 09 jumps 5 → 6. Total 79 → 81.
Three follow-on fixes after the optional-shader change rebased onto current
main (PR #832 introduced page-side compositing and the producer's hf#732
layered pipeline since this PR was opened).
shader-transitions/hyper-shader.ts
- Treat `cache.prog === null` as the canonical immutable marker for
CSS-only transitions via a new `isCssOnlyTransition()` helper.
- `disposeCachedTransition()` now restores the always-ready CSS fallback
state for prog=null caches instead of zeroing `fallback`/`ready` — the
previous behaviour, combined with `markScenesDirty()` re-running the
prewarm/capture pipeline, could put a CSS-only cache through the WebGL
path and reach `renderShader(state.prog!)` with a null prog (Copilot
review on lines 1168 + 1319).
- `markScenesDirty()` skips CSS-only caches; they have no shader to
recompile and no texture pyramid to recapture.
- `ensureTransitionCachesReady()` filters CSS-only caches out of the
prewarm work list.
- `tickShader()` now routes on `cache.fallback || cache.prog === null`
and threads a narrowed non-null `prog` local into `renderShader()`,
removing the unsound `state.prog!` non-null assertion.
- `initEngineMode()` filters CSS-only transitions before passing them to
`installPageSideCompositor()`, which expects `shader: ShaderName`
(required). Page-side compositing is shader-only; CSS crossfades stay
on the GSAP opacity timeline.
producer/render/stages/captureHdrHybridLoop.ts
producer/render/stages/captureHdrSequentialLoop.ts
- Guard `activeTransition.shader` against undefined: when omitted, route
the Node-side blend through `crossfade` (the engine's canonical
opacity blend, equivalent to `applyFallbackTransition()` on the page).
- The hybrid path also bypasses the worker pool when `shaderName` is
absent and runs `crossfade` inline.
This addresses the Copilot review comments and unblocks the 5 failing CI
jobs (Build, Typecheck, CLI smoke, Windows tests, Windows render) which
all rooted in 4 TS errors at these exact sites.
Co-authored-by: Cursor <cursoragent@cursor.com>
Add mediabunny (MPL-2.0) to CREDITS.md third-party licenses section.
Add regression test for 4-5 clip compositions under the lowered lazy
threshold — verifies lazy mode activates and no spurious eviction churn
occurs when all clips fit within the promoted cap.
Two more product-UI patterns common in 2026 product videos that the library was missing:
- 04-16 Notification Stack: 4 shadcn-style toast notifications cascade in from the right
over a greyed-out mock app shell. Success ✓ green / Info ℹ blue / Warning ! amber /
Error × red. Each has icon + title + message + timestamp + close button + auto-dismiss
progress bar at bottom. After ~5s the first notification auto-dismisses (slides out
right) and the stack collapses up. Canonical toast UI pattern.
- 04-17 Loading States Showcase: 6 loading-state UI patterns side-by-side. 01 SKELETON
(gradient sweep), 02 SPINNER (rotating ring 5x), 03 PROGRESS BAR (0→78% with synced
counter), 04 DOTS (3-dot pulser with staggered scale yoyo, 5 cycles), 05 CIRCULAR
(SVG stroke-dashoffset 0→65%), 06 PULSE (opacity yoyo on dashed placeholder labeled
"Building…"). All 6 patterns seekable — no setTimeout, no requestAnimationFrame.
Both lint clean, both snapshot-verified, both rendered + uploaded.
Grand Tour rebuilt with 79 scenes (9:07) at
https://www.heygenverse.com/s/12548e7f-205c-4144-a2be-4423c2ccc16c/raw.
Section 04 jumps 15 → 17 (composed-UI). Total 77 → 79.
Restore rollback path: enqueueEdit now returns the queued promise so
Promise.resolve(handler(...)).catch(rollback) in useTimelineClipDrag
fires correctly on save failure. Handlers return the promise chain.
Fix lost-update race in probe enrichment: use zustand's functional
setState so concurrent probe completions each read the latest state
atomically instead of all reading the same stale snapshot.
Harden file-change suppression: pendingTimelineEditPathRef is now a
Set<string> with exact-match lookup instead of single-slot + endsWith.
Multiple concurrent edits on different files are all suppressed correctly.
Remove dead canOffsetTrimClipStart function and its tests — no longer
called after the capability gate simplification.
Document runtime sync mechanism: added comment explaining that the
runtime re-reads data attributes on each sync tick (init.ts:1324-1368).
Fix comment wording in patchIframeDomTiming catch block.
Extract resolveResizePlaybackStart, simplify patchIframeDomTiming to
accept attr tuples, inline findIframeElement. Reduces CRAP scores in
the resize handler lambda and DOM patching functions.
Three of the most common product-video patterns the library was still missing:
- 04-15 Testimonial Card: customer quote pattern. Fraunces italic quote with red accent on
key phrase ("forty minutes"), author row (MJ avatar + Maya Jensen / Head of Brand at
Northshore + composed Northshore logo card), 5-star rating cascade with back.out(2),
sub-caption "42 TESTIMONIALS · AVG TIME-TO-SHIP DOWN 89%". Quote types word-by-word.
- 10-05 CTA Hero: SaaS closer pattern. Massive headline "Ship your launch video today."
(gradient italic accent on "today"), sub-headline, primary CTA button with gradient +
glow halo + shimmer that sweeps twice during hold, secondary "Watch demo" link,
credibility row (No watermark / Cancel anytime / 847 teams / 4K export). Aurora bg with
multi-color radial bloom + 24 deterministic particles drifting.
- 12-07 Logo Cloud: customer/brand grid pattern. 4×3 grid of 12 fictional brands (Northshore,
Atlas Labs, Prism, Voltsy, Loomwave, Sable, Rivet, Helio, Foundry, Meridian, Kestrel,
Orbit) — each with a colored brand mark (different gradients/shapes per brand) + wordmark.
Cells reveal via stagger.from "center" with grid [3, 4] (center-out wave). Spotlight cycles
through 6 cells after grid completes. Bottom credibility row with number pulses.
All 3 lint clean, all 3 snapshot-verified, all 3 rendered + uploaded.
Grand Tour rebuilt with 77 scenes (8:52) at
https://www.heygenverse.com/s/417ac325-e606-48f1-b716-8f8747b44d87/raw.
Section 04 jumps 14 → 15, section 10 jumps 4 → 5, section 12 jumps 6 → 7. Total 74 → 77.
Three more pedagogically clean reference scenes:
- 03-03 Stagger Origin Showcase: 4 panels × 15 dots, each panel running same back.out(1.7)
stagger but with different from: origin — "start" (left→right) / "center" (middle→edges) /
"edges" (edges→middle) / "end" (right→left). Color-coded per panel. After initial wave,
yoyo wave runs again so the pattern is visible twice. Same elements + same easing +
same duration — only origin differs. The reference for "stagger origin changes the feel."
- 05-03 Glitch Shader Transition: SIGNAL (deep purple) → DECODED (vivid green). Canvas 2D
draws 12 horizontal slice bands with seeded "random" y-positions, heights, and
x-displacements; each slice painted in 3 RGB-offset channels for chromatic-split look.
Hero text jitters during glitch window. Section 05 now has 3 distinct shader-transition
aesthetics (ripple = concentric, chromatic-aberration = on-image RGB, glitch = sliced
bands) covering the most common shader transition styles.
- 09-05 Sparkline Draw: 4-card live-metrics dashboard. Active users (blue climb 142k),
Revenue $87K MRR (green smooth climb), API calls 2.4M (amber volatile peaks), Avg
latency 84ms (purple decline — down delta because lower is better). Each card has
filled-area path BELOW + stroked line on TOP, both via stroke-dashoffset (fully seekable).
End-of-line dots fade in + pulse. Value counters tick up via tl.set() in sync with
sparkline draws. Delta arrows fade in last.
All 3 lint clean (0 errors), all 3 snapshot-verified, all 3 rendered + uploaded.
Grand Tour rebuilt with 74 scenes (8:30) at
https://www.heygenverse.com/s/aefd8761-7ae5-4399-bed4-3c33ea7dc3bf/raw.
Section 03 jumps 2 → 3, section 05 jumps 2 → 3, section 09 jumps 4 → 5. Total 71 → 74.