@lovelace_lol/loom3 1.0.39 → 1.0.41

package/dist/index.d.cts

@@ -92,7 +92,7 @@ declare const CC4_PRESET: Profile;
  * - Scalars: extension wins when provided.
  * - Maps: shallow-merged by key, values cloned.
  * - Arrays: replaced when the extension provides them (except annotationRegions).
- * - annotationRegions: merged by region name, shallow field merge (extension wins).
+ * - annotationRegions: merged by region name, with nested camera/style fields preserved.
  */
 declare function extendPresetWithProfile(base: Profile, extension?: Partial<Profile>): Profile;
 
@@ -224,7 +224,7 @@ declare const FISH_AU_MAPPING_CONFIG: {
  * Loom3 - Preset Exports
  *
  * All AU presets are exported from here.
- * Frontend passes a presetType string and Loom3 looks up the preset internally.
+ * Frontend passes a presetType string and Loom3 looks up or extends the preset internally.
  */
 
 /**
@@ -315,6 +315,33 @@ interface CompositeRotationState {
     roll: number;
 }
 type RotationsState = Record<string, CompositeRotationState>;
+type MorphTargetAttributeData = Float32Array | number[];
+interface MorphTargetDelta {
+    /** Mesh name from the loaded Three.js scene. */
+    meshName: string;
+    /** Morph target name to add to morphTargetDictionary. */
+    name: string;
+    /** POSITION deltas, usually XYZ values relative to the base mesh. */
+    position: MorphTargetAttributeData;
+    /** Optional NORMAL deltas. */
+    normal?: MorphTargetAttributeData;
+    /** Optional TANGENT deltas. */
+    tangent?: MorphTargetAttributeData;
+    /** Whether deltas are relative to base attributes. Defaults to true. */
+    relative?: boolean;
+}
+interface AddMorphTargetOptions {
+    /** Replace an existing morph target with the same name. */
+    replace?: boolean;
+    /** Initialize the new or replaced influence value to zero. Defaults to true. */
+    resetInfluence?: boolean;
+    /**
+     * Replace and dispose the BufferGeometry instead of mutating it in place.
+     * Defaults to true because Three.js does not support mutating morph attributes
+     * after a geometry has rendered.
+     */
+    forceGeometryReplacement?: boolean;
+}
 /** Source category for mixer-driven animations. */
 type AnimationSource = 'baked' | 'clip' | 'snippet';
 /** Shared blend-mode surface for downstream animation UIs. */
@@ -958,6 +985,25 @@ interface Animation {
      * @param meshNames - Optional specific meshes to target
      */
     transitionMorphInfluence(index: number, to: number, durationMs?: number, meshNames?: string[]): TransitionHandle;
+    /**
+     * Add or replace a runtime morph target on a mesh.
+     * Returns the morphTargetInfluences index assigned to the target.
+     */
+    addMorphTarget(target: MorphTargetDelta, options?: AddMorphTargetOptions): number;
+    /**
+     * Add multiple runtime morph targets and return their assigned indices keyed
+     * by "meshName:name".
+     */
+    addMorphTargets(targets: MorphTargetDelta[], options?: AddMorphTargetOptions): Record<string, number>;
+    /**
+     * Ensure a named morph influence slot exists on the mesh.
+     * If the target is missing, a zero-delta morph target is created.
+     */
+    ensureMorphInfluence(meshName: string, morphName: string): number;
+    /**
+     * Rebuild runtime morph caches after external geometry or dictionary changes.
+     */
+    refreshMorphTargets(meshNames?: string[]): void;
     /**
      * Set viseme value immediately (for lip-sync)
      * @param visemeIndex - Viseme index 0-14
@@ -1461,6 +1507,10 @@ declare class Loom3 implements LoomLarge {
      * @param balance - Optional L/R balance for bilateral morphs
      */
     transitionContinuum(negAU: number, posAU: number, continuumValue: number, durationMs?: number, balance?: number): TransitionHandle;
+    addMorphTarget(target: MorphTargetDelta, options?: AddMorphTargetOptions): number;
+    addMorphTargets(targets: MorphTargetDelta[], options?: AddMorphTargetOptions): Record<string, number>;
+    ensureMorphInfluence(meshName: string, morphName: string): number;
+    refreshMorphTargets(_meshNames?: string[]): void;
     /**
      * Set a morph target value.
      *
@@ -1607,6 +1657,12 @@ declare class Loom3 implements LoomLarge {
     private applyMorphTargets;
     private getMorphValue;
     private getMorphValueByIndex;
+    private applyMorphTargetDelta;
+    private requireNamedMesh;
+    private getMeshMorphDictionary;
+    private setMorphAttributeAtIndex;
+    private setZeroMorphAttributeAtIndex;
+    private addRuntimeMorphMesh;
     private getMorphKeyCacheKey;
     private getMorphIndexCacheKey;
     private syncVisemeRuntimeState;
@@ -2002,10 +2058,9 @@ declare function applyCharacterProfileToPreset(config: CharacterConfig): Profile
  *
  * Precedence:
  * 1. preset defaults
- * 2. saved `config.regions` overrides, or fallbacks when `annotationRegions`
- *    is present
+ * 2. canonical flattened `annotationRegions` / top-level profile overrides
  * 3. legacy nested `config.profile` overrides (compatibility only)
- * 4. flattened top-level profile overrides
+ * 4. legacy `config.regions` fallback only when canonical annotation overrides are absent
  */
 declare function extendCharacterConfigWithPreset(config: CharacterConfig): CharacterConfig;
 
@@ -2462,4 +2517,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 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 };
+export { type AUInfo, type AUSelector, AU_INFO, AU_MAPPING_CONFIG, AU_MIX_DEFAULTS, AU_TO_MORPHS, type AddMorphTargetOptions, 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 MorphTargetAttributeData, type MorphTargetDelta, 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

@@ -92,7 +92,7 @@ declare const CC4_PRESET: Profile;
  * - Scalars: extension wins when provided.
  * - Maps: shallow-merged by key, values cloned.
  * - Arrays: replaced when the extension provides them (except annotationRegions).
- * - annotationRegions: merged by region name, shallow field merge (extension wins).
+ * - annotationRegions: merged by region name, with nested camera/style fields preserved.
  */
 declare function extendPresetWithProfile(base: Profile, extension?: Partial<Profile>): Profile;
 
@@ -224,7 +224,7 @@ declare const FISH_AU_MAPPING_CONFIG: {
  * Loom3 - Preset Exports
  *
  * All AU presets are exported from here.
- * Frontend passes a presetType string and Loom3 looks up the preset internally.
+ * Frontend passes a presetType string and Loom3 looks up or extends the preset internally.
  */
 
 /**
@@ -315,6 +315,33 @@ interface CompositeRotationState {
     roll: number;
 }
 type RotationsState = Record<string, CompositeRotationState>;
+type MorphTargetAttributeData = Float32Array | number[];
+interface MorphTargetDelta {
+    /** Mesh name from the loaded Three.js scene. */
+    meshName: string;
+    /** Morph target name to add to morphTargetDictionary. */
+    name: string;
+    /** POSITION deltas, usually XYZ values relative to the base mesh. */
+    position: MorphTargetAttributeData;
+    /** Optional NORMAL deltas. */
+    normal?: MorphTargetAttributeData;
+    /** Optional TANGENT deltas. */
+    tangent?: MorphTargetAttributeData;
+    /** Whether deltas are relative to base attributes. Defaults to true. */
+    relative?: boolean;
+}
+interface AddMorphTargetOptions {
+    /** Replace an existing morph target with the same name. */
+    replace?: boolean;
+    /** Initialize the new or replaced influence value to zero. Defaults to true. */
+    resetInfluence?: boolean;
+    /**
+     * Replace and dispose the BufferGeometry instead of mutating it in place.
+     * Defaults to true because Three.js does not support mutating morph attributes
+     * after a geometry has rendered.
+     */
+    forceGeometryReplacement?: boolean;
+}
 /** Source category for mixer-driven animations. */
 type AnimationSource = 'baked' | 'clip' | 'snippet';
 /** Shared blend-mode surface for downstream animation UIs. */
@@ -958,6 +985,25 @@ interface Animation {
      * @param meshNames - Optional specific meshes to target
      */
     transitionMorphInfluence(index: number, to: number, durationMs?: number, meshNames?: string[]): TransitionHandle;
+    /**
+     * Add or replace a runtime morph target on a mesh.
+     * Returns the morphTargetInfluences index assigned to the target.
+     */
+    addMorphTarget(target: MorphTargetDelta, options?: AddMorphTargetOptions): number;
+    /**
+     * Add multiple runtime morph targets and return their assigned indices keyed
+     * by "meshName:name".
+     */
+    addMorphTargets(targets: MorphTargetDelta[], options?: AddMorphTargetOptions): Record<string, number>;
+    /**
+     * Ensure a named morph influence slot exists on the mesh.
+     * If the target is missing, a zero-delta morph target is created.
+     */
+    ensureMorphInfluence(meshName: string, morphName: string): number;
+    /**
+     * Rebuild runtime morph caches after external geometry or dictionary changes.
+     */
+    refreshMorphTargets(meshNames?: string[]): void;
     /**
      * Set viseme value immediately (for lip-sync)
      * @param visemeIndex - Viseme index 0-14
@@ -1461,6 +1507,10 @@ declare class Loom3 implements LoomLarge {
      * @param balance - Optional L/R balance for bilateral morphs
      */
     transitionContinuum(negAU: number, posAU: number, continuumValue: number, durationMs?: number, balance?: number): TransitionHandle;
+    addMorphTarget(target: MorphTargetDelta, options?: AddMorphTargetOptions): number;
+    addMorphTargets(targets: MorphTargetDelta[], options?: AddMorphTargetOptions): Record<string, number>;
+    ensureMorphInfluence(meshName: string, morphName: string): number;
+    refreshMorphTargets(_meshNames?: string[]): void;
     /**
      * Set a morph target value.
      *
@@ -1607,6 +1657,12 @@ declare class Loom3 implements LoomLarge {
     private applyMorphTargets;
     private getMorphValue;
     private getMorphValueByIndex;
+    private applyMorphTargetDelta;
+    private requireNamedMesh;
+    private getMeshMorphDictionary;
+    private setMorphAttributeAtIndex;
+    private setZeroMorphAttributeAtIndex;
+    private addRuntimeMorphMesh;
     private getMorphKeyCacheKey;
     private getMorphIndexCacheKey;
     private syncVisemeRuntimeState;
@@ -2002,10 +2058,9 @@ declare function applyCharacterProfileToPreset(config: CharacterConfig): Profile
  *
  * Precedence:
  * 1. preset defaults
- * 2. saved `config.regions` overrides, or fallbacks when `annotationRegions`
- *    is present
+ * 2. canonical flattened `annotationRegions` / top-level profile overrides
  * 3. legacy nested `config.profile` overrides (compatibility only)
- * 4. flattened top-level profile overrides
+ * 4. legacy `config.regions` fallback only when canonical annotation overrides are absent
  */
 declare function extendCharacterConfigWithPreset(config: CharacterConfig): CharacterConfig;
 
@@ -2462,4 +2517,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 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 };
+export { type AUInfo, type AUSelector, AU_INFO, AU_MAPPING_CONFIG, AU_MIX_DEFAULTS, AU_TO_MORPHS, type AddMorphTargetOptions, 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 MorphTargetAttributeData, type MorphTargetDelta, 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.js

@@ -1,5 +1,5 @@
 import * as THREE2 from 'three';
-import { Vector3, Clock, Box3, Quaternion, AdditiveAnimationBlendMode, NormalAnimationBlendMode, LoopPingPong, LoopOnce, LoopRepeat, QuaternionKeyframeTrack, NumberKeyframeTrack, AnimationClip, AnimationMixer, Mesh, PropertyBinding } from 'three';
+import { Vector3, Clock, Box3, BufferAttribute, Quaternion, AdditiveAnimationBlendMode, NormalAnimationBlendMode, LoopPingPong, LoopOnce, LoopRepeat, QuaternionKeyframeTrack, NumberKeyframeTrack, AnimationClip, AnimationMixer, Mesh, PropertyBinding } from 'three';
 
 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;
@@ -3552,7 +3552,7 @@ var mergeAnnotationRegion = (base, override) => {
   merged.meshes = override.meshes ? [...override.meshes] : base.meshes ? [...base.meshes] : void 0;
   merged.objects = override.objects ? [...override.objects] : base.objects ? [...base.objects] : void 0;
   merged.children = override.children ? [...override.children] : base.children ? [...base.children] : void 0;
-  merged.cameraOffset = override.cameraOffset ? { ...override.cameraOffset } : base.cameraOffset ? { ...base.cameraOffset } : void 0;
+  merged.cameraOffset = override.cameraOffset ? { ...base.cameraOffset, ...override.cameraOffset } : base.cameraOffset ? { ...base.cameraOffset } : void 0;
   merged.style = override.style ? {
     ...base.style,
     ...override.style,
@@ -4617,11 +4617,7 @@ var _Loom3 = class _Loom3 {
     this.morphIndexCache.clear();
     model.traverse((obj) => {
       if (obj.isMesh && obj.name) {
-        const infl = obj.morphTargetInfluences;
-        const dict = obj.morphTargetDictionary;
-        if (Array.isArray(infl) && infl.length > 0 || dict && Object.keys(dict).length > 0) {
-          this.meshByName.set(obj.name, obj);
-        }
+        this.meshByName.set(obj.name, obj);
       }
     });
     this.bones = this.resolveBones(model);
@@ -4989,6 +4985,58 @@ var _Loom3 = class _Loom3 {
     const currentContinuum = currentPos - currentNeg;
     return this.animation.addTransition(driverKey, currentContinuum, target, durationMs, (value) => this.setContinuum(negAU, posAU, value, balance));
   }
+  // ============================================================================
+  // MORPH CONTROL
+  // ============================================================================
+  addMorphTarget(target, options = {}) {
+    const staleMorphTargets = this.collectResolvedExpressionMorphTargets();
+    const index = this.applyMorphTargetDelta(target, options);
+    this.refreshMorphTargets([target.meshName]);
+    this.reinitializeRuntimeStateFromCurrentControls(staleMorphTargets);
+    return index;
+  }
+  addMorphTargets(targets, options = {}) {
+    const staleMorphTargets = this.collectResolvedExpressionMorphTargets();
+    const result = {};
+    for (const target of targets) {
+      const index = this.applyMorphTargetDelta(target, options);
+      result[`${target.meshName}:${target.name}`] = index;
+    }
+    this.refreshMorphTargets(Array.from(new Set(targets.map((target) => target.meshName))));
+    this.reinitializeRuntimeStateFromCurrentControls(staleMorphTargets);
+    return result;
+  }
+  ensureMorphInfluence(meshName, morphName) {
+    const mesh = this.requireNamedMesh(meshName);
+    const dict = this.getMeshMorphDictionary(mesh);
+    const existing = dict[morphName];
+    if (existing !== void 0) return existing;
+    const position = mesh.geometry.getAttribute("position");
+    if (!position) {
+      throw new Error(`Cannot create morph target "${morphName}" on mesh "${meshName}": geometry has no position attribute.`);
+    }
+    return this.addMorphTarget({
+      meshName,
+      name: morphName,
+      position: new Float32Array(position.count * position.itemSize),
+      relative: true
+    });
+  }
+  refreshMorphTargets(_meshNames) {
+    this.morphKeyCache.clear();
+    this.morphIndexCache.clear();
+    if (this.model) {
+      this.meshByName.clear();
+      this.model.traverse((obj) => {
+        if (obj.isMesh && obj.name) {
+          this.meshByName.set(obj.name, obj);
+        }
+      });
+      this.meshes = collectMorphMeshes(this.model);
+    }
+    this.rebuildMorphTargetsCache();
+    this.hairPhysics.refreshMeshSelection();
+  }
   setMorph(key, v, meshNamesOrTargets) {
     const val = clamp012(v);
     if (Array.isArray(meshNamesOrTargets) && meshNamesOrTargets.length > 0 && typeof meshNamesOrTargets[0] === "object" && "infl" in meshNamesOrTargets[0]) {
@@ -5607,6 +5655,148 @@ var _Loom3 = class _Loom3 {
     }
     return 0;
   }
+  applyMorphTargetDelta(target, options) {
+    const mesh = this.requireNamedMesh(target.meshName);
+    const sourceGeometry = mesh.geometry;
+    const position = sourceGeometry.getAttribute("position");
+    if (!position) {
+      throw new Error(`Cannot add morph target "${target.name}" to mesh "${target.meshName}": geometry has no position attribute.`);
+    }
+    if (!target.name || !target.name.trim()) {
+      throw new Error(`Cannot add morph target to mesh "${target.meshName}": target name is required.`);
+    }
+    const replace = options.replace === true;
+    const resetInfluence = options.resetInfluence !== false;
+    const forceGeometryReplacement = options.forceGeometryReplacement !== false;
+    const previousInfluences = mesh.morphTargetInfluences ? [...mesh.morphTargetInfluences] : [];
+    const previousDictionary = this.getMeshMorphDictionary(mesh);
+    const existingIndex = previousDictionary[target.name];
+    if (existingIndex !== void 0 && !replace) {
+      throw new Error(`Morph target "${target.name}" already exists on mesh "${target.meshName}". Pass replace: true to overwrite it.`);
+    }
+    const geometry = forceGeometryReplacement ? sourceGeometry.clone() : sourceGeometry;
+    const dictionary = { ...previousDictionary };
+    const usedIndices = Object.values(dictionary).filter(Number.isInteger);
+    const existingAttributeTargetCount = Math.max(
+      0,
+      ...Object.values(geometry.morphAttributes).map((attributes) => attributes?.length ?? 0)
+    );
+    const nextIndex = Math.max(existingAttributeTargetCount, usedIndices.length ? Math.max(...usedIndices) + 1 : 0);
+    const index = existingIndex ?? nextIndex;
+    dictionary[target.name] = index;
+    this.setMorphAttributeAtIndex(geometry, "position", target.position, position.itemSize, position.count, index, target.name);
+    const normal = geometry.getAttribute("normal");
+    if (target.normal) {
+      this.setMorphAttributeAtIndex(geometry, "normal", target.normal, normal?.itemSize ?? 3, position.count, index, target.name);
+    } else {
+      this.setZeroMorphAttributeAtIndex(geometry, "normal", normal?.itemSize ?? 3, position.count, index, target.name);
+    }
+    const tangent = geometry.getAttribute("tangent");
+    if (target.tangent) {
+      this.setMorphAttributeAtIndex(geometry, "tangent", target.tangent, tangent?.itemSize ?? 4, position.count, index, target.name);
+    } else {
+      this.setZeroMorphAttributeAtIndex(geometry, "tangent", tangent?.itemSize ?? 4, position.count, index, target.name);
+    }
+    const color = geometry.getAttribute("color");
+    const existingColorMorph = geometry.morphAttributes.color?.find(Boolean);
+    this.setZeroMorphAttributeAtIndex(
+      geometry,
+      "color",
+      color?.itemSize ?? existingColorMorph?.itemSize ?? 3,
+      position.count,
+      index,
+      target.name
+    );
+    geometry.morphTargetsRelative = target.relative !== false;
+    geometry.morphTargetDictionary = dictionary;
+    if (forceGeometryReplacement) {
+      mesh.geometry = geometry;
+      sourceGeometry.dispose();
+    }
+    const influenceLength = Math.max(previousInfluences.length, index + 1);
+    const influences = previousInfluences.slice(0, influenceLength);
+    while (influences.length < influenceLength) {
+      influences.push(0);
+    }
+    if (resetInfluence) {
+      influences[index] = 0;
+    }
+    mesh.morphTargetDictionary = dictionary;
+    mesh.morphTargetInfluences = influences;
+    this.addRuntimeMorphMesh(mesh);
+    if (!this.config.morphToMesh?.face?.length) {
+      this.config.morphToMesh = {
+        ...this.config.morphToMesh,
+        face: [mesh.name]
+      };
+    }
+    return index;
+  }
+  requireNamedMesh(meshName) {
+    const mesh = this.meshByName.get(meshName);
+    if (mesh) return mesh;
+    if (this.model) {
+      let found = null;
+      this.model.traverse((obj) => {
+        if (!found && obj.isMesh && obj.name === meshName) {
+          found = obj;
+        }
+      });
+      if (found) {
+        this.meshByName.set(meshName, found);
+        return found;
+      }
+    }
+    throw new Error(`Mesh "${meshName}" was not found in the current model.`);
+  }
+  getMeshMorphDictionary(mesh) {
+    const meshDictionary = mesh.morphTargetDictionary;
+    const geometryDictionary = mesh.geometry.morphTargetDictionary;
+    const dictionary = meshDictionary || geometryDictionary || {};
+    mesh.morphTargetDictionary = dictionary;
+    mesh.geometry.morphTargetDictionary = dictionary;
+    return dictionary;
+  }
+  setMorphAttributeAtIndex(geometry, semantic, data, itemSize, vertexCount, index, name) {
+    const expectedLength = vertexCount * itemSize;
+    if (data.length !== expectedLength) {
+      throw new Error(
+        `Morph target "${name}" ${semantic} data has ${data.length} values; expected ${expectedLength} (${vertexCount} vertices * itemSize ${itemSize}).`
+      );
+    }
+    const attributes = geometry.morphAttributes[semantic] ? [...geometry.morphAttributes[semantic]] : [];
+    while (attributes.length < index) {
+      const empty = new BufferAttribute(new Float32Array(expectedLength), itemSize);
+      empty.name = `morph_${attributes.length}`;
+      attributes.push(empty);
+    }
+    const values = data instanceof Float32Array ? new Float32Array(data) : Float32Array.from(data);
+    const attribute = new BufferAttribute(values, itemSize);
+    attribute.name = name;
+    attributes[index] = attribute;
+    geometry.morphAttributes[semantic] = attributes;
+  }
+  setZeroMorphAttributeAtIndex(geometry, semantic, itemSize, vertexCount, index, name) {
+    if (!geometry.morphAttributes[semantic]?.length) return;
+    const expectedLength = vertexCount * itemSize;
+    const attributes = [...geometry.morphAttributes[semantic]];
+    while (attributes.length < index) {
+      const empty2 = new BufferAttribute(new Float32Array(expectedLength), itemSize);
+      empty2.name = `morph_${attributes.length}`;
+      attributes.push(empty2);
+    }
+    const empty = new BufferAttribute(new Float32Array(expectedLength), itemSize);
+    empty.name = name;
+    attributes[index] = empty;
+    geometry.morphAttributes[semantic] = attributes;
+  }
+  addRuntimeMorphMesh(mesh) {
+    const key = mesh.name || mesh.uuid;
+    const exists = this.meshes.some((candidate) => (candidate.name || candidate.uuid) === key);
+    if (!exists) {
+      this.meshes.push(mesh);
+    }
+  }
   getMorphKeyCacheKey(key, meshNames) {
     return meshNames?.length ? `key:${key}@${meshNames.join(",")}` : `key:${key}`;
   }
@@ -6201,22 +6391,32 @@ function mergeRegionsByName(base, override) {
   }
   return Array.from(merged.values());
 }
+function getAnnotationRegions(value) {
+  return Array.isArray(value) ? value : void 0;
+}
+function getLegacyNestedOverrides(config) {
+  return isPlainObject2(config.profile) ? config.profile : {};
+}
+function getLegacyRuntimeRegions(config) {
+  return Array.isArray(config.regions) && config.regions.length > 0 ? config.regions : void 0;
+}
+function getCanonicalAnnotationOverrides(config) {
+  return mergeRegionsByName(
+    getAnnotationRegions(getLegacyNestedOverrides(config).annotationRegions),
+    getAnnotationRegions(config.annotationRegions)
+  );
+}
 function extractProfileOverrides(config) {
   const topLevelConfig = config;
-  const legacyNestedOverrides = isPlainObject2(config.profile) ? config.profile : {};
+  const legacyNestedOverrides = getLegacyNestedOverrides(config);
+  const canonicalAnnotationOverrides = getCanonicalAnnotationOverrides(config);
+  const legacyRuntimeRegions = getLegacyRuntimeRegions(config);
+  const annotationOverrides = canonicalAnnotationOverrides ?? (legacyRuntimeRegions ? legacyRuntimeRegions.map((region) => cloneRegion(region)) : void 0);
   const overrides = {};
   for (const key of PROFILE_OVERRIDE_KEYS) {
     if (key === "annotationRegions") {
-      const topLevelAnnotationRegions = Array.isArray(topLevelConfig.annotationRegions) ? topLevelConfig.annotationRegions : void 0;
-      const legacyAnnotationRegions = Array.isArray(legacyNestedOverrides.annotationRegions) ? legacyNestedOverrides.annotationRegions : void 0;
-      const legacyRegionFallback = Array.isArray(config.regions) && config.regions.length > 0 ? config.regions : void 0;
-      const legacyProfileRegions = mergeRegionsByName(legacyRegionFallback, legacyAnnotationRegions);
-      const regions = mergeRegionsByName(
-        legacyProfileRegions,
-        topLevelAnnotationRegions
-      );
-      if (regions) {
-        overrides.annotationRegions = regions.map((region) => cloneRegion(region));
+      if (annotationOverrides) {
+        overrides.annotationRegions = annotationOverrides.map((region) => cloneRegion(region));
       }
       continue;
     }
@@ -6229,13 +6429,6 @@ 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) {
@@ -6267,24 +6460,34 @@ function extendCharacterConfigWithPreset(config) {
   if (!presetType || presetType === "custom") {
     return config;
   }
+  const canonicalAnnotationOverrides = getCanonicalAnnotationOverrides(config);
+  const legacyRuntimeRegions = getLegacyRuntimeRegions(config);
   const profileOverrides = extractProfileOverrides(config);
   const extendedPresetProfile = applyCharacterProfileToPreset(config);
   if (!extendedPresetProfile) {
     return config;
   }
-  const presetRegions = extendedPresetProfile.annotationRegions;
-  const mergedRegions = hasCanonicalAnnotationRegionOverrides(config) ? mergeRegionsByName(config.regions, presetRegions) : mergeRegionsByName(presetRegions, config.regions);
-  const normalizedRegions = normalizeRegionTree(
-    mergedRegions,
+  const presetRegionNames = new Set(
+    (getPreset(presetType).annotationRegions ?? []).map((region) => region.name)
+  );
+  const extendedAnnotationRegions = normalizeRegionTree(
+    extendedPresetProfile.annotationRegions,
+    profileOverrides.disabledRegions
+  );
+  const extendedRegionNames = new Set((extendedAnnotationRegions ?? []).map((region) => region.name));
+  const legacyExtraRegions = canonicalAnnotationOverrides && legacyRuntimeRegions ? legacyRuntimeRegions.filter((region) => !presetRegionNames.has(region.name) && !extendedRegionNames.has(region.name)).map((region) => cloneRegion(region)) : void 0;
+  const mergedRegions = normalizeRegionTree(
+    mergeRegionsByName(extendedAnnotationRegions, legacyExtraRegions),
     profileOverrides.disabledRegions
   );
   const extendedRegions = orderExtendedRegions(
-    normalizedRegions,
-    [config.regions, profileOverrides.annotationRegions, presetRegions]
+    mergedRegions,
+    canonicalAnnotationOverrides ? [extendedAnnotationRegions, legacyExtraRegions] : [legacyRuntimeRegions, extendedAnnotationRegions]
   );
   return {
     ...config,
     ...extendedPresetProfile,
+    annotationRegions: extendedRegions ?? extendedAnnotationRegions,
     regions: extendedRegions ?? config.regions
   };
 }
@@ -7444,7 +7647,7 @@ function extractMorphs(meshes) {
   for (const mesh of meshes) {
     const geo = mesh.geometry;
     if (!geo.morphAttributes) continue;
-    const dict = geo.morphTargetDictionary;
+    const dict = mesh.morphTargetDictionary || geo.morphTargetDictionary;
     if (dict) {
       for (const [name, index] of Object.entries(dict)) {
         morphs.push({