illutions 0.25.0 → 0.27.0

package/dist/main.d.ts

@@ -18,6 +18,8 @@ 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 { ReflectorForSSRPass } from 'three/addons/objects/ReflectorForSSRPass.js';
 import { RenderPass } from 'three/addons/postprocessing/RenderPass.js';
 import { ShaderPass } from 'three/addons/postprocessing/ShaderPass.js';
@@ -30,6 +32,7 @@ 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.
@@ -42,10 +45,10 @@ export declare interface AaCfg {
      */
     guiOpened: boolean;
     /**
-     * Selects the anti-aliasing mode.
+     * Selects the anti-aliasing mode. TRAA automatically falls back to FXAA when WebGL is used.
      * @default 'none'
      */
-    mode: 'none' | 'fxaa' | 'smaa';
+    mode: 'none' | 'fxaa' | 'smaa' | 'traa';
 }
 
 export declare type ActionFadeMode = 'in' | 'out';
@@ -75,7 +78,7 @@ export declare interface AmbientlightCfg {
 /** @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';
+    type: 'Anim_Complete' | 'Anim_Start';
     /** The name of the `THREE.Object3D` whose animation changed state. */
     objName: string;
     /** The name of the calling method. */
@@ -85,7 +88,7 @@ export declare interface AnimEvent {
 /** @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';
+    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. */
@@ -97,12 +100,13 @@ export declare interface AnimFadeEvent {
 }
 
 /**
- * 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`.
+ * 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.
  * @category Core
  */
 export declare class App<TClasses extends Classes = {}> {
     readonly audio: Audio_2;
+    private readonly compCtrls;
     readonly engine: Engine;
     readonly envCtrls: EnvCtrls;
     readonly events: Events;
@@ -172,19 +176,19 @@ declare class Audio_2 {
     }): boolean;
     private loadSound;
     /**
-     * Loads an audio file without playing it and sends an `AUDIO_LOADED` event when the sound is ready.
+     * Loads an audio file without playing it and sends an `Audio_Loaded` event when the sound is ready.
      * @param params - The sound options.
      */
     load({ name, url, object, volume, fade, loop }: SoundParams): void;
     /**
      * Loads an audio file and plays it automatically when loading is complete.
-     * Use this method when no separate `AUDIO_LOADED` handling is required.
+     * Use this method when no separate `Audio_Loaded` handling is required.
      * @param params - The sound options.
      */
     loadAndPlay({ name, url, object, volume, fade, loop }: SoundParams): void;
     /**
      * Plays an audio that has finished loading, with a smooth fade-in.
-     * When using {@link load}, call this method after receiving the matching `AUDIO_LOADED` event.
+     * 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.
@@ -291,7 +295,7 @@ 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';
+    type: 'Audio_Loaded';
     /** The unique name assigned to the loaded sound. */
     soundName: string;
 }
@@ -437,7 +441,7 @@ export declare interface CamPerspectiveCfg extends CamBaseCfg {
 /** @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';
+    type: 'Canvas_Key_Down' | 'Canvas_Key_Up';
     /** Native keyboard event from the canvas interaction. */
     event: KeyboardEvent;
 }
@@ -445,7 +449,7 @@ export declare interface CanvasKeyEvent {
 /** @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';
+    type: 'Canvas_Click' | 'Canvas_Pointer_Down' | 'Canvas_Pointer_Move' | 'Canvas_Pointer_Up';
     /** Native pointer event from the canvas interaction. */
     event: PointerEvent;
 }
@@ -459,6 +463,8 @@ export declare interface Cfg {
     audio: AudioCfg;
     /** Camera settings. */
     cam: CamCfg;
+    /** Component settings. */
+    comps: CompsCfg;
     /** Debug settings. */
     debug: DebugCfg;
     /** Environment controls settings. */
@@ -507,7 +513,7 @@ export declare type Classes<TObj3DClasses extends Record<string, Obj3DClass> = {
 /** @event Fired when a clip starts, completes, is canceled, fades its weight, or changes its playback speed. */
 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';
+    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;
     /** The name of the calling method. */
@@ -531,21 +537,31 @@ export declare class Comp extends HTMLElement {
     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.
+    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.
-     * @param params.enableOcclusionCheck - Whether to enable occlusion visibility checks. Default: **false**
      */
-    follow({ obj, enableOcclusionCheck }: {
+    follow({ obj }: {
         obj: Obj3D | string;
-        enableOcclusionCheck?: boolean;
     }): void;
-    /** Stops this component from following the currently subscribed {@link Obj3D}. */
-    unfollow(): 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
@@ -560,12 +576,27 @@ export declare class Comp extends HTMLElement {
      */
     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;
 }
 
 /** 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[] }
@@ -575,6 +606,47 @@ export declare type CompInsts<T extends Record<string, CompClass>> = {
     [K in keyof T]: InstanceType<T[K]>[];
 };
 
+/** @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.
+ * @category Cfg
+ */
+export declare interface CompsCfg {
+    /** Screen-space overlap settings. */
+    overlap: CompsOverlapCfg;
+}
+
+/**
+ * Defines screen-space overlap settings for components.
+ * @category Cfg
+ */
+export declare interface CompsOverlapCfg {
+    /**
+     * Minimum spacing in pixels between visible components.
+     * @default 20
+     */
+    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.
  * @category Cfg
@@ -605,10 +677,12 @@ export declare class Engine {
     private readonly objs3D;
     private readonly cfg;
     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 */
@@ -620,6 +694,7 @@ export declare class Engine {
     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 */
@@ -641,6 +716,7 @@ export declare class Engine {
     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.
@@ -665,7 +741,7 @@ export declare class Engine {
      *
      * {@link AnimEvent}
      */
-    animCamCurveToTarget({ camTarget, aimTarget, radiusOut, duration, ease }: {
+    animCamCurveTo({ camTarget, aimTarget, radiusOut, duration, ease }: {
         camTarget: THREE_TYPE.Vector3 | string | Obj3D;
         aimTarget?: THREE_TYPE.Vector3 | string | Obj3D;
         radiusOut?: number;
@@ -689,7 +765,7 @@ export declare class Engine {
      *
      * {@link AnimEvent}
      */
-    animCamToObj({ target, duration, ease, dist }: {
+    animCamTo({ target, duration, ease, dist }: {
         target: string | Obj3D;
         duration?: number;
         ease?: string;
@@ -746,7 +822,7 @@ export declare class Engine {
     }): void;
     private calcEaseArea;
     /**
-     * Selects the active anti-aliasing mode. The modes `'fxaa'` and `'smaa'` lazy-load their required modules.
+     * 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.
      */
     enableAaMode(aaMode: Cfg['post']['aa']['mode']): Promise<void>;
@@ -763,7 +839,6 @@ export declare class Engine {
     private isPostCfg;
     /* Excluded from this release type: isPostEnabled */
     private isPostGpu;
-    private loadScene;
     /**
      * Finds a Three.js animation clip by name and plays it through the `THREE.AnimationMixer`.
      *
@@ -936,7 +1011,7 @@ export declare class Engine {
      * @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`.
+     * 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**
@@ -1096,6 +1171,22 @@ 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;
+}
+
 /**
  * Internal event dispatcher for the engine.
  * @category Core
@@ -1106,7 +1197,7 @@ export declare class Events {
     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(). */
+    /** 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 */
@@ -1123,6 +1214,10 @@ export declare class Events {
     /* 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.
@@ -1297,7 +1392,7 @@ export declare interface FpvCtrlsCfg {
 /** @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';
+    type: 'FpvCtrls_Disabled' | 'FpvCtrls_Enabled' | 'FpvCtrls_Lock' | 'FpvCtrls_Unlock';
 }
 
 /**
@@ -1462,6 +1557,11 @@ export declare interface LightCfg {
      * @default true
      */
     castShadow: boolean;
+    /**
+     * Loads and initializes the renderer-specific LTC data required by RectAreaLight.
+     * @default false
+     */
+    rectArea: boolean;
     /**
      * Shadow map resolution along the horizontal axis.
      * @default 512
@@ -1494,6 +1594,8 @@ 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.
@@ -1591,10 +1693,10 @@ export declare interface ModelCfg {
         texture: 'none' | 'webp' | 'ktx2';
     };
     /**
-     * The file path of your GLTF/GLB scene model. Set to `null` if no model should be loaded.
-     * @default null
+     * 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.
+     * @default []
      */
-    file: string | null;
+    file: string[];
     /**
      * Public path to the Draco decoder files.
      * @default 'draco/'
@@ -1610,7 +1712,7 @@ export declare interface ModelCfg {
 /** @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';
+    type: 'Model_Error';
     /** The caught error object. */
     error: Error;
 }
@@ -1618,9 +1720,11 @@ export declare interface ModelErrorEvent {
 /** @event Fired while model assets are loading and triggers the corresponding XState event. */
 export declare interface ModelLoadingEvent {
     /** Identifies this event type. */
-    type: 'MODEL_LOADING';
+    type: 'Model_Loading';
     /** Loading progress in percent (0-100). */
     loading: number;
+    /** One-based index of the model level currently loading. */
+    level: number;
 }
 
 declare class Modules {
@@ -1629,6 +1733,7 @@ declare class Modules {
     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;
@@ -1644,6 +1749,9 @@ declare class Modules {
     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;
@@ -1651,6 +1759,8 @@ declare class Modules {
     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;
@@ -1677,6 +1787,7 @@ declare class Modules {
     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>;
@@ -1686,11 +1797,12 @@ declare class Modules {
     importStatelyAi(): Promise<void>;
     importThreeTsl(): Promise<void>;
     importThreeWebGpu(): Promise<void>;
+    importTRAANode(aaMode: Cfg['post']['aa']['mode']): 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.
+ * 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
  */
 export declare class Obj3D {
@@ -1714,17 +1826,23 @@ export declare class Obj3D {
      * @public
      */
     protected scene: Readonly<THREE_TYPE.Scene>;
-    /** Whether occlusion checking is enabled for this object. Default: **false** */
-    enableOcclusionCheck: boolean;
-    private readonly eventDispatcher;
+    /* Excluded from this release type: eventDispatcher */
+    private posNdc;
     private posScreen;
     private posScreenLast;
     private posWorld;
     private posWorldLast;
+    private posCamWorld;
+    private posWorldOccl;
+    private posCamWorldOccl;
+    private quatWorld;
+    private quatWorldLast;
+    private rotWorld;
     private visible;
     private visibleFrustum;
+    private visibleFrustumLast;
     private visibleLast;
-    /* Excluded from this release type: visibleOcclusion */
+    private visibleOccl;
     /* Excluded from this release type: __constructor */
     /**
      * Registers a listener that is called whenever the specified event occurs.
@@ -1735,20 +1853,23 @@ export declare class Obj3D {
     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;
+    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.
      * @returns The projected screen position in canvas coordinates, or `null` if no `THREE.Object3D` is assigned.
      */
-    getScreenPosition(cam3D: Cam3D): {
+    getScreenPos(cam3D: Cam3D): {
         x: number;
         y: number;
     } | null;
-    private isVisibleFrustum;
+    /* 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.
      * @public
@@ -1780,7 +1901,7 @@ export declare class Obj3D {
     removeEventListener<TType extends Obj3DEvent['type']>(type: TType, listener: (event: Extract<Obj3DEvent, {
         type: TType;
     }>) => void): void;
-    private resetEventStateIfNoListeners;
+    private resetEventState;
     /* Excluded from this release type: start */
     /* Excluded from this release type: traverse */
     /* Excluded from this release type: update */
@@ -1790,7 +1911,15 @@ export declare class Obj3D {
 export declare type Obj3DClass = new (canvas: HTMLElement, cfg: Cfg, name: string) => Objs3D;
 
 /** Defines all event types supported by `Obj3D.addEventListener`. */
-export declare type Obj3DEvent = Obj3DPosWorldEvent | Obj3DPosScreenEvent | Obj3DVisibleEvent | Obj3DPointerEvent;
+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.
@@ -1804,44 +1933,48 @@ export declare type Obj3DInsts<T extends Record<string, Obj3DClass>> = {
 /** @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';
+    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. */
+    /** The name of the object receiving the pointer event. */
     objName: string;
 }
 
-/** @event Fired when the screen position of a 3D object changes and triggers the corresponding XState event. */
+/**
+ * @event Fired when the screen position of a 3D object changes.
+ */
 export declare interface Obj3DPosScreenEvent {
     /** Identifies this event type. */
-    type: 'OBJ3D_POS_SCREEN_CHANGED';
+    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. */
+/**
+ * @event Fired when the world position of a 3D object changes.
+ */
 export declare interface Obj3DPosWorldEvent {
     /** Identifies this event type. */
-    type: 'OBJ3D_POS_WORLD_CHANGED';
+    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. */
+/**
+ * @event Fired when the world rotation of a 3D object changes.
+ */
 export declare interface Obj3DRotWorldEvent {
     /** Identifies this event type. */
-    type: 'OBJ3D_ROT_WORLD_CHANGED';
+    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. */
+/** @event Fired when the combined frustum and occlusion 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. */
+    type: 'Obj3D_Visible_Changed';
+    /** Whether the object is inside the camera frustum and not occluded. */
     visible: boolean;
 }
 
@@ -1988,7 +2121,7 @@ export declare interface OrbitCtrlsCfg {
 /** @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';
+    type: 'OrbitCtrls_Changed' | 'OrbitCtrls_Disabled' | 'OrbitCtrls_Enabled' | 'OrbitCtrls_End' | 'OrbitCtrls_Start' | 'OrbitCtrls_Disposed';
 }
 
 /**
@@ -2031,7 +2164,7 @@ export declare interface PostCfg {
 /** @event Fired after the progress bar has finished hiding and triggers the corresponding XState event. */
 export declare interface ProgressBarHiddenEvent {
     /** Identifies this event type. */
-    type: 'PROGRESSBAR_HIDDEN';
+    type: 'ProgressBar_Hidden';
 }
 
 /**
@@ -2045,16 +2178,20 @@ export declare class Raycast {
     private readonly canvas;
     private readonly cfg;
     private readonly engine;
-    private readonly events;
     private readonly objs3D;
-    private raycasterSelect;
+    private raycasterPick;
     private raycasterVisible;
-    private objsSelectTracked;
+    private objsOccluders;
+    private readonly objsOccls;
+    private readonly objsPickables;
     private objActive;
     private objCandidate;
     private closestObjCounter;
+    private indexOcclNext;
+    private timeOcclNext;
     private isEnabled;
-    private callback;
+    private callbackOccls;
+    private callbackPointerHover;
     private listenerClick;
     private listenerCancel;
     private listenerDown;
@@ -2068,18 +2205,14 @@ export declare class Raycast {
     private dirCamToObj;
     private posNdcPointer;
     /* Excluded from this release type: __constructor */
+    private checkOcclVisible;
     /** 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;
-    private getObjectAtPointer;
-    /**
-     * 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 getObjAtPointer;
+    private getOcclState;
+    /* Excluded from this release type: getOcclVisible */
     private onCanvasClick;
     private onCanvasPointerLeave;
     private onCanvasPointerMove;
@@ -2090,6 +2223,19 @@ export declare class Raycast {
     private onPointerEnter;
     private onPointerLeave;
     private onPointerMove;
+    /* Excluded from this release type: resetOcclState */
+    /** Removes the explicit occlusion-object restriction so that all scene objects are checked again. */
+    resetOccluders(): void;
+    /**
+     * Restricts occlusion raycasts to the specified scene objects. Without an explicit restriction, all scene objects are checked.
+     *
+     * @param params - Parameter object.
+     * @param params.objs3D - The `Obj3D` instances that may block visibility.
+     */
+    setOccluders({ objs3D }: {
+        objs3D: Obj3D[];
+    }): void;
+    /* Excluded from this release type: trackOccl */
     /**
      * 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`, `pointercancel`, `pointerdown`, `pointerleave`, `pointerup`).
@@ -2097,33 +2243,45 @@ export declare class Raycast {
      * @param params - Parameter object.
      * @param params.objs3D - The `Obj3D` instances to track.
      */
-    trackSelectables({ objs3D }: {
+    trackPickables({ 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;
+    /* Excluded from this release type: untrackOccl */
     /**
      * 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 }: {
+    untrackPickables({ objs3D }: {
         objs3D: Obj3D[];
     }): void;
-    /* Excluded from this release type: updatePointerHover */
+    /**
+     * 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;
+    private updateOccls;
+    private updatePointerHover;
     private updatePointerPosition;
 }
 
 /**
- * Defines the raycasting settings used to detect selectable objects around the pointer.
+ * Defines the raycasting settings used to detect pickable objects around the pointer.
  * @category Cfg
  */
 export declare interface RaycastCfg {
+    /**
+     * Time in milliseconds over which all pending occlusion checks are distributed once. A value of `0` processes all pending checks in one frame.
+     * @default 0
+     */
+    occlInterval: number;
+    /**
+     * Relative movement threshold used to request a new occlusion check. The value is multiplied by the current distance between the camera and the tracked object. A value of `0` reacts to every position change.
+     * @default 0.01
+     */
+    occlMoveFactor: number;
     /**
      * Circle radius around the pointer in pixels.
      * @default 10
@@ -2224,7 +2382,7 @@ export declare interface RenderCfg {
          * Whether renderer-level anti-aliasing is enabled.
          * @default false
          */
-        aa: boolean;
+        antialias: boolean;
     };
     /**
      * WebGL-specific renderer configuration.
@@ -2275,13 +2433,13 @@ export declare interface SceneCfg {
 /** @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';
+    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';
+    type: 'Scene_Rendered';
 }
 
 /**
@@ -2413,6 +2571,21 @@ export declare interface SsrCfg {
      * @default false
      */
     guiOpened: boolean;
+    /**
+     * Controls the maximum distance a fragment can reflect.
+     * @default 180
+     */
+    maxDistance: number;
+    /**
+     * Controls the cutoff thickness in reflection calculations.
+     * @default 0.018
+     */
+    thickness: number;
+    /**
+     * Resolution scale for effect computation.
+     * @default 1
+     */
+    resolutionScale: number;
 }
 
 /**
@@ -2440,31 +2613,16 @@ export declare interface SsrWebGlCfg {
      * @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
@@ -2492,36 +2650,11 @@ export declare interface SsrWebGlCfg {
  * @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 intensity value.
      * @default 0.5
      */
     intensity: 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
@@ -2587,7 +2720,7 @@ export declare type WebGpuRendererParams = NonNullable<ConstructorParameters<typ
 /** @event Fired when the window size changes and triggers the corresponding XState event. */
 export declare interface WindowResizeEvent {
     /** Identifies this event type. */
-    type: 'WINDOW_RESIZE';
+    type: 'Window_Resize';
 }
 
 export { }