@vysmo/transitions-react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maesto LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# @vysmo/transitions-react
+
+React bindings for [`@vysmo/transitions`](https://www.npmjs.com/package/@vysmo/transitions). One `<Transition>` component, one hook (`useTransitionRunner`), zero opinion on how you drive progress — controlled or self-driving, your call.
+
+[Live demos + parameter playground](https://vysmo.com/transitions) · [Source](https://github.com/vysmodev)
+
+## Install
+
+```bash
+pnpm add @vysmo/transitions @vysmo/transitions-react
+```
+
+`react` ≥ 18 is a peer dependency.
+
+## Quick start
+
+```tsx
+import { Transition } from "@vysmo/transitions-react";
+import { paintBleed } from "@vysmo/transitions";
+
+export function Hero() {
+  return (
+    <Transition
+      transition={paintBleed}
+      from="/images/a.jpg"
+      to="/images/b.jpg"
+      duration={1200}
+      style={{ width: "100%", aspectRatio: "16 / 9" }}
+    />
+  );
+}
+```
+
+That's the whole minimum. The component mounts a `<canvas>`, creates a `Runner`, resolves the URLs into decoded `Image`s, and runs an autoplay from `progress=0` to `progress=1` over `duration` ms. On unmount the runner is disposed.
+
+## Controlled progress
+
+Pass a `progress` prop — autoplay is bypassed and the component renders exactly at the value you supply. Drive it from anything: scroll progress, a scrubber, a tween library, your own state.
+
+```tsx
+// @no-check
+import { Transition } from "@vysmo/transitions-react";
+import { paintBleed } from "@vysmo/transitions";
+import { useScrollProgress } from "./somewhere";
+
+export function ScrollHero() {
+  const progress = useScrollProgress();   // 0 → 1 as the section passes
+  return (
+    <Transition
+      transition={paintBleed}
+      from="/a.jpg"
+      to="/b.jpg"
+      progress={progress}
+    />
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `transition` | `Transition` | — | Any transition exported by `@vysmo/transitions`. |
+| `from` | `Source` | — | URL string, `HTMLImageElement`, canvas, video, or `ImageBitmap`. |
+| `to` | `Source` | — | Same shape as `from`. |
+| `progress` | `number` | — | Controlled `[0,1]`. When set, autoplay is bypassed. |
+| `duration` | `number` | `1000` | Autoplay duration ms. Used only when `progress` is omitted. |
+| `playing` | `boolean` | `true` | Whether autoplay is running. Used only when `progress` is omitted. |
+| `loop` | `boolean` | `false` | Loop autoplay. |
+| `ease` | `(t: number) => number` | linear | Easing applied to autoplay. Pair with [`@vysmo/easings`](https://www.npmjs.com/package/@vysmo/easings) for named curves. |
+| `params` | `UniformParams` | — | Override shader uniform defaults (e.g. `{ blur: 0.05 }`). |
+| `onComplete` | `() => void` | — | Fires when a non-loop autoplay reaches `progress=1`. |
+| `className` | `string` | — | Forwarded to the `<canvas>`. |
+| `style` | `CSSProperties` | — | Forwarded to the `<canvas>`. |
+
+## Sizing
+
+The component renders a `<canvas>` and syncs its internal pixel dimensions to its CSS box via `ResizeObserver`, with `devicePixelRatio` applied. Style the canvas via `className` / `style` and the runner adapts.
+
+## Hook (advanced)
+
+If you need direct `Runner` access — e.g. to compose multiple renders per frame, or to drive a transition off a non-React render loop — use `useTransitionRunner`:
+
+```tsx
+import { useRef } from "react";
+import { useTransitionRunner } from "@vysmo/transitions-react";
+import { paintBleed } from "@vysmo/transitions";
+
+function CustomDriver({ from, to, progress }) {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  const runner = useTransitionRunner(canvasRef);
+
+  if (runner) {
+    runner.render(paintBleed, { from, to, progress });
+  }
+
+  return <canvas ref={canvasRef} />;
+}
+```
+
+The component is the right call for ~95% of cases; reach for the hook when the props don't expose what you need.
+
+## SSR
+
+The wrapper is SSR-safe: `useEffect` bodies don't run on the server, and the module body itself doesn't touch `window` / `document`. Server renders an empty `<canvas>`; client mounts the runner.
+
+## License
+
+MIT.

package/dist/Transition.d.ts

@@ -0,0 +1,47 @@
+import type { CSSProperties, ReactElement } from "react";
+import { type Transition as TransitionType, type UniformParams } from "@vysmo/transitions";
+import { type Source } from "./resolve-source.js";
+export interface TransitionProps {
+    /** Any transition exported by `@vysmo/transitions`. */
+    transition: TransitionType<UniformParams>;
+    /** First image. URL string, `HTMLImageElement`, canvas, video, or `ImageBitmap`. */
+    from: Source;
+    /** Second image. Same accepted shapes as `from`. */
+    to: Source;
+    /**
+     * Controlled progress in `[0, 1]`. When set, the component renders at
+     * exactly this progress and the autoplay loop is bypassed — drive it
+     * yourself (scroll progress, scrubber, animation library, etc.).
+     */
+    progress?: number;
+    /** Autoplay duration in ms. Used only when `progress` is omitted. Default `1000`. */
+    duration?: number;
+    /** Whether internal autoplay is running. Used only when `progress` is omitted. Default `true`. */
+    playing?: boolean;
+    /** Loop autoplay. Default `false`. */
+    loop?: boolean;
+    /** Easing function applied during autoplay. Default linear. */
+    ease?: (t: number) => number;
+    /** Override shader uniform defaults. */
+    params?: UniformParams;
+    /** Fires when a non-loop autoplay reaches `progress=1`. */
+    onComplete?: () => void;
+    /** Forwarded to the canvas element. */
+    className?: string;
+    /** Forwarded to the canvas element. */
+    style?: CSSProperties;
+}
+/**
+ * React wrapper around `@vysmo/transitions`'s `Runner`. Renders a
+ * `<canvas>` and drives a transition between two images — either
+ * controlled by a `progress` prop or self-driving via `duration` /
+ * `playing` / `loop` / `ease` for the common "play once on mount"
+ * case.
+ *
+ * The component creates one runner on mount and disposes it on
+ * unmount; sources are resolved (URL strings → decoded `Image`s) on
+ * `from` / `to` change. Canvas size syncs to its CSS box via
+ * `ResizeObserver`, with DPR applied so output stays sharp on retina.
+ */
+export declare function Transition({ transition, from, to, progress, duration, playing, loop, ease, params, onComplete, className, style, }: TransitionProps): ReactElement;
+//# sourceMappingURL=Transition.d.ts.map

package/dist/Transition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Transition.d.ts","sourceRoot":"","sources":["../src/Transition.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AACzD,OAAO,EAEL,KAAK,UAAU,IAAI,cAAc,EACjC,KAAK,aAAa,EAEnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAiB,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAEjE,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,UAAU,EAAE,cAAc,CAAC,aAAa,CAAC,CAAC;IAC1C,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,EAAE,EAAE,MAAM,CAAC;IACX;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kGAAkG;IAClG,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,sCAAsC;IACtC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,+DAA+D;IAC/D,IAAI,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC7B,wCAAwC;IACxC,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;IACxB,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,EACzB,UAAU,EACV,IAAI,EACJ,EAAE,EACF,QAAQ,EACR,QAAe,EACf,OAAc,EACd,IAAY,EACZ,IAAI,EACJ,MAAM,EACN,UAAU,EACV,SAAS,EACT,KAAK,GACN,EAAE,eAAe,GAAG,YAAY,CAkGhC"}

package/dist/Transition.js

@@ -0,0 +1,113 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { Runner, } from "@vysmo/transitions";
+import { resolveSource } from "./resolve-source.js";
+/**
+ * React wrapper around `@vysmo/transitions`'s `Runner`. Renders a
+ * `<canvas>` and drives a transition between two images — either
+ * controlled by a `progress` prop or self-driving via `duration` /
+ * `playing` / `loop` / `ease` for the common "play once on mount"
+ * case.
+ *
+ * The component creates one runner on mount and disposes it on
+ * unmount; sources are resolved (URL strings → decoded `Image`s) on
+ * `from` / `to` change. Canvas size syncs to its CSS box via
+ * `ResizeObserver`, with DPR applied so output stays sharp on retina.
+ */
+export function Transition({ transition, from, to, progress, duration = 1000, playing = true, loop = false, ease, params, onComplete, className, style, }) {
+    const canvasRef = useRef(null);
+    const runnerRef = useRef(null);
+    const [sources, setSources] = useState(null);
+    // Stash callable / object props in refs so the autoplay effect's
+    // dependency list can stay narrow — callers passing inline literals
+    // for `params` / `onComplete` / `ease` should not restart autoplay.
+    const paramsRef = useRef(params);
+    paramsRef.current = params;
+    const onCompleteRef = useRef(onComplete);
+    onCompleteRef.current = onComplete;
+    const easeRef = useRef(ease);
+    easeRef.current = ease;
+    // Mount: create runner + resize observer; dispose on unmount.
+    useEffect(() => {
+        const canvas = canvasRef.current;
+        if (!canvas)
+            return;
+        const syncSize = () => {
+            const rect = canvas.getBoundingClientRect();
+            const dpr = window.devicePixelRatio || 1;
+            const w = Math.max(1, Math.round(rect.width * dpr));
+            const h = Math.max(1, Math.round(rect.height * dpr));
+            if (canvas.width !== w)
+                canvas.width = w;
+            if (canvas.height !== h)
+                canvas.height = h;
+        };
+        syncSize();
+        const runner = new Runner({ canvas });
+        runnerRef.current = runner;
+        const ro = typeof ResizeObserver !== "undefined" ? new ResizeObserver(syncSize) : null;
+        ro?.observe(canvas);
+        return () => {
+            ro?.disconnect();
+            runner.dispose();
+            runnerRef.current = null;
+        };
+    }, []);
+    // Resolve sources whenever `from` / `to` change.
+    useEffect(() => {
+        let cancelled = false;
+        Promise.all([resolveSource(from), resolveSource(to)]).then(([f, t]) => {
+            if (!cancelled)
+                setSources({ from: f, to: t });
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [from, to]);
+    // Render: controlled (one render per progress change) or autoplay (rAF loop).
+    useEffect(() => {
+        const runner = runnerRef.current;
+        if (!runner || !sources)
+            return;
+        const renderArgs = paramsRef.current
+            ? { from: sources.from, to: sources.to, params: paramsRef.current }
+            : { from: sources.from, to: sources.to };
+        if (progress !== undefined) {
+            runner.render(transition, { ...renderArgs, progress });
+            return;
+        }
+        if (!playing)
+            return;
+        let cancelled = false;
+        let raf = 0;
+        let start = 0;
+        const tick = (now) => {
+            if (cancelled)
+                return;
+            if (start === 0)
+                start = now;
+            const t = Math.min(1, (now - start) / duration);
+            const easedT = easeRef.current ? easeRef.current(t) : t;
+            runner.render(transition, { ...renderArgs, progress: easedT });
+            if (t < 1) {
+                raf = requestAnimationFrame(tick);
+            }
+            else if (loop) {
+                start = 0;
+                raf = requestAnimationFrame(tick);
+            }
+            else {
+                onCompleteRef.current?.();
+            }
+        };
+        raf = requestAnimationFrame(tick);
+        return () => {
+            cancelled = true;
+            if (raf)
+                cancelAnimationFrame(raf);
+        };
+    }, [sources, transition, progress, playing, loop, duration]);
+    return _jsx("canvas", { ref: canvasRef, className: className, style: style });
+}
+//# sourceMappingURL=Transition.js.map

package/dist/Transition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Transition.js","sourceRoot":"","sources":["../src/Transition.tsx"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { Transition, type TransitionProps } from "./Transition.js";
+export { useTransitionRunner } from "./use-transition-runner.js";
+export { resolveSource, type Source, type ResolvedSource } from "./resolve-source.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,KAAK,MAAM,EAAE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { Transition } from "./Transition.js";
+export { useTransitionRunner } from "./use-transition-runner.js";
+export { resolveSource } from "./resolve-source.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAwB,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,aAAa,EAAoC,MAAM,qBAAqB,CAAC"}

package/dist/resolve-source.d.ts

@@ -0,0 +1,17 @@
+import type { TextureSource } from "@vysmo/transitions";
+/**
+ * What the React wrapper accepts as a `from` / `to`. Strings are
+ * convenience for `<img src=…>`-style URLs; everything else passes
+ * straight through to the runner.
+ */
+export type Source = string | HTMLImageElement | HTMLCanvasElement | HTMLVideoElement | ImageBitmap;
+export type ResolvedSource = Exclude<Source, string>;
+/**
+ * Resolve a `Source` to a paint-ready `TextureSource`. Strings load via
+ * a fresh `Image` with `crossOrigin="anonymous"` and `decode()` so the
+ * transition can render on the next frame without showing a blank
+ * canvas. Non-string sources await `decode()` if applicable, then
+ * pass through.
+ */
+export declare function resolveSource(source: Source): Promise<TextureSource>;
+//# sourceMappingURL=resolve-source.d.ts.map

package/dist/resolve-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-source.d.ts","sourceRoot":"","sources":["../src/resolve-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;;GAIG;AACH,MAAM,MAAM,MAAM,GACd,MAAM,GACN,gBAAgB,GAChB,iBAAiB,GACjB,gBAAgB,GAChB,WAAW,CAAC;AAEhB,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAErD;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAY1E"}

package/dist/resolve-source.js

@@ -0,0 +1,22 @@
+/**
+ * Resolve a `Source` to a paint-ready `TextureSource`. Strings load via
+ * a fresh `Image` with `crossOrigin="anonymous"` and `decode()` so the
+ * transition can render on the next frame without showing a blank
+ * canvas. Non-string sources await `decode()` if applicable, then
+ * pass through.
+ */
+export async function resolveSource(source) {
+    if (typeof source === "string") {
+        const img = new Image();
+        img.crossOrigin = "anonymous";
+        img.src = source;
+        if ("decode" in img)
+            await img.decode();
+        return img;
+    }
+    if (source instanceof HTMLImageElement && !source.complete) {
+        await source.decode();
+    }
+    return source;
+}
+//# sourceMappingURL=resolve-source.js.map

package/dist/resolve-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-source.js","sourceRoot":"","sources":["../src/resolve-source.ts"],"names":[],"mappings":"AAgBA;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAc;IAChD,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,IAAI,KAAK,EAAE,CAAC;QACxB,GAAG,CAAC,WAAW,GAAG,WAAW,CAAC;QAC9B,GAAG,CAAC,GAAG,GAAG,MAAM,CAAC;QACjB,IAAI,QAAQ,IAAI,GAAG;YAAE,MAAM,GAAG,CAAC,MAAM,EAAE,CAAC;QACxC,OAAO,GAAG,CAAC;IACb,CAAC;IACD,IAAI,MAAM,YAAY,gBAAgB,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;QAC3D,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC;IACxB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/use-transition-runner.d.ts

@@ -0,0 +1,16 @@
+import type { RefObject } from "react";
+import { Runner } from "@vysmo/transitions";
+/**
+ * Low-level escape hatch for callers who want the `<Transition>`
+ * component's lifecycle but their own render loop. Pass a ref to a
+ * canvas you mount yourself; the hook constructs a `Runner` once the
+ * canvas is in the DOM and disposes it on unmount, returning the
+ * runner instance (or `null` while it's still mounting).
+ *
+ * The component built on this is `<Transition>` — reach for the hook
+ * only when you're integrating with a non-React render loop or need
+ * direct `runner.render()` access for multi-pass / displacement cases
+ * the props don't expose yet.
+ */
+export declare function useTransitionRunner(canvasRef: RefObject<HTMLCanvasElement | null>): Runner | null;
+//# sourceMappingURL=use-transition-runner.d.ts.map

package/dist/use-transition-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-transition-runner.d.ts","sourceRoot":"","sources":["../src/use-transition-runner.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,SAAS,CAAC,iBAAiB,GAAG,IAAI,CAAC,GAC7C,MAAM,GAAG,IAAI,CAef"}

package/dist/use-transition-runner.js

@@ -0,0 +1,31 @@
+"use client";
+import { useEffect, useState } from "react";
+import { Runner } from "@vysmo/transitions";
+/**
+ * Low-level escape hatch for callers who want the `<Transition>`
+ * component's lifecycle but their own render loop. Pass a ref to a
+ * canvas you mount yourself; the hook constructs a `Runner` once the
+ * canvas is in the DOM and disposes it on unmount, returning the
+ * runner instance (or `null` while it's still mounting).
+ *
+ * The component built on this is `<Transition>` — reach for the hook
+ * only when you're integrating with a non-React render loop or need
+ * direct `runner.render()` access for multi-pass / displacement cases
+ * the props don't expose yet.
+ */
+export function useTransitionRunner(canvasRef) {
+    const [runner, setRunner] = useState(null);
+    useEffect(() => {
+        const canvas = canvasRef.current;
+        if (!canvas)
+            return;
+        const r = new Runner({ canvas });
+        setRunner(r);
+        return () => {
+            r.dispose();
+            setRunner(null);
+        };
+    }, [canvasRef]);
+    return runner;
+}
+//# sourceMappingURL=use-transition-runner.js.map

package/dist/use-transition-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-transition-runner.js","sourceRoot":"","sources":["../src/use-transition-runner.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAE5C,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAA8C;IAE9C,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAgB,IAAI,CAAC,CAAC;IAE1D,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC;QACjC,IAAI,CAAC,MAAM;YAAE,OAAO;QACpB,MAAM,CAAC,GAAG,IAAI,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;QACjC,SAAS,CAAC,CAAC,CAAC,CAAC;QACb,OAAO,GAAG,EAAE;YACV,CAAC,CAAC,OAAO,EAAE,CAAC;YACZ,SAAS,CAAC,IAAI,CAAC,CAAC;QAClB,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;IAEhB,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@vysmo/transitions-react",
+  "version": "0.1.0",
+  "description": "React bindings for @vysmo/transitions — a <Transition> component that renders any of the 60 WebGL transition shaders between two images, with controlled progress or self-driving autoplay.",
+  "license": "MIT",
+  "keywords": [
+    "react",
+    "webgl",
+    "webgl2",
+    "transitions",
+    "shader",
+    "animation",
+    "vysmo"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./src/index.ts",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "@vysmo/transitions": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitest/browser": "^3.2.4",
+    "playwright": "^1.59.1",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4",
+    "@vysmo/transitions": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "test": "vitest run && vitest run --config vitest.ssr.config.ts",
+    "test:browser": "vitest run",
+    "test:ssr": "vitest run --config vitest.ssr.config.ts",
+    "test:watch": "vitest"
+  }
+}

package/src/Transition.tsx

@@ -0,0 +1,167 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import type { CSSProperties, ReactElement } from "react";
+import {
+  Runner,
+  type Transition as TransitionType,
+  type UniformParams,
+  type TextureSource,
+} from "@vysmo/transitions";
+import { resolveSource, type Source } from "./resolve-source.js";
+
+export interface TransitionProps {
+  /** Any transition exported by `@vysmo/transitions`. */
+  transition: TransitionType<UniformParams>;
+  /** First image. URL string, `HTMLImageElement`, canvas, video, or `ImageBitmap`. */
+  from: Source;
+  /** Second image. Same accepted shapes as `from`. */
+  to: Source;
+  /**
+   * Controlled progress in `[0, 1]`. When set, the component renders at
+   * exactly this progress and the autoplay loop is bypassed — drive it
+   * yourself (scroll progress, scrubber, animation library, etc.).
+   */
+  progress?: number;
+  /** Autoplay duration in ms. Used only when `progress` is omitted. Default `1000`. */
+  duration?: number;
+  /** Whether internal autoplay is running. Used only when `progress` is omitted. Default `true`. */
+  playing?: boolean;
+  /** Loop autoplay. Default `false`. */
+  loop?: boolean;
+  /** Easing function applied during autoplay. Default linear. */
+  ease?: (t: number) => number;
+  /** Override shader uniform defaults. */
+  params?: UniformParams;
+  /** Fires when a non-loop autoplay reaches `progress=1`. */
+  onComplete?: () => void;
+  /** Forwarded to the canvas element. */
+  className?: string;
+  /** Forwarded to the canvas element. */
+  style?: CSSProperties;
+}
+
+/**
+ * React wrapper around `@vysmo/transitions`'s `Runner`. Renders a
+ * `<canvas>` and drives a transition between two images — either
+ * controlled by a `progress` prop or self-driving via `duration` /
+ * `playing` / `loop` / `ease` for the common "play once on mount"
+ * case.
+ *
+ * The component creates one runner on mount and disposes it on
+ * unmount; sources are resolved (URL strings → decoded `Image`s) on
+ * `from` / `to` change. Canvas size syncs to its CSS box via
+ * `ResizeObserver`, with DPR applied so output stays sharp on retina.
+ */
+export function Transition({
+  transition,
+  from,
+  to,
+  progress,
+  duration = 1000,
+  playing = true,
+  loop = false,
+  ease,
+  params,
+  onComplete,
+  className,
+  style,
+}: TransitionProps): ReactElement {
+  const canvasRef = useRef<HTMLCanvasElement | null>(null);
+  const runnerRef = useRef<Runner | null>(null);
+  const [sources, setSources] = useState<{ from: TextureSource; to: TextureSource } | null>(null);
+
+  // Stash callable / object props in refs so the autoplay effect's
+  // dependency list can stay narrow — callers passing inline literals
+  // for `params` / `onComplete` / `ease` should not restart autoplay.
+  const paramsRef = useRef(params);
+  paramsRef.current = params;
+  const onCompleteRef = useRef(onComplete);
+  onCompleteRef.current = onComplete;
+  const easeRef = useRef(ease);
+  easeRef.current = ease;
+
+  // Mount: create runner + resize observer; dispose on unmount.
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+
+    const syncSize = () => {
+      const rect = canvas.getBoundingClientRect();
+      const dpr = window.devicePixelRatio || 1;
+      const w = Math.max(1, Math.round(rect.width * dpr));
+      const h = Math.max(1, Math.round(rect.height * dpr));
+      if (canvas.width !== w) canvas.width = w;
+      if (canvas.height !== h) canvas.height = h;
+    };
+    syncSize();
+
+    const runner = new Runner({ canvas });
+    runnerRef.current = runner;
+
+    const ro = typeof ResizeObserver !== "undefined" ? new ResizeObserver(syncSize) : null;
+    ro?.observe(canvas);
+
+    return () => {
+      ro?.disconnect();
+      runner.dispose();
+      runnerRef.current = null;
+    };
+  }, []);
+
+  // Resolve sources whenever `from` / `to` change.
+  useEffect(() => {
+    let cancelled = false;
+    Promise.all([resolveSource(from), resolveSource(to)]).then(([f, t]) => {
+      if (!cancelled) setSources({ from: f, to: t });
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [from, to]);
+
+  // Render: controlled (one render per progress change) or autoplay (rAF loop).
+  useEffect(() => {
+    const runner = runnerRef.current;
+    if (!runner || !sources) return;
+
+    const renderArgs = paramsRef.current
+      ? { from: sources.from, to: sources.to, params: paramsRef.current }
+      : { from: sources.from, to: sources.to };
+
+    if (progress !== undefined) {
+      runner.render(transition, { ...renderArgs, progress });
+      return;
+    }
+
+    if (!playing) return;
+
+    let cancelled = false;
+    let raf = 0;
+    let start = 0;
+
+    const tick = (now: number) => {
+      if (cancelled) return;
+      if (start === 0) start = now;
+      const t = Math.min(1, (now - start) / duration);
+      const easedT = easeRef.current ? easeRef.current(t) : t;
+      runner.render(transition, { ...renderArgs, progress: easedT });
+      if (t < 1) {
+        raf = requestAnimationFrame(tick);
+      } else if (loop) {
+        start = 0;
+        raf = requestAnimationFrame(tick);
+      } else {
+        onCompleteRef.current?.();
+      }
+    };
+    raf = requestAnimationFrame(tick);
+
+    return () => {
+      cancelled = true;
+      if (raf) cancelAnimationFrame(raf);
+    };
+  }, [sources, transition, progress, playing, loop, duration]);
+
+  return <canvas ref={canvasRef} className={className} style={style} />;
+}

package/src/__tests__/Transition.test.tsx

@@ -0,0 +1,143 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { createRoot, type Root } from "react-dom/client";
+import { act } from "react";
+import { dissolve } from "@vysmo/transitions";
+import { Transition } from "../Transition.js";
+
+// React 19's `act` only short-circuits its scheduler when this flag is
+// set; otherwise it logs a noisy "not configured to support act"
+// warning even when the wrapping does happen correctly.
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+function makeSolid(r: number, g: number, b: number, size = 32): HTMLCanvasElement {
+  const canvas = document.createElement("canvas");
+  canvas.width = size;
+  canvas.height = size;
+  const ctx = canvas.getContext("2d");
+  if (!ctx) throw new Error("2D context unavailable");
+  ctx.fillStyle = `rgb(${r}, ${g}, ${b})`;
+  ctx.fillRect(0, 0, size, size);
+  return canvas;
+}
+
+function flush(): Promise<void> {
+  return new Promise((r) => setTimeout(r, 0));
+}
+
+describe("<Transition>", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    container.style.width = "128px";
+    container.style.height = "128px";
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(async () => {
+    await act(async () => {
+      root.unmount();
+    });
+    container.remove();
+  });
+
+  it("renders a canvas element", async () => {
+    const a = makeSolid(255, 0, 0);
+    const b = makeSolid(0, 0, 255);
+    await act(async () => {
+      root.render(<Transition transition={dissolve} from={a} to={b} progress={0} />);
+    });
+    expect(container.querySelector("canvas")).toBeTruthy();
+  });
+
+  it("at progress=0 renders the from-image (red)", async () => {
+    const a = makeSolid(255, 0, 0);
+    const b = makeSolid(0, 0, 255);
+    await act(async () => {
+      root.render(<Transition transition={dissolve} from={a} to={b} progress={0} />);
+    });
+    await flush();
+    // Re-render to ensure render effect runs after sources resolve.
+    await act(async () => {
+      root.render(<Transition transition={dissolve} from={a} to={b} progress={0} />);
+    });
+    const canvas = container.querySelector("canvas")!;
+    const gl = canvas.getContext("webgl2", { preserveDrawingBuffer: true });
+    // We're not asserting pixels here — the runner doesn't preserve the
+    // drawing buffer by default (and the wrapper doesn't expose that
+    // option yet). The fact that the component mounted, resolved the
+    // sources, and drove a render without throwing is the contract.
+    expect(gl).toBeTruthy();
+  });
+
+  it("forwards className and style to the canvas", async () => {
+    const a = makeSolid(255, 0, 0);
+    const b = makeSolid(0, 0, 255);
+    await act(async () => {
+      root.render(
+        <Transition
+          transition={dissolve}
+          from={a}
+          to={b}
+          progress={0.5}
+          className="test-class"
+          style={{ borderRadius: "12px" }}
+        />,
+      );
+    });
+    const canvas = container.querySelector("canvas")!;
+    expect(canvas.className).toBe("test-class");
+    expect(canvas.style.borderRadius).toBe("12px");
+  });
+
+  it("resolves a string URL to an image (data URL path)", async () => {
+    // 1×1 transparent PNG.
+    const url =
+      "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=";
+    await act(async () => {
+      root.render(<Transition transition={dissolve} from={url} to={url} progress={0} />);
+    });
+    // Wait for image decode.
+    await flush();
+    await flush();
+    expect(container.querySelector("canvas")).toBeTruthy();
+  });
+
+  it("autoplays when no progress prop is given and calls onComplete", async () => {
+    const a = makeSolid(255, 0, 0);
+    const b = makeSolid(0, 0, 255);
+    let completed = false;
+    await act(async () => {
+      root.render(
+        <Transition
+          transition={dissolve}
+          from={a}
+          to={b}
+          duration={50}
+          onComplete={() => {
+            completed = true;
+          }}
+        />,
+      );
+    });
+    // Wait for autoplay to finish (~50ms) plus rAF.
+    await new Promise((r) => setTimeout(r, 200));
+    expect(completed).toBe(true);
+  });
+
+  it("disposes runner on unmount without throwing", async () => {
+    const a = makeSolid(255, 0, 0);
+    const b = makeSolid(0, 0, 255);
+    await act(async () => {
+      root.render(<Transition transition={dissolve} from={a} to={b} progress={0.5} />);
+    });
+    await act(async () => {
+      root.unmount();
+    });
+    // Re-create root for afterEach to unmount safely.
+    root = createRoot(container);
+    expect(container.querySelector("canvas")).toBeNull();
+  });
+});

package/src/__tests__/ssr.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+
+/**
+ * SSR safety: the module must load in Node without DOM globals. This
+ * verifies that no top-level code touches `window` / `document` / etc
+ * — `useEffect` bodies don't run on the server, so as long as the
+ * imports + module bodies are clean, the wrapper is SSR-safe.
+ */
+describe("SSR safety", () => {
+  it("window is undefined in this runtime", () => {
+    expect(typeof window).toBe("undefined");
+  });
+
+  it("module loads without DOM globals", async () => {
+    const mod = await import("../index.js");
+    expect(mod).toBeDefined();
+    expect(typeof mod.Transition).toBe("function");
+    expect(typeof mod.useTransitionRunner).toBe("function");
+    expect(typeof mod.resolveSource).toBe("function");
+  });
+});

package/src/index.ts

@@ -0,0 +1,3 @@
+export { Transition, type TransitionProps } from "./Transition.js";
+export { useTransitionRunner } from "./use-transition-runner.js";
+export { resolveSource, type Source, type ResolvedSource } from "./resolve-source.js";

package/src/resolve-source.ts

@@ -0,0 +1,36 @@
+import type { TextureSource } from "@vysmo/transitions";
+
+/**
+ * What the React wrapper accepts as a `from` / `to`. Strings are
+ * convenience for `<img src=…>`-style URLs; everything else passes
+ * straight through to the runner.
+ */
+export type Source =
+  | string
+  | HTMLImageElement
+  | HTMLCanvasElement
+  | HTMLVideoElement
+  | ImageBitmap;
+
+export type ResolvedSource = Exclude<Source, string>;
+
+/**
+ * Resolve a `Source` to a paint-ready `TextureSource`. Strings load via
+ * a fresh `Image` with `crossOrigin="anonymous"` and `decode()` so the
+ * transition can render on the next frame without showing a blank
+ * canvas. Non-string sources await `decode()` if applicable, then
+ * pass through.
+ */
+export async function resolveSource(source: Source): Promise<TextureSource> {
+  if (typeof source === "string") {
+    const img = new Image();
+    img.crossOrigin = "anonymous";
+    img.src = source;
+    if ("decode" in img) await img.decode();
+    return img;
+  }
+  if (source instanceof HTMLImageElement && !source.complete) {
+    await source.decode();
+  }
+  return source;
+}

package/src/use-transition-runner.ts

@@ -0,0 +1,36 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import type { RefObject } from "react";
+import { Runner } from "@vysmo/transitions";
+
+/**
+ * Low-level escape hatch for callers who want the `<Transition>`
+ * component's lifecycle but their own render loop. Pass a ref to a
+ * canvas you mount yourself; the hook constructs a `Runner` once the
+ * canvas is in the DOM and disposes it on unmount, returning the
+ * runner instance (or `null` while it's still mounting).
+ *
+ * The component built on this is `<Transition>` — reach for the hook
+ * only when you're integrating with a non-React render loop or need
+ * direct `runner.render()` access for multi-pass / displacement cases
+ * the props don't expose yet.
+ */
+export function useTransitionRunner(
+  canvasRef: RefObject<HTMLCanvasElement | null>,
+): Runner | null {
+  const [runner, setRunner] = useState<Runner | null>(null);
+
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+    const r = new Runner({ canvas });
+    setRunner(r);
+    return () => {
+      r.dispose();
+      setRunner(null);
+    };
+  }, [canvasRef]);
+
+  return runner;
+}