@lovelace_lol/embody 0.0.6 → 0.0.8

package/dist/interfaces/Animation.d.ts

@@ -1,315 +0,0 @@
-/**
- * Animation Interface
- *
- * Groups AU/morph/viseme methods, transitions, and mixer playback.
- */
-import type { TransitionHandle, AnimationPlayOptions, AnimationClipInfo, AnimationState, AnimationActionHandle, ClipOptions, ClipHandle, CompositeRotation, CurvePoint, SnippetChannel, AnimationBlendMode, MorphTargetDelta, AddMorphTargetOptions } from '../core/types';
-/** Loop mode for mixer clips */
-export type MixerLoopMode = 'once' | 'repeat' | 'pingpong';
-export 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;
-    /**
-     * 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
-     * @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 viseme value by profile-defined slot id.
-     */
-    setVisemeById?(slotId: string, value: number, jawScale?: number): void;
-    /**
-     * Transition viseme value smoothly by profile-defined slot id.
-     */
-    transitionVisemeById?(slotId: string, 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[];
-    /**
-     * Remove a loaded animation clip by name.
-     * @param clipName - Name of the animation clip to remove
-     * @returns True when the clip existed and was removed
-     */
-    removeAnimationClip(clipName: string): boolean;
-    /**
-     * Play a loaded animation clip 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 loop mode for a specific animation.
-     * @param clipName - Name of the animation
-     * @param loopMode - Loop policy for the mixer action
-     */
-    setAnimationLoopMode(clipName: string, loopMode: MixerLoopMode): void;
-    /**
-     * Set the repeat count for a specific animation.
-     * @param clipName - Name of the animation
-     * @param repeatCount - Number of repetitions, or undefined for the mixer default
-     */
-    setAnimationRepeatCount(clipName: string, repeatCount?: number): void;
-    /**
-     * Set reverse playback for a specific animation.
-     * @param clipName - Name of the animation
-     * @param reverse - Whether the mixer action should run backwards
-     */
-    setAnimationReverse(clipName: string, reverse: boolean): void;
-    /**
-     * Set the blend mode for a specific animation.
-     * @param clipName - Name of the animation
-     * @param blendMode - Mixer blend mode wrapper exposed to downstream UIs
-     */
-    setAnimationBlendMode(clipName: string, blendMode: AnimationBlendMode): void;
-    /**
-     * Seek a specific animation to a time in seconds.
-     * @param clipName - Name of the animation
-     * @param time - Target time in seconds
-     */
-    seekAnimation(clipName: string, time: 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;
-    /**
-     * Build and play an AnimationClip from typed channel data.
-     * This is the preferred dynamic path when numeric IDs could mean different
-     * namespaces, such as AU 1, viseme slot 1, or lip-sync control 103.
-     */
-    buildTypedClip(clipName: string, channels: SnippetChannel[], 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 data that cannot be converted to mixer tracks.
-     */
-    supportsClipCurves(curves: Record<string, Array<CurvePoint>>): boolean;
-    /**
-     * Callback when a snippet finishes playback.
-     * Used by animation schedulers for sequencing.
-     */
-    onSnippetEnd?(name: string): void;
-}

package/dist/interfaces/EmbodyRuntime.d.ts

@@ -1,90 +0,0 @@
-/**
- * Embody Runtime Interface
- *
- * Defines the contract for 3D character animation engines.
- * Uses Three.js types directly - no framework abstraction overhead.
- */
-import type { Mesh, Object3D } from 'three';
-import type { Profile, MeshInfo } from '../mappings/types';
-import type { PresetType } from '../presets';
-import type { Animation } from './Animation';
-import type { Hair } from './Hair';
-import type { EmbodyAnimationRuntimeFactory } from '../core/types';
-/**
- * Payload for initializing the engine with a loaded model
- */
-export interface ReadyPayload {
-    meshes: Mesh[];
-    model: Object3D;
-}
-/**
- * Configuration options for the Embody engine
- */
-export interface EmbodyConfig {
-    /** AU to morph target mappings (partial extensions merged into the preset). */
-    profile?: Partial<Profile>;
-    /** Preset type to resolve if profile is not provided. */
-    presetType?: PresetType | string;
-    /**
-     * Optional animation runtime factory from `@lovelace_lol/embody/cljs`.
-     * When supplied, dynamic snippet handles are owned by that runtime while
-     * this engine remains the Three.js renderer connector.
-     */
-    animationRuntimeFactory?: EmbodyAnimationRuntimeFactory;
-}
-export type { MeshInfo } from '../mappings/types';
-/**
- * Embody Engine Interface
- *
- * The main interface for controlling 3D character facial animation.
- * Supports Action Units (AUs), morph targets, visemes, and bone control.
- */
-export interface EmbodyRuntime 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;
-}

package/dist/interfaces/Hair.d.ts

@@ -1,181 +0,0 @@
-/**
- * Hair Interface
- *
- * Groups hair registration, styling, and physics methods.
- */
-import type { Mesh, Object3D } from 'three';
-export interface HairObjectRef {
-    name: string;
-    isMesh: boolean;
-    isEyebrow: boolean;
-}
-export interface HairPhysicsDirectionConfig {
-    yawSign: 1 | -1;
-    pitchSign: 1 | -1;
-}
-export interface HairMorphTargetsConfig {
-    swayLeft: string;
-    swayRight: string;
-    swayFront: string;
-    fluffRight: string;
-    fluffBottom: string;
-    headUp: Record<string, number>;
-    headDown: Record<string, number>;
-}
-export 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;
-    morphTargets: HairMorphTargetsConfig;
-}
-export type HairPhysicsRuntimeConfigUpdate = Partial<HairPhysicsRuntimeConfig> & {
-    direction?: Partial<HairPhysicsDirectionConfig>;
-    morphTargets?: Partial<HairMorphTargetsConfig>;
-};
-export 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;
-}
-export interface HairColorAppearance {
-    name?: string;
-    baseColor: string;
-    emissive: string;
-    emissiveIntensity: number;
-}
-export interface HairAppearanceState {
-    hairColor: Required<Pick<HairColorAppearance, 'baseColor' | 'emissive' | 'emissiveIntensity'>> & {
-        name?: string;
-    };
-    eyebrowColor: Required<Pick<HairColorAppearance, 'baseColor' | 'emissive' | 'emissiveIntensity'>> & {
-        name?: string;
-    };
-    showOutline: boolean;
-    outlineColor: string;
-    outlineOpacity: number;
-}
-export interface Hair {
-    /**
-     * Register hair objects from a scene.
-     * Returns engine-agnostic references for UI and runtime helpers.
-     * Registration must not rewrite material colors.
-     */
-    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;
-    /**
-     * Sample current hair/eyebrow material appearance from registered meshes.
-     * Does not mutate the scene.
-     */
-    getHairAppearance(): HairAppearanceState;
-    /**
-     * Apply color to registered non-eyebrow hair meshes.
-     */
-    setHairColor(color: HairColorAppearance | string): void;
-    /**
-     * Apply color to registered eyebrow meshes.
-     */
-    setEyebrowColor(color: HairColorAppearance | string): void;
-    /**
-     * Update hair base color only (keeps emissive settings).
-     */
-    setHairBaseColor(baseColor: string): void;
-    /**
-     * Update eyebrow base color only (keeps emissive settings).
-     */
-    setEyebrowBaseColor(baseColor: string): void;
-    /**
-     * Update hair glow (emissive + intensity).
-     */
-    setHairGlow(emissive: string, intensity: number): void;
-    /**
-     * Update eyebrow glow (emissive + intensity).
-     */
-    setEyebrowGlow(emissive: string, intensity: number): void;
-    /**
-     * Toggle/update hair mesh outline for all registered hair objects.
-     */
-    setHairOutline(outline: {
-        show: boolean;
-        color?: string;
-        opacity?: number;
-    }): void;
-}

package/dist/interfaces/HairPhysics.d.ts

@@ -1,90 +0,0 @@
-/**
- * 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
- */
-export interface HairPhysicsConfig {
-    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
- */
-export 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
- */
-export interface HairState {
-    x: number;
-    z: number;
-    vx: number;
-    vz: number;
-}
-/**
- * Head orientation state for physics input
- */
-export interface HeadState {
-    yaw: number;
-    pitch: number;
-    roll: number;
-    yawVelocity: number;
-    pitchVelocity: number;
-}
-/**
- * Output morph values from physics simulation
- */
-export interface HairMorphOutput {
-    [morphKey: string]: number;
-}
-/**
- * Hair Physics simulation interface
- */
-export interface HairPhysics {
-    /**
-     * 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;
-    /**
-     * Get current physics state (for debugging/UI)
-     */
-    getState(): HairState;
-    /**
-     * Update configuration
-     */
-    setConfig(config: Partial<HairPhysicsConfig>): void;
-    /**
-     * Get current configuration
-     */
-    getConfig(): HairPhysicsConfig;
-    /**
-     * Reset physics state to rest position
-     */
-    reset(): void;
-}

package/dist/interfaces/index.d.ts

@@ -1,11 +0,0 @@
-/**
- * Embody Interfaces
- *
- * Framework-agnostic interfaces for 3D character animation.
- * Implement these interfaces to add support for different 3D engines.
- */
-export type { EmbodyRuntime, ReadyPayload, EmbodyConfig, } from './EmbodyRuntime';
-export type { MeshInfo } from '../mappings/types';
-export type { Animation, MixerLoopMode } from './Animation';
-export type { HairPhysics, HairPhysicsConfig, HairStrand, HairState } from './HairPhysics';
-export type { Hair, HairPhysicsRuntimeConfig, HairPhysicsRuntimeConfigUpdate, HairPhysicsDirectionConfig, HairMorphTargetsConfig, HairObjectRef, HairObjectState, } from './Hair';