illutions 0.29.1 → 0.31.0

package/dist/main.d.ts

@@ -1,42 +1,12 @@
 import { AnyEventObject } from 'xstate';
 import { AnyStateMachine } from 'xstate';
-import { ao } from 'three/addons/tsl/display/GTAONode.js';
-import { createBrowserInspector } from '@statelyai/inspect';
-import { default as default_2 } from 'three/addons/tsl/display/GTAONode.js';
-import { default as default_3 } from 'three/addons/tsl/display/SSRNode.js';
-import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
-import { EffectComposer } from 'three/addons/postprocessing/EffectComposer.js';
-import { EXRLoader } from 'three/addons/loaders/EXRLoader.js';
-import { FXAAShader } from 'three/addons/shaders/FXAAShader.js';
-import { GLTF } from 'three/addons/loaders/GLTFLoader.js';
-import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
-import { HDRLoader } from 'three/addons/loaders/HDRLoader.js';
-import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
-import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';
-import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
-import { OrbitControls as OrbitControls_2 } from 'three/examples/jsm/controls/OrbitControls.js';
-import { OutputPass } from 'three/addons/postprocessing/OutputPass.js';
-import { Pane } from 'tweakpane';
-import { PointerLockControls } from 'three/addons/controls/PointerLockControls.js';
-import { PointerLockControls as PointerLockControls_2 } from 'three/examples/jsm/controls/PointerLockControls.js';
-import { RectAreaLightTexturesLib } from 'three/addons/lights/RectAreaLightTexturesLib.js';
-import { RectAreaLightUniformsLib } from 'three/addons/lights/RectAreaLightUniformsLib.js';
+import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
 import { ReflectorForSSRPass } from 'three/addons/objects/ReflectorForSSRPass.js';
-import { RenderPass } from 'three/addons/postprocessing/RenderPass.js';
-import { ShaderPass } from 'three/addons/postprocessing/ShaderPass.js';
-import { smaa } from 'three/addons/tsl/display/SMAANode.js';
-import { SMAAPass } from 'three/addons/postprocessing/SMAAPass.js';
-import { SSAOPass } from 'three/addons/postprocessing/SSAOPass.js';
-import { ssr } from 'three/addons/tsl/display/SSRNode.js';
-import { SSRPass } from 'three/addons/postprocessing/SSRPass.js';
 import type * as THREE_TYPE from 'three';
 import type * as THREE_WEBGPU_TYPE from 'three/webgpu';
-import type * as THREE_WEBTSL_TYPE from 'three/tsl';
-import { TierResult } from 'detect-gpu';
-import { traa } from 'three/addons/tsl/display/TRAANode.js';
 
 /**
- * Defines the shared anti-aliasing settings.
+ * Shared anti-aliasing Inspector settings.
  * @category Cfg
  */
 export declare interface AaCfg {
@@ -45,17 +15,21 @@ export declare interface AaCfg {
      * @default false
      */
     guiOpened: boolean;
-    /**
-     * Selects the anti-aliasing mode. TRAA automatically falls back to FXAA when WebGL is used.
-     * @default 'none'
-     */
-    mode: 'none' | 'fxaa' | 'smaa' | 'traa';
 }
 
+/** Anti-aliasing modes available across rendering backends. */
+export declare type AaMode = AaModeWebGl | AaModeWebGpu;
+
+/** Anti-aliasing modes available with WebGL. */
+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';
 
 /**
- * Defines the ambient light settings controlling global scene illumination.
+ * Controls uniform ambient illumination.
  * @category Cfg
  */
 export declare interface AmbientlightCfg {
@@ -76,9 +50,8 @@ export declare interface AmbientlightCfg {
     intensity: number;
 }
 
-/** @event Fired when an object animation starts or finishes and triggers the corresponding XState event. */
+/** @event Fired when an object or material color animation starts or completes. */
 export declare interface AnimEvent {
-    /** Identifies this event type. */
     type: 'Anim_Complete' | 'Anim_Start';
     /** The name of the `THREE.Object3D` whose animation changed state. */
     objName: string;
@@ -86,9 +59,8 @@ export declare interface AnimEvent {
     fct: string;
 }
 
-/** @event Fired when a material fade animation starts or finishes and triggers the corresponding XState event. */
+/** @event Fired when a numeric material animation starts or completes. */
 export declare interface AnimFadeEvent {
-    /** Identifies this event type. */
     type: 'Anim_Fade_Complete' | 'Anim_Fade_Start';
     /** The name of the `THREE.Mesh` whose material fade changed state. */
     objName: string;
@@ -101,77 +73,70 @@ export declare interface AnimFadeEvent {
 }
 
 /**
- * Represents the central controller of the illutions 3D engine. The class initializes and manages all core modules of the engine.
- * It provides an entry point for creating and controlling a complete 3D scene.
+ * Starts the application and provides access to its components and runtime systems.
  * @category Core
  */
-export declare class App<TClasses extends Classes = {}> {
+export declare class App<TComps extends Comps = {}> {
     readonly audio: Audio_2;
-    private readonly compCtrls;
+    private readonly ctrl;
     readonly engine: Engine;
-    private readonly lib;
+    private readonly model;
     readonly envCtrls: EnvCtrls;
     readonly events: Events;
     readonly orbitCtrls: OrbitCtrls;
     readonly fpvCtrls: FpvCtrls;
     readonly raycast: Raycast;
+    readonly scene: Scene;
     readonly stateMachine: StateMachine;
+    private readonly webCtrls;
     private cam3D;
     private readonly inspector;
-    readonly comps: CompInsts<NonNullable<TClasses['comps']>>;
-    readonly objs3D: Obj3DInsts<NonNullable<TClasses['objs3D']>>;
-    private compsMap;
+    readonly comps: CompsInsts<TComps>;
     private objs3DMap;
-    /* Excluded from this release type: __constructor */
-    init(cfg: Cfg): Promise<void>;
+    private websMap;
     /**
-     * Asynchronously creates and initializes a new `App` instance, which acts as the central entry point of the application. After successful validation, this method constructs a fully configured App object that manages 3D objects, web components, application state, and runtime dependencies. This method is typically called once during application startup to ensure a consistent initialization sequence, guaranteeing that all required configuration values and checks are completed before the main logic begins execution.
-     * @param cfg - A `Cfg` object containing initialization parameters, runtime settings, and optional debug options.
-     * @param classes - Class registry for components and 3D objects. Default: **empty object**
+     * 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 createStateMachine - Factory function that receives the fully created `App` instance and returns a state machine.
      *
-     * @returns A promise that resolves when the app startup sequence has completed or when a startup error has been caught.
+     * @returns Resolves after startup completes or a startup error is caught.
      *
      * **Example**
-     * {@includeCode ../examples/app-run.ts}
+     * {@includeCode ../../../apps-doc/examples/app-run.ts}
      */
-    static run<TClasses extends Classes = {}>(cfg?: Cfg, classes?: TClasses, createStateMachine?: (app: App<TClasses>) => AnyStateMachine): Promise<void>;
+    static run<TComps extends Comps = {}>(cfg?: Cfg, comps?: TComps, createStateMachine?: (app: App<TComps>) => AnyStateMachine): Promise<void>;
 }
 
 /**
- * The `Audio` class manages audio playback within a Three.js scene. It handles loading, attaching, fading, and controlling global and positional audio sources, and ensures smooth transitions and automatic
- * AudioContext management.
+ * Loads and controls global and positional audio with volume fades.
  * @category Core
  */
 declare class Audio_2 {
     private readonly ctx;
     private readonly loader;
-    private readonly engine;
+    private readonly scene;
     private readonly events;
     private readonly loadedSounds;
     private readonly params;
     private listener;
-    /* Excluded from this release type: __constructor */
     private attachSoundTo;
     /**
-     * Returns the audio parameters currently used at runtime.
-     * @returns A snapshot of the mutable audio settings.
+     * Returns a snapshot of playback timing and positional audio settings.
      */
     get(): Partial<AudioCfg>;
     /**
-     * Checks whether an audio source with the given name is loaded.
-     * @param params - Parameter object.
-     * @param params.name - The name of the audio.
-     * @returns True if the audio is loaded, otherwise false.
+     * Checks whether a named sound is loaded.
+     * @param params - Sound selection.
+     * @param params.name - Sound name.
      */
     isLoaded({ name }: {
         name: string;
     }): boolean;
     /**
-     * Checks whether an audio source with the given name is currently playing.
-     * @param params - Parameter object.
-     * @param params.name - The name of the audio.
-     * @returns True if the audio is playing, otherwise false.
+     * Checks whether a named sound is playing.
+     * @param params - Sound selection.
+     * @param params.name - Sound name.
      */
     isPlaying({ name }: {
         name: string;
@@ -189,11 +154,11 @@ declare class Audio_2 {
      */
     loadAndPlay({ name, url, object, volume, fade, loop }: SoundParams): void;
     /**
-     * Plays an audio that has finished loading, with a smooth fade-in.
+     * Plays a loaded sound with a volume fade-in.
      * 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 - Parameter object.
-     * @param params.name - The name of the loaded audio to play.
+     * @param params - Sound selection.
+     * @param params.name - Loaded sound name.
      */
     play({ name }: {
         name: string;
@@ -205,10 +170,10 @@ declare class Audio_2 {
     private setAttribute;
     private setAudioContext;
     /**
-     * Creates a `THREE.AudioListener` and attaches it to a named scene object or the active camera managed by `Cam3D`.
+     * Attaches an audio listener to a scene object or camera. Set a listener before loading sounds.
      *
-     * @param params - Parameter object.
-     * @param params.object - The name of a scene object or the `Cam3D` instance to attach the listener to.
+     * @param params - Listener target.
+     * @param params.object - Scene object name or camera to attach the listener to.
      */
     setListener({ object }: {
         object: string | Cam3D;
@@ -221,24 +186,23 @@ declare class Audio_2 {
      */
     set(params: Partial<AudioCfg>): void;
     /**
-     * Stops the playback of an audio with a smooth fade-out.
-     * @param params - Parameter object.
-     * @param params.name - The name of the audio to stop.
+     * Fades out a playing sound and stops it.
+     * @param params - Sound selection.
+     * @param params.name - Sound name.
      */
     stop({ name }: {
         name: string;
     }): void;
     /**
-     * Registers and executes a low-level extension function with access to the public `Audio` API.
-     * @param extension - Function that receives the current `Audio` instance and can use its public members and methods.
-     * @remarks This method is intended for advanced custom integrations where developers need direct access to the engine instance. The extension is executed once immediately when `use()` is called.
+     * Runs an extension callback immediately with access to the public API.
+     * @param extension - Callback receiving this `Audio` instance.
      */
     use(extension: (audio: Audio_2) => void): void;
 }
 export { Audio_2 as Audio }
 
 /**
- * Defines the audio settings used for playback timing and distance-based spatial attenuation.
+ * Controls playback timing and how positional sound fades with distance.
  * @category Cfg
  */
 export declare interface AudioCfg {
@@ -253,7 +217,7 @@ export declare interface AudioCfg {
      */
     guiOpened: boolean;
     /**
-     * The default sound start offset in milliseconds.
+     * Delay in milliseconds before loading audio for automatic playback.
      * @default 200
      */
     delayPlaySound: number;
@@ -268,7 +232,7 @@ export declare interface AudioCfg {
      */
     rolloffFactor: number;
     /**
-     * The maximum distance at which the sound is still audible.
+     * Distance beyond which linear attenuation stops reducing volume.
      * @default 1000
      */
     maxDistance: number;
@@ -278,12 +242,12 @@ export declare interface AudioCfg {
      */
     distanceModel: 'linear' | 'inverse' | 'exponential';
     /**
-     * The angle inside the cone where there is no attenuation.
+     * Inner cone angle in degrees, within which sound is not attenuated.
      * @default 360
      */
     coneInnerAngle: number;
     /**
-     * The angle outside the cone where full attenuation is applied.
+     * Outer cone angle in degrees, beyond which `coneOuterGain` applies.
      * @default 360
      */
     coneOuterAngle: number;
@@ -296,27 +260,25 @@ export declare interface AudioCfg {
 
 /** @event Fired when an audio file has finished loading and is ready for playback. */
 export declare interface AudioLoadedEvent {
-    /** Identifies this event type. */
     type: 'Audio_Loaded';
     /** The unique name assigned to the loaded sound. */
     soundName: string;
 }
 
 /**
- * Defines how an animation action is blended with other active actions.
- * - 'normal': Blends the action's values with other normal actions according to their weights.
- * - 'additive': Adds the action's values to the current animation result according to its weight.
+ * Controls how an animation blends with other active animations.
+ * - `'normal'`: Blends the action's values with other normal actions according to their weights.
+ * - `'additive'`: Adds the action's values to the current animation result according to its weight.
  */
 export declare type BlendMode = 'normal' | 'additive';
 
 /**
- * Wraps a `THREE.Camera` and provides a structured interface for configuring and controlling camera settings.
- * @category 3D Objects
+ * Controls the active camera and adopts compatible cameras from GLTF scenes.
+ * @category Scene Components
  */
 export declare class Cam3D extends Obj3D {
-    /* Excluded from this release type: lookMode */
     /**
-     * The `THREE.Camera` instance used for rendering the scene. It can represent different camera types, such as perspective or orthographic.
+     * Active perspective or orthographic camera.
      * @default `THREE.PerspectiveCamera`
      */
     readonly obj: THREE_TYPE.Camera;
@@ -327,23 +289,19 @@ export declare class Cam3D extends Obj3D {
     /** Reference to the original target `THREE.Object3D` loaded from the GLTF scene. */
     targetGltf: THREE_TYPE.Object3D | null;
     private readonly tmpVec;
-    /* Excluded from this release type: __constructor */
     /**
-     * Called once for a camera found while traversing a GLTF scene. Copies the traversed camera type, projection settings, and world transform to `obj`.
+     * Called when a matching GLTF camera is found. Adopts its projection and world transform when the camera types match.
      * @param objGltf - The GLTF `THREE.Camera` object.
      * @public
      *
      * **Example**
-     * {@includeCode ../../examples/cam3d-dollycamera.ts}
+     * {@includeCode ../../../../apps-doc/examples/cam3d-dollycamera.ts}
      */
     protected onTraverse(objGltf: THREE_TYPE.Camera): void;
-    /* Excluded from this release type: traverse */
-    /* Excluded from this release type: update */
-    /* Excluded from this release type: updateCanvasResize */
 }
 
 /**
- * Defines the shared camera settings used to position, orient and clip the scene view.
+ * Controls camera position, viewing direction, and clipping distances.
  * @category Cfg
  */
 export declare interface CamBaseCfg {
@@ -377,18 +335,27 @@ export declare interface CamBaseCfg {
     };
 }
 
-export declare type CamCfg = CamPerspectiveCfg | CamOrthographicCfg;
-
 /**
- * Defines the orthographic camera settings used to render the scene without perspective distortion.
+ * Selects the camera projection and controls the initial view.
  * @category Cfg
  */
-export declare interface CamOrthographicCfg extends CamBaseCfg {
+export declare interface CamCfg extends CamBaseCfg {
     /**
-     * The camera type.
-     * @default 'orthographic'
+     * The active camera type.
+     * @default 'perspective'
      */
-    type: 'orthographic';
+    type: 'perspective' | 'orthographic';
+    /** Perspective camera projection settings. */
+    perspective: CamPerspectiveCfg;
+    /** Orthographic camera projection settings. */
+    orthographic: CamOrthographicCfg;
+}
+
+/**
+ * Controls the visible area of an orthographic camera.
+ * @category Cfg
+ */
+export declare interface CamOrthographicCfg {
     /**
      * Camera frustum left plane.
      * @default -1
@@ -409,61 +376,42 @@ export declare interface CamOrthographicCfg extends CamBaseCfg {
      * @default -1
      */
     bottom: number;
-    /** @private */
-    fov?: never;
-    /** @private */
-    aspect?: never;
 }
 
 /**
- * Defines the perspective camera settings used to render the scene with depth perception.
+ * Controls perspective projection.
  * @category Cfg
  */
-export declare interface CamPerspectiveCfg extends CamBaseCfg {
-    /**
-     * The camera type.
-     * @default 'perspective'
-     */
-    type: 'perspective';
+export declare interface CamPerspectiveCfg {
     /**
      * Vertical field of view in degrees.
      * @default 75
      */
     fov: number;
-    /** @private */
-    left?: never;
-    /** @private */
-    right?: never;
-    /** @private */
-    top?: never;
-    /** @private */
-    bottom?: never;
 }
 
-/** @event Fired when the user uses keys while the canvas has focus and triggers the corresponding XState event. */
+/** @event Fired when a key is pressed or released while the canvas has focus. */
 export declare interface CanvasKeyEvent {
-    /** Identifies this event type. */
     type: 'Canvas_Key_Down' | 'Canvas_Key_Up';
     /** Native keyboard event from the canvas interaction. */
     event: KeyboardEvent;
 }
 
-/** @event Fired when the user uses the pointer on the canvas and triggers the corresponding XState event. */
+/** @event Fired when the pointer clicks, enters, or leaves the canvas. */
 export declare interface CanvasPointerEvent {
-    /** Identifies this event type. */
     type: 'Canvas_Click' | 'Canvas_Pointer_Enter' | 'Canvas_Pointer_Leave';
     /** Native pointer event from the canvas interaction. */
     event: PointerEvent;
 }
 
 /**
- * Defines the full configuration structure used to initialize the application.
+ * Startup settings for the application.
  * @category Cfg
  */
 export declare interface Cfg {
     /** Audio settings. */
     audio: AudioCfg;
-    /** Camera settings. */
+    /** Camera settings for a perspective or orthographic camera. */
     cam: CamCfg;
     /** Component settings. */
     comps: CompsCfg;
@@ -471,6 +419,8 @@ export declare interface Cfg {
     debug: DebugCfg;
     /** Environment controls settings. */
     envCtrls: EnvCtrlsCfg;
+    /** First-person controls settings. */
+    fpvCtrls: FpvCtrlsCfg;
     /** Default GUI settings. */
     gui: GuiCfg;
     /** Light and shadow settings. */
@@ -481,40 +431,30 @@ export declare interface Cfg {
     model: ModelCfg;
     /** Orbit controls settings. */
     orbitCtrls: OrbitCtrlsCfg;
-    /** First-person controls settings. */
-    fpvCtrls: FpvCtrlsCfg;
     /** Post-processing settings. */
     post: PostCfg;
-    /** Renderer settings. */
-    render: RenderCfg;
     /** Raycasting settings. */
     raycast: RaycastCfg;
+    /** Renderer settings. */
+    render: RenderCfg;
     /** Scene settings. */
     scene: SceneCfg;
     /** State machine settings. */
     stateMachine: StateMachineCfg;
 }
 
-/** Defines the initial configuration that is applied when the application starts. */
+/** Default startup settings, updated by `setCfg()`. */
 export declare const cfg: Cfg;
 
-/**
- * Groups optional class registries for `Obj3D` and `Comp`.
- *
- * @typeParam TObj3DClasses - Record of named 3D object class constructors.
- * @typeParam TCompClasses - Record of named component class constructors.
- *
- * @example
- * type MyClasses = Classes<{ cube: typeof Cube }, { marker: typeof Marker }>;
- */
-export declare type Classes<TObj3DClasses extends Record<string, Obj3DClass> = {}, TCompClasses extends Record<string, CompClass> = {}> = {
-    objs3D?: TObj3DClasses;
-    comps?: TCompClasses;
+/** Configuration values accepted by `setCfg`. */
+export declare type CfgSet = DeepPartial<Cfg> & {
+    render?: DeepPartial<RenderCfg> & {
+        profile?: RenderProfileValidCfg;
+    };
 };
 
-/** @event Fired when a clip starts, completes, is canceled, fades its weight, or changes its playback speed. */
+/** @event Fired when clip playback, weight fading, or speed changes start or complete, or when playback is canceled. */
 export declare interface ClipEvent {
-    /** Identifies this event type. */
     type: 'Clip_Start' | 'Clip_Complete' | 'Clip_Cancel' | 'Clip_Fade_Start' | 'Clip_Fade_Complete' | 'Clip_Speed_Start' | 'Clip_Speed_Complete';
     /** The name of the affected `THREE.AnimationClip`. */
     clipName: string;
@@ -524,112 +464,46 @@ export declare interface ClipEvent {
     fadeMode?: ActionFadeMode;
 }
 
-/** Defines how a scene object participates in raycasting. */
-export declare interface Collider {
-    /** Scene object or scene-object name used for raycasting. */
-    obj: Obj3D | string;
-    /** Hides the object while it is registered as a collider. */
-    hide?: boolean;
-    /** Allows the object to occlude tracked occludees and pickables. */
-    occluder?: boolean;
-    /** Allows the object to emit pointer events. */
-    pickable?: boolean;
-}
-
-declare type ColorNode = THREE_WEBGPU_TYPE.Node<'vec4'>;
-
 /**
- * Represents a reusable web-component logic unit bound to a custom element that participates in the scene lifecycle.
- * @category Components
+ * Uses a `Mesh3D` for pointer picking or occlusion and optionally maps raycast events to another rendered mesh.
+ * @category Scene Components
  */
-export declare class Comp extends HTMLElement {
-    /** The root HTML element that hosts the visual container for the engine. */
-    canvas: Readonly<HTMLElement>;
-    cfg: Cfg;
-    comps: Map<string, Comp[]> | null;
-    events: Readonly<Events>;
-    objs3D: Map<string, Obj3D>;
-    private compCtrls;
-    private obj3DFollow;
-    private visible;
-    private visibleFollow;
-    private visibleOverlap;
-    private unSubFollow;
-    private unSubVisible;
-    private clearFollow;
-    private emitEvent;
-    /**
-     * Makes this component follow an `Obj3D` by subscribing to updates of its screen position and combined visibility.
-     *
-     * @param params - The follow parameters.
-     * @param params.obj - The `Obj3D` to follow in the scene.
-     */
-    follow({ obj }: {
-        obj: Obj3D | string;
-    }): void;
-    /* Excluded from this release type: getObj3DFollow */
-    /* Excluded from this release type: isVisibleFollow */
-    /**
-     * Applies the combined followed-object and overlap visibility.
-     * @param visible - Whether the web component is visible after combining all visibility conditions.
-     */
-    protected onVisibilityChanged(visible: boolean): void;
-    /**
-     * Called once after the `THREE.Scene`, the `THREE.WebGLRenderer` or `THREE.WebGPURenderer`, the `EnvCtrls` are initialized and an existing GLTF model has been loaded and traversed.
-     * @public
-     *
-     * **Example**
-     * {@includeCode ../../examples/ilu-onready.ts}
-     */
-    protected onReady(): void;
-    /**
-     * Called once after the `THREE.Scene` is initialized, before an existing GLTF model is loaded.
-     * @public
-     */
-    protected onStart(): void;
-    /* Excluded from this release type: ready */
-    /* Excluded from this release type: setVisibleOverlap */
-    /* Excluded from this release type: start */
-    /**
-     * Registers this component for screen-space overlap tracking using `cfg.comps.overlap.padding`.
-     * Farther registered components are hidden when their screen-space rectangles overlap.
-     */
-    trackOverlap(): void;
-    /** Stops this component from following the currently subscribed {@link Obj3D}. */
-    unfollow(): void;
-    /** Stops screen-space overlap tracking and removes any overlap-based hiding from this component. */
-    untrackOverlap(): void;
-    private updateVisibility;
+export declare class Coll3D extends Mesh3D {
+    /** The rendered mesh represented by this collider, or `null` when the collider represents itself. */
+    target: Mesh3D | null;
+    /** Allows this collider or its mesh descendants to emit pointer events. */
+    pickable: boolean;
+    /** Allows this collider or its mesh descendants to occlude tracked objects. */
+    occluder: boolean;
+    private readonly targetName;
+}
+
+/** Initial parameters for a mesh used as a raycast collider. */
+export declare interface Coll3DParams extends Obj3DParams {
+    /** Name of the rendered `Mesh3D` represented by this collider. Without a target, the collider represents itself. */
+    target?: string;
+    /** Allows the collider to emit pointer events. */
+    pickable?: boolean;
+    /** Allows the collider to occlude tracked objects. */
+    occluder?: boolean;
 }
 
-/** Constructor type for `Comp` classes. */
-export declare type CompClass = new () => Comp;
-
-/* Excluded from this release type: CompCtrls */
-
-export declare type CompEvent = CompOverlapEvent | CompVisibleEvent;
-
 /**
- * Maps a record of Comp classes to a record of component instance arrays.
- * { key1: typeof Comp1 } -> { key1: Comp1[] }
- * @hidden
+ * 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 CompInsts<T extends Record<string, CompClass>> = {
-    [K in keyof T]: InstanceType<T[K]>[];
+export declare type Comps<TScene extends Record<string, SceneEntry> = {}, TWeb extends Record<string, WebEntry> = {}> = {
+    scene?: TScene;
+    web?: TWeb;
 };
 
-/** @event Fired when the overlap state of a web component changes and triggers the corresponding XState event. */
-export declare interface CompOverlapEvent {
-    /** Identifies this event type. */
-    type: 'Comp_Overlap_Changed';
-    /** The affected web component. */
-    comp: Comp;
-    /** Whether the component is overlapped by a nearer component. */
-    overlapped: boolean;
-}
-
 /**
- * Defines component settings.
+ * Shared component settings.
  * @category Cfg
  */
 export declare interface CompsCfg {
@@ -637,8 +511,14 @@ export declare interface CompsCfg {
     overlap: CompsOverlapCfg;
 }
 
+/** Registered scene components and web component instances available at runtime. */
+export declare type CompsInsts<T extends Comps> = {
+    scene: SceneInsts<NonNullable<T['scene']>>;
+    web: WebInsts<NonNullable<T['web']>>;
+};
+
 /**
- * Defines screen-space overlap settings for components.
+ * Controls spacing when hiding overlapping web components.
  * @category Cfg
  */
 export declare interface CompsOverlapCfg {
@@ -649,467 +529,163 @@ export declare interface CompsOverlapCfg {
     padding: number;
 }
 
-/** @event Fired when the combined 3D-object and overlap visibility of a web component changes and triggers the corresponding XState event. */
-export declare interface CompVisibleEvent {
-    /** Identifies this event type. */
-    type: 'Comp_Visible_Changed';
-    /** The affected web component. */
-    comp: Comp;
-    /** Whether the component is visible after combining all visibility conditions. */
-    visible: boolean;
-}
-
 /**
- * Defines the debugging settings that can be toggled during development.
+ * Controls diagnostic console output.
  * @category Cfg
  */
 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.
+     * - `'none'`: No debug messages are logged.
+     * - `'xstate'`: Only logs events that were accepted by the state machine.
+     * - `'all'`: Logs all debug messages.
      * @default 'xstate'
      */
-    log: 'none' | 'xstate' | 'all';
+    log: DebugLog;
 }
 
+/** @inheritDoc DebugCfg.log */
+export declare type DebugLog = 'none' | 'xstate' | 'all';
+
+declare type DeepPartial<T> = T extends readonly unknown[] ? T : T extends object ? {
+    [P in keyof T]?: DeepPartial<T[P]>;
+} : T;
+
 /**
- * The `Engine` class serves as the core runtime of the illutions Engine. It initializes and manages the Three.js scene, renderer, camera, lighting, post-processing, and loaded models. The class orchestrates
- * rendering, animation playback, and material updates, while integrating system events, raycasting, and performance monitoring. It provides the foundation for real-time interaction and visual consistency across
- * all scene components.
+ * Renders the scene and controls post-processing and adaptive performance.
  * @category Core
  */
 export declare class Engine {
-    /* Excluded from this release type: scene */
     private readonly cam3D;
+    private readonly cfg;
     private readonly events;
-    private readonly lib;
     private readonly modules;
     private readonly objs3D;
-    private readonly cfg;
+    private readonly scene;
     private readonly infoBox;
-    private readonly model;
-    private actionCtrls;
-    private gltf;
-    private mixer;
     private callbacks;
     private resolveWaitForRender;
     private canvas;
     private composer;
-    /* Excluded from this release type: renderer */
     private renderPipeline;
-    /* Excluded from this release type: sceneReady */
-    /* Excluded from this release type: rendererReady */
+    private postProfile;
+    private postProfileLast;
     private fxaaPass;
     private outputPass;
     private renderPass;
     private smaaPass;
     private tslPass;
     private aaNode;
-    /* Excluded from this release type: ssaoPass */
-    /* Excluded from this release type: gtaoNode */
-    /* Excluded from this release type: ssrPass */
-    /* Excluded from this release type: ssrNode */
-    /* Excluded from this release type: groundReflector */
-    private reflectivesSSR;
-    private ambientLight;
-    private hemisphereLight;
-    private powerMode;
-    private postNoise;
-    private postNoiseCheck;
+    private rttNode;
+    private traaWarmupContext;
+    private ecoButtonActive;
+    private gfxChanging;
+    private gfxIndex;
+    private gfxLevels;
+    private gfxMode;
+    private readonly gfxPostProfiles;
+    private gfxState;
+    private gfxDownOnly;
     private dTs;
     private dT;
-    private dTFrameMax;
-    private gpuFps;
     private timeGsap;
     private timeLast;
     private timeLastFrame;
     private resizeTimeout;
     private resizeDelay;
-    /* Excluded from this release type: __constructor */
-    /* Excluded from this release type: init */
-    private initFirstScene;
-    private initWebGpuRenderer;
     /**
-     * Registers a callback that is executed on every requestAnimationFrame update.
-     * @param {(deltaTime: number) => void} cb - Callback executed once per frame with `deltaTime`.
+     * Runs a callback on each animation frame, including frames skipped by Eco Mode.
+     * @param cb - Callback receiving the elapsed time in seconds.
      */
     addOnFrameUpdate(cb: (deltaTime: number) => void): void;
     /**
-     * Animates the camera on a curved path towards a target position while optionally updating the camera's look-at target.
-     *
-     * @param params - Parameter object for the animation.
-     * @param params.camTarget - The target the camera should move toward.
-     * @param params.aimTarget - The target the camera should face during or after the animation.
-     * @param params.radiusOut - The outward curve radius used to shape the camera path. Default: **1**
-     * @param params.duration - The animation duration in seconds. Default: **2**
-     * @param params.ease - The easing function name for GSAP. Default: **'power1.inOut'**
-     *
-     * @remarks
-     * The method resolves `camTarget` and optionally `aimTarget` to world positions and animates the camera position along a curved trajectory instead of a straight line. If `aimTarget` is provided,
-     * the camera target position is interpolated towards the resolved aim position while the camera moves along the curve.
-     *
-     * **Events**
-     *
-     * {@link AnimEvent}
+     * 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.
      */
-    animCamCurveTo({ camTarget, aimTarget, radiusOut, duration, ease }: {
-        camTarget: THREE_TYPE.Vector3 | string | Obj3D;
-        aimTarget?: THREE_TYPE.Vector3 | string | Obj3D;
-        radiusOut?: number;
-        duration?: number;
-        ease?: string;
-    }): void;
+    enableAaMode(aaMode: AaMode): Promise<void>;
     /**
-     * Animates the `THREE.PerspectiveCamera` towards a target object and frames it based on its own geometry. The camera keeps the resolved target object as the look-at target while its distance is calculated
-     * from the object's bounding size and the camera's field of view.
-     *
-     * @param params - Parameter object for the animation.
-     * @param params.target - The target object or the name of the target object.
-     * @param params.duration - The animation duration in seconds. Default: **1**
-     * @param params.ease - The easing function name for GSAP. Default: **'power2.inOut'**
-     * @param params.dist - Framing factor applied to the calculated camera distance. Default: **1**
-     *
-     * @remarks
-     * Only the target object's own geometry is used to calculate the bounding size. Child objects are intentionally ignored.
-     *
-     * **Events**
-     *
-     * {@link AnimEvent}
+     * Switches screen-space lighting at runtime. WebGL supports SSAO; WebGPU supports GTAO and SSGI.
+     * SSGI requires TRAA, a perspective camera, and compatible WebGPU hardware.
+     * @param sslMode - Lighting mode, or `none` to disable it.
      */
-    animCamTo({ target, duration, ease, dist }: {
-        target: string | Obj3D;
-        duration?: number;
-        ease?: string;
-        dist?: number;
-    }): void;
+    enableSslMode(sslMode: SslMode): Promise<void>;
     /**
-     * The method finds a Three.js mesh by name, validates that it has a material with color properties and animates them (e.g. color, emissive, ...).
-     *
-     * @param params - Parameter object for the animation.
-     * @param params.mesh - The name of the mesh object whose material color should be animated.
-     * @param params.duration - The animation duration in seconds. Default: **0**
-     * @param params.ease - The easing function name for GSAP. Default: **'power1.inOut'**
-     *
-     * @remarks
-     * Additional properties of `params` can specify one or more material color fields to animate (e.g. `color`, `emissive`, ...), with their target color values. Values may be color strings, numbers,
-     * or `THREE.Color` instances.
-     *
-     * **Events**
-     *
-     * {@link AnimEvent}
+     * Enables or disables screen-space reflections, loading the effect when needed. Disabling WebGL SSR also hides its ground reflector.
+     * @param enable - Whether to show reflections.
      */
-    animMaterialColor({ mesh, ...params }: {
-        mesh: string;
-        duration?: number;
-        ease?: string;
-    } & {
-        [key: string]: string | number | THREE_TYPE.Color;
-    }): void;
+    enableSsr(enable: boolean): Promise<void>;
+    private isPostCfg;
     /**
-     * The method finds a Three.js mesh by name, validates that it has a material with numeric properties (e.g. `metalness`, `roughness`, `opacity`, etc.) and animates them over time using GSAP.
-     *
-     * @param params - Parameter object for the animation.
-     * @param params.mesh - The name of the mesh object whose material property will be animated.
-     * @param params.startValue - The starting value of the property. Default: **Current material's value**
-     * @param params.infinite - If `true`, the animation loops infinitely. Default: **false**
-     * @param params.duration - The animation duration in seconds. Default: **0**
-     * @param params.ease - The easing function name for GSAP. Default: **'power1.inOut'**
-     * @param params.needsUpdate - Requests one material recompilation when the animation starts. Default: **false**
-     *
-     * @remarks
-     * Additional properties of `params` can specify one or more material numeric fields to animate (e.g. `metalness`, `roughness`, `opacity`, ...) with their target numeric values. Only the **first** provided
-     * property will be animated per call.
-     *
-     * **Events**
-     *
-     * {@link AnimFadeEvent}
+     * Stops a registered animation-frame callback.
+     * @param cb - Previously registered callback.
      */
-    animMaterialNumeric({ mesh, needsUpdate, ...params }: {
-        mesh: string;
-        startValue?: number | null;
-        infinite?: boolean;
-        duration?: number;
-        ease?: string;
-        needsUpdate?: boolean;
-        [key: string]: any;
-    }): void;
-    private calcEaseArea;
+    removeOnFrameUpdate(cb: (deltaTime: number) => void): void;
+    private setGfxLevel;
+    private setPostWebGl;
+    private setPostWebGpu;
+    /** Toggles the browser fullscreen mode for the associated canvas element. */
+    toggleFullscreen(): void;
+    private update;
     /**
-     * Selects the active anti-aliasing mode. The modes `'fxaa'`, `'smaa'` and `'traa'` lazy-load their required modules.
-     * @param aaMode - The anti-aliasing mode to use.
+     * Resizes the renderer, camera projection, post-processing, and reflections to fit the canvas.
      */
-    enableAaMode(aaMode: Cfg['post']['aa']['mode']): Promise<void>;
+    updateCanvasResize(): void;
     /**
-     * Enables or disables screen-space ambient occlusion. Passing `true` lazy-loads the required module.
-     * @param enable - Whether SSAO should be enabled.
+     * Runs an extension callback immediately with access to the public API.
+     * @param extension - Callback receiving this `Engine` instance.
      */
-    enableSsao(enable: boolean): Promise<void>;
+    use(extension: (engine: Engine) => void): void;
+}
+
+/**
+ * Controls environment lighting, the visible background, and their rotation. The first map supplies lighting and background; later maps update only the background.
+ * @category Core
+ */
+export declare class EnvCtrls {
+    private readonly cfg;
+    private readonly engine;
+    private readonly events;
+    private readonly modules;
+    private readonly scene;
+    private envEnabled;
+    private envInit;
+    private envLoadId;
+    private envIntensity;
+    private bgdIntensity;
+    private bgdBlurriness;
+    private rotation;
+    private rotationSpeed;
+    private envType;
+    private envMaps;
+    private envText;
+    private bgdText;
+    private callback;
+    private frameWaiters;
+    private timeBgdRot;
+    private applyBgds;
+    private applyEnv;
+    private disposePrevBgd;
+    private disposeText;
     /**
-     * Enables or disables screen-space reflections. In WebGL mode, the SSR pass also synchronizes the ground reflector and the optional selective reflection objects. When SSR is disabled, the reflector is detached from the pass and hidden. Passing `true` lazy-loads the required module.
-     * @param enable - Whether SSR should be enabled.
+     * Loads and applies environment lighting and background maps. Later maps replace only the background.
+     * @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`.
      */
-    enableSsr(enable: boolean): Promise<void>;
-    private isPostCfg;
-    /* Excluded from this release type: isPostEnabled */
-    private isPostGpu;
+    enable(params?: {
+        type: EnvCtrlsCfg["type"];
+        map: EnvCtrlsCfg["map"];
+    }): void;
+    /** Removes environment lighting and background maps, cancels pending updates, and stops rotation. */
+    disable(): void;
     /**
-     * Finds a Three.js animation clip by name and plays it through the `THREE.AnimationMixer`.
-     *
-     * @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.blendMode - How the action is blended with other active actions. Default: **'normal'**
-     * @param params.finishMode - Whether the final pose is held or faded out after the final loop. Default: **'hold'**
-     * @param params.loopMode - Number of plays or `'infinite'` for endless looping. Default: **1**
-     * @param params.stopMode - Which previous actions of the same layer are stopped before playback. Default: **'all'**
-     * @param params.fadeDuration - Duration in seconds for fading affected previous actions out and the new action in. Default: **0**
-     * @param params.fadeDurationFinish - Duration in seconds for `finishMode: '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.startSpeed - Initial playback speed for speed interpolation. Default: **0**
-     * @param params.endSpeed - Target playback speed. Default: **1**
-     * @param params.duration - Duration in seconds for speed interpolation. Default: **0**
-     * @param params.ease - GSAP easing function name. Default: **'power1.inOut'**
-     *
-     * @remarks
-     * Calling a running or fading-in action again is ignored. A finished or stopped action starts again, while an unfinished fading-out action continues at its current time and fades back in from its current weight.
-     *
-     * `finishMode` and `fadeDurationFinish` have no effect when `loopMode` is `'infinite'`.
-     *
-     * **Events**
-     *
-     * {@link ClipEvent}
+     * Returns a snapshot of environment rotation, intensity, and background blurriness.
      */
-    playClip({ layer, clip: clipName, blendMode, finishMode, loopMode, stopMode, fadeDuration, fadeDurationFinish, reverse, reset, startSpeed, endSpeed, duration, ease }: {
-        layer: string;
-        clip: string;
-        singleAction?: boolean;
-        blendMode?: BlendMode;
-        finishMode?: FinishMode;
-        loopMode?: LoopMode;
-        stopMode?: StopMode;
-        fadeDuration?: number;
-        fadeDurationFinish?: number;
-        reverse?: boolean;
-        reset?: boolean;
-        startSpeed?: number;
-        endSpeed?: number;
-        duration?: number;
-        ease?: string;
-    }): void;
+    get(): Partial<EnvCtrlsCfg>;
     /**
-     * Finds a camera animation clip by name and plays it through the `THREE.AnimationMixer`.
-     *
-     * @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.blendMode - How the action is blended with other active actions. Default: **'normal'**
-     * @param params.loopMode - Number of plays or `'infinite'` for endless looping. Default: **1**
-     * @param params.stopMode - Which previous actions of the same layer are stopped before playback. Default: **'all'**
-     * @param params.fadeDuration - 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.startSpeed - Initial playback speed for speed interpolation. Default: **0**
-     * @param params.endSpeed - Target playback speed. Default: **1**
-     * @param params.duration - Duration in seconds for speed interpolation. Default: **0**
-     * @param params.ease - GSAP easing function name. Default: **'power1.inOut'**
-     *
-     * @remarks
-     * Calling a running or fading-in action again is ignored. A finished or stopped action starts again, while an unfinished fading-out action continues at its current time and fades back in from its current weight.
-     *
-     * **Events**
-     *
-     * {@link ClipEvent}
-     */
-    playClipCam({ layer, clip: clipName, blendMode, loopMode, stopMode, fadeDuration, reverse, reset, startSpeed, endSpeed, duration, ease }: {
-        layer: string;
-        clip: string;
-        blendMode?: BlendMode;
-        loopMode?: LoopMode;
-        stopMode?: StopMode;
-        fadeDuration?: number;
-        reverse?: boolean;
-        reset?: boolean;
-        startSpeed?: number;
-        endSpeed?: number;
-        duration?: number;
-        ease?: string;
-    }): void;
-    /** The method removes the existing `THREE.AmbientLight` from the scene and releases its resources. If no ambient light exists, the method exits without performing any action. */
-    removeAmbientLight(): void;
-    /** The method removes the existing `THREE.Fog` from the scene. If no fog exists, the method exits without performing any action. */
-    removeFog(): void;
-    /** The method removes the existing `THREE.HemisphereLight` from the scene and releases its resources. If no hemisphere light exists, the method exits without performing any action. */
-    removeHemisphereLight(): void;
-    /**
-     * Removes a previously registered frame update callback.
-     * @param {(deltaTime: number) => void} cb - Callback to remove.
-     */
-    removeOnFrameUpdate(cb: (deltaTime: number) => void): void;
-    /**
-     * The method creates or updates a Three.js `THREE.AmbientLight` instance in the scene.
-     *
-     * @param params - Parameter object for controlling the ambient light.
-     * @param params.color - The ambient light color. If omitted and the light already exists, the current color remains unchanged.
-     * @param params.intensity - The ambient light intensity. If omitted and the light already exists, the current intensity remains unchanged.
-     *
-     * @remarks
-     * The method does not apply any default values when creating the light. Creation is skipped unless both `color` and `intensity` are defined. When updating an existing light,
-     * the scene reflects changes automatically on the next render call.
-     */
-    setAmbientLight({ color, intensity }: {
-        color?: THREE_TYPE.ColorRepresentation;
-        intensity?: number;
-    }): void;
-    private setAnimationLoop;
-    /**
-     * The method creates or updates a Three.js `THREE.Fog` instance in the scene.
-     *
-     * @param params - Parameter object for controlling the fog.
-     * @param params.color - The fog color. If omitted and the fog already exists, the current color remains unchanged.
-     * @param params.near - The near distance where fog starts. If omitted and the fog already exists, the current near value remains unchanged.
-     * @param params.far - The far distance where fog ends. If omitted and the fog already exists, the current far value remains unchanged.
-     *
-     * @remarks
-     * The method does not apply any default values when creating the fog. Creation is skipped unless `color`, `near` and `far` are defined. When updating an existing fog, the scene reflects changes automatically
-     * on the next render call.
-     */
-    setFog({ color, near, far }: {
-        color?: THREE_TYPE.ColorRepresentation;
-        near?: number;
-        far?: number;
-    }): void;
-    /* Excluded from this release type: setFxaaResolution */
-    /**
-     * The method creates or updates a Three.js `THREE.HemisphereLight` instance in the scene.
-     *
-     * @param params - Parameter object for controlling the hemisphere light.
-     * @param params.skyColor - The sky light color. If omitted and the light already exists, the current sky color remains unchanged.
-     * @param params.groundColor - The ground light color. If omitted and the light already exists, the current ground color remains unchanged.
-     * @param params.intensity - The hemisphere light intensity. If omitted and the light already exists, the current intensity remains unchanged.
-     *
-     * @remarks
-     * The method does not apply any default values when creating the light. Creation is skipped unless `skyColor`, `groundColor` and `intensity` are defined. When updating an existing light, the scene
-     * reflects changes automatically on the next render call.
-     */
-    setHemisphereLight({ skyColor, groundColor, intensity }: {
-        skyColor?: THREE_TYPE.ColorRepresentation;
-        groundColor?: THREE_TYPE.ColorRepresentation;
-        intensity?: number;
-    }): void;
-    /**
-     * The method finds a Three.js mesh by name, validates that it has a material, and updates one or more of its material properties at runtime. It supports both numeric and color values as well as
-     * texture paths (`map`, `emissiveMap`), which are automatically loaded via `THREE.TextureLoader`.
-     *
-     * @param params - Parameter object for setting material properties.
-     * @param params.obj - The name of the mesh whose material properties should be modified.
-     * @param params.needsUpdate - Requests material recompilation after applying the properties. Default: **false**
-     *
-     * @remarks
-     * Additional properties of `params` can define one or more material fields to update (e.g. `color`, `roughness`, `metalness`, `map`, `emissiveMap`, ...), each with its target value. Texture paths provided
-     * as strings are loaded asynchronously and assigned to the corresponding material slots. Unsupported or mismatched property types are ignored with a warning in debug mode.
-     */
-    setMaterialProperties({ obj, needsUpdate, ...props }: {
-        obj: string;
-        needsUpdate?: boolean;
-        [key: string]: any;
-    }): void;
-    /* Excluded from this release type: setPostWebGl */
-    /* Excluded from this release type: setPostWebGpu */
-    /**
-     * The method finds a Three.js animation clip by name, validates that it exists within the loaded GLTF, and stops its playback via the `THREE.AnimationMixer`. It supports smooth fade-out transitions using
-     * GSAP before stopping the clip completely.
-     *
-     * @param params - Parameter object for controlling the stop behavior.
-     * @param params.clipName - The name of the animation clip to stop.
-     * @param params.fadeOut - The fade-out duration in seconds before stopping the clip. Default: **0**
-     * @param params.ease - The easing function name for the fade-out transition. Default: **'power1.inOut'**
-     *
-     * @remarks
-     * The method gradually reduces the clip's playback speed to zero when `fadeOut` is greater than zero. It emits `Clip_Speed_Start`, `Clip_Speed_Complete`, and finally `Clip_Cancel`.
-     * If no speed transition is specified, the clip is canceled immediately.
-     *
-     * **Events**
-     *
-     * {@link ClipEvent}
-     */
-    stopAnimClip({ clipName, fadeOut, ease }: {
-        clipName: string;
-        fadeOut?: number;
-        ease?: string;
-    }): void;
-    /** Toggles the browser fullscreen mode for the associated canvas element. */
-    toggleFullscreen(): void;
-    /**
-     * Registers and executes a low-level extension function with access to the public `Engine` API.
-     * @param extension - Function that receives the current `Engine` instance and can use its public members and methods.
-     * @remarks This method is intended for advanced custom integrations where developers need direct access to the engine instance. The extension is executed once immediately when `use()` is called.
-     */
-    use(extension: (engine: Engine) => void): void;
-    private update;
-    /** Updates the renderer, post-processing composer, and ground reflector to match the current canvas size. Ensures that the rendering resolution and reflection buffers remain consistent when the viewport changes. */
-    updateCanvasResize(): void;
-}
-
-/**
- * Controls `THREE.Scene.environment` and `THREE.Scene.background` textures, including environment lighting and optional rotation.
- * The first configured map is used for environment lighting and the initial background. Additional maps replace only the visible background after loading.
- * WebGL uses a PMREM-processed texture for environment lighting while keeping the loaded texture for the visible background.
- * @category Core
- */
-export declare class EnvCtrls {
-    private cfg;
-    private engine;
-    private modules;
-    /* Excluded from this release type: envReady */
-    /* Excluded from this release type: textReady */
-    /* Excluded from this release type: bgdReady */
-    private envEnabled;
-    private envInit;
-    private envLoadId;
-    private envIntensity;
-    private bgdIntensity;
-    private bgdBlurriness;
-    private rotation;
-    private rotationSpeed;
-    private envType;
-    private envMaps;
-    private envText;
-    private bgdText;
-    private callback;
-    private frameWaiters;
-    private timeBgdRot;
-    /* Excluded from this release type: __constructor */
-    /* Excluded from this release type: init */
-    private applyBgds;
-    private applyEnv;
-    private disposePrevBgd;
-    private disposeText;
-    /**
-     * Enables environment and background handling.
-     * The first map is applied to `THREE.Scene.environment` and `THREE.Scene.background`; additional maps load in order and replace only `THREE.Scene.background`.
-     * WebGL uses a PMREM-processed texture for `THREE.Scene.environment` and the loaded texture for `THREE.Scene.background`.
-     * @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`.
-     */
-    enable(params?: {
-        type: EnvCtrlsCfg["type"];
-        map: EnvCtrlsCfg["map"];
-    }): void;
-    /** Disables the environment system and resets all values. */
-    disable(): void;
-    /**
-     * Returns the current runtime environment control values.
-     * @returns A snapshot of the mutable runtime settings.
-     */
-    get(): Partial<EnvCtrlsCfg>;
-    /**
-     * Returns whether the environment system is currently enabled.
-     * @returns `true` if `EnvCtrls` is currently enabled, otherwise `false`.
+     * Checks whether an environment or background map is applied.
+     * @returns `true` when at least one map is applied.
      */
     isEnabled(): boolean;
     private loadText;
@@ -1127,7 +703,7 @@ export declare class EnvCtrls {
 }
 
 /**
- * Defines the environment controls settings for `THREE.Scene.environment` and `THREE.Scene.background`.
+ * Controls environment lighting and the visible background.
  * @category Cfg
  */
 export declare interface EnvCtrlsCfg {
@@ -1137,7 +713,7 @@ export declare interface EnvCtrlsCfg {
      */
     backgroundBlurriness: number;
     /**
-     * Attenuates the color of the background.
+     * Scales background brightness.
      * @default 0
      */
     backgroundIntensity: number;
@@ -1152,12 +728,12 @@ export declare interface EnvCtrlsCfg {
      */
     enable: boolean;
     /**
-     * Attenuates the color of the environment.
+     * Scales environment lighting intensity.
      * @default 1.8
      */
     environmentIntensity: number;
     /**
-     * Loads the EXR or HDR loader via dynamic import.
+     * Prepares environment map loading without enabling environment lighting.
      * @default false
      */
     load: boolean;
@@ -1178,7 +754,7 @@ export declare interface EnvCtrlsCfg {
         z: number;
     };
     /**
-     * Rotation speed of the environment and background map.
+     * Environment and background rotation speed in degrees per second.
      * @default 0
      */
     rotationSpeed: number;
@@ -1189,24 +765,13 @@ export declare interface EnvCtrlsCfg {
     type: 'hdr' | 'exr' | 'texture';
 }
 
-declare type EventByType<TEvent extends {
-    type: string;
-}, TType extends EventType<TEvent>> = Extract<TEvent, {
-    type: TType;
-}>;
-
-declare class EventDispatcher<TEvent extends {
-    type: string;
-}> {
-    private readonly listeners;
-    addEventListener<TType extends EventType<TEvent>>(type: TType, listener: Listener<EventByType<TEvent, TType>>): Unsubscribe;
-    removeEventListener<TType extends EventType<TEvent>>(type: TType, listener: Listener<EventByType<TEvent, TType>>): void;
-    emit(event: TEvent): void;
-    listenerCount<TType extends EventType<TEvent>>(type: TType): number;
+/** @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 {
+    type: 'Env_Loaded';
 }
 
 /**
- * Internal event dispatcher for the engine.
+ * Sends application and engine events to the state machine.
  * @category Core
  */
 export declare class Events {
@@ -1214,39 +779,24 @@ export declare class Events {
     private stateMachine;
     private eventQueue;
     private isProcessingEvents;
-    /* Excluded from this release type: __constructor */
-    /** A nested snapshot.can() is only evaluated after the current event callback has completed. */
     private enqueue;
-    /* Excluded from this release type: anim */
-    /* Excluded from this release type: animFade */
-    /* Excluded from this release type: audioLoaded */
-    /* Excluded from this release type: clip */
-    /* Excluded from this release type: modelError */
-    /* Excluded from this release type: modelLoaded */
-    /* Excluded from this release type: modelLoading */
-    /* Excluded from this release type: sceneRendered */
     /**
      * Sends an event to the state machine and optionally logs a debug message to the console.
-     * @param event - Any XState event object (must include a `type` property) to be dispatched to the actor.
+     * @param event - Event to send to the state machine.
      * @param log - Information to log with the event.
      */
     send(event: AnyEventObject, log?: string): void;
-    /* Excluded from this release type: windowResize */
 }
 
-declare type EventType<TEvent extends {
-    type: string;
-}> = TEvent['type'];
-
 /**
- * Defines how an animation action behaves after its final loop.
- * - 'hold': Keeps the action enabled and holds its final pose.
- * - 'fadeOut': Fades the action out using fadeDurationFinish, or disables it immediately when the duration is 0.
+ * Controls what happens after the final animation loop.
+ * - `'hold'`: Keeps the action enabled and holds its final pose.
+ * - `'fadeOut'`: Fades out over `fadeDurationFinish` seconds, or stops immediately when the duration is `0`.
  */
 export declare type FinishMode = 'hold' | 'fadeOut';
 
 /**
- * Defines the fog settings controlling scene depth-based color attenuation.
+ * Blends distant objects into the fog color.
  * @category Cfg
  */
 export declare interface FogCfg {
@@ -1273,7 +823,7 @@ export declare interface FogCfg {
 }
 
 /**
- * This class integrates three.js PointerLockControls directly in the engine's render loop, supporting runtime updates and dynamic enabling/disabling.
+ * Controls first-person camera movement and pointer look.
  * @category Core
  */
 export declare class FpvCtrls {
@@ -1282,7 +832,6 @@ export declare class FpvCtrls {
     private readonly engine;
     private readonly events;
     private readonly modules;
-    /* Excluded from this release type: pointerLockCtrls */
     private readonly params;
     private isMoveForward;
     private isMoveLeft;
@@ -1294,25 +843,37 @@ export declare class FpvCtrls {
     private readonly onClick;
     private readonly onKeyDown;
     private readonly onKeyUp;
-    /* Excluded from this release type: __constructor */
-    /** Creates three.js `PointerLockControls`. */
+    /**
+     * Prepares pointer-look controls without enabling them.
+     */
     create(): void;
-    /** Disables three.js `PointerLockControls`. */
+    /**
+     * Stops first-person movement and releases pointer lock.
+     */
     disable(): void;
-    /** Enables three.js `PointerLockControls` for the current camera. */
+    /**
+     * Enables first-person movement and pointer-look interaction.
+     */
     enable(): void;
-    /** Disposes three.js `PointerLockControls` and cleans up their runtime resources. */
+    /**
+     * Releases pointer-look controls and their event listeners.
+     */
     dispose(): void;
     /**
-     * Returns the parameters currently used by three.js `PointerLockControls`.
-     * @returns A snapshot of the mutable first-person control settings.
+     * Returns a snapshot of the current first-person control settings.
      */
     get(): Partial<FpvCtrlsCfg>;
-    /** Returns whether three.js `PointerLockControls` are enabled. */
+    /**
+     * Checks whether first-person controls are enabled.
+     */
     isEnabled(): boolean;
-    /** Returns whether three.js `PointerLockControls` are currently locked. */
+    /**
+     * Checks whether pointer lock is active.
+     */
     isLocked(): boolean;
-    /** Locks three.js `PointerLockControls` and starts pointer-look interaction. */
+    /**
+     * Requests pointer lock to control the viewing direction.
+     */
     lock(): void;
     /**
      * Moves the controlled camera forward.
@@ -1330,25 +891,25 @@ export declare class FpvCtrls {
      */
     moveUp(distance: number): void;
     /**
-     * Updates one or more three.js `PointerLockControls` properties. `FpvCtrls` must be enabled.
-     * @param params - Object containing any subset of first-person control parameters.
+     * Updates first-person movement and pointer-look settings. Controls must already be created.
+     * @param params - Settings to change; omitted values remain unchanged.
      */
     set(params: Partial<FpvCtrlsCfg>): void;
-    /** Unlocks three.js `PointerLockControls` and stops pointer-look interaction. */
+    /**
+     * Releases pointer lock and stops pointer-look interaction.
+     */
     unlock(): void;
     /**
-     * Registers and executes a low-level extension function with access to the public `FpvCtrls` API.
+     * Runs an extension callback immediately with access to the public API.
      *
-     * @param extension - Function that receives the current `FpvCtrls` instance and can use its public members and methods.
+     * @param extension - Callback receiving this `FpvCtrls` instance.
      *
-     * @remarks
-     * This method is intended for advanced custom integrations where developers need direct access to the FpvCtrls instance. The extension is executed once immediately when `use()` is called.
      */
     use(extension: (fpvctrls: FpvCtrls) => void): void;
 }
 
 /**
- * Defines the First Person View Controls settings used to move and rotate the camera inside a scene.
+ * Controls first-person camera movement and pointer look.
  * @category Cfg
  */
 export declare interface FpvCtrlsCfg {
@@ -1358,7 +919,7 @@ export declare interface FpvCtrlsCfg {
      */
     enable: boolean;
     /**
-     * Loads First Person View Controls via dynamic import.
+     * Prepares first-person controls without enabling them.
      * @default false
      */
     load: boolean;
@@ -1409,14 +970,13 @@ export declare interface FpvCtrlsCfg {
     keyMoveDown: string;
 }
 
-/** @event Fired when an `FpvCtrls` event occurs and triggers the corresponding XState event. */
+/** @event Fired when first-person controls are enabled, disabled, disposed, locked, or unlocked. */
 export declare interface FpvCtrlsEvent {
-    /** Identifies this event type. */
     type: 'FpvCtrls_Disabled' | 'FpvCtrls_Disposed' | 'FpvCtrls_Enabled' | 'FpvCtrls_Lock' | 'FpvCtrls_Unlock';
 }
 
 /**
- * Defines the FXAA anti-aliasing settings used to smooth jagged edges in the rendered image.
+ * Controls edge smoothing with FXAA.
  * @category Cfg
  */
 export declare interface FxaaCfg {
@@ -1427,29 +987,59 @@ export declare interface FxaaCfg {
     sharpness: number;
 }
 
-declare type FXAAPostNode = (input: ColorNode) => ColorNode;
+/**
+ * Controls contact shading with GTAO.
+ * @category Cfg
+ */
+export declare interface GtaoCfg {
+    /**
+     * Ambient occlusion radius in world units.
+     * @default 0.25
+     */
+    radius: number;
+    /**
+     * Assumed surface thickness for ambient occlusion.
+     * @default 1
+     */
+    thickness: number;
+    /**
+     * Scales the strength of the ambient occlusion.
+     * @default 1
+     */
+    scale: number;
+    /**
+     * Sample count for ambient occlusion; higher values increase GPU work.
+     * @default 16
+     */
+    samples: number;
+    /**
+     * Resolution scale for ambient occlusion.
+     * @default 1
+     */
+    resolutionScale: number;
+}
 
 /**
- * Defines the GUI elements for runtime information, controls and inspection.
+ * Controls runtime statistics, the Inspector, and the Menu Bar.
  * @category Cfg
  */
 export declare interface GuiCfg {
-    /** The infobox for runtime statistics and renderer information. */
+    /** Runtime statistics and renderer information. */
     infoBox: InfoBoxCfg;
-    /** The inspector for runtime properties. */
+    /** Runtime Inspector settings. */
     inspector: {
         /**
-         * Activates the inspector for runtime property control via lazy loading.
+         * Enables the Inspector for tuning runtime settings.
          * @default false
          */
         enable: boolean;
     };
-    /** The menubar at the bottom. */
+    /** Menu Bar settings. */
     menuBar: MenuBarCfg;
 }
 
 /**
- * Defines the hemisphere light settings controlling ambient sky and ground illumination.
+ * Controls ambient lighting from the sky and ground.
  * @category Cfg
  */
 export declare interface HemisphereCfg {
@@ -1475,21 +1065,13 @@ export declare interface HemisphereCfg {
     intensity: number;
 }
 
-declare interface ImageTexture {
-    name: string;
-    material: THREE_TYPE.MeshBasicMaterial | THREE_TYPE.MeshStandardMaterial;
-    slot: TextureSlot;
-    lightMapIntensity: number;
-    channel: number;
-}
-
 /**
- * Defines the built-in engine infobox settings used to display FPS, CPU/frame timing and renderer.info values.
+ * Selects runtime statistics shown in the Info Bar.
  * @category Cfg
  */
 export declare interface InfoBoxCfg {
     /**
-     * Enables or disables infobox data collection.
+     * Displays the Info Bar and collects runtime statistics.
      * @default false
      */
     enable: boolean;
@@ -1509,76 +1091,72 @@ export declare interface InfoBoxCfg {
      */
     frame: boolean;
     /**
-     * Shows renderer.info.render.calls.
+     * Shows the number of draw calls.
      * @default true
      */
     calls: boolean;
     /**
-     * Shows renderer.info.render.triangles.
+     * Shows the number of rendered triangles.
      * @default true
      */
     triangles: boolean;
     /**
-     * Shows renderer.info.render.lines.
+     * Shows the number of rendered lines.
      * @default true
      */
     lines: boolean;
     /**
-     * Shows renderer.info.render.points.
+     * Shows the number of rendered points.
      * @default true
      */
     points: boolean;
     /**
-     * Shows renderer.info.memory.geometries.
+     * Shows the number of allocated geometries.
      * @default true
      */
     geometries: boolean;
     /**
-     * Shows renderer.info.memory.textures.
+     * Shows the number of allocated textures.
      * @default true
      */
     textures: boolean;
     /**
-     * Shows the number of compiled WebGL programs from renderer.info.programs.
+     * Shows the number of compiled WebGL shader programs.
      * @default true
      */
     programs: boolean;
     /**
-     * Refresh rate of the displayed values.
+     * Number of display updates per second.
      * @default 10
      */
     logsPerSecond: number;
 }
 
-/* Excluded from this release type: Lib */
-
 /**
- * The `Light3D` class represents a managed light source.
- * @category 3D Objects
+ * Connects a light to the scene component lifecycle.
+ * @category Scene Components
  */
 export declare class Light3D extends Obj3D {
     /**
-     * The underlying `THREE.Light` object that defines illumination parameters and behavior. It can be replaced to represent various light types such as point, directional, or spot lights.
+     * Light used by this component. Replace it to use another light type.
      * @default `THREE.PointLight`
      * @public
      */
     obj: THREE_TYPE.Light;
-    /* Excluded from this release type: __constructor */
     /**
-     * Called for each traversed light during `.gltf` parsing. Stores the current `THREE.Light` in `this.obj`.
+     * Called when a matching GLTF light is found. Adopts the light for this component.
      *
      * @param objGltf - The currently traversed `THREE.Light`.
      * @public
      *
      * **Example**
-     * {@includeCode ../../examples/light3D-spot.ts}
+     * {@includeCode ../../../../apps-doc/examples/light3d-spot.ts}
      */
     protected onTraverse(objGltf: THREE_TYPE.Light): void;
-    /* Excluded from this release type: traverse */
 }
 
 /**
- * Defines the light shadow settings used to configure shadow map resolution and shadow camera limits.
+ * Controls light shadows and area-light support.
  * @category Cfg
  */
 export declare interface LightCfg {
@@ -1588,7 +1166,7 @@ export declare interface LightCfg {
      */
     castShadow: boolean;
     /**
-     * Loads and initializes the renderer-specific LTC data required by RectAreaLight.
+     * Enables rectangular area-light support.
      * @default false
      */
     rectArea: boolean;
@@ -1624,17 +1202,15 @@ export declare interface LightCfg {
     far: number;
 }
 
-declare type Listener<TEvent> = (event: TEvent) => void;
-
 /**
- * Defines how often an animation action is played.
- * - number: Plays the action the specified positive number of times.
- * - 'infinite': Repeats the action indefinitely.
+ * Controls how often an animation plays.
+ * - A positive number: Plays the action the specified positive number of times.
+ * - `'infinite'`: Repeats the action indefinitely.
  */
 export declare type LoopMode = number | 'infinite';
 
 /**
- * Defines the menu bar settings used to display licensed UI controls and branding.
+ * Controls the Menu Bar appearance and availability.
  * @category Cfg
  */
 export declare interface MenuBarCfg {
@@ -1656,22 +1232,20 @@ export declare interface MenuBarCfg {
 }
 
 /**
- * Manages 3D meshes in illutions. Wraps a `THREE.Mesh` and provides support for scene integration and optional screen-space reflection (SSR) features.
- * @category 3D Objects
+ * Controls a mesh, its materials, and optional screen-space reflections.
+ * @category Scene Components
  */
 export declare class Mesh3D extends Obj3D {
     /**
-     * The underlying `THREE.Mesh` used for rendering. It can be replaced with a custom mesh that uses different geometry or material settings.
+     * Mesh rendered by this component. Replace it to use custom geometry or materials.
      * @default `THREE.BoxGeometry`, `THREE.MeshPhysicalMaterial`
      */
     obj: THREE_TYPE.Mesh;
     /** `ReflectorForSSRPass` surface used for screen-space reflections (SSR). When set, it renders dynamic reflections on a ground plane. */
     groundReflector: ReflectorForSSRPass | null;
-    /** Objects that participate in the screen-space reflection (SSR) effect. These objects are used for reflective rendering in the scene. */
+    /** Objects selected for WebGL screen-space reflections. */
     reflectivesSSR: THREE_TYPE.Object3D[];
     private model;
-    /* Excluded from this release type: lib */
-    /* Excluded from this release type: __constructor */
     /**
      * Animates one or more color properties of this mesh's material.
      * @param params - Animation parameters and target material color properties such as `color` or `emissive`.
@@ -1702,47 +1276,42 @@ export declare class Mesh3D extends Obj3D {
         [key: string]: any;
     }): void;
     /**
-     * Updates one or more material properties of this mesh.
-     * @param properties - Material properties to update. Texture paths are supported for `map` and `emissiveMap`.
-     * @param properties.needsUpdate - Requests material recompilation after applying the properties. Default: **false**
-     */
-    setMaterialProperties({ needsUpdate, ...properties }: {
-        needsUpdate?: boolean;
-        [key: string]: any;
-    }): void;
-    /**
-     * Loads an unused texture embedded in the current GLTF and assigns it to a material.
-     * @param options - Unused texture assignment settings.
-     * @param options.name - Name of the GLTF image used by the texture.
-     * @param options.material - Material that receives the unused texture.
-     * @param options.slot - Target material texture slot. See {@link TextureSlot}.
-     * @param options.lightMapIntensity - Light map intensity used for `LightMap`. Default: **1**
-     * @param options.channel - Texture UV channel. Default: **1**
+     * Returns an image texture requested from an unused GLTF image.
+     * @param name - GLTF image name passed to {@link requestImageTexture} during `onStart()`.
+     * @returns The initialized texture shared across progressive model levels.
      * @public
      */
-    protected setTexture({ name, material, slot, lightMapIntensity, channel }: {
-        name: string;
-        material: THREE_TYPE.MeshBasicMaterial | THREE_TYPE.MeshStandardMaterial;
-        slot: TextureSlot;
-        lightMapIntensity?: number;
-        channel?: number;
-    }): void;
+    protected getImageTexture(name: string): THREE_TYPE.Texture;
     /**
-     * Called for each traversed mesh during GLTF parsing. Stores the current `THREE.Mesh` in `this.obj`.
+     * Called when a matching GLTF mesh is found. Adopts the mesh for this component.
      * @param objGltf - The currently traversed mesh.
      * @public
      *
      * **Example**
-     * {@includeCode ../../examples/mesh3D-cube.ts}
+     * {@includeCode ../../../../apps-doc/examples/mesh3d-cube.ts}
      */
     protected onTraverse(objGltf: THREE_TYPE.Mesh): void;
-    /* Excluded from this release type: setModel */
-    /* Excluded from this release type: setReflectivesSSR */
-    /* Excluded from this release type: traverse */
+    /**
+     * Requests a Three.js texture from an unused GLTF image for initialization before the model is traversed. Call this method from `onStart()` for every unused image that will be accessed later.
+     * @param name - Name of the GLTF image.
+     * @public
+     */
+    protected requestImageTexture(name: string): void;
+    /**
+     * Updates one or more properties across all material slots of this mesh. Shared materials are modified in place.
+     * @param properties - Material properties to update. Texture paths are supported for `map` and `emissiveMap`.
+     * @param properties.recursive - Includes all descendant meshes when true. Default: **false**
+     * @param properties.needsUpdate - Requests material recompilation after applying the properties. Default: **false**
+     */
+    setMaterialProps({ recursive, needsUpdate, ...properties }: {
+        recursive?: boolean;
+        needsUpdate?: boolean;
+        [key: string]: any;
+    }): void;
 }
 
 /**
- * Defines the mesh-specific rendering settings used to control shadows and frustum culling.
+ * Controls shadows and visibility culling for imported meshes.
  * @category Cfg
  */
 export declare interface MeshCfg {
@@ -1763,46 +1332,8 @@ export declare interface MeshCfg {
     frustumCulled: boolean;
 }
 
-declare class Model {
-    private readonly canvas;
-    private readonly cfg;
-    private readonly events;
-    private readonly modules;
-    private readonly renderer;
-    private readonly initFirstScene;
-    private readonly reportModelReady;
-    private readonly rendererReady;
-    private readonly waitForRender;
-    /* Excluded from this release type: sceneReady */
-    private resolveSceneReady;
-    private rejectSceneReady;
-    private gltf;
-    private meshes;
-    private scene;
-    private readonly imageTextures;
-    private readonly imageTextureInits;
-    private readonly textures;
-    constructor({ canvas, cfg, events, modules, renderer, rendererReady, initFirstScene, reportModelReady, waitForRender }: ModelParams);
-    private addMaterialsFromMesh;
-    private addTexturesFromMaterial;
-    private addTexture;
-    private applyImageTexturesToMaterials;
-    private disposeGeometries;
-    private disposeSourceMaterials;
-    private initImageTexture;
-    private initImageTextures;
-    private initTextures;
-    /* Excluded from this release type: load */
-    private loadGltf;
-    private prepareImageTextures;
-    /* Excluded from this release type: prepareImageTextureForMaterial */
-    private reportError;
-    private updateGeometries;
-    private updateTextureImages;
-}
-
 /**
- * Defines the GLTF/GLB model loading settings used to fetch models and configure optional Draco decoding.
+ * Controls progressive GLTF/GLB loading and compression support.
  * @category Cfg
  */
 export declare interface ModelCfg {
@@ -1819,7 +1350,7 @@ export declare interface ModelCfg {
         texture: 'none' | 'webp' | 'ktx2';
     };
     /**
-     * An ordered list of non-empty, progressively higher-quality GLTF/GLB scene paths. The first file initializes the scene, subsequent files replace matching mesh geometries and textured materials in order.
+     * GLTF/GLB paths ordered from low to high quality. The first file initializes the scene; later files replace matching geometry and textured materials.
      * @default []
      */
     file: string[];
@@ -1835,9 +1366,8 @@ export declare interface ModelCfg {
     progressBar: boolean;
 }
 
-/** @event Fired when an error occurs while loading model assets and triggers the corresponding XState event. */
+/** @event Fired when model loading fails. */
 export declare interface ModelErrorEvent {
-    /** Identifies this event type. */
     type: 'Model_Error';
     /** The caught error object. */
     error: Error;
@@ -1849,7 +1379,7 @@ export declare interface ModelLoadedEvent {
     type: 'Model_Loaded' | `Model${number}_Loaded`;
 }
 
-/** @event Fired while model assets are loading and triggers the corresponding XState event. */
+/** @event Fired as model loading progresses. */
 export declare interface ModelLoadingEvent {
     /** Identifies the loading model. */
     type: 'Model_Loading' | `Model${number}_Loading`;
@@ -1857,124 +1387,43 @@ export declare interface ModelLoadingEvent {
     loading: number;
 }
 
-declare interface ModelParams {
-    canvas: HTMLElement;
-    cfg: Cfg;
-    events: Events;
-    modules: Modules;
-    renderer: Renderer_2;
-    rendererReady: Promise<void> | null;
-    initFirstScene: (gltf: GLTF) => Map<string, THREE_TYPE.Mesh>;
-    reportModelReady: () => void;
-    waitForRender: () => Promise<void>;
-}
-
-/** @event Fired after the final progressive model variant has been applied and rendered and triggers the corresponding XState event. */
+/** @event Fired after the final progressive model has been applied and rendered. */
 export declare interface ModelReadyEvent {
-    /** Identifies this event type. */
     type: 'Model_Ready';
 }
 
-declare class Modules {
-    gpuTier: TierResult | null;
-    fxaaNode: FXAAPostNode | null;
-    fxaaShader: typeof FXAAShader | null;
-    smaaPassClass: typeof SMAAPass | null;
-    smaaNode: typeof smaa | null;
-    traaNode: typeof traa | null;
-    ssaoPassClass: typeof SSAOPass | null;
-    gtaoNodeClass: typeof ao | null;
-    ssrNode: typeof ssr | null;
-    ssrPassClass: typeof SSRPass | null;
-    paneClass: typeof Pane | null;
-    createBrowserInspector: typeof createBrowserInspector | null;
-    effectComposerClass: typeof EffectComposer | null;
-    envLoader: EXRLoader | HDRLoader | null;
-    dracoLoader: DRACOLoader | null;
-    gltfLoader: GLTFLoader | null;
-    ktx2Loader: KTX2Loader | null;
-    meshoptDecoder: typeof MeshoptDecoder | null;
-    outputPassClass: typeof OutputPass | null;
-    renderPassClass: typeof RenderPass | null;
-    shaderPassClass: typeof ShaderPass | null;
-    rectAreaLightNodeClass: typeof THREE_WEBGPU_TYPE.RectAreaLightNode | null;
-    rectAreaLightTexturesLib: typeof RectAreaLightTexturesLib | null;
-    rectAreaLightUniformsLib: typeof RectAreaLightUniformsLib | null;
-    orbitControlsClass: typeof OrbitControls | null;
-    pointerLockControlsClass: typeof PointerLockControls | null;
-    webGpuRendererClass: typeof THREE_WEBGPU_TYPE.WebGPURenderer | null;
-    renderPipelineClass: typeof THREE_WEBGPU_TYPE.RenderPipeline | null;
-    tslPass: typeof THREE_WEBTSL_TYPE.pass | null;
-    tslMrt: typeof THREE_WEBTSL_TYPE.mrt | null;
-    tslOutput: typeof THREE_WEBTSL_TYPE.output | null;
-    tslVelocity: typeof THREE_WEBTSL_TYPE.velocity | null;
-    tslRenderOutput: typeof THREE_WEBTSL_TYPE.renderOutput | null;
-    tslNormalView: typeof THREE_WEBTSL_TYPE.normalView | null;
-    tslMetalness: typeof THREE_WEBTSL_TYPE.metalness | null;
-    tslRoughness: typeof THREE_WEBTSL_TYPE.roughness | null;
-    tslSample: typeof THREE_WEBTSL_TYPE.sample | null;
-    tslVec2: typeof THREE_WEBTSL_TYPE.vec2 | null;
-    tslVec3: typeof THREE_WEBTSL_TYPE.vec3 | null;
-    tslVec4: typeof THREE_WEBTSL_TYPE.vec4 | null;
-    tslFloat: typeof THREE_WEBTSL_TYPE.float | null;
-    packNormalToRGB: typeof THREE_WEBTSL_TYPE.packNormalToRGB | null;
-    unpackRGBToNormal: typeof THREE_WEBTSL_TYPE.unpackRGBToNormal | null;
-    private cfg;
-    constructor(cfg: Cfg);
-    private consoleLog;
-    importDracoLoader(): Promise<void>;
-    importEffectComposer(): Promise<void>;
-    importENVLoader(): Promise<void>;
-    importFpvCtrls(): Promise<void>;
-    importFXAANode(aaMode: Cfg['post']['aa']['mode']): Promise<void>;
-    importFXAAShader(aaMode: Cfg['post']['aa']['mode']): Promise<void>;
-    importGLTFLoader(): Promise<void>;
-    importGpuDetect(): Promise<void>;
-    importGtaoNode(enable: boolean): Promise<void>;
-    importKTX2Loader(): Promise<void>;
-    importMeshoptDecoder(): Promise<void>;
-    importOrbitCtrls(): Promise<void>;
-    importOutputPass(): Promise<void>;
-    importRectAreaLight(webGpu: boolean): Promise<void>;
-    importRenderPass(): Promise<void>;
-    importSMAANode(aaMode: Cfg['post']['aa']['mode']): Promise<void>;
-    importSMAAPass(aaMode: Cfg['post']['aa']['mode']): Promise<void>;
-    importSSAOPass(enable: boolean): Promise<void>;
-    importSsrNode(enable: boolean): Promise<void>;
-    importSsrPass(enable: boolean): Promise<void>;
-    importStatelyAi(): Promise<void>;
-    importThreeTsl(): Promise<void>;
-    importThreeWebGpu(): Promise<void>;
-    importTRAANode(aaMode: Cfg['post']['aa']['mode']): Promise<void>;
-    importTweakpane(): Promise<void>;
-}
+/**
+ * Controls where multisample anti-aliasing smooths edges.
+ *
+ * - `'none'`: Disables MSAA.
+ * - `'render'`: Applies MSAA only while rendering the scene.
+ * - `'post'`: Also applies MSAA to supported post-processing scene targets.
+ */
+export declare type MsaaMode = 'none' | 'render' | 'post';
 
 /**
  * Wraps a `THREE.Object3D` and provides lifecycle hooks, scene integration, animation support, and position-, rotation- and visibility-change events. Extend this class to implement custom object behavior.
- * @category 3D Objects
+ * @category Scene Components
  */
 export declare class Obj3D {
     /** @public */
     protected canvas: HTMLElement;
     protected cfg: Cfg;
-    /* Excluded from this release type: events */
     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;
-    /** @public */
+    /** Contains all Scene Components registered through `comps.scene`, keyed by registration name. */
     protected objs3D: Map<string, Obj3D> | null;
-    /* Excluded from this release type: raycast */
     /**
-     * The active Three.js renderer used by this object. It is exposed for advanced use cases that require renderer-dependent Three.js APIs, such as reading the canvas size, pixel ratio, drawing buffer size, or updating renderer-based helper objects like cube cameras.
+     * Active renderer for custom rendering integrations.
      * @public
      */
     protected renderer: Readonly<THREE_TYPE.WebGLRenderer> | Readonly<THREE_WEBGPU_TYPE.WebGPURenderer>;
     /**
-     * The `THREE.Scene` instance this object belongs to.
+     * The Illutions scene this component belongs to. Use `scene.obj` for direct Three.js scene access.
      * @public
      */
-    protected scene: Readonly<THREE_TYPE.Scene>;
-    /* Excluded from this release type: eventDispatcher */
+    scene: Scene;
     private posNdc;
     private posScreen;
     private posScreenLast;
@@ -1987,13 +1436,14 @@ export declare class Obj3D {
     private quatWorldLast;
     private rotWorld;
     private visible;
-    private visibleFrustum;
-    private visibleFrustumLast;
+    private inFrustum;
+    private inFrustumLast;
     private visibleLast;
-    private visibleOccl;
-    /* Excluded from this release type: __constructor */
+    private occluded;
+    private objHidden;
+    private visibleBeforeHidden;
     /**
-     * Registers a listener that is called whenever the specified event occurs.
+     * Subscribes to an object event.
      * @param type - The event type to listen for.
      * @param listener - Callback invoked when the event occurs.
      * @returns A function that unsubscribes the listener.
@@ -2003,11 +1453,9 @@ export declare class Obj3D {
     }>) => void): Unsubscribe;
     private calcFrustumVisibility;
     private calcPosScreen;
-    /* Excluded from this release type: calcPosWorld */
     private calcPosOccl;
     private calcRotWorld;
     private calcVisibility;
-    /* Excluded from this release type: emitEvent */
     /**
      * Returns the object's screen position in canvas coordinates.
      * @param cam3D - Camera used for projection to canvas coordinates.
@@ -2017,19 +1465,18 @@ export declare class Obj3D {
         x: number;
         y: number;
     } | null;
-    /* Excluded from this release type: hasEventListener */
     /**
-     * Called once after the `THREE.Scene`, the `THREE.WebGLRenderer` or `THREE.WebGPURenderer`, the `EnvCtrls` are initialized and an existing GLTF model has been loaded and traversed.
+     * Called once when the scene, renderer, and initial environment are ready and, if configured, the first model has been loaded and traversed.
      * @public
      */
     protected onReady(): void;
     /**
-     * Called once after the `THREE.Scene` is initialized, before an existing GLTF model is loaded.
+     * Called once after the scene is initialized, before model loading begins.
      * @public
      */
     protected onStart(): void;
     /**
-     * Called once for each traversed child during GLTF parsing. Stores the currently traversed `THREE.Object3D` instance in `this.obj`.
+     * Called for each matching object found during GLTF traversal. Adopts the object for this component.
      * @param objGltf - The traversed `THREE.Object3D` instance.
      * @public
      */
@@ -2040,9 +1487,8 @@ export declare class Obj3D {
      * @public
      */
     protected onUpdate(deltaTime: number): void;
-    /* Excluded from this release type: ready */
     /**
-     * Removes a previously registered listener for the specified event.
+     * Unsubscribes a listener from an object event.
      * @param type - The event type to remove the listener from.
      * @param listener - Callback to remove from the event listeners.
      */
@@ -2050,37 +1496,26 @@ export declare class Obj3D {
         type: TType;
     }>) => void): void;
     private resetEventState;
-    /* Excluded from this release type: start */
-    /* Excluded from this release type: traverse */
-    /* Excluded from this release type: update */
 }
 
-/** Constructor type for `Obj3D` classes. */
-export declare type Obj3DClass = new (canvas: HTMLElement, cfg: Cfg, name: string) => Objs3D;
-
-/** Defines all event types supported by `Obj3D.addEventListener`. */
+/** Object events available to registered listeners. */
 export declare type Obj3DEvent = Obj3DPosWorldEvent | Obj3DPosScreenEvent | Obj3DRotWorldEvent | Obj3DFrustumEvent | Obj3DVisibleEvent | Obj3DPointerEvent;
 
 /** @event Fired when the frustum visibility of a 3D object changes. */
 export declare interface Obj3DFrustumEvent {
-    /** Identifies this event type. */
     type: 'Obj3D_Frustum_Changed';
     /** Whether the object's world position is inside the camera frustum. */
     visibleFrustum: boolean;
 }
 
-/**
- * Maps a record of Obj3D classes to a record of typed object instances.
- * `{ key1: typeof Obj3D1 } -> { key1: Obj3D1 }`
- * @hidden
- */
-export declare type Obj3DInsts<T extends Record<string, Obj3DClass>> = {
-    [K in keyof T]: InstanceType<T[K]>;
-};
+/** Initial parameters shared by all `Obj3D` classes. */
+export declare interface Obj3DParams {
+    /** Hides the underlying Three.js object from rendering without disabling raycasting. */
+    hidden?: boolean;
+}
 
-/** @event Fired when the user uses the pointer on an active object and triggers the corresponding XState event. */
+/** @event Fired when the pointer interacts with a pickable object. */
 export declare interface Obj3DPointerEvent {
-    /** Identifies this event type. */
     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;
@@ -2092,7 +1527,6 @@ export declare interface Obj3DPointerEvent {
  * @event Fired when the screen position of a 3D object changes.
  */
 export declare interface Obj3DPosScreenEvent {
-    /** Identifies this event type. */
     type: 'Obj3D_Pos_Screen_Changed';
     /** The object's position projected into screen space. */
     posScreen: THREE_TYPE.Vector2;
@@ -2102,7 +1536,6 @@ export declare interface Obj3DPosScreenEvent {
  * @event Fired when the world position of a 3D object changes.
  */
 export declare interface Obj3DPosWorldEvent {
-    /** Identifies this event type. */
     type: 'Obj3D_Pos_World_Changed';
     /** The object's position in world coordinates. */
     posWorld: THREE_TYPE.Vector3;
@@ -2112,30 +1545,22 @@ export declare interface Obj3DPosWorldEvent {
  * @event Fired when the world rotation of a 3D object changes.
  */
 export declare interface Obj3DRotWorldEvent {
-    /** Identifies this event type. */
     type: 'Obj3D_Rot_World_Changed';
     /** The object's rotation in world coordinates. */
     rotWorld: THREE_TYPE.Euler;
 }
 
-/** @event Fired when the combined frustum and occlusion visibility of a 3D object changes and triggers the corresponding XState event. */
+/** @event Fired when an object's combined hidden, frustum, and occlusion visibility changes. */
 export declare interface Obj3DVisibleEvent {
-    /** Identifies this event type. */
     type: 'Obj3D_Visible_Changed';
-    /** Whether the object is inside the camera frustum and not occluded. */
+    /** Whether the object is not hidden, is inside the camera frustum, and is not occluded. */
     visible: boolean;
 }
 
 export declare type Objs3D = Cam3D | Light3D | Mesh3D | Obj3D;
 
-declare interface OccludeeState {
-    obj: THREE_TYPE.Object3D;
-    needsCheck: boolean;
-    visible: boolean;
-}
-
 /**
- * Integrates three.js OrbitControls directly in the engine's render loop, supporting runtime updates and dynamic enabling/disabling.
+ * Controls camera orbit, panning, and zooming around a target.
  * @category Core
  */
 export declare class OrbitCtrls {
@@ -2144,49 +1569,52 @@ export declare class OrbitCtrls {
     private readonly engine;
     private readonly events;
     private readonly modules;
-    orbitControls: OrbitControls_2 | null;
+    orbitControls: OrbitControls | null;
     private readonly params;
     private orbitCtrlsFirstChange;
     private callback;
     private readonly touchPointerIds;
-    /* Excluded from this release type: __constructor */
-    /** Creates three.js `OrbitControls`. */
+    /**
+     * Prepares orbit controls without enabling them.
+     */
     create(): void;
-    /** Disables three.js `OrbitControls` and cleans up the event listeners. */
+    /**
+     * Stops orbit interaction and automatic camera updates.
+     */
     disable(): void;
-    /** Enables three.js `OrbitControls` for the current camera. */
+    /**
+     * Enables camera orbit, panning, and zooming.
+     */
     enable(): void;
-    /** Disposes three.js `OrbitControls` and removes them from the render loop. */
+    /**
+     * Releases orbit controls and stops their camera updates.
+     */
     dispose(): void;
     /**
-     * Returns the parameters currently used by three.js `OrbitControls`.
-     * @returns A snapshot of the mutable orbit control settings.
+     * Returns a snapshot of the current orbit control settings.
      */
     get(): Partial<OrbitCtrlsCfg>;
     /**
-     * Returns whether three.js `OrbitControls` are currently enabled.
-     * @returns `true` if `OrbitControls` are currently enabled; otherwise, `false`.
+     * Checks whether orbit controls are enabled.
      */
     isEnabled(): boolean;
     /**
-     * Updates one or more three.js `OrbitControls` properties. `OrbitCtrls` must be enabled.
-     * @param params - Object containing any subset of orbit control parameters.
+     * Updates orbit, panning, and zoom settings. Controls must already be created.
+     * @param params - Settings to change; omitted values remain unchanged.
      */
     set(params: Partial<OrbitCtrlsCfg>): void;
     /**
-     * Registers and executes a low-level extension function with access to the public `OrbitCtrls` API.
+     * Runs an extension callback immediately with access to the public API.
      *
-     * @param extension - Function that receives the current `OrbitCtrls` instance and can use its public members and methods.
+     * @param extension - Callback receiving this `OrbitCtrls` instance.
      *
-     * @remarks
-     * This method is intended for advanced custom integrations where developers need direct access to the engine instance.
      * The extension is executed once immediately when `use()` is called.
      */
     use(extension: (orbitCtrls: OrbitCtrls) => void): void;
 }
 
 /**
- * Defines the Orbit Controls settings used to rotate, pan, zoom and constrain the camera around a target.
+ * Controls camera orbit, panning, zooming, and movement limits.
  * @category Cfg
  */
 export declare interface OrbitCtrlsCfg {
@@ -2196,7 +1624,7 @@ export declare interface OrbitCtrlsCfg {
      */
     autoRotate: boolean;
     /**
-     * Rotation speed of automatic rotation.
+     * Speed of automatic camera rotation.
      * @default 2.0
      */
     autoRotateSpeed: number;
@@ -2231,7 +1659,7 @@ export declare interface OrbitCtrlsCfg {
      */
     enableZoom: boolean;
     /**
-     * Loads OrbitControls via dynamic import.
+     * Prepares orbit controls without enabling them.
      * @default false
      */
     load: boolean;
@@ -2282,14 +1710,13 @@ export declare interface OrbitCtrlsCfg {
     zoomSpeed: number;
 }
 
-/** @event Fired when an OrbitControls event occurs and triggers the corresponding XState event. */
+/** @event Fired when orbit interaction starts, changes, or ends, or controls are enabled, disabled, or disposed. */
 export declare interface OrbitCtrlsEvent {
-    /** Identifies this event type. */
     type: 'OrbitCtrls_Changed' | 'OrbitCtrls_Disabled' | 'OrbitCtrls_Enabled' | 'OrbitCtrls_End' | 'OrbitCtrls_Start' | 'OrbitCtrls_Disposed';
 }
 
 /**
- * Defines the post-processing settings used by the rendering pipeline.
+ * Tunes post-processing effects selected by the renderer profiles.
  * @category Cfg
  */
 export declare interface PostCfg {
@@ -2300,8 +1727,8 @@ export declare interface PostCfg {
     guiOpened: boolean;
     /** Anti-aliasing settings. */
     aa: AaCfg;
-    /** Shared SSAO settings. */
-    ssao: SsaoCfg;
+    /** Shared screen-space lighting settings. */
+    ssl: SslCfg;
     /** Shared SSR settings. */
     ssr: SsrCfg;
     /** WebGL post-processing settings. */
@@ -2312,22 +1739,23 @@ export declare interface PostCfg {
             fxaa: FxaaCfg;
         };
         /** WebGL SSAO settings. */
-        ssao: SsaoWebGlCfg;
+        ssao: SsaoCfg;
         /** WebGL SSR settings. */
         ssr: SsrWebGlCfg;
     };
     /** WebGPU post-processing settings. */
     webgpu: {
-        /** WebGPU SSAO settings. */
-        ssao: SsaoWebGpuCfg;
+        /** WebGPU GTAO settings. */
+        gtao: GtaoCfg;
+        /** WebGPU SSGI settings. */
+        ssgi: SsgiCfg;
         /** WebGPU SSR settings. */
         ssr: SsrWebGpuCfg;
     };
 }
 
-/** @event Fired after the progress bar has finished hiding and triggers the corresponding XState event. */
+/** @event Fired after the loading progress bar has finished hiding. */
 export declare interface ProgressBarHiddenEvent {
-    /** Identifies this event type. */
     type: 'ProgressBar_Hidden';
 }
 
@@ -2342,6 +1770,7 @@ export declare class Raycast {
     private readonly engine;
     private readonly events;
     private readonly objs3D;
+    private readonly scene;
     private raycasterPick;
     private raycasterVisible;
     private colliders;
@@ -2370,10 +1799,12 @@ export declare class Raycast {
     private posWorldObj;
     private dirCamToObj;
     private posNdcPointer;
-    /* Excluded from this release type: __constructor */
     private checkOccludeeVisible;
-    /** Removes all colliders and restores scene objects hidden by `setColliders()`. */
-    clearColliders(): void;
+    /**
+     * Removes existing scene objects from raycasting and resets their collider roles.
+     * @param objs - Registered `Coll3D` instances to remove.
+     */
+    clearColliders(objs: Coll3D[]): void;
     /** Enables pickable raycasting and its pointer event listeners. */
     enablePickables(): void;
     /** Disables pickable raycasting without removing the collider configuration. */
@@ -2382,8 +1813,8 @@ export declare class Raycast {
     private getPickableHit;
     private getObjAtPointer;
     private emitPointerEvent;
-    /* Excluded from this release type: getOccludeeState */
-    /* Excluded from this release type: getOccludeeVisible */
+    private invalidateOccludees;
+    private rebuildColliderCaches;
     private onCanvasClick;
     private onCanvasPointerLeave;
     private onCanvasPointerMove;
@@ -2392,16 +1823,13 @@ export declare class Raycast {
     private onCanvasPointerExit;
     private onCanvasPointerUp;
     /**
-     * Replaces the current raycast colliders. The complete scene is used for occlusion until this method or `clearColliders()` is called for the first time.
-     * @param colliders - Scene objects and their occluder, pickable, and visibility roles.
+     * Adds or updates existing scene objects as raycast colliders. The complete scene is used for occlusion until this method or `clearColliders()` is called for the first time.
+     * @param colls3D - Registered `Coll3D` instances to add or update.
      */
-    setColliders(colliders: Collider[]): void;
-    /* Excluded from this release type: trackOccludee */
-    /* Excluded from this release type: untrackOccludee */
+    setColliders(colls3D: Coll3D[]): void;
     /**
-     * Registers and executes a low-level extension function with access to the public `Raycast` API.
-     * @param extension - Function that receives the current `Raycast` instance and can use its public members and methods.
-     * @remarks This method is intended for advanced custom integrations where developers need direct access to the engine instance. The extension is executed once immediately when `use()` is called.
+     * Runs an extension callback immediately with access to the public API.
+     * @param extension - Callback receiving this `Raycast` instance.
      */
     use(extension: (raycast: Raycast) => void): void;
     private updateOccludees;
@@ -2410,7 +1838,7 @@ export declare class Raycast {
 }
 
 /**
- * Defines the raycasting settings used to detect pickable objects around the pointer.
+ * Controls pointer picking and occlusion checks.
  * @category Cfg
  */
 export declare interface RaycastCfg {
@@ -2425,12 +1853,12 @@ export declare interface RaycastCfg {
      */
     circleSteps: number;
     /**
-     * Number of closest objects to detect.
+     * Number of consecutive closest-object detections required before the active hover target changes.
      * @default 5
      */
     countClosestObjs: number;
     /**
-     * Time in milliseconds over which all pending occludee checks are distributed once. A value of `0` processes all pending checks in one frame.
+     * Time in milliseconds over which pending occlusion checks are spread. A value of `0` processes them all in one frame.
      * @default 0
      */
     occludeeInterval: number;
@@ -2442,10 +1870,15 @@ export declare interface RaycastCfg {
 }
 
 /**
- * Defines the renderer settings used to control frame timing, resolution, shadows, tone mapping and output color space.
+ * Controls rendering quality, performance, shadows, and color output.
  * @category Cfg
  */
 export declare interface RenderCfg {
+    /**
+     * Enables or disables adaptive graphics quality selection.
+     * @default false
+     */
+    adaptiveGfx: boolean;
     /**
      * Selects the rendering backend.
      *
@@ -2460,27 +1893,27 @@ export declare interface RenderCfg {
      * Automatically updates the canvas, renderer, post-processing, camera and reflector sizes on window resize.
      * @default true
      */
-    autoResize?: boolean;
-    /**
-     * Whether the GUI render dropdown is open.
-     * @default false
-     */
-    guiOpened: boolean;
+    autoResize: boolean;
     /**
-     * Enables or disables the maximum frames limiter.
+     * Enables or disables Eco mode availability.
      * @default true
      */
-    fpsLimiter: boolean;
+    ecoMode: boolean;
     /**
-     * Maximum frames per second.
+     * Minimum rendering FPS to preserve when Eco Mode skips frames.
      * @default 30
      */
-    fpsMax: number;
+    fpsMin: number;
     /**
-     * Maximum number of delta time history samples.
-     * @default 10
+     * Number of recent frame timings used to evaluate performance.
+     * @default 20
      */
     deltaTimesMax: number;
+    /**
+     * Whether the GUI render dropdown is open.
+     * @default false
+     */
+    guiOpened: boolean;
     /**
      * Output color space.
      * @default THREE.SRGBColorSpace
@@ -2520,12 +1953,9 @@ export declare interface RenderCfg {
          * @default false
          */
         alpha: boolean;
-        /**
-         * Whether renderer-level anti-aliasing is enabled.
-         * @default false
-         */
-        antialias: boolean;
     };
+    /** Renderer feature profiles. */
+    profile: RenderProfileCfg;
     /**
      * WebGL-specific renderer configuration.
      */
@@ -2546,18 +1976,348 @@ export declare interface RenderCfg {
     };
 }
 
-/** Defines the available renderer backends. */
+/** @inheritDoc RenderCfg.api */
 export declare type Renderer = 'webgl' | 'webgpu' | 'auto';
 
-declare type Renderer_2 = THREE_TYPE.WebGLRenderer | THREE_WEBGPU_TYPE.WebGPURenderer;
+/** Complete effect selections for both rendering backends. */
+export declare interface RenderProfileCfg {
+    /** Resolved WebGL rendering profile. */
+    webgl: RenderProfileWebGl;
+    /** Resolved WebGPU rendering profile. */
+    webgpu: RenderProfileWebGpu;
+}
+
+/** Overrides renderer effects while preserving unspecified defaults and valid combinations. */
+export declare interface RenderProfileValidCfg {
+    /** WebGL effect overrides. */
+    webgl?: Partial<RenderProfileWebGl>;
+    /** Compatible WebGPU effect overrides. */
+    webgpu?: {
+        /** Disables MSAA or applies it only to the renderer. */
+        msaa?: Exclude<MsaaMode, 'post'>;
+        /** Selects non-temporal anti-aliasing. */
+        aa?: Exclude<AaModeWebGpu, 'traa'>;
+        /** Selects ambient occlusion without indirect illumination. */
+        ssl?: Exclude<SslModeWebGpu, 'ssgi'>;
+        /** Enables screen-space reflections. */
+        ssr?: boolean;
+    } | {
+        /** Applies MSAA to the renderer and post-processing. */
+        msaa: 'post';
+        /** Selects non-temporal anti-aliasing. */
+        aa?: Exclude<AaModeWebGpu, 'traa'>;
+        /** Post-processing MSAA does not support screen-space lighting. */
+        ssl?: 'none';
+        /** Enables screen-space reflections. */
+        ssr?: boolean;
+    } | {
+        /** Disables MSAA or applies it only to the renderer. */
+        msaa?: Exclude<MsaaMode, 'post'>;
+        /** Selects Temporal Reprojection Anti-Aliasing. */
+        aa: 'traa';
+        /** Selects screen-space lighting. */
+        ssl?: SslModeWebGpu;
+        /** Enables screen-space reflections. */
+        ssr?: boolean;
+    };
+}
+
+/** Selects MSAA, anti-aliasing, ambient occlusion, and reflections for WebGL. */
+export declare type RenderProfileWebGl = {
+    /** Selects where MSAA is applied. */
+    msaa: MsaaMode;
+    /** Selects the anti-aliasing mode. */
+    aa: AaModeWebGl;
+    /** Selects screen-space ambient occlusion. */
+    ssl: SslModeWebGl;
+    /** Enables screen-space reflections. */
+    ssr: boolean;
+};
+
+/** Selects compatible WebGPU effects. SSGI requires TRAA; post-processing MSAA excludes TRAA and screen-space lighting. */
+export declare type RenderProfileWebGpu = {
+    /** Enables screen-space reflections. */
+    ssr: boolean;
+} & ({
+    /** Disables MSAA or applies it only to the renderer. */
+    msaa: Exclude<MsaaMode, 'post'>;
+    /** Selects a non-temporal anti-aliasing mode. */
+    aa: Exclude<AaModeWebGpu, 'traa'>;
+    /** Selects screen-space lighting without SSGI. */
+    ssl: Exclude<SslModeWebGpu, 'ssgi'>;
+} | {
+    /** Applies MSAA to the renderer and post-processing. */
+    msaa: 'post';
+    /** Selects a non-temporal anti-aliasing mode. */
+    aa: Exclude<AaModeWebGpu, 'traa'>;
+    /** Post-processing MSAA does not support screen-space lighting. */
+    ssl: 'none';
+} | {
+    /** TRAA cannot be combined with post-processing MSAA. */
+    msaa: Exclude<MsaaMode, 'post'>;
+    /** Selects Temporal Reprojection Anti-Aliasing. */
+    aa: 'traa';
+    /** Selects screen-space lighting. */
+    ssl: SslModeWebGpu;
+});
+
+/**
+ * Controls scene contents, camera animation, materials, lighting, and clip playback.
+ * @category Core
+ */
+export declare class Scene {
+    private readonly cfg;
+    private readonly cam3D;
+    private readonly events;
+    private readonly objs3D;
+    private ambientLight;
+    private hemisphereLight;
+    readonly obj: THREE_TYPE.Scene;
+    /**
+     * Moves the camera along a curved path, optionally turning it toward a new target.
+     * @param params - Camera movement settings.
+     * @param params.camTarget - Destination position or object.
+     * @param params.aimTarget - Position or object to look at while moving.
+     * @param params.radiusOut - Outward curve radius. Default: **1**
+     * @param params.duration - Duration in seconds. Default: **2**
+     * @param params.ease - GSAP easing function. Default: **'power1.inOut'**
+     *
+     * @remarks
+     * Emits {@link AnimEvent} when the animation starts and completes.
+     */
+    animCamCurveTo({ camTarget, aimTarget, radiusOut, duration, ease }: {
+        camTarget: THREE_TYPE.Vector3 | string | Obj3D;
+        aimTarget?: THREE_TYPE.Vector3 | string | Obj3D;
+        radiusOut?: number;
+        duration?: number;
+        ease?: string;
+    }): void;
+    /**
+     * Moves a perspective camera to frame an object while looking at it. Only the object's own geometry is used; child objects are excluded.
+     * @param params - Camera movement settings.
+     * @param params.target - Object or scene object name to frame.
+     * @param params.duration - Duration in seconds. Default: **1**
+     * @param params.ease - GSAP easing function. Default: **'power2.inOut'**
+     * @param params.dist - Multiplier for the calculated camera distance. Default: **1.25**
+     *
+     * @remarks
+     * Emits {@link AnimEvent} when the animation starts and completes.
+     */
+    animCamTo({ target, duration, ease, dist }: {
+        target: string | Obj3D;
+        duration?: number;
+        ease?: string;
+        dist?: number;
+    }): void;
+    /**
+     * Animates one or more material colors on a mesh.
+     * @param params - Target colors, such as `color` or `emissive`, and animation settings.
+     * @param params.mesh - Scene mesh name or `Mesh3D` component.
+     * @param params.duration - Duration in seconds. Default: **0**
+     * @param params.ease - GSAP easing function. Default: **'power1.inOut'**
+     *
+     * @remarks
+     * Colors may be strings, numbers, or `THREE.Color` values. Emits {@link AnimFadeEvent} when the animation starts and completes.
+     */
+    animMaterialColor({ mesh, duration, ease, ...colorProps }: {
+        mesh: string | Mesh3D;
+        duration?: number;
+        ease?: string;
+    } & {
+        [key: string]: string | number | THREE_TYPE.Color | Mesh3D;
+    }): void;
+    /**
+     * Animates a numeric material property on a mesh. Only the first supplied property is animated.
+     * @param params - Target value and animation settings.
+     * @param params.mesh - Scene mesh name or `Mesh3D` component.
+     * @param params.startValue - Starting value. Defaults to the current material value.
+     * @param params.infinite - Repeats the animation indefinitely. Default: **false**
+     * @param params.duration - Duration in seconds. Default: **0**
+     * @param params.ease - GSAP easing function. Default: **'power1.inOut'**
+     * @param params.needsUpdate - Recompiles the material when animation starts. Default: **false**
+     *
+     * @remarks
+     * Emits {@link AnimFadeEvent} when the animation starts and completes.
+     */
+    animMaterialNumeric({ mesh, needsUpdate, startValue, infinite, duration, ease, ...props }: {
+        mesh: string | Mesh3D;
+        startValue?: number | null;
+        infinite?: boolean;
+        duration?: number;
+        ease?: string;
+        needsUpdate?: boolean;
+        [key: string]: any;
+    }): void;
+    private calcEaseArea;
+    /**
+     * 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.blendMode - How the action is blended with other active actions. Default: **'normal'**
+     * @param params.finishMode - Whether the final pose is held or faded out after the final loop. Default: **'hold'**
+     * @param params.loopMode - Number of plays or `'infinite'` for endless looping. Default: **1**
+     * @param params.stopMode - Which previous actions of the same layer are stopped before playback. Default: **'all'**
+     * @param params.fadeDuration - Duration in seconds for fading affected previous actions out and the new action in. Default: **0**
+     * @param params.fadeDurationFinish - Duration in seconds for `finishMode: '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.startSpeed - Initial playback speed for speed interpolation. Default: **0**
+     * @param params.endSpeed - Target playback speed. Default: **1**
+     * @param params.duration - Duration in seconds for speed interpolation. Default: **0**
+     * @param params.ease - 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.
+     *
+     * `finishMode` and `fadeDurationFinish` have no effect when `loopMode` is `'infinite'`.
+     *
+     * **Events**
+     *
+     * {@link ClipEvent}
+     */
+    playClip({ layer, clip: clipName, blendMode, finishMode, loopMode, stopMode, fadeDuration, fadeDurationFinish, reverse, reset, startSpeed, endSpeed, duration, ease }: {
+        layer: string;
+        clip: string;
+        singleAction?: boolean;
+        blendMode?: BlendMode;
+        finishMode?: FinishMode;
+        loopMode?: LoopMode;
+        stopMode?: StopMode;
+        fadeDuration?: number;
+        fadeDurationFinish?: number;
+        reverse?: boolean;
+        reset?: boolean;
+        startSpeed?: number;
+        endSpeed?: number;
+        duration?: number;
+        ease?: 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.blendMode - How the action is blended with other active actions. Default: **'normal'**
+     * @param params.loopMode - Number of plays or `'infinite'` for endless looping. Default: **1**
+     * @param params.stopMode - Which previous actions of the same layer are stopped before playback. Default: **'all'**
+     * @param params.fadeDuration - 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.startSpeed - Initial playback speed for speed interpolation. Default: **0**
+     * @param params.endSpeed - Target playback speed. Default: **1**
+     * @param params.duration - Duration in seconds for speed interpolation. Default: **0**
+     * @param params.ease - 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, blendMode, loopMode, stopMode, fadeDuration, reverse, reset, startSpeed, endSpeed, duration, ease }: {
+        layer: string;
+        clip: string;
+        blendMode?: BlendMode;
+        loopMode?: LoopMode;
+        stopMode?: StopMode;
+        fadeDuration?: number;
+        reverse?: boolean;
+        reset?: boolean;
+        startSpeed?: number;
+        endSpeed?: number;
+        duration?: number;
+        ease?: string;
+    }): void;
+    /**
+     * Removes the built-in ambient light and releases its resources.
+     */
+    removeAmbientLight(): void;
+    /**
+     * Removes scene fog.
+     */
+    removeFog(): void;
+    /**
+     * Removes the built-in hemisphere light and releases its resources.
+     */
+    removeHemisphereLight(): void;
+    /**
+     * Creates or updates uniform ambient lighting. Creation requires both color and intensity; omitted values remain unchanged when updating.
+     * @param params - Ambient light settings.
+     * @param params.color - Light color.
+     * @param params.intensity - Light intensity.
+     */
+    setAmbientLight({ color, intensity }: {
+        color?: THREE_TYPE.ColorRepresentation;
+        intensity?: number;
+    }): void;
+    /**
+     * Creates or updates distance-based scene fog. Creation requires all three settings; omitted values remain unchanged when updating.
+     * @param params - Fog settings.
+     * @param params.color - Fog color.
+     * @param params.near - Distance at which fog begins.
+     * @param params.far - Distance at which fog fully obscures objects.
+     */
+    setFog({ color, near, far }: {
+        color?: THREE_TYPE.ColorRepresentation;
+        near?: number;
+        far?: number;
+    }): void;
+    /**
+     * Creates or updates ambient sky and ground lighting. Creation requires all three settings; omitted values remain unchanged when updating.
+     * @param params - Hemisphere light settings.
+     * @param params.skyColor - Light color from above.
+     * @param params.groundColor - Light color from below.
+     * @param params.intensity - Light intensity.
+     */
+    setHemisphereLight({ skyColor, groundColor, intensity }: {
+        skyColor?: THREE_TYPE.ColorRepresentation;
+        groundColor?: THREE_TYPE.ColorRepresentation;
+        intensity?: number;
+    }): void;
+    /**
+     * Updates all material slots on a mesh, optionally including its descendants. Shared materials also affect other objects that use them.
+     * @param params - Target material values, such as `color`, `roughness`, or `map`.
+     * @param params.obj - Scene object name or `Mesh3D` component.
+     * @param params.recursive - Includes descendant meshes. Default: **false**
+     * @param params.needsUpdate - Recompiles materials after applying the values. Default: **false**
+     *
+     * @remarks
+     * Texture paths for `map` and `emissiveMap` load asynchronously. Unsupported values are skipped with a warning.
+     */
+    setMaterialProps({ obj, recursive, needsUpdate, ...props }: {
+        obj: string | Mesh3D;
+        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.fadeOut - Slowdown duration in seconds. Default: **0**
+     * @param params.ease - 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}.
+     */
+    stopAnimClip({ clipName, fadeOut, ease }: {
+        clipName: string;
+        fadeOut?: number;
+        ease?: string;
+    }): void;
+}
 
 /**
- * Defines the scene settings used to configure background, environment, model, fog and lights.
+ * Controls the canvas, fog, and built-in scene lights.
  * @category Cfg
  */
 export declare interface SceneCfg {
     /**
-     * Custom element tag in which the canvas is rendered.
+     * Selector for the element that hosts the rendered canvas.
      * @default 'ilu-canvas'
      */
     canvas: string;
@@ -2574,20 +2334,49 @@ export declare interface SceneCfg {
     hemisphere: HemisphereCfg;
 }
 
-/** @event Fired when the scene is set up and ready and triggers the corresponding XState event. */
+/** Scene component classes available for registration. */
+export declare type SceneClass = new (canvas: HTMLElement, cfg: Cfg, name: string, params?: Obj3DParams) => Objs3D;
+
+/** Scene component class with optional initial parameters. */
+export declare type SceneEntry<TClass extends SceneClass = SceneClass> = TClass | {
+    class: TClass;
+    /**
+     * Initial parameters assigned to a scene component class when the app starts. Accepts `Obj3DParams` or `Coll3DParams`, depending on the registered `class`. */
+    params?: ConstructorParameters<TClass>[3];
+};
+
+/**
+ * Maps a record of Scene Component classes or entries to a record of typed object instances.
+ * `{ key1: typeof SceneComp1 } -> { key1: SceneComp1 }`
+ * @hidden
+ */
+export declare type SceneInsts<T extends Record<string, SceneEntry>> = {
+    [K in keyof T]: T[K] extends SceneClass ? InstanceType<T[K]> : T[K] extends {
+        class: infer TClass extends SceneClass;
+    } ? InstanceType<TClass> : never;
+};
+
+/** @event Fired when the initial scene resources and component readiness hooks are complete. */
 export declare interface SceneReadyEvent {
-    /** Identifies this event type. */
     type: 'Scene_Ready';
 }
 
-/** @event Fired after the scene or a progressive scene variant has been rendered for the first time and triggers the corresponding XState event. */
+/** @event Fired after the initial scene or a progressive model level is rendered for the first time. */
 export declare interface SceneRenderedEvent {
     /** Identifies the rendered scene or progressive scene variant. */
     type: 'Scene_Rendered' | `Scene${number}_Rendered`;
 }
 
 /**
- * Defines the SMAA anti-aliasing pass settings used to smooth jagged edges in the rendered image.
+ * Updates startup settings while preserving unspecified defaults. Nested settings are merged; supplied arrays replace existing arrays.
+ * @param value - Configuration values that override the framework defaults.
+ * @returns The configured `cfg` object.
+ * @category Cfg
+ */
+export declare function setCfg(value: CfgSet): Cfg;
+
+/**
+ * Controls edge smoothing with SMAA.
  * @category Cfg
  */
 export declare interface SmaaCfg {
@@ -2620,29 +2409,12 @@ export declare type SoundParams = {
 };
 
 /**
- * Defines the screen-space ambient occlusion settings used to enhance depth and shading.
+ * Controls contact shading with WebGL SSAO.
  * @category Cfg
  */
 export declare interface SsaoCfg {
     /**
-     * Imports the SSAO module dynamically and enables the SSAO effect.
-     * @default false
-     */
-    enable: boolean;
-    /**
-     * Whether the GUI SSAO dropdown is open.
-     * @default false
-     */
-    guiOpened: boolean;
-}
-
-/**
- * Defines the WebGL screen-space ambient occlusion settings.
- * @category Cfg
- */
-export declare interface SsaoWebGlCfg {
-    /**
-     * Defines the radius of the ambient occlusion kernel.
+     * Sampling radius for ambient occlusion.
      * @default 8
      */
     kernelRadius: number;
@@ -2658,58 +2430,58 @@ export declare interface SsaoWebGlCfg {
     maxDistance: number;
 }
 
+/** Controls ambient occlusion and indirect diffuse lighting with WebGPU SSGI. */
+export declare interface SsgiCfg {
+    /** Whether the GUI SSGI dropdown is open. */
+    guiOpened: boolean;
+    /** Number of per-pixel hemisphere slices. */
+    sliceCount: number;
+    /** Number of samples taken along each side of a hemisphere slice. */
+    stepCount: number;
+    /** Strength of the ambient occlusion component. */
+    aoIntensity: number;
+    /** Strength of the indirect diffuse lighting component. */
+    giIntensity: number;
+    /** Effective sampling radius. */
+    radius: number;
+    /** Whether the sample distance is evaluated in screen space. */
+    useScreenSpaceSampling: boolean;
+    /** Exponent controlling sample distribution. */
+    expFactor: number;
+    /** Assumed thickness of screen-space geometry. */
+    thickness: number;
+    /** Whether thickness grows with distance. */
+    useLinearThickness: boolean;
+    /** Amount of lighting emitted by back-facing surfaces. */
+    backfaceLighting: number;
+}
+
 /**
- * Defines the WebGPU screen-space ambient occlusion settings.
+ * Shared screen-space lighting Inspector settings.
  * @category Cfg
  */
-export declare interface SsaoWebGpuCfg {
-    /**
-     * Defines the radius of the ambient occlusion in world space.
-     * @default 0.25
-     */
-    radius: number;
+export declare interface SslCfg {
     /**
-     * Defines the thickness used for the ambient occlusion calculation.
-     * @default 1
-     */
-    thickness: number;
-    /**
-     * Controls how strongly the AO is attenuated over distance.
-     * @default 1
-     */
-    distanceExponent: number;
-    /**
-     * Defines how quickly the AO fades with distance.
-     * @default 1
-     */
-    distanceFallOff: number;
-    /**
-     * Scales the strength of the ambient occlusion.
-     * @default 1
-     */
-    scale: number;
-    /**
-     * Defines the number of samples used to compute the AO.
-     * @default 16
-     */
-    samples: number;
-    /**
-     * Defines the render resolution scale of the AO effect.
-     * @default 1
+     * Whether the GUI SSL dropdown is open.
+     * @default false
      */
-    resolutionScale: number;
+    guiOpened: boolean;
 }
 
+/** Screen-space lighting modes available across rendering backends. */
+export declare type SslMode = SslModeWebGl | SslModeWebGpu;
+
+/** Screen-space lighting modes available with WebGL. */
+export declare type SslModeWebGl = 'none' | 'ssao';
+
+/** Screen-space lighting modes available with WebGPU. */
+export declare type SslModeWebGpu = 'none' | 'gtao' | 'ssgi';
+
 /**
- * Defines the shared screen-space reflection settings.
+ * Shared screen-space reflection parameters.
  * @category Cfg
  */
 export declare interface SsrCfg {
-    /**
-     * Imports the SSR module dynamically and enables the SSR effect.
-     * @default false
-     */
-    enable: boolean;
     /**
      * Whether the GUI SSR dropdown is open.
      * @default false
@@ -2733,7 +2505,7 @@ export declare interface SsrCfg {
 }
 
 /**
- * Defines the WebGL screen-space reflection settings.
+ * Tunes screen-space reflections with WebGL.
  * @category Cfg
  */
 export declare interface SsrWebGlCfg {
@@ -2748,7 +2520,7 @@ export declare interface SsrWebGlCfg {
      */
     distanceAttenuation: boolean;
     /**
-     * Enables fresnel-based reflections.
+     * Strengthens reflections at grazing viewing angles using the Fresnel effect.
      * @default true
      */
     fresnel: boolean;
@@ -2790,7 +2562,7 @@ export declare interface SsrWebGlCfg {
 }
 
 /**
- * Defines the WebGPU screen-space reflection settings.
+ * Tunes screen-space reflections with WebGPU.
  * @category Cfg
  */
 export declare interface SsrWebGpuCfg {
@@ -2812,8 +2584,7 @@ export declare interface SsrWebGpuCfg {
 }
 
 /**
- * Manages the lifecycle of an XState state machine within the application. The class encapsulates the creation and execution of a state machine actor, providing a controlled interface to start, monitor,
- * and debug its runtime behavior.
+ * Starts the application state machine and manages its XState actor.
  * @category Core
  */
 export declare class StateMachine {
@@ -2823,56 +2594,147 @@ export declare class StateMachine {
     private lastState;
     private snapshot;
     private stateMachine;
-    /* Excluded from this release type: __constructor */
-    /* Excluded from this release type: sendEvent */
     /**
-     * Starts the provided XState state machine and initializes its corresponding actor.
+     * Starts the supplied state machine.
      * @param stateMachine - A fully constructed XState 5 machine.
      *
      * **Example**
-     * {@includeCode ../examples/app-statemachine.ts}
+     * {@includeCode ../../../apps-doc/examples/app-statemachine.ts}
 
      */
     start(stateMachine: AnyStateMachine): void;
 }
 
 /**
- * Defines the application state machine settings used to control inspector-related state.
+ * Controls state-machine inspection.
  * @category Cfg
  */
 export declare interface StateMachineCfg {
     /**
-     * Imports statelyai/inspect module dynamically and enables inspector mode.
+     * Enables the Stately Inspector to visualize states and transitions.
      * @default false
      */
     inspector: boolean;
 }
 
 /**
- * Defines which previous active animation actions of the same layer are stopped before a new action is played.
- * - 'all': Stops all previous active actions.
- * - 'last': Stops only the most recently played previous active action.
- * - 'none': Keeps all previous active actions running.
+ * 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;
+
 /**
- * Defines the material texture slots available for unused GLTF images.
- *
- * - `ColorMap` assigns the texture to `map`. Use it with a `MeshBasicMaterial` for a fully baked color texture.
- * - `LightMap` assigns the texture to the `lightMap` slot and requires a `MeshStandardMaterial`.
- * - `AlphaMap` assigns a separate alpha texture to the `alphaMap` slot, which GLTF does not support natively.
+ * Connects a custom HTML element to the scene lifecycle and object visibility.
+ * @category Web Components
  */
-export declare type TextureSlot = 'ColorMap' | 'LightMap' | 'AlphaMap';
+export declare class Web extends HTMLElement {
+    /** Element that hosts the rendered canvas. */
+    canvas: Readonly<HTMLElement>;
+    cfg: Cfg;
+    events: Readonly<Events>;
+    objs3D: Map<string, Obj3D>;
+    webs: Map<string, Web[]> | null;
+    private obj3DFollow;
+    private visible;
+    private visibleFollow;
+    private visibleOverlap;
+    private webCtrls;
+    private unSubFollow;
+    private unSubVisible;
+    private clearFollow;
+    private emitEvent;
+    /**
+     * Makes this component follow an `Obj3D` by subscribing to updates of its screen position and combined visibility.
+     *
+     * @param params - The follow parameters.
+     * @param params.obj - The `Obj3D` to follow in the scene.
+     */
+    follow({ obj }: {
+        obj: Obj3D | string;
+    }): void;
+    /**
+     * Applies the combined followed-object and overlap visibility.
+     * @param visible - Whether the web component is visible after combining all visibility conditions.
+     */
+    protected onVisibilityChanged(visible: boolean): void;
+    /**
+     * Called once when the scene, renderer, and initial environment are ready and, if configured, the first model has been loaded and traversed.
+     * @public
+     *
+     * **Example**
+     * {@includeCode ../../../../apps-doc/examples/marker-onready.ts}
+     */
+    protected onReady(): void;
+    /**
+     * Called once after the scene is initialized, before model loading begins.
+     * @public
+     */
+    protected onStart(): void;
+    /**
+     * Registers this component for screen-space overlap tracking using `cfg.comps.overlap.padding`.
+     * Farther registered components are hidden when their screen-space rectangles overlap.
+     */
+    trackOverlap(): void;
+    /** Stops this component from following the currently subscribed {@link Obj3D}. */
+    unfollow(): void;
+    /** Stops screen-space overlap tracking and removes any overlap-based hiding from this component. */
+    untrackOverlap(): void;
+    private updateVisibility;
+}
 
-/** Function returned by an event subscription. Calling it removes the associated listener. */
-export declare type Unsubscribe = () => void;
+/** Web component classes available for registration. */
+export declare type WebClass = new () => Web;
 
+/** Web component class with optional initial parameters. */
+export declare type WebEntry<TClass extends WebClass = WebClass> = TClass | {
+    class: TClass;
+    params?: WebParams;
+};
+
+export declare type WebEvent = WebOverlapEvent | WebVisibleEvent;
+
+/** @inheritDoc RenderCfg.webgpu.params */
 export declare type WebGpuRendererParams = NonNullable<ConstructorParameters<typeof THREE_WEBGPU_TYPE.WebGPURenderer>[0]>;
 
-/** @event Fired when the window size changes and triggers the corresponding XState event. */
+/**
+ * Maps a record of Web Component classes or entries to a record of component instance arrays.
+ * `{ key1: typeof Web1 } -> { key1: Web1[] }`
+ * @hidden
+ */
+export declare type WebInsts<T extends Record<string, WebEntry>> = {
+    [K in keyof T]: T[K] extends WebClass ? InstanceType<T[K]>[] : T[K] extends {
+        class: infer TClass extends WebClass;
+    } ? InstanceType<TClass>[] : never;
+};
+
+/** @event Fired when a web component becomes overlapped or unobstructed. */
+export declare interface WebOverlapEvent {
+    type: 'Web_Overlap_Changed';
+    /** The affected web component. */
+    web: Web;
+    /** Whether the component is overlapped by a nearer component. */
+    overlapped: boolean;
+}
+
+/** Initial parameters assigned to a web component class when the app starts. */
+export declare type WebParams = Record<string, unknown>;
+
+/** @event Fired when a web component's combined object and overlap visibility changes. */
+export declare interface WebVisibleEvent {
+    type: 'Web_Visible_Changed';
+    /** The affected web component. */
+    web: Web;
+    /** Whether the component is visible after combining all visibility conditions. */
+    visible: boolean;
+}
+
+/** @event Fired when the window size changes. */
 export declare interface WindowResizeEvent {
-    /** Identifies this event type. */
     type: 'Window_Resize';
 }