@effect-motion/react 0.2.0

package/README.md

@@ -0,0 +1,32 @@
+# @effect-motion/react
+
+React bindings for [effect-motion](https://www.npmjs.com/package/effect-motion): a `<Player>` component and a `usePlayer` hook for playing scenes in the browser.
+
+Because scenes are deterministic and finite, the player runs a scene once, collects every frame, and plays them back — so seeking in either direction is free.
+
+## Install
+
+`effect` and `effect-motion` are peer dependencies — install them alongside:
+
+```bash
+pnpm add @effect-motion/react effect-motion effect
+```
+
+## Play a scene
+
+`<Player>` runs the scene and gives you transport controls — play/pause and a scrubbable progress bar:
+
+```tsx
+import { Player } from "@effect-motion/react";
+import { scene } from "./my-scene";
+
+export function App() {
+	return <Player scene={scene} width={500} height={300} autoPlay />;
+}
+```
+
+Prefer your own UI? `usePlayer(scene, options)` exposes the same state and controls (`status`, `frame`, `progress`, `play`, `pause`, `seek`, …) without any chrome.
+
+## Documentation
+
+Full docs, concepts, and live examples: **https://github.com/julia-script/effect-motion**

package/dist/Player.d.ts

@@ -0,0 +1,11 @@
+import { type AnyScene, type UsePlayerOptions } from "./usePlayer";
+export interface PlayerProps extends UsePlayerOptions {
+    readonly scene: AnyScene;
+}
+/**
+ * A scene player: metadata-sized SVG viewport and a transport bar with
+ * play/pause, a scrubber clamped to the buffered range, a time readout,
+ * and a loop toggle. Focus the player for keyboard control: Space toggles
+ * playback, arrow keys step one frame.
+ */
+export declare const Player: ({ scene, ...options }: PlayerProps) => import("react").JSX.Element;

package/dist/Player.js

@@ -0,0 +1,136 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * biome-ignore-all lint/a11y/noNoninteractiveTabindex: the player root is a
+ * deliberate focus target for transport shortcuts (space/arrows), like the
+ * native <video> element
+ * biome-ignore-all lint/a11y/noStaticElementInteractions: keyboard transport
+ * is scoped to the focused player root
+ */
+import { Layer } from "effect";
+import * as Effect from "effect/Effect";
+import { Svg } from "effect-motion";
+import { useEffect, useRef } from "react";
+import { usePlayer, } from "./usePlayer";
+const layers = Svg.layer.pipe(Layer.provideMerge(Svg.shapesLayer));
+// everything in the SVG DOM sink and its entity renderers is synchronous
+const renderFrame = (frame, target) => Effect.runSync(Effect.gen(function* () {
+    const renderer = yield* Svg.SvgDomRenderer.Context;
+    // no size in the config: the sink falls back to frame metadata
+    yield* renderer.render(frame, { target });
+}).pipe(Effect.provide(layers)));
+const iconProps = {
+    width: 14,
+    height: 14,
+    viewBox: "0 0 16 16",
+    fill: "currentColor",
+};
+// icons are decorative: the owning buttons carry the accessible labels
+const PlayIcon = () => (_jsx("svg", { ...iconProps, "aria-hidden": "true", children: _jsx("path", { d: "M4.5 2.5v11l9-5.5z" }) }));
+const PauseIcon = () => (_jsx("svg", { ...iconProps, "aria-hidden": "true", children: _jsx("path", { d: "M4 2.5h3v11H4zM9 2.5h3v11H9z" }) }));
+const LoopIcon = () => (_jsx("svg", { ...iconProps, "aria-hidden": "true", children: _jsx("path", { d: "M4 5h6V3l3.5 3L10 9V7H5v3H3V6a1 1 0 0 1 1-1zM12 11H6v2l-3.5-3L6 7v2h5V6h2v4a1 1 0 0 1-1 1z" }) }));
+const buttonStyle = (active) => ({
+    display: "inline-flex",
+    alignItems: "center",
+    justifyContent: "center",
+    width: 28,
+    height: 28,
+    padding: 0,
+    border: "none",
+    borderRadius: 6,
+    background: "transparent",
+    color: active ? "#8b9cff" : "#d6d6de",
+    cursor: "pointer",
+});
+const formatTime = (frames, frameRate) => {
+    const seconds = Math.floor(frames / frameRate);
+    return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, "0")}`;
+};
+/**
+ * A scene player: metadata-sized SVG viewport and a transport bar with
+ * play/pause, a scrubber clamped to the buffered range, a time readout,
+ * and a loop toggle. Focus the player for keyboard control: Space toggles
+ * playback, arrow keys step one frame.
+ */
+export const Player = ({ scene, ...options }) => {
+    const player = usePlayer(scene, options);
+    const viewportRef = useRef(null);
+    // scene resolution: frame metadata once available, else explicit props
+    const sceneWidth = player.currentFrame?.width ?? options.width;
+    const sceneHeight = player.currentFrame?.height ?? options.height;
+    useEffect(() => {
+        const target = viewportRef.current;
+        if (target === null || player.currentFrame === null) {
+            return;
+        }
+        renderFrame(player.currentFrame, target);
+        // ponytail: post-process the sink's root for responsive scaling —
+        // viewBox + CSS size lets the fixed-pixel SVG fill the viewport box;
+        // move viewBox into the sink if another consumer needs scaling
+        const svg = target.querySelector("svg");
+        if (svg !== null) {
+            svg.setAttribute("viewBox", `0 0 ${player.currentFrame.width} ${player.currentFrame.height}`);
+            svg.style.width = "100%";
+            svg.style.height = "100%";
+            svg.style.display = "block";
+        }
+    }, [player.currentFrame]);
+    const handleKeyDown = (event) => {
+        // buttons and the scrubber already handle these keys natively
+        const tag = event.target.tagName;
+        if (tag === "BUTTON" || tag === "INPUT") {
+            return;
+        }
+        if (event.key === " ") {
+            event.preventDefault();
+            player.toggle();
+        }
+        else if (event.key === "ArrowRight") {
+            event.preventDefault();
+            player.pause();
+            player.seek(player.frame + 1);
+        }
+        else if (event.key === "ArrowLeft") {
+            event.preventDefault();
+            player.pause();
+            player.seek(player.frame - 1);
+        }
+    };
+    return (_jsxs("div", { tabIndex: 0, onKeyDown: handleKeyDown, style: {
+            display: "flex",
+            flexDirection: "column",
+            // fill the container like a video element; the aspect ratio
+            // below keeps the scene's proportions at any width
+            width: "100%",
+            background: "#101014",
+            borderRadius: 10,
+            overflow: "hidden",
+        }, children: [_jsxs("div", { style: {
+                    position: "relative",
+                    width: "100%",
+                    aspectRatio: sceneWidth !== undefined && sceneHeight !== undefined
+                        ? `${sceneWidth} / ${sceneHeight}`
+                        : undefined,
+                    minHeight: sceneHeight === undefined ? 120 : undefined,
+                }, children: [_jsx("div", { ref: viewportRef, style: { width: "100%", height: "100%" } }), player.status === "loading" ? (_jsx("div", { style: {
+                            position: "absolute",
+                            inset: 0,
+                            display: "flex",
+                            alignItems: "center",
+                            justifyContent: "center",
+                            color: "#6b6b76",
+                            fontSize: 13,
+                        }, children: "Loading\u2026" })) : null] }), _jsxs("div", { style: {
+                    display: "flex",
+                    alignItems: "center",
+                    gap: 8,
+                    padding: "6px 10px",
+                    background: "#1a1a20",
+                }, children: [_jsx("button", { type: "button", onClick: player.toggle, disabled: player.status !== "ready", "aria-label": player.playing ? "Pause" : "Play", style: buttonStyle(false), children: player.playing ? _jsx(PauseIcon, {}) : _jsx(PlayIcon, {}) }), _jsx("input", { type: "range", "aria-label": "Progress", min: 0, max: Math.max(0, (player.totalFrames ?? player.bufferedFrames) - 1), step: 1, value: player.frame, onChange: (event) => player.seek(Number(event.currentTarget.value)), disabled: player.status !== "ready", style: { flex: 1, accentColor: "#8b9cff", margin: 0 } }), _jsx("span", { style: {
+                            color: "#b9b9c3",
+                            fontSize: 12,
+                            fontVariantNumeric: "tabular-nums",
+                            whiteSpace: "nowrap",
+                        }, children: player.totalFrames !== null
+                            ? `${formatTime(player.frame, player.frameRate)} / ${formatTime(player.totalFrames, player.frameRate)}`
+                            : formatTime(player.frame, player.frameRate) }), _jsx("button", { type: "button", onClick: () => player.setLoop(!player.loop), "aria-label": "Loop", "aria-pressed": player.loop, style: buttonStyle(player.loop), children: _jsx(LoopIcon, {}) })] }), player.status === "error" ? (_jsxs("div", { role: "alert", style: { color: "#ff8a8a", padding: "6px 10px" }, children: ["Scene failed: ", String(player.error)] })) : null] }));
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { Player, type PlayerProps } from "./Player";
+export { type AnyScene, type Player as PlayerHandle, type PlayerFrame, type PlayerStatus, type UsePlayerOptions, usePlayer, } from "./usePlayer";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { Player } from "./Player";
+export { usePlayer, } from "./usePlayer";

package/dist/usePlayer.d.ts

@@ -0,0 +1,46 @@
+import { type Entity, Scene } from "effect-motion";
+export type PlayerStatus = "loading" | "ready" | "error";
+/** A scene as produced by `Scene.make`, requirements erased. */
+export type AnyScene = Scene.Scene<unknown, unknown, Entity.AnyEntity>;
+export type PlayerFrame = Scene.Frame<Entity.AnyEntity>;
+export interface UsePlayerOptions {
+    readonly seed?: number | string | undefined;
+    /** frames per second of both the scene runner and the playback clock */
+    readonly frameRate?: number | undefined;
+    /** scene resolution, forwarded to the runner and stamped on frames */
+    readonly width?: number | undefined;
+    readonly height?: number | undefined;
+    /** start playing as soon as the first frame is buffered */
+    readonly autoPlay?: boolean | undefined;
+}
+export interface Player {
+    readonly status: PlayerStatus;
+    /** the failure value when `status` is "error" */
+    readonly error: unknown;
+    /** the frame to show right now (null while loading/error) */
+    readonly currentFrame: PlayerFrame | null;
+    /** current frame index */
+    readonly frame: number;
+    /** frames pulled from the scene so far */
+    readonly bufferedFrames: number;
+    /** null until the scene's stream completes (never, for infinite scenes) */
+    readonly totalFrames: number | null;
+    /** 0..1 — against totalFrames when known, else the buffered edge */
+    readonly progress: number;
+    readonly playing: boolean;
+    readonly loop: boolean;
+    readonly frameRate: number;
+    readonly play: () => void;
+    readonly pause: () => void;
+    readonly toggle: () => void;
+    readonly seek: (frame: number) => void;
+    readonly setLoop: (loop: boolean) => void;
+}
+/**
+ * Prepare a scene for playback: pull frames from the scene's stream with a
+ * read-ahead buffer and play them back on a rAF clock. Playback starts as
+ * soon as the first frame is buffered, so long and infinite scenes play
+ * without waiting for completion. Played frames are retained, so backward
+ * seeking is free; forward seeking clamps to the buffered edge.
+ */
+export declare const usePlayer: (scene: AnyScene, options?: UsePlayerOptions) => Player;

package/dist/usePlayer.js

@@ -0,0 +1,218 @@
+import * as Effect from "effect/Effect";
+import * as Pull from "effect/Pull";
+import * as Stream from "effect/Stream";
+import { Fonts, Scene } from "effect-motion";
+import { useCallback, useEffect, useRef, useState } from "react";
+/**
+ * Prepare a scene for playback: pull frames from the scene's stream with a
+ * read-ahead buffer and play them back on a rAF clock. Playback starts as
+ * soon as the first frame is buffered, so long and infinite scenes play
+ * without waiting for completion. Played frames are retained, so backward
+ * seeking is free; forward seeking clamps to the buffered edge.
+ */
+export const usePlayer = (scene, options = {}) => {
+    const { seed, frameRate = 60, width, height, autoPlay = false } = options;
+    // ponytail: the buffer is append-only and unbounded — infinite scenes
+    // grow it forever; swap in a ring buffer with a re-run-from-0 story if
+    // memory ever matters. buffer[i] never changes once present, so reading
+    // it during render is safe.
+    const bufferRef = useRef([]);
+    const [bufferedFrames, setBufferedFrames] = useState(0);
+    const [totalFrames, setTotalFrames] = useState(null);
+    const [error, setError] = useState(null);
+    const [frame, setFrame] = useState(0);
+    const [playing, setPlaying] = useState(false);
+    const [loop, setLoop] = useState(false);
+    const [fontsReady, setFontsReady] = useState(false);
+    // font preload: load the scene's declared url fonts (Fonts annotation)
+    // alongside initial buffering. Fonts cannot affect frame data, so this
+    // only gates `status` — a failed load warns and proceeds with the
+    // browser's normal fallback.
+    useEffect(() => {
+        const entries = Fonts.get(scene).filter((f) => f.src.url !== undefined);
+        if (entries.length === 0 ||
+            typeof FontFace === "undefined" ||
+            typeof document === "undefined" ||
+            document.fonts === undefined) {
+            setFontsReady(true);
+            return;
+        }
+        setFontsReady(false);
+        let cancelled = false;
+        const loads = entries.map((f) => {
+            const face = new FontFace(f.family, `url(${f.src.url})`, {
+                ...(f.weight !== undefined && { weight: String(f.weight) }),
+                ...(f.style !== undefined && { style: f.style }),
+            });
+            document.fonts.add(face);
+            return face.load().then(undefined, (err) => {
+                console.warn(`effect-motion: font "${f.family}" failed to load`, err);
+            });
+        });
+        Promise.all(loads).then(() => {
+            if (!cancelled) {
+                setFontsReady(true);
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [scene]);
+    // latest-value refs keep the fill loop and the rAF clock out of effect
+    // deps: neither should restart on every frame or buffer growth
+    const autoPlayRef = useRef(autoPlay);
+    autoPlayRef.current = autoPlay;
+    const frameRef = useRef(frame);
+    frameRef.current = frame;
+    const totalRef = useRef(totalFrames);
+    totalRef.current = totalFrames;
+    const loopRef = useRef(loop);
+    loopRef.current = loop;
+    // fill loop: pull frames ahead of the playhead until the stream ends
+    useEffect(() => {
+        const controller = new AbortController();
+        bufferRef.current = [];
+        frameRef.current = 0;
+        setBufferedFrames(0);
+        setTotalFrames(null);
+        setError(null);
+        setFrame(0);
+        setPlaying(false);
+        const readAhead = 2 * frameRate;
+        const frames = Scene.stream(scene, {
+            frameRate,
+            ...(seed !== undefined && { seed }),
+            ...(width !== undefined && { width }),
+            ...(height !== undefined && { height }),
+        });
+        const fill = Effect.gen(function* () {
+            const pull = yield* Stream.toPull(frames);
+            let first = true;
+            while (true) {
+                if (bufferRef.current.length - frameRef.current >= readAhead) {
+                    // ponytail: 50ms poll instead of demand signalling — the
+                    // condition changes at most once per played frame; wire a
+                    // real latch if the wakeups ever show up in a profile
+                    yield* Effect.sleep(50);
+                    continue;
+                }
+                const chunk = yield* pull;
+                bufferRef.current.push(...chunk);
+                setBufferedFrames(bufferRef.current.length);
+                if (first) {
+                    first = false;
+                    if (autoPlayRef.current) {
+                        setPlaying(true);
+                    }
+                }
+            }
+        }).pipe(
+        // the pull signals stream end as a Done failure: the scene is finite
+        Pull.catchDone(() => Effect.sync(() => setTotalFrames(bufferRef.current.length))), Effect.scoped);
+        Effect.runPromise(fill, { signal: controller.signal }).then(undefined, (err) => {
+            // aborted means unmount/re-run: no state updates after that
+            if (!controller.signal.aborted) {
+                setError(err);
+            }
+        });
+        return () => controller.abort();
+    }, [scene, seed, frameRate, width, height]);
+    // playback clock: advance the index at frameRate while playing, clamped
+    // to the buffered edge — playing at the live edge waits for frames
+    useEffect(() => {
+        if (!playing) {
+            return;
+        }
+        const frameMs = 1000 / frameRate;
+        let raf = 0;
+        let last = null;
+        let acc = 0;
+        const tick = (now) => {
+            if (last !== null) {
+                acc += now - last;
+                const advance = Math.floor(acc / frameMs);
+                if (advance > 0) {
+                    acc -= advance * frameMs;
+                    setFrame((f) => {
+                        const buffered = bufferRef.current.length;
+                        if (buffered === 0) {
+                            return f;
+                        }
+                        let next = f + advance;
+                        const total = totalRef.current;
+                        if (total !== null && loopRef.current && next > total - 1) {
+                            next = next % total;
+                        }
+                        return Math.min(next, buffered - 1);
+                    });
+                }
+            }
+            last = now;
+            raf = requestAnimationFrame(tick);
+        };
+        raf = requestAnimationFrame(tick);
+        return () => cancelAnimationFrame(raf);
+    }, [playing, frameRate]);
+    // auto-pause on the last frame of a completed stream (loop wraps instead)
+    useEffect(() => {
+        if (playing && !loop && totalFrames !== null && frame >= totalFrames - 1) {
+            setPlaying(false);
+        }
+    }, [playing, loop, totalFrames, frame]);
+    const play = useCallback(() => {
+        if (bufferRef.current.length === 0) {
+            return;
+        }
+        // replay: sitting on the last frame of a finished scene means start over
+        setFrame((f) => {
+            const total = totalRef.current;
+            return total !== null && f >= total - 1 ? 0 : f;
+        });
+        setPlaying(true);
+    }, []);
+    const pause = useCallback(() => {
+        setPlaying(false);
+    }, []);
+    const toggle = useCallback(() => {
+        if (playing) {
+            pause();
+        }
+        else {
+            play();
+        }
+    }, [playing, play, pause]);
+    const seek = useCallback((target) => {
+        const buffered = bufferRef.current.length;
+        if (buffered === 0) {
+            return;
+        }
+        setFrame(Math.min(Math.max(0, Math.floor(target)), buffered - 1));
+    }, []);
+    const status = error !== null
+        ? "error"
+        : bufferedFrames > 0 && fontsReady
+            ? "ready"
+            : "loading";
+    const denominator = (totalFrames ?? bufferedFrames) - 1;
+    return {
+        status,
+        error,
+        currentFrame: bufferRef.current[frame] ?? null,
+        frame,
+        bufferedFrames,
+        totalFrames,
+        progress: denominator > 0
+            ? Math.min(frame / denominator, 1)
+            : totalFrames !== null
+                ? 1
+                : 0,
+        playing,
+        loop,
+        frameRate,
+        play,
+        pause,
+        toggle,
+        seek,
+        setLoop,
+    };
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@effect-motion/react",
+  "version": "0.2.0",
+  "description": "React bindings for effect-motion: usePlayer hook and Player component",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/julia-script/effect-motion.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://github.com/julia-script/effect-motion#readme",
+  "bugs": "https://github.com/julia-script/effect-motion/issues",
+  "keywords": [
+    "effect",
+    "motion",
+    "react",
+    "animation",
+    "motion-graphics"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "effect-motion": "^0.2.0"
+  },
+  "peerDependencies": {
+    "effect": ">=4.0.0-beta.94",
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "effect": "4.0.0-beta.94",
+    "happy-dom": "^20.10.6",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
+    "test": "vitest run",
+    "check": "tsc --noEmit"
+  }
+}