@motionscript/react 0.1.0 → 0.1.1-alpha.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @motionscript/react
 
+## 0.1.1-alpha.1
+
+## 0.1.1-alpha.0
+
+### Patch Changes
+
+- Updated dependencies [3630b74]
+- Updated dependencies [1c43a37]
+- Updated dependencies [e279864]
+  - @motionscript/core@0.1.1-alpha.0
+
 ## 0.1.0
 
 ## 0.1.0-alpha.10

package/README.md

@@ -84,7 +84,7 @@ it returns in — which is also why nothing in this package imports a platform,
 it works with `@motionscript/browser`'s engine, a headless one, or a test double.
 
 **Create it once and share it.** It holds the renderer and the exporter, so a
-second engine is a second wasm module and a second GL stack. `engine` is
+second engine is a second wasm module and a second renderer. `engine` is
 nullable precisely because building one is async: the player no-ops until it
 arrives, which keeps the hook out of a conditional.
 

package/dist/browser/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/ui/use-engine.ts", "../../src/ui/playhead.ts", "../../src/ui/use-motion-player.ts", "../../src/ui/stage.tsx"],
-  "sourcesContent": ["import { useEffect, useRef, useState, type DependencyList } from \"react\";\n\nimport type { Engine } from \"@motionscript/core\";\n\nexport interface UseEngineOptions {\n    /**\n     * Rebuild the engine when any of these change, compared the way\n     * `useEffect` compares its own. The default, `[]`, builds it once.\n     *\n     * Not for the factory's closure: the latest `create` is always the one\n     * called, so an inline arrow does not rebuild anything. List only what\n     * makes a *different* engine, such as the node types or the wasm URL.\n     */\n    deps?: DependencyList;\n    /** Called when `create` rejects or throws. Defaults to `console.error`. */\n    onError?: (error: unknown) => void;\n}\n\nfunction logError(error: unknown) {\n    console.error(\"Could not start the MotionScript engine.\", error);\n}\n\n/**\n * Builds an engine once, hands it to you when it is ready, and disposes it\n * when it is no longer wanted.\n *\n * ```tsx\n * const engine = useEngine(() => createBrowserEngine());\n * const player = useMotionPlayer({ engine, document: doc });\n * ```\n *\n * `null` until it arrives, which {@link useMotionPlayer} accepts. Nothing in\n * this package imports a platform, so what to build is the factory's job: the\n * browser's `createBrowserEngine`, a headless one, or a test double.\n *\n * Disposal covers the cases a hand-written effect gets wrong: an unmount while\n * the wasm was still loading (StrictMode does this on every mount in\n * development) frees the engine the moment it lands, and a change in `deps`\n * disposes the old one and returns `null` until the new one is ready.\n *\n * Call it once and hand the engine down. A second call is a second wasm module\n * and a second GL stack. Anything that must be true before a player sees the\n * engine, such as `setManifest`, belongs in `create`, not in an effect beside it.\n */\nexport function useEngine<E extends Engine = Engine>(\n    create: () => E | Promise<E>,\n    options: UseEngineOptions = {},\n): E | null {\n    const { deps = [], onError } = options;\n    const [engine, setEngine] = useState<E | null>(null);\n    const createRef = useRef(create);\n    const onErrorRef = useRef(onError);\n\n    useEffect(() => {\n        createRef.current = create;\n        onErrorRef.current = onError;\n    });\n\n    useEffect(() => {\n        let live = true;\n        let built: E | null = null;\n\n        new Promise<E>(resolve => resolve(createRef.current()))\n            .then(next => {\n                built = next;\n                if (!live) {\n                    next.dispose();\n                    return;\n                }\n                setEngine(next);\n            })\n            .catch(error => {\n                if (live) (onErrorRef.current ?? logError)(error);\n            });\n\n        return () => {\n            live = false;\n            built?.dispose();\n            setEngine(null);\n        };\n        // The caller's list, not ours: it is what makes a different engine.\n        // eslint-disable-next-line react-hooks/exhaustive-deps\n    }, deps);\n\n    return engine;\n}\n", "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 { clipTimeToFrame, DEFAULT_FPS, DEFAULT_VIEWPORT, isProjectDocument } from \"@motionscript/core\";\n\nimport type {\n    BuildError,\n    Engine,\n    NodeBox,\n    NodeHandle,\n    Node3DFrame,\n    NodeOverride,\n    NodeState,\n    NodeTextLayout,\n    PlaybackController,\n    AssetTimelineResult,\n    ProjectDocument,\n    ReparentPlacement,\n    VisualDocument,\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/**\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\n/**\n * Sessions this hook has disposed. React can replay a child's effects with the\n * `session` it last rendered after this hook's cleanup has run — a suspended\n * boundary being revealed, StrictMode's dev replay — so a stage asks here\n * before binding to the one it was handed.\n */\nconst disposedSessions = new WeakSet<Session>();\n\n/** @internal Whether `session` was disposed by a player. Not exported from the package. */\nexport function isSessionDisposed(session: Session): boolean {\n    return disposedSessions.has(session);\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 gets it from {@link useEngine}\n     * and it is `null` for the first render or two. The player no-ops until it\n     * arrives, which is what keeps the hook out of a conditional.\n     *\n     * **Create it once, and share it.** It holds the renderer 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 renderer, 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 | VisualDocument;\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    /** The node's props before any command has acted on it: the same at every frame, and answered while it is off screen. */\n    getNodeInitialProps(nodeId: string): NodeState[\"properties\"] | 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    /**\n     * Where `point` lands in the coordinates the node at `path` positions its\n     * children in (a graph's units), or `null` when those are pixels: the\n     * `x`/`y` to give a node dropped or pasted there.\n     */\n    childPlanePoint(path: string, point: Vector2): Vector2 | null;\n    /**\n     * What keeps the node at `path` looking as it does once it moves under the\n     * node at `parentPath`: `offsets` (`x`/`y` values it takes under its parent\n     * now) as the ones that put it at the same place there, and the turn to add\n     * and the factor to scale by. `null` when that parent arranges its children\n     * itself.\n     */\n    reparentPlacement(path: string, parentPath: string, offsets: readonly Vector2[]): ReparentPlacement | null;\n    /** The points an editor may drag on the node at `path` (an arrow's ends), in viewport space. */\n    nodeHandles(path: string): NodeHandle[] | null;\n    /** The value of `prop` that puts its handle under `point`, or `null`. */\n    handleValue(path: string, prop: 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 ?? DEFAULT_VIEWPORT;\n    const fps = projectDoc?.fps ?? options.fps ?? engine?.fps ?? DEFAULT_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    const speedRef = useRef(speed);\n    /**\n     * What the transport has been told to do, ahead of the next render. State\n     * only shows the last value a batch settled on, and the controller is\n     * driven by the calls that were made, so the two can disagree inside one\n     * batch (`seek` then `play`).\n     */\n    const playingRef = useRef(false);\n\n    useEffect(() => {\n        onFramePaintedRef.current = onFramePainted;\n        loopRef.current = loop;\n        fpsRef.current = fps;\n        speedRef.current = speed;\n        playingRef.current = isPlaying;\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): Promise<boolean> => {\n        const pc = controllerRef.current;\n        if (!pc) return Promise.resolve(false);\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        // Resolves `true` when this was still the newest seek as it landed.\n        return pc.seek(clamped).then(() => {\n            const newest = token === seekTokenRef.current;\n            if (newest) setLoading(false);\n            return newest;\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.floor(clipTimeToFrame(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 {\n                playingRef.current = false;\n                setIsPlaying(false);\n            }\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            disposedSessions.add(opened);\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 renderer, 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    //\n    // A seek pauses the clock, and the clock effect above has already started\n    // this session, so a player that was playing resumes once the park lands\n    // (with its assets loaded, so the first ticks draw rather than catch up). It\n    // does not if the transport moved meanwhile: a newer seek, or a pause.\n    useEffect(() => {\n        const pc = controllerRef.current;\n        if (!pc) return;\n        const wasPlaying = playingRef.current;\n        const parked = seekTo(playhead.getSnapshot());\n        if (!wasPlaying) return;\n        void parked.then(newest => {\n            if (!newest || controllerRef.current !== pc || !playingRef.current || pc.isPlaying) return;\n            pc.play(speedRef.current);\n        });\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            playingRef.current = false;\n            setIsPlaying(false);\n            void seekTo(frame);\n        };\n\n        return {\n            playhead,\n            // Both drive the controller as well as the state. In one batch a\n            // `seek` and a `play` cancel out in state (`true`, `false`, `true`\n            // while playing), so the effect on `isPlaying` never re-runs, yet the\n            // seek has already paused the clock; the state is the settled\n            // answer and the controller is what was actually asked.\n            play: () => {\n                playingRef.current = true;\n                setIsPlaying(true);\n                const pc = controllerRef.current;\n                if (pc && !pc.isPlaying) pc.play(speedRef.current);\n            },\n            pause: () => {\n                playingRef.current = false;\n                setIsPlaying(false);\n                controllerRef.current?.pause();\n            },\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            getNodeInitialProps: (nodeId: string) => controllerRef.current?.getNodeInitialProps(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            childPlanePoint: (path: string, point: Vector2) =>\n                controllerRef.current?.childPlanePoint(path, point) ?? null,\n            reparentPlacement: (path: string, parentPath: string, offsets: readonly Vector2[]) =>\n                controllerRef.current?.reparentPlacement(path, parentPath, offsets) ?? null,\n            nodeHandles: (path: string) => controllerRef.current?.nodeHandles(path) ?? null,\n            handleValue: (path: string, prop: string, point: Vector2) =>\n                controllerRef.current?.handleValue(path, prop, 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 { isSessionDisposed, 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 GPU 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 } = player;\n    // The session's own size, not the player's: the player's moves a commit\n    // ahead, in the commit whose cleanup disposes the old session, and a buffer\n    // resized there would re-bind that disposed session.\n    const viewport = session?.viewport ?? player.viewport;\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 the renderer 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 GPU 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 the renderer 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        // A replayed effect can hold a session its player has since disposed.\n        if (!session || !canvas || !ctx || isSessionDisposed(session)) 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 || isSessionDisposed(session)) 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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",
+  "sourcesContent": ["import { useEffect, useRef, useState, type DependencyList } from \"react\";\n\nimport type { Engine } from \"@motionscript/core\";\n\nexport interface UseEngineOptions {\n    /**\n     * Rebuild the engine when any of these change, compared as `useEffect` does.\n     * The default, `[]`, builds it once. List only what makes a *different*\n     * engine (node types, the wasm URL): the latest `create` is always the one\n     * called, so its closure is not a dependency.\n     */\n    deps?: DependencyList;\n    /** Called when `create` rejects or throws. Defaults to `console.error`. */\n    onError?: (error: unknown) => void;\n}\n\nfunction logError(error: unknown) {\n    console.error(\"Could not start the MotionScript engine.\", error);\n}\n\n/**\n * Builds an engine once, `null` until it arrives, and disposes it when it is no\n * longer wanted. What to build is the factory's job: nothing here imports a\n * platform.\n *\n * ```tsx\n * const engine = useEngine(() => createBrowserEngine());\n * const player = useMotionPlayer({ engine, document: doc });\n * ```\n *\n * An unmount while the factory was still pending (StrictMode does this on every\n * dev mount) frees the engine the moment it lands; a change in `deps` disposes\n * the old one and returns `null` until the new one is ready.\n *\n * Call it once and hand the engine down: a second call is a second wasm module\n * and renderer. Anything that must hold before a player sees the engine, such as\n * `setManifest`, belongs in `create`, not in an effect beside it.\n */\nexport function useEngine<E extends Engine = Engine>(\n    create: () => E | Promise<E>,\n    options: UseEngineOptions = {},\n): E | null {\n    const { deps = [], onError } = options;\n    const [engine, setEngine] = useState<E | null>(null);\n    const createRef = useRef(create);\n    const onErrorRef = useRef(onError);\n\n    useEffect(() => {\n        createRef.current = create;\n        onErrorRef.current = onError;\n    });\n\n    useEffect(() => {\n        let live = true;\n        let built: E | null = null;\n\n        new Promise<E>(resolve => resolve(createRef.current()))\n            .then(next => {\n                built = next;\n                if (!live) {\n                    next.dispose();\n                    return;\n                }\n                setEngine(next);\n            })\n            .catch(error => {\n                if (live) (onErrorRef.current ?? logError)(error);\n            });\n\n        return () => {\n            live = false;\n            built?.dispose();\n            setEngine(null);\n        };\n        // The caller's list, not ours: it is what makes a different engine.\n        // eslint-disable-next-line react-hooks/exhaustive-deps\n    }, deps);\n\n    return engine;\n}\n", "import { useSyncExternalStore } from \"react\";\n\n/**\n * The playhead, held outside React: a frame written at clock rate through\n * `useState` would re-render the player's owner faster than the project's frame\n * rate, and nothing in a render depends on it (the controller paints straight\n * onto the canvas). Only components that 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/** Subscribe *this* component to the playhead. Takes `{ playhead }` rather than `Player` to avoid an import cycle with `use-motion-player`. */\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 { clipTimeToFrame, DEFAULT_FPS, DEFAULT_VIEWPORT, isProjectDocument } from \"@motionscript/core\";\n\nimport type {\n    BuildError,\n    Engine,\n    NodeBox,\n    NodeHandle,\n    Node3DFrame,\n    NodeOverride,\n    NodeState,\n    NodeTextLayout,\n    PlaybackController,\n    AssetTimelineResult,\n    ProjectDocument,\n    ReparentPlacement,\n    VisualDocument,\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/** Background asset discovery: only frame-0 tracks are discovered before mount, the rest stream in. The timeline's length never waits on it. */\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\n/**\n * Sessions this hook has disposed. React can replay a child's effects with the\n * `session` it last rendered after this hook's cleanup ran (a suspended\n * boundary revealed, StrictMode), so a stage asks here before binding.\n */\nconst disposedSessions = new WeakSet<Session>();\n\n/** @internal Not exported from the package. */\nexport function isSessionDisposed(session: Session): boolean {\n    return disposedSessions.has(session);\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. Nullable because building one\n     * is async ({@link useEngine}): the player no-ops until it arrives.\n     *\n     * Create it once and share it: it holds the renderer and the exporter, so a\n     * fresh one per render rebuilds the renderer behind every player on it.\n     * Compared by identity; a different engine is a full rebuild.\n     */\n    engine: Engine | null | undefined;\n    /**\n     * What to play; nothing opens until there is one. A project document carries\n     * its own viewport, fps, theme and tracks; a scene document (still or\n     * composition) carries none, so `viewport` and `fps` come from here or the\n     * engine.\n     *\n     * Content-diffed, identity first: a new document is reconciled onto the\n     * running session, each track patched in place and rebuilt only when it\n     * cannot be. Treat documents as immutable: an in-place edit is not seen.\n     *\n     * A new document keeps the player's place (the playhead is clamped to a\n     * shorter timeline, playback carries on). Seek or pause yourself when a swap\n     * means \"start over\".\n     */\n    document?: ProjectDocument | VisualDocument;\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 has\n     * been painted (clock, seek or document swap).\n     *\n     * Not the playhead, which reports where the clock is: a seek is async, so the\n     * number can move before the canvas does. Use it to keep an overlay in step\n     * with the pixels, and keep it cheap: it runs on the render loop. Read through\n     * a ref, so changing it costs nothing.\n     */\n    onFramePainted?: (frame: number) => void;\n}\n\n/** A document's transport and its session, with no DOM. Two calls to {@link useMotionPlayer} share only the engine. */\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    /** Pauses, then seeks. 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    /** The node's props before any command has acted on it: the same at every frame, and answered while it is off screen. */\n    getNodeInitialProps(nodeId: string): NodeState[\"properties\"] | 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    // Points below 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    /**\n     * Where `point` lands in the coordinates the node at `path` positions its\n     * children in (a graph's units), or `null` when those are pixels: the\n     * `x`/`y` to give a node dropped or pasted there.\n     */\n    childPlanePoint(path: string, point: Vector2): Vector2 | null;\n    /**\n     * What keeps the node at `path` looking as it does once it moves under the\n     * node at `parentPath`: `offsets` (`x`/`y` values it takes under its parent\n     * now) as the ones that put it at the same place there, and the turn to add\n     * and the factor to scale by. `null` when that parent arranges its children\n     * itself.\n     */\n    reparentPlacement(path: string, parentPath: string, offsets: readonly Vector2[]): ReparentPlacement | null;\n    /** The points an editor may drag on the node at `path` (an arrow's ends), in viewport space. */\n    nodeHandles(path: string): NodeHandle[] | null;\n    /** The value of `prop` that puts its handle under `point`, or `null`. */\n    handleValue(path: string, prop: 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    // Document, then options, then engine. Resolved during render, before any\n    // session exists, so a stage can size its canvas on the first pass.\n    const projectDoc = document && isProjectDocument(document) ? document : undefined;\n    const resolvedViewport = projectDoc?.viewport ?? options.viewport ?? engine?.viewport ?? DEFAULT_VIEWPORT;\n    const fps = projectDoc?.fps ?? options.fps ?? engine?.fps ?? DEFAULT_FPS;\n\n    // Held by size: a host that rebuilds its document per edit would otherwise\n    // 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    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    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    const speedRef = useRef(speed);\n    /**\n     * What the transport was told to do, ahead of the next render. State shows\n     * only the last value a batch settled on, so it can disagree with the\n     * controller inside one batch (`seek` then `play`).\n     */\n    const playingRef = useRef(false);\n\n    useEffect(() => {\n        onFramePaintedRef.current = onFramePainted;\n        loopRef.current = loop;\n        fpsRef.current = fps;\n        speedRef.current = speed;\n        playingRef.current = isPlaying;\n    });\n\n    // An edit keeps the transport and errors (the reconcile effect re-reads both,\n    // so an unfixed error never blinks out); only losing the document stops it,\n    // during render 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    /** Pulls duration, errors and progress off the controller, keeping what did not change: a fresh array or object is a new `Player` on every edit. */\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    /** One instance, so the transport, the reconcile effect and a session's first paint share one seek discipline. */\n    const [seekTo] = useState(() => (frame: number): Promise<boolean> => {\n        const pc = controllerRef.current;\n        if (!pc) return Promise.resolve(false);\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        // A superseded seek still resolves (its generation guard bailed in the\n        // controller) but never painted, so only the newest may clear `loading`:\n        // consumers pace scrubbing off that edge.\n        const token = ++seekTokenRef.current;\n        setLoading(true);\n        return pc.seek(clamped).then(() => {\n            const newest = token === seekTokenRef.current;\n            if (newest) setLoading(false);\n            return newest;\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 afterwards, so this hook owns no 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.floor(clipTimeToFrame(t, fpsRef.current));\n            playhead.set(frame);\n\n            // Asks the controller: a swap can change the length after 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 {\n                playingRef.current = false;\n                setIsPlaying(false);\n            }\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            disposedSessions.add(opened);\n            opened.dispose();\n        };\n        // `document` is deliberately absent (only whether there is one): the effect\n        // below reconciles a new one onto the live session. Everything listed\n        // needs a rebuild: a different engine is a different renderer, and a live\n        // surface cannot change 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 running session. Skipped on the pass\n    // that opened it, which already holds this document.\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` paints the current frame once its assets load, and a\n        // 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    // Parks a new session on the frame the playhead holds, so a rebuild keeps its\n    // place. The seek pauses the clock the effect above just started, so a player\n    // that was playing resumes once the park lands (assets loaded, so the first\n    // ticks draw rather than catch up), unless a newer seek or a pause moved the\n    // transport meanwhile.\n    useEffect(() => {\n        const pc = controllerRef.current;\n        if (!pc) return;\n        const wasPlaying = playingRef.current;\n        const parked = seekTo(playhead.getSnapshot());\n        if (!wasPlaying) return;\n        void parked.then(newest => {\n            if (!newest || controllerRef.current !== pc || !playingRef.current || pc.isPlaying) return;\n            pc.play(speedRef.current);\n        });\n    }, [session, playhead, seekTo]);\n\n    // Built once: every action reads the controller through a ref, so a re-render\n    // never invalidates a handler a child holds.\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            playingRef.current = false;\n            setIsPlaying(false);\n            void seekTo(frame);\n        };\n\n        return {\n            playhead,\n            // Both drive the controller as well as state: in one batch a `seek` and\n            // a `play` cancel out in state, so the `isPlaying` effect never re-runs\n            // though the seek already paused the clock.\n            play: () => {\n                playingRef.current = true;\n                setIsPlaying(true);\n                const pc = controllerRef.current;\n                if (pc && !pc.isPlaying) pc.play(speedRef.current);\n            },\n            pause: () => {\n                playingRef.current = false;\n                setIsPlaying(false);\n                controllerRef.current?.pause();\n            },\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            getNodeInitialProps: (nodeId: string) => controllerRef.current?.getNodeInitialProps(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            childPlanePoint: (path: string, point: Vector2) =>\n                controllerRef.current?.childPlanePoint(path, point) ?? null,\n            reparentPlacement: (path: string, parentPath: string, offsets: readonly Vector2[]) =>\n                controllerRef.current?.reparentPlacement(path, parentPath, offsets) ?? null,\n            nodeHandles: (path: string) => controllerRef.current?.nodeHandles(path) ?? null,\n            handleValue: (path: string, prop: string, point: Vector2) =>\n                controllerRef.current?.handleValue(path, prop, 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 { isSessionDisposed, type Player } from \"./use-motion-player\";\n\n/** Core compiles without the DOM lib, so `RenderSurface.mount` takes `unknown`; narrowed here, where `HTMLCanvasElement` exists. */\ntype StageRenderContext = Omit<EngineRenderContext, \"mount\"> & {\n    mount(canvas: HTMLCanvasElement): void;\n};\n\nconst IDENTITY_VIEW = Object.freeze({ zoom: 1, x: 0, y: 0 });\n\nexport interface MotionStageProps {\n    player: Player;\n    /**\n     * Device pixels rasterized per viewport unit. Defaults to `1`. Not a zoom or\n     * a crop: the scene's coordinate space is unchanged and CSS scales the canvas\n     * back to its box. `<1` suits a preview shown far smaller than the output size.\n     *\n     * Every change re-creates the GPU surface, dropping texture-backed images\n     * (decoded video frames, 3D composites; they re-upload on demand), so quantize\n     * to a few steps and never drive it from a resize observer. Prefer scales that\n     * keep both dimensions whole: `pixelRatio` is one number, so uneven rounding\n     * shifts the frame's centre by up to half a device pixel.\n     *\n     * `player.screenshot()` returns the surface's size, so it is scaled too.\n     */\n    renderScale?: number;\n    /**\n     * The canvas's own size in CSS pixels, when it is not the frame. Omitted, the\n     * canvas is the frame: `viewport × renderScale`, stretched over its box.\n     *\n     * Supplied together with {@link view}, the canvas becomes a window onto the\n     * frame: it takes the size of the area shown, `renderScale` means device\n     * pixels per CSS pixel, and only what is on screen is rasterized, so zooming\n     * in stays sharp. It re-creates the surface like `renderScale`: quantize it.\n     */\n    surfaceSize?: Size2D;\n    /**\n     * Pan and zoom applied to the render itself; requires {@link surfaceSize}.\n     * `zoom` multiplies scene units; `x`/`y` offset the frame's centre in CSS\n     * pixels, positive `y` downwards (a CSS translate).\n     *\n     * A change costs a repaint and nothing else. A CSS transform could not add\n     * 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. Requires {@link surfaceSize} and\n     * {@link view}. Defaults to `true`; off lets a node parked past the edge\n     * rasterize into the rest of the surface.\n     */\n    clipToFrame?: boolean;\n    /**\n     * Defaults to `\"black\"`. `\"transparent\"` leaves undrawn frame pixels\n     * unpainted so the host's backdrop (a checkerboard) shows through. Requires\n     * {@link surfaceSize} and {@link view}.\n     */\n    frameBackground?: \"black\" | \"transparent\";\n    className?: string;\n    style?: CSSProperties;\n}\n\n/**\n * A canvas bound to a {@link Player}'s session. One stage per player: a session\n * drives one surface, and a second stage would take it 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 } = player;\n    // The session's own size, not the player's: the player's moves a commit\n    // ahead, in the commit whose cleanup disposes the old session, and a buffer\n    // resized there would re-bind that disposed session.\n    const viewport = session?.viewport ?? player.viewport;\n\n    // Floored at 1: a zero-sized surface fails creation outright.\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    // Without both `surfaceSize` and `view` the canvas is the frame, so all four revert to defaults.\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    // A ref because the context is mutable external state whose knobs are\n    // written; writing through the `player` prop trips the immutability lint.\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    // Bind the surface and rebuild it when the backing store changes. An effect,\n    // not a callback, because React has written the canvas's new `width`/`height`\n    // by the time effects run and the renderer reads them when it builds the\n    // surface: mounting before the resize would build the previous size.\n    // `repaint()` because a new surface starts blank and a paused clock would not\n    // fill it.\n    useEffect(() => {\n        const canvas = canvasRef.current;\n        const ctx = ctxRef.current;\n        // A replayed effect can hold a session its player has since disposed.\n        if (!session || !canvas || !ctx || isSessionDisposed(session)) 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        // Detaches the old surface first, which drops the texture-backed images\n        // that belong to it.\n        ctx.mount(canvas);\n        session.controller.repaint();\n    }, [session, renderScale, bufferWidth, bufferHeight]);\n\n    // Keyed on the view's fields, not the object: callers pass a fresh\n    // `{zoom, x, y}` every render, which would repaint every render.\n    useEffect(() => {\n        const ctx = ctxRef.current;\n        if (!session || !ctx || isSessionDisposed(session)) 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                width={bufferWidth}\n                height={bufferHeight}\n                style={{\n                    display: session ? \"block\" : \"none\",\n                    ...(surfaceSize\n                        ? {\n                              // `surfaceSize` is honoured literally, not stretched\n                              // to the box: it is quantized, so it is usually a\n                              // little larger than the box and a different shape,\n                              // and stretching would squash one axis.\n                              //\n                              // Centred because `executePass` puts the scene origin\n                              // at the surface's centre, so this lands the frame\n                              // where the layout says; the spare pixels hang off\n                              // all four edges and the parent clips them.\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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",
   "names": ["logError", "error", "useEngine", "create", "options", "deps", "onError", "engine", "setEngine", "useState", "createRef", "useRef", "onErrorRef", "useEffect", "live", "built", "resolve", "next", "createPlayheadStore", "frame", "listeners", "onChange", "notify", "usePlayhead", "player", "playhead", "useSyncExternalStore", "disposedSessions", "isSessionDisposed", "session", "INITIAL_PRECOMP", "NO_ERRORS", "precompProgressOf", "result", "track", "samePrecomp", "a", "b", "sameErrors", "i", "other", "errorsFrom", "reported", "held", "useMotionPlayer", "document", "onFramePainted", "projectDoc", "isProjectDocument", "resolvedViewport", "DEFAULT_VIEWPORT", "fps", "DEFAULT_FPS", "viewport", "setViewport", "hasDocument", "setSession", "isPlaying", "setIsPlaying", "speed", "setSpeedState", "muted", "setMutedState", "loop", "setLoopState", "loading", "setLoading", "duration", "setDuration", "errors", "setErrors", "precomp", "setPrecomp", "totalFrames", "controllerRef", "sessionRef", "documentRef", "onFramePaintedRef", "seekTokenRef", "loopRef", "fpsRef", "speedRef", "playingRef", "prevDocument", "setPrevDocument", "sync", "useCallback", "pc", "progress", "seekTo", "last", "clamped", "token", "newest", "opened", "errs", "t", "clipTimeToFrame", "wasPlaying", "parked", "actions", "seek", "playing", "delta", "nodeId", "path", "parentPoints", "localPoints", "point", "parentPath", "offsets", "prop", "tolerance", "props", "useMemo", "IDENTITY_VIEW", "MotionStage", "renderScale", "surfaceSize", "view", "clipToFrame", "frameBackground", "className", "style", "canvasRef", "bufferWidth", "bufferHeight", "activeView", "activeFrame", "activeClipToFrame", "activeFrameBackground", "viewRef", "frameRectRef", "clipToFrameRef", "frameBackgroundRef", "ctxRef", "canvas", "ctx", "jsx"]
 }

package/dist/browser/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionscript/react",
-  "version": "0.1.0-alpha.10",
+  "version": "0.1.1-alpha.0",
   "exports": {
     ".": "dist/browser/index.js"
   },

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,YAAY,EAAE,mBAAmB,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC3F,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,YAAY,EAAE,mBAAmB,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC3F,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/motionscript-react.js

@@ -6,26 +6,22 @@ function logError(error) {
 	console.error("Could not start the MotionScript engine.", error);
 }
 /**
-* Builds an engine once, hands it to you when it is ready, and disposes it
-* when it is no longer wanted.
+* Builds an engine once, `null` until it arrives, and disposes it when it is no
+* longer wanted. What to build is the factory's job: nothing here imports a
+* platform.
 *
 * ```tsx
 * const engine = useEngine(() => createBrowserEngine());
 * const player = useMotionPlayer({ engine, document: doc });
 * ```
 *
-* `null` until it arrives, which {@link useMotionPlayer} accepts. Nothing in
-* this package imports a platform, so what to build is the factory's job: the
-* browser's `createBrowserEngine`, a headless one, or a test double.
+* An unmount while the factory was still pending (StrictMode does this on every
+* dev mount) frees the engine the moment it lands; a change in `deps` disposes
+* the old one and returns `null` until the new one is ready.
 *
-* Disposal covers the cases a hand-written effect gets wrong: an unmount while
-* the wasm was still loading (StrictMode does this on every mount in
-* development) frees the engine the moment it lands, and a change in `deps`
-* disposes the old one and returns `null` until the new one is ready.
-*
-* Call it once and hand the engine down. A second call is a second wasm module
-* and a second GL stack. Anything that must be true before a player sees the
-* engine, such as `setManifest`, belongs in `create`, not in an effect beside it.
+* Call it once and hand the engine down: a second call is a second wasm module
+* and renderer. Anything that must hold before a player sees the engine, such as
+* `setManifest`, belongs in `create`, not in an effect beside it.
 */
 function useEngine(create, options = {}) {
 	const { deps = [], onError } = options;
@@ -77,12 +73,7 @@ function createPlayheadStore() {
 		}
 	};
 }
-/**
-* 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.
-*/
+/** Subscribe *this* component to the playhead. Takes `{ playhead }` rather than `Player` to avoid an import cycle with `use-motion-player`. */
 function usePlayhead(player) {
 	const { playhead } = player;
 	return useSyncExternalStore(playhead.subscribe, playhead.getSnapshot, playhead.getSnapshot);
@@ -91,12 +82,11 @@ function usePlayhead(player) {
 //#region src/ui/use-motion-player.ts
 /**
 * Sessions this hook has disposed. React can replay a child's effects with the
-* `session` it last rendered after this hook's cleanup has run — a suspended
-* boundary being revealed, StrictMode's dev replay — so a stage asks here
-* before binding to the one it was handed.
+* `session` it last rendered after this hook's cleanup ran (a suspended
+* boundary revealed, StrictMode), so a stage asks here before binding.
 */
 var disposedSessions = /* @__PURE__ */ new WeakSet();
-/** @internal Whether `session` was disposed by a player. Not exported from the package. */
+/** @internal Not exported from the package. */
 function isSessionDisposed(session) {
 	return disposedSessions.has(session);
 }
@@ -144,7 +134,6 @@ function useMotionPlayer(options) {
 	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);
@@ -166,10 +155,9 @@ function useMotionPlayer(options) {
 	const fpsRef = useRef(fps);
 	const speedRef = useRef(speed);
 	/**
-	* What the transport has been told to do, ahead of the next render. State
-	* only shows the last value a batch settled on, and the controller is
-	* driven by the calls that were made, so the two can disagree inside one
-	* batch (`seek` then `play`).
+	* What the transport was told to do, ahead of the next render. State shows
+	* only the last value a batch settled on, so it can disagree with the
+	* controller inside one batch (`seek` then `play`).
 	*/
 	const playingRef = useRef(false);
 	useEffect(() => {
@@ -188,23 +176,14 @@ function useMotionPlayer(options) {
 			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.
-	*/
+	/** Pulls duration, errors and progress off the controller, keeping what did not change: a fresh array or object is a new `Player` 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.
-	*/
+	/** One instance, so the transport, the reconcile effect and a session's first paint share one seek discipline. */
 	const [seekTo] = useState(() => (frame) => {
 		const pc = controllerRef.current;
 		if (!pc) return Promise.resolve(false);
@@ -398,44 +377,21 @@ function useMotionPlayer(options) {
 }
 //#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.
+* A canvas bound to a {@link Player}'s session. One stage per player: a session
+* drives one surface, and a second stage would take it from the first.
 */
 function MotionStage({ player, renderScale = 1, surfaceSize, view, clipToFrame, frameBackground, className, style }) {
 	const canvasRef = useRef(null);
 	const { session } = player;
 	const viewport = session?.viewport ?? player.viewport;
-	/**
-	* 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 the renderer 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;
@@ -444,14 +400,6 @@ function MotionStage({ player, renderScale = 1, surfaceSize, view, clipToFrame,
 	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 GPU 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;
@@ -460,19 +408,6 @@ function MotionStage({ player, renderScale = 1, surfaceSize, view, clipToFrame,
 		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 the renderer 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;
@@ -490,13 +425,6 @@ function MotionStage({ player, renderScale = 1, surfaceSize, view, clipToFrame,
 		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 || isSessionDisposed(session)) return;

package/dist/motionscript-react.js.map

@@ -1 +1 @@
-{"version":3,"file":"motionscript-react.js","names":[],"sources":["../src/ui/use-engine.ts","../src/ui/playhead.ts","../src/ui/use-motion-player.ts","../src/ui/stage.tsx"],"sourcesContent":["import { useEffect, useRef, useState, type DependencyList } from \"react\";\n\nimport type { Engine } from \"@motionscript/core\";\n\nexport interface UseEngineOptions {\n    /**\n     * Rebuild the engine when any of these change, compared the way\n     * `useEffect` compares its own. The default, `[]`, builds it once.\n     *\n     * Not for the factory's closure: the latest `create` is always the one\n     * called, so an inline arrow does not rebuild anything. List only what\n     * makes a *different* engine, such as the node types or the wasm URL.\n     */\n    deps?: DependencyList;\n    /** Called when `create` rejects or throws. Defaults to `console.error`. */\n    onError?: (error: unknown) => void;\n}\n\nfunction logError(error: unknown) {\n    console.error(\"Could not start the MotionScript engine.\", error);\n}\n\n/**\n * Builds an engine once, hands it to you when it is ready, and disposes it\n * when it is no longer wanted.\n *\n * ```tsx\n * const engine = useEngine(() => createBrowserEngine());\n * const player = useMotionPlayer({ engine, document: doc });\n * ```\n *\n * `null` until it arrives, which {@link useMotionPlayer} accepts. Nothing in\n * this package imports a platform, so what to build is the factory's job: the\n * browser's `createBrowserEngine`, a headless one, or a test double.\n *\n * Disposal covers the cases a hand-written effect gets wrong: an unmount while\n * the wasm was still loading (StrictMode does this on every mount in\n * development) frees the engine the moment it lands, and a change in `deps`\n * disposes the old one and returns `null` until the new one is ready.\n *\n * Call it once and hand the engine down. A second call is a second wasm module\n * and a second GL stack. Anything that must be true before a player sees the\n * engine, such as `setManifest`, belongs in `create`, not in an effect beside it.\n */\nexport function useEngine<E extends Engine = Engine>(\n    create: () => E | Promise<E>,\n    options: UseEngineOptions = {},\n): E | null {\n    const { deps = [], onError } = options;\n    const [engine, setEngine] = useState<E | null>(null);\n    const createRef = useRef(create);\n    const onErrorRef = useRef(onError);\n\n    useEffect(() => {\n        createRef.current = create;\n        onErrorRef.current = onError;\n    });\n\n    useEffect(() => {\n        let live = true;\n        let built: E | null = null;\n\n        new Promise<E>(resolve => resolve(createRef.current()))\n            .then(next => {\n                built = next;\n                if (!live) {\n                    next.dispose();\n                    return;\n                }\n                setEngine(next);\n            })\n            .catch(error => {\n                if (live) (onErrorRef.current ?? logError)(error);\n            });\n\n        return () => {\n            live = false;\n            built?.dispose();\n            setEngine(null);\n        };\n        // The caller's list, not ours: it is what makes a different engine.\n        // eslint-disable-next-line react-hooks/exhaustive-deps\n    }, deps);\n\n    return engine;\n}\n","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 { clipTimeToFrame, DEFAULT_FPS, DEFAULT_VIEWPORT, isProjectDocument } from \"@motionscript/core\";\n\nimport type {\n    BuildError,\n    Engine,\n    NodeBox,\n    NodeHandle,\n    Node3DFrame,\n    NodeOverride,\n    NodeState,\n    NodeTextLayout,\n    PlaybackController,\n    AssetTimelineResult,\n    ProjectDocument,\n    ReparentPlacement,\n    VisualDocument,\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/**\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\n/**\n * Sessions this hook has disposed. React can replay a child's effects with the\n * `session` it last rendered after this hook's cleanup has run — a suspended\n * boundary being revealed, StrictMode's dev replay — so a stage asks here\n * before binding to the one it was handed.\n */\nconst disposedSessions = new WeakSet<Session>();\n\n/** @internal Whether `session` was disposed by a player. Not exported from the package. */\nexport function isSessionDisposed(session: Session): boolean {\n    return disposedSessions.has(session);\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 gets it from {@link useEngine}\n     * and it is `null` for the first render or two. The player no-ops until it\n     * arrives, which is what keeps the hook out of a conditional.\n     *\n     * **Create it once, and share it.** It holds the renderer 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 renderer, 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 | VisualDocument;\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    /** The node's props before any command has acted on it: the same at every frame, and answered while it is off screen. */\n    getNodeInitialProps(nodeId: string): NodeState[\"properties\"] | 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    /**\n     * Where `point` lands in the coordinates the node at `path` positions its\n     * children in (a graph's units), or `null` when those are pixels: the\n     * `x`/`y` to give a node dropped or pasted there.\n     */\n    childPlanePoint(path: string, point: Vector2): Vector2 | null;\n    /**\n     * What keeps the node at `path` looking as it does once it moves under the\n     * node at `parentPath`: `offsets` (`x`/`y` values it takes under its parent\n     * now) as the ones that put it at the same place there, and the turn to add\n     * and the factor to scale by. `null` when that parent arranges its children\n     * itself.\n     */\n    reparentPlacement(path: string, parentPath: string, offsets: readonly Vector2[]): ReparentPlacement | null;\n    /** The points an editor may drag on the node at `path` (an arrow's ends), in viewport space. */\n    nodeHandles(path: string): NodeHandle[] | null;\n    /** The value of `prop` that puts its handle under `point`, or `null`. */\n    handleValue(path: string, prop: 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 ?? DEFAULT_VIEWPORT;\n    const fps = projectDoc?.fps ?? options.fps ?? engine?.fps ?? DEFAULT_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    const speedRef = useRef(speed);\n    /**\n     * What the transport has been told to do, ahead of the next render. State\n     * only shows the last value a batch settled on, and the controller is\n     * driven by the calls that were made, so the two can disagree inside one\n     * batch (`seek` then `play`).\n     */\n    const playingRef = useRef(false);\n\n    useEffect(() => {\n        onFramePaintedRef.current = onFramePainted;\n        loopRef.current = loop;\n        fpsRef.current = fps;\n        speedRef.current = speed;\n        playingRef.current = isPlaying;\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): Promise<boolean> => {\n        const pc = controllerRef.current;\n        if (!pc) return Promise.resolve(false);\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        // Resolves `true` when this was still the newest seek as it landed.\n        return pc.seek(clamped).then(() => {\n            const newest = token === seekTokenRef.current;\n            if (newest) setLoading(false);\n            return newest;\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.floor(clipTimeToFrame(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 {\n                playingRef.current = false;\n                setIsPlaying(false);\n            }\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            disposedSessions.add(opened);\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 renderer, 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    //\n    // A seek pauses the clock, and the clock effect above has already started\n    // this session, so a player that was playing resumes once the park lands\n    // (with its assets loaded, so the first ticks draw rather than catch up). It\n    // does not if the transport moved meanwhile: a newer seek, or a pause.\n    useEffect(() => {\n        const pc = controllerRef.current;\n        if (!pc) return;\n        const wasPlaying = playingRef.current;\n        const parked = seekTo(playhead.getSnapshot());\n        if (!wasPlaying) return;\n        void parked.then(newest => {\n            if (!newest || controllerRef.current !== pc || !playingRef.current || pc.isPlaying) return;\n            pc.play(speedRef.current);\n        });\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            playingRef.current = false;\n            setIsPlaying(false);\n            void seekTo(frame);\n        };\n\n        return {\n            playhead,\n            // Both drive the controller as well as the state. In one batch a\n            // `seek` and a `play` cancel out in state (`true`, `false`, `true`\n            // while playing), so the effect on `isPlaying` never re-runs, yet the\n            // seek has already paused the clock; the state is the settled\n            // answer and the controller is what was actually asked.\n            play: () => {\n                playingRef.current = true;\n                setIsPlaying(true);\n                const pc = controllerRef.current;\n                if (pc && !pc.isPlaying) pc.play(speedRef.current);\n            },\n            pause: () => {\n                playingRef.current = false;\n                setIsPlaying(false);\n                controllerRef.current?.pause();\n            },\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            getNodeInitialProps: (nodeId: string) => controllerRef.current?.getNodeInitialProps(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            childPlanePoint: (path: string, point: Vector2) =>\n                controllerRef.current?.childPlanePoint(path, point) ?? null,\n            reparentPlacement: (path: string, parentPath: string, offsets: readonly Vector2[]) =>\n                controllerRef.current?.reparentPlacement(path, parentPath, offsets) ?? null,\n            nodeHandles: (path: string) => controllerRef.current?.nodeHandles(path) ?? null,\n            handleValue: (path: string, prop: string, point: Vector2) =>\n                controllerRef.current?.handleValue(path, prop, 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 { isSessionDisposed, 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 GPU 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 } = player;\n    // The session's own size, not the player's: the player's moves a commit\n    // ahead, in the commit whose cleanup disposes the old session, and a buffer\n    // resized there would re-bind that disposed session.\n    const viewport = session?.viewport ?? player.viewport;\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 the renderer 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 GPU 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 the renderer 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        // A replayed effect can hold a session its player has since disposed.\n        if (!session || !canvas || !ctx || isSessionDisposed(session)) 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 || isSessionDisposed(session)) 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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"}
+{"version":3,"file":"motionscript-react.js","names":[],"sources":["../src/ui/use-engine.ts","../src/ui/playhead.ts","../src/ui/use-motion-player.ts","../src/ui/stage.tsx"],"sourcesContent":["import { useEffect, useRef, useState, type DependencyList } from \"react\";\n\nimport type { Engine } from \"@motionscript/core\";\n\nexport interface UseEngineOptions {\n    /**\n     * Rebuild the engine when any of these change, compared as `useEffect` does.\n     * The default, `[]`, builds it once. List only what makes a *different*\n     * engine (node types, the wasm URL): the latest `create` is always the one\n     * called, so its closure is not a dependency.\n     */\n    deps?: DependencyList;\n    /** Called when `create` rejects or throws. Defaults to `console.error`. */\n    onError?: (error: unknown) => void;\n}\n\nfunction logError(error: unknown) {\n    console.error(\"Could not start the MotionScript engine.\", error);\n}\n\n/**\n * Builds an engine once, `null` until it arrives, and disposes it when it is no\n * longer wanted. What to build is the factory's job: nothing here imports a\n * platform.\n *\n * ```tsx\n * const engine = useEngine(() => createBrowserEngine());\n * const player = useMotionPlayer({ engine, document: doc });\n * ```\n *\n * An unmount while the factory was still pending (StrictMode does this on every\n * dev mount) frees the engine the moment it lands; a change in `deps` disposes\n * the old one and returns `null` until the new one is ready.\n *\n * Call it once and hand the engine down: a second call is a second wasm module\n * and renderer. Anything that must hold before a player sees the engine, such as\n * `setManifest`, belongs in `create`, not in an effect beside it.\n */\nexport function useEngine<E extends Engine = Engine>(\n    create: () => E | Promise<E>,\n    options: UseEngineOptions = {},\n): E | null {\n    const { deps = [], onError } = options;\n    const [engine, setEngine] = useState<E | null>(null);\n    const createRef = useRef(create);\n    const onErrorRef = useRef(onError);\n\n    useEffect(() => {\n        createRef.current = create;\n        onErrorRef.current = onError;\n    });\n\n    useEffect(() => {\n        let live = true;\n        let built: E | null = null;\n\n        new Promise<E>(resolve => resolve(createRef.current()))\n            .then(next => {\n                built = next;\n                if (!live) {\n                    next.dispose();\n                    return;\n                }\n                setEngine(next);\n            })\n            .catch(error => {\n                if (live) (onErrorRef.current ?? logError)(error);\n            });\n\n        return () => {\n            live = false;\n            built?.dispose();\n            setEngine(null);\n        };\n        // The caller's list, not ours: it is what makes a different engine.\n        // eslint-disable-next-line react-hooks/exhaustive-deps\n    }, deps);\n\n    return engine;\n}\n","import { useSyncExternalStore } from \"react\";\n\n/**\n * The playhead, held outside React: a frame written at clock rate through\n * `useState` would re-render the player's owner faster than the project's frame\n * rate, and nothing in a render depends on it (the controller paints straight\n * onto the canvas). Only components that 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/** Subscribe *this* component to the playhead. Takes `{ playhead }` rather than `Player` to avoid an import cycle with `use-motion-player`. */\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 { clipTimeToFrame, DEFAULT_FPS, DEFAULT_VIEWPORT, isProjectDocument } from \"@motionscript/core\";\n\nimport type {\n    BuildError,\n    Engine,\n    NodeBox,\n    NodeHandle,\n    Node3DFrame,\n    NodeOverride,\n    NodeState,\n    NodeTextLayout,\n    PlaybackController,\n    AssetTimelineResult,\n    ProjectDocument,\n    ReparentPlacement,\n    VisualDocument,\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/** Background asset discovery: only frame-0 tracks are discovered before mount, the rest stream in. The timeline's length never waits on it. */\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\n/**\n * Sessions this hook has disposed. React can replay a child's effects with the\n * `session` it last rendered after this hook's cleanup ran (a suspended\n * boundary revealed, StrictMode), so a stage asks here before binding.\n */\nconst disposedSessions = new WeakSet<Session>();\n\n/** @internal Not exported from the package. */\nexport function isSessionDisposed(session: Session): boolean {\n    return disposedSessions.has(session);\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. Nullable because building one\n     * is async ({@link useEngine}): the player no-ops until it arrives.\n     *\n     * Create it once and share it: it holds the renderer and the exporter, so a\n     * fresh one per render rebuilds the renderer behind every player on it.\n     * Compared by identity; a different engine is a full rebuild.\n     */\n    engine: Engine | null | undefined;\n    /**\n     * What to play; nothing opens until there is one. A project document carries\n     * its own viewport, fps, theme and tracks; a scene document (still or\n     * composition) carries none, so `viewport` and `fps` come from here or the\n     * engine.\n     *\n     * Content-diffed, identity first: a new document is reconciled onto the\n     * running session, each track patched in place and rebuilt only when it\n     * cannot be. Treat documents as immutable: an in-place edit is not seen.\n     *\n     * A new document keeps the player's place (the playhead is clamped to a\n     * shorter timeline, playback carries on). Seek or pause yourself when a swap\n     * means \"start over\".\n     */\n    document?: ProjectDocument | VisualDocument;\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 has\n     * been painted (clock, seek or document swap).\n     *\n     * Not the playhead, which reports where the clock is: a seek is async, so the\n     * number can move before the canvas does. Use it to keep an overlay in step\n     * with the pixels, and keep it cheap: it runs on the render loop. Read through\n     * a ref, so changing it costs nothing.\n     */\n    onFramePainted?: (frame: number) => void;\n}\n\n/** A document's transport and its session, with no DOM. Two calls to {@link useMotionPlayer} share only the engine. */\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    /** Pauses, then seeks. 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    /** The node's props before any command has acted on it: the same at every frame, and answered while it is off screen. */\n    getNodeInitialProps(nodeId: string): NodeState[\"properties\"] | 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    // Points below 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    /**\n     * Where `point` lands in the coordinates the node at `path` positions its\n     * children in (a graph's units), or `null` when those are pixels: the\n     * `x`/`y` to give a node dropped or pasted there.\n     */\n    childPlanePoint(path: string, point: Vector2): Vector2 | null;\n    /**\n     * What keeps the node at `path` looking as it does once it moves under the\n     * node at `parentPath`: `offsets` (`x`/`y` values it takes under its parent\n     * now) as the ones that put it at the same place there, and the turn to add\n     * and the factor to scale by. `null` when that parent arranges its children\n     * itself.\n     */\n    reparentPlacement(path: string, parentPath: string, offsets: readonly Vector2[]): ReparentPlacement | null;\n    /** The points an editor may drag on the node at `path` (an arrow's ends), in viewport space. */\n    nodeHandles(path: string): NodeHandle[] | null;\n    /** The value of `prop` that puts its handle under `point`, or `null`. */\n    handleValue(path: string, prop: 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    // Document, then options, then engine. Resolved during render, before any\n    // session exists, so a stage can size its canvas on the first pass.\n    const projectDoc = document && isProjectDocument(document) ? document : undefined;\n    const resolvedViewport = projectDoc?.viewport ?? options.viewport ?? engine?.viewport ?? DEFAULT_VIEWPORT;\n    const fps = projectDoc?.fps ?? options.fps ?? engine?.fps ?? DEFAULT_FPS;\n\n    // Held by size: a host that rebuilds its document per edit would otherwise\n    // 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    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    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    const speedRef = useRef(speed);\n    /**\n     * What the transport was told to do, ahead of the next render. State shows\n     * only the last value a batch settled on, so it can disagree with the\n     * controller inside one batch (`seek` then `play`).\n     */\n    const playingRef = useRef(false);\n\n    useEffect(() => {\n        onFramePaintedRef.current = onFramePainted;\n        loopRef.current = loop;\n        fpsRef.current = fps;\n        speedRef.current = speed;\n        playingRef.current = isPlaying;\n    });\n\n    // An edit keeps the transport and errors (the reconcile effect re-reads both,\n    // so an unfixed error never blinks out); only losing the document stops it,\n    // during render 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    /** Pulls duration, errors and progress off the controller, keeping what did not change: a fresh array or object is a new `Player` on every edit. */\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    /** One instance, so the transport, the reconcile effect and a session's first paint share one seek discipline. */\n    const [seekTo] = useState(() => (frame: number): Promise<boolean> => {\n        const pc = controllerRef.current;\n        if (!pc) return Promise.resolve(false);\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        // A superseded seek still resolves (its generation guard bailed in the\n        // controller) but never painted, so only the newest may clear `loading`:\n        // consumers pace scrubbing off that edge.\n        const token = ++seekTokenRef.current;\n        setLoading(true);\n        return pc.seek(clamped).then(() => {\n            const newest = token === seekTokenRef.current;\n            if (newest) setLoading(false);\n            return newest;\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 afterwards, so this hook owns no 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.floor(clipTimeToFrame(t, fpsRef.current));\n            playhead.set(frame);\n\n            // Asks the controller: a swap can change the length after 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 {\n                playingRef.current = false;\n                setIsPlaying(false);\n            }\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            disposedSessions.add(opened);\n            opened.dispose();\n        };\n        // `document` is deliberately absent (only whether there is one): the effect\n        // below reconciles a new one onto the live session. Everything listed\n        // needs a rebuild: a different engine is a different renderer, and a live\n        // surface cannot change 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 running session. Skipped on the pass\n    // that opened it, which already holds this document.\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` paints the current frame once its assets load, and a\n        // 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    // Parks a new session on the frame the playhead holds, so a rebuild keeps its\n    // place. The seek pauses the clock the effect above just started, so a player\n    // that was playing resumes once the park lands (assets loaded, so the first\n    // ticks draw rather than catch up), unless a newer seek or a pause moved the\n    // transport meanwhile.\n    useEffect(() => {\n        const pc = controllerRef.current;\n        if (!pc) return;\n        const wasPlaying = playingRef.current;\n        const parked = seekTo(playhead.getSnapshot());\n        if (!wasPlaying) return;\n        void parked.then(newest => {\n            if (!newest || controllerRef.current !== pc || !playingRef.current || pc.isPlaying) return;\n            pc.play(speedRef.current);\n        });\n    }, [session, playhead, seekTo]);\n\n    // Built once: every action reads the controller through a ref, so a re-render\n    // never invalidates a handler a child holds.\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            playingRef.current = false;\n            setIsPlaying(false);\n            void seekTo(frame);\n        };\n\n        return {\n            playhead,\n            // Both drive the controller as well as state: in one batch a `seek` and\n            // a `play` cancel out in state, so the `isPlaying` effect never re-runs\n            // though the seek already paused the clock.\n            play: () => {\n                playingRef.current = true;\n                setIsPlaying(true);\n                const pc = controllerRef.current;\n                if (pc && !pc.isPlaying) pc.play(speedRef.current);\n            },\n            pause: () => {\n                playingRef.current = false;\n                setIsPlaying(false);\n                controllerRef.current?.pause();\n            },\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            getNodeInitialProps: (nodeId: string) => controllerRef.current?.getNodeInitialProps(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            childPlanePoint: (path: string, point: Vector2) =>\n                controllerRef.current?.childPlanePoint(path, point) ?? null,\n            reparentPlacement: (path: string, parentPath: string, offsets: readonly Vector2[]) =>\n                controllerRef.current?.reparentPlacement(path, parentPath, offsets) ?? null,\n            nodeHandles: (path: string) => controllerRef.current?.nodeHandles(path) ?? null,\n            handleValue: (path: string, prop: string, point: Vector2) =>\n                controllerRef.current?.handleValue(path, prop, 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 { isSessionDisposed, type Player } from \"./use-motion-player\";\n\n/** Core compiles without the DOM lib, so `RenderSurface.mount` takes `unknown`; narrowed here, where `HTMLCanvasElement` exists. */\ntype StageRenderContext = Omit<EngineRenderContext, \"mount\"> & {\n    mount(canvas: HTMLCanvasElement): void;\n};\n\nconst IDENTITY_VIEW = Object.freeze({ zoom: 1, x: 0, y: 0 });\n\nexport interface MotionStageProps {\n    player: Player;\n    /**\n     * Device pixels rasterized per viewport unit. Defaults to `1`. Not a zoom or\n     * a crop: the scene's coordinate space is unchanged and CSS scales the canvas\n     * back to its box. `<1` suits a preview shown far smaller than the output size.\n     *\n     * Every change re-creates the GPU surface, dropping texture-backed images\n     * (decoded video frames, 3D composites; they re-upload on demand), so quantize\n     * to a few steps and never drive it from a resize observer. Prefer scales that\n     * keep both dimensions whole: `pixelRatio` is one number, so uneven rounding\n     * shifts the frame's centre by up to half a device pixel.\n     *\n     * `player.screenshot()` returns the surface's size, so it is scaled too.\n     */\n    renderScale?: number;\n    /**\n     * The canvas's own size in CSS pixels, when it is not the frame. Omitted, the\n     * canvas is the frame: `viewport × renderScale`, stretched over its box.\n     *\n     * Supplied together with {@link view}, the canvas becomes a window onto the\n     * frame: it takes the size of the area shown, `renderScale` means device\n     * pixels per CSS pixel, and only what is on screen is rasterized, so zooming\n     * in stays sharp. It re-creates the surface like `renderScale`: quantize it.\n     */\n    surfaceSize?: Size2D;\n    /**\n     * Pan and zoom applied to the render itself; requires {@link surfaceSize}.\n     * `zoom` multiplies scene units; `x`/`y` offset the frame's centre in CSS\n     * pixels, positive `y` downwards (a CSS translate).\n     *\n     * A change costs a repaint and nothing else. A CSS transform could not add\n     * 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. Requires {@link surfaceSize} and\n     * {@link view}. Defaults to `true`; off lets a node parked past the edge\n     * rasterize into the rest of the surface.\n     */\n    clipToFrame?: boolean;\n    /**\n     * Defaults to `\"black\"`. `\"transparent\"` leaves undrawn frame pixels\n     * unpainted so the host's backdrop (a checkerboard) shows through. Requires\n     * {@link surfaceSize} and {@link view}.\n     */\n    frameBackground?: \"black\" | \"transparent\";\n    className?: string;\n    style?: CSSProperties;\n}\n\n/**\n * A canvas bound to a {@link Player}'s session. One stage per player: a session\n * drives one surface, and a second stage would take it 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 } = player;\n    // The session's own size, not the player's: the player's moves a commit\n    // ahead, in the commit whose cleanup disposes the old session, and a buffer\n    // resized there would re-bind that disposed session.\n    const viewport = session?.viewport ?? player.viewport;\n\n    // Floored at 1: a zero-sized surface fails creation outright.\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    // Without both `surfaceSize` and `view` the canvas is the frame, so all four revert to defaults.\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    // A ref because the context is mutable external state whose knobs are\n    // written; writing through the `player` prop trips the immutability lint.\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    // Bind the surface and rebuild it when the backing store changes. An effect,\n    // not a callback, because React has written the canvas's new `width`/`height`\n    // by the time effects run and the renderer reads them when it builds the\n    // surface: mounting before the resize would build the previous size.\n    // `repaint()` because a new surface starts blank and a paused clock would not\n    // fill it.\n    useEffect(() => {\n        const canvas = canvasRef.current;\n        const ctx = ctxRef.current;\n        // A replayed effect can hold a session its player has since disposed.\n        if (!session || !canvas || !ctx || isSessionDisposed(session)) 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        // Detaches the old surface first, which drops the texture-backed images\n        // that belong to it.\n        ctx.mount(canvas);\n        session.controller.repaint();\n    }, [session, renderScale, bufferWidth, bufferHeight]);\n\n    // Keyed on the view's fields, not the object: callers pass a fresh\n    // `{zoom, x, y}` every render, which would repaint every render.\n    useEffect(() => {\n        const ctx = ctxRef.current;\n        if (!session || !ctx || isSessionDisposed(session)) 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                width={bufferWidth}\n                height={bufferHeight}\n                style={{\n                    display: session ? \"block\" : \"none\",\n                    ...(surfaceSize\n                        ? {\n                              // `surfaceSize` is honoured literally, not stretched\n                              // to the box: it is quantized, so it is usually a\n                              // little larger than the box and a different shape,\n                              // and stretching would squash one axis.\n                              //\n                              // Centred because `executePass` puts the scene origin\n                              // at the surface's centre, so this lands the frame\n                              // where the layout says; the spare pixels hang off\n                              // all four edges and the parent clips them.\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

@@ -1,11 +1,8 @@
 /**
- * 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.
+ * The playhead, held outside React: a frame written at clock rate through
+ * `useState` would re-render the player's owner faster than the project's frame
+ * rate, and nothing in a render depends on it (the controller paints straight
+ * onto the canvas). Only components that display it subscribe.
  */
 export interface PlayheadStore {
     subscribe(onChange: () => void): () => void;
@@ -14,12 +11,7 @@ export interface PlayheadStore {
     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.
- */
+/** Subscribe *this* component to the playhead. Takes `{ playhead }` rather than `Player` to avoid an import cycle with `use-motion-player`. */
 export declare function usePlayhead(player: {
     playhead: PlayheadStore;
 }): number;

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

@@ -1 +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"}
+{"version":3,"file":"playhead.d.ts","sourceRoot":"","sources":["../../src/ui/playhead.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;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,+IAA+I;AAC/I,wBAAgB,WAAW,CAAC,MAAM,EAAE;IAAE,QAAQ,EAAE,aAAa,CAAA;CAAE,GAAG,MAAM,CAGvE"}

package/dist/ui/stage.d.ts

@@ -2,62 +2,38 @@ import { CSSProperties } from 'react';
 import { Size2D } from '@motionscript/core';
 import { Player } from './use-motion-player';
 export interface MotionStageProps {
-    /** The player whose session this stage draws. */
     player: Player;
     /**
-     * Device pixels to rasterize per viewport unit. Defaults to `1`.
+     * Device pixels rasterized per viewport unit. Defaults to `1`. Not a zoom or
+     * a crop: the scene's coordinate space is unchanged and CSS scales the canvas
+     * back to its box. `<1` suits a preview shown far smaller than the output size.
      *
-     * **Not a zoom and not a crop.** The viewport stays the scene's logical
-     * coordinate space; this only changes how many real pixels that space is
-     * drawn into, and CSS scales the canvas back up to fill its box.
+     * Every change re-creates the GPU surface, dropping texture-backed images
+     * (decoded video frames, 3D composites; they re-upload on demand), so quantize
+     * to a few steps and never drive it from a resize observer. Prefer scales that
+     * keep both dimensions whole: `pixelRatio` is one number, so uneven rounding
+     * shifts the frame's centre by up to half a device pixel.
      *
-     * The lever exists because a preview is usually displayed far smaller than
-     * the project's output size: a 1920×1080 project in a 700px-wide panel
-     * rasterizes roughly seven times the pixels anyone can see. `0.5` there is a
-     * quarter of the fill, the shader work and the effect offscreens.
-     *
-     * Two things to know before animating it:
-     *
-     * - **Every change re-creates the GPU surface**, which drops the storage
-     *   adapter's texture-backed images (decoded video frames, 3D composites;
-     *   still images survive) and asks for a fresh GL context. Quantize to a few
-     *   steps and let it settle — never drive it from a resize observer.
-     * - **Prefer scales that keep both dimensions whole.** `pixelRatio` is one
-     *   uniform number, so a scale that rounds differently on each axis shifts
-     *   the frame's centre by up to half a device pixel.
-     *
-     * A snapshot from `player.screenshot()` comes back at the surface's size, so
-     * it is scaled too — render at `1` if you need full resolution out of it.
+     * `player.screenshot()` returns the surface's size, so it is scaled too.
      */
     renderScale?: number;
     /**
-     * The canvas's own size in CSS pixels, when it is **not** the frame.
-     *
-     * Omitted — the default — the canvas is the frame: sized `viewport ×
-     * renderScale` and stretched over its box by CSS, which is what every
-     * export, thumbnail and plain player wants.
+     * The canvas's own size in CSS pixels, when it is not the frame. Omitted, the
+     * canvas is the frame: `viewport × renderScale`, stretched over its box.
      *
-     * Supplied, together with {@link view}, the canvas becomes a *window* onto
-     * the frame: it takes the size of the area it is shown in, `renderScale`
-     * stops meaning "fraction of the project's resolution" and starts meaning
-     * device pixels per CSS pixel, and only what is on screen is rasterized.
-     * That is what lets an editor zoom in without going soft or paying for the
-     * whole frame at the zoomed resolution.
-     *
-     * It re-creates the surface exactly as `renderScale` does, and wants the
-     * same treatment: quantize it and let it settle.
+     * Supplied together with {@link view}, the canvas becomes a window onto the
+     * frame: it takes the size of the area shown, `renderScale` means device
+     * pixels per CSS pixel, and only what is on screen is rasterized, so zooming
+     * in stays sharp. It re-creates the surface like `renderScale`: quantize it.
      */
     surfaceSize?: Size2D;
     /**
-     * A pan and zoom applied to the render itself. Requires {@link surfaceSize}.
-     *
+     * Pan and zoom applied to the render itself; requires {@link surfaceSize}.
      * `zoom` multiplies scene units; `x`/`y` offset the frame's centre in CSS
-     * pixels, positive `y` downwards — the same sign convention as a CSS
-     * translate, so a preview can hand over the pan it was already computing.
+     * pixels, positive `y` downwards (a CSS translate).
      *
-     * Changing it costs a repaint and nothing else: no surface, no textures, no
-     * precomp. That is the point of it living here rather than in a CSS
-     * transform, which cannot add resolution it was not rasterized with.
+     * A change costs a repaint and nothing else. A CSS transform could not add
+     * resolution it was not rasterized with.
      */
     view?: {
         zoom: number;
@@ -65,34 +41,23 @@ export interface MotionStageProps {
         y: number;
     };
     /**
-     * Whether the frame's edge bounds what draws, rather than only where its own
-     * backdrop goes. Requires {@link surfaceSize} and {@link view}. Defaults to
-     * `true`.
-     *
-     * Off lets a node parked past the frame's edge rasterize into the rest of
-     * the surface instead of being discarded — for a host that wants to show,
-     * faded, what a node placed there while animating in or out.
+     * Whether the frame's edge bounds what draws. Requires {@link surfaceSize} and
+     * {@link view}. Defaults to `true`; off lets a node parked past the edge
+     * rasterize into the rest of the surface.
      */
     clipToFrame?: boolean;
     /**
-     * What the frame's backdrop is painted with. Defaults to `"black"`.
-     *
-     * `"transparent"` leaves the frame unpainted where nothing was drawn, so
-     * whatever the host renders behind the canvas shows through — a
-     * checkerboard, for an editor that has to distinguish "no scene covers this"
-     * from "a scene covers it in black". Requires {@link surfaceSize} and
-     * {@link view}, the same way {@link clipToFrame} does.
+     * Defaults to `"black"`. `"transparent"` leaves undrawn frame pixels
+     * unpainted so the host's backdrop (a checkerboard) shows through. Requires
+     * {@link surfaceSize} and {@link view}.
      */
     frameBackground?: "black" | "transparent";
     className?: string;
     style?: CSSProperties;
 }
 /**
- * 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.
+ * A canvas bound to a {@link Player}'s session. One stage per player: a session
+ * drives one surface, and a second stage would take it from the first.
  */
 export declare function MotionStage({ player, renderScale, surfaceSize, view, clipToFrame, frameBackground, className, style, }: MotionStageProps): import("react").JSX.Element;
 //# sourceMappingURL=stage.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"stage.d.ts","sourceRoot":"","sources":["../../src/ui/stage.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,aAAa,EAAE,MAAM,OAAO,CAAC;AAE9D,OAAO,KAAK,EAAuB,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEtE,OAAO,EAAqB,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAsBrE,MAAM,WAAW,gBAAgB;IAC7B,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;;;;;OAgBG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,EACxB,MAAM,EACN,WAAe,EACf,WAAW,EACX,IAAI,EACJ,WAAW,EACX,eAAe,EACf,SAAS,EACT,KAAK,GACR,EAAE,gBAAgB,+BAqJlB"}
+{"version":3,"file":"stage.d.ts","sourceRoot":"","sources":["../../src/ui/stage.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,aAAa,EAAE,MAAM,OAAO,CAAC;AAE9D,OAAO,KAAK,EAAuB,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEtE,OAAO,EAAqB,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AASrE,MAAM,WAAW,gBAAgB;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,EACxB,MAAM,EACN,WAAe,EACf,WAAW,EACX,IAAI,EACJ,WAAW,EACX,eAAe,EACf,SAAS,EACT,KAAK,GACR,EAAE,gBAAgB,+BA4GlB"}

package/dist/ui/use-engine.d.ts

@@ -2,38 +2,32 @@ import { DependencyList } from 'react';
 import { Engine } from '@motionscript/core';
 export interface UseEngineOptions {
     /**
-     * Rebuild the engine when any of these change, compared the way
-     * `useEffect` compares its own. The default, `[]`, builds it once.
-     *
-     * Not for the factory's closure: the latest `create` is always the one
-     * called, so an inline arrow does not rebuild anything. List only what
-     * makes a *different* engine, such as the node types or the wasm URL.
+     * Rebuild the engine when any of these change, compared as `useEffect` does.
+     * The default, `[]`, builds it once. List only what makes a *different*
+     * engine (node types, the wasm URL): the latest `create` is always the one
+     * called, so its closure is not a dependency.
      */
     deps?: DependencyList;
     /** Called when `create` rejects or throws. Defaults to `console.error`. */
     onError?: (error: unknown) => void;
 }
 /**
- * Builds an engine once, hands it to you when it is ready, and disposes it
- * when it is no longer wanted.
+ * Builds an engine once, `null` until it arrives, and disposes it when it is no
+ * longer wanted. What to build is the factory's job: nothing here imports a
+ * platform.
  *
  * ```tsx
  * const engine = useEngine(() => createBrowserEngine());
  * const player = useMotionPlayer({ engine, document: doc });
  * ```
  *
- * `null` until it arrives, which {@link useMotionPlayer} accepts. Nothing in
- * this package imports a platform, so what to build is the factory's job: the
- * browser's `createBrowserEngine`, a headless one, or a test double.
+ * An unmount while the factory was still pending (StrictMode does this on every
+ * dev mount) frees the engine the moment it lands; a change in `deps` disposes
+ * the old one and returns `null` until the new one is ready.
  *
- * Disposal covers the cases a hand-written effect gets wrong: an unmount while
- * the wasm was still loading (StrictMode does this on every mount in
- * development) frees the engine the moment it lands, and a change in `deps`
- * disposes the old one and returns `null` until the new one is ready.
- *
- * Call it once and hand the engine down. A second call is a second wasm module
- * and a second GL stack. Anything that must be true before a player sees the
- * engine, such as `setManifest`, belongs in `create`, not in an effect beside it.
+ * Call it once and hand the engine down: a second call is a second wasm module
+ * and renderer. Anything that must hold before a player sees the engine, such as
+ * `setManifest`, belongs in `create`, not in an effect beside it.
  */
 export declare function useEngine<E extends Engine = Engine>(create: () => E | Promise<E>, options?: UseEngineOptions): E | null;
 //# sourceMappingURL=use-engine.d.ts.map

package/dist/ui/use-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-engine.d.ts","sourceRoot":"","sources":["../../src/ui/use-engine.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,KAAK,cAAc,EAAE,MAAM,OAAO,CAAC;AAEzE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,MAAM,WAAW,gBAAgB;IAC7B;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACtC;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAC/C,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAC5B,OAAO,GAAE,gBAAqB,GAC/B,CAAC,GAAG,IAAI,CAsCV"}
+{"version":3,"file":"use-engine.d.ts","sourceRoot":"","sources":["../../src/ui/use-engine.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,KAAK,cAAc,EAAE,MAAM,OAAO,CAAC;AAEzE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,MAAM,WAAW,gBAAgB;IAC7B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACtC;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAC/C,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAC5B,OAAO,GAAE,gBAAqB,GAC/B,CAAC,GAAG,IAAI,CAsCV"}

package/dist/ui/use-motion-player.d.ts

@@ -1,11 +1,6 @@
 import { BuildError, Engine, NodeBox, NodeHandle, Node3DFrame, NodeOverride, NodeState, NodeTextLayout, ProjectDocument, ReparentPlacement, VisualDocument, Session, Size2D, TrackSpan, TreeState, Vector2, Vector3 } from '@motionscript/core';
 import { PlayheadStore } from './playhead';
-/**
- * How far background discovery has got. Only the tracks on frame 0 are
- * discovered before the player mounts; the rest stream in behind it (see
- * `AssetTimeline.runAsync`). The timeline's length never waits on it — every track
- * declares its own.
- */
+/** Background asset discovery: only frame-0 tracks are discovered before mount, the rest stream in. The timeline's length never waits on it. */
 export interface PrecompProgress {
     /** Tracks discovered so far. */
     discoveredTracks: number;
@@ -14,40 +9,31 @@ export interface PrecompProgress {
     /** True once every track has been discovered. */
     complete: boolean;
 }
-/** @internal Whether `session` was disposed by a player. Not exported from the package. */
+/** @internal Not exported from the package. */
 export declare function isSessionDisposed(session: Session): boolean;
 export interface MotionPlayerOptions {
     /**
-     * The engine this player opens its session on.
+     * The engine this player opens its session on. Nullable because building one
+     * is async ({@link useEngine}): the player no-ops until it arrives.
      *
-     * Nullable on purpose: building one is asynchronous
-     * (`await createBrowserEngine(...)`), so a host gets it from {@link useEngine}
-     * and it is `null` for the first render or two. The player no-ops until it
-     * arrives, which is what keeps the hook out of a conditional.
-     *
-     * **Create it once, and share it.** It holds the renderer and the exporter, so
-     * a fresh one per render rebuilds the WebGL surface behind every player on
-     * it. Identity-compared: a different engine is a different renderer, and so
-     * a full rebuild.
+     * Create it once and share it: it holds the renderer and the exporter, so a
+     * fresh one per render rebuilds the renderer behind every player on it.
+     * Compared by identity; a different engine is a full rebuild.
      */
     engine: Engine | null | undefined;
     /**
-     * What to play. Nothing opens until there is one.
-     *
-     * A **project** document is the whole answer: it carries its own viewport,
-     * fps, theme and tracks. A **scene** document (still or composition) is one
-     * clip and carries none of that, so `viewport` and `fps` must come from here
-     * or from the engine.
+     * What to play; nothing opens until there is one. A project document carries
+     * its own viewport, fps, theme and tracks; a scene document (still or
+     * composition) carries none, so `viewport` and `fps` come from here or the
+     * engine.
      *
-     * Content-diffed, with identity as the fast path: a new document is reconciled
-     * onto the running session, each track's built tree patched in place and
-     * rebuilt only when its change cannot be patched. Treat documents as
-     * immutable — an edit made in place to one the player already holds is not
-     * seen.
+     * Content-diffed, identity first: a new document is reconciled onto the
+     * running session, each track patched in place and rebuilt only when it
+     * cannot be. Treat documents as immutable: an in-place edit is not seen.
      *
-     * A new document keeps the player's place: the playhead stays where it was
-     * (clamped when the timeline got shorter), and playback carries on if it was
-     * running. Seek or pause yourself when a swap means "start over".
+     * A new document keeps the player's place (the playhead is clamped to a
+     * shorter timeline, playback carries on). Seek or pause yourself when a swap
+     * means "start over".
      */
     document?: ProjectDocument | VisualDocument;
     /** Overrides the engine's, for a source that carries none. */
@@ -61,27 +47,17 @@ export interface MotionPlayerOptions {
     /** Initial loop state. Change it later with {@link Player.setLoop}. */
     loop?: boolean;
     /**
-     * Called **synchronously**, on the same task as the draw, each time a frame
-     * has been painted — whether by the clock, a seek, or a document swap.
+     * Called synchronously, on the same task as the draw, each time a frame has
+     * been painted (clock, seek or document swap).
      *
-     * Not the playhead, which reports where the *clock* is. A seek is
-     * asynchronous, so between the two there is a window in which the number has
-     * moved and the canvas has not. Reach for this to keep an overlay — a
-     * selection box, a caret, a handle — in step with the pixels, and keep the
-     * listener cheap: it runs on the render loop, before the browser has had a
-     * chance to composite.
-     *
-     * Read through a ref, so changing it costs nothing.
+     * Not the playhead, which reports where the clock is: a seek is async, so the
+     * number can move before the canvas does. Use it to keep an overlay in step
+     * with the pixels, and keep it cheap: it runs on the render loop. Read through
+     * a ref, so changing it costs nothing.
      */
     onFramePainted?: (frame: number) => void;
 }
-/**
- * One document, its transport, and the session driving it. No DOM.
- *
- * Hand it to a {@link MotionStage} to put pixels on screen. Two calls to
- * {@link useMotionPlayer} produce two of these with nothing shared but the
- * engine — separate playheads, clocks, audio devices and transports.
- */
+/** A document's transport and its session, with no DOM. Two calls to {@link useMotionPlayer} share only the engine. */
 export interface Player {
     /** The live session, or `null` before the engine and a document arrive. */
     readonly session: Session | null;
@@ -106,7 +82,7 @@ export interface Player {
     play(): void;
     pause(): void;
     toggle(): void;
-    /** Seek while paused. Clamped to the timeline. */
+    /** Pauses, then seeks. Clamped to the timeline. */
     seek(frame: number): void;
     /** Seek relative to where the playhead is now. */
     step(delta: number): void;

package/dist/ui/use-motion-player.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-motion-player.d.ts","sourceRoot":"","sources":["../../src/ui/use-motion-player.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"use-motion-player.d.ts","sourceRoot":"","sources":["../../src/ui/use-motion-player.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionscript/react",
-  "version": "0.1.0",
+  "version": "0.1.1-alpha.1",
   "type": "module",
   "description": "React bindings for Motion Script.",
   "repository": {
@@ -35,7 +35,7 @@
   "peerDependencies": {
     "react": "^18.2.0 || ^19.0.0",
     "react-dom": "^18.2.0 || ^19.0.0",
-    "@motionscript/core": "^0.1.0"
+    "@motionscript/core": "^0.1.1-alpha.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.1",
@@ -57,8 +57,8 @@
     "vite": "^8.0.11",
     "vite-plugin-dts": "5.0.0",
     "vitest": "^4.1.5",
-    "@motionscript/core": "0.1.0",
-    "@motionscript/browser": "0.1.0"
+    "@motionscript/core": "0.1.1-alpha.1",
+    "@motionscript/browser": "0.1.1-alpha.1"
   },
   "scripts": {
     "dev": "vite",