@needle-tools/engine 5.1.0-canary.deec6e4 → 5.1.0-canary.e6680fa

package/dist/needle-engine.d.ts

@@ -40,11 +40,13 @@ import { GLTFLoader } from '../../../node_modules/@types/three/examples/jsm/load
 import { GLTFLoaderPlugin } from '../../../node_modules/@types/three/examples/jsm/loaders/GLTFLoader.js';
 import { GLTFParser } from '../../../node_modules/@types/three/examples/jsm/loaders/GLTFLoader.js';
 import { Group } from 'three';
+import { ImpulseJoint } from '@dimforge/rapier3d-compat';
 import { InstancedMesh } from 'three';
 import { Intersection } from 'three';
 import { IParticleSystem as IParticleSystem_2 } from 'three.quarks';
 import { KeyframeTrack } from 'three';
 import { Layers } from 'three';
+import { Light as Light_2 } from 'three';
 import { LightProbe } from 'three';
 import { Line2 } from '../../../../node_modules/@types/three/examples/jsm/lines/Line2.js';
 import { Loader } from 'three';
@@ -117,6 +119,12 @@ export declare const $componentName: unique symbol;
 
 export declare const $physicsKey: unique symbol;
 
+/* Excluded from this release type: $TXm */
+
+/* Excluded from this release type: __CYjiNy */
+
+/* Excluded from this release type: __gGoBKfJa */
+
 export declare class __Ignore {
 }
 
@@ -254,6 +262,31 @@ export declare class ActionModel implements IBehaviorElement {
     writeTo(document: USDDocument, writer: USDWriter): void;
 }
 
+/**
+ * Options for an activation clip in the timeline builder
+ */
+export declare type ActivationClipOptions = {
+    /** Start time of the clip in seconds. If omitted, placed after the previous clip on this track. */
+    start?: number;
+    /** Duration of the clip in seconds (required) */
+    duration: number;
+    /** Ease-in duration in seconds (default: 0) */
+    easeIn?: number;
+    /** Ease-out duration in seconds (default: 0) */
+    easeOut?: number;
+};
+
+/**
+ * Builder for activation tracks. Provides `.clip()` for defining activation windows.
+ * @category Animation and Sequencing
+ */
+export declare interface ActivationTrackBuilder extends TimelineBuilderBase {
+    /** Adds an activation clip that shows/hides the bound object */
+    clip(options: ActivationClipOptions): ActivationTrackBuilder;
+    /** Mutes this track so it is skipped during playback */
+    muted(muted?: boolean): ActivationTrackBuilder;
+}
+
 export declare const activeInHierarchyFieldName = "needle_isActiveInHierarchy";
 
 /**
@@ -487,6 +520,62 @@ declare class Animation_2 extends Component implements IAnimationComponent {
 }
 export { Animation_2 as Animation }
 
+/**
+ * A fluent builder for creating `AnimationClip` instances from code.
+ *
+ * Use {@link AnimationBuilder.create} to start a new builder, chain `.track()` calls
+ * to add animation tracks, and call `.build()` to produce the clip.
+ *
+ * @example Single track
+ * ```ts
+ * const clip = AnimationBuilder.create()
+ *     .track(door, "position", { from: [0,0,0], to: [2,0,0], duration: 1 })
+ *     .build();
+ * ```
+ *
+ * @example Multiple tracks
+ * ```ts
+ * const clip = AnimationBuilder.create("DoorOpen")
+ *     .track(door, "position", { from: [0,0,0], to: [2,0,0], duration: 1 })
+ *     .track(light, "intensity", { from: 0, to: 5, duration: 1 })
+ *     .build(room);
+ * ```
+ *
+ * @category Animation and Sequencing
+ * @group Utilities
+ */
+export declare class AnimationBuilder {
+    private _name?;
+    private _tracks;
+    /** Creates a new AnimationBuilder instance */
+    static create(name?: string): AnimationBuilder;
+    constructor(name?: string);
+    /** Adds an animation track for an Object3D's position or scale */
+    track(target: Object3D, property: "position" | "scale", keyframes: KF_2<Vec3Value>, options?: TrackOptions): this;
+    /** Adds an animation track for an Object3D's quaternion */
+    track(target: Object3D, property: "quaternion", keyframes: KF_2<QuatValue>, options?: TrackOptions): this;
+    /** Adds an animation track for an Object3D's rotation (Euler, converted to quaternion) */
+    track(target: Object3D, property: "rotation", keyframes: KF_2<EulerValue>, options?: TrackOptions): this;
+    /** Adds an animation track for an Object3D's visibility */
+    track(target: Object3D, property: "visible", keyframes: KF_2<boolean>, options?: TrackOptions): this;
+    /** Adds an animation track for a material's numeric property */
+    track(target: Material, property: "opacity" | "roughness" | "metalness" | "alphaTest" | "emissiveIntensity" | "envMapIntensity" | "bumpScale" | "displacementScale" | "displacementBias", keyframes: KF_2<number>, options?: TrackOptions): this;
+    /** Adds an animation track for a material's color property */
+    track(target: Material, property: "color" | "emissive", keyframes: KF_2<ColorValue>, options?: TrackOptions): this;
+    /** Adds an animation track for a light's numeric property */
+    track(target: Light_2, property: "intensity" | "distance" | "angle" | "penumbra" | "decay", keyframes: KF_2<number>, options?: TrackOptions): this;
+    /** Adds an animation track for a light's color */
+    track(target: Light_2, property: "color", keyframes: KF_2<ColorValue>, options?: TrackOptions): this;
+    /** Adds an animation track for a camera's numeric property */
+    track(target: PerspectiveCamera, property: "fov" | "near" | "far" | "zoom", keyframes: KF_2<number>, options?: TrackOptions): this;
+    /**
+     * Builds and returns the `AnimationClip`.
+     * @param root - Optional root Object3D for resolving track paths.
+     *   When provided, tracks targeting a different object use `target.name` for named resolution.
+     */
+    build(root?: Object3D): AnimationClip;
+}
+
 /**
  * @category Animation and Sequencing
  * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
@@ -500,6 +589,34 @@ export declare type AnimationClipModel = {
     rotation?: Quat | Quaternion;
 };
 
+/**
+ * Options for an animation clip in the timeline builder
+ */
+export declare type AnimationClipOptions = {
+    /** Start time of the clip in seconds. If omitted, placed after the previous clip on this track. */
+    start?: number;
+    /** Duration of the clip in seconds. Defaults to the animation clip duration. */
+    duration?: number;
+    /** Playback speed multiplier (default: 1) */
+    speed?: number;
+    /** Whether the animation should loop within the clip (default: false) */
+    loop?: boolean;
+    /** Ease-in duration in seconds (default: 0) */
+    easeIn?: number;
+    /** Ease-out duration in seconds (default: 0) */
+    easeOut?: number;
+    /** Offset into the source animation clip in seconds (default: 0) */
+    clipIn?: number;
+    /** Whether to remove the start offset of the animation (default: false) */
+    removeStartOffset?: boolean;
+    /** Pre-extrapolation mode (default: None) */
+    preExtrapolation?: ClipExtrapolation;
+    /** Post-extrapolation mode (default: None) */
+    postExtrapolation?: ClipExtrapolation;
+    /** Play the clip in reverse */
+    reversed?: boolean;
+};
+
 /**
  * AnimationCurve is a representation of a curve that can be used to animate values over time.
  *
@@ -577,6 +694,19 @@ export declare class AnimationExtension implements IUSDExporterExtension {
 
 declare type AnimationIdentifier = AnimationClip | number | string | undefined;
 
+/** User-friendly interpolation mode names */
+export declare type AnimationInterpolation = "linear" | "smooth" | "step";
+
+/** A single keyframe: a time and a value */
+export declare type AnimationKeyframe<V> = {
+    /** Time in seconds */
+    time: number;
+    /** The value at this time */
+    value: V;
+    /** Interpolation mode for this track (default: `"linear"`). Note: Three.js applies one mode per track; the first keyframe's mode is used. */
+    interpolation?: AnimationInterpolation;
+};
+
 /**
  * Registry for animation related data. Use {@link registerAnimationMixer} to register an animation mixer instance.
  * Can be accessed from {@link Context.animations} and is used internally e.g. when exporting GLTF files.
@@ -597,43 +727,39 @@ declare class AnimationsRegistry {
     unregisterAnimationMixer(mixer: AnimationMixer | null | undefined): void;
 }
 
-export declare class AnimationTrackHandler extends TrackHandler {
-    /* Excluded from this release type: models */
-    /* Excluded from this release type: trackOffset */
-    /** The object that is being animated. */
-    target?: Object3D;
-    /** The AnimationMixer, should be shared with the animator if an animator is bound */
-    mixer?: AnimationMixer;
-    clips: Array<AnimationClip>;
-    actions: Array<AnimationAction>;
-    /**
-     * You can use the weight to blend the timeline animation tracks with multiple animation tracks on the same object.
-     * @default 1
-     */
-    weight: number;
-    /** holds data/info about clips differences */
-    private _actionOffsets;
-    private _didBind;
-    private _animator;
-    onDisable(): void;
-    onDestroy(): void;
-    onStateChanged(): void;
-    createHooks(clipModel: Models.AnimationClipModel, clip: any): void;
-    bind(): void;
-    private ensureTrackOffsets;
-    private _useclipOffsets;
-    private _totalOffsetPosition;
-    private _totalOffsetRotation;
-    private _totalOffsetPosition2;
-    private _totalOffsetRotation2;
-    private _summedPos;
-    private _tempPos;
-    private _summedRot;
-    private _tempRot;
-    private _clipRotQuat;
-    evaluate(time: number): void;
-    private createRotationInterpolant;
-    private createPositionInterpolant;
+/**
+ * Builder for animation tracks.
+ * Provides `.clip()` for pre-built AnimationClips and `.track()` for inline animation definition.
+ *
+ * @category Animation and Sequencing
+ */
+export declare interface AnimationTrackBuilder extends TimelineBuilderBase {
+    /** Adds a pre-built AnimationClip */
+    clip(asset: AnimationClip, options?: AnimationClipOptions): AnimationTrackBuilder;
+    /** Adds a clip from a single {@link TrackDescriptor} */
+    clip(descriptor: TrackDescriptor, options?: AnimationClipOptions): AnimationTrackBuilder;
+    /** Adds a clip from multiple {@link TrackDescriptor}s */
+    clip(descriptors: TrackDescriptor[], options?: AnimationClipOptions): AnimationTrackBuilder;
+    /** Adds an animation track for an Object3D's position or scale */
+    track(target: Object3D, property: "position" | "scale", keyframes: KF_3<Vec3Value>, options?: TrackOptions): AnimationTrackBuilder;
+    /** Adds an animation track for an Object3D's quaternion */
+    track(target: Object3D, property: "quaternion", keyframes: KF_3<QuatValue>, options?: TrackOptions): AnimationTrackBuilder;
+    /** Adds an animation track for an Object3D's rotation (Euler, converted to quaternion) */
+    track(target: Object3D, property: "rotation", keyframes: KF_3<EulerValue>, options?: TrackOptions): AnimationTrackBuilder;
+    /** Adds an animation track for an Object3D's visibility */
+    track(target: Object3D, property: "visible", keyframes: KF_3<boolean>, options?: TrackOptions): AnimationTrackBuilder;
+    /** Adds an animation track for a material's numeric property */
+    track(target: Material, property: "opacity" | "roughness" | "metalness" | "alphaTest" | "emissiveIntensity" | "envMapIntensity" | "bumpScale" | "displacementScale" | "displacementBias", keyframes: KF_3<number>, options?: TrackOptions): AnimationTrackBuilder;
+    /** Adds an animation track for a material's color property */
+    track(target: Material, property: "color" | "emissive", keyframes: KF_3<ColorValue>, options?: TrackOptions): AnimationTrackBuilder;
+    /** Adds an animation track for a light's numeric property */
+    track(target: Light_2, property: "intensity" | "distance" | "angle" | "penumbra" | "decay", keyframes: KF_3<number>, options?: TrackOptions): AnimationTrackBuilder;
+    /** Adds an animation track for a light's color */
+    track(target: Light_2, property: "color", keyframes: KF_3<ColorValue>, options?: TrackOptions): AnimationTrackBuilder;
+    /** Adds an animation track for a camera's numeric property */
+    track(target: PerspectiveCamera, property: "fov" | "near" | "far" | "zoom", keyframes: KF_3<number>, options?: TrackOptions): AnimationTrackBuilder;
+    /** Mutes this track so it is skipped during playback */
+    muted(muted?: boolean): AnimationTrackBuilder;
 }
 
 declare class AnimationTriggers {
@@ -726,6 +852,12 @@ export declare class Animator extends Component implements IAnimationComponent {
      * Identifies this component as an animation component in the engine
      */
     get isAnimationComponent(): boolean;
+    /**
+     * The current animator mixer, used for low-level control of animations. Owned by the AnimatorController
+     * @returns The current AnimationMixer, or null if no controller is assigned
+     * @see AnimatorController.mixer
+     */
+    get mixer(): AnimationMixer | null;
     /**
      * When enabled, animation will affect the root transform position and rotation
      */
@@ -1102,13 +1234,6 @@ export declare class AnimatorController {
      * @param animator - The animator to bind this controller to
      */
     bind(animator: Animator): void;
-    /**
-     * Creates a deep copy of this controller.
-     * Clones the model data but does not copy runtime state.
-     *
-     * @returns A new AnimatorController instance with the same configuration
-     */
-    clone(): AnimatorController | null;
     /**
      * Updates the controller's state machine and animations.
      * Called each frame by the animator component.
@@ -1151,11 +1276,15 @@ export declare class AnimatorController {
 /**
  * A fluent builder for creating {@link AnimatorController} instances from code.
  *
- * Use {@link AnimatorController.build} to create a new builder.
+ * Use {@link AnimatorControllerBuilder.create} or {@link AnimatorController.build} to create a new builder.
  *
- * @example
+ * The builder tracks state names and parameter types through the fluent chain,
+ * providing autocomplete for state names in `.transition()` and type-aware
+ * `.condition()` calls (e.g., trigger parameters don't require a mode argument).
+ *
+ * @example With pre-built AnimationClips
  * ```ts
- * const controller = AnimatorController.build("CharacterController")
+ * const controller = AnimatorControllerBuilder.create("CharacterController")
  *     .floatParameter("Speed", 0)
  *     .triggerParameter("Jump")
  *     .state("Idle", { clip: idleClip, loop: true })
@@ -1166,36 +1295,70 @@ export declare class AnimatorController {
  *     .transition("Walk", "Idle", { duration: 0.25 })
  *         .condition("Speed", "less", 0.1)
  *     .transition("*", "Jump", { duration: 0.1 })
- *         .condition("Jump", "if")
+ *         .condition("Jump")
  *     .transition("Jump", "Idle", { hasExitTime: true, exitTime: 0.9, duration: 0.25 })
  *     .build();
  * ```
  *
+ * @example With inline tracks (no pre-built clips needed)
+ * ```ts
+ * const controller = AnimatorControllerBuilder.create("Door")
+ *     .boolParameter("Open", false)
+ *     .state("Closed", { loop: true })
+ *         .track(door, "position", { from: [0, 0, 0], to: [0, 0, 0], duration: 1 })
+ *     .state("Open", { loop: true })
+ *         .track(door, "position", { from: [0, 0, 0], to: [2, 0, 0], duration: 1 })
+ *         .track(light, "intensity", { from: 0, to: 5, duration: 1 })
+ *     .transition("Closed", "Open", { duration: 0.25 })
+ *         .condition("Open", "if")
+ *     .transition("Open", "Closed", { duration: 0.25 })
+ *         .condition("Open", "ifNot")
+ *     .build(room);
+ * ```
+ *
+ * @typeParam TStates - Union of state names added via `.state()`. Used for autocomplete and validation in `.transition()` and `.defaultState()`.
+ * @typeParam TParams - Record mapping parameter names to their types (`"trigger"`, `"bool"`, `"float"`, `"int"`). Used for type-aware `.condition()` overloads.
+ *
  * @category Animation and Sequencing
  * @group Utilities
  */
-export declare class AnimatorControllerBuilder {
+export declare class AnimatorControllerBuilder<TStates extends string = never, TParams extends Record<string, "trigger" | "bool" | "float" | "int"> = {}> {
     private _name;
     private _parameters;
     private _states;
     private _anyStateTransitions;
     private _defaultStateName;
     private _lastTransition;
+    private _lastState;
+    /**
+     * Creates a new AnimatorControllerBuilder instance.
+     * @param name - Optional name for the controller
+     */
+    static create(name?: string): AnimatorControllerBuilder;
     constructor(name?: string);
     /** Adds a float parameter */
-    floatParameter(name: string, defaultValue?: number): this;
+    floatParameter<N extends string>(name: N, defaultValue?: number): AnimatorControllerBuilder<TStates, TParams & Record<N, "float">>;
     /** Adds an integer parameter */
-    intParameter(name: string, defaultValue?: number): this;
+    intParameter<N extends string>(name: N, defaultValue?: number): AnimatorControllerBuilder<TStates, TParams & Record<N, "int">>;
     /** Adds a boolean parameter */
-    boolParameter(name: string, defaultValue?: boolean): this;
+    boolParameter<N extends string>(name: N, defaultValue?: boolean): AnimatorControllerBuilder<TStates, TParams & Record<N, "bool">>;
     /** Adds a trigger parameter */
-    triggerParameter(name: string): this;
+    triggerParameter<N extends string>(name: N): AnimatorControllerBuilder<TStates, TParams & Record<N, "trigger">>;
     /**
      * Adds a state to the controller. The first state added becomes the default state.
+     *
+     * When `options.clip` is provided, the state uses that clip directly.
+     * When omitted, chain `.track()` calls to define animation tracks inline:
+     * ```ts
+     * .state("Open", { loop: true })
+     *     .track(door, "position", { from: [0,0,0], to: [2,0,0], duration: 1 })
+     *     .track(light, "intensity", { from: 0, to: 5, duration: 1 })
+     * ```
+     *
      * @param name - Unique name for the state
-     * @param options - State configuration including clip, loop, speed
+     * @param options - State configuration including clip, loop, speed. When omitted, use `.track()` to add animation data.
      */
-    state(name: string, options: StateOptions): this;
+    state<N extends string>(name: N, options?: StateOptions): AnimatorControllerBuilder<TStates | N, TParams>;
     /**
      * Adds a transition between two states.
      * Use `"*"` as the source to create a transition from any state.
@@ -1204,26 +1367,52 @@ export declare class AnimatorControllerBuilder {
      * @param to - Destination state name
      * @param options - Transition configuration
      */
-    transition(from: string, to: string, options?: TransitionOptions): this;
+    transition(from: TStates | "*", to: TStates, options?: TransitionOptions): AnimatorControllerBuilder<TStates, TParams>;
     /**
      * Adds a condition to the most recently added transition.
      * Multiple conditions on the same transition are AND-ed together.
+     *
+     * The required arguments depend on the parameter type:
+     * - **Trigger**: `.condition("Jump")` — mode defaults to `"if"`, no threshold needed
+     * - **Bool**: `.condition("Open", "if")` or `.condition("Open", "ifNot")`
+     * - **Float/Int**: `.condition("Speed", "greater", 0.1)`
+     *
      * @param parameter - Name of the parameter to evaluate
-     * @param mode - Condition mode: `"if"`, `"ifNot"`, `"greater"`, `"less"`, `"equals"`, `"notEqual"`
-     * @param threshold - Comparison threshold for numeric conditions (default: 0)
      */
-    condition(parameter: string, mode: ConditionMode, threshold?: number): this;
+    condition(parameter: ParamNamesOfType<TParams, "trigger">, mode?: "if" | "ifNot"): AnimatorControllerBuilder<TStates, TParams>;
+    condition(parameter: ParamNamesOfType<TParams, "bool">, mode: "if" | "ifNot"): AnimatorControllerBuilder<TStates, TParams>;
+    condition(parameter: ParamNamesOfType<TParams, "float" | "int">, mode: "greater" | "less" | "equals" | "notEqual", threshold?: number): AnimatorControllerBuilder<TStates, TParams>;
+    /** Adds an animation track for an Object3D's position or scale to the current state */
+    track(target: Object3D, property: "position" | "scale", keyframes: KF<Vec3Value>, options?: TrackOptions): this;
+    /** Adds an animation track for an Object3D's quaternion to the current state */
+    track(target: Object3D, property: "quaternion", keyframes: KF<QuatValue>, options?: TrackOptions): this;
+    /** Adds an animation track for an Object3D's rotation (Euler, converted to quaternion) to the current state */
+    track(target: Object3D, property: "rotation", keyframes: KF<EulerValue>, options?: TrackOptions): this;
+    /** Adds an animation track for an Object3D's visibility to the current state */
+    track(target: Object3D, property: "visible", keyframes: KF<boolean>, options?: TrackOptions): this;
+    /** Adds an animation track for a material's numeric property to the current state */
+    track(target: Material, property: "opacity" | "roughness" | "metalness" | "alphaTest" | "emissiveIntensity" | "envMapIntensity" | "bumpScale" | "displacementScale" | "displacementBias", keyframes: KF<number>, options?: TrackOptions): this;
+    /** Adds an animation track for a material's color property to the current state */
+    track(target: Material, property: "color" | "emissive", keyframes: KF<ColorValue>, options?: TrackOptions): this;
+    /** Adds an animation track for a light's numeric property to the current state */
+    track(target: Light_2, property: "intensity" | "distance" | "angle" | "penumbra" | "decay", keyframes: KF<number>, options?: TrackOptions): this;
+    /** Adds an animation track for a light's color to the current state */
+    track(target: Light_2, property: "color", keyframes: KF<ColorValue>, options?: TrackOptions): this;
+    /** Adds an animation track for a camera's numeric property to the current state */
+    track(target: PerspectiveCamera, property: "fov" | "near" | "far" | "zoom", keyframes: KF<number>, options?: TrackOptions): this;
     /**
      * Sets which state is the default/entry state.
      * If not called, the first added state is used.
      * @param name - Name of the state
      */
-    defaultState(name: string): this;
+    defaultState(name: TStates): AnimatorControllerBuilder<TStates, TParams>;
     /**
      * Builds and returns the {@link AnimatorController}.
      * Resolves all state name references to indices.
+     * @param root - Optional root Object3D for resolving {@link TrackDescriptor} track paths.
+     *   When provided, tracks targeting a different object use `target.name` for named resolution.
      */
-    build(): AnimatorController;
+    build(root?: Object3D): AnimatorController;
 }
 
 export declare type AnimatorControllerModel = {
@@ -1472,6 +1661,75 @@ export declare class Attractor extends Component {
 
 declare type AttributeChangeCallback = (value: string | null) => void;
 
+/**
+ * Represents an audio clip that can be loaded and played independently.
+ * The AudioClip class encapsulates the URL of the audio resource and provides
+ * methods for playback control (play, pause, stop) and querying duration.
+ */
+export declare class AudioClip {
+    readonly url: string;
+    /**
+     * Creates a new AudioClip instance with the specified URL.
+     * @param url The URL of the audio resource to load. This can be a path to an audio file or a MediaStream URL.
+     */
+    constructor(url: string);
+    /** Whether the clip is currently playing.
+     * @returns `true` if the clip is actively playing audio.
+     */
+    get isPlaying(): boolean;
+    /**
+     * The total duration of the audio clip in seconds.
+     * Loads the audio metadata if not already available.
+     * @returns A promise that resolves with the duration in seconds.
+     */
+    getDuration(): Promise<number>;
+    /**
+     * Plays the audio clip from the current position.
+     * @returns A promise that resolves when playback finishes, or rejects on error.
+     * If the clip is looping, the promise will never resolve on its own – call {@link stop} or {@link pause} to end playback.
+     */
+    play(): Promise<void>;
+    /**
+     * Pauses playback at the current position.
+     * Call {@link play} to resume.
+     */
+    pause(): void;
+    /**
+     * Stops playback and resets the position to the beginning.
+     */
+    stop(): void;
+    /** Whether the clip should loop when reaching the end. */
+    get loop(): boolean;
+    set loop(value: boolean);
+    /** Playback volume from 0 (silent) to 1 (full). */
+    get volume(): number;
+    set volume(value: number);
+    /** Current playback position in seconds. */
+    get currentTime(): number;
+    set currentTime(value: number);
+    /** Normalized playback progress from 0 to 1.
+     * @returns The current playback position as a value between 0 and 1, or 0 if the duration is unknown.
+     */
+    get progress(): number;
+    /**
+     * Seeks to a normalized position (0–1) in the clip.
+     * @param position A value between 0 (start) and 1 (end).
+     */
+    seek(position: number): void;
+    /** The underlying HTMLAudioElement, or `undefined` if not yet created.
+     * Use this to connect the element to the Web Audio API via `createMediaElementSource()`.
+     * @returns The HTMLAudioElement if the clip has been loaded or played, otherwise `undefined`.
+     */
+    get audioElement(): HTMLAudioElement | undefined;
+    private _audioElement?;
+    private _duration?;
+    private _loadPromise?;
+    private _loop;
+    private _volume;
+    /** Lazily creates and loads the shared HTMLAudioElement. */
+    private ensureAudioElement;
+}
+
 /**
  * @category Animation and Sequencing
  * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
@@ -1486,6 +1744,26 @@ declare type AudioClipModel_2 = Models.ClipModel & {
     _didTriggerPlay: boolean;
 };
 
+/**
+ * Options for an audio clip in the timeline builder
+ */
+export declare type AudioClipOptions = {
+    /** Start time of the clip in seconds. If omitted, placed after the previous clip on this track. */
+    start?: number;
+    /** Duration of the clip in seconds (required for audio since we can't infer it) */
+    duration: number;
+    /** Playback speed multiplier (default: 1) */
+    speed?: number;
+    /** Volume multiplier for this clip (default: 1) */
+    volume?: number;
+    /** Whether the audio should loop within the clip (default: false) */
+    loop?: boolean;
+    /** Ease-in duration in seconds (default: 0) */
+    easeIn?: number;
+    /** Ease-out duration in seconds (default: 0) */
+    easeOut?: number;
+};
+
 export declare class AudioExtension implements IUSDExporterExtension {
     static getName(clip: string): string;
     get extensionName(): string;
@@ -1522,7 +1800,7 @@ export { AudioListener_2 as AudioListener }
 /**
  * Defines how audio volume attenuates over distance from the listener.
  */
-declare enum AudioRolloffMode {
+export declare enum AudioRolloffMode {
     /**
      * Logarithmic rolloff provides a natural, real-world attenuation where volume decreases
      * exponentially with distance.
@@ -1627,9 +1905,10 @@ export declare class AudioSource extends Component {
      */
     get isPlaying(): boolean;
     /**
-     * The total duration of the current audio clip in seconds.
+     * The total duration of the currently loaded audio clip in seconds.
      *
      * @returns Duration in seconds or undefined if no clip is loaded
+     * @remarks For MediaStream clips, duration is not directly available and will return undefined. If the audio clip has not started loading or is still loading, duration may also be undefined until the audio buffer is ready.
      */
     get duration(): number | undefined;
     /**
@@ -1654,7 +1933,8 @@ export declare class AudioSource extends Component {
     /**
      * Controls how the audio is positioned in space.
      * Values range from 0 (2D, non-positional) to 1 (fully 3D positioned).
-     * Note: 2D playback is not fully supported in the current implementation.
+     * Internally uses a dual-path audio graph to crossfade between a spatialized (PannerNode)
+     * and a non-spatialized (direct) signal path.
      */
     get spatialBlend(): number;
     set spatialBlend(val: number);
@@ -1702,7 +1982,11 @@ export declare class AudioSource extends Component {
     private audioLoader;
     private shouldPlay;
     private _lastClipStartedLoading;
+    private _loadedClip;
     private _audioElement;
+    private _entryNode;
+    private _spatialGain;
+    private _bypassGain;
     /**
      * Returns the underlying {@link PositionalAudio} object, creating it if necessary.
      * The audio source needs a user interaction to be initialized due to browser autoplay policies.
@@ -1730,6 +2014,15 @@ export declare class AudioSource extends Component {
     private onApplicationMuteChanged;
     private createAudio;
     private __onAllowAudioCallback;
+    /**
+     * Sets up the dual-path audio graph for spatial blend crossfading.
+     * Creates two parallel signal paths from source to output:
+     * - 3D path: entry → panner → spatialGain → gain (spatialized)
+     * - 2D path: entry → bypassGain → gain (non-spatialized)
+     */
+    private setupSpatialBlendNodes;
+    /** Updates the spatial/bypass gain values based on the current spatialBlend. */
+    private updateSpatialBlendGains;
     private applySpatialDistanceSettings;
     private onNewClip;
     /**
@@ -1737,8 +2030,9 @@ export declare class AudioSource extends Component {
      * If no argument is provided, plays the currently assigned clip.
      *
      * @param clip - Optional audio clip or {@link MediaStream} to play
+     * @returns A promise that resolves when playback starts successfully, or rejects on error
      */
-    play(clip?: string | MediaStream | undefined): void;
+    play(clip?: string | MediaStream | undefined): Promise<boolean>;
     /**
      * Pauses audio playback while maintaining the current position.
      * Use play() to resume from the paused position.
@@ -1755,30 +2049,15 @@ export declare class AudioSource extends Component {
     /* Excluded from this release type: update */
 }
 
-export declare class AudioTrackHandler extends TrackHandler {
-    models: Array<AudioClipModel_2>;
-    listener: AudioListener_3;
-    audio: Array<Audio_2>;
-    audioContextTimeOffset: Array<number>;
-    lastTime: number;
-    audioSource?: AudioSource;
-    private _audioLoader;
-    private getAudioFilePath;
-    onAllowAudioChanged(allow: boolean): void;
-    addModel(model: Models.ClipModel): void;
-    onDisable(): void;
-    onDestroy(): void;
-    onMuteChanged(): void;
-    stop(): void;
-    private _playableDirectorResumed;
-    onPauseChanged(): void;
-    evaluate(time: number): void;
-    /** Call to load audio buffer for a specific time in the track. Can be used to preload the timeline audio */
-    loadAudio(time: number, lookAhead?: number, lookBehind?: number): Promise<(AudioBuffer | null)[]> | null;
-    private isInTimeRange;
-    private static _audioBuffers;
-    static dispose(): void;
-    private handleAudioLoading;
+/**
+ * Builder for audio tracks. Provides `.clip()` for adding audio clips by URL.
+ * @category Animation and Sequencing
+ */
+export declare interface AudioTrackBuilder extends TimelineBuilderBase {
+    /** Adds an audio clip by URL */
+    clip(url: string, options: AudioClipOptions): AudioTrackBuilder;
+    /** Mutes this track so it is skipped during playback */
+    muted(muted?: boolean): AudioTrackBuilder;
 }
 
 /* Excluded from this release type: AuralMode */
@@ -1811,69 +2090,6 @@ export declare class Avatar extends Component {
     private loadAvatarObjects;
 }
 
-/* Excluded from this release type: Avatar_Brain_LookAt */
-
-/* Excluded from this release type: Avatar_MouthShapes */
-
-/* Excluded from this release type: Avatar_MustacheShake */
-
-/* Excluded from this release type: Avatar_POI */
-
-/* Excluded from this release type: AvatarBlink_Simple */
-
-/* Excluded from this release type: AvatarEyeLook_Rotation */
-
-/**
- * Handles loading and instantiating avatar models from various sources.
- * Provides functionality to find and extract important parts of an avatar (head, hands).
- *
- * Debug mode can be enabled with the URL parameter `?debugavatar`,
- * which will log detailed information about avatar loading and configuration.
- */
-export declare class AvatarLoader {
-    private readonly avatarRegistryUrl;
-    /**
-     * Retrieves or creates a new avatar instance from an ID or existing Object3D.
-     * @param context The application context
-     * @param avatarId Either a string ID to load an avatar or an existing Object3D to use as avatar
-     * @returns Promise resolving to an AvatarModel if successful, or null if failed
-     */
-    getOrCreateNewAvatarInstance(context: Context, avatarId: string | Object3D): Promise<AvatarModel | null>;
-    /**
-     * Loads an avatar model from a file or registry using the provided ID.
-     * @param context The engine context
-     * @param avatarId The ID of the avatar to load
-     * @returns Promise resolving to the loaded avatar's Object3D, or null if failed
-     */
-    private loadAvatar;
-    /**
-     * Caches an avatar model for reuse.
-     * @param _id The ID to associate with the model
-     * @param _model The avatar model to cache
-     */
-    private cacheModel;
-    /**
-     * Analyzes an Object3D to find avatar parts (head, hands) based on naming conventions.
-     * @param obj The Object3D to search for avatar parts
-     * @returns A structured AvatarModel with references to found parts
-     */
-    private findAvatar;
-    /**
-     * Recursively searches for an avatar part by name within an Object3D hierarchy.
-     * @param obj The Object3D to search within
-     * @param searchString Array of strings that should all be present in the object name
-     * @returns The found Object3D part or null if not found
-     */
-    private findAvatarPart;
-    /**
-     * Handles HTTP response errors from avatar loading operations.
-     * @param response The fetch API response to check
-     * @returns The response if it was ok
-     * @throws Error with status text if response was not ok
-     */
-    private handleCustomAvatarErrors;
-}
-
 /**
  * Marks a GameObject as being controlled or owned by a player in networked XR sessions.
  * This is used internally by the networking system to identify player-controlled objects.
@@ -1934,35 +2150,6 @@ declare type AvatarMarkerEventArgs = {
     gameObject: Object3D;
 };
 
-/**
- * Represents an avatar model with head and hands references.
- * Used for representing characters in 3D space.
- */
-export declare class AvatarModel {
-    /** The root object of the avatar model */
-    root: Object3D;
-    /** The head object of the avatar model */
-    head: Object3D;
-    /** The left hand object of the avatar model, if available */
-    leftHand: Object3D | null;
-    /** The right hand object of the avatar model, if available */
-    rigthHand: Object3D | null;
-    /**
-     * Checks if the avatar model has a valid configuration.
-     * An avatar is considered valid if it has a head.
-     * @returns Whether the avatar has a valid setup
-     */
-    get isValid(): boolean;
-    /**
-     * Creates a new avatar model.
-     * @param root The root object of the avatar
-     * @param head The head object of the avatar
-     * @param leftHand The left hand object of the avatar
-     * @param rigthHand The right hand object of the avatar
-     */
-    constructor(root: Object3D, head: Object3D, leftHand: Object3D | null, rigthHand: Object3D | null);
-}
-
 export declare enum Axes {
     None = 0,
     X = 2,
@@ -2326,7 +2513,6 @@ export declare class BoxCollider extends Collider implements IBoxCollider {
     center: Vector3;
     /* Excluded from this release type: onEnable */
     /* Excluded from this release type: onDisable */
-    /* Excluded from this release type: onValidate */
     /**
      * Automatically fits the collider to the geometry of the object.
      * Sets the size and center based on the object's bounding box.
@@ -2600,6 +2786,7 @@ declare class CallHandle extends EventDispatcher<any> {
  * CallInfo represents a single callback method that can be invoked by the {@link EventList}.
  */
 export declare class CallInfo {
+    $serializedTypes: Record<string, any>;
     /**
      * When the CallInfo is enabled it will be invoked when the EventList is invoked
      */
@@ -2946,7 +3133,7 @@ export declare class Canvas extends UIRootComponent implements ICanvas {
     private _receivers;
     registerEventReceiver(receiver: ICanvasEventReceiver): void;
     unregisterEventReceiver(receiver: ICanvasEventReceiver): void;
-    onEnterXR(args: NeedleXREventArgs): Promise<void>;
+    onEnterXR(args: NeedleXREventArgs): void;
     onLeaveXR(args: NeedleXREventArgs): void;
     onBeforeRenderRoutine: () => void;
     onAfterRenderRoutine: () => void;
@@ -3275,7 +3462,12 @@ export declare enum ClearFlags {
     Skybox = 1,
     /** Clear the background with a solid color. The alpha channel of the color determines the transparency */
     SolidColor = 2,
-    /** Clear the background with a transparent color */
+    /**
+     * No declared background intent. Sets the render clear color to fully
+     * transparent so the canvas shows through when nothing else is configured,
+     * but leaves `scene.background` untouched — backgrounds set by other code
+     * (custom loaders, user assignment) are preserved.
+     */
     Uninitialized = 4
 }
 
@@ -3522,6 +3714,22 @@ export declare abstract class Collider extends Component implements ICollider {
      * The layers that this collider will interact with. Used for filtering collision detection.
      */
     filter?: number[];
+    /**
+     * The density of the collider, used for automatic mass calculation when the attached {@link Rigidbody} has `autoMass` enabled.
+     * Rapier computes mass from density using the real-world formula: `mass = density × volume`.
+     * The volume is derived from the collider shape (sphere, box, capsule, or convex hull).
+     *
+     * Reference values (relative to water = 1.0):
+     * - Wood: 0.5–0.9
+     * - Water: 1.0 (engine default)
+     * - Rubber: 1.2
+     * - Steel: 7.8
+     *
+     * @default undefined — uses the physics engine default of 1.0
+     */
+    density?: number;
+    /* Excluded from this release type: _propertiesDirty */
+    /* Excluded from this release type: onValidate */
     /* Excluded from this release type: awake */
     /* Excluded from this release type: start */
     /* Excluded from this release type: onEnable */
@@ -3625,6 +3833,9 @@ declare class ColorSerializer extends TypeSerializer {
 
 export declare let colorSerializer: ColorSerializer;
 
+/** A Color value, either as a Three.js Color or as an `[r, g, b]` tuple (0–1) */
+declare type ColorValue = Color | [number, number, number];
+
 /**
  * Utility method to check if two materials were created from the same glTF material
  */
@@ -3644,7 +3855,7 @@ export declare function compareAssociation<T extends Material>(obj1: T, obj2: T)
  * **Input event methods:**
  * {@link onPointerDown}, {@link onPointerUp}, {@link onPointerEnter}, {@link onPointerExit} and {@link onPointerMove}.
  *
- * @example
+ * @example Basic component
  * ```typescript
  * import { Behaviour } from "@needle-tools/engine";
  * export class MyComponent extends Behaviour {
@@ -3657,6 +3868,25 @@ export declare function compareAssociation<T extends Material>(obj1: T, obj2: T)
  * }
  * ```
  *
+ * @example Automatic cleanup with autoCleanup
+ * ```typescript
+ * import { Behaviour, serializable, EventList } from "@needle-tools/engine";
+ * export class ScoreTracker extends Behaviour {
+ *   @serializable(EventList)
+ *   onScoreChanged?: EventList<number>;
+ *
+ *   start() {
+ *     // Registered during start → survives enable/disable, cleaned up on destroy
+ *     this.autoCleanup(this.onScoreChanged?.on(score => console.log("Score:", score)));
+ *   }
+ *
+ *   onEnable() {
+ *     // Registered during onEnable → cleaned up on disable
+ *     this.autoCleanup(() => this.cleanupResources());
+ *   }
+ * }
+ * ```
+ *
  * @group Components
  */
 declare abstract class Component implements IComponent, EventTarget, Partial<INeedleXRSessionEventReceiver>, Partial<IPointerEventHandler> {
@@ -3707,6 +3937,50 @@ declare abstract class Component implements IComponent, EventTarget, Partial<INe
      * @returns True if the component is enabled and all parent GameObjects are active
      */
     get activeAndEnabled(): boolean;
+    private __disableCleanups?;
+    private __destroyCleanups?;
+    /**
+     * @experimental
+     * Register a resource for automatic cleanup tied to this component's lifecycle.
+     * Accepts {@link IDisposable} objects, cleanup functions, or event unsubscribe functions.
+     * `null` and `undefined` are safe no-ops (convenient for conditional subscriptions).
+     *
+     * **Lifecycle-aware:** The cleanup store is chosen automatically based on when `autoCleanup` is called:
+     * - Called during {@link onEnable} → cleaned up on {@link onDisable} (and re-registered on re-enable)
+     * - Called during {@link awake} or {@link start} → cleaned up on {@link onDestroy} (survives enable/disable cycles)
+     * - Called at any other time (e.g. from update) → cleaned up on {@link onDisable}
+     *
+     * @param disposable An {@link IDisposable}, a cleanup/unsubscribe function, or `null`/`undefined`
+     *
+     * @example EventList subscriptions
+     * ```ts
+     * import { Behaviour, serializable, EventList } from "@needle-tools/engine";
+     *
+     * export class MyComponent extends Behaviour {
+     *     @serializable(EventList)
+     *     onScoreChanged?: EventList<number>;
+     *
+     *     onEnable() {
+     *         this.autoCleanup(this.onScoreChanged?.on(score => {
+     *             console.log("Score:", score);
+     *         }));
+     *     }
+     * }
+     * ```
+     *
+     * @example Lifetime subscriptions in awake
+     * ```ts
+     * import { Behaviour } from "@needle-tools/engine";
+     *
+     * export class Persistent extends Behaviour {
+     *     awake() {
+     *         // Registered during awake → survives enable/disable, cleaned up on destroy
+     *         this.autoCleanup(() => this.save());
+     *     }
+     * }
+     * ```
+     */
+    protected autoCleanup(disposable: IDisposable | DisposeFn | Function | null | undefined): void;
     private get __isActive();
     private get __isActiveInHierarchy();
     private set __isActiveInHierarchy(value);
@@ -3725,11 +3999,6 @@ declare abstract class Component implements IComponent, EventTarget, Partial<INe
      * For example, URL to the glTF file this component was loaded from
      */
     sourceId?: SourceIdentifier;
-    /**
-     * Called when this component needs to remap guids after an instantiate operation.
-     * @param guidsMap Mapping from old guids to newly generated guids
-     */
-    resolveGuids?(guidsMap: GuidsMap): void;
     /**
      * Called once when the component becomes active for the first time.
      * This is the first lifecycle callback to be invoked
@@ -3942,6 +4211,10 @@ declare abstract class Component implements IComponent, EventTarget, Partial<INe
     destroy(): void;
     /* Excluded from this release type: __didAwake */
     /* Excluded from this release type: __didStart */
+    /** True while start() has finished executing (used by autoCleanup to distinguish start from update) */
+    private __didCompleteStart;
+    /** True while onEnable() is executing (used by autoCleanup to route to disable store) */
+    private __inEnableOrDisableCallback;
     /* Excluded from this release type: __didEnable */
     /* Excluded from this release type: __isEnabled */
     /* Excluded from this release type: __destroyed */
@@ -4231,6 +4504,7 @@ export declare class ContactShadows extends Component {
     set needsUpdate(val: boolean);
     get needsUpdate(): boolean;
     private _needsUpdate;
+    private _needsFit;
     /** All shadow objects are parented to this object.
      * The gameObject itself should not be transformed because we want the ContactShadows object e.g. also have a GroundProjectedEnv component
      * in which case ContactShadows scale would affect the projection
@@ -4484,19 +4758,31 @@ export declare class Context implements IContext {
     private _mainCamera;
     private _fallbackCamera;
     /** access application state (e.g. if all audio should be muted) */
-    application: Application;
+    get application(): Application;
+    private _application;
     /** access animation mixer used by components in the scene */
-    animations: AnimationsRegistry;
+    get animations(): AnimationsRegistry;
+    private _animations;
     /** access timings (current frame number, deltaTime, timeScale, ...) */
-    time: Time;
+    get time(): Time;
+    private _time;
     /** access input data (e.g. click or touch events) */
-    input: Input;
+    get input(): Input;
+    private _input;
     /** access physics related methods (e.g. raycasting). To access the phyiscs engine use `context.physics.engine` */
-    physics: Physics;
+    get physics(): Physics;
+    private _physics;
     /** access postprocessing effects stack. Add/remove effects and configure adaptive performance settings */
-    postprocessing: PostProcessing;
+    get postprocessing(): PostProcessing;
+    private _postprocessing;
     /** access networking methods (use it to send or listen to messages or join a networking backend) */
-    connection: NetworkConnection;
+    get connection(): NetworkConnection;
+    private _connection;
+    /** context-level event bus for decoupled component communication
+     * @see {@link ContextEventMap} for known event types
+     */
+    get events(): EventBus;
+    private _events;
     /**  @deprecated AssetDatabase is deprecated */
     assets: AssetDatabase;
     /** All registered lights in the scene, maintained by the Light component.
@@ -4755,6 +5041,18 @@ export declare type ContextEventArgs = {
     files?: LoadedModel[];
 };
 
+/** Typed event map for {@link Context.events}.
+ * Known events get full autocomplete; custom events can be typed at the call site via generic parameter.
+ */
+export declare interface ContextEventMap {
+    "scene-content-changed": {
+        /** The component that triggered the change (e.g. SceneSwitcher, DropListener) */
+        readonly source: IComponent;
+        /** The root object that was added/loaded */
+        readonly object: Object3D;
+    };
+}
+
 /** Use to register to various Needle Engine context events and to get access to all current instances
  * e.g. when being created in the DOM
  * @example
@@ -4806,6 +5104,20 @@ export declare type ControlClipModel = {
     updateDirector: boolean;
 };
 
+/**
+ * Options for a control clip in the timeline builder
+ */
+export declare type ControlClipOptions = {
+    /** Start time of the clip in seconds. If omitted, placed after the previous clip on this track. */
+    start?: number;
+    /** Duration of the clip in seconds (required) */
+    duration: number;
+    /** Whether to control the activation of the source object (default: true) */
+    controlActivation?: boolean;
+    /** Whether to update a nested PlayableDirector on the source object (default: true) */
+    updateDirector?: boolean;
+};
+
 /** true when selectstart was ever received.
  * On VisionOS 1.1 we always have select events (as per the spec), so this is always true
  */
@@ -4816,12 +5128,15 @@ declare type ControllerAxes = "xr-standard-thumbstick" | "xr-standard-touchpad";
  */
 export declare type ControllerChangedEvt = (args: NeedleXRControllerEventArgs) => void;
 
-export declare class ControlTrackHandler extends TrackHandler {
-    models: Array<Models.ClipModel>;
-    timelines: Array<PlayableDirector | null>;
-    resolveSourceObjects(_context: Context): void;
-    private _previousActiveModel;
-    evaluate(time: number): void;
+/**
+ * Builder for control tracks. Provides `.clip()` for controlling nested objects/timelines.
+ * @category Animation and Sequencing
+ */
+export declare interface ControlTrackBuilder extends TimelineBuilderBase {
+    /** Adds a control clip for a source object */
+    clip(sourceObject: Object3D, options: ControlClipOptions): ControlTrackBuilder;
+    /** Mutes this track so it is skipped during playback */
+    muted(muted?: boolean): ControlTrackBuilder;
 }
 
 /**@obsolete use Graphics.copyTexture */
@@ -5009,7 +5324,6 @@ export declare class CursorFollow extends Component {
      * - Cursor that follows terrain or mesh surfaces
      *
      * **Important notes:**
-     * - Requires objects in the scene to have colliders for raycasting to work
      * - Works best with {@link keepDistance} set to `false` to allow depth changes
      * - Can be combined with {@link damping} for smooth surface following
      * - The raycast uses the physics system's raycast functionality
@@ -5136,7 +5450,7 @@ export declare function decompressGpuTexture(texture: any, maxTextureSize?: numb
  *   return true;
  * });
  * */
-export declare function deepClone(obj: any, predicate?: deepClonePredicate): any;
+export declare function deepClone(obj: any, predicate?: deepClonePredicate, _visited?: WeakSet<object>): any;
 
 declare type deepClonePredicate = (owner: any, propertyName: string, current: any) => boolean;
 
@@ -5364,7 +5678,7 @@ export declare namespace DeviceUtilities {
  * Controls how the {@link PlayableDirector} behaves when playback reaches the end.
  * @see {@link PlayableDirector.extrapolationMode}
  */
-declare enum DirectorWrapMode {
+export declare enum DirectorWrapMode {
     /** Hold the last frame when playback reaches the end of the timeline. */
     Hold = 0,
     /** Loop back to the start and continue playing indefinitely. */
@@ -5373,6 +5687,101 @@ declare enum DirectorWrapMode {
     None = 2
 }
 
+/**
+ * A store for managing disposable resources (event subscriptions, listeners, callbacks)
+ * that should be cleaned up together.
+ *
+ * DisposableStore collects disposables and disposes them all at once when
+ * {@link dispose} is called. After disposal, the store can be reused — new items
+ * can be added and a subsequent {@link dispose} call will clean those up.
+ *
+ * This is the same pattern used internally by VSCode for lifecycle-bound resource management.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { DisposableStore, on } from "@needle-tools/engine";
+ *
+ * const store = new DisposableStore();
+ *
+ * // Register a DOM event listener (typed!)
+ * store.add(on(window, "resize", (ev) => console.log(ev)));
+ *
+ * // Register the return value of EventList.on()
+ * store.add(myEventList.on(data => console.log(data)));
+ *
+ * // Register a raw cleanup function
+ * store.add(() => someSDK.off("event", handler));
+ *
+ * // Later: dispose everything at once
+ * store.dispose();
+ * ```
+ *
+ * @example Use with Needle Engine components
+ * ```ts
+ * import { Behaviour, serializable, EventList, on } from "@needle-tools/engine";
+ *
+ * export class MyComponent extends Behaviour {
+ *     @serializable(EventList)
+ *     onClick?: EventList;
+ *
+ *     onEnable() {
+ *         // DOM events — fully typed
+ *         this.autoCleanup(on(window, "resize", (ev) => this.onResize(ev)));
+ *
+ *         // EventList — .on() returns a function, autoCleanup accepts it
+ *         this.autoCleanup(this.onClick?.on(() => console.log("clicked!")));
+ *     }
+ *     // No onDisable needed — cleaned up automatically!
+ * }
+ * ```
+ *
+ * @category Utilities
+ * @group Lifecycle
+ */
+export declare class DisposableStore implements IDisposable {
+    private _disposables;
+    /** The number of registered disposables */
+    get size(): number;
+    /**
+     * Register a disposable resource. Accepts:
+     * - An {@link IDisposable} object (has a `dispose()` method) — e.g. from {@link on}
+     * - A cleanup function (e.g. return value of `EventList.on()`)
+     * - `null` or `undefined` (safe no-op for conditional subscriptions)
+     *
+     * When {@link dispose} is called, all registered resources are cleaned up.
+     *
+     * @param disposable The resource to register for disposal
+     *
+     * @example
+     * ```ts
+     * const store = new DisposableStore();
+     *
+     * // IDisposable object from on()
+     * store.add(on(window, "resize", handler));
+     *
+     * // Function returned by EventList.on()
+     * store.add(myEvent.on(handler));
+     *
+     * // Raw cleanup function
+     * store.add(() => connection.close());
+     *
+     * // Conditional — safe with undefined
+     * store.add(this.maybeEvent?.on(handler));
+     * ```
+     */
+    add(disposable: IDisposable | DisposeFn | Function | null | undefined): void;
+    /**
+     * Dispose all registered resources. Each registered disposable is cleaned up,
+     * then the internal list is cleared. The store can be reused after disposal.
+     *
+     * Called automatically by the engine when a component's `onDisable` lifecycle fires.
+     */
+    dispose(): void;
+}
+
+/** A function that performs cleanup when called */
+export declare type DisposeFn = () => void;
+
 /** Recursive disposes all referenced resources by this object. Does not traverse children */
 export declare function disposeObjectResources(obj: object | null | undefined): void;
 
@@ -5480,6 +5889,12 @@ export declare class DragControls extends Component implements IPointerEventHand
      * providing visual feedback about the object's position relative to surfaces below it.
      */
     showGizmo: boolean;
+    /** Invoked once when a drag begins (after the minimum drag distance threshold is met). */
+    dragStarted: EventList;
+    /** Invoked every frame while the object is being dragged. */
+    dragUpdated: EventList;
+    /** Invoked once when the last pointer is released and the drag ends. */
+    dragEnded: EventList;
     /**
      * Returns the object currently being dragged by this DragControls component, if any.
      * @returns The object being dragged or null if no object is currently dragged
@@ -5920,6 +6335,45 @@ export declare class EnvironmentScene extends Scene {
     createAreaLightMaterial(intensity: number): MeshBasicMaterial;
 }
 
+/** An Euler value, either as a Three.js Euler or as a `[x, y, z]` tuple (radians) */
+declare type EulerValue = Euler | [number, number, number];
+
+/** Typed event bus. Known {@link ContextEventMap} events get full autocomplete.
+ * Custom events can be typed at the call site via generic parameter.
+ * @example Known events
+ * ```ts
+ * context.events.on("scene-content-changed", e => e.object);
+ * ```
+ * @example Custom events — type at call site
+ * ```ts
+ * context.events.emit<{ pts: number }>("scored", { pts: 10 });
+ * context.events.on<{ pts: number }>("scored", e => e.pts);
+ * ```
+ * @example Once
+ * ```ts
+ * context.events.on("scene-content-changed", e => { ... }, { once: true });
+ * ```
+ */
+export declare class EventBus {
+    private _listeners;
+    /** Emit a known {@link ContextEventMap} event */
+    emit<K extends keyof ContextEventMap & string>(type: K, detail?: ContextEventMap[K]): void;
+    /** Emit a custom event with user-provided type */
+    emit<T>(type: string, detail?: T): void;
+    /** Subscribe to a known {@link ContextEventMap} event. Returns an unsubscribe function. */
+    on<K extends keyof ContextEventMap & string>(type: K, callback: (args: ContextEventMap[K]) => void, options?: EventBusListenerOptions): () => void;
+    /** Subscribe to a custom event with user-provided type. Returns an unsubscribe function. */
+    on<T>(type: string, callback: (args: T) => void, options?: EventBusListenerOptions): () => void;
+    /** Remove all listeners. Called when the context is cleared or destroyed. */
+    clear(): void;
+}
+
+/** Options for {@link EventBus.on}. */
+export declare interface EventBusListenerOptions {
+    /** If true the listener is automatically removed after the first invocation. */
+    once?: boolean;
+}
+
 /**
  * EventList manages a list of callbacks that can be invoked together.
  * Used for Unity-style events that can be configured in the editor (Unity or Blender).
@@ -5966,13 +6420,9 @@ export declare class EnvironmentScene extends Scene {
  * @see {@link Button} for UI button events
  */
 export declare class EventList<TArgs extends any = any> implements IEventList {
+    $serializedTypes: Record<string, any>;
     /** checked during instantiate to create a new instance */
     readonly isEventList = true;
-    /* Excluded from this release type: __internalOnInstantiate */
-    private target?;
-    private key?;
-    /** set an event target to try invoke the EventTarget dispatchEvent when this EventList is invoked */
-    setEventTarget(key: string, target: object): void;
     /** How many callback methods are subscribed to this event */
     get listenerCount(): number;
     /** If the event is currently being invoked */
@@ -6005,13 +6455,41 @@ export declare class EventList<TArgs extends any = any> implements IEventList {
     invoke(...args: Array<TArgs>): boolean;
     /** Add a new event listener to this event
      * @returns a function to remove the event listener
+     * @see {@link removeEventListener} for more details and return value information
+     * @see {@link off} for an alias with better readability when unsubscribing from events
+     * @example
+     * ```ts
+     * const off = myEvent.addEventListener(args => console.log("Clicked!", args));
+     * // later
+     * off();
+     * ```
      */
     addEventListener(callback: (args: TArgs) => void): Function;
+    /**
+     * Alias for addEventListener for better readability when subscribing to events. You can use it like this:
+     * ```ts
+     * myEvent.on(args => console.log("Clicked!", args));
+     * ```
+     * @returns a function to remove the event listener
+     * @see {@link addEventListener} for more details and return value information
+     */
+    on(callback: (args: TArgs) => void): Function;
     /**
      * Remove an event listener from this event.
      * @returns true if the event listener was found and removed, false otherwise
      */
     removeEventListener(fn: Function | null | undefined): boolean;
+    /**
+     * Alias for removeEventListener for better readability when unsubscribing from events. You can use it like this:
+     * ```ts
+     * const off = myEvent.on(args => console.log("Clicked!", args));
+     * // later
+     * off();
+     * ```
+     *
+     * @see {@link removeEventListener} for more details and return value information
+     */
+    off(callback: Function | null | undefined): boolean;
     /**
      * Remove all event listeners from this event. Use with caution! This will remove all listeners!
      */
@@ -6042,6 +6520,7 @@ declare type EventListenerOptions_2 = {
     signal?: AbortSignal;
 };
 
+/** @deprecated No longer automatically dispatched. Use `eventList.on()` directly instead. */
 export declare class EventListEvent<TArgs extends any> extends Event {
     args?: TArgs;
 }
@@ -6495,7 +6974,7 @@ declare type FitParameters = {
  * @see {@link HingeJoint} for rotating connections
  */
 export declare class FixedJoint extends Joint {
-    protected createJoint(self: Rigidbody, other: Rigidbody): void;
+    protected createJoint(self: Rigidbody, other: Rigidbody): any;
 }
 
 declare type FocusRect = DOMRect | Element | {
@@ -7679,14 +8158,8 @@ export declare type GuidsMap = {
     [key: string]: string;
 };
 
-/* Excluded from this release type: hasCommercialLicense */
-
-/* Excluded from this release type: hasIndieLicense */
-
 /* Excluded from this release type: hasPointerEventComponent */
 
-/* Excluded from this release type: hasProLicense */
-
 export declare function hideDebugConsole(): void;
 
 export declare enum HideFlags {
@@ -7746,7 +8219,7 @@ export declare class HingeJoint extends Joint {
     anchor?: Vector3;
     /** Axis of rotation for the hinge (e.g., Vector3(0,1,0) for vertical axis) */
     axis?: Vector3;
-    protected createJoint(self: Rigidbody, other: Rigidbody): void;
+    protected createJoint(self: Rigidbody, other: Rigidbody): any;
 }
 
 declare type HitPointObject = Object3D & {
@@ -7969,7 +8442,7 @@ declare const HTMLElementBase: typeof HTMLElement;
 
 export declare type IAnimationComponent = Pick<IComponent, "gameObject"> & {
     isAnimationComponent: boolean;
-    addClip?(clip: AnimationClip): any;
+    addClip?(clip: AnimationClip): void;
 };
 
 /* Excluded from this release type: IApplyPrototypeExtension */
@@ -8043,6 +8516,12 @@ export declare interface ICollider extends IComponent {
      * Default: undefined
      */
     filter?: number[];
+    /** The density of the collider used for automatic mass calculation.
+     * When the attached Rigidbody has `autoMass` enabled, the mass is computed as `density × volume`.
+     * Note: Make sure to call updateProperties after having changed this property
+     * Default: undefined (uses physics engine default of 1.0)
+     */
+    density?: number;
 }
 
 export declare type ICollisionContext = {
@@ -8069,7 +8548,6 @@ export declare interface IComponent extends IHasGuid {
     /* Excluded from this release type: __internalEnable */
     /* Excluded from this release type: __internalDisable */
     /* Excluded from this release type: __internalDestroy */
-    /* Excluded from this release type: resolveGuids */
     /** experimental, called when the script is registered for the first time, this is called even if the component is not enabled. */
     registering?(): any;
     awake(): any;
@@ -8106,6 +8584,24 @@ export declare interface IConnectionData {
 
 export declare type IContext = Context;
 
+/**
+ * Interface for objects that hold resources and can be disposed.
+ * Implement this interface on any object that needs deterministic cleanup.
+ *
+ * @example
+ * ```ts
+ * class MyResource implements IDisposable {
+ *     dispose() { /* release resources *\/ }
+ * }
+ * ```
+ *
+ * @category Utilities
+ * @group Lifecycle
+ */
+export declare interface IDisposable {
+    dispose(): void;
+}
+
 /** Implement to receive callbacks from {@type @needle-tools/editor-sync} package */
 declare interface IEditorModification {
     /**
@@ -8125,7 +8621,6 @@ export declare interface IEffectProvider {
 
 export declare interface IEventList {
     readonly isEventList: true;
-    __internalOnInstantiate(map: InstantiateContext): IEventList;
 }
 
 export declare interface IGameObject extends Object3D {
@@ -8418,13 +8913,45 @@ export declare interface INeedleXRSessionEventReceiver extends Pick<IComponent,
 export declare interface INetworkConnection {
     get isConnected(): boolean;
     get isInRoom(): boolean;
-    send(key: string, data: IModel | object | boolean | null | string | number, queue: SendQueue): unknown;
+    send(key: string, data?: IModel | object | boolean | string | number, queue?: SendQueue): unknown;
 }
 
 export declare interface INetworkingWebsocketUrlProvider {
     getWebsocketUrl(): string | null;
 }
 
+/**
+ * @experimental
+ * Interface for a network transport layer used by {@link NetworkConnection}.
+ * The default implementation wraps a websocket via `websocket-ts`.
+ * Custom implementations can be injected into {@link NetworkConnection.connect}
+ * for testing or alternative transports.
+ *
+ * **Lifecycle:** After creating a transport and passing it to `connect()`,
+ * `NetworkConnection` sets the four event callbacks (`onOpen`, `onClose`,
+ * `onError`, `onMessage`) and then calls {@link start}. The transport
+ * should call `onOpen` when the connection is ready.
+ */
+export declare interface INetworkTransport {
+    /** Start the connection. Called by NetworkConnection after event callbacks are set.
+     * May return a promise if setup is async (e.g. dynamic imports). */
+    start(): void | Promise<void>;
+    /** Send data (string for JSON messages, Uint8Array for binary) */
+    send(data: string | Uint8Array): void;
+    /** Close the transport */
+    close(): void | Promise<void>;
+    /** The URL this transport is connected to, if applicable */
+    readonly url: string | undefined;
+    /** Called when the transport connection opens */
+    onOpen: (() => void) | null;
+    /** Called when the transport connection closes */
+    onClose: (() => void) | null;
+    /** Called when an error occurs */
+    onError: ((err: any) => void) | null;
+    /** Called when a message is received. Data is either a string (JSON) or Blob (binary). */
+    onMessage: ((data: string | Blob) => void) | null;
+}
+
 export declare class InheritVelocityModule {
     enabled: boolean;
     curve: MinMaxCurve;
@@ -8511,14 +9038,33 @@ export declare class Input implements IInput {
      */
     private readonly _eventListeners;
     /** Adds an event listener for the specified event type. The callback will be called when the event is triggered.
+     *
+     * Returns an unsubscribe function — call it to remove the listener.
+     * Pass it to {@link Behaviour.autoCleanup} for automatic lifecycle management.
+     *
      * @param type The event type to listen for
      * @param callback The callback to call when the event is triggered
      * @param options The options for adding the event listener.
-     * @example Basic usage
+     * @returns A function that removes the event listener when called.
+     *
+     * @example With autoCleanup (recommended)
      * ```ts
-     * input.addEventListener("pointerdown", (evt) => {
+     * export class MyComponent extends Behaviour {
+     *   onEnable() {
+     *     this.autoCleanup(this.context.input.addEventListener("pointerdown", (evt) => {
+     *       console.log("Pointer down", evt.pointerId, evt.pointerType);
+     *     }));
+     *   }
+     *   // Listener is automatically removed on disable — no manual cleanup needed!
+     * }
+     * ```
+     * @example Manual unsubscribe
+     * ```ts
+     * const off = input.addEventListener("pointerdown", (evt) => {
      *   console.log("Pointer down", evt.pointerId, evt.pointerType);
      * });
+     * // later
+     * off();
      * ```
      * @example Adding a listener that is called after all other listeners
      * By using a higher value for the queue the listener will be called after other listeners (default queue is 0).
@@ -8534,8 +9080,8 @@ export declare class Input implements IInput {
      * }, { once: true });
      * ```
      */
-    addEventListener(type: PointerEventNames, callback: PointerEventListener, options?: EventListenerOptions_2): any;
-    addEventListener(type: KeyboardEventNames, callback: KeyboardEventListener, options?: EventListenerOptions_2): any;
+    addEventListener(type: PointerEventNames, callback: PointerEventListener, options?: EventListenerOptions_2): () => void;
+    addEventListener(type: KeyboardEventNames, callback: KeyboardEventListener, options?: EventListenerOptions_2): () => void;
     /** Removes the event listener from the specified event type. If no queue is specified the listener will be removed from all queues.
      * @param type The event type to remove the listener from
      * @param callback The callback to remove
@@ -8981,7 +9527,7 @@ export declare function instantiate(instance: AssetReference, opts?: IInstantiat
 export declare function instantiate(instance: IGameObject | Object3D, opts?: IInstantiateOptions | null): IGameObject;
 
 /**
- * Provides access to the instantiated object and its clone
+ * Provides access to the instantiated object map (used by EventList etc.)
  */
 export declare type InstantiateContext = Readonly<InstantiateReferenceMap>;
 
@@ -9021,7 +9567,8 @@ export declare class InstantiateOptions implements IInstantiateOptions {
     cloneAssign(other: InstantiateOptions | IInstantiateOptions): void;
 }
 
-declare type InstantiateReferenceMap = Record<string, ObjectCloneReference>;
+/** Maps uuid/guid → { original, clone } for Object3D and Component instances */
+export declare type InstantiateReferenceMap = Record<string, ObjectCloneReference>;
 
 /**
  * An empty component that can be used to mark an object as interactable.
@@ -9092,8 +9639,10 @@ export declare interface IPhysicsEngine {
     postStep(): any;
     /** Indicates whether the physics engine is currently updating */
     get isUpdating(): boolean;
-    /** Clears all cached data (e.g., mesh data when creating scaled mesh colliders) */
-    clearCaches(): any;
+    /** Tears down the physics world and frees all resources. The world will be re-created on next use. */
+    dispose(): void;
+    /** @deprecated Use {@link dispose} instead. */
+    clearCaches(): void;
     /** Enables or disables the physics engine */
     enabled: boolean;
     /** Returns the underlying physics world object */
@@ -9140,6 +9689,11 @@ export declare interface IPhysicsEngine {
          * @returns False to ignore this collider, true to include it
          */
         filterPredicate?: (collider: ICollider) => boolean;
+        /** When true, trigger/sensor colliders will be included in the raycast results.
+         * By default trigger colliders are skipped.
+         * @default false
+         */
+        includeTriggers?: boolean;
     }): RaycastResult;
     /**
      * Performs a raycast that also returns the normal vector at the hit point
@@ -9167,6 +9721,11 @@ export declare interface IPhysicsEngine {
          * @returns False to ignore this collider, true to include it
          */
         filterPredicate?: (collider: ICollider) => boolean;
+        /** When true, trigger/sensor colliders will be included in the raycast results.
+         * By default trigger colliders are skipped.
+         * @default false
+         */
+        includeTriggers?: boolean;
     }): RaycastResult;
     /**
      * Finds all colliders within a sphere
@@ -9323,8 +9882,9 @@ export declare interface IPhysicsEngine {
      * @returns The underlying physics body or null if not found
      */
     getBody(obj: ICollider | IRigidbody): null | any;
-    addFixedJoint(body1: IRigidbody, body2: IRigidbody): any;
-    addHingeJoint(body1: IRigidbody, body2: IRigidbody, anchor: Vec3, axis: Vec3): any;
+    addFixedJoint(body1: IRigidbody, body2: IRigidbody): Promise<any> | any;
+    addHingeJoint(body1: IRigidbody, body2: IRigidbody, anchor: Vec3, axis: Vec3): Promise<any> | any;
+    removeJoint(joint: any): void;
     /** Enable to render collider shapes */
     debugRenderColliders: boolean;
     /** Enable to visualize raycasts in the scene with gizmos */
@@ -9545,6 +10105,18 @@ export declare function isDestroyed(go: Object3D): boolean;
 /** True when the application runs on a local url */
 export declare function isDevEnvironment(): boolean;
 
+/**
+ * Type guard to check if an object implements {@link IDisposable}.
+ *
+ * @example
+ * ```ts
+ * if (isDisposable(obj)) {
+ *     obj.dispose(); // safe to call
+ * }
+ * ```
+ */
+export declare function isDisposable(value: unknown): value is IDisposable;
+
 export declare function isDisposed(obj: object): boolean;
 
 export declare interface ISerializable {
@@ -9579,6 +10151,10 @@ export declare function isHotReloadEnabled(): boolean;
 /**@returns true if the element is an needle engine icon element */
 export declare function isIconElement(element: Node): boolean;
 
+export declare interface ISignalReceiver {
+    readonly isSignalReceiver: true;
+}
+
 /** @deprecated use {@link DeviceUtilities.isiOS} instead */
 export declare function isiOS(): boolean;
 
@@ -9613,6 +10189,8 @@ export declare function isResourceTrackingEnabled(): boolean;
 /** @deprecated use {@link DeviceUtilities.isSafari} instead */
 export declare function isSafari(): boolean;
 
+export declare function isTrackModel(obj: unknown): obj is TrackModel;
+
 export declare function isUsingInstancing(instance: Object3D): boolean;
 
 export declare interface ITime {
@@ -9737,7 +10315,9 @@ declare abstract class Joint extends Component {
     connectedBody?: Rigidbody;
     get rigidBody(): Rigidbody | null;
     private _rigidBody;
+    private _jointHandle;
     onEnable(): void;
+    onDisable(): void;
     private create;
     protected abstract createJoint(self: Rigidbody, other: Rigidbody): any;
 }
@@ -9779,6 +10359,15 @@ declare class Keyframe_2 {
 }
 export { Keyframe_2 as Keyframe }
 
+/** Keyframe array or tween shorthand */
+declare type KF<V> = AnimationKeyframe<V>[] | Tween<V>;
+
+/** Keyframe array or tween shorthand */
+declare type KF_2<V> = AnimationKeyframe<V>[] | Tween<V>;
+
+/** Keyframe array or tween shorthand */
+declare type KF_3<V> = AnimationKeyframe<V>[] | Tween<V>;
+
 declare type LabelHandle = {
     setText(str: string): any;
 };
@@ -10447,13 +11036,15 @@ export declare function markAsInstancedRendered(go: Object3D, instanced: boolean
     time: number;
 }
 
-export declare class MarkerTrackHandler extends TrackHandler {
-    models: Array<Models.MarkerModel & Record<string, any>>;
-    needsSorting: boolean;
-    foreachMarker<T>(type?: string | null): Generator<T, void, unknown>;
-    onEnable(): void;
-    evaluate(_time: number): void;
-    private sort;
+/**
+ * Builder for marker tracks. Provides `.marker()` for adding markers.
+ * @category Animation and Sequencing
+ */
+export declare interface MarkerTrackBuilder extends TimelineBuilderBase {
+    /** Adds a marker referencing a signal asset by guid */
+    marker(time: number, asset: string, options?: SignalMarkerOptions): MarkerTrackBuilder;
+    /** Mutes this track so it is skipped during playback */
+    muted(muted?: boolean): MarkerTrackBuilder;
 }
 
 export declare enum MarkerType {
@@ -10999,6 +11590,7 @@ export declare type Model = (GLTF | FBX | OBJ | CustomModel);
 
 declare namespace Models {
     export {
+        isTrackModel,
         TimelineAssetModel,
         TrackType,
         ClipExtrapolation,
@@ -11206,11 +11798,17 @@ export declare interface NeedleEngineAttributes {
     'hash': string;
     /** Set to automatically add OrbitControls to the loaded scene. */
     'camera-controls': string;
-    /** Override the default draco decoder path location. */
+    /** Override the default Draco decoder/decompressor path. Can be a URL or a local path to a directory containing the Draco decoder files.
+     * @default "https://www.gstatic.com/draco/versioned/decoders/1.5.7/"
+     * @example <needle-engine dracoDecoderPath="./decoders/draco/"></needle-engine>
+     */
     'dracoDecoderPath': string;
-    /** Override the default draco library type. */
+    /** Override the default Draco decoder type. */
     'dracoDecoderType': 'wasm' | 'js';
-    /** Override the default KTX2 transcoder/decoder path. */
+    /** Override the default KTX2 transcoder/decoder path. Can be a URL or a local path to a directory containing the KTX2 transcoder files.
+     * @default "https://cdn.needle.tools/static/three/0.179.1/basis2/"
+     * @example <needle-engine ktx2DecoderPath="./decoders/ktx2/"></needle-engine>
+     */
     'ktx2DecoderPath': string;
     /** Prevent context from being disposed when element is removed from DOM. */
     'keep-alive': 'true' | 'false';
@@ -12164,8 +12762,7 @@ export declare class NeedleXRSession implements INeedleXRSession {
     get referenceSpace(): XRSpace | null;
     /** @returns the XRFrame `viewerpose` using the xr `referenceSpace` */
     get viewerPose(): XRViewerPose | undefined;
-    /** @returns `true` if any image is currently being tracked */
-    /** returns true if images are currently being tracked */
+    /** @returns `true` if any image is currently being tracked or emulated */
     get isTrackingImages(): boolean;
     /** The currently active XR rig */
     get rig(): IXRRig | null;
@@ -12211,6 +12808,8 @@ export declare class NeedleXRSession implements INeedleXRSession {
     private readonly _xr_update_scripts;
     /** scripts that are in the scene but inactive (e.g. disabled parent gameObject) */
     private readonly _inactive_scripts;
+    /** tracks scripts that have received onEnterXR — prevents spurious onLeaveXR calls */
+    private readonly _scripts_in_xr;
     private readonly _controllerAdded;
     private readonly _controllerRemoved;
     private readonly _originalCameraWorldPosition?;
@@ -12598,7 +13197,7 @@ export declare class NetworkConnection implements INetworkConnection {
     /** Use to leave a room that you are currently connected to (use `leaveRoom()` to disconnect from the currently active room but you can also specify a room name) */
     leaveRoom(room?: string | null): boolean;
     /** Send a message to the networking backend - it will be broadcasted to all connected users (except yourself) in the same room by default */
-    send<K extends NetworkEventKey>(key: K, data?: (K extends keyof NetworkEventMap ? NetworkEventData<K> : WebsocketSendType) | null, queue?: SendQueue): void;
+    send<K extends NetworkEventKey>(key: K, data?: (K extends keyof NetworkEventMap ? NetworkEventData<K> : WebsocketSendType), queue?: SendQueue): void;
     /**
      * Deletes the network state for a specific object on the server.
      * This removes the object's state from the room, preventing it from being sent to newly joining users.
@@ -12620,61 +13219,69 @@ export declare class NetworkConnection implements INetworkConnection {
     private _defaultMessagesBufferArray;
     sendBufferedMessagesNow(): void;
     /** Use to start listening to networking events.
-     * To unsubscribe from events use the `{@link stopListen}` method.
+     * Returns an unsubscribe function that removes the listener when called.
+     * The returned function can also be passed to {@link stopListen} or {@link Component.autoCleanup} for automatic lifecycle management.
      *
-     * @example Custom event example
+     * @example With autoCleanup (recommended)
      * ```ts
-     * // Listen to a custom event sent by the server
-     * this.context.connection.beginListen<MyDataType>("my-custom-event", (data) => {
-     *   console.log("Received custom event:", data);
-     * });
+     * export class MyComponent extends Behaviour {
+     *   onEnable() {
+     *     this.autoCleanup(this.context.connection.beginListen("joined-room", () => {
+     *       console.log("I joined a networked room");
+     *     }));
+     *   }
+     *   // Automatically unsubscribed on disable — no manual cleanup needed!
+     * }
      * ```
      *
-     * @example Listening to room events
+     * @example Manual unsubscribe
+     * ```ts
+     * const unsub = this.context.connection.beginListen("joined-room", () => { });
+     * // Later:
+     * unsub(); // removes the listener
+     * ```
+     *
+     * @example With stopListen (legacy pattern, still supported)
      * ```ts
-     * // Make sure to unsubscribe from events when the component is disabled
      * export class MyComponent extends Behaviour {
      *   onEnable() {
-     *     this.connection.beginListen("joined-room", this.onJoinedRoom)
+     *     this.context.connection.beginListen("joined-room", this.onJoinedRoom);
      *   }
      *   onDisable() {
-     *     this.connection.stopListen("joined-room", this.onJoinedRoom)
+     *     this.context.connection.stopListen("joined-room", this.onJoinedRoom);
      *   }
      *   onJoinedRoom = () => {
-     *      console.log("I joined a networked room")
+     *     console.log("I joined a networked room");
      *   }
      * }
      * ```
      * @link https://engine.needle.tools/docs/networking.html
      *
      */
-    beginListen<K extends NetworkEventKey>(key: K, callback: K extends keyof NetworkEventMap ? NetworkEventMap[K] : (...args: any[]) => void): K extends keyof NetworkEventMap ? NetworkEventMap[K] : (...args: any[]) => void;
+    beginListen<K extends NetworkEventKey>(key: K, callback: K extends keyof NetworkEventMap ? NetworkEventMap[K] : (...args: any[]) => void): DisposeFn;
     /**@deprecated please use stopListen instead (2.65.2-pre) */
     stopListening<K extends NetworkEventKey>(key: K, callback: (K extends keyof NetworkEventMap ? NetworkEventMap[K] : (...args: any[]) => void) | null): void;
-    /** Use to stop listening to networking events
+    /** Use to stop listening to networking events.
+     * Accepts either the original callback or the unsubscribe function returned by {@link beginListen}.
      * To subscribe to events use the `{@link beginListen}` method.
-     * See the example below for typical usage:
      *
-     * ### Component Example
+     * @example
      * ```ts
-     * // Make sure to unsubscribe from events when the component is disabled
-     * export class MyComponent extends Behaviour {
-     *   onEnable() {
-     *     this.connection.beginListen("joined-room", this.onJoinedRoom)
-     *   }
-     *   onDisable() {
-     *     this.connection.stopListen("joined-room", this.onJoinedRoom)
-     *   }
-     *   onJoinedRoom = () => {
-     *      console.log("I joined a networked room")
-     *   }
-     * }
+     * // Both patterns work:
+     * this.context.connection.stopListen("joined-room", this.onJoinedRoom); // original callback
+     * this.context.connection.stopListen("joined-room", unsub);             // unsubscribe fn from beginListen
      * ```
      */
-    stopListen<K extends NetworkEventKey>(key: K, callback: (K extends keyof NetworkEventMap ? NetworkEventMap[K] : (...args: any[]) => void) | null): void;
-    /** Use to start listening to networking binary events */
-    beginListenBinary(identifier: string, callback: BinaryCallback): BinaryCallback;
-    /** Use to stop listening to networking binary events */
+    private static _didLogStopListenHint;
+    stopListen<K extends NetworkEventKey>(key: K, callback: (K extends keyof NetworkEventMap ? NetworkEventMap[K] : (...args: any[]) => void) | Function | null): void;
+    /** Use to start listening to networking binary events.
+     * Returns an unsubscribe function that removes the listener when called.
+     * The returned function can also be passed to {@link stopListenBinary} or {@link Component.autoCleanup}.
+     */
+    beginListenBinary(identifier: string, callback: BinaryCallback): DisposeFn;
+    /** Use to stop listening to networking binary events.
+     * Accepts either the original callback or the unsubscribe function returned by {@link beginListenBinary}.
+     */
     stopListenBinary(identifier: string, callback: any): void;
     private netWebSocketUrlProvider?;
     /** Use to override the networking server backend url.
@@ -12683,16 +13290,19 @@ export declare class NetworkConnection implements INetworkConnection {
     registerProvider(prov: INetworkingWebsocketUrlProvider): void;
     /** Used to connect to the networking server
      * @param url Optional url to connect to. If not provided, it will use the url from the registered `INetworkingWebsocketUrlProvider` or the default backend networking url. If you want to change the url after connecting, you need to disconnect first and then connect again with the new url.
+     * @param transport Optional custom transport to use instead of the default websocket. Useful for testing or alternative transports.
      */
-    connect(url?: string): Promise<boolean>;
+    connect(url?: string, transport?: INetworkTransport): Promise<boolean>;
     /** Disconnect from the networking backend + reset internal state */
     disconnect(): void;
+    /** Full teardown: disconnect, clear all listeners, and release all resources.
+     * Called when the owning Context is destroyed. After dispose(), this instance should not be reused. */
+    dispose(): void;
     private _listeners;
     private _listenersBinary;
     private connected;
-    private channelId;
     private _connectionId;
-    private _ws;
+    private _transport;
     private _waitingForSocket;
     private _isInRoom;
     private _currentRoomName;
@@ -12702,6 +13312,8 @@ export declare class NetworkConnection implements INetworkConnection {
     private _state;
     private _currentDelay;
     private _connectingToWebsocketPromise;
+    /** Wire up a transport's event callbacks and start it */
+    private connectTransport;
     private connectWebsocket;
     private onMessage;
     private handleIncomingBinaryMessage;
@@ -12830,7 +13442,7 @@ export declare interface NetworkEventMap {
  * @see {@link RoomEvents} for room lifecycle events
  * @see {@link isLocalNetwork} for local network detection
  * @link https://engine.needle.tools/docs/how-to-guides/networking/
- * @summary Networking configuration
+ * @summary Configures the websocket server URL for multiplayer networking
  * @category Networking
  * @group Components
  */
@@ -12967,7 +13579,7 @@ export declare type OBJ = {
     scenes: Object3D[];
 };
 
-declare type ObjectCloneReference = {
+export declare type ObjectCloneReference = {
     readonly original: object;
     readonly clone: object;
 };
@@ -13174,6 +13786,61 @@ export declare function offXRSessionEnd(fn: (evt: XRSessionEventArgs) => void):
  */
 export declare function offXRSessionStart(fn: (evt: XRSessionEventArgs) => void): void;
 
+/**
+ * @experimental
+ * Subscribe to a DOM event on any {@link EventTarget} (window, document, HTML elements, etc.)
+ * and return an {@link IDisposable} that removes the listener when disposed.
+ *
+ * Provides full TypeScript event type inference — the callback parameter
+ * is automatically typed based on the event name (e.g. `"resize"` → `UIEvent`,
+ * `"click"` → `MouseEvent`).
+ *
+ * Use with {@link DisposableStore.add} for automatic lifecycle cleanup in components.
+ *
+ * @param target The EventTarget to listen on (window, document, an element, etc.)
+ * @param type The event name (e.g. `"resize"`, `"click"`, `"keydown"`)
+ * @param listener The event handler callback
+ * @param options Optional addEventListener options (passive, capture, once, signal)
+ * @returns An {@link IDisposable} that removes the event listener when disposed
+ *
+ * @example Standalone usage
+ * ```ts
+ * import { on } from "@needle-tools/engine";
+ *
+ * const sub = on(window, "resize", (ev) => {
+ *     // ev is typed as UIEvent
+ *     console.log("resized", ev.target);
+ * });
+ *
+ * // Later: clean up
+ * sub.dispose();
+ * ```
+ *
+ * @example With autoCleanup in a component
+ * ```ts
+ * import { Behaviour, on } from "@needle-tools/engine";
+ *
+ * export class MyComponent extends Behaviour {
+ *     onEnable() {
+ *         this.autoCleanup(on(window, "resize", (ev) => { /* UIEvent *\/ }));
+ *         this.autoCleanup(on(document, "keydown", (ev) => { /* KeyboardEvent *\/ }));
+ *         this.autoCleanup(on(this.context.domElement, "click", (ev) => { /* MouseEvent *\/ }));
+ *     }
+ *     // All listeners removed automatically on disable!
+ * }
+ * ```
+ *
+ * @category Utilities
+ * @group Lifecycle
+ */
+export declare function on<K extends keyof WindowEventMap>(target: Window, type: K, listener: (ev: WindowEventMap[K]) => void, options?: boolean | AddEventListenerOptions): IDisposable;
+
+export declare function on<K extends keyof DocumentEventMap>(target: Document, type: K, listener: (ev: DocumentEventMap[K]) => void, options?: boolean | AddEventListenerOptions): IDisposable;
+
+export declare function on<K extends keyof HTMLElementEventMap>(target: HTMLElement, type: K, listener: (ev: HTMLElementEventMap[K]) => void, options?: boolean | AddEventListenerOptions): IDisposable;
+
+export declare function on(target: EventTarget, type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): IDisposable;
+
 /**
  * Register a callback in the engine onAfterRender event
  * This is called every frame after the main camera has rendered
@@ -13808,14 +14475,13 @@ export declare class OrbitControls extends Component implements ICameraControlle
        */
       private setLookTargetFromConstraint;
       private lerpLookTarget;
+      private canFocusAtPointer;
       private setTargetFromRaycast;
       /**
        * Fits the camera to show the objects provided (defaults to the scene if no objects are passed in)
        * @param options The options for fitting the camera. Use to provide objects to fit to, fit direction and size and other settings.
        */
       fitCamera(options?: OrbitFitCameraOptions): any;
-      /** @deprecated Use fitCamera(options) */
-      fitCamera(objects?: Object3D | Array<Object3D>, options?: Omit<OrbitFitCameraOptions, "objects">): any;
       private _haveAttachedKeyboardEvents;
      }
 
@@ -14016,6 +14682,11 @@ export declare class OrbitControls extends Component implements ICameraControlle
          value: number | boolean | string;
      };
 
+     /** Extracts parameter names of a given type from the builder's tracked parameter map */
+     declare type ParamNamesOfType<TParams, PType extends string> = {
+         [K in keyof TParams & string]: TParams[K] extends PType ? K : never;
+     }[keyof TParams & string];
+
      declare type ParseNumber<T> = T extends `${infer U extends number}` ? U : never;
 
      /** Load a gltf file from a url. This is the core method used by Needle Engine to load gltf files. All known extensions are registered here.
@@ -14647,13 +15318,15 @@ export declare class OrbitControls extends Component implements ICameraControlle
           * The timeline asset containing tracks, clips, and markers that this director will play.
           * Assign a timeline asset exported from Unity or Blender to enable playback.
           */
-         playableAsset?: Models.TimelineAssetModel;
+         get playableAsset(): Models.TimelineAssetModel | undefined;
+         set playableAsset(value: Models.TimelineAssetModel | undefined);
+         private _playableAsset?;
          /**
           * When true, the timeline starts playing automatically when the component awakens.
           * Set to false to control playback manually via `play()`.
           * @default false
           */
-         playOnAwake?: boolean;
+         playOnAwake: boolean;
          /**
           * Determines how the timeline behaves when it reaches the end of its duration.
           * @default DirectorWrapMode.Loop
@@ -14731,15 +15404,15 @@ export declare class OrbitControls extends Component implements ICameraControlle
          /** Iterates over all tracks of the timeline
           * @returns all tracks of the timeline
           */
-         forEachTrack(): Generator<Tracks.TrackHandler, void, unknown>;
+         forEachTrack(): Generator<Tracks.TimelineTrackHandler, void, unknown>;
          /**
           * @returns all animation tracks of the timeline
           */
-         get animationTracks(): Tracks.AnimationTrackHandler[];
+         get animationTracks(): Tracks.TimelineAnimationTrack[];
          /**
           * @returns all audio tracks of the timeline
           */
-         get audioTracks(): Tracks.AudioTrackHandler[];
+         get audioTracks(): Tracks.TimelineAudioTrack[];
          /**
           * @returns all signal tracks of the timeline
           */
@@ -14747,7 +15420,15 @@ export declare class OrbitControls extends Component implements ICameraControlle
          /**
           * @returns all marker tracks of the timeline
           */
-         get markerTracks(): Tracks.MarkerTrackHandler[];
+         get markerTracks(): Tracks.TimelineMarkerTrack[];
+         /**
+          * @returns all activation tracks of the timeline
+          */
+         get activationTracks(): Tracks.TimelineActivationTrack[];
+         /**
+          * @returns all tracks of the timeline
+          */
+         get tracks(): ReadonlyArray<Tracks.TimelineTrackHandler>;
          /**
           * Iterates over all markers of the timeline, optionally filtering by type
           *
@@ -14761,13 +15442,13 @@ export declare class OrbitControls extends Component implements ICameraControlle
           *
           */
          foreachMarker<T extends Record<string, any>>(type?: string | null): Generator<(T & Models.MarkerModel)>;
-         private _guidsMap?;
-         /* Excluded from this release type: resolveGuids */
+         private _needsGraphRebuild;
          private _isPlaying;
          private _internalUpdateRoutine;
          private _isPaused;
          /** internal, true during the time stop() is being processed */
          private _isStopping;
+         /* Excluded from this release type: _isUserEvaluation */
          private _time;
          private _duration;
          private _weight;
@@ -14776,6 +15457,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private readonly _signalTracks;
          private readonly _markerTracks;
          private readonly _controlTracks;
+         private readonly _activationTracks;
          private readonly _customTracks;
          private readonly _tracksArray;
          private get _allTracks();
@@ -15767,6 +16449,9 @@ export declare class OrbitControls extends Component implements ICameraControlle
          w: number;
      };
 
+     /** A Quaternion value, either as a Three.js Quaternion or as a `[x, y, z, w]` tuple */
+     declare type QuatValue = Quaternion | [number, number, number, number];
+
      /** Generates a random number
       * @deprecated use Mathf.random(min, max)
       */
@@ -15892,6 +16577,11 @@ export declare class OrbitControls extends Component implements ICameraControlle
               * @default undefined
               */
              useIgnoreRaycastLayer?: boolean;
+             /** When true, trigger/sensor colliders will be included in the raycast results.
+              * By default trigger colliders are skipped.
+              * @default false
+              */
+             includeTriggers?: boolean;
          }): null | {
              point: Vector3;
              collider: ICollider;
@@ -15909,6 +16599,11 @@ export declare class OrbitControls extends Component implements ICameraControlle
               * @default undefined
               */
              useIgnoreRaycastLayer?: boolean;
+             /** When true, trigger/sensor colliders will be included in the raycast results.
+              * By default trigger colliders are skipped.
+              * @default false
+              */
+             includeTriggers?: boolean;
          }): null | {
              point: Vector3;
              normal: Vector3;
@@ -15954,6 +16649,10 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private _gravity;
          get gravity(): Vec3;
          set gravity(value: Vec3);
+         /** Tears down the physics world and frees all WASM resources.
+          * After calling this, the world will be re-created on next use. */
+         dispose(): void;
+         /** @deprecated Use {@link dispose} instead. */
          clearCaches(): void;
          addBoxCollider(collider: ICollider, size: Vector3): Promise<void>;
          addSphereCollider(collider: ICollider): Promise<void>;
@@ -16000,7 +16699,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private getRigidbodyRelativeMatrix;
          private static centerConnectionPos;
          private static centerConnectionRot;
-         addFixedJoint(body1: IRigidbody, body2: IRigidbody): void;
+         private _jointTempMatrix;
+         addFixedJoint(body1: IRigidbody, body2: IRigidbody): Promise<ImpulseJoint | null>;
          /** The joint prevents any relative movement between two rigid-bodies, except for relative rotations along one axis. This is typically used to simulate wheels, fans, etc. They are characterized by one local anchor as well as one local axis on each rigid-body. */
          addHingeJoint(body1: IRigidbody, body2: IRigidbody, anchor: {
              x: number;
@@ -16010,8 +16710,11 @@ export declare class OrbitControls extends Component implements ICameraControlle
              x: number;
              y: number;
              z: number;
-         }): void;
+         }): Promise<ImpulseJoint | null>;
+         removeJoint(joint: ImpulseJoint): void;
+         /** Compute the relative transform from body1's local space to body2's local space (W2⁻¹ * W1), ignoring scale. */
          private calculateJointRelativeMatrices;
+         private normalizeMatrixColumns;
      }
 
      /**
@@ -16814,10 +17517,17 @@ export declare class OrbitControls extends Component implements ICameraControlle
       */
      export declare class Rigidbody extends Component implements IRigidbody {
          get isRigidbody(): boolean;
-         /** When true the mass will be automatically calculated by the attached colliders */
+         /** When true the mass is automatically computed from the attached colliders using `mass = density × volume`.
+          * Each collider's {@link Collider.density} determines how heavy it contributes to the total mass.
+          * Disable to set mass explicitly via the `mass` property.
+          */
          autoMass: boolean;
-         /** By default the mass will be automatically calculated (see `autoMass`) by the physics engine using the collider sizes
-          * To set the mass manually you can either set the `mass` value or set `autoMass` to `false`
+         /** The mass of the rigidbody in kg (when `autoMass` is disabled).
+          * When `autoMass` is enabled, reading this returns the computed mass from `density × volume` of all attached colliders.
+          * Setting this property automatically disables `autoMass`.
+          *
+          * **Prefer using {@link Collider.density}** with `autoMass` enabled instead — density scales
+          * naturally with collider size, while explicit mass stays fixed regardless of shape changes.
           */
          set mass(value: number);
          get mass(): number;
@@ -16900,7 +17610,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
          onEnable(): void;
          onDisable(): void;
          onDestroy(): void;
-         onValidate(): void;
+         onValidate(property?: string): void;
+         private static _didWarnAutoMass;
          beforePhysics(): Generator<undefined, void, unknown>;
          /** Teleport the rigidbody to a new position in the world.
           * Will reset forces before setting the object world position
@@ -18120,10 +18831,17 @@ export declare class OrbitControls extends Component implements ICameraControlle
 
      export declare function sendDestroyed(guid: string, con: INetworkConnection, opts?: SyncDestroyOptions): void;
 
+     /** Controls when a network message is actually sent to the server.
+      * @see {@link NetworkConnection.send}
+      */
      export declare enum SendQueue {
+         /** Hold the message until the transport connection opens, then send it. Use for messages that must arrive as soon as the socket is ready (e.g. join-room). */
          OnConnection = 0,
+         /** Hold the message until the client has joined a room, then send it. Use for messages that require room context. */
          OnRoomJoin = 1,
+         /** Buffer the message and send it on the next `sendBufferedMessagesNow()` call (typically once per frame). This is the default for `send()`. */
          Queued = 2,
+         /** Send the message to the server immediately without buffering. */
          Immediate = 3
      }
 
@@ -18556,6 +19274,16 @@ export declare class OrbitControls extends Component implements ICameraControlle
          asset: string;
      }
 
+     /**
+      * Options for a signal marker in the timeline builder
+      */
+     export declare type SignalMarkerOptions = {
+         /** Whether the signal should fire if the playback starts past its time (default: false) */
+         retroActive?: boolean;
+         /** Whether the signal should only fire once (default: false) */
+         emitOnce?: boolean;
+     };
+
      /** SignalReceiver is a component that listens for signals and invokes a reaction when a signal is received.
       * Signals can be added to a signal track on a {@link PlayableDirector}
       *
@@ -18563,7 +19291,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * @category Animation and Sequencing
       * @group Components
       */
-     export declare class SignalReceiver extends Component {
+     export declare class SignalReceiver extends Component implements ISignalReceiver {
+         readonly isSignalReceiver = true;
          private static receivers;
          static invoke(guid: string): void;
          events?: SignalReceiverEvent[];
@@ -18582,10 +19311,26 @@ export declare class OrbitControls extends Component implements ICameraControlle
          reaction: EventList<void>;
      }
 
-     export declare class SignalTrackHandler extends TrackHandler {
+     /**
+      * Builder for signal tracks. Provides `.signal()` for callback-based signals and `.marker()` for asset-based markers.
+      * @category Animation and Sequencing
+      */
+     export declare interface SignalTrackBuilder extends TimelineBuilderBase {
+         /** Adds a signal with a callback that fires at the given time */
+         signal(time: number, callback: Function, options?: SignalMarkerOptions): SignalTrackBuilder;
+         /** Adds a signal marker referencing a signal asset by guid */
+         marker(time: number, asset: string, options?: SignalMarkerOptions): SignalTrackBuilder;
+         /** Mutes this track so it is skipped during playback */
+         muted(muted?: boolean): SignalTrackBuilder;
+     }
+
+     export declare class SignalTrackHandler extends TimelineTrackHandler {
          models: Models.SignalMarkerModel[];
          didTrigger: boolean[];
          receivers: Array<SignalReceiver | null>;
+         private _lastTime;
+         onEnable(): void;
+         onMuteChanged(): void;
          evaluate(time: number): void;
      }
 
@@ -19085,10 +19830,6 @@ export declare class OrbitControls extends Component implements ICameraControlle
           * Removes scale change monitoring when the collider is disabled.
           */
          onDisable(): void;
-         /**
-          * Updates collider properties when validated in the editor or inspector.
-          */
-         onValidate(): void;
      }
 
      export declare class SphereIntersection implements Intersection {
@@ -19841,8 +20582,15 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * Configuration for an animation state in the builder
       */
      export declare type StateOptions = {
-         /** The animation clip for this state */
-         clip: AnimationClip;
+         /**
+          * The animation clip for this state. Accepts:
+          * - A pre-built `AnimationClip`
+          * - A single {@link TrackDescriptor} from {@link track}
+          * - An array of {@link TrackDescriptor}s (multiple tracks combined into one clip)
+          *
+          * When omitted, use {@link AnimatorControllerBuilder.track .track()} to define animation tracks inline.
+          */
+         clip?: AnimationClip | TrackDescriptor | TrackDescriptor[];
          /** Whether the animation should loop (default: false) */
          loop?: boolean;
          /** Base speed multiplier (default: 1) */
@@ -20408,6 +21156,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
          set font(val: string | null);
          get font(): string | null;
          private _font;
+         private _assignedAtRuntime;
          /**
           * Whether to support basic rich text tags in the `text` property. Supported tags include `<b>`, `<i>`, and `<color=hex>`. For example: `Hello <b>World</b>` or `Score: <color=#ff0000>100</color>`
           * @default false
@@ -20663,6 +21412,57 @@ export declare class OrbitControls extends Component implements ICameraControlle
          /* Excluded from this release type: update */
      }
 
+     /**
+      * Handles activation (visibility) of bound objects for a timeline activation track.
+      *
+      * Each clip on the track defines a time range during which the bound objects should be active (visible).
+      * @see TimelineTrackHandler for details on how tracks and clips work in general, and how to mutate them at runtime.
+      * @see PlayableDirector for how to control timeline playback and time.
+      * @see TimelineBuilder for how to create and configure timelines and tracks in the editor.
+      */
+     export declare class TimelineActivationTrack extends TimelineTrackHandler {
+         evaluate(time: number): void;
+     }
+
+     export declare class TimelineAnimationTrack extends TimelineTrackHandler {
+         /* Excluded from this release type: models */
+         /* Excluded from this release type: trackOffset */
+         /** The object that is being animated. */
+         target?: Object3D;
+         /** The AnimationMixer, should be shared with the animator if an animator is bound */
+         mixer?: AnimationMixer;
+         clips: Array<AnimationClip>;
+         actions: Array<AnimationAction>;
+         /**
+          * You can use the weight to blend the timeline animation tracks with multiple animation tracks on the same object.
+          * @default 1
+          */
+         weight: number;
+         /** holds data/info about clips differences */
+         private _actionOffsets;
+         private _didBind;
+         private _animator;
+         onDisable(): void;
+         onDestroy(): void;
+         onStateChanged(): void;
+         createHooks(clipModel: Models.AnimationClipModel, clip: any): void;
+         bind(): void;
+         private ensureTrackOffsets;
+         private _useclipOffsets;
+         private _totalOffsetPosition;
+         private _totalOffsetRotation;
+         private _totalOffsetPosition2;
+         private _totalOffsetRotation2;
+         private _summedPos;
+         private _tempPos;
+         private _summedRot;
+         private _tempRot;
+         private _clipRotQuat;
+         evaluate(time: number): void;
+         private createRotationInterpolant;
+         private createPositionInterpolant;
+     }
+
      /**
       * @category Animation and Sequencing
       * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
@@ -20672,6 +21472,325 @@ export declare class OrbitControls extends Component implements ICameraControlle
          tracks: TrackModel[];
      };
 
+     /**
+      * Handles audio playback for a timeline audio track.
+      *
+      * **Runtime mutation:** The track model is read fresh every frame during `evaluate()`.
+      * You can mutate `track.volume`, `clip.start`, `clip.end`, `clip.asset.volume` etc.
+      * at any time — changes take effect on the next frame without rebuilding the timeline.
+      *
+      * **Audio stopping:** Audio clips are automatically stopped when:
+      * - Timeline time moves outside a clip's `[start, end]` range (e.g. jumping or normal playback advancing past a clip)
+      * - The track is muted (via `muted = true`)
+      * - The director is stopped (`director.stop()`)
+      * - The director is paused (`director.pause()`)
+      * - The director is disabled or destroyed
+      */
+     export declare class TimelineAudioTrack extends TimelineTrackHandler {
+         models: Array<AudioClipModel_2>;
+         listener: AudioListener_3;
+         audio: Array<Audio_2>;
+         audioContextTimeOffset: Array<number>;
+         lastTime: number;
+         audioSource?: AudioSource;
+         /** Track-level volume multiplier (0–1). Applied on top of per-clip volume each frame. */
+         get volume(): number;
+         set volume(val: number);
+         private _audioLoader;
+         private getAudioFilePath;
+         onAllowAudioChanged(allow: boolean): void;
+         addModel(model: Models.ClipModel): void;
+         onDisable(): void;
+         onDestroy(): void;
+         onMuteChanged(): void;
+         stop(): void;
+         private _playableDirectorResumed;
+         onPauseChanged(): void;
+         evaluate(time: number): void;
+         /** Call to load audio buffer for a specific time in the track. Can be used to preload the timeline audio */
+         loadAudio(time: number, lookAhead?: number, lookBehind?: number): Promise<(AudioBuffer | null)[]> | null;
+         private isInTimeRange;
+         private static _audioBuffers;
+         static dispose(): void;
+         private handleAudioLoading;
+     }
+
+     /**
+      * A fluent builder for creating timeline assets ({@link TimelineAssetModel}) from code.
+      *
+      * Use {@link TimelineBuilder.create} to start building a timeline.
+      *
+      * @example Using build() for timelines without signal callbacks
+      * ```ts
+      * const timeline = TimelineBuilder.create("MySequence")
+      *     .animationTrack("Character", animator)
+      *         .clip(walkClip, { duration: 2, easeIn: 0.3 })
+      *         .clip(runClip, { duration: 3, easeIn: 0.5, easeOut: 0.5 })
+      *     .activationTrack("FX", particleObject)
+      *         .clip({ start: 1, duration: 2 })
+      *     .audioTrack("Music", audioSource)
+      *         .clip("music.mp3", { start: 0, duration: 5, volume: 0.8 })
+      *     .build();
+      *
+      * director.playableAsset = timeline;
+      * director.play();
+      * ```
+      *
+      * @example With inline tracks (no pre-built clips needed)
+      * ```ts
+      * TimelineBuilder.create("DoorSequence")
+      *     .animationTrack("Door", door)
+      *         .track(door, "position", { from: [0, 0, 0], to: [2, 0, 0], duration: 1 })
+      *         .track(light, "intensity", { from: 0, to: 5, duration: 1 })
+      *     .signalTrack("Events")
+      *         .signal(0.5, () => playSound("creak"))
+      *     .install(director);
+      *
+      * director.play();
+      * ```
+      *
+      * @example Using install() with signal callbacks
+      * ```ts
+      * TimelineBuilder.create("WithSignals")
+      *     .animationTrack("Character", animator)
+      *         .clip(walkClip, { duration: 2 })
+      *     .signalTrack("Events")
+      *         .signal(1.0, () => console.log("1 second!"))
+      *         .signal(2.0, () => spawnParticles())
+      *     .install(director);
+      *
+      * director.play();
+      * ```
+      *
+      * @category Animation and Sequencing
+      * @group Utilities
+      */
+     export declare class TimelineBuilder {
+         private _name;
+         private _tracks;
+         private _currentTrack;
+         private _pendingSignals;
+         private _idProvider;
+         private constructor();
+         /**
+          * Creates a new TimelineBuilder instance.
+          * @param name - Name for the timeline asset
+          * @param seed - Optional numeric seed for deterministic guid generation. Defaults to `Date.now()`.
+          */
+         static create(name?: string, seed?: number): TimelineBuilderBase;
+         /**
+          * Adds an animation track. Chain `.clip()` calls to add pre-built clips,
+          * or chain `.track()` calls to define animation data inline:
+          *
+          * @example With pre-built AnimationClip
+          * ```ts
+          * .animationTrack("Character", animator)
+          *     .clip(walkClip, { duration: 2, easeIn: 0.3 })
+          *     .clip(runClip, { duration: 3 })
+          * ```
+          *
+          * @example With inline tracks
+          * ```ts
+          * .animationTrack("Door", door)
+          *     .track(door, "position", { from: [0, 0, 0], to: [2, 0, 0], duration: 1 })
+          *     .track(light, "intensity", { from: 0, to: 5, duration: 1 })
+          * ```
+          *
+          * @param name - Display name for the track
+          * @param binding - The Animator or Object3D to animate
+          */
+         animationTrack(name: string, binding?: Animator | Object3D | null): AnimationTrackBuilder;
+         /**
+          * Adds an audio track. Subsequent `.clip()` calls add audio clips to this track.
+          * @param name - Display name for the track
+          * @param binding - The AudioSource to play audio on (optional)
+          * @param volume - Track volume multiplier (default: 1)
+          */
+         audioTrack(name: string, binding?: AudioSource | Object3D | null, volume?: number): AudioTrackBuilder;
+         /**
+          * Adds an activation track. Subsequent `.clip()` calls define when the bound object is active.
+          * @param name - Display name for the track
+          * @param binding - The Object3D to show/hide
+          */
+         activationTrack(name: string, binding?: Object3D | null): ActivationTrackBuilder;
+         /**
+          * Adds a control track. Subsequent `.clip()` calls control nested timelines or objects.
+          * @param name - Display name for the track
+          */
+         controlTrack(name: string): ControlTrackBuilder;
+         /**
+          * Adds a signal track. Use `.signal()` or `.marker()` to add signal markers.
+          * @param name - Display name for the track
+          * @param binding - The SignalReceiver component (optional — if using `.signal()` with callbacks, one is created automatically by {@link install})
+          */
+         signalTrack(name: string, binding?: SignalReceiver | Object3D | null): SignalTrackBuilder;
+         /**
+          * Adds a marker track. Use `.marker()` to add markers.
+          * @param name - Display name for the track
+          */
+         markerTrack(name: string): MarkerTrackBuilder;
+         /**
+          * Adds a clip to the current track. The clip type must match the track type.
+          *
+          * - On an **animation track**: pass an `AnimationClip`, a {@link TrackDescriptor}, or a `TrackDescriptor[]` — and optional {@link AnimationClipOptions}
+          * - On an **audio track**: pass a clip URL (string) and {@link AudioClipOptions}
+          * - On an **activation track**: pass {@link ActivationClipOptions}
+          * - On a **control track**: pass an Object3D and {@link ControlClipOptions}
+          */
+         clip(asset: AnimationClip, options?: AnimationClipOptions): this;
+         clip(descriptor: TrackDescriptor, options?: AnimationClipOptions): this;
+         clip(descriptors: TrackDescriptor[], options?: AnimationClipOptions): this;
+         clip(url: string, options: AudioClipOptions): this;
+         clip(options: ActivationClipOptions): this;
+         clip(sourceObject: Object3D, options: ControlClipOptions): this;
+         /**
+          * Adds a signal marker to the current signal or marker track.
+          * @param time - Time in seconds when the signal fires
+          * @param asset - The signal asset identifier (guid string)
+          * @param options - Optional marker configuration
+          */
+         marker(time: number, asset: string, options?: SignalMarkerOptions): this;
+         /**
+          * Adds a signal with a callback to the current signal track.
+          * This is a convenience method that automatically generates a signal asset guid,
+          * adds the marker, and registers the callback so that {@link install} can wire up
+          * the `SignalReceiver` on the director's GameObject.
+          *
+          * @param time - Time in seconds when the signal fires
+          * @param callback - The function to invoke when the signal fires
+          * @param options - Optional marker configuration
+          *
+          * @example
+          * ```ts
+          * const timeline = TimelineBuilder.create("Sequence")
+          *     .signalTrack("Events")
+          *         .signal(1.0, () => console.log("1 second reached!"))
+          *         .signal(3.5, () => console.log("halfway!"), { emitOnce: true })
+          *     .install(director);
+          * ```
+          */
+         signal(time: number, callback: Function, options?: SignalMarkerOptions): this;
+         /**
+          * Mutes the current track so it is skipped during playback.
+          */
+         muted(muted?: boolean): this;
+         /** Adds an animation track descriptor for an Object3D's position or scale to the current animation track */
+         track(target: Object3D, property: "position" | "scale", keyframes: KF_3<Vec3Value>, options?: TrackOptions): this;
+         /** Adds an animation track descriptor for an Object3D's quaternion to the current animation track */
+         track(target: Object3D, property: "quaternion", keyframes: KF_3<QuatValue>, options?: TrackOptions): this;
+         /** Adds an animation track descriptor for an Object3D's rotation (Euler, converted to quaternion) to the current animation track */
+         track(target: Object3D, property: "rotation", keyframes: KF_3<EulerValue>, options?: TrackOptions): this;
+         /** Adds an animation track descriptor for an Object3D's visibility to the current animation track */
+         track(target: Object3D, property: "visible", keyframes: KF_3<boolean>, options?: TrackOptions): this;
+         /** Adds an animation track descriptor for a material's numeric property to the current animation track */
+         track(target: Material, property: "opacity" | "roughness" | "metalness" | "alphaTest" | "emissiveIntensity" | "envMapIntensity" | "bumpScale" | "displacementScale" | "displacementBias", keyframes: KF_3<number>, options?: TrackOptions): this;
+         /** Adds an animation track descriptor for a material's color property to the current animation track */
+         track(target: Material, property: "color" | "emissive", keyframes: KF_3<ColorValue>, options?: TrackOptions): this;
+         /** Adds an animation track descriptor for a light's numeric property to the current animation track */
+         track(target: Light_2, property: "intensity" | "distance" | "angle" | "penumbra" | "decay", keyframes: KF_3<number>, options?: TrackOptions): this;
+         /** Adds an animation track descriptor for a light's color to the current animation track */
+         track(target: Light_2, property: "color", keyframes: KF_3<ColorValue>, options?: TrackOptions): this;
+         /** Adds an animation track descriptor for a camera's numeric property to the current animation track */
+         track(target: PerspectiveCamera, property: "fov" | "near" | "far" | "zoom", keyframes: KF_3<number>, options?: TrackOptions): this;
+         /**
+          * Builds and returns the {@link TimelineAssetModel}.
+          * Assign the result to `PlayableDirector.playableAsset` to play it.
+          *
+          * If you used `.signal()` with callbacks, use {@link install} instead — it calls `build()`
+          * internally and also wires up the SignalReceiver on the director's GameObject.
+          */
+         build(): TimelineAssetModel;
+         /**
+          * Builds the timeline asset, assigns it to the director, and wires up any
+          * `.signal()` callbacks by creating/configuring a {@link SignalReceiver} on the
+          * director's GameObject.
+          *
+          * @param director - The PlayableDirector to install the timeline on
+          * @returns The built TimelineAssetModel (also assigned to `director.playableAsset`)
+          *
+          * @example
+          * ```ts
+          * TimelineBuilder.create("MyTimeline")
+          *     .animationTrack("Anim", animator)
+          *         .clip(walkClip, { duration: 2 })
+          *     .signalTrack("Events")
+          *         .signal(1.0, () => console.log("signal fired!"))
+          *     .install(director);
+          *
+          * director.play();
+          * ```
+          */
+         install(director: PlayableDirector): TimelineAssetModel;
+         private pushTrack;
+         /** Commits any pending `.track()` descriptors on the current animation track into a clip */
+         private commitInlineTracks;
+     }
+
+     /**
+      * Shared methods available on all track builders and the TimelineBuilder entry point.
+      * Provides track creation, build, and install methods.
+      *
+      * @category Animation and Sequencing
+      */
+     export declare interface TimelineBuilderBase {
+         /** Adds an animation track. Chain `.clip()` or `.track()` to add content. */
+         animationTrack(name: string, binding?: Animator | Object3D | null): AnimationTrackBuilder;
+         /** Adds an audio track. Chain `.clip()` to add audio clips. */
+         audioTrack(name: string, binding?: AudioSource | Object3D | null, volume?: number): AudioTrackBuilder;
+         /** Adds an activation track. Chain `.clip()` to define activation windows. */
+         activationTrack(name: string, binding?: Object3D | null): ActivationTrackBuilder;
+         /** Adds a control track. Chain `.clip()` to control nested objects/timelines. */
+         controlTrack(name: string): ControlTrackBuilder;
+         /** Adds a signal track. Chain `.signal()` or `.marker()` to add events. */
+         signalTrack(name: string, binding?: SignalReceiver | Object3D | null): SignalTrackBuilder;
+         /** Adds a marker track. Chain `.marker()` to add markers. */
+         markerTrack(name: string): MarkerTrackBuilder;
+         /** Builds and returns the {@link TimelineAssetModel}. */
+         build(): TimelineAssetModel;
+         /** Builds the timeline, assigns it to the director, and wires up signal callbacks. */
+         install(director: PlayableDirector): TimelineAssetModel;
+     }
+
+     export declare class TimelineControlTrack extends TimelineTrackHandler {
+         models: Array<Models.ClipModel>;
+         timelines: Array<PlayableDirector | null>;
+         resolveSourceObjects(_context: Context): void;
+         private _previousActiveModel;
+         evaluate(time: number): void;
+     }
+
+     export declare class TimelineMarkerTrack extends TimelineTrackHandler {
+         models: Array<Models.MarkerModel & Record<string, any>>;
+         needsSorting: boolean;
+         foreachMarker<T>(type?: string | null): Generator<T, void, unknown>;
+         onEnable(): void;
+         evaluate(_time: number): void;
+         private sort;
+     }
+
+     /**
+      * A TrackHandler is responsible for evaluating a specific type of timeline track.
+      * A timeline track can be an animation track, audio track, signal track, control track etc and is controlled by a {@link PlayableDirector}.
+      */
+     export declare abstract class TimelineTrackHandler {
+         director: PlayableDirector;
+         track: Models.TrackModel;
+         get muted(): boolean;
+         set muted(val: boolean);
+         forEachClip(backwards?: boolean): IterableIterator<Models.ClipModel>;
+         onEnable?(): any;
+         onDisable?(): any;
+         onDestroy?(): any;
+         abstract evaluate(time: number): any;
+         onMuteChanged?(): any;
+         onPauseChanged?(): any;
+         /** invoked when PlayableDirectory playmode state changes (paused, playing, stopped) */
+         onStateChanged?(isPlaying: boolean): any;
+         getClipTime(time: number, model: Models.ClipModel): number;
+         getClipTimeNormalized(time: number, model: Models.ClipModel): number;
+         evaluateWeight(time: number, index: number, models: Array<Models.ClipModel>, isActive?: boolean): number;
+     }
+
      declare type TonemappingAttributeOptions = "none" | "linear" | "neutral" | "agx";
 
      /**
@@ -20700,27 +21819,20 @@ export declare class OrbitControls extends Component implements ICameraControlle
      export declare function toSourceId(src: string | null): SourceIdentifier | undefined;
 
      /**
-      * A TrackHandler is responsible for evaluating a specific type of timeline track.
-      * A timeline track can be an animation track, audio track, signal track, control track etc and is controlled by a {@link PlayableDirector}.
+      * An opaque descriptor for a single animation track.
+      * Created by {@link track} and resolved into a Three.js KeyframeTrack
+      * when passed to {@link createAnimation}, or inline to
+      * {@link AnimatorControllerBuilder.state} / {@link TimelineBuilder.clip}.
+      *
+      * @category Animation and Sequencing
       */
-     export declare abstract class TrackHandler {
-         director: PlayableDirector;
-         track: Models.TrackModel;
-         get muted(): boolean;
-         set muted(val: boolean);
-         forEachClip(backwards?: boolean): IterableIterator<Models.ClipModel>;
-         onEnable?(): any;
-         onDisable?(): any;
-         onDestroy?(): any;
-         abstract evaluate(time: number): any;
-         onMuteChanged?(): any;
-         onPauseChanged?(): any;
-         /** invoked when PlayableDirectory playmode state changes (paused, playing, stopped) */
-         onStateChanged?(isPlaying: boolean): any;
-         getClipTime(time: number, model: Models.ClipModel): number;
-         getClipTimeNormalized(time: number, model: Models.ClipModel): number;
-         evaluateWeight(time: number, index: number, models: Array<Models.ClipModel>, isActive?: boolean): number;
-     }
+     declare type TrackDescriptor = {
+         readonly __isTrackDescriptor: true;
+         /* Excluded from this release type: _target */
+         /* Excluded from this release type: _property */
+         /* Excluded from this release type: _keyframes */
+         /* Excluded from this release type: _root */
+     };
 
      /**
       * @category Animation and Sequencing
@@ -20746,14 +21858,26 @@ export declare class OrbitControls extends Component implements ICameraControlle
          rotation: Quat | Quaternion;
      };
 
+     /** Options for a single track */
+     declare type TrackOptions = {
+         /**
+          * Root object for resolving the track path.
+          * - If `root === target` → self-targeting (`.property`)
+          * - If `root !== target` → named targeting (`"targetName.property"` using `target.name`)
+          * - If omitted → self-targeting by default
+          */
+         root?: Object3D;
+     };
+
      declare namespace Tracks {
          export {
-             TrackHandler,
-             AnimationTrackHandler,
-             AudioTrackHandler,
-             MarkerTrackHandler,
+             TimelineTrackHandler,
+             TimelineAnimationTrack,
+             TimelineAudioTrack,
+             TimelineMarkerTrack,
              SignalTrackHandler,
-             ControlTrackHandler
+             TimelineActivationTrack,
+             TimelineControlTrack
          }
      }
 
@@ -20959,10 +22083,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
      export declare type TransitionOptions = {
          /** Duration of the crossfade in seconds (default: 0) */
          duration?: number;
-         /** Normalized exit time 0-1 (default: 1). Only used when hasExitTime is true */
+         /** Normalized exit time 0-1. When set, the transition waits until the source animation reaches this point before transitioning. */
          exitTime?: number;
-         /** Whether the transition waits for exitTime before transitioning (default: false) */
-         hasExitTime?: boolean;
          /** Normalized offset into the destination state's animation (default: 0) */
          offset?: number;
          /** Whether duration is in seconds (true) or normalized (false) (default: false) */
@@ -21032,6 +22154,18 @@ export declare class OrbitControls extends Component implements ICameraControlle
 
      export declare function tryGetGuid(obj: any): string | undefined | null;
 
+     /** Shorthand for a simple two-keyframe animation (start → end) */
+     export declare type Tween<V> = {
+         /** Start value (at time 0) */
+         from: V;
+         /** End value (at time = duration) */
+         to: V;
+         /** Duration in seconds (default: 1) */
+         duration?: number;
+         /** Interpolation mode (default: `"linear"`) */
+         interpolation?: AnimationInterpolation;
+     };
+
      declare type Type = new (...args: any[]) => any;
 
      declare type TypeResolver<T> = (data: any) => Constructor<T> | null;
@@ -21555,6 +22689,9 @@ export declare class OrbitControls extends Component implements ICameraControlle
          z: number;
      };
 
+     /** A Vector3 value, either as a Three.js Vector3 or as a `[x, y, z]` tuple */
+     declare type Vec3Value = Vector3 | [number, number, number];
+
      export declare type Vec4 = {
          x: number;
          y: number;
@@ -21775,8 +22912,14 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private _receivedInput;
          /* Excluded from this release type: __constructor */
          private _playErrors;
-         /** start playing the video source */
-         play(): void;
+         /**
+          * Plays the assigned video clip, URL, or MediaStream.
+          * If a `clip` argument is passed, it is used as the new video source (mirroring {@link AudioSource.play}).
+          *
+          * @param clip - Optional video URL string or {@link MediaStream} to play. If omitted, plays the currently assigned source.
+          * @returns A promise that resolves to `true` when playback was successfully started, or `false` on error.
+          */
+         play(clip?: string | MediaStream): Promise<boolean>;
          /**
           * Stop the video playback. This will reset the video to the beginning
           */
@@ -22046,9 +23189,9 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * voip.createMenuButton = true;
       *
       * // Manual control
-      * voip.connect();    // Start sending audio
-      * voip.disconnect(); // Stop sending
-      * voip.setMuted(true); // Mute microphone
+      * voip.connect();    // Start sending your microphone
+      * voip.disconnect(); // Stop sending your microphone
+      * voip.setMuted(true); // Mute incoming audio (silence other users)
       * ```
       *
       * @summary Voice over IP for networked audio communication
@@ -22107,8 +23250,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
           */
          get incomingStreams(): ReadonlyMap<string, HTMLAudioElement>;
          /**
-          * Threshold for speaking detection (0–255). When a user's audio amplitude exceeds this,
-          * they are considered "speaking". Default is 30.
+          * Normalized amplitude threshold for speaking detection (0–1). When a user's average
+          * audio amplitude exceeds this, they are considered "speaking". Default is 0.1.
           */
          speakingThreshold: number;
          /**
@@ -22118,6 +23261,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
          onSpeakingChanged: EventList;
          private _speakingStates;
          private _analysers;
+         private _sharedAudioContext?;
+         private _lastSpeakingPollMs;
          private _net?;
          private _menubutton?;
          /* Excluded from this release type: awake */
@@ -22127,21 +23272,27 @@ export declare class OrbitControls extends Component implements ICameraControlle
          /** Set via the mic button (e.g. when the websocket connection closes and rejoins but the user was muted before we don't want to enable VOIP again automatically) */
          private _allowSending;
          private _outputStream;
+         private _connectInFlight?;
          /**
           * @returns true if the component is currently sending audio
           */
          get isSending(): boolean;
          /** Start sending audio. */
          connect(audioSource?: MediaTrackConstraints): Promise<boolean>;
+         private _connectImpl;
          /** Stop sending audio (muting your own microphone) */
          disconnect(opts?: {
              remember: boolean;
          }): void;
          /**
-          * Mute or unmute the audio stream (this will only mute incoming streams and not mute your own microphone. Use disconnect() to mute your own microphone)
+          * Mute or unmute the audio you hear from other users (incoming streams).
+          * This does NOT mute your own microphone — use {@link disconnect} to stop sending your microphone.
           */
          setMuted(mute: boolean): void;
-         /** Returns true if the audio stream is currently muted */
+         /**
+          * Returns true if incoming audio is currently muted (you can't hear other users).
+          * When there are no incoming streams, returns false.
+          */
          get isMuted(): boolean;
          private updateButton;
          /** @deprecated */
@@ -22153,6 +23304,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
          /* Excluded from this release type: update */
          private setupAnalyser;
          private cleanupAnalyser;
+         private closeSharedAudioContext;
          private onReceiveStream;
          private onStreamEnded;
          private onEnabledChanged;
@@ -22476,7 +23628,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private onApplyPose;
      }
 
-     declare type WebsocketSendType = IModel | object | boolean | null | string | number;
+     declare type WebsocketSendType = IModel | object | boolean | string | number;
 
      /**
       * Use the [WebXR](https://engine.needle.tools/docs/api/WebXR) component to enable VR and AR on **iOS and Android** in your scene. VisionOS support is also provided via QuickLook USDZ export.
@@ -22870,6 +24022,25 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * @link https://github.com/immersive-web/marker-tracking/blob/main/explainer.md - WebXR Marker Tracking Specification
       */
      export declare class WebXRImageTracking extends Component {
+         /**
+          * Event invoked every frame when images are being tracked.
+          * @example
+          * ```ts
+          * const tracker = this.gameObject.getComponent(WebXRImageTracking);
+          * tracker?.imageTracked.addEventListener(evt => {
+          *   for (const img of evt.trackedImages) {
+          *     console.log(img.url, img.state);
+          *   }
+          * });
+          * ```
+          */
+         imageTracked: EventList<WebXRImageTrackingEvent>;
+         /** @inheritdoc */
+         addEventListener<K extends keyof WebXRImageTrackingEventMap>(type: K, listener: (evt: WebXRImageTrackingEventMap[K]) => any): void;
+         addEventListener<T extends Event>(type: string, listener: (evt: T) => any): void;
+         /** @inheritdoc */
+         removeEventListener<K extends keyof WebXRImageTrackingEventMap>(type: K, listener: (evt: WebXRImageTrackingEventMap[K]) => any): void;
+         removeEventListener<T extends Event>(type: string, listener: (evt: T) => any): void;
          /**
           * Set which marker should be primary (first in the list).
           * Useful when deploying to QuickLook mode where one marker is tracked at a time.
@@ -22956,6 +24127,18 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private onImageTrackingUpdate;
      }
 
+     /** Data passed to image tracking event listeners. */
+     export declare interface WebXRImageTrackingEvent {
+         /** The images currently being tracked this frame. */
+         readonly trackedImages: readonly WebXRTrackedImage[];
+     }
+
+     /** Event map for {@link WebXRImageTracking} events. Use with `addEventListener` for typed event handling. */
+     export declare interface WebXRImageTrackingEventMap {
+         /** Dispatched every frame when images are being tracked. The event detail contains the tracking data for the current frame. */
+         "image-tracking": CustomEvent<WebXRImageTrackingEvent>;
+     }
+
      /**
       * Configuration model for a tracked image marker.
       * Defines which image to track, its physical size, and which 3D content to display when detected.
@@ -23154,8 +24337,39 @@ export declare class OrbitControls extends Component implements ICameraControlle
          get widthInMeters(): number;
          /** The ImageBitmap used for tracking */
          get bitmap(): ImageBitmap;
-         /** The {@link WebXRImageTrackingModel} configuration for this tracked image */
+         /**
+          * The {@link WebXRImageTrackingModel} configuration for this tracked image.
+          * Use this to access the assigned 3D object, marker settings, and other image tracking configuration.
+          * Available on each {@link WebXRTrackedImage} received from the `image-tracking` {@link CustomEvent} (`event.detail`).
+          * @example
+          * ```ts
+          * tracker.addEventListener("image-tracking", event => {
+          *   for (const img of event.detail.trackedImages) {
+          *     const model = img.model;
+          *     // Access the assigned 3D object
+          *     const obj = model.object;
+          *     // Access other settings
+          *     console.log(model.widthInMeters, model.hideWhenTrackingIsLost);
+          *   }
+          * });
+          * ```
+          */
          get model(): WebXRImageTrackingModel;
+         /**
+          * The 3D object or prefab assigned to this tracked image marker in the {@link WebXRImageTrackingModel}.
+          * Use this to access the object associated with an AR image tracking marker from the `image-tracking` {@link CustomEvent}.
+          * Shorthand for `this.model.object`.
+          * @example
+          * ```ts
+          * tracker.addEventListener("image-tracking", event => {
+          *   for (const img of event.detail.trackedImages) {
+          *     const obj = img.trackedModel;
+          *     // verbose alternative: img.model.object
+          *   }
+          * });
+          * ```
+          */
+         get trackedModel(): AssetReference | undefined;
          /**
           * The measured size of the detected image in the real world.
           * May differ from `widthInMeters` if the physical marker doesn't match the configured size.
@@ -23519,35 +24733,6 @@ export declare class OrbitControls extends Component implements ICameraControlle
      export { }
 
 
-declare module 'three' {
-    interface SkinnedMesh {
-        staticGenerator?: StaticGeometryGenerator;
-        staticGeometry?: BufferGeometry;
-        staticGeometryLastUpdate?: number;
-    }
-    interface Mesh {
-        acceleratedRaycast?: any;
-    }
-    interface SkinnedMesh {
-        /** @deprecated use autoUpdateMeshBvhInterval */
-        autoUpdateMeshBVH?: boolean;
-        /**
-         * Interval in milliseconds to automatically update the mesh BVH. When set to >= 0 the BVH will be updated every x milliseconds.
-         * @default undefined (disabled)
-         */
-        autoUpdateMeshBvhInterval?: number;
-        bvhNeedsUpdate?: boolean;
-    }
-}
-
-
-declare module 'three' {
-    interface Vector3 {
-        slerp(end: Vector3, t: number): Vector3;
-    }
-}
-
-
 declare module 'three' {
     interface Object3D {
         get guid(): string | undefined;
@@ -23686,3 +24871,32 @@ declare module 'three' {
         contains(object: Object3D | null | undefined): boolean;
     }
 }
+
+
+declare module 'three' {
+    interface Vector3 {
+        slerp(end: Vector3, t: number): Vector3;
+    }
+}
+
+
+declare module 'three' {
+    interface SkinnedMesh {
+        staticGenerator?: StaticGeometryGenerator;
+        staticGeometry?: BufferGeometry;
+        staticGeometryLastUpdate?: number;
+    }
+    interface Mesh {
+        acceleratedRaycast?: any;
+    }
+    interface SkinnedMesh {
+        /** @deprecated use autoUpdateMeshBvhInterval */
+        autoUpdateMeshBVH?: boolean;
+        /**
+         * Interval in milliseconds to automatically update the mesh BVH. When set to >= 0 the BVH will be updated every x milliseconds.
+         * @default undefined (disabled)
+         */
+        autoUpdateMeshBvhInterval?: number;
+        bvhNeedsUpdate?: boolean;
+    }
+}