@lovelace_lol/embody 0.0.1

package/dist/engines/three/ThreeAnimationRuntime.d.ts

@@ -0,0 +1,203 @@
+/**
+ * ThreeAnimationRuntime - Lerp-based animation driver
+ *
+ * Internal driver for time-based interpolation with easing functions.
+ */
+import { AnimationClip, Quaternion } from 'three';
+import type { Mesh, Object3D } from 'three';
+import type { TransitionHandle, AnimationPlayOptions, AnimationClipInfo, AnimationState, AnimationActionHandle, CurvesMap, ClipOptions, ClipHandle, Snippet, CompositeRotation, AnimationBlendMode, SnippetChannel, TypedSnippet, EmbodyAnimationRuntimeFactory } from '../../core/types';
+import type { Profile } from '../../mappings/types';
+import type { ResolvedBones } from './types';
+declare const easeInOutQuad: (t: number) => number;
+declare const easeInOutCubic: (t: number) => number;
+export { easeInOutQuad, easeInOutCubic };
+export declare class ThreeAnimationRuntime {
+    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;
+}
+export interface ThreeAnimationSystemHost {
+    getModel: () => Object3D | null;
+    getMeshes: () => Mesh[];
+    getMeshByName: (name: string) => Mesh | undefined;
+    getMeshNamesForAU?: (auId: number) => string[];
+    getMeshNamesForViseme?: () => string[];
+    getCurrentAUValue?: (auId: number) => number;
+    getCurrentVisemeValue?: (visemeIndex: number) => number;
+    getCurrentMorphValue?: (morphKey: string, meshNames?: string[]) => number;
+    getCurrentMorphIndexValue?: (morphIndex: number, meshNames?: string[]) => number;
+    getCurrentBoneQuaternion?: (nodeKey: string) => Quaternion | null;
+    getCurrentBonePositionValue?: (nodeKey: string, axis: 'x' | 'y' | 'z') => number | null;
+    getBones: () => ResolvedBones;
+    getConfig: () => Profile;
+    getCompositeRotations: () => CompositeRotation[];
+    computeSideValues: (base: number, balance?: number) => {
+        left: number;
+        right: number;
+    };
+    getAUMixWeight: (auId: number) => number;
+    isMixedAU: (auId: number) => boolean;
+    reapplyProceduralState?: () => void;
+}
+/** @deprecated Use ThreeAnimationSystemHost. */
+export type AnimationControllerHost = ThreeAnimationSystemHost;
+/** @deprecated Use ThreeAnimationSystemHost. */
+export type BakedAnimationHost = ThreeAnimationSystemHost;
+export type ThreeAnimationSystemOptions = {
+    animationRuntimeFactory?: EmbodyAnimationRuntimeFactory;
+};
+type ClipParamsUpdate = {
+    weight?: number;
+    rate?: number;
+    loop?: boolean;
+    loopMode?: 'once' | 'repeat' | 'pingpong';
+    repeatCount?: number;
+    reverse?: boolean;
+    actionId?: string;
+};
+export declare class ThreeAnimationSystem {
+    private host;
+    private animationMixer;
+    private clipAnimationMixer;
+    private mixerFinishedListenerAttached;
+    private clipMixerFinishedListenerAttached;
+    private animationClips;
+    private bakedSourceClips;
+    private bakedMixerActions;
+    private bakedAdditiveMixerClips;
+    private bakedActionGroups;
+    private bakedMixerClipToSource;
+    private animationActions;
+    private animationFinishedCallbacks;
+    private clipActions;
+    private clipHandles;
+    private rendererClipHandles;
+    private clipSources;
+    private playbackState;
+    private actionIds;
+    private actionIdToClip;
+    private clipMonitors;
+    private dynamicClipSources;
+    private cljsAnimationRuntime;
+    constructor(host: ThreeAnimationSystemHost, options?: ThreeAnimationSystemOptions);
+    private shouldDebugClipLogs;
+    private debugClipLog;
+    private createRuntimeConnector;
+    getRuntimeSnapshot(): Record<string, unknown> | null;
+    private getActionId;
+    private setActionId;
+    private clearActionId;
+    private uncacheClip;
+    private uncacheAction;
+    private releaseBakedMixerAction;
+    private clearBakedAdditiveMixerClip;
+    private clearAllBakedAdditiveMixerClips;
+    private resolveTrackTarget;
+    private getMorphTrackBaseValue;
+    private canCreateFirstFrameReferenceTrack;
+    private createFirstFrameReferenceTrack;
+    private createAdditiveReferenceTrack;
+    private createAdditiveMixerClip;
+    private getOrCreateBakedAdditiveMixerClip;
+    private setClipEventMetadata;
+    private getClipEventMetadata;
+    private curvesHaveInheritedStart;
+    private channelsHaveInheritedStart;
+    private rebuildDynamicClip;
+    private resolveInheritedClipForPlayback;
+    private getKeyframeIndex;
+    private emitClipEvent;
+    private emitKeyframesForRange;
+    private resetClipMonitor;
+    private syncClipMonitorTime;
+    private cleanupClipMonitor;
+    private advanceClipMonitor;
+    private normalizePlaybackOptions;
+    private applyPlaybackState;
+    private setPlaybackState;
+    private getPlaybackStateSnapshot;
+    private mergePlaybackOptions;
+    private isBakedSourceClip;
+    private getBakedSourceClip;
+    private getBakedChannelInfo;
+    private getBakedAggregateBlendMode;
+    private applyPlaybackStateToBakedAction;
+    private resolveStartTime;
+    private getOrCreateBakedMixerAction;
+    private getRepresentativeBakedAction;
+    private createBakedActionGroup;
+    private getMeshNamesForAU;
+    private getMeshNamesForViseme;
+    private hasActiveAdditivePlayback;
+    update(dtSeconds: number): void;
+    dispose(): void;
+    loadAnimationClips(clips: unknown[]): void;
+    getAnimationClips(): AnimationClipInfo[];
+    removeAnimationClip(clipName: string): boolean;
+    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;
+    setAnimationLoopMode(clipName: string, loopMode: 'repeat' | 'once' | 'pingpong'): void;
+    setAnimationRepeatCount(clipName: string, repeatCount?: number): void;
+    setAnimationReverse(clipName: string, reverse: boolean): void;
+    setAnimationBlendMode(clipName: string, blendMode: AnimationBlendMode): void;
+    seekAnimation(clipName: string, time: 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;
+    typedSnippetToClip(clipName: string, channels: SnippetChannel[], options?: ClipOptions): AnimationClip | null;
+    private playClipDirect;
+    playClip(clip: AnimationClip, options?: ClipOptions): ClipHandle | null;
+    playSnippet(snippet: Snippet | {
+        name: string;
+        curves: CurvesMap;
+    } | TypedSnippet | {
+        name: string;
+        channels: SnippetChannel[];
+    }, options?: ClipOptions): ClipHandle | null;
+    playTypedSnippet(snippet: TypedSnippet | {
+        name: string;
+        channels: SnippetChannel[];
+    }, options?: ClipOptions): ClipHandle | null;
+    buildClip(clipName: string, curves: CurvesMap, options?: ClipOptions): ClipHandle | null;
+    private buildClipDirect;
+    buildTypedClip(clipName: string, channels: SnippetChannel[], options?: ClipOptions): ClipHandle | null;
+    cleanupSnippet(name: string): void;
+    private cleanupSnippetDirect;
+    updateClipParams(name: string, params: ClipParamsUpdate): boolean;
+    private updateClipParamsDirect;
+    private addMorphTracks;
+    private addMorphIndexTracks;
+    private sampleFinalKeyframeValue;
+    private ensureMixer;
+    private ensureClipMixer;
+    private handleMixerFinished;
+    private createAnimationHandle;
+    private createBakedAnimationHandle;
+}
+/** @deprecated Use ThreeAnimationSystem. */
+export { ThreeAnimationSystem as AnimationController };
+/** @deprecated Use ThreeAnimationSystem. */
+export { ThreeAnimationSystem as BakedAnimationController };

package/dist/engines/three/ThreeClipAdapter.d.ts

@@ -0,0 +1,24 @@
+import { AnimationClip } from 'three';
+import type { Object3D } from 'three';
+import type { BoneId, ClipIR, MeshId, MorphTargetId } from '../../core/contracts';
+export interface ThreeClipMeshBinding {
+    readonly trackName: string;
+}
+export interface ThreeClipMorphTargetBinding {
+    readonly meshId: MeshId;
+    readonly index: number;
+}
+export interface ThreeClipAdapterBindings {
+    readonly meshes?: ReadonlyMap<MeshId, Object3D | ThreeClipMeshBinding>;
+    readonly morphTargets?: ReadonlyMap<MorphTargetId, ThreeClipMorphTargetBinding>;
+    readonly bones?: ReadonlyMap<BoneId, Object3D | string>;
+}
+export declare class ThreeClipAdapter {
+    private meshes;
+    private morphTargets;
+    private bones;
+    constructor(bindings?: ThreeClipAdapterBindings);
+    setBindings(bindings: ThreeClipAdapterBindings): void;
+    toAnimationClip(clip: ClipIR): AnimationClip;
+    private toKeyframeTrack;
+}

package/dist/engines/three/ThreeFrameApplier.d.ts

@@ -0,0 +1,68 @@
+import type { Mesh, Object3D } from 'three';
+import type { BoneId, FrameDelta, HostFrameApplier, MeshId, MorphTargetId, Transform } from '../../core/contracts';
+export interface ThreeMorphTargetBinding {
+    readonly meshId: MeshId;
+    readonly mesh: Mesh;
+    readonly index: number;
+}
+export interface ThreeFrameApplierBindings {
+    readonly meshes?: ReadonlyMap<MeshId, Mesh>;
+    readonly morphTargets?: ReadonlyMap<MorphTargetId, ThreeMorphTargetBinding>;
+    readonly bones?: ReadonlyMap<BoneId, Object3D>;
+}
+export interface ThreeMaterialConfig {
+    renderOrder?: number;
+    transparent?: boolean;
+    opacity?: number;
+    depthWrite?: boolean;
+    depthTest?: boolean;
+    blending?: keyof typeof THREE_BLENDING_MODES;
+}
+export interface ThreeResolvedMaterialConfig {
+    renderOrder: number;
+    transparent: boolean;
+    opacity: number;
+    depthWrite: boolean;
+    depthTest: boolean;
+    blending: keyof typeof THREE_BLENDING_MODES;
+}
+export interface ThreeMeshMaterialConfig {
+    readonly material?: ThreeMaterialConfig;
+}
+export declare const THREE_BLENDING_MODES: {
+    readonly Normal: 1;
+    readonly Additive: 2;
+    readonly Subtractive: 3;
+    readonly Multiply: 4;
+    readonly None: 0;
+};
+export declare class ThreeFrameApplier implements HostFrameApplier<Object3D> {
+    private meshes;
+    private morphTargets;
+    private bones;
+    private originalEmissive;
+    constructor(bindings?: ThreeFrameApplierBindings);
+    setBindings(bindings: ThreeFrameApplierBindings): void;
+    applyFrameDelta(model: Object3D, frame: FrameDelta): void;
+    applyPackedMorphFrameDelta(values: ArrayLike<number>, stride?: number): void;
+    /** Rows: `[boneId, px, py, pz, qx, qy, qz, qw, flags]`; flags bit0=position, bit1=rotation. */
+    applyPackedBoneFrameDelta(values: ArrayLike<number>, stride?: number): void;
+    applyObjectTransform(target: Object3D, transform: Transform, mode?: 'absolute' | 'additive'): void;
+    applyMorphTargets(targets: readonly {
+        infl: number[];
+        idx: number;
+    }[], value: number): void;
+    resetMorphTargets(targets: readonly {
+        infl: number[];
+        idx: number;
+    }[]): void;
+    setMeshVisible(root: Object3D, meshName: string, visible: boolean): void;
+    highlightMesh(root: Object3D, meshName: string | null, color?: number, intensity?: number): void;
+    getMeshMaterialConfig(root: Object3D, meshName: string): ThreeResolvedMaterialConfig | null;
+    setMeshMaterialConfig(root: Object3D, meshName: string, config: ThreeMaterialConfig): void;
+    applyMeshMaterialConfigs(root: Object3D, configs: Readonly<Record<string, ThreeMeshMaterialConfig>>): void;
+    private applyMeshMaterialConfig;
+    private setMorphTarget;
+    private applyTransform;
+    private visitNamedMesh;
+}

package/dist/engines/three/ThreeModelInspector.d.ts

@@ -0,0 +1,54 @@
+import type { AnimationClip, Mesh, Object3D } from 'three';
+import type { HostModelInspector, ModelDescriptor } from '../../core/contracts';
+import type { Profile } from '../../mappings/types';
+import type { ResolvedBones } from './types';
+export interface ThreeAnimationTrackDescriptor {
+    readonly name: string;
+    readonly targetName: string;
+    readonly property: string;
+    readonly type: 'position' | 'rotation' | 'scale' | 'morph' | 'unknown';
+    readonly keyframeCount: number;
+    readonly valueSize: number;
+    readonly valueRange?: {
+        readonly min: readonly number[];
+        readonly max: readonly number[];
+    };
+}
+export interface ThreeAnimationClipDescriptor {
+    readonly name: string;
+    readonly duration: number;
+    readonly tracks: readonly ThreeAnimationTrackDescriptor[];
+    readonly animatedBones: readonly string[];
+    readonly animatedMorphs: readonly string[];
+}
+export interface ThreeModelInspectionOptions {
+    readonly meshes?: readonly Mesh[];
+    readonly profile?: Profile;
+    readonly previousBones?: ResolvedBones;
+    readonly animations?: readonly AnimationClip[];
+}
+export interface ThreeModelInspection {
+    readonly descriptor: ModelDescriptor;
+    readonly meshByName: Map<string, Mesh>;
+    readonly allMeshes: Mesh[];
+    readonly morphMeshes: Mesh[];
+    readonly bones: ResolvedBones;
+    readonly resolvedFaceMeshes: string[];
+    readonly faceMesh: Mesh | null;
+    readonly animations: ThreeAnimationClipDescriptor[];
+}
+export declare class ThreeModelInspector implements HostModelInspector<Object3D> {
+    describeModel(model: Object3D): ModelDescriptor;
+    inspectModel(model: Object3D, options?: ThreeModelInspectionOptions): ThreeModelInspection;
+    collectMeshes(root: Object3D): Mesh[];
+    buildMeshByName(root: Object3D): Map<string, Mesh>;
+    resolveBones(root: Object3D, profile: Profile, previousBones?: ResolvedBones): ResolvedBones;
+    resolveFaceMeshes(meshes: readonly Mesh[], meshByName: ReadonlyMap<string, Mesh>, bones: ResolvedBones, profile: Profile): string[];
+    describeAnimations(animations: readonly AnimationClip[]): ThreeAnimationClipDescriptor[];
+    private mergeMorphMeshes;
+    private buildDescriptor;
+    private collectDescriptorBoneObjects;
+    private findNearestDescriptorBoneId;
+    private describeTrack;
+}
+export declare function collectMorphMeshes(root: Object3D): Mesh[];

package/dist/engines/three/bakedClipPartitioning.d.ts

@@ -0,0 +1,16 @@
+import { AnimationClip, KeyframeTrack, Object3D } from 'three';
+import type { AnimationBlendMode, BakedClipChannel, BakedClipChannelInfo } from '../../core/types';
+import type { ResolvedBones } from './types';
+export interface PartitionedBakedMixerClip {
+    channel: BakedClipChannel;
+    clip: AnimationClip;
+}
+export interface PartitionedBakedClip {
+    sourceClip: AnimationClip;
+    channels: BakedClipChannelInfo[];
+    mixerClips: PartitionedBakedMixerClip[];
+}
+export declare function classifyBakedTrack(track: KeyframeTrack, model: Object3D, bones: ResolvedBones): BakedClipChannel;
+export declare function resolveBakedChannelBlendMode(channel: BakedClipChannel, requestedBlendMode: AnimationBlendMode): AnimationBlendMode | undefined;
+export declare function resolveBakedAggregateBlendMode(channels: BakedClipChannelInfo[], requestedBlendMode: AnimationBlendMode): AnimationBlendMode;
+export declare function partitionBakedClip(clip: AnimationClip, model: Object3D, bones: ResolvedBones): PartitionedBakedClip;

package/dist/engines/three/balanceUtils.d.ts

@@ -0,0 +1,3 @@
+export declare function clampBalance(value: number): number;
+export declare function getSideScale(balance: number, side?: 'left' | 'right'): number;
+export declare function resolveCurveBalance(curveId: string, globalBalance: number, balanceMap?: Record<string, number>): number;

package/dist/engines/three/characterHost.d.ts

@@ -0,0 +1,80 @@
+/**
+ * High-level character host: default scene + model load + Embody binding.
+ *
+ * Default path: pass a container HTMLElement + character model URL.
+ * Advanced path: inject an existing Three.js scene/renderer/camera.
+ */
+import { type AnimationClip, type Camera, type Mesh, type Object3D, type PerspectiveCamera, type Scene, type WebGLRenderer } from 'three';
+import type { EmbodyConfig } from '../../interfaces/EmbodyRuntime';
+import { Embody } from './Embody';
+import { type DefaultCharacterLightingController, type DefaultCharacterSceneOptions } from './characterScene';
+import { type CharacterModelLoadOptions, type CharacterModelTransform } from './modelLoader';
+export interface CharacterHostCharacterOptions extends CharacterModelTransform {
+    /** Resolved model URL (GLB/GLTF/FBX). */
+    modelUrl: string;
+    /** Optional Embody preset / profile (also accepted via `embody`). */
+    presetType?: EmbodyConfig['presetType'];
+    profile?: EmbodyConfig['profile'];
+}
+export interface CharacterHostExternalScene {
+    scene: Scene;
+    renderer: WebGLRenderer;
+    camera: Camera;
+    /**
+     * When true, host appends `renderer.domElement` into `container` if it is not
+     * already mounted. Default: false.
+     */
+    mountCanvas?: boolean;
+    /** When true, host listens for window resize. Default: false for external. */
+    manageResize?: boolean;
+}
+export interface CharacterHostOptions {
+    /** Element that receives the WebGL canvas in the default scene path. */
+    container: HTMLElement;
+    /** Character to load and bind. */
+    character: CharacterHostCharacterOptions;
+    /** Embody runtime config. `presetType` / `profile` on character win when both set. */
+    embody?: EmbodyConfig;
+    /** Default-scene options (ignored when `external` is provided). */
+    scene?: DefaultCharacterSceneOptions;
+    /** Advanced: inject an existing Three.js scene instead of creating one. */
+    external?: CharacterHostExternalScene;
+    /** Model loader options (progress, Draco path, shadows). */
+    loader?: CharacterModelLoadOptions;
+    /** Call `engine.start()` after binding. Default: true */
+    autoStart?: boolean;
+    /**
+     * Run a requestAnimationFrame render loop (`renderer.render(scene, camera)`).
+     * Default: true when Embody owns the scene, false when `external` is given.
+     */
+    renderLoop?: boolean;
+    /**
+     * Frame the camera on the loaded model (position + lookAt). Applies on every
+     * `setCharacter`. Default: true when Embody owns the scene, false otherwise.
+     */
+    autoFrame?: boolean;
+}
+export interface CharacterHost {
+    engine: Embody;
+    scene: Scene;
+    renderer: WebGLRenderer;
+    camera: Camera | PerspectiveCamera;
+    model: Object3D;
+    meshes: Mesh[];
+    animations: AnimationClip[];
+    lighting: DefaultCharacterLightingController | null;
+    /** True when Embody created and owns the default scene/renderer. */
+    ownsScene: boolean;
+    container: HTMLElement;
+    /** Replace the loaded character while keeping the same scene/engine. */
+    setCharacter: (character: CharacterHostCharacterOptions, loader?: CharacterModelLoadOptions) => Promise<void>;
+    resize: () => void;
+    dispose: () => void;
+}
+/**
+ * Create a character host.
+ *
+ * Default: Embody creates the Three.js scene inside `container` and loads
+ * `character.modelUrl`. Advanced: pass `external` with an existing scene.
+ */
+export declare function createCharacterHost(options: CharacterHostOptions): Promise<CharacterHost>;

package/dist/engines/three/characterScene.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Default Three.js scene host for Embody characters.
+ *
+ * Creates renderer / scene / camera / lighting / shadow plane and mounts the
+ * canvas into a caller-supplied HTMLElement. Advanced callers can skip this
+ * and inject an existing Three.js scene via createCharacterHost.
+ */
+import { Mesh, PerspectiveCamera, Scene, WebGLRenderer, type Texture } from 'three';
+export type DefaultCharacterLightingPresetId = 'cleanStudio' | 'softFill' | 'inspection' | 'contrast';
+export interface DefaultCharacterLightingSettings {
+    envMapEnabled: boolean;
+    environmentIntensity: number;
+    environmentBlur: number;
+    exposure: number;
+    ambientIntensity: number;
+    keyIntensity: number;
+    fillIntensity: number;
+    rimIntensity: number;
+    shadowOpacity: number;
+}
+export interface DefaultCharacterLightingController {
+    getSettings: () => DefaultCharacterLightingSettings;
+    getEnvironmentTexture: () => Texture | null;
+    setSettings: (patch: Partial<DefaultCharacterLightingSettings>) => DefaultCharacterLightingSettings;
+    setPreset: (presetId: DefaultCharacterLightingPresetId) => DefaultCharacterLightingSettings;
+    subscribe: (listener: (settings: DefaultCharacterLightingSettings) => void) => () => void;
+    dispose: () => void;
+}
+export type CharacterSceneTypeId = 'studio' | 'showcase' | 'inspection' | 'void';
+/** A named bundle of scene defaults (background, lighting preset, shadow plane). */
+export interface CharacterSceneTypeDefinition {
+    id: CharacterSceneTypeId;
+    label: string;
+    description: string;
+    /** Scene background color (hex), or null for a transparent canvas. */
+    background: number | null;
+    lightingPreset: DefaultCharacterLightingPresetId;
+    shadowPlane: boolean;
+}
+export interface DefaultCharacterSceneOptions {
+    /** Named scene type providing background/lighting/shadow defaults. Default: 'studio' */
+    type?: CharacterSceneTypeId;
+    /** Perspective camera FOV. Default: 45 */
+    cameraFov?: number;
+    /** Cap device pixel ratio. Default: 1.5 */
+    pixelRatioCap?: number;
+    /** Enable shadow maps. Default: true */
+    shadows?: boolean;
+    /** Add a ground shadow receiver. Default: from scene type */
+    shadowPlane?: boolean;
+    /** Scene background color (hex or CSS string), or null for transparent. Default: from scene type */
+    background?: number | string | null;
+    /** Initial lighting settings / overrides */
+    lighting?: Partial<DefaultCharacterLightingSettings>;
+    /** Lighting preset applied before lighting overrides. Default: from scene type */
+    lightingPreset?: DefaultCharacterLightingPresetId;
+    /** Listen for window resize. Default: true */
+    manageResize?: boolean;
+}
+export interface DefaultCharacterScene {
+    container: HTMLElement;
+    scene: Scene;
+    renderer: WebGLRenderer;
+    camera: PerspectiveCamera;
+    lighting: DefaultCharacterLightingController;
+    shadowPlane: Mesh | null;
+    /** Resolved scene type used for defaults. */
+    sceneType: CharacterSceneTypeId;
+    ownsScene: true;
+    resize: () => void;
+    dispose: () => void;
+}
+export declare const DEFAULT_CHARACTER_SCENE_TYPE_ID: CharacterSceneTypeId;
+export declare const CHARACTER_SCENE_TYPES: Record<CharacterSceneTypeId, CharacterSceneTypeDefinition>;
+export declare const CHARACTER_SCENE_TYPE_IDS: readonly CharacterSceneTypeId[];
+export declare const DEFAULT_CHARACTER_LIGHTING_PRESET_ID: DefaultCharacterLightingPresetId;
+export declare const DEFAULT_CHARACTER_LIGHTING_PRESETS: Record<DefaultCharacterLightingPresetId, {
+    id: DefaultCharacterLightingPresetId;
+    label: string;
+    settings: DefaultCharacterLightingSettings;
+}>;
+export declare const DEFAULT_CHARACTER_LIGHTING_SETTINGS: DefaultCharacterLightingSettings;
+export declare const DEFAULT_CHARACTER_LIGHTING_PRESET_IDS: readonly DefaultCharacterLightingPresetId[];
+/**
+ * Normalize persisted / untrusted lighting settings (e.g. profile JSON).
+ * Returns null when the value is not a plain object.
+ */
+export declare function normalizeDefaultCharacterLightingSettings(value: unknown): DefaultCharacterLightingSettings | null;
+export declare function createShadowPlane(scene: Scene, options?: {
+    size?: number;
+    opacity?: number;
+    yPosition?: number;
+}): Mesh;
+export declare function createDefaultCharacterLighting(scene: Scene, renderer: WebGLRenderer, initialSettings?: Partial<DefaultCharacterLightingSettings>): DefaultCharacterLightingController;
+/**
+ * Create a default Embody character scene mounted into `container`.
+ */
+export declare function createDefaultCharacterScene(container: HTMLElement, options?: DefaultCharacterSceneOptions): DefaultCharacterScene;

package/dist/engines/three/hair/HairPhysicsController.d.ts

@@ -0,0 +1,124 @@
+import { Mesh } from 'three';
+import type { Object3D } from 'three';
+import type { ClipHandle, ClipOptions, CurvesMap } from '../../../core/types';
+import type { HairPhysicsDirectionConfig as SharedHairPhysicsDirectionConfig, HairMorphTargetsConfig as SharedHairMorphTargetsConfig, HairPhysicsRuntimeConfig as SharedHairPhysicsConfig, HairPhysicsRuntimeConfigUpdate as SharedHairPhysicsConfigUpdate, HairAppearanceState, HairColorAppearance } from '../../../interfaces/Hair';
+import type { HairPhysicsProfileConfig } from '../../../mappings/types';
+import type { EmbodyCoreWasmModule } from '../../../wasmTypes';
+export type HairPhysicsDirectionConfig = SharedHairPhysicsDirectionConfig;
+export type HairMorphTargets = SharedHairMorphTargetsConfig;
+export type HairPhysicsConfig = SharedHairPhysicsConfig;
+export type HairPhysicsConfigUpdate = SharedHairPhysicsConfigUpdate;
+export interface HairPhysicsHost {
+    getMeshByName: (name: string) => Mesh | undefined;
+    getSelectedHairMeshNames?: () => string[];
+    buildClip?: (clipName: string, curves: CurvesMap, options?: ClipOptions) => ClipHandle | null;
+    cleanupSnippet?: (name: string) => void;
+}
+export declare class HairPhysicsController {
+    private host;
+    private core;
+    private hairPhysicsEnabled;
+    private hairPhysicsConfig;
+    private readonly idleClipName;
+    private readonly gravityClipName;
+    private readonly impulseClipNames;
+    private idleClipHandle;
+    private gravityClipHandle;
+    private idleClipDirty;
+    private gravityClipDirty;
+    private impulseClips;
+    private impulseClipDirty;
+    private impulseEndTimers;
+    private impulseFadeSteps;
+    private hasHeadState;
+    private lastHeadHorizontal;
+    private lastHeadVertical;
+    private registeredHairObjects;
+    private cachedHairMeshNames;
+    private warnedMissingMorphTargets;
+    private appearance;
+    private appearanceSampled;
+    constructor(host: HairPhysicsHost);
+    /** Attach the Wasm module owned by the engine/session that created this controller. */
+    setCore(core: EmbodyCoreWasmModule): void;
+    private requireCore;
+    private isEyebrowMesh;
+    private sampleColorFromMesh;
+    private ensureAppearanceSampled;
+    private applyColorToCategory;
+    getHairAppearance(): HairAppearanceState;
+    setHairColor(color: HairColorAppearance | string): void;
+    setEyebrowColor(color: HairColorAppearance | string): void;
+    setHairBaseColor(baseColor: string): void;
+    setEyebrowBaseColor(baseColor: string): void;
+    setHairGlow(emissive: string, intensity: number): void;
+    setEyebrowGlow(emissive: string, intensity: number): void;
+    setHairOutline(outline: {
+        show: boolean;
+        color?: string;
+        opacity?: number;
+    }): void;
+    clearRegisteredHairObjects(): void;
+    registerHairObjects(objects: Object3D[]): Array<{
+        name: string;
+        isMesh: boolean;
+        isEyebrow: boolean;
+    }>;
+    autoRegisterHairMesh(mesh: Mesh, category: 'hair' | 'eyebrow'): void;
+    getRegisteredHairObjects(): Mesh[];
+    setHairPhysicsEnabled(enabled: boolean): void;
+    isHairPhysicsEnabled(): boolean;
+    setHairPhysicsProfileConfig(hairConfig?: HairPhysicsProfileConfig): void;
+    setHairPhysicsConfig(config: HairPhysicsConfigUpdate): void;
+    getHairPhysicsConfig(): HairPhysicsConfig;
+    validateHairMorphTargets(): string[];
+    update(dtSeconds: number): void;
+    onHeadRotationChanged(yaw: number, pitch: number): void;
+    getHairMorphTargets(meshName?: string): string[];
+    private collectConfiguredMorphKeys;
+    private collectAvailableHairMorphKeys;
+    private warnMissingHairMorphTargets;
+    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 getHairMeshNames;
+    refreshMeshSelection(): void;
+    private supportsMixerClips;
+    private startIdleClip;
+    private startGravityClip;
+    private stopIdleClip;
+    private stopGravityClip;
+    private buildImpulseClips;
+    private stopImpulseClips;
+    private clearImpulseTimers;
+    private triggerHeadImpulse;
+    private updateGravityFromHeadPitch;
+    private playImpulseClip;
+    private fadeImpulseClip;
+    private buildIdleWindCurves;
+    private buildImpulseCurves;
+    private buildGravityCurves;
+    private hairCurveConfigJson;
+}