illutions 0.34.0 → 0.35.0

package/dist/main.d.ts

@@ -19,7 +19,10 @@ export declare interface AaCfg {
     guiOpened: boolean;
 }
 
-/** Anti-aliasing modes available across rendering backends. */
+/**
+ * Anti-aliasing modes available across rendering backends; 'none' disables smoothing.
+ * See {@link AaModeWebGl} and {@link AaModeWebGpu} for backend-specific values.
+ */
 export declare type AaMode = AaModeWebGl | AaModeWebGpu;
 
 /** Anti-aliasing modes available with WebGL. */
@@ -28,8 +31,6 @@ export declare type AaModeWebGl = 'none' | 'fxaa' | 'smaa';
 /** Anti-aliasing modes available with WebGPU. */
 export declare type AaModeWebGpu = 'none' | 'fxaa' | 'smaa' | 'traa';
 
-export declare type ActionFadeMode = 'in' | 'out';
-
 /**
  * Controls uniform ambient illumination.
  * @category Cfg
@@ -54,6 +55,7 @@ export declare interface AmbientlightCfg {
 
 /** @event Fired when an object or material color animation starts, completes, or is canceled. */
 export declare interface AnimEvent {
+    /** Event identifier used to select listeners and state machine transitions. */
     type: 'Anim_Complete' | 'Anim_Start' | 'Anim_Cancel';
     /** The name of the `THREE.Object3D` whose animation changed state. */
     objName: string;
@@ -63,6 +65,7 @@ export declare interface AnimEvent {
 
 /** @event Fired when a material color or numeric property animation starts, completes, or is canceled. */
 export declare interface AnimMaterialEvent {
+    /** Event identifier used to select listeners and state machine transitions. */
     type: 'Anim_Material_Complete' | 'Anim_Material_Start' | 'Anim_Material_Cancel';
     /** The name of the material whose animation changed state. */
     materialName: string;
@@ -72,31 +75,94 @@ export declare interface AnimMaterialEvent {
     values: Record<string, number | string>;
 }
 
+/** Target object, orientation, and animation settings shared by rotation methods. */
+declare interface AnimRotOptions {
+    /** Exact Three.js object name, including cameras. */
+    obj: string;
+    /** Target X angle in radians; omitted axes keep their starting target angles. */
+    x?: number;
+    /** Target Y angle in radians. */
+    y?: number;
+    /** Target Z angle in radians. */
+    z?: number;
+    /** Rotation interpolation. Default: **'euler'**; **'quat'** takes the shortest orientation path. */
+    path?: 'euler' | 'quat';
+    /** Euler order for interpreting angles in both paths. Default: **'XYZ'** */
+    order?: THREE_TYPE.EulerOrder;
+    /** Orientation space. Default: **'parent'** */
+    space?: 'parent' | 'world';
+    /** Duration in seconds. Default: **1**. A value of 0 applies the values immediately. */
+    time?: number;
+    /** GSAP easing function. Default: **'power2.inOut'** */
+    ease?: string;
+}
+
+/** Target object, scale, and animation settings shared by scaling methods. */
+declare interface AnimScaleOptions {
+    /** Exact Three.js object name, including cameras. */
+    obj: string;
+    /** Target X scale; omitted axes remain unchanged. */
+    x?: number;
+    /** Target Y scale. */
+    y?: number;
+    /** Target Z scale. */
+    z?: number;
+    /** Duration in seconds. Default: **1**. A value of 0 applies the values immediately. */
+    time?: number;
+    /** GSAP easing function. Default: **'power2.inOut'** */
+    ease?: string;
+}
+
+/** Target object, position, and animation settings shared by translation methods. */
+declare interface AnimTranslOptions {
+    /** Exact Three.js object name, including cameras. */
+    obj: string;
+    /** Target X position; omitted axes keep their starting values. */
+    x?: number;
+    /** Target Y position. */
+    y?: number;
+    /** Target Z position. */
+    z?: number;
+    /** Position space. Default: **'parent'** */
+    space?: 'parent' | 'world';
+    /** Duration in seconds. Default: **1**. A value of 0 applies the values immediately. */
+    time?: number;
+    /** GSAP easing function. Default: **'power2.inOut'** */
+    ease?: string;
+}
+
 /**
  * Starts the application and provides access to its components and runtime systems.
  * @category Core
  */
-export declare class App<TComps extends Comps = {}> {
+export declare class App<TAssets extends Assets = {}> {
+    /** Controls loaded sounds by their case-sensitive names and provides shared listener and positional settings. */
     readonly audio: Audio_2;
+    /** Controls any loaded model clip by name, without requiring asset registration. */
+    readonly clips: Clips;
     private readonly ctrl;
     readonly engine: Engine;
-    private readonly model;
     readonly envCtrls: EnvCtrls;
     readonly events: Events;
-    readonly orbitCtrls: OrbitCtrls;
     readonly fpvCtrls: FpvCtrls;
+    private readonly model;
+    readonly orbitCtrls: OrbitCtrls;
     readonly raycast: Raycast;
     readonly scene: Scene;
     readonly stateMachine: StateMachine;
     private readonly webCtrls;
     private cam3D;
-    readonly comps: CompsInsts<TComps>;
+    /** Registered Clip instances keyed as in assets.clips. Their obj remains null until model animation assignment. */
+    readonly clip: ClipsInsts<TAssets>;
+    /** Registered Sound instances keyed as in assets.sounds. Call load() or loadAndStart() to load their sources. */
+    readonly sound: SoundsInsts<TAssets>;
+    readonly comps: CompsInsts<TAssets>;
     private objs3DMap;
     private websMap;
     /**
      * Starts the application, loads the initial scene resources, and connects components and the optional state machine. Startup errors are caught and logged.
      * @param cfg - Startup settings. Defaults to the exported `cfg`.
-     * @param comps - Scene Component and Web Component definitions. Default: **empty object**
+     * @param assets - Scene Component, Web Component, Clip, and Sound class registrations with optional parameters. Default: **empty object**
      * @param createStateMachine - Factory function that receives the fully created `App` instance and returns a state machine.
      *
      * @returns Resolves after startup completes or a startup error is caught.
@@ -104,11 +170,35 @@ export declare class App<TComps extends Comps = {}> {
      * **Example**
      * {@includeCode ../../../apps-doc/examples/app-run.ts}
      */
-    static run<TComps extends Comps = {}>(cfg?: Cfg, comps?: TComps, createStateMachine?: (app: App<TComps>) => AnyStateMachine): Promise<void>;
+    static run<TAssets extends Assets = {}>(cfg?: Cfg, assets?: TAssets, createStateMachine?: (app: App<TAssets>) => AnyStateMachine): Promise<void>;
 }
 
 /**
- * Loads and controls global and positional audio with volume fades.
+ * Groups the optional scene components, web components, animation clips, and sounds used by the app.
+ *
+ * @typeParam TScene - Record of named scene component classes or entries with initial parameters.
+ * @typeParam TWeb - Record of named web component classes or entries with initial parameters.
+ * @typeParam TClips - Record of named clip classes or entries with initial parameters.
+ * @typeParam TSounds - Record of named sound classes or entries with initial loading defaults.
+ *
+ * @example
+ * type MyAssets = Assets<{ cube: typeof Cube }, { marker: typeof Marker }>;
+ */
+export declare type Assets<TScene extends Record<string, SceneEntry> = {}, TWeb extends Record<string, WebEntry> = {}, TClips extends Record<string, ClipEntry> = {}, TSounds extends Record<string, SoundEntry> = {}> = {
+    /** Clip classes or entries keyed by application name. Model names default to these keys; see {@link ClipParams}. */
+    clips?: TClips;
+    /** Sound classes or entries keyed by application name. Registration does not load audio; see {@link SoundInstParams}. */
+    sounds?: TSounds;
+    /** Scene component definitions keyed by registration name. */
+    scene?: TScene;
+    /** Web component definitions keyed by registration name. */
+    web?: TWeb;
+};
+
+/**
+ * Loads and controls global and positional audio by case-sensitive sound name.
+ * Use App.sound for registered Sound instances with the same playback behavior.
+ * Set a listener before loading. Events are sent to the application before registered sound listeners.
  * @category Core
  */
 declare class Audio_2 {
@@ -118,78 +208,75 @@ declare class Audio_2 {
     private readonly events;
     private readonly params;
     private readonly scene;
-    private readonly sounds;
+    private readonly soundActions;
+    private readonly soundInsts;
     private attachSoundTo;
-    private fadeSound;
+    /**
+     * Changes volume, playback speed, and loop on a loaded sound. Spatial overrides are load-time options.
+     * A paused sound continues at its current position. Omitted settings remain unchanged.
+     * The optional fade transitions volume and speed together; loop changes immediately.
+     * Replaces the current transition and pending pause or stop. Does not start a stopped or finished sound.
+     * @inlineType SoundChangeOptions
+     * @param params - Sound settings to change; see {@link SoundTween} for transition settings.
+     */
+    change({ name, volume, speed, loop, fade }: SoundChangeOptions): void;
     /**
      * Returns the shared positional sound defaults.
      */
     get(): SoundParamsPos;
+    private emitEvent;
+    private getSound;
     /**
      * Checks whether a named sound is loaded.
      * @param params - Sound selection.
-     * @param params.name - Sound name.
      */
     isLoaded({ name }: {
         name: string;
     }): boolean;
     /**
-     * Checks whether a named sound is playing.
+     * Checks whether a named sound has the playing state. Paused sounds return false; change({ speed: 0 }) alone does not pause the state.
      * @param params - Sound selection.
-     * @param params.name - Sound name.
      */
     isPlaying({ name }: {
         name: string;
     }): boolean;
     private loadSound;
     /**
-     * Loads an audio file without playing it and sends an `Audio_Loaded` event when the sound is ready.
+     * Loads an audio file without playing it. For a registered Sound, assigns obj and calls onReady() before Audio_Loaded.
+     * Per-sound positional overrides are applied at load time; omitted settings inherit the shared defaults.
+     * @inlineType SoundParams
      * @param params - The sound options.
      */
     load(params: SoundParams): void;
     /**
      * Loads an audio file and plays it automatically when loading is complete.
-     * Use this method when no separate `Audio_Loaded` handling is required.
+     * Calls a registered Sound.onReady(), then sends Audio_Loaded before automatic playback.
+     * A playback or change() call in either handler supersedes the automatic start.
+     * Resumes the audio context and waits for the configured delayLoadSound before loading.
+     * @inlineType SoundLoadAndStartOptions
      * @param params - The sound options.
-     * @param params.time - Fade-in duration for this start in seconds. Defaults to 0 (no fade).
-     * @param params.ease - GSAP easing for the fade-in. Defaults to linear ('none').
      */
-    loadAndPlay({ time, ease, ...params }: {
-        time?: number;
-        ease?: string;
-    } & SoundParams): void;
+    loadAndStart({ time, ease, ...params }: SoundLoadAndStartOptions): void;
     /**
-     * Plays or resumes a loaded sound, optionally fading in from zero.
-     * When using {@link load}, call this method after receiving the matching `Audio_Loaded` event.
-     * This method does not wait for an audio file that is still loading.
-     * @param params - Sound selection.
-     * @param params.name - Loaded sound name.
-     * @param params.time - Fade-in duration in seconds. Defaults to 0 (no fade).
-     * @param params.ease - GSAP easing for the fade-in. Defaults to linear ('none').
+     * Fades a sound out, then holds its position by setting playback speed to zero.
+     * @inlineType SoundPauseOptions
+     * @param params - Sound name and optional fade-out settings; see {@link SoundTween}.
      */
-    play({ name, time, ease }: {
-        name: string;
-        time?: number;
-        ease?: string;
-    }): void;
+    pause({ name, fadeOut }: SoundPauseOptions): void;
     /**
-     * Pauses a playing sound and keeps its position for the next play().
-     * @param params - Sound selection and optional fade-out settings.
-     * @param params.name - Sound name.
-     * @param params.time - Fade-out duration in seconds. Defaults to 0 (no fade).
-     * @param params.ease - GSAP easing for the fade-out. Defaults to linear ('none').
+     * Continues a paused sound at its retained position and speed, optionally fading in.
+     * @inlineType SoundResumeOptions
+     * @param params - Sound name and optional fade-in settings; see {@link SoundTween}.
      */
-    pause({ name, time, ease }: {
-        name: string;
-        time?: number;
-        ease?: string;
-    }): void;
+    resume({ name, fadeIn }: SoundResumeOptions): void;
     /**
-     * Resumes the Web Audio context after a user gesture.
+     * Resumes the Web Audio context after a user gesture without resuming an individually paused sound.
      */
-    resume(): void;
+    resumeContext(): void;
+    private runSound;
     /**
      * Updates shared positional defaults without replacing individual sound overrides.
+     * @inlineType SoundParamsPos
      * @param params - Positional defaults to update; omitted values remain unchanged.
      */
     set(params: Partial<SoundParamsPos>): void;
@@ -203,28 +290,21 @@ declare class Audio_2 {
     setListener({ obj }: {
         obj: string | Cam3D;
     }): void;
+    private setSoundParamsPositional;
     /**
-     * Updates the volume and positional overrides of a loaded sound immediately.
-     * Volume is stored during a fade without interrupting it.
-     * @param params - Sound name and settings to change; omitted settings remain unchanged.
+     * Starts a loaded sound from the beginning, replacing its previous playback and transitions.
+     * When using load(), call this after the matching Audio_Loaded event.
+     * @inlineType SoundStartOptions
+     * @param params - Sound name and optional fade-in time/ease. The default is immediate.
      */
-    setSoundParams({ name, volume, ...positional }: {
-        name: string;
-        volume?: number;
-    } & Partial<SoundParamsPos>): void;
-    private setSoundParamsPos;
+    start({ name, time, ease }: SoundStartOptions): void;
     /**
-     * Stops a playing or paused sound and resets its position, optionally fading out.
-     * @param params - Sound selection.
-     * @param params.name - Sound name.
-     * @param params.time - Fade-out duration in seconds. Defaults to 0 (no fade).
-     * @param params.ease - GSAP easing for the fade-out. Defaults to linear ('none').
+     * Stops a sound and resets its position, optionally fading out first.
+     * @inlineType SoundStopOptions
+     * @param params - Sound name and optional fade-out time/ease. The default is immediate.
      */
-    stop({ name, time, ease }: {
-        name: string;
-        time?: number;
-        ease?: string;
-    }): void;
+    stop({ name, time, ease }: SoundStopOptions): void;
+    private tweenSound;
     /**
      * Runs an extension callback immediately with access to the public API.
      * @param extension - Callback receiving this `Audio` instance.
@@ -255,9 +335,10 @@ export declare interface AudioCfg extends SoundParamsPos {
     delayLoadSound: number;
 }
 
-/** @event Fired when a sound finishes loading, starts playback, completes naturally, or is stopped. */
+/** @event Fired when a sound finishes loading, starts, pauses, resumes, finishes naturally, or is stopped. */
 export declare interface AudioEvent {
-    type: 'Audio_Loaded' | 'Audio_Start' | 'Audio_Complete' | 'Audio_Stop';
+    /** Event identifier used to select listeners and state machine transitions. */
+    type: 'Audio_Loaded' | 'Audio_Start' | 'Audio_Finished' | 'Audio_Stop' | 'Audio_Pause' | 'Audio_Resume';
     /** The unique name assigned to the sound. */
     soundName: string;
 }
@@ -318,8 +399,11 @@ export declare interface CamBaseCfg {
      * @default { x: 0, y: 0, z: 0 }
      */
     lookAt: {
+        /** X coordinate in scene units. */
         x: number;
+        /** Y coordinate in scene units. */
         y: number;
+        /** Z coordinate in scene units. */
         z: number;
     };
     /**
@@ -327,8 +411,11 @@ export declare interface CamBaseCfg {
      * @default { x: 0, y: 0.5, z: 0.5 }
      */
     position: {
+        /** X coordinate in scene units. */
         x: number;
+        /** Y coordinate in scene units. */
         y: number;
+        /** Z coordinate in scene units. */
         z: number;
     };
 }
@@ -390,6 +477,7 @@ export declare interface CamPerspectiveCfg {
 
 /** @event Fired when a key is pressed or released while the canvas has focus. */
 export declare interface CanvasKeyEvent {
+    /** Event identifier used to select listeners and state machine transitions. */
     type: 'Canvas_Key_Down' | 'Canvas_Key_Up';
     /** Native keyboard event from the canvas interaction. */
     event: KeyboardEvent;
@@ -397,6 +485,7 @@ export declare interface CanvasKeyEvent {
 
 /** @event Fired when the pointer clicks, enters, or leaves the canvas. */
 export declare interface CanvasPointerEvent {
+    /** Event identifier used to select listeners and state machine transitions. */
     type: 'Canvas_Click' | 'Canvas_Pointer_Enter' | 'Canvas_Pointer_Leave';
     /** Native pointer event from the canvas interaction. */
     event: PointerEvent;
@@ -446,22 +535,301 @@ export declare const cfg: Cfg;
 
 /** Configuration values accepted by `setCfg`. */
 export declare type CfgSet = DeepPartial<Cfg> & {
+    /** Partial rendering settings. See {@link RenderCfg}. */
     render?: DeepPartial<RenderCfg> & {
+        /** Rendering profiles restricted to compatible effect combinations. See {@link RenderProfileValidCfg}. */
         profile?: RenderProfileValidCfg;
     };
 };
 
-/** @event Fired when clip playback, weight fading, or speed changes start or complete, or when playback is canceled. */
+/**
+ * Provides playback controls and listeners for a model animation registered in assets.clips.
+ * Extend this class to add custom behavior. Instances are exposed through App.clip.
+ * Playback controls have no effect until obj is assigned. Listeners can be registered before readiness and remain registered across restarts.
+ * @category Core
+ */
+export declare class Clip {
+    private clips;
+    private readonly params;
+    /** The matched Three.js animation clip. Null until assigned before onReady() and Scene_Ready. */
+    obj: THREE_TYPE.AnimationClip | null;
+    /**
+     * Subscribes to an event from this clip.
+     * @returns A function that unsubscribes the listener.
+     */
+    addEventListener<TType extends ClipEvent['type']>(type: TType, listener: (event: ClipEvent & {
+        type: TType;
+    }) => void): Unsubscribe;
+    /**
+     * Changes only the supplied settings of an active clip, preserving its position and markers.
+     * @inlineType ClipInstChangeOptions
+     * @param params - Optional loop, reverse, fade, and speed settings.
+     *
+     * @remarks
+     * A speed target of zero holds playback. A later speed update continues at the same position.
+     * Loop counts include completed repetitions, as in Three.js. See {@link ClipEvent}.
+     */
+    change(params?: ClipInstChangeOptions): void;
+    /**
+     * Reduces playback speed to zero while retaining the clip's position and weight.
+     * @inlineType ClipInstPauseOptions
+     * @param params - Optional speed transition settings.
+     */
+    pause(params?: ClipInstPauseOptions): void;
+    /** Unsubscribes a listener from this clip. */
+    removeEventListener<TType extends ClipEvent['type']>(type: TType, listener: (event: ClipEvent & {
+        type: TType;
+    }) => void): void;
+    /**
+     * Continues playback towards the speed retained when pause() was called.
+     * @inlineType ClipInstResumeOptions
+     * @param params - Optional speed transition settings.
+     */
+    resume(params?: ClipInstResumeOptions): void;
+    /**
+     * Plays this clip, optionally fading in, changing speed, or replacing selected clips.
+     * @inlineType ClipInstStartOptions
+     * @param params - Clip playback settings.
+     *
+     * @remarks
+     * A new call restarts playback and replaces the previous settings and markers. Use change() to change an active clip.
+     * Finite clips hold their final pose and emit Clip_Finished. Crossfades share the fadeIn duration.
+     * See {@link ClipEvent}.
+     */
+    start(params?: ClipInstStartOptions): void;
+    /**
+     * Stops this clip after its optional fade-out and speed-out transitions.
+     * @inlineType ClipInstStopOptions
+     * @param params - Outgoing transitions and clips to crossfade in.
+     *
+     * @remarks
+     * Crossfades share the fadeOut duration. Stopping does not wait for a loop boundary.
+     * Replaced transitions do not emit completion events. See {@link ClipEvent}.
+     */
+    stop(params?: ClipInstStopOptions): void;
+    /** Called after the loaded animation clip and its controls are assigned, before Scene_Ready. */
+    protected onReady(): void;
+}
+
+/** Optional loop, reverse, fade, and speed settings. */
+declare interface ClipChangeOptions {
+    /** Model animation clip name, matched without regard to case. */
+    clip: string;
+    /** The layer assigned when playback started. Default: **null**, selecting only clips in the shared unnamed layer. */
+    layer?: string | null;
+    /** Loop setting. See {@link LoopMode}. Omitted: unchanged. */
+    modeLoop?: LoopMode;
+    /** Playback direction without changing the clip position. Omitted: unchanged. Without speed, changes direction immediately; supply speed.time for a gradual change. */
+    reverse?: boolean;
+    /** Changes the active clip's blend weight. See {@link ClipTween}. Default `to`: **1**. Omitted: unchanged. */
+    fade?: ClipTween;
+    /** Changes playback speed. See {@link ClipTween}. Default `to`: **1**. Omitted: unchanged. */
+    speed?: ClipTween;
+}
+
+/** Clip classes available for registration. */
+export declare type ClipClass = new (name: string, params?: ClipParams) => Clip;
+
+/** Clip class with optional initial parameters. */
+export declare type ClipEntry<TClass extends ClipClass = ClipClass> = TClass | {
+    /** Clip class to instantiate. */
+    class: TClass;
+    /** Model animation selection and basic playback defaults. */
+    params?: ClipParams;
+};
+
+/** @event Fired when clip playback, weight fading, or speed changes start or complete, or when playback is paused, resumed, or stopped. */
 export declare interface ClipEvent {
-    type: 'Clip_Start' | 'Clip_Complete' | 'Clip_Cancel' | 'Clip_Fade_Start' | 'Clip_Fade_Complete' | 'Clip_Speed_Start' | 'Clip_Speed_Complete';
+    /** Event identifier used to select listeners and state machine transitions. */
+    type: 'Clip_Start' | 'Clip_Finished' | 'Clip_Stop' | 'Clip_Pause' | 'Clip_Resume' | 'Clip_Fade_Start' | 'Clip_Fade_Complete' | 'Clip_Speed_Start' | 'Clip_Speed_Complete' | 'Clip_Loop' | 'Clip_Marker';
     /** The name of the affected `THREE.AnimationClip`. */
     clipName: string;
     /** The associated animation action, when available. */
     action?: THREE_TYPE.AnimationAction;
     /** Whether the clip weight is fading in or out. */
-    fadeMode?: ActionFadeMode;
+    fadeMode?: 'in' | 'out';
+    /** Completed loops for Clip_Loop, or the current one-based loop for Clip_Marker. */
+    loopCount?: number;
+    /** The name of the crossed marker. */
+    markerName?: string;
 }
 
+/** Settings for Clip.change(); the instance selects the model clip. */
+declare type ClipInstChangeOptions = Omit<ClipChangeOptions, 'clip'>;
+
+/** Speed transition for Clip.pause(); the instance selects the model clip. */
+declare type ClipInstPauseOptions = Omit<ClipPauseOptions, 'clip'>;
+
+/** Speed transition for Clip.resume(); the instance selects the model clip. */
+declare type ClipInstResumeOptions = Omit<ClipResumeOptions, 'clip'>;
+
+/** Maps application registration keys to concrete Clip instances, including subclass methods. The underlying clips are assigned before Scene_Ready. */
+export declare type ClipInsts<T extends Record<string, ClipEntry>> = {
+    [K in keyof T]: T[K] extends ClipClass ? InstanceType<T[K]> : T[K] extends {
+        class: infer TClass extends ClipClass;
+    } ? InstanceType<TClass> : never;
+};
+
+/** Playback settings for Clip.start(); the instance selects the model clip. */
+declare type ClipInstStartOptions = Omit<ClipStartOptions, 'clip'>;
+
+/** Outgoing transitions for Clip.stop(); the instance selects the model clip. */
+declare type ClipInstStopOptions = Omit<ClipStopOptions, 'clip'>;
+
+/**
+ * Defines a named point in a clip that emits Clip_Marker when crossed during playback.
+ * Playback must advance by at most one clip duration per update (deltaTime * absolute speed <= clip duration).
+ */
+export declare type ClipMarker = {
+    /** Marker name included in the event as markerName. */
+    name: string;
+    /** Position in seconds within the animation clip. */
+    time: number;
+};
+
+/** Initial parameters for a registered clip. */
+export declare interface ClipParams extends Pick<ClipStartOptions, 'modeLoop' | 'modeBlend' | 'reverse' | 'cam' | 'layer'> {
+    /** Model animation clip name, matched without regard to case. Defaults to the registration key. */
+    name?: string;
+}
+
+/** Clip selection and speed transition settings. */
+declare interface ClipPauseOptions {
+    /** Model animation clip name, matched without regard to case. */
+    clip: string;
+    /** The layer assigned when playback started. Default: **null**. */
+    layer?: string | null;
+    /** Transition duration in seconds. Default: **1**. */
+    time?: number;
+    /** GSAP easing name. Default: **'power1.inOut'**. */
+    ease?: string;
+}
+
+/** Clip selection and speed transition settings. */
+declare interface ClipResumeOptions {
+    /** Model animation clip name, matched without regard to case. */
+    clip: string;
+    /** The layer assigned when playback started. Default: **null**. */
+    layer?: string | null;
+    /** Transition duration in seconds. Default: **1**. */
+    time?: number;
+    /** GSAP easing name. Default: **'power1.inOut'**. */
+    ease?: string;
+}
+
+/**
+ * Controls loaded model animation clips by name through App.clips, including unregistered clips.
+ * Names are matched without regard to case; events retain the original model clip name.
+ * App.clip exposes registered Clip instances that delegate to these same controls.
+ * Wait for Scene_Ready before application playback. Supply the layer used by start() to subsequent controls.
+ * @category Core
+ */
+export declare class Clips {
+    private readonly cam3D;
+    private readonly events;
+    private mixer;
+    private readonly clips;
+    private readonly clipInsts;
+    private readonly clipActions;
+    private clipActionsFrame;
+    private readonly vec3Obj;
+    private readonly vec3Aim;
+    private getClip;
+    /**
+     * Changes only the supplied settings of an active clip, preserving its position and markers.
+     * @inlineType ClipChangeOptions
+     * @param params - Optional loop, reverse, fade, and speed settings.
+     */
+    change({ clip, layer, modeLoop, reverse, fade, speed }: ClipChangeOptions): void;
+    private emitEvent;
+    private fadeTween;
+    private finished;
+    private loop;
+    /**
+     * Reduces playback speed to zero while retaining the clip's position and weight.
+     * @inlineType ClipPauseOptions
+     * @param params - Clip selection and speed transition settings.
+     */
+    pause({ clip, layer, time, ease }: ClipPauseOptions): void;
+    /**
+     * Continues playback towards the speed retained when pause() was called.
+     * @inlineType ClipResumeOptions
+     * @param params - Clip selection and speed transition settings.
+     */
+    resume({ clip, layer, time, ease }: ClipResumeOptions): void;
+    private speedTween;
+    /**
+     * Plays a model animation clip, optionally fading in, changing speed, or replacing selected clips.
+     * @inlineType ClipStartOptions
+     * @param params - Model clip name and playback settings. Starting restarts the clip; cam: true follows the exported camera and target.
+     */
+    start({ clip, ...params }: ClipStartOptions): void;
+    private startClip;
+    /**
+     * Stops a model animation clip after its optional fade-out and speed-out transitions.
+     * @inlineType ClipStopOptions
+     * @param params - Clip selection, outgoing transitions, and clips to crossfade in.
+     */
+    stop({ clip, layer, fadeOut, speedOut, crossfade }: ClipStopOptions): void;
+    private stopClip;
+    private stopTweens;
+    private updateCamera;
+    private updateEvents;
+}
+
+/** Typed clip instances exposed through App.clip for an Assets definition. */
+export declare type ClipsInsts<T extends Assets> = ClipInsts<NonNullable<T['clips']>>;
+
+/** Clip playback settings. */
+declare interface ClipStartOptions {
+    /** Model animation clip name, matched without regard to case. */
+    clip: string;
+    /** Named layer used to group animation actions. Default: **null**, the shared unnamed layer. */
+    layer?: string | null;
+    /** Follow the exported camera and its target. Default: **false**. Coordinate camera controls in the application. */
+    cam?: boolean;
+    /** Blend mode. See {@link BlendMode}. Default: **'normal'** */
+    modeBlend?: BlendMode;
+    /** Loop setting. See {@link LoopMode}. Default: **1** */
+    modeLoop?: LoopMode;
+    /** If true, plays the clip in reverse. Default: **false** */
+    reverse?: boolean;
+    /** Blends the clip in. See {@link ClipTween}. Default `to`: **1**. Omitted: applies target **1** immediately. */
+    fadeIn?: ClipTween;
+    /** Changes playback speed. See {@link ClipTween}. Default `to`: **1**. Omitted: applies target **1** immediately. */
+    speedIn?: ClipTween;
+    /** Playback markers. See {@link ClipMarker}. Default: **[]** */
+    markers?: ClipMarker[];
+    /** Other clip names or references to fade out on the same layer, or 'all' for all other enabled clips on that layer. Default: **[]** */
+    crossfade?: 'all' | (string | Clip)[];
+}
+
+/** Clip selection, outgoing transitions, and clips to crossfade in. */
+declare interface ClipStopOptions {
+    /** Model animation clip name, matched without regard to case. */
+    clip: string;
+    /** The layer assigned when playback started. Default: **null**, selecting only clips in the shared unnamed layer. */
+    layer?: string | null;
+    /** Blends the clip out before stopping. See {@link ClipTween}. Default `to`: **0**. Omitted: no outgoing transition. */
+    fadeOut?: ClipTween;
+    /** Changes playback speed before stopping. See {@link ClipTween}. Default `to`: **0**. Omitted: no outgoing transition. */
+    speedOut?: ClipTween;
+    /** Clip names or references to fade in on the same layer while this clip stops. Default: **[]** */
+    crossfade?: (string | Clip)[];
+}
+
+/** Describes a transition of a clip's blend weight or playback speed. */
+export declare type ClipTween = {
+    /** Initial value. Omitted: the current weight or signed playback speed. Explicit speed values follow the clip's reverse setting. */
+    from?: number;
+    /** Target value. Its default depends on the method parameter. Speed targets follow the clip's reverse setting; zero holds playback. */
+    to?: number;
+    /** Transition duration in seconds. Default: **0** (applied immediately). */
+    time?: number;
+    /** GSAP easing function name. Default: **'power1.inOut'** */
+    ease?: string;
+};
+
 /**
  * Uses a `Mesh3D` for pointer picking or occlusion and optionally maps raycast events to another rendered mesh.
  * @category Scene Components
@@ -486,20 +854,6 @@ export declare interface Coll3DParams extends Obj3DParams {
     occluder?: boolean;
 }
 
-/**
- * Groups the optional scene and web component definitions used by the app.
- *
- * @typeParam TScene - Record of named scene component classes or entries with initial parameters.
- * @typeParam TWeb - Record of named web component classes or entries with initial parameters.
- *
- * @example
- * type MyComps = Comps<{ cube: typeof Cube }, { marker: typeof Marker }>;
- */
-export declare type Comps<TScene extends Record<string, SceneEntry> = {}, TWeb extends Record<string, WebEntry> = {}> = {
-    scene?: TScene;
-    web?: TWeb;
-};
-
 /**
  * Shared component settings.
  * @category Cfg
@@ -510,8 +864,10 @@ export declare interface CompsCfg {
 }
 
 /** Registered scene components and web component instances available at runtime. */
-export declare type CompsInsts<T extends Comps> = {
+export declare type CompsInsts<T extends Assets> = {
+    /** Scene component instances keyed by registration name. */
     scene: SceneInsts<NonNullable<T['scene']>>;
+    /** Web component instance arrays keyed by registration name. */
     web: WebInsts<NonNullable<T['web']>>;
 };
 
@@ -536,17 +892,18 @@ export declare type CoordinateSpace = 'parent' | 'local' | 'world';
  */
 export declare interface DebugCfg {
     /**
-     * Controls how much debug information is written to the console.
-     *
-     * - `'none'`: No debug messages are logged.
-     * - `'xstate'`: Only logs events that were accepted by the state machine.
-     * - `'all'`: Logs all debug messages.
+     * See {@link DebugLog}.
      * @default 'xstate'
      */
     log: DebugLog;
 }
 
-/** @inheritDoc DebugCfg.log */
+/**
+ * Controls how much debug information is written to the console.
+ * - `'none'`: No debug messages are logged.
+ * - `'xstate'`: Only logs events that were accepted by the state machine.
+ * - `'all'`: Logs all debug messages.
+ */
 export declare type DebugLog = 'none' | 'xstate' | 'all';
 
 declare type DeepPartial<T> = T extends readonly unknown[] ? T : T extends object ? {
@@ -562,6 +919,7 @@ export { degToRad }
 export declare class Engine {
     private readonly cam3D;
     private readonly cfg;
+    private readonly clips;
     private readonly events;
     private readonly modules;
     private readonly objs3D;
@@ -602,14 +960,14 @@ export declare class Engine {
      */
     addOnFrameUpdate(cb: (deltaTime: number) => void): void;
     /**
-     * Switches edge smoothing at runtime, loading the selected effect when needed. TRAA is available only with WebGPU.
-     * @param aaMode - Anti-aliasing mode, or `none` to disable smoothing.
+     * Switches edge smoothing at runtime, loading the selected effect when needed.
+     * @param aaMode - See {@link AaMode}.
      */
     enableAaMode(aaMode: AaMode): Promise<void>;
     /**
-     * Switches screen-space lighting at runtime. WebGL supports SSAO; WebGPU supports GTAO and SSGI.
+     * Switches screen-space lighting at runtime.
      * SSGI requires TRAA, a perspective camera, and compatible WebGPU hardware.
-     * @param sslMode - Lighting mode, or `none` to disable it.
+     * @param sslMode - See {@link SslMode}.
      */
     enableSslMode(sslMode: SslMode): Promise<void>;
     /**
@@ -670,10 +1028,10 @@ export declare class EnvCtrls {
     private disposePrevBgd;
     private disposeText;
     /**
-     * Loads and applies environment lighting and background maps. Later maps replace only the background.
+     * Loads and applies the configured environment maps. See {@link EnvCtrlsCfg}.
      * @param params - Optional environment loading parameters. If provided, both `type` and `map` are required.
-     * @param params.type - Environment map file type. Defaults to `cfg.envCtrls.type`.
-     * @param params.map - Ordered environment map paths. Defaults to `cfg.envCtrls.map`.
+     * @param params.type - See {@link EnvCtrlsCfg.type}. Defaults to `cfg.envCtrls.type`.
+     * @param params.map - See {@link EnvCtrlsCfg.map}. Defaults to `cfg.envCtrls.map`.
      */
     enable(params?: {
         type: EnvCtrlsCfg["type"];
@@ -682,7 +1040,7 @@ export declare class EnvCtrls {
     /** Removes environment lighting and background maps, cancels pending updates, and stops rotation. */
     disable(): void;
     /**
-     * Returns a snapshot of environment rotation in radians, rotation speed in radians per second, intensity, and background blurriness.
+     * Returns a snapshot of rotation, rotation speed, intensities, and background blurriness. See {@link EnvCtrlsCfg}.
      */
     get(): Partial<EnvCtrlsCfg>;
     /**
@@ -693,7 +1051,7 @@ export declare class EnvCtrls {
     private loadText;
     /**
      * Updates supported environment control values at runtime.
-     * @param params - Runtime values to update: rotation speed in radians per second, intensities, background blurriness or rotation in radians.
+     * @param params - Supported runtime settings to change; omitted values remain unchanged. See {@link EnvCtrlsCfg}.
      */
     set(params: Partial<EnvCtrlsCfg>): void;
     private setEnv;
@@ -751,8 +1109,11 @@ export declare interface EnvCtrlsCfg {
      * @default { x: 0, y: 0, z: 0 }
      */
     rotation: {
+        /** Rotation around the X axis in radians. */
         x: number;
+        /** Rotation around the Y axis in radians. */
         y: number;
+        /** Rotation around the Z axis in radians. */
         z: number;
     };
     /**
@@ -769,6 +1130,7 @@ export declare interface EnvCtrlsCfg {
 
 /** @event Fired after the initial environment is applied and all progressive background loading attempts have completed. Failed background maps may have been skipped. Canceled or superseded loads do not fire this event. */
 export declare interface EnvLoadedEvent {
+    /** Event identifier used to select listeners and state machine transitions. */
     type: 'Env_Loaded';
 }
 
@@ -790,13 +1152,6 @@ export declare class Events {
     send(event: AnyEventObject, log?: string): void;
 }
 
-/**
- * Controls what happens after the final animation loop.
- * - `'hold'`: Keeps the action enabled and holds its final pose.
- * - `'fadeOut'`: Fades out over `fadeTimeFinish` seconds, or stops immediately when the duration is `0`.
- */
-export declare type FinishMode = 'hold' | 'fadeOut';
-
 /**
  * Blends distant objects into the fog color.
  * @category Cfg
@@ -974,6 +1329,7 @@ export declare interface FpvCtrlsCfg {
 
 /** @event Fired when first-person controls are enabled, disabled, disposed, locked, or unlocked. */
 export declare interface FpvCtrlsEvent {
+    /** Event identifier used to select listeners and state machine transitions. */
     type: 'FpvCtrls_Disabled' | 'FpvCtrls_Disposed' | 'FpvCtrls_Enabled' | 'FpvCtrls_Lock' | 'FpvCtrls_Unlock';
 }
 
@@ -1330,6 +1686,7 @@ export declare interface MeshCfg {
  * @category Cfg
  */
 export declare interface ModelCfg {
+    /** Mesh and texture compression formats used by the model assets. */
     compress: {
         /**
          * Mesh compression used by the GLTF/GLB file.
@@ -1361,6 +1718,7 @@ export declare interface ModelCfg {
 
 /** @event Fired when model loading fails. */
 export declare interface ModelErrorEvent {
+    /** Event identifier used to select listeners and state machine transitions. */
     type: 'Model_Error';
     /** The caught error object. */
     error: Error;
@@ -1382,6 +1740,7 @@ export declare interface ModelLoadingEvent {
 
 /** @event Fired after the final progressive model has been applied and rendered. */
 export declare interface ModelReadyEvent {
+    /** Event identifier used to select listeners and state machine transitions. */
     type: 'Model_Ready';
 }
 
@@ -1402,10 +1761,9 @@ export declare class Obj3D {
     /** @public */
     protected canvas: HTMLElement;
     protected cfg: Cfg;
-    protected name: string;
     /** The managed `THREE.Object3D` instance for this object. It is `null` until a scene object is assigned. */
     obj: THREE_TYPE.Object3D | null;
-    /** Contains all Scene Components registered through `comps.scene`, keyed by registration name. */
+    /** Contains all Scene Components registered through `comps.scene`, keyed by lowercase registration name. */
     protected objs3D: Map<string, Obj3D> | null;
     /**
      * Active renderer for custom rendering integrations.
@@ -1454,19 +1812,22 @@ export declare class Obj3D {
     }>) => void): Unsubscribe;
     /**
      * Animates this object's orientation in radians through {@link Scene.animRotTo}.
+     * @inlineType ObjRotOptions
      * @param params - Target orientation and animation settings, without an object parameter.
      */
-    animRotTo(params: Omit<Parameters<Scene['animRotTo']>[0], 'obj'>): void;
+    animRotTo({ x, y, z, path, order, space, time, ease }: ObjRotOptions): void;
     /**
      * Animates this object's scale through {@link Scene.animScaleTo}.
+     * @inlineType ObjScaleOptions
      * @param params - Target scale and animation settings, without an object parameter.
      */
-    animScaleTo(params: Omit<Parameters<Scene['animScaleTo']>[0], 'obj'>): void;
+    animScaleTo({ x, y, z, time, ease }: ObjScaleOptions): void;
     /**
      * Animates this object's position through {@link Scene.animTranslTo}.
+     * @inlineType ObjTranslOptions
      * @param params - Target position and animation settings, without an object parameter.
      */
-    animTranslTo(params: Omit<Parameters<Scene['animTranslTo']>[0], 'obj'>): void;
+    animTranslTo({ x, y, z, space, time, ease }: ObjTranslOptions): void;
     /**
      * Animates angular velocity in radians per second. World rotation requires uniformly scaled parents.
      * @param params - Target angular velocity and animation settings.
@@ -1584,6 +1945,7 @@ export declare type Obj3DEvent = Obj3DPosWorldEvent | Obj3DPosScreenEvent | Obj3
 
 /** @event Fired when the frustum visibility of a 3D object changes. */
 export declare interface Obj3DFrustumEvent {
+    /** Event identifier used to select listeners and state machine transitions. */
     type: 'Obj3D_Frustum_Changed';
     /** Whether the object's world position is inside the camera frustum. */
     visibleFrustum: boolean;
@@ -1591,12 +1953,15 @@ export declare interface Obj3DFrustumEvent {
 
 /** Initial parameters shared by all `Obj3D` classes. */
 export declare interface Obj3DParams {
+    /** Model object name, matched without regard to case. Defaults to the registration key. */
+    name?: string;
     /** Hides the underlying Three.js object from rendering without disabling raycasting. */
     hidden?: boolean;
 }
 
 /** @event Fired when the pointer interacts with a pickable object. */
 export declare interface Obj3DPointerEvent {
+    /** Event identifier used to select listeners and state machine transitions. */
     type: 'Obj3D_Click' | 'Obj3D_Pointer_Enter' | 'Obj3D_Pointer_Down' | 'Obj3D_Pointer_Leave' | 'Obj3D_Pointer_Move' | 'Obj3D_Pointer_Up';
     /** Native pointer event from the active object interaction. */
     event: PointerEvent;
@@ -1608,6 +1973,7 @@ export declare interface Obj3DPointerEvent {
  * @event Fired when the screen position of a 3D object changes.
  */
 export declare interface Obj3DPosScreenEvent {
+    /** Event identifier used to select listeners and state machine transitions. */
     type: 'Obj3D_Pos_Screen_Changed';
     /** The object's position projected into screen space. */
     posScreen: THREE_TYPE.Vector2;
@@ -1617,6 +1983,7 @@ export declare interface Obj3DPosScreenEvent {
  * @event Fired when the world position of a 3D object changes.
  */
 export declare interface Obj3DPosWorldEvent {
+    /** Event identifier used to select listeners and state machine transitions. */
     type: 'Obj3D_Pos_World_Changed';
     /** The object's position in world coordinates. */
     posWorld: THREE_TYPE.Vector3;
@@ -1626,6 +1993,7 @@ export declare interface Obj3DPosWorldEvent {
  * @event Fired when the world rotation of a 3D object changes.
  */
 export declare interface Obj3DRotWorldEvent {
+    /** Event identifier used to select listeners and state machine transitions. */
     type: 'Obj3D_Rot_World_Changed';
     /** The object's rotation in world coordinates. */
     rotWorld: THREE_TYPE.Euler;
@@ -1633,13 +2001,21 @@ export declare interface Obj3DRotWorldEvent {
 
 /** @event Fired when an object's combined hidden, frustum, and occlusion visibility changes. */
 export declare interface Obj3DVisibleEvent {
+    /** Event identifier used to select listeners and state machine transitions. */
     type: 'Obj3D_Visible_Changed';
     /** Whether the object is not hidden, is inside the camera frustum, and is not occluded. */
     visible: boolean;
 }
 
+declare type ObjRotOptions = Omit<AnimRotOptions, 'obj'>;
+
+/** Scene object component types managed by the framework. */
 export declare type Objs3D = Cam3D | Light3D | Mesh3D | Obj3D;
 
+declare type ObjScaleOptions = Omit<AnimScaleOptions, 'obj'>;
+
+declare type ObjTranslOptions = Omit<AnimTranslOptions, 'obj'>;
+
 /**
  * Controls camera orbit, panning, and zooming around a target.
  * @category Core
@@ -1792,6 +2168,7 @@ export declare interface OrbitCtrlsCfg {
 
 /** @event Fired when orbit interaction starts, changes, or ends, or controls are enabled, disabled, or disposed. */
 export declare interface OrbitCtrlsEvent {
+    /** Event identifier used to select listeners and state machine transitions. */
     type: 'OrbitCtrls_Changed' | 'OrbitCtrls_Disabled' | 'OrbitCtrls_Enabled' | 'OrbitCtrls_End' | 'OrbitCtrls_Start' | 'OrbitCtrls_Disposed';
 }
 
@@ -1836,6 +2213,7 @@ export declare interface PostCfg {
 
 /** @event Fired after the loading progress bar has finished hiding. */
 export declare interface ProgressBarHiddenEvent {
+    /** Event identifier used to select listeners and state machine transitions. */
     type: 'ProgressBar_Hidden';
 }
 
@@ -1962,12 +2340,7 @@ export declare interface RenderCfg {
      */
     adaptiveGfx: boolean;
     /**
-     * Selects the rendering backend.
-     *
-     * - `webgl`: use `THREE.WebGLRenderer`
-     * - `webgpu`: use `THREE.WebGPURenderer`
-     * - `auto`: use WebGPU if supported, otherwise fall back to WebGL
-     *
+     * See {@link Renderer}.
      * @default 'auto'
      */
     api: Renderer;
@@ -2051,14 +2424,17 @@ export declare interface RenderCfg {
      * WebGPU-specific renderer configuration.
      */
     webgpu: {
-        /**
-         * Parameters passed to `THREE.WebGPURenderer`.
-         */
+        /** See {@link WebGpuRendererParams}. */
         params: WebGpuRendererParams;
     };
 }
 
-/** @inheritDoc RenderCfg.api */
+/**
+ * Selects the rendering backend.
+ * - `'webgl'`: Uses `THREE.WebGLRenderer`.
+ * - `'webgpu'`: Uses `THREE.WebGPURenderer`.
+ * - `'auto'`: Uses WebGPU if supported, otherwise falls back to WebGL.
+ */
 export declare type Renderer = 'webgl' | 'webgpu' | 'auto';
 
 /** Complete effect selections for both rendering backends. */
@@ -2144,12 +2520,13 @@ export declare type RenderProfileWebGpu = {
 });
 
 /**
- * Controls scene contents, camera animation, materials, lighting, and clip playback.
+ * Controls scene contents, camera animation, materials, and lighting.
  * @category Core
  */
 export declare class Scene {
-    private readonly cfg;
     private readonly cam3D;
+    private readonly cfg;
+    private readonly clips;
     private readonly events;
     private readonly objs3D;
     private readonly tweensObj;
@@ -2222,7 +2599,7 @@ export declare class Scene {
     /**
      * Animates all assigned materials of an object, optionally including descendant meshes.
      * @param params - Target material values and shared animation settings.
-     * @param params.obj - Scene object name or `Mesh3D` component.
+     * @param params.obj - Exact Three.js object name.
      * @param params.recursive - Includes descendant meshes. Default: **false**
      * @param params.infinite - Repeats each animation indefinitely. Default: **false**
      * @param params.time - Duration in seconds. Default: **0**
@@ -2233,7 +2610,7 @@ export declare class Scene {
      * Each shared material is animated once. Tweens and {@link AnimMaterialEvent} are managed per material.
      */
     animMaterialsTo({ obj, recursive, ...params }: {
-        obj: string | Mesh3D;
+        obj: string;
         recursive?: boolean;
         infinite?: boolean;
         time?: number;
@@ -2243,16 +2620,8 @@ export declare class Scene {
     }): void;
     /**
      * Animates orientation from its current value using Euler angles in radians.
+     * @inlineType AnimRotOptions
      * @param params - Target object, orientation, and animation settings.
-     * @param params.obj - Scene object name or component, including cameras.
-     * @param params.x - Target X angle in radians; omitted axes keep their starting target angles.
-     * @param params.y - Target Y angle in radians.
-     * @param params.z - Target Z angle in radians.
-     * @param params.path - Rotation interpolation. Default: **'euler'**; **'quat'** takes the shortest orientation path.
-     * @param params.order - Euler order for interpreting angles in both paths. Default: **'XYZ'**
-     * @param params.space - Orientation space. Default: **'parent'**
-     * @param params.time - Duration in seconds. Default: **1**. A value of 0 applies the values immediately.
-     * @param params.ease - GSAP easing function. Default: **'power2.inOut'**
      * @remarks
      * Euler interpolation supports full turns. Each call starts from the current orientation without retaining previous turns.
      * Quaternion interpolation takes the shortest path; omitted Euler axes may change during interpolation.
@@ -2261,147 +2630,29 @@ export declare class Scene {
      * A new call cancels only the previous orientation animation of the same object.
      * Emits {@link AnimEvent}: `Anim_Start`, `Anim_Complete`, or `Anim_Cancel` when replaced.
      */
-    animRotTo({ obj, x, y, z, path, order, space, time, ease }: {
-        obj: string | Obj3D;
-        x?: number;
-        y?: number;
-        z?: number;
-        path?: 'euler' | 'quat';
-        order?: THREE_TYPE.EulerOrder;
-        space?: 'parent' | 'world';
-        time?: number;
-        ease?: string;
-    }): void;
+    animRotTo({ obj, x, y, z, path, order, space, time, ease }: AnimRotOptions): void;
     /**
      * Animates selected local scale axes from their current values.
+     * @inlineType AnimScaleOptions
      * @param params - Target object, scale, and animation settings.
-     * @param params.obj - Scene object name or component, including cameras.
-     * @param params.x - Target X scale; omitted axes remain unchanged.
-     * @param params.y - Target Y scale.
-     * @param params.z - Target Z scale.
-     * @param params.time - Duration in seconds. Default: **1**. A value of 0 applies the values immediately.
-     * @param params.ease - GSAP easing function. Default: **'power2.inOut'**
      * @remarks
      * A new call cancels only the previous scale animation of the same object.
      * Emits {@link AnimEvent}: `Anim_Start`, `Anim_Complete`, or `Anim_Cancel` when replaced.
      */
-    animScaleTo({ obj, x, y, z, time, ease }: {
-        obj: string | Obj3D;
-        x?: number;
-        y?: number;
-        z?: number;
-        time?: number;
-        ease?: string;
-    }): void;
+    animScaleTo({ obj, x, y, z, time, ease }: AnimScaleOptions): void;
     /**
      * Animates selected position axes from their current values in parent or world space.
+     * @inlineType AnimTranslOptions
      * @param params - Target object, position, and animation settings.
-     * @param params.obj - Scene object name or component, including cameras.
-     * @param params.x - Target X position; omitted axes keep their starting values.
-     * @param params.y - Target Y position.
-     * @param params.z - Target Z position.
-     * @param params.space - Position space. Default: **'parent'**
-     * @param params.time - Duration in seconds. Default: **1**. A value of 0 applies the values immediately.
-     * @param params.ease - GSAP easing function. Default: **'power2.inOut'**
      * @remarks
      * World targets account for moving parents. Cameras switch to free look mode.
      * A new call cancels only the previous position animation of the same object.
      * Emits {@link AnimEvent}: `Anim_Start`, `Anim_Complete`, or `Anim_Cancel` when replaced.
      */
-    animTranslTo({ obj, x, y, z, space, time, ease }: {
-        obj: string | Obj3D;
-        x?: number;
-        y?: number;
-        z?: number;
-        space?: 'parent' | 'world';
-        time?: number;
-        ease?: string;
-    }): void;
+    animTranslTo({ obj, x, y, z, space, time, ease }: AnimTranslOptions): void;
     private getMtrls;
     private getObj;
-    /**
-     * Plays a named animation clip with blending, looping, and speed control.
-     *
-     * @param params - Parameters for controlling the animation playback.
-     * @param params.layer - The freely named layer used to group animation actions.
-     * @param params.clip - The name of the animation clip to play.
-     * @param params.modeBlend - How the action is blended with other active actions. Default: **'normal'**
-     * @param params.modeFinish - Whether the final pose is held or faded out after the final loop. Default: **'hold'**
-     * @param params.modeLoop - Number of plays or `'infinite'` for endless looping. Default: **1**
-     * @param params.modeStop - Which previous actions of the same layer are stopped before playback. Default: **'all'**
-     * @param params.fadeTime - Duration in seconds for fading affected previous actions out and the new action in. Default: **0**
-     * @param params.fadeTimeFinish - Duration in seconds for `modeFinish: 'fadeOut'`. Default: **0**
-     * @param params.reverse - If `true`, plays the clip in reverse. Default: **false**
-     * @param params.reset - If `true`, resets the clip before a new playback. Default: **false**
-     * @param params.speedStart - Initial playback speed for speed interpolation. Default: **0**
-     * @param params.speedEnd - Target playback speed. Default: **1**
-     * @param params.speedTime - Duration in seconds for speed interpolation. Default: **0**
-     * @param params.speedEase - GSAP easing function name. Default: **'power1.inOut'**
-     *
-     * @remarks
-     * Playing an active or fading-in action again updates its speed without restarting it. Finished or stopped actions restart; fading-out actions resume from their current time and weight.
-     *
-     * `modeFinish` and `fadeTimeFinish` have no effect when `modeLoop` is `'infinite'`.
-     *
-     * **Events**
-     *
-     * {@link ClipEvent}
-     */
-    playClip({ layer, clip: clipName, modeBlend, modeFinish, modeLoop, modeStop, fadeTime, fadeTimeFinish, reverse, reset, speedStart, speedEnd, speedTime, speedEase }: {
-        layer: string;
-        clip: string;
-        singleAction?: boolean;
-        modeBlend?: BlendMode;
-        modeFinish?: FinishMode;
-        modeLoop?: LoopMode;
-        modeStop?: StopMode;
-        fadeTime?: number;
-        fadeTimeFinish?: number;
-        reverse?: boolean;
-        reset?: boolean;
-        speedStart?: number;
-        speedEnd?: number;
-        speedTime?: number;
-        speedEase?: string;
-    }): void;
-    /**
-     * Plays a named camera animation clip with blending, looping, and speed control.
-     *
-     * @param params - Parameters for controlling the camera animation playback.
-     * @param params.layer - The freely named layer used to group camera animation actions.
-     * @param params.clip - The name of the camera animation clip to play.
-     * @param params.modeBlend - How the action is blended with other active actions. Default: **'normal'**
-     * @param params.modeLoop - Number of plays or `'infinite'` for endless looping. Default: **1**
-     * @param params.modeStop - Which previous actions of the same layer are stopped before playback. Default: **'all'**
-     * @param params.fadeTime - Duration in seconds for fading affected previous actions out and the new action in. Default: **0**
-     * @param params.reverse - If `true`, plays the clip in reverse. Default: **false**
-     * @param params.reset - If `true`, resets the clip before a new playback. Default: **false**
-     * @param params.speedStart - Initial playback speed for speed interpolation. Default: **0**
-     * @param params.speedEnd - Target playback speed. Default: **1**
-     * @param params.speedTime - Duration in seconds for speed interpolation. Default: **0**
-     * @param params.speedEase - GSAP easing function name. Default: **'power1.inOut'**
-     *
-     * @remarks
-     * Playing an active or fading-in action again updates its speed without restarting it. Finished or stopped actions restart; fading-out actions resume from their current time and weight.
-     *
-     * **Events**
-     *
-     * {@link ClipEvent}
-     */
-    playClipCam({ layer, clip: clipName, modeBlend, modeLoop, modeStop, fadeTime, reverse, reset, speedStart, speedEnd, speedTime, speedEase }: {
-        layer: string;
-        clip: string;
-        modeBlend?: BlendMode;
-        modeLoop?: LoopMode;
-        modeStop?: StopMode;
-        fadeTime?: number;
-        reverse?: boolean;
-        reset?: boolean;
-        speedStart?: number;
-        speedEnd?: number;
-        speedTime?: number;
-        speedEase?: string;
-    }): void;
+    private getObj3D;
     /**
      * Removes the built-in ambient light and releases its resources.
      */
@@ -2465,7 +2716,7 @@ export declare class Scene {
     /**
      * Updates all assigned materials of an object, optionally including descendant meshes.
      * @param params - Target material values, such as `color`, `roughness`, or `map`.
-     * @param params.obj - Scene object name or `Mesh3D` component.
+     * @param params.obj - Exact Three.js object name.
      * @param params.recursive - Includes descendant meshes. Default: **false**
      * @param params.needsUpdate - Recompiles materials after applying the values. Default: **false**
      *
@@ -2473,26 +2724,11 @@ export declare class Scene {
      * Each shared material is updated once. Texture paths for `map` and `emissiveMap` load asynchronously.
      */
     setMaterialsProps({ obj, recursive, ...props }: {
-        obj: string | Mesh3D;
+        obj: string;
         recursive?: boolean;
         needsUpdate?: boolean;
         [key: string]: any;
     }): void;
-    /**
-     * Stops a named animation clip, optionally slowing it to a halt first.
-     * @param params - Stop settings.
-     * @param params.clipName - Animation clip name.
-     * @param params.speedTime - Slowdown duration in seconds. Default: **0**
-     * @param params.speedEase - GSAP easing function for the slowdown. Default: **'power1.inOut'**
-     *
-     * @remarks
-     * A slowdown emits `Clip_Speed_Start` and `Clip_Speed_Complete`, followed by `Clip_Cancel`. A duration of `0` cancels immediately. See {@link ClipEvent}.
-     */
-    stopClip({ clipName, speedTime, speedEase }: {
-        clipName: string;
-        speedTime?: number;
-        speedEase?: string;
-    }): void;
 }
 
 /**
@@ -2523,6 +2759,7 @@ export declare type SceneClass = new (canvas: HTMLElement, cfg: Cfg, name: strin
 
 /** Scene component class with optional initial parameters. */
 export declare type SceneEntry<TClass extends SceneClass = SceneClass> = TClass | {
+    /** Scene component class to instantiate. */
     class: TClass;
     /**
      * Initial parameters assigned to a scene component class when the app starts. Accepts `Obj3DParams` or `Coll3DParams`, depending on the registered `class`. */
@@ -2542,6 +2779,7 @@ export declare type SceneInsts<T extends Record<string, SceneEntry>> = {
 
 /** @event Fired when the initial scene resources and component readiness hooks are complete. */
 export declare interface SceneReadyEvent {
+    /** Event identifier used to select listeners and state machine transitions. */
     type: 'Scene_Ready';
 }
 
@@ -2576,6 +2814,142 @@ export declare interface SmaaCfg {
     guiOpened: boolean;
 }
 
+/**
+ * Provides loading, playback controls, and listeners for a sound registered in assets.sounds.
+ * Extend this class to implement custom sound behavior. Instances are exposed through App.sound.
+ * Registration does not load audio. Set the Audio listener, then call load() or loadAndStart().
+ * Playback controls have no effect until obj is assigned; loading calls merge registered defaults with supplied options.
+ * @category Core
+ */
+export declare class Sound {
+    private readonly audio;
+    private readonly params;
+    /** The loaded Three.js audio source. It is null until loading completes. */
+    obj: THREE_TYPE.Audio<GainNode> | THREE_TYPE.PositionalAudio | null;
+    /** Subscribes to this sound's events after application event handling. Listeners persist across restarts. Returns an unsubscribe function. */
+    addEventListener<TType extends AudioEvent['type']>(type: TType, listener: (event: AudioEvent & {
+        type: TType;
+    }) => void): Unsubscribe;
+    /**
+     * Changes this sound's volume, speed, and loop through {@link Audio.change}.
+     * A paused sound resumes; a stopped or finished sound remains stopped. Positional settings are load-time options.
+     * @inlineType SoundInstChangeOptions
+     * @param params - Settings and optional transitions.
+     */
+    change(params?: SoundInstChangeOptions): void;
+    /** Checks whether this sound is loaded. */
+    isLoaded(): boolean;
+    /** Checks whether this sound is playing. */
+    isPlaying(): boolean;
+    /**
+     * Loads this sound using its registered defaults. Calls onReady() before Audio_Loaded is emitted.
+     * @inlineType SoundInstLoadOptions
+     * @param params - Loading overrides. Omitted settings use the registered values.
+     */
+    load(params?: SoundInstLoadOptions): void;
+    /**
+     * Loads this sound and starts it after onReady() and Audio_Loaded.
+     * Playback or change() calls in those handlers supersede automatic playback. The registered name cannot be overridden.
+     * @inlineType SoundInstLoadAndStartOptions
+     * @param params - Loading overrides and fade-in settings.
+     */
+    loadAndStart(params?: SoundInstLoadAndStartOptions): void;
+    /** Called after the audio source is loaded, configured, and attached, before Audio_Loaded is emitted. */
+    protected onReady(): void;
+    /**
+     * Pauses this sound through {@link Audio.pause}.
+     * @inlineType SoundInstPauseOptions
+     * @param params - Optional fade-out settings.
+     */
+    pause(params?: SoundInstPauseOptions): void;
+    /** Unsubscribes a listener from this sound. */
+    removeEventListener<TType extends AudioEvent['type']>(type: TType, listener: (event: AudioEvent & {
+        type: TType;
+    }) => void): void;
+    /**
+     * Resumes this sound through {@link Audio.resume}.
+     * @inlineType SoundInstResumeOptions
+     * @param params - Optional fade-in settings.
+     */
+    resume(params?: SoundInstResumeOptions): void;
+    /**
+     * Starts this sound from the beginning through {@link Audio.start}.
+     * @inlineType SoundInstStartOptions
+     * @param params - Optional fade-in settings.
+     */
+    start(params?: SoundInstStartOptions): void;
+    /**
+     * Stops this sound through {@link Audio.stop}.
+     * @inlineType SoundInstStopOptions
+     * @param params - Optional fade-out settings.
+     */
+    stop(params?: SoundInstStopOptions): void;
+}
+
+/** Volume, speed, and loop settings for an existing sound. Positional overrides are supplied when loading. Omitted settings remain unchanged. */
+declare interface SoundChangeOptions {
+    /** Unique audio source name. */
+    name: string;
+    /** Target volume. */
+    volume?: number;
+    /** Target playback speed. Default playback speed: **1**. */
+    speed?: number;
+    /** Whether playback should loop. */
+    loop?: boolean;
+    /** Transition applied to the supplied numeric settings. Omitted: immediate. */
+    fade?: SoundTween;
+}
+
+/** Sound classes available for registration. */
+export declare type SoundClass = new (audio: Audio_2, name: string, params?: SoundInstParams) => Sound;
+
+/** Sound class with optional loading defaults. */
+export declare type SoundEntry<TClass extends SoundClass = SoundClass> = TClass | {
+    /** Sound class to instantiate. */
+    class: TClass;
+    /** Basic loading defaults merged with each load() or loadAndStart() call. The name is always the registration key. */
+    params?: SoundInstParams;
+};
+
+/** Settings for Sound.change(); the instance supplies its registered name. */
+declare type SoundInstChangeOptions = Omit<SoundChangeOptions, 'name'>;
+
+/** Loading overrides and start fade merged with registered Sound defaults; the registered name is retained. */
+declare type SoundInstLoadAndStartOptions = Partial<Omit<SoundLoadAndStartOptions, 'name'>>;
+
+/** Loading overrides merged with registered Sound defaults; the registered name is retained. */
+declare type SoundInstLoadOptions = Partial<Omit<SoundParams, 'name'>>;
+
+/** Basic loading defaults for a registered sound. Its name is always the registration key. */
+export declare type SoundInstParams = Partial<Pick<SoundParams, 'url' | 'parent' | 'volume' | 'loop'>>;
+
+/** Fade-out settings for Sound.pause(). */
+declare type SoundInstPauseOptions = Omit<SoundPauseOptions, 'name'>;
+
+/** Fade-in settings for Sound.resume(). */
+declare type SoundInstResumeOptions = Omit<SoundResumeOptions, 'name'>;
+
+/** Maps sound registrations to their concrete instances. */
+export declare type SoundInsts<T extends Record<string, SoundEntry>> = {
+    [K in keyof T]: T[K] extends SoundClass ? InstanceType<T[K]> : T[K] extends {
+        class: infer TClass extends SoundClass;
+    } ? InstanceType<TClass> : never;
+};
+
+/** Fade-in settings for Sound.start(), which restarts from the beginning. */
+declare type SoundInstStartOptions = Omit<SoundStartOptions, 'name'>;
+
+/** Fade-out settings for Sound.stop(), which resets the position. */
+declare type SoundInstStopOptions = Omit<SoundStopOptions, 'name'>;
+
+/** Loads a sound and starts it when loading is complete. */
+declare interface SoundLoadAndStartOptions extends SoundParams {
+    /** Fade-in duration in seconds. Default: **0**. */
+    time?: number;
+    /** GSAP easing name. Default: **'none'**. */
+    ease?: string;
+}
+
 /**
  * Parameters used to load a global or positional audio source.
  * @category Cfg
@@ -2583,7 +2957,7 @@ export declare interface SmaaCfg {
 export declare interface SoundParams extends Partial<SoundParamsPos> {
     /**
      * Whether playback should loop.
-     * @default true
+     * @default false
      */
     loop?: boolean;
     /**
@@ -2593,7 +2967,7 @@ export declare interface SoundParams extends Partial<SoundParamsPos> {
     /**
      * Scene object name or Obj3D component for positional audio. Use an empty string for global audio.
      */
-    obj: string | Obj3D;
+    parent: string | Obj3D;
     /**
      * Path or URL to the audio file.
      */
@@ -2647,6 +3021,53 @@ export declare interface SoundParamsPos {
     coneOuterGain: number;
 }
 
+/** Pauses a sound while retaining its position and playback speed. */
+declare interface SoundPauseOptions {
+    /** Unique audio source name. */
+    name: string;
+    /** Fade-out before pausing. Omitted: immediate. */
+    fadeOut?: SoundTween;
+}
+
+/** Resumes a sound at its retained position and playback speed. */
+declare interface SoundResumeOptions {
+    /** Unique audio source name. */
+    name: string;
+    /** Fade-in when resuming. Omitted: immediate. */
+    fadeIn?: SoundTween;
+}
+
+/** Typed sound instances exposed through App.sound for an Assets definition. */
+export declare type SoundsInsts<T extends Assets> = SoundInsts<NonNullable<T['sounds']>>;
+
+/** Starts a loaded sound from the beginning. */
+declare interface SoundStartOptions {
+    /** Unique audio source name. */
+    name: string;
+    /** Fade-in duration in seconds. Default: **0**. */
+    time?: number;
+    /** GSAP easing name. Default: **'none'**. */
+    ease?: string;
+}
+
+/** Stops a sound and resets its playback position. */
+declare interface SoundStopOptions {
+    /** Unique audio source name. */
+    name: string;
+    /** Fade-out duration in seconds. Default: **0**. */
+    time?: number;
+    /** GSAP easing name. Default: **'none'**. */
+    ease?: string;
+}
+
+/** Transition settings for sound volume and playback speed. */
+export declare type SoundTween = {
+    /** Fade duration in seconds. Defaults to `0` (immediate). */
+    time?: number;
+    /** GSAP easing name or expression. Defaults to `'none'` (linear). */
+    ease?: string;
+};
+
 /**
  * Controls contact shading with WebGL SSAO.
  * @category Cfg
@@ -2707,7 +3128,10 @@ export declare interface SslCfg {
     guiOpened: boolean;
 }
 
-/** Screen-space lighting modes available across rendering backends. */
+/**
+ * Screen-space lighting modes available across rendering backends; 'none' disables screen-space lighting.
+ * See {@link SslModeWebGl} and {@link SslModeWebGpu} for backend-specific values.
+ */
 export declare type SslMode = SslModeWebGl | SslModeWebGpu;
 
 /** Screen-space lighting modes available with WebGL. */
@@ -2856,27 +3280,23 @@ export declare interface StateMachineCfg {
     inspector: boolean;
 }
 
-/**
- * Controls which active animations on the same layer stop before a new animation plays.
- * - `'all'`: Stops all previous active actions.
- * - `'last'`: Stops only the most recently played previous active action.
- * - `'none'`: Keeps all previous active actions running.
- */
-export declare type StopMode = 'all' | 'last' | 'none';
-
 /** Removes the listener associated with an event subscription. */
 export declare type Unsubscribe = () => void;
 
 /**
  * Connects a custom HTML element to the scene lifecycle and object visibility.
+ * @typeParam TScene - Scene Component registrations from `assets.scene`.
  * @category Web Components
  */
-export declare class Web extends HTMLElement {
+export declare class Web<TScene extends Record<string, SceneEntry> = {}> extends HTMLElement {
     /** Element that hosts the rendered canvas. */
     canvas: Readonly<HTMLElement>;
     cfg: Cfg;
     events: Readonly<Events>;
-    objs3D: Map<string, Obj3D>;
+    /** Registered Scene Component instances, keyed by their Assets names. Use from `onReady()` onward. */
+    comps: {
+        scene: SceneInsts<TScene>;
+    };
     webs: Map<string, Web[]> | null;
     private obj3DFollow;
     private visible;
@@ -2894,7 +3314,7 @@ export declare class Web extends HTMLElement {
      * @param params.obj - The `Obj3D` to follow in the scene.
      */
     follow({ obj }: {
-        obj: Obj3D | string;
+        obj: Obj3D;
     }): void;
     /**
      * Applies the combined followed-object and overlap visibility.
@@ -2931,13 +3351,16 @@ export declare type WebClass = new () => Web;
 
 /** Web component class with optional initial parameters. */
 export declare type WebEntry<TClass extends WebClass = WebClass> = TClass | {
+    /** Web component class to register. */
     class: TClass;
+    /** Initial values assigned to the registered web component. See {@link WebParams}. */
     params?: WebParams;
 };
 
+/** Web component events available to registered listeners. */
 export declare type WebEvent = WebOverlapEvent | WebVisibleEvent;
 
-/** @inheritDoc RenderCfg.webgpu.params */
+/** Parameters passed to `THREE.WebGPURenderer`. */
 export declare type WebGpuRendererParams = NonNullable<ConstructorParameters<typeof THREE_WEBGPU_TYPE.WebGPURenderer>[0]>;
 
 /**
@@ -2953,6 +3376,7 @@ export declare type WebInsts<T extends Record<string, WebEntry>> = {
 
 /** @event Fired when a web component becomes overlapped or unobstructed. */
 export declare interface WebOverlapEvent {
+    /** Event identifier used to select listeners and state machine transitions. */
     type: 'Web_Overlap_Changed';
     /** The affected web component. */
     web: Web;
@@ -2965,6 +3389,7 @@ export declare type WebParams = Record<string, unknown>;
 
 /** @event Fired when a web component's combined object and overlap visibility changes. */
 export declare interface WebVisibleEvent {
+    /** Event identifier used to select listeners and state machine transitions. */
     type: 'Web_Visible_Changed';
     /** The affected web component. */
     web: Web;
@@ -2974,6 +3399,7 @@ export declare interface WebVisibleEvent {
 
 /** @event Fired when the window size changes. */
 export declare interface WindowResizeEvent {
+    /** Event identifier used to select listeners and state machine transitions. */
     type: 'Window_Resize';
 }