@effect-motion/react 0.3.2 → 0.5.0

package/README.md

@@ -1,8 +1,8 @@
 # @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
 
@@ -14,18 +14,30 @@ 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:
+`<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,54 @@
 "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 device pixel ratio to render at — 75% of the way from 1 to the
+ * display's native ratio.
+ *
+ * @remarks
+ * Rendering at full native ratio on a high-DPI display costs several times
+ * the pixels for a difference nobody sees in motion. Softening it keeps text
+ * and edges sharp at a fraction of the fill cost.
+ *
+ * Read on every render, so dragging a window between monitors picks up the
+ * new ratio.
  */
 const calculateDpr = () => typeof window === "undefined" ? 1 : 1 + (window.devicePixelRatio - 1) * 0.75;
-// const layer = Layer.con
-// const runtime = ManagedRuntime.make()
 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 +60,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 +77,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 +88,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 +118,40 @@ 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 on first render
+        let sized = { width: 0, height: 0, dpr: 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
@@ -167,11 +215,24 @@ 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 dpr = calculateDpr();
+            if (sized.width !== frame.width ||
+                sized.height !== frame.height ||
+                sized.dpr !== dpr) {
+                sized = { width: frame.width, height: frame.height, dpr };
+                FrameRenderer.setViewport(sink, frame.width, frame.height, dpr);
+            }
+            // 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 play = Effect.suspend(() => {
             if (isPlaying)
                 return Effect.void;
@@ -256,16 +317,10 @@ const useScene = (scene, options) => {
             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 +358,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)));
@@ -325,35 +384,87 @@ const useScene = (scene, options) => {
         ? 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 +504,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 +547,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 +574,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,6 +1,6 @@
 {
   "name": "@effect-motion/react",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "React bindings for effect-motion: usePlayer hook and Player component",
   "type": "module",
   "license": "MIT",
@@ -35,8 +35,8 @@
     "access": "public"
   },
   "dependencies": {
-    "effect-motion": "^0.3.2",
-    "@effect-motion/thorvg": "^0.1.0"
+    "@effect-motion/renderer": "^0.5.0",
+    "effect-motion": "^0.5.0"
   },
   "peerDependencies": {
     "effect": ">=4.0.0-beta.98",