@rkmodules/rules 0.0.170 → 0.0.171

package/dist/index.esm.mjs

@@ -544,31 +544,6 @@ function toArray(a) {
     return Object.values(a).flat();
 }
 
-var getType = {
-    name: "getType",
-    label: "Get Type",
-    description: "Gets the type of a value as a string",
-    inputs: {
-        input: { type: "any" },
-    },
-    outputs: {
-        type: "string",
-    },
-    impl: function (inputs, params) { return __awaiter(void 0, void 0, void 0, function () {
-        return __generator(this, function (_a) {
-            return [2 /*return*/, {
-                    type: mapTree(inputs.input, function (x) {
-                        if (x === undefined)
-                            return "empty";
-                        if (x === null)
-                            return "empty";
-                        return typeof x;
-                    }),
-                }];
-        });
-    }); },
-};
-
 // utilities
 /**
  * merges two trees by concatenating the branches with the same path
@@ -640,6 +615,27 @@ function hasReference(value) {
 function parseReference(ref) {
     return ref.slice(1, -1);
 }
+/** Reference paths using the same literal-array and token rules as interpolation. */
+function getReferencePaths(value) {
+    var paths = new Set();
+    var visit = function (value) {
+        if (Array.isArray(value)) {
+            if (!value.every(Array.isArray))
+                value.forEach(visit);
+        }
+        else if (value && typeof value === "object") {
+            Object.values(value).forEach(visit);
+        }
+        else if (typeof value === "string") {
+            (value.match(/<.*?>/g) || []).forEach(function (token) {
+                if (isReference(token))
+                    paths.add(parseReference(token));
+            });
+        }
+    };
+    visit(value);
+    return __spreadArray([], __read(paths), false);
+}
 function uid$1() {
     return Math.random().toString(36).substring(2, 15);
 }
@@ -746,7 +742,200 @@ function interpolate(inputs, scope) {
     }));
 }
 
+// Bounds count entries, not bytes. Each location keeps only its last successful result.
+var MAX_SCOPES = 32;
+var MAX_ENTRIES = 1024;
+var cachePath = function (path) { return JSON.stringify(path); };
+function sameRecord(a, b) {
+    var keys = Object.keys(a);
+    var otherKeys = Object.keys(b);
+    return keys.length === otherKeys.length && keys.every(function (key, i) { return key === otherKeys[i] && Object.is(a[key], b[key]); });
+}
+function put(map, key, value) {
+    map.delete(key);
+    map.set(key, value);
+    if (map.size > MAX_ENTRIES)
+        map.delete(map.keys().next().value);
+}
+/** Engine-owned caches; execution state is carried explicitly across async boundaries. */
+var ExecutionCache = /** @class */ (function () {
+    function ExecutionCache() {
+        this.scopes = new Map();
+    }
+    ExecutionCache.prototype.begin = function (graph, options) {
+        var _a;
+        var cacheKey = (_a = options.cacheKey) !== null && _a !== void 0 ? _a : "";
+        var key = cachePath([graph, cacheKey]);
+        var scope = this.scopes.get(key);
+        if (!scope) {
+            scope = { graph: graph, cacheKey: cacheKey, generation: 0, run: 0,
+                interpolation: new Map(), pure: new Map(), preview: new Map() };
+        }
+        this.scopes.delete(key);
+        this.scopes.set(key, scope);
+        if (this.scopes.size > MAX_SCOPES) {
+            var oldest = this.scopes.keys().next().value;
+            this.scopes.get(oldest).generation++;
+            this.scopes.delete(oldest);
+        }
+        return { scope: scope, generation: scope.generation, run: ++scope.run,
+            options: __assign({}, options), visited: new Set() };
+    };
+    ExecutionCache.prototype.current = function (run) {
+        return run.generation === run.scope.generation && run.run === run.scope.run;
+    };
+    ExecutionCache.prototype.clear = function (options) {
+        var e_1, _a;
+        if (options === void 0) { options = {}; }
+        try {
+            for (var _b = __values(this.scopes.values()), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var scope = _c.value;
+                if (options.graph !== undefined && scope.graph !== options.graph)
+                    continue;
+                if (options.cacheKey !== undefined && scope.cacheKey !== options.cacheKey)
+                    continue;
+                // Pending runs may finish for their callers, but cannot refill cleared caches.
+                scope.generation++;
+                if (!options.kind || options.kind === "all") {
+                    scope.interpolation.clear();
+                    scope.pure.clear();
+                    scope.preview.clear();
+                }
+                else {
+                    scope[options.kind].clear();
+                }
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+    };
+    ExecutionCache.prototype.visit = function (run, path) {
+        run.visited.add(cachePath(path));
+    };
+    ExecutionCache.prototype.finish = function (run) {
+        var e_2, _a, e_3, _b;
+        if (!this.current(run))
+            return;
+        try {
+            for (var _c = __values([run.scope.interpolation, run.scope.pure, run.scope.preview]), _d = _c.next(); !_d.done; _d = _c.next()) {
+                var map = _d.value;
+                try {
+                    for (var _e = (e_3 = void 0, __values(map.keys())), _f = _e.next(); !_f.done; _f = _e.next()) {
+                        var key = _f.value;
+                        if (!run.visited.has(key))
+                            map.delete(key);
+                    }
+                }
+                catch (e_3_1) { e_3 = { error: e_3_1 }; }
+                finally {
+                    try {
+                        if (_f && !_f.done && (_b = _e.return)) _b.call(_e);
+                    }
+                    finally { if (e_3) throw e_3.error; }
+                }
+            }
+        }
+        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+        finally {
+            try {
+                if (_d && !_d.done && (_a = _c.return)) _a.call(_c);
+            }
+            finally { if (e_2) throw e_2.error; }
+        }
+    };
+    ExecutionCache.prototype.interpolate = function (run, path, raw, scope) {
+        var key = cachePath(path);
+        run.visited.add(key);
+        if (!this.current(run))
+            return interpolate(raw, scope);
+        var previous = run.scope.interpolation.get(key);
+        var ports = new Map();
+        var entries = Object.entries(raw).map(function (_a) {
+            var _b = __read(_a, 2), name = _b[0], value = _b[1];
+            // Deep references depend on the base tree's identity. Unrelated scope
+            // entries never invalidate this port; a fresh execution context is fine.
+            var old = previous === null || previous === void 0 ? void 0 : previous.ports.get(name);
+            var paths = old && Object.is(old.raw, value) ? old.paths :
+                getReferencePaths(value).map(function (path) { return path.split(".").slice(0, 2).join("."); });
+            var dependencies = paths.map(function (path) { return getValue$1(scope, path); });
+            var same = old && Object.is(old.raw, value) &&
+                old.dependencies.length === dependencies.length &&
+                dependencies.every(function (value, i) { return Object.is(value, old.dependencies[i]); });
+            var port = same ? old : {
+                raw: value,
+                paths: paths,
+                dependencies: dependencies,
+                tree: interpolate({ value: value }, scope).value,
+            };
+            ports.set(name, port);
+            return [name, port.tree];
+        });
+        var next = Object.fromEntries(entries);
+        var result = previous && sameRecord(previous.result, next) ? previous.result : next;
+        put(run.scope.interpolation, key, { ports: ports, result: result });
+        return result;
+    };
+    ExecutionCache.prototype.key = function (call) {
+        call.inputs; call.params; var metadata = __rest(call, ["inputs", "params"]);
+        return metadata;
+    };
+    ExecutionCache.prototype.get = function (run, path, kind, fn, call, inputs, params) {
+        var key = cachePath(path);
+        run.visited.add(key);
+        if (!this.current(run))
+            return;
+        var entry = run.scope[kind].get(key);
+        if (entry && entry.definition === fn && entry.impl === fn.impl &&
+            sameRecord(entry.metadata, this.key(call)) && sameRecord(entry.inputs, inputs) &&
+            sameRecord(entry.params, params)) {
+            put(run.scope[kind], key, entry);
+            return entry;
+        }
+    };
+    ExecutionCache.prototype.set = function (run, path, kind, fn, call, inputs, params, result, impl, createdAt) {
+        if (!this.current(run))
+            return;
+        var key = cachePath(path);
+        run.visited.add(key);
+        put(run.scope[kind], key, { definition: fn, impl: impl, metadata: this.key(call),
+            inputs: __assign({}, inputs), params: __assign({}, params), result: result, info: { kind: kind, createdAt: createdAt } });
+    };
+    return ExecutionCache;
+}());
+
+var getType = {
+    pure: true,
+    name: "getType",
+    label: "Get Type",
+    description: "Gets the type of a value as a string",
+    inputs: {
+        input: { type: "any" },
+    },
+    outputs: {
+        type: "string",
+    },
+    impl: function (inputs, params) { return __awaiter(void 0, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            return [2 /*return*/, {
+                    type: mapTree(inputs.input, function (x) {
+                        if (x === undefined)
+                            return "empty";
+                        if (x === null)
+                            return "empty";
+                        return typeof x;
+                    }),
+                }];
+        });
+    }); },
+};
+
 var getValue = {
+    pure: true,
     name: "getValue",
     label: "Get Value",
     description: "Get a value from an object at a specified path.",
@@ -777,6 +966,8 @@ var getValue = {
 };
 
 var log = {
+    // Logging is a required side effect, even when the data is unchanged.
+    pure: false,
     name: "log",
     label: "Log",
     description: "Logs the input data to the console",
@@ -801,6 +992,7 @@ var log = {
  * value primitive function
  */
 var value = {
+    pure: true,
     name: "value",
     label: "Value",
     description: "Outputs a constant value of a specified type",
@@ -852,6 +1044,7 @@ function isNumber() {
 }
 
 var add$1 = {
+    pure: true,
     name: "add",
     label: "Add",
     description: "Add two numbers or strings",
@@ -897,6 +1090,8 @@ function evaluate(expression, scope) {
  * TODO: need rank polymorhism on the tree item sizes
  */
 var calc = {
+    // Expressions can use randomness; failed evaluations also log diagnostics.
+    pure: false,
     name: "calc",
     label: "Calc",
     nodeType: "Calc",
@@ -1035,6 +1230,7 @@ function getUnboundSymbols(expr, scope, extraBound) {
 }
 
 var cosDeg = {
+    pure: true,
     name: "cosDeg",
     label: "Cosine",
     description: "Cosine of angle in degrees",
@@ -1058,6 +1254,7 @@ var cosDeg = {
 };
 
 var divide = {
+    pure: true,
     name: "divide",
     label: "Divide",
     description: "Divide two numbers",
@@ -1084,6 +1281,7 @@ var divide = {
 };
 
 var equalTo = {
+    pure: true,
     name: "equalTo",
     label: "Equal to",
     description: "Compare equal and not equal",
@@ -1114,6 +1312,7 @@ var equalTo = {
 };
 
 var greaterThan = {
+    pure: true,
     name: "greaterThan",
     label: "Greater Than",
     description: "Compare on greater than or greater than or equal to",
@@ -1144,6 +1343,7 @@ var greaterThan = {
 };
 
 var lessThan = {
+    pure: true,
     name: "lessThan",
     label: "Less Than",
     description: "Compare on less than or less than or equal to",
@@ -1174,6 +1374,7 @@ var lessThan = {
 };
 
 var modulo = {
+    pure: true,
     name: "modulo",
     label: "Modulo",
     description: "Division remainder of two numbers",
@@ -1198,6 +1399,7 @@ var modulo = {
 };
 
 var multiply = {
+    pure: true,
     name: "multiply",
     label: "Multiply",
     description: "Multiply two numbers",
@@ -1222,6 +1424,7 @@ var multiply = {
 };
 
 var pow = {
+    pure: true,
     name: "pow",
     label: "Power",
     description: "Power a number",
@@ -1246,6 +1449,7 @@ var pow = {
 };
 
 var sinDeg = {
+    pure: true,
     name: "sinDeg",
     label: "Sine",
     description: "Sine of angle in degrees",
@@ -1269,6 +1473,7 @@ var sinDeg = {
 };
 
 var sqrt = {
+    pure: true,
     name: "sqrt",
     label: "Square root",
     description: "Square root of a number",
@@ -1294,6 +1499,7 @@ var sqrt = {
 };
 
 var subtract$1 = {
+    pure: true,
     name: "subtract",
     label: "Subtract",
     description: "Subtract two numbers",
@@ -1318,6 +1524,7 @@ var subtract$1 = {
 };
 
 var tanDeg = {
+    pure: true,
     name: "tanDeg",
     label: "Tangent",
     description: "Tangent of angle in degrees",
@@ -1341,6 +1548,7 @@ var tanDeg = {
 };
 
 var ceil = {
+    pure: true,
     name: "ceil",
     label: "Round up",
     description: "Round a number up to the nearest integer",
@@ -1369,6 +1577,7 @@ var ceil = {
 };
 
 var floor = {
+    pure: true,
     name: "floor",
     label: "Round down",
     description: "Round a number down to the nearest integer",
@@ -1397,6 +1606,7 @@ var floor = {
 };
 
 var round = {
+    pure: true,
     name: "round",
     label: "Round",
     description: "Round a number to the nearest integer",
@@ -1425,6 +1635,7 @@ var round = {
 };
 
 var sum = {
+    pure: true,
     name: "sum",
     label: "Sum",
     description: "Sum of all items in a group",
@@ -1475,6 +1686,7 @@ var primitives$8 = (_a$8 = {},
     _a$8);
 
 var joinStrings = {
+    pure: true,
     name: "joinStrings",
     label: "Join Strings",
     description: "Join all strings in a group",
@@ -1503,6 +1715,7 @@ var joinStrings = {
 };
 
 var stringEqualTo = {
+    pure: true,
     name: "stringEqualTo",
     label: "String Equal to",
     description: "Compare string equal and not equal",
@@ -1529,6 +1742,7 @@ var stringEqualTo = {
 };
 
 var stringTemplate = {
+    pure: true,
     name: "stringTemplate",
     label: "String Template",
     description: "Assembles a string from inputs, use ${...} to interpolate inputs",
@@ -1568,6 +1782,7 @@ var stringTemplate = {
 };
 
 var toString = {
+    pure: true,
     name: "toString",
     label: "To String",
     description: "convert to string",
@@ -1599,6 +1814,7 @@ var primitives$7 = (_a$7 = {},
     _a$7);
 
 var filterList = {
+    pure: true,
     name: "filterList",
     label: "Filter List",
     description: "Filters the list by a boolean value",
@@ -1642,6 +1858,7 @@ var filterList = {
 };
 
 var listItem = {
+    pure: true,
     name: "listItem",
     label: "List Item",
     description: "Retrieve the items from the list at the specified indices",
@@ -1690,6 +1907,7 @@ var listItem = {
 };
 
 var listLength = {
+    pure: true,
     name: "listLength",
     label: "List Length",
     description: "Get the length of a list",
@@ -1711,6 +1929,7 @@ var listLength = {
 };
 
 var concat = {
+    pure: true,
     name: "concat",
     label: "Concat Lists",
     description: "Concatenates two lists back to back",
@@ -1737,6 +1956,7 @@ var concat = {
 };
 
 var relativeItem = {
+    pure: true,
     name: "relativeItem",
     label: "Relative Item",
     description: "Pairs each item in the tree with its next item",
@@ -1775,6 +1995,7 @@ var relativeItem = {
 };
 
 var relativeItems = {
+    pure: true,
     name: "relativeItems",
     label: "Relative Items",
     description: "Pairs each item in the tree with an item in another tree at a specified offset",
@@ -1820,6 +2041,7 @@ function isNumStr(str) {
     return !isNaN(Number(str));
 }
 var listInput = {
+    pure: true,
     name: "listInput",
     label: "List Input",
     description: "Input a list",
@@ -1860,6 +2082,7 @@ var listInput = {
 };
 
 var uniqueItems = {
+    pure: true,
     name: "uniqueItems",
     label: "Unique Items",
     description: "Removes duplicate items from a list",
@@ -1896,6 +2119,7 @@ var uniqueItems = {
 };
 
 var coalesce = {
+    pure: true,
     name: "coalesce",
     label: "Coalesce Items",
     description: "Outputs the first item if it's not empty, otherwise the second item",
@@ -1920,6 +2144,7 @@ var coalesce = {
 };
 
 var destructureList = {
+    pure: true,
     name: "destructureList",
     label: "Destructure List",
     description: "Separates an list into a part with the specified values and the rest",
@@ -1944,7 +2169,7 @@ var destructureList = {
                 var included = [];
                 var excluded = [];
                 var matches = [];
-                console.log("Destructuring list", list, items);
+                // console.log("Destructuring list", list, items);
                 list.forEach(function (value) {
                     var m = items.includes(value);
                     matches.push(m);
@@ -1990,6 +2215,7 @@ var primitives$6 = (_a$6 = {},
     _a$6);
 
 var splitGroup = {
+    pure: true,
     name: "splitGroup",
     label: "Split Group",
     description: "Splits every item of a group into its own group",
@@ -2009,6 +2235,7 @@ var splitGroup = {
 };
 
 var mergeGroup = {
+    pure: true,
     name: "mergeGroup",
     label: "Merge Group",
     description: "Merge the deepest groups into their parent.",
@@ -2034,6 +2261,7 @@ var mergeGroup = {
 };
 
 var cartesianGroups = {
+    pure: true,
     name: "cartesianGroups",
     label: "Cartesian Groups",
     description: "Duplicate groups such that all pairings are created.",
@@ -2073,6 +2301,7 @@ var cartesianGroups = {
 };
 
 var mergeTree = {
+    pure: true,
     name: "mergeTree",
     label: "Merge Tree",
     description: "Merge groups with the same index into a single tree.",
@@ -2101,6 +2330,7 @@ var mergeTree = {
 };
 
 var simplifyTree = {
+    pure: true,
     name: "simplifyTree",
     label: "Simplify Groups",
     description: "Simplify a tree by removing redundant groups.",
@@ -2123,6 +2353,7 @@ var simplifyTree = {
 };
 
 var groupAll = {
+    pure: true,
     name: "groupAll",
     label: "Group All",
     description: "Adds a group around all groups in the input tree",
@@ -2147,6 +2378,7 @@ var groupAll = {
 };
 
 var normalizeTree = {
+    pure: true,
     name: "normalizeTree",
     label: "Normalize Groups",
     description: "Normalize a tree to consequtive groups and removed empty groups.",
@@ -2176,6 +2408,7 @@ var normalizeTree = {
 };
 
 var filterTree = {
+    pure: true,
     name: "filterTree",
     label: "Filter Tree",
     description: "Filter groups by path matchers",
@@ -2221,6 +2454,7 @@ var filterTree = {
 };
 
 var treeItem = {
+    pure: true,
     name: "treeItem",
     label: "Tree Item",
     description: "Retrieve the groups from a tree at specified indexes",
@@ -2263,6 +2497,7 @@ var primitives$5 = (_a$5 = {},
     _a$5);
 
 var series = {
+    pure: true,
     name: "series",
     label: "Series",
     description: "Create a series of numbers.",
@@ -2303,6 +2538,7 @@ var primitives$4 = (_a$4 = {},
     _a$4);
 
 var booleanAnd = {
+    pure: true,
     name: "booleanAnd",
     label: "And",
     description: "Returns true if both of the items are true",
@@ -2326,6 +2562,7 @@ var booleanAnd = {
 };
 
 var booleanNot = {
+    pure: true,
     name: "booleanNot",
     label: "Not",
     description: "Inverts the input boolean value",
@@ -2348,6 +2585,7 @@ var booleanNot = {
 };
 
 var booleanOr = {
+    pure: true,
     name: "booleanOr",
     label: "Or",
     description: "Returns true if one of the items is true",
@@ -2371,6 +2609,7 @@ var booleanOr = {
 };
 
 var groupAnd = {
+    pure: true,
     name: "groupAnd",
     label: "Group and",
     description: "Returns true if all of the items in a group are true",
@@ -2400,6 +2639,7 @@ var groupAnd = {
 };
 
 var groupOr = {
+    pure: true,
     name: "groupOr",
     label: "Group or",
     description: "Returns true if any of the items in a group are true",
@@ -2429,6 +2669,7 @@ var groupOr = {
 };
 
 var groupStats = {
+    pure: true,
     name: "groupStats",
     label: "Group stats",
     description: "Returns statistics about a group of numbers",
@@ -2493,6 +2734,7 @@ var primitives$3 = (_a$3 = {},
     _a$3);
 
 var inputs = {
+    pure: true,
     name: "inputs",
     label: "Input",
     description: "Data input.",
@@ -2509,6 +2751,7 @@ var inputs = {
 };
 
 var output = {
+    pure: true,
     name: "output",
     label: "Output",
     description: "Data output.",
@@ -2529,6 +2772,7 @@ var primitives$2 = (_a$2 = {},
     _a$2);
 
 var mergeObject = {
+    pure: true,
     name: "mergeObject",
     label: "Merge Object",
     description: "Merges objects in groups",
@@ -2557,6 +2801,7 @@ var mergeObject = {
 };
 
 var object = {
+    pure: true,
     name: "object",
     label: "Object",
     description: "Creates an object",
@@ -2584,6 +2829,7 @@ var object = {
 };
 
 var listToArray = {
+    pure: true,
     name: "listToArray",
     label: "To Array",
     description: "Converts each branch to an array",
@@ -2606,6 +2852,7 @@ var listToArray = {
 };
 
 var objectEntries = {
+    pure: true,
     name: "objectEntries",
     label: "Entries",
     description: "Gets keys and pairs of an object",
@@ -2639,6 +2886,7 @@ var objectEntries = {
 };
 
 var arrayToList = {
+    pure: true,
     name: "arrayToList",
     label: "Array to List",
     description: "Separates array",
@@ -2667,6 +2915,7 @@ var arrayToList = {
 };
 
 var explodeObject = {
+    pure: true,
     name: "explodeObject",
     label: "Explode Object",
     description: "Separates all fields of an object",
@@ -2726,6 +2975,7 @@ var explodeObject = {
 };
 
 var setField = {
+    pure: true,
     name: "setField",
     label: "Set Field",
     description: "Sets a field in an object to a specified value.",
@@ -2765,6 +3015,7 @@ var setField = {
 };
 
 var destructureObject = {
+    pure: true,
     name: "destructureObject",
     label: "Destructure Object",
     description: "Separates an object into a part with the specified fields and the rest",
@@ -2834,6 +3085,8 @@ var primitives$1 = (_a$1 = {},
 var INFERRED = "inferred";
 var ary$1 = __spreadArray([INFERRED], __read(Intl.supportedValuesOf("timeZone")), false);
 var parseDate = {
+    // Empty values fall back to the clock; parsing also logs to the console.
+    pure: false,
     name: "parseDate",
     label: "Parse",
     description: "Parses a date string",
@@ -2871,6 +3124,8 @@ var parseDate = {
 
 var ary = Intl.supportedValuesOf("timeZone");
 var formatDate = {
+    // Empty values fall back to the clock; omitted options use host locale/timezone.
+    pure: false,
     name: "formatDate",
     label: "Format",
     description: "Formats a date",
@@ -2990,6 +3245,7 @@ var formatDate = {
 };
 
 var duration = {
+    pure: true,
     name: "duration",
     label: "Duration",
     description: "Creates a duration",
@@ -3030,6 +3286,8 @@ var duration = {
 };
 
 var isoDate = {
+    // Empty values fall back to the current clock.
+    pure: false,
     name: "isoDate",
     label: "To ISO",
     description: "ISO 8601 format of a date",
@@ -3055,6 +3313,8 @@ var isoDate = {
 };
 
 var today = {
+    // Reads the current clock on every evaluation.
+    pure: false,
     name: "today",
     label: "Today",
     description: "The date of today",
@@ -3121,31 +3381,49 @@ function normalizeVarDef(varDef) {
     return varDef;
 }
 function getReferences(inputs) {
-    var references = [];
-    Object.entries(inputs).forEach(function (_a) {
+    return Object.entries(inputs).flatMap(function (_a) {
         var _b = __read(_a, 2), name = _b[0], value = _b[1];
-        var values = Array.isArray(value) ? value : [value];
-        values.forEach(function (value) {
-            if (!isReference(value)) {
-                return;
-            }
-            var path = parseReference(value);
+        return getReferencePaths(value).map(function (path) {
             var parts = path.split(".");
-            references.push({
+            return {
                 name: name,
                 path: path,
                 parts: parts,
                 refNode: parts[0],
                 refField: parts.slice(1).join("."),
-            });
+            };
         });
     });
-    return references;
 }
-function topSort(fn) {
+function getExecutionOrder(fn) {
     var ordered = [];
     var visiting = new Set();
     var done = new Set();
+    var body = fn.body || {};
+    var nodeIds = new Map();
+    Object.keys(body).forEach(function (id) {
+        var referenceId = safeName(id);
+        if (referenceId === "inputs") {
+            throw new Error("Node ID \"".concat(id, "\" is reserved for graph inputs"));
+        }
+        if (nodeIds.has(referenceId)) {
+            throw new Error("Ambiguous node reference \"".concat(referenceId, "\": \"").concat(nodeIds.get(referenceId), "\" and \"").concat(id, "\""));
+        }
+        nodeIds.set(referenceId, id);
+    });
+    var resolve = function (ref, location) {
+        if (ref.parts.length < 2 || ref.parts.some(function (part) { return !part; })) {
+            throw new Error("Invalid reference <".concat(ref.path, "> in ").concat(location, ".").concat(ref.name));
+        }
+        // Public inputs can be supplied at runtime without static definitions.
+        if (ref.refNode === "inputs")
+            return;
+        var id = nodeIds.get(ref.refNode);
+        if (id === undefined) {
+            throw new Error("Reference <".concat(ref.path, "> in ").concat(location, ".").concat(ref.name, " points to missing node \"").concat(ref.refNode, "\""));
+        }
+        return id;
+    };
     var visit = function (id) {
         // if already done, return
         if (done.has(id))
@@ -3156,19 +3434,11 @@ function topSort(fn) {
         }
         // mark as visiting
         visiting.add(id);
-        var fnCall = fn.body[id];
-        if (!fnCall) {
-            console.warn("Function ".concat(id, " not found in body"), fn);
-        }
-        // check the inputs and visit them
-        Object.values(fnCall.inputs || {}).forEach(function (input) {
-            if (isReference(input)) {
-                var _a = __read(parseReference(input).split("."), 1), id_1 = _a[0];
-                // visit inputs
-                if (id_1 !== "inputs") {
-                    visit(id_1);
-                }
-            }
+        var fnCall = body[id];
+        getReferences(fnCall.inputs || {}).forEach(function (ref) {
+            var dependency = resolve(ref, "node \"".concat(id, "\" input"));
+            if (dependency !== undefined)
+                visit(dependency);
         });
         // push to end of the list
         ordered.push(id);
@@ -3177,7 +3447,12 @@ function topSort(fn) {
         // mark as done
         done.add(id);
     };
-    Object.keys(fn.body).forEach(visit);
+    Object.keys(body).forEach(visit);
+    getReferences(fn.outputs || {}).forEach(function (ref) { return resolve(ref, "output"); });
+    return ordered;
+}
+function topSort(fn) {
+    var ordered = getExecutionOrder(fn);
     var orderedBody = Object.fromEntries(ordered.map(function (id) { return [id, fn.body[id]]; }));
     return __assign(__assign({}, fn), { body: orderedBody });
 }
@@ -3189,41 +3464,161 @@ function getDefault(varDef, inputs) {
     }
     return normDef.default;
 }
+var removedReference = Symbol("removedReference");
+// Copy only containers that change, retaining unrelated values and references.
+// A removed standalone reference is omitted; in a template it becomes empty text.
+function removeReferences(value, matches) {
+    if (isReference(value)) {
+        return matches(value) ? removedReference : value;
+    }
+    if (typeof value === "string") {
+        return value.replace(/<.*?>/g, function (ref) {
+            return isReference(ref) && matches(ref) ? "" : ref;
+        });
+    }
+    if (Array.isArray(value)) {
+        var changed_1 = false;
+        var items_1 = [];
+        value.forEach(function (item) {
+            var next = removeReferences(item, matches);
+            if (next !== item)
+                changed_1 = true;
+            if (next !== removedReference)
+                items_1.push(next);
+        });
+        return changed_1 ? items_1 : value;
+    }
+    if (value && typeof value === "object") {
+        var prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null)
+            return value;
+        var changed_2 = false;
+        var entries_1 = [];
+        Object.entries(value).forEach(function (_a) {
+            var _b = __read(_a, 2), key = _b[0], item = _b[1];
+            var next = removeReferences(item, matches);
+            if (next !== item)
+                changed_2 = true;
+            if (next !== removedReference)
+                entries_1.push([key, next]);
+        });
+        return changed_2 ? Object.fromEntries(entries_1) : value;
+    }
+    return value;
+}
 var Engine = /** @class */ (function () {
     function Engine(morePrimitives, env) {
         if (morePrimitives === void 0) { morePrimitives = {}; }
         if (env === void 0) { env = {}; }
+        this.graphDefinitions = new WeakMap();
+        this.automaticMounts = new Map();
         this.listeners = {};
-        this.cache = {};
-        this.cacheMiss = Symbol("cacheMiss");
+        this.cache = new ExecutionCache();
+        this.graphRunners = new WeakMap();
+        this.executions = new WeakMap();
+        this.latestRuns = new WeakMap();
         this.context = null;
         this.fnIndex = __assign(__assign({}, primitives), morePrimitives);
         this.env = env;
     }
-    Engine.prototype.checkCache = function (fnName, inputs) {
-        if (!this.cache[fnName]) {
-            return this.cacheMiss;
-        }
-        // TODO: need to check the interpolated inputs, as the references can be the same
-        // however, the interpolation does create new objects
-        return {};
+    /** Clear successful results; running calls finish but cannot refill invalidated entries. */
+    Engine.prototype.clearCache = function (options) {
+        if (options === void 0) { options = {}; }
+        this.cache.clear(options);
     };
-    Engine.prototype.runGraph = function (node, inputs, params) {
+    Engine.prototype.executeCall = function (fn_1, call_1, inputs_1, params_1, context_1, name_1, executionId_1, run_1, path_1) {
+        return __awaiter(this, arguments, void 0, function (fn, call, inputs, params, context, name, executionId, run, path, root) {
+            var graphRunner, kind, hit, startTime, start, result, createdAt, impl, _a, endTime, event;
+            if (root === void 0) { root = false; }
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        this.cache.visit(run, path);
+                        graphRunner = this.graphRunners.get(fn);
+                        kind = graphRunner
+                            ? undefined
+                            : fn.pure
+                                ? "pure"
+                                : run.options.mode === "preview" && fn.previewCache
+                                    ? "preview"
+                                    : undefined;
+                        hit = kind
+                            ? this.cache.get(run, path, kind, fn, call, inputs, params)
+                            : undefined;
+                        startTime = performance.now();
+                        start = {
+                            name: name,
+                            fn: call.name,
+                            inputs: inputs,
+                            params: params,
+                            executionId: executionId,
+                            context: context,
+                            startTime: startTime,
+                        };
+                        if (!hit) return [3 /*break*/, 1];
+                        result = hit.result;
+                        createdAt = hit.info.createdAt;
+                        return [3 /*break*/, 8];
+                    case 1:
+                        context.activations[name] = true;
+                        impl = fn.impl;
+                        console.log("Executing function call: ".concat(name));
+                        _b.label = 2;
+                    case 2:
+                        _b.trys.push([2, , 7, 8]);
+                        this.fireEvent("functionCall", start);
+                        if (!graphRunner) return [3 /*break*/, 4];
+                        return [4 /*yield*/, graphRunner(inputs, params, run, path)];
+                    case 3:
+                        _a = (_b.sent()).result;
+                        return [3 /*break*/, 6];
+                    case 4: return [4 /*yield*/, impl.call(fn, inputs, params, this, root ? null : context, name)];
+                    case 5:
+                        _a = _b.sent();
+                        _b.label = 6;
+                    case 6:
+                        result = _a;
+                        createdAt = Date.now();
+                        if (kind)
+                            this.cache.set(run, path, kind, fn, call, inputs, params, result, impl, createdAt);
+                        return [3 /*break*/, 8];
+                    case 7:
+                        context.activations[name] = false;
+                        context.timings[name] = performance.now() - startTime;
+                        return [7 /*endfinally*/];
+                    case 8:
+                        endTime = performance.now();
+                        context.activations[name] = false;
+                        context.timings[name] = endTime - startTime;
+                        context.scope[name] = result;
+                        event = __assign(__assign({}, start), { result: result, endTime: endTime, duration: endTime - startTime, cached: !!hit, cache: kind ? { kind: kind, createdAt: createdAt } : undefined });
+                        // Hits still notify subscribers and populate a fresh context for the editor.
+                        this.fireEvent("functionResult", event);
+                        return [2 /*return*/, event];
+                }
+            });
+        });
+    };
+    Engine.prototype.runGraph = function (node, suppliedInputs, params, executionOrder, run, path) {
         return __awaiter(this, void 0, void 0, function () {
-            var _a, body, executionId, context, startTime, _b, _c, _d, _i, name_1, fnCall, fn, inputs_1, params_1, result_1, cacheResult, startTime_1, endTime_1, result, endTime, response;
-            return __generator(this, function (_e) {
-                switch (_e.label) {
+            var _a, body, executionId, defaults, mappedDefaults, inputs, context, startTime, executionOrder_1, executionOrder_1_1, name_1, fnCall, fn, callPath, inputs_1, params_1, e_1_1, result, endTime, response;
+            var e_1, _b;
+            return __generator(this, function (_c) {
+                switch (_c.label) {
                     case 0:
                         _a = node.body, body = _a === void 0 ? {} : _a;
                         executionId = uid$1();
-                        // add input defaults
+                        defaults = {};
                         Object.entries(node.inputs || {}).forEach(function (_a) {
                             var _b = __read(_a, 2), name = _b[0], def = _b[1];
                             var normDef = normalizeVarDef(def);
-                            if (inputs[name] === undefined && normDef.default !== undefined) {
-                                inputs[name] = getDefault(normDef, inputs);
+                            if (suppliedInputs[name] === undefined &&
+                                normDef.default !== undefined) {
+                                defaults[name] = getDefault(normDef, suppliedInputs);
                             }
                         });
+                        mappedDefaults = this.cache.interpolate(run, __spreadArray(__spreadArray([], __read(path), false), ["$defaults"], false), defaults, {});
+                        inputs = __assign(__assign({}, suppliedInputs), mappedDefaults);
                         context = {
                             scope: { inputs: inputs },
                             calls: {},
@@ -3232,76 +3627,46 @@ var Engine = /** @class */ (function () {
                             timings: {},
                             activations: {},
                         };
+                        this.executions.set(context, { run: run, path: path });
                         startTime = performance.now();
-                        _b = body;
-                        _c = [];
-                        for (_d in _b)
-                            _c.push(_d);
-                        _i = 0;
-                        _e.label = 1;
+                        _c.label = 1;
                     case 1:
-                        if (!(_i < _c.length)) return [3 /*break*/, 5];
-                        _d = _c[_i];
-                        if (!(_d in _b)) return [3 /*break*/, 4];
-                        name_1 = _d;
+                        _c.trys.push([1, 6, 7, 8]);
+                        executionOrder_1 = __values(executionOrder), executionOrder_1_1 = executionOrder_1.next();
+                        _c.label = 2;
+                    case 2:
+                        if (!!executionOrder_1_1.done) return [3 /*break*/, 5];
+                        name_1 = executionOrder_1_1.value;
                         fnCall = body[name_1];
                         fn = this.fnIndex[fnCall.name];
-                        if (!fn) {
+                        if (!fn)
                             throw new Error("function ".concat(fnCall.name, " not found in index"));
-                        }
-                        inputs_1 = interpolate(fnCall.inputs || {}, context.scope);
+                        callPath = __spreadArray(__spreadArray([], __read(path), false), [name_1], false);
+                        inputs_1 = this.cache.interpolate(run, __spreadArray(__spreadArray([], __read(callPath), false), ["$inputs"], false), fnCall.inputs || {}, context.scope);
                         params_1 = fnCall.params || {};
-                        result_1 = {};
                         context.calls[name_1] = fnCall;
                         context.inputs[name_1] = inputs_1;
                         context.params[name_1] = params_1;
-                        cacheResult = this.checkCache(name_1, inputs_1);
-                        if (!(cacheResult !== this.cacheMiss)) return [3 /*break*/, 2];
-                        // use as result
-                        result_1 = cacheResult;
-                        // store the result in the scope
-                        context.scope[name_1] = result_1;
-                        return [3 /*break*/, 4];
-                    case 2:
-                        // cache miss, call the function implementation
-                        context.activations[name_1] = true;
-                        startTime_1 = performance.now();
-                        this.fireEvent("functionCall", {
-                            name: name_1,
-                            fn: fnCall.name,
-                            inputs: inputs_1,
-                            params: params_1,
-                            executionId: executionId,
-                            context: context,
-                            startTime: startTime_1,
-                        });
-                        return [4 /*yield*/, fn.impl(inputs_1, params_1, this, context, name_1)];
+                        return [4 /*yield*/, this.executeCall(fn, fnCall, inputs_1, params_1, context, name_1, executionId, run, callPath)];
                     case 3:
-                        // call the implentation of sub functions
-                        result_1 = _e.sent();
-                        endTime_1 = performance.now();
-                        context.activations[name_1] = false;
-                        context.timings[name_1] = endTime_1 - startTime_1;
-                        // store the result in the scope
-                        context.scope[name_1] = result_1;
-                        this.fireEvent("functionResult", {
-                            name: name_1,
-                            fn: fnCall.name,
-                            inputs: inputs_1,
-                            params: params_1,
-                            executionId: executionId,
-                            context: context,
-                            result: result_1,
-                            startTime: startTime_1,
-                            endTime: endTime_1,
-                            duration: endTime_1 - startTime_1,
-                        });
-                        _e.label = 4;
+                        _c.sent();
+                        _c.label = 4;
                     case 4:
-                        _i++;
-                        return [3 /*break*/, 1];
-                    case 5:
-                        result = interpolate(node.outputs || {}, context.scope);
+                        executionOrder_1_1 = executionOrder_1.next();
+                        return [3 /*break*/, 2];
+                    case 5: return [3 /*break*/, 8];
+                    case 6:
+                        e_1_1 = _c.sent();
+                        e_1 = { error: e_1_1 };
+                        return [3 /*break*/, 8];
+                    case 7:
+                        try {
+                            if (executionOrder_1_1 && !executionOrder_1_1.done && (_b = executionOrder_1.return)) _b.call(executionOrder_1);
+                        }
+                        finally { if (e_1) throw e_1.error; }
+                        return [7 /*endfinally*/];
+                    case 8:
+                        result = this.cache.interpolate(run, __spreadArray(__spreadArray([], __read(path), false), ["$outputs"], false), node.outputs || {}, context.scope);
                         endTime = performance.now();
                         response = {
                             name: node.name,
@@ -3337,6 +3702,16 @@ var Engine = /** @class */ (function () {
             return node;
         }
         var _a = node.body, body = _a === void 0 ? {} : _a, props = __rest(node, ["body"]);
+        // Validate before registering or mounting, preserving the last working
+        // definition if an edit introduces a broken reference or cycle.
+        var executionOrder = getExecutionOrder(node);
+        executionOrder.forEach(function (id) {
+            var call = body[id];
+            if (!Object.prototype.hasOwnProperty.call(_this.fnIndex, call.name) ||
+                !_this.fnIndex[call.name]) {
+                throw new Error("function ".concat(call.name, " not found in index (node \"").concat(id, "\")"));
+            }
+        });
         // create a primitive function, one that has an implementation and optional mounting function
         var primitive = __assign(__assign({}, props), { outputs: Object.fromEntries(Object.entries(node.outputs || {}).map(function (_a) {
                 var _b = __read(_a, 2), key = _b[0]; _b[1];
@@ -3344,8 +3719,9 @@ var Engine = /** @class */ (function () {
             })), mount: function (trigger) {
                 // mount all the nodes
                 var unsubs = [];
-                Object.values(body).forEach(function (n) {
+                executionOrder.forEach(function (id) {
                     var _a;
+                    var n = body[id];
                     var fn = _this.fnIndex[n.name];
                     if (!fn) {
                         console.warn("function ".concat(n.name, " not found in index"));
@@ -3357,7 +3733,7 @@ var Engine = /** @class */ (function () {
                     }
                 });
                 return function () {
-                    var e_1, _a;
+                    var e_2, _a;
                     try {
                         // console.log(`Unmounting function: ${node.name}`);
                         // unmount all the nodes
@@ -3366,35 +3742,48 @@ var Engine = /** @class */ (function () {
                             unsub();
                         }
                     }
-                    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+                    catch (e_2_1) { e_2 = { error: e_2_1 }; }
                     finally {
                         try {
                             if (unsubs_1_1 && !unsubs_1_1.done && (_a = unsubs_1.return)) _a.call(unsubs_1);
                         }
-                        finally { if (e_1) throw e_1.error; }
+                        finally { if (e_2) throw e_2.error; }
                     }
                 };
-            }, impl: function (inputs, params, engine) { return __awaiter(_this, void 0, void 0, function () {
-                var response;
+            }, impl: function (inputs, params, engine, context, name) { return __awaiter(_this, void 0, void 0, function () {
+                var parent, run, path, response;
                 return __generator(this, function (_a) {
                     switch (_a.label) {
-                        case 0: return [4 /*yield*/, engine.runGraph(node, inputs, params)];
+                        case 0:
+                            parent = context && engine.executions.get(context);
+                            run = (parent === null || parent === void 0 ? void 0 : parent.run) || engine.cache.begin(node.name, {});
+                            path = parent ? __spreadArray(__spreadArray([], __read(parent.path), false), [name], false) : ["_root"];
+                            return [4 /*yield*/, engine.runGraph(node, inputs, params, executionOrder, run, path)];
                         case 1:
                             response = _a.sent();
+                            if (!parent)
+                                engine.cache.finish(run);
                             return [2 /*return*/, response.result];
                     }
                 });
             }); } });
+        this.graphRunners.set(primitive, function (inputs, params, run, path) {
+            return _this.runGraph(node, inputs, params, executionOrder, run, path);
+        });
         // register the primitive
         this.fnIndex[primitive.name] = primitive;
+        this.graphDefinitions.set(primitive, node);
         return primitive;
     };
-    Engine.prototype.mount = function (node) {
+    Engine.prototype.mount = function (node, inputs, options) {
         var _this = this;
         var _a;
+        if (inputs === void 0) { inputs = {}; }
+        if (options === void 0) { options = {}; }
         return (_a = node.mount) === null || _a === void 0 ? void 0 : _a.call(node, function () {
-            // console.log(`Triggering node: ${node.name}`);
-            _this.run(node);
+            var _a, _b;
+            var latest = _this.latestRuns.get(node);
+            void _this.run(node, (_a = latest === null || latest === void 0 ? void 0 : latest.inputs) !== null && _a !== void 0 ? _a : inputs, (_b = latest === null || latest === void 0 ? void 0 : latest.options) !== null && _b !== void 0 ? _b : options);
         });
     };
     Engine.prototype.getContext = function () {
@@ -3413,138 +3802,188 @@ var Engine = /** @class */ (function () {
         };
     };
     Engine.prototype.fireEvent = function (eventName, event) {
-        var e_2, _a;
+        var e_3, _a;
         try {
             for (var _b = __values(this.listeners[eventName] || []), _c = _b.next(); !_c.done; _c = _b.next()) {
                 var listener = _c.value;
                 listener(event);
             }
         }
-        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+        catch (e_3_1) { e_3 = { error: e_3_1 }; }
         finally {
             try {
                 if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
             }
-            finally { if (e_2) throw e_2.error; }
+            finally { if (e_3) throw e_3.error; }
         }
     };
     Engine.prototype.run = function (node_1) {
-        return __awaiter(this, arguments, void 0, function (node, inputs) {
-            var builtFn, mappedInputs, result;
+        return __awaiter(this, arguments, void 0, function (node, inputs, options) {
+            if (inputs === void 0) { inputs = {}; }
+            if (options === void 0) { options = {}; }
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, this.runDetailed(node, inputs, options)];
+                    case 1: return [2 /*return*/, (_a.sent()).result];
+                }
+            });
+        });
+    };
+    Engine.prototype.runDetailed = function (node_1) {
+        return __awaiter(this, arguments, void 0, function (node, inputs, options) {
+            var builtFn, rebuilt, mounted, unmount, run, mappedInputs, runner, response, context;
             var _a;
             if (inputs === void 0) { inputs = {}; }
+            if (options === void 0) { options = {}; }
             return __generator(this, function (_b) {
                 switch (_b.label) {
                     case 0:
                         if (!isPrimitive(node)) {
                             builtFn = this.getFunction(node.name);
-                            if (!builtFn) {
-                                // not yet build
+                            rebuilt = false;
+                            // Graphs are edited immutably: the name identifies a registry slot,
+                            // while object identity tells us whether its definition is current.
+                            if (!builtFn || this.graphDefinitions.get(builtFn) !== node) {
                                 builtFn = this.build(node);
-                                // mount if needed
-                                this.mount(builtFn);
+                                rebuilt = true;
                             }
-                            return [2 /*return*/, this.run(builtFn, inputs)];
+                            mounted = this.automaticMounts.get(node.name);
+                            if (rebuilt || (mounted && mounted.fn !== builtFn)) {
+                                // Only replace subscriptions owned by run(); explicit mount()
+                                // callers retain ownership of their cleanup callbacks.
+                                (_a = mounted === null || mounted === void 0 ? void 0 : mounted.unmount) === null || _a === void 0 ? void 0 : _a.call(mounted);
+                                this.automaticMounts.delete(node.name);
+                                unmount = this.mount(builtFn);
+                                this.automaticMounts.set(node.name, {
+                                    fn: builtFn,
+                                    unmount: unmount || undefined,
+                                });
+                            }
+                            node = builtFn;
                         }
-                        mappedInputs = interpolate(inputs, {});
-                        return [4 /*yield*/, ((_a = node.impl) === null || _a === void 0 ? void 0 : _a.call(node, mappedInputs, {}, this, null, "_root"))];
+                        this.latestRuns.set(node, { inputs: inputs, options: __assign({}, options) });
+                        run = this.cache.begin(node.name, options);
+                        mappedInputs = this.cache.interpolate(run, ["$inputs"], inputs, {});
+                        runner = this.graphRunners.get(node);
+                        if (!runner) return [3 /*break*/, 2];
+                        return [4 /*yield*/, runner(mappedInputs, {}, run, ["_root"])];
                     case 1:
-                        result = _b.sent();
-                        // console.log("Engine run complete", result);
-                        return [2 /*return*/, result];
+                        response = _b.sent();
+                        return [3 /*break*/, 4];
+                    case 2:
+                        context = {
+                            scope: { inputs: mappedInputs },
+                            calls: { _root: { name: node.name } },
+                            inputs: { _root: mappedInputs },
+                            params: { _root: {} },
+                            timings: {},
+                            activations: {},
+                        };
+                        return [4 /*yield*/, this.executeCall(node, context.calls._root, mappedInputs, {}, context, "_root", uid$1(), run, ["_root"], true)];
+                    case 3:
+                        response = _b.sent();
+                        response = __assign(__assign({}, response), { name: node.name, fn: "root" });
+                        this.fireEvent("result", response);
+                        this.context = context;
+                        _b.label = 4;
+                    case 4:
+                        this.cache.finish(run);
+                        return [2 /*return*/, response];
                 }
             });
         });
     };
-    Engine.prototype.runDetailed = function (node_1) {
-        return __awaiter(this, arguments, void 0, function (node, inputs) {
-            var _this = this;
-            if (inputs === void 0) { inputs = {}; }
-            return __generator(this, function (_a) {
-                return [2 /*return*/, new Promise(function (resolve, reject) {
-                        var unsub = _this.subscribe("result", function (event) {
-                            if (event.name === node.name) {
-                                resolve(event);
-                                unsub();
-                            }
-                        });
-                        _this.run(node, inputs).catch(function (e) {
-                            unsub();
-                            reject(e);
-                        });
-                    })];
-            });
-        });
-    };
     Engine.prototype.getFunction = function (name) {
         return this.fnIndex[name];
     };
     // node handlers
     Engine.prototype.applyNodeDelete = function (oldFn, nodeIds) {
-        var newFn = __assign(__assign({}, oldFn), { body: __assign({}, oldFn.body) });
-        if (nodeIds.every(function (id) { return id === "output"; })) {
-            // cannot delete output node
+        var deletedIds = new Set(nodeIds.filter(function (id) { return id !== "output"; }));
+        if (!deletedIds.size) {
+            // The generated output node is protected, including in bulk deletes.
             return oldFn;
         }
-        if (nodeIds.includes("inputs")) {
+        var newFn = __assign(__assign({}, oldFn), { body: __assign({}, oldFn.body) });
+        if (deletedIds.has("inputs")) {
             delete newFn.inputs;
         }
-        nodeIds.forEach(function (id) {
+        deletedIds.forEach(function (id) {
             delete newFn.body[id];
         });
-        // remove any references to the deleted nodes
+        var matches = function (ref) {
+            return deletedIds.has(parseReference(ref).split(".")[0]);
+        };
+        // Clone affected nodes as well as their inputs so shallow comparisons work.
         Object.entries(newFn.body).forEach(function (_a) {
             var _b = __read(_a, 2), id = _b[0], node = _b[1];
-            Object.entries(node.inputs || {}).forEach(function (_a) {
-                var _b;
-                var _c = __read(_a, 2), name = _c[0], value = _c[1];
-                if (isReference(value)) {
-                    var path = parseReference(value);
-                    var parts = path.split(".");
-                    if (nodeIds.includes(parts[0])) {
-                        (_b = newFn.body[id].inputs) === null || _b === void 0 ? true : delete _b[name];
-                    }
+            if (!node.inputs)
+                return;
+            var inputs = removeReferences(node.inputs, matches);
+            if (inputs !== node.inputs) {
+                newFn.body[id] = __assign(__assign({}, node), { inputs: inputs });
+            }
+        });
+        Object.entries(oldFn.outputs || {}).forEach(function (_a) {
+            var _b = __read(_a, 2), name = _b[0], value = _b[1];
+            var next = removeReferences(value, matches);
+            if (next !== value) {
+                if (newFn.outputs === oldFn.outputs) {
+                    newFn.outputs = __assign({}, oldFn.outputs);
                 }
-            });
+                // Keep the public port, matching explicit output-edge deletion.
+                newFn.outputs[name] = next === removedReference ? "" : next;
+            }
         });
         return newFn;
     };
     Engine.prototype.applyEdgeDelete = function (oldFn, fromNode, toNode, fromField, toField) {
         var _a, _b;
-        var newFn = __assign(__assign({}, oldFn), { body: __assign({}, oldFn.body), outputs: __assign({}, oldFn.outputs) });
+        var _c, _d, _e;
+        var matches = function (ref) { return ref === "<".concat(fromNode, ".").concat(fromField, ">"); };
         if (toNode === "output") {
-            // deleting of output edges
-            if ((_a = newFn.outputs) === null || _a === void 0 ? void 0 : _a[toField]) {
-                // set to empty to prevent port from being removed, as that would cause the output node to be deleted
-                newFn.outputs[toField] = "";
-            }
-            return newFn;
-        }
-        var to = newFn.body[toNode];
+            var value_1 = (_c = oldFn.outputs) === null || _c === void 0 ? void 0 : _c[toField];
+            if (value_1 === undefined)
+                return oldFn;
+            var next_1 = removeReferences(value_1, matches);
+            if (next_1 === value_1)
+                return oldFn;
+            return __assign(__assign({}, oldFn), { outputs: __assign(__assign({}, oldFn.outputs), (_a = {}, _a[toField] = next_1 === removedReference ? "" : next_1, _a)) });
+        }
+        var to = oldFn.body[toNode];
         var fn = this.fnIndex[to === null || to === void 0 ? void 0 : to.name];
         if (!to) {
             console.warn("Invalid nodes for edge deletion");
-            return newFn;
+            return oldFn;
         }
         if (!fn) {
             console.warn("Function ".concat(to === null || to === void 0 ? void 0 : to.name, " not found in index, which is unexpected as you are deleting an edge to it."));
-            return newFn;
+            return oldFn;
+        }
+        var value = (_d = to.inputs) === null || _d === void 0 ? void 0 : _d[toField];
+        if (value === undefined) {
+            console.warn("No matching edge found to delete");
+            return oldFn;
         }
-        if (to.inputs && to.inputs[toField] === "<".concat(fromNode, ".").concat(fromField, ">")) {
-            // delete the incoming edge
-            delete to.inputs[toField];
+        var next = removeReferences(value, matches);
+        if (next === value) {
+            console.warn("No matching edge found to delete");
+            return oldFn;
+        }
+        var inputs = __assign({}, to.inputs);
+        if (next === removedReference) {
+            delete inputs[toField];
             // revert to default value if exists
-            if ((_b = fn.inputs) === null || _b === void 0 ? void 0 : _b[toField]) {
+            if ((_e = fn.inputs) === null || _e === void 0 ? void 0 : _e[toField]) {
                 var normDef = normalizeVarDef(fn.inputs[toField]);
                 if (normDef.default !== undefined) {
-                    to.inputs[toField] = getDefault(normDef, to.inputs);
+                    inputs[toField] = getDefault(normDef, inputs);
                 }
             }
         }
         else {
-            console.warn("No matching edge found to delete");
+            inputs[toField] = next;
         }
-        return newFn;
+        return __assign(__assign({}, oldFn), { body: __assign(__assign({}, oldFn.body), (_b = {}, _b[toNode] = __assign(__assign({}, to), { inputs: inputs }), _b)) });
     };
     Engine.prototype.applyNodeAdd = function (oldFn, nodeName, callback) {
         var newFn = __assign(__assign({}, oldFn), { body: __assign({}, oldFn.body) });
@@ -3591,25 +4030,20 @@ var Engine = /** @class */ (function () {
         return topSort(newFn);
     };
     Engine.prototype.applyNodeConnect = function (oldFn, fromNode, toNode, fromField, toField) {
-        var _a;
+        var _a, _b;
         var newFn = __assign(__assign({}, oldFn), { body: __assign({}, oldFn.body) });
         if (toNode === "output") {
             newFn.outputs = __assign(__assign({}, oldFn.outputs), (_a = {}, _a[toField] = "<".concat(fromNode, ".").concat(fromField, ">"), _a));
             // no need to sort, as only output has changed
             return newFn;
         }
-        // const from = newFn.body[fromNode];
-        var to = __assign({}, newFn.body[toNode]);
+        var to = oldFn.body[toNode];
         if (!to) {
             console.warn("Invalid nodes for connection");
-            return newFn;
-        }
-        if (!to.inputs) {
-            to.inputs = {};
+            return oldFn;
         }
-        // add the reference
-        to.inputs[toField] = "<".concat(fromNode, ".").concat(fromField, ">");
-        newFn.body[toNode] = to;
+        // Copy the inputs before assigning: copying only the node still aliases them.
+        newFn.body[toNode] = __assign(__assign({}, to), { inputs: __assign(__assign({}, to.inputs), (_b = {}, _b[toField] = "<".concat(fromNode, ".").concat(fromField, ">"), _b)) });
         return topSort(newFn);
     };
     return Engine;
@@ -6743,9 +7177,10 @@ function GenericNode(_a) {
     var paramEntries = Object.entries(params || data.paramDefs || {});
     var engine = useEngine();
     var _e = __read(React.useState({}), 2), result = _e[0], setResult = _e[1];
-    var _f = __read(React.useState(null), 2), duration = _f[0], setDuration = _f[1];
-    var _g = __read(useInner(((_c = outputEntries[0]) === null || _c === void 0 ? void 0 : _c[0]) || null, [outputs, data.outputDefs]), 2), focus = _g[0], setFocus = _g[1];
-    var _h = __read(React.useState(false), 2), showPreview = _h[0], setShowPreview = _h[1];
+    var _f = __read(React.useState(), 2), cache = _f[0], setCache = _f[1];
+    var _g = __read(React.useState(null), 2), duration = _g[0], setDuration = _g[1];
+    var _h = __read(useInner(((_c = outputEntries[0]) === null || _c === void 0 ? void 0 : _c[0]) || null, [outputs, data.outputDefs]), 2), focus = _h[0], setFocus = _h[1];
+    var _j = __read(React.useState(false), 2), showPreview = _j[0], setShowPreview = _j[1];
     var previewValue = focus ? result[focus] : Object.values(result)[0];
     React.useEffect(function () {
         return engine.subscribe("functionResult", function (event) {
@@ -6753,9 +7188,10 @@ function GenericNode(_a) {
             if (event.name === id) {
                 setResult(event.result || {});
                 setDuration((_a = event.duration) !== null && _a !== void 0 ? _a : null);
+                setCache(event.cached ? event.cache : undefined);
             }
         });
-    }, []);
+    }, [engine, id]);
     return (React.createElement(NodeContainer, { label: data.label, selected: selected, id: id, className: (_d = data.nodeProps) === null || _d === void 0 ? void 0 : _d.className },
         React.createElement("div", { className: styles$1.Description }, data.description),
         children,
@@ -6777,9 +7213,10 @@ function GenericNode(_a) {
                 _b)), onClick: function () { return setShowPreview(!showPreview); } }, "Preview")),
         showPreview && (React.createElement("div", { className: styles$1.Preview },
             React.createElement(TreeView, { value: previewValue }),
-            duration !== null && (React.createElement("div", { className: styles$1.Duration },
-                duration.toFixed(2),
-                " ms"))))));
+            duration !== null && (React.createElement("div", { className: styles$1.Duration }, cache ? (React.createElement("span", { title: "Result computed ".concat(new Date(cache.createdAt).toLocaleString()) },
+                cache.kind === "preview" ? "Cached preview" : "Cached",
+                " · ",
+                new Date(cache.createdAt).toLocaleTimeString())) : "".concat(duration.toFixed(2), " ms")))))));
 }
 
 var math = create(all, {});
@@ -7845,44 +8282,58 @@ function useDraggableNode(name, itemProps) {
     return function (ref) { return drag(ref); };
 }
 
-/**
- * using functions
- *
- * in React context
- * - use useFunction. This will build the function, mount it if needed and provides a run function.
- *
- *
- * in Vanilla context
- * - use engine.build(fn) to build the function
- * - use engine.mount(fn) to mount the function (if it has a mount function)
- * - use await engine.run(fn, inputs) to run the function and get the result
+/** Build a graph, optionally subscribe to triggers, and retain the latest run inputs.
+ * Preview caching requires { mode: "preview" }; refresh clears external preview
+ * results for this graph/session and reruns with the latest inputs.
  */
-function useFunction(engine, fn, mount) {
+function useFunction(engine, fn, mount, options) {
     var _this = this;
-    var _a = __read(React.useState(null), 2), result = _a[0], setResult = _a[1];
-    var builtFn = React.useMemo(function () { return engine.build(fn); }, [fn]);
+    if (options === void 0) { options = {}; }
+    var _a = options.mode, mode = _a === void 0 ? "normal" : _a, _b = options.cacheKey, cacheKey = _b === void 0 ? "" : _b;
+    var _c = __read(React.useState(null), 2), result = _c[0], setResult = _c[1];
+    var builtFn = React.useMemo(function () { return engine.build(fn); }, [engine, fn]);
+    var latestInputs = React.useRef({});
+    var sequence = React.useRef(0);
+    var currentDefinition = React.useRef(builtFn);
+    currentDefinition.current = builtFn;
+    var run = React.useCallback(function () {
+        var args_1 = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args_1[_i] = arguments[_i];
+        }
+        return __awaiter(_this, __spreadArray([], __read(args_1), false), void 0, function (inputs) {
+            var request, result;
+            if (inputs === void 0) { inputs = latestInputs.current; }
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        latestInputs.current = inputs;
+                        request = ++sequence.current;
+                        return [4 /*yield*/, engine.run(builtFn, inputs, { mode: mode, cacheKey: cacheKey })];
+                    case 1:
+                        result = _a.sent();
+                        if (request === sequence.current && currentDefinition.current === builtFn) {
+                            setResult(result);
+                        }
+                        return [2 /*return*/, result];
+                }
+            });
+        });
+    }, [engine, builtFn, mode, cacheKey]);
+    var latestRun = React.useRef(run);
+    latestRun.current = run;
     React.useEffect(function () {
+        var _a;
         if (mount) {
-            return engine.mount(builtFn);
+            // Keep this hook's inputs/options even when another editor shares the engine.
+            return (_a = builtFn.mount) === null || _a === void 0 ? void 0 : _a.call(builtFn, function () { void latestRun.current(); });
         }
     }, [builtFn, mount]);
-    var run = React.useCallback(function (inputs) { return __awaiter(_this, void 0, void 0, function () {
-        var result;
-        return __generator(this, function (_a) {
-            switch (_a.label) {
-                case 0: return [4 /*yield*/, engine.run(builtFn, inputs)];
-                case 1:
-                    result = _a.sent();
-                    setResult(result);
-                    return [2 /*return*/, result];
-            }
-        });
-    }); }, [builtFn]);
-    return React.useMemo(function () { return ({
-        fn: builtFn,
-        run: run,
-        result: result,
-    }); }, [builtFn, run, result]);
+    var refresh = React.useCallback(function () {
+        engine.clearCache({ kind: "preview", graph: fn.name, cacheKey: cacheKey });
+        return run();
+    }, [engine, fn.name, cacheKey, run]);
+    return React.useMemo(function () { return ({ fn: builtFn, run: run, refresh: refresh, result: result }); }, [builtFn, run, refresh, result]);
 }
 
 // cheap lodash replacements
@@ -8868,5 +9319,5 @@ function DDContext(_a) {
     return React.createElement(DndProvider, { backend: HTML5Backend }, children);
 }
 
-export { DDContext, DISCARD, Engine, Flow, FlowContext, GenericNode, Input, InputBoolean, InputNumber, InputSelect, InputString, InputText, Lib, Output, Param, binaryOnTree, binaryOnTreeBranch, broadCast, deRefEdgeHandle, ensureBranch, expandTree, forEachBranch, forEachItem, getBranch, getBranches, getItem, getPaths, getPositions, getReferences, getValue$1 as getValue, getVariable, graftTree, hasReference, interpolate, isEmpty, isEmptyTree, isList, isMultiBranch, isReference, isSingleTon, isTree, mapTree, mapTreeBranch, mergeWithOrder, nAryOnTree, nAryOnTreeBranch, normalizePaths, normalizeVarDef, parseReference, primitives, pushItem, safeName, sameShape, simplifyTree$1 as simplifyTree, toArray, topSort, treeSize, treeStats, trimTree, uid$1 as uid, useControls, useDraggableNode, useEngine, useFlow, useFunction, useGraphedFunction, usePositions, usePrompts, useUpdatePositions, useVariable, variableStore };
+export { DDContext, DISCARD, Engine, Flow, FlowContext, GenericNode, Input, InputBoolean, InputNumber, InputSelect, InputString, InputText, Lib, Output, Param, binaryOnTree, binaryOnTreeBranch, broadCast, deRefEdgeHandle, ensureBranch, expandTree, forEachBranch, forEachItem, getBranch, getBranches, getItem, getPaths, getPositions, getReferencePaths, getReferences, getValue$1 as getValue, getVariable, graftTree, hasReference, interpolate, isEmpty, isEmptyTree, isList, isMultiBranch, isReference, isSingleTon, isTree, mapTree, mapTreeBranch, mergeWithOrder, nAryOnTree, nAryOnTreeBranch, normalizePaths, normalizeVarDef, parseReference, primitives, pushItem, safeName, sameShape, simplifyTree$1 as simplifyTree, toArray, topSort, treeSize, treeStats, trimTree, uid$1 as uid, useControls, useDraggableNode, useEngine, useFlow, useFunction, useGraphedFunction, usePositions, usePrompts, useUpdatePositions, useVariable, variableStore };
 //# sourceMappingURL=index.esm.mjs.map