@rig-c/play 1.21.1 → 1.21.3

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="assets/banner.svg" alt="@rig-c/play - plays rigc's compiled model as DOM elements or one canvas" width="100%" />
+  <img src="https://raw.githubusercontent.com/rig-c/play/main/assets/banner.svg" alt="@rig-c/play — Plays rig-c's compiled model as plain DOM elements or one canvas" width="100%" />
 </p>
 
 <p align="center">
@@ -12,8 +12,8 @@
 compiled model document `rigc build` writes, `skeleton.model.json` — as **plain
 DOM**: one absolutely-positioned `<img>` per rigid slot, posed with a single CSS
 `matrix()` write per frame, and deforming meshes on small per-part canvases; or
-as **one canvas** per player. It poses through `rig-c/core`, rigc's own posing
-core, bundled into the package, and links nothing from Esoteric Software.
+as **one canvas** per player. It poses through rigc's bundled `rig-c/runtime`
+and `rig-c/core`, and links nothing from Esoteric Software.
 `rig-play` is the convenience install name; `spine-html` is the legacy install name.
 The compiler is [@rig-c/core](https://github.com/rig-c/core) (npm `@rig-c/core`)
 and the part generator [rig-c/parts](https://github.com/rig-c/parts).
@@ -39,65 +39,14 @@ links to either earlier name keep working.
 
 ### Measured
 
-**Standing comparison against `@esotericsoftware/spine-webgl 4.3.13` (`npm run bench`, #39)** —
-measured on 2026-10-17 in **headed** Chromium `151.0.7922.34` on an Apple M4 GPU
-(`ANGLE (Apple, ANGLE Metal Renderer: Apple M4, Unspecified Version)`, macOS `Darwin 25.6.0`,
-10 cores, 32 GiB RAM, `1280×720` viewport, `devicePixelRatio: 1`, 100 warm-up frames +
-600 measured frames per row, `loadPerCoreBefore: 0.33`, `loadPerCoreAfter: 0.33` under the
-`1.0` load guard; each row is its own page load with only that runtime animating, and grid
-scenes batch the official skeletons through one shared WebGL canvas while `small players`
-mounts independent player instances):
-
-| scene | runtime | rig | clipped to | fps | pose ms | render ms | drawn players | triangles | draw calls | origin Δpx | live contexts |
-| --- | --- | --- | --- | --: | --: | --: | --: | --: | --: | --: | --: |
-| 1 meshed rig animating | dom | `portrait-packed` `turn` | pane | 59.99 | 0.17 | 0.16 | —/1 | 48 | — | 0.007 | —/1 |
-| 1 meshed rig animating | canvas | `portrait-packed` `turn` | pane | 59.99 | 0.23 | 0.18 | —/1 | 0 | 0 | 0.007 | —/1 |
-| 1 meshed rig animating | official | `portrait-packed` `turn` | pane | 60.00 | 0.05 | 0.13 | 1/1 | 88 | 1 | 0.000 | 1/1 |
-| 4 meshed rigs animating | dom | `portrait-packed` `turn` | pane | 60.01 | 0.46 | 0.48 | —/4 | 96 | — | 0.009 | —/1 |
-| 4 meshed rigs animating | canvas | `portrait-packed` `turn` | pane | 60.00 | 0.60 | 0.49 | —/4 | 176 | 2 | 0.009 | —/1 |
-| 4 meshed rigs animating | official | `portrait-packed` `turn` | pane | 59.99 | 0.13 | 0.17 | 4/4 | 352 | 1 | 0.000 | 1/1 |
-| 16 meshed rigs animating | dom | `portrait-packed` `turn` | pane | 60.00 | 0.66 | 0.74 | —/16 | 384 | — | 0.010 | —/1 |
-| 16 meshed rigs animating | canvas | `portrait-packed` `turn` | pane | 59.87 | 0.84 | 0.50 | —/16 | 704 | 8 | 0.010 | —/1 |
-| 16 meshed rigs animating | official | `portrait-packed` `turn` | pane | 60.00 | 0.21 | 0.30 | 16/16 | 1408 | 1 | 0.000 | 1/1 |
-| 36 meshed rigs animating | dom | `portrait-packed` `turn` | pane | 48.28 | 1.24 | 1.42 | —/36 | 1104 | — | 0.010 | —/1 |
-| 36 meshed rigs animating | canvas | `portrait-packed` `turn` | pane | 60.11 | 1.15 | 0.85 | —/36 | 1760 | 20 | 0.010 | —/1 |
-| 36 meshed rigs animating | official | `portrait-packed` `turn` | pane | 60.00 | 0.43 | 0.49 | 36/36 | 3168 | 1 | 0.000 | 1/1 |
-| 64 meshed rigs animating | dom | `portrait-packed` `turn` | pane | 29.07 | 2.13 | 2.69 | —/64 | 1824 | — | 0.010 | —/1 |
-| 64 meshed rigs animating | canvas | `portrait-packed` `turn` | pane | 53.99 | 1.62 | 1.17 | —/64 | 3168 | 36 | 0.010 | —/1 |
-| 64 meshed rigs animating | official | `portrait-packed` `turn` | pane | 59.99 | 0.42 | 0.54 | 64/64 | 5632 | 1 | 0.000 | 1/1 |
-| 1 meshed rig animating (canvas2d) | dom | `portrait-packed` `turn` | pane | 60.00 | 0.18 | 0.28 | —/1 | 48 | — | 0.007 | —/0 |
-| 1 meshed rig animating (canvas2d) | canvas | `portrait-packed` `turn` | pane | 60.00 | 0.20 | 0.18 | —/1 | 88 | 1 | 0.007 | —/1 |
-| 1 meshed rig animating (canvas2d) | official | `portrait-packed` `turn` | pane | 59.99 | 0.06 | 0.14 | 1/1 | 88 | 1 | 0.000 | 1/1 |
-| 16 meshed rigs animating (canvas2d) | dom | `portrait-packed` `turn` | pane | 59.89 | 0.65 | 0.99 | —/16 | 384 | — | 0.010 | —/0 |
-| 16 meshed rigs animating (canvas2d) | canvas | `portrait-packed` `turn` | pane | 60.00 | 0.93 | 0.59 | —/16 | 792 | 9 | 0.010 | —/1 |
-| 16 meshed rigs animating (canvas2d) | official | `portrait-packed` `turn` | pane | 60.00 | 0.18 | 0.31 | 16/16 | 1408 | 1 | 0.000 | 1/1 |
-| 1 held pose | dom | `portrait-packed` `turn` | pane | 60.11 | 0.00 | 0.15 | —/1 | 0 | — | 0.007 | —/1 |
-| 1 held pose | canvas | `portrait-packed` `turn` | pane | 60.02 | 0.01 | 0.11 | —/1 | 0 | 0 | 0.007 | —/1 |
-| 1 held pose | official | `portrait-packed` `turn` | pane | 60.00 | 0.00 | 0.13 | 1/1 | 88 | 1 | 0.000 | 1/1 |
-| 16 held poses | dom | `portrait-packed` `turn` | pane | 60.09 | 0.00 | 0.43 | —/16 | 0 | — | 0.010 | —/1 |
-| 16 held poses | canvas | `portrait-packed` `turn` | pane | 59.99 | 0.01 | 0.55 | —/16 | 0 | 0 | 0.010 | —/1 |
-| 16 held poses | official | `portrait-packed` `turn` | pane | 60.08 | 0.00 | 0.35 | 16/16 | 1408 | 1 | 0.000 | 1/1 |
-| 64 held poses | dom | `portrait-packed` `turn` | pane | 59.99 | 0.02 | 2.43 | —/64 | 0 | — | 0.010 | —/1 |
-| 64 held poses | canvas | `portrait-packed` `turn` | pane | 60.10 | 0.02 | 2.56 | —/64 | 0 | 0 | 0.010 | —/1 |
-| 64 held poses | official | `portrait-packed` `turn` | pane | 60.10 | 0.00 | 0.90 | 64/64 | 5632 | 1 | 0.000 | 1/1 |
-| 1 rigid rig animating | dom | `walk-packed` `walk` | pane | 59.99 | 0.30 | 0.15 | —/1 | 0 | — | 0.007 | —/1 |
-| 1 rigid rig animating | canvas | `walk-packed` `walk` | pane | 59.99 | 0.33 | 0.21 | —/1 | 30 | 1 | 0.007 | —/1 |
-| 1 rigid rig animating | official | `walk-packed` `walk` | pane | 60.00 | 0.04 | 0.16 | 1/1 | 30 | 1 | 0.000 | 1/1 |
-| 16 rigid rigs animating | dom | `walk-packed` `walk` | pane | 60.00 | 0.77 | 0.65 | —/16 | 0 | — | 0.010 | —/1 |
-| 16 rigid rigs animating | canvas | `walk-packed` `walk` | pane | 60.00 | 0.62 | 0.47 | —/16 | 480 | 16 | 0.010 | —/1 |
-| 16 rigid rigs animating | official | `walk-packed` `walk` | pane | 60.00 | 0.15 | 0.22 | 16/16 | 480 | 1 | 0.000 | 1/1 |
-| 64 rigid rigs animating | dom | `walk-packed` `walk` | pane | 59.89 | 1.58 | 1.63 | —/64 | 0 | — | 0.010 | —/1 |
-| 64 rigid rigs animating | canvas | `walk-packed` `walk` | pane | 42.00 | 1.50 | 1.21 | —/64 | 1920 | 64 | 0.010 | —/1 |
-| 64 rigid rigs animating | official | `walk-packed` `walk` | pane | 60.00 | 0.14 | 0.13 | 64/64 | 1920 | 1 | 0.000 | 1/1 |
-| 8 small players | dom | `walk-packed` `walk` | cell | 60.00 | 0.24 | 0.18 | —/8 | 0 | — | 0.012 | —/1 |
-| 8 small players | canvas | `walk-packed` `walk` | cell | 60.00 | 0.33 | 0.30 | —/8 | 240 | 8 | 0.012 | —/1 |
-| 8 small players | official | `walk-packed` `walk` | cell | 60.00 | 0.09 | 0.24 | 8/8 | 240 | 8 | 0.007 | 8/8 |
-| 20 small players | dom | `walk-packed` `walk` | cell | 60.00 | 1.03 | 0.84 | —/20 | 0 | — | 0.015 | —/1 |
-| 20 small players | canvas | `walk-packed` `walk` | cell | 59.99 | 0.69 | 0.54 | —/20 | 600 | 20 | 0.015 | —/1 |
-| 20 small players | official | `walk-packed` `walk` | cell | 60.00 | 0.13 | 0.24 | 16/20 | 480 | 16 | 0.006 | 16/20 |
-
-Where each side wins and loses on that table, the Safari mesh-backend readings
-and the 0.x numbers are in [docs/BENCHMARK.md](docs/BENCHMARK.md).
+The [standing comparison and its conditions](https://github.com/rig-c/play/blob/main/docs/BENCHMARK.md#measured) record these tradeoffs:
+
+| scene | observation in that comparison |
+| --- | --- |
+| High-count meshed grids | Batched official WebGL leads. |
+| Held poses | DOM and canvas modes skip rasterization. |
+| Rigid-heavy grids | DOM avoids per-player canvas blits. |
+| Many independent players | DOM and canvas share a WebGL context across players. |
 
 ## Install
 
@@ -112,8 +61,7 @@ The package plays rigs built by [rigc](https://github.com/rig-c/core):
 is what the player loads, and it states everything posing and drawing need —
 the skeleton, the animations, and where every region sits on its page — so the
 `.atlas` and `skeleton.json` beside it are not fetched. Poses are computed by
-`rig-c/core`, rigc's own posing core, which is bundled into this package: there
-is nothing else to install.
+the bundled `rig-c/runtime` and `rig-c/core`: there is nothing else to install.
 
 ```ts
 import { loadModel, RigPlayer } from '@rig-c/play';
@@ -180,23 +128,23 @@ package built from this tree.
 
 ## Where to read next
 
-- [docs/REFERENCE.md](docs/REFERENCE.md) — what the player does once it is on
+- [docs/REFERENCE.md](https://github.com/rig-c/play/blob/main/docs/REFERENCE.md) — what the player does once it is on
   the page: what ships and what is measured (*Status*), then every API section
   from wind, gravity and dragging to the runtime knobs and what they cost.
   `physicsMoved(scope, motion)` supplies apparent world movement to named bone,
   subtree or constraint physics; `moved()` continues to report whole-rig motion.
   See the reference for explicit pivots, units and evaluation/history limits.
-- [docs/MIGRATION.md](docs/MIGRATION.md) — coming from 1.8 (meshes draw through
-  WebGL by default since 1.9) and from `spine-html` 0.8 (the 0.8 → 1.0 table,
-  what has no counterpart, before and after).
-- [docs/TESTING.md](docs/TESTING.md) — how the suite holds the picture: the two
+- [docs/MIGRATION.md](https://github.com/rig-c/play/blob/main/docs/MIGRATION.md) — adding live-frame consumers, coming
+  from 1.8 (meshes draw through WebGL by default since 1.9) and from `spine-html`
+  0.8 (the 0.8 → 1.0 table, what has no counterpart, before and after).
+- [docs/TESTING.md](https://github.com/rig-c/play/blob/main/docs/TESTING.md) — how the suite holds the picture: the two
   render modes' parity, the clipping oracle, the loading harness, and the
   independent official raster oracle.
-- [docs/BENCHMARK.md](docs/BENCHMARK.md) — the readings behind *Measured*, and
+- [docs/BENCHMARK.md](https://github.com/rig-c/play/blob/main/docs/BENCHMARK.md) — the readings behind *Measured*, and
   the bench that produces them: scenes, framing, and what a headless number is
   not evidence of.
-- [CHANGELOG.md](CHANGELOG.md) — what each version changed;
-  [RELEASING.md](RELEASING.md) — how a version is cut.
+- [CHANGELOG.md](https://github.com/rig-c/play/blob/main/CHANGELOG.md) — what each version changed;
+  [RELEASING.md](https://github.com/rig-c/play/blob/main/RELEASING.md) — how a version is cut.
 
 ## Demo (this repository)
 
@@ -224,52 +172,28 @@ deterministic captures.
 
 ## How it works
 
-`loadModel` reads the rig's compiled model document (`rig-c/core`'s `readModel`),
-and `RigPlayer` opens an animation on a live track (`openTrack`): bones,
-constraints, physics, deform and draw order are posed by the core — all
-CPU-side, renderer-agnostic — one `dt` at a time. At load time each region of
-the document's `pages` section is cut into its own bitmap (rotation restored),
-one blob URL per region — except regions that already cover their whole page,
-which are used as they are. Per frame, the pose becomes a `PosedFrame`: for
-each slot in draw order, a region's four world corners (order **BL, UL, UR,
-BR**) or a mesh's world vertices, page UVs and triangles, its tint, blend and
-clip. For a region: flip Y (the frame is Y-up), derive the affine from three
+`loadModel` reads the rig's compiled model document (`rig-c/core`'s `readModel`).
+With the default `poser: 'auto'`, `RigPlayer` uses `rig-c/runtime`'s
+`compileRuntime` and `RuntimePose` for covered models and animations, drawing
+from a borrowed `LiveFrame` exposed by `player.liveFrame()`. Features and
+operations outside that path's coverage use the `rig-c/core` oracle —
+`openTrack` for a single track, `openTracks` for track composition. Models with
+physics constraints stay on that oracle path. `player.poser` reports `"runtime"` or
+`"oracle: <reason>"`; `poser: 'oracle'` selects the oracle explicitly. Posing
+stays CPU-side and renderer-agnostic, advancing one `dt` at a time.
+Both renderers accept a borrowed `LiveFrame` or a detached `PosedFrame`.
+`player.posedFrame()` returns a snapshot that survives later pose mutations;
+a live frame is valid only until the next pose mutation. See
+[Borrowing a live frame](https://github.com/rig-c/play/blob/main/docs/REFERENCE.md#borrowing-a-live-frame) for the
+buffer layout, lifetime and fallback policy.
+At load time each region of the document's `pages` section is cut into its own
+bitmap (rotation restored), one blob URL per region — except regions that
+already cover their whole page, which are used as they are. Both frame forms
+describe, for each slot in draw order, a region's four world corners (order
+**BL, UL, UR, BR**) or a mesh's world vertices, page UVs and triangles, its tint,
+blend and clip. For a region: flip Y (the frame is Y-up), derive the affine from three
 corners, write one `matrix()` string. That's the whole rigid render path.
 
 ## License
 
-@rig-c/play's own code is MIT (see [LICENSE](LICENSE)). That says nothing about Spine,
-so here is what is true of this package and this repository, stated plainly:
-
-1. The published package — `@rig-c/play`, and `rig-play` and `spine-html`, the same files — **links
-   nothing from Esoteric Software**. Its one module bundles the renderer and
-   `rig-c/core` (MIT), which poses rigc's model document; no part of the
-   [Spine Runtimes](https://github.com/EsotericSoftware/spine-runtimes) is in it or
-   required beside it.
-2. Development tooling pins `@esotericsoftware/spine-webgl` 4.3.13 and its matching
-   spine-core dependency for the independent oracle and comparison/benchmark.
-   The [Spine Runtimes License Agreement](https://esotericsoftware.com/spine-runtimes-license)
-   covers those runtimes, not this project's MIT license. They remain outside
-   production source, the public API and the library package; package guards
-   and the library-only pack allowlist hold that boundary.
-   The optional load-profile harness keeps `spine-pixi-v8` 4.3.13 and PixiJS
-   in a separate private install under `bench/oracle`.
-3. `rigc build`, which this repository runs to make its fixtures, also writes Spine
-   skeleton data (`skeleton.json` and `skeleton.atlas`) beside each model document.
-   Development tooling reads this paired export independently. Generated fixtures
-   remain gitignored and excluded from the library package. See [NOTICE.md](NOTICE.md).
-4. A product that plays that Spine data with a Spine Runtime has integrated the Spine
-   Runtimes, whose licence permits it **under Section 2 of the
-   [Spine Editor License Agreement](https://esotericsoftware.com/spine-editor-license)**,
-   or otherwise on the condition that **each user of the product obtains their own
-   Spine Editor license** — the licence's own two routes, restated, not a term of
-   this project.
-
-> **What a consumer does with rigc's Spine-format output is governed by Esoteric
-> Software's terms**, not by this package — @rig-c/play neither adds those terms nor
-> removes them.
-
-The optional load-profile harness fetches checksum-pinned spineboy and raptor
-example assets together with their upstream `license.txt`. These development
-fixtures are gitignored and excluded from the library package. See
-[NOTICE.md](NOTICE.md) for the full notice.
+See [NOTICE.md](NOTICE.md) for licensing and third-party notices.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/play",
-  "version": "1.21.1",
+  "version": "1.21.3",
   "description": "Plays skeleton.model.json written by rigc build as plain DOM elements — rigid slots as <img> posed by CSS matrix, deform meshes on small per-part canvases — or as one canvas.",
   "type": "module",
   "license": "MIT",