@hyperframes/shader-transitions

WebGL shader transitions for HyperFrames compositions. Renders GPU-accelerated scene-to-scene transitions using fragment shaders, driven by GSAP timelines.

Install

npm install @hyperframes/shader-transitions

Or load directly via CDN:

<script src="https://cdn.jsdelivr.net/npm/@hyperframes/shader-transitions/dist/index.global.js"></script>

Usage

import { init } from "@hyperframes/shader-transitions";

const tl = init({
  bgColor: "#0a0a0a",
  accentColor: "#ff6b2b",
  scenes: ["scene-1", "scene-2", "scene-3"],
  transitions: [
    { time: 3, shader: "domain-warp", duration: 0.8 },
    { time: 8, shader: "light-leak", duration: 0.7 },
  ],
});

The init() function pre-captures animated scene samples for every transition, composites cached samples with the selected shader during playback, and returns a GSAP timeline. Scene animations keep advancing through shader transitions without running DOM captures in the playback loop. If WebGL is unavailable, it falls back to normal timeline playback without shader compositing.

When the browser exposes Chrome's experimental CanvasDrawElement API, scene capture uses native HTML-in-canvas via drawElementImage(). Other browsers keep using the existing html2canvas fallback. You can feature-detect the native path with isHtmlInCanvasCaptureSupported().

With an existing timeline

Pass your own GSAP timeline to layer transitions onto it:

const tl = gsap.timeline({ paused: true });
// ... add your scene animations ...

init({
  bgColor: "#000",
  scenes: ["intro", "demo", "outro"],
  transitions: [
    { time: 5, shader: "cinematic-zoom" },
    { time: 12, shader: "glitch", duration: 0.5 },
  ],
  timeline: tl,
});

Available shaders

| Shader | Description | | --------------------- | ---------------------------------------------------- | | domain-warp | Organic noise-based warp with glowing edge | | ridged-burn | Ridged noise burn with sparks and heat glow | | whip-pan | Horizontal motion blur simulating a fast camera pan | | sdf-iris | Circular iris wipe with glowing ring edge | | ripple-waves | Concentric ripple distortion radiating from center | | gravitational-lens | Warping gravity well with chromatic aberration | | cinematic-zoom | Radial zoom blur with chromatic fringing | | chromatic-split | RGB channel separation expanding from center | | glitch | Digital glitch with block displacement and scanlines | | swirl-vortex | Spiral rotation with noise-based warping | | thermal-distortion | Heat shimmer rising from the bottom | | flash-through-white | Flash to white then reveal the next scene | | cross-warp-morph | Noise-driven morph blending both scenes | | light-leak | Warm cinematic light leak with lens flare |

API

init(config): GsapTimeline

| Option | Type | Required | Description | | ------------------- | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | bgColor | string | yes | Fallback background color (hex) for scene capture. Use the composition's body/canvas background — individual scenes set their own background-color via CSS. | | accentColor | string | no | Accent color (hex) for shader glow effects | | scenes | string[] | yes | Element IDs of each scene, in order | | transitions | TransitionConfig[] | yes | Transition definitions (see below) | | timeline | GsapTimeline | no | Existing timeline to attach transitions to | | compositionId | string | no | Override the data-composition-id for timeline registration | | previewCaptureFps | number | no | Browser preview pre-capture samples per transition second. Defaults to 30; rendering uses deterministic per-frame compositing instead. |

Browser preview capture scale and transition-prep loading UI ownership are controlled by <hyperframes-player> (shader-capture-scale, shader-loading) instead of composition code. Direct non-player previews keep the built-in full-fidelity loading fallback.

Browser previews store captured transition snapshots in IndexedDB using a key derived from composition ID, scene DOM/style signatures, transition timing, capture FPS, scale, and dimensions. On refresh, matching snapshots are reloaded into WebGL textures instead of being captured again. Runtime scene or stylesheet edits mark only adjacent transition caches dirty; recapture is deferred until playback so editing stays responsive.

TransitionConfig

| Option | Type | Default | Description | | ---------- | ------------ | ---------------- | -------------------------------- | | time | number | — | Start time in seconds | | shader | ShaderName | — | Shader name from the table above | | duration | number | 0.7 | Transition duration in seconds | | ease | string | "power2.inOut" | GSAP easing function |

SHADER_NAMES

Array of all available shader name strings, useful for validation or building UIs.

import { SHADER_NAMES } from "@hyperframes/shader-transitions";
// ["domain-warp", "ridged-burn", "whip-pan", ...]

Distribution

| Format | File | Use case | | ------ | ---------------------- | ------------------------------------------- | | ESM | dist/index.js | Bundlers (Vite, webpack, etc.) | | CJS | dist/index.cjs | Node.js / require() | | IIFE | dist/index.global.js | <script> tag, CDN (global: HyperShader) |

All formats include source maps. TypeScript definitions included.

Related packages

• @hyperframes/core -- types, parsers, runtime
• @hyperframes/engine -- rendering engine
• hyperframes -- CLI

License

MIT