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

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';
 
-export declare const $componentName: unique symbol;
+declare const $componentName: unique symbol;
 
 export declare const $physicsKey: unique symbol;
 
@@ -120,62 +120,6 @@ 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;
@@ -2323,7 +2267,6 @@ export declare class Button extends Component implements IPointerEventHandler {
     awake(): void;
     start(): void;
     onEnable(): void;
-    onDisable(): void;
     onDestroy(): void;
     private _requestedAnimatorTrigger?;
     private setAnimatorTriggerAtEndOfFrame;
@@ -2900,9 +2843,6 @@ 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;
@@ -2947,9 +2887,6 @@ 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;
@@ -4355,7 +4292,6 @@ 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
@@ -5346,7 +5282,6 @@ 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
@@ -5738,9 +5673,6 @@ 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;
@@ -7844,7 +7776,6 @@ 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;
@@ -10162,22 +10093,13 @@ 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
@@ -10215,26 +10137,6 @@ 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);
@@ -10342,69 +10244,12 @@ 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.
-     * 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
-     * ```
+     * Removes a specific property override
+     * @param name The property name to clear
      */
     removeOveride<K extends NonFunctionPropertyNames<T>>(name: K | ({} & string)): void;
     /**
-     * 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
+     * Removes all property overrides from this block
      */
     clearAllOverrides(): void;
     /**
@@ -10805,58 +10650,32 @@ export declare namespace NEEDLE_ENGINE_MODULES {
 export { NEEDLE_progressive }
 
 /**
- * [&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
+ * A <needle-button> can be used to simply add VR, AR or Quicklook buttons to your website without having to write any code.
+ * @example
  * ```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 button labels
+ * @example custom label
  * ```html
- * <needle-button ar>Start AR Experience</needle-button>
- * <needle-button vr>Enter VR Mode</needle-button>
+ * <needle-button ar>Start AR</needle-button>
+ * <needle-button vr>Start VR</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: #ff6b6b;
- *     color: white;
- *     border-radius: 8px;
- *     padding: 1rem 2rem;
- *   }
- *   needle-button:hover {
- *     background-color: #ff5252;
- *   }
+ * needle-button {
+ *    background-color: red;
+ *   color: white;
+ * }
  * </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;
@@ -10933,18 +10752,10 @@ 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 Basic usage
- * ```html
+ * @example
  * <needle-engine src="https://example.com/scene.glb"></needle-engine>
- * ```
- *
- * @example With camera controls disabled
- * ```html
+ * @example
  * <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[];
@@ -11271,8 +11082,6 @@ 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
  **/
@@ -12494,34 +12303,10 @@ export declare class NetworkedStreams extends EventDispatcher<any> {
 }
 
 /**
- * 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
+ * Provides configuration to the built-in networking system.
+ * This component supplies websocket URLs for establishing connections.
+ * It implements the {@link INetworkingWebsocketUrlProvider} interface.
  *
- * 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
@@ -12530,7 +12315,6 @@ 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;
     /**
@@ -12904,40 +12688,7 @@ export declare function onClear(cb: LifecycleMethod, opts?: LifecycleMethodOptio
 export declare function onDestroy(cb: LifecycleMethod, opts?: LifecycleMethodOptions): () => void;
 
 /**
- * [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
+ * OneEuroFilter is a simple low-pass filter for noisy signals. It uses a one-euro filter to smooth the signal.
  */
 export declare class OneEuroFilter {
     /**
@@ -14448,9 +14199,6 @@ 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;
@@ -14497,9 +14245,6 @@ 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;
@@ -15630,7 +15375,6 @@ 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;
@@ -19744,7 +19488,6 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private getTextOpts;
          onEnable(): void;
          onDisable(): void;
-         onDestroy(): void;
          private getAlignment;
          private feedText;
          private _didHandleTextRenderOnTop;
@@ -22936,6 +22679,12 @@ export declare namespace MaterialX {
     }): Promise<import("three").Material | null>;
 }
 
+declare global {
+    interface HTMLElementTagNameMap {
+        "needle-button": NeedleButtonElement;
+    }
+}
+
 /**
  * @internal
  */
@@ -22985,10 +22734,20 @@ export declare namespace InternalAttributeUtils {
     }): false | string | null;
 }
 
-declare global {
-    interface HTMLElementTagNameMap {
-        "needle-button": NeedleButtonElement;
-    }
+
+/**
+ * @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;
 }
 
 
@@ -23131,22 +22890,6 @@ 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;