@lovelace_lol/loom3 1.0.36 → 1.0.37

package/README.md

@@ -1846,6 +1846,7 @@ Loom3 can convert AU/morph curves into AnimationMixer clips for smooth, mixer-on
 Key APIs:
 - `snippetToClip(name, curves, options)` builds an AnimationClip from curves.
 - `playClip(clip, options)` returns a ClipHandle you can pause/resume/stop.
+- `clipHandle.subscribe(listener)` streams lifecycle events from the runtime update loop.
 - `clipHandle.stop()` now resolves cleanly (no rejected promise).
 
 ```typescript
@@ -1856,10 +1857,24 @@ const clip = loom.snippetToClip('gaze', {
 
 if (clip) {
   const handle = loom.playClip(clip, { loop: false, speed: 1 });
+  const unsubscribe = handle?.subscribe?.((event) => {
+    if (event.type === 'keyframe') {
+      console.log(event.currentTime, event.keyframeIndex);
+    }
+  });
+
   await handle.finished;
+  unsubscribe?.();
 }
 ```
 
+Clip stream events are discrete runtime events, not a polling surface:
+
+- `keyframe` fires when playback crosses an authored keyframe.
+- `loop` fires when looping playback starts another iteration.
+- `seek` fires when `setTime()` scrubs the clip.
+- `completed` fires when non-looping playback reaches its terminal state.
+
 ### Playing a snippet directly
 
 If you already have a named snippet object, you can skip manual clip creation:
@@ -2138,7 +2153,7 @@ This is a compact reference for the public surface exported by `@lovelace_lol/lo
 
 ### Types and lower-level exports
 
-- Configuration/types: `Profile`, `MeshInfo`, `BlendingMode`, `TransitionHandle`, `ClipHandle`, `Snippet`, `AnimationState`, `AnimationClipInfo`.
+- Configuration/types: `Profile`, `MeshInfo`, `BlendingMode`, `TransitionHandle`, `ClipEvent`, `ClipEventListener`, `ClipHandle`, `Snippet`, `AnimationState`, `AnimationClipInfo`.
 - Standalone implementations: `AnimationThree`, `HairPhysics`, `BLENDING_MODES`.
 - Region and geometry helpers: `resolveBoneName()`, `resolveBoneNames()`, `resolveFaceCenter()`, `findFaceCenter()`, `getModelForwardDirection()`, `detectFacingDirection()`.
 

package/dist/index.cjs

@@ -291,6 +291,8 @@ var makeActionId = () => `act_${Math.random().toString(36).slice(2, 8)}_${Date.n
 var X_AXIS = new THREE.Vector3(1, 0, 0);
 var Y_AXIS = new THREE.Vector3(0, 1, 0);
 var Z_AXIS = new THREE.Vector3(0, 0, 1);
+var CLIP_EVENT_METADATA_KEY = "__loom3ClipEvents";
+var CLIP_EVENT_EPSILON = 1e-4;
 var BakedAnimationController = class {
   constructor(host) {
     __publicField(this, "host");
@@ -309,6 +311,7 @@ var BakedAnimationController = class {
     __publicField(this, "playbackState", /* @__PURE__ */ new Map());
     __publicField(this, "actionIds", /* @__PURE__ */ new WeakMap());
     __publicField(this, "actionIdToClip", /* @__PURE__ */ new Map());
+    __publicField(this, "clipMonitors", /* @__PURE__ */ new Map());
     this.host = host;
   }
   getActionId(action) {
@@ -322,6 +325,161 @@ var BakedAnimationController = class {
     action.__actionId = actionId;
     return actionId;
   }
+  setClipEventMetadata(clip, metadata) {
+    const userData = clip.userData ?? (clip.userData = {});
+    userData[CLIP_EVENT_METADATA_KEY] = metadata;
+  }
+  getClipEventMetadata(clip) {
+    const userData = clip.userData;
+    const keyframeTimes = Array.isArray(userData?.[CLIP_EVENT_METADATA_KEY]?.keyframeTimes) ? userData[CLIP_EVENT_METADATA_KEY].keyframeTimes.filter((time) => Number.isFinite(time)) : [];
+    return { keyframeTimes };
+  }
+  getKeyframeIndex(times, currentTime) {
+    if (!times.length) return -1;
+    const target = Math.max(0, currentTime) + 1e-3;
+    let lo = 0;
+    let hi = times.length - 1;
+    let idx = 0;
+    while (lo <= hi) {
+      const mid = lo + hi >>> 1;
+      if (times[mid] <= target) {
+        idx = mid;
+        lo = mid + 1;
+      } else {
+        hi = mid - 1;
+      }
+    }
+    return idx;
+  }
+  emitClipEvent(monitor, event) {
+    for (const listener of Array.from(monitor.listeners)) {
+      try {
+        listener(event);
+      } catch (error) {
+        console.error("[Loom3] clip event listener failed", error);
+      }
+    }
+  }
+  emitKeyframesForRange(monitor, startTime, endTime, direction, includeStart) {
+    if (!monitor.keyframeTimes.length) return;
+    const times = direction === 1 ? monitor.keyframeTimes : [...monitor.keyframeTimes].reverse();
+    for (const time of times) {
+      const matchesForward = direction === 1 && (includeStart ? time >= startTime - CLIP_EVENT_EPSILON : time > startTime + CLIP_EVENT_EPSILON) && time <= endTime + CLIP_EVENT_EPSILON;
+      const matchesReverse = direction === -1 && (includeStart ? time <= startTime + CLIP_EVENT_EPSILON : time < startTime - CLIP_EVENT_EPSILON) && time >= endTime - CLIP_EVENT_EPSILON;
+      if (!matchesForward && !matchesReverse) continue;
+      const keyframeIndex = monitor.keyframeTimes.indexOf(time);
+      monitor.lastKeyframeIndex = keyframeIndex;
+      this.emitClipEvent(monitor, {
+        type: "keyframe",
+        clipName: monitor.clipName,
+        keyframeIndex,
+        totalKeyframes: monitor.keyframeTimes.length,
+        currentTime: time,
+        duration: monitor.duration,
+        iteration: monitor.iteration
+      });
+    }
+  }
+  resetClipMonitor(monitor, currentTime) {
+    monitor.iteration = 0;
+    monitor.direction = monitor.initialDirection;
+    monitor.lastTime = currentTime;
+    monitor.lastKeyframeIndex = this.getKeyframeIndex(monitor.keyframeTimes, currentTime);
+    monitor.finishedPending = false;
+  }
+  syncClipMonitorTime(monitor, currentTime, emitSeek = false) {
+    const clamped = Math.max(0, Math.min(monitor.duration, currentTime));
+    monitor.lastTime = clamped;
+    monitor.lastKeyframeIndex = this.getKeyframeIndex(monitor.keyframeTimes, clamped);
+    if (emitSeek) {
+      this.emitClipEvent(monitor, {
+        type: "seek",
+        clipName: monitor.clipName,
+        currentTime: clamped,
+        duration: monitor.duration,
+        iteration: monitor.iteration
+      });
+    }
+  }
+  cleanupClipMonitor(actionId) {
+    const monitor = this.clipMonitors.get(actionId);
+    if (!monitor || monitor.cleanedUp) return;
+    monitor.cleanedUp = true;
+    try {
+      monitor.action.paused = true;
+    } catch {
+    }
+    monitor.resolveFinished();
+    monitor.listeners.clear();
+    this.clipMonitors.delete(actionId);
+    this.actionIdToClip.delete(actionId);
+  }
+  advanceClipMonitor(monitor, previousTime) {
+    if (monitor.cleanedUp || monitor.action.paused && !monitor.finishedPending) return;
+    const currentTime = Math.max(0, Math.min(monitor.duration, monitor.action.time));
+    const delta = currentTime - previousTime;
+    if (monitor.loopMode === "pingpong") {
+      const movingForward = monitor.direction === 1;
+      const bouncedAtEnd = movingForward && delta < -CLIP_EVENT_EPSILON;
+      const bouncedAtStart = !movingForward && delta > CLIP_EVENT_EPSILON;
+      if (bouncedAtEnd) {
+        this.emitKeyframesForRange(monitor, previousTime, monitor.duration, 1, false);
+        monitor.direction = -1;
+        this.emitKeyframesForRange(monitor, monitor.duration, currentTime, -1, false);
+      } else if (bouncedAtStart) {
+        this.emitKeyframesForRange(monitor, previousTime, 0, -1, false);
+        monitor.direction = 1;
+        monitor.iteration += 1;
+        this.emitClipEvent(monitor, {
+          type: "loop",
+          clipName: monitor.clipName,
+          iteration: monitor.iteration,
+          currentTime: 0,
+          duration: monitor.duration
+        });
+        this.emitKeyframesForRange(monitor, 0, currentTime, 1, false);
+      } else if (delta > CLIP_EVENT_EPSILON) {
+        this.emitKeyframesForRange(monitor, previousTime, currentTime, 1, false);
+        monitor.direction = 1;
+      } else if (delta < -CLIP_EVENT_EPSILON) {
+        this.emitKeyframesForRange(monitor, previousTime, currentTime, -1, false);
+        monitor.direction = -1;
+      }
+    } else if (monitor.direction === 1) {
+      const wrapped = currentTime + CLIP_EVENT_EPSILON < previousTime;
+      if (wrapped) {
+        this.emitKeyframesForRange(monitor, previousTime, monitor.duration, 1, false);
+        monitor.iteration += 1;
+        this.emitClipEvent(monitor, {
+          type: "loop",
+          clipName: monitor.clipName,
+          iteration: monitor.iteration,
+          currentTime: 0,
+          duration: monitor.duration
+        });
+        this.emitKeyframesForRange(monitor, 0, currentTime, 1, true);
+      } else if (delta > CLIP_EVENT_EPSILON) {
+        this.emitKeyframesForRange(monitor, previousTime, currentTime, 1, false);
+      }
+    } else {
+      const wrapped = currentTime > previousTime + CLIP_EVENT_EPSILON;
+      if (wrapped) {
+        this.emitKeyframesForRange(monitor, previousTime, 0, -1, false);
+        monitor.iteration += 1;
+        this.emitClipEvent(monitor, {
+          type: "loop",
+          clipName: monitor.clipName,
+          iteration: monitor.iteration,
+          currentTime: monitor.duration,
+          duration: monitor.duration
+        });
+        this.emitKeyframesForRange(monitor, monitor.duration, currentTime, -1, true);
+      } else if (delta < -CLIP_EVENT_EPSILON) {
+        this.emitKeyframesForRange(monitor, previousTime, currentTime, -1, false);
+      }
+    }
+    this.syncClipMonitorTime(monitor, currentTime);
+  }
   normalizePlaybackOptions(options, defaults) {
     const clipOptions = options;
     const rawRate = options?.playbackRate ?? options?.speed ?? 1;
@@ -533,7 +691,28 @@ var BakedAnimationController = class {
   }
   update(dtSeconds) {
     if (this.animationMixer) {
+      const snapshots = Array.from(this.clipMonitors.values()).map((monitor) => ({
+        actionId: monitor.actionId,
+        previousTime: monitor.action.time
+      }));
       this.animationMixer.update(dtSeconds);
+      for (const { actionId, previousTime } of snapshots) {
+        const monitor = this.clipMonitors.get(actionId);
+        if (!monitor) continue;
+        this.advanceClipMonitor(monitor, previousTime);
+        if (monitor.finishedPending) {
+          const finalTime = Math.max(0, Math.min(monitor.duration, monitor.action.time));
+          this.syncClipMonitorTime(monitor, finalTime);
+          this.emitClipEvent(monitor, {
+            type: "completed",
+            clipName: monitor.clipName,
+            currentTime: finalTime,
+            duration: monitor.duration,
+            iteration: monitor.iteration
+          });
+          this.cleanupClipMonitor(actionId);
+        }
+      }
     }
   }
   dispose() {
@@ -553,6 +732,7 @@ var BakedAnimationController = class {
     this.clipHandles.clear();
     this.clipSources.clear();
     this.playbackState.clear();
+    this.clipMonitors.clear();
   }
   loadAnimationClips(clips) {
     const model = this.host.getModel();
@@ -691,6 +871,7 @@ var BakedAnimationController = class {
     }
     const action = this.animationActions.get(clipName);
     if (action) {
+      const actionId = this.getActionId(action);
       const isBaked = (this.clipSources.get(clipName) ?? "baked") === "baked";
       action.stop();
       if (!isBaked && this.animationMixer) {
@@ -713,9 +894,11 @@ var BakedAnimationController = class {
         }
       }
       this.animationFinishedCallbacks.delete(clipName);
+      if (actionId) this.cleanupClipMonitor(actionId);
     }
     const clipAction = this.clipActions.get(clipName);
     if (clipAction && clipAction !== action) {
+      const actionId = this.getActionId(clipAction);
       try {
         clipAction.stop();
         if (this.animationMixer) {
@@ -728,6 +911,7 @@ var BakedAnimationController = class {
       } catch {
       }
       this.clipActions.delete(clipName);
+      if (actionId) this.cleanupClipMonitor(actionId);
     }
     if (this.clipActions.get(clipName) === action) {
       this.clipActions.delete(clipName);
@@ -1289,6 +1473,7 @@ var BakedAnimationController = class {
       return null;
     }
     const clip = new THREE.AnimationClip(clipName, maxTime, tracks);
+    this.setClipEventMetadata(clip, { keyframeTimes });
     console.log(`[Loom3] snippetToClip: Created clip "${clipName}" with ${tracks.length} tracks, duration ${maxTime.toFixed(2)}s`);
     return clip;
   }
@@ -1320,28 +1505,38 @@ var BakedAnimationController = class {
       this.animationClips.push(clip);
     }
     this.applyPlaybackState(action, playbackState);
+    if (actionId) {
+      this.cleanupClipMonitor(actionId);
+    }
     let resolveFinished;
     const finishedPromise = new Promise((resolve) => {
       resolveFinished = resolve;
     });
-    const cleanup = () => {
-      try {
-        this.animationFinishedCallbacks.delete(clip.name);
-      } catch {
-      }
-      try {
-        action.paused = true;
-      } catch {
-      }
+    const keyframeTimes = this.getClipEventMetadata(clip).keyframeTimes;
+    const initialDirection = playbackState.reverse ? -1 : 1;
+    const monitor = {
+      action,
+      actionId,
+      clip,
+      clipName: clip.name,
+      duration: clip.duration,
+      keyframeTimes,
+      listeners: /* @__PURE__ */ new Set(),
+      initialDirection,
+      direction: initialDirection,
+      iteration: 0,
+      lastTime: Math.max(0, Math.min(clip.duration, action.time)),
+      lastKeyframeIndex: this.getKeyframeIndex(keyframeTimes, action.time),
+      loopMode: playbackState.loopMode,
+      finishedPending: false,
+      cleanedUp: false,
+      resolveFinished
     };
-    this.animationFinishedCallbacks.set(clip.name, () => {
-      resolveFinished();
-      cleanup();
-    });
-    finishedPromise.catch(() => cleanup());
+    this.clipMonitors.set(actionId, monitor);
     action.reset();
     action.time = startTime;
     action.play();
+    this.resetClipMonitor(monitor, action.time);
     this.clipActions.set(clip.name, action);
     this.animationActions.set(clip.name, action);
     this.setPlaybackState(clip.name, playbackState);
@@ -1359,6 +1554,7 @@ var BakedAnimationController = class {
           })
         );
         action.play();
+        this.resetClipMonitor(monitor, action.time);
       },
       stop: () => {
         action.stop();
@@ -1376,8 +1572,7 @@ var BakedAnimationController = class {
         this.animationActions.delete(clip.name);
         this.animationFinishedCallbacks.delete(clip.name);
         this.playbackState.delete(clip.name);
-        resolveFinished();
-        cleanup();
+        this.cleanupClipMonitor(actionId);
       },
       pause: () => {
         action.paused = true;
@@ -1395,6 +1590,8 @@ var BakedAnimationController = class {
         const next = this.playbackState.get(clip.name) ?? playbackState;
         next.playbackRate = Number.isFinite(r) ? Math.max(0, Math.abs(r)) : 1;
         this.applyPlaybackState(action, next);
+        monitor.direction = next.reverse ? -1 : 1;
+        monitor.initialDirection = monitor.direction;
         this.setPlaybackState(clip.name, next);
       },
       setLoop: (mode, repeatCount) => {
@@ -1403,6 +1600,7 @@ var BakedAnimationController = class {
         next.loop = mode !== "once";
         next.repeatCount = repeatCount;
         this.applyPlaybackState(action, next);
+        monitor.loopMode = mode;
         this.setPlaybackState(clip.name, next);
       },
       setTime: (t) => {
@@ -1412,9 +1610,16 @@ var BakedAnimationController = class {
           this.animationMixer?.update(0);
         } catch {
         }
+        this.syncClipMonitorTime(monitor, clamped, true);
       },
       getTime: () => action.time,
       getDuration: () => clip.duration,
+      subscribe: (listener) => {
+        monitor.listeners.add(listener);
+        return () => {
+          monitor.listeners.delete(listener);
+        };
+      },
       finished: finishedPromise
     };
     this.clipHandles.set(clip.name, handle);
@@ -1438,6 +1643,7 @@ var BakedAnimationController = class {
     if (!this.animationMixer || !this.host.getModel()) return;
     for (const [clipName, action] of Array.from(this.clipActions.entries())) {
       if (clipName === name || clipName.startsWith(`${name}_`)) {
+        const actionId = this.getActionId(action);
         try {
           action.stop();
           const clip = action.getClip();
@@ -1452,6 +1658,7 @@ var BakedAnimationController = class {
         this.clipHandles.delete(clipName);
         this.animationFinishedCallbacks.delete(clipName);
         this.playbackState.delete(clipName);
+        if (actionId) this.cleanupClipMonitor(actionId);
       }
     }
   }
@@ -1475,6 +1682,8 @@ var BakedAnimationController = class {
     console.log("[Loom3] updateClipParams start", debugSnapshot());
     const apply = (action) => {
       if (!action) return;
+      const actionId = this.getActionId(action);
+      const monitor = actionId ? this.clipMonitors.get(actionId) : void 0;
       const clipName = action.getClip().name;
       const next = this.playbackState.get(clipName) ?? this.normalizePlaybackOptions(void 0, { loop: false, source: this.clipSources.get(clipName) ?? "clip" });
       try {
@@ -1493,6 +1702,10 @@ var BakedAnimationController = class {
         }
         const signedRate = next.reverse ? -next.playbackRate : next.playbackRate;
         action.setEffectiveTimeScale(signedRate);
+        if (monitor) {
+          monitor.direction = next.reverse ? -1 : 1;
+          monitor.initialDirection = monitor.direction;
+        }
         updated = true;
       }
       if (typeof params.loop === "boolean" || params.loopMode || params.repeatCount !== void 0) {
@@ -1500,6 +1713,7 @@ var BakedAnimationController = class {
         next.loop = next.loopMode !== "once";
         next.repeatCount = params.repeatCount;
         this.applyPlaybackState(action, next);
+        if (monitor) monitor.loopMode = next.loopMode;
         updated = true;
       }
       this.setPlaybackState(clipName, next);
@@ -1579,6 +1793,14 @@ var BakedAnimationController = class {
     if (this.animationMixer && !this.mixerFinishedListenerAttached) {
       this.animationMixer.addEventListener("finished", (event) => {
         const action = event.action;
+        const actionId = this.getActionId(action);
+        if (actionId) {
+          const monitor = this.clipMonitors.get(actionId);
+          if (monitor) {
+            monitor.finishedPending = true;
+            return;
+          }
+        }
         const clip = action.getClip();
         const bakedRuntime = this.bakedRuntimeClipToSource.get(clip.name);
         if (bakedRuntime) {
@@ -4285,9 +4507,11 @@ function getPreset(presetType) {
       return CC4_PRESET;
   }
 }
+var resolvePreset = getPreset;
 function getPresetWithProfile(presetType, profile) {
   return extendPresetWithProfile(getPreset(presetType), profile);
 }
+var resolvePresetWithOverrides = getPresetWithProfile;
 
 // src/engines/three/Loom3.ts
 var deg2rad = (d) => d * Math.PI / 180;
@@ -7443,6 +7667,8 @@ exports.mergeCharacterRegionsByName = mergeRegionsByName;
 exports.resolveBoneName = resolveBoneName;
 exports.resolveBoneNames = resolveBoneNames;
 exports.resolveFaceCenter = resolveFaceCenter;
+exports.resolvePreset = resolvePreset;
+exports.resolvePresetWithOverrides = resolvePresetWithOverrides;
 exports.suggestBestPreset = suggestBestPreset;
 exports.validateMappingConfig = validateMappingConfig;
 exports.validateMappings = validateMappings;