rig-play 1.0.0 → 1.2.0

package/README.md

@@ -245,6 +245,53 @@ 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).
 
+### Reading the pose
+
+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
+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
+```
+
+`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.
+
+### Adjusting bones
+
+A per-pose write to bone locals — a breath's scale, a look's rotation, a mouth
+driven while the body holds still:
+
+```ts
+const player = new RigPlayer(root, assets, {
+  adjust: (bones) => { bones.bone('mouth').scaleY = 1 + openness; },
+});
+player.adjust = null;   // or set it later; setting it re-poses the held pose at once
+```
+
+The function runs once per pose, after the animation's timelines and before the
+world transforms, constraints and physics — `rig-c/core`'s `openTrack({ adjust })`,
+which rig-c holds to the Spine runtime at tolerance 0. **A write lasts one
+pose.** The core poses every step from the setup pose, so a value you want held
+is written again each pose and nothing compounds; a 0.8 caller that multiplied a
+channel on a skeleton it kept between frames writes the value it wants, every
+pose. It runs on every pose the animation is applied to, the first one after
+`play` included, and `seek` and a `mode` change keep it.
+
+A paused player and a zero step re-pose nothing, so a change the function would
+make is not seen until the next step — unless you ask: setting `player.adjust`
+re-poses the held pose at the same track time, and `player.repose()` does the
+same for a function whose own state changed (the mouth above), without stepping,
+firing events or drawing. A non-finite value, a bone the document does not have,
+or an error the function throws refuses that step in the core's words, and the
+track is reopened by the next `play` or `seek`.
+
 ### One load, several players
 
 One `loadModel` backs any number of players: the regions are cut once, and
@@ -493,6 +540,146 @@ 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. |
+| `skeleton.findBone('head').worldX`, `.worldY`, `.a` … `.d` | `player.bone('head')` | `{ x, y, a, b, c, d, rotationX, rotationY, scaleX, scaleY, active }`, the core's world transform for the pose the player holds (the setup pose before `play`). An unknown name is refused by name. Since 1.1.0. |
+| `bone.scaleY = …` on a `Skeleton` between `state.apply` and `updateWorldTransform` | `RigPlayerOptions.adjust`, `player.adjust`, `player.repose()` | A function called once per pose with the pose's bone locals (`bones.bone('mouth').scaleY = v`). A write lasts one pose: the core poses every step from the setup pose, so write the value you want, every pose — nothing compounds. See *Adjusting bones*. Since 1.2.0. |
+| `skeleton.getBounds(offset, size)` | `player.bounds()` | `{ x, y, width, height }` or null, world units, Y up: the box of every drawn region's corners and mesh's vertices, a slot under a clip counted inside the clip's own box. `ModelAssets.stage` remains the declared framing, not this box. Since 1.1.0. |
+
+### 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.
+- **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

package/dist/index.d.ts

@@ -2,6 +2,6 @@ export { type CanvasBackend, CanvasRenderer, type CanvasViewport } from './Canva
 export { DomRenderer, type MeshBackend } from './DomRenderer.js';
 export { type PageLayout, type PageRegion, type RegionImage, revokeRegions, unpackRegions } from './DomTexture.js';
 export { type LoadModelOptions, loadModel, type ModelAssets, type ModelDocument } from './loadModel.js';
-export { type RenderMode, type RigEvent, RigPlayer, type RigPlayerOptions } from './player.js';
+export { type AdjustableBones, type BoneAdjust, type BoneLocals, type BoneWorld, type PoseBounds, type RenderMode, type RigEvent, RigPlayer, type RigPlayerOptions } 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,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACnH,OAAO,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACxG,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/F,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,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACnH,OAAO,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACxG,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACxL,YAAY,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,SAAS,EACT,WAAW,EACX,SAAS,GACV,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -3819,6 +3819,81 @@ function posedBones(doc, timelines, t, plant = {}) {
     return bone2;
   });
 }
+const LOCAL_CHANNELS = { rotation: 0, x: 0, y: 0, scaleX: 1, scaleY: 1, shearX: 0, shearY: 0 };
+class StepLocals {
+  constructor(bones, index, setup) {
+    this.bones = bones;
+    this.index = index;
+    this.setup = setup;
+  }
+  read(channel2) {
+    return this.bones[this.index][channel2] ?? LOCAL_CHANNELS[channel2];
+  }
+  write(channel2, value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) throw new CoreInputError(`the adjustment wrote bone "${this.setup.name}" ${channel2} = ${String(value)}, not a finite number`);
+    if (this.bones[this.index] === this.setup) this.bones[this.index] = { ...this.setup };
+    this.bones[this.index][channel2] = value;
+  }
+  get rotation() {
+    return this.read("rotation");
+  }
+  set rotation(v) {
+    this.write("rotation", v);
+  }
+  get x() {
+    return this.read("x");
+  }
+  set x(v) {
+    this.write("x", v);
+  }
+  get y() {
+    return this.read("y");
+  }
+  set y(v) {
+    this.write("y", v);
+  }
+  get scaleX() {
+    return this.read("scaleX");
+  }
+  set scaleX(v) {
+    this.write("scaleX", v);
+  }
+  get scaleY() {
+    return this.read("scaleY");
+  }
+  set scaleY(v) {
+    this.write("scaleY", v);
+  }
+  get shearX() {
+    return this.read("shearX");
+  }
+  set shearX(v) {
+    this.write("shearX", v);
+  }
+  get shearY() {
+    return this.read("shearY");
+  }
+  set shearY(v) {
+    this.write("shearY", v);
+  }
+}
+function adjustLocals(doc, bones, adjust) {
+  const views = /* @__PURE__ */ new Map();
+  const names = doc.bones.map((b) => b.name);
+  adjust({
+    names,
+    bone(name) {
+      let view = views.get(name);
+      if (view === void 0) {
+        const index = names.indexOf(name);
+        if (index < 0) throw new CoreInputError(`the adjustment asked for bone ${JSON.stringify(name)}, which is not one of this document's bones`);
+        view = new StepLocals(bones, index, doc.bones[index]);
+        views.set(name, view);
+      }
+      return view;
+    }
+  });
+}
 const clamp01 = (v) => v < 0 ? 0 : v > 1 ? 1 : v;
 function posedSlots(doc, timelines, t, plant = {}, sliders = [], placeholders) {
   const resolve = plant.shown ?? shownAttachment;
@@ -3895,6 +3970,7 @@ function stepRows(posed) {
 function posedBoneStep(doc, timelines, t, plant, constraints, sliders, step) {
   const active = activeBones(doc);
   const bones = posedBones(doc, timelines, t, plant);
+  if (step?.adjust !== void 0) adjustLocals(doc, bones, step.adjust);
   let world = (plant.evaluate ?? worldTransforms)(bones, active);
   if (constraints !== void 0 && step !== void 0) {
     const records = stepPhysicsRecords(pathDeformed(doc, posedRecords(constraintRecords(doc), constraints, t), timelines, t, plant), constraints.physicsKeyed ?? [], t, active, step.ctx, step.before);
@@ -4515,6 +4591,8 @@ function rawNumber(v) {
 function constraintRecords(doc) {
   return doc.constraints.flatMap((c) => c.record === void 0 ? [] : [c.record]);
 }
+const NOT_ADMITTED = [];
+const POSED_BLOCKS = ["setup.bones", "setup.slots", "setup.drawOrder", "setup.attachments", "setup.clips", "setup.clipped"];
 const activeOfView = /* @__PURE__ */ new WeakMap();
 function activeBones(doc) {
   const kept = activeOfView.get(doc);
@@ -4582,6 +4660,97 @@ function resolveShown(doc, slotName, placeholder) {
   const agree = rows.every((r) => r.name === rows[0].name && r.path === rows[0].path);
   return agree ? filling[0] : { conflict: rows.map((r) => ({ skin: r.skin, shown: r.name, path: r.path })) };
 }
+function poseSetup(doc, plant = {}, physics) {
+  const evaluate = plant.evaluate ?? worldTransforms;
+  const resolve = plant.shown ?? shownAttachment;
+  const colour = plant.colour ?? readColour;
+  const blend = plant.blend ?? readBlend;
+  const round = plant.round ?? gridRound;
+  const bonesWhy = constraintsAbsentWhy(doc, solverRules(plant.solver));
+  let bones = null;
+  let setupWorld = null;
+  const applied = [];
+  if (bonesWhy === null) {
+    const active = activeBones(doc);
+    const records = constraintRecords(doc);
+    setupWorld = applyConstraints(doc.bones, evaluate(doc.bones, active), active, plant.constraints ? plant.constraints(records) : records, null, applied, physics, void 0, solverRules(plant.solver));
+    const world = setupWorld;
+    bones = doc.bones.map((b) => {
+      const t = world.get(b.name);
+      if (t === void 0) throw new CoreInputError(`the evaluator returned no transform for bone "${b.name}"`);
+      return [b.name, round(t.worldX), round(t.worldY), round(t.a), round(t.b), round(t.c), round(t.d), active.has(b.name) ? 1 : 0, b.parent ?? null];
+    });
+  }
+  const conflicts = [];
+  const slotRows = [];
+  const liveBones = activeBones(doc);
+  const slotGate = plant.slotTimelines ?? slotTimelinesApply;
+  for (const slot of doc.slots) {
+    const pose = {
+      placeholder: slot.setup,
+      light: slot.color === void 0 ? [1, 1, 1, 1] : [...colour(slot.color)],
+      dark: slot.dark === void 0 ? null : readColour(slot.dark).slice(0, 3)
+    };
+    if (slotGate(doc, slot, liveBones)) applySliderSlots(slot.name, pose, applied);
+    const posedRecord = { ...slot, setup: pose.placeholder };
+    const shown = pose.placeholder === null ? null : resolve(doc, posedRecord);
+    if (shown !== null && "conflict" in shown) {
+      conflicts.push(`slot "${slot.name}" placeholder "${pose.placeholder}" is filled by skins ${shown.conflict.map((c) => `"${c.skin}" (shows ${JSON.stringify(c.shown)}, path ${JSON.stringify(c.path)})`).join(", ")}`);
+      continue;
+    }
+    const row = shown === null ? null : shownRow(shown);
+    const [r, g, b, a] = pose.light;
+    const dark = pose.dark;
+    slotRows.push([
+      slot.name,
+      row === null ? null : row.name,
+      round(r),
+      round(g),
+      round(b),
+      round(a),
+      dark === null ? null : [round(dark[0]), round(dark[1]), round(dark[2])],
+      row === null ? null : row.path,
+      blend(slot)
+    ]);
+  }
+  const slotsWhy = (bonesWhy === null ? null : slidersWhy(doc)) ?? (conflicts.length === 0 ? null : `${conflicts.join("; ")} — under --skin all the LAST of them in the Spine file's skin order wins, and that order is the emitter's (default first, the rest in the editor's order), not the model's; the per-skin dumps (--skin <name>) judge it`);
+  const slots = slotsWhy === null ? slotRows : null;
+  const upstream = [bonesWhy === null ? null : `setup.bones is absent (${bonesWhy}), and every vertex goes through a bone's world matrix`, slotsWhy === null ? null : "setup.slots is absent, so what a slot shows is not posed"].filter((x) => x !== null);
+  const orderWhy = bonesWhy === null ? null : slidersKeyingWhy(doc, "drawOrder");
+  let drawOrder = null;
+  if (orderWhy === null) {
+    let order = doc.slots.map((_s, i) => i);
+    for (const app of applied) order = (plant.drawOrder ?? drawOrderAt)(doc.slots.length, app.timelines.drawOrder, app.at) ?? order;
+    drawOrder = order.map((i) => doc.slots[i].name);
+  }
+  let attachments = null;
+  let clips = null;
+  let clipsWhy = upstream.length === 0 ? null : upstream.join("; ");
+  let attachmentsWhy = clipsWhy;
+  let clipped = null;
+  let clippedWhy = clipsWhy ?? orderWhy;
+  let shownInOrder = null;
+  if (clipsWhy === null && setupWorld !== null && drawOrder !== null) {
+    const world = setupWorld;
+    const placeholders = new Map(doc.slots.map((sl) => [sl.name, sl.setup]));
+    const states = attachmentStates(doc, resolve, placeholders, null, applied, plant);
+    const rank = new Map(drawOrder.map((n, i) => [n, i]));
+    const shown = [...states.shown].sort((a, b) => (rank.get(a.slot) ?? 0) - (rank.get(b.slot) ?? 0));
+    shownInOrder = states.why.length === 0 ? shown : null;
+    const posed = poseGeometry(shown, world, sourceOfDoc(doc), round, { region: plant.region, vertices: plant.vertices }, drawWalkOf(doc, drawOrder, plant));
+    const stateWhy = states.why.length === 0 ? null : `${states.why.join("; ")}`;
+    attachments = stateWhy === null ? posed.attachments : null;
+    attachmentsWhy = stateWhy ?? posed.attachmentsWhy;
+    clips = stateWhy === null ? posed.clips : null;
+    clipsWhy = stateWhy;
+    clipped = stateWhy === null ? posed.clipped : null;
+    clippedWhy = stateWhy ?? posed.clippedWhy;
+  }
+  const why = { "setup.bones": bonesWhy, "setup.slots": slotsWhy, "setup.drawOrder": orderWhy, "setup.attachments": attachmentsWhy, "setup.clips": clipsWhy, "setup.clipped": clippedWhy };
+  const absent = NOT_ADMITTED.map(([block, reason]) => [block, reason]);
+  for (const block of POSED_BLOCKS) if (why[block] !== null) absent.push([block, why[block]]);
+  return { setup: { bones, slots, drawOrder, attachments, clips, clipped }, absent, world: setupWorld, shown: shownInOrder };
+}
 function drawWalkOf(doc, order, plant = {}) {
   const active = activeBones(doc);
   return {
@@ -4601,6 +4770,22 @@ function sourceOfDoc(doc) {
     return g?.kind === "mesh" ? g.vertices : sourceProblem(doc.skins, skin, slot, source) ?? `the linked mesh's source "${source}" carries no vertices`;
   };
 }
+function slidersKeyingWhy(doc, group) {
+  const keyed = doc.constraints.flatMap((c) => {
+    if (c.kind !== "slider") return [];
+    const anim = doc.animations.find((a) => a.name === c.animation);
+    return anim !== void 0 && anim.timelines[group].length > 0 ? [`slider "${c.name}" applies animation "${c.animation}", which keys the draw order`] : [];
+  });
+  return keyed.length === 0 ? null : `${keyed.join("; ")} — a slider's time is read off the bones, which are absent`;
+}
+function slidersWhy(doc) {
+  const keyed = doc.constraints.flatMap((c) => {
+    if (c.kind !== "slider") return [];
+    const slots = doc.animations.find((a) => a.name === c.animation)?.slots ?? [];
+    return slots.length === 0 ? [] : [`slider "${c.name}" applies animation "${c.animation}", which keys slot(s) ${slots.map((x) => `"${x}"`).join(", ")}`];
+  });
+  return keyed.length === 0 ? null : `${keyed.join("; ")} — the oracle's setup applies sliders, and a slider poses the slots its animation keys at a time read off the bones, which are absent`;
+}
 function drawOrderOf(shown, order) {
   const rank = new Map(order.map((n, r) => [n, r]));
   return [...shown].sort((a, b) => (rank.get(a.slot) ?? 0) - (rank.get(b.slot) ?? 0));
@@ -4677,6 +4862,22 @@ function rawDrawn(doc, shown, world, order, plant, mode = RAW_MODE) {
   const clipped = geometry.drawnClipped.map((c) => [c[0], c[1], c[2], c[3].map((v) => numberOf(v, `clipped vertex of slot "${c[0]}"`, mode)), c[4].map((v) => numberOf(v, `clipped uv of slot "${c[0]}"`, mode)), c[5]]);
   return { drawn, clips, clipped };
 }
+function poseRawSetup(doc, plant = {}) {
+  return setupPoseIn(doc, plant, RAW_MODE);
+}
+function setupPoseIn(doc, plant, mode) {
+  const { world, shown, slots, drawOrder } = setupPosed(doc, plant, mode);
+  const drawn = rawDrawn(doc, shown, world, drawOrder, plant, mode);
+  return { trackTime: 0, animationTime: 0, bones: rawBones(doc, world), slots, drawOrder, ...drawn, events: [], shown: drawOrderOf(shown, drawOrder) };
+}
+function setupPosed(doc, plant, mode) {
+  const posed = poseSetup(doc, { ...plant, ...roundPlant(mode) }, freshStepContext(plant.physicsStep));
+  const absent = posed.absent.filter(([block]) => block !== "setup.clipped");
+  if (absent.length > 0) throw new CoreInputError(`the raw setup pose leaves ${absent.map(([b, why]) => `${b} out (${why})`).join("; ")}`);
+  const { setup, world, shown } = posed;
+  if (world === null || shown === null || setup.slots === null || setup.drawOrder === null) throw new CoreInputError("the raw setup pose was not posed");
+  return { world, shown, slots: setup.slots, drawOrder: setup.drawOrder };
+}
 function loopedTime(trackTime, duration) {
   return duration === 0 ? 0 : trackTime % duration;
 }
@@ -4694,16 +4895,16 @@ function animationOf(doc, animation) {
   if (anim === void 0) throw new CoreInputError(`animation "${animation}" is not one of this document's [${doc.animations.map((a) => a.name).join(", ")}]`);
   return anim;
 }
-function openWalk(doc, anim, plant, reset, mode, shape) {
+function openWalk(doc, anim, plant, reset, mode, shape, adjust) {
   const why = constraintsAbsentWhy(doc) ?? pathAnimationsWhy(doc) ?? steppedPreviousPassWhy(doc);
   if (why !== null) throw new CoreInputError(`the raw walk leaves the bones out: ${why}`);
   const ctx = freshStepContext(plant.physicsStep);
   if (mode.loop && mode.wrapResets !== false) ctx.loop = true;
-  const track = { doc, anim, duration: anim.timelines.duration, mode, plant, raw: { ...plant, ...roundPlant(mode) }, resolve: plant.shown ?? shownAttachment, shape, ctx, trackTime: 0, last: -1 };
+  const track = { doc, anim, duration: anim.timelines.duration, mode, plant, raw: { ...plant, ...roundPlant(mode) }, resolve: plant.shown ?? shownAttachment, shape, ctx, adjust, trackTime: 0, last: -1 };
   return { track, first: stepWalk(track, 0, true) };
 }
 function stepWalk(track, dt, first = false) {
-  const { doc, anim, duration, mode, plant, raw, resolve, shape, ctx } = track;
+  const { doc, anim, duration, mode, plant, raw, resolve, shape, ctx, adjust } = track;
   track.trackTime += dt;
   const trackTime = track.trackTime;
   const last = track.last;
@@ -4711,7 +4912,7 @@ function stepWalk(track, dt, first = false) {
   const before = ctx.time;
   ctx.time += mode.clock === void 0 ? dt : mode.clock(dt, t - (first ? 0 : Math.max(last, 0)));
   const sliders = [];
-  const world = shape.rows ? posedBoneWorld(doc, anim.timelines, t, raw, anim.constraints, sliders, { ctx, before }).world : posedBoneWorldAlone(doc, anim.timelines, t, raw, anim.constraints, sliders, { ctx, before });
+  const world = shape.rows ? posedBoneWorld(doc, anim.timelines, t, raw, anim.constraints, sliders, { ctx, before, adjust }).world : posedBoneWorldAlone(doc, anim.timelines, t, raw, anim.constraints, sliders, { ctx, before, adjust });
   if (first) ctx.phase = "update";
   const placeholders = /* @__PURE__ */ new Map();
   const slots = posedSlots(doc, anim.timelines, t, raw, sliders, placeholders);
@@ -4731,8 +4932,8 @@ function stepWalk(track, dt, first = false) {
   track.last = t;
   return pose;
 }
-function openRawTrack(doc, animation, plant, reset, mode) {
-  return openWalk(doc, animationOf(doc, animation), plant, reset, mode, RAW_SHAPE);
+function openRawTrack(doc, animation, plant, reset, mode, adjust) {
+  return openWalk(doc, animationOf(doc, animation), plant, reset, mode, RAW_SHAPE, adjust);
 }
 function stepRawTrack(track, dt) {
   return stepWalk(track, dt);
@@ -4741,7 +4942,8 @@ const HELD = { loop: false, keep: false };
 const LOOPED = { loop: true, keep: false, live: true };
 function openTrack(doc, animation, options, plant = {}) {
   if (typeof options !== "object" || options === null || typeof options.loop !== "boolean") throw new CoreInputError(`the live track's options.loop is ${JSON.stringify(options?.loop)}, not true or false`);
-  const { track, first } = openRawTrack(doc, animation, plant, options.reset, options.loop ? LOOPED : HELD);
+  if (options.adjust !== void 0 && typeof options.adjust !== "function") throw new CoreInputError(`the live track's options.adjust is ${typeof options.adjust}, not a function`);
+  const { track, first } = openRawTrack(doc, animation, plant, options.reset, options.loop ? LOOPED : HELD, options.adjust);
   return new Track(track, first);
 }
 class Track {
@@ -4771,7 +4973,7 @@ class Track {
       this.latest = pose.animationTime;
       return pose;
     } catch (err) {
-      if (err instanceof CoreInputError) this.refused = `${n} (${err.message})`;
+      this.refused = `${n} (${err instanceof Error ? err.message : String(err)})`;
       throw err;
     }
   }
@@ -7095,6 +7297,12 @@ class RigPlayer {
   loop = true;
   paused = false;
   pose = null;
+  setup = null;
+  adjustFn = null;
+  /** Handed to every track the player opens; reads the current `adjust` so setting it later needs no reopen. */
+  adjustHook = (locals) => {
+    if (this.adjustFn !== null) this.adjustFn(locals);
+  };
   listeners = {
     event: /* @__PURE__ */ new Set(),
     complete: /* @__PURE__ */ new Set()
@@ -7108,6 +7316,7 @@ class RigPlayer {
     this.root = root;
     this.assets = assets;
     this.meshBackend = options.meshBackend;
+    this.adjustFn = options.adjust ?? null;
     this.active = this.create(options.mode ?? "dom");
   }
   /**
@@ -7216,6 +7425,106 @@ class RigPlayer {
     if (this.pose === null) return;
     this.renderer.render(this.posedFrame());
   }
+  /**
+   * The per-pose adjustment of bone locals (`BoneAdjust`), or null for none.
+   * It is applied by every track the player opens — `play`, the reopen inside
+   * `seek` — and by the pose drawn again after `mode` changes, on every pose
+   * the animation is applied to, the first one included. Setting it re-poses
+   * the pose the player holds at once (`repose`), so a held or paused player
+   * shows the change on its next `draw` without a step.
+   */
+  get adjust() {
+    return this.adjustFn;
+  }
+  set adjust(fn) {
+    if (fn !== null && typeof fn !== "function") throw new Error(`adjust must be a function or null, got ${typeof fn}`);
+    this.adjustFn = fn;
+    this.repose();
+  }
+  /**
+   * Poses the held pose again at the same track time, through the current
+   * `adjust`, without stepping, firing or drawing. A paused player and a zero
+   * step re-pose nothing, so a caller whose adjustment reads its own state
+   * (a mouth driven while the body is held) calls this when that state
+   * changed, then `draw`. Nothing before `play`.
+   */
+  repose() {
+    if (this.track === null || this.pose === null) return;
+    this.pose = this.track.step(0);
+  }
+  /**
+   * Where `name` is in the pose the player holds — the pose of the last
+   * `advance`/`frame`/`seek`, or the setup pose before `play`. Read off the
+   * core's pose, so it is the same in `dom` and `canvas` mode and costs nothing
+   * until called. An unknown bone is refused by name.
+   */
+  bone(name) {
+    const pose = this.posed();
+    for (const bone2 of pose.bones) {
+      if (bone2.name !== name) continue;
+      return {
+        name,
+        active: bone2.active,
+        x: bone2.worldX,
+        y: bone2.worldY,
+        a: bone2.a,
+        b: bone2.b,
+        c: bone2.c,
+        d: bone2.d,
+        rotationX: bone2.rotationX,
+        rotationY: bone2.rotationY,
+        scaleX: bone2.scaleX,
+        scaleY: bone2.scaleY
+      };
+    }
+    throw new Error(`no bone named ${JSON.stringify(name)} in this document (bones: ${pose.bones.map((b) => b.name).join(", ")})`);
+  }
+  /**
+   * The box of what the pose the player holds draws, in world units, Y up:
+   * every region's four corners and every mesh's vertices, in the same frame
+   * record the renderer takes (`posedFrame`). A slot under a clip counts only
+   * inside the clip polygon's own box (an inverse clip removes nothing from
+   * the count); bounding boxes, paths and points are not drawn and do not
+   * count. `null` when nothing draws. The same numbers in `dom` and `canvas`
+   * mode; nothing is computed until called.
+   */
+  bounds() {
+    const frame2 = this.pose === null ? frameOf(this.source, this.posed(), this.color) : this.posedFrame();
+    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+    for (const slot of frame2.order) {
+      const points = slot.kind === "region" ? slot.corners : slot.vertices;
+      let lo = -Infinity, lb = -Infinity, hi = Infinity, hb = Infinity;
+      if (slot.clip && !slot.clip.inverse) {
+        const c = slot.clip.polygon;
+        lo = Infinity;
+        lb = Infinity;
+        hi = -Infinity;
+        hb = -Infinity;
+        for (let i = 0; i < c.length; i += 2) {
+          if (c[i] < lo) lo = c[i];
+          if (c[i] > hi) hi = c[i];
+          if (c[i + 1] < lb) lb = c[i + 1];
+          if (c[i + 1] > hb) hb = c[i + 1];
+        }
+      }
+      for (let i = 0; i < points.length; i += 2) {
+        const x = Math.min(Math.max(points[i], lo), hi);
+        const y = Math.min(Math.max(points[i + 1], lb), hb);
+        if (x < minX) minX = x;
+        if (x > maxX) maxX = x;
+        if (y < minY) minY = y;
+        if (y > maxY) maxY = y;
+      }
+    }
+    if (minX === Infinity) return null;
+    return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+  }
+  /** The pose the reads above see: the track's, or the setup pose before `play` (posed once). */
+  posed() {
+    if (this.pose !== null) return this.pose;
+    if (this.setup === null) this.setup = poseRawSetup(this.view);
+    return this.setup;
+  }
   /** The pose the player holds, as the frame record the renderer draws. */
   posedFrame() {
     if (this.pose === null) return { order: [] };
@@ -7228,7 +7537,7 @@ class RigPlayer {
     this.pose = null;
   }
   open() {
-    this.track = openTrack(this.view, this.animation, { loop: this.loop, reset: "animation" });
+    this.track = openTrack(this.view, this.animation, { loop: this.loop, reset: "animation", adjust: this.adjustHook });
     this.pose = this.track.first;
   }
   /**