@babylonjs/loaders 9.26.2 → 9.27.0

package/glTF/2.0/Extensions/KHR_interactivity/interactivityGraphModel.d.ts

@@ -1,4 +1,4 @@
-import { type IKHRInteractivity, type IKHRInteractivity_Declaration, type IKHRInteractivity_Graph } from "babylonjs-gltf2interface";
+import { type IKHRInteractivity, type IKHRInteractivity_Declaration, type IKHRInteractivity_Graph, type IKHRInteractivity_OutputSocketReference, type IKHRInteractivity_Variable } from "babylonjs-gltf2interface";
 import { FlowGraphTypes } from "@babylonjs/core/FlowGraph/flowGraphRichTypes.js";
 /**
  * Ratified KHR_interactivity specification baseline used by this importer.
@@ -29,6 +29,87 @@ export interface IKHRInteractivityDiagnostic {
     /** Diagnostic severity. */
     severity: "error" | "warning";
 }
+/**
+ * Stable source identity retained on every FlowGraph block lowered from a KHR_interactivity node.
+ */
+export interface IKHRInteractivityBlockProvenance {
+    /** Source graph index. */
+    graphIndex: number;
+    /** Source node index. */
+    nodeIndex: number;
+    /** Source declaration index. */
+    declarationIndex: number;
+    /** Full operation name. */
+    operation: string;
+    /** Role of this block in a one-to-many mapping. Negative roles identify generated helper blocks. */
+    role: number;
+    /** Stable JSON pointer to the source node. */
+    sourcePath: string;
+    /** Original and lowered configuration values used for safe inverse transforms. */
+    configuration?: Record<string, IKHRInteractivityConfigurationProvenance>;
+    /** Importer-generated primitive configuration that must remain unchanged for inverse export. */
+    generatedConfiguration?: Record<string, unknown>;
+    /** Runtime fingerprints for generated configuration that changes representation while parsing. */
+    generatedConfigurationRuntime?: Record<string, IKHRInteractivityInputDefaultProvenance>;
+    /** Importer-generated unconnected input defaults that have no authored KHR socket representation. */
+    generatedInputDefaults?: Record<string, IKHRInteractivityInputDefaultProvenance>;
+}
+/**
+ * Import-time value retained for an unconnected FlowGraph input that is not represented by an authored KHR socket.
+ */
+export interface IKHRInteractivityInputDefaultProvenance {
+    /** Type-tagged JSON-stable fingerprint of the normalized runtime input value. */
+    runtimeValueFingerprint?: string;
+    /** Whether the import-time value could not be fingerprinted safely. */
+    unrepresentable?: true;
+}
+/**
+ * Provenance for a transformed KHR configuration value.
+ */
+export interface IKHRInteractivityConfigurationProvenance {
+    /** Exact source configuration array. */
+    sourceValue?: unknown[];
+    /** Lowered FlowGraph configuration value immediately after import. */
+    runtimeValue?: unknown;
+}
+/** @internal */
+export declare function _NormalizeKHRInteractivityRuntimeValue(value: unknown): unknown[] | undefined;
+/** @internal */
+export declare function _CreateKHRInteractivityRuntimeValueSnapshot(value: unknown): IKHRInteractivityInputDefaultProvenance;
+/**
+ * Stable source identity retained on a FlowGraph connection lowered from a KHR_interactivity socket.
+ */
+export interface IKHRInteractivitySocketProvenance extends IKHRInteractivityBlockProvenance {
+    /** Socket category. */
+    kind: "value" | "flow";
+    /** Whether the socket is consumed by or produced from the logical KHR node. */
+    direction: "input" | "output";
+    /** Exact source KHR socket identifier. */
+    socket: string;
+    /** Exact canonical source value, when this is an input value socket. */
+    sourceValue?: IKHRInteractivity_Variable | IKHRInteractivity_OutputSocketReference;
+    /** Lowered inline runtime value immediately after import. */
+    runtimeValue?: unknown[];
+    /** Type-tagged runtime fingerprint used to distinguish parsing precision changes from edits. */
+    runtimeValueSnapshot?: IKHRInteractivityInputDefaultProvenance;
+}
+/**
+ * Canonical source retained on a FlowGraph lowered from KHR_interactivity.
+ */
+export interface IKHRInteractivityGraphProvenance {
+    /** Source graph index. */
+    graphIndex: number;
+    /** Ratified specification revision used by the importer. */
+    specificationCommit: string;
+    /** Detached canonical source graph. */
+    source: IKHRInteractivity_Graph;
+    /** Explicit editor-authored variable defaults keyed by canonical variable index. */
+    authoredVariableValues?: Record<number, unknown[]>;
+    /** Explicit editor-authored FlowGraph variable types keyed by canonical variable index. */
+    authoredVariableTypes?: Record<number, string>;
+    /** True when variables were explicitly added, renamed, or deleted in the editor. */
+    authoredVariableStructureChanged?: boolean;
+}
 /**
  * Canonical declaration information retained during import.
  */

package/glTF/2.0/Extensions/KHR_interactivity/interactivityGraphModel.js

@@ -20,6 +20,95 @@ export const gltfTypeToBabylonType = {
     ref: { length: 1, flowGraphType: "string" /* FlowGraphTypes.String */, elementType: "string" },
     custom: { length: 0, flowGraphType: "any" /* FlowGraphTypes.Any */, elementType: "any" },
 };
+/** @internal */
+export function _NormalizeKHRInteractivityRuntimeValue(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value !== null && typeof value === "object") {
+        const asArray = value.asArray;
+        if (typeof asArray === "function") {
+            return Array.from(asArray.call(value));
+        }
+        if ("value" in value && typeof value.value !== "object") {
+            return [value.value];
+        }
+    }
+    return Array.isArray(value) ? value.slice() : [value];
+}
+function _EncodeRuntimeValueSnapshot(value, ancestors) {
+    if (value === undefined) {
+        return ["undefined"];
+    }
+    if (value === null) {
+        return ["null"];
+    }
+    switch (typeof value) {
+        case "boolean":
+            return ["boolean", value];
+        case "number":
+            return ["number", Number.isNaN(value) ? "NaN" : value === Infinity ? "Infinity" : value === -Infinity ? "-Infinity" : Object.is(value, -0) ? "-0" : value];
+        case "string":
+            return ["string", value];
+        case "object": {
+            if (Object.getOwnPropertySymbols(value).length > 0) {
+                return undefined;
+            }
+            if (Array.isArray(value)) {
+                const hasNonIndexProperty = Object.getOwnPropertyNames(value).some((key) => key !== "length" && (!/^(0|[1-9]\d*)$/.test(key) || Number(key) >= value.length || !("value" in Object.getOwnPropertyDescriptor(value, key))));
+                if (hasNonIndexProperty) {
+                    return undefined;
+                }
+            }
+            else {
+                const prototype = Object.getPrototypeOf(value);
+                if (prototype !== Object.prototype && prototype !== null) {
+                    return undefined;
+                }
+                const hasNonJsonProperty = Object.getOwnPropertyNames(value).some((key) => !Object.prototype.propertyIsEnumerable.call(value, key) || !("value" in Object.getOwnPropertyDescriptor(value, key)));
+                if (hasNonJsonProperty) {
+                    return undefined;
+                }
+            }
+            if (ancestors.has(value)) {
+                return undefined;
+            }
+            ancestors.add(value);
+            let encoded;
+            if (Array.isArray(value)) {
+                const entries = value.map((entry) => _EncodeRuntimeValueSnapshot(entry, ancestors));
+                encoded = entries.some((entry) => entry === undefined) ? undefined : ["array", entries];
+            }
+            else {
+                const entries = [];
+                let unrepresentable = false;
+                for (const key of Object.keys(value).sort()) {
+                    const entry = _EncodeRuntimeValueSnapshot(value[key], ancestors);
+                    if (entry === undefined) {
+                        unrepresentable = true;
+                        break;
+                    }
+                    entries.push([key, entry]);
+                }
+                encoded = unrepresentable ? undefined : ["object", entries];
+            }
+            ancestors.delete(value);
+            return encoded;
+        }
+        default:
+            return undefined;
+    }
+}
+/** @internal */
+export function _CreateKHRInteractivityRuntimeValueSnapshot(value) {
+    try {
+        const encoded = _EncodeRuntimeValueSnapshot(Array.isArray(value) ? value : _NormalizeKHRInteractivityRuntimeValue(value), new Set());
+        return encoded === undefined ? { unrepresentable: true } : { runtimeValueFingerprint: JSON.stringify(encoded) };
+    }
+    catch {
+        return { unrepresentable: true };
+    }
+}
 function _cloneJson(value) {
     if (Array.isArray(value)) {
         return value.map((entry) => _cloneJson(entry));
@@ -49,6 +138,9 @@ export function CloneKHRInteractivityGraph(graph) {
 function _isValidIndex(value, length) {
     return typeof value === "number" && Number.isInteger(value) && value >= 0 && value < length;
 }
+function _isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
 function _addError(diagnostics, path, message) {
     diagnostics.push({ path, message, severity: "error" });
 }
@@ -88,6 +180,10 @@ function _validateValue(value, graph, diagnostics, path) {
     if (value.value === undefined) {
         return;
     }
+    if (!Array.isArray(value.value)) {
+        _addError(diagnostics, `${path}/value`, "Value must be an array when present.");
+        return;
+    }
     const type = graph.types[value.type];
     const runtimeType = gltfTypeToBabylonType[type.signature];
     if (runtimeType && type.signature !== "custom" && value.value.length !== runtimeType.length) {
@@ -144,12 +240,12 @@ function _isCompatibleExtensionDeclaration(declaration, graph, schema) {
         if (actualKeys.length !== expectedKeys.length || actualKeys.some((key, index) => key !== expectedKeys[index])) {
             return false;
         }
-        return actualKeys.every((key) => graph.types?.[actual[key].type]?.signature === expected[key]);
+        return actualKeys.every((key) => _isRecord(actual[key]) && graph.types?.[actual[key].type]?.signature === expected[key]);
     };
     return matches(declaration.inputValueSockets, schema.inputValueSockets) && matches(declaration.outputValueSockets, schema.outputValueSockets);
 }
 function _validateConfigurationValue(value, type) {
-    if (!value) {
+    if (!Array.isArray(value)) {
         return false;
     }
     const isInt = (entry) => typeof entry === "number" && Number.isInteger(entry) && entry >= -2147483648 && entry <= 2147483647;
@@ -208,30 +304,14 @@ function _isEffectiveConfigurationValue(configuration, property, graph, assetNod
             return false;
         }
     }
+    if (property.allowedValues && configuration.value.some((value) => !property.allowedValues.includes(value))) {
+        return false;
+    }
     if (property.debugLogTemplate && !ParseDebugLogTemplate(configuration.value[0]).valid) {
         return false;
     }
     return true;
 }
-function _getAllowedDynamicFlowOutputSockets(node, mapping, graph, assetNodeCount) {
-    for (const [key, property] of Object.entries(mapping.configuration ?? {})) {
-        if (!property.generatesOutputFlowSockets) {
-            continue;
-        }
-        const configured = node.configuration?.[key];
-        const values = _isEffectiveConfigurationValue(configured, property, graph, assetNodeCount) ? configured.value : property.defaultValue;
-        return new Set(Array.isArray(values) ? values.map(String) : []);
-    }
-    return undefined;
-}
-function _matchesFlowOutputSocket(mapping, socket, allowedDynamicSockets) {
-    const flowMappings = mapping.outputs?.flows;
-    if (flowMappings && Object.prototype.hasOwnProperty.call(flowMappings, socket)) {
-        return true;
-    }
-    const hasWildcard = Object.keys(flowMappings ?? {}).some((name) => name.startsWith("[") && name.endsWith("]"));
-    return !hasWildcard || !allowedDynamicSockets || allowedDynamicSockets.has(socket);
-}
 /**
  * Creates the executable graph view with all ratified configuration defaults and fallback rules
  * applied without modifying the lossless source graph.
@@ -313,7 +393,11 @@ function _resolveOutputTypeIndex(nodeIndex, socket, graph, declarations, visited
     if (declaredType !== undefined) {
         return declaredType;
     }
-    const booleanType = () => graph.types?.findIndex((type) => type.signature === "bool");
+    const findTypeIndex = (signature) => {
+        const index = graph.types?.findIndex((type) => type.signature === signature) ?? -1;
+        return index >= 0 ? index : undefined;
+    };
+    const booleanType = () => findTypeIndex("bool");
     if (socket === "isValid") {
         return booleanType();
     }
@@ -335,14 +419,14 @@ function _resolveOutputTypeIndex(nodeIndex, socket, graph, declarations, visited
     }
     const fixedSignature = _getFixedOutputSignature(declaration.operation, socket);
     if (fixedSignature) {
-        return graph.types?.findIndex((type) => type.signature === fixedSignature);
+        return findTypeIndex(String(fixedSignature));
     }
     const mapping = getMappingForDeclaration(declaration.source, false);
     const outputMapping = mapping?.outputs?.values?.[socket];
     const mappedType = outputMapping?.gltfType;
     const signature = mappedType === "number" ? "float" : mappedType === "boolean" ? "bool" : mappedType;
     if (signature && signature in gltfTypeToBabylonType) {
-        return graph.types?.findIndex((type) => type.signature === signature);
+        return findTypeIndex(signature);
     }
     const typeSource = outputMapping?.typeSourceInput ? sourceNode.values?.[outputMapping.typeSourceInput] : undefined;
     return typeSource ? _resolveValueTypeIndex(typeSource, graph, declarations, visited) : undefined;
@@ -414,7 +498,14 @@ function _validateNode(node, nodeIndex, graph, declarations, diagnostics, graphP
         }
     };
     for (const [key, configuration] of Object.entries(node.configuration ?? {})) {
-        if (configuration.value && configuration.value.length === 0) {
+        if (!_isRecord(configuration)) {
+            _addError(diagnostics, `${path}/configuration/${key}`, `Configuration "${key}" must be an object.`);
+            continue;
+        }
+        if (configuration.value !== undefined && !Array.isArray(configuration.value)) {
+            _addError(diagnostics, `${path}/configuration/${key}/value`, "Configuration value must be an array when present.");
+        }
+        else if (configuration.value && configuration.value.length === 0) {
             _addError(diagnostics, `${path}/configuration/${key}/value`, "Configuration value arrays must contain at least one item when present.");
         }
     }
@@ -445,6 +536,9 @@ function _validateNode(node, nodeIndex, graph, declarations, diagnostics, graphP
                 reportConfigurationIssue(property, `${path}/configuration/${key}/value/0`, `Type "${String(signature)}" is not supported by this operation.`);
             }
         }
+        if (isConfigurationValid && configuration.value && property.allowedValues && configuration.value.some((value) => !property.allowedValues.includes(value))) {
+            reportConfigurationIssue(property, `${path}/configuration/${key}/value`, `Configuration "${key}" contains an unsupported value.`);
+        }
         if (isConfigurationValid && configuration.value && property.debugLogTemplate && !ParseDebugLogTemplate(configuration.value[0]).valid) {
             reportConfigurationIssue(property, `${path}/configuration/${key}/value/0`, `Configuration "${key}" is not a valid debug message template.`);
         }
@@ -549,6 +643,10 @@ function _validateNode(node, nodeIndex, graph, declarations, diagnostics, graphP
         }
     }
     for (const [key, value] of Object.entries(node.values ?? {})) {
+        if (!_isRecord(value)) {
+            _addError(diagnostics, `${path}/values/${key}`, `Input value socket "${key}" must be an object.`);
+            continue;
+        }
         if (declarationModel.support === "unsupported-extension" && !declarationModel.source.inputValueSockets?.[key]) {
             _addError(diagnostics, `${path}/values/${key}`, `Input value socket "${key}" is not defined by operation "${declarationModel.operation}".`);
         }
@@ -579,8 +677,28 @@ function _validateNode(node, nodeIndex, graph, declarations, diagnostics, graphP
                 }
                 const declaredOutputType = sourceDeclaration.source.outputValueSockets?.[sourceSocket]?.type;
                 const effectiveOutputType = declaredOutputType ?? _resolveOutputTypeIndex(value.node, sourceSocket, graph, declarations);
-                if (value.type !== undefined && effectiveOutputType !== undefined && value.type !== effectiveOutputType) {
-                    _addError(diagnostics, `${path}/values/${key}/type`, `Type assertion does not match output socket "${sourceSocket}".`);
+                if (value.type !== undefined) {
+                    const mappedOutputs = sourceMapping?.outputs?.values;
+                    const mappedOutput = mappedOutputs && Object.prototype.hasOwnProperty.call(mappedOutputs, sourceSocket) ? mappedOutputs[sourceSocket] : undefined;
+                    const mappedType = mappedOutput?.gltfType;
+                    const mappedOutputSignature = mappedType === "number"
+                        ? "float"
+                        : mappedType === "boolean"
+                            ? "bool"
+                            : mappedType === "vector2"
+                                ? "float2"
+                                : mappedType === "vector3"
+                                    ? "float3"
+                                    : mappedType === "vector4"
+                                        ? "float4"
+                                        : mappedType;
+                    const fixedOutputSignature = _getFixedOutputSignature(sourceDeclaration.operation, sourceSocket) ??
+                        (mappedOutputSignature && Object.prototype.hasOwnProperty.call(gltfTypeToBabylonType, mappedOutputSignature) ? mappedOutputSignature : undefined);
+                    const assertedSignature = graph.types?.[value.type]?.signature;
+                    if ((fixedOutputSignature !== undefined && assertedSignature !== fixedOutputSignature) ||
+                        (fixedOutputSignature === undefined && effectiveOutputType !== undefined && value.type !== effectiveOutputType)) {
+                        _addError(diagnostics, `${path}/values/${key}/type`, `Type assertion does not match output socket "${sourceSocket}".`);
+                    }
                 }
             }
         }
@@ -589,9 +707,9 @@ function _validateNode(node, nodeIndex, graph, declarations, diagnostics, graphP
         }
     }
     for (const [key, flow] of Object.entries(node.flows ?? {})) {
-        const allowedDynamicSockets = _getAllowedDynamicFlowOutputSockets(node, mapping, graph, assetNodeCount);
-        if (!_matchesFlowOutputSocket(mapping, key, allowedDynamicSockets)) {
-            _addError(diagnostics, `${path}/flows/${key}`, `Output flow socket "${key}" is not defined by operation "${declarationModel.operation}".`);
+        if (!_isRecord(flow)) {
+            _addError(diagnostics, `${path}/flows/${key}`, `Output flow socket "${key}" must be an object.`);
+            continue;
         }
         if (!_isValidIndex(flow.node, graph.nodes?.length ?? 0)) {
             _addError(diagnostics, `${path}/flows/${key}/node`, `Node index ${String(flow.node)} is out of range.`);
@@ -647,14 +765,23 @@ export function CreateKHRInteractivityGraphModel(graph, index = 0, supportedExte
         }
     }
     for (let eventIndex = 0; eventIndex < (graph.events?.length ?? 0); eventIndex++) {
-        if (graph.events[eventIndex].values && Object.keys(graph.events[eventIndex].values).length === 0) {
+        const event = graph.events[eventIndex];
+        if (event.values !== undefined && !_isRecord(event.values)) {
+            _addError(diagnostics, `${path}/events/${eventIndex}/values`, '"values" must be an object when present.');
+            event.values = undefined;
+        }
+        else if (event.values && Object.keys(event.values).length === 0) {
             _addError(diagnostics, `${path}/events/${eventIndex}/values`, '"values" must contain at least one property when present.');
         }
     }
     for (let declarationIndex = 0; declarationIndex < (graph.declarations?.length ?? 0); declarationIndex++) {
         const declaration = graph.declarations[declarationIndex];
         for (const key of ["inputValueSockets", "outputValueSockets"]) {
-            if (declaration[key] && Object.keys(declaration[key]).length === 0) {
+            if (declaration[key] !== undefined && !_isRecord(declaration[key])) {
+                _addError(diagnostics, `${path}/declarations/${declarationIndex}/${key}`, `"${key}" must be an object when present.`);
+                declaration[key] = undefined;
+            }
+            else if (declaration[key] && Object.keys(declaration[key]).length === 0) {
                 _addError(diagnostics, `${path}/declarations/${declarationIndex}/${key}`, `"${key}" must contain at least one property when present.`);
             }
         }
@@ -662,7 +789,11 @@ export function CreateKHRInteractivityGraphModel(graph, index = 0, supportedExte
     for (let nodeIndex = 0; nodeIndex < (graph.nodes?.length ?? 0); nodeIndex++) {
         const node = graph.nodes[nodeIndex];
         for (const key of ["configuration", "values", "flows"]) {
-            if (node[key] && Object.keys(node[key]).length === 0) {
+            if (node[key] !== undefined && !_isRecord(node[key])) {
+                _addError(diagnostics, `${path}/nodes/${nodeIndex}/${key}`, `"${key}" must be an object when present.`);
+                node[key] = undefined;
+            }
+            else if (node[key] && Object.keys(node[key]).length === 0) {
                 _addError(diagnostics, `${path}/nodes/${nodeIndex}/${key}`, `"${key}" must contain at least one property when present.`);
             }
         }
@@ -671,7 +802,10 @@ export function CreateKHRInteractivityGraphModel(graph, index = 0, supportedExte
     const declarations = (graph.declarations ?? []).map((declaration, declarationIndex) => {
         const inputSockets = Object.keys(declaration.inputValueSockets ?? {})
             .sort()
-            .map((key) => `${JSON.stringify(key)}:${declaration.inputValueSockets[key].type}`)
+            .map((key) => {
+            const definition = declaration.inputValueSockets[key];
+            return `${JSON.stringify(key)}:${_isRecord(definition) ? String(definition.type) : "invalid"}`;
+        })
             .join(",");
         const declarationKey = `${JSON.stringify(declaration.op)}:${JSON.stringify(declaration.extension ?? "")}:${inputSockets}`;
         if (declarationKeys.has(declarationKey)) {
@@ -686,9 +820,17 @@ export function CreateKHRInteractivityGraphModel(graph, index = 0, supportedExte
             _addError(diagnostics, `${path}/declarations/${declarationIndex}`, "Core operation declarations cannot define dynamic value sockets.");
         }
         for (const [socket, definition] of Object.entries(declaration.inputValueSockets ?? {})) {
+            if (!_isRecord(definition)) {
+                _addError(diagnostics, `${path}/declarations/${declarationIndex}/inputValueSockets/${socket}`, `Input value socket "${socket}" must be an object.`);
+                continue;
+            }
             _validateTypeIndex(definition.type, graph, diagnostics, `${path}/declarations/${declarationIndex}/inputValueSockets/${socket}/type`);
         }
         for (const [socket, definition] of Object.entries(declaration.outputValueSockets ?? {})) {
+            if (!_isRecord(definition)) {
+                _addError(diagnostics, `${path}/declarations/${declarationIndex}/outputValueSockets/${socket}`, `Output value socket "${socket}" must be an object.`);
+                continue;
+            }
             _validateTypeIndex(definition.type, graph, diagnostics, `${path}/declarations/${declarationIndex}/outputValueSockets/${socket}/type`);
         }
         return {
@@ -721,6 +863,10 @@ export function CreateKHRInteractivityGraphModel(graph, index = 0, supportedExte
             _addError(diagnostics, `${path}/events/${eventIndex}/values/event`, 'Custom event value socket id "event" is reserved.');
         }
         for (const [socket, value] of Object.entries(graph.events[eventIndex].values ?? {})) {
+            if (!_isRecord(value)) {
+                _addError(diagnostics, `${path}/events/${eventIndex}/values/${socket}`, `Event value socket "${socket}" must be an object.`);
+                continue;
+            }
             _validateValue(value, graph, diagnostics, `${path}/events/${eventIndex}/values/${socket}`);
         }
     }