@lovelace_lol/loom3 1.0.36 → 1.0.38

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>;
 }
@@ -1970,12 +2002,28 @@ declare function applyCharacterProfileToPreset(config: CharacterConfig): Profile
  *
  * Precedence:
  * 1. preset defaults
- * 2. flattened top-level profile overrides
+ * 2. saved `config.regions` overrides, or fallbacks when `annotationRegions`
+ *    is present
  * 3. legacy nested `config.profile` overrides (compatibility only)
- * 4. top-level saved `config.regions` overrides by region name
+ * 4. flattened top-level profile overrides
  */
 declare function extendCharacterConfigWithPreset(config: CharacterConfig): CharacterConfig;
 
+type CameraRelativeGazeOffset = {
+    x: number;
+    y: number;
+};
+interface CameraRelativeGazeOptions {
+    yawWeight?: number;
+    pitchWeight?: number;
+    epsilon?: number;
+}
+/**
+ * Convert the current camera position into a normalized gaze offset in model-local space.
+ * This is intentionally pure so apps can cache or subscribe to camera changes however they want.
+ */
+declare function computeCameraRelativeGazeOffset(model: THREE.Object3D | null, cameraPosition: THREE.Vector3, targetPosition: THREE.Vector3, options?: CameraRelativeGazeOptions): CameraRelativeGazeOffset;
+
 interface ResolvedFaceCenter {
     center: THREE.Vector3;
     method: string;
@@ -2414,4 +2462,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 CameraRelativeGazeOffset, type CameraRelativeGazeOptions, 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, computeCameraRelativeGazeOffset, 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>;
 }
@@ -1970,12 +2002,28 @@ declare function applyCharacterProfileToPreset(config: CharacterConfig): Profile
  *
  * Precedence:
  * 1. preset defaults
- * 2. flattened top-level profile overrides
+ * 2. saved `config.regions` overrides, or fallbacks when `annotationRegions`
+ *    is present
  * 3. legacy nested `config.profile` overrides (compatibility only)
- * 4. top-level saved `config.regions` overrides by region name
+ * 4. flattened top-level profile overrides
  */
 declare function extendCharacterConfigWithPreset(config: CharacterConfig): CharacterConfig;
 
+type CameraRelativeGazeOffset = {
+    x: number;
+    y: number;
+};
+interface CameraRelativeGazeOptions {
+    yawWeight?: number;
+    pitchWeight?: number;
+    epsilon?: number;
+}
+/**
+ * Convert the current camera position into a normalized gaze offset in model-local space.
+ * This is intentionally pure so apps can cache or subscribe to camera changes however they want.
+ */
+declare function computeCameraRelativeGazeOffset(model: THREE.Object3D | null, cameraPosition: THREE.Vector3, targetPosition: THREE.Vector3, options?: CameraRelativeGazeOptions): CameraRelativeGazeOffset;
+
 interface ResolvedFaceCenter {
     center: THREE.Vector3;
     method: string;
@@ -2414,4 +2462,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 CameraRelativeGazeOffset, type CameraRelativeGazeOptions, 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, computeCameraRelativeGazeOffset, 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 };