@needle-tools/engine 5.1.0-alpha.2 → 5.1.0-alpha.4

package/dist/needle-engine.d.ts

@@ -40,6 +40,7 @@ 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';
@@ -254,6 +255,24 @@ 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;
+};
+
+export declare class ActivationTrackHandler extends TrackHandler {
+    evaluate(time: number): void;
+}
+
 export declare const activeInHierarchyFieldName = "needle_isActiveInHierarchy";
 
 /**
@@ -500,6 +519,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.
  *
@@ -726,6 +773,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 +1155,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.
@@ -1472,6 +1518,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 +1601,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;
@@ -1627,9 +1762,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 +1790,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 +1839,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 +1871,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 +1887,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,6 +1906,20 @@ export declare class AudioSource extends Component {
     /* Excluded from this release type: update */
 }
 
+/**
+ * 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 AudioTrackHandler extends TrackHandler {
     models: Array<AudioClipModel_2>;
     listener: AudioListener_3;
@@ -1762,6 +1927,9 @@ export declare class AudioTrackHandler extends TrackHandler {
     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;
@@ -1811,69 +1979,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 +2039,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 +2402,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 +2675,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 +3022,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;
@@ -3522,6 +3598,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 */
@@ -3623,7 +3715,7 @@ declare class ColorSerializer extends TypeSerializer {
     onSerialize(data: any): any | void;
 }
 
-export declare const colorSerializer: ColorSerializer;
+export declare let colorSerializer: ColorSerializer;
 
 /**
  * Utility method to check if two materials were created from the same glTF material
@@ -3644,7 +3736,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 +3749,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 +3818,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 +3880,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 +4092,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 */
@@ -4097,7 +4251,7 @@ declare class ComponentSerializer extends TypeSerializer {
     findObjectForGuid(guid: string, root: Object3D): any;
 }
 
-export declare const componentSerializer: ComponentSerializer;
+export declare let componentSerializer: ComponentSerializer;
 
 declare type ComponentType = "button" | "thumbstick" | "squeeze" | "touchpad";
 
@@ -4806,6 +4960,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
  */
@@ -5136,7 +5304,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 +5532,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 +5541,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 +5743,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,19 +6189,6 @@ export declare class EnvironmentScene extends Scene {
     createAreaLightMaterial(intensity: number): MeshBasicMaterial;
 }
 
-export declare const euler: EulerSerializer;
-
-declare class EulerSerializer extends TypeSerializer {
-    constructor();
-    onDeserialize(data: any, _context: SerializationContext): Euler | undefined;
-    onSerialize(data: any, _context: SerializationContext): {
-        x: any;
-        y: any;
-        z: any;
-        order: any;
-    };
-}
-
 /**
  * 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).
@@ -5979,13 +6235,9 @@ declare class EulerSerializer extends TypeSerializer {
  * @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 */
@@ -6018,13 +6270,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!
      */
@@ -6055,6 +6335,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;
 }
@@ -6065,7 +6346,7 @@ declare class EventListSerializer extends TypeSerializer {
     onDeserialize(data: EventListData, context: SerializationContext): EventList<any> | undefined | null;
 }
 
-export declare const eventListSerializer: EventListSerializer;
+export declare let eventListSerializer: EventListSerializer;
 
 /**
  * [EventSystem](https://engine.needle.tools/docs/api/EventSystem) is responsible for managing and dispatching input events to UI components within the scene.
@@ -6508,7 +6789,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 | {
@@ -7759,7 +8040,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 & {
@@ -7982,7 +8263,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 */
@@ -8056,6 +8337,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 = {
@@ -8082,7 +8369,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;
@@ -8119,6 +8405,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 {
     /**
@@ -8138,7 +8442,6 @@ export declare interface IEffectProvider {
 
 export declare interface IEventList {
     readonly isEventList: true;
-    __internalOnInstantiate(map: InstantiateContext): IEventList;
 }
 
 export declare interface IGameObject extends Object3D {
@@ -8431,13 +8734,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;
@@ -8457,10 +8792,20 @@ export declare class InheritVelocityModule {
     applyCurrent(vel: Vector3 | Vector3_2, t01: number, lerpFactor: number): void;
 }
 
+/* Excluded from this release type: initAddressableSerializers */
+
+/** Register all builtin serializers and prototype patches.
+ * Must be called from {@link initEngine} so the registrations survive tree-shaking
+ * when the package declares `sideEffects: false`.
+ */
+export declare function initBuiltinSerializers(): void;
+
 /** Register the Rapier physics backend. Called from {@link initEngine}
  * to ensure it runs regardless of tree-shaking. */
 export declare function initPhysics(): void;
 
+/* Excluded from this release type: initVolumeParameterSerializer */
+
 /**
  * Handles all input events including mouse, touch, keyboard, and XR controllers.
  * Access via `this.context.input` from any component.
@@ -8984,7 +9329,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>;
 
@@ -9024,7 +9369,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.
@@ -9095,8 +9441,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 */
@@ -9326,8 +9674,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 */
@@ -9548,6 +9897,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 {
@@ -9582,6 +9943,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;
 
@@ -9616,6 +9981,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 {
@@ -9740,7 +10107,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;
 }
@@ -11002,6 +11371,7 @@ export declare type Model = (GLTF | FBX | OBJ | CustomModel);
 
 declare namespace Models {
     export {
+        isTrackModel,
         TimelineAssetModel,
         TrackType,
         ClipExtrapolation,
@@ -11051,6 +11421,8 @@ export declare type MouseButtonName = "left" | "right" | "middle";
  * Safe to import at module level, including in SSR environments.
  * For pages with multiple `<needle-engine>` elements, use `ctx` directly instead.
  *
+ * @experimental This API may change in future releases.
+ *
  * @example
  * import { needle } from "@needle-tools/engine";
  * button.onclick = () => {
@@ -11207,11 +11579,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';
@@ -12165,8 +12543,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;
@@ -12212,6 +12589,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?;
@@ -12599,7 +12978,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.
@@ -12621,61 +13000,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 Manual unsubscribe
+     * ```ts
+     * const unsub = this.context.connection.beginListen("joined-room", () => { });
+     * // Later:
+     * unsub(); // removes the listener
      * ```
      *
-     * @example Listening to room events
+     * @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.
@@ -12684,16 +13071,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;
@@ -12703,6 +13093,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;
@@ -12831,7 +13223,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
  */
@@ -12968,7 +13360,7 @@ export declare type OBJ = {
     scenes: Object3D[];
 };
 
-declare type ObjectCloneReference = {
+export declare type ObjectCloneReference = {
     readonly original: object;
     readonly clone: object;
 };
@@ -13052,7 +13444,7 @@ declare class ObjectSerializer extends TypeSerializer {
     onDeserialize(data: ObjectData | string | null, context: SerializationContext): Object3D<Object3DEventMap> | Component | null | undefined;
 }
 
-export declare const objectSerializer: ObjectSerializer;
+export declare let objectSerializer: ObjectSerializer;
 
 declare type ObjectToNodeMap = {
     [uuid: string]: number;
@@ -13175,6 +13567,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
@@ -14648,13 +15095,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
@@ -14749,6 +15198,14 @@ export declare class OrbitControls extends Component implements ICameraControlle
           * @returns all marker tracks of the timeline
           */
          get markerTracks(): Tracks.MarkerTrackHandler[];
+         /**
+          * @returns all activation tracks of the timeline
+          */
+         get activationTracks(): Tracks.ActivationTrackHandler[];
+         /**
+          * @returns all tracks of the timeline
+          */
+         get tracks(): ReadonlyArray<Tracks.TrackHandler>;
          /**
           * Iterates over all markers of the timeline, optionally filtering by type
           *
@@ -14762,13 +15219,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;
@@ -14777,6 +15234,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();
@@ -15955,6 +16413,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>;
@@ -16001,7 +16463,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;
@@ -16011,8 +16474,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;
      }
 
      /**
@@ -16815,10 +17281,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;
@@ -16901,7 +17374,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
@@ -18121,10 +18595,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
      }
 
@@ -18557,6 +19038,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}
       *
@@ -18564,7 +19055,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[];
@@ -18587,6 +19079,9 @@ export declare class OrbitControls extends Component implements ICameraControlle
          models: Models.SignalMarkerModel[];
          didTrigger: boolean[];
          receivers: Array<SignalReceiver | null>;
+         private _lastTime;
+         onEnable(): void;
+         onMuteChanged(): void;
          evaluate(time: number): void;
      }
 
@@ -19086,10 +19581,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 {
@@ -20409,6 +20900,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
@@ -20673,6 +21165,166 @@ export declare class OrbitControls extends Component implements ICameraControlle
          tracks: TrackModel[];
      };
 
+     /**
+      * 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 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): TimelineBuilder;
+         /**
+          * Adds an animation track. Subsequent `.clip()` calls add animation clips to this track.
+          * @param name - Display name for the track
+          * @param binding - The Animator or Object3D to animate
+          */
+         animationTrack(name: string, binding?: Animator | Object3D | null): this;
+         /**
+          * 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): this;
+         /**
+          * 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): this;
+         /**
+          * Adds a control track. Subsequent `.clip()` calls control nested timelines or objects.
+          * @param name - Display name for the track
+          */
+         controlTrack(name: string): this;
+         /**
+          * 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): this;
+         /**
+          * Adds a marker track. Use `.marker()` to add markers.
+          * @param name - Display name for the track
+          */
+         markerTrack(name: string): this;
+         /**
+          * Adds a clip to the current track. The clip type must match the track type.
+          *
+          * - On an **animation track**: pass an `AnimationClip` 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(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;
+         /**
+          * 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;
+     }
+
      declare type TonemappingAttributeOptions = "none" | "linear" | "neutral" | "agx";
 
      /**
@@ -20754,6 +21406,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
              AudioTrackHandler,
              MarkerTrackHandler,
              SignalTrackHandler,
+             ActivationTrackHandler,
              ControlTrackHandler
          }
      }
@@ -22477,7 +23130,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.
@@ -23520,6 +24173,28 @@ 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 Object3D {
         get guid(): string | undefined;
@@ -23665,25 +24340,3 @@ declare module 'three' {
         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;
-    }
-}