@rig-c/play 1.15.0 → 1.17.0

package/README.md

@@ -603,6 +603,103 @@ poses the held pose again at the same time. Two active sets drawing the same
 bone are refused by name, as two sets touching one slot are. A `drawn` naming
 a bone the document does not have is refused when `sets.json` is loaded.
 
+**Physics under a drawn bone** (#173). A physics chain hung from a bone a set
+re-poses — a sleeve under a raised arm — reads the jump to the drawn angle as
+motion: the constraint remembers where its bone was and pointed, so the
+switch kicks it (on the test rig `drape`, a 110° raise throws the sleeve's
+tip about 297 units off the arm in the switch itself, against an idle
+frame-to-frame range of 1.5). Every set call takes an option for the chains
+under the bones the switch re-poses:
+
+```ts
+player.setSets(['raise'], { physics: 'carry' }); // also setSet, addSet, removeSet
+```
+
+- `'carry'` moves each affected constraint's remembered state by the rigid
+  turn of its deepest re-posed ancestor, so the chain keeps its pose relative
+  to the arm and goes on swinging from there (the switch itself moves the
+  sleeve 0 relative to the arm; gravity then re-settles it in the turned pose,
+  which is physics and not the switch).
+- `'reset'` restarts each affected constraint at the new pose, as a physics
+  `reset` key does: the chain snaps straight along its bones (17 units on the
+  same raise) and settles from there.
+- Absent, nothing changes: today's behaviour, frame for frame. This stays the
+  default.
+
+`'carry'` is recommended: on `drape` it moves the sleeve 0 relative to the arm
+at the switch and 0 at the deactivation, where `'reset'` moves it 17 units at
+the switch and 118 at the deactivation (no option: 297 and 298).
+
+A constraint is affected when its bone is a bone whose drawn rotation the call
+adds, removes or changes, or a descendant of one; every other chain is not
+touched. The option does nothing before `play` (the setup pose carries no
+physics state) and nothing when no physics hangs under a re-posed bone. Three limits:
+
+- Carry moves the positions and direction the constraint remembers; a
+  constraint with `x`/`y` keeps its translation offsets along the world axes,
+  unturned.
+- A drawn bone nested under a carried chain reads its new world from the
+  chain's state before the carry.
+- A later `seek` replays from the start with the sets then active, as it
+  always has, so it does not reproduce a carried switch.
+
+**Easing a drawn set in and out** (#174). A drawn set snaps its bones to the
+drawn angles in one frame. `ease` turns them there over a duration instead,
+and swaps the attachments halfway, the way an alternate drawing takes over
+at a middle angle:
+
+```ts
+player.setSets(['wave_r'], { ease: 0.5 });   // also setSet, addSet, removeSet
+player.setSets([], { ease: 0.5 });           // and back
+```
+
+- **The curve.** Each bone whose drawn rotation the call adds, removes or
+  changes turns from what it shows to its new local rotation along the
+  shorter way: `start + shortestΔ(start, end) · smoothstep(u)`, with
+  `u = elapsed / ease`. Going on, the start is the clip's value at the time
+  (it moves with the clip) and the end the drawn local; going off, the start
+  is the drawn local and the end the clip's value. So the progress from start
+  to end never leaves `[0, 1]` and never turns back, while the clip plays
+  underneath. On `@rig-c/parts`' public wind example with its gesture set
+  (`wave_r`, 0.5 s), it is 0 to 1 and non-decreasing on every frame, on and
+  off; on a clip that holds the arm still, the sleeve's world angle goes
+  −119.32° → −110° and back with no overshoot.
+- **The swap.** The held pose draws the attachments it showed until the frame
+  whose `u` is nearest ½, then the set's (a tie goes to the later frame; the
+  next step is predicted from the current one, so a constant `dt` lands on
+  the nearest frame). On the wind example at `frame(1/60)`, 0.5 s swaps on
+  frame 15 and 0.25 s on frame 8. `activeSets`, `set` and `slotIdentity().sets`
+  name the call's sets from the call on; `slotIdentity().slots` reports what
+  the pose draws, so before the swap it shows the previous attachments.
+- **The end.** On the frame the elapsed time reaches `ease`, the player is in
+  exactly the instant switch's state: from then on every bone matches an
+  instant switch made at the same frame (0° measured) and the slot identity
+  too.
+- **Time.** The elapsed time is the player's step (`dt × timeScale`): a
+  paused player, or a step of 0, holds the ease where it is. Before `play`
+  there is nothing to step and the switch is instant; so is a call that
+  re-poses no bone. A `seek` or a skin change lands an ease in flight at
+  once.
+- **A call during an ease** starts a new one from the angles shown (no jump:
+  reversing a 0.5 s ease at 0.3 makes no frame-to-frame step larger than the
+  ease's own), and the attachment swap starts again from what is drawn. A
+  call without `ease` during an ease lands it at once.
+- `ease: 0`, or no `ease`, is the instant switch, frame for frame. Anything
+  but a finite number at or above 0 is refused by name before anything
+  changes.
+
+With physics: `ease` and `physics: 'carry'` carry the chains under the eased
+bones on every eased frame — before each step, the turn the frame's blend
+makes is read as #173's switch is (a trial pose at the previous time) and
+the chains are moved by it — so the ease's own turn is not read as motion.
+`physics: 'reset'` with `ease` restarts them once, at the call. On `drape`
+(0.5 s raise, sleeve tips in the arm's frame): the ease alone moves the
+sleeve up to 30 units a frame relative to the arm (the chain reads the turn
+as motion), ease + carry at most 3.9 on the `idle` clip (its idle ranges are
+1.5 hanging and 4.2 raised) and 2.3 on `shift` (0.85 and 0.07), where
+gravity re-settles the chain in the turning arm's frame (with gravity at 0,
+0.83 against 0.84).
+
 `sets.json` keys are read strictly. Besides `slots`, `hides` and `drawn`, a
 set may carry `drawnLength`, `registration` and `threshold`, which parts
 writes and which place nothing under `check --set`: play reads past them by

package/dist/index.d.ts

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

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -8962,6 +8962,42 @@ function frameOf(source, pose, color = [1, 1, 1, 1], draws = () => true) {
   return { order };
 }
 const DEFAULT_ENVIRONMENT = Object.freeze({ wind: Object.freeze([1, 0]), gravity: Object.freeze([0, 1]) });
+function setEaseOption(call, options) {
+  const ease = options?.ease;
+  if (ease === void 0) return 0;
+  if (typeof ease !== "number" || !Number.isFinite(ease) || ease < 0) {
+    throw new Error(`${call}: options.ease must be a finite number of seconds at or above 0, got ${typeof ease === "number" ? String(ease) : JSON.stringify(ease)}`);
+  }
+  return ease;
+}
+function easeProgress(ease) {
+  return Math.min(Math.max(ease.elapsed / ease.duration, 0), 1);
+}
+function smoothstep(u) {
+  return u * u * (3 - 2 * u);
+}
+function setPhysicsOption(call, options) {
+  if (options === void 0) return void 0;
+  if (options === null || typeof options !== "object") {
+    throw new Error(`${call}: options must be an object like { physics: 'carry' }, got ${JSON.stringify(options)}`);
+  }
+  const physics = options.physics;
+  if (physics === void 0 || physics === "carry" || physics === "reset") return physics;
+  throw new Error(`${call}: options.physics must be 'carry' or 'reset', got ${JSON.stringify(physics)}`);
+}
+function drawnChanged(before, after) {
+  const changed = /* @__PURE__ */ new Set();
+  if (before !== null) {
+    for (const [bone2, rotation] of before) if (after?.get(bone2) !== rotation) changed.add(bone2);
+  }
+  if (after !== null) {
+    for (const [bone2, rotation] of after) if (before?.get(bone2) !== rotation) changed.add(bone2);
+  }
+  return changed;
+}
+function physicsContextOf(stepper) {
+  return "first" in stepper ? stepper.track.ctx : stepper.path.ctx;
+}
 function predicateOf(names) {
   const allowed = new Set(names);
   return (slot) => allowed.has(slot);
@@ -9261,6 +9297,14 @@ class RigPlayer {
   touchedSets = /* @__PURE__ */ new Map();
   /** The active sets' drawn bones as local rotations, applied before `adjust` on every pose (#170); null when none draws. */
   drawnPose = null;
+  /** Test-only (#173's planted control): `carry` maps every state through the identity instead of the anchor's turn. Not API. */
+  carryPlant = false;
+  /** An eased set switch in flight (#174), or null. */
+  easing = null;
+  /** The last positive step `advance` took: what predicts the next one when an ease starts. */
+  lastStep = 0;
+  /** Test-only (#174's planted controls): swap the attachments at u = 0, or ease by w = 1.2u (1 at u = 1). Not API. */
+  easePlant = null;
   adjustFn = null;
   /** Current preview patches, reapplied through the public core API on replay; no edit history. */
   physicsPatches = /* @__PURE__ */ new Map();
@@ -9271,7 +9315,8 @@ class RigPlayer {
   draws = () => true;
   /** Handed to every track the player opens; reads the current `adjust` so setting it later needs no reopen. */
   adjustHook = (locals, ctx) => {
-    if (this.drawnPose !== null) for (const [bone2, rotation] of this.drawnPose) locals.bone(bone2).rotation = rotation;
+    if (this.easing !== null) this.applyEase(this.easing, locals);
+    else if (this.drawnPose !== null) for (const [bone2, rotation] of this.drawnPose) locals.bone(bone2).rotation = rotation;
     if (this.adjustFn !== null) this.adjustFn(locals, ctx);
   };
   listeners = {
@@ -9480,11 +9525,12 @@ class RigPlayer {
     if (time > 0) this.stepTo(time);
     return tracks;
   }
-  /** Stores `raw` and applies `activeSet` when one is active. Zero work when `activeSet === null`. */
+  /** Stores `raw` and applies the shown set (`activeSet`, or before an ease's swap the composition it eases from). Zero work when none. */
   setRawPose(raw) {
     this.rawPose = raw;
     this.heldParameters = null;
-    this.pose = this.activeSet === null ? raw : applySetToPose(this.view, raw, this.activeSet);
+    const set = this.shownSet();
+    this.pose = set === null ? raw : applySetToPose(this.view, raw, set);
     this.poseGeneration++;
     this.cachedIdentity = null;
   }
@@ -9602,6 +9648,7 @@ class RigPlayer {
     if (this.animation === null) throw new Error("seek before play: no animation is open");
     if (!(time >= 0) || !Number.isFinite(time)) throw new Error(`seek time must be a finite time at or above 0, got ${String(time)}`);
     if (this.beyondBase) throw new Error("seek is defined for a single animation on track 0; after a mix, another track, a queue or a clear the player cannot replay to a time — step it forward with frame/advance instead");
+    this.easing = null;
     const cache = this.ensureSeekCache();
     const stepper = this.tracks ?? this.track;
     const exactHit = cache.exact.get(time);
@@ -9757,6 +9804,8 @@ class RigPlayer {
     if (this.pose === null) return;
     const step = dt * this.timeScale;
     if (this.paused || !(step > 0)) return;
+    this.lastStep = step;
+    if (this.easing !== null) this.advanceEase(this.easing, step);
     const tracks = this.tracks;
     if (tracks !== null) {
       const before2 = [];
@@ -9799,6 +9848,7 @@ class RigPlayer {
     this.source = frameSource(view, this.read.parsed);
     this.skinName = name;
     this.setup = null;
+    this.easing = null;
     this.clearSeekCache();
     if (this.animation !== null && (this.track !== null || this.tracks !== null)) {
       const time = this.time;
@@ -9852,11 +9902,13 @@ class RigPlayer {
    * A name not in `sets.json` throws by name; a build without `sets.json` has
    * `sets()` empty and `setSet` throws.
    */
-  setSet(name) {
+  setSet(name, options) {
     if (this.setList.length === 0) {
       throw new Error(`cannot setSet(${JSON.stringify(name)}): this model has no sets.json`);
     }
-    this.activate(name === null ? [] : [this.namedSet(name)]);
+    const physics = setPhysicsOption("setSet", options);
+    const ease = setEaseOption("setSet", options);
+    this.activate(name === null ? [] : [this.namedSet(name)], physics, ease);
   }
   /**
    * Makes exactly `names` the active attachment sets (#168), together: each
@@ -9865,43 +9917,84 @@ class RigPlayer {
    * companion). Composition does not depend on the order of `names`. An
    * unknown name, a repeated name or two sets touching one slot throw by name
    * and leave the active sets as they were; `[]` restores the base.
+   *
+   * `options.physics` (#173) decides what a switch that re-poses `drawn` bones
+   * does to the physics constraints hung under them — on a bone whose drawn
+   * rotation this call adds, removes or changes, or on a descendant of one:
+   * `'carry'` moves each one's remembered state (where its bone was and
+   * pointed) by the rigid turn of its deepest re-posed ancestor, so the chain
+   * keeps its pose relative to the bone; `'reset'` restarts each one at the
+   * new pose, as a physics `reset` key does. Absent, the constraints read the
+   * jump as motion and kick, as they always have. Anything else throws before
+   * anything changes. Nothing to do before `play` or when no physics hangs
+   * under a re-posed bone. A later `seek` replays from the start with the sets
+   * then active and does not reproduce a carried switch. `setSet`, `addSet`
+   * and `removeSet` take the same option.
+   *
+   * `options.ease` (#174, seconds, a finite number at or above 0) eases the
+   * bones the call re-poses instead of snapping them. Each bone whose drawn
+   * rotation the call adds, removes or changes turns from what it shows to
+   * its new local rotation along the shorter way, as
+   * `start + shortestΔ(start, end) · smoothstep(elapsed / ease)`: going on,
+   * from the clip's value at the time to the drawn local; going off, from the
+   * drawn local to the clip's value. The attachments the pose draws stay the
+   * previous ones until the frame whose `elapsed / ease` is nearest ½ (the
+   * next step predicted from the current one; a tie goes to the later frame),
+   * then become the call's; `activeSets` and `slotIdentity().sets` name the
+   * call's sets at once, while `slotIdentity().slots` follows what is drawn.
+   * On the frame the elapsed time reaches `ease` the player is in exactly the
+   * instant switch's state. The elapsed time is the player's step
+   * (`dt × timeScale`), so a paused player or a zero step holds the ease;
+   * before `play`, or when no bone's rotation changes, the switch is instant.
+   * A call during an ease eases again from the angles shown (a call without
+   * `ease` lands it at once), and `seek` or a skin change lands it at once.
+   * With `physics: 'carry'` the chains under the eased bones are carried on
+   * every eased frame, by the turn that frame's blend makes; with `'reset'`
+   * they restart once, at the call. `0` or absent is the instant switch on
+   * the same code path; anything else throws by name before anything changes.
    */
-  setSets(names) {
+  setSets(names, options) {
     if (this.setList.length === 0) {
       throw new Error(`cannot setSets(${JSON.stringify(names)}): this model has no sets.json`);
     }
+    const physics = setPhysicsOption("setSets", options);
+    const ease = setEaseOption("setSets", options);
     const sets = names.map((name) => this.namedSet(name));
     for (let i = 0; i < sets.length; i++) {
       for (let j = 0; j < i; j++) {
         if (sets[i] === sets[j]) throw new Error(`set ${JSON.stringify(sets[i].name)} is named twice in setSets`);
       }
     }
-    this.activate(sets);
+    this.activate(sets, physics, ease);
   }
   /**
    * Activates `name` beside the sets already active (#168): a set already
    * active is left as it is; one touching a slot an active set touches throws
    * by name (the slot and both sets) and changes nothing.
    */
-  addSet(name) {
+  addSet(name, options) {
     if (this.setList.length === 0) {
       throw new Error(`cannot addSet(${JSON.stringify(name)}): this model has no sets.json`);
     }
+    const physics = setPhysicsOption("addSet", options);
+    const ease = setEaseOption("addSet", options);
     const found = this.namedSet(name);
     if (this.activeList.includes(found)) return;
-    this.activate([...this.activeList, found]);
+    this.activate([...this.activeList, found], physics, ease);
   }
   /**
    * Deactivates `name`, keeping every other active set (#168). An unknown name
    * throws by name; a set that is not active is left as it is.
    */
-  removeSet(name) {
+  removeSet(name, options) {
     if (this.setList.length === 0) {
       throw new Error(`cannot removeSet(${JSON.stringify(name)}): this model has no sets.json`);
     }
+    const physics = setPhysicsOption("removeSet", options);
+    const ease = setEaseOption("removeSet", options);
     const found = this.namedSet(name);
     if (!this.activeList.includes(found)) return;
-    this.activate(this.activeList.filter((s) => s !== found));
+    this.activate(this.activeList.filter((s) => s !== found), physics, ease);
   }
   /** The declared set named `name`, or a throw naming it and the available sets. */
   namedSet(name) {
@@ -9947,11 +10040,203 @@ class RigPlayer {
     }
     return touched;
   }
+  /**
+   * The physics under the bones a set switch re-poses (#173), before the
+   * repose step: the `changed` bones' rotations went from what the held pose
+   * shows to what the player now applies (`drawnPose`, or an ease's next
+   * blend, #174), and every physics constraint whose bone is one of the
+   * changed bones or a descendant of one is carried or reset. Nothing to do
+   * before `play` (the setup pose carries no physics state) or when no
+   * constraint hangs under a changed bone.
+   */
+  handOverPhysics(changed, mode) {
+    const stepper = this.tracks ?? this.track;
+    if (stepper === null || this.pose === null || this.rawPose === null) return;
+    if (changed.size === 0) return;
+    const parentOf = new Map(this.view.bones.map((b) => [b.name, b.parent]));
+    const anchorOf = (bone2) => {
+      for (let b = bone2; b !== void 0; b = parentOf.get(b)) if (changed.has(b)) return b;
+      return void 0;
+    };
+    const ctx = physicsContextOf(stepper);
+    const affected = [];
+    for (const c of this.view.constraints) {
+      if (c.kind !== "physics") continue;
+      const bone2 = c.record?.bone;
+      const anchor = bone2 === void 0 ? void 0 : anchorOf(bone2);
+      if (anchor === void 0) continue;
+      const state = ctx.states.get(c.name);
+      if (state === void 0 || state.pending) continue;
+      affected.push({ name: c.name, anchor });
+    }
+    if (affected.length === 0) return;
+    if (mode === "reset") {
+      for (const { name } of affected) {
+        const s = ctx.states.get(name);
+        s.remaining = 0;
+        s.lastTime = ctx.time;
+        s.pending = true;
+        s.xOffset = s.xLag = s.xVelocity = 0;
+        s.yOffset = s.yLag = s.yVelocity = 0;
+        s.rotateOffset = s.rotateLag = s.rotateVelocity = 0;
+        s.scaleOffset = s.scaleLag = s.scaleVelocity = 0;
+      }
+      return;
+    }
+    const anchors = new Set(affected.map((a) => a.anchor));
+    const worlds = (pose) => {
+      const out = /* @__PURE__ */ new Map();
+      for (const b of pose.bones) if (anchors.has(b.name)) out.set(b.name, b);
+      return out;
+    };
+    const old = worlds(this.rawPose);
+    const snapshot = captureStepperState(stepper);
+    const now = worlds(stepper.step(0));
+    restoreStepperState(stepper, snapshot);
+    const maps = /* @__PURE__ */ new Map();
+    for (const anchor of anchors) {
+      const o = old.get(anchor);
+      const n = now.get(anchor);
+      if (o === void 0 || n === void 0) continue;
+      if (this.carryPlant) {
+        maps.set(anchor, [1, 0, 0, 1, 0, 0]);
+        continue;
+      }
+      const det = o.a * o.d - o.b * o.c;
+      if (!Number.isFinite(det) || det === 0) continue;
+      const ia = o.d / det;
+      const ib = -o.b / det;
+      const ic = -o.c / det;
+      const id = o.a / det;
+      const a = n.a * ia + n.b * ic;
+      const b = n.a * ib + n.b * id;
+      const c = n.c * ia + n.d * ic;
+      const d = n.c * ib + n.d * id;
+      maps.set(anchor, [a, b, c, d, n.worldX - (a * o.worldX + b * o.worldY), n.worldY - (c * o.worldX + d * o.worldY)]);
+    }
+    const states = physicsContextOf(stepper).states;
+    for (const { name, anchor } of affected) {
+      const m = maps.get(anchor);
+      const s = states.get(name);
+      if (m === void 0 || s === void 0) continue;
+      const [a, b, c, d, x, y] = m;
+      const ux = s.ux;
+      s.ux = a * ux + b * s.uy + x;
+      s.uy = c * ux + d * s.uy + y;
+      const cx = s.cx;
+      s.cx = a * cx + b * s.cy + x;
+      s.cy = c * cx + d * s.cy + y;
+      const tx = s.tx;
+      s.tx = a * tx + b * s.ty;
+      s.ty = c * tx + d * s.ty;
+    }
+  }
+  /**
+   * The composition the held pose draws: `activeSet`, except before an ease's
+   * swap (#174), when it is the composition the ease started from.
+   */
+  shownSet() {
+    const easing = this.easing;
+    return easing === null || easing.swapped ? this.activeSet : easing.fromSet;
+  }
+  /** The local an eased bone shows at the ease's current progress, given the clip's local `clip`. */
+  easedLocal(easing, from, to, clip) {
+    const start = from ?? clip;
+    const end = to ?? clip;
+    const u = easeProgress(easing);
+    const w = this.easePlant === "overshoot" ? u < 1 ? 1.2 * u : 1 : smoothstep(u);
+    return start + normaliseDegrees(end - start) * w;
+  }
+  /**
+   * The ease's part of `adjustHook` (#174): every drawn bone the ease does not
+   * turn takes its drawn local, as without an ease; every eased bone reads
+   * the clip's local (what the timelines left) and then takes its blend.
+   */
+  applyEase(easing, locals) {
+    for (const bone2 of easing.bones.keys()) easing.clip.set(bone2, locals.bone(bone2).rotation);
+    if (this.drawnPose !== null) {
+      for (const [bone2, rotation] of this.drawnPose) if (!easing.bones.has(bone2)) locals.bone(bone2).rotation = rotation;
+    }
+    for (const [bone2, { from, to }] of easing.bones) {
+      locals.bone(bone2).rotation = this.easedLocal(easing, from, to, easing.clip.get(bone2));
+    }
+  }
+  /**
+   * Starts an eased switch (#174) to the sets already made active, from what
+   * the held pose shows: an eased bone's start is the local it shows (fixed),
+   * or the clip's value for a bone that showed the clip's; its end is the new
+   * drawn local, or the clip's value for a bone whose set went. Returns false,
+   * changing nothing, when there is nothing to ease — before `play` (no step
+   * to ease over) or when no bone's rotation changes — and the call is then
+   * an instant one.
+   */
+  startEase(duration, shownBefore, drawn, physics) {
+    const stepper = this.tracks ?? this.track;
+    if (stepper === null || this.pose === null) return false;
+    const before = this.drawnPose;
+    const after = drawn === void 0 ? null : drawnLocals(this.view, drawn);
+    const previous = this.easing;
+    const candidates = drawnChanged(before, after);
+    if (previous !== null) for (const bone2 of previous.bones.keys()) candidates.add(bone2);
+    const bones = /* @__PURE__ */ new Map();
+    for (const bone2 of candidates) {
+      const to = after?.get(bone2) ?? null;
+      let from;
+      const eased = previous?.bones.get(bone2);
+      if (previous !== null && eased !== void 0) {
+        from = previous.elapsed > 0 ? this.easedLocal(previous, eased.from, eased.to, previous.clip.get(bone2)) : eased.from;
+      } else {
+        from = before?.get(bone2) ?? null;
+      }
+      if (from === to) continue;
+      bones.set(bone2, { from, to });
+    }
+    if (bones.size === 0) return false;
+    const easing = {
+      duration,
+      elapsed: 0,
+      bones,
+      clip: /* @__PURE__ */ new Map(),
+      fromSet: shownBefore,
+      swapped: false,
+      physics
+    };
+    if (this.easePlant === "swap-at-0" || this.swapsNow(0, this.lastStep / duration)) easing.swapped = true;
+    this.easing = easing;
+    this.drawnPose = after;
+    if (physics === "reset") this.handOverPhysics(new Set(bones.keys()), "reset");
+    this.reposeDrawn();
+    return true;
+  }
+  /**
+   * Whether the frame at progress `u` is the one nearest ½, the next frame
+   * being at `next`: it is when `u` reached ½ or the next one would be
+   * farther from it; a tie (within 1e-9) goes to the later frame.
+   */
+  swapsNow(u, next) {
+    if (u >= 0.5) return true;
+    return next > u && 0.5 - u < next - 0.5 - 1e-9;
+  }
+  /**
+   * One step of an eased switch (#174), before the track steps: the elapsed
+   * time advances by the step, the attachments swap when this is the frame
+   * nearest ½ (`swapsNow`, the next step predicted by this one), and the
+   * ease ends — the instant switch's state, `drawnPose` alone — on the frame
+   * it reaches its duration. With `physics: 'carry'`, the chains under the
+   * eased bones are carried by the turn this frame's blend makes, read by a
+   * trial `step(0)` at the previous time (`handOverPhysics`).
+   */
+  advanceEase(easing, step) {
+    easing.elapsed += step;
+    if (easing.elapsed >= easing.duration) this.easing = null;
+    else if (!easing.swapped && this.swapsNow(easing.elapsed / easing.duration, (easing.elapsed + step) / easing.duration)) easing.swapped = true;
+    if (easing.physics === "carry") this.handOverPhysics(new Set(easing.bones.keys()), "carry");
+  }
   /**
    * Makes `sets` (distinct) the active sets: refuses any two touching one slot
    * before changing anything, then applies their composition to the held pose.
    */
-  activate(sets) {
+  activate(sets, physics, ease = 0) {
     for (let i = 0; i < sets.length; i++) {
       for (let j = 0; j < i; j++) {
         const other = this.touched(sets[j]);
@@ -9973,12 +10258,27 @@ class RigPlayer {
       }
     }
     const drawnBefore = this.activeSet?.drawn;
+    const shownBefore = this.shownSet();
     this.activeList = this.setList.filter((s) => sets.includes(s));
     this.activeSet = composeSets(this.activeList);
     this.clearSeekCache();
     const drawn = this.activeSet?.drawn;
+    if (ease > 0 && this.startEase(ease, shownBefore, drawn, physics)) return;
+    const easing = this.easing;
+    if (easing !== null) {
+      this.easing = null;
+      const posedBefore = this.drawnPose;
+      this.drawnPose = drawn === void 0 ? null : drawnLocals(this.view, drawn);
+      const changed = drawnChanged(posedBefore, this.drawnPose);
+      for (const bone2 of easing.bones.keys()) changed.add(bone2);
+      if (physics !== void 0) this.handOverPhysics(changed, physics);
+      this.reposeDrawn();
+      return;
+    }
     if (drawn !== drawnBefore && !(drawn === void 0 && drawnBefore === void 0)) {
+      const posedBefore = this.drawnPose;
       this.drawnPose = drawn === void 0 ? null : drawnLocals(this.view, drawn);
+      if (physics !== void 0) this.handOverPhysics(drawnChanged(posedBefore, this.drawnPose), physics);
       this.reposeDrawn();
       return;
     }
@@ -10170,9 +10470,10 @@ class RigPlayer {
     const setupShownSlots = new Set(setupPose.shown.map((s) => s.slot));
     const rawRowBySlot = new Map(raw.slots.map((r) => [r[0], r]));
     const slots = [];
+    const shownSet = this.shownSet();
     for (let z = 0; z < pose.drawOrder.length; z++) {
       const slotName = pose.drawOrder[z];
-      if (this.activeSet !== null && hiddenBySet(slotName, this.activeSet)) {
+      if (shownSet !== null && hiddenBySet(slotName, shownSet)) {
         slots.push(Object.freeze({
           slot: slotName,
           z,
@@ -10207,7 +10508,7 @@ class RigPlayer {
         continue;
       }
       const rawRow = rawRowBySlot.get(slotName);
-      const overriddenBySet = this.activeSet !== null && slotName in this.activeSet.slots;
+      const overriddenBySet = shownSet !== null && slotName in shownSet.slots;
       const setupHadAttachment = setupShownSlots.has(slotName);
       const isTimelineNull = !overriddenBySet && (setupHadAttachment && rawRow?.[1] === null || this.isSlotKeyedNullByTimeline(slotName, raw.animationTime));
       slots.push(Object.freeze({
@@ -10272,6 +10573,7 @@ class RigPlayer {
     this.renderer.dispose();
     this.clearSeekCache();
     this.cachedIdentity = null;
+    this.easing = null;
     this.tracks = null;
     this.track = null;
     this.pose = null;