rig-play 0.8.0 → 1.1.0

package/README.md

@@ -1,32 +1,43 @@
 <p align="center">
-  <img src="assets/banner.svg" alt="spine-html - DOM-first Spine 2D runtime" width="100%" />
+  <img src="assets/banner.svg" alt="rig-play - plays rigc's compiled model as DOM elements or one canvas" width="100%" />
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/spine-html"><img src="https://img.shields.io/npm/v/spine-html.svg?style=flat-square&color=FF6B4A" alt="npm version" /></a>
-  <a href="https://www.npmjs.com/package/spine-html"><img src="https://img.shields.io/npm/dm/spine-html.svg?style=flat-square&color=EC4899" alt="npm downloads" /></a>
+  <a href="https://www.npmjs.com/package/rig-play"><img src="https://img.shields.io/npm/v/rig-play.svg?style=flat-square&color=FF6B4A" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/rig-play"><img src="https://img.shields.io/npm/dm/rig-play.svg?style=flat-square&color=EC4899" alt="npm downloads" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-38BDF8.svg?style=flat-square" alt="license" /></a>
 </p>
 
-Render [Spine](https://esotericsoftware.com/) skeletal animations as **plain DOM** — one
-absolutely-positioned `<img>` per slot, posed with a single CSS `matrix()` write per frame.
-No canvas, no WebGL for the rigid tier.
+Plays the rigs [rigc](https://github.com/firejune/rigc) builds — the 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, deforming meshes on small per-part canvases; or as **one canvas** per player.
+`spine-html` is the same package under the name it first shipped as.
 
 ## Why
 
-Every Spine web runtime rasterizes into a canvas. But `spine-core` is fully
-renderer-independent: it computes bone world transforms — and even deformed mesh
-vertices — on the CPU. For **region attachments** (the rigid parts of a skeleton), a bone
-transform is a plain affine map, and CSS `transform: matrix()` expresses that *exactly*.
-So the rigid tier of a Spine skeleton can live in the DOM, composited by the browser,
-inspectable in devtools, styled with CSS.
-
-The idea has been floated on the official forum three times since 2014 and was never
-built — the blockers named were meshes, clipping, and DOM update overhead. This project
-is the experiment: how far does the DOM actually go, and how cheap is it?
-
-Measured so far (PoC, Apple silicon — headless and on-device numbers are labeled,
-they do **not** substitute for each other):
+The package began in 0.x as `spine-html`, an experiment in drawing Spine skeletons
+without a canvas. Every Spine web runtime rasterizes into one, yet the pose itself is
+computed on the CPU, and for a **region attachment** (a rigid part) the bone transform is
+a plain affine map that CSS `transform: matrix()` expresses *exactly* — so the rigid tier
+could live in the DOM, composited by the browser, inspectable in devtools, styled with
+CSS. The idea had been floated on the Spine forum three times since 2014 and never built;
+the blockers named were meshes, clipping and DOM update overhead, and the 0.x line
+answered each of them (per-part mesh canvases, element-level `clip-path`, dirty-skip).
+
+At 1.0 it stopped being a Spine runtime. It plays the model document `rigc build` writes,
+poses it through `rig-c/core` — rigc's own posing core, bundled into the package — and
+links nothing from Esoteric Software; a Spine export is refused by name. It gained a
+second render mode that draws the whole frame into one canvas. And it took the name
+`rig-play`, which says what it is; `spine-html` keeps being published with the same
+files, so links to the old name keep working.
+
+### Measured
+
+Measured on the 0.x line, on the spineboy exports it then played (PoC, Apple silicon —
+headless and on-device numbers are labeled, they do **not** substitute for each other).
+The renderer tiers they describe carried over; they have not been re-measured since the
+player moved to rigc's model (#60):
 
 - Rigid only (spineboy-ess), headless Chromium: 10 skeletons / 180 slot images at
   **~0.03 ms skeleton math + ~0.22 ms DOM writes per frame** — about 1.5% of a
@@ -63,10 +74,24 @@ deforming) holds **60 fps on every engine measured**, and the 10-skeleton
 stress scene holds 45 fps on the weakest one (Safari, webgl backend). Ships
 with a self-contained test suite (backend visual parity + invariants) and CI.
 
+**Two render modes.** `mode: 'dom'` (the default, everything below) draws a rig
+as elements. `mode: 'canvas'` draws the whole frame into **one `<canvas>`** per
+player: every slot as textured triangles from its atlas page through the same
+shared WebGL context the mesh tier's `webgl` backend uses, into one rect, then
+one `drawImage` onto the player's canvas. Tint and dark (two-colour) tint are
+vertex colours, blend modes are batch state, clips are cut on the CPU by
+`rig-c/core`'s clipper — no `clip-path`, no SVG filter, no per-slot element.
+`RigPlayer` swaps between the two in place (`player.mode = 'canvas'`). The
+canvas mode is held against the DOM tier pixel for pixel on the parity suite's
+frozen poses (bad pixels ≤ 1.6% of drawn content, measured, macOS Chromium and
+WebKit); which mode is faster where is **not measured on a device yet**, so the
+default stays `dom`.
+
 - ✅ Region attachments (rigid parts): exact affine mapping, draw-order via `z-index`,
   attachment swaps, alpha
 - ✅ Atlas unpacking at load time (90°-packed regions restored to the orientation
-  spine-core's UVs name, held by the pixel oracle on exports whose packer rotated),
+  the region's UVs name, held against hand-written UVs on a rigc build whose region
+  is packed turned),
   so the rigid per-frame path never touches a canvas — a region that covers its whole
   page is passed through uncut, and `revokeRegions()` frees the rest when a skeleton
   is unloaded
@@ -92,8 +117,8 @@ with a self-contained test suite (backend visual parity + invariants) and CI.
   (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
   inverse of the `<img>` matrix for rigid slots, the canvas translate for mesh
-  slots. Covers **part masks** (a clip with a real end slot, like this repository's
-  own `portal` animation) and **whole-skeleton clips** (an end slot that never
+  slots. Covers **part masks** (a clip with a real end slot, like the figure test
+  rig's `mask` animation) and **whole-skeleton clips** (an end slot that never
   arrives, which takes a fast path: one `clip-path` on the root instead of one per
   element). **Inverse clips** are supported too: the region they keep has a hole
   in it, so it needs two rings, and `polygon()` carries only one — a box and a
@@ -134,284 +159,184 @@ with a self-contained test suite (backend visual parity + invariants) and CI.
 ## Install
 
 ```bash
-npm i spine-html @esotericsoftware/spine-core
+npm i rig-play
+npm i -D rig-c    # the build tool: `rigc build` writes the model rig-play loads
 ```
 
+The package plays rigs built by [rigc](https://github.com/firejune/rigc):
+`rigc build` writes a compiled model document, `skeleton.model.json` (spec
+`rigc-compiled/3`), next to the Spine pair and the atlas pages. That document
+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.
+
 ```ts
-import { Skeleton, AnimationState, AnimationStateData, Physics }
-  from '@esotericsoftware/spine-core';
-import { loadSkeletonAssets, SpineHtmlRenderer } from 'spine-html';
+import { loadModel, RigPlayer } from 'rig-play';
 
-const assets = await loadSkeletonAssets({
-  atlasUrl: '/spineboy/spineboy.atlas',
-  skeletonUrl: '/spineboy/spineboy-pro.json',
-});
+const assets = await loadModel({ modelUrl: '/rigs/walk/skeleton.model.json' });
 
-// A positioned element becomes the skeleton origin (Spine is Y-up: the
-// skeleton grows upward from it). Layout and scaling are the caller's.
-const skeleton = new Skeleton(assets.data);
-const state = new AnimationState(new AnimationStateData(assets.data));
-state.setAnimation(0, 'walk', true);
-const renderer = new SpineHtmlRenderer(rootElement, assets.regionImages);
+// A positioned element becomes the rig's world origin (Y-up: the rig grows
+// upward from it). Layout and scaling are the caller's.
+const player = new RigPlayer(rootElement, assets);
+player.play('walk');                        // looping; { loop: false } holds at the end
 
 function frame(delta: number) {
-  state.update(delta);
-  state.apply(skeleton);
-  skeleton.update(delta);
-  skeleton.updateWorldTransform(Physics.update);
-  renderer.render(skeleton);
+  player.frame(delta);                      // step the track by delta × timeScale, draw
 }
 
 // Unloading (a cutscene ends, a level swaps): elements first, bitmaps second.
 // The unpacked regions are blob URLs — nothing else frees them.
-renderer.dispose();
+player.dispose();
 assets.dispose();
 ```
 
-`spine-html` is a third-party renderer and is not affiliated with or endorsed by
+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
+step, and `seek(t)` moves it to a time. A seek is "reopen, then step to the
+time" in `seekStep` increments (1/60 s by default) — never a jump, because a
+physics rig has history and its pose at a time depends on the steps that
+reached it. `on('event', …)` receives the event keys each step crosses, in the
+runtime's order across a loop's wrap; `on('complete', …)` fires once a step
+completes a cycle. `skin` (a constructor option) poses under a named skin;
+without it the rig is posed the way a fresh Spine skeleton is, with no skin
+set. `player.color` multiplies a whole-rig colour into every slot's tint.
+`player.renderer` is the `DomRenderer` underneath, whose knobs and counters
+are below.
+
+**What it refuses, by name.** A Spine export (`.json`, `.skel`) is refused
+before anything is fetched: this package reads compiled models and nothing
+else. A document whose `spec` is not one `rig-c/core` reads is refused with the
+core's own sentence plus "build it with `rigc build`", and so is a
+`rigc-compiled/1` document, which predates the `pages` section.
+
+`rig-play` is a third-party renderer and is not affiliated with or endorsed by
 Esoteric Software.
 
-### Which spine-core to install
-
-> **Install the `@esotericsoftware/spine-core` that matches the Spine editor
-> version your data was exported from.**
-
-A Spine runtime reads only the data its own generation exported, so this is
-never a choice between "newest" and "oldest" — it is decided by your `.json` or
-`.skel` files. `spine-core` is a **peer** dependency here precisely so the
-decision stays yours, and `spine-html` draws from either generation:
-
-| `@esotericsoftware/spine-core` | `spine-html` |
-| --- | --- |
-| **4.3.x** | ✅ supported |
-| **4.2.x** | ✅ supported |
-| **4.1.x** | ✅ supported — browser/bundler only, see the Node note below |
-| **4.0.x** | ✅ supported — browser/bundler only, see the Node note below |
-| 3.8.x and older | ❌ not supported — no runtime is published under this package name |
-
-*Supported* means one specific thing: a column of this repository's CI runs the
-**whole** test suite on that minor, against **that version's own** example
-exports, with the pixel oracle drawing the same poses through
-`@esotericsoftware/spine-webgl` of the same generation. `peerDependencies` is
-that set and nothing wider. Nothing in the API above changes with the version —
-the difference is absorbed internally, in one file, chosen once per renderer by
-looking at the objects spine-core hands over.
-
-> **Node note, for 4.1 and 4.0 only.** Those two releases of `spine-core`
-> cannot be imported by plain Node: they ship extensionless relative specifiers
-> in their own `dist/`, and 4.0 also omits `"type": "module"`. Every bundler
-> resolves them (so do CDNs such as esm.sh), which is how a browser consumer
-> meets them, and `spine-html` itself is unaffected — but `import` of either
-> package from a Node process fails, so **SSR and Node-side tooling cannot load
-> them**. It is upstream's defect and not fixable from here. 4.1 has one more:
-> a single extensionless specifier inside its own `.d.ts` makes it fail a
-> `moduleResolution: "nodenext"` typecheck. 4.2 and 4.3 have neither problem.
-
-**Worth knowing, because it is silent.** If you point a 4.3 runtime at older
-data, the bad outcome is not the one that throws. 4.3 reads constraints from a
-single top-level `constraints` array, where 4.2 and older write separate
-`ik` / `transform` / `path` / `physics` ones — so an older export that still
-parses loads **none of its constraints at all**, and the skeleton animates on
-bones alone: no IK, no path, no physics, no error. Measured over a real-world
-corpus of 267 skeletons (88% of them 4.2 exports): 40% failed to parse under
-4.3.13 outright, and across those that did parse, **0 of 7,065** constraints and
-**0 of 5,704** physics constraints were loaded. If a skeleton renders but goes
-limp, this is why — and installing the matching `spine-core` is the whole fix.
-
-**If your data was exported by 4.1 or 4.0, install the matching runtime.**
-Since 0.8.0 both are supported columns, and installing spine-core 4.2 for such
-data is **not** a substitute — the failure is the quiet kind again. Read off
-`SkeletonJson` in each generation:
-
-- 4.0 and 4.1 write a bone's inheritance mode as `transform`
-  (`noRotationOrReflection`, `onlyTranslation`, …); 4.2 reads `inherit` and
-  nothing else, so every such bone falls back to `Normal`.
-- 4.0 writes mesh deform timelines under the animation's `deform`; 4.1 and 4.2
-  read `attachments` and never look at `deform`, so those timelines are dropped.
-
-Neither throws. Over a real-world corpus of shipped web skeletons, 96 of 418
-exports made by 4.0 and 20 of 101 made by 4.1 carry such bones (643 of them),
-and 91 of the 4.0 exports carry 1,031 deform timelines between them — all of it
-lost without a message under 4.2, while the file parses, every constraint
-loads, and the rig renders without an error.
-
-Spine's own spineboy export carries both, which is why every CI column checks
-this rather than trusting it: four bones at `noRotationOrReflection` and four
-mesh deform timelines, declared under the key that branch's exporter writes, and
-asserted to have arrived in the parsed `SkeletonData`.
-
-> **Correction.** The README shipped with 0.7.1, and the 0.7.0 release notes,
-> said "install spine-core 4.2" for 4.1 / 4.0 data — on the strength of exactly
-> the evidence that looks conclusive: every export parsed, all 14,022
-> constraints loaded, a 60-rig sample rendered cleanly. That evidence was real
-> and the conclusion was wrong, because **parsing without an error says nothing
-> about keys a newer reader no longer looks for.** The same corpus holds 19
-> Spine 3.8 exports that also parse cleanly under a 4.x runtime — and then pose
-> most of their bones at non-finite transforms (3.8 writes a rotate key as
-> `angle` and a curve as scalars; 4.0 reads `value` and an array). The test that
-> would have caught this is a diff of the keys each generation's reader
-> consumes, which is what the list above is. 0.7.1 corrected the advice to "4.2
-> is not a stand-in, and 4.1 / 4.0 are not supported"; 0.8.0 supports them, so
-> the advice is now simply the rule at the top of this section.
-
-Spine 3.8 and older are out of scope: they are not published under this package
-name.
-
-### One atlas, several skeletons
-
-Skeletons that share an atlas — a character's `-ess` and `-pro` exports, a whole
-cast packed onto one page — load in two steps instead. Calling
-`loadSkeletonAssets` once per skeleton would fetch and unpack the same pages
-again and mint a second set of region blob URLs:
+### Drawing your own frames
 
-```ts
-import { loadAtlasAssets, loadSkeletonJson, SpineHtmlRenderer } from 'spine-html';
+`RigPlayer` is the convenient path; the renderer underneath takes a plain
+record, so anything that can produce one can draw through it:
 
-const shared = await loadAtlasAssets({ atlasUrl: '/spineboy/spineboy.atlas' });
-const [essData, proData] = await Promise.all([
-  loadSkeletonJson(shared, '/spineboy/spineboy-ess.json'),
-  loadSkeletonJson(shared, '/spineboy/spineboy-pro.json'),
-]);
+```ts
+import { DomRenderer, type PosedFrame } from 'rig-play';
 
-const ess = new SpineHtmlRenderer(essRoot, shared.regionImages);
-const pro = new SpineHtmlRenderer(proRoot, shared.regionImages);
+const renderer = new DomRenderer(rootElement, assets.regionImages, assets.pageImages);
+renderer.render(frame); // frame: PosedFrame
+```
 
-// Unloading: every renderer first, then the one dispose() that owns the bitmaps.
-ess.dispose();
-pro.dispose();
-shared.dispose();
+```ts
+PosedFrame { order: PosedSlot[] }                     // the slots that draw, in draw order
+PosedSlot = { slot; z; blend: 'Normal'|'Additive'|'Multiply'|'Screen';
+              tint: [r, g, b, a]; dark?: [r, g, b];
+              clip?: { polygon: number[]; inverse: boolean; convex: boolean } }   // world space, Y up
+          & ( { kind: 'region'; region: string; corners: number[] /* BL, UL, UR, BR */;
+                page: string; pma: boolean; uvs: number[] /* page UVs at the corners */ }
+            | { kind: 'mesh'; page: string; pma: boolean; vertices: number[];
+                uvs: number[]; triangles: number[]; sequence: number } )
 ```
 
-`loadAtlasAssets` takes the atlas half of the options above (`resolvePage`,
-`crossOrigin`, `fetch`) and `loadSkeletonJson` the skeleton half (`scale`,
-`fetch`). Ownership is the thing to keep straight: the atlas assets belong to
-the caller, reading a skeleton against them never frees them, and one
-`regionImages` map is meant to be handed to several renderers — so there is
-exactly one `dispose()` for however many skeletons were read. `loadSkeletonJson`
-asks only for `{ atlas }`, so a caller that built its atlas by hand (below) can
-still use it for the read. `loadSkeletonAssets` is these two calls with the
-atlas half kept private: use it for one atlas and one skeleton, this for the
-rest.
+`player.posedFrame()` returns the record the player would draw. Two things the
+renderer reads off it by identity rather than by value: every slot a clip
+covers carries the **same** `clip` object (one that covers every slot of the
+frame takes the one-`clip-path`-on-the-root path), and a mesh's `uvs` and
+`triangles` are the same arrays from frame to frame for the same texture
+mapping (a new array re-rasters the mesh).
 
-### Binary exports (`.skel`)
+### Reading the pose
 
-Binary exports are read by a second parser, `SkeletonBinary`, which is as big as
-the JSON one. It lives behind its own entry point so that consumers who only
-ever read `.json` never carry it:
+Two reads off the pose the player holds — the last `frame`/`advance`/`seek`,
+or the setup pose before `play` — for framing a stage around a rig:
 
 ```ts
-import { loadAtlasAssets, SpineHtmlRenderer } from 'spine-html';
-import { loadSkeletonBinary } from 'spine-html/binary';
-
-const shared = await loadAtlasAssets({ atlasUrl: '/spineboy/spineboy.atlas' });
-const data = await loadSkeletonBinary(shared, '/spineboy/spineboy-pro.skel');
-
-const renderer = new SpineHtmlRenderer(rootElement, shared.regionImages);
-// Unloading, as above: renderer.dispose(); shared.dispose();
+const head = player.bone('head');   // { x, y, a, b, c, d, rotationX, rotationY, scaleX, scaleY, active }
+const box = player.bounds();        // { x, y, width, height } | null — world units, Y up
 ```
 
-`loadSkeletonBinary` is `loadSkeletonJson` with the parser swapped: same
-arguments, the same `{ scale, fetch }` options, the same ownership rule — it
-never frees `assets`, whichever way it ends. Those two calls are the binary path
-in full. There is no one-call `loadSkeletonAssetsBinary`, because the atlas half
-is precisely what a caller reading binary usually wants kept in hand, and hiding
-it again would only earn back a line.
+`bone` is the core's world transform for that bone (`rig-c/core`'s `RawBone`,
+unchanged), and an unknown name is refused by name. `bounds` is the box of
+every region's four corners and every mesh's vertices in the frame record the
+renderer takes; a slot under a clip counts only inside the clip polygon's own
+box, an inverse clip removes nothing, and bounding boxes, paths and points do
+not draw and do not count. Both cost nothing until called and read the same
+numbers in `dom` and `canvas` mode.
 
-The subpath is the whole mechanism, so import it as written: pulling
-`loadSkeletonBinary` out of `'spine-html'` is not possible, by design. Worth
-knowing about the format itself: binary exports are version-locked to the
-runtime that reads them, so a `.skel` written by an editor newer than your
-installed `@esotericsoftware/spine-core` fails in the read, not in the fetch.
-
-### Loading it yourself
+### One load, several players
 
-`loadSkeletonAssets` is optional sugar over five `spine-core` calls, and the
-package works without it. Drop to the low-level path whenever you need
-something no loader does — images that are already in memory, an atlas that is
-not fetched from a URL at all:
+One `loadModel` backs any number of players: the regions are cut once, and
+every player draws from the one `regionImages` map. A player owns none of it —
+disposing a player leaves the bitmaps alive for the others — so there is exactly
+one `assets.dispose()`, after the last player is gone:
 
 ```ts
-import { TextureAtlas, AtlasAttachmentLoader, SkeletonJson }
-  from '@esotericsoftware/spine-core';
-import { DomTexture, unpackRegions, revokeRegions } from 'spine-html';
-
-const atlas = new TextureAtlas(atlasText);
-const pageImages = new Map<string, HTMLImageElement>();
-for (const page of atlas.pages) {
-  const image = await loadImage(page.name); // your loader
-  page.setTexture(new DomTexture(image));
-  pageImages.set(page.name, image);
-}
-const regionImages = await unpackRegions(atlas, pageImages);
-const data = new SkeletonJson(new AtlasAttachmentLoader(atlas)).readSkeletonData(jsonText);
+const assets = await loadModel({ modelUrl: '/rigs/walk/skeleton.model.json' });
+const a = new RigPlayer(rootA, assets);
+const b = new RigPlayer(rootB, assets, { skin: 'winter' });
 
-// …and on unload, after every renderer using them is disposed:
-revokeRegions(regionImages);
+a.dispose();
+b.dispose();
+assets.dispose();
 ```
 
-A region the packer stored turned (`rotate: 90`) is cut upright again, and which
-way round that is comes from spine-core's own UVs rather than from the cut: such
-a region's corners carry `(u2, v2), (u, v2), (u, v), (u2, v)` in the order
-BL, UL, UR, BR, so the artwork's top-left corner sits at the packed rect's
+A document is one rig. Two rigs whose builds share page images load as two
+documents; the images are fetched by URL, so a page both name at the same URL
+is loaded once by the browser — but each load cuts its own regions and owns its
+own blob URLs.
+
+### Loading it yourself
+
+`loadModel` is a convenience over two calls the package exports: read the
+document, load its pages, and cut the regions with `unpackRegions`, which takes
+the document's `pages` section — `{ name, width, height, pma, regions: [{ name,
+x, y, width, height, degrees }] }` per page — and a map of page images keyed by
+those names. Use it when the page images do not come from a URL (`resolvePage`
+on `loadModel` covers the ones that come from another URL), and pair it with
+`revokeRegions` on unload.
+
+A region the packer stored turned (`degrees: 90`) is cut upright again, and
+which way round that is comes from the UVs a runtime assigns such a region,
+not from the cut: its corners carry `(u2, v2), (u, v2), (u, v), (u2, v)` in the
+order BL, UL, UR, BR, so the artwork's top-left corner sits at the packed rect's
 bottom-left and unpacking it is a clockwise turn. Every release up to 0.7.0
-turned it the other way and drew rotated rigid parts 180° round (#49); if you
-worked around that by re-packing an atlas without rotation, you can stop.
+turned it the other way and drew rotated rigid parts 180° round (#49).
 
 `unpackRegions` mints one blob URL per region; `revokeRegions` is its
 counterpart. It only frees URLs `unpackRegions` created, so a map you built
-yourself (below) and page images reused by the whole-page pass-through survive
-it — and calling it twice is a no-op. Load once for the page's lifetime and you
-can ignore it; load and unload repeatedly without it and you leak an atlas per
+yourself and page images reused by the whole-page pass-through survive it — and
+calling it twice is a no-op. Load once for the page's lifetime and you can
+ignore it; load and unload repeatedly without it and you leak an atlas per
 cycle.
 
 ### Pages that ship at another resolution
 
-A page image may ship at a resolution its atlas does not declare — a
-half-resolution texture build, or an @2x variant, with the `size:` line left as
-the packer wrote it. Nothing here needs a flag for that. A region's bounds are
-read **relative to the declared page size** and scaled onto the image's natural
-size, which is exactly how `spine-core` derives the UVs the mesh tier samples
-with (`region.u = region.x / page.width`), so both tiers land on the same
-pixels at any resolution:
-
-```
-hero.png
-size: 4096, 4096     # what the packer wrote
-                     # hero.png itself ships 2048×2048
-```
+A page image may ship at a resolution its document does not declare — a
+half-resolution texture build, or an @2x variant, with the page's `width` and
+`height` left as the build wrote them. Nothing here needs a flag for that. A
+region's bounds are read **relative to the declared page size** and scaled onto
+the image's natural size, which is how the page UVs the mesh tier samples with
+are derived too (`u = x / page.width`), so both tiers land on the same pixels at
+any resolution.
 
 Each unpacked bitmap comes out at the **native resolution of the pixels it was
 cut from** — half-resolution pages cost a quarter of the cut pixels, and
 nothing is upscaled back — while `RegionImage.width`/`height` stay in **atlas
 units**. Those two numbers are the `<img>` layout box and the denominator of
-its CSS matrix, so the skeleton poses identically and the browser scales the
+its CSS matrix, so the rig poses identically and the browser scales the
 smaller bitmap into the same box, the way a GPU samples a smaller texture
-through the same UVs. Ship one atlas and swap the images per device if you
-like.
-
-The corollary: a `size:` line that is simply **wrong** is now wrong for the
-whole renderer rather than for the mesh tier alone. Bounds are read against
-what the atlas declares, so a page declared at a size its artwork was not
-packed at reads every region from the wrong place in both tiers — correct the
-`size:` line, which is what every other Spine runtime needs too.
-
-### Premultiplied pages (`pma: true`)
-
-The Spine texture packer premultiplies alpha by default, and says so with a page
-line:
-
-```
-hero.png
-size: 2048, 2048
-pma: true
-```
-
-Such a page's RGB is already multiplied by its alpha, and nothing is asked of
-you: the flag is read off the atlas and each tier is handed the page in the
-convention it actually consumes. The `webgl` mesh backend uploads the texels
-unconverted (its blend already expects premultiplied source — lossless). The DOM
-and canvas2d tiers cannot: an `<img>` and `drawImage` composite straight alpha by
-definition, so they read a straight-alpha derivation of the page —
+through the same UVs. Ship one build and swap the images per device if you
+like (`resolvePage`).
+
+### Premultiplied pages (`pma`)
+
+A page's `pma` flag in the document's `pages` section — the build copies it from
+the atlas's `pma: true` line — says its RGB is already multiplied by its alpha,
+and nothing is asked of you: each tier is handed the page in the convention it
+actually consumes. The `webgl` mesh backend uploads the texels unconverted (its
+blend already expects premultiplied source — lossless). The DOM and canvas2d
+tiers cannot: an `<img>` and `drawImage` composite straight alpha by definition,
+so they read a straight-alpha derivation of the page —
 `rgb = round(rgb * 255 / a)`, computed once and shared by the region cuts and
 the mesh raster. Without it every semi-transparent texel is multiplied by its
 alpha a second time and draws darker than it was authored: soft edges, soft
@@ -419,100 +344,89 @@ shadows, glows.
 
 What it costs: **one page-sized canvas per premultiplied page image**
 (width × height × 4 bytes — 1 MiB for a 1024×256 page, 16 MiB for a 2048×2048
-one), alive as long as you hold the page image and released with it; the cache
-is weak, so there is nothing to free by hand. A page with no `pma:` line derives
-nothing and takes exactly the path it always did. The division is 8-bit and
-starts from a canvas read, which has itself quantized a premultiplied texel, so
-a very transparent texel can land a few levels off — exact at alpha 0 and 255,
-within one level of 255 above alpha 128, and a little more below that, by an
-amount that belongs to the browser's canvas rather than to this package (some
-rasterizers round premultiplied storage several times more coarsely than
-others). It is bounded by what that canvas already costs, and it is invisible
-wherever the texel is: a texel at alpha 11 is ~4% opaque. The `webgl` backend,
-having no such step, is exact.
-
-One consequence worth knowing if your atlas is one part per page: a whole-page
+one), alive as long as the page image is and released with it; the cache is
+weak, so there is nothing to free by hand. A page without the flag derives
+nothing. The division is 8-bit and starts from a canvas read, which has itself
+quantized a premultiplied texel, so a very transparent texel can land a few
+levels off — exact at alpha 0 and 255, within one level of 255 above alpha 128,
+and a little more below that, by an amount that belongs to the browser's canvas
+rather than to this package. It is invisible wherever the texel is: a texel at
+alpha 11 is ~4% opaque. The `webgl` backend, having no such step, is exact.
+
+One consequence worth knowing if your build is one part per page: a whole-page
 region on a premultiplied page is **cut** rather than handed through, because
 the page's own URL holds premultiplied pixels (see below).
 
 ### What unloading frees
 
-`revokeRegions()` — and `assets.dispose()`, which just calls it — frees the blob
-URLs `unpackRegions` minted, and nothing else. The rest is pinned by objects you
-own: an atlas **page image** is held by the `DomTexture` you attached to its
-page, and `SkeletonData` reaches that same image through every attachment
-(`region.texture.getImage()`), so a page is released only once the atlas, the
-skeleton data and every renderer drawing from them are gone. `atlas.dispose()`
-does not do it — `DomTexture.dispose()` is a no-op, because the image is yours.
-With the `webgl` mesh backend the shared blitter also uploads each page image on
-first use, but that GL texture is not the module's forever: every renderer
-drawing the page holds a reference to it, `renderer.dispose()` hands those back,
-and the texture is deleted once the last renderer using that page is disposed —
-a later frame that needs the page uploads it again. The cache is keyed weakly by
-the page image, so a renderer dropped without `dispose()` costs GPU memory until
+`revokeRegions()` — and `assets.dispose()`, which calls it — frees the blob URLs
+`unpackRegions` minted, and nothing else. The page images are held by
+`assets.pageImages` and by every player drawing from them, so a page is
+released once you drop the assets and every player is disposed. With the
+`webgl` mesh backend the shared blitter also uploads each page image on first
+use, but that GL texture is not the module's forever: every renderer drawing
+the page holds a reference to it, `player.dispose()` hands those back, and the
+texture is deleted once the last renderer using that page is disposed — a later
+frame that needs the page uploads it again. The cache is keyed weakly by the
+page image, so a renderer dropped without `dispose()` costs GPU memory until
 the context is lost, but never keeps the image itself alive.
 
-A meshed skeleton samples the page bitmap every frame, so its decoded form stays
-in use: a floor on the order of `page width × page height × 4` bytes per page —
-1 MiB for spineboy's single 1024×256 page. A rigid-only skeleton draws nothing
-from the page after `unpackRegions`, and what a merely reachable, undrawn image
-costs is up to the browser, not measurable from script.
+A rig with meshes samples its page bitmaps every frame, so their decoded form
+stays in use: a floor on the order of `page width × page height × 4` bytes per
+page. A rigid-only rig draws nothing from the pages after `unpackRegions`, and
+what a merely reachable, undrawn image costs is up to the browser, not
+measurable from script.
 
 Unload in this order:
 
-1. `renderer.dispose()`, for every renderer using the images.
-2. `revokeRegions(regionImages)` (or `assets.dispose()`).
-3. Drop your references to the atlas and the skeleton data.
+1. `player.dispose()`, for every player using the assets.
+2. `assets.dispose()` (or `revokeRegions(regionImages)`).
+3. Drop your references to the assets.
 
-### One part per page (loose part PNGs)
+### One part per page
 
-Not every pipeline runs the Spine editor's texture packer. If your parts are
-loose PNGs, declare each one as its own atlas page — a blank line closes a page
-block, the next line opens the next:
+`rigc build` writes one page per part by default — each part PNG is its own
+page, its one region covering it — and `rigc build --pack` arranges the parts
+onto shared pages instead. Both play here, unchanged:
 
-```
-head.png
-size: 512, 512
-head
-bounds: 0, 0, 512, 512
-
-torso.png
-size: 640, 480
-torso
-bounds: 0, 0, 640, 480
-```
-
-`spine-core` parses this as a normal multi-page atlas and nothing here needs a
-flag. Two things to know:
-
-- **`size:` is the frame every coordinate is read in**, so each page's
-  `bounds` must be written against the `size:` above them. The two need not be
-  the PNG's pixel size — that is the point of the section above, and a
-  half-resolution `head.png` under `size: 512, 512` works — but a `size:` that
-  matches neither the bounds nor the artwork reads every region from the wrong
-  place, in both tiers.
-- Regions like these cover their whole page, so `unpackRegions` hands the page
-  image straight through instead of cutting and re-encoding it — at any image
-  resolution, since covering the page is a statement about the declared size.
-  Load cost for this atlas shape is just the image loads. The exception is a
-  page marked `pma: true`: its URL holds premultiplied pixels, which an `<img>`
-  would composite as straight alpha, so those regions are cut from the
-  straight-alpha derivation like any other (and the blob is revoked by
-  `revokeRegions` like any other).
-
-For a **rigid-only** skeleton you can skip atlas unpacking altogether and hand
-the renderer a map you build yourself — meshes cannot, because the deform tier
-samples the page bitmap through the atlas region:
-
-```ts
-const regionImages = new Map([
-  ['head', { url: '/parts/head.png', width: 512, height: 512 }],
-]);
-const renderer = new SpineHtmlRenderer(rootElement, regionImages);
-```
+- Regions that cover their whole page are handed straight through by
+  `unpackRegions` instead of being cut and re-encoded — at any image resolution,
+  since covering the page is a statement about the declared size. Load cost for
+  this shape is just the image loads. The exception is a page marked `pma`: its
+  URL holds premultiplied pixels, which an `<img>` would composite as straight
+  alpha, so those regions are cut from the straight-alpha derivation like any
+  other (and the blob is revoked by `revokeRegions` like any other).
+- A packed build cuts every region from its page once, at load, and its meshes
+  sample the shared page through page UVs.
 
 ### Runtime knobs and what they cost
 
+- `player.mode` / `new RigPlayer(root, assets, { mode })` — `'dom'` (default)
+  or `'canvas'`. Changing it disposes the current renderer (elements removed,
+  GPU pages handed back) and creates the other over the same root and assets;
+  `pixelRatio` and `clipping` carry over and the held pose is redrawn at once.
+  `player.renderer` is then a `CanvasRenderer`, whose knobs are `pixelRatio`,
+  `clipping`, `viewport` and `backend`. What each mode costs, as counters:
+  - **dom** — one element per drawn slot, one style write per changed slot,
+    and the mesh tier's rasters (the knobs below).
+  - **canvas** — one canvas element per player and, per frame that changed,
+    one pass over every slot: `drawCalls` (one per run of one page under one
+    blend), `blendFlushes` (runs a blend change ended), `trianglesDrawn`,
+    `blits` (one), or `framesReused` (one) when the record did not change and
+    nothing is drawn. It never creates a WebGL context of its own, so any number
+    of players stays under the browser's ~16-context cap (20 players, one
+    context — `tests/canvas-mode.spec.ts`). The canvas covers a rect of the
+    root's coordinates that grows (never shrinks) to what the frames draw —
+    `canvasReallocCount` settles at zero — or a fixed `renderer.viewport` (world
+    units, Y up) when you set one. Blends are composed inside that canvas, which
+    starts transparent: an additive slot adds onto the slots under it and is
+    then composited onto the page normally, where the DOM tier's
+    `plus-lighter` adds onto the page itself. Where WebGL is unavailable or the
+    context is lost, the frame is drawn with canvas2d on the same canvas so it
+    never draws nothing — **alpha tint only, RGB and dark tint unsupported
+    there** — and that fallback is **not the measured path** (`backendActive`
+    says which ran).
+
 - `renderer.pixelRatio` — mesh-canvas backing pixels per CSS pixel (defaults to
   `devicePixelRatio`; if you scale the root element, fold that scale in so the
   raster matches the screen: `devicePixelRatio * rootScale`). **Writing it
@@ -546,8 +460,12 @@ const renderer = new SpineHtmlRenderer(rootElement, regionImages);
   mesh once (no reallocation), so it is fine to expose as a user setting.
 - `renderer.triangleExpand` — clip overdraw in px that closes antialiased mesh
   seams (default 0.5). Also re-rasters every mesh once when changed.
-- `renderer.clipping` — apply clipping attachments (default `true`). What it
-  writes is one CSS `clip-path` per element the active clip covers, in that
+- `renderer.clipping` — apply the clips the frame carries (default `true`).
+  Which slots a clip covers is decided where the frame is made — the player's
+  adapter walks the draw order the way the runtime's draw loop does (one clip in
+  force at a time, a second one met while one is in force ignored, the end slot
+  inside its own clip). What the renderer writes is one CSS `clip-path` per
+  element a clip covers, in that
   element's own local frame; nothing reaches the raster backends, and a clip is
   not part of the mesh dirty signature, so a mesh that held still keeps reusing
   its raster under a moving clip. **Writes happen on change only**: each
@@ -555,11 +473,11 @@ const renderer = new SpineHtmlRenderer(rootElement, regionImages);
   1/1000 of a local unit so float jitter cannot defeat that cache, and a static
   polygon over a static pose therefore costs **zero style writes per frame after
   the first** — `renderer.clipWriteCount` is the check, alongside
-  `clipCount` (applied) and `clipSkipCount` (not applied: switched off, a second
-  clip met while one was active, an inactive bone, a degenerate polygon).
-  **The whole-skeleton fast path**: when the clip starts before anything has been
-  drawn and never ends, one `clip-path` goes on the root instead of one per
-  element. The root is *your* element, so its inline `clip-path` is **borrowed,
+  `clipCount` (clips applied) and `clipSkipCount` (clips in the frame not
+  applied: switched off, or a degenerate polygon; a clip the runtime itself
+  ignores never reaches the frame). **The whole-skeleton fast path**: when one
+  clip covers every slot of the frame, one `clip-path` goes on the root instead
+  of one per element. The root is *your* element, so its inline `clip-path` is **borrowed,
   not taken** — saved on the first write and put back verbatim when the clip
   stops covering the frame, when `clipping` goes `false`, and by `dispose()`.
   Per-element clip-paths and the root clip-path are never both in force for the
@@ -593,6 +511,150 @@ on-device (Chromium, dpr 2, stage under `scale(0.25)`, ~2.2 M CSS px on screen):
 | 92 meshes | `devicePixelRatio` (2) | 141.1 Mpx | 36–39 |
 | 92 meshes | `dpr × zoom` (0.5) | 9.1 Mpx | 60–61 |
 
+## Coming from spine-html 0.8
+
+This is not a drop-in upgrade. 0.8 drew a Spine export (`.json` or `.skel`, plus its
+`.atlas`) that `@esotericsoftware/spine-core` parsed and posed: the caller built the
+`Skeleton` and the `AnimationState`, advanced them each frame, and handed the skeleton to
+`renderer.render(skeleton)`. 1.0 loads one file, the `skeleton.model.json` that
+`rigc build` writes, poses it through `rig-c/core` (bundled into the package, with no peer
+dependency), and `RigPlayer` owns the track, so the caller's frame is `player.frame(dt)`.
+A Spine export is refused by name before anything is fetched: the data has to be a rigc
+build, and this package declares no loader for anything else.
+
+What did not move: a positioned root element is still the rig's origin (Y up) with its
+layout and scaling left to the caller, the DOM tier keeps its knobs under a new class
+name, and unloading is still elements first, bitmaps second.
+
+### 0.8 → 1.0
+
+| 0.8.0 (`spine-html`) | 1.0.0 (`rig-play`) | Note |
+| --- | --- | --- |
+| `npm i spine-html @esotericsoftware/spine-core` | `npm i rig-play`, and `npm i -D rig-c` for the build tool | 0.8 declared spine-core as a peer dependency (`>=4.0.0 <4.4.0`). 1.0.0 declares no dependencies and no peer dependencies. |
+| `loadSkeletonAssets(options)` | `loadModel(options)` | One URL instead of two. The `.atlas` and `skeleton.json` a build writes beside the document are not fetched. |
+| `LoadSkeletonAssetsOptions.atlasUrl`, `skeletonUrl` | `LoadModelOptions.modelUrl` | |
+| `resolvePage(pageName, atlasUrl)` | `resolvePage(pageName, modelUrl)` | The default now resolves a page name against the model URL's directory. |
+| `crossOrigin`, `fetch` | `crossOrigin`, `fetch` | Unchanged. |
+| `scale` (`LoadSkeletonAssetsOptions`, `LoadSkeletonJsonOptions`) | none | See below. |
+| `SkeletonAssets` | `ModelAssets` | |
+| `SkeletonAssets.data` | `ModelAssets.document`, `animations`, `skins`, `stage`, `spec` | `document` is opaque (`ModelDocument`); the player poses it. What a caller used to read off the skeleton data is stated as `animations` (name and duration), `skins` (names) and `stage` (the stage the build declared, or null). |
+| `SkeletonAssets.atlas` | `ModelAssets.pageImages` | The page images, keyed by page name. There is no atlas object; where each region sits is in the document's `pages` section. |
+| `SkeletonAssets.regionImages` | `ModelAssets.regionImages` | Same `Map<string, RegionImage>`. |
+| `SkeletonAssets.dispose()`, `AtlasAssets.dispose()` | `ModelAssets.dispose()` | Same contract: frees the blob URLs the load minted, idempotent, called after the players are disposed. |
+| `loadAtlasAssets` + `loadSkeletonJson` (one atlas, several skeletons) | none | One `loadModel` backs any number of `RigPlayer`s of the same rig. Two rigs are two loads, and each cuts its own regions. See below. |
+| `loadSkeletonBinary` from `spine-html/binary` | none | 1.0.0 has one entry point. A `.skel` URL is refused by name. |
+| `unpackRegions(atlas, pageImages)` | `unpackRegions(pages, pageImages)` | The first argument is the document's `pages` section (`readonly PageLayout[]`) instead of a `TextureAtlas`. |
+| `revokeRegions(images)` | `revokeRegions(images)` | Unchanged. |
+| `RegionImage` | `RegionImage` | Unchanged (`url`, `width`, `height`, in atlas units). |
+| `DomTexture` | none | Not exported; there is no atlas page to attach a texture to. |
+| `new Skeleton(assets.data)` and `new AnimationState(new AnimationStateData(assets.data))` | `new RigPlayer(root, assets, options?)` | The player holds the pose and the track. |
+| `state.setAnimation(0, 'walk', true)` | `player.play('walk', { loop: true })` | `loop` defaults to true. `play` opens the animation at its first pose with the physics reset there. `player.current` names what is playing. |
+| `state.update(delta)`, `state.apply(skeleton)`, `skeleton.update(delta)`, `skeleton.updateWorldTransform(Physics.update)`, `renderer.render(skeleton)` | `player.frame(dt)` | Or `player.advance(dt)` then `player.draw()`, to time the two apart. |
+| time scale (the caller's own, on the spine-core side) | `player.timeScale` | Multiplies every step. 0 holds the pose without re-posing it; a negative value is not stepped. |
+| holding a pose (the caller stopped advancing) | `player.pause()`, `player.resume()` | `frame` keeps drawing the held pose. |
+| moving to a time (the caller's own, on the spine-core side) | `player.seek(time)`, `RigPlayerOptions.seekStep`, `player.time` | A seek reopens the animation and steps forward in `seekStep` increments (1/60 s by default). Events and completes crossed on the way are not fired. |
+| events (the caller's own listener on the spine-core side) | `player.on('event', listener)`, `player.on('complete', listener)` | `'event'` hands a `RigEvent` (`name`, `time`, `int`, `float`, `string`); `'complete'` hands `{ animation }`. `on` returns a function that removes the listener. |
+| skin (set by the caller on its `Skeleton`) | `RigPlayerOptions.skin` | A constructor option. The names are in `ModelAssets.skins`. Without it the rig is posed with no skin set. |
+| `SpineHtmlRenderer` | `DomRenderer`, reached as `player.renderer` | In `mode: 'dom'`, the default. `mode: 'canvas'` is new and makes `player.renderer` a `CanvasRenderer`. |
+| `new SpineHtmlRenderer(root, regionImages)` | `new DomRenderer(root, regionImages, pages?)` | Only for drawing your own frames; `RigPlayer` constructs its renderer. `pages` is the page-image map the mesh tier samples (`ModelAssets.pageImages`). A hand-built `regionImages` map is still accepted. |
+| `renderer.render(skeleton)` | `renderer.render(frame)` | Takes a `PosedFrame`, not a skeleton. `player.posedFrame()` returns the one the player would draw. |
+| `renderer.pixelRatio` | `player.renderer.pixelRatio` | On both renderers. Carried over when `player.mode` changes. |
+| `renderer.syncPixelRatio()` | `DomRenderer.syncPixelRatio()` | DOM mode only. `player.renderer` is typed as either renderer, so narrow it (`instanceof DomRenderer`) before calling. |
+| `renderer.meshBackingPixels` | `DomRenderer.meshBackingPixels` | DOM mode only. |
+| `renderer.meshBackend`, `meshBackendActive`, type `MeshBackend` | `DomRenderer.meshBackend`, `meshBackendActive`, type `MeshBackend` | Same values (`'canvas2d'` default, `'webgl'`). Also settable up front as `RigPlayerOptions.meshBackend`. |
+| `renderer.triangleExpand` | `DomRenderer.triangleExpand` | Same default (0.5). |
+| `renderer.clipping` | `player.renderer.clipping` | On both renderers. Carried over when `player.mode` changes. |
+| `clipCount`, `clipSkipCount`, `clipWriteCount` | same names on `DomRenderer` | `clipSkipCount` counts less than it did: a second clip met while one is in force, and a clip on an inactive bone, no longer reach the frame, so they are not counted. |
+| `meshCount`, `meshReuseCount`, `canvasReallocCount`, `triangleCount` | same names on `DomRenderer` | |
+| tint: skeleton × slot × attachment colour | `player.color` × slot × attachment | `player.color` is `[r, g, b, a]` and takes the place of the skeleton's colour. The product arrives as `tint` on each `PosedSlot`. |
+| dark (two-colour) tint: unsupported | `DomRenderer`: unsupported. `CanvasRenderer`: drawn | Carried as `dark` on a `PosedSlot`. The canvas mode's canvas2d fallback draws alpha only. |
+| `renderer.dispose()` | `player.dispose()` | Then `assets.dispose()`, as before. `DomRenderer.dispose()` and `CanvasRenderer.dispose()` exist for a renderer you constructed yourself. |
+
+### No counterpart in 1.0.0
+
+Things a 0.8 caller could do because it held the spine-core objects, or through a 0.8
+export, for which 1.0.0 declares nothing:
+
+- **A Spine export as input.** `loadSkeletonJson`, `loadSkeletonBinary`, `loadAtlasAssets`,
+  the `spine-html/binary` entry and `DomTexture` have no counterpart, and neither does
+  choosing which spine-core generation reads the data. `loadModel` reads a compiled model
+  document and nothing else.
+- **Scaling the skeleton as it is read.** `LoadModelOptions` declares no `scale`. Scaling
+  the root element is still the caller's.
+- **One unpacked atlas shared by different skeletons.** A document is one rig, and each
+  `loadModel` cuts its own regions and owns its own blob URLs. Sharing is per rig: one
+  load, several players.
+- **More than one track, mixing between animations, or queueing one after another.**
+  `RigPlayer` declares one track; `play` reopens it at the animation's first pose.
+- **Reading or writing a bone.** No bone is exposed: nothing sets a bone's local values
+  between the step and the draw, and nothing returns a bone's world transform. What is
+  readable is the posed slots: `player.posedFrame()` carries each drawn slot's world
+  `corners` or `vertices`.
+- **A bounds query for the current pose.** None is declared. `ModelAssets.stage` is the
+  stage the document states (or null), which is the rig's declared framing and not the
+  box of the pose being drawn.
+- **Changing the skin after construction.** `skin` is a `RigPlayerOptions` field and
+  `RigPlayer` declares no way to change it later; a second player over the same assets
+  is the declared route.
+- **Changing one slot from code** (its attachment, its colour). `RigPlayer` declares only
+  the whole-rig `color`. The frame record is a plain object, so a caller that draws its
+  own frames through `DomRenderer.render` or `CanvasRenderer.render` decides what is in
+  it.
+- **Choosing how physics is stepped each frame.** 0.8's loop passed `Physics.update`
+  itself; 1.0.0 declares no physics option. `play` and `seek` reset physics at the
+  animation's first pose and every step advances it.
+- **Track callbacks other than the two declared.** `on` accepts `'event'` and
+  `'complete'`.
+
+Knobs on `DomRenderer` that `CanvasRenderer` does not declare:
+
+- `syncPixelRatio()`. `CanvasRenderer.pixelRatio` exists and is set by hand
+  (`devicePixelRatio * rootScale`).
+- `meshBackend` and `meshBackendActive`. The canvas mode has its own pair, `backend` and
+  `backendActive` (type `CanvasBackend`, `'webgl'` by default).
+- `triangleExpand`, `meshBackingPixels`, `clipWriteCount`, `meshCount`, `meshReuseCount`,
+  `triangleCount`. The canvas mode's counters are `drawCalls`, `blendFlushes`,
+  `trianglesDrawn`, `framesReused` and `blits`.
+
+Both declare `pixelRatio`, `clipping`, `clipCount`, `clipSkipCount`, `canvasReallocCount`,
+`render` and `dispose`. Only `pixelRatio` and `clipping` carry over when `player.mode`
+changes.
+
+### Before and after
+
+0.8.0:
+
+```ts
+import { Skeleton, AnimationState, AnimationStateData, Physics } from '@esotericsoftware/spine-core';
+import { loadSkeletonAssets, SpineHtmlRenderer } from 'spine-html';
+const assets = await loadSkeletonAssets({ atlasUrl: '/hero/hero.atlas', skeletonUrl: '/hero/hero.json' });
+const skeleton = new Skeleton(assets.data);
+const state = new AnimationState(new AnimationStateData(assets.data));
+state.setAnimation(0, 'walk', true);
+const renderer = new SpineHtmlRenderer(rootElement, assets.regionImages);
+function frame(delta: number) {
+  state.update(delta);
+  state.apply(skeleton);
+  skeleton.update(delta);
+  skeleton.updateWorldTransform(Physics.update);
+  renderer.render(skeleton);
+}
+renderer.dispose(); assets.dispose(); // on unload
+```
+
+1.0.0:
+
+```ts
+import { loadModel, RigPlayer } from 'rig-play';
+const assets = await loadModel({ modelUrl: '/rigs/walk/skeleton.model.json' });
+const player = new RigPlayer(rootElement, assets);
+player.play('walk', { loop: true });
+function frame(delta: number) {
+  player.frame(delta);
+}
+player.dispose(); assets.dispose(); // on unload
+```
+
 ## Demo (this repository)
 
 ```bash
@@ -600,18 +662,22 @@ bun install
 bun run dev
 ```
 
-The official spineboy example assets are downloaded automatically on first `dev`/`build`
-(they are owned by Esoteric Software and not redistributed in this repository — see
-[NOTICE.md](NOTICE.md)); `bun run fetch-assets` runs the same idempotent step manually.
+The demo plays rigc's own gallery rigs (`walk`, `flex`, `squash`, `portrait`,
+`nod`, `look`, `ride`), each built by `rigc build` from a pinned rigc tag into
+`public/rigs/<name>/` on first `dev`/`build` — and each again with `--pack` into
+`public/rigs/<name>-packed/`. The same step builds this repository's test rigs
+(`tests/rigs/`: `figure`, `glow`, `turned`), which `?rig=` also reaches; nothing
+is downloaded but the rigc tag's gallery sources. `bun run fetch-assets` runs it
+manually, and it is idempotent.
 
-Debug knobs (query string): `?skel=pro|ess` `?anim=walk` `?count=10` pick the scene,
-`?tint=ff8080` tints the whole skeleton, `?dpr=2` overrides the mesh-canvas backing
+Debug knobs (query string): `?rig=flex` `?anim=wave` `?count=10` pick the scene,
+`?tint=ff8080` tints the whole rig, `?dpr=2` overrides the mesh-canvas backing
 ratio, `?timescale=0` freezes the pose (every mesh should report "reused"),
 `?expand=0` disables the crack-closing clip overdraw, `?backend=webgl` rasterizes
 meshes through the shared WebGL blitter (also a live header select; the stats line
-names the active backend), `?clipping=0` turns clipping attachments back off (they
-are then counted and skipped, as before v0.6 — try it on `?anim=portal`), and
-`?time=1.2` seeks every instance to the same pose for deterministic captures.
+names the active backend), `?clipping=0` turns clips back off (they are then
+counted and skipped), and `?time=1.2` seeks every instance to the same pose for
+deterministic captures.
 
 ## Tests
 
@@ -620,29 +686,33 @@ 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, **once per supported spine-core minor**). That
-matrix is what the compatibility table above is made of: each column installs
-that minor over the lockfile's, fetches the matching spine-runtimes branch's
-example exports, and runs everything. `SPINE_ASSETS_BRANCH=4.2 bun run
-fetch-assets` gets those exports locally, and `SPINE_CORE_MINOR` tells the run
-which minor it is against — anything but the typed one builds without
-`tsc --noEmit`, since the package is typed against one generation and runs on
-several. Two checks in `tests/package.spec.ts` are skipped, with the reason
-printed, where the **installed peer alone** already fails them: importing
-`spine-core` 4.0 in plain Node, and typechecking a consumer of `spine-core` 4.1
-under `nodenext`. Both are the upstream packaging defect described in the
-compatibility section, both are probed rather than keyed on a version, and
-nothing is relaxed in the columns that can run them. The visual check is
-**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 with
-`?backend=canvas2d` and `?backend=webgl` in the same engine and the buffers
-are diffed directly with a shift-tolerant comparison, so missing parts,
-wrong colors, and tint/blend divergence fail regardless of platform.
-Hairline seams are guarded by a deterministic canary (`?expand=0` must
-change the canvas2d raster), and counter tests pin the dirty-skip /
-grow-only-backing / clip-counter invariants plus spine-core's region corner
-order (BL, UL, UR, BR).
+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
+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,
+additive blend, clipping, a mesh — scores 4.2–77%) and 2.5% on the gallery
+scenes (floors 0.585–1.553%, Chromium and WebKit). The DOM tier's two mesh
+backends get the same A/B (`?backend=canvas2d` against `?backend=webgl`, at most
+0.5%). Hairline seams are guarded by a deterministic canary (`?expand=0` must
+change the canvas2d raster), the canvas2d source sub-rect by another (expand 32
+against 8), and counter tests pin the dirty-skip / grow-only-backing /
+clip-counter invariants plus the region corner order (BL, UL, UR, BR) and the
+turned-region UVs, read off rig-c's pose against hand-written numbers.
 
 Clipping gets its own oracle (`tests/clipping.spec.ts`), because a clip-path
 that went through the wrong transform still parses and still counts as applied.
@@ -666,56 +736,7 @@ resolving, so blob ownership — every unpacked URL freed, nothing the caller
 owns touched, nothing stranded by a failed load — is asserted rather than
 assumed.
 
-### The pixel oracle: a reference that is not us
-
-Everything above compares this package against itself. That catches one mesh
-backend drifting from the other and, by construction, cannot catch a defect
-they **share** — which is what happened with `pma: true` pages, drawn one
-multiply too dark in every tier while the suite stayed green for months.
-
-So `tests/oracle.spec.ts` compares against the official runtime. The same
-export, the same frozen pose, the same size, the same atlas page, drawn by
-`@esotericsoftware/spine-webgl` into a canvas whose orthographic camera is
-solved to land world space on exactly the pixels the DOM stage lands it on —
-then both are screenshotted and diffed. Thirteen cells: the rigid tier, the mesh
-tier on both backends, the exporter's own premultiplied page (`spineboy-pma`)
-on all three, a clipping pose, an additive-blend pose, a mesh-deform pose on
-both backends, a per-slot rgba/alpha pose, and a whole-skeleton tint.
-
-It earned its keep on the first run: the rigid tier was drawing every
-90°-packed atlas region 180° round (#49), in every release up to 0.7.0, and no
-comparison of this package against itself could have seen it. Rotated packing is
-held there now — the example exports rotate 17 regions on the 4.0 and 4.1
-branches and ten on the 4.2 branch where the 4.3 branch's rotate none, so the
-older columns are what keep the restore honest, and each cell logs how many
-regions its atlas rotated so a green run on an unrotated one cannot be mistaken
-for the proof.
-
-The deform cell is the one chosen for what the *data* carries rather than for a
-feature of the renderer: `hoverboard` is the only animation in spineboy-pro with
-mesh deform keys, it is the section whose JSON key moved between 4.0 and 4.1,
-and the pose drives two of the four bones whose inheritance mode moved between
-4.1 and 4.2. On the older columns it is therefore a deformed mesh posed through
-bones only the matching runtime reads, diffed against that runtime's own
-reference.
-
-Two things make it evidence rather than decoration. The camera match is
-**derived** — solved against the DOM mapping, not fitted to a picture — and
-then **proved by driving it**: a deliberate one-world-unit offset of one side
-must change the diff, which it does by 3.3× and 6.5×. And what is forgiven is
-antialiasing and texture filtering and nothing else, so the stage sits where
-one atlas texel is one CSS pixel and neither runtime resamples. Limits are
-ratios of drawn content, plus a darker-minus-lighter excess on the
-premultiplied cells, because that defect class can only go one way — never an
-absolute per-pixel precision number, which is a platform's number and not a
-package's.
-
-spine-webgl is a **development dependency**. It is named by one file under
-`tests/`, it is in neither `dependencies` nor `peerDependencies`, and
-`tests/package.spec.ts` asserts that nothing the published package contains so
-much as mentions it.
-
-## Benchmark: side by side with the official runtime
+## Benchmark: DOM mode vs canvas mode
 
 ```bash
 bun run bench:dev     # the page, for a person to watch (and for Safari)
@@ -723,34 +744,48 @@ bun run bench         # drives it in a headed Chromium and writes a report
 ```
 
 `bench/` is a separate vite project — not part of the library, and not part of
-what `bun run build` emits — that runs the same skeleton in both runtimes side
-by side, each with its own stats line in the demo's style. Scenes by query
-string: `?scene=mesh` (the deform tier working every frame), `?scene=held` (a
-frozen pose, where unchanged meshes reuse their raster and the reference
-redraws regardless), `?scene=rigid`, and `?scene=many&count=N` independent
-players — which is also where the architectural difference shows, since the
-reference needs one WebGL context per player against browsers' cap of ~16 and
-this package shares a single one however many there are. The page reports
-reaching that cap rather than dying at it.
+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.
+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),
+`?scene=rigid` (`walk-packed`, region attachments only) and
+`?scene=many&count=N` independent players; `?rig=` and `?model=` name another
+build. All four take `&count=N` up to 64 (a page limit, so that a cell stays
+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
+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
+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.
 
 `scripts/bench.mjs` walks `bench/scenes.json`, opens each scene in a **headed**
 Chromium (a hidden page throttles `requestAnimationFrame`, so a headless
-reading would be the browser's power policy rather than either runtime's cost),
-runs a fixed number of frames per runtime — one at a time, because rAF has a
-single cadence per document — and writes JSON plus a markdown table with the
+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
 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 rigs that never enter this repository.
+local rigc builds that never enter this repository.
 
-> **Numbers pending.** No comparison table is published yet, and one taken on a
-> loaded CI runner or in a headless browser would not be worth reading. 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 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.
+> **Numbers pending.** No comparison table is published yet. A 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
+> 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.
 
 The server is part of the test: a run tests whatever is being served on its
 port. Two checkouts of this repository on one machine (a worktree, a second
@@ -768,25 +803,45 @@ perf oracle is the demo's stats line on a real device.
 
 ## How it works
 
-1. `@esotericsoftware/spine-core` loads the skeleton and drives `AnimationState`,
-   constraints, and physics — all CPU-side, renderer-agnostic.
-2. At load time each atlas region 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.
-3. Per frame, for each slot in draw order: `computeWorldVertices` yields the region's
-   four corners in world space (order **BL, UL, UR, BR** — note the comments inside
-   `computeWorldVertices` are stale). Flip Y (Spine is Y-up), derive the affine from
-   three corners, write one `matrix()` string. That's the whole render path.
+1. `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.
+2. 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.
+3. 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 corners, write one `matrix()` string. That's the
+   whole rigid render path.
 
 ## License
 
-The code in this repository is MIT licensed.
-
-It depends on the [Spine Runtimes](https://github.com/EsotericSoftware/spine-runtimes)
-(`@esotericsoftware/spine-core`), which are licensed under the
-[Spine Runtimes License](https://esotericsoftware.com/spine-runtimes-license):
-**integrating the Spine Runtimes — including through this project — requires each user
-to have their own valid Spine Editor license.** See [NOTICE.md](NOTICE.md).
-
-Example assets (spineboy) are owned by Esoteric Software and are fetched from the
-official repository at setup time, not redistributed here.
+rig-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-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. 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.
+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.
+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-play neither adds those terms nor
+> removes them.
+
+No example assets of Esoteric Software's are fetched or redistributed. See
+[NOTICE.md](NOTICE.md) for the full notice.