@effect-motion/react 0.4.0 → 0.6.0

package/README.md

@@ -1,31 +1,43 @@
 # @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.
+React bindings for [effect-motion](https://www.npmjs.com/package/effect-motion): a `<Player>` component 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.
+Frames stream in as the scene runs rather than being rendered up front, so playback starts before the whole scene is computed. By default a finite scene keeps every frame it has pulled, which makes seeking backwards free; an endless scene keeps a bounded window instead.
 
 ## Install
 
 `effect` and `effect-motion` are peer dependencies — install them alongside:
 
 ```bash
-pnpm add @effect-motion/react effect-motion effect
+bun 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:
+`<Player>` runs the scene and gives you transport controls — play/pause, a scrubbable progress bar, and a repeat toggle:
 
 ```tsx
 import { Player } from "@effect-motion/react";
 import { scene } from "./my-scene";
 
 export function App() {
-	return <Player scene={scene} width={500} height={300} autoPlay />;
+	return <Player scene={scene} autoPlay />;
 }
 ```
 
-Prefer your own UI? `usePlayer(scene, options)` exposes the same state and controls (`status`, `frame`, `progress`, `play`, `pause`, `seek`, …) without any chrome.
+The player's size comes from its container — the canvas fills the available width at the scene's aspect ratio, and the scene's own resolution is set when you write it (`Scene.make(…, { width, height })`).
+
+For a scene that never ends, pass `isInfinite` so memory stays bounded and the scrubber (which has no meaning without an end) is hidden:
+
+```tsx
+<Player scene={ambientScene} isInfinite autoPlay />
+```
+
+If the scene uses custom fonts or images, pass their loaders as `renderLayers`. It is required — and checked at compile time — whenever the scene declares resources:
+
+```tsx
+<Player scene={scene} renderLayers={Font.layer(Inter, bytes)} />
+```
 
 ## Documentation
 

package/dist/Player.d.ts

@@ -1,14 +1,155 @@
-import type * as Scope from "effect/Scope";
+import * as Layer from "effect/Layer";
 import type * as Runner from "effect-motion/Runner";
 import * as Scene from "effect-motion/Scene";
-export type PlayerProps = {
+/**
+ * Props for {@link Player}.
+ *
+ * @typeParam S - The scene's type, which decides whether `renderLayers` is
+ *   required.
+ *
+ * @remarks
+ * Only `scene` is required — and `renderLayers`, if the scene declares
+ * resources. Everything else has a working default.
+ */
+export type PlayerProps<S extends Scene.AnyScene = Scene.AnyScene> = {
+    /**
+     * How many frames to buffer ahead before playing.
+     *
+     * @remarks
+     * The default buffers the WHOLE scene, which is what makes the total
+     * duration and a complete progress bar available immediately. Lower it to
+     * start playing sooner on a long scene: the progress bar then tracks how
+     * much is buffered so far, and the total time stays hidden until the
+     * scene has been pulled to its end.
+     *
+     * An infinite scene can never be fully buffered, so it falls back to 60
+     * frames.
+     *
+     * @defaultValue `Infinity` (60 when `isInfinite`)
+     */
     prebufferedFrames?: number;
+    /**
+     * Start playing on mount instead of waiting for the play button.
+     *
+     * @defaultValue `false`
+     */
     autoPlay?: boolean;
+    /**
+     * Frames per second, for both the scene and the playback clock.
+     *
+     * @remarks
+     * Overridden by `settings.frameRate` when both are given, so the two can
+     * never disagree.
+     *
+     * @defaultValue `60`
+     */
     fps?: number;
+    /**
+     * Declare that the scene never ends.
+     *
+     * @remarks
+     * Set this for a scene built to run forever — an ambient loop, a
+     * `Schedule.forever` background. It changes three things: frames are
+     * buffered in a bounded window rather than kept forever, only a prefix is
+     * prebuffered, and the scrubber and repeat toggle are hidden, since
+     * neither means anything without an end. Play and pause remain.
+     *
+     * @defaultValue `false`
+     */
     isInfinite?: boolean;
+    /**
+     * Whether repeat starts switched on.
+     *
+     * @remarks
+     * An INITIAL value, not a controlled prop — the player owns repeat state
+     * once mounted, because the user can toggle it with the repeat button.
+     * Ignored for an infinite scene.
+     *
+     * @defaultValue `false`
+     */
     defaultRepeatMode?: boolean;
+    /**
+     * How many frames of scene DATA to keep in memory.
+     *
+     * @remarks
+     * Frame data, not rendered pixels. A finite scene keeps everything so
+     * seeking anywhere works; an infinite scene keeps a window, since
+     * retaining every frame of an endless scene would grow without bound.
+     *
+     * Seeking before the retained window clamps to its oldest frame — a scene
+     * is a forward-only stream, so frames that fell out cannot be recomputed.
+     * Raise this if deep backward scrubbing on a long scene matters.
+     *
+     * @defaultValue `Infinity` for a finite scene; `1800` (~30s at 60fps) when
+     *   `isInfinite`
+     */
     bufferCapacity?: number;
+    /**
+     * Playback settings passed to the scene run — `seed`, `maxFrames`, and
+     * `frameRate`.
+     *
+     * @remarks
+     * Resolution and background are NOT here: those belong to the scene's own
+     * composition config, fixed when it was made. A `frameRate` given here
+     * wins over the `fps` prop.
+     */
     settings?: Partial<Runner.Settings>;
-    scene: Scene.Scene<never, Runner.Runner | Scope.Scope>;
-};
-export declare const Player: ({ scene, fps: fpsProp, prebufferedFrames, autoPlay, isInfinite, defaultRepeatMode, bufferCapacity, settings, }: PlayerProps) => import("react").JSX.Element;
+    /** The scene to play. */
+    scene: S;
+} & (Scene.Resources<S> extends never ? {
+    /**
+     * Not accepted: this scene declares no resources, so passing
+     * loaders is a compile error.
+     */
+    renderLayers?: never;
+} : {
+    /**
+     * Loaders for the fonts and images the scene uses.
+     *
+     * @remarks
+     * REQUIRED when the scene declares resources, and it must cover
+     * every one of them — the types will not let you mount a player
+     * that is missing a loader, so a missing font is a compile error
+     * rather than blank text at runtime. Combine several with
+     * `Layer.mergeAll(...)`.
+     *
+     * Loads run once, eagerly, when the player mounts. A failed load
+     * shows in the player's error panel.
+     */
+    renderLayers: Layer.Layer<Scene.Resources<S>, unknown, never>;
+});
+/**
+ * A video-style player for an effect-motion scene.
+ *
+ * @remarks
+ * Self-contained: a canvas plus play/pause, a scrubber with buffered-range
+ * indicator, a time readout, and a repeat toggle. Controls fade out during
+ * playback and return on hover. There is no stylesheet to import — the skin
+ * is inline styles and inline SVG — and no way to restyle it short of
+ * wrapping it.
+ *
+ * The canvas is `width: 100%` with automatic height, so the player fills its
+ * container at the scene's aspect ratio. Size it by sizing the parent.
+ *
+ * Frames stream in rather than being pre-rendered, so playback starts before
+ * the whole scene is computed. Playback keeps real time: if a frame renders
+ * slowly the player drops intermediate frames rather than falling behind.
+ *
+ * Each player owns its own GPU renderer and scene run, released on unmount.
+ *
+ * Failures — no WebGPU, a font that would not load, a render error — are
+ * shown in the player's own frame as an alert panel, not just logged to the
+ * console.
+ *
+ * @example
+ * ```tsx
+ * <Player scene={scene} autoPlay />
+ * ```
+ *
+ * @example
+ * An endless scene: bounded memory, and no scrubber or repeat button.
+ * ```tsx
+ * <Player scene={ambientScene} isInfinite autoPlay />
+ * ```
+ */
+export declare const Player: <S extends Scene.AnyScene>({ scene, fps: fpsProp, prebufferedFrames, autoPlay, isInfinite, defaultRepeatMode, bufferCapacity, settings, renderLayers, }: PlayerProps<S>) => import("react").JSX.Element;

package/dist/Player.js

@@ -1,43 +1,68 @@
 "use client";
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import * as Engine from "@effect-motion/thorvg/Engine";
-import * as Session from "@effect-motion/thorvg/Session";
+import * as FrameRenderer from "@effect-motion/renderer/Renderer";
 import { Cause, Context, Data, Effect, ManagedRuntime, Schedule, Semaphore, } from "effect";
 import * as Layer from "effect/Layer";
-import * as CanvasExporter from "effect-motion/CanvasExporter";
-import * as Fonts from "effect-motion/Fonts";
-import * as Images from "effect-motion/Images";
-import * as Renderer from "effect-motion/Renderer";
 import * as Scene from "effect-motion/Scene";
 import * as Time from "effect-motion/Time";
 import { useEffect, useEffectEvent, useRef, useState, } from "react";
-const thorLayer = Engine.browserLayer("https://unpkg.com/@thorvg/webcanvas@1.0.8/dist/thorvg.wasm");
+/**
+ * Anything that went wrong inside the player: acquiring the renderer, a
+ * resource load, pulling a frame, or rendering one.
+ *
+ * @remarks
+ * Internal. The first failure is captured and shown in the player's error
+ * panel; `message` says which stage failed and `cause` carries the original.
+ */
 class PlayerError extends Data.TaggedError("PlayerError") {
     static of(message) {
         return (cause) => new PlayerError({ message, cause });
     }
 }
 /**
- * Softened device-pixel-ratio, thorvg.web's formula: interpolate 75% of the
- * way from 1 to the native dpr — visually indistinguishable from full dpr at
- * a fraction of the rasterized pixels. Read per render call so moving the
- * window across monitors picks up the new ratio.
+ * The viewport for a `width` × `height` frame shown in `canvas`: logical size
+ * is the frame's, pixel density follows how big the canvas is displayed.
+ *
+ * @remarks
+ * Scene coordinates, camera and HUD stay in frame units; only the pixel ratio
+ * changes, set so the backing store matches the displayed CSS size at device
+ * density — a 1920-wide scene shown 700 CSS px wide on a 2× display renders
+ * 1400 px wide, not 3840. Capped at the device ratio, so never more detail
+ * than the display can show. Before layout (width 0) it falls back to the
+ * device ratio.
+ *
+ * `pw`/`ph` are the backing-store size three will set (it floors), used to
+ * skip resizes that would not change a pixel.
  */
-const calculateDpr = () => typeof window === "undefined" ? 1 : 1 + (window.devicePixelRatio - 1) * 0.75;
-// const layer = Layer.con
-// const runtime = ManagedRuntime.make()
+const viewportFor = (canvas, width, height) => {
+    const dpr = window.devicePixelRatio;
+    const displayed = canvas.clientWidth;
+    const ratio = displayed > 0 ? Math.min(dpr, (displayed * dpr) / width) : dpr;
+    return {
+        width,
+        height,
+        ratio,
+        pw: Math.floor(width * ratio),
+        ph: Math.floor(height * ratio),
+    };
+};
 const PlayerScene = Context.Service("PlayerScene");
 /**
- * Frame-data buffer keyed by absolute frame index, retaining at most
- * `capacity` of the most-recently-pulled frames. Frames are pulled from the
- * scene monotonically forward (never re-derivable at a random index — the
- * scene is a forward-only stream), so the ring drops the oldest frames once
- * the window is full. A finite scene that fits within `capacity` behaves like
- * a plain array (nothing is ever evicted). Seeking below the retained window
- * clamps to `oldest` — the earliest frame still in memory.
+ * The frame buffer: keeps the most recent `capacity` frames, keyed by
+ * absolute frame index.
+ *
+ * @remarks
+ * A scene is a forward-only stream — frame 400 can only be reached by
+ * pulling frames 0 through 399 — so a frame that has been evicted cannot be
+ * recomputed on demand. That is why seeking below the retained window clamps
+ * to {@link FrameRing.oldest} rather than replaying.
+ *
+ * With an infinite `capacity` nothing is ever evicted and this behaves like
+ * a plain array, which is the finite-scene default.
  */
 class FrameRing {
     capacity;
+    /** slots indexed by `absoluteIndex % capacity`, or densely when unbounded */
     // ponytail: fixed-capacity ring keyed by absolute index. capacity=Infinity
     // keeps everything (finite scenes that fit); a finite cap bounds memory for
     // long/infinite scenes at the cost of losing far-back seek. Bump the cap if
@@ -49,7 +74,7 @@ class FrameRing {
         this.capacity = capacity;
         this.slots = Number.isFinite(capacity) ? new Array(capacity) : [];
     }
-    /** oldest absolute index still retained */
+    /** The earliest frame index still in memory — the floor for any seek. */
     get oldest() {
         return Number.isFinite(this.capacity)
             ? Math.max(0, this.pulled - this.capacity)
@@ -66,7 +91,7 @@ class FrameRing {
             ? this.slots[index % this.capacity]
             : this.slots[index];
     }
-    /** append the next frame at the edge, evicting the oldest if full */
+    /** Append the next frame, evicting the oldest once the window is full. */
     push(frame) {
         if (Number.isFinite(this.capacity)) {
             this.slots[this.pulled % this.capacity] = frame;
@@ -77,7 +102,25 @@ class FrameRing {
         this.pulled++;
     }
 }
-const useScene = (scene, options) => {
+/**
+ * The player's engine: runs the scene, buffers frames, drives the playback
+ * clock, and renders to a canvas.
+ *
+ * @remarks
+ * Internal — {@link Player} is the public surface. Returns the canvas ref,
+ * playback state, and the controls the chrome is wired to.
+ *
+ * Two things worth knowing when reading this. All the Effect work runs in
+ * ONE `ManagedRuntime` created per mount and disposed on unmount, which is
+ * what releases the GPU renderer and interrupts in-flight fibers. And the
+ * playback clock is wall-clock on purpose: it drives real-time playback
+ * speed, not scene time, so the determinism rule banning clocks inside
+ * scenes does not apply to it.
+ */
+const useScene = (sceneProp, options) => {
+    // internal seam mirroring makeScene's: the props boundary guarantees
+    // renderLayers covers Scene.Resources<S>, so frames render as loader-free
+    const scene = sceneProp;
     // loop is read live from optsRef inside the play loop, not destructured here
     const { fps, prebufferedFrames, autoPlay, isInfinite, settings } = options;
     const canvasRef = useRef(null);
@@ -89,21 +132,41 @@ const useScene = (scene, options) => {
     // repeat mode is player state seeded from the prop (an initial value); the
     // user toggles it live via the repeat button
     const [loop, setLoop] = useState(options.loop);
+    // first real failure (engine acquisition, loader load at runtime build,
+    // render) — rendered visibly by the Player, never only logged
+    const [error, setError] = useState(null);
     // latest option values (incl. live loop), read inside the long-lived Effect
     // service without re-creating the runtime (which would re-run the scene)
     const optsRef = useRef({ ...options, loop });
     optsRef.current = { ...options, loop };
-    // One runtime per mount, DISPOSED on unmount: disposal closes the session
-    // (canvas deleted, fonts released — refcounted, so siblings keep theirs)
-    // and releases the engine (a browser no-op: the wasm module is a page
-    // singleton, design D2; two players share one module via the idempotent
-    // acquire). Held in a ref, not state, so a strict-mode remount can
-    // recreate it after the first cleanup disposed it.
+    // One runtime per mount, DISPOSED on unmount: disposal closes the layer
+    // scope, which disposes the per-player three renderer (GPU resources,
+    // retained objects) — nothing is shared across players. Held in a ref,
+    // not state, so a strict-mode remount can recreate it after the first
+    // cleanup disposed it.
     const makeRuntime = () => ManagedRuntime.make(Layer.effectContext(Effect.gen(function* () {
         const runningScene = yield* Scene.run(scene, {
             ...settings,
             frameRate: fps,
         });
+        // the per-player renderer, bound to this mount's canvas and
+        // released with the runtime; init (incl. WebGPU device) happens
+        // here, so an acquisition failure surfaces as the error state
+        const canvas = canvasRef.current;
+        if (canvas === null) {
+            return yield* Effect.fail(PlayerError.of("Player canvas is not mounted")(null));
+        }
+        const sink = yield* FrameRenderer.make({
+            canvas,
+            width: 1,
+            height: 1,
+        }).pipe(Effect.mapError(PlayerError.of("Error acquiring the renderer")));
+        // viewport tracking: sized from frame metadata + displayed size
+        // on first render, then on every resize / DPR change
+        let sized = { width: 0, height: 0, ratio: 0, pw: 0, ph: 0 };
+        // pipeline pre-warm happens once, on the first rendered frame,
+        // before playback reveals motion — no first-frame compile jank
+        let prewarmed = false;
         let currentFrame = 0;
         let isPlaying = false;
         // total frame count once the stream ends; null while unknown
@@ -155,7 +218,8 @@ const useScene = (scene, options) => {
             };
         }).pipe(Effect.mapError(PlayerError.of("Error getting frame buffer")));
         const renderSemaphore = yield* Semaphore.make(1);
-        const render = (frameIndex) => renderSemaphore.withPermitsIfAvailable(1)(Effect.gen(function* () {
+        // unlocked: callers hold renderSemaphore
+        const renderFrame = (frameIndex) => Effect.gen(function* () {
             if (!canvasRef.current) {
                 return;
             }
@@ -167,11 +231,48 @@ const useScene = (scene, options) => {
             // past the buffered edge resolves to the edge (clamped in
             // loadFrameBuffer), and the playhead must reflect what's shown
             updateCurrentFrame(framebuffer.index);
-            const renderBuffer = yield* Renderer.render(framebuffer.frame, {
-                dpr: calculateDpr(),
-            });
-            yield* CanvasExporter.toCanvas(renderBuffer, canvasRef.current);
-        }).pipe(Effect.mapError(PlayerError.of("Error exporting canvas"))));
+            const frame = framebuffer.frame;
+            const next = viewportFor(canvas, frame.width, frame.height);
+            if (next.width !== sized.width ||
+                next.height !== sized.height ||
+                next.pw !== sized.pw ||
+                next.ph !== sized.ph) {
+                sized = next;
+                FrameRenderer.setViewport(sink, next.width, next.height, next.ratio);
+            }
+            // font loaders resolve from this runtime's context (the
+            // renderLayers merge); missing loaders defect loudly
+            yield* FrameRenderer.resolveResources(sink, frame);
+            yield* FrameRenderer.syncFrame(sink, frame);
+            if (!prewarmed) {
+                prewarmed = true;
+                yield* FrameRenderer.prewarm(sink);
+            }
+            yield* FrameRenderer.render(sink);
+        }).pipe(Effect.mapError(PlayerError.of("Error rendering frame")));
+        const render = (frameIndex) => renderSemaphore.withPermitsIfAvailable(1)(renderFrame(frameIndex));
+        // resize / DPR change: resizing clears the canvas, so re-render
+        // the shown frame (a paused player would otherwise stay blank or
+        // scaled). Waits for the permit rather than dropping, so the
+        // final size of a drag is never lost; at most one waits.
+        let redrawQueued = false;
+        const redraw = Effect.suspend(() => {
+            if (redrawQueued) {
+                return Effect.void;
+            }
+            redrawQueued = true;
+            return renderSemaphore.withPermits(1)(Effect.suspend(() => {
+                redrawQueued = false;
+                // unsized: the first render has not run yet and will size
+                if (sized.width === 0) {
+                    return Effect.void;
+                }
+                const next = viewportFor(canvas, sized.width, sized.height);
+                return next.pw === sized.pw && next.ph === sized.ph
+                    ? Effect.void
+                    : renderFrame(currentFrame);
+            }));
+        });
         const play = Effect.suspend(() => {
             if (isPlaying)
                 return Effect.void;
@@ -251,21 +352,16 @@ const useScene = (scene, options) => {
         return Context.make(PlayerScene, {
             play,
             pause,
+            redraw,
             frameIndex: Effect.sync(() => currentFrame),
             render,
             load: (frameIndex) => loadFrameBuffer(frameIndex),
         });
     })).pipe(
-    // per-mount session: the canvas (sized by the render path) plus the
-    // scene's declared fonts and images, held until the runtime is
-    // disposed. Session.make awaits font/image settlement, so nothing
-    // renders (and the player can't report ready) before assets settle.
-    Layer.provideMerge(Session.layer({
-        width: 1,
-        height: 1,
-        fonts: Fonts.urlMap(scene),
-        images: Images.urlMap(scene),
-    })), Layer.provideMerge(thorLayer)));
+    // caller-provided loader layers: every provided load runs here, at
+    // runtime construction (eager, preload-all-provided) — a failed
+    // load fails the runtime build and surfaces as the error state
+    Layer.provideMerge(options.renderLayers ?? Layer.empty)));
     const runtimeRef = useRef(null);
     const getRuntime = () => {
         if (runtimeRef.current === null) {
@@ -303,6 +399,10 @@ const useScene = (scene, options) => {
                 return;
             }
             console.error("effect-motion player:", String(exit.cause), exit.cause);
+            // surface the first failure visibly (loader/engine failures at
+            // runtime construction land here too — the runtime build is lazy,
+            // forced by the first render/load call)
+            setError((current) => current ?? exit.cause);
         });
     };
     const render = useEffectEvent((frameIndex) => runReported(Effect.service(PlayerScene).pipe(Effect.flatMap((e) => e.render(frameIndex)), Effect.scoped)));
@@ -319,41 +419,117 @@ const useScene = (scene, options) => {
             play();
         }
     }, []);
+    const redraw = useEffectEvent(() => runReported(Effect.service(PlayerScene).pipe(Effect.flatMap((e) => e.redraw), Effect.scoped)));
+    // keep the backing store at displayed size × device pixel ratio: the
+    // observer covers container resize and fullscreen; the resolution query
+    // covers DPR changes that leave the CSS size alone (monitor move, zoom)
+    useEffect(() => {
+        const canvas = canvasRef.current;
+        if (canvas === null) {
+            return;
+        }
+        const observer = new ResizeObserver(() => redraw());
+        observer.observe(canvas);
+        let media = null;
+        const onDprChange = () => {
+            media?.removeEventListener("change", onDprChange);
+            media = window.matchMedia(`(resolution: ${window.devicePixelRatio}dppx)`);
+            media.addEventListener("change", onDprChange);
+            redraw();
+        };
+        onDprChange();
+        return () => {
+            observer.disconnect();
+            media?.removeEventListener("change", onDprChange);
+        };
+    }, []);
     // scene time in seconds of the current frame, and total when known
     const currentTime = Time.frameToMillis(currentFrame, fps) / 1000;
     const totalTime = totalFrames !== null
         ? Time.frameToMillis(totalFrames - 1, fps) / 1000
         : null;
     return {
+        /** Attach to the canvas the player draws into. */
         ref: canvasRef,
+        /** The frame currently shown. */
         currentFrame,
+        /** How many frames have been pulled from the scene so far. */
         bufferedFrames,
+        /** Total frames, or `null` until the scene has been pulled to its end. */
         totalFrames,
+        /** Scene time of the current frame, in seconds. */
         currentTime,
+        /** Total duration in seconds, or `null` while unknown. */
         totalTime,
         play,
         pause,
+        /** Jump to a frame; clamps to the buffered window. */
         seek: render,
         isPlaying,
+        /** Whether repeat is on (player-owned after mount). */
         loop,
         setLoop,
+        /** Buffer ahead to a frame without displaying it. */
         load,
+        /** The first failure, or `null`. Rendered as the error panel. */
+        error,
     };
 };
-// keep-everything cap for an infinite scene: enough for ~30s of backward seek
-// at 60fps, ~1MB of frame data. Bump via bufferCapacity for deeper scrubbing.
+/**
+ * Frames retained for an infinite scene — about 30 seconds of backward seek
+ * at 60fps, roughly 1MB of frame data.
+ *
+ * @remarks
+ * An endless scene cannot keep every frame, so this bounds the window.
+ * Callers who need deeper scrubbing raise it with `bufferCapacity`.
+ */
 const INFINITE_BUFFER_CAP = 1800;
+/**
+ * A video-style player for an effect-motion scene.
+ *
+ * @remarks
+ * Self-contained: a canvas plus play/pause, a scrubber with buffered-range
+ * indicator, a time readout, and a repeat toggle. Controls fade out during
+ * playback and return on hover. There is no stylesheet to import — the skin
+ * is inline styles and inline SVG — and no way to restyle it short of
+ * wrapping it.
+ *
+ * The canvas is `width: 100%` with automatic height, so the player fills its
+ * container at the scene's aspect ratio. Size it by sizing the parent.
+ *
+ * Frames stream in rather than being pre-rendered, so playback starts before
+ * the whole scene is computed. Playback keeps real time: if a frame renders
+ * slowly the player drops intermediate frames rather than falling behind.
+ *
+ * Each player owns its own GPU renderer and scene run, released on unmount.
+ *
+ * Failures — no WebGPU, a font that would not load, a render error — are
+ * shown in the player's own frame as an alert panel, not just logged to the
+ * console.
+ *
+ * @example
+ * ```tsx
+ * <Player scene={scene} autoPlay />
+ * ```
+ *
+ * @example
+ * An endless scene: bounded memory, and no scrubber or repeat button.
+ * ```tsx
+ * <Player scene={ambientScene} isInfinite autoPlay />
+ * ```
+ */
 export const Player = ({ scene, fps: fpsProp = 60, 
 // default: prebuffer everything (Infinity) so the total time / progress bar
 // are known up front; an infinite scene falls back to a finite window below.
 prebufferedFrames = Number.POSITIVE_INFINITY, autoPlay = false, isInfinite = false, 
 // initial repeat mode; the player owns it after mount (toggle button)
-defaultRepeatMode = false, bufferCapacity, settings, }) => {
+defaultRepeatMode = false, bufferCapacity, settings, renderLayers, }) => {
     // one effective rate for both the scene run and the playback clock
     const fps = settings?.frameRate ?? fpsProp;
-    const { ref, currentFrame, bufferedFrames, totalFrames, currentTime, totalTime, play, pause, seek, isPlaying, loop, setLoop, } = useScene(scene, {
+    const { ref, currentFrame, bufferedFrames, totalFrames, currentTime, totalTime, play, pause, seek, isPlaying, loop, setLoop, error, } = useScene(scene, {
         fps,
         settings,
+        renderLayers: renderLayers,
         // an infinite scene can never buffer to the end — window it (60 frames
         // if the caller left prebufferedFrames unbounded)
         prebufferedFrames: isInfinite && !Number.isFinite(prebufferedFrames)
@@ -393,6 +569,11 @@ defaultRepeatMode = false, bufferCapacity, settings, }) => {
     const chipFrame = scrubbing ? currentFrame : hoverFrame;
     const chipFrac = denominator > 0 ? chipFrame / denominator : 0;
     const barActive = barHover || scrubbing;
+    // a failed engine acquisition, loader load, or render: show the failure
+    // in the player's frame instead of a black box + console line
+    if (error !== null) {
+        return (_jsx("div", { style: S.player, children: _jsxs("div", { style: S.errorPanel, role: "alert", children: [_jsx("strong", { children: "effect-motion player failed" }), _jsx("pre", { style: S.errorDetail, children: String(error) })] }) }));
+    }
     return (_jsxs("div", { style: S.player, onMouseEnter: () => setHovering(true), onMouseLeave: () => setHovering(false), children: [_jsx("canvas", { ref: ref, style: S.canvas, onClick: () => (isPlaying ? pause() : play()) }), !isPlaying && (_jsx("button", { type: "button", "aria-label": "Play", style: {
                     ...S.bigPlay,
                     background: bigPlayHover ? ACCENT : "rgba(0, 0, 0, 0.65)",
@@ -431,10 +612,13 @@ defaultRepeatMode = false, bufferCapacity, settings, }) => {
                         }, onClick: () => setLoop((v) => !v), children: _jsx(RepeatIcon, {}) }))] })] }));
 };
 // ---------------------------------------------------------------------------
-// chrome: Vimeo-style player skin. Self-contained by design — inline style
-// objects and inline SVG icons only, no stylesheet/tailwind/image deps.
+// chrome: the player skin. Self-contained by design — inline style objects
+// and inline SVG icons only, so the package ships no stylesheet and pulls in
+// no CSS framework or image assets. The tradeoff is that the look is fixed:
+// restyling means wrapping the player, not overriding classes.
 // ---------------------------------------------------------------------------
 const ACCENT = "#00adef"; // Vimeo blue
+/** Seconds as `m:ss`, for the time readout and the scrubber chip. */
 const formatTime = (seconds) => {
     const s = Math.max(0, Math.floor(seconds));
     return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, "0")}`;
@@ -455,6 +639,21 @@ const S = {
         WebkitUserSelect: "none",
         fontFamily: "system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif",
     },
+    errorPanel: {
+        padding: "24px 20px",
+        color: "#ffb4ab",
+        background: "#1a1113",
+        fontSize: 13,
+        lineHeight: 1.5,
+    },
+    errorDetail: {
+        margin: "8px 0 0",
+        whiteSpace: "pre-wrap",
+        wordBreak: "break-word",
+        fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
+        fontSize: 12,
+        opacity: 0.85,
+    },
     canvas: {
         display: "block",
         width: "100%",

package/dist/index.d.ts

@@ -1 +1,45 @@
+/**
+ * `@effect-motion/react` — play effect-motion scenes in the browser.
+ *
+ * @remarks
+ * One component: {@link Player}, a self-contained video-style player with
+ * play/pause, a scrubber, a time readout, and a repeat toggle. Point it at
+ * a scene and it renders.
+ *
+ * ```tsx
+ * <Player scene={scene} />
+ * ```
+ *
+ * Playback is streamed rather than pre-rendered. Frames are pulled from the
+ * scene on demand and buffered, so a long scene starts playing without
+ * being computed to the end first, and an endless one plays without
+ * accumulating forever.
+ *
+ * Everything is per-mount: each `Player` owns its own GPU renderer and
+ * scene run, disposed on unmount. Several on a page do not interfere, and
+ * navigating away releases the GPU resources.
+ *
+ * The component needs a browser — it renders through WebGPU to a canvas.
+ * Under a framework that server-renders, it is already marked
+ * `"use client"`.
+ *
+ * @example
+ * A scene with a custom font. The `renderLayers` prop is REQUIRED when the
+ * scene declares resources, and the types enforce it.
+ * ```tsx
+ * import { Player } from "@effect-motion/react";
+ * import * as Font from "effect-motion/Font";
+ * import * as Resource from "effect-motion/Resource";
+ *
+ * const Inter = Font.Font("Inter");
+ *
+ * <Player
+ * 	scene={scene}
+ * 	renderLayers={Font.layer(Inter, Resource.fetchBytes("/fonts/inter.ttf"))}
+ * 	autoPlay
+ * />
+ * ```
+ *
+ * @packageDocumentation
+ */
 export { Player, type PlayerProps } from "./Player.js";

package/dist/index.js

@@ -1 +1,45 @@
+/**
+ * `@effect-motion/react` — play effect-motion scenes in the browser.
+ *
+ * @remarks
+ * One component: {@link Player}, a self-contained video-style player with
+ * play/pause, a scrubber, a time readout, and a repeat toggle. Point it at
+ * a scene and it renders.
+ *
+ * ```tsx
+ * <Player scene={scene} />
+ * ```
+ *
+ * Playback is streamed rather than pre-rendered. Frames are pulled from the
+ * scene on demand and buffered, so a long scene starts playing without
+ * being computed to the end first, and an endless one plays without
+ * accumulating forever.
+ *
+ * Everything is per-mount: each `Player` owns its own GPU renderer and
+ * scene run, disposed on unmount. Several on a page do not interfere, and
+ * navigating away releases the GPU resources.
+ *
+ * The component needs a browser — it renders through WebGPU to a canvas.
+ * Under a framework that server-renders, it is already marked
+ * `"use client"`.
+ *
+ * @example
+ * A scene with a custom font. The `renderLayers` prop is REQUIRED when the
+ * scene declares resources, and the types enforce it.
+ * ```tsx
+ * import { Player } from "@effect-motion/react";
+ * import * as Font from "effect-motion/Font";
+ * import * as Resource from "effect-motion/Resource";
+ *
+ * const Inter = Font.Font("Inter");
+ *
+ * <Player
+ * 	scene={scene}
+ * 	renderLayers={Font.layer(Inter, Resource.fetchBytes("/fonts/inter.ttf"))}
+ * 	autoPlay
+ * />
+ * ```
+ *
+ * @packageDocumentation
+ */
 export { Player } from "./Player.js";

package/package.json

@@ -1,63 +1,63 @@
 {
-  "name": "@effect-motion/react",
-  "version": "0.4.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"
-    },
-    "./*": {
-      "types": "./dist/*.d.ts",
-      "default": "./dist/*.js"
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "@effect-motion/thorvg": "^0.2.0",
-    "effect-motion": "^0.4.0"
-  },
-  "peerDependencies": {
-    "effect": ">=4.0.0-beta.98",
-    "react": ">=18"
-  },
-  "devDependencies": {
-    "@testing-library/react": "^16.3.0",
-    "@types/node": "^26.1.1",
-    "@types/react": "^19.2.0",
-    "@types/react-dom": "^19.2.0",
-    "effect": "4.0.0-beta.98",
-    "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 --passWithNoTests",
-    "check": "tsc --noEmit"
-  }
-}
+	"name": "@effect-motion/react",
+	"version": "0.6.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"
+		},
+		"./*": {
+			"types": "./dist/*.d.ts",
+			"default": "./dist/*.js"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"dev": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
+		"test": "vitest run --passWithNoTests",
+		"check": "tsc --noEmit"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@effect-motion/renderer": "workspace:^",
+		"effect-motion": "workspace:^"
+	},
+	"peerDependencies": {
+		"effect": ">=4.0.0-rc.115",
+		"react": ">=18"
+	},
+	"devDependencies": {
+		"@testing-library/react": "^16.3.0",
+		"@types/node": "^26.1.1",
+		"@types/react": "^19.2.0",
+		"@types/react-dom": "^19.2.0",
+		"effect": "4.0.0-rc.115",
+		"happy-dom": "^20.10.6",
+		"react": "^19.2.0",
+		"react-dom": "^19.2.0",
+		"typescript": "^7.0.2",
+		"vitest": "^4.1.10"
+	}
+}