@lovelace_lol/loom3 1.0.36 → 1.0.37

package/dist/index.d.cts

@@ -236,10 +236,12 @@ type PresetType = 'cc4' | 'skeletal' | 'fish' | 'custom';
  * This allows frontend to pass a string instead of importing the full preset.
  */
 declare function getPreset(presetType: PresetType | string | undefined): Profile;
+declare const resolvePreset: typeof getPreset;
 /**
  * Get a preset, then extend it with an optional profile.
  */
 declare function getPresetWithProfile(presetType: PresetType | string | undefined, profile?: Partial<Profile>): Profile;
+declare const resolvePresetWithOverrides: typeof getPresetWithProfile;
 
 /**
  * Loom3 - Core Type Definitions
@@ -452,6 +454,34 @@ interface AnimationActionHandle {
     /** Promise that resolves when animation completes (only for non-looping) */
     finished: Promise<void>;
 }
+type ClipEvent = {
+    type: 'keyframe';
+    clipName: string;
+    keyframeIndex: number;
+    totalKeyframes: number;
+    currentTime: number;
+    duration: number;
+    iteration: number;
+} | {
+    type: 'loop';
+    clipName: string;
+    iteration: number;
+    currentTime: number;
+    duration: number;
+} | {
+    type: 'seek';
+    clipName: string;
+    currentTime: number;
+    duration: number;
+    iteration: number;
+} | {
+    type: 'completed';
+    clipName: string;
+    currentTime: number;
+    duration: number;
+    iteration: number;
+};
+type ClipEventListener = (event: ClipEvent) => void;
 /**
  * A single keyframe point in an animation curve.
  */
@@ -551,6 +581,8 @@ interface ClipHandle {
     getTime: () => number;
     /** Get total clip duration in seconds */
     getDuration: () => number;
+    /** Subscribe to clip lifecycle events emitted by the runtime update loop */
+    subscribe?: (listener: ClipEventListener) => () => void;
     /** Promise that resolves when clip finishes (non-looping only) */
     finished: Promise<void>;
 }
@@ -2414,4 +2446,4 @@ declare function detectFacingDirection(model: THREE.Object3D, eyeBoneNames?: {
     right: string[];
 }): 'forward' | 'backward' | 'unknown';
 
-export { type AUInfo, type AUSelector, AU_INFO, AU_MAPPING_CONFIG, AU_MIX_DEFAULTS, AU_TO_MORPHS, type AnalyzeModelOptions, type Animation, type AnimationActionHandle, type AnimationAnalysis, type AnimationBlendMode, type AnimationClipInfo, type AnimationEasing, type AnimationInfo, type AnimationPlayOptions, type AnimationSource, type AnimationState, AnimationThree, BETTA_FISH_PRESET, BLENDING_MODES, BONE_AU_TO_BINDINGS, type BlendingMode, type BoneBinding, type BoneInfo, type BoneKey, CC4_BONE_NODES, CC4_BONE_PREFIX, CC4_EYE_MESH_NODES, CC4_MESHES, CC4_PRESET, CC4_SUFFIX_PATTERN, COMPOSITE_ROTATIONS, CONTINUUM_LABELS, CONTINUUM_PAIRS_MAP, type CharacterConfig, type CharacterRegistry, type ClipHandle, type ClipOptions, type CompositeRotation, type CompositeRotationState, type CurvePoint, type CurvesMap, DEFAULT_HAIR_PHYSICS_CONFIG, type ExpandAnimation, type ExpandedRegionState, FISH_AU_MAPPING_CONFIG, type FaceCenterResult, type FallbackConfig, type FindFaceCenterOptions, type Hair, type HairMorphAxis, type HairMorphOutput$1 as HairMorphOutput, type HairMorphTargetMapping, type HairMorphTargetValueMapping, type HairMorphTargetsConfig, type HairObjectRef, type HairObjectState, HairPhysics, type HairPhysicsConfig$1 as HairPhysicsConfig, type HairPhysicsDirectionConfig, type HairPhysics$1 as HairPhysicsInterface, type HairMorphOutput as HairPhysicsMorphOutput, type HairPhysicsProfileConfig, type HairPhysicsRuntimeConfig, type HairPhysicsRuntimeConfigUpdate, type HairPhysicsState, type HairState, type HairStrand, type HeadState$1 as HeadState, type LineConfig, type LineCurve, type LineStyle, Loom3, type Loom3Config, Loom3 as Loom3Three, type LoomLarge, type LoomLargeConfig, Loom3 as LoomLargeThree, MORPH_TO_MESH, type MappingConsistencyResult, type MappingCorrection, type MappingCorrectionOptions, type MappingCorrectionResult, type MappingIssue, type MarkerGroup, type MarkerStyle, type MarkerStyleOverrides, type MeshCategory, type MeshInfo, type MeshMaterialSettings, type MixerLoopMode, type ModelAnalysisReport, type ModelData, type ModelMeshInfo, type MorphCategory, type MorphInfo, type MorphTargetRef, type MorphTargetsBySide, type NamedDirection, type PresetType, type Profile, type ReadyPayload, type Region, type RotationAxis, type RotationsState, type Snippet, type TrackInfo, type TransitionHandle, VISEME_JAW_AMOUNTS, VISEME_KEYS, type ValidateMappingOptions, type ValidationResult, analyzeModel, applyCharacterProfileToPreset, collectMorphMeshes, detectFacingDirection, extendCharacterConfigWithPreset, extendPresetWithProfile, extractFromGLTF, extractModelData, extractProfileOverrides, findFaceCenter, fuzzyNameMatch, generateMappingCorrections, getModelForwardDirection, getPreset, getPresetWithProfile, hasLeftRightMorphs, isMixedAU, isPresetCompatible, mergeRegionsByName as mergeCharacterRegionsByName, resolveBoneName, resolveBoneNames, resolveFaceCenter, suggestBestPreset, validateMappingConfig, validateMappings };
+export { type AUInfo, type AUSelector, AU_INFO, AU_MAPPING_CONFIG, AU_MIX_DEFAULTS, AU_TO_MORPHS, type AnalyzeModelOptions, type Animation, type AnimationActionHandle, type AnimationAnalysis, type AnimationBlendMode, type AnimationClipInfo, type AnimationEasing, type AnimationInfo, type AnimationPlayOptions, type AnimationSource, type AnimationState, AnimationThree, BETTA_FISH_PRESET, BLENDING_MODES, BONE_AU_TO_BINDINGS, type BlendingMode, type BoneBinding, type BoneInfo, type BoneKey, CC4_BONE_NODES, CC4_BONE_PREFIX, CC4_EYE_MESH_NODES, CC4_MESHES, CC4_PRESET, CC4_SUFFIX_PATTERN, COMPOSITE_ROTATIONS, CONTINUUM_LABELS, CONTINUUM_PAIRS_MAP, type CharacterConfig, type CharacterRegistry, type ClipEvent, type ClipEventListener, type ClipHandle, type ClipOptions, type CompositeRotation, type CompositeRotationState, type CurvePoint, type CurvesMap, DEFAULT_HAIR_PHYSICS_CONFIG, type ExpandAnimation, type ExpandedRegionState, FISH_AU_MAPPING_CONFIG, type FaceCenterResult, type FallbackConfig, type FindFaceCenterOptions, type Hair, type HairMorphAxis, type HairMorphOutput$1 as HairMorphOutput, type HairMorphTargetMapping, type HairMorphTargetValueMapping, type HairMorphTargetsConfig, type HairObjectRef, type HairObjectState, HairPhysics, type HairPhysicsConfig$1 as HairPhysicsConfig, type HairPhysicsDirectionConfig, type HairPhysics$1 as HairPhysicsInterface, type HairMorphOutput as HairPhysicsMorphOutput, type HairPhysicsProfileConfig, type HairPhysicsRuntimeConfig, type HairPhysicsRuntimeConfigUpdate, type HairPhysicsState, type HairState, type HairStrand, type HeadState$1 as HeadState, type LineConfig, type LineCurve, type LineStyle, Loom3, type Loom3Config, Loom3 as Loom3Three, type LoomLarge, type LoomLargeConfig, Loom3 as LoomLargeThree, MORPH_TO_MESH, type MappingConsistencyResult, type MappingCorrection, type MappingCorrectionOptions, type MappingCorrectionResult, type MappingIssue, type MarkerGroup, type MarkerStyle, type MarkerStyleOverrides, type MeshCategory, type MeshInfo, type MeshMaterialSettings, type MixerLoopMode, type ModelAnalysisReport, type ModelData, type ModelMeshInfo, type MorphCategory, type MorphInfo, type MorphTargetRef, type MorphTargetsBySide, type NamedDirection, type PresetType, type Profile, type ReadyPayload, type Region, type RotationAxis, type RotationsState, type Snippet, type TrackInfo, type TransitionHandle, VISEME_JAW_AMOUNTS, VISEME_KEYS, type ValidateMappingOptions, type ValidationResult, analyzeModel, applyCharacterProfileToPreset, collectMorphMeshes, detectFacingDirection, extendCharacterConfigWithPreset, extendPresetWithProfile, extractFromGLTF, extractModelData, extractProfileOverrides, findFaceCenter, fuzzyNameMatch, generateMappingCorrections, getModelForwardDirection, getPreset, getPresetWithProfile, hasLeftRightMorphs, isMixedAU, isPresetCompatible, mergeRegionsByName as mergeCharacterRegionsByName, resolveBoneName, resolveBoneNames, resolveFaceCenter, resolvePreset, resolvePresetWithOverrides, suggestBestPreset, validateMappingConfig, validateMappings };

package/dist/index.d.ts

@@ -236,10 +236,12 @@ type PresetType = 'cc4' | 'skeletal' | 'fish' | 'custom';
  * This allows frontend to pass a string instead of importing the full preset.
  */
 declare function getPreset(presetType: PresetType | string | undefined): Profile;
+declare const resolvePreset: typeof getPreset;
 /**
  * Get a preset, then extend it with an optional profile.
  */
 declare function getPresetWithProfile(presetType: PresetType | string | undefined, profile?: Partial<Profile>): Profile;
+declare const resolvePresetWithOverrides: typeof getPresetWithProfile;
 
 /**
  * Loom3 - Core Type Definitions
@@ -452,6 +454,34 @@ interface AnimationActionHandle {
     /** Promise that resolves when animation completes (only for non-looping) */
     finished: Promise<void>;
 }
+type ClipEvent = {
+    type: 'keyframe';
+    clipName: string;
+    keyframeIndex: number;
+    totalKeyframes: number;
+    currentTime: number;
+    duration: number;
+    iteration: number;
+} | {
+    type: 'loop';
+    clipName: string;
+    iteration: number;
+    currentTime: number;
+    duration: number;
+} | {
+    type: 'seek';
+    clipName: string;
+    currentTime: number;
+    duration: number;
+    iteration: number;
+} | {
+    type: 'completed';
+    clipName: string;
+    currentTime: number;
+    duration: number;
+    iteration: number;
+};
+type ClipEventListener = (event: ClipEvent) => void;
 /**
  * A single keyframe point in an animation curve.
  */
@@ -551,6 +581,8 @@ interface ClipHandle {
     getTime: () => number;
     /** Get total clip duration in seconds */
     getDuration: () => number;
+    /** Subscribe to clip lifecycle events emitted by the runtime update loop */
+    subscribe?: (listener: ClipEventListener) => () => void;
     /** Promise that resolves when clip finishes (non-looping only) */
     finished: Promise<void>;
 }
@@ -2414,4 +2446,4 @@ declare function detectFacingDirection(model: THREE.Object3D, eyeBoneNames?: {
     right: string[];
 }): 'forward' | 'backward' | 'unknown';
 
-export { type AUInfo, type AUSelector, AU_INFO, AU_MAPPING_CONFIG, AU_MIX_DEFAULTS, AU_TO_MORPHS, type AnalyzeModelOptions, type Animation, type AnimationActionHandle, type AnimationAnalysis, type AnimationBlendMode, type AnimationClipInfo, type AnimationEasing, type AnimationInfo, type AnimationPlayOptions, type AnimationSource, type AnimationState, AnimationThree, BETTA_FISH_PRESET, BLENDING_MODES, BONE_AU_TO_BINDINGS, type BlendingMode, type BoneBinding, type BoneInfo, type BoneKey, CC4_BONE_NODES, CC4_BONE_PREFIX, CC4_EYE_MESH_NODES, CC4_MESHES, CC4_PRESET, CC4_SUFFIX_PATTERN, COMPOSITE_ROTATIONS, CONTINUUM_LABELS, CONTINUUM_PAIRS_MAP, type CharacterConfig, type CharacterRegistry, type ClipHandle, type ClipOptions, type CompositeRotation, type CompositeRotationState, type CurvePoint, type CurvesMap, DEFAULT_HAIR_PHYSICS_CONFIG, type ExpandAnimation, type ExpandedRegionState, FISH_AU_MAPPING_CONFIG, type FaceCenterResult, type FallbackConfig, type FindFaceCenterOptions, type Hair, type HairMorphAxis, type HairMorphOutput$1 as HairMorphOutput, type HairMorphTargetMapping, type HairMorphTargetValueMapping, type HairMorphTargetsConfig, type HairObjectRef, type HairObjectState, HairPhysics, type HairPhysicsConfig$1 as HairPhysicsConfig, type HairPhysicsDirectionConfig, type HairPhysics$1 as HairPhysicsInterface, type HairMorphOutput as HairPhysicsMorphOutput, type HairPhysicsProfileConfig, type HairPhysicsRuntimeConfig, type HairPhysicsRuntimeConfigUpdate, type HairPhysicsState, type HairState, type HairStrand, type HeadState$1 as HeadState, type LineConfig, type LineCurve, type LineStyle, Loom3, type Loom3Config, Loom3 as Loom3Three, type LoomLarge, type LoomLargeConfig, Loom3 as LoomLargeThree, MORPH_TO_MESH, type MappingConsistencyResult, type MappingCorrection, type MappingCorrectionOptions, type MappingCorrectionResult, type MappingIssue, type MarkerGroup, type MarkerStyle, type MarkerStyleOverrides, type MeshCategory, type MeshInfo, type MeshMaterialSettings, type MixerLoopMode, type ModelAnalysisReport, type ModelData, type ModelMeshInfo, type MorphCategory, type MorphInfo, type MorphTargetRef, type MorphTargetsBySide, type NamedDirection, type PresetType, type Profile, type ReadyPayload, type Region, type RotationAxis, type RotationsState, type Snippet, type TrackInfo, type TransitionHandle, VISEME_JAW_AMOUNTS, VISEME_KEYS, type ValidateMappingOptions, type ValidationResult, analyzeModel, applyCharacterProfileToPreset, collectMorphMeshes, detectFacingDirection, extendCharacterConfigWithPreset, extendPresetWithProfile, extractFromGLTF, extractModelData, extractProfileOverrides, findFaceCenter, fuzzyNameMatch, generateMappingCorrections, getModelForwardDirection, getPreset, getPresetWithProfile, hasLeftRightMorphs, isMixedAU, isPresetCompatible, mergeRegionsByName as mergeCharacterRegionsByName, resolveBoneName, resolveBoneNames, resolveFaceCenter, suggestBestPreset, validateMappingConfig, validateMappings };
+export { type AUInfo, type AUSelector, AU_INFO, AU_MAPPING_CONFIG, AU_MIX_DEFAULTS, AU_TO_MORPHS, type AnalyzeModelOptions, type Animation, type AnimationActionHandle, type AnimationAnalysis, type AnimationBlendMode, type AnimationClipInfo, type AnimationEasing, type AnimationInfo, type AnimationPlayOptions, type AnimationSource, type AnimationState, AnimationThree, BETTA_FISH_PRESET, BLENDING_MODES, BONE_AU_TO_BINDINGS, type BlendingMode, type BoneBinding, type BoneInfo, type BoneKey, CC4_BONE_NODES, CC4_BONE_PREFIX, CC4_EYE_MESH_NODES, CC4_MESHES, CC4_PRESET, CC4_SUFFIX_PATTERN, COMPOSITE_ROTATIONS, CONTINUUM_LABELS, CONTINUUM_PAIRS_MAP, type CharacterConfig, type CharacterRegistry, type ClipEvent, type ClipEventListener, type ClipHandle, type ClipOptions, type CompositeRotation, type CompositeRotationState, type CurvePoint, type CurvesMap, DEFAULT_HAIR_PHYSICS_CONFIG, type ExpandAnimation, type ExpandedRegionState, FISH_AU_MAPPING_CONFIG, type FaceCenterResult, type FallbackConfig, type FindFaceCenterOptions, type Hair, type HairMorphAxis, type HairMorphOutput$1 as HairMorphOutput, type HairMorphTargetMapping, type HairMorphTargetValueMapping, type HairMorphTargetsConfig, type HairObjectRef, type HairObjectState, HairPhysics, type HairPhysicsConfig$1 as HairPhysicsConfig, type HairPhysicsDirectionConfig, type HairPhysics$1 as HairPhysicsInterface, type HairMorphOutput as HairPhysicsMorphOutput, type HairPhysicsProfileConfig, type HairPhysicsRuntimeConfig, type HairPhysicsRuntimeConfigUpdate, type HairPhysicsState, type HairState, type HairStrand, type HeadState$1 as HeadState, type LineConfig, type LineCurve, type LineStyle, Loom3, type Loom3Config, Loom3 as Loom3Three, type LoomLarge, type LoomLargeConfig, Loom3 as LoomLargeThree, MORPH_TO_MESH, type MappingConsistencyResult, type MappingCorrection, type MappingCorrectionOptions, type MappingCorrectionResult, type MappingIssue, type MarkerGroup, type MarkerStyle, type MarkerStyleOverrides, type MeshCategory, type MeshInfo, type MeshMaterialSettings, type MixerLoopMode, type ModelAnalysisReport, type ModelData, type ModelMeshInfo, type MorphCategory, type MorphInfo, type MorphTargetRef, type MorphTargetsBySide, type NamedDirection, type PresetType, type Profile, type ReadyPayload, type Region, type RotationAxis, type RotationsState, type Snippet, type TrackInfo, type TransitionHandle, VISEME_JAW_AMOUNTS, VISEME_KEYS, type ValidateMappingOptions, type ValidationResult, analyzeModel, applyCharacterProfileToPreset, collectMorphMeshes, detectFacingDirection, extendCharacterConfigWithPreset, extendPresetWithProfile, extractFromGLTF, extractModelData, extractProfileOverrides, findFaceCenter, fuzzyNameMatch, generateMappingCorrections, getModelForwardDirection, getPreset, getPresetWithProfile, hasLeftRightMorphs, isMixedAU, isPresetCompatible, mergeRegionsByName as mergeCharacterRegionsByName, resolveBoneName, resolveBoneNames, resolveFaceCenter, resolvePreset, resolvePresetWithOverrides, suggestBestPreset, validateMappingConfig, validateMappings };

package/dist/index.js

@@ -270,6 +270,8 @@ var makeActionId = () => `act_${Math.random().toString(36).slice(2, 8)}_${Date.n
 var X_AXIS = new Vector3(1, 0, 0);
 var Y_AXIS = new Vector3(0, 1, 0);
 var Z_AXIS = new Vector3(0, 0, 1);
+var CLIP_EVENT_METADATA_KEY = "__loom3ClipEvents";
+var CLIP_EVENT_EPSILON = 1e-4;
 var BakedAnimationController = class {
   constructor(host) {
     __publicField(this, "host");
@@ -288,6 +290,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) {
@@ -301,6 +304,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;
@@ -512,7 +670,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() {
@@ -532,6 +711,7 @@ var BakedAnimationController = class {
     this.clipHandles.clear();
     this.clipSources.clear();
     this.playbackState.clear();
+    this.clipMonitors.clear();
   }
   loadAnimationClips(clips) {
     const model = this.host.getModel();
@@ -670,6 +850,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) {
@@ -692,9 +873,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) {
@@ -707,6 +890,7 @@ var BakedAnimationController = class {
       } catch {
       }
       this.clipActions.delete(clipName);
+      if (actionId) this.cleanupClipMonitor(actionId);
     }
     if (this.clipActions.get(clipName) === action) {
       this.clipActions.delete(clipName);
@@ -1268,6 +1452,7 @@ var BakedAnimationController = class {
       return null;
     }
     const clip = new 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;
   }
@@ -1299,28 +1484,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);
@@ -1338,6 +1533,7 @@ var BakedAnimationController = class {
           })
         );
         action.play();
+        this.resetClipMonitor(monitor, action.time);
       },
       stop: () => {
         action.stop();
@@ -1355,8 +1551,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;
@@ -1374,6 +1569,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) => {
@@ -1382,6 +1579,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) => {
@@ -1391,9 +1589,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);
@@ -1417,6 +1622,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();
@@ -1431,6 +1637,7 @@ var BakedAnimationController = class {
         this.clipHandles.delete(clipName);
         this.animationFinishedCallbacks.delete(clipName);
         this.playbackState.delete(clipName);
+        if (actionId) this.cleanupClipMonitor(actionId);
       }
     }
   }
@@ -1454,6 +1661,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 {
@@ -1472,6 +1681,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) {
@@ -1479,6 +1692,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);
@@ -1558,6 +1772,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) {
@@ -4264,9 +4486,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;
@@ -7374,6 +7598,6 @@ async function analyzeModel(options) {
   };
 }
 
-export { AU_INFO, AU_MAPPING_CONFIG, AU_MIX_DEFAULTS, AU_TO_MORPHS, AnimationThree, BETTA_FISH_PRESET, BLENDING_MODES, BONE_AU_TO_BINDINGS, CC4_BONE_NODES, CC4_BONE_PREFIX, CC4_EYE_MESH_NODES, CC4_MESHES, CC4_PRESET, CC4_SUFFIX_PATTERN, COMPOSITE_ROTATIONS, CONTINUUM_LABELS, CONTINUUM_PAIRS_MAP, DEFAULT_HAIR_PHYSICS_CONFIG, FISH_AU_MAPPING_CONFIG, HairPhysics, Loom3, Loom3 as Loom3Three, Loom3 as LoomLargeThree, MORPH_TO_MESH, VISEME_JAW_AMOUNTS, VISEME_KEYS, analyzeModel, applyCharacterProfileToPreset, collectMorphMeshes, detectFacingDirection, extendCharacterConfigWithPreset, extendPresetWithProfile, extractFromGLTF, extractModelData, extractProfileOverrides, findFaceCenter, fuzzyNameMatch, generateMappingCorrections, getModelForwardDirection, getPreset, getPresetWithProfile, hasLeftRightMorphs, isMixedAU, isPresetCompatible, mergeRegionsByName as mergeCharacterRegionsByName, resolveBoneName, resolveBoneNames, resolveFaceCenter, suggestBestPreset, validateMappingConfig, validateMappings };
+export { AU_INFO, AU_MAPPING_CONFIG, AU_MIX_DEFAULTS, AU_TO_MORPHS, AnimationThree, BETTA_FISH_PRESET, BLENDING_MODES, BONE_AU_TO_BINDINGS, CC4_BONE_NODES, CC4_BONE_PREFIX, CC4_EYE_MESH_NODES, CC4_MESHES, CC4_PRESET, CC4_SUFFIX_PATTERN, COMPOSITE_ROTATIONS, CONTINUUM_LABELS, CONTINUUM_PAIRS_MAP, DEFAULT_HAIR_PHYSICS_CONFIG, FISH_AU_MAPPING_CONFIG, HairPhysics, Loom3, Loom3 as Loom3Three, Loom3 as LoomLargeThree, MORPH_TO_MESH, VISEME_JAW_AMOUNTS, VISEME_KEYS, analyzeModel, applyCharacterProfileToPreset, collectMorphMeshes, detectFacingDirection, extendCharacterConfigWithPreset, extendPresetWithProfile, extractFromGLTF, extractModelData, extractProfileOverrides, findFaceCenter, fuzzyNameMatch, generateMappingCorrections, getModelForwardDirection, getPreset, getPresetWithProfile, hasLeftRightMorphs, isMixedAU, isPresetCompatible, mergeRegionsByName as mergeCharacterRegionsByName, resolveBoneName, resolveBoneNames, resolveFaceCenter, resolvePreset, resolvePresetWithOverrides, suggestBestPreset, validateMappingConfig, validateMappings };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map