rig-play 1.10.0 → 1.11.0

package/NOTICE.md

@@ -11,20 +11,24 @@ document `rigc build` writes. No part of the
 [Spine Runtimes](https://github.com/EsotericSoftware/spine-runtimes) is in it,
 imported by it, or required beside it.
 
-**This repository links no Spine runtime either**, since #63.
-`@esotericsoftware/spine-core` and `@esotericsoftware/spine-webgl` are not
-dependencies of any kind — not `dependencies`, not `peerDependencies`, not
-`devDependencies` — and no lockfile entry names them. The test suite and the
-benchmark compare the package's two render modes with each other; the poses
-are rig-c's, held to the Spine runtime by rig-c's own CI, not here.
-`tests/package.spec.ts` asserts all of that, and that nothing the published
-package contains names an `@esotericsoftware/` package.
+**Development tooling uses the official Spine WebGL runtime.** Issue #39
+reintroduces `@esotericsoftware/spine-webgl` 4.3.13 as a pinned devDependency,
+with its matching `@esotericsoftware/spine-core` dependency, for the independent
+pixel oracle and comparison/benchmark tooling. These are licensed under the
+[Spine Runtimes License Agreement](https://esotericsoftware.com/spine-runtimes-license),
+updated April 5, 2025, copyright 2013–2025 Esoteric Software LLC; they are not
+covered by this project's MIT licence. Their licence and copyright notices
+apply to use and redistribution of that tooling. The earlier removal in #63
+remains the history of the production player: no runtime is added back to its
+public API or published library. `tests/package.spec.ts` checks the exact
+development exception and the runtime-free shipped code and declarations.
 
 One thing in this repository is Spine data, and it is worth stating where it
 sits. `rigc build`, which `scripts/fetch-assets.sh` runs to make the fixtures,
 writes **Spine skeleton data** (`skeleton.json` and `skeleton.atlas`) beside
-each model document, into the gitignored `public/rigs/`. Nothing here reads
-it, and it is neither committed nor published.
+each model document, into the gitignored `public/rigs/`. The development oracle
+and comparison tooling read that paired export independently of the model
+reader. These generated files are neither committed nor published in the package.
 
 ### What that means, as a chain of facts
 

package/README.md

@@ -38,6 +38,81 @@ 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:
+
+- **High-count meshed grids (`36` and `64 meshed rigs animating`) — `official` wins**: batching
+  all 64 skeletons into one WebGL canvas holds `59.99 fps` (`5,632 triangles` in `1 draw call`),
+  while `canvas` mode drops to `53.99 fps` (per-player `drawImage` blits from the shared WebGL
+  context) and `dom` mode drops to `48.28 fps` at 36 rigs and `29.07 fps` at 64 rigs (per-part
+  mesh canvas blits + DOM compositing). Up to 16 animating meshed rigs all three hold `60 fps`.
+- **Held poses (`1`, `16`, `64 held poses`) — `dom` and `canvas` skip rasterization**: both
+  modes reuse their rasters (`0 triangles`, `0 draw calls`), while `official` redraws
+  `88` / `1,408` / `5,632 triangles` every frame.
+- **Rigid-heavy grids (`64 rigid rigs animating`) — `dom` and batched `official` hold `60 fps`**:
+  `dom` updates `<img>` CSS transforms (`0 triangles`, `59.89 fps`), whereas `canvas` pays 64
+  per-player `drawImage` blits (`42.00 fps`).
+- **Many independent players on one page (`20 small players`) — `dom` and `canvas` draw all 20;
+  `official` loses 4 to the browser's 16-context WebGL cap**: both `@rig-c/play` modes share at
+  most one WebGL context across the page, while mounting 20 independent `spine-webgl` players
+  evicts 4 contexts (`16/20 drawn players`, `16/20 live contexts`).
+
 **The element mode's mesh backend is `'webgl'` by default since 1.9 (#109)**, read off
 macOS Safari on 2026-10-13 (1.8.2, gallery rig `look-packed`: 4 meshes, 464
 triangles, `sweep`; the demo's stats line after a 30 s settle; the Mac was also
@@ -131,9 +206,11 @@ default stays `dom`.
   not expressible this way and stays out of scope
 - ✅ DPR-aware mesh canvas backing store: `renderer.pixelRatio` (defaults to
   `devicePixelRatio`; if you scale the root element, fold that scale in)
-- ✅ Dirty-skip: a mesh whose canvas-space vertices didn't change reuses last frame's
-  raster — the CSS translate still tracks it, so parts that hold a pose (or move by
-  whole pixels) pay zero raster. 10 frozen spineboys: WebKit ~141 → ~0.5 ms/frame
+- ✅ Dirty-skip: a mesh whose canvas-space vertices match the last raster reuses it;
+  whole-pixel translations allow at most half a Float32 ULP at the current world
+  coordinate, strictly less than half a pixel. CSS still tracks the translation, while
+  stationary axes stay exact and the comparison anchor changes only on a redraw.
+  10 frozen spineboys: WebKit ~141 → ~0.5 ms/frame
 - ✅ Clipping attachments as element-level CSS `clip-path`: spine-core's semantics
   (one active clip at a time, applied from the clip's slot through its end slot
   inclusive), with the polygon expressed in each element's own local frame — the
@@ -294,6 +371,11 @@ layer answers the same world, and a `seek` replays under the environment as it
 stands — no history is kept. A rig with no physics ignores both.
 `tests/readme-page.spec.ts` runs this block in the minimal page.
 
+The demo's `wind.html` is the same thing with controls: wind and gravity
+sliders, a drag on the stage, and the rig named by `?model=` (the `cloth` test
+rig by default; `bun run dev`, then `/wind.html?model=rigs/<name>/skeleton.model.json`).
+`tests/wind-page.spec.ts` holds it.
+
 The player owns one track: `play(name, { loop })` opens an animation at its first
 pose, `frame(dt)` steps it (or `advance(dt)` then `draw()`, to time the two
 apart), `pause()` / `resume()` hold and release it, `timeScale` scales every
@@ -392,6 +474,52 @@ const front = new DomRenderer(frontRoot, assets.regionImages, assets.pageImages)
 front.render(player.posedFrame(['hand_f', 'arm_f_lo']));
 ```
 
+### Attachment sets (`sets.json`)
+
+A build from `@rig-c/parts` (or authored alongside a rig) may ship a `sets.json`
+sidecar beside `skeleton.model.json` declaring named attachment sets — an
+expression, a viseme, a side view — under spec `"rig-parts-sets/1"` or
+`"spine-parts-sets/1"`:
+
+```json
+{
+  "spec": "rig-parts-sets/1",
+  "sets": {
+    "smile": {
+      "slots": { "face": "face_smile", "prop": "prop_star" },
+      "hides": []
+    },
+    "wink": {
+      "slots": { "face": "face_wink" },
+      "hides": ["prop"]
+    }
+  }
+}
+```
+
+`loadModel` probes `sets.json` in the model document's directory by default
+(treating a 404 as "no sets"; pass `setsUrl: null` to skip the probe, or a URL
+string to require one at another path) and validates every slot and attachment
+name against the model document. `player.sets()` (and `assets.sets`) returns the
+declared `readonly RigSet[]` (`{ name, slots, hides }`), and `player.setSet(name)`
+switches the active set at runtime (#134):
+
+```ts
+player.sets();          // [{ name: 'smile', slots: { ... }, hides: [] }, ...]
+player.setSet('smile'); // covered slots take the set's attachments; <slot>_still and hides are hidden
+player.set;             // 'smile'
+player.setSet(null);    // restore base / track attachments
+```
+
+The active set is applied immediately to the held pose (including the setup pose
+before `play`) and after track evaluation on every subsequent `advance`, so a
+track key on a covered slot is overridden while the set is active and restored
+on the next frame when cleared with `setSet(null)`. Uncovered slots keep their
+track attachments, mesh deforms and sequence frames untouched; when no set is
+active (`null`), track evaluation runs with zero extra work and produces
+byte-identical poses. An unknown set name throws by name; on a build without
+`sets.json`, `sets()` is empty (`[]`) and `setSet` throws.
+
 ### Several tracks
 
 A base on track 0, a layer over it, a one-shot played once and mixed back out —
@@ -937,23 +1065,17 @@ deterministic captures.
 bun run test   # builds + serves the demo, then runs chromium + webkit
 ```
 
-Playwright drives the demo (`tests/`, config in `playwright.config.ts`; CI
-runs the same suite on ubuntu, one job). Every scene is a rig built by
-`rigc build` and posed by `rig-c/core` through `RigPlayer` — rigc's gallery rigs,
-and three test rigs authored in this repository (`tests/rigs/`) for what the
-gallery does not carry: `figure` (clipping attachments in rigc's format —
-convex, inverse, nested, whole-skeleton — rigid parts on turned bones, two grid
-meshes), `glow` (additive slots with slot colours over two weighted meshes) and
-`turned` (a region packed turned 90° on a hand-packed page). No Spine runtime
-is installed or compared against: the pose is rig-c's, held to spine-core at
-tolerance 0 by rig-c's own CI, and a pose doubt is a rigc issue. The visual
-checks are **A/B within one run**: no golden snapshots are committed (they rot
-across platforms/GPUs) — instead the same deterministic pose (`?time` +
-`?timescale=0`) is screenshotted twice in the same engine and the buffers are
-diffed directly with a shift-tolerant comparison, so missing parts, wrong
-colors, and tint/blend/clip divergence fail regardless of platform.
-
-**The picture gate** is the two render modes drawing the same picture: every
+Playwright drives rigc-built gallery and procedural test rigs through the
+production `RigPlayer`; its pose comes from `rig-c/core`. CI runs the same
+suite on Ubuntu with Chromium and WebKit. Internal parity captures the same
+deterministic pose in two modes/backends within one engine. An independent
+development oracle also reads the paired Spine export through the official
+WebGL runtime. No snapshot goldens are committed. Residue limits are measured
+per engine, case and renderer; an A/B design alone does not make a measured
+budget portable to another platform. Pose discrepancies remain rigc issues;
+the independent oracle checks the resulting raster.
+
+**Internal picture parity** checks the two render modes drawing the same picture: every
 scene captured in the DOM mode and in the canvas mode and diffed — bad pixels at
 most 1.5% of drawn content on the test-rig scenes (measured floors 0.007–0.524%,
 macOS Chromium; each scene's own feature dropped from the canvas mode — tint,
@@ -989,16 +1111,58 @@ resolving, so blob ownership — every unpacked URL freed, nothing the caller
 owns touched, nothing stranded by a failed load — is asserted rather than
 assumed.
 
-## Benchmark: DOM mode vs canvas mode
+### Independent official raster oracle
+
+`tests/oracle.spec.ts` compares real DOM WebGL, DOM canvas2d and whole-canvas
+output with `@esotericsoftware/spine-webgl` 4.3.13. The official reader parses
+the same build's Spine JSON, atlas and original PNGs independently; it never
+receives a `PosedFrame` or the player's alpha-corrected textures. JSON SHA-256
+binds the export to the compiled model, and generation/page dimensions fail
+closed. Both posers receive the same fixed-step history, crop, origin, scale
+and DPR 1; world geometry must agree exactly before raster acceptance.
+
+Captures include the actual images, element canvases, CSS transforms, tint
+and clipping. Transparent RGB remains diagnostic, except for additional narrow
+raw checks on the whole-canvas PMA case. Acceptance compares those
+same captured bytes on black and white backgrounds with the shared pixel
+differ, and separately constrains alpha coverage, sum, unequal-pixel count
+and maximum. `tests/oracleLimits.ts` stores measured engine/case/mode floors:
+zero stays exact; nonzero counts receive 10% plus two units, and nonzero byte
+maxima one byte. macOS and Linux have separately measured tables; other
+platforms are refused as uncalibrated. Tests never regenerate limits from the
+image under test.
+
+Cases cover geometry, tint, clipping, draw order with multiply/screen,
+rotated/named regions, additive glow and an original-PMA twin. Named UV and
+rotation coverage uses native scale: measured half-scale checker sampling
+has additional residue, so arbitrary-scale pixel identity is not claimed.
+The shared #37 negative control serves false PMA flags only in the player's
+model response, leaving original files and the official reader unchanged.
+Each renderer must first pass its healthy capture, then exceed the same
+healthy black-composite budget with the altered response. This runs on both
+CI browser projects. Original PMA PNG bytes are encoded before either reader
+sees them.
+
+The reference uses `antialias:false`, `preserveDrawingBuffer:true` and the
+official `pmaAdditiveBatching:false` option to retain additive coverage in
+transparent captures. Initialization finishes model/region extraction before
+official page uploads, avoiding a measured concurrent WebKit initialization
+artifact. Use the required nova-run guard and a unique `TEST_PORT` for a
+focused `bun run test tests/oracle.spec.ts --workers=1`; full-suite acceptance
+remains CI. Headless results are raster evidence, never device performance.
+
+## Benchmark: DOM, canvas and official WebGL
 
 ```bash
 bun run bench:dev     # the page, for a person to watch (and for Safari)
 bun run bench         # drives it in a headed Chromium and writes a report
+bun run bench --headless # counters only; all timing fields are null
 ```
 
 `bench/` is a separate vite project — not part of the library, and not part of
-what `bun run build` emits — that plays the same rigc gallery build in both
-render modes side by side, each with its own stats line in the demo's style.
+what `bun run build` emits — that compares DOM, whole-canvas and the independent
+official WebGL reader, each with its own stats line. The paired JSON hash must
+match the model before an official comparison can publish readings.
 Scenes by query string: `?scene=mesh` (`portrait-packed` turning its head, the
 deform tier working every frame), `?scene=held` (the same pose frozen, where
 unchanged meshes reuse their raster and an unchanged frame is reused),
@@ -1009,7 +1173,7 @@ something you can see), laid out on one grid whose per-rig scale shrinks with
 the column count, so a step up in count adds rigs rather than cropping the ones
 already there.
 
-**The two sides draw the same picture.** Both place rigs with one derivation and
+**The comparison uses the same framing.** All paths place rigs with one derivation and
 clip each to the same rect — the pane for a grid, the rig's own cell for `many`
 — with `overflow: hidden` on a box, the way a page embeds a player, and then
 *check* it: each side reports `origin Δpx`, the largest gap between where the
@@ -1017,9 +1181,12 @@ grid puts a rig and where that side drew it, and the report table carries it per
 row. (`contain: layout paint` is deliberately not used: paint containment clips
 to the same edge `overflow: hidden` does, and what it adds past the clip — a
 stacking context, a containing block, an independent formatting context —
-changes how one side is composited and buys the comparison nothing.) Both modes
-share the package's single WebGL context however many players there are; the
-canvas side's stats line says how many contexts the page holds.
+changes how one side is composited and buys the comparison nothing.) Production
+modes retain the package's shared WebGL context. Official grid scenes batch
+all skeletons through one context; only `many` uses independent contexts.
+Official surviving contexts and drawn players are counted separately from
+requested players. Production survival counters are null where its public
+API cannot measure them, rather than treating requested counts as survivors.
 
 `scripts/bench.mjs` walks `bench/scenes.json`, opens each scene in a **headed**
 Chromium (a hidden page throttles `requestAnimationFrame`, so a headless
@@ -1027,15 +1194,20 @@ reading would be the browser's power policy rather than either mode's cost),
 runs a fixed number of frames per mode — one at a time, because rAF has a single
 cadence per document — and writes JSON plus a markdown table with the
 conditions attached: browser version, device pixel ratio, window size, GPU
-string, and the load average before and after. Over a threshold it stamps the
+string, and the load average before and after. A software or unidentified GPU
+invalidates a headed timing report. Over a load threshold it stamps the
 whole report `INVALID: load average too high` and exits non-zero, because a
 benchmark on a busy machine measures the machine. `--corpus <dir>` points it at
-local rigc builds that never enter this repository.
+local rigc builds that never enter this repository. `--headless` instead steps
+fixed frames and records counters only: FPS, pose/render timing and GPU fields
+are null, with “측정 불가: 헤드리스” in JSON and the table. The official
+additive-batching and drawing-buffer settings are recorded as conditions.
 
-> **Numbers pending.** No comparison table is published yet. A reading taken on
+> **Performance numbers pending.** Counter reports establish the instrument,
+> not a performance comparison. A timing reading taken on
 > a loaded machine, a CI runner or a headless browser would not be worth
 > printing. The table will be taken the way every other number in this README
-> was: the two stats lines read on a real device, on a quiet machine, per scene
+> was: the stats lines read on a real device, on a quiet machine, per scene
 > and per engine — including Safari, which stays manual because no automation
 > preserves what is being measured there. Until then the instrument exists and
 > the measurement does not.
@@ -1079,12 +1251,16 @@ so here is what is true of this package and this repository, stated plainly:
    `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. This repository links no Spine runtime either, since #63: no package of Esoteric
-   Software's npm scope is a dependency of any kind, and the lockfile names none.
-   `tests/package.spec.ts` asserts both.
+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.
 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.
-   Nothing here reads it, and it is neither committed nor published.
+   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)**,

package/dist/DomRenderer.d.ts.map

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

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { type CanvasBackend, CanvasRenderer, type CanvasViewport } from './CanvasRenderer.js';
 export { DomRenderer, type MeshBackend, type MeshSourceRect } from './DomRenderer.js';
 export { type PageLayout, type PageRegion, type RegionEncoding, type RegionImage, revokeRegions, type UnpackRegionsOptions, unpackRegions } from './DomTexture.js';
-export { type LoadModelOptions, loadModel, type ModelAssets, type ModelDocument, type RegionLoading } from './loadModel.js';
+export { type LoadModelOptions, loadModel, type ModelAssets, type ModelDocument, type RegionLoading, type RigSet } from './loadModel.js';
 export { type AdjustableBones, type BoneAdjust, type BoneLocals, type BoneWorld, type PlayOptions, type PoseBounds, type QueueOptions, type RenderMode, type RigComplete, type RigEnvironment, type RigEvent, RigPlayer, type RigPlayerOptions, type SlotFilter, type TrackEntry } from './player.js';
 export type { BlendMode, PosedClip, PosedFrame, PosedMesh, PosedRegion, PosedSlot, } from './posedFrame.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC9F,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACtF,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,KAAK,WAAW,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACnK,OAAO,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC5H,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,QAAQ,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AACtS,YAAY,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,SAAS,EACT,WAAW,EACX,SAAS,GACV,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC9F,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACtF,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,KAAK,WAAW,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACnK,OAAO,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACzI,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,QAAQ,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AACtS,YAAY,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,SAAS,EACT,WAAW,EACX,SAAS,GACV,MAAM,iBAAiB,CAAC"}