Transitions for the modern web.

Why is my canvas blank?

Three things to check. (1) The canvas has measurable dimensions. The runner sets canvas.width / canvas.height from the canvas’s rendered size, but if the parent has collapsed to 0 it stays 0. (2) Your image sources are decoded before the first render call. runner.render doesn’t queue — if from or to hasn’t resolved an image yet, you get black. await img.decode() first. (3) Progress is in [0, 1]. Out of range values clamp visually but won’t throw.

Does it respect prefers-reduced-motion?

The library doesn’t drive any animation — you do, via your own animation library or scroll progress. So honoring user preference is just gating your driver: detect with matchMedia and either skip the animation entirely (render once at progress: 1) or run it instantly.

if (matchMedia("(prefers-reduced-motion: reduce)").matches) {
  // Skip the curl entirely — render once at the destination.
  runner.render(myTransition, { from, to, progress: 1 });
} else {
  animate({ from: 0, to: 1, duration: 1200,
    onUpdate: (p) => runner.render(myTransition, { from, to, progress: p }),
  });
}

How do I clean up the Runner?

Call runner.dispose(). Releases the WebGL context, shader / program cache, framebuffers, texture cache. Always run on unmount in component frameworks — otherwise re-renders accumulate dead contexts. Browsers cap WebGL contexts per page (~16 in Chrome) so leaking adds up fast.

What about Safari, iOS, older browsers?

WebGL2 ships in every modern browser: Safari 15+, iOS 15+, Firefox 51+, Chrome 56+, Edge, mobile Safari, mobile Chrome. The Runner constructor throws if the WebGL2 context can’t be created — wrap in try / catch and fall back to a CSS opacity crossfade for the long tail. For most sites it’s a non-issue.

How do I use this with React, Vue, or Svelte?

The vanilla API plays well with framework lifecycle hooks. The React pattern is a single useRef for the Runner plus an effect for re-render on prop change — Vue and Svelte look structurally similar.

// React
import { useEffect, useRef } from "react";
import { Runner, paintBleed } from "@vysmo/transitions";

function CrossfadeCanvas({ from, to, progress }) {
  const ref = useRef<HTMLCanvasElement>(null);
  const runnerRef = useRef<Runner | null>(null);

  useEffect(() => {
    const runner = new Runner({ canvas: ref.current! });
    runnerRef.current = runner;
    return () => runner.dispose();
  }, []);

  useEffect(() => {
    runnerRef.current?.render(paintBleed, { from, to, progress });
  }, [from, to, progress]);

  return <canvas ref={ref} />;
}

My custom transition flashes or has a hard cut. Why?

Three engineering invariants that every shader on this site has to meet — the same checklist applies to yours.

• Endpoint correctness. At progress=0 output must be pixel-pure from; at progress=1, pixel-pure to. If you’re using smoothstep(low, high, x) for a wipe, ensure the result evaluates to exactly 0 at p=0 and exactly 1 at p=1.
• Polish degrades at endpoints. Visual params (feather, blur, displacement, chroma split) must be zero-effect at p=0 and p=1. Common pattern: scale the effect by 4 * p * (1 - p) so it peaks mid-transition and gates cleanly to zero at both ends.
• Continuous motion. No visual freeze at any progress. A symmetric envelope like 4*p*(1-p) peaks at 0.5 and drops to zero velocity there — if it drives a positional transform AND your crossfade also centers at 0.5, the result reads as a "pause" mid-transition. Use monotonic transforms (angle = p * strength) for motion; reserve symmetric envelopes for effects that should zero at endpoints (blur, glow, aberration).