@lovelace_lol/loom3 1.0.36 → 1.0.38

package/dist/index.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var THREE = require('three');
+var THREE2 = require('three');
 
 function _interopNamespace(e) {
   if (e && e.__esModule) return e;
@@ -20,7 +20,7 @@ function _interopNamespace(e) {
   return Object.freeze(n);
 }
 
-var THREE__namespace = /*#__PURE__*/_interopNamespace(THREE);
+var THREE2__namespace = /*#__PURE__*/_interopNamespace(THREE2);
 
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
@@ -90,12 +90,12 @@ function getRuntimeClipName(sourceClipName, channel) {
 function parseTrackTarget(trackName, model) {
   let parsed;
   try {
-    parsed = THREE.PropertyBinding.parseTrackName(trackName);
+    parsed = THREE2.PropertyBinding.parseTrackName(trackName);
   } catch {
     return null;
   }
   const targetKey = parsed.objectName === "bones" && parsed.objectIndex ? String(parsed.objectIndex) : parsed.nodeName;
-  const target = targetKey ? model.getObjectByProperty("uuid", targetKey) ?? THREE.PropertyBinding.findNode(model, targetKey) : null;
+  const target = targetKey ? model.getObjectByProperty("uuid", targetKey) ?? THREE2.PropertyBinding.findNode(model, targetKey) : null;
   return {
     propertyName: parsed.propertyName,
     target,
@@ -183,7 +183,7 @@ function partitionBakedClip(clip, model, bones) {
     }
     runtimeClips.push({
       channel,
-      clip: new THREE.AnimationClip(getRuntimeClipName(clip.name, channel), clip.duration, tracks)
+      clip: new THREE2.AnimationClip(getRuntimeClipName(clip.name, channel), clip.duration, tracks)
     });
   }
   return {
@@ -288,9 +288,11 @@ var AnimationThree = class {
   }
 };
 var makeActionId = () => `act_${Math.random().toString(36).slice(2, 8)}_${Date.now().toString(36)}`;
-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 X_AXIS = new THREE2.Vector3(1, 0, 0);
+var Y_AXIS = new THREE2.Vector3(0, 1, 0);
+var Z_AXIS = new THREE2.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;
@@ -348,14 +506,14 @@ var BakedAnimationController = class {
     const signedRate = state.reverse ? -state.playbackRate : state.playbackRate;
     action.setEffectiveTimeScale(signedRate);
     action.setEffectiveWeight(state.weight);
-    action.blendMode = state.blendMode === "additive" ? THREE.AdditiveAnimationBlendMode : THREE.NormalAnimationBlendMode;
+    action.blendMode = state.blendMode === "additive" ? THREE2.AdditiveAnimationBlendMode : THREE2.NormalAnimationBlendMode;
     const reps = state.repeatCount ?? Infinity;
     if (state.loopMode === "pingpong") {
-      action.setLoop(THREE.LoopPingPong, reps);
+      action.setLoop(THREE2.LoopPingPong, reps);
     } else if (state.loopMode === "once") {
-      action.setLoop(THREE.LoopOnce, 1);
+      action.setLoop(THREE2.LoopOnce, 1);
     } else {
-      action.setLoop(THREE.LoopRepeat, reps);
+      action.setLoop(THREE2.LoopRepeat, reps);
     }
     action.clampWhenFinished = state.loopMode === "once";
   }
@@ -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);
@@ -974,7 +1158,7 @@ var BakedAnimationController = class {
       if (!state2 && !action2) {
         return null;
       }
-      const loopMode2 = state2?.loopMode ?? (action2?.loop === THREE.LoopPingPong ? "pingpong" : action2?.loop === THREE.LoopOnce ? "once" : "repeat");
+      const loopMode2 = state2?.loopMode ?? (action2?.loop === THREE2.LoopPingPong ? "pingpong" : action2?.loop === THREE2.LoopOnce ? "once" : "repeat");
       const playbackRate2 = state2?.playbackRate ?? Math.abs(action2?.getEffectiveTimeScale?.() ?? 1);
       const reverse2 = state2?.reverse ?? (action2?.getEffectiveTimeScale?.() ?? 1) < 0;
       const pausedValues = this.bakedActionGroups.get(clipName) ? Array.from(this.bakedActionGroups.get(clipName).channelActions.values()).map((entry) => entry.paused) : [];
@@ -1005,7 +1189,7 @@ var BakedAnimationController = class {
     if (!action) return null;
     const clip = action.getClip();
     const state = this.playbackState.get(clipName);
-    const loopMode = state?.loopMode ?? (action.loop === THREE.LoopPingPong ? "pingpong" : action.loop === THREE.LoopOnce ? "once" : "repeat");
+    const loopMode = state?.loopMode ?? (action.loop === THREE2.LoopPingPong ? "pingpong" : action.loop === THREE2.LoopOnce ? "once" : "repeat");
     const playbackRate = state?.playbackRate ?? Math.abs(action.getEffectiveTimeScale());
     const reverse = state?.reverse ?? action.getEffectiveTimeScale() < 0;
     return {
@@ -1192,12 +1376,12 @@ var BakedAnimationController = class {
           const jawBinding = config.auToBones[26]?.[0];
           const maxDegrees = jawBinding?.maxDegrees ?? 30;
           const radians = maxDegrees * Math.PI / 180 * jawAmount;
-          const jawQ = new THREE.Quaternion().copy(jawEntry.baseQuat);
-          jawQ.multiply(new THREE.Quaternion().setFromAxisAngle(Z_AXIS, radians));
+          const jawQ = new THREE2.Quaternion().copy(jawEntry.baseQuat);
+          jawQ.multiply(new THREE2.Quaternion().setFromAxisAngle(Z_AXIS, radians));
           jawValues.push(jawQ.x, jawQ.y, jawQ.z, jawQ.w);
         }
         const trackName = `${jawEntry.obj.uuid}.quaternion`;
-        tracks.push(new THREE.QuaternionKeyframeTrack(trackName, keyframeTimes, jawValues));
+        tracks.push(new THREE2.QuaternionKeyframeTrack(trackName, keyframeTimes, jawValues));
       }
     }
     if (keyframeTimes.length > 0) {
@@ -1241,7 +1425,7 @@ var BakedAnimationController = class {
         }
         const values = [];
         for (const t of keyframeTimes) {
-          const compositeQ = new THREE.Quaternion().copy(entry.baseQuat);
+          const compositeQ = new THREE2.Quaternion().copy(entry.baseQuat);
           const applyAxis = (axisConfig) => {
             if (!axisConfig) return;
             let axisValue = getAxisValue(nodeKey, axisConfig, t);
@@ -1250,7 +1434,7 @@ var BakedAnimationController = class {
             if (!binding?.maxDegrees || !binding.channel) return;
             const radians = binding.maxDegrees * Math.PI / 180 * Math.abs(axisValue) * binding.scale;
             const axis = binding.channel === "rx" ? X_AXIS : binding.channel === "ry" ? Y_AXIS : Z_AXIS;
-            const deltaQ = new THREE.Quaternion().setFromAxisAngle(axis, radians);
+            const deltaQ = new THREE2.Quaternion().setFromAxisAngle(axis, radians);
             compositeQ.multiply(deltaQ);
           };
           applyAxis(composite.yaw);
@@ -1259,7 +1443,7 @@ var BakedAnimationController = class {
           values.push(compositeQ.x, compositeQ.y, compositeQ.z, compositeQ.w);
         }
         const trackName = `${entry.obj.uuid}.quaternion`;
-        tracks.push(new THREE.QuaternionKeyframeTrack(trackName, keyframeTimes, values));
+        tracks.push(new THREE2.QuaternionKeyframeTrack(trackName, keyframeTimes, values));
       }
       for (const curveId of Object.keys(curves)) {
         if (!isNumericAU(curveId)) continue;
@@ -1280,7 +1464,7 @@ var BakedAnimationController = class {
             values.push(basePos + delta);
           }
           const trackName = `${entry.obj.uuid}.position[${axisIndex}]`;
-          tracks.push(new THREE.NumberKeyframeTrack(trackName, keyframeTimes, values));
+          tracks.push(new THREE2.NumberKeyframeTrack(trackName, keyframeTimes, values));
         }
       }
     }
@@ -1288,7 +1472,8 @@ var BakedAnimationController = class {
       console.warn(`[Loom3] snippetToClip: No tracks created for "${clipName}"`);
       return null;
     }
-    const clip = new THREE.AnimationClip(clipName, maxTime, tracks);
+    const clip = new THREE2.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);
@@ -1540,7 +1754,7 @@ var BakedAnimationController = class {
         values.push(Math.max(0, Math.min(2, kf.intensity * intensityScale)));
       }
       const trackName = `${mesh.uuid}.morphTargetInfluences[${morphIndex}]`;
-      const track = new THREE.NumberKeyframeTrack(trackName, times, values);
+      const track = new THREE2.NumberKeyframeTrack(trackName, times, values);
       tracks.push(track);
     };
     for (const mesh of targetMeshes) {
@@ -1563,7 +1777,7 @@ var BakedAnimationController = class {
         values.push(Math.max(0, Math.min(2, kf.intensity * intensityScale)));
       }
       const trackName = `${mesh.uuid}.morphTargetInfluences[${morphIndex}]`;
-      const track = new THREE.NumberKeyframeTrack(trackName, times, values);
+      const track = new THREE2.NumberKeyframeTrack(trackName, times, values);
       tracks.push(track);
     };
     for (const mesh of targetMeshes) {
@@ -1574,11 +1788,19 @@ var BakedAnimationController = class {
     const model = this.host.getModel();
     if (!model) return null;
     if (!this.animationMixer) {
-      this.animationMixer = new THREE.AnimationMixer(model);
+      this.animationMixer = new THREE2.AnimationMixer(model);
     }
     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) {
@@ -2703,7 +2925,7 @@ var HairPhysicsController = class {
     this.clearRegisteredHairObjects();
     const result = [];
     for (const obj of objects) {
-      if (obj instanceof THREE.Mesh) {
+      if (obj instanceof THREE2.Mesh) {
         const mesh = obj;
         this.registeredHairObjects.set(mesh.name, mesh);
         const meshInfo = CC4_MESHES[mesh.name];
@@ -4285,15 +4507,17 @@ 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;
-var X_AXIS2 = new THREE.Vector3(1, 0, 0);
-var Y_AXIS2 = new THREE.Vector3(0, 1, 0);
-var Z_AXIS2 = new THREE.Vector3(0, 0, 1);
+var X_AXIS2 = new THREE2.Vector3(1, 0, 0);
+var Y_AXIS2 = new THREE2.Vector3(0, 1, 0);
+var Z_AXIS2 = new THREE2.Vector3(0, 0, 1);
 function buildAUToCompositeMap(composites) {
   const map = /* @__PURE__ */ new Map();
   composites.forEach((comp) => {
@@ -4357,7 +4581,7 @@ var _Loom3 = class _Loom3 {
     __publicField(this, "bakedAnimations");
     __publicField(this, "hairPhysics");
     // Internal animation loop
-    __publicField(this, "clock", new THREE.Clock(false));
+    __publicField(this, "clock", new THREE2.Clock(false));
     // Don't auto-start
     __publicField(this, "animationFrameId", null);
     __publicField(this, "isRunning", false);
@@ -4504,11 +4728,11 @@ var _Loom3 = class _Loom3 {
     }
     const head = this.bones["HEAD"]?.obj;
     if (head && availableMorphMeshes.length > 0) {
-      const headPos = new THREE.Vector3();
+      const headPos = new THREE2.Vector3();
       head.getWorldPosition?.(headPos);
       const headCandidates = availableMorphMeshes.map((mesh) => {
-        const box = new THREE.Box3().setFromObject(mesh);
-        const center = new THREE.Vector3();
+        const box = new THREE2.Box3().setFromObject(mesh);
+        const center = new THREE2.Vector3();
         box.getCenter(center);
         const distance = box.containsPoint(headPos) ? 0 : center.distanceTo(headPos);
         const morphCount = mesh.morphTargetDictionary ? Object.keys(mesh.morphTargetDictionary).length : 0;
@@ -5543,13 +5767,13 @@ var _Loom3 = class _Loom3 {
       return;
     }
     const getAxis = (channel) => channel === "rx" ? X_AXIS2 : channel === "ry" ? Y_AXIS2 : Z_AXIS2;
-    const compositeQ = new THREE.Quaternion().copy(baseQuat);
+    const compositeQ = new THREE2.Quaternion().copy(baseQuat);
     if (config.yaw && rotState.yaw !== 0) {
       const binding = this.getCompositeAxisBindingForNode(nodeKey, config.yaw, rotState.yaw);
       if (binding?.maxDegrees && binding.channel) {
         const radians = deg2rad(binding.maxDegrees) * Math.abs(rotState.yaw) * binding.scale;
         const axis = getAxis(binding.channel);
-        const deltaQ = new THREE.Quaternion().setFromAxisAngle(axis, radians);
+        const deltaQ = new THREE2.Quaternion().setFromAxisAngle(axis, radians);
         compositeQ.multiply(deltaQ);
       }
     }
@@ -5558,7 +5782,7 @@ var _Loom3 = class _Loom3 {
       if (binding?.maxDegrees && binding.channel) {
         const radians = deg2rad(binding.maxDegrees) * Math.abs(rotState.pitch) * binding.scale;
         const axis = getAxis(binding.channel);
-        const deltaQ = new THREE.Quaternion().setFromAxisAngle(axis, radians);
+        const deltaQ = new THREE2.Quaternion().setFromAxisAngle(axis, radians);
         compositeQ.multiply(deltaQ);
       }
     }
@@ -5567,7 +5791,7 @@ var _Loom3 = class _Loom3 {
       if (binding?.maxDegrees && binding.channel) {
         const radians = deg2rad(binding.maxDegrees) * Math.abs(rotState.roll) * binding.scale;
         const axis = getAxis(binding.channel);
-        const deltaQ = new THREE.Quaternion().setFromAxisAngle(axis, radians);
+        const deltaQ = new THREE2.Quaternion().setFromAxisAngle(axis, radians);
         compositeQ.multiply(deltaQ);
       }
     }
@@ -6006,10 +6230,11 @@ function extractProfileOverrides(config) {
     if (key === "annotationRegions") {
       const topLevelAnnotationRegions = Array.isArray(topLevelConfig.annotationRegions) ? topLevelConfig.annotationRegions : void 0;
       const legacyAnnotationRegions = Array.isArray(legacyNestedOverrides.annotationRegions) ? legacyNestedOverrides.annotationRegions : void 0;
-      const presetOverrideRegions = mergeRegionsByName(legacyAnnotationRegions, topLevelAnnotationRegions);
+      const legacyRegionFallback = Array.isArray(config.regions) && config.regions.length > 0 ? config.regions : void 0;
+      const legacyProfileRegions = mergeRegionsByName(legacyRegionFallback, legacyAnnotationRegions);
       const regions = mergeRegionsByName(
-        presetOverrideRegions,
-        Array.isArray(config.regions) && config.regions.length > 0 ? config.regions : void 0
+        legacyProfileRegions,
+        topLevelAnnotationRegions
       );
       if (regions) {
         overrides.annotationRegions = regions.map((region) => cloneRegion(region));
@@ -6025,6 +6250,13 @@ function extractProfileOverrides(config) {
   }
   return overrides;
 }
+function hasCanonicalAnnotationRegionOverrides(config) {
+  const topLevelConfig = config;
+  if (Array.isArray(topLevelConfig.annotationRegions)) {
+    return true;
+  }
+  return isPlainObject2(config.profile) && Array.isArray(config.profile.annotationRegions);
+}
 function applyCharacterProfileToPreset(config) {
   const presetType = config.auPresetType;
   if (!presetType) {
@@ -6062,7 +6294,7 @@ function extendCharacterConfigWithPreset(config) {
     return config;
   }
   const presetRegions = extendedPresetProfile.annotationRegions;
-  const mergedRegions = mergeRegionsByName(presetRegions, config.regions);
+  const mergedRegions = hasCanonicalAnnotationRegionOverrides(config) ? mergeRegionsByName(config.regions, presetRegions) : mergeRegionsByName(presetRegions, config.regions);
   const normalizedRegions = normalizeRegionTree(
     mergedRegions,
     profileOverrides.disabledRegions
@@ -6077,6 +6309,43 @@ function extendCharacterConfigWithPreset(config) {
     regions: extendedRegions ?? config.regions
   };
 }
+var DEFAULT_EPSILON = 1e-4;
+var DEFAULT_YAW_WEIGHT = 0.35;
+var DEFAULT_PITCH_WEIGHT = 0.2;
+var ZERO_OFFSET = { x: 0, y: 0 };
+function clampOffset(value) {
+  return THREE2__namespace.MathUtils.clamp(value, -1, 1);
+}
+function toModelLocalDirection(model, worldDirection) {
+  const localDirection = worldDirection.clone();
+  model.updateWorldMatrix(true, false);
+  const worldQuaternion = new THREE2__namespace.Quaternion();
+  model.getWorldQuaternion(worldQuaternion);
+  localDirection.applyQuaternion(worldQuaternion.invert());
+  return localDirection.normalize();
+}
+function computeCameraRelativeGazeOffset(model, cameraPosition, targetPosition, options = {}) {
+  if (!model) {
+    return ZERO_OFFSET;
+  }
+  const epsilon = options.epsilon ?? DEFAULT_EPSILON;
+  const yawWeight = options.yawWeight ?? DEFAULT_YAW_WEIGHT;
+  const pitchWeight = options.pitchWeight ?? DEFAULT_PITCH_WEIGHT;
+  const worldOffset = new THREE2__namespace.Vector3().subVectors(cameraPosition, targetPosition);
+  if (worldOffset.lengthSq() < epsilon) {
+    return ZERO_OFFSET;
+  }
+  const localDirection = toModelLocalDirection(model, worldOffset.normalize());
+  const yawAngle = Math.atan2(localDirection.x, localDirection.z);
+  const pitchAngle = Math.atan2(
+    localDirection.y,
+    Math.max(Math.hypot(localDirection.x, localDirection.z), epsilon)
+  );
+  return {
+    x: clampOffset(yawAngle / (Math.PI / 2)) * yawWeight,
+    y: clampOffset(pitchAngle / (Math.PI / 3)) * pitchWeight
+  };
+}
 var DEFAULT_HEAD_BONE_NAMES = ["CC_Base_Head", "Head", "head", "Bip01_Head"];
 var DEFAULT_REFERENCE_HEIGHT = 1.8;
 var DEFAULT_FORWARD_OFFSET = 0.08;
@@ -6092,8 +6361,8 @@ function findFaceCenter(model, options = {}) {
     referenceHeight = DEFAULT_REFERENCE_HEIGHT
   } = options;
   const debugInfo = [];
-  const boundingBox = new THREE__namespace.Box3().setFromObject(model);
-  const modelSize = new THREE__namespace.Vector3();
+  const boundingBox = new THREE2__namespace.Box3().setFromObject(model);
+  const modelSize = new THREE2__namespace.Vector3();
   boundingBox.getSize(modelSize);
   const scale = modelSize.y / referenceHeight;
   debugInfo.push(`Model height: ${modelSize.y.toFixed(2)}m, scale factor: ${scale.toFixed(2)}`);
@@ -6104,7 +6373,7 @@ function findFaceCenter(model, options = {}) {
       const objName = obj.name.toLowerCase();
       for (const boneName of headBoneNames) {
         if (objName === boneName.toLowerCase() || objName.includes(boneName.toLowerCase())) {
-          headPos2 = new THREE__namespace.Vector3();
+          headPos2 = new THREE2__namespace.Vector3();
           obj.getWorldPosition(headPos2);
           debugInfo.push(`Found head bone "${obj.name}" at (${headPos2.x.toFixed(3)}, ${headPos2.y.toFixed(3)}, ${headPos2.z.toFixed(3)})`);
           return;
@@ -6123,7 +6392,7 @@ function findFaceCenter(model, options = {}) {
       if (!eyes2.left) {
         for (const name of EYE_BONE_NAMES.left) {
           if (objName.includes(name)) {
-            eyes2.left = new THREE__namespace.Vector3();
+            eyes2.left = new THREE2__namespace.Vector3();
             obj.getWorldPosition(eyes2.left);
             debugInfo.push(`Found left eye "${obj.name}" at (${eyes2.left.x.toFixed(3)}, ${eyes2.left.y.toFixed(3)}, ${eyes2.left.z.toFixed(3)})`);
             break;
@@ -6133,7 +6402,7 @@ function findFaceCenter(model, options = {}) {
       if (!eyes2.right) {
         for (const name of EYE_BONE_NAMES.right) {
           if (objName.includes(name)) {
-            eyes2.right = new THREE__namespace.Vector3();
+            eyes2.right = new THREE2__namespace.Vector3();
             obj.getWorldPosition(eyes2.right);
             debugInfo.push(`Found right eye "${obj.name}" at (${eyes2.right.x.toFixed(3)}, ${eyes2.right.y.toFixed(3)}, ${eyes2.right.z.toFixed(3)})`);
             break;
@@ -6145,7 +6414,7 @@ function findFaceCenter(model, options = {}) {
   };
   if (faceMeshNames && faceMeshNames.length > 0) {
     debugInfo.push(`Looking for face meshes: ${faceMeshNames.join(", ")}`);
-    const meshBox = new THREE__namespace.Box3();
+    const meshBox = new THREE2__namespace.Box3();
     let foundMesh = false;
     model.traverse((obj) => {
       const isMesh = obj.isMesh;
@@ -6153,7 +6422,7 @@ function findFaceCenter(model, options = {}) {
       for (const meshName of faceMeshNames) {
         if (obj.name === meshName || obj.name.includes(meshName)) {
           const mesh = obj;
-          const tempBox = new THREE__namespace.Box3().setFromObject(mesh);
+          const tempBox = new THREE2__namespace.Box3().setFromObject(mesh);
           meshBox.union(tempBox);
           foundMesh = true;
           debugInfo.push(`Found mesh: "${obj.name}"`);
@@ -6162,11 +6431,11 @@ function findFaceCenter(model, options = {}) {
       }
     });
     if (foundMesh && !meshBox.isEmpty()) {
-      const meshBoundsSize = new THREE__namespace.Vector3();
+      const meshBoundsSize = new THREE2__namespace.Vector3();
       meshBox.getSize(meshBoundsSize);
       const isFullBodyMesh = meshBoundsSize.y > modelSize.y * 0.7;
       if (!isFullBodyMesh) {
-        const meshCenter = new THREE__namespace.Vector3();
+        const meshCenter = new THREE2__namespace.Vector3();
         meshBox.getCenter(meshCenter);
         debugInfo.push(`Using face mesh center: (${meshCenter.x.toFixed(3)}, ${meshCenter.y.toFixed(3)}, ${meshCenter.z.toFixed(3)})`);
         return {
@@ -6180,7 +6449,7 @@ function findFaceCenter(model, options = {}) {
   }
   const eyes = findEyes();
   if (eyes.left && eyes.right) {
-    const eyeCenter = new THREE__namespace.Vector3().addVectors(eyes.left, eyes.right).multiplyScalar(0.5);
+    const eyeCenter = new THREE2__namespace.Vector3().addVectors(eyes.left, eyes.right).multiplyScalar(0.5);
     debugInfo.push(`Eye center (face position): (${eyeCenter.x.toFixed(3)}, ${eyeCenter.y.toFixed(3)}, ${eyeCenter.z.toFixed(3)})`);
     const headPos2 = findHeadBone();
     return {
@@ -6205,10 +6474,10 @@ function findFaceCenter(model, options = {}) {
     };
   }
   debugInfo.push("No head bone found, using model center fallback");
-  const modelCenter = new THREE__namespace.Vector3();
+  const modelCenter = new THREE2__namespace.Vector3();
   boundingBox.getCenter(modelCenter);
   const headHeight = boundingBox.min.y + modelSize.y * 0.9;
-  const fallbackCenter = new THREE__namespace.Vector3(modelCenter.x, headHeight, modelCenter.z);
+  const fallbackCenter = new THREE2__namespace.Vector3(modelCenter.x, headHeight, modelCenter.z);
   debugInfo.push(`Fallback center: (${fallbackCenter.x.toFixed(3)}, ${fallbackCenter.y.toFixed(3)}, ${fallbackCenter.z.toFixed(3)})`);
   return {
     center: fallbackCenter,
@@ -6217,7 +6486,7 @@ function findFaceCenter(model, options = {}) {
   };
 }
 function getModelForwardDirection(model) {
-  const forward = new THREE__namespace.Vector3(0, 0, 1);
+  const forward = new THREE2__namespace.Vector3(0, 0, 1);
   forward.applyQuaternion(model.quaternion);
   return forward.normalize();
 }
@@ -6234,7 +6503,7 @@ function detectFacingDirection(model, eyeBoneNames = {
     if (!eyes.left) {
       for (const name of eyeBoneNames.left) {
         if (objName.includes(name)) {
-          eyes.left = new THREE__namespace.Vector3();
+          eyes.left = new THREE2__namespace.Vector3();
           obj.getWorldPosition(eyes.left);
           break;
         }
@@ -6243,7 +6512,7 @@ function detectFacingDirection(model, eyeBoneNames = {
     if (!eyes.right) {
       for (const name of eyeBoneNames.right) {
         if (objName.includes(name)) {
-          eyes.right = new THREE__namespace.Vector3();
+          eyes.right = new THREE2__namespace.Vector3();
           obj.getWorldPosition(eyes.right);
           break;
         }
@@ -7159,19 +7428,19 @@ function extractBones(root) {
   const bones = [];
   const boneDepths = /* @__PURE__ */ new Map();
   root.traverse((obj) => {
-    if (obj instanceof THREE__namespace.Bone || obj.type === "Bone") {
-      const worldPos = new THREE__namespace.Vector3();
+    if (obj instanceof THREE2__namespace.Bone || obj.type === "Bone") {
+      const worldPos = new THREE2__namespace.Vector3();
       obj.getWorldPosition(worldPos);
       let depth = 0;
       let parent = obj.parent;
       while (parent) {
-        if (parent instanceof THREE__namespace.Bone || parent.type === "Bone") {
+        if (parent instanceof THREE2__namespace.Bone || parent.type === "Bone") {
           depth++;
         }
         parent = parent.parent;
       }
       boneDepths.set(obj.name, depth);
-      const parentBone = obj.parent instanceof THREE__namespace.Bone || obj.parent?.type === "Bone" ? obj.parent.name : null;
+      const parentBone = obj.parent instanceof THREE2__namespace.Bone || obj.parent?.type === "Bone" ? obj.parent.name : null;
       bones.push({
         name: obj.name,
         parent: parentBone,
@@ -7424,6 +7693,7 @@ exports.VISEME_KEYS = VISEME_KEYS;
 exports.analyzeModel = analyzeModel;
 exports.applyCharacterProfileToPreset = applyCharacterProfileToPreset;
 exports.collectMorphMeshes = collectMorphMeshes;
+exports.computeCameraRelativeGazeOffset = computeCameraRelativeGazeOffset;
 exports.detectFacingDirection = detectFacingDirection;
 exports.extendCharacterConfigWithPreset = extendCharacterConfigWithPreset;
 exports.extendPresetWithProfile = extendPresetWithProfile;
@@ -7443,6 +7713,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;