@needle-tools/engine 4.14.0-next.31f837e → 4.14.0-next.b2e3b1a

package/dist/needle-engine.d.ts

@@ -193,7 +193,7 @@ export declare function addComponent<T extends IComponent>(obj: Object3D, compon
 /** Register callbacks for registering custom gltf importer or exporter plugins */
 export declare function addCustomExtensionPlugin(ext: INeedleGLTFExtensionPlugin): void;
 
-export declare function addNewComponent<T extends IComponent>(obj: Object3D, componentInstance: T, callAwake?: boolean): T;
+export declare function addNewComponent<T extends IComponent>(obj: Object3D, componentInstance: T, callAwake?: boolean, register?: boolean): T;
 
 /**
  * Use patcher for patching properties insteadof calling Object.defineProperty individually
@@ -2029,7 +2029,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 {};
+        {};
 }
 
 /**
@@ -4324,6 +4324,18 @@ export declare class Context implements IContext {
      * Update the camera aspect ratio or orthorgraphic camera size. This is automatically called when a DOM size change is detected.
      */
     updateAspect(camera: PerspectiveCamera | OrthographicCamera, width?: number, height?: number): void;
+    /**
+     * Registers all uninitialized components found in the scene hierarchy with this context.
+     * Components that have been added to objects (e.g. via `addComponent`) but are not yet registered
+     * with a context will be collected and queued for initialization.
+     * On the next frame, these components will go through the full lifecycle: `awake` → `onEnable` → `start` → `update`.
+     *
+     * This is useful when components are created outside of the normal glTF loading pipeline,
+     * for example in an editor that adds components during edit mode and then needs to activate them for play mode.
+     * @param root The root object to search for components. Defaults to the context's scene.
+     * @returns The number of components that were newly registered.
+     */
+    registerSceneComponents(root?: Object3D): number;
     /** This will recreate the whole needle engine context and dispose the whole scene content
      * All content will be reloaded (loading times might be faster due to browser caches)
      * All scripts will be recreated */
@@ -8725,7 +8737,7 @@ export declare namespace InternalScreenshotUtils {
             [key: string]: boolean | number;
         };
     }): FullscreenPlane;
-    export {};
+        {};
 }
 
 /* Excluded from this release type: invokeLoadedImportPluginHooks */
@@ -10056,39 +10068,214 @@ 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).
+ *
+ * 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 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
+     * @param name The property name to clear
+     */
+    removeOveride<K extends NonFunctionPropertyNames<T>>(name: K | ({} & string)): void;
+    /**
+     * Removes all property overrides from this block
+     */
     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 {
     /**
@@ -10535,7 +10722,7 @@ export declare namespace NeedleEngineModelLoader {
      *
      */
     export function onDetermineModelMimetype(callback: MimetypeCallback): (() => void);
-    export {};
+        {};
 }
 
 /**
@@ -12218,6 +12405,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];
@@ -14691,9 +14882,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 +15313,49 @@ 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;
          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 +15677,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 +17220,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.
@@ -19318,8 +19545,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 +20820,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 +20855,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;
@@ -22154,6 +22386,127 @@ export declare class OrbitControls extends Component implements ICameraControlle
      export { }
 
 
+declare global {
+    interface HTMLElementTagNameMap {
+        "needle-engine": NeedleEngineWebComponent;
+    }
+}
+
+
+declare global {
+    interface Navigator {
+        userActivation?: {
+            isActive: boolean;
+        };
+    }
+}
+
+
+declare module 'three/examples/jsm/controls/OrbitControls.js' {
+    interface OrbitControls {
+        _sphericalDelta: import("three").Spherical;
+        _rotateLeft: (angleInRadians: number) => void;
+        _rotateUp: (angleInRadians: number) => void;
+        _pan: (dx: number, dy: number) => void;
+        _dollyIn: (dollyScale: number) => void;
+        _dollyOut: (dollyScale: number) => void;
+    }
+    interface OrbitControlsEventMap {
+        endMovement: Event;
+    }
+}
+
+
+declare global {
+    interface ViewTimeline {
+        axis: 'block' | 'inline';
+        currentTime: {
+            unit: 'seconds' | 'percent';
+            value: number;
+        };
+        duration: {
+            unit: 'seconds' | 'percent';
+            value: number;
+        };
+        source: Element | null;
+        startOffset: {
+            unit: 'px';
+            value: number;
+        };
+        endOffset: {
+            unit: 'px';
+            value: number;
+        };
+    }
+}
+
+export declare namespace NEEDLE_ENGINE_FEATURE_FLAGS {
+    let experimentalSmartHierarchyUpdate: boolean;
+}
+
+/**
+ * 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,21 +22529,161 @@ declare module 'three' {
 }
 
 
-declare module 'three/examples/jsm/controls/OrbitControls.js' {
-    interface OrbitControls {
-        _sphericalDelta: import("three").Spherical;
-        _rotateLeft: (angleInRadians: number) => void;
-        _rotateUp: (angleInRadians: number) => void;
-        _pan: (dx: number, dy: number) => void;
-        _dollyIn: (dollyScale: number) => void;
-        _dollyOut: (dollyScale: number) => void;
+declare global {
+    interface NavigatorUAData {
+        platform: string;
     }
-    interface OrbitControlsEventMap {
-        endMovement: Event;
+    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 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>;
+}
+
+declare global {
+    interface HTMLElementTagNameMap {
+        "needle-button": NeedleButtonElement;
+    }
+}
+
+/**
+ * @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;
+}
+
+
+/**
+ * @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 module 'three' {
     interface Object3D {
         get guid(): string | undefined;
@@ -22330,9 +22823,37 @@ declare module 'three' {
     }
 }
 
+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;
+}
+