spine-html 1.11.1 → 1.12.0

package/README.md

@@ -520,6 +520,52 @@ active (`null`), track evaluation runs with zero extra work and produces
 byte-identical poses. An unknown set name throws by name; on a build without
 `sets.json`, `sets()` is empty (`[]`) and `setSet` throws.
 
+### Slot identity snapshot (`slotIdentity()`)
+
+To inspect which attachment key, owning skin and visibility state each slot
+holds on the current frame — for a parts explorer or review overlay — without
+`seek`, `repose`, or restarting physics (#144):
+
+```ts
+const snap = player.slotIdentity();
+// {
+//   generation: number,              // matches player.generation and player.posedFrame().generation
+//   set: string | null,              // active set name (player.set)
+//   skin: string | null,             // active skin name (player.skin ?? null)
+//   slots: readonly [                // every slot in posed draw order (z = 0 .. slots.length - 1)
+//     {
+//       slot: string,
+//       z: number,
+//       attachment: string | null,   // resolved attachment key when drawn, null when not drawn
+//       skin: string | null,         // skin owning the resolved attachment ('default' or named skin), or null
+//       reason: 'hidden' | 'no-attachment' | 'timeline-null' | 'set-hide' | null,
+//     },
+//     ...
+//   ],
+// }
+```
+
+Every slot in the posed draw order (`z = 0 .. slots.length - 1`, hidden and null
+ones included) appears in `snap.slots`:
+
+- Drawn slots (`reason: null`) appear in the same `z` order as
+  `player.posedFrame().order`, naming the resolved attachment key (`attachment`)
+  and the skin that owns it (`skin`).
+- Non-drawn slots report `attachment: null`, `skin: null`, and why they are
+  absent from `posedFrame().order`:
+  - `'set-hide'` — hidden by the active attachment set (`set.hides` or a
+    `<base>_still` companion of a slot the set covers or hides).
+  - `'timeline-null'` — cleared by an active attachment timeline key (`null`).
+  - `'no-attachment'` — no attachment in the setup pose or under the active skin
+    (or a non-drawable attachment kind such as clipping/boundingbox/path/point).
+  - `'hidden'` — filtered out by `player.slots` or on an inactive bone under the
+    current skin.
+- `snap.generation` ticks monotonically with `player.generation` and
+  `player.posedFrame().generation` whenever the held pose, active set, active
+  skin or slot filter changes. The returned snapshot is frozen and cached per
+  generation, so reading it repeatedly on a held pose is allocation-free and
+  mutates no pixel or physics state.
+
 ### Several tracks
 
 A base on track 0, a layer over it, a one-shot played once and mixed back out —

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, type RegionLoading, type RigSet } from './loadModel.js';
-export { type AdjustableBones, type BoneAdjust, type BoneLocals, type BoneWorld, type PlayOptions, type PoseBounds, type QueueOptions, type RenderMode, type RigComplete, type RigEnvironment, type RigEvent, RigPlayer, type RigPlayerOptions, type SlotFilter, type TrackEntry } from './player.js';
+export { type AdjustableBones, type BoneAdjust, type BoneLocals, type BoneWorld, type PlayOptions, type PoseBounds, type QueueOptions, type RenderMode, type RigComplete, type RigEnvironment, type RigEvent, RigPlayer, type RigPlayerOptions, type SlotFilter, type 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,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACzI,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,QAAQ,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AACtS,YAAY,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,SAAS,EACT,WAAW,EACX,SAAS,GACV,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC9F,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACtF,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,KAAK,WAAW,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACnK,OAAO,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACzI,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,QAAQ,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,kBAAkB,EAAE,KAAK,oBAAoB,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAC7W,YAAY,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,SAAS,EACT,WAAW,EACX,SAAS,GACV,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -8699,9 +8699,16 @@ function predicateOf(names) {
   const allowed = new Set(names);
   return (slot) => allowed.has(slot);
 }
+function hiddenBySet(slotName, set) {
+  if (set.hides.includes(slotName)) return true;
+  if (slotName.endsWith("_still") && !(slotName in set.slots)) {
+    const base = slotName.slice(0, -"_still".length);
+    if (base in set.slots || set.hides.includes(base)) return true;
+  }
+  return false;
+}
 function applySetToPose(view, raw, set) {
   const coveredNames = new Set(Object.keys(set.slots));
-  const hiddenNames = new Set(set.hides);
   const overrideSlots = view.slots.flatMap((slot) => {
     const setup = set.slots[slot.name];
     return setup !== void 0 ? [{ ...slot, setup }] : [];
@@ -8729,14 +8736,7 @@ function applySetToPose(view, raw, set) {
   const rawShownBySlot = new Map(raw.shown.map((s) => [s.slot, s]));
   const rawDrawnBySlot = new Map(raw.drawn.map((d) => [d.slot, d]));
   const rawClipBySlot = new Map(raw.clips.map((c) => [c[0], c]));
-  const hiddenSlot = (slotName) => {
-    if (hiddenNames.has(slotName)) return true;
-    if (slotName.endsWith("_still") && !coveredNames.has(slotName)) {
-      const base = slotName.slice(0, -"_still".length);
-      if (coveredNames.has(base) || hiddenNames.has(base)) return true;
-    }
-    return false;
-  };
+  const hiddenSlot = (slotName) => hiddenBySet(slotName, set);
   const slots = raw.slots.map((rawRow) => {
     const slotName = rawRow[0];
     if (hiddenSlot(slotName)) {
@@ -8777,6 +8777,116 @@ function applySetToPose(view, raw, set) {
     clips
   };
 }
+const SEEK_FINE_STEP_LIMIT = 4096;
+const SEEK_COARSE_STRIDE = 8;
+const SEEK_EXACT_LIMIT = 1024;
+function capturePhysicsContext(ctx) {
+  const states = /* @__PURE__ */ new Map();
+  for (const [name, s] of ctx.states) states.set(name, { ...s });
+  return {
+    phase: ctx.phase,
+    time: ctx.time,
+    last: ctx.last,
+    loop: ctx.loop,
+    env: ctx.env,
+    states
+  };
+}
+function restorePhysicsContext(ctx, snap) {
+  ctx.phase = snap.phase;
+  ctx.time = snap.time;
+  ctx.last = snap.last;
+  if (snap.loop === void 0) delete ctx.loop;
+  else ctx.loop = snap.loop;
+  if (snap.env === void 0) delete ctx.env;
+  else ctx.env = snap.env;
+  ctx.states.clear();
+  for (const [name, s] of snap.states) ctx.states.set(name, { ...s });
+}
+function captureStepperState(stepper) {
+  if ("first" in stepper) {
+    const internal2 = stepper;
+    return {
+      kind: "track",
+      steps: internal2.steps,
+      latest: internal2.latest,
+      refused: internal2.refused,
+      trackTime: internal2.track.trackTime,
+      last: internal2.track.last,
+      ctx: capturePhysicsContext(internal2.track.ctx)
+    };
+  }
+  const internal = stepper;
+  const entry = internal.mixer.tracks[0] ?? null;
+  return {
+    kind: "tracks",
+    started: internal.started,
+    steps: internal.steps,
+    time: internal.time,
+    refused: internal.refused,
+    animationsChanged: internal.mixer.animationsChanged,
+    propertyIds: new Map(internal.mixer.propertyIds),
+    entry: entry === null ? null : {
+      delay: entry.delay,
+      trackTime: entry.trackTime,
+      trackLast: entry.trackLast,
+      nextTrackLast: entry.nextTrackLast,
+      trackEnd: entry.trackEnd,
+      animationLast: entry.animationLast,
+      nextAnimationLast: entry.nextAnimationLast,
+      mixTime: entry.mixTime,
+      mixDuration: entry.mixDuration,
+      totalAlpha: entry.totalAlpha,
+      alpha: entry.alpha,
+      additive: entry.additive,
+      keepHold: entry.keepHold,
+      timelineMode: [...entry.timelineMode],
+      timelineHoldMix: [...entry.timelineHoldMix],
+      timelinesRotation: [...entry.timelinesRotation]
+    },
+    ctx: capturePhysicsContext(internal.path.ctx)
+  };
+}
+function restoreStepperState(stepper, snap) {
+  if (snap.kind === "track") {
+    const internal2 = stepper;
+    internal2.steps = snap.steps;
+    internal2.latest = snap.latest;
+    internal2.refused = snap.refused;
+    internal2.track.trackTime = snap.trackTime;
+    internal2.track.last = snap.last;
+    restorePhysicsContext(internal2.track.ctx, snap.ctx);
+    return;
+  }
+  const internal = stepper;
+  internal.started = snap.started;
+  internal.steps = snap.steps;
+  internal.time = snap.time;
+  internal.refused = snap.refused;
+  internal.mixer.animationsChanged = snap.animationsChanged;
+  internal.mixer.propertyIds.clear();
+  for (const [k, v] of snap.propertyIds) internal.mixer.propertyIds.set(k, v);
+  const entry = internal.mixer.tracks[0] ?? null;
+  if (entry !== null && snap.entry !== null) {
+    entry.delay = snap.entry.delay;
+    entry.trackTime = snap.entry.trackTime;
+    entry.trackLast = snap.entry.trackLast;
+    entry.nextTrackLast = snap.entry.nextTrackLast;
+    entry.trackEnd = snap.entry.trackEnd;
+    entry.animationLast = snap.entry.animationLast;
+    entry.nextAnimationLast = snap.entry.nextAnimationLast;
+    entry.mixTime = snap.entry.mixTime;
+    entry.mixDuration = snap.entry.mixDuration;
+    entry.totalAlpha = snap.entry.totalAlpha;
+    entry.alpha = snap.entry.alpha;
+    entry.additive = snap.entry.additive;
+    entry.keepHold = snap.entry.keepHold;
+    entry.timelineMode = [...snap.entry.timelineMode];
+    entry.timelineHoldMix = [...snap.entry.timelineHoldMix];
+    entry.timelinesRotation = [...snap.entry.timelinesRotation];
+  }
+  restorePhysicsContext(internal.path.ctx, snap.ctx);
+}
 class RigPlayer {
   /**
    * The renderer this player draws through — its knobs and counters are the
@@ -8831,6 +8941,10 @@ class RigPlayer {
   /** The un-overridden pose from the track/tracks (or setup pose when `setSet` is called before `play`). */
   rawPose = null;
   setup = null;
+  seekCache = null;
+  poseGeneration = 0;
+  cachedIdentity = null;
+  cachedIdentityGen = -1;
   setList;
   setsByName;
   activeSet = null;
@@ -8862,6 +8976,8 @@ class RigPlayer {
     this.meshBackend = options.meshBackend;
     this.adjustFn = options.adjust ?? null;
     if (options.slots !== void 0 && options.slots !== null) this.slots = options.slots;
+    this.poseGeneration = 0;
+    this.cachedIdentity = null;
     this.active = this.create(options.mode ?? "dom");
   }
   /**
@@ -8928,6 +9044,7 @@ class RigPlayer {
     const alpha = options.alpha ?? 1;
     const additive = options.additive ?? false;
     this.paused = false;
+    this.clearSeekCache();
     const plain = track === 0 && mix === 0 && alpha === 1 && !additive;
     if (!plain) this.beyondBase = true;
     if (this.tracks === null && plain && !this.trackMode) {
@@ -8956,6 +9073,7 @@ class RigPlayer {
   queue(name, options = {}) {
     const track = options.track ?? 0;
     this.beyondBase = true;
+    this.clearSeekCache();
     const tracks = this.compose();
     tracks.addAnimation(track, name, { loop: options.loop ?? true, mixDuration: options.mix ?? 0, delay: options.delay ?? 0, alpha: options.alpha ?? 1, additive: options.additive ?? false });
     this.trackCount = Math.max(this.trackCount, track + 1);
@@ -8968,6 +9086,7 @@ class RigPlayer {
    */
   clear(track = 0, options = {}) {
     this.beyondBase = true;
+    this.clearSeekCache();
     const tracks = this.compose();
     tracks.setEmptyAnimation(track, options.mix ?? 0);
     this.trackCount = Math.max(this.trackCount, track + 1);
@@ -8981,6 +9100,7 @@ class RigPlayer {
    */
   queueClear(track = 0, options = {}) {
     this.beyondBase = true;
+    this.clearSeekCache();
     const tracks = this.compose();
     tracks.addEmptyAnimation(track, options.mix ?? 0, options.delay ?? 0);
     this.trackCount = Math.max(this.trackCount, track + 1);
@@ -8995,6 +9115,7 @@ class RigPlayer {
    */
   setAlpha(track, alpha) {
     this.beyondBase = true;
+    this.clearSeekCache();
     const tracks = this.compose();
     tracks.setAlpha(track, alpha);
     this.setRawPose(tracks.step(0));
@@ -9025,6 +9146,7 @@ class RigPlayer {
    */
   compose() {
     if (this.tracks !== null) return this.tracks;
+    this.clearSeekCache();
     const tracks = openTracks(this.view, { reset: "animation", adjust: this.adjustHook, clock: physicsClockStep });
     const single = this.track;
     const time = single?.trackTime ?? 0;
@@ -9043,6 +9165,8 @@ class RigPlayer {
   setRawPose(raw) {
     this.rawPose = raw;
     this.pose = this.activeSet === null ? raw : applySetToPose(this.view, raw, this.activeSet);
+    this.poseGeneration++;
+    this.cachedIdentity = null;
   }
   /**
    * The world the rig's physics answers (#121): `wind` and `gravity`, as
@@ -9061,8 +9185,10 @@ class RigPlayer {
   environment(environment) {
     if (environment === null) {
       this.env = null;
+      this.clearSeekCache();
       this.stepper()?.setEnvironment(DEFAULT_ENVIRONMENT);
     } else if (environment !== void 0) {
+      this.clearSeekCache();
       const live = this.stepper();
       if (live) {
         live.setEnvironment(environment);
@@ -9101,20 +9227,101 @@ class RigPlayer {
     this.paused = false;
   }
   /**
-   * Moves a single animation on track 0 to `time`: the tracks are reopened
-   * with that animation and stepped forward in `seekStep` increments (the
-   * last one shorter) until the time is reached. Events and completes crossed
-   * on the way are not fired. It has a meaning for one animation on one
-   * track only — the player cannot replay when a mix, a second track or a
-   * queue was asked for — so after any of those it refuses by name; step the
-   * player forward instead.
+   * Moves a single animation on track 0 to `time`: snapshot-backed deterministic
+   * seek (#141) that produces the exact pose and physics state of reopening at 0
+   * and stepping forward in `seekStep` increments (the last one shorter) until
+   * `time` is reached. Events and completes crossed on the way are not fired.
+   * It has a meaning for one animation on one track only — the player cannot
+   * replay when a mix, a second track or a queue was asked for — so after any
+   * of those it refuses by name; step the player forward instead.
    */
   seek(time) {
     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.reopen();
-    this.stepTo(time);
+    const cache = this.ensureSeekCache();
+    const stepper = this.tracks ?? this.track;
+    const exactHit = cache.exact.get(time);
+    if (exactHit !== void 0) {
+      restoreStepperState(stepper, exactHit.state);
+      this.rawPose = exactHit.rawPose;
+      this.pose = exactHit.pose;
+      this.poseGeneration++;
+      this.cachedIdentity = null;
+      return;
+    }
+    const steps = Math.floor(time / this.seekStep);
+    while (cache.frontierSteps < steps) {
+      const raw = cache.frontier.step(this.seekStep);
+      cache.frontierSteps++;
+      if (cache.frontierSteps <= SEEK_FINE_STEP_LIMIT || cache.frontierSteps % SEEK_COARSE_STRIDE === 0) {
+        cache.grid.set(cache.frontierSteps, {
+          state: captureStepperState(cache.frontier),
+          rawPose: raw
+        });
+      }
+    }
+    const gridHit = cache.grid.get(steps);
+    if (gridHit !== void 0) {
+      restoreStepperState(stepper, gridHit.state);
+      this.rawPose = gridHit.rawPose;
+    } else {
+      const baseStep = steps - steps % SEEK_COARSE_STRIDE;
+      const baseSnap = cache.grid.get(baseStep);
+      restoreStepperState(stepper, baseSnap.state);
+      this.rawPose = baseSnap.rawPose;
+      for (let i = baseStep; i < steps; i++) this.rawPose = stepper.step(this.seekStep);
+    }
+    const rest = time - stepper.trackTime;
+    if (rest > 0) this.rawPose = stepper.step(rest);
+    if (this.rawPose !== null) this.setRawPose(this.rawPose);
+    if (this.rawPose !== null && this.pose !== null) {
+      if (cache.exact.size >= SEEK_EXACT_LIMIT) {
+        const oldest = cache.exact.keys().next().value;
+        if (oldest !== void 0) cache.exact.delete(oldest);
+      }
+      cache.exact.set(time, {
+        state: captureStepperState(stepper),
+        rawPose: this.rawPose,
+        pose: this.pose
+      });
+    }
+  }
+  clearSeekCache() {
+    this.seekCache = null;
+  }
+  ensureSeekCache() {
+    const mode = this.tracks !== null ? "tracks" : "track";
+    if (this.seekCache !== null && this.seekCache.mode === mode) {
+      return this.seekCache;
+    }
+    if (this.tracks === null && this.track === null) {
+      this.reopen();
+    }
+    let frontier;
+    let firstPose;
+    if (mode === "tracks") {
+      const tracks = openTracks(this.view, { reset: "animation", adjust: this.adjustHook, clock: physicsClockStep });
+      tracks.setAnimation(0, this.animation, { loop: this.loop, mixDuration: 0 });
+      firstPose = tracks.start();
+      this.applyEnvironment(tracks);
+      frontier = tracks;
+    } else {
+      const track = openTrack(this.view, this.animation, { loop: this.loop, reset: "animation", adjust: this.adjustHook, clock: physicsClockStep });
+      firstPose = track.first;
+      this.applyEnvironment(track);
+      frontier = track;
+    }
+    const grid = /* @__PURE__ */ new Map();
+    grid.set(0, { state: captureStepperState(frontier), rawPose: firstPose });
+    this.seekCache = {
+      mode,
+      frontier,
+      frontierSteps: 0,
+      grid,
+      exact: /* @__PURE__ */ new Map()
+    };
+    return this.seekCache;
   }
   /** Whatever is open, opened again with track 0's animation as `play` last set it, at pose 0: the single track, or the tracks under `tracks: true`. */
   reopen() {
@@ -9217,6 +9424,7 @@ class RigPlayer {
     this.source = frameSource(view, this.read.parsed);
     this.skinName = name;
     this.setup = null;
+    this.clearSeekCache();
     if (this.animation !== null && (this.track !== null || this.tracks !== null)) {
       const time = this.time;
       this.reopen();
@@ -9224,6 +9432,9 @@ class RigPlayer {
     } else if (this.rawPose !== null) {
       this.setup = poseRawSetup(this.view);
       this.setRawPose(this.setup);
+    } else {
+      this.poseGeneration++;
+      this.cachedIdentity = null;
     }
   }
   /**
@@ -9259,9 +9470,12 @@ class RigPlayer {
     }
     if (name === null) {
       this.activeSet = null;
+      this.clearSeekCache();
       const base2 = this.rawPose ?? (this.setup ?? (this.setup = poseRawSetup(this.view)));
       this.rawPose = base2;
       this.pose = base2;
+      this.poseGeneration++;
+      this.cachedIdentity = null;
       return;
     }
     const found = this.setsByName.get(name);
@@ -9271,9 +9485,12 @@ class RigPlayer {
       );
     }
     this.activeSet = found;
+    this.clearSeekCache();
     const base = this.rawPose ?? (this.setup ?? (this.setup = poseRawSetup(this.view)));
     this.rawPose = base;
     this.pose = applySetToPose(this.view, base, found);
+    this.poseGeneration++;
+    this.cachedIdentity = null;
   }
   /**
    * Which slots this player draws (`SlotFilter`), or null for every slot.
@@ -9289,11 +9506,15 @@ class RigPlayer {
     if (filter === null) {
       this.slotFilter = null;
       this.draws = () => true;
+      this.poseGeneration++;
+      this.cachedIdentity = null;
       return;
     }
     if (typeof filter === "function") {
       this.slotFilter = filter;
       this.draws = filter;
+      this.poseGeneration++;
+      this.cachedIdentity = null;
       return;
     }
     if (!Array.isArray(filter)) throw new Error(`slots must be an array of slot names, a function, or null, got ${typeof filter}`);
@@ -9305,6 +9526,8 @@ class RigPlayer {
     const allowed = new Set(filter);
     this.slotFilter = [...filter];
     this.draws = (slot) => allowed.has(slot);
+    this.poseGeneration++;
+    this.cachedIdentity = null;
   }
   /**
    * The per-pose adjustment of bone locals (`BoneAdjust`), or null for none.
@@ -9320,6 +9543,7 @@ class RigPlayer {
   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.clearSeekCache();
     this.repose();
   }
   /**
@@ -9330,6 +9554,7 @@ class RigPlayer {
    * changed, then `draw`. Nothing before `play`.
    */
   repose() {
+    this.clearSeekCache();
     const stepper = this.tracks ?? this.track;
     if (stepper === null || this.pose === null) return;
     this.setRawPose(stepper.step(0));
@@ -9407,6 +9632,10 @@ class RigPlayer {
     if (this.setup === null) this.setup = poseRawSetup(this.view);
     return this.activeSet === null ? this.setup : applySetToPose(this.view, this.setup, this.activeSet);
   }
+  /** Monotonic pose generation counter matching `posedFrame().generation` and `slotIdentity().generation`. */
+  get generation() {
+    return this.poseGeneration;
+  }
   /**
    * The pose the player holds, as the frame record the renderer draws — under
    * this player's `slots` filter, or under `slots` given here instead (a
@@ -9415,13 +9644,137 @@ class RigPlayer {
    * posed once).
    */
   posedFrame(slots) {
-    if (this.pose === null) return { order: [] };
     const draws = slots === void 0 ? this.draws : slots === null ? () => true : typeof slots === "function" ? slots : predicateOf(slots);
-    return frameOf(this.source, this.pose, this.color, draws);
+    const frame2 = this.pose === null ? { order: [] } : frameOf(this.source, this.pose, this.color, draws);
+    Object.defineProperty(frame2, "generation", {
+      value: this.poseGeneration,
+      enumerable: false,
+      configurable: true
+    });
+    return frame2;
+  }
+  /**
+   * A read-only slot identity snapshot coherent with `posedFrame()` (#144):
+   * for every slot in the posed draw order (`z = 0 .. slots.length - 1`, hidden
+   * and null slots included), its resolved attachment key (`string | null`),
+   * the skin that owns that attachment (`string | null`), and `reason` (`null`
+   * when drawn in `posedFrame().order`, or `'hidden' | 'no-attachment' | 'timeline-null' | 'set-hide'`
+   * when not drawn), together with the active `set`, active `skin`, and frame
+   * `generation`. Read off the held pose without `seek`, `repose`, or physics
+   * restart.
+   */
+  slotIdentity() {
+    if (this.cachedIdentity !== null && this.cachedIdentityGen === this.poseGeneration) {
+      return this.cachedIdentity;
+    }
+    const setupPose = this.setup ?? (this.setup = poseRawSetup(this.view));
+    const pose = this.posed();
+    const raw = this.rawPose ?? setupPose;
+    const shownBySlot = new Map(pose.shown.map((s) => [s.slot, s]));
+    const setupShownSlots = new Set(setupPose.shown.map((s) => s.slot));
+    const rawRowBySlot = new Map(raw.slots.map((r) => [r[0], r]));
+    const slots = [];
+    for (let z = 0; z < pose.drawOrder.length; z++) {
+      const slotName = pose.drawOrder[z];
+      if (this.activeSet !== null && hiddenBySet(slotName, this.activeSet)) {
+        slots.push(Object.freeze({
+          slot: slotName,
+          z,
+          attachment: null,
+          skin: null,
+          reason: "set-hide"
+        }));
+        continue;
+      }
+      const shown = shownBySlot.get(slotName);
+      const isDrawableKind = shown !== void 0 && (shown.geometry.kind === "region" || shown.geometry.kind === "mesh" || shown.geometry.kind === "linkedmesh");
+      if (shown !== void 0 && isDrawableKind) {
+        const bone2 = this.source.boneOf.get(slotName);
+        const boneActive = bone2 !== void 0 && this.source.active.has(bone2);
+        if (this.draws(slotName) && boneActive) {
+          slots.push(Object.freeze({
+            slot: slotName,
+            z,
+            attachment: shown.name,
+            skin: shown.skin,
+            reason: null
+          }));
+        } else {
+          slots.push(Object.freeze({
+            slot: slotName,
+            z,
+            attachment: null,
+            skin: null,
+            reason: "hidden"
+          }));
+        }
+        continue;
+      }
+      const rawRow = rawRowBySlot.get(slotName);
+      const overriddenBySet = this.activeSet !== null && slotName in this.activeSet.slots;
+      const setupHadAttachment = setupShownSlots.has(slotName);
+      const isTimelineNull = !overriddenBySet && (setupHadAttachment && rawRow?.[1] === null || this.isSlotKeyedNullByTimeline(slotName, raw.animationTime));
+      slots.push(Object.freeze({
+        slot: slotName,
+        z,
+        attachment: null,
+        skin: null,
+        reason: isTimelineNull ? "timeline-null" : "no-attachment"
+      }));
+    }
+    const snapshot = Object.freeze({
+      generation: this.poseGeneration,
+      set: this.activeSet?.name ?? null,
+      skin: this.skinName ?? null,
+      slots: Object.freeze(slots)
+    });
+    this.cachedIdentity = snapshot;
+    this.cachedIdentityGen = this.poseGeneration;
+    return snapshot;
+  }
+  /** Whether an active animation's attachment timeline explicitly keyed `null` on `slotName` at `animationTime`. */
+  isSlotKeyedNullByTimeline(slotName, animationTime) {
+    const checkAnimation = (animName, time) => {
+      if (animName === null) return void 0;
+      const anim = this.view.animations.find((a) => a.name === animName);
+      if (anim === void 0) return void 0;
+      const target = anim.timelines.slots.find((s) => s.name === slotName);
+      if (target === void 0) return void 0;
+      let keyed;
+      for (const tl of target.timelines) {
+        if (tl.kind !== "attachment") continue;
+        let activeKey = null;
+        for (const k of tl.keys) {
+          if (k.time <= time) activeKey = k;
+          else break;
+        }
+        if (activeKey !== null) {
+          keyed = activeKey.name === null || activeKey.name === void 0;
+        }
+      }
+      return keyed;
+    };
+    if (this.tracks !== null) {
+      let result = false;
+      for (let t = 0; t < this.trackCount; t++) {
+        const cur = this.tracks.current(t);
+        if (cur !== null && cur.animation !== null) {
+          const k = checkAnimation(cur.animation, cur.animationTime);
+          if (k !== void 0) result = k;
+        }
+      }
+      return result;
+    }
+    if (this.track !== null && this.animation !== null) {
+      return checkAnimation(this.animation, animationTime) === true;
+    }
+    return false;
   }
   /** Removes the renderer's elements and hands its GPU pages back. The assets stay the caller's. */
   dispose() {
     this.renderer.dispose();
+    this.clearSeekCache();
+    this.cachedIdentity = null;
     this.tracks = null;
     this.track = null;
     this.pose = null;