illutions 0.21.6

package/dist/main.d.ts

@@ -0,0 +1,2479 @@
+import { AnyEventObject } from 'xstate';
+import { AnyStateMachine } from 'xstate';
+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 { 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 { PointerLockControls } from 'three/addons/controls/PointerLockControls.js';
+import { PointerLockControls as PointerLockControls_2 } from 'three/examples/jsm/controls/PointerLockControls.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 { SSAOPass } from 'three/addons/postprocessing/SSAOPass.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';
+
+/** Defines the shared anti-aliasing settings.
+ * @category Cfg
+ */
+export declare interface aaCfg {
+    /**
+     * Whether the GUI anti-aliasing dropdown is open.
+     * @default false
+     */
+    guiOpened: boolean;
+    /**
+     * Selects the anti-aliasing mode.
+     * @default 'none'
+     */
+    mode: 'none' | 'fxaa' | 'smaa';
+}
+
+/** Defines the ambient light settings controlling global scene illumination.
+ * @category Cfg
+ */
+export declare interface AmbientlightCfg {
+    /**
+     * Activates the ambient light in the scene.
+     * @default false
+     */
+    enable: boolean;
+    /**
+     * Light color applied uniformly to all objects.
+     * @default 0xffffff
+     */
+    color: THREE_TYPE.ColorRepresentation;
+    /**
+     * Intensity of the ambient light.
+     * @default 1
+     */
+    intensity: number;
+}
+
+/** @event Fired when an object animation starts or finishes and triggers the corresponding XState event. */
+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;
+    /** The name of the calling method. */
+    fct: string;
+}
+
+/** @event Fired when a material fade animation starts or finishes and triggers the corresponding XState event. */
+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;
+    /** The name of the calling method. */
+    fct: string;
+    /** The material property being faded. */
+    property: string;
+    /** The target value used for the fade operation. */
+    value: any;
+}
+
+/**
+ * Represents the central controller of the illutions 3D engine. The class initializes and manages all core modules of the engine, such as `Audio`, `Engine`, `Raycast` and `StateMachine`.
+ * It provides an entry point for creating and controlling a complete 3D scene.
+ * @category Core
+ */
+export declare class App<TClasses extends Classes = {}> {
+    readonly audio: Audio_2;
+    readonly cfgCtrl: CfgCtrl;
+    readonly engine: Engine;
+    readonly envCtrls: EnvCtrls;
+    readonly events: Events;
+    readonly orbitCtrls: OrbitCtrls;
+    readonly fpvCtrls: FpvCtrls;
+    readonly raycast: Raycast;
+    readonly stateMachine: StateMachine;
+    private cam3D;
+    private readonly gui;
+    readonly comps: CompInsts<NonNullable<TClasses['comps']>>;
+    readonly objs3D: Obj3DInsts<NonNullable<TClasses['objs3D']>>;
+    /* Excluded from this release type: __constructor */
+    init(cfg: Cfg): Promise<void>;
+    /**
+     * 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**
+     * @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.
+     *
+     * **Example**
+     * {@includeCode ../examples/app-run.ts}
+     */
+    static run<TClasses extends Classes = {}>(cfg?: Cfg, classes?: TClasses, createStateMachine?: (app: App<TClasses>) => 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.
+ * @category Core
+ */
+declare class Audio_2 {
+    private readonly cfg;
+    private readonly ctx;
+    private readonly loader;
+    private readonly engine;
+    private readonly sounds;
+    private audioCfgLast;
+    private callback;
+    private listener;
+    /* Excluded from this release type: __constructor */
+    private attachSoundTo;
+    /**
+     * 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.
+     */
+    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.
+     */
+    isPlaying({ name }: {
+        name: string;
+    }): boolean;
+    /**
+     * Loads an audio file and plays it once loaded with a smooth fade-in.
+     * @param params - The parameters for loading and playing an audio.
+     * @param params.name - Unique name of the audio.
+     * @param params.url - Path or URL to the audio file.
+     * @param params.object - The name of the object to attach the audio to for positional audio. Pass an empty string for global audio.
+     * @param params.volume - The target playback volume. Default: **0**
+     * @param params.fade - The fade-in duration of the audio in seconds. Default: **2**
+     * @param params.loop - Whether the audio should loop. Default: **true**
+     */
+    loadAndPlay({ name, url, object, volume, fade, loop }: {
+        name: string;
+        url: string;
+        object: string;
+        volume?: number;
+        fade?: number;
+        loop?: boolean;
+    }): void;
+    /**
+     * Plays an already loaded audio with a smooth fade-in.
+     * @param params - Parameter object.
+     * @param params.name - The name of the audio to play.
+     */
+    play({ name }: {
+        name: string;
+    }): void;
+    private setAttribute;
+    private setAudioContext;
+    /**
+     * Creates a `THREE.AudioListener` and attaches it to the specified object.
+     *
+     * @param params - Parameter object.
+     * @param params.object - The name of the scene object to attach the listener to.
+     */
+    setListener({ object: name }: {
+        object: string;
+    }): void;
+    private setAllPositionalSoundsCfg;
+    private setPositionalSoundCfg;
+    /**
+     * 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.
+     */
+    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.
+     */
+    use(extension: (audio: Audio_2) => void): void;
+    /* Excluded from this release type: update */
+}
+export { Audio_2 as Audio }
+
+/** Defines the audio settings used for playback timing and distance-based spatial attenuation.
+ * @category Cfg
+ */
+export declare interface AudioCfg {
+    /**
+     * Whether the GUI audio dropdown is open.
+     * @default false
+     */
+    guiOpened: boolean;
+    /**
+     * The default sound start offset in milliseconds.
+     * @default 200
+     */
+    delayPlaySound: number;
+    /**
+     * The reference distance after which the attenuation begins.
+     * @default 1
+     */
+    refDistance: number;
+    /**
+     * Determines how quickly the volume falls off with distance.
+     * @default 5
+     */
+    rolloffFactor: number;
+    /**
+     * The maximum distance at which the sound is still audible.
+     * @default 1000
+     */
+    maxDistance: number;
+    /**
+     * The distance attenuation model used.
+     * @default 'exponential'
+     */
+    distanceModel: 'linear' | 'inverse' | 'exponential';
+    /**
+     * The angle inside the cone where there is no attenuation.
+     * @default 360
+     */
+    coneInnerAngle: number;
+    /**
+     * The angle outside the cone where full attenuation is applied.
+     * @default 360
+     */
+    coneOuterAngle: number;
+    /**
+     * The gain factor outside the cone.
+     * @default 0
+     */
+    coneOuterGain: number;
+}
+
+/**
+ * Wraps a `THREE.Camera` and provides a structured interface for configuring and controlling camera settings.
+ * @category 3D Objects
+ */
+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.
+     * @default `THREE.PerspectiveCamera`
+     */
+    readonly obj: THREE_TYPE.Camera;
+    /** Reference to the original `THREE.Camera` loaded from the GLTF scene. */
+    objGltf: THREE_TYPE.Camera | null;
+    /** Target object used as the camera look-at target. */
+    objTarget: THREE_TYPE.Object3D;
+    /** 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`.
+     * @param objGltf - The GLTF `THREE.Camera` object.
+     * @public
+     *
+     * **Example**
+     * {@includeCode ../../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.
+ * @category Cfg
+ */
+export declare interface CamBaseCfg {
+    /**
+     * The distance to the near clipping plane.
+     * @default 0.1
+     */
+    near: number;
+    /**
+     * The distance to the far clipping plane.
+     * @default 1000
+     */
+    far: number;
+    /**
+     * The point in 3D space the camera should look at.
+     * @default { x: 0, y: 0, z: 0 }
+     */
+    lookAt: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /**
+     * The default position of the camera in 3D space.
+     * @default { x: 0, y: 0.5, z: 0.5 }
+     */
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+
+export declare type CamCfg = CamPerspectiveCfg | CamOrthographicCfg;
+
+/** Defines the orthographic camera settings used to render the scene without perspective distortion.
+ * @category Cfg
+ */
+export declare interface CamOrthographicCfg extends CamBaseCfg {
+    /**
+     * The camera type.
+     * @default 'orthographic'
+     */
+    type: 'orthographic';
+    /**
+     * Camera frustum left plane.
+     * @default -1
+     */
+    left: number;
+    /**
+     * Camera frustum right plane.
+     * @default 1
+     */
+    right: number;
+    /**
+     * Camera frustum top plane.
+     * @default 1
+     */
+    top: number;
+    /**
+     * Camera frustum bottom plane.
+     * @default -1
+     */
+    bottom: number;
+    /** @private */
+    fov?: never;
+    /** @private */
+    aspect?: never;
+}
+
+/** Defines the perspective camera settings used to render the scene with depth perception.
+ * @category Cfg
+ */
+export declare interface CamPerspectiveCfg extends CamBaseCfg {
+    /**
+     * The camera type.
+     * @default 'perspective'
+     */
+    type: 'perspective';
+    /**
+     * 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. */
+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. */
+export declare interface CanvasPointerEvent {
+    /** Identifies this event type. */
+    type: 'CANVAS_CLICK' | 'CANVAS_POINTER_DOWN' | 'CANVAS_POINTER_MOVE' | 'CANVAS_POINTER_UP';
+    /** Native pointer event from the canvas interaction. */
+    event: PointerEvent;
+}
+
+/** Defines the full configuration structure used to initialize the application.
+ * @category Cfg
+ */
+export declare interface Cfg {
+    /** Audio settings. */
+    audio: AudioCfg;
+    /** Camera settings. */
+    cam: CamCfg;
+    /** Debug settings. */
+    debug: DebugCfg;
+    /** Environment controls settings. */
+    envCtrls: EnvCtrlsCfg;
+    /** Light and shadow settings. */
+    light: LightCfg;
+    /** Menu bar settings. */
+    menuBar: MenuBarCfg;
+    /** Default mesh settings. */
+    mesh: MeshCfg;
+    /** GLTF/GLB model settings. */
+    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;
+    /** Scene settings. */
+    scene: SceneCfg;
+    /** State machine settings. */
+    stateMachine: StateMachineCfg;
+    /** Runtime statistics settings. */
+    stats: StatsCfg;
+}
+
+/** Defines the static configuration that is applied at compile-time. For runtime updates use {@link CfgCtrl}. */
+export declare const cfg: Cfg;
+
+/**
+ * Controls configuration options at runtime.
+ * @category Core
+ */
+export declare class CfgCtrl {
+    private cfg;
+    /* Excluded from this release type: __constructor */
+    /**
+     * Applies runtime updates to `AudioCfg`.
+     *
+     * @param params - Partial audio settings to apply.
+     * @param params.refDistance - {@link AudioCfg.refDistance}.
+     * @param params.rolloffFactor - {@link AudioCfg.rolloffFactor}.
+     * @param params.maxDistance - {@link AudioCfg.maxDistance}.
+     * @param params.distanceModel - {@link AudioCfg.distanceModel}.
+     * @param params.coneInnerAngle - {@link AudioCfg.coneInnerAngle}.
+     * @param params.coneOuterAngle - {@link AudioCfg.coneOuterAngle}.
+     * @param params.coneOuterGain - {@link AudioCfg.coneOuterGain}.
+     */
+    setAudio(params: Partial<AudioCfg>): void;
+    /**
+     * Applies runtime updates to `RenderCfg`.
+     *
+     * @param params - Partial render settings to apply.
+     * @param params.fpsLimiter - {@link RenderCfg.fpsLimiter}.
+     * @param params.deltaTimesMax - {@link RenderCfg.deltaTimesMax}.
+     */
+    setRender(params: Partial<RenderCfg>): void;
+}
+
+/**
+ * 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;
+};
+
+/** @event Fired when a clip starts or finishes playing and triggers the corresponding XState event. */
+export declare interface ClipEvent {
+    /** Identifies this event type. */
+    type: 'CLIP_START' | 'CLIP_COMPLETE';
+    /** The name of the `THREE.AnimationClip` that changed state. */
+    clipName: string;
+    /** The name of the calling method. */
+    fct: string;
+    /** The associated animation action, when available. */
+    action?: THREE_TYPE.AnimationAction;
+}
+
+/** @event Fired when a clip fade starts, completes, or fade-out starts/completes and triggers the corresponding XState event. */
+export declare interface ClipFadeEvent {
+    /** Identifies this event type. */
+    type: 'CLIP_FADE_START' | 'CLIP_FADE_COMPLETE' | 'CLIP_FADEOUT_COMPLETE' | 'CLIP_FADEOUT_START';
+    /** The name of the `THREE.AnimationClip` whose fade changed state. */
+    clipName: string;
+    /** The name of the calling method. */
+    fct: string;
+    /** The associated animation action, when available. */
+    action?: THREE_TYPE.AnimationAction;
+}
+
+/**
+ * Represents a reusable web-component logic unit bound to a custom element that participates in the scene lifecycle.
+ * @category Components
+ */
+export declare class Comp extends HTMLElement {
+    /** The root HTML element that hosts the visual container for the engine. */
+    canvas: Readonly<HTMLElement>;
+    cfg: Cfg;
+    cfgCtrl: Readonly<CfgCtrl>;
+    comps: Map<string, Comp[]> | null;
+    events: Readonly<Events>;
+    objs3D: Map<string, Obj3D>;
+    private unsubFollow;
+    private unsubVisible;
+    /**
+     * Makes this component follow an `Obj3D` by subscribing to updates of its screen position.
+     *
+     * @param params - The follow parameters.
+     * @param params.obj - The `Obj3D` to follow in the scene.
+     * @param params.enableOcclusionCheck - Whether to enable occlusion visibility checks. Default: **false**
+     */
+    follow({ obj, enableOcclusionCheck }: {
+        obj: Obj3D | string;
+        enableOcclusionCheck?: boolean;
+    }): void;
+    /** Stops this component from following the currently subscribed {@link Obj3D}. */
+    unfollow(): 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/comp-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: start */
+}
+
+/** Constructor type for `Comp` classes. */
+export declare type CompClass = new () => Comp;
+
+/**
+ * Maps a record of Comp classes to a record of component instance arrays.
+ * { key1: typeof Comp1 } -> { key1: Comp1[] }
+ * @hidden
+ */
+export declare type CompInsts<T extends Record<string, CompClass>> = {
+    [K in keyof T]: InstanceType<T[K]>[];
+};
+
+/** Defines the debugging settings that can be toggled during development.
+ * @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.
+     * @default 'xstate'
+     */
+    log: 'none' | 'xstate' | 'all';
+}
+
+/**
+ * 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.
+ * @category Core
+ */
+export declare class Engine {
+    /* Excluded from this release type: scene */
+    private readonly cam3D;
+    private readonly events;
+    private readonly modules;
+    private readonly comps;
+    private readonly objs3D;
+    private readonly cfg;
+    private readonly stats;
+    private actionObserver;
+    private gltf;
+    private mixer;
+    private composer;
+    /* Excluded from this release type: renderer */
+    private renderPipeline;
+    /* Excluded from this release type: modelReady */
+    /* Excluded from this release type: rendererReady */
+    private callbacks;
+    private canvas;
+    private fxaaPass;
+    private outputPass;
+    private renderPass;
+    private smaaPass;
+    private tslPass;
+    /* 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 postAuto;
+    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 initWebGpuRenderer;
+    private isPostEnabled;
+    /**
+     * Registers a callback that is executed on every requestAnimationFrame update.
+     * @param {(deltaTime: number) => void} cb - Callback executed once per frame with `deltaTime`.
+     */
+    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}
+     */
+    animCamCurveToTarget({ camTarget, aimTarget, radiusOut, duration, ease }: {
+        camTarget: THREE_TYPE.Vector3 | string | Obj3D;
+        aimTarget?: THREE_TYPE.Vector3 | string | Obj3D;
+        radiusOut?: number;
+        duration?: number;
+        ease?: string;
+    }): 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}
+     */
+    animCamToObj({ target, duration, ease, dist }: {
+        target: string | Obj3D;
+        duration?: number;
+        ease?: string;
+        dist?: number;
+    }): 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}
+     */
+    animMaterialColor({ mesh, duration, ease, ...colorProps }: {
+        mesh: string;
+        duration?: number;
+        ease?: string;
+    } & {
+        [key: string]: string | number | THREE_TYPE.Color;
+    }): void;
+    /**
+     * 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'**
+     *
+     * @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}
+     */
+    animMaterialNumeric({ mesh, startValue, infinite, duration, ease, ...props }: {
+        mesh: string;
+        startValue?: number | null;
+        infinite?: boolean;
+        duration?: number;
+        ease?: string;
+        [key: string]: any;
+    }): void;
+    private calcEaseArea;
+    /**
+     * Selects the active anti-aliasing mode. The modes `'fxaa'` and `'smaa'` lazy-load their required modules.
+     * @param aaMode - The anti-aliasing mode to use.
+     */
+    enableAaMode(aaMode: Cfg['post']['aa']['mode']): Promise<void>;
+    /**
+     * Enables or disables screen-space ambient occlusion. Passing `true` lazy-loads the required module.
+     * @param enable - Whether SSAO should be enabled.
+     */
+    enableSsao(enable: boolean): Promise<void>;
+    /**
+     * 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.
+     */
+    enableSsr(enable: boolean): Promise<void>;
+    private getPostAuto;
+    private loadModel;
+    private pauseObjActions;
+    /**
+     * The method finds a Three.js animation clip by name, validates that it exists within the loaded GLTF and plays it via the `THREE.AnimationMixer`. It supports fade-in/out speed transitions, reverse playback,
+     * and infinite looping of the clip.
+     *
+     * @param params - Parameter object for controlling the animation playback.
+     * @param params.obj - The name of the object whose animation clip should be played.
+     * @param params.clip - The name of the animation clip to play.
+     * @param params.pauseActions - Defines which other actions of the same object should be paused before playing this clip. Default: **'all'**
+     * @param params.reverse - If `true`, plays the clip in reverse. Default: **false**
+     * @param params.infinite - If `true`, the animation loops infinitely. Default: **false**
+     * @param params.reset - If `true`, resets the clip to its start position before playback. In reverse mode, it resets to the clip end. Default: **false**
+     * @param params.startSpeed - The initial playback speed at the beginning of the fade. Default: **0**
+     * @param params.endSpeed - The target playback speed at the end of the fade. Default: **1**
+     * @param params.duration - The duration in seconds for the fade transition between start and end speed. Default: **0**
+     * @param params.ease - The easing function name for GSAP. Default: **'power1.inOut'**
+
+     * @remarks
+     * The method interpolates `timeScale` of the `THREE.AnimationAction`, allowing smooth acceleration or deceleration of animation playback.
+     *
+     * **Events**
+     *
+     * {@link ClipEvent}
+     */
+    playClip({ obj, clip: clipName, pauseActions, reverse, infinite, reset, startSpeed, endSpeed, duration, ease }: {
+        obj: string;
+        clip: string;
+        singleAction?: boolean;
+        pauseActions?: PauseObjectActions;
+        reverse?: boolean;
+        infinite?: boolean;
+        reset?: boolean;
+        startSpeed?: number;
+        endSpeed?: number;
+        duration?: number;
+        ease?: string;
+    }): void;
+    /**
+     * The method finds a camera animation clip by name, validates that it exists within the loaded GLTF and plays it via the `THREE.AnimationMixer`. It supports fade-in/out speed transitions, reverse playback,
+     * and infinite looping of the clip.
+     *
+     * @param params - Parameter object for controlling the animation playback.
+     * @param params.obj - The name of the camera object whose animation clip should be played.
+     * @param params.clip - The name of the camera object's animation clip to play.
+     * @param params.pauseActions - Defines which other actions of the same object should be paused before playing this clip. Default: **'all'**
+     * @param params.reverse - If `true`, plays the clip in reverse. Default: **false**
+     * @param params.infinite - If `true`, the animation loops infinitely. Default: **false**
+     * @param params.reset - If `true`, resets the clip to its start position before playback. In reverse mode, it resets to the clip end. Default: **false**
+     * @param params.startSpeed - The initial playback speed at the beginning of the fade. Default: **0**
+     * @param params.endSpeed - The target playback speed at the end of the fade. Default: **1**
+     * @param params.duration - The duration in seconds for the fade transition between start and end speed. Default: **0**
+     * @param params.ease - The easing function name for GSAP. Default: **'power1.inOut'**
+     *
+     * @remarks
+     * The method interpolates `timeScale` of the `THREE.AnimationAction`, allowing smooth acceleration or deceleration of camera animation playback.
+     *
+     * **Events**
+     *
+     * {@link ClipEvent}
+     */
+    playClipCam({ obj, clip: clipName, pauseActions, reverse, infinite, reset, startSpeed, endSpeed, duration, ease }: {
+        obj: string;
+        clip: string;
+        pauseActions?: PauseObjectActions;
+        reverse?: boolean;
+        infinite?: 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.
+     *
+     * @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, ...props }: {
+        obj: string;
+        [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, allowing a visually smooth stop. Once completed, a `ClipFade` event with type `CLIP_FADEOUT_COMPLETE`
+     * is emitted. If no fade-out is specified, the clip stops immediately.
+     *
+     * **Events**
+     *
+     * {@link ClipFadeEvent}
+     */
+    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;
+}
+
+/**
+ * This class controls and manages `THREE.Scene.environment` and `THREE.Scene.background` textures (HDRI, EXR, standard textures), including environment lighting and optional animated rotation.
+ * @category Core
+ */
+export declare class EnvCtrls {
+    private cfg;
+    private engine;
+    private modules;
+    /* Excluded from this release type: envReady */
+    /* Excluded from this release type: textureReady */
+    private envEnabled;
+    private envInit;
+    private envIntensity;
+    private bgIntensity;
+    private bgBlurriness;
+    private rotation;
+    private rotationSpeed;
+    private timeBgRot;
+    private callback;
+    /* Excluded from this release type: __constructor */
+    /* Excluded from this release type: init */
+    private applyEnv;
+    /**
+     * Enables the environment system. Loads an environment texture and applies it to `THREE.Scene.environment` and `THREE.Scene.background`.
+
+     * @param params - Optional environment loading parameters. If provided, both `type` and `map` are required.
+     * @param params.type - Environment map type. Defaults to `cfg.envCtrls.type`.
+     * @param params.map - Environment map path or URL. 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 environment controls parameters. */
+    get(): Partial<EnvCtrlsCfg>;
+    /**
+     * Returns whether the environment system is currently enabled.
+     * @returns `true` if `EnvCtrls` is currently enabled, otherwise `false`.
+     */
+    isEnabled(): boolean;
+    private loadTexture;
+    /**
+     * Sets one or multiple environment control parameters at runtime.
+     * @param params - Object containing any subset of environment control parameters.
+     */
+    set(params: Partial<EnvCtrlsCfg>): void;
+    private setEnv;
+    private startEnv;
+    private update;
+}
+
+/** Defines the environment controls settings for `THREE.Scene.environment` and `THREE.Scene.background`.
+ * @category Cfg
+ */
+export declare interface EnvCtrlsCfg {
+    /**
+     * Sets the blurriness of the background.
+     * @default 0
+     */
+    backgroundBlurriness: number;
+    /**
+     * Attenuates the color of the background.
+     * @default 0
+     */
+    backgroundIntensity: number;
+    /**
+     * Enables or disables environment and background map handling.
+     * @default false
+     */
+    enable: boolean;
+    /**
+     * Attenuates the color of the environment.
+     * @default 1.8
+     */
+    environmentIntensity: number;
+    /**
+     * Loads the EXR or HDR loader via dynamic import.
+     * @default false
+     */
+    load: boolean;
+    /**
+     * Path to the environment map.
+     * @default ''
+     */
+    map: string;
+    /**
+     * Environment and background rotation values in degrees.
+     * @default { x: 0, y: 0, z: 0 }
+     */
+    rotation: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /**
+     * Rotation speed of the environment and background map.
+     * @default 0
+     */
+    rotationSpeed: number;
+    /**
+     * Specifies the type of environment map file.
+     * @default 'exr'
+     */
+    type: 'hdr' | 'exr' | 'texture';
+}
+
+/**
+ * Internal event dispatcher for the engine.
+ * @category Core
+ */
+export declare class Events {
+    private cfg;
+    private stateMachine;
+    private eventQueue;
+    private isProcessingEvents;
+    /* Excluded from this release type: __constructor */
+    /** Queues callbacks and processes them sequentially to prevent re-entrant or simultaneous access to send(). */
+    private enqueue;
+    /* Excluded from this release type: anim */
+    /* Excluded from this release type: animFade */
+    /* Excluded from this release type: clip */
+    /* Excluded from this release type: clipFade */
+    /* Excluded from this release type: modelError */
+    /* Excluded from this release type: modelLoading */
+    /**
+     * 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 log - Information to log with the event.
+     */
+    send(event: AnyEventObject, log?: string): void;
+    /* Excluded from this release type: windowResize */
+}
+
+/** Defines the fog settings controlling scene depth-based color attenuation.
+ * @category Cfg
+ */
+export declare interface FogCfg {
+    /**
+     * Activates fog in the scene.
+     * @default false
+     */
+    enable: boolean;
+    /**
+     * Fog color value.
+     * @default 0x000000
+     */
+    color: THREE_TYPE.ColorRepresentation;
+    /**
+     * Distance at which fog begins.
+     * @default 0
+     */
+    near: number;
+    /**
+     * Distance at which fog ends.
+     * @default 100
+     */
+    far: number;
+}
+
+/**
+ * This class integrates three.js PointerLockControls directly in the engine's render loop, supporting runtime updates and dynamic enabling/disabling.
+ * @category Core
+ */
+export declare class FpvCtrls {
+    private readonly cam3D;
+    private readonly canvas;
+    private readonly cfg;
+    private readonly engine;
+    private readonly events;
+    private readonly modules;
+    /* Excluded from this release type: pointerLockCtrls */
+    private minPolarAngle;
+    private maxPolarAngle;
+    private pointerSpeed;
+    private keyMoveForward;
+    private keyMoveLeft;
+    private keyMoveBackward;
+    private keyMoveRight;
+    private keyMoveUp;
+    private keyMoveDown;
+    private isMoveForward;
+    private isMoveLeft;
+    private isMoveBackward;
+    private isMoveRight;
+    private isMoveUp;
+    private isMoveDown;
+    private callback;
+    private readonly onClick;
+    private readonly onKeyDown;
+    private readonly onKeyUp;
+    /* Excluded from this release type: __constructor */
+    /** Creates three.js `PointerLockControls`. */
+    create(): void;
+    /** Disables three.js `PointerLockControls`. */
+    disable(): void;
+    /** Enables three.js `PointerLockControls` for the current camera. */
+    enable(): void;
+    /** Disposes three.js `PointerLockControls` and cleans up their runtime resources. */
+    dispose(): void;
+    /** Returns the current three.js `PointerLockControls` configuration. */
+    get(): Partial<FpvCtrlsCfg>;
+    /** Returns whether three.js `PointerLockControls` are enabled. */
+    isEnabled(): boolean;
+    /** Returns whether three.js `PointerLockControls` are currently locked. */
+    isLocked(): boolean;
+    /** Locks three.js `PointerLockControls` and starts pointer-look interaction. */
+    lock(): void;
+    /**
+     * Moves the controlled camera forward.
+     * @param distance - Distance to move in world units.
+     */
+    moveForward(distance: number): void;
+    /**
+     * Moves the controlled camera to the right.
+     * @param distance - Distance to move in world units.
+     */
+    moveRight(distance: number): void;
+    /**
+     * Moves the controlled camera up.
+     * @param distance - Distance to move in world units.
+     */
+    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.
+     */
+    set(params: Partial<FpvCtrlsCfg>): void;
+    /** Unlocks three.js `PointerLockControls` and stops pointer-look interaction. */
+    unlock(): void;
+    /**
+     * Registers and executes a low-level extension function with access to the public `FpvCtrls` API.
+     *
+     * @param extension - Function that receives the current `FpvCtrls` 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 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.
+ * @category Cfg
+ */
+export declare interface FpvCtrlsCfg {
+    /**
+     * Enables First Person View Controls.
+     * @default false
+     */
+    enable: boolean;
+    /**
+     * Loads First Person View Controls via dynamic import.
+     * @default false
+     */
+    load: boolean;
+    /**
+     * Minimum allowed vertical look angle in radians.
+     * @default 0
+     */
+    minPolarAngle: number;
+    /**
+     * Maximum allowed vertical look angle in radians.
+     * @default Math.PI
+     */
+    maxPolarAngle: number;
+    /**
+     * Speed factor for pointer movement.
+     * @default 0.1
+     */
+    pointerSpeed: number;
+    /**
+     * KeyboardEvent.code for moving forward.
+     * @default 'KeyW'
+     */
+    keyMoveForward: string;
+    /**
+     * KeyboardEvent.code for moving left.
+     * @default 'KeyA'
+     */
+    keyMoveLeft: string;
+    /**
+     * KeyboardEvent.code for moving backward.
+     * @default 'KeyS'
+     */
+    keyMoveBackward: string;
+    /**
+     * KeyboardEvent.code for moving right.
+     * @default 'KeyD'
+     */
+    keyMoveRight: string;
+    /**
+     * KeyboardEvent.code for moving up.
+     * @default 'KeyQ'
+     */
+    keyMoveUp: string;
+    /**
+     * KeyboardEvent.code for moving down.
+     * @default 'KeyE'
+     */
+    keyMoveDown: string;
+}
+
+/** @event Fired when an `FpvCtrls` event occurs and triggers the corresponding XState event. */
+export declare interface FpvCtrlsEvent {
+    /** Identifies this event type. */
+    type: 'FPVCTRLS_DISABLED' | 'FPVCTRLS_ENABLED' | 'FPVCTRLS_LOCK' | 'FPVCTRLS_UNLOCK' | 'FPVCTRLS_DISABLED';
+}
+
+/** Defines the FXAA anti-aliasing settings used to smooth jagged edges in the rendered image.
+ * @category Cfg
+ */
+export declare interface FxaaCfg {
+    /**
+     * Controls the sharpness used in the FXAA shader.
+     * @default 0.5
+     */
+    sharpness: number;
+}
+
+/** Defines the hemisphere light settings controlling ambient sky and ground illumination.
+ * @category Cfg
+ */
+export declare interface HemisphereCfg {
+    /**
+     * Activates the hemisphere light in the scene.
+     * @default false
+     */
+    enable: boolean;
+    /**
+     * Light color from above.
+     * @default 0xffffbb
+     */
+    skyColor: THREE_TYPE.ColorRepresentation;
+    /**
+     * Light color from below.
+     * @default 0x080820
+     */
+    groundColor: THREE_TYPE.ColorRepresentation;
+    /**
+     * Intensity of the hemisphere light.
+     * @default 1
+     */
+    intensity: number;
+}
+
+/**
+ * The `Light3D` class represents a managed light source.
+ * @category 3D Objects
+ */
+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.
+     * @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`.
+     *
+     * @param objGltf - The currently traversed `THREE.Light`.
+     * @public
+     *
+     * **Example**
+     * {@includeCode ../../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.
+ * @category Cfg
+ */
+export declare interface LightCfg {
+    /**
+     * Shadow map resolution along the horizontal axis.
+     * @default 2048
+     */
+    mapWidth: number;
+    /**
+     * Shadow map resolution along the vertical axis.
+     * @default 2048
+     */
+    mapHeight: number;
+    /**
+     * Constant shadow bias applied to reduce shadow acne.
+     * @default -0.00002
+     */
+    bias: number;
+    /**
+     * Normal-based shadow bias to further reduce shadow artifacts.
+     * @default 0.005
+     */
+    normalBias: number;
+    /**
+     * Near clipping plane of the light's shadow camera.
+     * @default 0.1
+     */
+    near: number;
+    /**
+     * Far clipping plane of the light's shadow camera.
+     * @default 5
+     */
+    far: number;
+}
+
+/** Defines the menu bar settings used to display licensed UI controls and branding.
+ * @category Cfg
+ */
+export declare interface MenuBarCfg {
+    /**
+     * Enables or disables the menu bar.
+     * @default true
+     */
+    enable: boolean;
+    /**
+     * Background color of the menu bar.
+     * @default '#F40B5780'
+     */
+    backgroundColor: THREE_TYPE.ColorRepresentation;
+    /**
+     * Encoded SVG logo used as the menu bar's CSS background image.
+     * @default ''
+     */
+    logo: string;
+}
+
+/**
+ * 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
+ */
+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.
+     * @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. */
+    reflectivesSSR: THREE_TYPE.Object3D[];
+    /* Excluded from this release type: __constructor */
+    /**
+     * Called for each traversed mesh during GLTF parsing. Stores the current `THREE.Mesh` in `this.obj`.
+     * @param objGltf - The currently traversed mesh.
+     * @public
+     *
+     * **Example**
+     * {@includeCode ../../examples/mesh3D-cube.ts}
+     */
+    protected onTraverse(objGltf: THREE_TYPE.Mesh): void;
+    /* Excluded from this release type: setReflectivesSSR */
+    /* Excluded from this release type: traverse */
+}
+
+/** Defines the mesh-specific rendering settings used to control shadows and frustum culling.
+ * @category Cfg
+ */
+export declare interface MeshCfg {
+    /**
+     * If `true`, the mesh will cast shadows.
+     * @default true
+     */
+    castShadow: boolean;
+    /**
+     * If `true`, the mesh will receive shadows cast by other objects.
+     * @default true
+     */
+    receiveShadow: boolean;
+    /**
+     * If `true`, the mesh will be culled when outside the camera's frustum.
+     * @default false
+     */
+    frustumCulled: boolean;
+}
+
+/** Defines the GLTF/GLB model loading settings used to fetch models and configure optional Draco decoding.
+ * @category Cfg
+ */
+export declare interface ModelCfg {
+    compression: {
+        /**
+         * Mesh compression used by the GLTF/GLB file.
+         * @default 'none'
+         */
+        mesh: 'none' | 'draco' | 'meshopt';
+        /**
+         * Texture compression used by the GLTF/GLB file.
+         * @default 'none'
+         */
+        texture: 'none' | 'webp' | 'ktx2';
+    };
+    /**
+     * The file path of your GLTF/GLB scene model. Set to `null` if no model should be loaded.
+     * @default null
+     */
+    file: string | null;
+    /**
+     * Public path to the Draco decoder files.
+     * @default '/draco/'
+     */
+    decoderPath: string;
+    /**
+     * Shows a loading progress bar while the model is being fetched.
+     * @default true
+     */
+    progressBar: boolean;
+}
+
+/** @event Fired when an error occurs while loading model assets and triggers the corresponding XState event. */
+export declare interface ModelErrorEvent {
+    /** Identifies this event type. */
+    type: 'MODEL_ERROR';
+    /** The caught error object. */
+    error: Error;
+}
+
+/** @event Fired while model assets are loading and triggers the corresponding XState event. */
+export declare interface ModelLoadingEvent {
+    /** Identifies this event type. */
+    type: 'MODEL_LOADING';
+    /** Loading progress in percent (0-100). */
+    loading: number;
+}
+
+declare class Modules {
+    gpuTier: any;
+    fxaaNode: any;
+    fxaaShader: any;
+    smaaPassClass: any;
+    smaaNode: any;
+    ssaoPassClass: any;
+    gtaoNodeClass: any;
+    ssrNode: any;
+    ssrPassClass: any;
+    paneClass: any;
+    createBrowserInspector: any;
+    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;
+    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;
+    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;
+    tslDirectionToColor: typeof THREE_WEBTSL_TYPE.directionToColor | null;
+    tslColorToDirection: typeof THREE_WEBTSL_TYPE.colorToDirection | 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>;
+    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>;
+    importTweakpane(): Promise<void>;
+}
+
+/**
+ * Wraps a `THREE.Object3D` and provides lifecycle hooks, scene integration, animation support, and position-change events. Extend this class to implement custom object behavior.
+ * @category 3D Objects
+ */
+export declare class Obj3D {
+    /** @public */
+    protected canvas: HTMLElement;
+    protected cfg: Cfg;
+    /** @public */
+    protected readonly cfgCtrl: Readonly<CfgCtrl>;
+    /* 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 */
+    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.
+     * @public
+     */
+    protected renderer: Readonly<THREE_TYPE.WebGLRenderer> | Readonly<THREE_WEBGPU_TYPE.WebGPURenderer>;
+    /**
+     * The `THREE.Scene` instance this object belongs to.
+     * @public
+     */
+    protected scene: Readonly<THREE_TYPE.Scene>;
+    /** Whether occlusion checking is enabled for this object. Default: **false** */
+    enableOcclusionCheck: boolean;
+    private readonly eventDispatcher;
+    private posScreen;
+    private posScreenLast;
+    private posWorld;
+    private posWorldLast;
+    private visible;
+    private visibleFrustum;
+    private visibleLast;
+    /* Excluded from this release type: visibleOcclusion */
+    /* Excluded from this release type: __constructor */
+    /**
+     * Registers a listener that is called whenever the specified event occurs.
+     * @param type - The event type to listen for.
+     * @param listener - Callback invoked when the event occurs.
+     * @returns A function that unsubscribes the listener.
+     */
+    addEventListener<TType extends Obj3DEvent['type']>(type: TType, listener: (event: Extract<Obj3DEvent, {
+        type: TType;
+    }>) => void): Unsubscribe;
+    private calcScreenPos;
+    protected checkWorldAndScreenPos(cam3D: Cam3D, obj: THREE_TYPE.Object3D): void;
+    protected checkVisible(): void;
+    /* Excluded from this release type: emitEvent */
+    /**
+     * Returns the object's screen position in canvas coordinates.
+     * @param cam3D - Camera used for projection to canvas coordinates.
+     * @returns The projected screen position in canvas coordinates, or `null` if no `THREE.Object3D` is assigned.
+     */
+    getScreenPosition(cam3D: Cam3D): {
+        x: number;
+        y: number;
+    } | null;
+    private isVisibleFrustum;
+    /**
+     * 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
+     */
+    protected onReady(): void;
+    /**
+     * Called once after the `THREE.Scene` is initialized, before an existing GLTF model is loaded.
+     * @public
+     */
+    protected onStart(): void;
+    /**
+     * Called once for each traversed child during GLTF parsing. Stores the currently traversed `THREE.Object3D` instance in `this.obj`.
+     * @param objGltf - The traversed `THREE.Object3D` instance.
+     * @public
+     */
+    protected onTraverse(objGltf: THREE_TYPE.Object3D): void;
+    /**
+     * Called on every animation frame update.
+     * @param deltaTime - Time elapsed since the previous frame in seconds.
+     * @public
+     */
+    protected onUpdate(deltaTime: number): void;
+    /* Excluded from this release type: ready */
+    /**
+     * Removes a previously registered listener for the specified event.
+     * @param type - The event type to remove the listener from.
+     * @param listener - Callback to remove from the event listeners.
+     */
+    removeEventListener<TType extends Obj3DEvent['type']>(type: TType, listener: (event: Extract<Obj3DEvent, {
+        type: TType;
+    }>) => void): void;
+    private resetEventStateIfNoListeners;
+    /* 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, cfgCtrl: CfgCtrl, name: string) => Objs3D;
+
+/** Defines all event types supported by `Obj3D.addEventListener`. */
+export declare type Obj3DEvent = Obj3DPosWorldEvent | Obj3DPosScreenEvent | Obj3DVisibleEvent | Obj3DPointerEvent;
+
+/**
+ * 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]>;
+};
+
+/** @event Fired when the user uses the pointer on an active object and triggers the corresponding XState event. */
+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;
+    /** The name of the object whose selected state changed. */
+    objName: string;
+}
+
+/** @event Fired when the screen position of a 3D object changes and triggers the corresponding XState event. */
+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;
+}
+
+/** @event Fired when the world position of a 3D object changes and triggers the corresponding XState event. */
+export declare interface Obj3DPosWorldEvent {
+    /** Identifies this event type. */
+    type: 'OBJ3D_POS_WORLD_CHANGED';
+    /** The object's position in world coordinates. */
+    posWorld: THREE_TYPE.Vector3;
+}
+
+/** @event Fired when the world or screen rotation of a 3D object changes and triggers the corresponding XState event. */
+export declare interface Obj3DRotWorldEvent {
+    /** Identifies this event type. */
+    type: 'OBJ3D_ROT_WORLD_CHANGED';
+    /** The object's rotation in world coordinates. */
+    rotWorld: THREE_TYPE.Euler;
+    /** The object's rotation projected into screen space. */
+    rotScreen: THREE_TYPE.Euler;
+}
+
+/** @event Fired when the visibility of a 3D object changes and triggers the corresponding XState event. */
+export declare interface Obj3DVisibleEvent {
+    /** Identifies this event type. */
+    type: 'OBJ3D_VISIBLE_CHANGED';
+    /** The object's visibility status. */
+    visible: boolean;
+}
+
+export declare type Objs3D = Cam3D | Light3D | Mesh3D | Obj3D;
+
+/**
+ * Integrates three.js OrbitControls directly in the engine's render loop, supporting runtime updates and dynamic enabling/disabling.
+ * @category Core
+ */
+export declare class OrbitCtrls {
+    private readonly cam3D;
+    private readonly canvas;
+    private readonly cfg;
+    private readonly engine;
+    private readonly events;
+    private readonly modules;
+    orbitControls: OrbitControls_2 | null;
+    private enableDamping;
+    private dampingFactor;
+    private minDistance;
+    private maxDistance;
+    private enableZoom;
+    private zoomSpeed;
+    private enableRotate;
+    private rotateSpeed;
+    private enablePan;
+    private panSpeed;
+    private autoRotate;
+    private autoRotateSpeed;
+    private minPolarAngle;
+    private maxPolarAngle;
+    private orbitCtrlsFirstChange;
+    private callback;
+    private listenerPointersStart;
+    private listenerPointersEnd;
+    private readonly touchPointerIds;
+    /* Excluded from this release type: __constructor */
+    /** Creates three.js `OrbitControls`. */
+    create(): void;
+    /** Disables three.js `OrbitControls` and cleans up the event listeners. */
+    disable(): void;
+    /** Enables three.js `OrbitControls` for the current camera. */
+    enable(): void;
+    /** Disposes three.js `OrbitControls` and removes them from the render loop. */
+    dispose(): void;
+    /**
+     * Returns whether three.js `OrbitControls` are currently enabled.
+     * @returns `true` if `OrbitControls` are currently enabled; otherwise, `false`.
+     */
+    isEnabled(): boolean;
+    /**
+     * Updates one or more three.js `OrbitControls` properties. `OrbitCtrls` must be enabled.
+     * @param params - Object containing any subset of orbit control parameters.
+     */
+    set(params: Partial<OrbitCtrlsCfg>): void;
+    /** Returns the current three.js `OrbitControls` configuration. */
+    get(): Partial<OrbitCtrlsCfg>;
+    /**
+     * Registers and executes a low-level extension function with access to the public `OrbitCtrls` API.
+     *
+     * @param extension - Function that receives the current `OrbitCtrls` 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: (orbitCtrls: OrbitCtrls) => void): void;
+    private updatePointersEnd;
+    private updatePointersStart;
+}
+
+/** Defines the Orbit Controls settings used to rotate, pan, zoom and constrain the camera around a target.
+ * @category Cfg
+ */
+export declare interface OrbitCtrlsCfg {
+    /**
+     * Enables automatic camera rotation.
+     * @default false
+     */
+    autoRotate: boolean;
+    /**
+     * Rotation speed of automatic rotation.
+     * @default 2.0
+     */
+    autoRotateSpeed: number;
+    /**
+     * Amount of damping applied per frame.
+     * @default 0.1
+     */
+    dampingFactor: number;
+    /**
+     * Enables OrbitControls.
+     * @default false
+     */
+    enable: boolean;
+    /**
+     * Enables smooth inertia-like camera movement.
+     * @default false
+     */
+    enableDamping: boolean;
+    /**
+     * Enables or disables camera panning.
+     * @default true
+     */
+    enablePan: boolean;
+    /**
+     * Enables or disables camera rotation.
+     * @default true
+     */
+    enableRotate: boolean;
+    /**
+     * Enables or disables zoom interaction.
+     * @default true
+     */
+    enableZoom: boolean;
+    /**
+     * Loads OrbitControls via dynamic import.
+     * @default false
+     */
+    load: boolean;
+    /**
+     * Maximum allowed distance between the camera and the target.
+     * @default Infinity
+     */
+    maxDistance: number;
+    /**
+     * Maximum allowed vertical orbit angle in degrees.
+     * @default 180
+     */
+    maxPolarAngle: number;
+    /**
+     * Minimum allowed distance between the camera and the target.
+     * @default 0
+     */
+    minDistance: number;
+    /**
+     * Minimum allowed vertical orbit angle in degrees.
+     * @default 0
+     */
+    minPolarAngle: number;
+    /**
+     * Speed factor for panning movement.
+     * @default 1.0
+     */
+    panSpeed: number;
+    /**
+     * Speed factor for camera rotation.
+     * @default 1.0
+     */
+    rotateSpeed: number;
+    /**
+     * Speed factor for zooming.
+     * @default 1.0
+     */
+    zoomSpeed: number;
+}
+
+/** @event Fired when an OrbitControls event occurs and triggers the corresponding XState event. */
+export declare interface OrbitCtrlsEvent {
+    /** Identifies this event type. */
+    type: 'ORBITCTRLS_CHANGED' | 'ORBITCTRLS_DISABLED' | 'ORBITCTRLS_ENABLED' | 'ORBITCTRLS_END' | 'ORBITCTRLS_START' | 'ORBITCTRLS_DISPOSED';
+}
+
+/**
+ * Defines which existing animation actions of the same object should be paused before a new clip is played.
+ * - `'all'`: Pauses all actions of the object.
+ * - `'finished'`: Pauses only actions of the object that are no longer active.
+ * - `'last'`: Pauses only the last matching action of the object.
+ * - `'none'`: Pauses no actions.
+ */
+export declare type PauseObjectActions = 'all' | 'finished' | 'last' | 'none';
+
+/** Defines the post-processing settings used by the rendering pipeline.
+ * @category Cfg
+ */
+export declare interface PostCfg {
+    /**
+     * Enables GPU-based auto activation for post-processing.
+     * @default true
+     */
+    auto: boolean;
+    /**
+     * Whether the GUI post-processing dropdown is open.
+     * @default false
+     */
+    guiOpened: boolean;
+    /** Anti-aliasing settings. */
+    aa: aaCfg;
+    /** Shared SSAO settings. */
+    ssao: SsaoCfg;
+    /** Shared SSR settings. */
+    ssr: SsrCfg;
+    /** WebGL post-processing settings. */
+    webgl: {
+        /** WebGL anti-aliasing settings. */
+        aa: {
+            /** WebGL FXAA settings. */
+            fxaa: FxaaCfg;
+        };
+        /** WebGL SSAO settings. */
+        ssao: SsaoWebGlCfg;
+        /** WebGL SSR settings. */
+        ssr: SsrWebGlCfg;
+    };
+    /** WebGPU post-processing settings. */
+    webgpu: {
+        /** WebGPU SSAO settings. */
+        ssao: SsaoWebGpuCfg;
+        /** WebGPU SSR settings. */
+        ssr: SsrWebGpuCfg;
+    };
+}
+
+/**
+ * The Raycast class manages pointer-based raycasting in a `THREE.Scene`. It tracks specified objects, detects cursor intersections with them, and triggers intersection and non-intersection events via
+ * the application state. The class dynamically enables or disables pointer listeners depending on the number of tracked objects. It also handles pointer events (click, down, up, move, enter, leave) for the
+ * intersected 3D objects.
+ * @category Core
+ */
+export declare class Raycast {
+    private readonly cam3D;
+    private readonly canvas;
+    private readonly cfg;
+    private readonly engine;
+    private readonly events;
+    private readonly objs3D;
+    private raycasterSelect;
+    private raycasterVisible;
+    private objsSelectTracked;
+    private objActive;
+    private objCandidate;
+    private closestObjCounter;
+    private isEnabled;
+    private callbackSelect;
+    private listenerClick;
+    private listenerDown;
+    private listenerMove;
+    private listenerUp;
+    private pointerEvent;
+    private posPrevPointerX;
+    private posPrevPointerY;
+    private posWorldObj;
+    private dirCamToObj;
+    private posNdcPointer;
+    /* Excluded from this release type: __constructor */
+    /** Enables pointer-based raycasting and adds all necessary pointer event listeners and the frame update callback. */
+    enable(): void;
+    /** Disables pointer-based raycasting and removes all pointer event listeners and the frame update callback. */
+    disable(): void;
+    /**
+     * Checks whether an object's world position is visible from the active camera without being occluded.
+     *
+     * @param obj - The object whose visibility should be tested.
+     * @returns `true` if no other object blocks the line of sight to the object's world position, otherwise `false`.
+     */
+    isVisibleOcclusion(obj: THREE_TYPE.Object3D): boolean;
+    private onClick;
+    private onPointerDown;
+    private onPointerEnter;
+    private onPointerLeave;
+    private onPointerMove;
+    private onPointerUp;
+    /**
+     * Begins tracking a list of scene objects for pointer intersection detection. If the raycaster is not yet listening for pointer movements, this method automatically attaches pointer event listeners
+     * (`pointermove`, `click`, `pointerdown`, `pointerup`).
+     *
+     * @param params - Parameter object.
+     * @param params.objs3D - The `Obj3D` instances to track.
+     */
+    trackSelectable({ objs3D }: {
+        objs3D: Obj3D[];
+    }): 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.
+     */
+    use(extension: (raycast: Raycast) => void): void;
+    /**
+     * Stops tracking the specified scene objects for ray intersection detection. It automatically removes the pointer event listeners if no tracked objects remain.
+     *
+     * @param params - Parameter object.
+     * @param params.objs3D - The `Obj3D` instances to untrack.
+     */
+    untrackSelectable({ objs3D }: {
+        objs3D: Obj3D[];
+    }): void;
+    /* Excluded from this release type: updateSelect */
+    private updatePointer;
+}
+
+/** Defines the raycasting settings used to detect selectable objects around the pointer.
+ * @category Cfg
+ */
+export declare interface RaycastCfg {
+    /**
+     * Circle radius around the pointer in pixels.
+     * @default 10
+     */
+    circleRadius: number;
+    /**
+     * Number of rays to cast around the circle.
+     * @default 12
+     */
+    circleSteps: number;
+    /**
+     * Number of closest objects to detect.
+     * @default 5
+     */
+    countClosestObjs: number;
+}
+
+/** Defines the renderer settings used to control frame timing, resolution, shadows, tone mapping and output color space.
+ * @category Cfg
+ */
+export declare interface RenderCfg {
+    /**
+     * Selects the rendering backend.
+     *
+     * - `webgl`: use `THREE.WebGLRenderer`
+     * - `webgpu`: use `THREE.WebGPURenderer`
+     * - `auto`: use WebGPU if supported, otherwise fall back to WebGL
+     *
+     * @default 'auto'
+     */
+    api: Renderer;
+    /**
+     * 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;
+    /**
+     * Enables or disables the maximum frames limiter.
+     * @default true
+     */
+    fpsLimiter: boolean;
+    /**
+     * Maximum frames per second.
+     * @default 30
+     */
+    fpsMax: number;
+    /**
+     * Maximum number of delta time history samples.
+     * @default 10
+     */
+    deltaTimesMax: number;
+    /**
+     * Activates the GUI module via lazy loading.
+     * @default false
+     */
+    gui: boolean;
+    /**
+     * Output color space.
+     * @default THREE.SRGBColorSpace
+     */
+    outputColorSpace: THREE_TYPE.ColorSpace;
+    /**
+     * Sets the renderer pixel ratio.
+     * @default 1
+     */
+    pixelRatio: number;
+    /**
+     * Enables or disables shadow maps.
+     * @default true
+     */
+    shadowMapEnabled: boolean;
+    /**
+     * Type of shadow map.
+     * @default THREE.PCFShadowMap
+     */
+    shadowMapType: THREE_TYPE.ShadowMapType;
+    /**
+     * Tone mapping algorithm.
+     * @default THREE.ACESFilmicToneMapping
+     */
+    toneMapping: THREE_TYPE.ToneMapping;
+    /**
+     * Tone mapping exposure value.
+     * @default 1.0
+     */
+    toneMappingExposure: number;
+    /**
+     * WebGL renderer configuration.
+     */
+    webgl: {
+        /**
+         * Parameters passed to `THREE.WebGLRenderer`.
+         * @default antialias: true, alpha: false, powerPreference: 'low-power'
+         */
+        parameters: THREE_TYPE.WebGLRendererParameters;
+    };
+    /**
+     * WebGPU renderer configuration.
+     */
+    webgpu: {
+        /**
+         * Parameters passed to `THREE.WebGPURenderer`.
+         * @default antialias: true, alpha: false
+         */
+        parameters: WebGpuRendererParameters;
+    };
+}
+
+/** Defines the available renderer backends. */
+export declare type Renderer = 'webgl' | 'webgpu' | 'auto';
+
+/** Defines the scene settings used to configure background, environment, model, fog and lights.
+ * @category Cfg
+ */
+export declare interface SceneCfg {
+    /**
+     * Custom element tag in which the canvas is rendered.
+     * @default 'comp-canvas'
+     */
+    canvas: string;
+    /**
+     * Whether the GUI scene dropdown is open.
+     * @default false
+     */
+    guiOpened: boolean;
+    /** Fog settings. */
+    fog: FogCfg;
+    /** Ambient light settings. */
+    ambientlight: AmbientlightCfg;
+    /** Hemisphere light settings. */
+    hemisphere: HemisphereCfg;
+}
+
+/** @event Fired when the scene is set up and ready and triggers the corresponding XState event. */
+export declare interface SceneReadyEvent {
+    /** Identifies this event type. */
+    type: 'SCENE_READY';
+}
+
+/** @event Fired after the scene has been rendered for the first time and triggers the corresponding XState event. */
+export declare interface SceneRenderedEvent {
+    /** Identifies this event type. */
+    type: 'SCENE_RENDERED';
+}
+
+/** Defines the SMAA anti-aliasing pass settings used to smooth jagged edges in the rendered image.
+ * @category Cfg
+ */
+export declare interface SmaaCfg {
+    /**
+     * Enables or disables SMAA.
+     * @default false
+     */
+    enable: boolean;
+    /**
+     * Whether the GUI SMAA dropdown is open.
+     * @default false
+     */
+    guiOpened: boolean;
+}
+
+/** Defines the screen-space ambient occlusion settings used to enhance depth and shading.
+ * @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.
+     * @default 8
+     */
+    kernelRadius: number;
+    /**
+     * Minimum distance between surfaces before AO applies.
+     * @default 0.005
+     */
+    minDistance: number;
+    /**
+     * Maximum distance for SSAO calculation.
+     * @default 0.1
+     */
+    maxDistance: number;
+}
+
+/** Defines the WebGPU screen-space ambient occlusion settings.
+ * @category Cfg
+ */
+export declare interface SsaoWebGpuCfg {
+    /**
+     * Defines the radius of the ambient occlusion in world space.
+     * @default 0.25
+     */
+    radius: number;
+    /**
+     * 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
+     */
+    resolutionScale: number;
+}
+
+/** Defines the shared screen-space reflection settings.
+ * @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
+     */
+    guiOpened: boolean;
+}
+
+/** Defines the WebGL screen-space reflection settings.
+ * @category Cfg
+ */
+export declare interface SsrWebGlCfg {
+    /**
+     * Whether multiple light bounces are calculated for reflections.
+     * @default false
+     */
+    bouncing: boolean;
+    /**
+     * Enables distance-based attenuation of reflections.
+     * @default true
+     */
+    distanceAttenuation: boolean;
+    /**
+     * Enables fresnel-based reflections.
+     * @default true
+     */
+    fresnel: boolean;
+    /**
+     * Enables infinite-thickness reflection mode.
+     * @default false
+     */
+    infiniteThick: boolean;
+    /**
+     * Controls the maximum distance a fragment can reflect.
+     * @default 180
+     */
+    maxDistance: number;
+    /**
+     * Reflection opacity value.
+     * @default 0.5
+     */
+    opacity: number;
+    /**
+     * Controls the cutoff thickness in reflection calculations.
+     * @default 0.018
+     */
+    thickness: number;
+    /**
+     * Enables blur on reflections.
+     * @default true
+     */
+    blur: boolean;
+    /**
+     * Resolution scale for effect computation.
+     * @default 1
+     */
+    resolutionScale: number;
+    /**
+     * Output configuration of the SSR pass.
+     * @default 0
+     */
+    output: number;
+    /**
+     * Whether SSR only affects selected objects.
+     * @default false
+     */
+    selective: boolean;
+    /**
+     * Whether the pass clears before rendering.
+     * @default true
+     */
+    clear: boolean;
+    /**
+     * Maximum roughness threshold for reflective objects.
+     * @default 0.5
+     */
+    maxRoughness: number;
+}
+
+/** Defines the WebGPU screen-space reflection settings.
+ * @category Cfg
+ */
+export declare interface SsrWebGpuCfg {
+    /**
+     * Enables distance-based attenuation of reflections.
+     * @default true
+     */
+    distanceAttenuation: boolean;
+    /**
+     * Enables fresnel-based reflections.
+     * @default true
+     */
+    fresnel: boolean;
+    /**
+     * Maximum SSR ray distance.
+     * @default 180
+     */
+    maxDistance: number;
+    /**
+     * Reflection opacity value.
+     * @default 0.5
+     */
+    opacity: number;
+    /**
+     * Ray thickness used for SSR intersection tests.
+     * @default 0.018
+     */
+    thickness: number;
+    /**
+     * SSR render resolution scale.
+     * @default 1
+     */
+    resolutionScale: number;
+    /**
+     * SSR quality factor.
+     * @default 0.5
+     */
+    quality: number;
+    /**
+     * SSR blur quality level.
+     * @default 1
+     */
+    blurQuality: 1 | 2 | 3;
+}
+
+/**
+ * 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.
+ * @category Core
+ */
+export declare class StateMachine {
+    private readonly cfg;
+    private readonly modules;
+    private actor;
+    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.
+     * @param stateMachine - A fully constructed XState 5 machine.
+     *
+     * **Example**
+     * {@includeCode ../examples/app-statemachine.ts}
+
+     */
+    start(stateMachine: AnyStateMachine): void;
+}
+
+/** Defines the application state machine settings used to control inspector-related state.
+ * @category Cfg
+ */
+export declare interface StateMachineCfg {
+    /**
+     * Imports statelyai/inspect module dynamically and enables inspector mode.
+     * @default false
+     */
+    inspector: boolean;
+}
+
+/** Defines the built-in engine stats panel settings used to display FPS, CPU/frame timing and renderer.info values.
+ * @category Cfg
+ */
+export declare interface StatsCfg {
+    /**
+     * Enables or disables stats data collection.
+     * @default true
+     */
+    enabled: boolean;
+    /**
+     * Shows the FPS value.
+     * @default true
+     */
+    fps: boolean;
+    /**
+     * Shows the measured CPU/update time in milliseconds.
+     * @default true
+     */
+    cpu: boolean;
+    /**
+     * Shows the frame time in milliseconds.
+     * @default true
+     */
+    frame: boolean;
+    /**
+     * Shows renderer.info.render.calls.
+     * @default true
+     */
+    calls: boolean;
+    /**
+     * Shows renderer.info.render.triangles.
+     * @default true
+     */
+    triangles: boolean;
+    /**
+     * Shows renderer.info.render.lines.
+     * @default true
+     */
+    lines: boolean;
+    /**
+     * Shows renderer.info.render.points.
+     * @default true
+     */
+    points: boolean;
+    /**
+     * Shows renderer.info.memory.geometries.
+     * @default true
+     */
+    geometries: boolean;
+    /**
+     * Shows renderer.info.memory.textures.
+     * @default true
+     */
+    textures: boolean;
+    /**
+     * Shows the number of compiled WebGL programs from renderer.info.programs.
+     * @default true
+     */
+    programs: boolean;
+    /**
+     * Refresh rate of the displayed values.
+     * @default 10
+     */
+    logsPerSecond: number;
+}
+
+/** Function returned by an event subscription. Calling it removes the associated listener. */
+export declare type Unsubscribe = () => void;
+
+export declare type WebGpuRendererParameters = NonNullable<ConstructorParameters<typeof THREE_WEBGPU_TYPE.WebGPURenderer>[0]>;
+
+/** @event Fired when the window size changes and triggers the corresponding XState event. */
+export declare interface WindowResizeEvent {
+    /** Identifies this event type. */
+    type: 'WINDOW_RESIZE';
+}
+
+export { }