babylonjs-loaders 9.25.0 → 9.26.0

package/babylonjs.loaders.module.d.ts

@@ -7,6 +7,7 @@ export * from "babylonjs-loaders/glTF/pure";
 export * from "babylonjs-loaders/OBJ/pure";
 export * from "babylonjs-loaders/STL/pure";
 export * from "babylonjs-loaders/SPLAT/pure";
+export * from "babylonjs-loaders/USD/pure";
 export * from "babylonjs-loaders/dynamic";
 
 }
@@ -17,6 +18,7 @@ export * from "babylonjs-loaders/glTF/index";
 export * from "babylonjs-loaders/OBJ/index";
 export * from "babylonjs-loaders/STL/index";
 export * from "babylonjs-loaders/SPLAT/index";
+export * from "babylonjs-loaders/USD/index";
 export * from "babylonjs-loaders/dynamic";
 
 }
@@ -8731,6 +8733,436 @@ declare module "babylonjs-loaders/glTF/1.0/glTFBinaryExtension" {
 export * from "babylonjs-loaders/glTF/1.0/glTFBinaryExtension.pure";
 import "babylonjs-loaders/glTF/1.0/glTFLoader";
 
+}
+declare module "babylonjs-loaders/USD/usdWorkerMessages" {
+import { USDLoadProgress } from "babylonjs-loaders/USD/usdLoadingOptions";
+export interface WorkerAsset {
+    bytes: Uint8Array;
+    fileName: string;
+    files?: Record<string, Uint8Array>;
+    resolveByFileName: boolean;
+    glueUrl?: string;
+    wasmUrl?: string;
+    dataUrl?: string;
+}
+export interface ExtractRequest {
+    type: "extract";
+    requestId: number;
+    asset: WorkerAsset;
+}
+export interface WorkerTimings {
+    totalMs: number;
+    stageOpenMs: number;
+    stageReadMs: number;
+    preparationMs: number;
+    packingMs: number;
+    heapCopyMs: number;
+}
+export interface WorkerStatistics {
+    nodes: number;
+    meshes: number;
+    analyticPrimitives: number;
+    instances: number;
+    materials: number;
+    vertices: number;
+    triangles: number;
+    commandBytes: number;
+    dataBytes: number;
+}
+export type WorkerResponse = {
+    type: "progress";
+    requestId: number;
+    progress: USDLoadProgress;
+} | {
+    type: "log";
+    requestId: number;
+    level: number;
+    message: string;
+} | {
+    type: "result";
+    requestId: number;
+    commands: ArrayBuffer;
+    data: ArrayBuffer;
+    timings: WorkerTimings;
+    statistics: WorkerStatistics;
+    missingAssets: string[];
+} | {
+    type: "error";
+    requestId: number;
+    message: string;
+    stack?: string;
+};
+
+}
+declare module "babylonjs-loaders/USD/usdSceneMaterializer" {
+import { AbstractAssetContainer } from "babylonjs/assetContainer";
+import { Scene } from "babylonjs/scene.pure";
+export interface MaterializationResult {
+    container: AbstractAssetContainer & {
+        dispose(): void;
+    };
+    materializeMs: number;
+}
+export function materializeCommandBuffers(scene: Scene, commandBuffer: ArrayBuffer, dataBuffer: ArrayBuffer, addToScene: boolean, signal?: AbortSignal): Promise<MaterializationResult>;
+
+}
+declare module "babylonjs-loaders/USD/usdLoadingOptions" {
+/**
+ * Binary input accepted for supporting USD layers and assets.
+ */
+export type USDBinaryInput = ArrayBuffer | ArrayBufferView;
+/**
+ * Virtual files supplied alongside the root USD layer, keyed by their path relative to the
+ * root layer.
+ */
+export type USDVirtualFiles = Readonly<Record<string, USDBinaryInput>>;
+/**
+ * Progress phases reported by the USD worker and Babylon materializer.
+ */
+export interface USDLoadProgress {
+    /**
+     * Current importer phase.
+     */
+    phase: "initializing" | "staging" | "extracting" | "materializing";
+    /**
+     * Human-readable phase description.
+     */
+    message: string;
+}
+/**
+ * Options for the OpenUSD scene loader.
+ */
+export interface USDFileLoaderOptions {
+    /**
+     * Virtual path used to stage the root layer. Set this when supporting files need
+     * to resolve relative to a directory hierarchy.
+     */
+    rootFileName?: string;
+    /**
+     * Supporting layers, payloads, and textures keyed by virtual path in the same
+     * virtual file system as `rootFileName`.
+     */
+    files?: USDVirtualFiles;
+    /**
+     * Enables conservative file-name fallback for unresolved absolute references.
+     * Defaults to true.
+     */
+    resolveByFileName?: boolean;
+    /**
+     * URL of the module worker. Defaults to the protocol-versioned worker hosted on the Babylon.js CDN.
+     */
+    workerUrl?: string | URL;
+    /**
+     * URL of the generated Emscripten JavaScript module.
+     */
+    glueUrl?: string;
+    /**
+     * URL of the OpenUSD WebAssembly binary.
+     */
+    wasmUrl?: string;
+    /**
+     * URL of the OpenUSD preloaded resource bundle.
+     */
+    dataUrl?: string;
+    /**
+     * Called when the importer moves to a new processing phase.
+     */
+    onProgress?: (progress: USDLoadProgress) => void;
+    /**
+     * Called for OpenUSD diagnostic messages.
+     */
+    onLog?: (level: "info" | "warning" | "error", message: string) => void;
+    /**
+     * Called after extraction and Babylon.js object creation complete.
+     */
+    onComplete?: (diagnostics: USDImportDiagnostics) => void;
+}
+/**
+ * Timing data measured by the OpenUSD worker and Babylon materializer.
+ */
+export interface USDImportTimings {
+    /** Total extraction time, including the final Wasm heap copy. */
+    totalMs: number;
+    /** Time spent opening and composing the USD stage. */
+    stageOpenMs: number;
+    /** Time spent traversing the composed stage. */
+    stageReadMs: number;
+    /** Time spent preparing renderable vertex streams. */
+    preparationMs: number;
+    /** Time spent packing the command and raw-data buffers. */
+    packingMs: number;
+    /** Time spent copying command and data buffers from the Wasm heap. */
+    heapCopyMs: number;
+    /** Time spent creating Babylon.js objects. */
+    materializeMs: number;
+}
+/**
+ * Statistics reported for an imported USD stage.
+ */
+export interface USDImportStatistics {
+    /** Number of transform nodes extracted from the composed stage. */
+    nodes: number;
+    /** Number of polygonal `UsdGeomMesh` sources. */
+    meshes: number;
+    /** Number of analytic cube, sphere, cylinder, and cone sources. */
+    analyticPrimitives: number;
+    /** Number of native Babylon instances created from shared USD geometry. */
+    instances: number;
+    /** Number of authored USD materials translated. */
+    materials: number;
+    /** Number of unique vertices in polygonal source meshes. */
+    vertices: number;
+    /** Number of unique triangles in polygonal source meshes. */
+    triangles: number;
+    /** Size of the command buffer in bytes. */
+    commandBytes: number;
+    /** Size of the raw-data buffer in bytes. */
+    dataBytes: number;
+}
+/**
+ * Diagnostics reported after a USD import completes.
+ */
+export interface USDImportDiagnostics {
+    /** Timing data for extraction and Babylon.js object creation. */
+    timings: USDImportTimings;
+    /** Counts and buffer sizes reported by the OpenUSD extractor. */
+    statistics: USDImportStatistics;
+    /** Asset references OpenUSD could not resolve from the supplied virtual files. */
+    missingAssets: readonly string[];
+}
+
+}
+declare module "babylonjs-loaders/USD/usdFileLoader.types" {
+export {};
+import { USDFileLoaderMetadata } from "babylonjs-loaders/USD/usdFileLoader.metadata";
+import { USDFileLoaderOptions } from "babylonjs-loaders/USD/usdLoadingOptions";
+module "babylonjs/Loading/sceneLoader" {
+    interface SceneLoaderPluginOptions {
+        /**
+         * Defines options for the USD loader.
+         */
+        [USDFileLoaderMetadata.name]: Partial<USDFileLoaderOptions>;
+    }
+}
+
+}
+declare module "babylonjs-loaders/USD/usdFileLoader.pure" {
+/** This file must only contain pure code and pure imports */
+import { AssetContainer } from "babylonjs/assetContainer";
+import { ISceneLoaderAsyncResult, ISceneLoaderPluginAsync, ISceneLoaderPluginFactory, ISceneLoaderProgressEvent, SceneLoaderPluginOptions } from "babylonjs/Loading/sceneLoader";
+import { Scene } from "babylonjs/scene.pure";
+import { USDFileLoaderOptions } from "babylonjs-loaders/USD/usdLoadingOptions";
+/**
+ * OpenUSD scene loader backed by a WebAssembly command-buffer extractor.
+ */
+export class USDFileLoader implements ISceneLoaderPluginAsync, ISceneLoaderPluginFactory {
+    /**
+     * Default URLs for the prebuilt OpenUSD importer assets.
+     */
+    static DefaultConfiguration: {
+        glueUrl: string;
+        wasmUrl: string;
+        dataUrl: string;
+        workerUrl: string;
+    };
+    /**
+     * Defines the name of the plugin.
+     */
+    readonly name: "usd";
+    /**
+     * Defines the extensions the plugin can load.
+     */
+    readonly extensions: {
+        readonly ".usd": {
+            readonly isBinary: true;
+        };
+        readonly ".usda": {
+            readonly isBinary: true;
+        };
+        readonly ".usdc": {
+            readonly isBinary: true;
+        };
+        readonly ".usdz": {
+            readonly isBinary: true;
+        };
+    };
+    private readonly _options;
+    private _worker;
+    private _workerUrl;
+    private _workerBlobUrl;
+    private _nextRequestId;
+    private readonly _pending;
+    private readonly _activeLoads;
+    /**
+     * Creates a USD loader.
+     * @param options Options controlling worker assets, supporting files, and diagnostics.
+     */
+    constructor(options?: Partial<USDFileLoaderOptions>);
+    /**
+     * Creates a configured plugin instance for a SceneLoader operation.
+     * @param options SceneLoader plugin options.
+     * @returns The configured USD loader.
+     */
+    createPlugin(options: SceneLoaderPluginOptions): ISceneLoaderPluginAsync;
+    /**
+     * Imports all objects from a USD stage into a scene.
+     * @param _meshesNames Mesh name filtering is not currently supported.
+     * @param scene The scene receiving the imported objects.
+     * @param data The USD, USDA, USDC, or USDZ bytes.
+     * @param rootUrl The source root URL.
+     * @param onProgress SceneLoader progress callback.
+     * @param fileName Name of the root USD layer.
+     * @returns The imported Babylon.js objects.
+     */
+    importMeshAsync(_meshesNames: string | readonly string[] | null | undefined, scene: Scene, data: unknown, rootUrl: string, onProgress?: (event: ISceneLoaderProgressEvent) => void, fileName?: string): Promise<ISceneLoaderAsyncResult>;
+    /**
+     * Loads a USD stage into a scene.
+     * @param scene The scene receiving the imported objects.
+     * @param data The USD, USDA, USDC, or USDZ bytes.
+     * @param rootUrl The source root URL.
+     * @param onProgress SceneLoader progress callback.
+     * @param fileName Name of the root USD layer.
+     */
+    loadAsync(scene: Scene, data: unknown, rootUrl: string, onProgress?: (event: ISceneLoaderProgressEvent) => void, fileName?: string): Promise<void>;
+    /**
+     * Loads a USD stage into an asset container.
+     * @param scene The scene used to create imported objects.
+     * @param data The USD, USDA, USDC, or USDZ bytes.
+     * @param rootUrl The source root URL.
+     * @param onProgress SceneLoader progress callback.
+     * @param fileName Name of the root USD layer.
+     * @returns The populated asset container.
+     */
+    loadAssetContainerAsync(scene: Scene, data: unknown, rootUrl: string, onProgress?: (event: ISceneLoaderProgressEvent) => void, fileName?: string): Promise<AssetContainer>;
+    /**
+     * Releases the worker and rejects pending loads.
+     */
+    dispose(): void;
+    private _loadAsync;
+    private _getWorker;
+    private _terminateWorker;
+}
+/** @internal */
+export function _RegisterUSDLoaderDependencies(): void;
+/**
+ * Registers the USD scene loader plugin and its Babylon.js runtime dependencies.
+ * Safe to call multiple times; only the first call has an effect.
+ */
+export function RegisterUSDFileLoader(): void;
+
+}
+declare module "babylonjs-loaders/USD/usdFileLoader.metadata" {
+/**
+ * Defines the USD loader plugin metadata.
+ */
+export const USDFileLoaderMetadata: {
+    readonly name: "usd";
+    readonly extensions: {
+        readonly ".usd": {
+            readonly isBinary: true;
+        };
+        readonly ".usda": {
+            readonly isBinary: true;
+        };
+        readonly ".usdc": {
+            readonly isBinary: true;
+        };
+        readonly ".usdz": {
+            readonly isBinary: true;
+        };
+    };
+};
+
+}
+declare module "babylonjs-loaders/USD/usdFileLoader" {
+/**
+ * Re-exports the pure implementation and applies the runtime registration side effect.
+ * Import "./usdFileLoader.pure" for tree-shakeable, side-effect-free usage.
+ */
+export * from "babylonjs-loaders/USD/usdFileLoader.types";
+export * from "babylonjs-loaders/USD/usdFileLoader.pure";
+
+}
+declare module "babylonjs-loaders/USD/usdCommandProtocol" {
+export const COMMAND_MAGIC = 1111774037;
+export const PROTOCOL_VERSION = 4;
+export const MISSING_OFFSET = 4294967295;
+export enum Command {
+    Scene = 1,
+    Texture = 2,
+    Material = 3,
+    TransformNode = 4,
+    Skeleton = 5,
+    Geometry = 6,
+    Mesh = 7,
+    Instance = 8,
+    Animation = 9,
+    AnalyticPrimitive = 10
+}
+export enum AnalyticPrimitiveType {
+    Cube = 0,
+    Sphere = 1,
+    Cylinder = 2,
+    Cone = 3
+}
+export enum PrimitiveAxis {
+    X = 0,
+    Y = 1,
+    Z = 2
+}
+export enum AnimationTarget {
+    Node = 0,
+    Bone = 1
+}
+export enum AnimationProperty {
+    Position = 0,
+    RotationQuaternion = 1,
+    Scaling = 2,
+    Matrix = 3
+}
+export enum MaterialFlags {
+    DoubleSided = 1,
+    Unlit = 2,
+    AlphaBlend = 4
+}
+export enum MeshFlags {
+    DoubleSided = 1,
+    LeftHanded = 2
+}
+export enum GeometryFlags {
+    Normals = 1,
+    Tangents = 2,
+    Uv0 = 4,
+    Colors = 8,
+    Skin0 = 16,
+    Skin1 = 32
+}
+export interface CommandRecord {
+    opcode: Command;
+    flags: number;
+    payloadOffset: number;
+    payloadLength: number;
+}
+export function readCommands(buffer: ArrayBuffer): CommandRecord[];
+export class PayloadReader {
+    #private;
+    offset: number;
+    constructor(buffer: ArrayBuffer, offset: number, length: number);
+    u32(): number;
+    f32(): number;
+}
+
+}
+declare module "babylonjs-loaders/USD/pure" {
+/** Pure barrel — re-exports only side-effect-free modules */
+export * from "babylonjs-loaders/USD/usdFileLoader.pure";
+export * from "babylonjs-loaders/USD/usdLoadingOptions";
+
+}
+declare module "babylonjs-loaders/USD/index" {
+export * from "babylonjs-loaders/USD/usdFileLoader";
+export * from "babylonjs-loaders/USD/usdLoadingOptions";
+
 }
 declare module "babylonjs-loaders/STL/stlFileLoader.types" {
 export {};
@@ -9776,6 +10208,18 @@ export interface ISOGLODMetadata {
  * Selects which LOD value drives the {@link GaussianSplattingStream} debug wireframe colors.
  */
 export type GaussianSplattingStreamDebugLodSource = "optimal" | "current";
+/**
+ * Immutable metadata-resolution state for a stream's total number of finest-LOD splats.
+ * @experimental
+ */
+export type GaussianSplattingStreamLod0SplatCount = Readonly<{
+    status: "pending";
+}> | Readonly<{
+    status: "available";
+    count: number;
+}> | Readonly<{
+    status: "unavailable";
+}>;
 /**
  * Options for {@link GaussianSplattingStream}.
  */
@@ -9895,6 +10339,7 @@ export class GaussianSplattingStream extends GaussianSplattingMesh implements IG
     private readonly _rootUrl;
     private readonly _streamOptions;
     private readonly _leafNodes;
+    private _lod0SplatCount;
     private _lodBaseDistance;
     private _lodMultiplier;
     private _lodBehindPenalty;
@@ -10059,6 +10504,19 @@ export class GaussianSplattingStream extends GaussianSplattingMesh implements IG
      * @experimental
      */
     get effectiveSplatBudget(): number;
+    /**
+     * The resolved maximum number of splats kept resident in the work buffer. This combines
+     * {@link IGaussianSplattingStreamOptions.maxResidentSplats} and {@link IGaussianSplattingStreamOptions.memoryBudgetMb},
+     * taking the smaller limit when both are configured. `0` means the resident budget is disabled.
+     * @experimental
+     */
+    get residentSplatBudget(): number;
+    /**
+     * The total number of splats represented by valid level-0 leaf entries. This remains pending while source
+     * metadata is loading and is unavailable when no applicable level-0 entries exist or required metadata fails.
+     * @experimental
+     */
+    get lod0SplatCount(): GaussianSplattingStreamLod0SplatCount;
     /**
      * Resolves the raw {@link splatBudget} option to a concrete cap: `undefined` ⇒ 0 (disabled), `"auto"` ⇒ a
      * device-tiered default, a positive number ⇒ itself (floored).
@@ -10228,6 +10686,11 @@ export class GaussianSplattingStream extends GaussianSplattingMesh implements IG
      * @returns sorted unique file indices
      */
     private _collectAllFileIds;
+    /**
+     * Settles the level-0 diagnostic from normalized renderable leaf entries after their source metadata resolves.
+     * A file may back several leaf ranges, so its source count is deliberately not used in the total.
+     */
+    private _resolveLod0SplatCount;
     /**
      * Fetches the environment bundle and every referenced file's metadata to learn splat counts, caching
      * each file's parsed metadata for the later on-demand decode. Metadata fetches run in parallel.
@@ -21491,6 +21954,408 @@ declare namespace BABYLON.GLTF1 {
 }
 declare namespace BABYLON {
 
+    export interface WorkerAsset {
+        bytes: Uint8Array;
+        fileName: string;
+        files?: Record<string, Uint8Array>;
+        resolveByFileName: boolean;
+        glueUrl?: string;
+        wasmUrl?: string;
+        dataUrl?: string;
+    }
+    export interface ExtractRequest {
+        type: "extract";
+        requestId: number;
+        asset: WorkerAsset;
+    }
+    export interface WorkerTimings {
+        totalMs: number;
+        stageOpenMs: number;
+        stageReadMs: number;
+        preparationMs: number;
+        packingMs: number;
+        heapCopyMs: number;
+    }
+    export interface WorkerStatistics {
+        nodes: number;
+        meshes: number;
+        analyticPrimitives: number;
+        instances: number;
+        materials: number;
+        vertices: number;
+        triangles: number;
+        commandBytes: number;
+        dataBytes: number;
+    }
+    export type WorkerResponse = {
+        type: "progress";
+        requestId: number;
+        progress: USDLoadProgress;
+    } | {
+        type: "log";
+        requestId: number;
+        level: number;
+        message: string;
+    } | {
+        type: "result";
+        requestId: number;
+        commands: ArrayBuffer;
+        data: ArrayBuffer;
+        timings: WorkerTimings;
+        statistics: WorkerStatistics;
+        missingAssets: string[];
+    } | {
+        type: "error";
+        requestId: number;
+        message: string;
+        stack?: string;
+    };
+
+
+    export interface MaterializationResult {
+        container: AbstractAssetContainer & {
+            dispose(): void;
+        };
+        materializeMs: number;
+    }
+    export function materializeCommandBuffers(scene: Scene, commandBuffer: ArrayBuffer, dataBuffer: ArrayBuffer, addToScene: boolean, signal?: AbortSignal): Promise<MaterializationResult>;
+
+
+    /**
+     * Binary input accepted for supporting USD layers and assets.
+     */
+    export type USDBinaryInput = ArrayBuffer | ArrayBufferView;
+    /**
+     * Virtual files supplied alongside the root USD layer, keyed by their path relative to the
+     * root layer.
+     */
+    export type USDVirtualFiles = Readonly<Record<string, USDBinaryInput>>;
+    /**
+     * Progress phases reported by the USD worker and Babylon materializer.
+     */
+    export interface USDLoadProgress {
+        /**
+         * Current importer phase.
+         */
+        phase: "initializing" | "staging" | "extracting" | "materializing";
+        /**
+         * Human-readable phase description.
+         */
+        message: string;
+    }
+    /**
+     * Options for the OpenUSD scene loader.
+     */
+    export interface USDFileLoaderOptions {
+        /**
+         * Virtual path used to stage the root layer. Set this when supporting files need
+         * to resolve relative to a directory hierarchy.
+         */
+        rootFileName?: string;
+        /**
+         * Supporting layers, payloads, and textures keyed by virtual path in the same
+         * virtual file system as `rootFileName`.
+         */
+        files?: USDVirtualFiles;
+        /**
+         * Enables conservative file-name fallback for unresolved absolute references.
+         * Defaults to true.
+         */
+        resolveByFileName?: boolean;
+        /**
+         * URL of the module worker. Defaults to the protocol-versioned worker hosted on the Babylon.js CDN.
+         */
+        workerUrl?: string | URL;
+        /**
+         * URL of the generated Emscripten JavaScript module.
+         */
+        glueUrl?: string;
+        /**
+         * URL of the OpenUSD WebAssembly binary.
+         */
+        wasmUrl?: string;
+        /**
+         * URL of the OpenUSD preloaded resource bundle.
+         */
+        dataUrl?: string;
+        /**
+         * Called when the importer moves to a new processing phase.
+         */
+        onProgress?: (progress: USDLoadProgress) => void;
+        /**
+         * Called for OpenUSD diagnostic messages.
+         */
+        onLog?: (level: "info" | "warning" | "error", message: string) => void;
+        /**
+         * Called after extraction and Babylon.js object creation complete.
+         */
+        onComplete?: (diagnostics: USDImportDiagnostics) => void;
+    }
+    /**
+     * Timing data measured by the OpenUSD worker and Babylon materializer.
+     */
+    export interface USDImportTimings {
+        /** Total extraction time, including the final Wasm heap copy. */
+        totalMs: number;
+        /** Time spent opening and composing the USD stage. */
+        stageOpenMs: number;
+        /** Time spent traversing the composed stage. */
+        stageReadMs: number;
+        /** Time spent preparing renderable vertex streams. */
+        preparationMs: number;
+        /** Time spent packing the command and raw-data buffers. */
+        packingMs: number;
+        /** Time spent copying command and data buffers from the Wasm heap. */
+        heapCopyMs: number;
+        /** Time spent creating Babylon.js objects. */
+        materializeMs: number;
+    }
+    /**
+     * Statistics reported for an imported USD stage.
+     */
+    export interface USDImportStatistics {
+        /** Number of transform nodes extracted from the composed stage. */
+        nodes: number;
+        /** Number of polygonal `UsdGeomMesh` sources. */
+        meshes: number;
+        /** Number of analytic cube, sphere, cylinder, and cone sources. */
+        analyticPrimitives: number;
+        /** Number of native Babylon instances created from shared USD geometry. */
+        instances: number;
+        /** Number of authored USD materials translated. */
+        materials: number;
+        /** Number of unique vertices in polygonal source meshes. */
+        vertices: number;
+        /** Number of unique triangles in polygonal source meshes. */
+        triangles: number;
+        /** Size of the command buffer in bytes. */
+        commandBytes: number;
+        /** Size of the raw-data buffer in bytes. */
+        dataBytes: number;
+    }
+    /**
+     * Diagnostics reported after a USD import completes.
+     */
+    export interface USDImportDiagnostics {
+        /** Timing data for extraction and Babylon.js object creation. */
+        timings: USDImportTimings;
+        /** Counts and buffer sizes reported by the OpenUSD extractor. */
+        statistics: USDImportStatistics;
+        /** Asset references OpenUSD could not resolve from the supplied virtual files. */
+        missingAssets: readonly string[];
+    }
+
+
+        interface SceneLoaderPluginOptions {
+            /**
+             * Defines options for the USD loader.
+             */
+            [USDFileLoaderMetadata.name]: Partial<USDFileLoaderOptions>;
+        }
+
+
+    /** This file must only contain pure code and pure imports */
+    /**
+     * OpenUSD scene loader backed by a WebAssembly command-buffer extractor.
+     */
+    export class USDFileLoader implements ISceneLoaderPluginAsync, ISceneLoaderPluginFactory {
+        /**
+         * Default URLs for the prebuilt OpenUSD importer assets.
+         */
+        static DefaultConfiguration: {
+            glueUrl: string;
+            wasmUrl: string;
+            dataUrl: string;
+            workerUrl: string;
+        };
+        /**
+         * Defines the name of the plugin.
+         */
+        readonly name: "usd";
+        /**
+         * Defines the extensions the plugin can load.
+         */
+        readonly extensions: {
+            readonly ".usd": {
+                readonly isBinary: true;
+            };
+            readonly ".usda": {
+                readonly isBinary: true;
+            };
+            readonly ".usdc": {
+                readonly isBinary: true;
+            };
+            readonly ".usdz": {
+                readonly isBinary: true;
+            };
+        };
+        private readonly _options;
+        private _worker;
+        private _workerUrl;
+        private _workerBlobUrl;
+        private _nextRequestId;
+        private readonly _pending;
+        private readonly _activeLoads;
+        /**
+         * Creates a USD loader.
+         * @param options Options controlling worker assets, supporting files, and diagnostics.
+         */
+        constructor(options?: Partial<USDFileLoaderOptions>);
+        /**
+         * Creates a configured plugin instance for a SceneLoader operation.
+         * @param options SceneLoader plugin options.
+         * @returns The configured USD loader.
+         */
+        createPlugin(options: SceneLoaderPluginOptions): ISceneLoaderPluginAsync;
+        /**
+         * Imports all objects from a USD stage into a scene.
+         * @param _meshesNames Mesh name filtering is not currently supported.
+         * @param scene The scene receiving the imported objects.
+         * @param data The USD, USDA, USDC, or USDZ bytes.
+         * @param rootUrl The source root URL.
+         * @param onProgress SceneLoader progress callback.
+         * @param fileName Name of the root USD layer.
+         * @returns The imported Babylon.js objects.
+         */
+        importMeshAsync(_meshesNames: string | readonly string[] | null | undefined, scene: Scene, data: unknown, rootUrl: string, onProgress?: (event: ISceneLoaderProgressEvent) => void, fileName?: string): Promise<ISceneLoaderAsyncResult>;
+        /**
+         * Loads a USD stage into a scene.
+         * @param scene The scene receiving the imported objects.
+         * @param data The USD, USDA, USDC, or USDZ bytes.
+         * @param rootUrl The source root URL.
+         * @param onProgress SceneLoader progress callback.
+         * @param fileName Name of the root USD layer.
+         */
+        loadAsync(scene: Scene, data: unknown, rootUrl: string, onProgress?: (event: ISceneLoaderProgressEvent) => void, fileName?: string): Promise<void>;
+        /**
+         * Loads a USD stage into an asset container.
+         * @param scene The scene used to create imported objects.
+         * @param data The USD, USDA, USDC, or USDZ bytes.
+         * @param rootUrl The source root URL.
+         * @param onProgress SceneLoader progress callback.
+         * @param fileName Name of the root USD layer.
+         * @returns The populated asset container.
+         */
+        loadAssetContainerAsync(scene: Scene, data: unknown, rootUrl: string, onProgress?: (event: ISceneLoaderProgressEvent) => void, fileName?: string): Promise<AssetContainer>;
+        /**
+         * Releases the worker and rejects pending loads.
+         */
+        dispose(): void;
+        private _loadAsync;
+        private _getWorker;
+        private _terminateWorker;
+    }
+    /** @internal */
+    export function _RegisterUSDLoaderDependencies(): void;
+    /**
+     * Registers the USD scene loader plugin and its Babylon.js runtime dependencies.
+     * Safe to call multiple times; only the first call has an effect.
+     */
+    export function RegisterUSDFileLoader(): void;
+
+
+    /**
+     * Defines the USD loader plugin metadata.
+     */
+    export var USDFileLoaderMetadata: {
+        readonly name: "usd";
+        readonly extensions: {
+            readonly ".usd": {
+                readonly isBinary: true;
+            };
+            readonly ".usda": {
+                readonly isBinary: true;
+            };
+            readonly ".usdc": {
+                readonly isBinary: true;
+            };
+            readonly ".usdz": {
+                readonly isBinary: true;
+            };
+        };
+    };
+
+
+    /**
+     * Re-exports the pure implementation and applies the runtime registration side effect.
+     * Import "./usdFileLoader.pure" for tree-shakeable, side-effect-free usage.
+     */
+
+
+    export const COMMAND_MAGIC = 1111774037;
+    export const PROTOCOL_VERSION = 4;
+    export const MISSING_OFFSET = 4294967295;
+    export enum Command {
+        Scene = 1,
+        Texture = 2,
+        Material = 3,
+        TransformNode = 4,
+        Skeleton = 5,
+        Geometry = 6,
+        Mesh = 7,
+        Instance = 8,
+        Animation = 9,
+        AnalyticPrimitive = 10
+    }
+    export enum AnalyticPrimitiveType {
+        Cube = 0,
+        Sphere = 1,
+        Cylinder = 2,
+        Cone = 3
+    }
+    export enum PrimitiveAxis {
+        X = 0,
+        Y = 1,
+        Z = 2
+    }
+    export enum AnimationTarget {
+        Node = 0,
+        Bone = 1
+    }
+    export enum AnimationProperty {
+        Position = 0,
+        RotationQuaternion = 1,
+        Scaling = 2,
+        Matrix = 3
+    }
+    export enum MaterialFlags {
+        DoubleSided = 1,
+        Unlit = 2,
+        AlphaBlend = 4
+    }
+    export enum MeshFlags {
+        DoubleSided = 1,
+        LeftHanded = 2
+    }
+    export enum GeometryFlags {
+        Normals = 1,
+        Tangents = 2,
+        Uv0 = 4,
+        Colors = 8,
+        Skin0 = 16,
+        Skin1 = 32
+    }
+    export interface CommandRecord {
+        opcode: Command;
+        flags: number;
+        payloadOffset: number;
+        payloadLength: number;
+    }
+    export function readCommands(buffer: ArrayBuffer): CommandRecord[];
+    export class PayloadReader {
+        #private;
+        offset: number;
+        constructor(buffer: ArrayBuffer, offset: number, length: number);
+        u32(): number;
+        f32(): number;
+    }
+
+
+    /** Pure barrel — re-exports only side-effect-free modules */
+
+
+
+
         interface SceneLoaderPluginOptions {
             /**
              * Defines options for the stl loader.
@@ -22459,6 +23324,18 @@ declare namespace BABYLON {
      * Selects which LOD value drives the {@link GaussianSplattingStream} debug wireframe colors.
      */
     export type GaussianSplattingStreamDebugLodSource = "optimal" | "current";
+    /**
+     * Immutable metadata-resolution state for a stream's total number of finest-LOD splats.
+     * @experimental
+     */
+    export type GaussianSplattingStreamLod0SplatCount = Readonly<{
+        status: "pending";
+    }> | Readonly<{
+        status: "available";
+        count: number;
+    }> | Readonly<{
+        status: "unavailable";
+    }>;
     /**
      * Options for {@link GaussianSplattingStream}.
      */
@@ -22578,6 +23455,7 @@ declare namespace BABYLON {
         private readonly _rootUrl;
         private readonly _streamOptions;
         private readonly _leafNodes;
+        private _lod0SplatCount;
         private _lodBaseDistance;
         private _lodMultiplier;
         private _lodBehindPenalty;
@@ -22742,6 +23620,19 @@ declare namespace BABYLON {
          * @experimental
          */
         get effectiveSplatBudget(): number;
+        /**
+         * The resolved maximum number of splats kept resident in the work buffer. This combines
+         * {@link IGaussianSplattingStreamOptions.maxResidentSplats} and {@link IGaussianSplattingStreamOptions.memoryBudgetMb},
+         * taking the smaller limit when both are configured. `0` means the resident budget is disabled.
+         * @experimental
+         */
+        get residentSplatBudget(): number;
+        /**
+         * The total number of splats represented by valid level-0 leaf entries. This remains pending while source
+         * metadata is loading and is unavailable when no applicable level-0 entries exist or required metadata fails.
+         * @experimental
+         */
+        get lod0SplatCount(): GaussianSplattingStreamLod0SplatCount;
         /**
          * Resolves the raw {@link splatBudget} option to a concrete cap: `undefined` ⇒ 0 (disabled), `"auto"` ⇒ a
          * device-tiered default, a positive number ⇒ itself (floored).
@@ -22911,6 +23802,11 @@ declare namespace BABYLON {
          * @returns sorted unique file indices
          */
         private _collectAllFileIds;
+        /**
+         * Settles the level-0 diagnostic from normalized renderable leaf entries after their source metadata resolves.
+         * A file may back several leaf ranges, so its source count is deliberately not used in the total.
+         */
+        private _resolveLod0SplatCount;
         /**
          * Fetches the environment bundle and every referenced file's metadata to learn splat counts, caching
          * each file's parsed metadata for the later on-demand decode. Metadata fetches run in parallel.