feat(shader-transitions): optional shader field — CSS crossfade mixing in HyperShader

[ukimsanov]

What

Makes the shader field in TransitionConfig optional. When omitted, HyperShader performs a smooth CSS opacity crossfade instead of a WebGL effect — using the existing applyFallbackTransition() path that was already there for texture-load failures.

Why

Previously, using HyperShader.init() locked the entire composition into WebGL-only transitions. Any transition that didn't need a shader effect (smooth cuts, crossfades between related beats) still required picking the least-intrusive shader (flash-through-white at 0.01s). This was an all-or-nothing constraint that produced unwanted white flashes in practice.

Now shader and CSS crossfade transitions can be mixed freely in the same composition:

var tl = HyperShader.init({
  bgColor: "#000",
  scenes: ["beat-1", "beat-2", "beat-3", "beat-4"],
  transitions: [
    { time: 4.0, shader: "sdf-iris", duration: 0.7 },   // WebGL shader
    { time: 8.5, duration: 0.8 },                         // no shader → CSS crossfade
    { time: 13.0, shader: "domain-warp", duration: 0.6 }, // WebGL shader
  ],
});

How

• TransitionConfig.shader changed from ShaderName (required) to ShaderName | undefined (optional)
• In the program compilation loop: skip transitions with no shader
• In the transition setup loop: isCssFallback = !t.shader — fallback transitions get prog: null, ready: true, fallback: true, dirty: false — no prewarming needed
• renderShader call uses non-null assertion (state.prog!) — safe because the fallback path returns before this point
• HfTransitionMeta.shader in both the local interface and engine/src/types.ts made optional to match
• CachedTransition.prog type widened to WebGLProgram | null

Test plan

• Built packages/shader-transitions — clean TypeScript, no errors
• Tested with a 3-scene composition: sdf-iris shader + CSS crossfade + domain-warp shader
• Rendered to MP4 — both transition types composite correctly
• Verified CSS crossfade fallback uses applyFallbackTransition() smooth opacity interpolation
• Player scrubber works correctly (using HyperShader.init() without timeline: option)

[miguel-heygen]

fix the failed ci checks btw

[Copilot]

Pull request overview

This PR updates @hyperframes/shader-transitions and the engine protocol types to allow transitions that omit a shader and instead use the existing DOM/CSS opacity crossfade fallback path. This enables mixing WebGL shader transitions and CSS crossfades within the same composition, without forcing a “minimal” shader everywhere.

Changes:

• Make TransitionConfig.shader optional and skip WebGL program compilation when shader is omitted.
• Represent CSS-only transitions as cached transitions with prog: null and mark them as immediately ready/fallback.
• Update HfTransitionMeta.shader to be optional (engine protocol + local bundle copy) to reflect CSS crossfade transitions.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
packages/shader-transitions/src/hyper-shader.ts	Makes shader optional, skips program compilation for CSS-only transitions, and sets up cached transitions to use the CSS fallback path with prog: null.
packages/engine/src/types.ts	Updates the protocol type to make HfTransitionMeta.shader optional for CSS crossfade transitions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

packages/shader-transitions/src/hyper-shader.ts:2301

• In engine render mode with page-side compositing enabled, transitions with shader === undefined are skipped by the compositor, but the engine-mode GSAP timeline only performs opacity flips (both scenes stay opacity=1 for the full transition window, then the from-scene drops to 0 at the end). That means CSS-crossfade transitions will render as two fully-visible scenes overlaid (ghosting) when the producer chooses the page-side compositing + single-frame capture path. Consider either (a) scheduling an actual opacity crossfade tween for shader === undefined transitions when pageCompositingFlag is true, or (b) having the page-side compositor handle undefined-shader entries (e.g. treat them as a simple mix) so the captured frame matches the intended crossfade.

    // Pass the full transitions array so transition[i] still pairs with
    // scenes[i]/scenes[i+1]. The compositor itself skips entries with
    // `shader === undefined` while preserving the index↔scene mapping.
    // (CSS crossfades remain driven by the GSAP opacity timeline.)
    installPageSideCompositor({
      scenes,
      transitions,
      bgColor,
      accentColors,
      width: compWidth,
      height: compHeight,
      defaultDuration: DEFAULT_DURATION,
    });

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

packages/shader-transitions/src/hyper-shader.ts:2314

• installPageSideCompositor() returns a boolean but the result is ignored. If page-side compositing is enabled by the producer and the compositor fails to install (unsupported drawElementImage/WebGL, or shader program compile failures), engine-mode shader transitions will remain in the opacity-flip state (both scenes visible) with no Node-side blend, producing incorrect frames. Consider checking the return value and falling back deterministically (e.g., re-schedule those transitions as CSS crossfades, or otherwise disable page-side compositing in a way the producer can react to).

    installPageSideCompositor({
      scenes,
      transitions,
      bgColor,
      accentColors,

[miguel-heygen]

Clean work. The CSS crossfade mixing path is well-guarded:

Verified:

• renderShader requires non-null prog — both call sites (page composite via programs.get() + !prog continue, browser path via the cache.fallback || cache.prog === null early return) narrow correctly before reaching it
• CSS opacity tweens in initEngineMode are harmless in the Node-side layered path — captureTransitionFrameOnWorker captures scenes independently by ID, not affected by CSS opacity
• installPageSideCompositor skips CSS entries safely — resolved[] is time-indexed, not position-indexed, so skipping doesn't misalign scene pairs
• isCssOnlyTransition helper correctly guards disposeCachedTransition and markScenesDirty from routing CSS transitions through the WebGL prewarm path
• Strict undefined check on t.shader — empty string from vanilla JS callers still fails loudly through createProgram, good defensive choice
• Compilation failure degradation (shader specified but programs.get() returns null) falls through to CSS crossfade with a warning — correct

One note: The transition cache state machine (dirty/ready/fallback/persisted) has no test coverage. The initial values for CSS transitions (dirty: false, ready: true, fallback: true, persisted: true) and the early-return in disposeCachedTransition are correct but would benefit from a unit test. Not a blocker.