@lovelace_lol/loom3 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,2384 @@
+import * as THREE from 'three';
+import { Object3D, Mesh, AnimationClip } from 'three';
+import { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
+
+/**
+ * CC4 Preset - Character Creator 4 AU Mappings
+ *
+ * Complete FACS Action Unit to morph target and bone mappings for CC4 rigs.
+ * This includes all the composite rotations, continuum pairs, mesh classifications,
+ * and AU metadata that we painstakingly worked through.
+ */
+
+declare const AU_TO_MORPHS: Record<number, MorphTargetsBySide>;
+declare const BONE_AU_TO_BINDINGS: Record<number, BoneBinding[]>;
+declare const VISEME_KEYS: string[];
+/**
+ * Jaw opening amounts for each viseme index (0-14).
+ * Values are 0-1 representing how much the jaw should open.
+ * Used by snippetToClip when autoVisemeJaw is enabled.
+ */
+declare const VISEME_JAW_AMOUNTS: number[];
+/** Check if an AU has both morphs and bones (can blend between them) */
+declare const isMixedAU: (id: number) => boolean;
+/** Check if an AU has separate left/right morphs */
+declare const hasLeftRightMorphs: (auId: number) => boolean;
+declare const COMPOSITE_ROTATIONS: CompositeRotation[];
+/**
+ * Continuum pair mappings - precomputed from COMPOSITE_ROTATIONS
+ * Maps AU ID to its continuum partner info for bidirectional axes
+ * (e.g., AU 51 "Head Left" is paired with AU 52 "Head Right")
+ */
+declare const CONTINUUM_PAIRS_MAP: Record<number, {
+    pairId: number;
+    isNegative: boolean;
+    axis: 'pitch' | 'yaw' | 'roll';
+    node: 'JAW' | 'HEAD' | 'EYE_L' | 'EYE_R' | 'TONGUE';
+}>;
+/**
+ * Human-readable labels for continuum pairs
+ * Key format: "negativeAU-positiveAU"
+ * Used by UI components (ContinuumSlider, AUSection) to display friendly axis names
+ */
+declare const CONTINUUM_LABELS: Record<string, string>;
+/**
+ * Bone name prefix for CC4 rigs.
+ * Base bone names are stored without this prefix in CC4_BONE_NODES.
+ * The engine will prepend this when resolving bones.
+ */
+declare const CC4_BONE_PREFIX = "CC_Base_";
+/**
+ * Suffix pattern regex for fuzzy bone matching.
+ * Matches numbered suffixes like _01, _038 (common in Sketchfab exports)
+ * and .001, .002 (common in Blender exports).
+ */
+declare const CC4_SUFFIX_PATTERN = "_\\d+$|\\.\\d+$";
+declare const CC4_BONE_NODES: {
+    readonly EYE_L: "L_Eye";
+    readonly EYE_R: "R_Eye";
+    readonly HEAD: "Head";
+    readonly NECK: "NeckTwist01";
+    readonly NECK_TWIST: "NeckTwist02";
+    readonly JAW: "JawRoot";
+    readonly TONGUE: "Tongue01";
+};
+declare const CC4_EYE_MESH_NODES: {
+    readonly LEFT: "CC_Base_Eye";
+    readonly RIGHT: "CC_Base_Eye_1";
+};
+declare const AU_INFO: Record<string, AUInfo>;
+/** Default mix weights (0 = morph only, 1 = bone only) */
+declare const AU_MIX_DEFAULTS: Record<number, number>;
+/** Exact mesh name -> category mapping from the character GLB */
+declare const CC4_MESHES: Record<string, MeshInfo>;
+/** Which mesh each morph category applies to */
+declare const MORPH_TO_MESH: Record<MorphCategory, string[]>;
+declare const CC4_PRESET: Profile;
+
+/**
+ * Merge a base preset with a profile override.
+ *
+ * Rules:
+ * - Scalars: override if provided.
+ * - Maps: shallow-merged by key (override wins), values cloned.
+ * - Arrays: replaced when override is provided (except annotationRegions).
+ * - annotationRegions: merged by region name, shallow field merge (override wins).
+ */
+declare function resolveProfile(base: Profile, override: Partial<Profile>): Profile;
+
+declare const BETTA_FISH_PRESET: {
+    name: string;
+    animalType: string;
+    emoji: string;
+    bones: readonly ["Armature_rootJoint", "Bone_Armature", "Bone.001_Armature", "Bone.009_Armature", "Bone.027_Armature", "Bone.029_Armature", "Bone.031_Armature", "Bone.028_Armature", "Bone.030_Armature", "Bone.032_Armature", "Bone.010_Armature", "Bone.012_Armature", "Bone.014_Armature", "Bone.016_Armature", "Bone.011_Armature", "Bone.013_Armature", "Bone.015_Armature", "Bone.017_Armature", "Bone.002_Armature", "Bone.003_Armature", "Bone.004_Armature", "Bone.005_Armature", "Bone.020_Armature", "Bone.025_Armature", "Bone.026_Armature", "Bone.039_Armature", "Bone.040_Armature", "Bone.041_Armature", "Bone.042_Armature", "Bone.043_Armature", "Bone.044_Armature", "Bone.045_Armature", "Bone.019_Armature", "Bone.023_Armature", "Bone.024_Armature", "Bone.034_Armature", "Bone.036_Armature", "Bone.038_Armature", "Bone.018_Armature", "Bone.021_Armature", "Bone.022_Armature", "Bone.033_Armature", "Bone.035_Armature", "Bone.037_Armature", "Bone.046_Armature", "Bone.048_Armature", "Bone.050_Armature", "Bone.047_Armature", "Bone.049_Armature", "Bone.051_Armature", "Bone.006_Armature", "Bone.007_Armature", "Bone.008_Armature"];
+    boneNodes: {
+        readonly ROOT: "Armature_rootJoint";
+        readonly BODY_ROOT: "Bone_Armature";
+        readonly HEAD: "001";
+        readonly BODY_FRONT: "002";
+        readonly BODY_MID: "003";
+        readonly BODY_BACK: "004";
+        readonly TAIL_BASE: "005";
+        readonly GILL_L: "046";
+        readonly GILL_L_MID: "048";
+        readonly GILL_L_TIP: "050";
+        readonly GILL_R: "047";
+        readonly GILL_R_MID: "049";
+        readonly GILL_R_TIP: "051";
+        readonly DORSAL_ROOT: "006";
+        readonly DORSAL_L: "007";
+        readonly DORSAL_R: "008";
+        readonly VENTRAL_L: "018";
+        readonly VENTRAL_L_MID: "021";
+        readonly VENTRAL_L_TIP: "022";
+        readonly VENTRAL_R: "033";
+        readonly VENTRAL_R_MID: "035";
+        readonly VENTRAL_R_TIP: "037";
+        readonly PECTORAL_L_ROOT: "009";
+        readonly PECTORAL_L_CHAIN1: "027";
+        readonly PECTORAL_L_CHAIN1_MID: "029";
+        readonly PECTORAL_L_CHAIN1_TIP: "031";
+        readonly PECTORAL_L_CHAIN2: "028";
+        readonly PECTORAL_L_CHAIN2_MID: "030";
+        readonly PECTORAL_L_CHAIN2_TIP: "032";
+        readonly PECTORAL_R_ROOT: "010";
+        readonly PECTORAL_R_CHAIN1: "012";
+        readonly PECTORAL_R_CHAIN1_A: "014";
+        readonly PECTORAL_R_CHAIN1_B: "016";
+        readonly PECTORAL_R_ROOT2: "011";
+        readonly PECTORAL_R_CHAIN2: "013";
+        readonly PECTORAL_R_CHAIN2_A: "015";
+        readonly PECTORAL_R_CHAIN2_B: "017";
+        readonly EYE_L: "EYES_0";
+        readonly EYE_R: "EYES_0";
+        readonly TAIL_TOP: "020";
+        readonly TAIL_TOP_MID: "025";
+        readonly TAIL_TOP_TIP: "026";
+        readonly TAIL_MID: "039";
+        readonly TAIL_MID_A: "040";
+        readonly TAIL_MID_A_TIP: "041";
+        readonly TAIL_MID_B: "042";
+        readonly TAIL_MID_B_TIP: "043";
+        readonly TAIL_MID_C: "044";
+        readonly TAIL_MID_C_TIP: "045";
+        readonly TAIL_SIDE_L: "019";
+        readonly TAIL_SIDE_L_MID: "023";
+        readonly TAIL_SIDE_L_TIP: "024";
+        readonly TAIL_SIDE_R: "034";
+        readonly TAIL_SIDE_R_MID: "036";
+        readonly TAIL_SIDE_R_TIP: "038";
+    };
+    boneBindings: Record<number, BoneBinding[]>;
+    actionInfo: Record<string, AUInfo>;
+    eyeMeshNodes: {
+        readonly LEFT: "EYES_0";
+        readonly RIGHT: "EYES_0";
+    };
+    auToMorphs: Record<number, MorphTargetsBySide>;
+    morphToMesh: Record<string, string[]>;
+    visemeKeys: string[];
+};
+declare const AU_MAPPING_CONFIG: {
+    name: string;
+    animalType: string;
+    emoji: string;
+    auToBones: Record<number, BoneBinding[]>;
+    boneNodes: {
+        readonly ROOT: "Armature_rootJoint";
+        readonly BODY_ROOT: "Bone_Armature";
+        readonly HEAD: "001";
+        readonly BODY_FRONT: "002";
+        readonly BODY_MID: "003";
+        readonly BODY_BACK: "004";
+        readonly TAIL_BASE: "005";
+        readonly GILL_L: "046";
+        readonly GILL_L_MID: "048";
+        readonly GILL_L_TIP: "050";
+        readonly GILL_R: "047";
+        readonly GILL_R_MID: "049";
+        readonly GILL_R_TIP: "051";
+        readonly DORSAL_ROOT: "006";
+        readonly DORSAL_L: "007";
+        readonly DORSAL_R: "008";
+        readonly VENTRAL_L: "018";
+        readonly VENTRAL_L_MID: "021";
+        readonly VENTRAL_L_TIP: "022";
+        readonly VENTRAL_R: "033";
+        readonly VENTRAL_R_MID: "035";
+        readonly VENTRAL_R_TIP: "037";
+        readonly PECTORAL_L_ROOT: "009";
+        readonly PECTORAL_L_CHAIN1: "027";
+        readonly PECTORAL_L_CHAIN1_MID: "029";
+        readonly PECTORAL_L_CHAIN1_TIP: "031";
+        readonly PECTORAL_L_CHAIN2: "028";
+        readonly PECTORAL_L_CHAIN2_MID: "030";
+        readonly PECTORAL_L_CHAIN2_TIP: "032";
+        readonly PECTORAL_R_ROOT: "010";
+        readonly PECTORAL_R_CHAIN1: "012";
+        readonly PECTORAL_R_CHAIN1_A: "014";
+        readonly PECTORAL_R_CHAIN1_B: "016";
+        readonly PECTORAL_R_ROOT2: "011";
+        readonly PECTORAL_R_CHAIN2: "013";
+        readonly PECTORAL_R_CHAIN2_A: "015";
+        readonly PECTORAL_R_CHAIN2_B: "017";
+        readonly EYE_L: "EYES_0";
+        readonly EYE_R: "EYES_0";
+        readonly TAIL_TOP: "020";
+        readonly TAIL_TOP_MID: "025";
+        readonly TAIL_TOP_TIP: "026";
+        readonly TAIL_MID: "039";
+        readonly TAIL_MID_A: "040";
+        readonly TAIL_MID_A_TIP: "041";
+        readonly TAIL_MID_B: "042";
+        readonly TAIL_MID_B_TIP: "043";
+        readonly TAIL_MID_C: "044";
+        readonly TAIL_MID_C_TIP: "045";
+        readonly TAIL_SIDE_L: "019";
+        readonly TAIL_SIDE_L_MID: "023";
+        readonly TAIL_SIDE_L_TIP: "024";
+        readonly TAIL_SIDE_R: "034";
+        readonly TAIL_SIDE_R_MID: "036";
+        readonly TAIL_SIDE_R_TIP: "038";
+    };
+    bonePrefix: string;
+    boneSuffix: string;
+    suffixPattern: string;
+    auToMorphs: Record<number, MorphTargetsBySide>;
+    morphToMesh: Record<string, string[]>;
+    visemeKeys: string[];
+    auInfo: Record<string, AUInfo>;
+    compositeRotations: CompositeRotation[];
+    eyeMeshNodes: {
+        readonly LEFT: "EYES_0";
+        readonly RIGHT: "EYES_0";
+    };
+    meshes: Record<string, MeshInfo>;
+    auMixDefaults: Record<number, number>;
+    continuumPairs: Record<number, {
+        pairId: number;
+        isNegative: boolean;
+        axis: "pitch" | "yaw" | "roll";
+        node: string;
+    }>;
+    continuumLabels: Record<string, string>;
+};
+
+/**
+ * Preset types that can be passed to Loom3
+ */
+type PresetType = 'cc4' | 'skeletal' | 'fish' | 'custom';
+/**
+ * Resolve a preset by type name.
+ * This allows frontend to pass a string instead of importing the full preset.
+ */
+declare function resolvePreset(presetType: PresetType | string | undefined): Profile | {
+    name: string;
+    animalType: string;
+    emoji: string;
+    auToBones: Record<number, BoneBinding[]>;
+    boneNodes: {
+        readonly ROOT: "Armature_rootJoint";
+        readonly BODY_ROOT: "Bone_Armature";
+        readonly HEAD: "001";
+        readonly BODY_FRONT: "002";
+        readonly BODY_MID: "003";
+        readonly BODY_BACK: "004";
+        readonly TAIL_BASE: "005";
+        readonly GILL_L: "046";
+        readonly GILL_L_MID: "048";
+        readonly GILL_L_TIP: "050";
+        readonly GILL_R: "047";
+        readonly GILL_R_MID: "049";
+        readonly GILL_R_TIP: "051";
+        readonly DORSAL_ROOT: "006";
+        readonly DORSAL_L: "007";
+        readonly DORSAL_R: "008";
+        readonly VENTRAL_L: "018";
+        readonly VENTRAL_L_MID: "021";
+        readonly VENTRAL_L_TIP: "022";
+        readonly VENTRAL_R: "033";
+        readonly VENTRAL_R_MID: "035";
+        readonly VENTRAL_R_TIP: "037";
+        readonly PECTORAL_L_ROOT: "009";
+        readonly PECTORAL_L_CHAIN1: "027";
+        readonly PECTORAL_L_CHAIN1_MID: "029";
+        readonly PECTORAL_L_CHAIN1_TIP: "031";
+        readonly PECTORAL_L_CHAIN2: "028";
+        readonly PECTORAL_L_CHAIN2_MID: "030";
+        readonly PECTORAL_L_CHAIN2_TIP: "032";
+        readonly PECTORAL_R_ROOT: "010";
+        readonly PECTORAL_R_CHAIN1: "012";
+        readonly PECTORAL_R_CHAIN1_A: "014";
+        readonly PECTORAL_R_CHAIN1_B: "016";
+        readonly PECTORAL_R_ROOT2: "011";
+        readonly PECTORAL_R_CHAIN2: "013";
+        readonly PECTORAL_R_CHAIN2_A: "015";
+        readonly PECTORAL_R_CHAIN2_B: "017";
+        readonly EYE_L: "EYES_0";
+        readonly EYE_R: "EYES_0";
+        readonly TAIL_TOP: "020";
+        readonly TAIL_TOP_MID: "025";
+        readonly TAIL_TOP_TIP: "026";
+        readonly TAIL_MID: "039";
+        readonly TAIL_MID_A: "040";
+        readonly TAIL_MID_A_TIP: "041";
+        readonly TAIL_MID_B: "042";
+        readonly TAIL_MID_B_TIP: "043";
+        readonly TAIL_MID_C: "044";
+        readonly TAIL_MID_C_TIP: "045";
+        readonly TAIL_SIDE_L: "019";
+        readonly TAIL_SIDE_L_MID: "023";
+        readonly TAIL_SIDE_L_TIP: "024";
+        readonly TAIL_SIDE_R: "034";
+        readonly TAIL_SIDE_R_MID: "036";
+        readonly TAIL_SIDE_R_TIP: "038";
+    };
+    bonePrefix: string;
+    boneSuffix: string;
+    suffixPattern: string;
+    auToMorphs: Record<number, MorphTargetsBySide>;
+    morphToMesh: Record<string, string[]>;
+    visemeKeys: string[];
+    auInfo: Record<string, AUInfo>;
+    compositeRotations: CompositeRotation[];
+    eyeMeshNodes: {
+        readonly LEFT: "EYES_0";
+        readonly RIGHT: "EYES_0";
+    };
+    meshes: Record<string, MeshInfo>;
+    auMixDefaults: Record<number, number>;
+    continuumPairs: Record<number, {
+        pairId: number;
+        isNegative: boolean;
+        axis: "pitch" | "yaw" | "roll";
+        node: string;
+    }>;
+    continuumLabels: Record<string, string>;
+};
+/**
+ * Resolve a preset and merge optional overrides.
+ */
+declare function resolvePresetWithOverrides(presetType: PresetType | string | undefined, overrides?: Partial<Profile>): Profile;
+
+/**
+ * Loom3 - Core Type Definitions
+ *
+ * Type definitions for the 3D character animation engine.
+ * These are framework-agnostic interfaces that work with any 3D engine.
+ */
+/**
+ * TransitionHandle - returned from transition methods
+ * Provides promise-based completion notification plus fine-grained control.
+ */
+interface TransitionHandle {
+    /** Resolves when the transition completes (or is cancelled) */
+    promise: Promise<void>;
+    /** Pause this transition (holds at current value) */
+    pause: () => void;
+    /** Resume this transition after pause */
+    resume: () => void;
+    /** Cancel this transition immediately (resolves promise) */
+    cancel: () => void;
+}
+/** Standard bone keys used in AU bindings */
+type BoneKey = 'EYE_L' | 'EYE_R' | 'JAW' | 'HEAD' | 'NECK' | 'TONGUE' | string;
+/**
+ * BoneBinding - Defines how an AU maps to bone transformations
+ */
+interface BoneBinding {
+    node: BoneKey;
+    channel: 'rx' | 'ry' | 'rz' | 'tx' | 'ty' | 'tz';
+    scale: -1 | 1;
+    maxDegrees?: number;
+    maxUnits?: number;
+    /** Optional side hint for balance-aware AUs. */
+    side?: 'left' | 'right';
+}
+/**
+ * RotationAxis - Defines which AUs control a specific rotation axis
+ */
+interface RotationAxis {
+    aus: number[];
+    axis: 'rx' | 'ry' | 'rz';
+    negative?: number;
+    positive?: number;
+}
+/**
+ * CompositeRotation - Defines unified rotation axes for bones
+ */
+interface CompositeRotation {
+    node: string;
+    pitch: RotationAxis | null;
+    yaw: RotationAxis | null;
+    roll: RotationAxis | null;
+}
+/**
+ * AUInfo - Metadata about an Action Unit
+ */
+interface AUInfo {
+    id: string;
+    name: string;
+    muscularBasis?: string;
+    links?: string[];
+    faceArea?: 'Upper' | 'Lower';
+    facePart?: string;
+}
+/** Per-axis rotation state - simple -1 to 1 values like stable version */
+interface CompositeRotationState {
+    pitch: number;
+    yaw: number;
+    roll: number;
+}
+type RotationsState = Record<string, CompositeRotationState>;
+/**
+ * Options for playing a baked animation clip.
+ */
+interface AnimationPlayOptions {
+    /** Playback speed multiplier (default: 1.0) */
+    speed?: number;
+    /** Animation intensity/weight (0-1, default: 1.0) */
+    intensity?: number;
+    /** Whether the animation should loop (default: true) */
+    loop?: boolean;
+    /** Loop mode: 'repeat' (restart from beginning), 'pingpong' (reverse direction), 'once' (no loop) */
+    loopMode?: 'repeat' | 'pingpong' | 'once';
+    /** Number of repetitions when looping (default: Infinity for repeat/pingpong) */
+    repeatCount?: number;
+    /** Crossfade duration in seconds when transitioning from another animation (default: 0.3) */
+    crossfadeDuration?: number;
+    /** Clamp animation at end when not looping (default: true) */
+    clampWhenFinished?: boolean;
+    /** Start time offset in seconds (default: 0) */
+    startTime?: number;
+}
+/**
+ * Information about a loaded animation clip.
+ */
+interface AnimationClipInfo {
+    /** Name of the animation clip */
+    name: string;
+    /** Duration of the animation in seconds */
+    duration: number;
+    /** Number of tracks (bones/morphs being animated) */
+    trackCount: number;
+}
+/**
+ * State of a currently playing animation.
+ */
+interface AnimationState {
+    /** Name of the animation */
+    name: string;
+    /** Whether the animation is currently playing */
+    isPlaying: boolean;
+    /** Whether the animation is paused */
+    isPaused: boolean;
+    /** Current playback time in seconds */
+    time: number;
+    /** Duration of the animation in seconds */
+    duration: number;
+    /** Current playback speed */
+    speed: number;
+    /** Current weight/intensity (0-1) */
+    weight: number;
+    /** Whether the animation is looping */
+    isLooping: boolean;
+}
+/**
+ * Handle returned when playing an animation, providing control methods.
+ */
+interface AnimationActionHandle {
+    /** Stop the animation */
+    stop: () => void;
+    /** Pause the animation */
+    pause: () => void;
+    /** Resume a paused animation */
+    resume: () => void;
+    /** Set playback speed */
+    setSpeed: (speed: number) => void;
+    /** Set animation weight/intensity (0-1) */
+    setWeight: (weight: number) => void;
+    /** Seek to a specific time in seconds */
+    seekTo: (time: number) => void;
+    /** Get current animation state */
+    getState: () => AnimationState;
+    /** Crossfade to another animation */
+    crossfadeTo: (clipName: string, duration?: number) => AnimationActionHandle | null;
+    /** Promise that resolves when animation completes (only for non-looping) */
+    finished: Promise<void>;
+}
+/**
+ * A single keyframe point in an animation curve.
+ */
+interface CurvePoint {
+    /** Time in seconds */
+    time: number;
+    /** Intensity value (0-1) */
+    intensity: number;
+    /** When true, inherit current AU value at playback start */
+    inherit?: boolean;
+}
+/**
+ * Map of curve IDs (AU numbers or morph names) to keyframe arrays.
+ */
+type CurvesMap = Record<string, CurvePoint[]>;
+/**
+ * Options for building and playing a clip from curves.
+ */
+interface ClipOptions {
+    /** Whether the clip should loop (default: false) */
+    loop?: boolean;
+    /** Loop mode: repeat (default), pingpong (forward/back), or once */
+    loopMode?: 'repeat' | 'pingpong' | 'once';
+    /** Number of repetitions when looping (default: Infinity for repeat/pingpong) */
+    repeatCount?: number;
+    /** Playback rate multiplier (default: 1.0) */
+    playbackRate?: number;
+    /** Play clip backwards when true (implemented via negative time scale) */
+    reverse?: boolean;
+    /** Mixer weight/intensity (default: 1.0) */
+    mixerWeight?: number;
+    /** Left/right balance for bilateral AUs (-1 to 1, default: 0) */
+    balance?: number;
+    /** Jaw scale for viseme playback (default: 1.0) */
+    jawScale?: number;
+    /** Intensity scale multiplier (default: 1.0) */
+    intensityScale?: number;
+    /** Optional morph target mesh names to constrain track creation */
+    meshNames?: string[];
+    /** Snippet category - when 'visemeSnippet', numeric curve IDs (0-14) are viseme indices; otherwise they're AU IDs */
+    snippetCategory?: 'auSnippet' | 'visemeSnippet';
+    /**
+     * When true, automatically generate jaw bone rotation from viseme curves.
+     * Uses VISEME_JAW_AMOUNTS to determine jaw opening per viseme index.
+     * Only applies when snippetCategory is 'visemeSnippet'.
+     * Default: true (for backwards compatibility with transitionViseme behavior)
+     */
+    autoVisemeJaw?: boolean;
+}
+/**
+ * Handle returned when playing a dynamically-built clip.
+ */
+interface ClipHandle {
+    /** Name of the clip */
+    clipName: string;
+    /** Optional unique id for the underlying mixer action */
+    actionId?: string;
+    /** Start or restart playback */
+    play: () => void;
+    /** Stop playback and reset */
+    stop: () => void;
+    /** Pause playback at current position */
+    pause: () => void;
+    /** Resume paused playback */
+    resume: () => void;
+    /** Optional weight setter for live mixer updates */
+    setWeight?: (w: number) => void;
+    /** Optional playback-rate setter for live mixer updates */
+    setPlaybackRate?: (r: number) => void;
+    /** Optional loop setter for live mixer updates */
+    setLoop?: (mode: 'once' | 'repeat' | 'pingpong', repeatCount?: number) => void;
+    /** Optional time setter for scrubbing */
+    setTime?: (time: number) => void;
+    /** Get current playback time in seconds */
+    getTime: () => number;
+    /** Get total clip duration in seconds */
+    getDuration: () => number;
+    /** Promise that resolves when clip finishes (non-looping only) */
+    finished: Promise<void>;
+}
+/**
+ * Snippet definition for animation playback.
+ * Can be loaded from JSON and converted to a mixer clip.
+ */
+interface Snippet {
+    /** Unique name for this snippet */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Map of AU/morph IDs to keyframe curves */
+    curves: CurvesMap;
+    /** Category for grouping (e.g., 'eyeHeadTracking', 'visemeSnippet') */
+    snippetCategory?: string;
+    /** Priority for scheduling conflicts */
+    snippetPriority?: number;
+    /** Whether to loop playback */
+    loop?: boolean;
+}
+
+/**
+ * Loom3 - Profile Types
+ *
+ * Type definitions for character profiles.
+ * Profiles define how Action Units map to morphs/bones for a specific rig.
+ */
+
+/**
+ * Profile - Complete configuration for AU-to-morph/bone mappings
+ *
+ * This is the main configuration object that defines how Action Units
+ * map to morph targets and bone transformations for a specific rig type.
+ */
+interface Profile {
+    /** Human-readable name for this profile (e.g., 'Character Creator 4', 'Betta Fish') */
+    name?: string;
+    /** Type of animal/creature this profile is for (e.g., 'human', 'fish', 'dog') */
+    animalType?: string;
+    /** Emoji representing this animal type (e.g., '😊' for human, '🐟' for fish) */
+    emoji?: string;
+    /** AU ID to morph target names split by side */
+    auToMorphs: Record<number, MorphTargetsBySide>;
+    /** AU ID to bone bindings (e.g., AU 51 → [{ node: 'HEAD', channel: 'ry', scale: 1, maxDegrees: 30 }]) */
+    auToBones: Record<number, BoneBinding[]>;
+    /** Bone key to actual node name in the model (e.g., 'HEAD' → 'Head' or 'CC_Base_Head') */
+    boneNodes: Record<string, string>;
+    /**
+     * Optional: Prefix to prepend to bone names when resolving nodes.
+     * If set, boneNodes should contain base names without prefix (e.g., 'Head' instead of 'CC_Base_Head').
+     * The engine will try: prefix + baseName + suffix, then fuzzy match with suffixPattern.
+     */
+    bonePrefix?: string;
+    /**
+     * Optional: Suffix to append to bone names when resolving nodes.
+     * Combined with bonePrefix: prefix + baseName + suffix (e.g., 'Bone.' + '001' + '_Armature' = 'Bone.001_Armature')
+     */
+    boneSuffix?: string;
+    /**
+     * Optional: Prefix to prepend to morph target names when resolving.
+     * Similar to bonePrefix but for morph targets.
+     */
+    morphPrefix?: string;
+    /**
+     * Optional: Suffix to append to morph target names when resolving.
+     * Similar to boneSuffix but for morph targets.
+     */
+    morphSuffix?: string;
+    /**
+     * Optional: Regex pattern string for fuzzy matching bone/morph names with suffixes.
+     * Common patterns: "_\\d+$" for numbered suffixes (_01, _038), "\\.\\d+$" for Blender (.001)
+     * When set, the engine will try exact match first, then fuzzy match using this pattern.
+     */
+    suffixPattern?: string;
+    /**
+     * Optional: Suffixes that indicate left-side morph targets.
+     * Used for auto-detecting laterality in the mapping editor.
+     * Default: ['_L', ' L']
+     */
+    leftMorphSuffixes?: string[];
+    /**
+     * Optional: Suffixes that indicate right-side morph targets.
+     * Used for auto-detecting laterality in the mapping editor.
+     * Default: ['_R', ' R']
+     */
+    rightMorphSuffixes?: string[];
+    /** Morph category to mesh names (e.g., 'face' → ['CC_Base_Body_1']) */
+    morphToMesh: Record<string, string[]>;
+    /** Viseme targets in order (typically 15 phoneme positions) */
+    visemeKeys: MorphTargetRef[];
+    /** Optional: Jaw opening amounts per viseme index (0-1). Used for auto-generating jaw rotation in clips. */
+    visemeJawAmounts?: number[];
+    /** Optional: Default mix weights for bone/morph blending (0 = morph only, 1 = bone only) */
+    auMixDefaults?: Record<number, number>;
+    /** Optional: AU metadata (names, muscle basis, etc.) */
+    auInfo?: Record<string, AUInfo>;
+    /** Optional: Eye mesh node fallbacks (some rigs use mesh nodes instead of bone nodes) */
+    eyeMeshNodes?: {
+        LEFT: string;
+        RIGHT: string;
+    };
+    /** Optional: Composite rotation definitions for bones (defaults to CC4 composites) */
+    compositeRotations?: CompositeRotation[];
+    /** Optional: Mesh info for material settings (depthWrite, blending, renderOrder, etc.) */
+    meshes?: Record<string, MeshInfo>;
+    /**
+     * Optional: Continuum pair mappings for bidirectional AU axes.
+     * Maps AU ID to its partner info (pairId, isNegative, axis, node).
+     * Enables negative value shorthand: setAU(51, -0.5) activates AU 52 at 0.5
+     */
+    continuumPairs?: Record<number, {
+        pairId: number;
+        isNegative: boolean;
+        axis: 'pitch' | 'yaw' | 'roll';
+        node: string;
+    }>;
+    /**
+     * Optional: Human-readable labels for continuum pairs.
+     * Key format: "negativeAU-positiveAU" (e.g., "51-52")
+     * Value: Display label (e.g., "Head Turn — Left ↔ Right")
+     */
+    continuumLabels?: Record<string, string>;
+    /**
+     * Optional: Annotation regions for camera/marker overlays.
+     */
+    annotationRegions?: AnnotationRegion[];
+    /**
+     * Optional: Hair physics defaults for this preset/profile.
+     */
+    hairPhysics?: HairPhysicsProfileConfig;
+}
+/**
+ * Hair physics morph mapping axis types.
+ */
+type HairMorphAxis = 'yaw' | 'pitch' | 'roll';
+/**
+ * Single morph target mapping with axis metadata.
+ */
+interface HairMorphTargetMapping {
+    key: string;
+    axis: HairMorphAxis;
+}
+/**
+ * Morph target mapping with axis metadata and intensity value.
+ */
+interface HairMorphTargetValueMapping {
+    value: number;
+    axis: HairMorphAxis;
+}
+/**
+ * Hair physics defaults stored in presets/profiles.
+ */
+interface HairPhysicsProfileConfig {
+    stiffness?: number;
+    damping?: number;
+    inertia?: number;
+    gravity?: number;
+    responseScale?: number;
+    idleSwayAmount?: number;
+    idleSwaySpeed?: number;
+    windStrength?: number;
+    windDirectionX?: number;
+    windDirectionZ?: number;
+    windTurbulence?: number;
+    windFrequency?: number;
+    idleClipDuration?: number;
+    impulseClipDuration?: number;
+    direction?: {
+        yawSign?: 1 | -1;
+        pitchSign?: 1 | -1;
+    };
+    morphTargets?: {
+        swayLeft?: HairMorphTargetMapping;
+        swayRight?: HairMorphTargetMapping;
+        swayFront?: HairMorphTargetMapping;
+        fluffRight?: HairMorphTargetMapping;
+        fluffBottom?: HairMorphTargetMapping;
+        headUp?: Record<string, HairMorphTargetValueMapping>;
+        headDown?: Record<string, HairMorphTargetValueMapping>;
+    };
+}
+/**
+ * Annotation region definition for camera markers.
+ */
+interface AnnotationRegion {
+    name: string;
+    bones?: string[];
+    meshes?: string[];
+    objects?: string[];
+    paddingFactor?: number;
+    cameraAngle?: number;
+    cameraOffset?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    parent?: string;
+    children?: string[];
+    expandAnimation?: 'outward' | 'staggered';
+    showChildConnections?: boolean;
+    style?: {
+        markerColor?: number;
+        markerRadius?: number;
+        lineColor?: number;
+        labelColor?: string;
+        labelBackground?: string;
+        labelFontSize?: number;
+        opacity?: number;
+        lineDirection?: 'radial' | 'camera' | 'up' | 'down' | 'left' | 'right' | 'forward' | 'backward' | {
+            x: number;
+            y: number;
+            z: number;
+        };
+        line?: {
+            style?: 'solid' | 'dashed' | 'dotted';
+            curve?: 'straight' | 'bezier' | 'arc';
+            arrowHead?: boolean;
+            thickness?: number;
+            length?: number;
+        };
+    };
+    groupId?: string;
+    isFallback?: boolean;
+}
+/**
+ * Morph target key (name in morphTargetDictionary).
+ */
+type MorphTargetKey = string;
+/**
+ * Morph target index (morphTargetInfluences slot).
+ */
+type MorphTargetIndex = number;
+/**
+ * Morph target reference (key or index).
+ */
+type MorphTargetRef = MorphTargetKey | MorphTargetIndex;
+interface MorphTargetsBySide {
+    left: MorphTargetRef[];
+    right: MorphTargetRef[];
+    center: MorphTargetRef[];
+}
+/**
+ * Helper type for mesh categories in morphToMesh
+ */
+type MorphCategory = 'face' | 'viseme' | 'eye' | 'tongue' | 'hair';
+/**
+ * Mesh category types for character mesh classification
+ */
+type MeshCategory = 'body' | 'eye' | 'eyeOcclusion' | 'tearLine' | 'teeth' | 'tongue' | 'hair' | 'eyebrow' | 'cornea' | 'eyelash';
+/**
+ * Blending mode names (matches Three.js constants)
+ */
+type BlendingMode = 'Normal' | 'Additive' | 'Subtractive' | 'Multiply' | 'None';
+/**
+ * Blending mode options for Three.js materials
+ * Maps mode name to Three.js blending constant value
+ */
+declare const BLENDING_MODES: Record<BlendingMode, number>;
+/**
+ * Material settings for mesh rendering
+ */
+interface MeshMaterialSettings {
+    renderOrder?: number;
+    transparent?: boolean;
+    opacity?: number;
+    depthWrite?: boolean;
+    depthTest?: boolean;
+    blending?: BlendingMode;
+}
+/**
+ * Mesh info including category, morph count, and optional material settings.
+ * Used in presets, profiles, and runtime.
+ */
+interface MeshInfo {
+    name?: string;
+    visible?: boolean;
+    category: MeshCategory;
+    morphCount: number;
+    material?: MeshMaterialSettings;
+}
+
+/**
+ * Animation Interface
+ *
+ * Groups AU/morph/viseme methods, transitions, and mixer playback.
+ */
+
+/** Loop mode for mixer clips */
+type MixerLoopMode = 'once' | 'repeat' | 'pingpong';
+interface Animation {
+    /**
+     * Set AU value immediately (no transition)
+     * @param id - AU number (e.g., 12 for smile) or string ('12L' for left side)
+     * @param v - Value 0-1
+     * @param balance - Optional L/R balance: -1 = left only, 0 = both, +1 = right only
+     */
+    setAU(id: number | string, v: number, balance?: number): void;
+    /**
+     * Transition AU value smoothly over time
+     * @param id - AU number or string
+     * @param to - Target value 0-1
+     * @param durationMs - Transition duration in milliseconds
+     * @param balance - Optional L/R balance
+     */
+    transitionAU(id: number | string, to: number, durationMs?: number, balance?: number): TransitionHandle;
+    /**
+     * Get current AU value (from cached auValues)
+     */
+    getAU(id: number): number;
+    /**
+     * Set a continuum AU pair immediately (no animation).
+     * @param negAU - AU ID for negative direction (e.g., 61 for eyes left)
+     * @param posAU - AU ID for positive direction (e.g., 62 for eyes right)
+     * @param continuumValue - Value from -1 (full negative) to +1 (full positive)
+     * @param balance - Optional L/R balance for bilateral morphs
+     */
+    setContinuum(negAU: number, posAU: number, continuumValue: number, balance?: number): void;
+    /**
+     * Smoothly transition a continuum AU pair (e.g., eyes left/right, head up/down).
+     * @param negAU - AU ID for negative direction
+     * @param posAU - AU ID for positive direction
+     * @param continuumValue - Target value from -1 (full negative) to +1 (full positive)
+     * @param durationMs - Transition duration in milliseconds
+     * @param balance - Optional L/R balance for bilateral morphs
+     */
+    transitionContinuum(negAU: number, posAU: number, continuumValue: number, durationMs?: number, balance?: number): TransitionHandle;
+    /**
+     * Set morph target value immediately (by key)
+     * @param key - Morph target name (morphTargetDictionary key)
+     * @param v - Value 0-1
+     * @param meshNames - Optional specific meshes to target
+     */
+    setMorph(key: string, v: number, meshNames?: string[]): void;
+    /**
+     * Set morph influence value immediately (by index)
+     * @param index - Morph target index (morphTargetInfluences slot)
+     * @param v - Value 0-1
+     * @param meshNames - Optional specific meshes to target
+     */
+    setMorphInfluence(index: number, v: number, meshNames?: string[]): void;
+    /**
+     * Transition morph target value smoothly (by key)
+     * @param key - Morph target name (morphTargetDictionary key)
+     * @param to - Target value 0-1
+     * @param durationMs - Transition duration in milliseconds
+     * @param meshNames - Optional specific meshes to target
+     */
+    transitionMorph(key: string, to: number, durationMs?: number, meshNames?: string[]): TransitionHandle;
+    /**
+     * Transition morph influence value smoothly (by index)
+     * @param index - Morph target index (morphTargetInfluences slot)
+     * @param to - Target value 0-1
+     * @param durationMs - Transition duration in milliseconds
+     * @param meshNames - Optional specific meshes to target
+     */
+    transitionMorphInfluence(index: number, to: number, durationMs?: number, meshNames?: string[]): TransitionHandle;
+    /**
+     * Set viseme value immediately (for lip-sync)
+     * @param visemeIndex - Viseme index 0-14
+     * @param value - Value 0-1
+     * @param jawScale - Jaw movement multiplier (default 1.0)
+     */
+    setViseme(visemeIndex: number, value: number, jawScale?: number): void;
+    /**
+     * Transition viseme value smoothly
+     */
+    transitionViseme(visemeIndex: number, to: number, durationMs?: number, jawScale?: number): TransitionHandle;
+    /**
+     * Set mix weight for an AU (blend between morph and bone contribution)
+     */
+    setAUMixWeight(id: number, weight: number): void;
+    /**
+     * Get current mix weight for an AU
+     */
+    getAUMixWeight(id: number): number;
+    /**
+     * Check if an AU has bilateral bone bindings (L and R nodes)
+     * Used to determine if a balance slider should be shown for bone-only bilateral AUs
+     */
+    hasLeftRightBones(auId: number): boolean;
+    /**
+     * Pause all transitions
+     */
+    pause(): void;
+    /**
+     * Resume all transitions
+     */
+    resume(): void;
+    /**
+     * Check if engine is paused
+     */
+    getPaused(): boolean;
+    /**
+     * Clear all active transitions
+     */
+    clearTransitions(): void;
+    /**
+     * Get count of active transitions
+     */
+    getActiveTransitionCount(): number;
+    /**
+     * Reset all facial animation to neutral state
+     */
+    resetToNeutral(): void;
+    /**
+     * Load animation clips from a GLTF/GLB file.
+     * Call this after onReady() with the animations array from the GLTF loader.
+     * @param clips - Array of AnimationClip objects from GLTF loader
+     */
+    loadAnimationClips(clips: unknown[]): void;
+    /**
+     * Get list of all loaded animation clips.
+     */
+    getAnimationClips(): AnimationClipInfo[];
+    /**
+     * Play a baked animation by name.
+     * @param clipName - Name of the animation clip to play
+     * @param options - Playback options (speed, intensity, loop, etc.)
+     * @returns Handle for controlling the animation, or null if clip not found
+     */
+    playAnimation(clipName: string, options?: AnimationPlayOptions): AnimationActionHandle | null;
+    /**
+     * Stop a specific animation by name.
+     * @param clipName - Name of the animation to stop
+     */
+    stopAnimation(clipName: string): void;
+    /**
+     * Stop all currently playing animations.
+     */
+    stopAllAnimations(): void;
+    /**
+     * Pause a specific animation by name.
+     * @param clipName - Name of the animation to pause
+     */
+    pauseAnimation(clipName: string): void;
+    /**
+     * Resume a paused animation by name.
+     * @param clipName - Name of the animation to resume
+     */
+    resumeAnimation(clipName: string): void;
+    /**
+     * Pause all currently playing animations.
+     */
+    pauseAllAnimations(): void;
+    /**
+     * Resume all paused animations.
+     */
+    resumeAllAnimations(): void;
+    /**
+     * Set the playback speed for a specific animation.
+     * @param clipName - Name of the animation
+     * @param speed - Playback speed multiplier (1.0 = normal, 0.5 = half, 2.0 = double)
+     */
+    setAnimationSpeed(clipName: string, speed: number): void;
+    /**
+     * Set the intensity/weight for a specific animation.
+     * @param clipName - Name of the animation
+     * @param intensity - Weight value from 0 (no effect) to 1 (full effect)
+     */
+    setAnimationIntensity(clipName: string, intensity: number): void;
+    /**
+     * Set the global time scale for all animations.
+     * @param timeScale - Global time scale multiplier
+     */
+    setAnimationTimeScale(timeScale: number): void;
+    /**
+     * Get the current state of a specific animation.
+     * @param clipName - Name of the animation
+     * @returns Animation state or null if not found/playing
+     */
+    getAnimationState(clipName: string): AnimationState | null;
+    /**
+     * Get states of all currently playing animations.
+     */
+    getPlayingAnimations(): AnimationState[];
+    /**
+     * Crossfade from current animation(s) to a new animation.
+     * @param clipName - Name of the target animation
+     * @param duration - Crossfade duration in seconds
+     * @param options - Additional playback options for the target animation
+     */
+    crossfadeTo(clipName: string, duration?: number, options?: AnimationPlayOptions): AnimationActionHandle | null;
+    /**
+     * Get the composite rotations configuration for the current preset.
+     * Used by animation schedulers for coordinated head/eye movements.
+     */
+    getCompositeRotations(): CompositeRotation[];
+    /**
+     * Build and play an AnimationClip from curve data.
+     * Used by animation schedulers to convert keyframe data to mixer clips.
+     * @param clipName - Unique name for the clip
+     * @param curves - Map of curve IDs to keyframe arrays
+     * @param options - Playback options
+     * @returns Handle for controlling the clip, or null if not supported
+     */
+    buildClip(clipName: string, curves: Record<string, Array<CurvePoint>>, options?: ClipOptions): ClipHandle | null;
+    /**
+     * Update parameters on an active clip.
+     * @param name - Name of the clip to update
+     * @param params - Parameters to update
+     * @returns true if clip was found and updated
+     */
+    updateClipParams(name: string, params: {
+        weight?: number;
+        rate?: number;
+        loop?: boolean;
+        loopMode?: MixerLoopMode;
+        repeatCount?: number;
+        reverse?: boolean;
+        actionId?: string;
+    }): boolean;
+    /**
+     * Clean up resources for a snippet/clip.
+     * @param name - Name of the snippet to clean up
+     */
+    cleanupSnippet(name: string): void;
+    /**
+     * Check if the given curves can be played through buildClip.
+     * Returns false if curves contain bone-only AUs that can't be baked.
+     */
+    supportsClipCurves(curves: Record<string, Array<CurvePoint>>): boolean;
+    /**
+     * Callback when a snippet finishes playback.
+     * Used by animation schedulers for sequencing.
+     */
+    onSnippetEnd?(name: string): void;
+}
+
+/**
+ * Hair Interface
+ *
+ * Groups hair registration, styling, and physics methods.
+ */
+
+interface HairObjectRef {
+    name: string;
+    isMesh: boolean;
+    isEyebrow: boolean;
+}
+interface HairPhysicsDirectionConfig$1 {
+    yawSign: 1 | -1;
+    pitchSign: 1 | -1;
+}
+interface HairMorphTargetsConfig {
+    swayLeft: string;
+    swayRight: string;
+    swayFront: string;
+    fluffRight: string;
+    fluffBottom: string;
+    headUp: Record<string, number>;
+    headDown: Record<string, number>;
+}
+interface HairPhysicsRuntimeConfig {
+    stiffness: number;
+    damping: number;
+    inertia: number;
+    gravity: number;
+    responseScale: number;
+    idleSwayAmount: number;
+    idleSwaySpeed: number;
+    windStrength: number;
+    windDirectionX: number;
+    windDirectionZ: number;
+    windTurbulence: number;
+    windFrequency: number;
+    idleClipDuration: number;
+    impulseClipDuration: number;
+    direction: HairPhysicsDirectionConfig$1;
+    morphTargets: HairMorphTargetsConfig;
+}
+type HairPhysicsRuntimeConfigUpdate = Partial<HairPhysicsRuntimeConfig> & {
+    direction?: Partial<HairPhysicsDirectionConfig$1>;
+    morphTargets?: Partial<HairMorphTargetsConfig>;
+};
+interface HairObjectState {
+    color?: {
+        baseColor: string;
+        emissive: string;
+        emissiveIntensity: number;
+    };
+    outline?: {
+        show: boolean;
+        color: string;
+        opacity: number;
+    };
+    visible?: boolean;
+    scale?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    position?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    isEyebrow?: boolean;
+}
+interface Hair {
+    /**
+     * Register hair objects from a scene.
+     * Returns engine-agnostic references for UI and service layers.
+     */
+    registerHairObjects(objects: Object3D[]): HairObjectRef[];
+    /**
+     * Get hair objects registered in the engine.
+     */
+    getRegisteredHairObjects(): Mesh[];
+    /**
+     * Enable or disable hair physics simulation.
+     */
+    setHairPhysicsEnabled(enabled: boolean): void;
+    /**
+     * Check if hair physics is enabled.
+     */
+    isHairPhysicsEnabled(): boolean;
+    /**
+     * Update hair physics configuration.
+     */
+    setHairPhysicsConfig(config: HairPhysicsRuntimeConfigUpdate): void;
+    /**
+     * Get current hair physics configuration.
+     */
+    getHairPhysicsConfig(): HairPhysicsRuntimeConfig;
+    /**
+     * Validate hair morph target mappings against registered hair meshes.
+     * Returns a list of missing morph keys (if any).
+     */
+    validateHairMorphTargets(): string[];
+    /**
+     * Get head rotation values used for hair physics (range -1 to 1).
+     */
+    getHeadRotation(): {
+        yaw: number;
+        pitch: number;
+        roll: number;
+    };
+    /**
+     * Manually tick hair physics (optional).
+     */
+    updateHairPhysics(dt: number): void;
+    /**
+     * Get available hair morph targets for a mesh.
+     */
+    getHairMorphTargets(meshName?: string): string[];
+    /**
+     * Set morph targets on specific meshes.
+     */
+    setMorphOnMeshes(meshNames: string[], morphKey: string, value: number): void;
+    /**
+     * Apply hair/eyebrow styling state to a mesh.
+     */
+    applyHairStateToObject(objectName: string, state: HairObjectState): void;
+}
+
+/**
+ * LoomLarge Engine Interface
+ *
+ * Defines the contract for 3D character animation engines.
+ * Uses Three.js types directly - no framework abstraction overhead.
+ */
+
+/**
+ * Payload for initializing the engine with a loaded model
+ */
+interface ReadyPayload {
+    meshes: Mesh[];
+    model: Object3D;
+}
+/**
+ * Configuration options for the Loom3 engine
+ */
+interface LoomLargeConfig {
+    /** AU to morph target mappings (partial overrides merged via resolveProfile). */
+    profile?: Partial<Profile>;
+    /** Preset type to resolve if profile is not provided. */
+    presetType?: PresetType | string;
+}
+
+/**
+ * Loom3 Engine Interface
+ *
+ * The main interface for controlling 3D character facial animation.
+ * Supports Action Units (AUs), morph targets, visemes, and bone control.
+ */
+interface LoomLarge extends Animation, Hair {
+    /**
+     * Initialize the engine with a loaded model.
+     * Call this after loading your 3D model.
+     */
+    onReady(payload: ReadyPayload): void;
+    /**
+     * Update animation state. Call each frame with delta time in seconds.
+     * If using start(), this is called automatically.
+     */
+    update(deltaSeconds: number): void;
+    /**
+     * Start the internal animation loop (RAF-based).
+     * Automatically calls update() each frame with delta time.
+     */
+    start(): void;
+    /**
+     * Stop the internal animation loop.
+     */
+    stop(): void;
+    /**
+     * Dispose engine resources and cleanup.
+     * Stops the animation loop and clears all transitions.
+     */
+    dispose(): void;
+    /**
+     * Get list of all meshes in the model
+     */
+    getMeshList(): MeshInfo[];
+    /**
+     * Set mesh visibility
+     */
+    setMeshVisible(meshName: string, visible: boolean): void;
+    /**
+     * Highlight a mesh with an emissive glow effect
+     * @param meshName - Name of the mesh to highlight (null to clear all highlights)
+     * @param color - Highlight color (default: cyan)
+     * @param intensity - Emissive intensity (default: 0.5)
+     */
+    highlightMesh(meshName: string | null, color?: number, intensity?: number): void;
+    /**
+     * Update AU mappings configuration
+     */
+    setProfile(profile: Profile): void;
+    /**
+     * Get current AU mappings configuration
+     */
+    getProfile(): Profile;
+}
+type Loom3Config = LoomLargeConfig;
+
+type HairPhysicsDirectionConfig = {
+    yawSign: 1 | -1;
+    pitchSign: 1 | -1;
+};
+type HairMorphTargets = {
+    swayLeft: string;
+    swayRight: string;
+    swayFront: string;
+    fluffRight: string;
+    fluffBottom: string;
+    headUp: Record<string, number>;
+    headDown: Record<string, number>;
+};
+type HairPhysicsConfig$2 = {
+    stiffness: number;
+    damping: number;
+    inertia: number;
+    gravity: number;
+    responseScale: number;
+    idleSwayAmount: number;
+    idleSwaySpeed: number;
+    windStrength: number;
+    windDirectionX: number;
+    windDirectionZ: number;
+    windTurbulence: number;
+    windFrequency: number;
+    idleClipDuration: number;
+    impulseClipDuration: number;
+    direction: HairPhysicsDirectionConfig;
+    morphTargets: HairMorphTargets;
+};
+type HairPhysicsConfigUpdate = Partial<HairPhysicsConfig$2> & {
+    direction?: Partial<HairPhysicsDirectionConfig>;
+    morphTargets?: Partial<HairMorphTargets>;
+};
+
+/**
+ * Loom3 - Three.js Implementation
+ *
+ * Default implementation of the LoomLarge interface for Three.js.
+ * Controls 3D character facial animation using Action Units (AUs),
+ * morph targets, visemes, and bone transformations.
+ */
+
+declare class Loom3 implements LoomLarge {
+    onSnippetEnd?: (name: string) => void;
+    private config;
+    private animation;
+    private compositeRotations;
+    private auToCompositeMap;
+    private auValues;
+    private auBalances;
+    private rigReady;
+    private missingBoneWarnings;
+    private rotations;
+    private pendingCompositeNodes;
+    private isPaused;
+    private translations;
+    private faceMesh;
+    private resolvedFaceMeshes;
+    private meshes;
+    private model;
+    private meshByName;
+    private morphKeyCache;
+    private morphIndexCache;
+    private resolvedAUMorphTargets;
+    private resolvedVisemeTargets;
+    private bones;
+    private mixWeights;
+    private visemeValues;
+    private static readonly VISEME_JAW_AMOUNTS;
+    private bakedAnimations;
+    private hairPhysics;
+    private clock;
+    private animationFrameId;
+    private isRunning;
+    constructor(config?: LoomLargeConfig, animation?: {
+        tick(dtSeconds: number): void;
+        addTransition(key: string, from: number, to: number, durationMs: number, apply: (value: number) => void, easing?: (t: number) => number): TransitionHandle;
+        clearTransitions(): void;
+        getActiveTransitionCount(): number;
+    });
+    onReady(payload: ReadyPayload): void;
+    private rebuildMorphTargetsCache;
+    private resolveFaceMeshes;
+    update(deltaSeconds: number): void;
+    /** Start the internal animation loop using Three.js Clock */
+    start(): void;
+    /** Stop the internal animation loop */
+    stop(): void;
+    dispose(): void;
+    setAU(id: number | string, v: number, balance?: number): void;
+    transitionAU(id: number | string, to: number, durationMs?: number, balance?: number): TransitionHandle;
+    getAU(id: number): number;
+    getCompositeRotations(): CompositeRotation[];
+    /**
+     * Set a continuum AU pair immediately (no animation).
+     *
+     * Sign convention:
+     * - Negative value (-1 to 0): activates negAU (e.g., head left, eyes left)
+     * - Positive value (0 to +1): activates posAU (e.g., head right, eyes right)
+     *
+     * @param negAU - AU ID for negative direction (e.g., 61 for eyes left)
+     * @param posAU - AU ID for positive direction (e.g., 62 for eyes right)
+     * @param continuumValue - Value from -1 (full negative) to +1 (full positive)
+     * @param balance - Optional L/R balance for bilateral morphs
+     */
+    setContinuum(negAU: number, posAU: number, continuumValue: number, balance?: number): void;
+    /**
+     * Smoothly transition a continuum AU pair (e.g., eyes left/right, head up/down).
+     * Takes a continuum value from -1 to +1 and internally manages both AU values.
+     *
+     * @param negAU - AU ID for negative direction (e.g., 61 for eyes left)
+     * @param posAU - AU ID for positive direction (e.g., 62 for eyes right)
+     * @param continuumValue - Target value from -1 (full negative) to +1 (full positive)
+     * @param durationMs - Transition duration in milliseconds
+     * @param balance - Optional L/R balance for bilateral morphs
+     */
+    transitionContinuum(negAU: number, posAU: number, continuumValue: number, durationMs?: number, balance?: number): TransitionHandle;
+    /**
+     * Set a morph target value.
+     *
+     * Fast paths (in order of speed):
+     * 1. Pass pre-resolved { infl, idx } array directly - zero lookups
+     * 2. String key with cache hit - one Map lookup
+     * 3. String key cache miss - dictionary lookup, then cached for next time
+     */
+    setMorph(key: string, v: number, meshNames?: string[]): void;
+    setMorph(key: string, v: number, targets: {
+        infl: number[];
+        idx: number;
+    }[]): void;
+    setMorphInfluence(index: number, v: number, meshNames?: string[]): void;
+    /**
+     * Resolve morph key to direct targets for ultra-fast repeated access.
+     * Use this when you need to set the same morph many times (e.g., in animation loops).
+     */
+    resolveMorphTargets(key: string, meshNames?: string[]): {
+        infl: number[];
+        idx: number;
+    }[];
+    resolveMorphTargetsByIndex(index: number, meshNames?: string[]): {
+        infl: number[];
+        idx: number;
+    }[];
+    transitionMorph(key: string, to: number, durationMs?: number, meshNames?: string[]): TransitionHandle;
+    transitionMorphInfluence(index: number, to: number, durationMs?: number, meshNames?: string[]): TransitionHandle;
+    setViseme(visemeIndex: number, value: number, jawScale?: number): void;
+    transitionViseme(visemeIndex: number, to: number, durationMs?: number, jawScale?: number): TransitionHandle;
+    setAUMixWeight(id: number, weight: number): void;
+    getAUMixWeight(id: number): number;
+    /**
+     * Check if an AU has bilateral bone bindings (left + right side hints).
+     * Used to determine if a balance slider should be shown for bone-only bilateral AUs.
+     */
+    hasLeftRightBones(auId: number): boolean;
+    pause(): void;
+    resume(): void;
+    getPaused(): boolean;
+    clearTransitions(): void;
+    getActiveTransitionCount(): number;
+    resetToNeutral(): void;
+    getMeshList(): MeshInfo[];
+    /** Get all morph targets grouped by mesh name */
+    getMorphTargets(): Record<string, string[]>;
+    /** Get morph target indices mapped to labels for each mesh */
+    getMorphTargetIndices(): Record<string, {
+        index: number;
+        name: string;
+    }[]>;
+    /** Get all resolved bone names and their current transforms */
+    getBones(): Record<string, {
+        position: [number, number, number];
+        rotation: [number, number, number];
+    }>;
+    setMeshVisible(meshName: string, visible: boolean): void;
+    /** Store original emissive colors for highlight reset */
+    private originalEmissive;
+    /**
+     * Highlight a mesh with an emissive glow effect
+     * @param meshName - Name of the mesh to highlight (null to clear all highlights)
+     * @param color - Highlight color (default: cyan 0x00ffff)
+     * @param intensity - Emissive intensity (default: 0.5)
+     */
+    highlightMesh(meshName: string | null, color?: number, intensity?: number): void;
+    /** Blending mode options for Three.js materials */
+    private static readonly BLENDING_MODES;
+    /** Get material config for a mesh */
+    getMeshMaterialConfig(meshName: string): {
+        renderOrder: number;
+        transparent: boolean;
+        opacity: number;
+        depthWrite: boolean;
+        depthTest: boolean;
+        blending: string;
+    } | null;
+    /** Set material config for a mesh */
+    setMeshMaterialConfig(meshName: string, config: {
+        renderOrder?: number;
+        transparent?: boolean;
+        opacity?: number;
+        depthWrite?: boolean;
+        depthTest?: boolean;
+        blending?: string;
+    }): void;
+    private applyHairPhysicsProfileConfig;
+    setProfile(profile: Profile): void;
+    getProfile(): Profile;
+    /**
+     * Get the mesh names that should receive morph influences for a given AU.
+     * Routes by facePart: Tongue → tongue, Eye → eye, everything else → face.
+     */
+    getMeshNamesForAU(auId: number): string[];
+    registerHairObjects(objects: Object3D[]): Array<{
+        name: string;
+        isMesh: boolean;
+        isEyebrow: boolean;
+    }>;
+    getRegisteredHairObjects(): Mesh[];
+    setHairPhysicsEnabled(enabled: boolean): void;
+    isHairPhysicsEnabled(): boolean;
+    setHairPhysicsConfig(config: HairPhysicsConfigUpdate): void;
+    getHairPhysicsConfig(): HairPhysicsConfig$2;
+    validateHairMorphTargets(): string[];
+    /** Get head rotation values for hair physics (range -1 to 1) */
+    getHeadRotation(): {
+        yaw: number;
+        pitch: number;
+        roll: number;
+    };
+    updateHairPhysics(dt: number): void;
+    getHairMorphTargets(meshName?: string): string[];
+    setMorphOnMeshes(meshNames: string[], morphKey: string, value: number): void;
+    applyHairStateToObject(objectName: string, state: {
+        color?: {
+            baseColor: string;
+            emissive: string;
+            emissiveIntensity: number;
+        };
+        outline?: {
+            show: boolean;
+            color: string;
+            opacity: number;
+        };
+        visible?: boolean;
+        scale?: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        position?: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        isEyebrow?: boolean;
+    }): void;
+    private computeSideValues;
+    private getAUMorphsBySide;
+    private applyMorphTargets;
+    private getMorphValue;
+    private getMorphValueByIndex;
+    private getMorphKeyCacheKey;
+    private getMorphIndexCacheKey;
+    private isMixedAU;
+    private initBoneRotations;
+    /** Update rotation state - just stores -1 to 1 value like stable version */
+    private updateBoneRotation;
+    private updateBoneTranslation;
+    private transitionBoneRotation;
+    private transitionBoneTranslation;
+    private flushPendingComposites;
+    /**
+     * Apply composite rotation using quaternion composition like stable version.
+     * Looks up maxDegrees and channel from BONE_AU_TO_BINDINGS.
+     */
+    private applyCompositeRotation;
+    private resolveBones;
+    private combineHandles;
+    /**
+     * Apply render order and material settings from CC4_MESHES to all meshes.
+     * This ensures proper layering (e.g., hair renders on top of eyebrows).
+     * Also auto-registers hair and eyebrow meshes for hair physics.
+     */
+    private applyMeshMaterialSettings;
+    loadAnimationClips(clips: unknown[]): void;
+    getAnimationClips(): AnimationClipInfo[];
+    playAnimation(clipName: string, options?: AnimationPlayOptions): AnimationActionHandle | null;
+    stopAnimation(clipName: string): void;
+    stopAllAnimations(): void;
+    pauseAnimation(clipName: string): void;
+    resumeAnimation(clipName: string): void;
+    pauseAllAnimations(): void;
+    resumeAllAnimations(): void;
+    setAnimationSpeed(clipName: string, speed: number): void;
+    setAnimationIntensity(clipName: string, intensity: number): void;
+    setAnimationTimeScale(timeScale: number): void;
+    getAnimationState(clipName: string): AnimationState | null;
+    getPlayingAnimations(): AnimationState[];
+    crossfadeTo(clipName: string, duration?: number, options?: AnimationPlayOptions): AnimationActionHandle | null;
+    snippetToClip(clipName: string, curves: CurvesMap, options?: ClipOptions): AnimationClip | null;
+    playClip(clip: AnimationClip, options?: ClipOptions): ClipHandle | null;
+    playSnippet(snippet: Snippet | {
+        name: string;
+        curves: CurvesMap;
+    }, options?: ClipOptions): ClipHandle | null;
+    buildClip(clipName: string, curves: CurvesMap, options?: ClipOptions): ClipHandle | null;
+    cleanupSnippet(name: string): void;
+    updateClipParams(name: string, params: {
+        weight?: number;
+        rate?: number;
+        loop?: boolean;
+        loopMode?: 'once' | 'repeat' | 'pingpong';
+        repeatCount?: number;
+        reverse?: boolean;
+        actionId?: string;
+    }): boolean;
+    /**
+     * Check if curves can be played through buildClip.
+     * Returns false if curves contain bone-only AUs that can't be baked to morph tracks.
+     */
+    supportsClipCurves(curves: Record<string, Array<{
+        time: number;
+        intensity: number;
+        inherit?: boolean;
+    }>>): boolean;
+}
+/**
+ * Helper function to collect meshes with morph targets from a scene.
+ */
+declare function collectMorphMeshes(root: Object3D): Mesh[];
+
+/**
+ * AnimationThree - Lerp-based animation driver
+ *
+ * Internal driver for time-based interpolation with easing functions.
+ */
+
+declare class AnimationThree {
+    private transitions;
+    /**
+     * Tick all active transitions by dt seconds.
+     * Applies eased interpolation and removes completed transitions.
+     * Respects individual transition pause state.
+     */
+    tick(dtSeconds: number): void;
+    /**
+     * Add or replace a transition for the given key.
+     * If a transition with the same key exists, it is cancelled and replaced.
+     * @returns TransitionHandle with { promise, pause, resume, cancel }
+     */
+    addTransition(key: string, from: number, to: number, durationMs: number, apply: (value: number) => void, easing?: (t: number) => number): TransitionHandle;
+    /** Clear all running transitions. */
+    clearTransitions(): void;
+    /** Get count of active transitions. */
+    getActiveTransitionCount(): number;
+}
+
+/**
+ * Hair Physics Interface
+ *
+ * Defines the contract for hair physics simulation systems.
+ * Implementations can use different physics models (spring-damper, verlet, etc.)
+ */
+/**
+ * Configuration for hair physics simulation
+ */
+interface HairPhysicsConfig$1 {
+    mass: number;
+    stiffness: number;
+    damping: number;
+    gravity: number;
+    headInfluence: number;
+    windEnabled: boolean;
+    windStrength: number;
+    windDirectionX: number;
+    windDirectionZ: number;
+    windTurbulence: number;
+    windFrequency: number;
+}
+/**
+ * Hair strand definition for multi-strand simulation
+ */
+interface HairStrand {
+    id: string;
+    morphKeys: {
+        left: string;
+        right: string;
+        front?: string;
+        back?: string;
+    };
+    mass?: number;
+    stiffness?: number;
+    damping?: number;
+}
+/**
+ * Current physics state of hair simulation
+ */
+interface HairState {
+    x: number;
+    z: number;
+    vx: number;
+    vz: number;
+}
+/**
+ * Head orientation state for physics input
+ */
+interface HeadState$1 {
+    yaw: number;
+    pitch: number;
+    roll: number;
+    yawVelocity: number;
+    pitchVelocity: number;
+}
+/**
+ * Output morph values from physics simulation
+ */
+interface HairMorphOutput$1 {
+    [morphKey: string]: number;
+}
+/**
+ * Hair Physics simulation interface
+ */
+interface HairPhysics$1 {
+    /**
+     * Update physics simulation
+     * @param dt Delta time in seconds
+     * @param headState Current head orientation and velocity
+     * @returns Morph values to apply to hair meshes
+     */
+    update(dt: number, headState: HeadState$1): HairMorphOutput$1;
+    /**
+     * Get current physics state (for debugging/UI)
+     */
+    getState(): HairState;
+    /**
+     * Update configuration
+     */
+    setConfig(config: Partial<HairPhysicsConfig$1>): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): HairPhysicsConfig$1;
+    /**
+     * Reset physics state to rest position
+     */
+    reset(): void;
+}
+
+/** Line stroke style */
+type LineStyle = 'solid' | 'dashed' | 'dotted';
+/** Line curve type */
+type LineCurve = 'straight' | 'bezier' | 'arc';
+/** Named direction presets for line orientation */
+type NamedDirection = 'radial' | 'camera' | 'up' | 'down' | 'left' | 'right' | 'forward' | 'backward';
+/** Line configuration for markers */
+interface LineConfig {
+    /** Stroke style. Default: 'solid' */
+    style?: LineStyle;
+    /** Curve type. Default: 'straight' */
+    curve?: LineCurve;
+    /** Show arrow head at end. Default: false */
+    arrowHead?: boolean;
+    /** Line thickness (affects dash size). Default: 2 */
+    thickness?: number;
+    /** Line length override (model units) */
+    length?: number;
+}
+/** Style overrides that can be applied per-region */
+interface MarkerStyleOverrides {
+    /** Override marker sphere color (hex) */
+    markerColor?: number;
+    /** Override marker sphere radius (model units) */
+    markerRadius?: number;
+    /** Override line color (hex) */
+    lineColor?: number;
+    /** Override label text color (CSS) */
+    labelColor?: string;
+    /** Override label background (CSS) */
+    labelBackground?: string;
+    /** Override label font size (pixels) */
+    labelFontSize?: number;
+    /** Override overall marker opacity (0-1) */
+    opacity?: number;
+    /** Custom line direction: named preset or explicit vector */
+    lineDirection?: NamedDirection | {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Line styling options */
+    line?: LineConfig;
+}
+/** Animation style for expanding/collapsing child markers */
+type ExpandAnimation = 'outward' | 'staggered';
+/** Expanded region state */
+interface ExpandedRegionState {
+    regionName: string;
+    isExpanded: boolean;
+    children: string[];
+}
+/** Fallback behavior configuration */
+interface FallbackConfig {
+    /** Name of the fallback marker to show when all group markers are occluded */
+    fallbackMarker?: string;
+    /** Behavior when clicking fallback: 'fit-all' tries to fit all in frame, 'rotate' rotates camera */
+    clickBehavior?: 'fit-all' | 'rotate';
+}
+/** Marker group for fallback behavior */
+interface MarkerGroup {
+    /** Unique group identifier */
+    groupId: string;
+    /** Region names in this group */
+    regions: string[];
+    /** Fallback configuration */
+    fallback?: FallbackConfig;
+}
+/**
+ * Single region definition - maps a name to geometry targets
+ */
+interface Region {
+    /** Display name for the annotation */
+    name: string;
+    /** Bone names to focus on */
+    bones?: string[];
+    /** Mesh object names to focus on */
+    meshes?: string[];
+    /** Any object names (bones or meshes). Use ['*'] for all objects */
+    objects?: string[];
+    /** Override default padding factor for this annotation */
+    paddingFactor?: number;
+    /**
+     * Camera angle in degrees around the Y axis (horizontal orbit).
+     * 0 = front (default), 90 = right side, 180 = back, 270 = left side
+     */
+    cameraAngle?: number;
+    /** Fine-tune camera position offset */
+    cameraOffset?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    /** Parent region name - children animate outward from parent when expanded */
+    parent?: string;
+    /** Child region names - shown when this region is expanded */
+    children?: string[];
+    /** Animation style for expand/collapse. Default: 'outward' */
+    expandAnimation?: ExpandAnimation;
+    /** Show connecting lines to children when expanded. Default: true */
+    showChildConnections?: boolean;
+    /** Per-marker style overrides */
+    style?: MarkerStyleOverrides;
+    /** Marker group ID for fallback behavior */
+    groupId?: string;
+    /** If true, this marker acts as a fallback for its group */
+    isFallback?: boolean;
+    /** Custom position override (user-adjusted). If set, overrides calculated position. */
+    customPosition?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+/**
+ * Marker style for annotation visualization
+ * - 'html': Simple HTML overlay markers with numbered dots directly over targets
+ * - '3d': 3D markers with lines and labels rendered in scene space
+ */
+type MarkerStyle = 'html' | '3d';
+/**
+ * Per-character configuration for camera + animation
+ */
+interface CharacterConfig {
+    /** Unique identifier for the character */
+    characterId: string;
+    /** Display name */
+    characterName: string;
+    /** Path to GLB file (relative to public folder) */
+    modelPath: string;
+    /** Which region to focus on load */
+    defaultRegion?: string;
+    /** List of available regions */
+    regions: Region[];
+    /** Marker visualization style. Default: '3d' */
+    markerStyle?: MarkerStyle;
+    /** Play intro animation on load (orbit around model, then zoom to torso). Default: false */
+    playIntroOnLoad?: boolean;
+    /** Model position offset to apply on load (e.g., to raise fish above ground) */
+    modelOffset?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    /** Model rotation in degrees to apply on load (e.g., to fix models exported with wrong orientation) */
+    modelRotation?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    /** Ensure model's lowest point clears the ground by this amount (world units) */
+    modelGroundClearance?: number;
+    /** Preset type for animation mapping. Default: 'cc4' */
+    auPresetType?: PresetType;
+    /** Optional: profile overrides applied on top of the preset */
+    profile?: Partial<Profile>;
+    /** Prefix to prepend to bone names (e.g., 'Bone.' for fish) */
+    bonePrefix?: string;
+    /** Suffix to append to bone names (e.g., '_Armature' for fish) */
+    boneSuffix?: string;
+    /** Semantic bone name mapping (e.g., 'HEAD' → '001') */
+    boneNodes?: Record<string, string>;
+    /** Regex pattern for fuzzy bone/mesh name matching (e.g., '_\\d+$|\\.\\d+$') */
+    suffixPattern?: string;
+    /** Marker groups for fallback behavior */
+    markerGroups?: MarkerGroup[];
+    /** Global line styling defaults */
+    lineDefaults?: LineConfig;
+    /** Global marker style defaults (overridden by per-region style) */
+    markerDefaults?: Partial<MarkerStyleOverrides>;
+}
+/**
+ * Registry of all available characters
+ */
+interface CharacterRegistry {
+    characters: CharacterConfig[];
+    defaultCharacter?: string;
+}
+
+interface ResolvedFaceCenter {
+    center: THREE.Vector3;
+    method: string;
+    debugInfo: string[];
+}
+declare function resolveBoneName(semanticName: string, config?: CharacterConfig): string;
+declare function resolveBoneNames(names: string[] | undefined, config?: CharacterConfig): string[];
+declare function fuzzyNameMatch(objectName: string, targetName: string, suffixPattern?: string): boolean;
+declare function resolveFaceCenter(model: THREE.Object3D, region: Region, config?: CharacterConfig): ResolvedFaceCenter;
+
+/**
+ * HairPhysics - Spring-damper pendulum simulation for hair movement
+ *
+ * This is a pure physics simulation class with no Three.js dependencies.
+ * It outputs normalized morph values (0-1) that can be applied to hair meshes
+ * via EngineThree.setMorph() or transitionMorph().
+ *
+ * Physics model:
+ * - Hair is modeled as a damped pendulum affected by:
+ *   - Gravity (constant downward force based on head orientation)
+ *   - Head velocity (inertia causes hair to lag behind head movement)
+ *   - Wind (oscillating force with turbulence)
+ *   - Spring restoration (hair returns to rest position)
+ *   - Damping (air resistance)
+ */
+interface HairPhysicsConfig {
+    mass: number;
+    stiffness: number;
+    damping: number;
+    gravity: number;
+    headInfluence: number;
+    windEnabled: boolean;
+    windStrength: number;
+    windDirectionX: number;
+    windDirectionZ: number;
+    windTurbulence: number;
+    windFrequency: number;
+}
+interface HairPhysicsState {
+    x: number;
+    z: number;
+    vx: number;
+    vz: number;
+}
+interface HairMorphOutput {
+    L_Hair_Left: number;
+    L_Hair_Right: number;
+    L_Hair_Front: number;
+    R_Hair_Left: number;
+    R_Hair_Right: number;
+    R_Hair_Front: number;
+}
+interface HeadState {
+    yaw: number;
+    pitch: number;
+    roll: number;
+    yawVelocity: number;
+    pitchVelocity: number;
+}
+declare const DEFAULT_HAIR_PHYSICS_CONFIG: HairPhysicsConfig;
+declare class HairPhysics {
+    private config;
+    private state;
+    private time;
+    private prevHeadYaw;
+    private prevHeadPitch;
+    constructor(config?: Partial<HairPhysicsConfig>);
+    /**
+     * Update physics simulation
+     * @param dt Delta time in seconds
+     * @param headState Current head orientation and velocity
+     * @returns Morph values to apply to hair meshes
+     */
+    update(dt: number, headState: HeadState): HairMorphOutput;
+    /**
+     * Convert physics state to morph target values
+     * Maps pendulum position to left/right/front morphs for both sides
+     */
+    private computeMorphOutput;
+    /**
+     * Get current physics state (for debugging/UI)
+     */
+    getState(): HairPhysicsState;
+    /**
+     * Update configuration
+     */
+    setConfig(config: Partial<HairPhysicsConfig>): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): HairPhysicsConfig;
+    /**
+     * Reset physics state to rest position
+     */
+    reset(): void;
+}
+
+/**
+ * Loom3 - Mapping Corrections
+ *
+ * Attempts to generate a corrected mapping configuration using fuzzy matching.
+ * This is a best-effort helper that can be layered on top of validation.
+ */
+
+interface MorphMesh$1 {
+    name: string;
+    morphTargetDictionary?: Record<string, number>;
+    morphTargetInfluences?: number[];
+}
+interface Skeleton$1 {
+    bones: Array<{
+        name: string;
+    }>;
+}
+interface MappingCorrection {
+    type: 'bone' | 'morph' | 'viseme' | 'mesh';
+    source: string;
+    target: string;
+    confidence: number;
+    reason: string;
+    applied: boolean;
+    auId?: number;
+    key?: string;
+}
+interface MappingCorrectionResult {
+    correctedConfig: Profile;
+    corrections: MappingCorrection[];
+    unresolved: MappingCorrection[];
+}
+interface MappingCorrectionOptions {
+    minConfidence?: number;
+    /**
+     * When true, normalize names to resolved full names and clear prefix/suffix.
+     * This is useful when target names don't follow the prefix/suffix pattern.
+     */
+    useResolvedNames?: boolean;
+}
+declare function generateMappingCorrections(meshes: MorphMesh$1[], skeleton: Skeleton$1 | null, config: Profile, options?: MappingCorrectionOptions): MappingCorrectionResult;
+
+/**
+ * Loom3 - Mapping Validation
+ *
+ * Validates that AU mapping presets are compatible with a loaded character model.
+ * Checks that bones, morph targets, and meshes referenced in the preset exist in the model.
+ */
+
+/**
+ * Result of validating a preset against a model
+ */
+interface ValidationResult {
+    /** Overall validity - true if essential mappings are found */
+    valid: boolean;
+    /** Compatibility score from 0-100 */
+    score: number;
+    /** Morph targets referenced in preset but not found in model */
+    missingMorphs: string[];
+    /** Bones referenced in preset but not found in model */
+    missingBones: string[];
+    /** Morph targets successfully matched */
+    foundMorphs: string[];
+    /** Bones successfully matched */
+    foundBones: string[];
+    /** Morph targets in model not used by preset */
+    unmappedMorphs: string[];
+    /** Bones in model not used by preset */
+    unmappedBones: string[];
+    /** Meshes referenced by morphToMesh but not found in model */
+    missingMeshes: string[];
+    /** Meshes referenced by morphToMesh and found in model */
+    foundMeshes: string[];
+    /** Meshes in model not referenced by morphToMesh */
+    unmappedMeshes: string[];
+    /** Non-fatal warnings and suggestions */
+    warnings: string[];
+    /** Optional: corrected config when suggestions are requested */
+    suggestedConfig?: Profile;
+    /** Optional: corrections applied or suggested */
+    corrections?: MappingCorrection[];
+    /** Optional: unresolved mappings that could not be corrected */
+    unresolved?: MappingCorrection[];
+}
+type IssueSeverity = 'error' | 'warning';
+interface MappingIssue {
+    code: string;
+    severity: IssueSeverity;
+    message: string;
+    data?: Record<string, unknown>;
+}
+interface MappingConsistencyResult {
+    valid: boolean;
+    errors: MappingIssue[];
+    warnings: MappingIssue[];
+    issues: MappingIssue[];
+}
+interface ValidateMappingOptions extends MappingCorrectionOptions {
+    suggestCorrections?: boolean;
+}
+/**
+ * Interface for mesh with morph targets (compatible with Three.js Mesh)
+ */
+interface MorphMesh {
+    name: string;
+    morphTargetDictionary?: Record<string, number>;
+    morphTargetInfluences?: number[];
+}
+/**
+ * Interface for skeleton (compatible with Three.js Skeleton)
+ */
+interface Skeleton {
+    bones: Array<{
+        name: string;
+    }>;
+}
+/**
+ * Validate that the mapping dictionaries are internally consistent.
+ */
+declare function validateMappingConfig(config: Profile): MappingConsistencyResult;
+declare function validateMappings(meshes: MorphMesh[], skeleton: Skeleton | null, config: Profile, options?: ValidateMappingOptions): ValidationResult;
+/**
+ * Quick check if a preset is compatible with a model.
+ * Returns true if at least 50% of mappings are found.
+ */
+declare function isPresetCompatible(meshes: MorphMesh[], skeleton: Skeleton | null, config: Profile): boolean;
+/**
+ * Suggest the best preset from a list based on validation scores.
+ */
+declare function suggestBestPreset<T extends Profile>(meshes: MorphMesh[], skeleton: Skeleton | null, presets: T[]): {
+    preset: T;
+    score: number;
+} | null;
+
+/**
+ * Loom3 - Model Data Extraction
+ *
+ * Extracts bones, morph targets, meshes, and animations from 3D models.
+ * Works with both GLTF files and runtime Three.js models.
+ */
+
+/**
+ * Bone information extracted from skeleton
+ */
+interface BoneInfo {
+    name: string;
+    parent: string | null;
+    children: string[];
+    worldPosition: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Depth in hierarchy (0 = root) */
+    depth: number;
+}
+/**
+ * Morph target information
+ */
+interface MorphInfo {
+    name: string;
+    meshName: string;
+    index: number;
+}
+/**
+ * Model mesh information (from extraction)
+ */
+interface ModelMeshInfo {
+    name: string;
+    hasMorphTargets: boolean;
+    morphCount: number;
+}
+/**
+ * Animation track information
+ */
+interface TrackInfo {
+    name: string;
+    targetName: string;
+    property: string;
+    type: 'position' | 'rotation' | 'scale' | 'morph' | 'unknown';
+    keyframeCount: number;
+    valueRange?: {
+        min: number[];
+        max: number[];
+    };
+}
+/**
+ * Animation clip information
+ */
+interface AnimationInfo {
+    name: string;
+    duration: number;
+    tracks: TrackInfo[];
+    animatedBones: string[];
+    animatedMorphs: string[];
+}
+/**
+ * Complete model data extraction result
+ */
+interface ModelData {
+    bones: BoneInfo[];
+    morphs: MorphInfo[];
+    meshes: ModelMeshInfo[];
+    animations: AnimationInfo[];
+    /** Quick lookups */
+    boneNames: string[];
+    morphNames: string[];
+    meshNames: string[];
+}
+/**
+ * Extract all data from a runtime Three.js model
+ *
+ * @param model - The root Object3D of the loaded model
+ * @param meshes - Array of meshes with morph targets (optional, will be collected if not provided)
+ * @param animations - Array of AnimationClips from the GLTF (optional)
+ */
+declare function extractModelData(model: THREE.Object3D, meshes?: THREE.Mesh[], animations?: THREE.AnimationClip[]): ModelData;
+/**
+ * Extract all data from a GLTF file
+ *
+ * @param gltf - The loaded GLTF object
+ */
+declare function extractFromGLTF(gltf: GLTF): ModelData;
+
+/**
+ * Loom3 - Unified Model Analysis API
+ *
+ * Combines model extraction, validation, and correction suggestions
+ * into a single comprehensive analysis report.
+ */
+
+/**
+ * Animation analysis results
+ */
+interface AnimationAnalysis {
+    count: number;
+    hasIdleCandidate: boolean;
+    clips: Array<{
+        name: string;
+        duration: number;
+        affectedBones: string[];
+        affectedMorphs: string[];
+    }>;
+}
+/**
+ * Complete model analysis report
+ */
+interface ModelAnalysisReport {
+    /** Extracted model data */
+    model: ModelData;
+    /** Validation results (if preset provided) */
+    validation?: ValidationResult;
+    /** Animation analysis */
+    animations: AnimationAnalysis;
+    /** Overall health score (0-100) */
+    overallScore: number;
+    /** Human-readable summary */
+    summary: string;
+}
+/**
+ * Options for model analysis
+ */
+interface AnalyzeModelOptions {
+    /** The model source */
+    source: {
+        type: 'gltf';
+        gltf: GLTF;
+    } | {
+        type: 'runtime';
+        model: THREE.Object3D;
+        meshes: THREE.Mesh[];
+        animations: THREE.AnimationClip[];
+    };
+    /** Optional preset to validate against */
+    preset?: Profile;
+    /** Request correction suggestions */
+    suggestCorrections?: boolean;
+}
+/**
+ * Analyze a 3D model comprehensively
+ *
+ * Extracts model data, validates against a preset (if provided),
+ * analyzes animations, and returns a comprehensive report.
+ *
+ * @param options - Analysis options
+ * @returns Complete analysis report
+ */
+declare function analyzeModel(options: AnalyzeModelOptions): Promise<ModelAnalysisReport>;
+
+/**
+ * Loom3 - Geometry Helpers
+ *
+ * Helper functions for finding face positions, annotation centers,
+ * and other geometry-related calculations for character models.
+ */
+
+/**
+ * Result of finding a face center position
+ */
+interface FaceCenterResult {
+    /** The calculated face center position in world space */
+    center: THREE.Vector3;
+    /** The head bone position (if found) */
+    headBonePosition?: THREE.Vector3;
+    /** How the center was determined */
+    method: 'head-bone-offset' | 'bone-average' | 'mesh-center' | 'fallback';
+    /** Debug info about what was found */
+    debugInfo: string[];
+}
+/**
+ * Options for finding face center
+ */
+interface FindFaceCenterOptions {
+    /** Names of bones to search for head bone (e.g., ['CC_Base_Head']) */
+    headBoneNames?: string[];
+    /** Names of face meshes - when provided, uses mesh bounding box center for positioning */
+    faceMeshNames?: string[];
+    /** Forward offset from head bone to face surface (default: 0.08 = 8cm) */
+    forwardOffset?: number;
+    /** Reference model height for scaling (default: 1.8m) */
+    referenceHeight?: number;
+}
+/**
+ * Find the center position of a character's face.
+ *
+ * Strategy:
+ * 1. If face mesh names provided and they're face-only meshes, use mesh center
+ * 2. Otherwise find head bone and use EYE positions to determine forward direction
+ *    (Eyes are reliably IN FRONT of the head bone, unlike jaw which is below)
+ *
+ * @param model - The root Object3D of the character model
+ * @param options - Configuration options
+ * @returns FaceCenterResult with the calculated position
+ */
+declare function findFaceCenter(model: THREE.Object3D, options?: FindFaceCenterOptions): FaceCenterResult;
+/**
+ * Get the forward direction of a model in world space.
+ * Assumes the model's local forward is positive Z.
+ *
+ * @param model - The model to get forward direction for
+ * @returns Normalized forward direction vector in world space
+ */
+declare function getModelForwardDirection(model: THREE.Object3D): THREE.Vector3;
+/**
+ * Check if a character model is facing forward (toward camera at origin).
+ * Uses head/eye bone positions to determine facing direction.
+ *
+ * @param model - The character model
+ * @param eyeBoneNames - Names of eye bones to search for
+ * @returns 'forward' if facing camera, 'backward' if facing away, 'unknown' if can't determine
+ */
+declare function detectFacingDirection(model: THREE.Object3D, eyeBoneNames?: {
+    left: string[];
+    right: string[];
+}): 'forward' | 'backward' | 'unknown';
+
+export { type AUInfo, AU_INFO, AU_MIX_DEFAULTS, AU_TO_MORPHS, type AnalyzeModelOptions, type Animation, type AnimationActionHandle, type AnimationAnalysis, type AnimationClipInfo, type AnimationInfo, type AnimationPlayOptions, 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, AU_MAPPING_CONFIG as 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$1 as 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, collectMorphMeshes, detectFacingDirection, extractFromGLTF, extractModelData, findFaceCenter, fuzzyNameMatch, generateMappingCorrections, getModelForwardDirection, hasLeftRightMorphs, isMixedAU, isPresetCompatible, resolveBoneName, resolveBoneNames, resolveFaceCenter, resolvePreset, resolvePresetWithOverrides, resolveProfile, suggestBestPreset, validateMappingConfig, validateMappings };