illutions 0.24.1 → 0.26.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,12 +45,14 @@ 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';
+
 /**
  * Defines the ambient light settings controlling global scene illumination.
  * @category Cfg
@@ -95,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;
@@ -296,8 +302,8 @@ export declare interface AudioLoadedEvent {
 
 /**
  * Defines how an animation action is blended with other active actions.
- * - `'normal'`: Blends the action's values with other normal actions according to their weights.
- * - `'additive'`: Adds the action's values to the current animation result according to its weight.
+ * - 'normal': Blends the action's values with other normal actions according to their weights.
+ * - 'additive': Adds the action's values to the current animation result according to its weight.
  */
 export declare type BlendMode = 'normal' | 'additive';
 
@@ -457,6 +463,8 @@ export declare interface Cfg {
     audio: AudioCfg;
     /** Camera settings. */
     cam: CamCfg;
+    /** Component settings. */
+    comps: CompsCfg;
     /** Debug settings. */
     debug: DebugCfg;
     /** Environment controls settings. */
@@ -502,28 +510,18 @@ export declare type Classes<TObj3DClasses extends Record<string, Obj3DClass> = {
     comps?: TCompClasses;
 };
 
-/** @event Fired when a clip starts or finishes playing and triggers the corresponding XState event. */
+/** @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';
-    /** 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. */
+    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. */
     fct: string;
     /** The associated animation action, when available. */
     action?: THREE_TYPE.AnimationAction;
+    /** Whether the clip weight is fading in or out. */
+    fadeMode?: ActionFadeMode;
 }
 
 declare type ColorNode = THREE_WEBGPU_TYPE.Node<'vec4'>;
@@ -539,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
@@ -568,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[] }
@@ -583,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
@@ -610,12 +674,10 @@ export declare class Engine {
     private readonly cam3D;
     private readonly events;
     private readonly modules;
-    private readonly comps;
     private readonly objs3D;
     private readonly cfg;
     private readonly infoBox;
-    private actionObserver;
-    private readonly objActions;
+    private actionCtrls;
     private gltf;
     private mixer;
     private callbacks;
@@ -630,6 +692,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 */
@@ -652,7 +715,6 @@ export declare class Engine {
     /* Excluded from this release type: __constructor */
     /* Excluded from this release type: init */
     private initWebGpuRenderer;
-    private addActionToObj;
     /**
      * Registers a callback that is executed on every requestAnimationFrame update.
      * @param {(deltaTime: number) => void} cb - Callback executed once per frame with `deltaTime`.
@@ -676,7 +738,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;
@@ -700,7 +762,7 @@ export declare class Engine {
      *
      * {@link AnimEvent}
      */
-    animCamToObj({ target, duration, ease, dist }: {
+    animCamTo({ target, duration, ease, dist }: {
         target: string | Obj3D;
         duration?: number;
         ease?: string;
@@ -756,10 +818,8 @@ export declare class Engine {
         [key: string]: any;
     }): void;
     private calcEaseArea;
-    private stopObjActions;
-    private finishAction;
     /**
-     * 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>;
@@ -781,35 +841,37 @@ export declare class Engine {
      * Finds a Three.js animation clip by name and plays it through the `THREE.AnimationMixer`.
      *
      * @param params - Parameters for controlling the animation playback.
-     * @param params.obj - The name of the object whose animation clip should be played.
+     * @param params.layer - The freely named layer used to group animation actions.
      * @param params.clip - The name of the animation clip to play.
      * @param params.blendMode - How the action is blended with other active actions. Default: **'normal'**
      * @param params.finishMode - Whether the final pose is held or faded out after the final loop. Default: **'hold'**
-     * @param params.loop - Number of plays or `'infinite'` for endless looping. Default: **1**
-     * @param params.stopMode - Which previous actions of the same object are stopped before playback. Default: **'all'**
+     * @param params.loopMode - Number of plays or `'infinite'` for endless looping. Default: **1**
+     * @param params.stopMode - Which previous actions of the same layer are stopped before playback. Default: **'all'**
      * @param params.fadeDuration - Duration in seconds for fading affected previous actions out and the new action in. Default: **0**
      * @param params.fadeDurationFinish - Duration in seconds for `finishMode: 'fadeOut'`. Default: **0**
      * @param params.reverse - If `true`, plays the clip in reverse. Default: **false**
-     * @param params.reset - If `true`, resets the clip before playback. Default: **false**
+     * @param params.reset - If `true`, resets the clip before a new playback. Default: **false**
      * @param params.startSpeed - Initial playback speed for speed interpolation. Default: **0**
      * @param params.endSpeed - Target playback speed. Default: **1**
      * @param params.duration - Duration in seconds for speed interpolation. Default: **0**
      * @param params.ease - GSAP easing function name. Default: **'power1.inOut'**
      *
      * @remarks
-     * `finishMode` and `fadeDurationFinish` have no effect when `loop` is `'infinite'`.
+     * Calling a running or fading-in action again is ignored. A finished or stopped action starts again, while an unfinished fading-out action continues at its current time and fades back in from its current weight.
+     *
+     * `finishMode` and `fadeDurationFinish` have no effect when `loopMode` is `'infinite'`.
      *
      * **Events**
      *
      * {@link ClipEvent}
      */
-    playClip({ obj, clip: clipName, blendMode, finishMode, loop, stopMode, fadeDuration, fadeDurationFinish, reverse, reset, startSpeed, endSpeed, duration, ease }: {
-        obj: string;
+    playClip({ layer, clip: clipName, blendMode, finishMode, loopMode, stopMode, fadeDuration, fadeDurationFinish, reverse, reset, startSpeed, endSpeed, duration, ease }: {
+        layer: string;
         clip: string;
         singleAction?: boolean;
         blendMode?: BlendMode;
         finishMode?: FinishMode;
-        loop?: LoopMode;
+        loopMode?: LoopMode;
         stopMode?: StopMode;
         fadeDuration?: number;
         fadeDurationFinish?: number;
@@ -824,30 +886,31 @@ export declare class Engine {
      * Finds a camera animation clip by name and plays it through the `THREE.AnimationMixer`.
      *
      * @param params - Parameters for controlling the camera animation playback.
-     * @param params.obj - The name of the camera object whose animation clip should be played.
+     * @param params.layer - The freely named layer used to group camera animation actions.
      * @param params.clip - The name of the camera animation clip to play.
      * @param params.blendMode - How the action is blended with other active actions. Default: **'normal'**
-     * @param params.loop - Number of plays or `'infinite'` for endless looping. Default: **1**
-     * @param params.stopMode - Which previous actions of the same object are stopped before playback. Default: **'all'**
+     * @param params.loopMode - Number of plays or `'infinite'` for endless looping. Default: **1**
+     * @param params.stopMode - Which previous actions of the same layer are stopped before playback. Default: **'all'**
      * @param params.fadeDuration - Duration in seconds for fading affected previous actions out and the new action in. Default: **0**
-
      * @param params.reverse - If `true`, plays the clip in reverse. Default: **false**
-     * @param params.reset - If `true`, resets the clip before playback. Default: **false**
+     * @param params.reset - If `true`, resets the clip before a new playback. Default: **false**
      * @param params.startSpeed - Initial playback speed for speed interpolation. Default: **0**
      * @param params.endSpeed - Target playback speed. Default: **1**
      * @param params.duration - Duration in seconds for speed interpolation. Default: **0**
      * @param params.ease - GSAP easing function name. Default: **'power1.inOut'**
      *
-
+     * @remarks
+     * Calling a running or fading-in action again is ignored. A finished or stopped action starts again, while an unfinished fading-out action continues at its current time and fades back in from its current weight.
+     *
      * **Events**
      *
      * {@link ClipEvent}
      */
-    playClipCam({ obj, clip: clipName, blendMode, loop, stopMode, fadeDuration, reverse, reset, startSpeed, endSpeed, duration, ease }: {
-        obj: string;
+    playClipCam({ layer, clip: clipName, blendMode, loopMode, stopMode, fadeDuration, reverse, reset, startSpeed, endSpeed, duration, ease }: {
+        layer: string;
         clip: string;
         blendMode?: BlendMode;
-        loop?: LoopMode;
+        loopMode?: LoopMode;
         stopMode?: StopMode;
         fadeDuration?: number;
         reverse?: boolean;
@@ -946,12 +1009,12 @@ 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, 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.
+     * The method gradually reduces the clip's playback speed to zero when `fadeOut` is greater than zero. It emits `CLIP_SPEED_START`, `CLIP_SPEED_COMPLETE`, and finally `CLIP_CANCEL`.
+     * If no speed transition is specified, the clip is canceled immediately.
      *
      * **Events**
      *
-     * {@link ClipFadeEvent}
+     * {@link ClipEvent}
      */
     stopAnimClip({ clipName, fadeOut, ease }: {
         clipName: string;
@@ -1122,7 +1185,6 @@ export declare class Events {
     /* Excluded from this release type: animFade */
     /* Excluded from this release type: audioLoaded */
     /* Excluded from this release type: clip */
-    /* Excluded from this release type: clipFade */
     /* Excluded from this release type: modelError */
     /* Excluded from this release type: modelLoading */
     /**
@@ -1136,8 +1198,8 @@ export declare class Events {
 
 /**
  * Defines how an animation action behaves after its final loop.
- * - `'hold'`: Keeps the action enabled and holds its final pose.
- * - `'fadeOut'`: Fades the action out using `fadeDurationFinish`, or disables it immediately when the duration is `0`.
+ * - 'hold': Keeps the action enabled and holds its final pose.
+ * - 'fadeOut': Fades the action out using fadeDurationFinish, or disables it immediately when the duration is 0.
  */
 export declare type FinishMode = 'hold' | 'fadeOut';
 
@@ -1308,7 +1370,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';
 }
 
 /**
@@ -1473,6 +1535,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
@@ -1507,8 +1574,8 @@ export declare interface LightCfg {
 
 /**
  * Defines how often an animation action is played.
- * - `number`: Plays the action the specified positive number of times.
- * - `'infinite'`: Repeats the action indefinitely.
+ * - number: Plays the action the specified positive number of times.
+ * - 'infinite': Repeats the action indefinitely.
  */
 export declare type LoopMode = number | 'infinite';
 
@@ -1640,6 +1707,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;
@@ -1655,6 +1723,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;
@@ -1662,6 +1733,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;
@@ -1688,6 +1761,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>;
@@ -1697,11 +1771,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 {
@@ -1725,17 +1800,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;
+    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.
@@ -1746,20 +1827,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
@@ -1791,7 +1875,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 */
@@ -1801,7 +1885,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.
@@ -1818,11 +1910,13 @@ export declare interface Obj3DPointerEvent {
     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';
@@ -1830,7 +1924,9 @@ export declare interface Obj3DPosScreenEvent {
     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';
@@ -1838,21 +1934,21 @@ export declare interface Obj3DPosWorldEvent {
     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';
     /** 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. */
+    /** Whether the object is inside the camera frustum and not occluded. */
     visible: boolean;
 }
 
@@ -2056,78 +2152,110 @@ 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 callbackSelect;
+    private callbackOccls;
+    private callbackPointerHover;
     private listenerClick;
+    private listenerCancel;
     private listenerDown;
+    private listenerLeave;
     private listenerMove;
     private listenerUp;
-    private pointerEvent;
+    private eventPointerMove;
     private posPrevPointerX;
     private posPrevPointerY;
     private posWorldObj;
     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;
-    /**
-     * 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 getObjAtPointer;
+    private getOcclState;
+    /* Excluded from this release type: getOcclVisible */
+    private onCanvasClick;
+    private onCanvasPointerLeave;
+    private onCanvasPointerMove;
+    private onCanvasPointerCancel;
+    private onCanvasPointerDown;
+    private onCanvasPointerExit;
+    private onCanvasPointerUp;
     private onPointerEnter;
     private onPointerLeave;
     private onPointerMove;
-    private onPointerUp;
+    /* Excluded from this release type: resetOcclState */
+    /** Removes the explicit occlusion-object restriction so that all scene objects are checked again. */
+    resetOccluders(): void;
     /**
-     * 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`).
+     * 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 to track.
+     * @param params.objs3D - The `Obj3D` instances that may block visibility.
      */
-    trackSelectables({ objs3D }: {
+    setOccluders({ objs3D }: {
         objs3D: Obj3D[];
     }): void;
+    /* Excluded from this release type: trackOccl */
     /**
-     * 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.
+     * 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`).
+     *
+     * @param params - Parameter object.
+     * @param params.objs3D - The `Obj3D` instances to track.
      */
-    use(extension: (raycast: Raycast) => void): void;
+    trackPickables({ objs3D }: {
+        objs3D: Obj3D[];
+    }): 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: updateSelect */
-    private updatePointer;
+    /**
+     * 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
@@ -2228,7 +2356,7 @@ export declare interface RenderCfg {
          * Whether renderer-level anti-aliasing is enabled.
          * @default false
          */
-        aa: boolean;
+        antialias: boolean;
     };
     /**
      * WebGL-specific renderer configuration.
@@ -2417,6 +2545,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;
 }
 
 /**
@@ -2444,31 +2587,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
@@ -2496,36 +2624,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
@@ -2576,10 +2679,10 @@ export declare interface StateMachineCfg {
 }
 
 /**
- * Defines which previous active animation actions of the same object are stopped before a new action is played.
- * - `'all'`: Stops all previous active actions.
- * - `'last'`: Stops only the most recently played previous active action.
- * - `'none'`: Keeps all previous active actions running.
+ * Defines which previous active animation actions of the same layer are stopped before a new action is played.
+ * - 'all': Stops all previous active actions.
+ * - 'last': Stops only the most recently played previous active action.
+ * - 'none': Keeps all previous active actions running.
  */
 export declare type StopMode = 'all' | 'last' | 'none';