spine-html 1.11.2 → 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)) {
@@ -8942,6 +8942,9 @@ class RigPlayer {
   rawPose = null;
   setup = null;
   seekCache = null;
+  poseGeneration = 0;
+  cachedIdentity = null;
+  cachedIdentityGen = -1;
   setList;
   setsByName;
   activeSet = null;
@@ -8973,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");
   }
   /**
@@ -9160,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
@@ -9239,6 +9246,8 @@ class RigPlayer {
       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);
@@ -9423,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;
     }
   }
   /**
@@ -9462,6 +9474,8 @@ class RigPlayer {
       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);
@@ -9475,6 +9489,8 @@ class RigPlayer {
     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.
@@ -9490,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}`);
@@ -9506,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.
@@ -9610,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
@@ -9618,14 +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;