Files
Miguel Ángel f888db950e fix(core): paint no timed clip until the runtime decides its visibility (#4460)
* fix(core): paint no timed clip until the runtime decides its visibility

Until its first visibility pass, a paused page showed every timed clip at once: an embed without
a loader flashed a later scene before the first, and a player's hidden iframe still decoded every
scene's images. The runtime now hides timed non-media clips from the moment its script runs,
and the first pass that decides them removes that rule, so each clip is shown only by the pass.

* refactor(core): name media with the realm-safe helper in the first-pass check

* fix(core): share the first-pass hide across runtime copies and shader captures

A second evaluation of the runtime (a sub-composition carrying its own runtime tag, or a page that
includes it twice) added a hide rule nothing removed, so the film stayed invisible. The rule and its
flag now live on the page: a copy that finds either, or finds the runtime already initialised, adds
none, and the first pass removes every copy. HyperShader's capture clone forces its scene visible
with !important, so a transition captured before the first pass still shows the scene's clips.
The runtime test now also pins evaluation-time hiding, inline visibility, media, and two copies.

* fix(core): grade media inside a clip once the first pass shows it

Color grading registers only media it can see. Media with no timing of its own inside a timed clip
inherited the first-pass hide, so grading skipped it, and lifting the rule is not a body mutation,
so nothing registered it again: the image or video stayed ungraded. The pass now refreshes grading
when it lifts the rule. The second-copy test now asserts on a paused page, before any seek.

* chore(core): keep the comment share of the first-pass hide files at or under their base

The comment ratchet counts one added comment line each in entry.ts, init.ts and capture.ts, and a
new file above its package's share. The three lines are gone, and the one note that has to stay
(why the hide runs at script evaluation) now lives in the new module's shorter header.
2026-09-24 23:04:23 -04:00
..
2026-09-24 21:51:48 -04:00

@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.

License

MIT