@needle-tools/engine 4.14.0-next.31f837e → 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;
@@ -2029,7 +2085,7 @@ export declare namespace BlobStorage {
     export function upload(file: File, opts?: UploadOptions): Promise<Upload_Result | null>;
     export function getBlobUrlForKey(key: string): string;
     export function download(url: string, progressCallback?: (prog: ProgressEvent) => void): Promise<Uint8Array | null>;
-    export {};
+        {};
 }
 
 /**
@@ -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;
@@ -8725,7 +8826,7 @@ export declare namespace InternalScreenshotUtils {
             [key: string]: boolean | number;
         };
     }): FullscreenPlane;
-    export {};
+        {};
 }
 
 /* Excluded from this release type: invokeLoadedImportPluginHooks */
@@ -10056,39 +10157,300 @@ export declare class MaskableGraphic extends Graphic {
     protected onAfterCreated(): void;
 }
 
+/**
+ * MaterialPropertyBlock allows per-object material property overrides without creating new material instances.
+ * 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
+ *
+ * - **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
+ *
+ * ## Getting a MaterialPropertyBlock
+ *
+ * **Important**: Do not use the constructor directly. Instead, use the static {@link MaterialPropertyBlock.get} method:
+ *
+ * ```typescript
+ * const block = MaterialPropertyBlock.get(myMesh);
+ * ```
+ *
+ * This method will either return an existing property block or create a new one if it doesn't exist.
+ * It automatically:
+ * - Creates the property block instance
+ * - Registers it in the internal registry
+ * - Attaches the necessary render callbacks to the object
+ * - Handles Groups by applying overrides to all child meshes
+ *
+ * @example Basic usage
+ * ```typescript
+ * // Get or create a property block for an object
+ * const block = MaterialPropertyBlock.get(myMesh);
+ *
+ * // Override the color property
+ * block.setOverride("color", new Color(1, 0, 0));
+ *
+ * // Override a texture with custom UV transform (useful for lightmaps)
+ * block.setOverride("lightMap", myLightmapTexture, {
+ *   offset: new Vector2(0.5, 0.5),
+ *   repeat: new Vector2(2, 2)
+ * });
+ *
+ * // Set a shader define
+ * 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);
+ * block.setOverride("lightMap", lightmapTexture);
+ * block.setOverride("lightMapIntensity", 1.5);
+ * ```
+ *
+ * @example See-through effect
+ * ```typescript
+ * const block = MaterialPropertyBlock.get(mesh);
+ * block.setOverride("transparent", true);
+ * block.setOverride("opacity", 0.3);
+ * ```
+ *
+ * @template T The material type this property block is associated with
+ */
 export declare class MaterialPropertyBlock<T extends Material = Material> {
     private _overrides;
     private _defines;
     private _object;
+    /** The object this property block is attached to */
     get object(): Object3D | null;
-    constructor(object?: Object3D | null);
+    /**
+     * Creates a new MaterialPropertyBlock
+     * @param object The object this property block is for (optional)
+     */
+    protected constructor(object?: Object3D | null);
+    /**
+     * Gets or creates a MaterialPropertyBlock for the given object.
+     * This is the recommended way to obtain a property block instance.
+     *
+     * @template T The material type
+     * @param object The object to get/create a property block for
+     * @returns The MaterialPropertyBlock associated with this object
+     *
+     * @example
+     * ```typescript
+     * const block = MaterialPropertyBlock.get(myMesh);
+     * block.setOverride("roughness", 0.5);
+     * ```
+     */
     static get<T extends Material = Material>(object: Object3D): MaterialPropertyBlock<T>;
+    /**
+     * Checks if an object has any property overrides
+     * @param object The object to check
+     * @returns True if the object has a property block with overrides
+     */
+    static hasOverrides(object: Object3D): boolean;
+    /**
+     * Disposes this property block and cleans up associated resources.
+     * After calling dispose, this property block should not be used.
+     */
     dispose(): void;
+    /**
+     * Sets or updates a material property override.
+     * The override will be applied to the material during rendering.
+     *
+     * @param name The name of the material property to override (e.g., "color", "map", "roughness")
+     * @param value The value to set
+     * @param textureTransform Optional UV transform (only used when value is a Texture)
+     *
+     * @example
+     * ```typescript
+     * // Override a simple property
+     * block.setOverride("roughness", 0.8);
+     *
+     * // Override a color
+     * block.setOverride("color", new Color(0xff0000));
+     *
+     * // Override a texture with UV transform
+     * block.setOverride("map", texture, {
+     *   offset: new Vector2(0, 0),
+     *   repeat: new Vector2(2, 2)
+     * });
+     * ```
+     */
     setOverride<K extends NonFunctionPropertyNames<T>>(name: K, value: T[K], textureTransform?: TextureTransform): void;
     setOverride(name: string, value: MaterialPropertyType, textureTransform?: TextureTransform): void;
-    getOverride(name: string): PropertyBlockOverride | undefined;
-    clearOverride(name: string): void;
+    /**
+     * Gets the override for a specific property with type-safe value inference
+     * @param name The property name to get
+     * @returns The PropertyBlockOverride with correctly typed value if it exists, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * const block = MaterialPropertyBlock.get<MeshStandardMaterial>(mesh);
+     *
+     * // Value is inferred as number | undefined
+     * const roughness = block.getOverride("roughness")?.value;
+     *
+     * // Value is inferred as Color | undefined
+     * const color = block.getOverride("color")?.value;
+     *
+     * // Value is inferred as Texture | null | undefined
+     * const map = block.getOverride("map")?.value;
+     *
+     * // Explicitly specify the type for properties not on the base material type
+     * const transmission = block.getOverride<number>("transmission")?.value;
+     *
+     * // Or use a more specific material type
+     * const physicalBlock = block as MaterialPropertyBlock<MeshPhysicalMaterial>;
+     * const transmissionTyped = physicalBlock.getOverride("transmission")?.value; // number
+     * ```
+     */
+    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
+     * ```
+     */
+    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
+     */
     clearAllOverrides(): void;
-    removeOverride(name: string): void;
-    get overrides(): PropertyBlockOverride[];
+    /**
+     * Gets all property overrides as a readonly array
+     * @returns Array of all property overrides
+     */
+    get overrides(): readonly PropertyBlockOverride[];
+    /**
+     * Checks if this property block has any overrides
+     * @returns True if there are any overrides set
+     */
     hasOverrides(): boolean;
     /**
-     * Set a shader define that will be included in the program cache key
-     * This allows different objects sharing the same material to have different shader programs
+     * Set a shader define that will be included in the program cache key.
+     * This allows different objects sharing the same material to have different shader programs.
+     *
+     * Defines affect shader compilation and are useful for enabling/disabling features per-object.
+     *
+     * @param name The define name (e.g., "USE_LIGHTMAP", "ENABLE_REFLECTIONS")
+     * @param value The define value (typically a boolean, number, or string)
+     *
+     * @example
+     * ```typescript
+     * // Enable a feature for this specific object
+     * block.setDefine("USE_CUSTOM_SHADER", true);
+     * block.setDefine("QUALITY_LEVEL", 2);
+     * ```
      */
     setDefine(name: string, value: string | number | boolean): void;
     /**
      * Remove a shader define
+     * @param name The define name to remove
      */
     clearDefine(name: string): void;
     /**
      * Get all defines set on this property block
+     * @returns A readonly record of all defines
      */
     getDefines(): Readonly<Record<string, string | number | boolean>>;
-    getCacheKey(): string;
+    /* Excluded from this release type: getCacheKey */
 }
 
-declare type MaterialPropertyType = number | number[] | Color | Texture | Vector2 | Vector3 | Vector4 | null;
+/**
+ * Valid types that can be used as material property overrides
+ */
+declare type MaterialPropertyType = number | number[] | Color | Texture | Vector2 | Vector3 | Vector4 | null | Euler;
 
 export declare namespace MaterialX {
     /**
@@ -10443,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;
@@ -10535,7 +10923,7 @@ export declare namespace NeedleEngineModelLoader {
      *
      */
     export function onDetermineModelMimetype(callback: MimetypeCallback): (() => void);
-    export {};
+        {};
 }
 
 /**
@@ -10545,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[];
@@ -10875,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
  **/
@@ -12096,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
@@ -12108,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;
     /**
@@ -12218,6 +12641,10 @@ export declare class NoiseModule {
     apply(_index: number, pos: Vec3, vel: Vec3, _deltaTime: number, age: number, life: number): void;
 }
 
+/**
+ * Utility type that extracts only non-function property names from a type
+ * @template T The type to extract property names from
+ */
 declare type NonFunctionPropertyNames<T> = {
     [K in keyof T]: T[K] extends Function ? never : K;
 }[keyof T];
@@ -12477,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 {
     /**
@@ -13963,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;
@@ -13998,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;
@@ -14691,9 +15181,16 @@ export declare class OrbitControls extends Component implements ICameraControlle
          constructor(reason: string);
      }
 
-     declare interface PropertyBlockOverride {
+     /**
+      * Represents a single material property override with optional texture transformation
+      * @template T The type of the property value
+      */
+     declare interface PropertyBlockOverride<T extends MaterialPropertyType = MaterialPropertyType> {
+         /** The name of the material property to override (e.g., "color", "map", "roughness") */
          name: string;
-         value: MaterialPropertyType;
+         /** The value to set for this property */
+         value: T;
+         /** Optional texture coordinate transformation (only used when value is a Texture) */
          textureTransform?: TextureTransform;
      }
 
@@ -15115,20 +15612,50 @@ export declare class OrbitControls extends Component implements ICameraControlle
      export declare class ReflectionProbe extends Component {
          private static _probes;
          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.
+          */
+         static readonly onEnabled: EventList<ReflectionProbe>;
+         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.
+          *
+          * Note: This method is used internally by the Renderer component to determine which reflection probe to apply. It is not recommended to call this method directly in most cases. Instead, assign probes to renderers using the "anchor" property or rely on automatic assignment when supported.
+          * Note: Volume-based automatic assignment is not fully supported yet, so explicit assignment is recommended for now.
+          *
+          * @param object The object to find a reflection probe for
+          * @param context The context to search within
+          * @param isAnchor If true, only return a probe if the object is the anchor of that probe
+          * @param anchor Optional anchor object to match against probes
+          */
          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;
+         /**
+          * Defines the center and size of the reflection probe's influence area.
+          */
          center?: Vector3;
+         /**
+          * Defines the size of the reflection probe's influence area. Objects within this box will be affected by the probe's reflections.
+          */
          size?: Vector3;
+         /**
+          * Workaround for lightmap. Compensates for the fact that lightmaps are pre-multiplied by intensity, while reflection probes are not. This means that if you use both lightmaps and reflection probes, you may need to adjust this value to get the correct balance between them. The default value of `Math.PI` is a good starting point for most cases, but you may need to tweak it based on your specific lighting setup and artistic needs.
+          */
+         __lightmapIntensityScale: boolean;
          private _boxHelper?;
          private isInBox;
          constructor();
          awake(): void;
+         onEnable(): void;
+         onDisable(): void;
          start(): void;
          onDestroy(): void;
-         onSet(_rend: IRenderer): void;
-         onUnset(_rend: IRenderer): void;
+         apply(object: Object3D): void;
+         unapply(obj: Object3D): void;
      }
 
      declare enum ReflectionProbeUsage {
@@ -15450,6 +15977,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
          onEnable(): void;
          onDisable(): void;
          onDestroy(): void;
+         private readonly onReflectionProbeEnabled;
+         private onReflectionProbeDisabled;
          onBeforeRender(): void;
          private onBeforeRenderThree;
          onAfterRender(): void;
@@ -16991,8 +17520,6 @@ export declare class OrbitControls extends Component implements ICameraControlle
          /* Excluded from this release type: onEnable */
          /* Excluded from this release type: onDisable */
          /* Excluded from this release type: update */
-         private readonly rendererMaterials;
-         private readonly rendererMaterialsOriginal;
          private updateDirection;
          /**
           * Update the alpha of the object's materials towards the target alpha over the given duration.
@@ -17088,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;
@@ -19078,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
@@ -19201,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;
@@ -19318,8 +19862,13 @@ export declare class OrbitControls extends Component implements ICameraControlle
      /**@obsolete use Graphics.textureToCanvas */
      export declare function textureToCanvas(texture: Texture, force?: boolean): HTMLCanvasElement | null;
 
+     /**
+      * Defines offset and repeat transformations for texture coordinates
+      */
      declare interface TextureTransform {
+         /** UV offset applied to the texture */
          offset?: Vector2;
+         /** UV repeat/scale applied to the texture */
          repeat?: Vector2;
      }
 
@@ -20588,7 +21137,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * scene.add(viewBox);
       * ```
       *
-      * @see {@link Camera} - The camera component that ViewBox controls
+      * @see {@link CameraComponent} - The camera component that ViewBox controls
       * @see {@link OrbitControls} - Camera controls that work alongside ViewBox
       * @see {@link DragControls} - Alternative camera controls compatible with ViewBox
       * @see {@link LookAtConstraint} - Another way to control camera targeting
@@ -20623,7 +21172,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
           * as they would appear with that field of view. Setting it to a wider FOV (e.g., 90) makes objects appear
           * smaller, while a narrower FOV (e.g., 30) makes them appear larger.
           *
-          * @see {@link Camera} for the camera component and its FOV property
+          * @see {@link CameraComponent} for the camera component and its FOV property
           * @default -1 (automatically uses the camera's FOV on the first frame)
           */
          referenceFieldOfView: number;
@@ -20712,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;
@@ -22154,6 +22710,88 @@ export declare class OrbitControls extends Component implements ICameraControlle
      export { }
 
 
+declare global {
+    interface HTMLElementTagNameMap {
+        "needle-engine": NeedleEngineWebComponent;
+    }
+}
+
+
+declare global {
+    interface Navigator {
+        userActivation?: {
+            isActive: boolean;
+        };
+    }
+}
+
+export declare namespace NEEDLE_ENGINE_FEATURE_FLAGS {
+    let experimentalSmartHierarchyUpdate: boolean;
+}
+
+/**
+ * External dependencies that are loaded on demand either by the engine automatically when needed or they can be loaded manually by calling the `load` function.
+ *
+ * Use the `ready` function to wait for the module to be loaded if you do not wand to trigger a load.
+ *
+ * If a module is already loaded it's also available in the `MODULE` variable.
+ */
+export declare namespace MODULES {
+    namespace MaterialX {
+        type TYPE = typeof import("@needle-tools/materialx");
+        let MODULE: TYPE;
+        let MAYBEMODULE: TYPE | null;
+        /** Wait for the module to be loaded (doesn't trigger a load) */
+        function ready(): Promise<TYPE>;
+        /** Load the module */
+        function load(): Promise<TYPE>;
+    }
+    namespace RAPIER_PHYSICS {
+        type TYPE = typeof import("@dimforge/rapier3d-compat");
+        let MODULE: TYPE;
+        let MAYBEMODULE: TYPE | null;
+        /** Wait for the module to be loaded (doesn't trigger a load) */
+        function ready(): Promise<TYPE>;
+        /** Load the module */
+        function load(): Promise<TYPE>;
+    }
+    namespace POSTPROCESSING {
+        type TYPE = typeof import("postprocessing");
+        let MODULE: TYPE;
+        let MAYBEMODULE: TYPE | null;
+        /** Wait for the module to be loaded (doesn't trigger a load) */
+        function ready(): Promise<TYPE>;
+        /** Load the module */
+        function load(): Promise<TYPE>;
+    }
+    namespace POSTPROCESSING_AO {
+        type TYPE = typeof import("n8ao");
+        let MODULE: TYPE;
+        let MAYBEMODULE: TYPE | null;
+        /** Wait for the module to be loaded (doesn't trigger a load) */
+        function ready(): Promise<TYPE>;
+        /** Load the module */
+        function load(): Promise<TYPE>;
+    }
+}
+
+
+export declare namespace PreviewHelper {
+    type PreviewInfo = {
+        position?: Vector3Like | Vec3;
+        size?: Vector3Like | Vec3;
+    };
+    function addPreview(params: {
+        parent: Object3D;
+        guid: string;
+    } & PreviewInfo): {
+        object: Object3D;
+        onProgress: (downloadProgress: number) => void;
+    };
+    function removePreview(guid: string): void;
+}
+
+
 declare module 'three' {
     interface SkinnedMesh {
         staticGenerator?: StaticGeometryGenerator;
@@ -22176,6 +22814,55 @@ declare module 'three' {
 }
 
 
+declare global {
+    interface NavigatorUAData {
+        platform: string;
+    }
+    interface Navigator {
+        userAgentData?: NavigatorUAData;
+    }
+}
+
+
+/**
+ * Utility functions to detect certain device types (mobile, desktop), browsers, or capabilities.
+ * @category Utilities
+ */
+export declare namespace DeviceUtilities {
+    /** @returns `true` for MacOS or Windows devices. `false` for Hololens and other headsets. */
+    function isDesktop(): boolean;
+    /** @returns `true` if it's a phone or tablet */
+    function isMobileDevice(): boolean;
+    /** @deprecated use {@link isiPad} instead */
+    function isIPad(): boolean;
+    /** @returns `true` if we're currently on an iPad */
+    function isiPad(): boolean;
+    /** @returns `true` if we're currently on an Android device */
+    function isAndroidDevice(): boolean;
+    /** @returns `true` if we're currently using the Mozilla XR Browser (only available for iOS) */
+    function isMozillaXR(): boolean;
+    /** @returns `true` if we're currently in the Needle App Clip */
+    function isNeedleAppClip(): boolean;
+    /** @returns `true` for MacOS devices */
+    function isMacOS(): boolean;
+    /** @returns `true` for VisionOS devices */
+    function isVisionOS(): boolean;
+    /** @returns `true` for mobile Apple devices like iPad, iPhone, iPod, Vision Pro, ... */
+    function isiOS(): boolean;
+    /** @returns `true` if we're currently on safari */
+    function isSafari(): boolean;
+    /** @returns `true` for Meta Quest devices and browser. */
+    function isQuest(): boolean;
+    /** @returns `true` if the browser has `<a rel="ar">` support, which indicates USDZ QuickLook support. */
+    function supportsQuickLookAR(): boolean;
+    /** @returns `true` if the user allowed to use the microphone */
+    function microphonePermissionsGranted(): Promise<boolean>;
+    function getiOSVersion(): string | null;
+    function getChromeVersion(): string | null;
+    function getSafariVersion(): string | null;
+}
+
+
 declare module 'three/examples/jsm/controls/OrbitControls.js' {
     interface OrbitControls {
         _sphericalDelta: import("three").Spherical;
@@ -22191,6 +22878,120 @@ declare module 'three/examples/jsm/controls/OrbitControls.js' {
 }
 
 
+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?: {
+            Spector: new () => Spector;
+        };
+    }
+    interface Spector {
+        displayUI: () => void;
+        setCanvas: (canvas: HTMLCanvasElement) => void;
+        spyCanvases: boolean;
+        startCaptureOnNextFrame: () => void;
+        captureCanvas: (canvas: HTMLCanvasElement) => any;
+    }
+}
+
+
+declare global {
+    interface HTMLElementTagNameMap {
+        "needle-logo-element": NeedleLogoElement;
+    }
+}
+
+
+export declare namespace MaterialX {
+    /**
+     * Utility function to load a MaterialX material from a URL. This can be used in your own code to load MaterialX materials outside of the glTF loading process. The URL should point to a MaterialX XML file.
+     */
+    function loadFromUrl(urlOrXML: string, opts?: {
+        url?: string;
+        loadingManager?: LoadingManager;
+        materialNameOrIndex?: number | string;
+    }): Promise<import("three").Material | null>;
+}
+
+/**
+ * @internal
+ */
+export declare namespace InternalAttributeUtils {
+    /**
+     * Checks if the given value is considered "falsey" in the context of HTML attributes.
+     * A value is considered falsey if it is "0" or "false" (case-insensitive).
+     *
+     * @param value - The attribute value to check.
+     * @returns True if the value is falsey, otherwise false.
+     */
+    function isFalsey(value: string | null): boolean;
+    /**
+     * Retrieves the value of the specified attribute from the given element.
+     * If the attribute value is considered falsey, it returns null.
+     * @returns The attribute value or null if falsey.
+     */
+    function getAttributeValueIfNotFalsey(element: Element, attributeName: string, opts?: {
+        onAttribute: (value: string) => void;
+    }): string | null;
+    /**
+     * Retrieves the value of the specified attribute from the given element.
+     * If the attribute value is considered falsey, it returns false.
+     * If the attribute is not set at all, it returns null.
+     * @returns The attribute value, false if falsey, or null if not set.
+     *
+     * @example
+     * ```typescript
+     * const result = HTMLAttributeUtils.getAttributeAndCheckFalsey(element, 'data-example', {
+     *     onAttribute: (value, falsey) => {
+     *         console.log(`Attribute value: ${value}
+     * , Is falsey: ${falsey}`);
+     *     }
+     * });
+     *
+     * if (result === false) {
+     *     console.log('The attribute is set to a falsey value.');
+     * } else if (result === null) {
+     *     console.log('The attribute is not set.');
+     * } else {
+     *     console.log(`The attribute value is: ${result}`);
+     * }
+     * ```
+     */
+    function getAttributeAndCheckFalsey(element: Element, attributeName: string, opts?: {
+        onAttribute: (value: string, falsey: boolean) => void;
+    }): false | string | null;
+}
+
+declare global {
+    interface HTMLElementTagNameMap {
+        "needle-button": NeedleButtonElement;
+    }
+}
+
+
 declare module 'three' {
     interface Object3D {
         get guid(): string | undefined;
@@ -22331,8 +23132,52 @@ 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;
+    }
+}
+
+
+/**
+ * Internal registry for USDZ exporters. This is used by NeedleXRSession.start("immersive-ar")
+ */
+export declare namespace InternalUSDZRegistry {
+    function exportAndOpen(): boolean;
+    function registerExporter(exporter: USDZExporter): void;
+    function unregisterExporter(exporter: USDZExporter): void;
+}
+
+
 declare module 'three' {
     interface Vector3 {
         slerp(end: Vector3, t: number): Vector3;
     }
 }
+
+export declare namespace LCP {
+    function observe(): void;
+}
+
+/**
+ * @param args - The arguments to initialize the performance analytics with.
+ */
+export declare module NeedleEnginePerformanceAnalytics {
+    function init(...args: Array<"lcp">): void;
+}
+