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

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;
@@ -4292,6 +4374,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 +5365,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 +5757,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 +7863,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 +10181,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 +10234,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 +10361,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 +10824,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 +10952,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[];
@@ -11082,6 +11290,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 +12513,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 +12549,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 +12923,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 +14467,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 +14516,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;
@@ -15375,6 +15649,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;
@@ -19488,6 +19763,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 +22955,6 @@ export declare namespace MaterialX {
     }): Promise<import("three").Material | null>;
 }
 
-declare global {
-    interface HTMLElementTagNameMap {
-        "needle-button": NeedleButtonElement;
-    }
-}
-
 /**
  * @internal
  */
@@ -22734,20 +23004,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 +23150,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;