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

package/CHANGELOG.md

@@ -0,0 +1,105 @@
+# @motionscript/react
+
+## 0.1.0-alpha.10
+
+## 0.1.0-alpha.9
+
+## 0.1.0-alpha.8
+
+## 0.1.0-alpha.7
+
+## 0.1.0-alpha.6
+
+## 0.1.0-alpha.5
+
+### Minor Changes
+
+- 36bfb89: `useEngine` builds an engine, hands it over when it is ready and disposes it when it is not wanted.
+
+  Every React host was writing the same effect: hold the engine in state, build it asynchronously, dispose it if the component unmounted while the wasm was loading (StrictMode does this on every mount in development) and again on cleanup. `useEngine(create, { deps, onError })` is that effect. It returns `null` until the engine arrives, which `useMotionPlayer` already accepts.
+
+  ```tsx
+  const engine = useEngine(() =>
+    createBrowserEngine({ wasmUrl: "/canvaskit.wasm" })
+  );
+  const player = useMotionPlayer({ engine, document: scene });
+  ```
+
+  The package still imports no platform: what to build is the factory you pass, so it works with `createBrowserEngine`, a headless engine or a test double. `deps` rebuilds the engine when something that makes a different one changes (the node types, say), disposing the old one first; the factory itself is read through a ref, so an inline arrow does not rebuild anything. `onError` replaces the default `console.error` when the factory rejects or throws. Anything that must hold before a player sees the engine, such as `setManifest`, goes in the factory.
+
+### Patch Changes
+
+- da6f97a: Every package ships a `NOTICE`, and a browser build lists what it bundles.
+
+  - Each tarball carries the repository `NOTICE`: the copyright line and the MIT attributions for the noise functions in `skia-render`'s fractal-noise fill (David Hoskins' "Hash without Sine", Inigo Quilez's 2D simplex noise).
+  - `@motionscript/canvaskit` ships `THIRD_PARTY_NOTICES.txt` with the licences of the libraries compiled into the binary: FreeType, HarfBuzz, ICU 74, zlib, libpng, Brotli, WOFF2, Emscripten and musl.
+  - `dist/browser/manifest.json` gains `thirdParty`, the packages the browser build bundled (`name`, `version`, `license`), and their licence and NOTICE files are written to `dist/browser/THIRD_PARTY_LICENSES.txt`. `@motionscript/browser` bundles mediabunny (MPL-2.0, unmodified; source at https://github.com/Vanilagy/mediabunny), esbuild-wasm and three; `@motionscript/math` bundles MathJax.
+
+- 1778355: `react` and `react-dom` peer on `^18.2.0 || ^19.0.0`, where they asked for `^19.2.3`. The package uses only hooks React 18 already has (`useSyncExternalStore` among them), so a React 18 app installs it without a peer warning.
+- 36bfb89: `MotionStage` no longer throws `Cannot read properties of undefined (reading 'MakeWebGLCanvasSurface')` by mounting its canvas on a session its player has already disposed. Two paths led there:
+
+  - A viewport change. The player's size moved a commit before its new session arrived, in the commit that disposed the old one, so the stage resized its canvas and mounted it on the disposed session. The canvas is now sized from the session's own viewport.
+  - A replayed effect: a Suspense boundary revealed again after something beside the player suspended, or StrictMode's dev replay, re-runs the stage's effects with the session it last rendered, after the player's cleanup disposed it. The stage now skips a session its player disposed.
+
+## 0.1.0-alpha.4
+
+### Minor Changes
+
+- c9535a6: A host can ask what a node holds before any command has acted on it.
+
+  - `PlaybackController.getNodeInitialProps(nodeId)`, and the React player's method of the same name, return a document node's props as it arrived (or as built, for one that has not arrived yet). The answer is the same at every frame and is given while the node is off screen, where `getNodeState`/`getNodeProps` describe the node at the frame showing.
+  - `ClipTimeline.baselineProps(id)` is the read underneath it. A bound prop is read through its binding.
+
+- 7f8b4d0: A node can give its children coordinates of its own, which is what a coordinate system needs: a child's `x`/`y` are then in the parent's units and the child keeps its size.
+
+  - A parent answers `_planeOf(child)` with a `ChildPlane` (`toOffset` and `toCoords`, exported). Paint, `global`, the anchor getters, `moveTo({ target })` and `parentPlanePointAt` all read it, and the last two answer in the parent's coordinates. A node whose parent publishes none is unchanged.
+  - `childPlanePointAt(root, path, point)`, and `childPlanePoint` on the player, say where a point lands in the coordinates a node positions its children in, for a host placing a node that is not there yet. They answer `null` for a node whose children are in pixels, and `_planeOf(null)` is what they ask.
+  - `findNode2D(from, id)` and `frameIn(host, node)` are exported from the SDK, for a node that follows another by id. `@motionscript/grids` now uses them and still exports both names.
+
+- 158723b: **Breaking:** the engine no longer has a "scene" in its document API. Its unit is a clip document on a project track, so the names that said "scene" now say what the thing is. This is a clean break: there are no aliases and no deprecated re-exports, so update the names below.
+
+  | Before                                                   | After                        |
+  | -------------------------------------------------------- | ---------------------------- |
+  | `SceneDocument` (`StillDocument \| CompositionDocument`) | `VisualDocument`             |
+  | `SceneTimeline`                                          | `ClipTimeline`               |
+  | `SceneEffect` (the union of effects a node can carry)    | `NodeEffect`                 |
+  | `integrateSpeedToSceneTime`                              | `integrateSpeedToClipTime`   |
+  | `sourceTimeAtSceneElapsed`                               | `sourceTimeAtClipElapsed`    |
+  | `Sound.sceneDurationFor`                                 | `Sound.clipDurationFor`      |
+  | `AudioSink.syncTo(sceneTime)` (parameter name)           | `AudioSink.syncTo(clipTime)` |
+
+  `ClipDocument` is now `VisualDocument | AudioDocument`, as before. The document types, the 3D `Scene3D` and its `scene3d` settings are unchanged: that is a 3D scene, not this.
+
+  Two messages changed with the names: `assertValidDocument` now throws `Invalid clip document:` (was `Invalid scene document:`), and the JSX runtime's error for a value that is not a node class reads `JSX element must be a Node class`.
+
+  The built-in `Canvas2D`, `Provider` and `ThemeProvider` moved from `nodes/scene/` to `nodes/root/` inside core. That directory was never an export path, so no import from the package changes.
+
+- 7f8b4d0: A node can name points an editor may drag to set its `Vector2` props. It answers `_handles()` with each prop and where it sits in its own frame, and `_handleValue(prop, at)` with the value that puts it somewhere else. `nodeHandlesAt` and `handleValueAt` (exported from the SDK), and `nodeHandles`/`handleValue` on the player, answer in viewport space. A math `vectorArrow` offers its two ends in graph units, and a `curlyBrace` that spans two points offers those.
+- 8e9afad: One frame/time conversion and one `FrameSpec`, and fixes to browser playback and export.
+
+  - Core exports `clipFrameToTime`, `clipTimeToFrame`, `frameSpecAtTime`, `FrameSpec` and `DEFAULT_OUTPUT`. The conversion is tolerant of float error: a time within a few ulps of a whole frame is that frame. The playback controller, `Session.seek`, track placement and the evaluator all use it. Before, `currentFrame` read one frame early for 2 to 6 percent of frames (frame 123 at 60 fps), so a document swap after `seek(123)` repainted frame 122, and `trackFrameCount` gained a frame when a length on a boundary landed an ulp high (4.15 s at 60 fps counted 250, not 249).
+  - `FrameSpec` is declared once, in core, and re-exported by `@motionscript/browser` and `@motionscript/headless`; the browser's `DEFAULT_OUTPUT` and the React hook's fallback are core's defaults. The React playhead reads the frame the clock reports through the same conversion.
+  - `WebTicker` no longer stalls a looping host: the end of a run is read again after listeners and tick callbacks have run, a final tick always fires, and a finished run pauses itself. `play` is synchronous, as `Ticker.play` is typed, so a `pause` or `seek` in the same turn works; a rejected `AudioContext.resume()` pauses and logs.
+  - A supersampled export draws into a canvas that is a whole multiple of the output, so an odd-sized viewport is no longer stretched by about 1 percent.
+  - `StillRenderer.toBytes`, `toBlob` and `toDataURL` throw before any frame has been drawn onto the surface, instead of encoding blank pixels.
+
+### Patch Changes
+
+- 4d4e5b0: Start-up failures in the headless engine are reported and cleaned up, and the React player's transport keeps the clock and its state in step.
+
+  - `@motionscript/headless`: a project entry that throws while it loads now rejects `start()` at once with `START_FAILED` and the cause, instead of waiting 60 seconds for `BRIDGE_TIMEOUT`. The page entry imports the project dynamically, so the throw is a rejection the entry already handles.
+  - `@motionscript/headless`: a `start()` that fails closes the Chromium it launched, so a retry no longer leaks the first browser, and a `close()` that lands while the engine is booting ends the boot with `CLOSED` instead of letting it finish on a closed engine.
+  - `@motionscript/react`: `seek()` then `play()` in one batch while already playing left the clock paused with `isPlaying` still `true`. `play()` and `pause()` now drive the controller as well as the state.
+  - `@motionscript/react`: a session rebuild while playing (a different engine, viewport size or fps) used to park the new session with a seek that paused it. A player that was playing now resumes once the park has landed, unless a newer seek or a pause came first. The README and CLAUDE.md say which changes rebuild the session.
+
+- 217ae88: A host can keep a node looking exactly as it does when it moves it to another parent, as a design tool does. `reparentPlacementAt(root, path, parentPath, offsets)` (the player's `reparentPlacement`) carries `x`/`y` values the node takes under its parent now, its own and its moves' destinations, to the ones that put its centre at the same place under the new parent, and gives the turn to add to its rotation and the factor to scale it by so the two parents' own turn and scale, cameras included, are undone. It works through a freeform parent's padding and alignment and a parent's own coordinates, and answers `null` for a parent that arranges its children in a run or a grid. `flowOps.freeSlot` says where a freeform arrangement puts one more item.
+
+## 0.1.0-alpha.3
+
+## 0.1.0-alpha.2
+
+## 0.1.0-alpha.1
+
+## 0.1.0-alpha.0
+
+Initial release.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,49 @@
+Motionscript
+Copyright 2026 Motionscript LLC
+
+This product includes the third-party code below, each part under the MIT
+License reproduced at the end of this file.
+
+- packages/renderer/crates/renderer/src/shaders/prim.wgsl (`fn_hash2`):
+  "Hash without Sine" by David Hoskins (https://www.shadertoy.com/view/4djSRW).
+  Copyright (c) 2014 David Hoskins.
+
+- packages/renderer/crates/renderer/src/shaders/prim.wgsl (`simplex_noise`): "Noise - simplex - 2D" by Inigo Quilez
+  (https://www.shadertoy.com/view/Msf3WH). Copyright (c) 2013 Inigo Quilez.
+
+- packages/renderer/crates/render3d (in @motionscript/renderer's WebAssembly):
+  its shaders (src/shaders/mesh.wgsl) port three.js r185's mesh programs and
+  src/geometry.rs its primitive generators (https://threejs.org).
+  Copyright (c) 2010-2026 three.js authors.
+
+@motionscript/renderer's WebAssembly (dist/ms_renderer_bg.wasm) compiles in
+Rust crates under MIT, Apache-2.0, Zlib and Unicode-3.0 terms (wgpu, naga,
+harfrust, read-fonts, kurbo, wasm-bindgen and others); their notices are in
+packages/renderer/THIRD_PARTY_NOTICES.txt.
+
+MP3 export loads @mediabunny/mp3-encoder (MPL-2.0), a WebAssembly build of
+the LAME MP3 encoder (LGPL, https://lame.sourceforge.io), on first use.
+
+The browser builds under dist/browser/ bundle each package's npm dependencies;
+dist/browser/THIRD_PARTY_LICENSES.txt in each package lists them with their
+licences.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,4 +1,145 @@
-# Temporary Holding Version
+# @motionscript/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
-If no other versions are published within 30 days, this package and version will be deleted.
+React bindings for [Motion Script](https://motionscript.dev): drop a scene into
+your app and play it back on a `<canvas>` drawn with WebGPU.
+
+```tsx
+import { createBrowserEngine } from '@motionscript/browser';
+import { MotionStage, useEngine, useMotionPlayer, usePlayhead } from '@motionscript/react';
+import doc from './scenes/my-scene.json';
+
+export function App() {
+  const engine = useEngine(() => createBrowserEngine());
+
+  const player = useMotionPlayer({ engine, document: doc, loop: true });
+  const frame = usePlayhead(player);
+
+  return (
+    <>
+      <MotionStage player={player} />
+      <button onClick={player.toggle}>{player.isPlaying ? 'Pause' : 'Play'}</button>
+      <input
+        type="range"
+        min={0}
+        max={player.totalFrames - 1}
+        value={frame}
+        onChange={e => player.seek(Number(e.target.value))}
+      />
+    </>
+  );
+}
+```
+
+## What's in here
+
+- **`useEngine`**: builds an engine from a factory you pass, returns it (`null`
+  until it arrives) and disposes it on unmount, including an unmount that
+  happened while the wasm was still loading, which StrictMode causes on every
+  mount in development. `useEngine(create, { deps, onError })`: `deps` rebuilds
+  it when something that makes a different engine changes, disposing the old one
+  first (default `[]`, built once); `onError` replaces the default
+  `console.error` when the factory rejects. The latest `create` is always the
+  one called, so an inline arrow rebuilds nothing. It imports no platform: the
+  factory is `createBrowserEngine`, a headless engine or a test double.
+- **`useMotionPlayer`**: opens a session on an engine and gives you the
+  transport for it — `play`/`pause`/`seek`/`speed`/`mute`/`loop`, the duration,
+  build errors, and the editor surface (`getTreeState`, `pickNode`,
+  `setNodeOverride`, `getTrackSpans`, …). A new `document` is reconciled onto the
+  running session and the player keeps its place — the playhead stays put
+  (clamped if the timeline got shorter) and playback carries on. The session
+  patches only what the edit touched: a track whose clip is unchanged keeps its
+  tree, and a changed one is updated in place where it can be, so treat
+  documents as immutable and build the next one rather than mutating the last.
+  Only a different `engine`, a document appearing or disappearing, or a changed
+  viewport size or `fps` rebuilds the session; the new one is parked on the same
+  frame and, if the player was playing, playback resumes once it has landed.
+  No DOM: it owns the timeline, not a canvas. A project document's own
+  `viewport` and `fps` win over the options, which win over the engine's, then
+  1920×1080 and 60. `speed`, `muted` and `loop` are initial values; change them
+  with `setSpeed`, `setMuted` and `setLoop`. A document that fails validation
+  throws from an effect and reaches the nearest error boundary; `errors` holds
+  discovery and draw errors. Pass a stable document reference: a new object on
+  every render is reconciled on every render.
+- **`MotionStage`**: a canvas bound to a player's session. It owns how the frame
+  is rasterized — `renderScale`, `surfaceSize`, `view`, `clipToFrame`,
+  `frameBackground` — and nothing about what is in it or when. A change to
+  `renderScale` or to the canvas's buffer size re-creates the GPU surface, which
+  drops decoded video frames and 3D composites (they re-upload on demand), so
+  quantize them to a few steps and never drive them from a resize observer.
+  `view`, `clipToFrame` and `frameBackground` apply only when `surfaceSize` and
+  `view` are both given; a `view` change costs a repaint and nothing else.
+  `player.screenshot()` returns the surface at its buffer size, so `renderScale`
+  scales it too.
+- **`usePlayhead`**: subscribes a component to the playhead. The frame moves at
+  clock rate, so keeping it out of the player's own state is what stops a host
+  re-rendering sixty-plus times a second — but only if you call it **as low in
+  the tree as it will go**. A component that subscribes re-renders on every
+  tick, and drags its children with it, so put it in the scrubber and the time
+  readout rather than in whatever renders the stage.
+
+### You own the engine
+
+There is no provider. Say how to build an engine with `useEngine` and pass what
+it returns in — which is also why nothing in this package imports a platform, so
+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
+nullable precisely because building one is async: the player no-ops until it
+arrives, which keeps the hook out of a conditional.
+
+**Set the asset manifest before you hand the engine down**, which means inside
+the factory you give `useEngine`, before it returns. Child effects run before
+the parent's, so a player given an engine whose catalog is still empty resolves
+its assets against that and never finds them
+([`apps/react/src/App.tsx`](https://github.com/motionscript-dev/motionscript/blob/main/apps/react/src/App.tsx) does it in order).
+
+### One player per timeline, one stage per player
+
+Two `useMotionPlayer` calls give you two fully independent players — separate
+playheads, clocks, audio devices and transports — sharing only the engine:
+
+```tsx
+const before = useMotionPlayer({ engine, document: docA });
+const after  = useMotionPlayer({ engine, document: docB });
+```
+
+A session drives **one** surface, so each player takes one `MotionStage`; a
+second would take the surface from the first.
+
+This package builds on [`@motionscript/core`](https://github.com/motionscript-dev/motionscript/tree/main/packages/core) (the scene graph and
+animation runtime). A browser host will also want
+[`@motionscript/browser`](https://github.com/motionscript-dev/motionscript/tree/main/packages/browser) for `createBrowserEngine`. The types a
+`Player` method mentions (`NodeBox`, `TreeState`, `NodeState`, `NodeOverride`,
+`TrackSpan`, …) are not re-exported here; import them from `@motionscript/core`.
+
+## Usage
+
+```bash
+npm install @motionscript/react @motionscript/core @motionscript/browser
+```
+
+`@motionscript/core`, `react` and `react-dom` (18.2 or later, or 19) are peer dependencies. The package
+is ESM only and declares `sideEffects: false`. `dist/browser/` is a minified
+module for an import map; it imports `react`, `react/jsx-runtime` and
+`@motionscript/core`, and the `manifest.json` beside it names the peers.
+
+See the [docs](https://motionscript.dev/docs) for the full feature set and API
+reference.
+
+## Development
+
+From the monorepo root:
+
+```bash
+pnpm --filter @motionscript/react build      # eslint, declarations, vite build, dist/browser
+pnpm --filter @motionscript/react dev        # vite over examples/, port 5174
+pnpm --filter @motionscript/react test       # vitest in a real Chromium
+pnpm --filter @motionscript/react typecheck  # tsc -b --noEmit
+```
+
+The tests drive the hook against a fake engine inside real Chromium
+(`@vitest/browser-playwright`); install it once with
+`pnpm --filter @motionscript/react exec playwright install chromium`.
+[`apps/react`](https://github.com/motionscript-dev/motionscript/tree/main/apps/react) is the playground: `pnpm dev react` after
+`pnpm build:lib`. The traps in editing the hook are in [`CLAUDE.md`](https://github.com/motionscript-dev/motionscript/blob/main/packages/react/CLAUDE.md).

package/dist/browser/index.js

@@ -0,0 +1,2 @@
+import{useCallback as oe,useEffect as R,useMemo as ce,useRef as i,useState as p,useSyncExternalStore as se}from"react";import{DEFAULT_FPS as ae,DEFAULT_VIEWPORT as ue,clipTimeToFrame as le,isProjectDocument as ie}from"@motionscript/core";import{jsx as Q}from"react/jsx-runtime";function de(r){console.error("Could not start the MotionScript engine.",r)}function we(r,n={}){let{deps:t=[],onError:d}=n,[g,T]=p(null),P=i(r),v=i(d);return R(()=>{P.current=r,v.current=d}),R(()=>{let M=!0,a=null;return new Promise(u=>u(P.current())).then(u=>{if(a=u,!M){u.dispose();return}T(u)}).catch(u=>{M&&(v.current??de)(u)}),()=>{M=!1,a?.dispose(),T(null)}},t),g}function pe(){let r=0,n=new Set;return{subscribe(t){return n.add(t),()=>{n.delete(t)}},getSnapshot:()=>r,set(t){if(t!==r){r=t;for(let d of n)d()}}}}function Re(r){let{playhead:n}=r;return se(n.subscribe,n.getSnapshot,n.getSnapshot)}var z=new WeakSet;function X(r){return z.has(r)}var fe={discoveredTracks:0,totalTracks:0,complete:!1},H=[];function he(r){return{discoveredTracks:r.tracks.filter(n=>n.discovered).length,totalTracks:r.tracks.length,complete:r.complete}}function me(r,n){return r.discoveredTracks===n.discoveredTracks&&r.totalTracks===n.totalTracks&&r.complete===n.complete}function ge(r,n){return r.length===n.length&&r.every((t,d)=>{let g=n[d];return t.trackId===g.trackId&&t.message===g.message&&t.nodeId===g.nodeId&&t.prop===g.prop&&t.stack===g.stack})}function Z(r){let n=r.length===0?H:r.slice();return t=>ge(t,n)?t:n}function Te(r){let{engine:n,document:t,onFramePainted:d}=r,g=t&&ie(t)?t:void 0,T=g?.viewport??r.viewport??n?.viewport??ue,P=g?.fps??r.fps??n?.fps??ae,[v,M]=p(T);(v.width!==T.width||v.height!==T.height)&&M(T);let a=t!==void 0,[u,I]=p(null),[m]=p(pe),[f,k]=p(!1),[y,S]=p(r.speed??1),[x,O]=p(r.muted??!1),[N,B]=p(r.loop??!1),[D,h]=p(!0),[w,U]=p(0),[V,W]=p(H),[$,ee]=p(fe),Y=Math.max(1,Math.round(w*P)),c=i(null),j=i(null),A=i(t),q=i(d),L=i(0),G=i(N),F=i(P),_=i(y),E=i(!1);R(()=>{q.current=d,G.current=N,F.current=P,_.current=y,E.current=f});let[te,re]=p(t);t!==te&&(re(t),t===void 0&&(k(!1),U(0),V.length>0&&W(H)));let b=oe(s=>{U(s.totalDuration),W(Z(s.buildErrors));let e=he(s.precomp);ee(o=>me(o,e)?o:e)},[]),[C]=p(()=>s=>{let e=c.current;if(!e)return Promise.resolve(!1);let o=Math.max(0,Math.round(e.totalDuration*F.current)-1),l=Math.min(Math.max(0,Math.round(s)),o);m.set(l);let ne=++L.current;return h(!0),e.seek(l).then(()=>{let K=ne===L.current;return K&&h(!1),K})});R(()=>{if(!n||!t)return;let s=n.open({document:t,viewport:v,fps:P,onPrecompProgress:()=>b(s.controller)}),e=s.controller;return e.onRenderError=o=>W(Z(o)),e.onFramePainted=o=>q.current?.(o),e.onTime(o=>{let l=Math.floor(le(o,F.current));m.set(l),!(l<Math.round(e.totalDuration*F.current)-1)&&(G.current?e.seekWhilePlaying(0):(E.current=!1,k(!1)))}),c.current=e,j.current=s,A.current=t,I(s),b(e),h(!0),()=>{c.current=null,j.current=null,I(null),z.add(s),s.dispose()}},[n,a,v.width,v.height,P,b]),R(()=>{if(A.current===t)return;A.current=t;let s=j.current;if(!s||!t)return;let e=s.controller;s.replace(t),b(e);let o=Math.max(0,Math.round(e.totalDuration*F.current)-1);m.set(Math.min(m.getSnapshot(),o));let l=++L.current;h(!0),e.whenReplaced().then(()=>{l===L.current&&h(!1)})},[t,b,m]),R(()=>{let s=c.current;s&&(f?s.play(y):s.pause())},[u,f,y]),R(()=>{c.current?.setMuted(x)},[u,x]),R(()=>{let s=c.current;if(!s)return;let e=E.current,o=C(m.getSnapshot());e&&o.then(l=>{!l||c.current!==s||!E.current||s.isPlaying||s.play(_.current)})},[u,m,C]);let[J]=p(()=>{let s=e=>{E.current=!1,k(!1),C(e)};return{playhead:m,play:()=>{E.current=!0,k(!0);let e=c.current;e&&!e.isPlaying&&e.play(_.current)},pause:()=>{E.current=!1,k(!1),c.current?.pause()},toggle:()=>k(e=>{let o=c.current;if(!e&&o){let l=Math.round(o.totalDuration*F.current)-1;m.getSnapshot()>=l&&o.seek(0)}return!e}),seek:s,step:e=>s(m.getSnapshot()+e),seekWhilePlaying:e=>c.current?.seekWhilePlaying(e),setSpeed:e=>S(e),setMuted:e=>O(e),setLoop:e=>B(e),screenshot:async()=>c.current?.screenshot()??void 0,repaint:()=>c.current?.repaint(),getTreeState:()=>c.current?.getTreeState()??null,getNodeProps:e=>c.current?.getNodeState(e)??null,getNodeInitialProps:e=>c.current?.getNodeInitialProps(e)??null,getTrackSpans:()=>c.current?.spans??[],whenReplaced:async()=>{await c.current?.whenReplaced()},getNodeBox:e=>c.current?.getNodeBox(e)??null,getNodePropsAt:e=>c.current?.getNodePropsAt(e)??null,getNodeBoxes:()=>c.current?.getNodeBoxes()??[],projectNode3D:(e,o,l)=>c.current?.projectNode3D(e,o,l)??null,parentPlanePoint:(e,o)=>c.current?.parentPlanePoint(e,o)??null,childPlanePoint:(e,o)=>c.current?.childPlanePoint(e,o)??null,reparentPlacement:(e,o,l)=>c.current?.reparentPlacement(e,o,l)??null,nodeHandles:e=>c.current?.nodeHandles(e)??null,handleValue:(e,o,l)=>c.current?.handleValue(e,o,l)??null,getTextLayout:e=>c.current?.getTextLayout(e)??null,pickNode:(e,o)=>c.current?.pickNode(e,o)??null,setNodeOverride:(e,o)=>c.current?.setNodeOverride(e,o),clearNodeOverrides:e=>c.current?.clearNodeOverrides(e)}});return ce(()=>({...J,session:u,viewport:v,fps:P,isPlaying:f,speed:y,muted:x,loop:N,loading:D,duration:w,totalFrames:Y,errors:V,precomp:$}),[J,u,v,P,f,y,x,N,D,w,Y,V,$])}var Pe=Object.freeze({zoom:1,x:0,y:0});function Me({player:r,renderScale:n=1,surfaceSize:t,view:d,clipToFrame:g,frameBackground:T,className:P,style:v}){let M=i(null),{session:a}=r,u=a?.viewport??r.viewport,I=Math.max(1,Math.round((t?.width??u.width)*n)),m=Math.max(1,Math.round((t?.height??u.height)*n)),f=t&&d?d:Pe,k=t&&d?u:null,y=t&&d?g??!0:!0,S=t&&d?T??"black":"black",x=i(f),O=i(k),N=i(y),B=i(S),D=i(null);return R(()=>{x.current=f,O.current=k,N.current=y,B.current=S,D.current=a?a.surface:null}),R(()=>{let h=M.current,w=D.current;!a||!h||!w||X(a)||(w.pixelRatio=n,w.view=x.current,w.frame=O.current,w.clipToFrame=N.current,w.frameBackground=B.current,w.mount(h),a.controller.repaint())},[a,n,I,m]),R(()=>{let h=D.current;!a||!h||X(a)||(h.view={zoom:f.zoom,x:f.x,y:f.y},h.frame=k,h.clipToFrame=y,h.frameBackground=S,a.controller.repaint())},[a,f.zoom,f.x,f.y,k?.width,k?.height,y,S]),Q("div",{className:P,style:{position:"relative",width:"100%",height:"100%",...v},children:Q("canvas",{ref:M,width:I,height:m,style:{display:a?"block":"none",...t?{position:"absolute",left:"50%",top:"50%",width:`${t.width}px`,height:`${t.height}px`,transform:"translate(-50%, -50%)"}:{width:"100%",height:"100%"}}})})}export{Me as MotionStage,we as useEngine,Te as useMotionPlayer,Re as usePlayhead};
+//# sourceMappingURL=index.js.map