@glissade/react 0.10.1 → 0.11.0-pre.1

package/dist/index.d.ts

@@ -1,13 +1,50 @@
-import { ReadonlySignal, Signal } from "@glissade/core";
-import { Player } from "@glissade/player";
+import { CSSProperties } from "react";
+import { ReadonlySignal, Signal, Timeline } from "@glissade/core";
+import { LoopMode, Player } from "@glissade/player";
+import { Scene } from "@glissade/scene";
 
-//#region src/index.d.ts
+//#region src/ScenePlayer.d.ts
 
+interface ScenePlayerProps {
+  /** The scene graph to render. */
+  scene: Scene;
+  /** The timeline document driving it. */
+  timeline: Timeline;
+  /** Loop policy (forwarded to the Player). */
+  loop?: LoopMode;
+  /** Render the default controls bar (play/pause, scrubber, time readout). */
+  controls?: boolean;
+  /** Start playing on mount. */
+  autoplay?: boolean;
+  /** Fired when a play completes naturally (true) or is interrupted (false). */
+  onFinished?: (completed: boolean) => void;
+  /** Called once the underlying Player is mounted (for imperative control). */
+  onReady?: (player: Player) => void;
+  className?: string;
+  style?: CSSProperties;
+}
+declare function ScenePlayer({
+  scene,
+  timeline,
+  loop,
+  controls,
+  autoplay,
+  onFinished,
+  onReady,
+  className,
+  style
+}: ScenePlayerProps): React.ReactElement;
+//#endregion
+//#region src/index.d.ts
 /** Subscribe a component to a signal; re-renders only when the value actually changes. */
 declare function useSignalValue<T>(sig: ReadonlySignal<T>): T;
+/** DESIGN §4 sketch name — alias of {@link useSignalValue} (`useSignal(node.width)`). */
+declare const useSignal: typeof useSignalValue;
 /** The player's current time, live. */
 declare function usePlayhead(player: Player): number;
-/** Playing state, derived from playhead motion + player state polling on invalidation. */
+/** Playing state, live: `time` tracks the playhead, `playing` tracks the
+ * reactive `playingSignal` (so the value updates on a pause, which doesn't move
+ * the playhead). */
 declare function usePlayerState(player: Player): {
   playing: boolean;
   time: number;
@@ -25,5 +62,7 @@ declare function useMachineState(machine: {
 declare function useInput<T extends boolean | number>(machine: {
   input(name: string): Signal<T>;
 }, name: string): [T, (value: T) => void];
+/** The declarative <ScenePlayer> over mount() (DESIGN §4.3, the <gs-player> twin). */
+
 //#endregion
-export { useInput, useMachineState, usePlayerState, usePlayhead, useSignalValue };
+export { ScenePlayer, type ScenePlayerProps, useInput, useMachineState, usePlayerState, usePlayhead, useSignal, useSignalValue };

package/dist/index.js

@@ -1,6 +1,113 @@
-import { useCallback, useSyncExternalStore } from "react";
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from "react";
 import "@glissade/core";
-import "@glissade/player";
+import { mount } from "@glissade/player";
+import "@glissade/scene";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/ScenePlayer.tsx
+/**
+* <ScenePlayer> (DESIGN.md §4.3 tier 3, the React twin of <gs-player>): a
+* declarative component over mount(). Props are mount-native (`scene` +
+* `timeline`); the controls inventory mirrors the element's — play/pause,
+* scrubber, time readout — but as plain React with className-styled nodes
+* rather than a shadow DOM + CSS parts.
+*
+* All mount() work happens in a useEffect keyed on [scene, timeline] (never
+* during render — SSR renders the inert canvas only). The component owns
+* playback so it can observe each play's `.finished` promise for onFinished
+* (a per-play completion signal, §2 — NOT a polled state).
+*/
+/**
+* The controls bar — split out so it can subscribe to live playhead state via
+* usePlayerState (a hook, so it must live in a component that only renders once
+* the player exists).
+*/
+function Controls({ player }) {
+	const { playing, time, duration } = usePlayerState(player);
+	return /* @__PURE__ */ jsxs("div", {
+		className: "gs-controls",
+		children: [
+			/* @__PURE__ */ jsx("button", {
+				className: "gs-controls-button",
+				type: "button",
+				"aria-label": "Play or pause",
+				onClick: () => {
+					if (player.playing) player.pause();
+					else player.play();
+				},
+				children: playing ? "Pause" : "Play"
+			}),
+			/* @__PURE__ */ jsx("input", {
+				className: "gs-controls-scrubber",
+				type: "range",
+				min: 0,
+				max: 1,
+				step: 1e-4,
+				value: duration > 0 ? time / duration : 0,
+				"aria-label": "Seek",
+				onChange: (e) => {
+					player.pause();
+					player.seek(parseFloat(e.target.value) * player.duration);
+				}
+			}),
+			/* @__PURE__ */ jsxs("span", {
+				className: "gs-controls-time",
+				children: [
+					time.toFixed(2),
+					" / ",
+					duration.toFixed(2),
+					"s"
+				]
+			})
+		]
+	});
+}
+function ScenePlayer({ scene, timeline, loop, controls = false, autoplay = false, onFinished, onReady, className, style }) {
+	const canvasRef = useRef(null);
+	const [player, setPlayer] = useState(null);
+	const onFinishedRef = useRef(onFinished);
+	onFinishedRef.current = onFinished;
+	const onReadyRef = useRef(onReady);
+	onReadyRef.current = onReady;
+	const autoplayRef = useRef(autoplay);
+	autoplayRef.current = autoplay;
+	useEffect(() => {
+		const canvas = canvasRef.current;
+		if (!canvas) return;
+		let cancelled = false;
+		const mounted = mount(scene, timeline, canvas, {
+			...loop !== void 0 ? { loop } : {},
+			autoplay: false
+		});
+		const p = mounted.player;
+		const rawPlay = p.play.bind(p);
+		const playAndTrack = (opts) => {
+			const handle = rawPlay(opts);
+			handle.finished.then((completed) => {
+				if (!cancelled) onFinishedRef.current?.(completed);
+			}, () => void 0);
+			return handle;
+		};
+		p.play = playAndTrack;
+		setPlayer(p);
+		onReadyRef.current?.(p);
+		if (autoplayRef.current) playAndTrack();
+		return () => {
+			cancelled = true;
+			setPlayer(null);
+			mounted.dispose();
+		};
+	}, [scene, timeline]);
+	return /* @__PURE__ */ jsxs("div", {
+		className,
+		style,
+		children: [/* @__PURE__ */ jsx("canvas", {
+			ref: canvasRef,
+			width: scene.size.w,
+			height: scene.size.h
+		}), controls && player ? /* @__PURE__ */ jsx(Controls, { player }) : null]
+	});
+}
+//#endregion
 //#region src/index.ts
 /**
 * @glissade/react — thin adapters (DESIGN.md §4.3 tier 3): vanilla core,
@@ -13,15 +120,19 @@ function useSignalValue(sig) {
 	const get = useCallback(() => sig.peek(), [sig]);
 	return useSyncExternalStore(subscribe, get, get);
 }
+/** DESIGN §4 sketch name — alias of {@link useSignalValue} (`useSignal(node.width)`). */
+const useSignal = useSignalValue;
 /** The player's current time, live. */
 function usePlayhead(player) {
 	return useSignalValue(player.playhead);
 }
-/** Playing state, derived from playhead motion + player state polling on invalidation. */
+/** Playing state, live: `time` tracks the playhead, `playing` tracks the
+* reactive `playingSignal` (so the value updates on a pause, which doesn't move
+* the playhead). */
 function usePlayerState(player) {
 	const time = usePlayhead(player);
 	return {
-		playing: player.playing,
+		playing: useSignalValue(player.playingSignal),
 		time,
 		duration: player.duration
 	};
@@ -40,4 +151,4 @@ function useInput(machine, name) {
 	return [useSignalValue(sig), useCallback((v) => sig.set(v), [sig])];
 }
 //#endregion
-export { useInput, useMachineState, usePlayerState, usePlayhead, useSignalValue };
+export { ScenePlayer, useInput, useMachineState, usePlayerState, usePlayhead, useSignal, useSignalValue };

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@glissade/react",
-  "version": "0.10.1",
+  "version": "0.11.0-pre.1",
   "description": "glissade React bindings: signals via useSyncExternalStore, player hooks.",
   "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20.19"
+  },
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -15,15 +18,21 @@
     "dist"
   ],
   "dependencies": {
-    "@glissade/core": "0.10.1",
-    "@glissade/player": "0.10.1"
+    "@glissade/core": "0.11.0-pre.1",
+    "@glissade/player": "0.11.0-pre.1",
+    "@glissade/scene": "0.11.0-pre.1"
   },
   "peerDependencies": {
     "react": ">=18"
   },
   "devDependencies": {
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
     "@types/react": "^19.1.0",
-    "react": "^19.1.0"
+    "@types/react-dom": "^19.1.0",
+    "jsdom": "^26.0.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
   },
   "repository": {
     "type": "git",