@needle-tools/engine 4.14.0-beta → 4.14.0-next.52fdb13

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,62 @@ 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.
+ */
+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 +2323,7 @@ export declare class Button extends Component implements IPointerEventHandler {
     awake(): void;
     start(): void;
     onEnable(): void;
+    onDisable(): void;
     onDestroy(): void;
     private _requestedAnimatorTrigger?;
     private setAnimatorTriggerAtEndOfFrame;
@@ -2815,7 +2872,15 @@ export declare class CapsuleCollider extends Collider {
 }
 
 /**
- * Change the material of objects when clicked.
+ * Switches the material of objects in the scene when clicked.
+ * Works in the browser and in USDZ/QuickLook (Everywhere Actions).
+ *
+ * Finds all objects in the scene that use `materialToSwitch` and replaces it with `variantMaterial`.
+ * Multiple `ChangeMaterialOnClick` components using the same `materialToSwitch` can be combined to create a material selection UI.
+ *
+ * @see {@link SetActiveOnClick} to toggle visibility of objects when clicked
+ * @see {@link PlayAnimationOnClick} to play animations when clicked
+ * @see [Everywhere Actions](https://engine.needle.tools/docs/everywhere-actions)
  * @summary Changes the material of objects when clicked
  * @category Everywhere Actions
  * @group Components
@@ -2835,6 +2900,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;
@@ -2856,21 +2924,32 @@ export declare class ChangeMaterialOnClick extends Component implements IPointer
 }
 
 /**
- * Make the object move to the target object's transform when clicked.
+ * Moves an object to the target object's transform when clicked.
+ * Works in the browser and in USDZ/QuickLook (Everywhere Actions).
+ *
+ * @see {@link SetActiveOnClick}to toggle visibility of objects when clicked
+ * @see {@link PlayAnimationOnClick} to play animations when clicked
+ * @see [Everywhere Actions](https://engine.needle.tools/docs/everywhere-actions)
  * @summary Moves an object to a target transform upon click
  * @category Everywhere Actions
  * @group Components
  */
 export declare class ChangeTransformOnClick extends Component implements IPointerClickHandler, UsdzBehaviour {
+    /** The object to move. */
     object?: Object3D;
+    /** The target object whose transform to move to. */
     target?: Object3D;
+    /** The duration of the movement animation in seconds. */
     duration: number;
+    /** If true, the motion is relative to the object's current transform instead of moving to the target's absolute position. */
     relativeMotion: boolean;
     private coroutine;
     private targetPos;
     private targetRot;
     private targetScale;
-    start(): void;
+    onEnable(): void;
+    onDisable(): void;
+    onDestroy(): void;
     onPointerEnter(): void;
     onPointerExit(): void;
     onPointerClick(args: PointerEventData): void;
@@ -4276,6 +4355,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
@@ -5266,6 +5346,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
@@ -5638,15 +5719,28 @@ export declare class EmissionModule {
 /* Excluded from this release type: EmphasizeActionMotionType */
 
 /**
- * Emphasize the target object when clicked.
+ * Applies an emphasis animation to a target object when this object is clicked.
+ * Works in USDZ/QuickLook (Everywhere Actions).
+ *
+ * The emphasis effect can be a bounce, jiggle, or other motion type defined by `motionType`.
+ *
+ * @see {@link PlayAnimationOnClick} to play animations when clicked
+ * @see {@link SetActiveOnClick} to toggle visibility when clicked
+ * @see [Everywhere Actions](https://engine.needle.tools/docs/everywhere-actions)
  * @summary Emphasizes the target object when clicked
  * @category Everywhere Actions
  * @group Components
  */
 export declare class EmphasizeOnClick extends Component implements UsdzBehaviour {
+    /** The target object to emphasize. */
     target?: Object3D;
+    /** The duration of the emphasis animation in seconds. */
     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;
@@ -7398,7 +7492,13 @@ export declare enum HideFlags {
 }
 
 /**
- * Hides the object on scene start.
+ * Hides the object when the scene starts.
+ * Works in the browser and in USDZ/QuickLook (Everywhere Actions).
+ *
+ * Useful for setting up objects that should initially be hidden and shown later via a {@link SetActiveOnClick} component.
+ *
+ * @see {@link SetActiveOnClick} to show or hide objects on click
+ * @see [Everywhere Actions](https://engine.needle.tools/docs/everywhere-actions)
  * @summary Hides the object on scene start
  * @category Everywhere Actions
  * @group Components
@@ -7744,6 +7844,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;
@@ -10061,13 +10162,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
@@ -10105,6 +10215,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);
@@ -10212,12 +10342,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;
     /**
@@ -10618,32 +10805,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;
@@ -10720,10 +10933,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[];
@@ -11050,6 +11271,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
  **/
@@ -12271,10 +12494,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
@@ -12283,6 +12530,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;
     /**
@@ -12656,7 +12904,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 {
     /**
@@ -14142,18 +14423,34 @@ export declare class OrbitControls extends Component implements ICameraControlle
      /* Excluded from this release type: PlayAction */
 
      /**
-      * Plays an animation when clicked.
+      * Plays an animation state when this object is clicked.
+      * Works in the browser and in USDZ/QuickLook (Everywhere Actions).
+      *
+      * Assign an {@link Animator} and a `stateName` to play a specific animation state,
+      * or assign an {@link Animation} component to play a legacy animation clip.
+      *
+      * For USDZ export, the component follows animator state transitions automatically, including looping states.
+      *
+      * @see {@link Animator}for playing animator state machine animations
+      * @see {@link Animation} for playing legacy animation clips
+      * @see {@link PlayAudioOnClick} to play audio when clicked
+      * @see {@link SetActiveOnClick} to toggle visibility when clicked
+      * @see [Everywhere Actions](https://engine.needle.tools/docs/everywhere-actions)
       * @summary Plays an animation when clicked
       * @category Everywhere Actions
       * @group Components
       */
      export declare class PlayAnimationOnClick extends Component implements IPointerClickHandler, UsdzBehaviour, UsdzAnimation {
+         /** The {@link Animator} component whose state to play when clicked. */
          animator?: Animator;
+         /** The name of the animation state to play. Required when using an {@link Animator}. */
          stateName?: string;
          trigger: "tap" | "start";
          animation?: Animation_2;
          private get target();
-         start(): void;
+         onEnable(): void;
+         onDisable(): void;
+         onDestroy(): void;
          onPointerEnter(): void;
          onPointerExit(): void;
          onPointerClick(args: PointerEventData): void;
@@ -14177,18 +14474,32 @@ export declare class OrbitControls extends Component implements ICameraControlle
      }
 
      /**
-      * Plays an audio clip when clicked.
+      * Plays an audio clip when this object is clicked.
+      * Works in the browser and in USDZ/QuickLook (Everywhere Actions).
+      *
+      * Assign a `target` {@link AudioSource} to use its spatial audio settings, or assign a `clip` URL directly.
+      * If no `target` is assigned, an {@link AudioSource} will be created automatically on this object.
+      *
+      * @see {@link AudioSource}for spatial audio settings
+      * @see {@link PlayAnimationOnClick} to play animations when clicked
+      * @see {@link SetActiveOnClick} to toggle visibility when clicked
+      * @see [Everywhere Actions](https://engine.needle.tools/docs/everywhere-actions)
       * @summary Plays an audio clip when clicked
       * @category Everywhere Actions
       * @group Components
       */
      export declare class PlayAudioOnClick extends Component implements IPointerClickHandler, UsdzBehaviour {
+         /** The {@link AudioSource} to use for playback. If not set, one will be created automatically on this object. */
          target?: AudioSource;
+         /** URL of the audio clip to play. If not set, the clip assigned to `target` is used. */
          clip: string;
+         /** If true, clicking again while the audio is playing will stop it. */
          toggleOnClick: boolean;
          trigger: "tap" | "start";
-         start(): void;
          ensureAudioSource(): void;
+         onEnable(): void;
+         onDisable(): void;
+         onDestroy(): void;
          onPointerEnter(): void;
          onPointerExit(): void;
          onPointerClick(args: PointerEventData): void;
@@ -15319,6 +15630,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
           */
          static get(object: Object3D | null | undefined, context: Context, isAnchor: boolean, anchor?: Object3D): ReflectionProbe | null;
          private _texture;
+         private _textureUrlInFlight?;
          set texture(tex: Texture);
          get texture(): Texture;
          intensity: number;
@@ -17303,17 +17615,28 @@ export declare class OrbitControls extends Component implements ICameraControlle
      export declare function setActive(go: Object3D, active: boolean | number): boolean;
 
      /**
-      * Set the active state of an object when clicked.
+      * Shows or hides a target object when this object is clicked.
+      * Works in the browser and in USDZ/QuickLook (Everywhere Actions).
+      *
+      * Optionally hides itself after being clicked (`hideSelf`), or toggles the target's visibility on each click (`toggleOnClick`).
+      *
+      * @see {@link HideOnStart}to hide an object when the scene starts
+      * @see {@link PlayAnimationOnClick} to play animations when clicked
+      * @see {@link ChangeMaterialOnClick} to change material when clicked
+      * @see [Everywhere Actions](https://engine.needle.tools/docs/everywhere-actions)
       * @summary Sets the active state of an object when clicked
       * @category Everywhere Actions
       * @group Components
       */
      export declare class SetActiveOnClick extends Component implements IPointerClickHandler, UsdzBehaviour {
+         /** The target object to show or hide. */
          target?: Object3D;
+         /** If true, the target's visibility will be toggled on each click. When enabled, `hideSelf` and `targetState` are ignored. */
          toggleOnClick: boolean;
+         /** The visibility state to apply to the target when clicked. Only used when `toggleOnClick` is false. */
          targetState: boolean;
+         /** If true, this object will hide itself after being clicked. Only used when `toggleOnClick` is false. */
          hideSelf: boolean;
-         start(): void;
          onPointerEnter(): void;
          onPointerExit(): void;
          onPointerClick(args: PointerEventData): void;
@@ -19293,7 +19616,12 @@ export declare class OrbitControls extends Component implements ICameraControlle
      export declare type SyncInstantiateOptions = IInstantiateOptions & Pick<IModel, "deleteOnDisconnect">;
 
      /**
-      * Triggers an action when the object is tapped/clicked.
+      * Triggers a {@link PreliminaryAction} (such as {@link VisibilityAction}) when the object is tapped or clicked.
+      * Works in the browser and in USDZ/QuickLook (Everywhere Actions).
+      *
+      * @see {@link VisibilityAction} for controlling object visibility on tap
+      * @see {@link SetActiveOnClick} for a combined trigger and action component
+      * @see [Everywhere Actions](https://engine.needle.tools/docs/everywhere-actions)
       * @summary Triggers an action when the object is tapped/clicked
       * @category Everywhere Actions
       * @group Components
@@ -19416,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;
@@ -20932,13 +21261,20 @@ export declare class OrbitControls extends Component implements ICameraControlle
      }
 
      /**
-      * Hides or shows the object when clicked.
+      * Action to show or hide an object.
+      * Use together with a {@link TapGestureTrigger} to show or hide objects when tapped or clicked.
+      *
+      * @see {@link TapGestureTrigger} to trigger actions on tap/click
+      * @see {@link SetActiveOnClick} for a combined trigger and action component
+      * @see [Everywhere Actions](https://engine.needle.tools/docs/everywhere-actions)
       * @summary Hides or shows the object when clicked
       * @category Everywhere Actions
       * @group Components
       */
      export declare class VisibilityAction extends PreliminaryAction {
+         /** The type of visibility action to apply. */
          type: VisibilityActionType;
+         /** The duration of the fade animation in seconds. */
          duration: number;
          getType(): "show" | "hide";
          getDuration(): number;
@@ -22389,45 +22725,6 @@ declare global {
     }
 }
 
-
-declare module 'three/examples/jsm/controls/OrbitControls.js' {
-    interface OrbitControls {
-        _sphericalDelta: import("three").Spherical;
-        _rotateLeft: (angleInRadians: number) => void;
-        _rotateUp: (angleInRadians: number) => void;
-        _pan: (dx: number, dy: number) => void;
-        _dollyIn: (dollyScale: number) => void;
-        _dollyOut: (dollyScale: number) => void;
-    }
-    interface OrbitControlsEventMap {
-        endMovement: Event;
-    }
-}
-
-
-declare global {
-    interface ViewTimeline {
-        axis: 'block' | 'inline';
-        currentTime: {
-            unit: 'seconds' | 'percent';
-            value: number;
-        };
-        duration: {
-            unit: 'seconds' | 'percent';
-            value: number;
-        };
-        source: Element | null;
-        startOffset: {
-            unit: 'px';
-            value: number;
-        };
-        endOffset: {
-            unit: 'px';
-            value: number;
-        };
-    }
-}
-
 export declare namespace NEEDLE_ENGINE_FEATURE_FLAGS {
     let experimentalSmartHierarchyUpdate: boolean;
 }
@@ -22566,6 +22863,45 @@ export declare namespace DeviceUtilities {
 }
 
 
+declare module 'three/examples/jsm/controls/OrbitControls.js' {
+    interface OrbitControls {
+        _sphericalDelta: import("three").Spherical;
+        _rotateLeft: (angleInRadians: number) => void;
+        _rotateUp: (angleInRadians: number) => void;
+        _pan: (dx: number, dy: number) => void;
+        _dollyIn: (dollyScale: number) => void;
+        _dollyOut: (dollyScale: number) => void;
+    }
+    interface OrbitControlsEventMap {
+        endMovement: Event;
+    }
+}
+
+
+declare global {
+    interface ViewTimeline {
+        axis: 'block' | 'inline';
+        currentTime: {
+            unit: 'seconds' | 'percent';
+            value: number;
+        };
+        duration: {
+            unit: 'seconds' | 'percent';
+            value: number;
+        };
+        source: Element | null;
+        startOffset: {
+            unit: 'px';
+            value: number;
+        };
+        endOffset: {
+            unit: 'px';
+            value: number;
+        };
+    }
+}
+
+
 declare global {
     interface Window {
         SPECTOR?: {
@@ -22600,12 +22936,6 @@ export declare namespace MaterialX {
     }): Promise<import("three").Material | null>;
 }
 
-declare global {
-    interface HTMLElementTagNameMap {
-        "needle-button": NeedleButtonElement;
-    }
-}
-
 /**
  * @internal
  */
@@ -22655,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;
+    }
 }
 
 
@@ -22811,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;