@needle-tools/engine 4.13.1 → 4.14.0-beta

package/dist/needle-engine.d.ts

@@ -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 {};
+        {};
 }
 
 /**
@@ -4684,6 +4684,7 @@ export declare function createMotion(name: string, id?: InstantiateIdProvider):
  *
  * @summary Makes objects follow the cursor/touch position in 3D space
  * @category Interactivity
+ * @category Web
  * @group Components
  * @component
  */
@@ -5081,6 +5082,7 @@ declare enum DeviceType {
 
 /**
  * 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. */
@@ -8723,7 +8725,7 @@ export declare namespace InternalScreenshotUtils {
             [key: string]: boolean | number;
         };
     }): FullscreenPlane;
-    export {};
+        {};
 }
 
 /* Excluded from this release type: invokeLoadedImportPluginHooks */
@@ -10054,6 +10056,215 @@ 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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.
+     *
+     * 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>>;
+    /* Excluded from this release type: getCacheKey */
+}
+
+/**
+ * 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 {
     /**
      * 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.
@@ -10499,7 +10710,7 @@ export declare namespace NeedleEngineModelLoader {
      *
      */
     export function onDetermineModelMimetype(callback: MimetypeCallback): (() => void);
-    export {};
+        {};
 }
 
 /**
@@ -11319,7 +11530,12 @@ export declare type NeedleXRHitTestResult = {
  * The XRRig can be accessed via the `rig` property
  * Set a custom XRRig via `NeedleXRSession.addRig(...)` or `NeedleXRSession.removeRig(...)`
  * By default the active XRRig with the highest priority in the scene is used
+ *
+ * ### Screenshots in XR
+ * Screenshots work automatically during XR sessions, including AR camera feed compositing. See {@link screenshot2} for more information.
+ *
  * @category XR
+ * @see {@link screenshot2} for taking screenshots in XR sessions
  */
 export declare class NeedleXRSession implements INeedleXRSession {
     private static _sync;
@@ -12177,6 +12393,14 @@ 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];
+
 /** Removes all undefined functions */
 declare type NoUndefinedNoFunctions<T> = FilterTypes<T, Function | undefined | null>;
 
@@ -12592,6 +12816,7 @@ export declare function onXRSessionStart(fn: (evt: XRSessionEventArgs) => void):
  * OpenURL behaviour opens a URL in a new tab or window when the object (or any if it's children) is clicked.
  *
  * @category Interactivity
+ * @category Web
  * @group Components
  */
 export declare class OpenURL extends Component implements IPointerClickHandler {
@@ -14645,6 +14870,19 @@ export declare class OrbitControls extends Component implements ICameraControlle
          constructor(reason: string);
      }
 
+     /**
+      * 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;
+         /** The value to set for this property */
+         value: T;
+         /** Optional texture coordinate transformation (only used when value is a Texture) */
+         textureTransform?: TextureTransform;
+     }
+
      export declare const PUBLIC_KEY: string;
 
      /** Adds an entry to the browser history. Internally uses `window.history.pushState` */
@@ -15063,21 +15301,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;
-         private static _rendererMaterialsCache;
-         onSet(_rend: IRenderer): void;
-         onUnset(_rend: IRenderer): void;
+         apply(object: Object3D): void;
+         unapply(obj: Object3D): void;
      }
 
      declare enum ReflectionProbeUsage {
@@ -15399,6 +15665,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;
@@ -15477,23 +15745,27 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private lightmapIndex;
          private lightmapScaleOffset;
          private readonly renderer;
-         private readonly clonedMaterials;
+         private _isApplied;
          private get context();
          private get gameObject();
          private lightmapTexture;
-         private lightmapScaleOffsetUniform;
-         private lightmapUniform;
          constructor(renderer: Renderer);
          init(lightmapIndex: number, lightmapScaleOffset: Vector4, lightmapTexture: Texture): void;
-         updateLightmapUniforms(material: Material): void;
+         updateLightmapUniforms(_material: any): void;
          /**
-          * Apply the lightmap to the object. This will clone the material and set the lightmap texture and scale/offset
+          * Apply the lightmap to the object using MaterialPropertyBlock instead of cloning materials.
+          * The lightmap texture and its per-object UV transform are set as overrides via PropertyBlock.
+          * Three.js reads material.lightMap to determine shader defines and upload uniforms,
+          * and uses texture.offset/repeat to compute lightMapTransform in the vertex shader.
           */
          applyLightmap(): void;
+         /** Update the lightMap override on all property blocks (e.g. after LOD swap) */
+         private updatePropertyBlockTexture;
+         /**
+          * Remove the lightmap from the object
+          */
+         onUnset(): void;
          private ensureLightmapUvs;
-         private ensureLightmapMaterial;
-         private assignLightmapTexture;
-         private onBeforeCompile;
          private setLightmapDebugMaterial;
      }
 
@@ -16327,40 +16599,179 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * const dataUrl = screenshot();
       * saveImage(dataUrl, "screenshot.png");
       * ```
+      *
       */
      export declare function screenshot(context?: Context, width?: number, height?: number, mimeType?: ScreenshotImageMimeType, camera?: Camera_2 | null): string | null;
 
      /**
-      * Take a screenshot from the current scene and return a {@link Texture}. This can applied to a surface in 3D space.
+      * Take a screenshot from the current scene and return a {@link Texture}. This can be applied to a surface in 3D space.
       * @param opts Provide `{ type: "texture" }` to get a texture instead of a data url.
       * @returns The texture of the screenshot. Returns null if the screenshot could not be taken.
+      * @category Utilities
+      * @example
+      * ```ts
+      * // Create a texture from the current view
+      * const screenshotTexture = screenshot2({ type: "texture", width: 512, height: 512 });
+      * if (screenshotTexture) {
+      *   myMaterial.map = screenshotTexture;
+      *   myMaterial.needsUpdate = true;
+      * }
+      *
+      * // Update an existing texture
+      * const existingTexture = new Texture();
+      * screenshot2({ type: "texture", target: existingTexture, transparent: true });
+      * ```
       */
      export declare function screenshot2(opts: ScreenshotOptionsTexture): Texture | null;
 
      /**
-      * Take a screenshot from the current scene.
-      * @param opts
-      * @returns The data url of the screenshot. Returns null if the screenshot could not be taken.
+      * Take a screenshot from the current scene and return a data URL string.
+      *
+      * @param opts Screenshot options. All properties are optional.
+      * @returns The data URL of the screenshot (e.g., "data:image/png;base64,..."). Returns null if the screenshot could not be taken.
+      * @category Utilities
+      *
+      * @example Basic screenshot
       * ```ts
-      * const res = screenshot2({
-      *    width: 1024,
+      * // Take a simple screenshot with default settings
+      * const dataUrl = screenshot2({});
+      * console.log(dataUrl); // "data:image/webp;base64,..."
+      * ```
+      *
+      * @example High-resolution screenshot with transparent background
+      * ```ts
+      * const dataUrl = screenshot2({
+      *   width: 2048,
+      *   height: 2048,
+      *   mimeType: "image/png",
+      *   transparent: true,
+      *   trim: true, // Remove transparent edges
+      * });
+      * ```
+      *
+      * @example Screenshot with custom background color
+      * ```ts
+      * import { Color } from "three";
+      *
+      * const dataUrl = screenshot2({
+      *   width: 1024,
       *   height: 1024,
-      *  mimeType: "image/webp",
-      * transparent: true,
-      * })
-      * // use saveImage to download the image
-      * saveImage(res, "screenshot.webp");
+      *   background: new Color(0x00ff00), // Green background
+      * });
+      * ```
+      *
+      * @example Download screenshot automatically
+      * ```ts
+      * screenshot2({
+      *   width: 1920,
+      *   height: 1080,
+      *   mimeType: "image/jpeg",
+      *   download_filename: "my-scene.jpg",
+      * });
+      * ```
+      *
+      * @example Manual download using saveImage
+      * ```ts
+      * const dataUrl = screenshot2({
+      *   width: 1024,
+      *   height: 1024,
+      *   mimeType: "image/webp",
+      *   transparent: true,
+      * });
+      * if (dataUrl) {
+      *   saveImage(dataUrl, "screenshot.webp");
+      * }
+      * ```
+      *
+      * @example Screenshot from specific camera
+      * ```ts
+      * const myCamera = this.gameObject.getComponent(Camera);
+      * const dataUrl = screenshot2({
+      *   camera: myCamera,
+      *   width: 1024,
+      *   height: 1024,
+      * });
       * ```
       */
      export declare function screenshot2(opts: ScreenshotOptionsDataUrl): string | null;
 
      /**
-      * Take a screenshot asynchronously from the current scene.
-      * @returns A promise that resolves with the blob of the screenshot. Returns null if the screenshot could not be taken.
-      * @param {ScreenshotOptionsBlob} opts Set `{ type: "blob" }` to get a blob instead of a data url.
+      * Take a screenshot asynchronously and return a Blob. This is useful when you need to process or upload the image data.
+      *
+      * @param opts Set `{ type: "blob" }` to get a blob instead of a data url. All other {@link ScreenshotOptions} are also available.
+      * @returns A Promise that resolves with the Blob of the screenshot. Returns null if the screenshot could not be taken.
+      * @category Utilities
+      *
+      * @example Upload screenshot to server
+      * ```ts
+      * const blob = await screenshot2({ type: "blob", mimeType: "image/png" });
+      * if (blob) {
+      *   const formData = new FormData();
+      *   formData.append("screenshot", blob, "screenshot.png");
+      *   await fetch("/api/upload", { method: "POST", body: formData });
+      * }
+      * ```
+      *
+      * @example Save blob to file (browser download)
+      * ```ts
+      * const blob = await screenshot2({
+      *   type: "blob",
+      *   width: 1920,
+      *   height: 1080,
+      *   transparent: true
+      * });
+      * if (blob) {
+      *   const url = URL.createObjectURL(blob);
+      *   saveImage(url, "screenshot.png");
+      *   URL.revokeObjectURL(url); // Clean up
+      * }
+      * ```
       */
      export declare function screenshot2(opts: ScreenshotOptionsBlob): Promise<Blob | null>;
 
+     /**
+      * Take a screenshot and share it using the Web Share API (mobile-friendly).
+      *
+      * **Note**: The Web Share API is only available in secure contexts (HTTPS) and may not be supported on all platforms/browsers.
+      *
+      * @param opts Set `{ type: "share" }` to share the screenshot. Additional options like `filename`, `title`, `text`, and `url` can be provided.
+      * @returns A Promise that resolves with an object containing the blob and whether it was successfully shared.
+      * @category Utilities
+      *
+      * @example Share screenshot on mobile
+      * ```ts
+      * const result = await screenshot2({
+      *   type: "share",
+      *   filename: "my-creation.png",
+      *   title: "Check out my 3D scene!",
+      *   text: "I created this with Needle Engine",
+      *   url: "https://engine.needle.tools",
+      *   mimeType: "image/png",
+      * });
+      *
+      * if (result.shared) {
+      *   console.log("Screenshot shared successfully!");
+      * } else {
+      *   console.log("User cancelled or sharing not supported");
+      * }
+      * ```
+      *
+      * @example Share with fallback
+      * ```ts
+      * const result = await screenshot2({
+      *   type: "share",
+      *   filename: "screenshot.webp",
+      *   file_type: "image/webp",
+      * });
+      *
+      * if (!result.shared && result.blob) {
+      *   // Fallback: download the image instead
+      *   const url = URL.createObjectURL(result.blob);
+      *   saveImage(url, "screenshot.webp");
+      *   URL.revokeObjectURL(url);
+      * }
+      * ```
+      */
      export declare function screenshot2(opts: ScreenshotOptionsShare): Promise<ScreenshotOptionsShareReturnType>;
 
      declare type ScreenshotImageMimeType = "image/webp" | "image/png" | "image/jpeg";
@@ -16422,11 +16833,29 @@ export declare class OrbitControls extends Component implements ICameraControlle
      };
 
      export declare type ScreenshotOptionsShare = ScreenshotOptions & {
+         /**
+          * Set `{ type: "share" }` to share the screenshot using the Web Share API. The promise will resolve with the blob of the screenshot and whether it was shared successfully or not. Note that the Web Share API is only available in secure contexts (HTTPS) and on some platforms.
+          */
          type: "share";
+         /**
+          * The filename to use when sharing the screenshot. If not provided, a default filename will be used.
+          */
          filename?: string;
+         /**
+          * The mime type of the shared file. If not provided, the mime type will be inferred from the screenshot options or default to "image/png".
+          */
          file_type?: ScreenshotImageMimeType;
+         /**
+          * The title to use when sharing the screenshot. This is optional and may not be supported by all platforms.
+          */
          title?: string;
+         /**
+          * The text to use when sharing the screenshot. This is optional and may not be supported by all platforms.
+          */
          text?: string;
+         /**
+          * The URL to use when sharing the screenshot. This is optional and may not be supported by all platforms.
+          */
          url?: string;
      };
 
@@ -16568,6 +16997,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
       *
       * @summary Links scroll position to target objects
       * @category Web
+      * @category Interaction
       * @group Components
       * @component
       */
@@ -16778,8 +17208,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.
@@ -19105,6 +19533,16 @@ 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;
+     }
+
      declare enum TextWrapMode {
          singleLine = "singleLine",
          hardBreaks = "hardBreaks",
@@ -20370,7 +20808,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
@@ -20405,7 +20843,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;
@@ -20779,11 +21217,20 @@ export declare class OrbitControls extends Component implements ICameraControlle
      /**
       * WebARCameraBackground is a component that allows to display the camera feed as a background in an AR session to more easily blend the real world with the virtual world or applying effects to the camera feed.
       *
+      * This component automatically requests `camera-access` permission when entering AR mode, which is required to:
+      * - Display the real-world camera feed as a background
+      * - Include the camera feed in AR screenshots taken with {@link screenshot2}
+      *
+      * **Note**: If you want to take AR screenshots with the camera feed but don't need to display it as a background,
+      * you can still add this component to your scene (it will request camera access) or manually request the
+      * `camera-access` feature in your `onBeforeXR` method.
+      *
       * - Example: https://samples.needle.tools/ar-camera-background
       *
       * @summary Displays the camera feed as background in WebAR sessions
       * @category XR
       * @group Components
+      * @see {@link screenshot2} for taking screenshots in AR (requires camera access for camera feed compositing)
       */
      export declare class WebARCameraBackground extends Component {
          /* Excluded from this release type: onBeforeXR */
@@ -20942,6 +21389,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * @see {@link XRControllerMovement} for VR locomotion
       * @see {@link WebARSessionRoot} for AR session configuration
       * @see {@link Avatar} for networked user avatars
+      * @see {@link screenshot2} for taking screenshots in XR (including AR camera feed compositing)
       * @link https://engine.needle.tools/docs/xr.html
       * @link https://engine.needle.tools/samples/?overlay=samples&tag=xr
       * @link https://engine.needle.tools/samples/collaborative-sandbox
@@ -21926,6 +22374,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;
@@ -21948,21 +22517,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;
@@ -22102,9 +22811,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;
+}
+