@rig-c/play 1.21.2 → 1.22.0

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">
@@ -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
 
@@ -179,23 +128,24 @@ 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) — adding live-frame consumers, coming
+- [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](docs/TESTING.md) — how the suite holds the picture: the two
+- [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.
+- [`skills/rig-play/SKILL.md`](skills/rig-play/SKILL.md) — the agent skill that routes a web-page playback or live-frame request to the guides above.
 
 ## Demo (this repository)
 
@@ -232,13 +182,11 @@ operations outside that path's coverage use the `rig-c/core` oracle —
 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](docs/REFERENCE.md#borrowing-a-live-frame) for the
+[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
@@ -249,39 +197,4 @@ 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` and `rig-c/runtime` (MIT), which pose 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.2",
+  "version": "1.22.0",
   "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",
@@ -60,7 +60,8 @@
     "dist/liveFrame.d.ts",
     "dist/liveFrame.d.ts.map",
     "dist/liveFrameSource.d.ts",
-    "dist/liveFrameSource.d.ts.map"
+    "dist/liveFrameSource.d.ts.map",
+    "skills"
   ],
   "sideEffects": false,
   "scripts": {

package/skills/rig-play/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: rig-play
+description: Play a rig built by rigc (skeleton.model.json) on a web page with @rig-c/play — as plain DOM (<img> for rigid slots posed by CSS matrix(), small per-part canvases for deforming meshes) or as one <canvas> per player, with multi-track playback, attachment sets, wind and gravity physics, bone adjustments and live-frame borrowing. Use when the request puts a compiled rig into the DOM or a standalone page canvas, or integrates a custom consumer over LiveFrame or PosedFrame. Not for authoring or compiling a rig (use rigc or rig-parts), retargeting a pose sequence (use rig-pose), or drawing inside PixiJS, Phaser or Three.js (use the rig-pixi, rig-phaser or rig-three skill).
+license: MIT
+compatibility: Browser ES2022 runtime (DOM and Canvas2D/WebGL). The canonical npm package is @rig-c/play (npm i @rig-c/play; rig-play is the convenience install name, spine-html is the legacy install name). Loads skeleton.model.json written by rigc build (@rig-c/core); bundles its own posing core and links no Esoteric Software runtime.
+---
+
+# @rig-c/play — playing a built rig on a web page
+
+Load this when a built rig (`skeleton.model.json` and its page images from
+`rigc build`, authored under `--profile rig-play`) goes **onto a web page as DOM
+elements or a standalone canvas**, or when a custom renderer consumes
+`player.liveFrame()` or `player.posedFrame()`. Every rule below is owned by
+[docs/REFERENCE.md](https://github.com/rig-c/play/blob/main/docs/REFERENCE.md);
+this file says when to open it and when an engine adapter is the better route.
+
+## When an engine adapter is the better route
+
+- **The page already runs PixiJS 8, Phaser 4.2+ or Three.js.** Do not stack a
+  separate DOM root or second `<canvas>` over an engine canvas: use
+  [`@rig-c/pixi`](https://github.com/rig-c/adapters/tree/main/packages/pixi) (`rig-pixi` skill),
+  [`@rig-c/phaser`](https://github.com/rig-c/adapters/tree/main/packages/phaser) (`rig-phaser` skill) or
+  [`@rig-c/three`](https://github.com/rig-c/adapters/tree/main/packages/three) (`rig-three` skill) so the rig draws
+  inside the host's scene graph, camera, draw order and WebGL context while
+  posing through `@rig-c/play`.
+- **High-count meshed grids.** Where many meshed instances are drawn together,
+  batched WebGL draw calls lead DOM/per-player canvas modes; use a host WebGL
+  adapter or check the scene tradeoffs in [docs/BENCHMARK.md](https://github.com/rig-c/play/blob/main/docs/BENCHMARK.md#measured).
+
+## Non-negotiables
+
+- **Load `skeleton.model.json`, never a Spine export.** `loadModel` reads
+  `rigc-compiled/*` (with `pages`) emitted by `rigc build` and refuses
+  `skeleton.json`, `.skel` and `rigc-compiled/1` by name before fetching —
+  [REFERENCE.md](https://github.com/rig-c/play/blob/main/docs/REFERENCE.md#status).
+- **Layout, Y-up origin and `syncPixelRatio()` belong to the caller.** The root
+  element is the rig's world origin (`Y` grows upward); after scaling the root
+  or container in CSS, call `player.renderer.syncPixelRatio()` so mesh canvases
+  raster at screen size rather than `1 / scale²` —
+  [README.md](https://github.com/rig-c/play/blob/main/README.md#a-minimal-page) and
+  [REFERENCE.md](https://github.com/rig-c/play/blob/main/docs/REFERENCE.md#runtime-knobs-and-what-they-cost).
+- **Respect `LiveFrame` lease lifetime.** `player.liveFrame()` is a borrowed
+  buffer valid only until the next pose mutation (`frame`, `seek`, `play`,
+  `setAttachmentSet`, physics or bone adjust); call `player.posedFrame()` when a
+  detached snapshot must survive later mutations —
+  [REFERENCE.md](https://github.com/rig-c/play/blob/main/docs/REFERENCE.md#borrowing-a-live-frame).
+- **Dispose player before assets.** Call `player.dispose()` first to remove DOM
+  elements and release shared WebGL page-texture references, then
+  `assets.dispose()` (or `revokeRegions`) once no player draws from those assets
+  so cut region blob URLs are freed —
+  [REFERENCE.md](https://github.com/rig-c/play/blob/main/docs/REFERENCE.md#what-unloading-frees).
+
+## What this will not do
+
+- Compile, gate or edit a rig (build with `rigc build --profile rig-play` first).
+- Load Spine `skeleton.json` or `.skel` exports, or link any `@esotericsoftware/*` runtime.
+- Render two-colour dark tint (`rgb2`) in DOM mode or the canvas2d fallback (supported on `CanvasRenderer`'s WebGL path; [REFERENCE.md](https://github.com/rig-c/play/blob/main/docs/REFERENCE.md#status)).
+- Re-measure CSS scale per frame (`syncPixelRatio()` forces a layout read and is caller-invoked only).
+
+## Read, in this order
+
+1. [README.md](https://github.com/rig-c/play/blob/main/README.md#install) —
+   `loadModel` + `RigPlayer`, fitting `assets.stage ?? player.bounds()` to a
+   container, `syncPixelRatio()` and cleanup (`node_modules/@rig-c/play/README.md` in an install).
+2. [docs/REFERENCE.md](https://github.com/rig-c/play/blob/main/docs/REFERENCE.md) —
+   [what ships and what is measured](https://github.com/rig-c/play/blob/main/docs/REFERENCE.md#status),
+   [wind, gravity and dragging](https://github.com/rig-c/play/blob/main/docs/REFERENCE.md#wind-gravity-and-dragging-the-rig),
+   [borrowing a live frame](https://github.com/rig-c/play/blob/main/docs/REFERENCE.md#borrowing-a-live-frame),
+   [attachment sets (`sets.json`)](https://github.com/rig-c/play/blob/main/docs/REFERENCE.md#attachment-sets-setsjson),
+   [several tracks](https://github.com/rig-c/play/blob/main/docs/REFERENCE.md#several-tracks),
+   [adjusting bones](https://github.com/rig-c/play/blob/main/docs/REFERENCE.md#adjusting-bones),
+   [live physics parameters](https://github.com/rig-c/play/blob/main/docs/REFERENCE.md#live-physics-parameters),
+   [what unloading frees](https://github.com/rig-c/play/blob/main/docs/REFERENCE.md#what-unloading-frees) and
+   [runtime knobs](https://github.com/rig-c/play/blob/main/docs/REFERENCE.md#runtime-knobs-and-what-they-cost).
+3. [docs/MIGRATION.md](https://github.com/rig-c/play/blob/main/docs/MIGRATION.md) and
+   [docs/BENCHMARK.md](https://github.com/rig-c/play/blob/main/docs/BENCHMARK.md).
+
+`docs/` lives in the GitHub repository and is not packed into `node_modules/@rig-c/play`;
+the installed package carries `README.md` and the exact TypeScript declarations
+under `node_modules/@rig-c/play/dist/*.d.ts`.