@motionscript/react 0.0.0-stage → 0.1.0-alpha.0

package/dist/motionscript-react.js

@@ -0,0 +1,452 @@
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { isProjectDocument } from "@motionscript/core";
+import { jsx } from "react/jsx-runtime";
+//#region src/ui/playhead.ts
+function createPlayheadStore() {
+	let frame = 0;
+	const listeners = /* @__PURE__ */ new Set();
+	return {
+		subscribe(onChange) {
+			listeners.add(onChange);
+			return () => {
+				listeners.delete(onChange);
+			};
+		},
+		getSnapshot: () => frame,
+		set(next) {
+			if (next === frame) return;
+			frame = next;
+			for (const notify of listeners) notify();
+		}
+	};
+}
+/**
+* Subscribe *this* component to the playhead.
+*
+* Typed structurally rather than against `Player` so the store and the hook
+* that reads it don't import each other.
+*/
+function usePlayhead(player) {
+	const { playhead } = player;
+	return useSyncExternalStore(playhead.subscribe, playhead.getSnapshot, playhead.getSnapshot);
+}
+//#endregion
+//#region src/ui/use-motion-player.ts
+/** Used only when neither the document nor the engine says otherwise. */
+var FALLBACK_VIEWPORT = {
+	width: 1920,
+	height: 1080
+};
+var FALLBACK_FPS = 60;
+var INITIAL_PRECOMP = {
+	discoveredTracks: 0,
+	totalTracks: 0,
+	complete: false
+};
+var NO_ERRORS = [];
+function precompProgressOf(result) {
+	return {
+		discoveredTracks: result.tracks.filter((track) => track.discovered).length,
+		totalTracks: result.tracks.length,
+		complete: result.complete
+	};
+}
+function samePrecomp(a, b) {
+	return a.discoveredTracks === b.discoveredTracks && a.totalTracks === b.totalTracks && a.complete === b.complete;
+}
+function sameErrors(a, b) {
+	return a.length === b.length && a.every((error, i) => {
+		const other = b[i];
+		return error.trackId === other.trackId && error.message === other.message && error.nodeId === other.nodeId && error.prop === other.prop && error.stack === other.stack;
+	});
+}
+/** A state updater that keeps the held errors when the report says the same thing. */
+function errorsFrom(reported) {
+	const next = reported.length === 0 ? NO_ERRORS : reported.slice();
+	return (held) => sameErrors(held, next) ? held : next;
+}
+/**
+* Opens a session on `engine` and gives you the transport for it.
+*
+* ```tsx
+* const player = useMotionPlayer({ engine, document: doc, loop: true });
+* <MotionStage player={player} />
+* ```
+*/
+function useMotionPlayer(options) {
+	const { engine, document, onFramePainted } = options;
+	const projectDoc = document && isProjectDocument(document) ? document : void 0;
+	const resolvedViewport = projectDoc?.viewport ?? options.viewport ?? engine?.viewport ?? FALLBACK_VIEWPORT;
+	const fps = projectDoc?.fps ?? options.fps ?? engine?.fps ?? FALLBACK_FPS;
+	const [viewport, setViewport] = useState(resolvedViewport);
+	if (viewport.width !== resolvedViewport.width || viewport.height !== resolvedViewport.height) setViewport(resolvedViewport);
+	const hasDocument = document !== void 0;
+	const [session, setSession] = useState(null);
+	/** Created once; stable for the hook's life, so `usePlayhead` never resubscribes. */
+	const [playhead] = useState(createPlayheadStore);
+	const [isPlaying, setIsPlaying] = useState(false);
+	const [speed, setSpeedState] = useState(options.speed ?? 1);
+	const [muted, setMutedState] = useState(options.muted ?? false);
+	const [loop, setLoopState] = useState(options.loop ?? false);
+	const [loading, setLoading] = useState(true);
+	const [duration, setDuration] = useState(0);
+	const [errors, setErrors] = useState(NO_ERRORS);
+	const [precomp, setPrecomp] = useState(INITIAL_PRECOMP);
+	const totalFrames = Math.max(1, Math.round(duration * fps));
+	const controllerRef = useRef(null);
+	const sessionRef = useRef(null);
+	const documentRef = useRef(document);
+	const onFramePaintedRef = useRef(onFramePainted);
+	/** Monotonic seek id; only the latest may clear the loading flag. */
+	const seekTokenRef = useRef(0);
+	/** Read by the tick handler, which is installed once and must see the latest. */
+	const loopRef = useRef(loop);
+	const fpsRef = useRef(fps);
+	useEffect(() => {
+		onFramePaintedRef.current = onFramePainted;
+		loopRef.current = loop;
+		fpsRef.current = fps;
+	});
+	const [prevDocument, setPrevDocument] = useState(document);
+	if (document !== prevDocument) {
+		setPrevDocument(document);
+		if (document === void 0) {
+			setIsPlaying(false);
+			setDuration(0);
+			if (errors.length > 0) setErrors(NO_ERRORS);
+		}
+	}
+	/**
+	* Pull what the controller now knows: timeline length, errors, progress.
+	* Runs on every swap, so it keeps whatever did not change — a fresh array or
+	* object here is a new `Player` for every consumer on every edit.
+	*/
+	const sync = useCallback((pc) => {
+		setDuration(pc.totalDuration);
+		setErrors(errorsFrom(pc.buildErrors));
+		const progress = precompProgressOf(pc.precomp);
+		setPrecomp((held) => samePrecomp(held, progress) ? held : progress);
+	}, []);
+	/**
+	* Move the playhead and repaint, with the loading flag the UI paces off.
+	*
+	* Created once so every caller — the transport, the reconcile effect and
+	* the first paint after a session opens — shares one seek discipline.
+	*/
+	const [seekTo] = useState(() => (frame) => {
+		const pc = controllerRef.current;
+		if (!pc) return;
+		const last = Math.max(0, Math.round(pc.totalDuration * fpsRef.current) - 1);
+		const clamped = Math.min(Math.max(0, Math.round(frame)), last);
+		playhead.set(clamped);
+		const token = ++seekTokenRef.current;
+		setLoading(true);
+		pc.seek(clamped).then(() => {
+			if (token === seekTokenRef.current) setLoading(false);
+		});
+	});
+	useEffect(() => {
+		if (!engine || !document) return;
+		const opened = engine.open({
+			document,
+			viewport,
+			fps,
+			onPrecompProgress: () => sync(opened.controller)
+		});
+		const pc = opened.controller;
+		pc.onRenderError = (errs) => setErrors(errorsFrom(errs));
+		pc.onFramePainted = (frame) => onFramePaintedRef.current?.(frame);
+		pc.onTime((t) => {
+			const frame = Math.trunc(t * fpsRef.current);
+			playhead.set(frame);
+			if (frame < Math.round(pc.totalDuration * fpsRef.current) - 1) return;
+			if (loopRef.current) pc.seekWhilePlaying(0);
+			else setIsPlaying(false);
+		});
+		controllerRef.current = pc;
+		sessionRef.current = opened;
+		documentRef.current = document;
+		setSession(opened);
+		sync(pc);
+		setLoading(true);
+		return () => {
+			controllerRef.current = null;
+			sessionRef.current = null;
+			setSession(null);
+			opened.dispose();
+		};
+	}, [
+		engine,
+		hasDocument,
+		viewport.width,
+		viewport.height,
+		fps,
+		sync
+	]);
+	useEffect(() => {
+		if (documentRef.current === document) return;
+		documentRef.current = document;
+		const live = sessionRef.current;
+		if (!live || !document) return;
+		const pc = live.controller;
+		live.replace(document);
+		sync(pc);
+		const last = Math.max(0, Math.round(pc.totalDuration * fpsRef.current) - 1);
+		playhead.set(Math.min(playhead.getSnapshot(), last));
+		const token = ++seekTokenRef.current;
+		setLoading(true);
+		pc.whenReplaced().then(() => {
+			if (token === seekTokenRef.current) setLoading(false);
+		});
+	}, [
+		document,
+		sync,
+		playhead
+	]);
+	useEffect(() => {
+		const pc = controllerRef.current;
+		if (!pc) return;
+		if (isPlaying) pc.play(speed);
+		else pc.pause();
+	}, [
+		session,
+		isPlaying,
+		speed
+	]);
+	useEffect(() => {
+		controllerRef.current?.setMuted(muted);
+	}, [session, muted]);
+	useEffect(() => {
+		seekTo(playhead.getSnapshot());
+	}, [
+		session,
+		playhead,
+		seekTo
+	]);
+	const [actions] = useState(() => {
+		const seek = (frame) => {
+			setIsPlaying(false);
+			seekTo(frame);
+		};
+		return {
+			playhead,
+			play: () => setIsPlaying(true),
+			pause: () => setIsPlaying(false),
+			toggle: () => setIsPlaying((playing) => {
+				const pc = controllerRef.current;
+				if (!playing && pc) {
+					const last = Math.round(pc.totalDuration * fpsRef.current) - 1;
+					if (playhead.getSnapshot() >= last) pc.seek(0);
+				}
+				return !playing;
+			}),
+			seek,
+			step: (delta) => seek(playhead.getSnapshot() + delta),
+			seekWhilePlaying: (frame) => controllerRef.current?.seekWhilePlaying(frame),
+			setSpeed: (next) => setSpeedState(next),
+			setMuted: (next) => setMutedState(next),
+			setLoop: (next) => setLoopState(next),
+			screenshot: async () => controllerRef.current?.screenshot() ?? void 0,
+			repaint: () => controllerRef.current?.repaint(),
+			getTreeState: () => controllerRef.current?.getTreeState() ?? null,
+			getNodeProps: (nodeId) => controllerRef.current?.getNodeState(nodeId) ?? null,
+			getTrackSpans: () => controllerRef.current?.spans ?? [],
+			whenReplaced: async () => {
+				await controllerRef.current?.whenReplaced();
+			},
+			getNodeBox: (path) => controllerRef.current?.getNodeBox(path) ?? null,
+			getNodePropsAt: (path) => controllerRef.current?.getNodePropsAt(path) ?? null,
+			getNodeBoxes: () => controllerRef.current?.getNodeBoxes() ?? [],
+			projectNode3D: (path, parentPoints, localPoints) => controllerRef.current?.projectNode3D(path, parentPoints, localPoints) ?? null,
+			parentPlanePoint: (path, point) => controllerRef.current?.parentPlanePoint(path, point) ?? null,
+			getTextLayout: (path) => controllerRef.current?.getTextLayout(path) ?? null,
+			pickNode: (point, tolerance) => controllerRef.current?.pickNode(point, tolerance) ?? null,
+			setNodeOverride: (path, props) => controllerRef.current?.setNodeOverride(path, props),
+			clearNodeOverrides: (path) => controllerRef.current?.clearNodeOverrides(path)
+		};
+	});
+	return useMemo(() => ({
+		...actions,
+		session,
+		viewport,
+		fps,
+		isPlaying,
+		speed,
+		muted,
+		loop,
+		loading,
+		duration,
+		totalFrames,
+		errors,
+		precomp
+	}), [
+		actions,
+		session,
+		viewport,
+		fps,
+		isPlaying,
+		speed,
+		muted,
+		loop,
+		loading,
+		duration,
+		totalFrames,
+		errors,
+		precomp
+	]);
+}
+//#endregion
+//#region src/ui/stage.tsx
+/**
+* What every stage that doesn't ask for a view gets: the whole frame, 1:1.
+*
+* A shared frozen object rather than a literal, so the view effect's dependency
+* on its fields is stable across renders for the overwhelming majority of
+* stages, which never pass `view` at all.
+*/
+var IDENTITY_VIEW = Object.freeze({
+	zoom: 1,
+	x: 0,
+	y: 0
+});
+/**
+* A canvas bound to a {@link Player}'s session.
+*
+* The stage owns how the frame is rasterized — resolution, view, clipping — and
+* nothing about what is in it or when. A session drives **one** surface, so one
+* stage per player: a second would take the surface from the first.
+*/
+function MotionStage({ player, renderScale = 1, surfaceSize, view, clipToFrame, frameBackground, className, style }) {
+	const canvasRef = useRef(null);
+	const { session, viewport } = player;
+	/**
+	* The canvas's backing store, in device pixels. `viewport × renderScale` in
+	* the default case, where the canvas *is* the frame; with `surfaceSize` it
+	* is the viewing area instead.
+	*
+	* Floored at 1 so a degenerate scale can't ask CanvasKit for a zero-sized
+	* surface, which fails the surface creation outright.
+	*/
+	const bufferWidth = Math.max(1, Math.round((surfaceSize?.width ?? viewport.width) * renderScale));
+	const bufferHeight = Math.max(1, Math.round((surfaceSize?.height ?? viewport.height) * renderScale));
+	/**
+	* The view transform to draw with, and the frame to clip and anchor against.
+	* Only meaningful together, so they resolve in one place: no `surfaceSize`
+	* means the canvas is the frame, and both revert to identity.
+	*/
+	const activeView = surfaceSize && view ? view : IDENTITY_VIEW;
+	const activeFrame = surfaceSize && view ? viewport : null;
+	const activeClipToFrame = surfaceSize && view ? clipToFrame ?? true : true;
+	const activeFrameBackground = surfaceSize && view ? frameBackground ?? "black" : "black";
+	const viewRef = useRef(activeView);
+	const frameRectRef = useRef(activeFrame);
+	const clipToFrameRef = useRef(activeClipToFrame);
+	const frameBackgroundRef = useRef(activeFrameBackground);
+	/**
+	* The live render context.
+	*
+	* Held here rather than reached through `player.session` at each use because
+	* it is mutable external state — a Skia context whose knobs are written, not
+	* a value derived from a prop — and writing through the prop is what the
+	* immutability lint is there to catch everywhere it *isn't* one of these.
+	*/
+	const ctxRef = useRef(null);
+	useEffect(() => {
+		viewRef.current = activeView;
+		frameRectRef.current = activeFrame;
+		clipToFrameRef.current = activeClipToFrame;
+		frameBackgroundRef.current = activeFrameBackground;
+		ctxRef.current = session ? session.surface : null;
+	});
+	/**
+	* Bind the surface, and rebuild it when the backing store changes.
+	*
+	* The order matters and is why this is an effect rather than a callback:
+	* React has already written the canvas's new `width`/`height` by the time
+	* effects run, and CanvasKit reads exactly those when it builds the surface
+	* (`MakeOnScreenGLSurface(ctx, canvas.width, canvas.height)`). Mounting
+	* before the resize would produce a surface of the previous size.
+	*
+	* `repaint()` afterwards because a new surface starts blank and the clock is
+	* not necessarily running to fill it — a paused editor would otherwise show
+	* black until something else moved.
+	*/
+	useEffect(() => {
+		const canvas = canvasRef.current;
+		const ctx = ctxRef.current;
+		if (!session || !canvas || !ctx) return;
+		ctx.pixelRatio = renderScale;
+		ctx.view = viewRef.current;
+		ctx.frame = frameRectRef.current;
+		ctx.clipToFrame = clipToFrameRef.current;
+		ctx.frameBackground = frameBackgroundRef.current;
+		ctx.mount(canvas);
+		session.controller.repaint();
+	}, [
+		session,
+		renderScale,
+		bufferWidth,
+		bufferHeight
+	]);
+	/**
+	* Apply {@link MotionStageProps.view} — a repaint and nothing more.
+	*
+	* Depends on the fields rather than the object so a caller passing a fresh
+	* `{zoom, x, y}` each render — which is every caller, since it comes from a
+	* gesture — doesn't repaint on renders where the view didn't move.
+	*/
+	useEffect(() => {
+		const ctx = ctxRef.current;
+		if (!session || !ctx) return;
+		ctx.view = {
+			zoom: activeView.zoom,
+			x: activeView.x,
+			y: activeView.y
+		};
+		ctx.frame = activeFrame;
+		ctx.clipToFrame = activeClipToFrame;
+		ctx.frameBackground = activeFrameBackground;
+		session.controller.repaint();
+	}, [
+		session,
+		activeView.zoom,
+		activeView.x,
+		activeView.y,
+		activeFrame?.width,
+		activeFrame?.height,
+		activeClipToFrame,
+		activeFrameBackground
+	]);
+	return /* @__PURE__ */ jsx("div", {
+		className,
+		style: {
+			position: "relative",
+			width: "100%",
+			height: "100%",
+			...style
+		},
+		children: /* @__PURE__ */ jsx("canvas", {
+			ref: canvasRef,
+			width: bufferWidth,
+			height: bufferHeight,
+			style: {
+				display: session ? "block" : "none",
+				...surfaceSize ? {
+					position: "absolute",
+					left: "50%",
+					top: "50%",
+					width: `${surfaceSize.width}px`,
+					height: `${surfaceSize.height}px`,
+					transform: "translate(-50%, -50%)"
+				} : {
+					width: "100%",
+					height: "100%"
+				}
+			}
+		})
+	});
+}
+//#endregion
+export { MotionStage, useMotionPlayer, usePlayhead };
+
+//# sourceMappingURL=motionscript-react.js.map

package/dist/motionscript-react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"motionscript-react.js","names":[],"sources":["../src/ui/playhead.ts","../src/ui/use-motion-player.ts","../src/ui/stage.tsx"],"sourcesContent":["import { useSyncExternalStore } from \"react\";\n\n/**\n * The playhead, held outside React.\n *\n * A frame number written at clock rate through `useState` re-renders whoever\n * owns the player, and on a high-refresh display that is faster than the\n * project's own frame rate. Nothing in a render depends on it: the controller\n * paints straight onto the canvas and React is not involved. So the number\n * lives here, and only the components that actually display it subscribe.\n */\nexport interface PlayheadStore {\n    subscribe(onChange: () => void): () => void;\n    getSnapshot(): number;\n    /** @internal — written by the player that owns this store. */\n    set(frame: number): void;\n}\n\nexport function createPlayheadStore(): PlayheadStore {\n    let frame = 0;\n    const listeners = new Set<() => void>();\n    return {\n        subscribe(onChange) {\n            listeners.add(onChange);\n            return () => {\n                listeners.delete(onChange);\n            };\n        },\n        getSnapshot: () => frame,\n        set(next) {\n            if (next === frame) return;\n            frame = next;\n            for (const notify of listeners) notify();\n        },\n    };\n}\n\n/**\n * Subscribe *this* component to the playhead.\n *\n * Typed structurally rather than against `Player` so the store and the hook\n * that reads it don't import each other.\n */\nexport function usePlayhead(player: { playhead: PlayheadStore }): number {\n    const { playhead } = player;\n    return useSyncExternalStore(playhead.subscribe, playhead.getSnapshot, playhead.getSnapshot);\n}\n","import { useCallback, useEffect, useMemo, useRef, useState } from \"react\";\n\nimport { isProjectDocument } from \"@motionscript/core\";\n\nimport type {\n    BuildError,\n    Engine,\n    NodeBox,\n    Node3DFrame,\n    NodeOverride,\n    NodeState,\n    NodeTextLayout,\n    PlaybackController,\n    AssetTimelineResult,\n    ProjectDocument,\n    SceneDocument,\n    Session,\n    Size2D,\n    TrackSpan,\n    TreeState,\n    Vector2,\n    Vector3,\n} from \"@motionscript/core\";\n\nimport { createPlayheadStore, type PlayheadStore } from \"./playhead\";\n\n/** Used only when neither the document nor the engine says otherwise. */\nconst FALLBACK_VIEWPORT: Size2D = { width: 1920, height: 1080 };\nconst FALLBACK_FPS = 60;\n\n/**\n * How far background discovery has got. Only the tracks on frame 0 are\n * discovered before the player mounts; the rest stream in behind it (see\n * `AssetTimeline.runAsync`). The timeline's length never waits on it — every track\n * declares its own.\n */\nexport interface PrecompProgress {\n    /** Tracks discovered so far. */\n    discoveredTracks: number;\n    /** Tracks in the project. */\n    totalTracks: number;\n    /** True once every track has been discovered. */\n    complete: boolean;\n}\n\nconst INITIAL_PRECOMP: PrecompProgress = { discoveredTracks: 0, totalTracks: 0, complete: false };\nconst NO_ERRORS: BuildError[] = [];\n\nfunction precompProgressOf(result: AssetTimelineResult): PrecompProgress {\n    return {\n        discoveredTracks: result.tracks.filter(track => track.discovered).length,\n        totalTracks: result.tracks.length,\n        complete: result.complete,\n    };\n}\n\nfunction samePrecomp(a: PrecompProgress, b: PrecompProgress): boolean {\n    return a.discoveredTracks === b.discoveredTracks && a.totalTracks === b.totalTracks && a.complete === b.complete;\n}\n\nfunction sameErrors(a: readonly BuildError[], b: readonly BuildError[]): boolean {\n    return a.length === b.length && a.every((error, i) => {\n        const other = b[i];\n        return error.trackId === other.trackId && error.message === other.message\n            && error.nodeId === other.nodeId && error.prop === other.prop && error.stack === other.stack;\n    });\n}\n\n/** A state updater that keeps the held errors when the report says the same thing. */\nfunction errorsFrom(reported: readonly BuildError[]): (held: BuildError[]) => BuildError[] {\n    const next = reported.length === 0 ? NO_ERRORS : reported.slice();\n    return held => (sameErrors(held, next) ? held : next);\n}\n\nexport interface MotionPlayerOptions {\n    /**\n     * The engine this player opens its session on.\n     *\n     * Nullable on purpose: building one is asynchronous\n     * (`await createBrowserEngine(...)`), so a host holds it in state and it is\n     * `null` for the first render or two. The player no-ops until it arrives,\n     * which is what keeps the hook out of a conditional.\n     *\n     * **Create it once, and share it.** It holds CanvasKit and the exporter, so\n     * a fresh one per render rebuilds the WebGL surface behind every player on\n     * it. Identity-compared: a different engine is a different CanvasKit, and so\n     * a full rebuild.\n     */\n    engine: Engine | null | undefined;\n    /**\n     * What to play. Nothing opens until there is one.\n     *\n     * A **project** document is the whole answer: it carries its own viewport,\n     * fps, theme and tracks. A **scene** document (still or composition) is one\n     * clip and carries none of that, so `viewport` and `fps` must come from here\n     * or from the engine.\n     *\n     * Content-diffed, with identity as the fast path: a new document is reconciled\n     * onto the running session, each track's built tree patched in place and\n     * rebuilt only when its change cannot be patched. Treat documents as\n     * immutable — an edit made in place to one the player already holds is not\n     * seen.\n     *\n     * A new document keeps the player's place: the playhead stays where it was\n     * (clamped when the timeline got shorter), and playback carries on if it was\n     * running. Seek or pause yourself when a swap means \"start over\".\n     */\n    document?: ProjectDocument | SceneDocument;\n    /** Overrides the engine's, for a source that carries none. */\n    viewport?: Size2D;\n    /** Overrides the engine's, for a source that carries none. */\n    fps?: number;\n    /** Initial playback rate. Change it later with {@link Player.setSpeed}. */\n    speed?: number;\n    /** Initial mute state. Change it later with {@link Player.setMuted}. */\n    muted?: boolean;\n    /** Initial loop state. Change it later with {@link Player.setLoop}. */\n    loop?: boolean;\n    /**\n     * Called **synchronously**, on the same task as the draw, each time a frame\n     * has been painted — whether by the clock, a seek, or a document swap.\n     *\n     * Not the playhead, which reports where the *clock* is. A seek is\n     * asynchronous, so between the two there is a window in which the number has\n     * moved and the canvas has not. Reach for this to keep an overlay — a\n     * selection box, a caret, a handle — in step with the pixels, and keep the\n     * listener cheap: it runs on the render loop, before the browser has had a\n     * chance to composite.\n     *\n     * Read through a ref, so changing it costs nothing.\n     */\n    onFramePainted?: (frame: number) => void;\n}\n\n/**\n * One document, its transport, and the session driving it. No DOM.\n *\n * Hand it to a {@link MotionStage} to put pixels on screen. Two calls to\n * {@link useMotionPlayer} produce two of these with nothing shared but the\n * engine — separate playheads, clocks, audio devices and transports.\n */\nexport interface Player {\n    /** The live session, or `null` before the engine and a document arrive. */\n    readonly session: Session | null;\n    /** The playhead, read with `usePlayhead(player)`. Stable for the hook's life. */\n    readonly playhead: PlayheadStore;\n    /** Resolved from the document, else the engine, else 1920×1080. */\n    readonly viewport: Size2D;\n    /** Resolved from the document, else the engine, else 60. */\n    readonly fps: number;\n\n    readonly isPlaying: boolean;\n    readonly speed: number;\n    readonly muted: boolean;\n    readonly loop: boolean;\n    /** True while a seek or a document swap is in flight. */\n    readonly loading: boolean;\n    /** The project's length, known from the document before any track is discovered. */\n    readonly duration: number;\n    /** {@link duration} in frames, floored at 1. */\n    readonly totalFrames: number;\n    readonly errors: BuildError[];\n    readonly precomp: PrecompProgress;\n\n    play(): void;\n    pause(): void;\n    toggle(): void;\n    /** Seek while paused. Clamped to the timeline. */\n    seek(frame: number): void;\n    /** Seek relative to where the playhead is now. */\n    step(delta: number): void;\n    /** Seek without interrupting playback. */\n    seekWhilePlaying(frame: number): void;\n    setSpeed(speed: number): void;\n    setMuted(muted: boolean): void;\n    setLoop(loop: boolean): void;\n\n    screenshot(): Promise<string | undefined>;\n    /** Re-layout and repaint the current frame — no re-evaluation. */\n    repaint(): void;\n\n    getTreeState(): TreeState | null;\n    getNodeProps(nodeId: string): NodeState | null;\n    /** Where each track sits on the timeline, in document order. */\n    getTrackSpans(): readonly TrackSpan[];\n    /**\n     * Resolves once the paint a document swap scheduled has landed. The swap\n     * does not paint before its assets have loaded, so await this before\n     * screenshotting or reading the tree.\n     */\n    whenReplaced(): Promise<void>;\n\n    // ---- Direct manipulation ----------------------------------------------\n    // Points are in viewport space — origin at the viewport centre, y-up, in\n    // this player's `viewport` pixels.\n\n    getNodeBox(path: string): NodeBox | null;\n    getNodePropsAt(path: string): NodeState[\"properties\"] | null;\n    getNodeBoxes(): NodeBox[];\n    projectNode3D(\n        path: string,\n        parentPoints: readonly Vector3[],\n        localPoints: readonly Vector3[],\n    ): Node3DFrame | null;\n    /**\n     * Where `point` lands on the plane the node at `path` is positioned in, in\n     * that plane's own y-up frame. Two answers differ by the `x`/`y` change that\n     * moves the node between them — which a screen delta no longer is once the\n     * node sits in a 2.5D space.\n     */\n    parentPlanePoint(path: string, point: Vector2): Vector2 | null;\n    getTextLayout(path: string): NodeTextLayout | null;\n    /** `tolerance` is grab-slop in scene units. */\n    pickNode(point: Vector2, tolerance?: number): NodeBox | null;\n    /** Layer transient props over a node without rebuilding its track. */\n    setNodeOverride(path: string, props: NodeOverride): void;\n    clearNodeOverrides(path?: string): void;\n}\n\n/**\n * Opens a session on `engine` and gives you the transport for it.\n *\n * ```tsx\n * const player = useMotionPlayer({ engine, document: doc, loop: true });\n * <MotionStage player={player} />\n * ```\n */\nexport function useMotionPlayer(options: MotionPlayerOptions): Player {\n    const { engine, document, onFramePainted } = options;\n\n    // Read straight off the document where it says so, else the caller's, else\n    // the engine's. All plain JSON, so this resolves during render, before any\n    // session exists — which is what lets a stage size its canvas on the first\n    // pass rather than after a mount.\n    const projectDoc = document && isProjectDocument(document) ? document : undefined;\n    const resolvedViewport = projectDoc?.viewport ?? options.viewport ?? engine?.viewport ?? FALLBACK_VIEWPORT;\n    const fps = projectDoc?.fps ?? options.fps ?? engine?.fps ?? FALLBACK_FPS;\n\n    // Held by size: a host that rebuilds its document per edit rebuilds this\n    // object with it, and a new one would hand every consumer a new `Player`.\n    const [viewport, setViewport] = useState(resolvedViewport);\n    if (viewport.width !== resolvedViewport.width || viewport.height !== resolvedViewport.height) {\n        setViewport(resolvedViewport);\n    }\n    const hasDocument = document !== undefined;\n\n    const [session, setSession] = useState<Session | null>(null);\n    /** Created once; stable for the hook's life, so `usePlayhead` never resubscribes. */\n    const [playhead] = useState(createPlayheadStore);\n\n    const [isPlaying, setIsPlaying] = useState(false);\n    const [speed, setSpeedState] = useState(options.speed ?? 1);\n    const [muted, setMutedState] = useState(options.muted ?? false);\n    const [loop, setLoopState] = useState(options.loop ?? false);\n    const [loading, setLoading] = useState(true);\n    const [duration, setDuration] = useState(0);\n    const [errors, setErrors] = useState<BuildError[]>(NO_ERRORS);\n    const [precomp, setPrecomp] = useState<PrecompProgress>(INITIAL_PRECOMP);\n\n    const totalFrames = Math.max(1, Math.round(duration * fps));\n\n    // Stable across renders so the action callbacks below never need rebuilding.\n    const controllerRef = useRef<PlaybackController | null>(null);\n    const sessionRef = useRef<Session | null>(null);\n    const documentRef = useRef(document);\n    const onFramePaintedRef = useRef(onFramePainted);\n    /** Monotonic seek id; only the latest may clear the loading flag. */\n    const seekTokenRef = useRef(0);\n    /** Read by the tick handler, which is installed once and must see the latest. */\n    const loopRef = useRef(loop);\n    const fpsRef = useRef(fps);\n\n    useEffect(() => {\n        onFramePaintedRef.current = onFramePainted;\n        loopRef.current = loop;\n        fpsRef.current = fps;\n    });\n\n    // An edit keeps the transport and its errors — the reconcile effect below\n    // re-reads both off the session, so an error the edit did not fix never\n    // blinks out for a commit. Only losing the document stops it, during render\n    // so nothing draws against a timeline that is gone.\n    const [prevDocument, setPrevDocument] = useState(document);\n    if (document !== prevDocument) {\n        setPrevDocument(document);\n        if (document === undefined) {\n            setIsPlaying(false);\n            setDuration(0);\n            if (errors.length > 0) setErrors(NO_ERRORS);\n        }\n    }\n\n    /**\n     * Pull what the controller now knows: timeline length, errors, progress.\n     * Runs on every swap, so it keeps whatever did not change — a fresh array or\n     * object here is a new `Player` for every consumer on every edit.\n     */\n    const sync = useCallback((pc: PlaybackController) => {\n        setDuration(pc.totalDuration);\n        setErrors(errorsFrom(pc.buildErrors));\n        const progress = precompProgressOf(pc.precomp);\n        setPrecomp(held => (samePrecomp(held, progress) ? held : progress));\n    }, []);\n\n    /**\n     * Move the playhead and repaint, with the loading flag the UI paces off.\n     *\n     * Created once so every caller — the transport, the reconcile effect and\n     * the first paint after a session opens — shares one seek discipline.\n     */\n    const [seekTo] = useState(() => (frame: number) => {\n        const pc = controllerRef.current;\n        if (!pc) return;\n        const last = Math.max(0, Math.round(pc.totalDuration * fpsRef.current) - 1);\n        const clamped = Math.min(Math.max(0, Math.round(frame)), last);\n        playhead.set(clamped);\n        // Only the newest seek may report \"settled\". A superseded seek still\n        // resolves — its generation guard bailed inside the controller — but it\n        // never painted, so clearing the loading flag from it would tell the UI\n        // a frame is ready while the newest is still in flight. Consumers pace\n        // scrubbing off that edge.\n        const token = ++seekTokenRef.current;\n        setLoading(true);\n        void pc.seek(clamped).then(() => {\n            if (token === seekTokenRef.current) setLoading(false);\n        });\n    });\n\n    useEffect(() => {\n        if (!engine || !document) return;\n\n        // `target` is omitted: the session opens unmounted, and a `MotionStage`\n        // binds a canvas to it afterwards. That is what lets this hook own the\n        // session without owning any DOM.\n        const opened = engine.open({\n            document,\n            viewport,\n            fps,\n            // A track landing can surface a build error it threw.\n            onPrecompProgress: () => sync(opened.controller),\n        });\n\n        const pc = opened.controller;\n        pc.onRenderError = errs => setErrors(errorsFrom(errs));\n        pc.onFramePainted = frame => onFramePaintedRef.current?.(frame);\n\n        pc.onTime((t: number) => {\n            const frame = Math.trunc(t * fpsRef.current);\n            playhead.set(frame);\n\n            // A document swap can change the timeline's length, so ask the\n            // controller rather than trusting a duration captured when this\n            // listener was installed.\n            const last = Math.round(pc.totalDuration * fpsRef.current) - 1;\n            if (frame < last) return;\n            if (loopRef.current) pc.seekWhilePlaying(0);\n            else setIsPlaying(false);\n        });\n\n        controllerRef.current = pc;\n        sessionRef.current = opened;\n        documentRef.current = document;\n        setSession(opened);\n        sync(pc);\n        setLoading(true);\n\n        return () => {\n            controllerRef.current = null;\n            sessionRef.current = null;\n            setSession(null);\n            // Disposes the controller and the render context together — the\n            // session owns both.\n            opened.dispose();\n        };\n        // `document` is deliberately absent — only whether there is one: a new\n        // document is reconciled onto the live session by the effect below\n        // rather than rebuilt into a new one. What remains genuinely does need a\n        // rebuild — a different engine is a different CanvasKit, and a live\n        // surface cannot change its size or rate (`Session.replace` refuses both).\n        // eslint-disable-next-line react-hooks/exhaustive-deps\n    }, [engine, hasDocument, viewport.width, viewport.height, fps, sync]);\n\n    // Reconcile a changed document onto the session already running. Skipped on\n    // the pass that opens it, which was opened with this very document —\n    // replacing it there would rediscover a timeline just discovered.\n    useEffect(() => {\n        if (documentRef.current === document) return;\n        documentRef.current = document;\n        const live = sessionRef.current;\n        if (!live || !document) return;\n        const pc = live.controller;\n        live.replace(document);\n        sync(pc);\n        // No seek: `replace` already paints the current frame once its assets\n        // load, clamped to the new length, and a running clock keeps ticking.\n        const last = Math.max(0, Math.round(pc.totalDuration * fpsRef.current) - 1);\n        playhead.set(Math.min(playhead.getSnapshot(), last));\n        const token = ++seekTokenRef.current;\n        setLoading(true);\n        void pc.whenReplaced().then(() => {\n            if (token === seekTokenRef.current) setLoading(false);\n        });\n    }, [document, sync, playhead]);\n\n    useEffect(() => {\n        const pc = controllerRef.current;\n        if (!pc) return;\n        if (isPlaying) pc.play(speed);\n        else pc.pause();\n    }, [session, isPlaying, speed]);\n\n    useEffect(() => {\n        controllerRef.current?.setMuted(muted);\n    }, [session, muted]);\n\n    // The one seek that isn't user-driven: park the new session on the frame\n    // the playhead already holds, so a rebuild keeps its place.\n    useEffect(() => {\n        seekTo(playhead.getSnapshot());\n    }, [session, playhead, seekTo]);\n\n    // Built once and stable for the hook's life: every one reads the controller\n    // through a ref, so a re-render never invalidates a handler a child holds —\n    // which is what lets a transport subscribe its listeners a single time.\n    const [actions] = useState<Omit<Player, keyof PlayerState>>(() => {\n        // Scrubbing is a pause: a seek that left the clock running would be\n        // overwritten by the next tick.\n        const seek = (frame: number) => {\n            setIsPlaying(false);\n            seekTo(frame);\n        };\n\n        return {\n            playhead,\n            play: () => setIsPlaying(true),\n            pause: () => setIsPlaying(false),\n            toggle: () =>\n                setIsPlaying(playing => {\n                    // Restarting from the end is what a play button means there.\n                    const pc = controllerRef.current;\n                    if (!playing && pc) {\n                        const last = Math.round(pc.totalDuration * fpsRef.current) - 1;\n                        if (playhead.getSnapshot() >= last) void pc.seek(0);\n                    }\n                    return !playing;\n                }),\n            seek,\n            step: (delta: number) => seek(playhead.getSnapshot() + delta),\n            seekWhilePlaying: (frame: number) => controllerRef.current?.seekWhilePlaying(frame),\n            setSpeed: (next: number) => setSpeedState(next),\n            setMuted: (next: boolean) => setMutedState(next),\n            setLoop: (next: boolean) => setLoopState(next),\n\n            screenshot: async () => controllerRef.current?.screenshot() ?? undefined,\n            repaint: () => controllerRef.current?.repaint(),\n\n            getTreeState: () => controllerRef.current?.getTreeState() ?? null,\n            getNodeProps: (nodeId: string) => controllerRef.current?.getNodeState(nodeId) ?? null,\n            getTrackSpans: () => controllerRef.current?.spans ?? [],\n            whenReplaced: async () => {\n                await controllerRef.current?.whenReplaced();\n            },\n\n            getNodeBox: (path: string) => controllerRef.current?.getNodeBox(path) ?? null,\n            getNodePropsAt: (path: string) => controllerRef.current?.getNodePropsAt(path) ?? null,\n            getNodeBoxes: () => controllerRef.current?.getNodeBoxes() ?? [],\n            projectNode3D: (path, parentPoints, localPoints) =>\n                controllerRef.current?.projectNode3D(path, parentPoints, localPoints) ?? null,\n            parentPlanePoint: (path: string, point: Vector2) =>\n                controllerRef.current?.parentPlanePoint(path, point) ?? null,\n            getTextLayout: (path: string) => controllerRef.current?.getTextLayout(path) ?? null,\n            pickNode: (point: Vector2, tolerance?: number) =>\n                controllerRef.current?.pickNode(point, tolerance) ?? null,\n            setNodeOverride: (path: string, props: NodeOverride) =>\n                controllerRef.current?.setNodeOverride(path, props),\n            clearNodeOverrides: (path?: string) => controllerRef.current?.clearNodeOverrides(path),\n        };\n    });\n\n    return useMemo(\n        () => ({\n            ...actions,\n            session,\n            viewport,\n            fps,\n            isPlaying,\n            speed,\n            muted,\n            loop,\n            loading,\n            duration,\n            totalFrames,\n            errors,\n            precomp,\n        }),\n        [\n            actions,\n            session,\n            viewport,\n            fps,\n            isPlaying,\n            speed,\n            muted,\n            loop,\n            loading,\n            duration,\n            totalFrames,\n            errors,\n            precomp,\n        ],\n    );\n}\n\n/** The fields the memo above supplies; everything else on `Player` is an action. */\ntype PlayerState = Pick<\n    Player,\n    | \"session\"\n    | \"viewport\"\n    | \"fps\"\n    | \"isPlaying\"\n    | \"speed\"\n    | \"muted\"\n    | \"loop\"\n    | \"loading\"\n    | \"duration\"\n    | \"totalFrames\"\n    | \"errors\"\n    | \"precomp\"\n>;\n","import { useEffect, useRef, type CSSProperties } from \"react\";\n\nimport type { EngineRenderContext, Size2D } from \"@motionscript/core\";\n\nimport type { Player } from \"./use-motion-player\";\n\n/**\n * The session's surface, with `mount` narrowed to a canvas.\n *\n * `core` compiles without the DOM lib, so `RenderSurface.mount` takes `unknown`\n * there. This is the narrowing that seam always assumed: it happens here, in\n * the one layer that genuinely has `HTMLCanvasElement`.\n */\ntype StageRenderContext = Omit<EngineRenderContext, \"mount\"> & {\n    mount(canvas: HTMLCanvasElement): void;\n};\n\n/**\n * What every stage that doesn't ask for a view gets: the whole frame, 1:1.\n *\n * A shared frozen object rather than a literal, so the view effect's dependency\n * on its fields is stable across renders for the overwhelming majority of\n * stages, which never pass `view` at all.\n */\nconst IDENTITY_VIEW = Object.freeze({ zoom: 1, x: 0, y: 0 });\n\nexport interface MotionStageProps {\n    /** The player whose session this stage draws. */\n    player: Player;\n    /**\n     * Device pixels to rasterize per viewport unit. Defaults to `1`.\n     *\n     * **Not a zoom and not a crop.** The viewport stays the scene's logical\n     * coordinate space; this only changes how many real pixels that space is\n     * drawn into, and CSS scales the canvas back up to fill its box.\n     *\n     * The lever exists because a preview is usually displayed far smaller than\n     * the project's output size: a 1920×1080 project in a 700px-wide panel\n     * rasterizes roughly seven times the pixels anyone can see. `0.5` there is a\n     * quarter of the fill, the shader work and the effect offscreens.\n     *\n     * Two things to know before animating it:\n     *\n     * - **Every change re-creates the Skia surface**, which drops the storage\n     *   adapter's texture-backed images (decoded video frames, 3D composites;\n     *   still images survive) and asks for a fresh GL context. Quantize to a few\n     *   steps and let it settle — never drive it from a resize observer.\n     * - **Prefer scales that keep both dimensions whole.** `pixelRatio` is one\n     *   uniform number, so a scale that rounds differently on each axis shifts\n     *   the frame's centre by up to half a device pixel.\n     *\n     * A snapshot from `player.screenshot()` comes back at the surface's size, so\n     * it is scaled too — render at `1` if you need full resolution out of it.\n     */\n    renderScale?: number;\n    /**\n     * The canvas's own size in CSS pixels, when it is **not** the frame.\n     *\n     * Omitted — the default — the canvas is the frame: sized `viewport ×\n     * renderScale` and stretched over its box by CSS, which is what every\n     * export, thumbnail and plain player wants.\n     *\n     * Supplied, together with {@link view}, the canvas becomes a *window* onto\n     * the frame: it takes the size of the area it is shown in, `renderScale`\n     * stops meaning \"fraction of the project's resolution\" and starts meaning\n     * device pixels per CSS pixel, and only what is on screen is rasterized.\n     * That is what lets an editor zoom in without going soft or paying for the\n     * whole frame at the zoomed resolution.\n     *\n     * It re-creates the surface exactly as `renderScale` does, and wants the\n     * same treatment: quantize it and let it settle.\n     */\n    surfaceSize?: Size2D;\n    /**\n     * A pan and zoom applied to the render itself. Requires {@link surfaceSize}.\n     *\n     * `zoom` multiplies scene units; `x`/`y` offset the frame's centre in CSS\n     * pixels, positive `y` downwards — the same sign convention as a CSS\n     * translate, so a preview can hand over the pan it was already computing.\n     *\n     * Changing it costs a repaint and nothing else: no surface, no textures, no\n     * precomp. That is the point of it living here rather than in a CSS\n     * transform, which cannot add resolution it was not rasterized with.\n     */\n    view?: { zoom: number; x: number; y: number };\n    /**\n     * Whether the frame's edge bounds what draws, rather than only where its own\n     * backdrop goes. Requires {@link surfaceSize} and {@link view}. Defaults to\n     * `true`.\n     *\n     * Off lets a node parked past the frame's edge rasterize into the rest of\n     * the surface instead of being discarded — for a host that wants to show,\n     * faded, what a node placed there while animating in or out.\n     */\n    clipToFrame?: boolean;\n    /**\n     * What the frame's backdrop is painted with. Defaults to `\"black\"`.\n     *\n     * `\"transparent\"` leaves the frame unpainted where nothing was drawn, so\n     * whatever the host renders behind the canvas shows through — a\n     * checkerboard, for an editor that has to distinguish \"no scene covers this\"\n     * from \"a scene covers it in black\". Requires {@link surfaceSize} and\n     * {@link view}, the same way {@link clipToFrame} does.\n     */\n    frameBackground?: \"black\" | \"transparent\";\n    className?: string;\n    style?: CSSProperties;\n}\n\n/**\n * A canvas bound to a {@link Player}'s session.\n *\n * The stage owns how the frame is rasterized — resolution, view, clipping — and\n * nothing about what is in it or when. A session drives **one** surface, so one\n * stage per player: a second would take the surface from the first.\n */\nexport function MotionStage({\n    player,\n    renderScale = 1,\n    surfaceSize,\n    view,\n    clipToFrame,\n    frameBackground,\n    className,\n    style,\n}: MotionStageProps) {\n    const canvasRef = useRef<HTMLCanvasElement>(null);\n    const { session, viewport } = player;\n\n    /**\n     * The canvas's backing store, in device pixels. `viewport × renderScale` in\n     * the default case, where the canvas *is* the frame; with `surfaceSize` it\n     * is the viewing area instead.\n     *\n     * Floored at 1 so a degenerate scale can't ask CanvasKit for a zero-sized\n     * surface, which fails the surface creation outright.\n     */\n    const bufferWidth = Math.max(1, Math.round((surfaceSize?.width ?? viewport.width) * renderScale));\n    const bufferHeight = Math.max(1, Math.round((surfaceSize?.height ?? viewport.height) * renderScale));\n\n    /**\n     * The view transform to draw with, and the frame to clip and anchor against.\n     * Only meaningful together, so they resolve in one place: no `surfaceSize`\n     * means the canvas is the frame, and both revert to identity.\n     */\n    const activeView = surfaceSize && view ? view : IDENTITY_VIEW;\n    const activeFrame = surfaceSize && view ? viewport : null;\n    const activeClipToFrame = surfaceSize && view ? (clipToFrame ?? true) : true;\n    const activeFrameBackground = surfaceSize && view ? (frameBackground ?? \"black\") : \"black\";\n\n    const viewRef = useRef(activeView);\n    const frameRectRef = useRef(activeFrame);\n    const clipToFrameRef = useRef(activeClipToFrame);\n    const frameBackgroundRef = useRef(activeFrameBackground);\n    /**\n     * The live render context.\n     *\n     * Held here rather than reached through `player.session` at each use because\n     * it is mutable external state — a Skia context whose knobs are written, not\n     * a value derived from a prop — and writing through the prop is what the\n     * immutability lint is there to catch everywhere it *isn't* one of these.\n     */\n    const ctxRef = useRef<StageRenderContext | null>(null);\n    useEffect(() => {\n        viewRef.current = activeView;\n        frameRectRef.current = activeFrame;\n        clipToFrameRef.current = activeClipToFrame;\n        frameBackgroundRef.current = activeFrameBackground;\n        ctxRef.current = session ? (session.surface as StageRenderContext) : null;\n    });\n\n    /**\n     * Bind the surface, and rebuild it when the backing store changes.\n     *\n     * The order matters and is why this is an effect rather than a callback:\n     * React has already written the canvas's new `width`/`height` by the time\n     * effects run, and CanvasKit reads exactly those when it builds the surface\n     * (`MakeOnScreenGLSurface(ctx, canvas.width, canvas.height)`). Mounting\n     * before the resize would produce a surface of the previous size.\n     *\n     * `repaint()` afterwards because a new surface starts blank and the clock is\n     * not necessarily running to fill it — a paused editor would otherwise show\n     * black until something else moved.\n     */\n    useEffect(() => {\n        const canvas = canvasRef.current;\n        const ctx = ctxRef.current;\n        if (!session || !canvas || !ctx) return;\n        ctx.pixelRatio = renderScale;\n        ctx.view = viewRef.current;\n        ctx.frame = frameRectRef.current;\n        ctx.clipToFrame = clipToFrameRef.current;\n        ctx.frameBackground = frameBackgroundRef.current;\n        // `mount` detaches the old surface first, which also drops the storage\n        // adapter's texture-backed images — they belong to the surface that made\n        // them. Video frames and 3D composites are re-uploaded on demand;\n        // decoded still images are raster-backed and survive.\n        ctx.mount(canvas);\n        session.controller.repaint();\n    }, [session, renderScale, bufferWidth, bufferHeight]);\n\n    /**\n     * Apply {@link MotionStageProps.view} — a repaint and nothing more.\n     *\n     * Depends on the fields rather than the object so a caller passing a fresh\n     * `{zoom, x, y}` each render — which is every caller, since it comes from a\n     * gesture — doesn't repaint on renders where the view didn't move.\n     */\n    useEffect(() => {\n        const ctx = ctxRef.current;\n        if (!session || !ctx) return;\n        ctx.view = { zoom: activeView.zoom, x: activeView.x, y: activeView.y };\n        ctx.frame = activeFrame;\n        ctx.clipToFrame = activeClipToFrame;\n        ctx.frameBackground = activeFrameBackground;\n        session.controller.repaint();\n        // eslint-disable-next-line react-hooks/exhaustive-deps\n    }, [\n        session,\n        activeView.zoom,\n        activeView.x,\n        activeView.y,\n        activeFrame?.width,\n        activeFrame?.height,\n        activeClipToFrame,\n        activeFrameBackground,\n    ]);\n\n    return (\n        <div className={className} style={{ position: \"relative\", width: \"100%\", height: \"100%\", ...style }}>\n            <canvas\n                ref={canvasRef}\n                // The backing store, in device pixels. CSS below stretches it\n                // back over the whole box either way, so this is purely how much\n                // gets rasterized.\n                width={bufferWidth}\n                height={bufferHeight}\n                style={{\n                    display: session ? \"block\" : \"none\",\n                    ...(surfaceSize\n                        ? {\n                              // `surfaceSize` is the canvas's CSS size, so it is\n                              // honoured literally rather than stretched to the\n                              // box: it is quantized by its caller, which means\n                              // it is usually a little larger than the box and\n                              // rarely the same shape. Stretched, that\n                              // difference would land as a non-uniform scale — a\n                              // picture squashed on one axis, a far worse\n                              // artefact than the softness this arrangement\n                              // exists to remove.\n                              //\n                              // Centred, so the surface's midpoint is the box's\n                              // midpoint: `executePass` puts the scene origin at\n                              // the centre of the surface, so this is what makes\n                              // the frame land where the caller's layout says it\n                              // is. The spare pixels hang off all four edges and\n                              // are clipped by whatever is holding this.\n                              position: \"absolute\",\n                              left: \"50%\",\n                              top: \"50%\",\n                              width: `${surfaceSize.width}px`,\n                              height: `${surfaceSize.height}px`,\n                              transform: \"translate(-50%, -50%)\",\n                          }\n                        : { width: \"100%\", height: \"100%\" }),\n                }}\n            />\n        </div>\n    );\n}\n"],"mappings":"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"}

package/dist/ui/playhead.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The playhead, held outside React.
+ *
+ * A frame number written at clock rate through `useState` re-renders whoever
+ * owns the player, and on a high-refresh display that is faster than the
+ * project's own frame rate. Nothing in a render depends on it: the controller
+ * paints straight onto the canvas and React is not involved. So the number
+ * lives here, and only the components that actually display it subscribe.
+ */
+export interface PlayheadStore {
+    subscribe(onChange: () => void): () => void;
+    getSnapshot(): number;
+    /** @internal — written by the player that owns this store. */
+    set(frame: number): void;
+}
+export declare function createPlayheadStore(): PlayheadStore;
+/**
+ * Subscribe *this* component to the playhead.
+ *
+ * Typed structurally rather than against `Player` so the store and the hook
+ * that reads it don't import each other.
+ */
+export declare function usePlayhead(player: {
+    playhead: PlayheadStore;
+}): number;
+//# sourceMappingURL=playhead.d.ts.map

package/dist/ui/playhead.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playhead.d.ts","sourceRoot":"","sources":["../../src/ui/playhead.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC1B,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IAC5C,WAAW,IAAI,MAAM,CAAC;IACtB,8DAA8D;IAC9D,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,wBAAgB,mBAAmB,IAAI,aAAa,CAiBnD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE;IAAE,QAAQ,EAAE,aAAa,CAAA;CAAE,GAAG,MAAM,CAGvE"}