@bian-womp/spark-graph 0.3.50 → 0.3.52

package/lib/cjs/index.cjs

@@ -998,39 +998,494 @@ const LOG_LEVEL_VALUES = {
     silent: 4,
 };
 
-/**
- * Shared utility functions for runtime components
- */
-/**
- * Type guard to check if a value is a Promise
- */
-function isPromise(value) {
-    return !!value && typeof value.then === "function";
+function parseJsonPath(path) {
+    if (typeof path === "string") {
+        return path.split(".").flatMap((segment) => {
+            const arrayMatch = segment.match(/^(.+)\[(\d+)\]$/);
+            if (arrayMatch) {
+                const index = parseInt(arrayMatch[2], 10);
+                return arrayMatch[1] ? [arrayMatch[1], index] : [index];
+            }
+            return [segment];
+        });
+    }
+    return path;
 }
-/**
- * Unwrap a value that might be a Promise
- */
-async function unwrapMaybePromise(value) {
-    return isPromise(value) ? await value : value;
+function getValueAtPath(obj, pathSegments) {
+    if (pathSegments.length === 0) {
+        return { value: obj, parent: null, key: "" };
+    }
+    let current = obj;
+    for (let i = 0; i < pathSegments.length - 1; i++) {
+        const segment = pathSegments[i];
+        if (current === null ||
+            current === undefined ||
+            typeof current !== "object") {
+            return null;
+        }
+        if (typeof segment === "string") {
+            if (Array.isArray(current)) {
+                const index = parseInt(segment, 10);
+                if (isNaN(index))
+                    return null;
+                current = current[index];
+            }
+            else {
+                current = current[segment];
+            }
+        }
+        else if (typeof segment === "number") {
+            if (Array.isArray(current)) {
+                if (segment >= 0 && segment < current.length) {
+                    current = current[segment];
+                }
+                else {
+                    return null;
+                }
+            }
+            else {
+                return null;
+            }
+        }
+        else if (segment instanceof RegExp) {
+            if (Array.isArray(current)) {
+                return null;
+            }
+            const obj = current;
+            const matchingKey = Object.keys(obj).find((key) => segment.test(key));
+            if (!matchingKey)
+                return null;
+            current = obj[matchingKey];
+        }
+        else {
+            return null;
+        }
+    }
+    const lastSegment = pathSegments[pathSegments.length - 1];
+    if (typeof lastSegment === "string") {
+        if (Array.isArray(current)) {
+            const index = parseInt(lastSegment, 10);
+            if (isNaN(index))
+                return null;
+            return { value: current[index], parent: current, key: index };
+        }
+        else if (current !== null &&
+            current !== undefined &&
+            typeof current === "object") {
+            return {
+                value: current[lastSegment],
+                parent: current,
+                key: lastSegment,
+            };
+        }
+    }
+    else if (typeof lastSegment === "number") {
+        if (Array.isArray(current)) {
+            if (lastSegment >= 0 && lastSegment < current.length) {
+                return {
+                    value: current[lastSegment],
+                    parent: current,
+                    key: lastSegment,
+                };
+            }
+        }
+        return null;
+    }
+    else if (lastSegment instanceof RegExp) {
+        if (Array.isArray(current)) {
+            return null;
+        }
+        const obj = current;
+        const matchingKey = Object.keys(obj).find((key) => lastSegment.test(key));
+        if (!matchingKey)
+            return null;
+        return { value: obj[matchingKey], parent: current, key: matchingKey };
+    }
+    return null;
+}
+function setValueAtPath(obj, pathSegments, newValue) {
+    const result = getValueAtPath(obj, pathSegments);
+    if (!result || result.parent === null)
+        return false;
+    if (Array.isArray(result.parent)) {
+        result.parent[result.key] = newValue;
+    }
+    else {
+        result.parent[result.key] = newValue;
+    }
+    return true;
 }
 /**
- * Shallow/deep-ish equality check to avoid unnecessary runs on identical values
+ * Sets a value at a path, creating intermediate objects as needed.
+ * Mutates the root object in place.
+ * @param root - The root object to modify (must be an object, will be initialized if needed)
+ * @param pathSegments - The path segments to traverse
+ * @param value - The value to set, or null to delete the path
+ * @throws Error if path cannot be created (e.g., array indices not supported, invalid parent types)
  */
-function valuesEqual(a, b) {
-    if (a === b)
-        return true;
-    if (typeof a !== typeof b)
-        return false;
-    if (a && b && typeof a === "object") {
-        try {
-            return JSON.stringify(a) === JSON.stringify(b);
+function setValueAtPathWithCreation(root, pathSegments, value) {
+    if (value === null) {
+        const result = getValueAtPath(root, pathSegments);
+        if (result && result.parent !== null && !Array.isArray(result.parent)) {
+            delete result.parent[result.key];
         }
-        catch {
+        return;
+    }
+    if (!root || typeof root !== "object" || Array.isArray(root)) {
+        throw new Error("Root must be an object");
+    }
+    let current = root;
+    for (let i = 0; i < pathSegments.length - 1; i++) {
+        const segment = pathSegments[i];
+        if (typeof segment === "string") {
+            if (!current ||
+                typeof current !== "object" ||
+                Array.isArray(current) ||
+                !(segment in current) ||
+                typeof current[segment] !== "object" ||
+                current[segment] === null ||
+                Array.isArray(current[segment])) {
+                if (!current || typeof current !== "object" || Array.isArray(current)) {
+                    throw new Error(`Cannot create path: parent at segment ${i} is not an object`);
+                }
+                current[segment] = {};
+            }
+            current = current[segment];
+        }
+        else {
+            throw new Error("Array indices not supported in extData paths");
+        }
+    }
+    const lastSegment = pathSegments[pathSegments.length - 1];
+    if (typeof lastSegment === "string") {
+        if (!current || typeof current !== "object" || Array.isArray(current)) {
+            throw new Error(`Cannot set value: parent at final segment is not an object`);
+        }
+        current[lastSegment] = value;
+    }
+    else {
+        throw new Error("Array indices not supported in extData paths");
+    }
+}
+function findMatchingPaths(obj, pathSegments, currentPath = []) {
+    if (pathSegments.length === 0) {
+        return [{ path: currentPath, value: obj }];
+    }
+    const [currentSegment, ...remainingSegments] = pathSegments;
+    const results = [];
+    if (currentSegment === undefined) {
+        return results;
+    }
+    if (typeof currentSegment === "string") {
+        if (Array.isArray(obj)) {
+            const index = parseInt(currentSegment, 10);
+            if (!isNaN(index) && index >= 0 && index < obj.length) {
+                results.push(...findMatchingPaths(obj[index], remainingSegments, [
+                    ...currentPath,
+                    index,
+                ]));
+            }
+        }
+        else if (obj !== null && obj !== undefined && typeof obj === "object") {
+            const objRecord = obj;
+            if (currentSegment in objRecord) {
+                results.push(...findMatchingPaths(objRecord[currentSegment], remainingSegments, [
+                    ...currentPath,
+                    currentSegment,
+                ]));
+            }
+        }
+    }
+    else if (typeof currentSegment === "number") {
+        if (Array.isArray(obj)) {
+            if (currentSegment >= 0 && currentSegment < obj.length) {
+                results.push(...findMatchingPaths(obj[currentSegment], remainingSegments, [
+                    ...currentPath,
+                    currentSegment,
+                ]));
+            }
+        }
+    }
+    else if (currentSegment instanceof RegExp) {
+        if (Array.isArray(obj)) {
+            for (let i = 0; i < obj.length; i++) {
+                results.push(...findMatchingPaths(obj[i], remainingSegments, [...currentPath, i]));
+            }
+        }
+        else if (obj !== null && obj !== undefined && typeof obj === "object") {
+            const objRecord = obj;
+            for (const key of Object.keys(objRecord)) {
+                if (currentSegment.test(key)) {
+                    results.push(...findMatchingPaths(objRecord[key], remainingSegments, [
+                        ...currentPath,
+                        key,
+                    ]));
+                }
+            }
+        }
+    }
+    return results;
+}
+function stringifyJson(obj, oneLiner) {
+    // No formatting requested: behave exactly like native JSON.stringify.
+    if (!oneLiner)
+        return JSON.stringify(obj);
+    const indentSize = Number.isFinite(oneLiner.indent)
+        ? Math.max(0, Math.floor(oneLiner.indent))
+        : 2;
+    const maxDepth = typeof oneLiner.maxDepth === "number" && Number.isFinite(oneLiner.maxDepth)
+        ? oneLiner.maxDepth
+        : undefined;
+    const patterns = (oneLiner.paths || []).filter(Boolean);
+    // Preserve JSON.stringify semantics for things like toJSON(), dropping functions/undefined, etc.
+    // Note: this still throws on circular structures (same as JSON.stringify).
+    const base = JSON.stringify(obj);
+    if (base === undefined)
+        return base;
+    const value = JSON.parse(base);
+    const pathMatchers = patterns.map((p) => compilePathMatcher(String(p)));
+    const formatKey = (k) => JSON.stringify(k);
+    const shouldInline = (path, key, v, depth) => {
+        if (maxDepth !== undefined && depth > maxDepth)
+            return true;
+        if (oneLiner.criteria?.({ path, key, value: v, depth }))
+            return true;
+        if (!pathMatchers.length)
             return false;
+        const tokensWithRoot = tokenizePath(path);
+        const tokensNoRoot = tokensWithRoot[0] === "$" ? tokensWithRoot.slice(1) : tokensWithRoot;
+        return pathMatchers.some((m) => m(tokensWithRoot, tokensNoRoot));
+    };
+    const stringifyInline = (v, depth, path) => {
+        if (v === null)
+            return "null";
+        const t = typeof v;
+        if (t === "string")
+            return JSON.stringify(v);
+        if (t === "number" || t === "boolean")
+            return String(v);
+        if (Array.isArray(v)) {
+            if (!v.length)
+                return "[]";
+            const parts = v.map((vv, i) => stringifyInline(vv));
+            return `[ ${parts.join(", ")} ]`;
+        }
+        if (t === "object") {
+            const keys = Object.keys(v);
+            if (!keys.length)
+                return "{}";
+            const parts = keys.map((k) => `${formatKey(k)}: ${stringifyInline(v[k])}`);
+            return `{ ${parts.join(", ")} }`;
+        }
+        // Shouldn't happen after JSON.parse(JSON.stringify(...)), but keep output valid JSON.
+        return "null";
+    };
+    const stringifyPretty = (v, depth, path, key) => {
+        if (shouldInline(path, key, v, depth))
+            return stringifyInline(v);
+        if (v === null)
+            return "null";
+        const t = typeof v;
+        if (t === "string")
+            return JSON.stringify(v);
+        if (t === "number" || t === "boolean")
+            return String(v);
+        const indentCur = " ".repeat(indentSize * depth);
+        const indentInner = " ".repeat(indentSize * (depth + 1));
+        if (Array.isArray(v)) {
+            if (!v.length)
+                return "[]";
+            // Compact array style: `[{...}, {...}]` while still allowing multi-line objects within.
+            const parts = v.map((vv, i) => stringifyPretty(vv, depth + 1, `${path}[${i}]`, String(i)));
+            return `[ ${parts.join(", ")} ]`;
+        }
+        if (t === "object") {
+            const keys = Object.keys(v);
+            if (!keys.length)
+                return "{}";
+            const lines = keys.map((k, idx) => {
+                const childPath = `${path}.${k}`;
+                const rendered = stringifyPretty(v[k], depth + 1, childPath, k);
+                const comma = idx === keys.length - 1 ? "" : ",";
+                return `${indentInner}${formatKey(k)}: ${rendered}${comma}`;
+            });
+            return `{\n${lines.join("\n")}\n${indentCur}}`;
         }
+        return "null";
+    };
+    return stringifyPretty(value, 0, "$", "$");
+}
+function tokenizePath(path) {
+    // Path format we generate: `$`, `$.a.b[0].c`
+    // Tokens: ["$", "a", "b", "[0]", "c"]
+    const tokens = [];
+    let i = 0;
+    if (path.startsWith("$")) {
+        tokens.push("$");
+        i = 1;
+    }
+    while (i < path.length) {
+        const ch = path[i];
+        if (ch === ".") {
+            i++;
+            const start = i;
+            while (i < path.length && path[i] !== "." && path[i] !== "[")
+                i++;
+            if (i > start)
+                tokens.push(path.slice(start, i));
+            continue;
+        }
+        if (ch === "[") {
+            const end = path.indexOf("]", i + 1);
+            if (end < 0) {
+                tokens.push(path.slice(i));
+                break;
+            }
+            tokens.push(path.slice(i, end + 1));
+            i = end + 1;
+            continue;
+        }
+        // Unexpected char; skip.
+        i++;
     }
-    return false;
+    return tokens.filter((t) => t.length);
 }
+function tokenizePattern(pattern) {
+    // Pattern format: `$`, `$.a.*.b`, `**.graph.**`, `arr[2].z`
+    // Tokens: ["$", "a", "*", "b"] etc. Brackets become their own token: ["arr","[2]","z"]
+    const tokens = [];
+    let i = 0;
+    if (pattern.startsWith("$")) {
+        tokens.push("$");
+        i = 1;
+    }
+    while (i < pattern.length) {
+        const ch = pattern[i];
+        if (ch === ".") {
+            i++;
+            continue;
+        }
+        if (ch === "[") {
+            const end = pattern.indexOf("]", i + 1);
+            if (end < 0) {
+                tokens.push(pattern.slice(i));
+                break;
+            }
+            tokens.push(pattern.slice(i, end + 1));
+            i = end + 1;
+            continue;
+        }
+        const start = i;
+        while (i < pattern.length && pattern[i] !== "." && pattern[i] !== "[")
+            i++;
+        if (i > start)
+            tokens.push(pattern.slice(start, i));
+    }
+    return tokens.filter((t) => t.length);
+}
+function compilePathMatcher(pattern) {
+    // Wildcard semantics (case-insensitive):
+    // - `*` matches exactly 1 path segment (key or `[index]`)
+    // - `**` matches 0 or more segments
+    // - `#` matches exactly 1 numeric segment (e.g. `"0"` or `[0]`)
+    // - `##` matches 0 or more numeric segments
+    // - `[*]` matches exactly 1 index segment
+    const pat = tokenizePattern(pattern);
+    const expectsRoot = pat[0] === "$";
+    const eq = (a, b) => a.localeCompare(b, undefined, { sensitivity: "accent" }) === 0;
+    const isIndex = (t) => t.startsWith("[") && t.endsWith("]");
+    const isNumericKey = (t) => /^[0-9]+$/.test(t);
+    const isNumericSegment = (t) => isNumericKey(t) || (isIndex(t) && /^[0-9]+$/.test(t.slice(1, -1)));
+    const match = (patTokens, pathTokens) => {
+        const memo = new Map();
+        const go = (pi, ti) => {
+            const key = `${pi},${ti}`;
+            const cached = memo.get(key);
+            if (cached !== undefined)
+                return cached;
+            let res = false;
+            if (pi === patTokens.length) {
+                res = ti === pathTokens.length;
+            }
+            else {
+                const p = patTokens[pi];
+                if (p === "**") {
+                    // Match any number of segments, including zero.
+                    for (let k = ti; k <= pathTokens.length; k++) {
+                        if (go(pi + 1, k)) {
+                            res = true;
+                            break;
+                        }
+                    }
+                }
+                else if (p === "##") {
+                    // Match any number of numeric segments, including zero.
+                    for (let k = ti; k <= pathTokens.length; k++) {
+                        let ok = true;
+                        for (let j = ti; j < k; j++) {
+                            if (!isNumericSegment(pathTokens[j])) {
+                                ok = false;
+                                break;
+                            }
+                        }
+                        if (ok && go(pi + 1, k)) {
+                            res = true;
+                            break;
+                        }
+                    }
+                }
+                else if (p === "*") {
+                    res = ti < pathTokens.length && go(pi + 1, ti + 1);
+                }
+                else if (p === "#") {
+                    res =
+                        ti < pathTokens.length &&
+                            isNumericSegment(pathTokens[ti]) &&
+                            go(pi + 1, ti + 1);
+                }
+                else if (p === "[*]") {
+                    res =
+                        ti < pathTokens.length &&
+                            isIndex(pathTokens[ti]) &&
+                            go(pi + 1, ti + 1);
+                }
+                else {
+                    res =
+                        ti < pathTokens.length &&
+                            eq(p.toLowerCase(), pathTokens[ti].toLowerCase()) &&
+                            go(pi + 1, ti + 1);
+                }
+            }
+            memo.set(key, res);
+            return res;
+        };
+        return go(0, 0);
+    };
+    return (tokensWithRoot, tokensNoRoot) => match(pat, expectsRoot ? tokensWithRoot : tokensNoRoot);
+}
+function stringifySceneAndOps(obj) {
+    return stringifyJson(obj, {
+        indent: 2,
+        paths: [
+            "**.camera.animation.*",
+            "**.animations.*",
+            "**.nodes.#.*",
+            "**.graphs.#.*",
+            "**.instances.#.*",
+            "**.shaders.#.*",
+            "**.materials.#.*",
+            "**.ext.#",
+            "**.ext.*.#.*",
+            "**.perUserExt.*.#",
+            "**.perUserExt.*.*.#",
+        ],
+        criteria: ({ value, key }) => (typeof value === "object" &&
+            value &&
+            Object.keys(value).sort().join(",") === "x,y,z") ||
+            key === "value",
+    });
+}
+
 /**
  * A reusable logger class that supports configurable log levels and prefixes.
  * Can be instantiated with a default log level and optionally override per call.
@@ -1108,7 +1563,7 @@ class LevelLogger {
             const contextStr = rest && Object.keys(rest).length > 0
                 ? `${formatJson ? "\n" : " "}${Object.entries(rest)
                     .map(([k, v]) => formatJson
-                    ? `${k}=${JSON.stringify(v, undefined, 2)}`
+                    ? `${k}=${stringifySceneAndOps(v)}`
                     : `${k}=${JSON.stringify(v)}`)
                     .join(formatJson ? "\n" : " ")}`
                 : "";
@@ -1438,6 +1893,40 @@ class RunContextManager {
     }
 }
 
+/**
+ * Shared utility functions for runtime components
+ */
+/**
+ * Type guard to check if a value is a Promise
+ */
+function isPromise(value) {
+    return !!value && typeof value.then === "function";
+}
+/**
+ * Unwrap a value that might be a Promise
+ */
+async function unwrapMaybePromise(value) {
+    return isPromise(value) ? await value : value;
+}
+/**
+ * Shallow/deep-ish equality check to avoid unnecessary runs on identical values
+ */
+function valuesEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (a && b && typeof a === "object") {
+        try {
+            return JSON.stringify(a) === JSON.stringify(b);
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
+
 function tryHandleResolving(def, registry, environment) {
     const out = new Map();
     const pending = new Set();
@@ -2154,7 +2643,7 @@ class EdgePropagator {
         // Set input value (respecting skipPropagateValues)
         const shouldSetValue = this.shouldSetInputValue(effectiveRunContexts);
         if (shouldSetValue && valueChanged) {
-            this.setTargetInput(edge, dstNode, processedValue);
+            this.setTargetInput(edge, processedValue);
         }
         else if (shouldSetValue && !valueChanged) {
             // Even if value didn't change, update timestamp if we're forcing execution
@@ -2213,7 +2702,7 @@ class EdgePropagator {
     /**
      * Set target input value and emit event
      */
-    setTargetInput(edge, dstNode, value) {
+    setTargetInput(edge, value) {
         this.graph.updateNodeInput(edge.target.nodeId, edge.target.handle, value);
         this.handleResolver.scheduleRecomputeHandles(edge.target.nodeId);
     }
@@ -2224,7 +2713,10 @@ class EdgePropagator {
         // Determine if we should propagate
         const shouldPropagate = this.shouldPropagateExecution(effectiveRunContexts);
         if (shouldPropagate && this.graph.allInboundHaveValue(targetNodeId)) {
-            this.nodeExecutor.execute(targetNodeId, effectiveRunContexts);
+            this.nodeExecutor.execute(targetNodeId, {
+                runContextIds: effectiveRunContexts,
+                reason: "executeDownstream",
+            });
         }
     }
     /**
@@ -2354,7 +2846,7 @@ class NodeExecutor {
     /**
      * Create an execution context for a node
      */
-    createExecutionContext(nodeId, node, inputs, runId, abortSignal, runContextIds, options) {
+    createExecutionContext(nodeId, inputs, runId, abortSignal, runContextIds, options) {
         const emitHandler = options?.emitHandler ??
             ((handle, value) => {
                 this.edgePropagator.propagate(nodeId, handle, value, runContextIds);
@@ -2366,8 +2858,9 @@ class NodeExecutor {
                 });
             });
         // Create log function that respects node's logLevel using LevelLogger
-        const nodeLogLevel = node.logLevel ?? "info";
-        const logger = new LevelLogger(nodeLogLevel, `[node:${runId || nodeId}:${node.typeId}]`);
+        const node = this.graph.getNode(nodeId);
+        const nodeLogLevel = node?.logLevel ?? "info";
+        const logger = new LevelLogger(nodeLogLevel, `[node:${runId || nodeId}:${node?.typeId ?? ""}]`);
         const log = (level, message, context) => {
             switch (level) {
                 case "debug":
@@ -2386,7 +2879,7 @@ class NodeExecutor {
         };
         return {
             nodeId,
-            state: node.state,
+            state: node?.state,
             setState: (next) => this.graph.updateNodeState(nodeId, next),
             emit: emitHandler,
             invalidateDownstream: () => {
@@ -2401,7 +2894,10 @@ class NodeExecutor {
                             this.runContextManager.createRunContext(nodeId, opts),
                         ]);
                     }
-                    this.execute(nodeId, runContextIdsToUse);
+                    this.execute(nodeId, {
+                        runContextIds: runContextIdsToUse,
+                        reason: opts?.reason ?? "executeFromContext",
+                    });
                 }
             },
             getInput: (handle) => inputs[handle],
@@ -2413,7 +2909,7 @@ class NodeExecutor {
                 this.eventEmitter.emit("stats", {
                     kind: "node-custom-data",
                     nodeId,
-                    typeId: node.typeId,
+                    typeId: node?.typeId ?? "",
                     runId,
                     data,
                 });
@@ -2424,13 +2920,14 @@ class NodeExecutor {
     /**
      * Internal method for executing inputs changed (also used by GraphRuntime)
      */
-    execute(nodeId, runContextIds, canSkipHandleResolution) {
+    execute(nodeId, opts) {
+        let { runContextIds, canSkipHandleResolution, reason = "" } = opts ?? {};
         const node = this.graph.getNode(nodeId);
         if (!node)
             return;
         const runMode = this.runtime.getRunMode();
         if (!runMode) {
-            console.trace("NodeExecutor.execute: no runMode, skipping execution");
+            console.trace(`NodeExecutor.execute[${nodeId}:${reason}]: no runMode, skipping execution`);
             return;
         }
         // In manual mode, require runContextIds unless autoRun policy is set
@@ -2442,12 +2939,12 @@ class NodeExecutor {
                 ]);
             }
             else {
-                console.trace("NodeExecutor.execute: no runContextIds provided in manual mode, skipping execution");
+                console.trace(`NodeExecutor.execute[${nodeId}:${reason}]: no runContextIds provided in manual mode, skipping execution`);
                 return;
             }
         }
         if (runMode === "auto" && runContextIds && runContextIds.size > 0) {
-            console.trace("NodeExecutor.execute: runContextIds provided in auto mode, ignoring");
+            console.trace(`NodeExecutor.execute[${nodeId}:${reason}]: runContextIds provided in auto mode, ignoring`);
             runContextIds = undefined;
         }
         // Early validation for auto-mode paused state
@@ -2490,7 +2987,11 @@ class NodeExecutor {
                 // Re-check node still exists and conditions
                 const nodeAfter = this.graph.getNode(nodeId);
                 if (nodeAfter) {
-                    this.execute(nodeId, runContextIds, true);
+                    this.execute(nodeId, {
+                        runContextIds,
+                        canSkipHandleResolution: true,
+                        reason: opts?.reason,
+                    });
                 }
                 if (runContextIds && runContextIds.size > 0) {
                     for (const id of runContextIds) {
@@ -2502,19 +3003,22 @@ class NodeExecutor {
         }
         // Handle debouncing
         const now = Date.now();
-        if (this.shouldDebounce(node, now)) {
-            this.handleDebouncedSchedule(node, nodeId, now, runContextIds);
+        if (this.shouldDebounce(nodeId, now)) {
+            this.handleDebouncedSchedule(nodeId, now, runContextIds, reason);
             return;
         }
         // Prepare execution plan
-        const executionPlan = this.prepareExecutionPlan(node, nodeId, runContextIds, now);
+        const executionPlan = this.prepareExecutionPlan(nodeId, runContextIds, now, reason);
         // Route to appropriate concurrency handler
-        this.routeToConcurrencyHandler(node, nodeId, executionPlan);
+        this.routeToConcurrencyHandler(nodeId, executionPlan);
     }
     /**
      * Check if execution should be debounced
      */
-    shouldDebounce(node, now) {
+    shouldDebounce(nodeId, now) {
+        const node = this.graph.getNode(nodeId);
+        if (!node)
+            return false;
         const policy = node.policy ?? {};
         const lastScheduledAt = node.lastScheduledAt;
         return !!(policy.debounceMs &&
@@ -2524,80 +3028,78 @@ class NodeExecutor {
     /**
      * Handle debounced scheduling by replacing the latest queued item
      */
-    handleDebouncedSchedule(node, nodeId, now, runContextIds) {
+    handleDebouncedSchedule(nodeId, now, runContextIds, reason) {
+        const node = this.graph.getNode(nodeId);
+        if (!node)
+            return;
         // Decrement pendingQueued for any existing queued items before replacing
         if (node.queue.length > 0) {
             this.decrementQueuedForPlans(node.queue, nodeId);
         }
-        const effectiveInputs = this.getEffectiveInputs(nodeId);
-        const runSeq = this.graph.incrementNodeRunSeq(nodeId);
-        const runId = `${nodeId}:${runSeq}:${now}`;
-        const policySnapshot = node.policy ? { ...node.policy } : undefined;
-        const plan = {
-            runId,
-            effectiveInputs,
-            runContextIdsForRun: runContextIds,
-            timestamp: now,
-            policy: policySnapshot,
-        };
-        this.graph.replaceNodeQueue(nodeId, [plan]);
+        const executionPlan = this.prepareExecutionPlan(nodeId, runContextIds, now, reason);
+        this.graph.replaceNodeQueue(nodeId, [executionPlan]);
     }
     /**
      * Prepare execution plan with all necessary information
      */
-    prepareExecutionPlan(node, nodeId, runContextIds, now) {
+    prepareExecutionPlan(nodeId, runContextIds, now, reason) {
+        const node = this.graph.getNode(nodeId);
         this.graph.setNodeLastScheduledAt(nodeId, now);
         const runSeq = this.graph.incrementNodeRunSeq(nodeId);
         const runId = `${nodeId}:${runSeq}:${now}`;
         this.graph.setNodeLatestRunId(nodeId, runId);
         const effectiveInputs = this.getEffectiveInputs(nodeId);
         // Take a shallow snapshot of the current policy for this run
-        const policySnapshot = node.policy ? { ...node.policy } : undefined;
+        const policySnapshot = node?.policy ? { ...node.policy } : undefined;
         return {
             runId,
             effectiveInputs,
             runContextIdsForRun: runContextIds,
             timestamp: now,
             policy: policySnapshot,
+            reason,
         };
     }
     /**
      * Route execution to appropriate concurrency handler
      */
-    routeToConcurrencyHandler(node, nodeId, plan) {
+    routeToConcurrencyHandler(nodeId, plan) {
         const mode = plan.policy?.asyncConcurrency ?? "switch";
         switch (mode) {
             case "drop":
-                this.handleDropMode(node, nodeId, plan);
+                this.handleDropMode(nodeId, plan);
                 break;
             case "queue":
-                this.handleQueueMode(node, nodeId, plan);
+                this.handleQueueMode(nodeId, plan);
                 break;
             case "switch":
             case "merge":
             default:
-                this.startRun(node, nodeId, plan);
+                this.startRun(nodeId, plan);
                 break;
         }
     }
     /**
      * Handle drop mode - drop execution if node is already running, otherwise start run
      */
-    handleDropMode(node, nodeId, plan) {
+    handleDropMode(nodeId, plan) {
+        const node = this.graph.getNode(nodeId);
+        if (!node)
+            return;
         // Drop if node is already running
         if (node.activeControllers.size > 0) {
             return; // Don't increment pendingCount if we're dropping this run
         }
         // Start run if node is not running
-        this.startRun(node, nodeId, plan);
+        this.startRun(nodeId, plan);
     }
     /**
      * Handle queue mode - add to queue and process sequentially
      */
-    handleQueueMode(node, nodeId, plan) {
+    handleQueueMode(nodeId, plan) {
         const maxQ = plan.policy?.maxQueue ?? 8;
-        const currentNode = this.graph.getNode(nodeId);
-        if (!currentNode)
+        const node = this.graph.getNode(nodeId);
+        if (!node)
             return;
         // Keep the originating run-context alive while work is queued by
         // incrementing queued counters for the plan's run-contexts.
@@ -2607,18 +3109,18 @@ class NodeExecutor {
             }
         }
         this.graph.addToNodeQueue(nodeId, plan);
-        if (currentNode.queue.length > maxQ) {
+        if (node.queue.length > maxQ) {
             const dropped = this.graph.shiftNodeQueue(nodeId);
             if (dropped) {
                 this.decrementQueuedForPlans(dropped, nodeId);
             }
         }
-        this.processQueue(node, nodeId);
+        this.processQueue(nodeId);
     }
     /**
      * Process queued executions sequentially
      */
-    processQueue(node, nodeId) {
+    processQueue(nodeId) {
         const processNext = () => {
             const node = this.graph.getNode(nodeId);
             if (!node)
@@ -2631,7 +3133,7 @@ class NodeExecutor {
             this.graph.setNodeLatestRunId(nodeId, next.runId);
             // Start the run first (which increments pendingNodes), then decrement
             // pendingQueued to ensure the run context stays alive.
-            this.startRun(node, nodeId, next, () => {
+            this.startRun(nodeId, next, () => {
                 setTimeout(processNext, 0);
             });
             this.decrementQueuedForPlans(next, nodeId);
@@ -2641,19 +3143,19 @@ class NodeExecutor {
     /**
      * Start a node execution run
      */
-    startRun(node, nodeId, plan, onDone) {
+    startRun(nodeId, plan, onDone) {
         // Track run-contexts
         this.trackRunContextStart(nodeId, plan.runContextIdsForRun);
         // Setup execution controller
-        const controller = this.createExecutionController(nodeId, node, plan.runId);
+        const controller = this.createExecutionController(nodeId, plan.runId);
         // Handle concurrency mode
-        this.applyConcurrencyMode(nodeId, node, controller, plan);
+        this.applyConcurrencyMode(nodeId, controller, plan);
         // Setup timeout if needed
-        const timeoutId = this.setupTimeout(node, controller, plan);
+        const timeoutId = this.setupTimeout(controller, plan);
         // Create execution context
-        const execCtx = this.createExecutionContext(nodeId, node, plan.effectiveInputs, plan.runId, controller.signal, plan.runContextIdsForRun, this.createEmitAndProgressHandlers(node, nodeId, plan));
+        const execCtx = this.createExecutionContext(nodeId, plan.effectiveInputs, plan.runId, controller.signal, plan.runContextIdsForRun, this.createEmitAndProgressHandlers(nodeId, plan));
         // Execute
-        this.executeNode(node, nodeId, execCtx, plan, controller, timeoutId, onDone);
+        this.executeNode(nodeId, execCtx, plan, controller, timeoutId, onDone);
     }
     /**
      * Track run-context start for pending nodes
@@ -2682,12 +3184,13 @@ class NodeExecutor {
     /**
      * Create execution controller and update node stats
      */
-    createExecutionController(nodeId, node, runId) {
+    createExecutionController(nodeId, runId) {
         const controller = new AbortController();
         const now = Date.now();
+        const node = this.graph.getNode(nodeId);
         this.graph.updateNodeStats(nodeId, {
-            runs: node.stats.runs + 1,
-            active: node.stats.active + 1,
+            runs: (node?.stats.runs ?? 0) + 1,
+            active: (node?.stats.active ?? 0) + 1,
             lastStartAt: now,
             progress: 0,
         });
@@ -2697,7 +3200,7 @@ class NodeExecutor {
     /**
      * Apply concurrency mode (switch mode aborts other controllers)
      */
-    applyConcurrencyMode(nodeId, node, controller, plan) {
+    applyConcurrencyMode(nodeId, controller, plan) {
         const mode = plan.policy?.asyncConcurrency ?? "switch";
         if (mode === "switch") {
             const controllers = this.graph.getNodeControllers(nodeId);
@@ -2710,7 +3213,7 @@ class NodeExecutor {
     /**
      * Setup timeout for execution if configured
      */
-    setupTimeout(node, controller, plan) {
+    setupTimeout(controller, plan) {
         const policy = plan.policy ?? {};
         if (policy.timeoutMs && policy.timeoutMs > 0) {
             return setTimeout(() => controller.abort("timeout"), policy.timeoutMs);
@@ -2720,7 +3223,7 @@ class NodeExecutor {
     /**
      * Create emit and progress handlers for execution context
      */
-    createEmitAndProgressHandlers(node, nodeId, plan) {
+    createEmitAndProgressHandlers(nodeId, plan) {
         const policy = plan.policy ?? {};
         return {
             emitHandler: (handle, value) => {
@@ -2755,7 +3258,10 @@ class NodeExecutor {
     /**
      * Execute the node with retry logic and cleanup
      */
-    executeNode(node, nodeId, ctx, plan, controller, timeoutId, onDone) {
+    executeNode(nodeId, ctx, plan, controller, timeoutId, onDone) {
+        const node = this.graph.getNode(nodeId);
+        if (!node)
+            return;
         // Fire node-start event
         this.eventEmitter.emit("stats", {
             kind: "node-start",
@@ -2763,7 +3269,11 @@ class NodeExecutor {
             typeId: node.typeId,
             runId: plan.runId,
         });
-        ctx.log("debug", "node-start");
+        ctx.log("debug", "node-start", {
+            inputs: node.inputs,
+            effectiveInputs: plan.effectiveInputs,
+            reason: plan.reason,
+        });
         const exec = async (attempt) => {
             let hadError = false;
             try {
@@ -2801,7 +3311,7 @@ class NodeExecutor {
                 });
             }
             finally {
-                this.cleanupExecution(node, nodeId, ctx, plan, controller, timeoutId, hadError, onDone);
+                this.cleanupExecution(nodeId, ctx, plan, controller, timeoutId, hadError, onDone);
             }
         };
         exec(0);
@@ -2809,7 +3319,7 @@ class NodeExecutor {
     /**
      * Cleanup after execution completes
      */
-    cleanupExecution(node, nodeId, ctx, plan, controller, timeoutId, hadError, onDone) {
+    cleanupExecution(nodeId, ctx, plan, controller, timeoutId, hadError, onDone) {
         // Decrement pendingNodes count for all relevant run-contexts
         if (plan.runContextIdsForRun && plan.runContextIdsForRun.size > 0) {
             for (const id of plan.runContextIdsForRun) {
@@ -2823,19 +3333,19 @@ class NodeExecutor {
         if (timeoutId)
             clearTimeout(timeoutId);
         this.graph.removeNodeController(nodeId, controller);
-        const currentNode = this.graph.getNode(nodeId);
-        if (!currentNode)
+        const node = this.graph.getNode(nodeId);
+        if (!node)
             return;
         const controllers = this.graph.getNodeControllers(nodeId);
         const lastEndAt = Date.now();
-        const lastDurationMs = currentNode.stats.lastStartAt && lastEndAt
-            ? lastEndAt - currentNode.stats.lastStartAt
+        const lastDurationMs = node.stats.lastStartAt && lastEndAt
+            ? lastEndAt - node.stats.lastStartAt
             : undefined;
         this.graph.updateNodeStats(nodeId, {
             active: Math.max(0, controllers.size),
             lastEndAt,
             lastDurationMs,
-            lastError: hadError ? currentNode.stats.lastError : undefined,
+            lastError: hadError ? node.stats.lastError : undefined,
         });
         // Track successful completion time (for detecting stale inputs)
         const isCancelled = controller.signal.aborted &&
@@ -2847,26 +3357,22 @@ class NodeExecutor {
         }
         // Only emit node-done if not cancelled (cancellation events emitted separately)
         if (!isCancelled) {
-            if (currentNode) {
+            if (node) {
                 this.eventEmitter.emit("stats", {
                     kind: "node-done",
                     nodeId,
-                    typeId: currentNode.typeId,
+                    typeId: node.typeId,
                     runId: plan.runId,
-                    durationMs: currentNode.stats.lastDurationMs,
+                    durationMs: node.stats.lastDurationMs,
                 });
             }
         }
-        if (currentNode) {
+        if (node) {
             ctx.log("debug", "node-done", {
-                durationMs: currentNode.stats.lastDurationMs,
+                durationMs: node.stats.lastDurationMs,
+                outputs: node.outputs,
                 hadError,
-                inputs: currentNode.inputs
-                    ? structuredClone(currentNode.inputs)
-                    : undefined,
-                outputs: currentNode.outputs
-                    ? structuredClone(currentNode.outputs)
-                    : undefined,
+                reason: plan.reason,
             });
         }
         if (onDone)
@@ -2875,14 +3381,13 @@ class NodeExecutor {
     /**
      * Cancel all active runs for a node
      */
-    cancelNodeActiveRuns(node, reason) {
-        const nodeId = node.nodeId;
+    cancelNodeActiveRuns(nodeId, reason) {
+        const node = this.graph.getNode(nodeId);
+        if (!node)
+            return;
         const controllers = this.graph.getNodeControllers(nodeId);
         for (const controller of controllers) {
-            const currentNode = this.graph.getNode(nodeId);
-            if (!currentNode)
-                continue;
-            const runId = currentNode.controllerRunIds.get(controller);
+            const runId = node.controllerRunIds.get(controller);
             if (runId) {
                 // Track cancelled runIds for snapshot and user-cancelled operations
                 // (to drop emits from cancelled runs)
@@ -2892,8 +3397,8 @@ class NodeExecutor {
                 // Emit cancellation event
                 this.eventEmitter.emit("stats", {
                     kind: "node-done",
-                    nodeId: currentNode.nodeId,
-                    typeId: currentNode.typeId,
+                    nodeId: nodeId,
+                    typeId: node.typeId,
                     runId,
                     cancelled: true,
                 });
@@ -2941,10 +3446,7 @@ class NodeExecutor {
         }
         // Cancel runs for all affected nodes
         for (const nodeId of toCancel) {
-            const node = this.graph.getNode(nodeId);
-            if (!node)
-                continue;
-            this.cancelNodeActiveRuns(node, reason);
+            this.cancelNodeActiveRuns(nodeId, reason);
             const runSeq = this.graph.incrementNodeRunSeq(nodeId);
             const now = Date.now();
             const suffix = reason === "snapshot" ? "snapshot" : "cancelled";
@@ -3184,7 +3686,7 @@ class GraphRuntime {
         // However, if autoRun policy is set, nodes run automatically even in manual mode.
         if (anyChanged) {
             this.handleResolver.scheduleRecomputeHandles(nodeId);
-            this.executeNodeAutoRun(nodeId);
+            this.executeNodeAutoRun(nodeId, { reason: "setInputs" });
         }
     }
     getOutput(nodeId, output) {
@@ -3195,7 +3697,7 @@ class GraphRuntime {
         this.graph.forEachNode((node) => {
             const effectiveInputs = this.nodeExecutor.getEffectiveInputs(node.nodeId);
             const ctrl = new AbortController();
-            const execCtx = this.nodeExecutor.createExecutionContext(node.nodeId, node, effectiveInputs, `${node.nodeId}:init`, ctrl.signal);
+            const execCtx = this.nodeExecutor.createExecutionContext(node.nodeId, effectiveInputs, `${node.nodeId}:init`, ctrl.signal);
             if (node.lifecycle?.prepare) {
                 execCtx.log("debug", "prepare-start");
                 node.lifecycle.prepare(node.params ?? {}, execCtx);
@@ -3206,7 +3708,7 @@ class GraphRuntime {
         if (this.runMode === "auto" && invalidate) {
             for (const nodeId of this.graph.getNodeIds()) {
                 if (this.graph.allInboundHaveValue(nodeId))
-                    this.execute(nodeId);
+                    this.execute(nodeId, { reason: "launch" });
             }
         }
         if (startPaused) {
@@ -3221,7 +3723,7 @@ class GraphRuntime {
         if (this.isInvalidateEvent(event)) {
             // Check if node has all inbound inputs (required for execution)
             if (this.graph.allInboundHaveValue(nodeId)) {
-                this.execute(nodeId);
+                this.execute(nodeId, { reason: "triggerExternal" });
             }
             return;
         }
@@ -3345,17 +3847,20 @@ class GraphRuntime {
             setTimeout(check, 10);
         });
     }
-    async runFromHereContext(startNodeId, options) {
+    async runFromHereContext(startNodeId, opts) {
         const node = this.graph.getNode(startNodeId);
         if (!node)
             return;
         return new Promise((resolve) => {
             const id = this.runContextManager.createRunContext(startNodeId, {
                 resolve,
-                ...options,
+                ...opts,
             });
             this.graph.addNodeRunContextId(startNodeId, id);
-            this.execute(startNodeId, new Set([id]));
+            this.execute(startNodeId, {
+                runContextIds: new Set([id]),
+                reason: opts?.reason ?? "runFromHereContext",
+            });
         });
     }
     setRunMode(runMode) {
@@ -3402,7 +3907,7 @@ class GraphRuntime {
             }
         }
     }
-    executeNodeAutoRun(nodeId) {
+    executeNodeAutoRun(nodeId, opts) {
         const node = this.graph.getNode(nodeId);
         const shouldAutoRun = this.runMode === "auto" || node?.policy?.autoRun === true;
         let runContextIdsToUse = undefined;
@@ -3412,7 +3917,10 @@ class GraphRuntime {
             ]);
         }
         if (shouldAutoRun && this.graph.allInboundHaveValue(nodeId)) {
-            this.execute(nodeId, runContextIdsToUse);
+            this.execute(nodeId, {
+                runContextIds: runContextIdsToUse,
+                reason: opts?.reason ?? "executeNodeAutoRun",
+            });
         }
     }
     copyOutputs(fromNodeId, toNodeId, options) {
@@ -3421,7 +3929,7 @@ class GraphRuntime {
             return;
         this.hydrate({ outputs: { [toNodeId]: { ...fromNode.outputs } } }, { invalidate: !options?.dry });
         this.handleResolver.scheduleRecomputeHandles(toNodeId);
-        this.executeNodeAutoRun(toNodeId);
+        this.executeNodeAutoRun(toNodeId, { reason: "copyOutputs" });
     }
     hydrate(payload, opts) {
         const releasePause = this.requestPause();
@@ -3479,7 +3987,7 @@ class GraphRuntime {
                     const node = this.graph.getNode(nodeId);
                     if (!node)
                         continue;
-                    this.nodeExecutor.cancelNodeActiveRuns(node, "node-deleted");
+                    this.nodeExecutor.cancelNodeActiveRuns(nodeId, "node-deleted");
                     this.runContextManager.cancelNodeInRunContexts(nodeId, true);
                     node.runtime.onDeactivated?.();
                     node.runtime.dispose?.();
@@ -3540,7 +4048,7 @@ class GraphRuntime {
                     this.graph.setNode(n.nodeId, newNode);
                     const effectiveInputs = this.nodeExecutor.getEffectiveInputs(newNode.nodeId);
                     const ctrl = new AbortController();
-                    const execCtx = this.nodeExecutor.createExecutionContext(newNode.nodeId, newNode, effectiveInputs, `${newNode.nodeId}:init`, ctrl.signal);
+                    const execCtx = this.nodeExecutor.createExecutionContext(newNode.nodeId, effectiveInputs, `${newNode.nodeId}:init`, ctrl.signal);
                     if (newNode.lifecycle?.prepare) {
                         execCtx.log("debug", "prepare-start");
                         newNode.lifecycle.prepare(newNode.params ?? {}, execCtx);
@@ -3651,7 +4159,7 @@ class GraphRuntime {
                         this.edgePropagator.clearArrayBuckets(nodeId);
                         // Trigger handle resolution when inputs are removed
                         this.handleResolver.scheduleRecomputeHandles(nodeId);
-                        this.executeNodeAutoRun(nodeId);
+                        this.executeNodeAutoRun(nodeId, { reason: "graphUpdate" });
                     }
                 }
                 // Propagate changes on edges added
@@ -3721,8 +4229,8 @@ class GraphRuntime {
         });
         this.graph.clear();
     }
-    execute(nodeId, runContextIds, canSkipHandleResolution) {
-        this.nodeExecutor.execute(nodeId, runContextIds, canSkipHandleResolution);
+    execute(nodeId, opts) {
+        this.nodeExecutor.execute(nodeId, opts);
     }
     propagate(srcNodeId, srcHandle, value, runContextIds) {
         this.edgePropagator.propagate(srcNodeId, srcHandle, value, runContextIds);
@@ -4085,6 +4593,7 @@ class LocalEngine {
         await this.graphRuntime.runFromHereContext(nodeId, {
             skipPropagateValues: options?.skipPropagateValues ?? false,
             propagate: false, // Don't schedule downstream nodes
+            reason: "computeNode",
         });
     }
     /**
@@ -4093,7 +4602,9 @@ class LocalEngine {
      * Uses run-context system for dynamic graph updates.
      */
     async runFromHere(nodeId) {
-        await this.graphRuntime.runFromHereContext(nodeId);
+        await this.graphRuntime.runFromHereContext(nodeId, {
+            reason: "runFromHere",
+        });
     }
     setRunMode(runMode) {
         this.graphRuntime.setRunMode(runMode);
@@ -5531,235 +6042,6 @@ function createValidationGraphRegistry(id) {
     return registry;
 }
 
-function parseJsonPath(path) {
-    if (typeof path === "string") {
-        return path.split(".").flatMap((segment) => {
-            const arrayMatch = segment.match(/^(.+)\[(\d+)\]$/);
-            if (arrayMatch) {
-                const index = parseInt(arrayMatch[2], 10);
-                return arrayMatch[1] ? [arrayMatch[1], index] : [index];
-            }
-            return [segment];
-        });
-    }
-    return path;
-}
-function getValueAtPath(obj, pathSegments) {
-    if (pathSegments.length === 0) {
-        return { value: obj, parent: null, key: "" };
-    }
-    let current = obj;
-    for (let i = 0; i < pathSegments.length - 1; i++) {
-        const segment = pathSegments[i];
-        if (current === null ||
-            current === undefined ||
-            typeof current !== "object") {
-            return null;
-        }
-        if (typeof segment === "string") {
-            if (Array.isArray(current)) {
-                const index = parseInt(segment, 10);
-                if (isNaN(index))
-                    return null;
-                current = current[index];
-            }
-            else {
-                current = current[segment];
-            }
-        }
-        else if (typeof segment === "number") {
-            if (Array.isArray(current)) {
-                if (segment >= 0 && segment < current.length) {
-                    current = current[segment];
-                }
-                else {
-                    return null;
-                }
-            }
-            else {
-                return null;
-            }
-        }
-        else if (segment instanceof RegExp) {
-            if (Array.isArray(current)) {
-                return null;
-            }
-            const obj = current;
-            const matchingKey = Object.keys(obj).find((key) => segment.test(key));
-            if (!matchingKey)
-                return null;
-            current = obj[matchingKey];
-        }
-        else {
-            return null;
-        }
-    }
-    const lastSegment = pathSegments[pathSegments.length - 1];
-    if (typeof lastSegment === "string") {
-        if (Array.isArray(current)) {
-            const index = parseInt(lastSegment, 10);
-            if (isNaN(index))
-                return null;
-            return { value: current[index], parent: current, key: index };
-        }
-        else if (current !== null &&
-            current !== undefined &&
-            typeof current === "object") {
-            return {
-                value: current[lastSegment],
-                parent: current,
-                key: lastSegment,
-            };
-        }
-    }
-    else if (typeof lastSegment === "number") {
-        if (Array.isArray(current)) {
-            if (lastSegment >= 0 && lastSegment < current.length) {
-                return {
-                    value: current[lastSegment],
-                    parent: current,
-                    key: lastSegment,
-                };
-            }
-        }
-        return null;
-    }
-    else if (lastSegment instanceof RegExp) {
-        if (Array.isArray(current)) {
-            return null;
-        }
-        const obj = current;
-        const matchingKey = Object.keys(obj).find((key) => lastSegment.test(key));
-        if (!matchingKey)
-            return null;
-        return { value: obj[matchingKey], parent: current, key: matchingKey };
-    }
-    return null;
-}
-function setValueAtPath(obj, pathSegments, newValue) {
-    const result = getValueAtPath(obj, pathSegments);
-    if (!result || result.parent === null)
-        return false;
-    if (Array.isArray(result.parent)) {
-        result.parent[result.key] = newValue;
-    }
-    else {
-        result.parent[result.key] = newValue;
-    }
-    return true;
-}
-/**
- * Sets a value at a path, creating intermediate objects as needed.
- * Mutates the root object in place.
- * @param root - The root object to modify (must be an object, will be initialized if needed)
- * @param pathSegments - The path segments to traverse
- * @param value - The value to set, or null to delete the path
- * @throws Error if path cannot be created (e.g., array indices not supported, invalid parent types)
- */
-function setValueAtPathWithCreation(root, pathSegments, value) {
-    if (value === null) {
-        const result = getValueAtPath(root, pathSegments);
-        if (result && result.parent !== null && !Array.isArray(result.parent)) {
-            delete result.parent[result.key];
-        }
-        return;
-    }
-    if (!root || typeof root !== "object" || Array.isArray(root)) {
-        throw new Error("Root must be an object");
-    }
-    let current = root;
-    for (let i = 0; i < pathSegments.length - 1; i++) {
-        const segment = pathSegments[i];
-        if (typeof segment === "string") {
-            if (!current ||
-                typeof current !== "object" ||
-                Array.isArray(current) ||
-                !(segment in current) ||
-                typeof current[segment] !== "object" ||
-                current[segment] === null ||
-                Array.isArray(current[segment])) {
-                if (!current || typeof current !== "object" || Array.isArray(current)) {
-                    throw new Error(`Cannot create path: parent at segment ${i} is not an object`);
-                }
-                current[segment] = {};
-            }
-            current = current[segment];
-        }
-        else {
-            throw new Error("Array indices not supported in extData paths");
-        }
-    }
-    const lastSegment = pathSegments[pathSegments.length - 1];
-    if (typeof lastSegment === "string") {
-        if (!current || typeof current !== "object" || Array.isArray(current)) {
-            throw new Error(`Cannot set value: parent at final segment is not an object`);
-        }
-        current[lastSegment] = value;
-    }
-    else {
-        throw new Error("Array indices not supported in extData paths");
-    }
-}
-function findMatchingPaths(obj, pathSegments, currentPath = []) {
-    if (pathSegments.length === 0) {
-        return [{ path: currentPath, value: obj }];
-    }
-    const [currentSegment, ...remainingSegments] = pathSegments;
-    const results = [];
-    if (currentSegment === undefined) {
-        return results;
-    }
-    if (typeof currentSegment === "string") {
-        if (Array.isArray(obj)) {
-            const index = parseInt(currentSegment, 10);
-            if (!isNaN(index) && index >= 0 && index < obj.length) {
-                results.push(...findMatchingPaths(obj[index], remainingSegments, [
-                    ...currentPath,
-                    index,
-                ]));
-            }
-        }
-        else if (obj !== null && obj !== undefined && typeof obj === "object") {
-            const objRecord = obj;
-            if (currentSegment in objRecord) {
-                results.push(...findMatchingPaths(objRecord[currentSegment], remainingSegments, [
-                    ...currentPath,
-                    currentSegment,
-                ]));
-            }
-        }
-    }
-    else if (typeof currentSegment === "number") {
-        if (Array.isArray(obj)) {
-            if (currentSegment >= 0 && currentSegment < obj.length) {
-                results.push(...findMatchingPaths(obj[currentSegment], remainingSegments, [
-                    ...currentPath,
-                    currentSegment,
-                ]));
-            }
-        }
-    }
-    else if (currentSegment instanceof RegExp) {
-        if (Array.isArray(obj)) {
-            for (let i = 0; i < obj.length; i++) {
-                results.push(...findMatchingPaths(obj[i], remainingSegments, [...currentPath, i]));
-            }
-        }
-        else if (obj !== null && obj !== undefined && typeof obj === "object") {
-            const objRecord = obj;
-            for (const key of Object.keys(objRecord)) {
-                if (currentSegment.test(key)) {
-                    results.push(...findMatchingPaths(objRecord[key], remainingSegments, [
-                        ...currentPath,
-                        key,
-                    ]));
-                }
-            }
-        }
-    }
-    return results;
-}
-
 function mergeGraphDefinitions(target, source) {
     const existingNodeIds = new Set(target.nodes.map((n) => n.nodeId));
     const existingEdgeIds = new Set(target.edges.map((e) => e.id));
@@ -6398,6 +6680,8 @@ exports.registerDelayNode = registerDelayNode;
 exports.registerProgressNodes = registerProgressNodes;
 exports.setValueAtPath = setValueAtPath;
 exports.setValueAtPathWithCreation = setValueAtPathWithCreation;
+exports.stringifyJson = stringifyJson;
+exports.stringifySceneAndOps = stringifySceneAndOps;
 exports.typed = typed;
 exports.unwrapTypeId = unwrapTypeId;
 exports.unwrapValue = unwrapValue;