@needle-tools/engine 4.14.0 → 4.15.0-next.f391a30

package/dist/needle-engine.d.ts

@@ -111,7 +111,7 @@ import { XRControllerModelFactory } from 'three/examples/jsm/webxr/XRControllerM
 import { XRHandMeshModel } from 'three/examples/jsm/webxr/XRHandMeshModel.js';
 import { XRHandSpace } from 'three';
 
-declare const $componentName: unique symbol;
+export declare const $componentName: unique symbol;
 
 export declare const $physicsKey: unique symbol;
 
@@ -120,6 +120,81 @@ export declare class __Ignore {
 
 export declare function __internalNotifyObjectDestroyed(obj: Object3D): void;
 
+/** Data describing the accessible semantics for a 3D object or component. */
+declare type AccessibilityData = {
+    /** ARIA role (e.g. `"button"`, `"img"`, `"region"`). */
+    role: string;
+    /** Human-readable label announced by screen readers. */
+    label: string;
+    /** When `true`, the element is hidden from the accessibility tree. */
+    hidden?: boolean;
+    /** When `true`, indicates the element's content is being updated. */
+    busy?: boolean;
+};
+
+/**
+ * Manages an accessible, screen-reader-friendly overlay for a Needle Engine {@link Context}.
+ *
+ * The manager maintains a visually-hidden DOM tree that mirrors relevant 3D scene objects
+ * with appropriate ARIA roles and labels. It also provides a live region so that hover
+ * events in the 3D scene can be announced to assistive technology without stealing focus.
+ *
+ * ## Automatic integration
+ * Several built-in components register accessible elements automatically:
+ * - {@link DragControls} — announces draggable objects and drag state
+ * - {@link Button} — exposes UI buttons to the accessibility tree
+ * - {@link Text} — exposes UI text content to screen readers
+ * - {@link ChangeTransformOnClick} — announces clickable transform actions
+ * - {@link ChangeMaterialOnClick} — announces clickable material changes
+ * - {@link EmphasizeOnClick} — announces clickable emphasis effects
+ * - {@link PlayAudioOnClick} — announces clickable audio playback
+ * - {@link PlayAnimationOnClick} — announces clickable animation triggers
+ *
+ * ## What this unlocks
+ * - Hovering over buttons and interactive objects with the cursor announces them to screen readers via an ARIA live region — no focus steal required
+ * - Screen readers can discover and navigate interactive 3D objects in the scene
+ * - Drag operations update the accessibility state (busy, label changes) in real time
+ * - Custom components can participate by calling {@link updateElement}, {@link focus}, and {@link hover}
+ *
+ * Access the manager via `this.context.accessibility` from any component.
+ */
+declare class AccessibilityManager {
+    private readonly context;
+    private static readonly _managers;
+    /** Returns the {@link AccessibilityManager} associated with the given context or component. */
+    static get(obj: Context | IComponent): AccessibilityManager | undefined;
+    constructor(context: Context);
+    private _enabled;
+    /** Enables or disables the accessibility overlay. When disabled, the overlay DOM is removed. */
+    set enabled(value: boolean);
+    /** Removes all tracked accessibility elements, keeping only the live region. */
+    clear(): void;
+    /** Removes the overlay from the DOM and unregisters this manager from the context. */
+    dispose(): void;
+    private readonly root;
+    private readonly liveRegion;
+    private readonly treeElements;
+    /**
+     * Creates or updates the accessible DOM element for a 3D object or component.
+     * @param obj - The scene object or component to represent.
+     * @param data - Partial accessibility data (role, label, hidden, busy) to apply.
+     */
+    updateElement<T extends Object3D | IComponent>(obj: T, data: Partial<AccessibilityData>): void;
+    /** Moves keyboard focus to the accessible element representing the given object. */
+    focus<T extends Object3D | IComponent>(obj: T): void;
+    /** Removes keyboard focus from the accessible element representing the given object. */
+    unfocus<T extends Object3D | IComponent>(obj: T): void;
+    /**
+     * Announces a hover event to screen readers via the ARIA live region.
+     * @param obj - The hovered object (used to look up its label if `text` is not provided).
+     * @param text - Optional text to announce. Falls back to the element's `aria-label`.
+     */
+    hover<T extends Object3D | IComponent>(obj: T, text?: string): void;
+    /** Removes the accessible DOM element for the given object and stops tracking it. */
+    removeElement(obj: Object3D | IComponent): void;
+    private set liveRegionMode(value);
+}
+
 export declare class ActionBuilder {
     static sequence(...params: IBehaviorElement[]): GroupActionModel;
     static parallel(...params: IBehaviorElement[]): GroupActionModel;
@@ -2267,6 +2342,7 @@ export declare class Button extends Component implements IPointerEventHandler {
     awake(): void;
     start(): void;
     onEnable(): void;
+    onDisable(): void;
     onDestroy(): void;
     private _requestedAnimatorTrigger?;
     private setAnimatorTriggerAtEndOfFrame;
@@ -2843,6 +2919,9 @@ export declare class ChangeMaterialOnClick extends Component implements IPointer
      */
     fadeDuration: number;
     start(): void;
+    onEnable(): void;
+    onDisable(): void;
+    onDestroy(): void;
     onPointerEnter(_args: PointerEventData): void;
     onPointerExit(_: PointerEventData): void;
     onPointerClick(args: PointerEventData): void;
@@ -2887,6 +2966,9 @@ export declare class ChangeTransformOnClick extends Component implements IPointe
     private targetPos;
     private targetRot;
     private targetScale;
+    onEnable(): void;
+    onDisable(): void;
+    onDestroy(): void;
     onPointerEnter(): void;
     onPointerExit(): void;
     onPointerClick(args: PointerEventData): void;
@@ -3421,21 +3503,6 @@ export declare const colorSerializer: ColorSerializer;
  */
 export declare function compareAssociation<T extends Material>(obj1: T, obj2: T): boolean;
 
-declare type ComparisonSceneOptions = {
-    /**
-     * An array of model urls to load
-     */
-    files: string[];
-    /**
-     * Optional dom element to attach the orbit controls to. By default this should be the WebGLRenderer.domElement
-     */
-    domElement?: HTMLElement;
-    /**
-     * Can be a .hdr or .exr file url
-     */
-    environment?: string;
-};
-
 /**
  * Needle Engine component's are the main building blocks of the Needle Engine.
  * Derive from {@link Behaviour} to implement your own using the provided lifecycle methods.
@@ -4292,6 +4359,7 @@ export declare class Context implements IContext {
     readonly lodsManager: LODsManager;
     /** Access the needle menu to add or remove buttons to the menu element */
     readonly menu: NeedleMenu_2;
+    readonly accessibility: AccessibilityManager;
     /**
      * Checks if the context is fully created and ready
      * @returns true if the context is fully created and ready
@@ -5282,6 +5350,7 @@ export declare class DragControls extends Component implements IPointerEventHand
     /* Excluded from this release type: start */
     /* Excluded from this release type: onEnable */
     /* Excluded from this release type: onDisable */
+    onDestroy(): void;
     /**
      * Checks if editing is allowed for the current networking connection.
      * @param _obj Optional object to check edit permissions for
@@ -5673,6 +5742,9 @@ export declare class EmphasizeOnClick extends Component implements UsdzBehaviour
     duration: number;
     /** The type of motion to use for the emphasis effect (e.g. `"bounce"`, `"jiggle"`). */
     motionType: EmphasizeActionMotionType;
+    onEnable(): void;
+    onDisable(): void;
+    onDestroy(): void;
     beforeCreateDocument(): void;
     createBehaviours(ext: any, model: any, _context: any): void;
     afterCreateDocument(_ext: any, _context: any): void;
@@ -7776,6 +7848,7 @@ export declare type ICollisionContext = {
 
 export declare interface IComponent extends IHasGuid {
     get isComponent(): boolean;
+    get [$componentName](): string | undefined;
     /** the object this component is attached to */
     gameObject: IGameObject;
     enabled: boolean;
@@ -10093,13 +10166,22 @@ export declare class MaskableGraphic extends Graphic {
  * This is useful for rendering multiple objects with the same base material but different properties
  * (e.g., different colors, textures, or shader parameters).
  *
+ * ## How Property Blocks Work
+ *
+ * **Important**: Overrides are registered on the **Object3D**, not on the material.
+ * This means:
+ * - If you change the object's material, the overrides will still be applied to the new material
+ * - Multiple objects can share the same material but have different property overrides
+ * - If you don't want overrides applied after changing a material, you must remove them using {@link removeOveride}, {@link clearAllOverrides}, or {@link dispose}
+ *
  * The property block system works by:
  * - Temporarily applying overrides in onBeforeRender
  * - Restoring original values in onAfterRender
  * - Managing shader defines and program cache keys for correct shader compilation
  * - Supporting texture coordinate transforms per object
  *
- * Common use cases:
+ * ## Common Use Cases
+ *
  * - **Lightmaps**: Apply unique lightmap textures to individual objects sharing the same material
  * - **Reflection Probes**: Apply different environment maps per object for localized reflections
  * - **See-through effects**: Temporarily override transparency/transmission properties for X-ray effects
@@ -10137,6 +10219,26 @@ export declare class MaskableGraphic extends Graphic {
  * block.setDefine("USE_CUSTOM_FEATURE", 1);
  * ```
  *
+ * @example Material swapping behavior
+ * ```typescript
+ * const mesh = new Mesh(geometry, materialA);
+ * const block = MaterialPropertyBlock.get(mesh);
+ * block.setOverride("color", new Color(1, 0, 0));
+ *
+ * // The color override is red for materialA
+ *
+ * // Swap the material - overrides persist and apply to the new material!
+ * mesh.material = materialB;
+ * // The color override is now red for materialB too
+ *
+ * // If you don't want overrides on the new material, remove them:
+ * block.clearAllOverrides(); // Remove all overrides
+ * // or
+ * block.removeOveride("color"); // Remove specific override
+ * // or
+ * block.dispose(); // Remove the entire property block
+ * ```
+ *
  * @example Lightmap usage
  * ```typescript
  * const block = MaterialPropertyBlock.get(mesh);
@@ -10244,12 +10346,69 @@ export declare class MaterialPropertyBlock<T extends Material = Material> {
     getOverride<K extends NonFunctionPropertyNames<T>>(name: K): PropertyBlockOverride<T[K] & MaterialPropertyType> | undefined;
     getOverride<V extends MaterialPropertyType = MaterialPropertyType>(name: string): PropertyBlockOverride<V> | undefined;
     /**
-     * Removes a specific property override
-     * @param name The property name to clear
+     * Removes a specific property override.
+     * After removal, the material will use its original property value for this property.
+     *
+     * @param name The property name to remove the override for
+     *
+     * @example
+     * ```typescript
+     * const block = MaterialPropertyBlock.get(mesh);
+     *
+     * // Set some overrides
+     * block.setOverride("color", new Color(1, 0, 0));
+     * block.setOverride("roughness", 0.5);
+     * block.setOverride("lightMap", lightmapTexture);
+     *
+     * // Remove a specific override - the material will now use its original color
+     * block.removeOveride("color");
+     *
+     * // Other overrides (roughness, lightMap) remain active
+     * ```
      */
     removeOveride<K extends NonFunctionPropertyNames<T>>(name: K | ({} & string)): void;
     /**
-     * Removes all property overrides from this block
+     * Removes all property overrides from this block.
+     * After calling this, the material will use its original values for all properties.
+     *
+     * **Note**: This does NOT remove shader defines. Use {@link clearDefine} or {@link dispose} for that.
+     *
+     * @example Remove all overrides but keep the property block
+     * ```typescript
+     * const block = MaterialPropertyBlock.get(mesh);
+     *
+     * // Set multiple overrides
+     * block.setOverride("color", new Color(1, 0, 0));
+     * block.setOverride("roughness", 0.5);
+     * block.setOverride("lightMap", lightmapTexture);
+     *
+     * // Later, remove all overrides at once
+     * block.clearAllOverrides();
+     *
+     * // The material now uses its original values
+     * // The property block still exists and can be reused with new overrides
+     * ```
+     *
+     * @example Temporarily disable all overrides
+     * ```typescript
+     * const block = MaterialPropertyBlock.get(mesh);
+     *
+     * // Save current overrides if you want to restore them later
+     * const savedOverrides = [...block.overrides];
+     *
+     * // Clear all overrides temporarily
+     * block.clearAllOverrides();
+     *
+     * // Do some rendering without overrides...
+     *
+     * // Restore overrides
+     * savedOverrides.forEach(override => {
+     *   block.setOverride(override.name, override.value, override.textureTransform);
+     * });
+     * ```
+     *
+     * @see {@link removeOveride} - To remove a single override
+     * @see {@link dispose} - To completely remove the property block and clean up resources
      */
     clearAllOverrides(): void;
     /**
@@ -10650,32 +10809,58 @@ export declare namespace NEEDLE_ENGINE_MODULES {
 export { NEEDLE_progressive }
 
 /**
- * A <needle-button> can be used to simply add VR, AR or Quicklook buttons to your website without having to write any code.
- * @example
+ * [&lt;needle-button&gt;](https://engine.needle.tools/docs/api/NeedleButtonElement) is a web component for easily adding AR, VR, Quicklook, or QR code buttons to your website without writing JavaScript code.
+ *
+ * The button automatically handles session management and displays appropriate UI based on device capabilities.
+ * It comes with default styling (glassmorphism design) but can be fully customized with CSS.
+ *
+ * **Supported button types:**
+ * - `ar` - WebXR AR session button
+ * - `vr` - WebXR VR session button
+ * - `quicklook` - Apple AR Quick Look button (iOS only)
+ * - `qrcode` - QR code sharing button
+ *
+ * @example Basic AR/VR buttons
  * ```html
+ * <needle-engine src="scene.glb"></needle-engine>
  * <needle-button ar></needle-button>
  * <needle-button vr></needle-button>
  * <needle-button quicklook></needle-button>
  * ```
  *
- * @example custom label
+ * @example Custom button labels
  * ```html
- * <needle-button ar>Start AR</needle-button>
- * <needle-button vr>Start VR</needle-button>
+ * <needle-button ar>Start AR Experience</needle-button>
+ * <needle-button vr>Enter VR Mode</needle-button>
  * <needle-button quicklook>View in AR</needle-button>
  * ```
  *
- * @example custom styling
+ * @example Custom styling
  * ```html
- * <!-- You can either style the element directly or use a CSS stylesheet -->
  * <style>
- * needle-button {
- *    background-color: red;
- *   color: white;
- * }
+ *   needle-button {
+ *     background-color: #ff6b6b;
+ *     color: white;
+ *     border-radius: 8px;
+ *     padding: 1rem 2rem;
+ *   }
+ *   needle-button:hover {
+ *     background-color: #ff5252;
+ *   }
  * </style>
  * <needle-button ar>Start AR</needle-button>
  * ```
+ *
+ * @example Unstyled button (for complete custom styling)
+ * ```html
+ * <needle-button ar unstyled>
+ *   <span class="my-icon">🥽</span>
+ *   Launch AR
+ * </needle-button>
+ * ```
+ *
+ * @see {@link NeedleEngineWebComponent} for the main &lt;needle-engine&gt; element
+ * @see {@link NeedleMenu} for the built-in menu component that can display similar buttons
  */
 export declare class NeedleButtonElement extends HTMLElement {
     #private;
@@ -10752,10 +10937,18 @@ export declare namespace NeedleEngineModelLoader {
  * The context is accessible from the `<needle-engine>` element: `document.querySelector("needle-engine").context`.
  * See {@link https://engine.needle.tools/docs/reference/needle-engine-attributes}
  *
- * @example
+ * @example Basic usage
+ * ```html
  * <needle-engine src="https://example.com/scene.glb"></needle-engine>
- * @example
+ * ```
+ *
+ * @example With camera controls disabled
+ * ```html
  * <needle-engine src="https://example.com/scene.glb" camera-controls="false"></needle-engine>
+ * ```
+ *
+ * @see {@link NeedleButtonElement} for adding AR/VR/Quicklook buttons via &lt;needle-button&gt;
+ * @see {@link NeedleMenu} for the built-in menu configuration component
  */
 export declare class NeedleEngineWebComponent extends HTMLElement implements INeedleEngineComponent {
     static get observedAttributes(): string[];
@@ -10794,7 +10987,10 @@ export declare class NeedleEngineWebComponent extends HTMLElement implements INe
     private _previousSrc;
     /** @private set to true after <needle-engine> did load completely at least once. Set to false when < to false when <needle-engine> is removed from the document removed from the document */
     private _didFullyLoad;
+    private _didInitialize;
     constructor();
+    private ensureInitialized;
+    private initializeDom;
     /* Excluded from this release type: connectedCallback */
     /* Excluded from this release type: disconnectedCallback */
     connectedMoveCallback(): void;
@@ -11082,6 +11278,8 @@ declare class NeedleGamepadButton {
  * @category User Interface
  * @group Components
  * @see {@link Context.menu} for programmatic menu control
+ * @see {@link NeedleButtonElement} for standalone &lt;needle-button&gt; web component
+ * @see {@link NeedleEngineWebComponent} for the main &lt;needle-engine&gt; element
  * @see {@link Voip} adds a microphone button to the menu
  * @see {@link ScreenCapture} adds a screen sharing button
  **/
@@ -12303,10 +12501,34 @@ export declare class NetworkedStreams extends EventDispatcher<any> {
 }
 
 /**
- * Provides configuration to the built-in networking system.
- * This component supplies websocket URLs for establishing connections.
- * It implements the {@link INetworkingWebsocketUrlProvider} interface.
+ * Provides websocket URL configuration for the built-in networking system.
+ * Add this component to override the default networking backend URL used by {@link NetworkConnection} (`this.context.connection`).
+ *
+ * The component registers itself as a URL provider on `awake()`. When the networking system connects,
+ * it queries this provider for the websocket URL to use instead of the default Needle networking backend.
+ *
+ * **URL resolution order:**
+ * 1. If `urlParameterName` is set and the corresponding URL parameter exists in the browser URL, that value is used
+ * 2. If running on a local network and `localhost` is set, the `localhost` URL is used
+ * 3. Otherwise, the `url` field is used
+ *
+ * Without this component, the default backend URL `wss://networking-2.needle.tools/socket` is used.
  *
+ * **Note:** This component only configures the websocket URL. To actually join a networked room,
+ * use a `SyncedRoom` component or call `this.context.connection.joinRoom("room-name")` directly.
+ *
+ * @example Overriding the URL via browser parameter
+ * ```ts
+ * // With urlParameterName="server", visiting:
+ * // https://myapp.com/?server=wss://my-server.com/socket
+ * // will connect to that server instead
+ * ```
+ *
+ * @see {@link NetworkConnection} for the main networking API (`this.context.connection`)
+ * @see {@link SyncedRoom} for automatic room joining
+ * @see {@link OwnershipModel} for networked object ownership
+ * @see {@link RoomEvents} for room lifecycle events
+ * @link https://engine.needle.tools/docs/how-to-guides/networking/
  * @summary Networking configuration
  * @category Networking
  * @group Components
@@ -12315,6 +12537,7 @@ export declare class Networking extends Component implements INetworkingWebsocke
     /**
      * The websocket URL to connect to for networking functionality.
      * Can be a complete URL or a relative path that will be resolved against the current origin.
+     * @default null
      */
     url: string | null;
     /**
@@ -12688,7 +12911,40 @@ export declare function onClear(cb: LifecycleMethod, opts?: LifecycleMethodOptio
 export declare function onDestroy(cb: LifecycleMethod, opts?: LifecycleMethodOptions): () => void;
 
 /**
- * OneEuroFilter is a simple low-pass filter for noisy signals. It uses a one-euro filter to smooth the signal.
+ * [OneEuroFilter](https://engine.needle.tools/docs/api/OneEuroFilter) is a low-pass filter designed to reduce jitter in noisy signals while maintaining low latency.
+ * It's particularly useful for smoothing tracking data from XR controllers, hand tracking, or other input devices where the signal contains noise but responsiveness is important.
+ *
+ * The filter automatically adapts its smoothing strength based on the signal's velocity:
+ * - When the signal moves slowly, it applies strong smoothing to reduce jitter
+ * - When the signal moves quickly, it reduces smoothing to maintain responsiveness
+ *
+ * Based on the research paper: [1€ Filter: A Simple Speed-based Low-pass Filter for Noisy Input](http://cristal.univ-lille.fr/~casiez/1euro/)
+ *
+ * @example Basic usage with timestamp
+ * ```ts
+ * const filter = new OneEuroFilter(120, 1.0, 0.0);
+ *
+ * // In your update loop:
+ * const smoothedValue = filter.filter(noisyValue, this.context.time.time);
+ * ```
+ *
+ * @example Without timestamps (using frequency estimate)
+ * ```ts
+ * // Assuming 60 FPS update rate
+ * const filter = new OneEuroFilter(60, 1.0, 0.5);
+ *
+ * // Call without timestamp - uses the frequency estimate
+ * const smoothedValue = filter.filter(noisyValue);
+ * ```
+ *
+ * @example Smoothing 3D positions
+ * ```ts
+ * const posFilter = new OneEuroFilterXYZ(90, 0.5, 0.0);
+ *
+ * posFilter.filter(trackedPosition, smoothedPosition, this.context.time.time);
+ * ```
+ *
+ * @see {@link OneEuroFilterXYZ} for filtering 3D vectors
  */
 export declare class OneEuroFilter {
     /**
@@ -14199,6 +14455,9 @@ export declare class OrbitControls extends Component implements ICameraControlle
          trigger: "tap" | "start";
          animation?: Animation_2;
          private get target();
+         onEnable(): void;
+         onDisable(): void;
+         onDestroy(): void;
          onPointerEnter(): void;
          onPointerExit(): void;
          onPointerClick(args: PointerEventData): void;
@@ -14245,6 +14504,9 @@ export declare class OrbitControls extends Component implements ICameraControlle
          toggleOnClick: boolean;
          trigger: "tap" | "start";
          ensureAudioSource(): void;
+         onEnable(): void;
+         onDisable(): void;
+         onDestroy(): void;
          onPointerEnter(): void;
          onPointerExit(): void;
          onPointerClick(args: PointerEventData): void;
@@ -15356,11 +15618,19 @@ export declare class OrbitControls extends Component implements ICameraControlle
       */
      export declare class ReflectionProbe extends Component {
          private static _probes;
+         /**
+          * Checks if the given material is currently using a reflection probe. This is determined by checking for an override on the material's "envMap" property, which is set by the Renderer component when applying a reflection probe.
+          */
          static isUsingReflectionProbe(material: Material): boolean;
          /**
           * Event invoked when a reflection probe is enabled. Used internally by Renderer components to update probes when they become active. Not recommended to call this directly in most cases.
+          * @see {@link onDisabled} for the corresponding disable event.
           */
          static readonly onEnabled: EventList<ReflectionProbe>;
+         /**
+          * Event invoked when a reflection probe is disabled. Used internally by Renderer components to update probes when they become inactive. Not recommended to call this directly in most cases.
+          * @see {@link onEnabled} for the corresponding enable event.
+          */
          static readonly onDisabled: EventList<ReflectionProbe>;
          /**
           * Gets the active reflection probe for the given object and context. If `isAnchor` is true, it will only return a probe if the object is the anchor of that probe. Otherwise, it checks if the object is within the probe's influence area.
@@ -15375,8 +15645,12 @@ export declare class OrbitControls extends Component implements ICameraControlle
           */
          static get(object: Object3D | null | undefined, context: Context, isAnchor: boolean, anchor?: Object3D): ReflectionProbe | null;
          private _texture;
-         set texture(tex: Texture);
-         get texture(): Texture;
+         private _textureUrlInFlight?;
+         /**
+          * The cubemap or HDR texture used for reflections. Can be assigned directly or via a URL string. When assigning via URL, the texture will be loaded asynchronously and applied once ready.
+          */
+         set texture(tex: Texture | null);
+         get texture(): Texture | null;
          intensity: number;
          /**
           * Defines the center and size of the reflection probe's influence area.
@@ -15393,12 +15667,18 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private _boxHelper?;
          private isInBox;
          constructor();
-         awake(): void;
-         onEnable(): void;
-         onDisable(): void;
-         start(): void;
-         onDestroy(): void;
+         /* Excluded from this release type: awake */
+         /* Excluded from this release type: onEnable */
+         /* Excluded from this release type: onDisable */
+         /* Excluded from this release type: start */
+         /* Excluded from this release type: onDestroy */
+         /**
+          * Applies this reflection probe to the given object by setting material property overrides for "envMap", "envMapRotation", and "envMapIntensity". This is typically called by the Renderer component when determining which reflection probe to use for a given object.
+          */
          apply(object: Object3D): void;
+         /**
+          * Removes the reflection probe overrides from the given object. This is typically called by the Renderer component when an object is no longer influenced by this probe or when the probe is disabled.
+          */
          unapply(obj: Object3D): void;
      }
 
@@ -19406,30 +19686,6 @@ export declare class OrbitControls extends Component implements ICameraControlle
 
      /* Excluded from this release type: TestRunner */
 
-     /**
-      * A collection of utility methods for quickly spinning up test environments
-      */
-     export declare class TestSceneUtils {
-         /**
-          * Use this method to quickly setup a scene to compare multiple models.
-          * @example
-          * ```ts
-          * const files = [
-          *    "https://threejs.org/examples/models/gltf/RobotExpressive/RobotExpressive.glb",
-          *   "https://threejs.org/examples/models/gltf/Lantern/glTF-Binary/Lantern.glb",
-          * ];
-          * const { scene, camera } = await TestUtils.createComparisonScene({ files });
-          * // this could now be assigned to the Needle Engine Context
-          * context.scene = scene;
-          * context.mainCamera = camera;
-          * ```
-          */
-         static createComparisonScene(opts: ComparisonSceneOptions): Promise<{
-             scene: Scene;
-             camera: PerspectiveCamera;
-         }>;
-     }
-
      /* Excluded from this release type: TestSimulateUserData */
 
      /**
@@ -19488,6 +19744,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private getTextOpts;
          onEnable(): void;
          onDisable(): void;
+         onDestroy(): void;
          private getAlignment;
          private feedText;
          private _didHandleTextRenderOnTop;
@@ -22679,12 +22936,6 @@ export declare namespace MaterialX {
     }): Promise<import("three").Material | null>;
 }
 
-declare global {
-    interface HTMLElementTagNameMap {
-        "needle-button": NeedleButtonElement;
-    }
-}
-
 /**
  * @internal
  */
@@ -22734,20 +22985,10 @@ export declare namespace InternalAttributeUtils {
     }): false | string | null;
 }
 
-
-/**
- * @category Splines
- * @see {@link SplineContainer} for the main spline component that defines the path and knots
- */
-export declare namespace SplineUtils {
-    /**
-     * Creates a SplineContainer from an array of points.
-     * @param positions The positions of the knots.
-     * @param closed Whether the spline is closed (the last knot connects to the first).
-     * @param tension The tension of the spline. 0 is no tension, 1 is high tension (straight lines between knots). Default is 0.75.
-     * @return The created SplineContainer component - add it to an Object3D to use it.
-     */
-    function createFromPoints(positions: Vector3[], closed?: boolean, tension?: number): SplineContainer;
+declare global {
+    interface HTMLElementTagNameMap {
+        "needle-button": NeedleButtonElement;
+    }
 }
 
 
@@ -22890,6 +23131,22 @@ declare module 'three' {
     }
 }
 
+
+/**
+ * @category Splines
+ * @see {@link SplineContainer} for the main spline component that defines the path and knots
+ */
+export declare namespace SplineUtils {
+    /**
+     * Creates a SplineContainer from an array of points.
+     * @param positions The positions of the knots.
+     * @param closed Whether the spline is closed (the last knot connects to the first).
+     * @param tension The tension of the spline. 0 is no tension, 1 is high tension (straight lines between knots). Default is 0.75.
+     * @return The created SplineContainer component - add it to an Object3D to use it.
+     */
+    function createFromPoints(positions: Vector3[], closed?: boolean, tension?: number): SplineContainer;
+}
+
 declare global {
     interface HTMLElementTagNameMap {
         "needle-logo-element": NeedleLogoElement;