babylonjs-loaders 9.26.1 → 9.26.2

package/babylonjs.loaders.d.ts

@@ -2828,8 +2828,9 @@ declare namespace BABYLON.GLTF2 {
         onLoading?(): void;
         /**
          * Called after the loader state changes to READY.
+         * @returns a promise when the extension has asynchronous readiness work
          */
-        onReady?(): void;
+        onReady?(): void | Promise<void>;
         /**
          * Define this method to modify the default behavior when loading scenes.
          * @param context The context when loading the asset
@@ -3417,7 +3418,7 @@ declare namespace BABYLON.GLTF2 {
         private _forEachExtensions;
         private _applyExtensions;
         private _extensionsOnLoading;
-        private _extensionsOnReady;
+        private _extensionsOnReadyAsync;
         private _extensionsLoadSceneAsync;
         private _extensionsLoadNodeAsync;
         private _extensionsLoadCameraAsync;
@@ -4060,9 +4061,10 @@ declare namespace BABYLON.GLTF2.Loader.Extensions {
     /**
      * get a path-to-object converter for the given glTF tree
      * @param gltf the glTF tree to use
+     * @param configure optional callback for adding asset-local accessors to this converter
      * @returns a path-to-object converter for the given glTF tree
      */
-    export function GetPathToObjectConverter(gltf: BABYLON.GLTF2.Loader.IGLTF): BABYLON.GLTF2.Loader.Extensions.GLTFPathToObjectConverter<unknown, unknown, unknown>;
+    export function GetPathToObjectConverter(gltf: BABYLON.GLTF2.Loader.IGLTF, configure?: (mapping: object) => void): BABYLON.GLTF2.Loader.Extensions.GLTFPathToObjectConverter<unknown, unknown, unknown>;
     /**
      * This function will return the object accessor for the given key in the object model
      * If the key is not found, it will return undefined
@@ -4081,8 +4083,9 @@ declare namespace BABYLON.GLTF2.Loader.Extensions {
      * Note that this will NOT change the typescript types. To do that you will need to change the interface itself (extending it in the module that uses it)
      * @param key the key to add the object accessor at. For example /cameras/\{\}/perspective/aspectRatio
      * @param accessor the object accessor to add
+     * @param mapping object-model mapping to update; defaults to the process-wide mapping used as the template for new converters
      */
-    export function AddObjectAccessorToKey<GLTFTargetType = any, BabylonTargetType = any, BabylonValueType = any>(key: string, accessor: IObjectAccessor<GLTFTargetType, BabylonTargetType, BabylonValueType>): void;
+    export function AddObjectAccessorToKey<GLTFTargetType = any, BabylonTargetType = any, BabylonValueType = any>(key: string, accessor: IObjectAccessor<GLTFTargetType, BabylonTargetType, BabylonValueType>, mapping?: object): void;
 
 
 
@@ -5038,6 +5041,8 @@ declare namespace BABYLON.GLTF2.Loader.Extensions {
          * The name of this extension.
          */
         readonly name = "KHR_node_selectability";
+        /** Applies node state before KHR_interactivity graphs start. */
+        readonly order = 100;
         /**
          * Defines whether this extension is enabled.
          */
@@ -5105,6 +5110,8 @@ declare namespace BABYLON.GLTF2.Loader.Extensions {
          * The name of this extension.
          */
         readonly name = "KHR_node_hoverability";
+        /** Applies node state before KHR_interactivity graphs start. */
+        readonly order = 100;
         /**
          * Defines whether this extension is enabled.
          */
@@ -6645,12 +6652,74 @@ declare namespace BABYLON {
         /**
          * Defines options for the KHR_interactivity extension.
          */
-        ["KHR_interactivity"]: {};
+        ["KHR_interactivity"]: {
+            /**
+             * Whether the selected default graph starts automatically after import.
+             * Defaults to true.
+             */
+            autoStart?: boolean;
+            /**
+             * Whether to retain only the canonical source model and executable
+             * FlowGraph serialization without constructing runtime graphs.
+             * Defaults to false.
+             */
+            parseOnly?: boolean;
+            /**
+             * Whether to enforce the ratified graph validation rules.
+             * Defaults to true. Set to false only for pre-ratification assets.
+             */
+            strictValidation?: boolean;
+        };
     }
 
 }
 declare namespace BABYLON.GLTF2.Loader.Extensions {
         /**
+     * Runtime projection of one canonical KHR_interactivity graph.
+     */
+    export interface IKHRInteractivityGraphImportResult {
+        /** Canonical source graph and diagnostics. */
+        graph: BABYLON.GLTF2.Loader.Extensions.IKHRInteractivityGraphModel;
+        /** Executable FlowGraph serialization when lowering succeeded. */
+        serializedFlowGraph?: ISerializedFlowGraph;
+        /** Runtime FlowGraph when runtime construction was requested. */
+        flowGraph?: FlowGraph;
+        /** Coordinator that owns the runtime FlowGraph. */
+        coordinator?: FlowGraphCoordinator;
+        /** Additional lowering/runtime diagnostics. */
+        diagnostics: BABYLON.GLTF2.Loader.Extensions.IKHRInteractivityDiagnostic[];
+    }
+    /**
+     * Completed KHR_interactivity import result associated with a loaded scene.
+     */
+    export interface IKHRInteractivityImportResult {
+        /** Stable zero-based identity of this interactivity asset among assets appended to the scene. */
+        assetIndex: number;
+        /** Canonical, lossless source document. */
+        document: BABYLON.GLTF2.Loader.Extensions.IKHRInteractivityDocument;
+        /** Graph import results in source order. */
+        graphs: IKHRInteractivityGraphImportResult[];
+        /** Shared path converter required by pointer blocks. */
+        pathConverter: BABYLON.GLTF2.Loader.Extensions.CompositePathToObjectConverter<IObjectAccessor>;
+        /** Live glTF loader data used by glTF data-provider blocks. */
+        glTF: BABYLON.GLTF2.GLTFLoader["gltf"];
+        /** Host resolver that supplies KHR reference semantics to executable graphs. */
+        hostResolver: BABYLON.GLTF2.Loader.Extensions.InteractivityHostResolver;
+    }
+    /**
+     * Gets the completed KHR_interactivity import result for a loaded scene.
+     * @param scene scene loaded from the glTF asset
+     * @returns the import result, or undefined when the scene has no KHR_interactivity data
+     */
+    export function GetKHRInteractivityImportResult(scene: Scene): IKHRInteractivityImportResult | undefined;
+    /**
+     * Gets every completed KHR_interactivity import result appended to a loaded scene.
+     * Results remain in asset load order and each result has a stable {@link IKHRInteractivityImportResult.assetIndex}.
+     * @param scene scene containing the loaded glTF assets
+     * @returns the scene's import results, or an empty array when it has no KHR_interactivity data
+     */
+    export function GetKHRInteractivityImportResults(scene: Scene): readonly IKHRInteractivityImportResult[];
+    /**
      * Loader extension for KHR_interactivity
      */
     export class KHR_interactivity implements BABYLON.GLTF2.IGLTFLoaderExtension {
@@ -6659,6 +6728,8 @@ declare namespace BABYLON.GLTF2.Loader.Extensions {
          * The name of this extension.
          */
         readonly name = "KHR_interactivity";
+        /** Runs after extensions that contribute interactivity operations and object state. */
+        readonly order = 200;
         /**
          * Defines whether this extension is enabled.
          */
@@ -6670,6 +6741,7 @@ declare namespace BABYLON.GLTF2.Loader.Extensions {
          * @param _loader
          */
         constructor(_loader: BABYLON.GLTF2.GLTFLoader);
+        private _initializePathConverter;
         dispose(): void;
         onReady(): Promise<void>;
     }
@@ -6677,7 +6749,7 @@ declare namespace BABYLON.GLTF2.Loader.Extensions {
      * @internal
      * populates the object model with the interactivity extension
      */
-    export function _AddInteractivityObjectModel(scene: Scene): void;
+    export function _AddInteractivityObjectModel(scene: Scene, targetFps: number, mapping: object): void;
     /**
      * @internal
      * Registers KHR_interactivity runtime dependencies without changing the extension registry.
@@ -7549,6 +7621,37 @@ declare namespace BABYLON.GLTF2.Loader.Extensions {
 
 
 
+}
+declare namespace BABYLON {
+
+
+}
+declare namespace BABYLON.GLTF2.Loader.Extensions {
+        type InteractivityNodeState = "hoverable" | "selectable";
+    /**
+     * Initializes authored and inherited selectability or hoverability state.
+     * @param nodes all nodes in the glTF asset
+     * @param state state kind to initialize
+     * @param getAuthoredState reads the extension-authored local state
+     */
+    export function InitializeInteractivityNodeState(nodes: readonly BABYLON.GLTF2.Loader.INode[], state: InteractivityNodeState, getAuthoredState: (node: BABYLON.GLTF2.Loader.INode) => boolean | undefined): void;
+    /**
+     * Gets the locally authored runtime state for a node.
+     * @param node glTF node
+     * @param state state kind
+     * @returns local state, defaulting to true
+     */
+    export function GetInteractivityNodeState(node: BABYLON.GLTF2.Loader.INode, state: InteractivityNodeState): boolean;
+    /**
+     * Updates local state and reapplies inherited state to the affected subtree.
+     * @param node glTF node
+     * @param state state kind
+     * @param value new local state
+     */
+    export function SetInteractivityNodeState(node: BABYLON.GLTF2.Loader.INode, state: InteractivityNodeState, value: boolean): void;
+
+
+
 }
 declare namespace BABYLON {
 
@@ -7574,9 +7677,10 @@ declare namespace BABYLON.GLTF2.Loader.Extensions {
         decodeEventReference(reference: string): string | undefined;
         /**
          * @param reference the reference to decode
+         * @param collection optional glTF root collection the reference must address
          * @returns the index the reference denotes, or `undefined` when it is not an indexed JSON Pointer
          */
-        decodeIndexReference(reference: string): number | undefined;
+        decodeIndexReference(reference: string, collection?: string): number | undefined;
         /**
          * Maps a Babylon object loaded from the glTF back to a JSON Pointer addressing it.
          *
@@ -7621,13 +7725,6 @@ declare namespace BABYLON.GLTF2.Loader.Extensions {
             value?: any;
         }[];
     }
-    export var gltfTypeToBabylonType: {
-        [key: string]: {
-            length: number;
-            flowGraphType: FlowGraphTypes;
-            elementType: "number" | "boolean" | "string";
-        };
-    };
     /**
      * Parses a KHR_interactivity graph definition (the raw glTF JSON object) into
      * the serialized FlowGraph form consumed by {@link ParseFlowGraphAsync}.
@@ -7637,9 +7734,11 @@ declare namespace BABYLON.GLTF2.Loader.Extensions {
      * {@link serializeToFlowGraph}.
      */
     export class InteractivityGraphToFlowGraphParser {
-        private _interactivityGraph;
         private _gltf;
         _animationTargetFps: number;
+        private _graphIndex;
+        private _supportedExtensions?;
+        private _declarationModels?;
         /**
          * Note - the graph should be rejected if the same type is defined twice.
          * We currently don't validate that.
@@ -7657,16 +7756,22 @@ declare namespace BABYLON.GLTF2.Loader.Extensions {
          * the last block) is not disturbed, then concatenated into the serialized graph.
          */
         private _insertedBlocks;
-        constructor(_interactivityGraph: BABYLON.GLTF2.IKHRInteractivity_Graph, _gltf: BABYLON.GLTF2.Loader.IGLTF, _animationTargetFps?: number);
+        constructor(interactivityGraph: BABYLON.GLTF2.IKHRInteractivity_Graph, _gltf: BABYLON.GLTF2.Loader.IGLTF, _animationTargetFps?: number, _graphIndex?: number, _supportedExtensions?: ReadonlySet<string> | undefined, _declarationModels?: readonly BABYLON.GLTF2.Loader.Extensions.IKHRInteractivityDeclarationModel[] | undefined);
+        private _interactivityGraph;
+        private get _strictValidation();
+        private _hasDefaultFlowInput;
+        private _getAllowedDynamicValueSockets;
+        private _getAllowedDynamicFlowSockets;
         get arrays(): {
             types: {
                 length: number;
                 flowGraphType: FlowGraphTypes;
-                elementType: "number" | "boolean" | "string";
+                elementType: "number" | "boolean" | "string" | "any";
             }[];
             mappings: {
                 flowGraphMapping: BABYLON.GLTF2.Loader.Extensions.IGLTFToFlowGraphMapping;
                 fullOperationName: string;
+                declaration: BABYLON.GLTF2.Loader.Extensions.IKHRInteractivityDeclarationModel;
             }[];
             staticVariables: {
                 type: FlowGraphTypes;
@@ -7682,12 +7787,15 @@ declare namespace BABYLON.GLTF2.Loader.Extensions {
         private _parseDeclarations;
         private _parseVariables;
         private _parseVariable;
+        private _normalizeStaticReference;
         private _parseEvents;
         private _parseNodes;
         private _getEmptyBlock;
+        private _createUnsupportedExtensionBlock;
         private _parseNodeConfiguration;
         private _parseNodeConnections;
         private _createNewSocketConnection;
+        private _isUnsupportedExtensionBlock;
         /**
          * Wires an upstream data output into a downstream data input through a runtime multiply block that
          * scales the value by the animation target fps. This converts a KHR animation time (seconds),
@@ -7697,6 +7805,8 @@ declare namespace BABYLON.GLTF2.Loader.Extensions {
          * @param context the serialized flow graph context that stores literal socket values
          * @param upstreamOutput the data output socket providing the time value (in seconds)
          * @param downstreamInput the data input socket that expects the time in frames
+         * @param nodeIndex source node receiving the converted value
+         * @param declarationIndex source declaration used by the receiving node
          */
         private _connectWithSecondsToFramesConversion;
         private _connectFlowGraphNodes;
@@ -7718,6 +7828,125 @@ declare namespace BABYLON.GLTF2.Loader.Extensions {
 
 
 
+}
+declare namespace BABYLON {
+
+
+}
+declare namespace BABYLON.GLTF2.Loader.Extensions {
+        /**
+     * Ratified KHR_interactivity specification baseline used by this importer.
+     */
+    export const KHR_INTERACTIVITY_SPECIFICATION_COMMIT = "f798712c5685bc9223a628140fba707db8889300";
+    /**
+     * Runtime representation of every ratified built-in KHR_interactivity type.
+     */
+    export var gltfTypeToBabylonType: {
+        [key: string]: {
+            length: number;
+            flowGraphType: FlowGraphTypes;
+            elementType: "number" | "boolean" | "string" | "any";
+        };
+    };
+    /**
+     * Classification of a KHR_interactivity declaration.
+     */
+    export type KHRInteractivityDeclarationSupport = "core" | "extension" | "unsupported-extension" | "unknown-core";
+    /**
+     * A structured KHR_interactivity import diagnostic.
+     */
+    export interface IKHRInteractivityDiagnostic {
+        /** JSON pointer identifying the source location. */
+        path: string;
+        /** Human-readable diagnostic text. */
+        message: string;
+        /** Diagnostic severity. */
+        severity: "error" | "warning";
+    }
+    /**
+     * Canonical declaration information retained during import.
+     */
+    export interface IKHRInteractivityDeclarationModel {
+        /** Declaration index in the source graph. */
+        index: number;
+        /** Full operation name, including the defining extension when present. */
+        operation: string;
+        /** Whether Babylon can execute the declaration. */
+        support: KHRInteractivityDeclarationSupport;
+        /** Exact source declaration. */
+        source: BABYLON.GLTF2.IKHRInteractivity_Declaration;
+    }
+    /**
+     * Canonical graph information retained during import.
+     */
+    export interface IKHRInteractivityGraphModel {
+        /** Graph index in the root extension. */
+        index: number;
+        /** Stable source path. */
+        path: string;
+        /** Human-readable graph name. */
+        name: string;
+        /** Exact source graph, including extension and extras payloads. */
+        source: BABYLON.GLTF2.IKHRInteractivity_Graph;
+        /** Executable graph with specification defaults and fallbacks applied. */
+        effectiveSource: BABYLON.GLTF2.IKHRInteractivity_Graph;
+        /** Canonical declarations in source order. */
+        declarations: IKHRInteractivityDeclarationModel[];
+        /** Validation diagnostics for this graph. */
+        diagnostics: IKHRInteractivityDiagnostic[];
+        /** Whether this graph is valid and can be lowered to FlowGraph. */
+        valid: boolean;
+    }
+    /**
+     * Lossless canonical representation of a KHR_interactivity root extension.
+     */
+    export interface IKHRInteractivityDocument {
+        /** Ratified specification revision used for validation. */
+        specificationCommit: string;
+        /** Exact source extension, including unknown extensions and extras. */
+        source: BABYLON.GLTF2.IKHRInteractivity;
+        /** Default graph index, or -1 when the source selection is invalid. */
+        defaultGraphIndex: number;
+        /** Canonical graph models in source order. */
+        graphs: IKHRInteractivityGraphModel[];
+        /** Root-level validation diagnostics. */
+        diagnostics: IKHRInteractivityDiagnostic[];
+    }
+    /**
+     * Creates a detached JSON copy of a KHR_interactivity graph.
+     * @param graph source graph
+     * @returns a lossless JSON copy
+     */
+    export function CloneKHRInteractivityGraph(graph: BABYLON.GLTF2.IKHRInteractivity_Graph): BABYLON.GLTF2.IKHRInteractivity_Graph;
+    /**
+     * Creates the executable graph view with all ratified configuration defaults and fallback rules
+     * applied without modifying the lossless source graph.
+     * @param graph source graph
+     * @param declarations canonical declarations
+     * @param assetNodeCount number of glTF nodes in the containing asset
+     * @returns normalized executable graph
+     */
+    export function CreateEffectiveKHRInteractivityGraph(graph: BABYLON.GLTF2.IKHRInteractivity_Graph, declarations: readonly IKHRInteractivityDeclarationModel[], assetNodeCount?: number): BABYLON.GLTF2.IKHRInteractivity_Graph;
+    /**
+     * Creates and validates a canonical copy of one KHR_interactivity graph.
+     * @param graph source graph
+     * @param index graph index in the root extension
+     * @param supportedExtensions enabled extensions that may provide executable operations
+     * @param assetNodeCount number of nodes in the containing glTF asset
+     * @returns the canonical graph model
+     */
+    export function CreateKHRInteractivityGraphModel(graph: BABYLON.GLTF2.IKHRInteractivity_Graph | null | undefined, index?: number, supportedExtensions?: ReadonlySet<string>, assetNodeCount?: number): IKHRInteractivityGraphModel;
+    /**
+     * Creates an immutable canonical KHR_interactivity document and validates all graph-local references.
+     * @param extension source extension object from the glTF document
+     * @param supportedExtensions enabled extensions that may provide executable operations
+     * @param assetNodeCount number of nodes in the containing glTF asset
+     * @returns the canonical document
+     */
+    export function CreateKHRInteractivityDocument(extension: BABYLON.GLTF2.IKHRInteractivity, supportedExtensions?: ReadonlySet<string>, assetNodeCount?: number): IKHRInteractivityDocument;
+
+
+
 }
 declare namespace BABYLON {
 
@@ -7727,6 +7956,82 @@ declare namespace BABYLON.GLTF2.Loader.Extensions {
     
 
 
+}
+declare namespace BABYLON {
+
+
+}
+declare namespace BABYLON.GLTF2.Loader.Extensions {
+        /**
+     * Socket definition retained for an unsupported extension operation.
+     */
+    export interface IFlowGraphUnsupportedInteractivitySocket {
+        /** Socket name. */
+        name: string;
+        /** FlowGraph runtime type name. */
+        type?: string;
+        /** Exact KHR_interactivity type signature. */
+        signature?: string;
+    }
+    /**
+     * Configuration for an unsupported KHR_interactivity extension operation.
+     */
+    export interface IFlowGraphUnsupportedInteractivityBlockConfiguration extends IFlowGraphBlockConfiguration {
+        /** Full extension operation name. */
+        operation: string;
+        /** Input value sockets declared by the extension. */
+        inputValueSockets: IFlowGraphUnsupportedInteractivitySocket[];
+        /** Output value sockets declared by the extension. */
+        outputValueSockets: IFlowGraphUnsupportedInteractivitySocket[];
+        /** Input flow sockets used by the source graph. */
+        inputFlowSockets: string[];
+        /** Output flow sockets used by the source graph. */
+        outputFlowSockets: string[];
+    }
+    /**
+     * Inspectable runtime no-op for an operation owned by an unsupported glTF extension.
+     */
+    export class FlowGraphUnsupportedInteractivityBlock extends FlowGraphExecutionBlock {
+        config: IFlowGraphUnsupportedInteractivityBlockConfiguration;
+        constructor(config: IFlowGraphUnsupportedInteractivityBlockConfiguration);
+        /** @internal */
+        _execute(_context: FlowGraphContext, _callingSignal: FlowGraphSignalConnection): void;
+        /** @returns the serialized class name */
+        getClassName(): string;
+    }
+
+
+
+}
+declare namespace BABYLON {
+
+
+}
+declare namespace BABYLON.GLTF2.Loader.Extensions {
+        /**
+     * Resolves a runtime object to its owning glTF node reference.
+     * @param context active FlowGraph context
+     * @param value runtime object, usually a picked primitive
+     * @returns the owning node reference or the null reference
+     */
+    export function GetInteractivityObjectReference(context: FlowGraphContext, value: object | undefined): string;
+    /**
+     * Converts a runtime object into the opaque reference used by KHR_interactivity.
+     */
+    export class FlowGraphObjectReferenceBlock extends FlowGraphBlock {
+        /** Runtime object to encode. */
+        readonly object: FlowGraphDataConnection<object | undefined>;
+        /** Opaque KHR_interactivity reference. */
+        readonly value: FlowGraphDataConnection<string>;
+        constructor(config?: IFlowGraphBlockConfiguration);
+        /** @internal */
+        _updateOutputs(context: FlowGraphContext): void;
+        /** @returns the serialized class name */
+        getClassName(): string;
+    }
+
+
+
 }
 declare namespace BABYLON {
 
@@ -7740,7 +8045,7 @@ declare namespace BABYLON.GLTF2.Loader.Extensions {
         /**
          * the glTF object to provide data from
          */
-        glTF: BABYLON.GLTF2.Loader.IGLTF;
+        glTF?: BABYLON.GLTF2.Loader.IGLTF;
     }
     /**
      * a glTF-based FlowGraph block that provides arrays with babylon object, based on the glTF tree
@@ -7757,7 +8062,7 @@ declare namespace BABYLON.GLTF2.Loader.Extensions {
          * Corresponds directly to the glTF nodes array
          */
         readonly nodes: FlowGraphDataConnection<TransformNode[]>;
-        constructor(config: IFlowGraphGLTFDataProviderBlockConfiguration);
+        constructor(config?: IFlowGraphGLTFDataProviderBlockConfiguration);
         getClassName(): string;
     }
 
@@ -7769,11 +8074,71 @@ declare namespace BABYLON {
 
 }
 declare namespace BABYLON.GLTF2.Loader.Extensions {
-        interface IGLTFToFlowGraphMappingObject {
+        /**
+     * Configuration for a KHR event reference output.
+     */
+    export interface IFlowGraphEventReferenceBlockConfiguration extends IFlowGraphBlockConfiguration {
+        /** Stable key shared by equivalent event operations. */
+        eventKey?: string;
+    }
+    /**
+     * Produces the opaque reference associated with a KHR event operation.
+     */
+    export class FlowGraphEventReferenceBlock extends FlowGraphExecutionBlock {
+        config: IFlowGraphEventReferenceBlockConfiguration;
+        private readonly _assetInverse;
+        private readonly _selectionPointValue;
+        private readonly _selectionRayOriginValue;
+        /** Output flow activated after event values are captured. */
+        readonly out: FlowGraphSignalConnection;
+        /** Runtime node associated with the event. */
+        readonly node: FlowGraphDataConnection<object | undefined>;
+        /** Controller index associated with the event. */
+        readonly controllerIndexInput: FlowGraphDataConnection<number>;
+        /** Selection point associated with the event. */
+        readonly selectionPointInput: FlowGraphDataConnection<Vector3>;
+        /** Selection ray origin associated with the event. */
+        readonly selectionRayOriginInput: FlowGraphDataConnection<Vector3>;
+        /** Opaque node reference. */
+        readonly nodeReference: FlowGraphDataConnection<string>;
+        /** Retained controller index. */
+        readonly controllerIndex: FlowGraphDataConnection<number>;
+        /** Retained selection point. */
+        readonly selectionPoint: FlowGraphDataConnection<Vector3>;
+        /** Retained selection ray origin. */
+        readonly selectionRayOrigin: FlowGraphDataConnection<Vector3>;
+        /** Opaque event reference. */
+        readonly value: FlowGraphDataConnection<string>;
+        constructor(config: IFlowGraphEventReferenceBlockConfiguration);
+        /** @internal */
+        _execute(context: FlowGraphContext): void;
+        /** @returns the serialized class name */
+        getClassName(): string;
+    }
+
+
+
+}
+declare namespace BABYLON {
+
+
+}
+declare namespace BABYLON.GLTF2.Loader.Extensions {
+        /**
+     * Describes how one KHR_interactivity configuration or socket property maps to FlowGraph.
+     *
+     * The same contract is used for fixed sockets, wildcard sockets, configuration validation,
+     * defaulting, and multi-block routing during strict graph lowering.
+     */
+    export interface IGLTFToFlowGraphMappingObject {
         /**
          * The name of the property in the FlowGraph block.
          */
         name: string;
+        /**
+         * Whether this socket mapping exists only for pre-ratification compatibility input.
+         */
+        compatibilityOnly?: boolean;
         /**
          * The type of the property in the glTF specs.
          * If not provided will be inferred.
@@ -7806,7 +8171,7 @@ declare namespace BABYLON.GLTF2.Loader.Extensions {
          * This is used if we generate more than one block for a single glTF node.
          * Defaults to the first block in the mapping.
          */
-        toBlock?: FlowGraphBlockNames;
+        toBlock?: FlowGraphBlockNames | string;
         /**
          * Used in configuration values. If defined, this will be the default value, if no value is provided.
          */
@@ -7820,6 +8185,75 @@ declare namespace BABYLON.GLTF2.Loader.Extensions {
          * be fed by a `pointer/get` (e.g. the read-only `maxTime` animation pointer).
          */
         convertConnectedTimeToFrames?: boolean;
+        /**
+         * KHR configuration value type used by canonical validation.
+         */
+        configurationType?: "bool" | "int" | "int[]" | "string";
+        /**
+         * Whether this configuration entry exists only for canonical validation.
+         */
+        validationOnly?: boolean;
+        /**
+         * Whether an operation without a complete default configuration requires this property.
+         */
+        required?: boolean;
+        /**
+         * Graph array referenced by an integer configuration value.
+         */
+        indexSource?: "types" | "variables" | "events" | "nodes" | "assetNodes";
+        /**
+         * Minimum number of values required for an array configuration.
+         */
+        minItems?: number;
+        /**
+         * Whether the configured indices generate required input value sockets.
+         */
+        generatesInputValueSockets?: boolean;
+        /**
+         * Whether integer case values generate required input value sockets.
+         */
+        generatesCaseInputValueSockets?: boolean;
+        /**
+         * Whether this string configuration generates JSON Pointer Template sockets.
+         */
+        pointerTemplate?: boolean;
+        /**
+         * Whether an invalid value falls back to the operation's default configuration.
+         */
+        invalidUsesDefault?: boolean;
+        /**
+         * Allowed KHR type signatures for a type-index configuration.
+         */
+        allowedSignatures?: readonly ("bool" | "float" | "float2" | "float3" | "float4" | "float2x2" | "float3x3" | "float4x4" | "int" | "ref" | "custom")[];
+        /**
+         * Input socket whose effective type determines this output socket type.
+         */
+        typeSourceInput?: string;
+        /** Inclusive minimum for an integer configuration value. */
+        minimum?: number;
+        /** Inclusive maximum for an integer configuration value. */
+        maximum?: number;
+        /**
+         * Whether this configuration value generates numbered input flow sockets.
+         */
+        generatesInputFlowSockets?: boolean;
+        /**
+         * Whether this configuration array generates output flow sockets.
+         */
+        generatesOutputFlowSockets?: boolean;
+        /**
+         * Properties in the same group fall back to their defaults together when any member is
+         * missing or invalid.
+         */
+        configurationGroup?: string;
+        /**
+         * Whether duplicate array values are removed from the effective configuration.
+         */
+        uniqueValues?: boolean;
+        /**
+         * Whether a string configuration value is a `debug/log` message template.
+         */
+        debugLogTemplate?: boolean;
     }
     /**
      * Description of how a KHR_interactivity declaration (op such as
@@ -7834,6 +8268,13 @@ declare namespace BABYLON.GLTF2.Loader.Extensions {
          * When adding blocks defined in this module use the KHR_interactivity prefix.
          */
         blocks: (FlowGraphBlockNames | string)[];
+        /**
+         * Exact value socket contract for an operation supplied by another extension.
+         */
+        declarationSchema?: {
+            inputValueSockets: Record<string, "bool" | "float" | "float2" | "float3" | "float4" | "float2x2" | "float3x3" | "float4x4" | "int" | "ref" | "custom">;
+            outputValueSockets: Record<string, "bool" | "float" | "float2" | "float3" | "float4" | "float2x2" | "float3x3" | "float4x4" | "int" | "ref" | "custom">;
+        };
         /**
          * The inputs of the glTF node mapped to the FlowGraph block.
          */
@@ -7942,6 +8383,12 @@ declare namespace BABYLON.GLTF2.Loader.Extensions {
     }
     export function getMappingForFullOperationName(fullOperationName: string): IGLTFToFlowGraphMapping | undefined;
     export function getMappingForDeclaration(declaration: BABYLON.GLTF2.IKHRInteractivity_Declaration, returnNoOpIfNotAvailable?: boolean): IGLTFToFlowGraphMapping | undefined;
+    /**
+     * Creates the typed no-op mapping required for an unsupported extension declaration.
+     * @param declaration unsupported extension declaration
+     * @returns a mapping that preserves the declared value sockets
+     */
+    export function getNoOpMappingForDeclaration(declaration: BABYLON.GLTF2.IKHRInteractivity_Declaration): IGLTFToFlowGraphMapping;
     /**
      * This function will add new mapping to glTF interactivity.
      * Other extensions can define new types of blocks, this is the way to let interactivity know how to parse them.
@@ -7950,6 +8397,22 @@ declare namespace BABYLON.GLTF2.Loader.Extensions {
      * @param mapping The mapping object. See documentation or examples below.
      */
     export function addNewInteractivityFlowGraphMapping(key: string, extension: string, mapping: IGLTFToFlowGraphMapping): void;
+    /**
+     * Result of parsing a ratified `debug/log` message template.
+     */
+    export interface IDebugLogTemplateParseResult {
+        /** Whether all literal braces are doubled and every parameter is well formed. */
+        valid: boolean;
+        /** Unique parameter socket ids in first-occurrence order. */
+        sockets: string[];
+    }
+    /**
+     * Parses a ratified `debug/log` message template.
+     * Literal braces must be doubled; non-empty text inside a single brace pair defines a socket id.
+     * @param message message template to parse
+     * @returns template validity and its exact dynamic socket ids
+     */
+    export function ParseDebugLogTemplate(message: string): IDebugLogTemplateParseResult;
     export function getAllSupportedNativeNodeTypes(): string[];
     /**
      *
@@ -10322,17 +10785,20 @@ declare namespace BABYLON {
         /** Number of times a failed file download is retried before giving up. PlayCanvas default `2`. */
         maxDownloadRetries?: number;
         /**
-         * GPU memory budget (in megabytes) for resident splats. When set (and smaller than the full dataset),
-         * LOD files are streamed through a fixed-size work buffer and unreferenced files are evicted to stay
-         * within budget, allowing datasets larger than a single full-dataset buffer. Converted to a splat count
-         * using the per-splat cost (core data plus any baked SH and rotation/scale textures). Combined with
-         * {@link maxResidentSplats} by taking the smaller of the two.
+         * Initial GPU/CPU memory estimate (in megabytes) for resident splats. It is converted to a splat count
+         * using the per-splat cost (core data plus any baked SH and rotation/scale textures), combined with
+         * {@link maxResidentSplats} by taking the smaller limit, then raised when necessary to fit the complete
+         * coarse layer. The work buffer has a fixed lifetime capacity; construct a new stream to use another limit.
+         * Finite non-positive values leave this limit unset; non-finite values are rejected.
          */
         memoryBudgetMb?: number;
         /**
-         * Maximum number of splats kept resident in the work buffer. When set (and smaller than the full
-         * dataset), enables eviction-based streaming (see {@link memoryBudgetMb}). Default unset = size the work
-         * buffer for the whole dataset (no eviction).
+         * Initial maximum number of splats kept resident in the fixed-size work buffer. It is raised when necessary
+         * to fit the complete coarse layer. When unset and the complete source size is known, streams retain the complete
+         * source. Streams that defer finer metadata use a bounded device-tiered default with coarse-derived refinement
+         * headroom.
+         * Finite non-positive values leave this limit unset; non-finite or unsafe positive counts are rejected.
+         * Positive fractional counts are floored to at least one splat before applying the coarse minimum.
          */
         maxResidentSplats?: number;
         /**
@@ -10362,10 +10828,10 @@ declare namespace BABYLON {
         /**
          * When true, higher-order spherical-harmonics carried by the SOG files (`shN`) are GPU-decoded into baked
          * packed-u32 SH textures so the streamed splats render with view-dependent lighting (matching the non-stream
-         * `.spz`/`.sog` path) instead of flat DC-only color. The SH degree is the max `shN.bands` across the streamed
-         * files (lower-band files neutral-fill). No effect when the files carry no `shN`. Defaults to `true`, matching
-         * the non-stream path's always-decode-if-present behavior; set to `false` to force flat DC-only color even
-         * when the data carries `shN` (e.g. to save the decode cost/texture memory).
+         * `.spz`/`.sog` path) instead of flat DC-only color. Streams with complete initial metadata use the maximum
+         * source SH degree. Streams that defer finer metadata reserve the supported degree-4 layout before it is known,
+         * even if the files ultimately carry no `shN`; lower-degree files neutral-fill the unused bands.
+         * Defaults to `true`; set to `false` to force flat DC-only color and avoid the SH decode cost/texture memory.
          */
         decodeSh?: boolean;
         /**
@@ -10410,6 +10876,7 @@ declare namespace BABYLON {
         private _hostBudgetAllocation;
         private _frustumCulling;
         private readonly _frustumPlanes;
+        private readonly _cullCameraViewProj;
         private readonly _cullViewProj;
         private readonly _frustumScratch;
         private _workBuffer;
@@ -10423,6 +10890,7 @@ declare namespace BABYLON {
         private _residency;
         private readonly _fileCounts;
         private readonly _fileMeta;
+        private readonly _baseFileIds;
         private readonly _decodedFiles;
         private readonly _loadingFiles;
         private readonly _decodeQueue;
@@ -10430,6 +10898,7 @@ declare namespace BABYLON {
         private readonly _cancelledDecodes;
         private _evictionEnabled;
         private _residentBudget;
+        private _minimumResidentSplats;
         private _maxResidentSplats;
         private _memoryBudgetMb;
         private _evictionCooldownFrames;
@@ -10441,6 +10910,7 @@ declare namespace BABYLON {
         private _environmentFiles;
         private _lodObserver;
         private _baseLayerReady;
+        private _metadataReady;
         private _framesSinceLodUpdate;
         private readonly _lastLodCamPositions;
         private _lastLodSignature;
@@ -10563,10 +11033,19 @@ declare namespace BABYLON {
         /**
          * 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.
+         * taking the smaller positive limit and raising it to {@link minimumResidentSplats}. With neither limit set,
+         * the complete source size is retained when known; otherwise a bounded device-tiered default is used.
+         * The fixed capacity is capped at the device texture limit. `0` means initial capacity has not been resolved.
          * @experimental
          */
         get residentSplatBudget(): number;
+        /**
+         * Minimum fixed work-buffer capacity required for the complete coarse representation: one invisible padding
+         * splat, the included environment, and every unique whole coarse source file. It is `0` until the required
+         * coarse metadata has resolved. Initial residency options below this value are raised to it.
+         * @experimental
+         */
+        get minimumResidentSplats(): 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.
@@ -10641,14 +11120,14 @@ declare namespace BABYLON {
         set debugLodSource(value: GaussianSplattingStreamDebugLodSource);
         dispose(doNotRecurse?: boolean): void;
         /**
-         * Disposes this stream (which tombstones its region) and then compacts the host once to actually reclaim the
-         * reserved rows. Used on a definitive load failure / empty result — a discrete, one-off reclaim, versus a bare
+         * Disposes this stream and, when hosted, compacts the host once to reclaim its tombstoned region's reserved
+         * rows. Used on a definitive load failure / empty result — a discrete, one-off reclaim, versus a bare
          * {@link dispose} that only tombstones so tearing down several parts doesn't rebuild the atlas repeatedly.
          */
         private _disposeAndReclaim;
         /**
          * The world matrix that actually places this stream's splats, used to map the camera into the space the
-         * node bounds live in (for LOD distance) and to build per-node world AABBs (for frustum culling). Standalone:
+         * node bounds live in (for LOD distance) and to build camera-local frusta (for frustum culling). Standalone:
          * this controller mesh carries the transform. Hosted: this controller is a hidden, unplaced node — the splats
          * are placed by the reserved part's proxy (SOG up-axis basis composed with the host's placement), so LOD and
          * culling MUST use the proxy's world matrix or they compute distances/frustum tests in the wrong space
@@ -10716,9 +11195,9 @@ declare namespace BABYLON {
          */
         private _collectLodEntries;
         /**
-         * Streams the scene: learns every source file's splat count, allocates one unified GPU work buffer
-         * sized for all LOD files, decodes the environment and the coarsest LOD of every node as a permanent
-         * base layer, then installs the per-frame loop that streams finer LODs on demand.
+         * Streams the scene. Large streams fetch only required coarse metadata before allocating and decoding the
+         * complete coarse layer; finer metadata starts afterwards so it cannot occupy the download queue ahead of
+         * visible geometry. Small streams and streams containing only coarse files retain an exact all-file capacity upper bound.
          */
         private _streamAllAsync;
         /**
@@ -10731,26 +11210,47 @@ declare namespace BABYLON {
          */
         private _waitForCanBackupAsync;
         /**
-         * Resolves the resident-splat budget from the raw options, sizing a memory (MB) budget with the actual per-splat
-         * GPU+CPU cost — core data plus the baked SH textures and rotation/scale textures when enabled — so SH/rotation
-         * assets don't silently consume up to double the configured budget. Requires the SH degree (from the metadata
-         * pre-pass) to be known. The smaller of the splat-count and memory budgets wins.
+         * Resolves the fixed initial work-buffer capacity. Explicit count/MB limits are combined by taking the smaller
+         * and then raised to the complete coarse minimum. Without an explicit limit, a known complete source retains
+         * legacy full residency. When finer metadata is deferred and the complete size is unknown, the device-tiered
+         * memory estimate is given at least one largest-coarse-file of headroom so one replacement file can refine
+         * while all coarse fallback files remain pinned.
+         * @param fullCapacity exact complete source capacity, or null when unavailable
+         * @param largestBaseFileCount largest whole coarse source file, used as modest replacement headroom
+         * @returns the fixed initial work-buffer capacity
          */
         private _resolveResidentBudget;
+        /**
+         * Returns the estimated combined GPU/CPU bytes occupied by one resident splat.
+         * @returns estimated bytes per resident splat
+         */
+        private _bytesPerResidentSplat;
         /**
          * Collects the unique set of source file indices referenced by any LOD of any leaf, sorted ascending.
          * @returns sorted unique file indices
          */
         private _collectAllFileIds;
+        /**
+         * Collects unique whole source files required by the coarsest entry of every valid leaf.
+         * @returns sorted unique coarse file indices
+         */
+        private _collectBaseFileIds;
+        /**
+         * Resolves the immutable minimum initial capacity from padding, environment, and unique whole coarse files.
+         * @param baseFileIds unique coarse source file indices
+         * @param environmentCount included environment splat count
+         */
+        private _resolveMinimumResidentSplats;
         /**
          * 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.
+         * Fetches the environment bundle and the supplied referenced files' metadata to learn splat counts, caching
+         * each file's parsed metadata for the later on-demand decode. File metadata fetches run in parallel.
          * @param fileIds file indices to fetch metadata for
+         * @param includeEnvironment whether to fetch the optional environment bundle in this phase
          * @returns the environment splat count (0 when there is no environment)
          */
         private _gatherCountsAsync;
@@ -10818,6 +11318,7 @@ declare namespace BABYLON {
          * Concurrent or repeat requests for the same file are ignored. If the file is cancelled mid-flight
          * (because every node that wanted it retargeted), the decode bails cooperatively at the next checkpoint.
          * @param fileId file index to decode
+         * @returns whether the file was decoded and published successfully
          */
         private _decodeFileAsync;
         /**
@@ -10982,6 +11483,22 @@ declare namespace BABYLON {
          * @returns whether any node's in-frustum state changed
          */
         private _updateNodeFrustum;
+        /**
+         * Normalizes an initial residency option, preserving finite non-positive values as an unset limit.
+         * @param value option value
+         * @param name option name used in errors
+         * @param integer whether the normalized value must be an integer splat count
+         * @returns normalized value
+         */
+        private static _NormalizeResidentLimit;
+        /**
+         * Adds trusted non-negative integer counts without allowing unsafe capacity arithmetic.
+         * @param left first count
+         * @param right second count
+         * @param label capacity name used in errors
+         * @returns the safe integer sum
+         */
+        private static _SafeAddCounts;
         /**
          * Reads the splat count from SOG metadata, coerced to a finite non-negative integer (metadata is untrusted, so
          * `count` / `shape[0]` may be a string or malformed — a non-numeric value must not leak into count arithmetic).