rig-play 1.1.0 → 1.3.0

package/README.md

@@ -263,6 +263,35 @@ 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
@@ -406,7 +435,7 @@ onto shared pages instead. Both play here, unchanged:
   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:
+  `syncPixelRatio()`, `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,
@@ -559,7 +588,7 @@ name, and unloading is still elements first, bitmaps second.
 | `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.syncPixelRatio()` | `player.renderer.syncPixelRatio()` | On both renderers, the same meaning and the same deadband (since 1.3.0; before it, DOM mode only). |
 | `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). |
@@ -569,6 +598,9 @@ name, and unloading is still elements first, bitmaps second.
 | 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
 
@@ -586,13 +618,6 @@ export, for which 1.0.0 declares nothing:
   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.
@@ -608,8 +633,6 @@ export, for which 1.0.0 declares nothing:
 
 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`,

package/dist/CanvasRenderer.d.ts

@@ -52,7 +52,12 @@ export interface CanvasViewport {
 export declare class CanvasRenderer {
     private readonly root;
     private readonly pages;
-    /** Backing-store pixels per root CSS pixel; defaults to the device pixel ratio. Fold a root scale in, as for the DOM tier. */
+    /**
+     * Backing-store pixels per root CSS pixel; defaults to the device pixel
+     * ratio. A root under a CSS-scaled ancestor rasters at the wrong resolution
+     * until the scale is folded in — `syncPixelRatio()` measures it, as for the
+     * DOM tier. The next `render` sizes the backing store to the new ratio.
+     */
     pixelRatio: number;
     /** Apply the clips the frame carries (default). False draws every slot unclipped and counts the clips in `clipSkipCount`. */
     clipping: boolean;
@@ -113,6 +118,16 @@ export declare class CanvasRenderer {
      */
     constructor(root: HTMLElement, pages: ReadonlyMap<string, HTMLImageElement>);
     /** Grows the automatic viewport to cover `box` (world units, Y up) ahead of the frames reaching it. */
+    /**
+     * Measures the root's effective on-screen scale and sets `pixelRatio` to
+     * `devicePixelRatio × scale`, returning the ratio now in effect — the same
+     * call, the same meaning and the same deadband as `DomRenderer`'s, so code
+     * written against `player.renderer` survives a `mode` change. One forced
+     * layout per call (a hidden box appended to the root, read, removed), which
+     * is why the renderer never calls it for you. The backing store follows on
+     * the next `render`; a root that is not laid out leaves the ratio alone.
+     */
+    syncPixelRatio(): number;
     reserve(box: CanvasViewport): void;
     /** Draws one frame. */
     render(frame: PosedFrame): void;

package/dist/CanvasRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CanvasRenderer.d.ts","sourceRoot":"","sources":["../src/CanvasRenderer.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAwB,UAAU,EAAa,MAAM,iBAAiB,CAAC;AAEnF,+DAA+D;AAC/D,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,UAAU,CAAC;AAEjD,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC7B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBAAa,cAAc;IAgEvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAhExB,8HAA8H;IAC9H,UAAU,SAA+D;IACzE,6HAA6H;IAC7H,QAAQ,UAAQ;IAChB;;;;OAIG;IACH,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAQ;IACvC,mHAAmH;IACnH,OAAO,EAAE,aAAa,CAAW;IACjC,wEAAwE;IACxE,aAAa,EAAE,aAAa,CAAW;IACvC,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IAEnC,8EAA8E;IAC9E,SAAS,SAAK;IACd,oEAAoE;IACpE,YAAY,SAAK;IACjB,iEAAiE;IACjE,cAAc,SAAK;IACnB,oFAAoF;IACpF,YAAY,SAAK;IACjB,yDAAyD;IACzD,KAAK,SAAK;IACV,wEAAwE;IACxE,kBAAkB,SAAK;IACvB,yCAAyC;IACzC,SAAS,SAAK;IACd,gIAAgI;IAChI,aAAa,SAAK;IAElB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAkC;IACtD,gHAAgH;IAChH,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,IAAI,CAA0B;IACtC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkB;IACvC,sFAAsF;IACtF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;IACvD,yGAAyG;IACzG,OAAO,CAAC,GAAG,CAAyB;IACpC,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,QAAQ,CAAiB;IAEjC;;;;;;OAMG;gBAEgB,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAgB/D,uGAAuG;IACvG,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI;IAIlC,uBAAuB;IACvB,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAuD/B,+GAA+G;IAC/G,OAAO,IAAI,IAAI;IAYf,OAAO,CAAC,MAAM;IAkBd,OAAO,CAAC,OAAO;IAUf,oFAAoF;IACpF,OAAO,CAAC,WAAW;IAkBnB,uGAAuG;IACvG,OAAO,CAAC,gBAAgB;IAoExB,iFAAiF;IACjF,OAAO,CAAC,UAAU;IAalB,OAAO,CAAC,MAAM,CAAa;IAE3B;;;OAGG;IACH,OAAO,CAAC,QAAQ;IA4BhB,+CAA+C;IAC/C,OAAO,CAAC,aAAa;IAmErB,OAAO,CAAC,MAAM;CAmEf"}
+{"version":3,"file":"CanvasRenderer.d.ts","sourceRoot":"","sources":["../src/CanvasRenderer.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAwB,UAAU,EAAa,MAAM,iBAAiB,CAAC;AAEnF,+DAA+D;AAC/D,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,UAAU,CAAC;AAEjD,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC7B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBAAa,cAAc;IAqEvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IArExB;;;;;OAKG;IACH,UAAU,SAA+D;IACzE,6HAA6H;IAC7H,QAAQ,UAAQ;IAChB;;;;OAIG;IACH,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAQ;IACvC,mHAAmH;IACnH,OAAO,EAAE,aAAa,CAAW;IACjC,wEAAwE;IACxE,aAAa,EAAE,aAAa,CAAW;IACvC,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IAEnC,8EAA8E;IAC9E,SAAS,SAAK;IACd,oEAAoE;IACpE,YAAY,SAAK;IACjB,iEAAiE;IACjE,cAAc,SAAK;IACnB,oFAAoF;IACpF,YAAY,SAAK;IACjB,yDAAyD;IACzD,KAAK,SAAK;IACV,wEAAwE;IACxE,kBAAkB,SAAK;IACvB,yCAAyC;IACzC,SAAS,SAAK;IACd,gIAAgI;IAChI,aAAa,SAAK;IAElB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAkC;IACtD,gHAAgH;IAChH,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,IAAI,CAA0B;IACtC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkB;IACvC,sFAAsF;IACtF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;IACvD,yGAAyG;IACzG,OAAO,CAAC,GAAG,CAAyB;IACpC,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,QAAQ,CAAiB;IAEjC;;;;;;OAMG;gBAEgB,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAgB/D,uGAAuG;IACvG;;;;;;;;OAQG;IACH,cAAc,IAAI,MAAM;IAKxB,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI;IAIlC,uBAAuB;IACvB,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAuD/B,+GAA+G;IAC/G,OAAO,IAAI,IAAI;IAYf,OAAO,CAAC,MAAM;IAkBd,OAAO,CAAC,OAAO;IAUf,oFAAoF;IACpF,OAAO,CAAC,WAAW;IAkBnB,uGAAuG;IACvG,OAAO,CAAC,gBAAgB;IAoExB,iFAAiF;IACjF,OAAO,CAAC,UAAU;IAalB,OAAO,CAAC,MAAM,CAAa;IAE3B;;;OAGG;IACH,OAAO,CAAC,QAAQ;IA4BhB,+CAA+C;IAC/C,OAAO,CAAC,aAAa;IAmErB,OAAO,CAAC,MAAM;CAmEf"}

package/dist/DomRenderer.d.ts.map

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

package/dist/index.d.ts

@@ -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 BoneWorld, type PoseBounds, 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,SAAS,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAChI,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

@@ -1,3 +1,31 @@
+const SCALE_PROBE_PX = 100;
+const PIXEL_RATIO_DEADBAND = 1e-3;
+function syncedPixelRatio(root, current) {
+  const probe = document.createElement("div");
+  probe.style.position = "absolute";
+  probe.style.left = "0";
+  probe.style.top = "0";
+  probe.style.width = `${SCALE_PROBE_PX}px`;
+  probe.style.height = `${SCALE_PROBE_PX}px`;
+  probe.style.visibility = "hidden";
+  probe.style.pointerEvents = "none";
+  root.appendChild(probe);
+  let width = 0;
+  let height = 0;
+  try {
+    const rect = probe.getBoundingClientRect();
+    width = rect.width;
+    height = rect.height;
+  } finally {
+    probe.remove();
+  }
+  const scale = Math.max(width, height) / SCALE_PROBE_PX;
+  if (!(scale > 0)) return current;
+  const dpr = typeof devicePixelRatio === "number" ? devicePixelRatio : 1;
+  const next = dpr * scale;
+  if (current > 0 && Math.abs(next - current) < current * PIXEL_RATIO_DEADBAND) return current;
+  return next;
+}
 const RUNTIME_PI = 3.1415927;
 const RAD$3 = RUNTIME_PI / 180;
 const RUNTIME_DEG = 180 / RUNTIME_PI;
@@ -3819,6 +3847,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 +3998,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);
@@ -4819,16 +4923,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;
@@ -4836,7 +4940,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);
@@ -4856,8 +4960,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);
@@ -4866,7 +4970,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 {
@@ -4896,7 +5001,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;
     }
   }
@@ -5661,8 +5766,6 @@ function getMeshGlBlitter() {
 const regionVertices = new Float32Array(8);
 const SVG_NS = "http://www.w3.org/2000/svg";
 let tintFilterSeq = 0;
-const SCALE_PROBE_PX = 100;
-const PIXEL_RATIO_DEADBAND = 1e-3;
 function expandPoint(x, y, cx, cy, amount) {
   const dx = x - cx;
   const dy = y - cy;
@@ -5873,32 +5976,8 @@ class DomRenderer {
    * @returns the pixel ratio now in effect (the current one if nothing moved).
    */
   syncPixelRatio() {
-    const probe = document.createElement("div");
-    probe.style.position = "absolute";
-    probe.style.left = "0";
-    probe.style.top = "0";
-    probe.style.width = `${SCALE_PROBE_PX}px`;
-    probe.style.height = `${SCALE_PROBE_PX}px`;
-    probe.style.visibility = "hidden";
-    probe.style.pointerEvents = "none";
-    this.root.appendChild(probe);
-    let width = 0;
-    let height = 0;
-    try {
-      const rect = probe.getBoundingClientRect();
-      width = rect.width;
-      height = rect.height;
-    } finally {
-      probe.remove();
-    }
-    const scale = Math.max(width, height) / SCALE_PROBE_PX;
-    if (!(scale > 0)) return this.pixelRatio;
-    const dpr = typeof devicePixelRatio === "number" ? devicePixelRatio : 1;
-    const next = dpr * scale;
-    const current = this.pixelRatio;
-    if (current > 0 && Math.abs(next - current) < current * PIXEL_RATIO_DEADBAND) return current;
-    this.pixelRatio = next;
-    return next;
+    this.pixelRatio = syncedPixelRatio(this.root, this.pixelRatio);
+    return this.pixelRatio;
   }
   /**
    * Draws one frame. Slots the frame does not carry — no attachment, a
@@ -6563,7 +6642,12 @@ class CanvasRenderer {
     this.ctx = canvas.getContext("2d");
     root.appendChild(canvas);
   }
-  /** Backing-store pixels per root CSS pixel; defaults to the device pixel ratio. Fold a root scale in, as for the DOM tier. */
+  /**
+   * Backing-store pixels per root CSS pixel; defaults to the device pixel
+   * ratio. A root under a CSS-scaled ancestor rasters at the wrong resolution
+   * until the scale is folded in — `syncPixelRatio()` measures it, as for the
+   * DOM tier. The next `render` sizes the backing store to the new ratio.
+   */
   pixelRatio = typeof devicePixelRatio === "number" ? devicePixelRatio : 1;
   /** Apply the clips the frame carries (default). False draws every slot unclipped and counts the clips in `clipSkipCount`. */
   clipping = true;
@@ -6616,6 +6700,19 @@ class CanvasRenderer {
   nextSig = new Float64Array(256);
   nextRefs = [];
   /** Grows the automatic viewport to cover `box` (world units, Y up) ahead of the frames reaching it. */
+  /**
+   * Measures the root's effective on-screen scale and sets `pixelRatio` to
+   * `devicePixelRatio × scale`, returning the ratio now in effect — the same
+   * call, the same meaning and the same deadband as `DomRenderer`'s, so code
+   * written against `player.renderer` survives a `mode` change. One forced
+   * layout per call (a hidden box appended to the root, read, removed), which
+   * is why the renderer never calls it for you. The backing store follows on
+   * the next `render`; a root that is not laid out leaves the ratio alone.
+   */
+  syncPixelRatio() {
+    this.pixelRatio = syncedPixelRatio(this.root, this.pixelRatio);
+    return this.pixelRatio;
+  }
   reserve(box) {
     this.growTo(box.x, -(box.y + box.height), box.x + box.width, -box.y);
   }
@@ -7221,6 +7318,11 @@ class RigPlayer {
   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()
@@ -7234,6 +7336,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");
   }
   /**
@@ -7342,6 +7445,33 @@ 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
@@ -7427,7 +7557,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;
   }
   /**