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

package/dist/needle-engine.d.ts

@@ -46,6 +46,7 @@ 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';
@@ -269,8 +270,15 @@ export declare type ActivationClipOptions = {
     easeOut?: number;
 };
 
-export declare class ActivationTrackHandler extends TrackHandler {
-    evaluate(time: number): void;
+/**
+ * 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";
@@ -506,6 +514,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.
@@ -624,6 +688,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.
@@ -644,43 +721,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 {
@@ -1197,11 +1270,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 })
@@ -1212,36 +1289,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.
@@ -1250,26 +1361,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 = {
@@ -1907,46 +2044,14 @@ export declare class AudioSource extends Component {
 }
 
 /**
- * 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
+ * Builder for audio tracks. Provides `.clip()` for adding audio clips by URL.
+ * @category Animation and Sequencing
  */
-export declare class AudioTrackHandler extends TrackHandler {
-    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;
+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 */
@@ -3717,6 +3822,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
  */
@@ -4385,6 +4493,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
@@ -4638,19 +4747,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.
@@ -4909,6 +5030,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
@@ -4984,12 +5117,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 */
@@ -5177,7 +5313,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
@@ -6189,6 +6324,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).
@@ -8859,14 +9033,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).
@@ -8882,8 +9075,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
@@ -9491,6 +9684,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
@@ -9518,6 +9716,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
@@ -10151,6 +10354,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;
 };
@@ -10819,13 +11031,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 {
@@ -14262,8 +14476,6 @@ export declare class OrbitControls extends Component implements ICameraControlle
        * @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;
      }
 
@@ -14464,6 +14676,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.
@@ -15181,15 +15398,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
           */
@@ -15197,15 +15414,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.ActivationTrackHandler[];
+         get activationTracks(): Tracks.TimelineActivationTrack[];
          /**
           * @returns all tracks of the timeline
           */
-         get tracks(): ReadonlyArray<Tracks.TrackHandler>;
+         get tracks(): ReadonlyArray<Tracks.TimelineTrackHandler>;
          /**
           * Iterates over all markers of the timeline, optionally filtering by type
           *
@@ -16226,6 +16443,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)
       */
@@ -16351,6 +16571,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;
@@ -16368,6 +16593,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;
@@ -19075,7 +19305,20 @@ 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>;
@@ -20333,8 +20576,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) */
@@ -21156,6 +21406,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.
@@ -21165,6 +21466,49 @@ 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.
       *
@@ -21186,6 +21530,19 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * 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")
@@ -21214,51 +21571,69 @@ export declare class OrbitControls extends Component implements ICameraControlle
           * @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;
+         static create(name?: string, seed?: number): TimelineBuilderBase;
          /**
-          * Adds an animation track. Subsequent `.clip()` calls add animation clips to this track.
+          * 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): this;
+         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): this;
+         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): this;
+         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): this;
+         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): this;
+         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): this;
+         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` and optional {@link AnimationClipOptions}
+          * - 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;
@@ -21293,6 +21668,24 @@ export declare class OrbitControls extends Component implements ICameraControlle
           * 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.
@@ -21323,6 +21716,73 @@ export declare class OrbitControls extends Component implements ICameraControlle
           */
          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";
@@ -21353,27 +21813,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
@@ -21399,15 +21852,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,
-             ActivationTrackHandler,
-             ControlTrackHandler
+             TimelineActivationTrack,
+             TimelineControlTrack
          }
      }
 
@@ -21613,10 +22077,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) */
@@ -21686,6 +22148,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;
@@ -22209,6 +22683,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;
@@ -24173,28 +24650,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 Object3D {
         get guid(): string | undefined;
@@ -24340,3 +24795,25 @@ 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;
+    }
+}