Merge pull request #456 from heygen-com/fix/shader-transitions-capture-robustness

fix(shader-transitions): harden capture against visibility, scrub, Safari taint
This commit is contained in:
Ular Kimsanov
2026-04-23 20:46:43 -04:00
committed by GitHub
2 changed files with 100 additions and 15 deletions
@@ -33,6 +33,33 @@ export function captureScene(sceneEl: HTMLElement, bgColor: string): Promise<HTM
scale: 1,
backgroundColor: bgColor,
logging: false,
// Safari applies stricter canvas-taint rules than Chrome. SVG data URLs
// with <filter> elements (e.g. feTurbulence grain backgrounds), certain
// cross-origin images, and mask/clip-path url() refs can taint the
// output canvas on WebKit. Without these flags, html2canvas throws
// `SecurityError: The operation is insecure` during its own read-back
// path and every shader transition falls through to the catch handler
// — observed in Safari + Claude Design's cross-origin iframe sandbox.
//
// useCORS: send CORS headers on image fetches so cross-origin images
// with proper `Access-Control-Allow-Origin` don't taint the
// canvas in the first place. Strict improvement.
// allowTaint: let html2canvas complete and return a canvas even when it
// becomes tainted (instead of throwing). Important caveat:
// a tainted canvas CANNOT be uploaded to WebGL via
// `gl.texImage2D` — WebGL spec requires SecurityError on
// non-origin-clean sources, with no opt-out. So this flag
// only moves the failure point from html2canvas to the
// texImage2D call in webgl.ts. In both cases `hyper-shader.ts`
// catches the rejected promise and runs the CSS crossfade
// fallback. Net effect: the end-user UX is the same (smooth
// CSS fade in either case), but we get a cleaner, more
// predictable error site and the flag is defensively
// correct for the non-taint branches where it genuinely
// helps (e.g., `crossOrigin="anonymous"` image fetches
// that already had CORS headers).
useCORS: true,
allowTaint: true,
ignoreElements: (el: Element) => el.tagName === "CANVAS" || el.hasAttribute("data-no-capture"),
});
}
@@ -41,6 +68,18 @@ export function captureScene(sceneEl: HTMLElement, bgColor: string): Promise<HTM
* Capture the incoming scene with .scene-content hidden (background + decoratives only).
* Shows the scene behind the outgoing scene via z-index, waits 2 rAFs for font rendering,
* captures, then restores.
*
* IMPORTANT: We force `visibility: visible` during capture because the HyperFrames runtime's
* time-based visibility gate (in `packages/core/src/runtime/init.ts`) sets `style.visibility
* = "hidden"` on every `[data-start]` element that's outside its current playback window —
* every frame. When a shader transition fires *before* the incoming scene's `data-start`
* boundary (the recommended "transition.time = boundary - duration/2" centered placement),
* the runtime has `visibility: hidden` on the incoming scene. Without the visibility override
* here, `html2canvas` captures the element as blank → shader transitions from the real
* outgoing scene to a blank incoming texture → users see content fade/morph into the
* background color mid-transition (a visible "blink"). Forcing `visibility: visible` only
* for the duration of the capture fixes this without affecting what the user sees during
* normal playback.
*/
export function captureIncomingScene(
toScene: HTMLElement,
@@ -49,14 +88,17 @@ export function captureIncomingScene(
return new Promise<HTMLCanvasElement>((resolve, reject) => {
const origZ = toScene.style.zIndex;
const origOpacity = toScene.style.opacity;
const origVisibility = toScene.style.visibility;
toScene.style.zIndex = "-1";
toScene.style.opacity = "1";
toScene.style.visibility = "visible";
const contentEl = toScene.querySelector<HTMLElement>(".scene-content");
if (contentEl) contentEl.style.visibility = "hidden";
const restore = () => {
if (contentEl) contentEl.style.visibility = "";
toScene.style.visibility = origVisibility;
toScene.style.opacity = origOpacity;
toScene.style.zIndex = origZ;
};
+58 -15
View File
@@ -14,12 +14,19 @@ import { initCapture, captureScene, captureIncomingScene } from "./capture.js";
declare const gsap: {
timeline: (opts: Record<string, unknown>) => GsapTimeline;
to: (target: HTMLElement | string, vars: Record<string, unknown>) => unknown;
fromTo: (
target: HTMLElement | string,
from: Record<string, unknown>,
to: Record<string, unknown>,
) => unknown;
};
interface GsapTimeline {
paused: () => boolean;
play: () => GsapTimeline;
pause: () => GsapTimeline;
time: () => number;
call: (fn: () => void, args: null, position: number) => GsapTimeline;
to: (
target: Record<string, unknown>,
@@ -271,25 +278,61 @@ export function init(config: HyperShaderConfig): GsapTimeline {
const toTex = textures.get(toId);
if (toTex) uploadTexture(gl, toTex, toCanvas);
document.querySelectorAll<HTMLElement>(".scene").forEach((s) => {
s.style.opacity = "0";
});
canvasEl.style.display = "block";
state.prog = prog;
state.fromId = fromId;
state.toId = toId;
state.progress = 0;
state.active = true;
// Guard: only apply transition-state DOM changes if the playhead
// is STILL inside this transition's [T, T+dur] window. Without
// this, a seek that crosses multiple transitions launches several
// async captures in parallel; each resolves ~80-200ms later and
// unconditionally calls querySelectorAll(".scene").opacity = "0"
// + canvas.display = "block" + state.active = true. The last one
// to resolve wins, so after seeking past a transition, state gets
// stuck pointing at the wrong transition and every scene is
// hidden — manifesting as the "scrub blanks until the next scene
// begins" bug. Checking tl.time() against the transition window
// keeps async capture completions from corrupting state the
// end-callback (at T+dur) or the next transition's start-callback
// has already set correctly.
const nowTime = tl.time();
const inWindow = nowTime >= T && nowTime < T + dur;
if (inWindow) {
document.querySelectorAll<HTMLElement>(".scene").forEach((s) => {
s.style.opacity = "0";
});
canvasEl.style.display = "block";
state.prog = prog;
state.fromId = fromId;
state.toId = toId;
state.progress = 0;
state.active = true;
}
if (wasPlaying) tl.play();
})
.catch((e) => {
console.warn("[HyperShader] Capture failed, falling back to hard cut:", e);
document.querySelectorAll<HTMLElement>(".scene").forEach((s) => {
s.style.opacity = "0";
});
const scene = document.getElementById(toId);
if (scene) scene.style.opacity = "1";
// Graceful fallback for unavoidable capture failures. The most
// common cause is Safari's stricter canvas-taint rules combined
// with SVG-filter-based background images (e.g. inline
// `<feTurbulence>` grain data URLs): html2canvas returns a
// tainted canvas, then `gl.texImage2D` throws SecurityError
// with no framework opt-out (WebGL spec). In Chrome this path
// rarely fires, but when it does (CORS-less cross-origin
// images, iframe sandbox restrictions, etc.) the old hard-cut
// was jarring. A CSS crossfade is strictly better UX.
console.warn("[HyperShader] Capture failed, CSS crossfade fallback:", e);
const nowTime = tl.time();
const inWindow = nowTime >= T && nowTime < T + dur;
if (inWindow) {
const fromEl = document.getElementById(fromId);
const toEl = document.getElementById(toId);
if (fromEl && toEl) {
gsap.to(fromEl, { opacity: 0, duration: dur, ease });
gsap.fromTo(toEl, { opacity: 0 }, { opacity: 1, duration: dur, ease });
} else {
document.querySelectorAll<HTMLElement>(".scene").forEach((s) => {
s.style.opacity = "0";
});
if (toEl) toEl.style.opacity = "1";
}
}
if (wasPlaying) tl.play();
});
},