ext/hyperframes
2
0
Fork 0
mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-07 10:06:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: add @hyperframes/shader-transitions package (#251)

Browse Source 
## Summary

New `@hyperframes/shader-transitions` package that encapsulates WebGL shader transitions into a single `HyperShader.init()` call. Replaces ~200 lines of per-composition boilerplate that LLMs failed to wire correctly 60% of the time.

### API

```js
var tl = HyperShader.init({
  bgColor: "#0a0a1a",
  accentColor: "#6366f1",
  scenes: ["scene1", "scene2", "scene3", "scene4", "scene5"],
  transitions: [
    { time: 7.2, shader: "cross-warp-morph", duration: 0.7 },
    { time: 15.2, shader: "domain-warp", duration: 0.7 },
  ]
});
tl.from("#s1-title", { y: 50, opacity: 0, duration: 0.7 }, 0.3);
```

### What the library handles

- **13 shader programs**: domain-warp, ridged-burn, whip-pan, sdf-iris, ripple-waves, gravitational-lens, cinematic-zoom, chromatic-split, glitch, swirl-vortex, thermal-distortion, cross-warp-morph, light-leak
- **html2canvas** bundled as dependency (not CDN) — single script tag for CLI users
- **DOM-during-holds**: canvas hidden between transitions, GSAP animations play on live DOM
- **Async capture with pause/resume**: timeline pauses during capture, resumes after textures uploaded — prevents progress tween from running ahead
- **Accent color theming**: `accentColor` derives dark/mid/bright uniforms. Burns, glows, leaks match the composition palette
- **Graceful degradation**: falls back silently when WebGL unavailable

### Code quality (from 3 review agents)

- No `!` non-null assertions — all WebGL creation calls throw on failure
- Vertex shader compiled once, cached across all programs
- Uniform/attribute locations cached per program via WeakMap (not looked up every frame)
- Captured canvases freed after texture upload (8MB each)
- Single timeline creation (was creating two, discarding one)
- Shared `tickShader()` render callback (was copy-pasted)
- `.finally()` for DOM restore in capture (was duplicated in `.then`/`.catch`)
- `parseHex` validates input (was silently producing NaN on invalid hex)
- Dead `ND`/`CP` shader library exports removed

### Shader-compatible CSS rules (transitions.md)

6 rules for compositions using shader transitions:
1. No `transparent` in gradients (canvas interpolates through black)
2. No gradient backgrounds on elements < 4px
3. No CSS variables on captured elements
4. `data-no-capture` for uncapturable decoratives
5. No gradient opacity < 0.15
6. Every `.scene` must have explicit `background-color` matching `bgColor`

### Build output

- IIFE (~214KB with html2canvas bundled, ~65KB gzipped) — `window.HyperShader`
- ESM + CJS + TypeScript declarations
- tsup build following `@hyperframes/player` conventions

## Test plan
- [ ] `bun run build` succeeds (includes shader-transitions)
- [ ] `bunx oxlint packages/shader-transitions/src/` — 0 errors
- [ ] Create a composition using `HyperShader.init()` — verify transitions fire, DOM animations play, accent colors match
- [ ] Test graceful degradation: composition works without WebGL (no transitions, no crash)
- [ ] Verify pause/resume: scrub to transition boundary — no jump in progress

🤖 Generated with [Claude Code](https://claude.com/claude-code)
This commit is contained in:
Vance Ingalls
2026-04-13 18:44:00 -07:00
committed by GitHub
parent 5de2af5bde
commit cb3d94c2a5
13 changed files with 1037 additions and 366 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/hyperframes/references/transitions.md
+53 -37
View File
@@ -1,14 +1,23 @@
# Scene Transitions
A transition tells the viewer how two scenes relate. A crossfade says "this continues." A push slide says "next point." A flash cut says "wake up." A blur crossfade says "drift with me." Choose transitions that match what the content is doing emotionally, not just technically.
A transition tells the viewer how two scenes relate. A crossfade says "this continues." A push slide says "next point." A blur crossfade says "drift with me." Choose transitions that match what the content is doing emotionally, not just technically.
## Animation Rules for Multi-Scene Compositions
These are non-negotiable for every multi-scene composition:
1. **Every composition uses transitions.** No exceptions. Scenes without transitions feel like jump cuts.
2. **Every scene uses entrance animations.** Elements animate IN via `gsap.from()` — opacity, position, scale, etc. No scene should pop fully-formed onto screen.
3. **Exit animations are BANNED** except on the final scene. Do NOT use `gsap.to()` to animate elements out before a transition fires. The transition IS the exit. Outgoing scene content must be fully visible when the transition starts — the transition handles the visual handoff.
4. **Final scene exception:** The last scene MAY fade elements out (e.g., fade to black at the end of the composition). This is the only scene where exit animations are allowed.
## Energy → Primary Transition
| Energy | Primary | Accent for key moments | Duration | Easing |
| ---------------------------------------- | ---------------------------- | ------------------------------ | --------- | ---------------------- |
| **Calm** (wellness, brand story, luxury) | Blur crossfade, focus pull | Light leak, circle iris | 0.5-0.8s | `sine.inOut`, `power1` |
| **Medium** (corporate, SaaS, explainer) | Push slide, staggered blocks | Squeeze, vertical push | 0.3-0.5s | `power2`, `power3` |
| **High** (promos, sports, music, launch) | Flash cut, zoom through | Staggered blocks, gravity drop | 0.15-0.3s | `power4`, `expo` |
| Energy | CSS Primary | Shader Primary | Accent | Duration | Easing |
| ---------------------------------------- | ---------------------------- | ------------------------------------ | ------------------------------ | --------- | ---------------------- |
| **Calm** (wellness, brand story, luxury) | Blur crossfade, focus pull | Cross-warp morph, thermal distortion | Light leak, circle iris | 0.5-0.8s | `sine.inOut`, `power1` |
| **Medium** (corporate, SaaS, explainer) | Push slide, staggered blocks | Whip pan, cinematic zoom | Squeeze, vertical push | 0.3-0.5s | `power2`, `power3` |
| **High** (promos, sports, music, launch) | Zoom through, overexposure | Ridged burn, glitch, chromatic split | Staggered blocks, gravity drop | 0.15-0.3s | `power4`, `expo` |
Pick ONE primary (60-70% of scene changes) + 1-2 accents. Never use a different transition for every scene.
@@ -16,17 +25,17 @@ Pick ONE primary (60-70% of scene changes) + 1-2 accents. Never use a different
Think about what the transition _communicates_, not just what it looks like.
| Mood | Transitions | Why it works |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Warm / inviting** | Light leak, blur crossfade, focus pull, film burn, light leak (shader), thermal distortion | Soft edges, warm color washes. Nothing sharp or mechanical. The transition feels like sunlight. |
| **Cold / clinical** | Squeeze, zoom out, blinds, shutter, grid dissolve, gravitational lens | Content transforms mechanically — compressed, shrunk, sliced, gridded. Zoom out creates clinical distance. No softness. |
| **Editorial / magazine** | Push slide, vertical push, diagonal split, shutter, whip pan | Like turning a page or slicing a layout. Clean directional movement. Whip pan is a fast editorial camera move. |
| **Tech / futuristic** | Grid dissolve, staggered blocks, blinds, chromatic aberration, glitch (shader), chromatic split (shader) | Grid dissolve is the core "data" transition. Shader glitch adds posterization + scan lines. |
| **Tense / edgy** | Glitch, VHS, chromatic aberration, flash cut, ripple, ridged burn, glitch (shader) | Instability, distortion, digital breakdown. Ridged burn adds sharp lightning-crack edges. |
| **Playful / fun** | Elastic push, 3D flip, circle iris, morph circle, clock wipe, ripple waves, swirl vortex | Overshoot, bounce, rotation, expansion. Swirl vortex adds organic spiral distortion. |
| **Dramatic / cinematic** | Zoom through, zoom out, gravity drop, overexposure, diagonal split, color dip to black, cinematic zoom (shader), gravitational lens, domain warp, flash through white | Scale, weight, light extremes. Shader transitions add per-pixel depth. |
| **Premium / luxury** | Focus pull, blur crossfade, color dip to black, slow crossfade, cross-warp morph, thermal distortion | Restraint. Cross-warp morph flows both scenes into each other organically. |
| **Retro / analog** | Film burn, light leak, VHS, clock wipe | Organic imperfection. Warm color bleeds, scan line displacement. Clock wipe evokes broadcast TV. |
| Mood | Transitions | Why it works |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| **Warm / inviting** | Light leak, blur crossfade, focus pull, film burn · **Shader:** thermal distortion, light leak, cross-warp morph | Soft edges, warm color washes. Nothing sharp or mechanical. |
| **Cold / clinical** | Squeeze, zoom out, blinds, shutter, grid dissolve · **Shader:** gravitational lens | Content transforms mechanically — compressed, shrunk, sliced, gridded. |
| **Editorial / magazine** | Push slide, vertical push, diagonal split, shutter · **Shader:** whip pan | Like turning a page or slicing a layout. Clean directional movement. |
| **Tech / futuristic** | Grid dissolve, staggered blocks, blinds, chromatic aberration · **Shader:** glitch, chromatic split | Grid dissolve is the core "data" transition. Shader glitch adds posterization + scan lines. |
| **Tense / edgy** | Glitch, VHS, chromatic aberration, ripple · **Shader:** ridged burn, glitch, domain warp | Instability, distortion, digital breakdown. Ridged burn adds sharp lightning-crack edges. |
| **Playful / fun** | Elastic push, 3D flip, circle iris, morph circle, clock wipe · **Shader:** ripple waves, swirl vortex | Overshoot, bounce, rotation, expansion. Swirl vortex adds organic spiral distortion. |
| **Dramatic / cinematic** | Zoom through, zoom out, gravity drop, overexposure, color dip to black · **Shader:** cinematic zoom, gravitational lens, domain warp | Scale, weight, light extremes. Shader transitions add per-pixel depth. |
| **Premium / luxury** | Focus pull, blur crossfade, color dip to black · **Shader:** cross-warp morph, thermal distortion | Restraint. Cross-warp morph flows both scenes into each other organically. |
| **Retro / analog** | Film burn, light leak, VHS, clock wipe · **Shader:** light leak | Organic imperfection. Warm color bleeds, scan line displacement. |
## Narrative Position
@@ -62,34 +71,41 @@ Think about what the transition _communicates_, not just what it looks like.
Read [transitions/catalog.md](transitions/catalog.md) for GSAP code and hard rules for every transition type.
| Category | Transitions |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-transforming | Push slide, vertical push, elastic push, squeeze, zoom through, zoom out, gravity drop, 3D flip |
| Reveal/mask | Circle iris, diamond iris, diagonal split, clock wipe, shutter |
| Dissolve | Crossfade, blur crossfade, focus pull, color dip |
| Cover | Staggered blocks, horizontal blinds, vertical blinds |
| Light | Light leak, overexposure burn, film burn |
| Distortion | Glitch, chromatic aberration, ripple, VHS tape |
| Pattern | Grid dissolve |
| Instant | Flash cut, morph circle |
| Shader (WebGL) | Domain warp, ridged burn, whip pan, SDF iris, ripple waves, gravitational lens, cinematic zoom, chromatic split, glitch, swirl vortex, thermal distortion, flash through white, cross-warp morph, light leak (shader) |
| Category | CSS | Shader (WebGL) |
| ----------- | -------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Push/slide | Push slide, vertical push, elastic push, squeeze | Whip pan |
| Scale/zoom | Zoom through, zoom out, gravity drop, 3D flip | Cinematic zoom, gravitational lens |
| Reveal/mask | Circle iris, diamond iris, diagonal split, clock wipe, shutter | SDF iris |
| Dissolve | Crossfade, blur crossfade, focus pull, color dip | Cross-warp morph, domain warp |
| Cover | Staggered blocks, horizontal blinds, vertical blinds | — |
| Light | Light leak, overexposure burn, film burn | Light leak (shader), thermal distortion |
| Distortion | Glitch, chromatic aberration, ripple, VHS tape | Glitch (shader), chromatic split, ridged burn, ripple waves, swirl vortex |
| Pattern | Grid dissolve, morph circle | — |
## Transitions That Don't Work in CSS
Avoid: star iris, tilt-shift, lens flare, hinge/door. See catalog.md for why.
## CSS vs Shader: When to Use Which
## CSS vs Shader
Most compositions should use **CSS/GSAP transitions** (the other categories above). They're simpler, lighter, and handle most needs. Use **shader transitions** only when you need an effect that CSS can't achieve:
CSS transitions animate scene containers with opacity, transforms, clip-path, and filters. Shader transitions composite both scene textures per-pixel on a WebGL canvas — they can warp, dissolve, and morph in ways CSS cannot.
| Use CSS/GSAP when | Use Shader when |
| ---------------------------------------------- | ----------------------------------------------- |
| Opacity, transform, clip-path, filter effects | Per-pixel noise dissolves, domain warping |
| Simple crossfades, wipes, slides | Both scenes actively morph into each other |
| No images/video in scenes (text + shapes only) | Live video needs to play through the transition |
| Quick to set up, no boilerplate | Willing to add WebGL setup layer (~200 lines) |
**Both are first-class options.** Shaders require setup boilerplate (~200 lines, copied from [transitions/shader-setup.md](transitions/shader-setup.md)) but produce richer, more cinematic effects. CSS transitions are simpler to set up. Choose based on the effect you want, not based on which is easier.
Shader transitions require setup boilerplate (canvas, scene capture, WebGL init). Read [transitions/shader-setup.md](transitions/shader-setup.md) for the complete code. The fragment shaders themselves are in the Shader section of [transitions/catalog.md](transitions/catalog.md).
When a composition uses shader transitions, ALL transitions in that composition should be shader-based (the WebGL canvas replaces DOM-based scene switching). Don't mix CSS and shader transitions in the same composition.
## Shader-Compatible CSS Rules
Shader transitions capture DOM scenes to WebGL textures via html2canvas. The canvas 2D rendering pipeline doesn't match CSS exactly. Follow these rules to avoid visible artifacts at transition boundaries:
1. **No `transparent` keyword in gradients.** Canvas interpolates `transparent` as `rgba(0,0,0,0)` (black at zero alpha), creating dark fringes. Always use the target color at zero alpha: `rgba(200,117,51,0)` not `transparent`.
2. **No gradient backgrounds on elements thinner than 4px.** Canvas can't match CSS gradient rendering on 1-2px elements. Use solid `background-color` on thin accent lines.
3. **No CSS variables (`var()`) on elements visible during capture.** html2canvas doesn't reliably resolve custom properties. Use literal color values in inline styles.
4. **Mark uncapturable decorative elements with `data-no-capture`.** The capture function skips these. They're present on the live DOM but absent from the shader texture. Use for elements that can't follow the rules above.
5. **No gradient opacity below 0.15.** Gradient elements below 10% opacity render differently in canvas vs CSS. Increase to 0.15+ or use a solid color at equivalent brightness.
6. **Every `.scene` div must have explicit `background-color`, AND set `BG_COLOR` in the shader setup to the same value.** html2canvas captures the scene element, not the body. Both the CSS `background-color` on `.scene` and the `backgroundColor` option in `html2canvas()` must be set to the composition's background color. Without either, the texture renders as black.
These rules only apply to shader transition compositions. CSS-only compositions have no restrictions.
## Visual Pattern Warning
skills/hyperframes/references/transitions/catalog.md
+6 -6
View File
@@ -34,7 +34,7 @@ Read [shader-setup.md](./shader-setup.md) for the full setup code these rules ap
**WebGL setup:** `gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false)` — NOT true. Vertex shader flips Y: `v_uv.y = 1.0 - v_uv.y`. `preserveDrawingBuffer: true` required for HyperFrames capture. No `fwidth()` without extension — use constant `0.003`.
**Rendering model:** GL canvas stays visible entire composition — DOM scenes remain `opacity: 0`. Passthrough shader for holds. Scene capture = static snapshots at load; animated GSAP tweens on elements won't appear.
**Rendering model:** DOM scenes play normally with GSAP animations during holds — canvas is hidden (`display:none`). When a transition starts: capture outgoing scene with full content, capture incoming scene with `.scene-content` hidden (background + decoratives only), show canvas, run shader. When transition ends: hide canvas, show next DOM scene. GSAP entrance animations play on the live DOM. The incoming scene's content is never visible in the shader — it only shows the background layer, preventing un-animated elements from flashing.
**Scene capture:** Canvas `fillText` doesn't match CSS fonts exactly (known, not a bug). No CSS gradients or SVGs. Images and videos ARE supported via `ctx.drawImage()`. Video scenes re-capture every frame during transitions via `recaptureVideoScene()`.
@@ -118,7 +118,7 @@ All code examples use `old` for the outgoing scene-inner selector and `new` for
| Distortion | Glitch, chromatic aberration, ripple, VHS tape | [css-distortion.md](./css-distortion.md) |
| Mechanical | Shutter, clock wipe | [css-mechanical.md](./css-mechanical.md) |
| Grid | Grid dissolve | [css-grid.md](./css-grid.md) |
| Other | Flash cut, gravity drop, morph circle | [css-other.md](./css-other.md) |
| Other | Gravity drop, morph circle | [css-other.md](./css-other.md) |
| Blur | Blur through, directional blur | [css-blur.md](./css-blur.md) |
| Destruction | Page burn | [css-destruction.md](./css-destruction.md) |
@@ -126,7 +126,7 @@ All code examples use `old` for the outgoing scene-inner selector and `new` for
WebGL fragment shaders that composite between scene textures per-pixel. Require setup boilerplate.
| What | Reference |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| Setup (canvas, capture, WebGL init, render loop, GSAP integration) | [shader-setup.md](./shader-setup.md) |
| Fragment shaders (14 transitions: domain warp, ridged burn, whip pan, SDF iris, ripple waves, gravitational lens, cinematic zoom, chromatic split, glitch, swirl vortex, thermal distortion, flash through white, cross-warp morph, light leak) | [shader-transitions.md](./shader-transitions.md) |
| What | Reference |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| Setup (canvas, capture, WebGL init, render loop, GSAP integration) | [shader-setup.md](./shader-setup.md) |
| Fragment shaders (13 transitions: domain warp, ridged burn, whip pan, SDF iris, ripple waves, gravitational lens, cinematic zoom, chromatic split, glitch, swirl vortex, thermal distortion, cross-warp morph, light leak) | [shader-transitions.md](./shader-transitions.md) |
skills/hyperframes/references/transitions/shader-setup.md
+141 -322
View File
@@ -1,6 +1,10 @@
# Shader Transition Setup
Complete boilerplate for WebGL shader transitions in HyperFrames. Read this when implementing a shader transition — copy the setup code, then plug in the fragment shader from the catalog.
Complete boilerplate for WebGL shader transitions in HyperFrames. Copy the setup code, then plug in the fragment shader from the catalog.
**Rendering model:** DOM scenes play normally with GSAP animations. The WebGL canvas is hidden (`display:none`) between transitions. When a transition starts, `beginTrans` uses html2canvas to capture the outgoing scene with full content, and the incoming scene with `.scene-content` hidden (background + decorative elements only). This prevents un-animated content from flashing during the transition. When the transition ends, `endTrans` hides the canvas and reveals the incoming DOM scene — GSAP entrance animations then play on live elements.
**Shader-compatible CSS:** Compositions using shader transitions must follow the rules in transitions.md § "Shader-Compatible CSS Rules" — no `transparent` in gradients, no gradient backgrounds on sub-4px elements, no `var()` on captured elements, `data-no-capture` on uncapturable decoratives.
## HTML
@@ -14,270 +18,14 @@ Complete boilerplate for WebGL shader transitions in HyperFrames. Read this when
</canvas>
```
## WebGL Init + Scene Capture
Handles images, video, shapes, and text. Supports `object-fit: cover` on images and live video re-upload during transitions.
## WebGL Init
```js
var sceneTextures = {};
var sceneHasVideo = {}; // tracks which scenes have live video
var glCanvas = document.getElementById("gl-canvas");
var gl = glCanvas.getContext("webgl", { preserveDrawingBuffer: true });
gl.viewport(0, 0, 1920, 1080);
gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
// Wait for all media to load before capturing
function waitForMedia() {
return new Promise(function (resolve) {
var promises = [];
document.querySelectorAll("img").forEach(function (img) {
if (!img.complete)
promises.push(
new Promise(function (r) {
img.onload = r;
img.onerror = r;
}),
);
});
document.querySelectorAll("video").forEach(function (vid) {
if (vid.readyState < 2)
promises.push(
new Promise(function (r) {
vid.addEventListener("loadeddata", r, { once: true });
}),
);
});
Promise.all(promises).then(resolve);
});
}
function captureScene(sceneId) {
return new Promise(function (resolve) {
var scene = document.getElementById(sceneId);
var origOpacity = scene.style.opacity;
var origZ = scene.style.zIndex;
scene.style.opacity = "1";
scene.style.zIndex = "999";
if (scene.querySelector("video")) sceneHasVideo[sceneId] = scene.querySelector("video");
requestAnimationFrame(function () {
requestAnimationFrame(function () {
var c = document.createElement("canvas");
c.width = 1920;
c.height = 1080;
var ctx = c.getContext("2d");
ctx.fillStyle = window.getComputedStyle(scene).backgroundColor;
ctx.fillRect(0, 0, 1920, 1080);
var sr = scene.getBoundingClientRect();
var els = scene.querySelectorAll("*");
for (var i = 0; i < els.length; i++) {
var el = els[i];
var cs = window.getComputedStyle(el);
if (cs.display === "none" || cs.visibility === "hidden") continue;
var r = el.getBoundingClientRect();
if (r.width < 1 || r.height < 1) continue;
var x = r.left - sr.left,
y = r.top - sr.top,
w = r.width,
h = r.height;
ctx.save();
ctx.globalAlpha = parseFloat(cs.opacity) || 1;
// <img> elements (with object-fit: cover support)
if (el.tagName === "IMG" && el.complete && el.naturalWidth > 0) {
try {
if (cs.objectFit === "cover") {
var iR = el.naturalWidth / el.naturalHeight,
bR = w / h;
var sx = 0,
sy = 0,
sw = el.naturalWidth,
sh = el.naturalHeight;
if (iR > bR) {
sw = sh * bR;
sx = (el.naturalWidth - sw) / 2;
} else {
sh = sw / bR;
sy = (el.naturalHeight - sh) / 2;
}
ctx.drawImage(el, sx, sy, sw, sh, x, y, w, h);
} else {
ctx.drawImage(el, x, y, w, h);
}
} catch (e) {}
ctx.restore();
continue;
}
// <video> elements (grabs current frame)
if (el.tagName === "VIDEO" && el.readyState >= 2) {
try {
var vR = el.videoWidth / el.videoHeight,
bR2 = w / h;
var vx = 0,
vy = 0,
vw = el.videoWidth,
vh = el.videoHeight;
if (vR > bR2) {
vw = vh * bR2;
vx = (el.videoWidth - vw) / 2;
} else {
vh = vw / bR2;
vy = (el.videoHeight - vh) / 2;
}
ctx.drawImage(el, vx, vy, vw, vh, x, y, w, h);
} catch (e) {}
ctx.restore();
continue;
}
// Background color
var bg = cs.backgroundColor;
if (bg && bg !== "rgba(0, 0, 0, 0)" && bg !== "transparent") {
ctx.fillStyle = bg;
var br = parseInt(cs.borderRadius) || 0;
if (br >= Math.min(w, h) / 2 - 1 && Math.abs(w - h) < 4) {
ctx.beginPath();
ctx.arc(x + w / 2, y + h / 2, Math.min(w, h) / 2, 0, Math.PI * 2);
ctx.fill();
} else if (br > 0) {
ctx.beginPath();
ctx.moveTo(x + br, y);
ctx.arcTo(x + w, y, x + w, y + h, br);
ctx.arcTo(x + w, y + h, x, y + h, br);
ctx.arcTo(x, y + h, x, y, br);
ctx.arcTo(x, y, x + w, y, br);
ctx.closePath();
ctx.fill();
} else {
ctx.fillRect(x, y, w, h);
}
}
// Text (leaf nodes only, with text-shadow)
var hasChildEls = el.querySelector("div, span, img, video");
var text = "";
for (var j = 0; j < el.childNodes.length; j++)
if (el.childNodes[j].nodeType === 3) text += el.childNodes[j].textContent;
text = text.trim();
if (text && !hasChildEls) {
ctx.font = cs.fontWeight + " " + cs.fontSize + " " + cs.fontFamily;
ctx.fillStyle = cs.color;
if (cs.letterSpacing && cs.letterSpacing !== "normal")
ctx.letterSpacing = cs.letterSpacing;
var shadow = cs.textShadow;
if (shadow && shadow !== "none") {
var sp = shadow.match(/rgba?\([^)]+\)\s+(-?\d+)px\s+(-?\d+)px\s+(-?\d+)px/);
if (sp) {
ctx.shadowColor = shadow.match(/rgba?\([^)]+\)/)[0];
ctx.shadowOffsetX = parseFloat(sp[1]);
ctx.shadowOffsetY = parseFloat(sp[2]);
ctx.shadowBlur = parseFloat(sp[3]);
}
}
if (cs.textAlign === "center" || w > 1800) {
ctx.textAlign = "center";
ctx.textBaseline = "middle";
ctx.fillText(text, x + w / 2, y + h / 2);
} else {
ctx.textAlign = "left";
ctx.textBaseline = "middle";
ctx.fillText(text, x, y + h / 2);
}
}
ctx.restore();
}
scene.style.opacity = origOpacity;
scene.style.zIndex = origZ;
var tex = gl.createTexture();
gl.bindTexture(gl.TEXTURE_2D, tex);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, c);
sceneTextures[sceneId] = tex;
resolve();
});
});
});
}
// Re-capture video scenes every frame (call in updateTrans and during holds)
function recaptureVideoScene(sceneId) {
var video = sceneHasVideo[sceneId];
if (!video || video.readyState < 2) return;
var scene = document.getElementById(sceneId);
var c = document.createElement("canvas");
c.width = 1920;
c.height = 1080;
var ctx = c.getContext("2d");
ctx.fillStyle = window.getComputedStyle(scene).backgroundColor;
ctx.fillRect(0, 0, 1920, 1080);
var sr = scene.getBoundingClientRect();
var els = scene.querySelectorAll("*");
for (var i = 0; i < els.length; i++) {
var el = els[i],
cs = window.getComputedStyle(el);
if (cs.display === "none") continue;
var r = el.getBoundingClientRect();
if (r.width < 1) continue;
var x = r.left - sr.left,
y = r.top - sr.top,
w = r.width,
h = r.height;
ctx.save();
ctx.globalAlpha = parseFloat(cs.opacity) || 1;
if (el.tagName === "VIDEO" && el.readyState >= 2) {
try {
var vR = el.videoWidth / el.videoHeight,
bR = w / h;
var sx = 0,
sy = 0,
sw = el.videoWidth,
sh = el.videoHeight;
if (vR > bR) {
sw = sh * bR;
sx = (el.videoWidth - sw) / 2;
} else {
sh = sw / bR;
sy = (el.videoHeight - sh) / 2;
}
ctx.drawImage(el, sx, sy, sw, sh, x, y, w, h);
} catch (e) {}
} else if (el.tagName === "IMG" && el.complete) {
try {
ctx.drawImage(el, x, y, w, h);
} catch (e) {}
} else {
var bg = cs.backgroundColor;
if (bg && bg !== "rgba(0, 0, 0, 0)") {
ctx.fillStyle = bg;
ctx.fillRect(x, y, w, h);
}
var txt = "";
for (var j = 0; j < el.childNodes.length; j++)
if (el.childNodes[j].nodeType === 3) txt += el.childNodes[j].textContent;
txt = txt.trim();
if (txt && !el.querySelector("div,span,img,video")) {
ctx.font = cs.fontWeight + " " + cs.fontSize + " " + cs.fontFamily;
ctx.fillStyle = cs.color;
ctx.textAlign = "left";
ctx.textBaseline = "middle";
ctx.fillText(txt, x, y + h / 2);
}
}
ctx.restore();
}
gl.bindTexture(gl.TEXTURE_2D, sceneTextures[sceneId]);
gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, c);
}
```
## Shader Compilation + Shared Constants
@@ -352,7 +100,54 @@ var CP = "vec3 palette(float t,vec3 a,vec3 b,vec3 c,vec3 d){" + "return a+b*cos(
## Render + State Machine
DOM scenes play normally with GSAP animations during holds. The canvas is only visible during shader transitions — hidden the rest of the time. Capture uses html2canvas (loaded from CDN alongside GSAP).
Add this script tag alongside GSAP:
```html
<script src="https://cdn.jsdelivr.net/npm/html2canvas@1.4.1/dist/html2canvas.min.js"></script>
```
```js
// Patch createPattern for html2canvas bug with 0-dimension elements
var _origCP = CanvasRenderingContext2D.prototype.createPattern;
CanvasRenderingContext2D.prototype.createPattern = function (img, rep) {
if (img && (img.width === 0 || img.height === 0)) return null;
return _origCP.call(this, img, rep);
};
function uploadTexture(sceneId, canvas) {
if (!sceneTextures[sceneId]) {
var tex = gl.createTexture();
gl.bindTexture(gl.TEXTURE_2D, tex);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
sceneTextures[sceneId] = tex;
}
gl.bindTexture(gl.TEXTURE_2D, sceneTextures[sceneId]);
gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, canvas);
}
// BG_COLOR must match your composition's background color (e.g. "#0a0a1a").
// html2canvas backgroundColor: null means transparent, which renders as black
// in WebGL textures. Always pass the explicit color.
var BG_COLOR = "#000"; // ← set to your composition's background
function captureScene(sceneEl) {
return html2canvas(sceneEl, {
width: 1920,
height: 1080,
scale: 1,
backgroundColor: BG_COLOR,
logging: false,
ignoreElements: function (el) {
return el.tagName === "CANVAS" || el.hasAttribute("data-no-capture");
},
});
}
function renderShader(prog, texFrom, texTo, progress) {
gl.useProgram(prog);
gl.activeTexture(gl.TEXTURE0);
@@ -370,8 +165,6 @@ function renderShader(prog, texFrom, texTo, progress) {
gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
}
var progPass = mkProg(H + "void main(){gl_FragColor=texture2D(u_from,v_uv);}");
var trans = {
active: false,
prog: null,
@@ -381,83 +174,109 @@ var trans = {
};
function beginTrans(prog, fromId, toId) {
trans.prog = prog;
trans.fromId = fromId;
trans.toId = toId;
trans.progress = 0;
trans.active = true;
if (!gl) return;
var fromScene = document.getElementById(fromId);
var toScene = document.getElementById(toId);
// Capture outgoing scene (DOM stays visible during async capture)
captureScene(fromScene)
.then(function (fromCanvas) {
uploadTexture(fromId, fromCanvas);
// Show incoming scene BEHIND outgoing (z-index -1) for capture
toScene.style.zIndex = "-1";
toScene.style.opacity = "1";
var contentEl = toScene.querySelector(".scene-content");
if (contentEl) contentEl.style.visibility = "hidden";
// Wait 2 rAFs for browser to render with correct fonts
return new Promise(function (resolve) {
requestAnimationFrame(function () {
requestAnimationFrame(function () {
captureScene(toScene).then(function (toCanvas) {
if (contentEl) contentEl.style.visibility = "";
toScene.style.opacity = "0";
toScene.style.zIndex = "";
uploadTexture(toId, toCanvas);
resolve();
});
});
});
});
})
.then(function () {
// Both textures ready — swap DOM for canvas
document.querySelectorAll(".scene").forEach(function (s) {
s.style.opacity = "0";
});
glCanvas.style.display = "block";
trans.prog = prog;
trans.fromId = fromId;
trans.toId = toId;
trans.progress = 0;
trans.active = true;
});
}
function updateTrans() {
if (!trans.active) return;
// Re-capture video scenes every frame during transition
if (sceneHasVideo[trans.fromId]) recaptureVideoScene(trans.fromId);
if (sceneHasVideo[trans.toId]) recaptureVideoScene(trans.toId);
if (!trans.active || !gl) return;
renderShader(trans.prog, sceneTextures[trans.fromId], sceneTextures[trans.toId], trans.progress);
}
function endTrans(showId) {
trans.active = false;
renderShader(progPass, sceneTextures[showId], sceneTextures[showId], 0);
glCanvas.style.display = "none";
document.getElementById(showId).style.opacity = "1";
}
```
## GSAP Timeline Integration
Scene 1 starts visible on the DOM. GSAP animates elements normally. The canvas is hidden until a transition begins. After each transition, the canvas hides and the next scene's DOM takes over.
```js
// Wait for media, start videos, capture all scenes, then build timeline
var sceneIds = ["scene1", "scene2" /* ... */];
waitForMedia()
.then(function () {
// Start any background videos (muted)
document.querySelectorAll("video").forEach(function (v) {
v.play();
});
return Promise.all(sceneIds.map(captureScene));
})
.then(function () {
glCanvas.style.display = "block";
renderShader(progPass, sceneTextures["scene1"], sceneTextures["scene1"], 0);
document.querySelectorAll(".scene").forEach(function (s) {
s.style.opacity = "0";
});
// Canvas starts hidden — DOM scene 1 is visible
glCanvas.style.display = "none";
var tl = gsap.timeline({
paused: true,
onUpdate: function () {
updateTrans();
},
});
var tl = gsap.timeline({
paused: true,
onUpdate: function () {
updateTrans();
},
});
// For each transition:
tl.call(
function () {
beginTrans(myShaderProg, "scene1", "scene2");
},
null,
T,
);
var tw = { p: 0 };
tl.to(
tw,
{
p: 1,
duration: DUR,
ease: "power2.inOut",
onUpdate: function () {
trans.progress = tw.p;
},
},
T,
);
tl.call(
function () {
endTrans("scene2");
},
null,
T + DUR,
);
// Scene 1 entrance animations go here (normal GSAP on DOM)...
window.__timelines["main"] = tl;
});
// Transition 1→2:
tl.call(
function () {
beginTrans(myShaderProg, "scene1", "scene2");
},
null,
T,
);
var tw1 = { p: 0 };
tl.to(
tw1,
{
p: 1,
duration: DUR,
ease: "power2.inOut",
onUpdate: function () {
trans.progress = tw1.p;
},
},
T,
);
tl.call(
function () {
endTrans("scene2");
},
null,
T + DUR,
);
// Scene 2 entrance animations go here (normal GSAP on DOM)...
window.__timelines["main"] = tl;
```