@field/cascade 0.10.0 → 0.12.0

package/dist/cli/chunk-CTPLRSWF.js

@@ -0,0 +1,2197 @@
+import {
+  expressionEngine
+} from "./chunk-RUU3YWXU.js";
+import {
+  resolvePropBinding
+} from "./chunk-HFHWYL55.js";
+import {
+  bundleFieldReferences,
+  deleteKey,
+  deserializeChannel,
+  isEmptyChannel,
+  serializeChannel,
+  setKey
+} from "./chunk-CO22XHNG.js";
+import {
+  CORE_TYPES,
+  canConnectTypes,
+  normalizeCascadeType
+} from "./chunk-FWMSGKEH.js";
+
+// src/utils/nodeTypeUtils.ts
+var nodeClassRegistries = /* @__PURE__ */ new Map();
+var nodeMetadataRegistry = /* @__PURE__ */ new Map();
+function registerNodeMetadata(metadata) {
+  nodeMetadataRegistry.set(metadata.type, metadata);
+}
+function getNodeMetadata(type) {
+  if (nodeMetadataRegistry.has(type)) {
+    return nodeMetadataRegistry.get(type) || null;
+  }
+  const shortType = packagePathToType(type);
+  if (nodeMetadataRegistry.has(shortType)) {
+    return nodeMetadataRegistry.get(shortType) || null;
+  }
+  return null;
+}
+function getNodeDisplayName(type) {
+  const metadata = getNodeMetadata(type);
+  if (metadata?.name) {
+    return metadata.name;
+  }
+  return packagePathToType(type);
+}
+function registerNodeClasses(libraryId, classes) {
+  const existing = nodeClassRegistries.get(libraryId);
+  nodeClassRegistries.set(libraryId, existing ? { ...existing, ...classes } : classes);
+}
+function typeToPackagePath(type) {
+  if (type.includes(".")) {
+    return type;
+  }
+  for (const [libraryId, classes] of nodeClassRegistries) {
+    if (type in classes) {
+      return `cascade.${libraryId}.${type}`;
+    }
+  }
+  return type;
+}
+function packagePathToType(packagePath) {
+  if (!packagePath.includes(".")) {
+    return packagePath;
+  }
+  const parts = packagePath.split(".");
+  return parts[parts.length - 1];
+}
+function isStandardLibraryNode(type) {
+  return type.includes(".") && type.startsWith("cascade.");
+}
+function getLibraryIdFromType(type) {
+  if (!type.includes(".")) {
+    return null;
+  }
+  const parts = type.split(".");
+  if (parts.length >= 2 && parts[0] === "cascade") {
+    return parts[1];
+  }
+  return null;
+}
+function getNodeClass(type) {
+  const libraryId = getLibraryIdFromType(type);
+  const nodeType = packagePathToType(type);
+  if (!libraryId) {
+    return null;
+  }
+  const registry = nodeClassRegistries.get(libraryId);
+  if (registry && registry[nodeType]) {
+    return registry[nodeType];
+  }
+  return null;
+}
+
+// src/utils/colorUtils.ts
+function normalizeColor(input) {
+  if (typeof input === "object" && !Array.isArray(input) && "r" in input && "g" in input && "b" in input) {
+    const obj = input;
+    const isNormalized = obj.r <= 1 && obj.g <= 1 && obj.b <= 1;
+    return {
+      r: isNormalized ? obj.r : obj.r / 255,
+      g: isNormalized ? obj.g : obj.g / 255,
+      b: isNormalized ? obj.b : obj.b / 255,
+      a: obj.a !== void 0 ? isNormalized ? obj.a : obj.a / 255 : 1
+    };
+  }
+  if (Array.isArray(input)) {
+    const isNormalized = input.every((v) => v <= 1);
+    return {
+      r: isNormalized ? input[0] : input[0] / 255,
+      g: isNormalized ? input[1] : input[1] / 255,
+      b: isNormalized ? input[2] : input[2] / 255,
+      a: input[3] !== void 0 ? isNormalized ? input[3] : input[3] / 255 : 1
+    };
+  }
+  if (typeof input === "string") {
+    const rgbMatch = input.match(/rgb\s*\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\)/);
+    if (rgbMatch) {
+      return {
+        r: parseInt(rgbMatch[1], 10) / 255,
+        g: parseInt(rgbMatch[2], 10) / 255,
+        b: parseInt(rgbMatch[3], 10) / 255,
+        a: 1
+      };
+    }
+    const hex = input.replace("#", "");
+    if (hex.length === 3 || hex.length === 6) {
+      const expanded = hex.length === 3 ? hex.split("").map((c) => c + c).join("") : hex;
+      const result = /^([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(expanded);
+      if (result) {
+        return {
+          r: parseInt(result[1], 16) / 255,
+          g: parseInt(result[2], 16) / 255,
+          b: parseInt(result[3], 16) / 255,
+          a: 1
+        };
+      }
+    }
+  }
+  return { r: 0, g: 0, b: 0, a: 1 };
+}
+function isColorValue(value) {
+  if (typeof value === "string") {
+    return value.startsWith("#") || value.startsWith("rgb(");
+  }
+  if (typeof value === "object" && value !== null) {
+    if ("r" in value && "g" in value && "b" in value) {
+      return true;
+    }
+    if (Array.isArray(value) && (value.length === 3 || value.length === 4)) {
+      return value.every((v) => typeof v === "number");
+    }
+  }
+  return false;
+}
+
+// src/types/coreTypes.ts
+var CORE_TYPES2 = CORE_TYPES;
+var CORE_SET = new Set(CORE_TYPES2);
+function isCoreType(type) {
+  return CORE_SET.has(type);
+}
+var normalizeType = normalizeCascadeType;
+function canConnect(fromType, toType) {
+  return canConnectTypes(fromType, toType);
+}
+
+// src/utils/thrownError.ts
+function asError(thrown) {
+  if (thrown instanceof Error) return thrown;
+  const described = describeThrown(thrown);
+  const error = new Error(described);
+  error.cause = thrown;
+  return error;
+}
+function describeThrown(thrown) {
+  if (thrown === null) return "null was thrown";
+  if (thrown === void 0) return "undefined was thrown";
+  if (typeof thrown === "string") return thrown || "an empty string was thrown";
+  if (typeof thrown !== "object") return `${String(thrown)} was thrown`;
+  const value = thrown;
+  const kind = typeof value.name === "string" && value.name ? value.name : value.constructor?.name || "object";
+  const parts = [];
+  if (typeof value.message === "string" && value.message) parts.push(value.message);
+  if (typeof value.reason === "string" && value.reason) parts.push(`reason: ${value.reason}`);
+  if (!parts.length) {
+    try {
+      const json = JSON.stringify(thrown);
+      if (json && json !== "{}") parts.push(json);
+    } catch {
+    }
+  }
+  return parts.length ? `${kind}: ${parts.join(", ")}` : `${kind} was thrown with no message`;
+}
+
+// src/nodes/outputEquality.ts
+function sameOutputValue(previous, next, budget = 2e6) {
+  const state = { remaining: budget };
+  return same(previous, next, state, true);
+}
+function sameBundleField(previous, next, budget = 2e6) {
+  return same(previous, next, { remaining: budget }, false);
+}
+function isPlain(value) {
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null || proto === Array.prototype;
+}
+function same(a, b, state, top) {
+  if (--state.remaining < 0) return false;
+  if (a === null || b === null || typeof a !== "object" || typeof b !== "object") {
+    if (typeof a === "function" || typeof b === "function") return false;
+    return Object.is(a, b);
+  }
+  if (a === b && (top || ArrayBuffer.isView(a) || !isPlain(a))) return false;
+  if (ArrayBuffer.isView(a) || ArrayBuffer.isView(b)) {
+    if (!ArrayBuffer.isView(a) || !ArrayBuffer.isView(b)) return false;
+    if (a.constructor !== b.constructor || a.byteLength !== b.byteLength) return false;
+    state.remaining -= a.byteLength / 8;
+    if (state.remaining < 0) return false;
+    const x2 = new Uint8Array(a.buffer, a.byteOffset, a.byteLength);
+    const y2 = new Uint8Array(b.buffer, b.byteOffset, b.byteLength);
+    for (let i = 0; i < x2.length; i++) if (x2[i] !== y2[i]) return false;
+    return true;
+  }
+  if (!isPlain(a) || !isPlain(b)) return false;
+  const arrayA = Array.isArray(a);
+  if (arrayA !== Array.isArray(b)) return false;
+  if (arrayA) {
+    const x2 = a;
+    const y2 = b;
+    if (x2.length !== y2.length) return false;
+    for (let i = 0; i < x2.length; i++) if (!same(x2[i], y2[i], state, false)) return false;
+    return true;
+  }
+  const x = a;
+  const y = b;
+  const keys = Object.keys(x);
+  if (keys.length !== Object.keys(y).length) return false;
+  for (const key of keys) {
+    if (!Object.prototype.hasOwnProperty.call(y, key)) return false;
+    if (!same(x[key], y[key], state, false)) return false;
+  }
+  return true;
+}
+
+// src/nodes/inputFingerprint.ts
+var identities = /* @__PURE__ */ new WeakMap();
+var nextIdentity = 1;
+var identityOf = (value) => identities.get(value) ?? (identities.set(value, nextIdentity), nextIdentity++);
+function hashBytes(view) {
+  const length = view.byteLength;
+  let words;
+  if ((view.byteOffset | length) & 3) {
+    const padded = new Uint8Array(length + 3 & ~3);
+    padded.set(new Uint8Array(view.buffer, view.byteOffset, length));
+    words = new Int32Array(padded.buffer);
+  } else {
+    words = new Int32Array(view.buffer, view.byteOffset, length >> 2);
+  }
+  let a = 2166136261 ^ length, b = 2654435769, c = 2246822507, d = 3266489909;
+  const count = words.length;
+  const blocks = count & ~3;
+  for (let i = 0; i < blocks; i += 4) {
+    a = Math.imul(a ^ words[i], 16777619);
+    a = a << 13 | a >>> 19;
+    b = Math.imul(b ^ words[i + 1], 1540483477);
+    b = b << 13 | b >>> 19;
+    c = Math.imul(c ^ words[i + 2], 16777619);
+    c = c << 13 | c >>> 19;
+    d = Math.imul(d ^ words[i + 3], 1540483477);
+    d = d << 13 | d >>> 19;
+  }
+  for (let i = blocks; i < count; i++) {
+    a = Math.imul(a ^ words[i], 16777619);
+    a = a << 13 | a >>> 19;
+  }
+  return [a, b, c, d].map((lane) => (lane >>> 0).toString(36)).join(".");
+}
+var hashingReplacer = (_key, item) => ArrayBuffer.isView(item) ? `#${hashBytes(item)}` : item;
+function valueFingerprint(value) {
+  const type = typeof value;
+  if (value == null || type !== "object" && type !== "function") return `${type}:${String(value)}`;
+  const object = value;
+  const channels = object.channels;
+  if (Array.isArray(channels) && channels.every((channel) => ArrayBuffer.isView(channel))) {
+    return `${object.width}x${object.height}:${object.colorSpace}:${channels.map(hashBytes).join(",")}`;
+  }
+  let json;
+  try {
+    json = JSON.stringify(object, hashingReplacer);
+  } catch {
+    json = `#${identityOf(object)}`;
+  }
+  const proto = Object.getPrototypeOf(object);
+  const content = proto === Object.prototype || proto === null || Array.isArray(object) || ArrayBuffer.isView(object);
+  return content ? `json:${json}` : `obj#${identityOf(object)}:${json}`;
+}
+
+// src/nodes/Node.ts
+function inferParamType(value) {
+  if (typeof value === "number") return Number.isInteger(value) ? "int" : "float";
+  if (typeof value === "boolean") return "bool";
+  if (typeof value === "string") return "string";
+  if (Array.isArray(value) && value.every((v) => typeof v === "number")) {
+    if (value.length === 2) return "vec2";
+    if (value.length === 3) return "vec3";
+    if (value.length === 4) return "vec4";
+  }
+  return "any";
+}
+function paramControlType(dataType) {
+  switch (normalizeType(dataType ?? "any")) {
+    case "int":
+      return "int";
+    case "float":
+      return "number";
+    case "bool":
+      return "boolean";
+    case "string":
+      return "text";
+    case "color":
+      return "color";
+    case "vec2":
+      return "vec2";
+    case "vec3":
+      return "vec3";
+    case "vec4":
+      return "vec4";
+    default:
+      return void 0;
+  }
+}
+var PROP_CONTROL_TO_DATA_TYPE = {
+  number: "float",
+  slider: "float",
+  range: "float",
+  float: "float",
+  int: "int",
+  text: "string",
+  textarea: "string",
+  string: "string",
+  select: "string",
+  boolean: "bool",
+  bool: "bool",
+  vector: "vec3"
+};
+function carryType(type) {
+  if (!type) return "any";
+  return normalizeType(PROP_CONTROL_TO_DATA_TYPE[type] ?? type);
+}
+var NUMERIC_CARRY = /* @__PURE__ */ new Set(["int", "float"]);
+function carryTypesMatch(before, after) {
+  if (before === "any" || after === "any") return true;
+  if (NUMERIC_CARRY.has(before) && NUMERIC_CARRY.has(after)) return true;
+  return before === after;
+}
+function sameStoredValue(a, b) {
+  if (a === b) return true;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((item, index) => sameStoredValue(item, b[index]));
+  }
+  if (isPlainRecord(a) && isPlainRecord(b)) {
+    const keys = Object.keys(a);
+    if (keys.length !== Object.keys(b).length) return false;
+    return keys.every((key) => key in b && sameStoredValue(a[key], b[key]));
+  }
+  return typeof a === "number" && typeof b === "number" && Number.isNaN(a) && Number.isNaN(b);
+}
+function isPlainRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+var Node = class _Node {
+  constructor(id, type, graph) {
+    // Ports - available to all nodes
+    this.inputs = [];
+    this.outputs = [];
+    // Props system
+    this.props = {};
+    this.propWatchers = /* @__PURE__ */ new Map();
+    // Actions system - button-triggered callbacks
+    this.actions = {};
+    // Variadic inputs
+    /** The node's own values — see param(). Distinct from `props`, which is the
+     *  older image-node control system. */
+    this.parameters = [];
+    this.parametersUsedDuringSetup = /* @__PURE__ */ new Set();
+    /**
+     * Props the node's own code declared with `addParm()`, and which its cook may
+     * therefore read as `this.props.name.value`.
+     *
+     * A prop restored from a document is NOT in here until the code that owns it
+     * has run, which for any on-demand-compiled module is after the first cook
+     * has begun. See evaluateAllExpressions for why that distinction has to be
+     * made rather than assumed.
+     */
+    this.propsDeclaredByCode = /* @__PURE__ */ new Set();
+    /** Non-null between a retarget and the cook that resolves it. */
+    this.carryOver = null;
+    /** The last completed reconciliation, for a panel that arrives after the fact. */
+    this.lastCarryOverReport = null;
+    this.variadic = false;
+    this.variadicDefault = null;
+    this.variadicOptions = {};
+    // Visual
+    this.preview = null;
+    // Metadata
+    this.comment = "";
+    this.error = null;
+    this.warning = null;
+    // Computation-specific
+    this.code = "";
+    this.bypass = false;
+    this.cook = false;
+    // Path system - hierarchical node organization
+    this.parent = null;
+    /**
+     * Child parameters this node shows as its own — Houdini's promoted
+     * parameters.
+     *
+     * Marcus, 2026-09-09, on where a force's settings should live: *"keep the
+     * force settings on the inside, but allow to promote parameters to the level
+     * above with 1 click."*
+     *
+     * **This is presentation, not state.** The value stays on the child and there
+     * is exactly one of it; the container only says which ones to show. The
+     * alternative — a real parameter on the container that writes through — would
+     * be a second copy of the value, a resolution order between the two, and a
+     * way for them to disagree. Props already carry a value, an expression and a
+     * channel with an order between them; doing it again for promotion is the
+     * mistake this avoids.
+     *
+     * Which is also why the runtime ignores this field entirely. Nothing about a
+     * cook changes when a parameter is promoted, so a headless render and a
+     * Studio session cannot diverge over it.
+     */
+    this.promotions = [];
+    this._children = [];
+    // ============ Early cutoff ============
+    /**
+     * Whether this node may be skipped when it is stale only because something
+     * upstream re-cooked and every input came back identical.
+     *
+     * On by default. A node whose result depends on something other than its
+     * inputs and its own parameters — the clock, a file it reads behind the
+     * graph's back, a random draw it wants fresh each time — sets this false, or
+     * marks itself dirty when that other thing changes (which is the better fix,
+     * and what time-dependent expressions already do).
+     */
+    this.earlyCutoff = true;
+    /** Per output port: bumped whenever a committed value is not provably the
+     *  same as the last one. What downstream nodes compare instead of values. */
+    this.outputVersions = /* @__PURE__ */ new Map();
+    /** Set when this node itself was invalidated (a parameter, its code, a
+     *  connection), as opposed to only being downstream of something that was.
+     *  A self-dirty node always cooks. */
+    this.selfDirty = true;
+    /** The input versions this node last cooked cleanly against, or null. */
+    this.cutoffKey = null;
+    /**
+     * Per bundle output: a version per field, plus an epoch bumped whenever a
+     * change could not be attributed to fields (an output the cook did not set,
+     * the same object committed twice). A consumer that declares the fields it
+     * reads compares these instead of the port's version, so a change to one
+     * field does not re-cook the consumers of the others.
+     */
+    this.bundleFieldVersions = /* @__PURE__ */ new Map();
+    // Execution state
+    this.hasExecuted = false;
+    this.lastInputHash = "";
+    /** The inputs an execute threw on, or null if the last cook did not throw.
+     *  Read only by `isDirty` — see the comment there for why it exists. */
+    this.failedInputHash = null;
+    /**
+     * The abort controllers for cooks currently in flight.
+     *
+     * A set rather than one, for the same reason `stagingStack` is a stack: two
+     * cooks can overlap, and the one that finishes first must not cancel the
+     * other. Aborted together on invalidation, because an invalidation
+     * invalidates every version of this node's work rather than the newest.
+     */
+    this.cookAborts = /* @__PURE__ */ new Set();
+    this.cookState = "stale";
+    this.cookGeneration = 0;
+    /**
+     * Output values staged by the cook currently running, one map per cook.
+     *
+     * A stack rather than a field, because it was a field and that was a race.
+     * `stagedOutputs` was instance state created per cook, iterated under a
+     * `generation === this.cookGeneration` guard, and nulled in `finally` — but
+     * `cookGeneration` only advances in `invalidateCook()`, and `cook()` has no
+     * re-entrancy guard. So two overlapping cooks of the same node with no
+     * invalidation between them both ran at the same generation: the second's
+     * `finally` nulled the field, the first resumed, passed the generation check
+     * because nothing had invalidated it, and iterated `null` —
+     * `stagedOutputs is not iterable`.
+     *
+     * Worse than the crash, and the reason this is a correctness fix rather than
+     * a robustness one: the second cook's `new Map()` **replaced the first's
+     * mid-flight**, so the first cook's staged writes were lost whenever the
+     * timing did not happen to produce the throw.
+     *
+     * The underlying fault is that per-cook state lived on the instance, and the
+     * thing protecting it (the generation) was not the thing destroying it (the
+     * `finally`) — two mechanisms guarding one field, neither aware of the other.
+     * Each cook now owns its own map, holds it locally, and removes it **by
+     * identity**, so an interleaving cannot make one cook drop another's.
+     *
+     * Diagnosed by MW-OBSERVATORY-ART, 2026-09-08.
+     */
+    this.stagingStack = [];
+    this.executionTimeout = 3e4;
+    // Cook info - performance tracking
+    this.cookInfo = {
+      lastCookTime: 0,
+      totalCookTime: 0,
+      cookCount: 0,
+      averageCookTime: 0,
+      lastCookTimestamp: 0,
+      peakMemory: 0
+    };
+    // Time dependency tracking (for expression engine)
+    this.isTimeDependent = false;
+    // Port tracking for cleanup
+    this.portsUsedDuringSetup = /* @__PURE__ */ new Set();
+    // Port index map for O(1) lookups (portId -> port)
+    this._portMap = /* @__PURE__ */ new Map();
+    // ============ Props System ============
+    /**
+     * Add a parameter to this node
+     * Short alias for defineProp - use in setup()
+     */
+    /** Props whose declared default expression has already been applied — see
+     *  `bindParameterProp`, which must not reinstate one the author deleted. */
+    this.defaultExpressionsApplied = /* @__PURE__ */ new Set();
+    /** Props whose plain stored value explicitly overrides a declared default
+     *  expression. The marker survives even when that value equals the default. */
+    this.plainPropOverrides = /* @__PURE__ */ new Set();
+    /**
+     * A container that a declaration said is one.
+     *
+     * Set by `attachDefinition` from `definition.container`, because `isNetwork`
+     * was a class override and a definition-v1 node is a plain `Node` — so a
+     * `cascade.core.Subnet` created through the adapter reported `false` and
+     * nothing that asks could tell it was a subnet.
+     *
+     * Marcus, 2026-09-09, hitting both symptoms of that at once: *"double
+     * clicking on the node goes to the code view ... not the subnet ... also the
+     * i and o keys are not doing anything."* Two features, one cause — the
+     * double-click handler and the i/o shortcuts both gate on `isNetwork()`, and
+     * both were correct code asking a question that could only ever answer no.
+     */
+    this.declaredContainer = null;
+    this.id = id;
+    this.type = type;
+    this.graph = graph;
+    this.position = { x: 0, y: 0 };
+    if (this.constructor !== _Node) {
+      this.setup();
+      queueMicrotask(() => {
+        if (this.onReady) {
+          try {
+            this.onReady();
+          } catch (err) {
+            console.error(`Error in onReady for node ${this.id}:`, err);
+          }
+        }
+      });
+    }
+  }
+  /** Is this child parameter shown on the parent? */
+  isPromotedToParent(param) {
+    return (this.parent?.promotions ?? []).some(
+      (entry) => entry.nodeId === this.id && entry.param === param
+    );
+  }
+  /**
+   * One click, both directions.
+   *
+   * A no-op without a parent rather than an error: the button is only rendered
+   * for a child, and a guard that throws would turn a stale UI into a crash.
+   */
+  setPromotedToParent(param, promoted) {
+    const parent = this.parent;
+    if (!parent) return;
+    const index = parent.promotions.findIndex(
+      (entry) => entry.nodeId === this.id && entry.param === param
+    );
+    if (promoted && index < 0) parent.promotions.push({ nodeId: this.id, param });
+    else if (!promoted && index >= 0) parent.promotions.splice(index, 1);
+  }
+  /** @internal The version of one output, for downstream cutoff. */
+  outputVersion(portId) {
+    return this.outputVersions.get(portId) ?? 0;
+  }
+  bumpOutputVersion(portId) {
+    this.outputVersions.set(portId, (this.outputVersions.get(portId) ?? 0) + 1);
+    const fields = this.bundleFieldVersions.get(portId);
+    if (fields) fields.epoch += 1;
+  }
+  /** @internal The version of one field of a bundle output. */
+  outputFieldVersion(portId, field) {
+    const entry = this.bundleFieldVersions.get(portId);
+    return entry ? `${entry.epoch}.${entry.fields.get(field) ?? 0}` : `0.0`;
+  }
+  /** Bump the versions of the fields a bundle commit changed. */
+  bumpBundleFields(portId, previous, next) {
+    let entry = this.bundleFieldVersions.get(portId);
+    if (!entry) {
+      entry = { epoch: 0, fields: /* @__PURE__ */ new Map() };
+      this.bundleFieldVersions.set(portId, entry);
+    }
+    const prev = previous !== null && typeof previous === "object" ? previous : null;
+    const curr = next !== null && typeof next === "object" ? next : null;
+    if (!prev || !curr || prev === curr) {
+      entry.epoch += 1;
+      return;
+    }
+    const has = Object.prototype.hasOwnProperty;
+    for (const field of /* @__PURE__ */ new Set([...Object.keys(prev), ...Object.keys(curr)])) {
+      const changed = has.call(prev, field) !== has.call(curr, field) || !sameBundleField(prev[field], curr[field]);
+      if (changed) entry.fields.set(field, (entry.fields.get(field) ?? 0) + 1);
+    }
+  }
+  /**
+   * The fields of a bundle input this node depends on, or null for the whole
+   * bundle. Declared by the node (`fieldSelection`), plus whatever its
+   * parameter expressions read through `ch("port.field")`. A node that does
+   * not declare its fields may read any of them, so it depends on all.
+   */
+  bundleFieldsRead(input) {
+    if (input.dataType !== "bundle" || !input.options?.fieldSelection) return null;
+    const fields = new Set(input.options.fieldSelection);
+    for (const prop of Object.values(this.props)) {
+      if (!prop?.expression) continue;
+      for (const reference of bundleFieldReferences(prop.expression))
+        if (reference.port === input.name) fields.add(reference.field);
+    }
+    return [...fields].sort();
+  }
+  /** @internal The scheduler calls this on the node an invalidation started at. */
+  markSelfDirty() {
+    this.selfDirty = true;
+  }
+  /** What every input currently comes from, as upstream output versions. Null
+   *  when an input comes from something that keeps no versions (an annotation),
+   *  which disables the cutoff for this node. */
+  inputVersionKey() {
+    const parts = [];
+    for (const input of this.inputs) {
+      if (input.connections.length === 0) {
+        parts.push(`${input.id}=${valueFingerprint(input.value)}`);
+        continue;
+      }
+      const fields = this.bundleFieldsRead(input);
+      for (const connection of input.connections) {
+        const upstream = this.graph.getNode(connection.from.nodeId);
+        if (!upstream) return null;
+        const source = `${input.id}<${connection.from.nodeId}:${connection.from.portId}`;
+        parts.push(fields ? `${source}{${fields.map((field) => `${field}@${upstream.outputFieldVersion(connection.from.portId, field)}`).join(",")}}` : `${source}@${upstream.outputVersion(connection.from.portId)}`);
+      }
+    }
+    return parts.join("|");
+  }
+  /**
+   * @internal Early cutoff: true when this node is stale only transitively,
+   * cooked cleanly last time, and every upstream output it reads still has the
+   * version it cooked against — i.e. the upstream re-cook produced the same
+   * values. Skipping it then is exact, and the nodes below it see unchanged
+   * versions in turn, so the whole subgraph stays cached.
+   */
+  canSkipCook() {
+    if (!this.earlyCutoff || this.selfDirty || !this.hasExecuted) return false;
+    if (this.cutoffKey === null || this.error !== null) return false;
+    if (!this.nodeFunction && this.onCook === _Node.prototype.onCook) return false;
+    return this.inputVersionKey() === this.cutoffKey;
+  }
+  /** @internal Mark clean without cooking; see `canSkipCook`. */
+  skipCook() {
+    this.setCookState("clean");
+  }
+  /** The owning graph's document `seed`, which `context.seed` derives from. */
+  get documentSeed() {
+    return this.graph?.seed;
+  }
+  // ============ Port Creation ============
+  in(name, defaultValue, options = {}) {
+    const portType = name === "trigger" ? "trigger" : "param";
+    const existingPort = this.inputs.find((p) => p.name === name);
+    if (existingPort) {
+      this.portsUsedDuringSetup.add(`input_${name}`);
+      if (options.type) existingPort.dataType = options.type;
+      if (defaultValue !== void 0 && existingPort.defaultValue !== defaultValue) {
+        existingPort.defaultValue = defaultValue;
+        if (existingPort.value === void 0 || existingPort.value === existingPort.defaultValue) {
+          existingPort.value = defaultValue;
+        }
+      }
+      existingPort.options = Object.assign(existingPort.options ?? {}, options);
+      return existingPort;
+    }
+    const portIndex = this.inputs.length;
+    const port = {
+      id: `${this.id}_in_${portIndex}`,
+      name,
+      portType,
+      dataType: options.type || "any",
+      value: defaultValue,
+      defaultValue,
+      options,
+      connections: []
+    };
+    this.inputs.push(port);
+    this._portMap.set(port.id, port);
+    this.portsUsedDuringSetup.add(`input_${name}`);
+    return port;
+  }
+  /**
+   * Declare an output port. Takes the same `options` as `in()` — an output that
+   * cannot state its type is a hole in the type system: the connection check
+   * only ever sees `any` on one side, and the port draws in the neutral colour
+   * whatever it actually carries.
+   */
+  out(name, portType = "param", options = {}) {
+    const existingPort = this.outputs.find((p) => p.name === name);
+    if (existingPort) {
+      this.portsUsedDuringSetup.add(`output_${name}`);
+      if (existingPort.portType !== portType) existingPort.portType = portType;
+      if (options.type) existingPort.dataType = options.type;
+      existingPort.options = { ...existingPort.options ?? {}, ...options };
+      return existingPort;
+    }
+    const portIndex = this.outputs.length;
+    const port = {
+      id: `${this.id}_out_${portIndex}`,
+      name,
+      portType,
+      dataType: options.type || "any",
+      value: void 0,
+      connections: [],
+      options,
+      setValue: (value) => this.setOutputValue(port, value),
+      trigger: (props) => {
+        port.connections.forEach((conn) => {
+          const targetNode = this.graph.getNode(conn.to.nodeId);
+          if (targetNode) {
+            const targetPort = targetNode.getInputPortById(conn.to.portId);
+            if (targetPort && targetPort.onTrigger) targetPort.onTrigger(props);
+          }
+        });
+      }
+    };
+    this.outputs.push(port);
+    this._portMap.set(port.id, port);
+    this.portsUsedDuringSetup.add(`output_${name}`);
+    return port;
+  }
+  // ============ Port Access ============
+  getInputPort(index) {
+    return index >= 0 && index < this.inputs.length ? this.inputs[index] : null;
+  }
+  getOutputPort(index) {
+    return index >= 0 && index < this.outputs.length ? this.outputs[index] : null;
+  }
+  /** Update the element id and every derived port id as one operation. */
+  renameId(newId) {
+    const oldId = this.id;
+    const renamed = /* @__PURE__ */ new Map();
+    this.id = newId;
+    this._portMap.clear();
+    for (const port of [...this.inputs, ...this.outputs]) {
+      const oldPortId = port.id;
+      port.id = oldPortId.startsWith(`${oldId}_`) ? `${newId}${oldPortId.slice(oldId.length)}` : oldPortId;
+      renamed.set(oldPortId, port.id);
+      this._portMap.set(port.id, port);
+    }
+    return renamed;
+  }
+  getPort(portId) {
+    return this._portMap.get(portId) || null;
+  }
+  getInputPortById(portId) {
+    const port = this._portMap.get(portId);
+    return port && "defaultValue" in port ? port : null;
+  }
+  setOutputValue(port, value) {
+    const staging = this.stagingStack[this.stagingStack.length - 1];
+    if (staging) {
+      staging.set(port, value);
+      return;
+    }
+    this.commitOutputValue(port, value);
+  }
+  commitOutputValue(port, value) {
+    if (!sameOutputValue(port.value, value)) {
+      if (port.dataType === "bundle") {
+        this.outputVersions.set(port.id, (this.outputVersions.get(port.id) ?? 0) + 1);
+        this.bumpBundleFields(port.id, port.value, value);
+      } else {
+        this.bumpOutputVersion(port.id);
+      }
+    }
+    port.value = value;
+    for (const connection of port.connections) {
+      const targetNode = this.graph.getNode(connection.to.nodeId);
+      const targetPort = targetNode?.getInputPortById(connection.to.portId);
+      if (!targetPort) continue;
+      targetPort.value = value;
+      targetPort.onChange?.(value);
+    }
+  }
+  addParm(name, config) {
+    this.props[name] = config;
+    this.propsDeclaredByCode.add(name);
+    this.reconcileProp(name);
+    if (this.cookState !== "cooking") this.markDirty();
+  }
+  /**
+   * Define a parameter on this node
+   * @deprecated Use addParm() instead
+   */
+  defineProp(name, config) {
+    this.addParm(name, config);
+  }
+  /**
+   * Add an action button to this node
+   * Actions appear in the Inspector and can be triggered by keyboard shortcuts
+   */
+  addAction(name, config) {
+    this.actions[name] = config;
+  }
+  /**
+   * Execute an action by name
+   */
+  async executeAction(name) {
+    const action = this.actions[name];
+    if (!action) return;
+    if (action.condition && !action.condition()) return;
+    await action.callback();
+  }
+  updateProp(name, value) {
+    if (!this.props[name]) return;
+    const newValue = Array.isArray(value) ? [...value] : value;
+    this.props[name] = { ...this.props[name], value: newValue };
+    if (this.props[name].onChange) {
+      try {
+        this.props[name].onChange(this.props[name], this);
+      } catch (err) {
+        console.error(`Error in prop onChange for ${name}:`, err);
+      }
+    }
+    const watchers = this.propWatchers.get(name);
+    if (watchers) {
+      watchers.forEach((cb) => {
+        try {
+          cb(newValue, this.props[name]);
+        } catch (err) {
+          console.error(`Error in prop watcher for ${name}:`, err);
+        }
+      });
+    }
+    this.props = { ...this.props };
+    this.markDirty();
+    _Node.onPropParamsChanged?.(this.id);
+  }
+  /**
+   * Update prop params (e.g., min, max) and trigger UI reactivity
+   */
+  updatePropParams(name, params) {
+    if (!this.props[name]) return;
+    this.props[name] = {
+      ...this.props[name],
+      params: { ...this.props[name].params, ...params }
+    };
+    this.props = { ...this.props };
+    _Node.onPropParamsChanged?.(this.id);
+  }
+  watchProp(name, callback) {
+    if (!this.propWatchers.has(name)) this.propWatchers.set(name, []);
+    this.propWatchers.get(name).push(callback);
+  }
+  // ============ Parm API (HOM-style wrappers) ============
+  /**
+   * Get a parameter wrapper object for HOM-style access
+   */
+  parm(name) {
+    const prop = this.props[name];
+    if (!prop) return null;
+    const self = this;
+    const live = () => self.props[name] ?? prop;
+    return {
+      name: () => name,
+      path: () => `${self.path()}/${name}`,
+      node: () => self,
+      eval: () => live().value,
+      evalAsFloat: () => parseFloat(live().value) || 0,
+      evalAsInt: () => parseInt(live().value, 10) || 0,
+      evalAsString: () => String(live().value ?? ""),
+      rawValue: () => live().value,
+      set: (value) => self.updateProp(name, value),
+      parmType: () => live().type || "any",
+      // Expression support
+      expression: () => live().expression ?? null,
+      setExpression: (expr) => {
+        self.props[name] = { ...self.props[name], expression: expr };
+        self.updateTimeDependent();
+        self.markDirty();
+      },
+      deleteExpression: () => {
+        const { expression: _, expressionError: __, ...rest } = self.props[name];
+        self.props[name] = rest;
+        if (self.defaultExpressionsApplied.has(name)) {
+          self.plainPropOverrides.add(name);
+        }
+        self.updateTimeDependent();
+        self.markDirty();
+      },
+      hasExpression: () => !!live().expression,
+      expressionError: () => live().expressionError ?? null,
+      // ---- Keyframe channel ----
+      // Same shape as the expression API above, deliberately: a channel and an
+      // expression are the same kind of binding, one drawn and one written.
+      channel: () => self.props[name]?.channel ?? null,
+      hasChannel: () => !isEmptyChannel(self.props[name]?.channel),
+      keys: () => self.props[name]?.channel?.keys ?? [],
+      /**
+       * Key the parameter. Both arguments default to "here, now": the current
+       * frame and the parameter's current evaluated value, which is what
+       * alt-clicking a parameter has to mean.
+       */
+      setKey: (frame, value, interpolation) => {
+        const at = frame ?? self.currentFrame();
+        const v = value ?? Number(self.evalParm(name));
+        if (!Number.isFinite(v)) return;
+        self.setPropChannel(name, setKey(self.props[name]?.channel, at, v, interpolation));
+      },
+      deleteKey: (frame) => {
+        const current = self.props[name]?.channel;
+        if (!current) return;
+        self.setPropChannel(name, deleteKey(current, frame));
+      },
+      clearChannel: () => self.setPropChannel(name, null)
+    };
+  }
+  // ============ Keyframe channels ============
+  /**
+   * The frame a channel is sampled against.
+   *
+   * One clock today — the expression engine's, which the host keeps in step
+   * with its own frame — so `sin($T)` and a keyed curve on the same node
+   * always agree. When timelines become document objects this is the single
+   * place that has to learn which one a node belongs to.
+   */
+  currentFrame() {
+    return expressionEngine.fframe;
+  }
+  /**
+   * Attach, replace or clear a channel. An empty channel is removed rather
+   * than stored, so `hasChannel()` and the serialised form never disagree
+   * about whether a parameter is animated.
+   */
+  setPropChannel(name, channel) {
+    const prop = this.props[name];
+    if (!prop) return;
+    if (!channel || isEmptyChannel(channel)) {
+      const { channel: _dropped, ...rest } = this.props[name];
+      this.props[name] = rest;
+    } else {
+      this.props[name] = { ...prop, channel };
+    }
+    this.props = { ...this.props };
+    this.updateTimeDependent();
+    this.markDirty();
+    _Node.onPropParamsChanged?.(this.id);
+  }
+  /**
+   * A prop as it goes to disk: the bare value when there is nothing more to
+   * say, the object form when it carries an expression, a channel, or both.
+   *
+   * Lives here rather than in the serializer because the channel type is the
+   * node's, and one writer is what stops the two forms disagreeing.
+   */
+  serializePropValue(name, value) {
+    const prop = this.props[name];
+    if (!prop) return value;
+    const channel = serializeChannel(prop.channel);
+    if (!prop.expression && !channel) return value;
+    return {
+      value,
+      ...prop.expression ? { expression: prop.expression } : {},
+      ...channel ? { channel } : {}
+    };
+  }
+  preservePlainProp(name) {
+    this.plainPropOverrides.add(name);
+  }
+  preservesPlainProp(name) {
+    return this.plainPropOverrides.has(name) && this.defaultExpressionsApplied.has(name);
+  }
+  /** Read a channel back off disk. Bad data yields no channel, never a throw. */
+  restorePropChannel(name, data) {
+    if (!this.props[name]) return;
+    const channel = deserializeChannel(data);
+    this.setPropChannel(name, isEmptyChannel(channel) ? null : channel);
+  }
+  /** The serialised channel for one prop, or undefined when it is not keyed. */
+  serializePropChannel(name) {
+    return serializeChannel(this.props[name]?.channel);
+  }
+  /**
+   * The one place a parameter becomes a value — in Studio.
+   *
+   * Three bindings, in one order: a keyframe channel, an expression, the raw
+   * value. All of them resolve BEFORE execute, so the node receives a plain
+   * number and never reads a clock — determinism is "same graph plus same
+   * frame gives the same output", which is still cacheable once the cache key
+   * gains a frame.
+   *
+   * The ORDER itself is no longer written here. It lives in
+   * `@cascade/runtime/params`, because the deterministic runtime resolves the
+   * same three bindings for the same document and a second implementation of
+   * the order would be a second answer to the same question. What stays here
+   * is the Studio-specific half: the clock the channel is sampled against, and
+   * the expression engine with its Inspector-facing error bookkeeping.
+   */
+  evalParm(name) {
+    const prop = this.props[name];
+    if (!prop) return void 0;
+    return resolvePropBinding(prop, {
+      frame: this.currentFrame(),
+      // `evaluateExpression` already stores the message on the prop for the
+      // panel and falls back to the raw value, so it reports no error upward:
+      // the resolver's own fallback would be the same value twice.
+      evaluateExpression: () => ({ value: this.evaluateExpression(name) })
+    }).value;
+  }
+  /**
+   * Set a parameter value (shorthand for updateProp)
+   */
+  setParm(name, value) {
+    this.updateProp(name, value);
+  }
+  /**
+   * Evaluate an expression for a parameter
+   * Returns the evaluated value or the raw value if evaluation fails
+   */
+  evaluateExpression(name) {
+    const prop = this.props[name];
+    if (!prop?.expression) return prop?.value;
+    expressionEngine.setGraph(this.graph);
+    const result = expressionEngine.evaluate(prop.expression, this);
+    if (result.error) {
+      this.props[name] = { ...this.props[name], expressionError: result.error };
+      return prop.value;
+    }
+    if (prop.expressionError) {
+      const { expressionError: _, ...rest } = this.props[name];
+      this.props[name] = rest;
+    }
+    return result.value;
+  }
+  /**
+   * Evaluate all expressions on this node and update values
+   * Called during execution to get current expression values
+   */
+  evaluateAllExpressions() {
+    for (const [name, prop] of Object.entries(this.props)) {
+      if (prop.expression && !prop.fromParameter && this.propsDeclaredByCode.has(name)) {
+        const evaluated = this.evaluateExpression(name);
+        if (evaluated !== void 0) {
+          this.props[name] = { ...this.props[name], value: evaluated };
+        }
+      }
+    }
+    this.updateTimeDependent();
+  }
+  // ============ Parameters ============
+  /**
+   * A value that belongs to the node — not a pin.
+   *
+   * Cascade only had inputs and outputs, so every setting a node had was
+   * declared as an input port that nobody ever wired. That reads wrong in the
+   * graph (density-blend showed twenty input pins when it has four real inputs
+   * and sixteen settings) and it reads wrong in the Inspector, where a crop
+   * fraction and an incoming image sat in the same list.
+   *
+   * So: inputs are edges from other nodes, parameters are the node's own
+   * values, outputs are edges out.
+   *
+   * A parameter can be PROMOTED to an input pin when you want it driven from
+   * upstream rather than typed — a signal's weight computed by another node,
+   * say. Promotion is per parameter and off by default: making every setting a
+   * pin is how the two got conflated in the first place.
+   */
+  param(name, defaultValue, options = {}) {
+    let parameter = this.parameters.find((p) => p.name === name);
+    if (!parameter) {
+      parameter = {
+        name,
+        value: defaultValue,
+        defaultValue,
+        dataType: options.type || inferParamType(defaultValue),
+        promoted: false,
+        options
+      };
+      this.parameters.push(parameter);
+    } else {
+      if (options.type) parameter.dataType = options.type;
+      parameter.defaultValue = defaultValue;
+      Object.assign(parameter.options, options);
+    }
+    this.parametersUsedDuringSetup.add(name);
+    this.reconcileParameter(parameter, defaultValue, options);
+    this.bindParameterProp(parameter, name, options);
+    if (parameter.promoted) {
+      const port = this.in(name, parameter.value, {
+        ...parameter.options,
+        type: parameter.dataType,
+        promoted: true
+      });
+      port.fromParameter = name;
+      if (port.connections.length > 0 && port.value !== void 0 && port.value !== null) {
+        return { ...parameter, value: port.value };
+      }
+    }
+    return parameter;
+  }
+  /**
+   * Give a parameter the prop that holds its value, and make `parameter.value`
+   * a view onto it.
+   *
+   * Called from `param()` on every declaration, so everything here is
+   * idempotent: an existing prop keeps its value, expression and channel, and
+   * only the declaration metadata is refreshed. The prop object is mutated
+   * rather than replaced for the same reason the Inspector does not re-key a
+   * row on commit — replacing it mid-drag destroys the control in use.
+   */
+  bindParameterProp(parameter, name, options) {
+    const descriptor = Object.getOwnPropertyDescriptor(parameter, "value");
+    const seeded = descriptor && !descriptor.get ? descriptor.value : void 0;
+    let prop = this.props[name];
+    if (!prop) {
+      prop = { value: seeded !== void 0 ? seeded : parameter.defaultValue };
+      this.props[name] = prop;
+      this.props = { ...this.props };
+    }
+    if (options.defaultExpression && !this.defaultExpressionsApplied.has(name)) {
+      this.defaultExpressionsApplied.add(name);
+      if (!this.plainPropOverrides.has(name) && !prop.expression) {
+        prop.expression = options.defaultExpression;
+        this.props = { ...this.props };
+        this.updateTimeDependent();
+      }
+    }
+    prop.fromParameter = name;
+    prop.hidden = true;
+    const control = paramControlType(parameter.dataType);
+    if (control) prop.type = control;
+    const params = { ...prop.params ?? {} };
+    if (options.min !== void 0) params.min = options.min;
+    if (options.max !== void 0) params.max = options.max;
+    if (options.step !== void 0) params.step = options.step;
+    if (normalizeType(parameter.dataType ?? "any") === "int") params.integer = true;
+    prop.params = params;
+    if (descriptor?.get) return;
+    Object.defineProperty(parameter, "value", {
+      // Resolved, not raw: a channel wins, then an expression, then the stored
+      // value — the same order `evalParm` uses, because it IS `evalParm`. This
+      // is what carries a key or `$T * 0.25` into a sketch's `execute()`
+      // without the sketch knowing anything about either.
+      get: () => this.evalParm(name),
+      set: (next) => this.writeParameterValue(name, next),
+      enumerable: true,
+      configurable: true
+    });
+  }
+  /**
+   * Write a parameter's stored value.
+   *
+   * **A written value clears a DEFAULT expression**, which is the rule the rest
+   * of the system already states — *a default expression is a default, and the
+   * author's number wins* — and which this method did not implement. The
+   * asymmetry was real and silent: `parameter.value` reads *resolved*, so
+   * writing 42 over a prop declaring `defaultExpression: '2 * 5'` stored 42 and
+   * then read back 10. A panel doing exactly that (`setParam` then `getParam`)
+   * saw its own write vanish, concluded the write had failed, and re-rendered
+   * every series instance at the value it had just replaced — identical cache
+   * keys, identical output, and nothing thrown or logged. Found by
+   * MW-OBSERVATORY-ART building the series panel.
+   *
+   * An expression the author wrote is a different matter and is NOT cleared
+   * here: it legitimately wins, and deleting it to make a write stick would
+   * destroy work. `setParameter` reports that case instead of hiding it.
+   *
+   * The prop object is replaced so a panel reading it sees the change; no cook
+   * is scheduled here — the callers that should (setParameter, updateProp) do
+   * it themselves.
+   */
+  writeParameterValue(name, value) {
+    const prop = this.props[name];
+    if (!prop) return;
+    const next = { ...prop, value: Array.isArray(value) ? [...value] : value };
+    if (prop.expression && this.defaultExpressionsApplied.has(name)) {
+      delete next.expression;
+      delete next.expressionError;
+      this.plainPropOverrides.add(name);
+    }
+    this.props[name] = next;
+    this.props = { ...this.props };
+    this.updateTimeDependent();
+  }
+  /**
+   * Why a written value would not be the value read back, or null if it would.
+   *
+   * `parameter.value` resolves a channel first, then an expression, then the
+   * stored value — so a write beneath either of the first two is stored and
+   * then shadowed. That is correct precedence and a terrible silence: the
+   * caller has no way to tell a shadowed write from a failed one, and both
+   * look like the parameter ignoring them.
+   */
+  parameterWriteShadowedBy(name) {
+    const prop = this.props[name];
+    if (!prop) return null;
+    if ((prop.channel?.keys?.length ?? 0) > 0) return "channel";
+    if (prop.expression && !this.defaultExpressionsApplied.has(name)) return "expression";
+    return null;
+  }
+  /**
+   * A parameter's stored value, before any channel or expression resolves it.
+   *
+   * `parameter.value` is deliberately the resolved one, so anything that has
+   * to record or re-key what the author actually set — serialisation, the
+   * alt-click gesture — must ask for the raw one instead. Writing the sampled
+   * value back to disk would freeze an animated parameter at whatever frame
+   * the save happened on.
+   */
+  rawParameterValue(name) {
+    if (this.props[name]) return this.props[name].value;
+    return this.parameters.find((parameter) => parameter.name === name)?.value;
+  }
+  /** Turn a parameter into an input pin, or back. */
+  setParameterPromoted(name, promoted) {
+    const parameter = this.parameters.find((p) => p.name === name);
+    if (!parameter || parameter.promoted === promoted) return;
+    parameter.promoted = promoted;
+    if (promoted) {
+      const port = this.in(name, parameter.value, {
+        ...parameter.options,
+        type: parameter.dataType,
+        promoted: true
+      });
+      port.fromParameter = name;
+    } else {
+      const index = this.inputs.findIndex((p) => p.name === name);
+      if (index >= 0) {
+        [...this.inputs[index].connections].forEach((conn) => this.graph?.disconnect(conn.id));
+        this.inputs.splice(index, 1);
+      }
+    }
+    this.markDirty();
+  }
+  /**
+   * Write a parameter and cook — unless the write would change nothing.
+   *
+   * It marked the node dirty unconditionally, and MW-OBSERVATORY-ART found
+   * what that costs a panel: the series panel re-writes its filter on every
+   * load, so **mounting it cooked the whole document to arrive at values it
+   * already held.** Every panel that restores state on mount hits this, and
+   * each of them would otherwise write the same guard.
+   *
+   * The equality test is on the RAW stored value, because that is what a write
+   * replaces. Two things it must not treat as unchanged, both of which would
+   * make this quietly wrong:
+   *
+   *   - a write that **clears a declared default expression** changes the
+   *     resolved value even though the stored one may match, so a bound prop
+   *     is never skipped;
+   *   - an array or object, which is compared structurally rather than by
+   *     reference — a panel that hands back a copy of the same numbers is the
+   *     exact case this exists for, and `===` would call it a change.
+   */
+  setParameter(name, value) {
+    const parameter = this.parameters.find((p) => p.name === name);
+    if (!parameter) return;
+    if (this.parameterWriteIsNoop(name, value)) return;
+    parameter.value = value;
+    this.markDirty();
+  }
+  /** Whether writing this value would leave the node exactly as it is. */
+  parameterWriteIsNoop(name, value) {
+    const prop = this.props[name];
+    if (!prop || prop.expression || (prop.channel?.keys?.length ?? 0) > 0) return false;
+    return sameStoredValue(prop.value, value);
+  }
+  // ============ Parameter carry-over ============
+  /**
+   * Snapshot every current setting and start reconciling against whatever the
+   * next definition declares. Idempotent per retarget; the snapshot stays until
+   * a cook completes, so a definition that fails to compile loses nothing.
+   */
+  beginParameterCarryOver() {
+    const carried = /* @__PURE__ */ new Map();
+    for (const parameter of this.parameters) {
+      carried.set(`parameter:${parameter.name}`, {
+        name: parameter.name,
+        kind: "parameter",
+        type: carryType(parameter.dataType),
+        // Raw, not resolved: a retarget carries what the author set, and
+        // `parameter.value` now resolves a channel or an expression.
+        value: this.rawParameterValue(parameter.name),
+        expression: this.props[parameter.name]?.expression,
+        channel: this.props[parameter.name]?.channel
+      });
+    }
+    for (const [name, prop] of Object.entries(this.props)) {
+      if (carried.has(`parameter:${name}`)) continue;
+      carried.set(`prop:${name}`, {
+        name,
+        kind: "prop",
+        type: carryType(prop.type),
+        value: prop.value,
+        expression: prop.expression,
+        channel: prop.channel
+      });
+    }
+    this.carryOver = {
+      carried,
+      resolved: /* @__PURE__ */ new Set(),
+      report: { kept: [], defaulted: [], dropped: [], retyped: [] }
+    };
+    this.parametersUsedDuringSetup.clear();
+  }
+  /** Give up on reconciling — the retarget itself failed. Values are left
+   *  exactly as they were and nothing is reported as dropped. */
+  abandonParameterCarryOver() {
+    this.carryOver = null;
+  }
+  hasPendingParameterCarryOver() {
+    return this.carryOver !== null;
+  }
+  /**
+   * Reconcile against a declaration list the caller already has, without
+   * waiting for a cook. Runs the declarations through the ordinary `param()` /
+   * `addParm()` path so the node ends up in the same state either way — this
+   * is the same pre-seeding deserialization does, only reported.
+   */
+  applyParameterDeclarations(declarations) {
+    if (!this.carryOver) return null;
+    for (const declaration of declarations) {
+      if (!declaration?.name) continue;
+      if (declaration.kind === "prop") {
+        this.addParm(declaration.name, {
+          value: declaration.defaultValue,
+          type: declaration.type
+        });
+      } else {
+        this.param(declaration.name, declaration.defaultValue, {
+          ...declaration.type ? { type: declaration.type } : {}
+        });
+      }
+    }
+    return this.finishParameterCarryOver();
+  }
+  /**
+   * Close the reconciliation: anything the new definition never declared is
+   * dropped from the node and reported with the value it held.
+   */
+  finishParameterCarryOver() {
+    const carry = this.carryOver;
+    if (!carry) return null;
+    for (const entry of carry.carried.values()) {
+      carry.report.dropped.push({
+        name: entry.name,
+        value: entry.value,
+        ...entry.expression ? { expression: entry.expression } : {}
+      });
+      const index = this.parameters.findIndex((p) => p.name === entry.name);
+      if (index >= 0) {
+        if (this.parameters[index].promoted) this.setParameterPromoted(entry.name, false);
+        const current = this.parameters.findIndex((p) => p.name === entry.name);
+        if (current >= 0) this.parameters.splice(current, 1);
+      }
+      if (!carry.resolved.has(`prop:${entry.name}`)) delete this.props[entry.name];
+    }
+    this.carryOver = null;
+    this.lastCarryOverReport = carry.report;
+    if (carry.report.dropped.length > 0) {
+      this.props = { ...this.props };
+      this.updateTimeDependent();
+      _Node.onPropParamsChanged?.(this.id);
+    }
+    return carry.report;
+  }
+  /** Called from param() for every declaration the new definition makes. */
+  reconcileParameter(parameter, defaultValue, options) {
+    const carry = this.carryOver;
+    if (!carry) return;
+    const key = `parameter:${parameter.name}`;
+    if (carry.resolved.has(key)) return;
+    carry.resolved.add(key);
+    const declared = options.type ?? inferParamType(defaultValue);
+    parameter.dataType = declared;
+    const declaredType = carryType(declared);
+    const crossKey = `prop:${parameter.name}`;
+    const carried = carry.carried.get(key) ?? carry.carried.get(crossKey);
+    if (!carried) {
+      parameter.value = defaultValue;
+      carry.report.defaulted.push(parameter.name);
+      return;
+    }
+    carry.carried.delete(key);
+    carry.carried.delete(crossKey);
+    if (carryTypesMatch(carried.type, declaredType)) {
+      parameter.value = carried.value;
+      if (carried.expression || carried.channel) {
+        this.props[parameter.name] = {
+          ...this.props[parameter.name] ?? {},
+          value: carried.value,
+          ...carried.expression ? { expression: carried.expression } : {},
+          ...carried.channel ? { channel: carried.channel } : {}
+        };
+        carry.resolved.add(crossKey);
+        this.updateTimeDependent();
+      }
+      carry.report.kept.push(parameter.name);
+    } else {
+      parameter.value = defaultValue;
+      carry.report.retyped.push({ name: parameter.name, from: carried.type, to: declaredType });
+    }
+  }
+  /** Called from addParm() for every prop the new definition declares. */
+  reconcileProp(name) {
+    const carry = this.carryOver;
+    if (!carry) return;
+    const key = `prop:${name}`;
+    if (carry.resolved.has(key)) return;
+    carry.resolved.add(key);
+    const prop = this.props[name];
+    const declaredType = carryType(prop?.type);
+    const crossKey = `parameter:${name}`;
+    const carried = carry.carried.get(key) ?? carry.carried.get(crossKey);
+    if (!carried) {
+      carry.report.defaulted.push(name);
+      return;
+    }
+    carry.carried.delete(key);
+    carry.carried.delete(crossKey);
+    if (carryTypesMatch(carried.type, declaredType)) {
+      this.props[name] = {
+        ...prop,
+        value: carried.value,
+        ...carried.expression ? { expression: carried.expression } : {},
+        ...carried.channel ? { channel: carried.channel } : {}
+      };
+      if (carried.expression || carried.channel) this.updateTimeDependent();
+      carry.report.kept.push(name);
+    } else {
+      carry.report.retyped.push({ name, from: carried.type, to: declaredType });
+    }
+  }
+  // ============ Variadic Inputs ============
+  setVariadic(defaultValue = null, options = {}) {
+    this.variadic = true;
+    this.variadicDefault = defaultValue;
+    this.variadicOptions = options;
+    this.syncVariadicPorts();
+  }
+  getVariadicInputs() {
+    return this.inputs.filter((p) => p.variadic && !p.options.hidden);
+  }
+  syncVariadicPorts() {
+    if (!this.variadic) return;
+    const existingPorts = this.inputs.filter((p) => p.variadic);
+    const usedCount = existingPorts.filter(
+      (p) => p.connections.length > 0 || p.value !== null && p.value !== this.variadicDefault
+    ).length;
+    for (let i = 0; i < usedCount + 1; i++) {
+      const port = this.in(`input_${i}`, this.variadicDefault, {
+        ...this.variadicOptions,
+        hidden: false
+      });
+      port.variadic = true;
+      if (!port.onChange) {
+        port.onChange = () => this.onUpdate?.();
+      }
+    }
+    for (let i = usedCount + 1; i < existingPorts.length; i++) {
+      if (existingPorts[i]) existingPorts[i].options.hidden = true;
+    }
+  }
+  // ============ Path System ============
+  /**
+   * Get the full path of this node from the root
+   * e.g., "/effects/blur1"
+   */
+  path() {
+    const segments = [this.id];
+    let current = this.parent;
+    while (current) {
+      segments.unshift(current.id);
+      current = current.parent;
+    }
+    return "/" + segments.join("/");
+  }
+  /**
+   * Get child nodes (for subnet types)
+   * Override in SubnetNode to return actual children
+   */
+  children() {
+    return this._children;
+  }
+  /**
+   * Whether this node can contain children.
+   *
+   * Two sources, and both are legitimate: a subclass that overrides this
+   * (`SubnetNode`), and a definition that declares a container. The class
+   * route came first and stays, because the class nodes are a third authoring
+   * style that is not going anywhere yet.
+   */
+  isNetwork() {
+    return this.declaredContainer === "subnet";
+  }
+  /**
+   * Find a node by relative path from this node
+   * Supports: "child", "../sibling", "./self", "../../parent/child"
+   */
+  node(relativePath) {
+    if (!relativePath) return null;
+    if (relativePath.startsWith("/")) {
+      return this.graph.nodeByPath(relativePath);
+    }
+    const segments = relativePath.split("/").filter((s) => s.length > 0);
+    let current = this;
+    for (const segment of segments) {
+      if (!current) return null;
+      if (segment === ".") {
+        continue;
+      }
+      if (segment === "..") {
+        current = current.parent;
+        continue;
+      }
+      if (current.isNetwork()) {
+        const child = current.children().find((c) => c.id === segment);
+        if (child) {
+          current = child;
+          continue;
+        }
+      }
+      return null;
+    }
+    return current;
+  }
+  /**
+   * Compute relative path from this node to another node
+   */
+  relativePathTo(other) {
+    const thisPath = this.path().split("/").filter((s) => s);
+    const otherPath = other.path().split("/").filter((s) => s);
+    let commonLength = 0;
+    while (commonLength < thisPath.length && commonLength < otherPath.length && thisPath[commonLength] === otherPath[commonLength]) {
+      commonLength++;
+    }
+    const ups = thisPath.length - commonLength;
+    const downs = otherPath.slice(commonLength);
+    const parts = [];
+    for (let i = 0; i < ups; i++) {
+      parts.push("..");
+    }
+    parts.push(...downs);
+    return parts.join("/") || ".";
+  }
+  /**
+   * Get nodes connected to this node's inputs
+   */
+  inputNodes() {
+    const nodes = [];
+    for (const input of this.inputs) {
+      for (const conn of input.connections) {
+        const node = this.graph.getNode(conn.from.nodeId);
+        if (node && !nodes.includes(node)) {
+          nodes.push(node);
+        }
+      }
+    }
+    return nodes;
+  }
+  /**
+   * Get nodes connected to this node's outputs
+   */
+  outputNodes() {
+    const nodes = [];
+    for (const output of this.outputs) {
+      for (const conn of output.connections) {
+        const node = this.graph.getNode(conn.to.nodeId);
+        if (node && !nodes.includes(node)) {
+          nodes.push(node);
+        }
+      }
+    }
+    return nodes;
+  }
+  // ============ Pattern Matching (Globbing) ============
+  /**
+   * Convert a glob pattern to a regular expression
+   * Supports: * (any chars), ? (single char), [abc] (char set), [!abc] (negated set)
+   */
+  globToRegex(pattern) {
+    let regex = "";
+    let i = 0;
+    while (i < pattern.length) {
+      const char = pattern[i];
+      switch (char) {
+        case "*":
+          regex += ".*";
+          break;
+        case "?":
+          regex += ".";
+          break;
+        case "[":
+          let j = i + 1;
+          let classContent = "";
+          if (pattern[j] === "!") {
+            classContent = "^";
+            j++;
+          }
+          while (j < pattern.length && pattern[j] !== "]") {
+            classContent += pattern[j];
+            j++;
+          }
+          regex += "[" + classContent + "]";
+          i = j;
+          break;
+        case ".":
+        case "+":
+        case "^":
+        case "$":
+        case "(":
+        case ")":
+        case "{":
+        case "}":
+        case "|":
+        case "\\":
+          regex += "\\" + char;
+          break;
+        default:
+          regex += char;
+      }
+      i++;
+    }
+    return new RegExp("^" + regex + "$");
+  }
+  /**
+   * Match direct children against a pattern
+   * Pattern syntax:
+   *   * - match any characters
+   *   ? - match single character
+   *   [abc] - match character set
+   *   [!abc] - exclude character set
+   *   ^pattern - exclude matches (use with space: "* ^backup*")
+   */
+  glob(pattern) {
+    const children = this.children();
+    if (!pattern || pattern === "*") {
+      return [...children];
+    }
+    const parts = pattern.split(/\s+/);
+    const includePatterns = [];
+    const excludePatterns = [];
+    for (const part of parts) {
+      if (part.startsWith("^")) {
+        excludePatterns.push(this.globToRegex(part.slice(1)));
+      } else {
+        includePatterns.push(this.globToRegex(part));
+      }
+    }
+    return children.filter((child) => {
+      const included = includePatterns.length === 0 || includePatterns.some((regex) => regex.test(child.id));
+      const excluded = excludePatterns.some((regex) => regex.test(child.id));
+      return included && !excluded;
+    });
+  }
+  /**
+   * Recursively match all descendants against a pattern
+   * Pattern syntax same as glob(), plus:
+   *   ** - match at any depth (prefix with **\/ to find nodes at any level)
+   */
+  recursiveGlob(pattern) {
+    const results = [];
+    const isAnyDepth = pattern.startsWith("**/");
+    const searchPattern = isAnyDepth ? pattern.slice(3) : pattern;
+    const search = (node, depth) => {
+      const children = node.children();
+      for (const child of children) {
+        if (isAnyDepth) {
+          if (this.globToRegex(searchPattern).test(child.id)) {
+            results.push(child);
+          }
+        } else if (depth === 0) {
+          if (this.globToRegex(searchPattern).test(child.id)) {
+            results.push(child);
+          }
+        }
+        if (child.isNetwork()) {
+          search(child, isAnyDepth ? depth : depth - 1);
+        }
+      }
+    };
+    if (pattern === "**") {
+      const collectAll = (node) => {
+        for (const child of node.children()) {
+          results.push(child);
+          if (child.isNetwork()) {
+            collectAll(child);
+          }
+        }
+      };
+      collectAll(this);
+      return results;
+    }
+    const pathDepth = isAnyDepth ? 0 : pattern.split("/").length - 1;
+    search(this, pathDepth);
+    return results;
+  }
+  // ============ Behavior Toggles ============
+  setBypass(value) {
+    this.bypass = value;
+    this.markDirty();
+  }
+  setCook(value) {
+    if (value && this.parent) {
+      this.parent.children().filter((n) => n !== this && n.cook).forEach((n) => n.setCook(false));
+    }
+    this.cook = value;
+    if (value) this.graph.cookingNodes.add(this);
+    else this.graph.cookingNodes.delete(this);
+    this.markDirty();
+  }
+  /**
+   * Set time dependency flag (called by expression compiler)
+   * Time-dependent nodes are marked dirty on each frame
+   */
+  setTimeDependent(value) {
+    this.isTimeDependent = value;
+  }
+  /**
+   * Re-derive time dependency from every binding on the node.
+   *
+   * A keyed parameter is time-dependent for exactly the reason a
+   * time-referencing expression is: its value changes with the frame, so a
+   * per-frame cook has to recook the subgraph it feeds. One key is enough —
+   * the value it holds is still a function of the frame everywhere else.
+   */
+  updateTimeDependent() {
+    const hasTimeRef = Object.values(this.props).some(
+      (prop) => prop.expression && expressionEngine.hasTimeReference(prop.expression) || !isEmptyChannel(prop.channel)
+    );
+    this.setTimeDependent(hasTimeRef);
+  }
+  shouldExecute() {
+    if (this.bypass) return false;
+    if (this.graph.cookingNodes.size > 0) {
+      return this.cook || this.graph.isDownstreamOfCooking(this);
+    }
+    return true;
+  }
+  executeBypass() {
+    this.inputs.forEach((input) => {
+      if (input.portType === "param") {
+        const matchingOutput = this.outputs.find((out) => out.name === input.name || this.outputs.length === 1);
+        if (matchingOutput) matchingOutput.setValue(input.value);
+      }
+    });
+  }
+  // ============ Dirty Tracking ============
+  markDirty() {
+    this.graph.scheduler.markStale(this);
+  }
+  /**
+   * The signal for the cook in flight, or null outside one.
+   *
+   * **Until 2026-09-09 Studio handed every node `new AbortController().signal`
+   * and never aborted it**, so `context.signal` was inert: a node that checked
+   * it — `series-source` does — could not be cancelled, and every long node
+   * ran to completion whether or not its result was still wanted. The
+   * generation check in `execute` then discarded the result, which is the
+   * expensive half in the wrong order: measured on `cloud-volumes`, an
+   * abandoned cook had already encoded and uploaded a 1.55 MB PNG before
+   * anything noticed it was superseded.
+   *
+   * So the signal is real, and a node with expensive work owes itself a check
+   * before committing to it. That is the only place preemption can be cheap.
+   */
+  get cookSignal() {
+    for (const controller of this.cookAborts) {
+      if (!controller.signal.aborted) return controller.signal;
+    }
+    return null;
+  }
+  /**
+   * @internal The signal of the newest cook in flight, aborted or not.
+   *
+   * Unlike `cookSignal`, this keeps answering after the cook is aborted, which
+   * is what a stage started late needs: a call made after the supersede must
+   * see an aborted signal and not start, not see no signal and run unguarded.
+   */
+  get inFlightCookSignal() {
+    let latest = null;
+    for (const controller of this.cookAborts) latest = controller;
+    return latest?.signal ?? null;
+  }
+  /** @internal Scheduler-owned invalidation primitive. */
+  invalidateCook() {
+    this.cookGeneration++;
+    this.abortCooks("superseded");
+    this.setCookState("stale");
+  }
+  /**
+   * @internal Abandon whatever this node is doing.
+   *
+   * Separate from `invalidateCook` because the scheduler needs to stop
+   * background work WITHOUT marking it stale — a preempted instance is not
+   * dirty, it is unfinished, and telling the graph it is stale would put it
+   * straight back in the queue it was just taken out of.
+   */
+  cancelCook(reason) {
+    this.abortCooks(reason);
+  }
+  abortCooks(reason) {
+    for (const controller of this.cookAborts) {
+      if (!controller.signal.aborted) controller.abort(new Error(reason));
+    }
+  }
+  /** @internal Scheduler-owned state transition. */
+  setCookState(state) {
+    if (this.cookState === state) return;
+    this.cookState = state;
+    this.graph.scheduler.notifyNodeStateChange();
+  }
+  /**
+   * What the inputs are, exactly: the same key the early cutoff uses. See
+   * `inputFingerprint.ts` for why this no longer samples. A connected input is
+   * its producers' output versions, which move on every commit that is not
+   * provably the same value — O(1) however large the image. A value set
+   * directly on the port has no producer, so it is hashed in full. A
+   * connection to something that keeps no versions (an annotation) falls back
+   * to hashing every input's value.
+   */
+  calculateInputHash() {
+    return this.inputVersionKey() ?? this.inputs.map((input) => valueFingerprint(input.value)).join("|");
+  }
+  get isDirty() {
+    if (!this.hasExecuted || this.cookState !== "clean") return true;
+    return this.calculateInputHash() !== this.lastInputHash;
+  }
+  /**
+   * The last cook threw, and nothing has changed since it did.
+   *
+   * Separate from `isDirty` on purpose, and this is the second attempt: folding
+   * it into `isDirty` closed the Viewer's cook loop and broke a contract the
+   * scheduler tests already pinned — `requestOutput` retries a failed node,
+   * which is the transient case (a fetch that timed out, a device lost) and is
+   * right. The two callers are not the same thing wearing different names. An
+   * explicit request means *give me this output now* and should retry; the
+   * Viewer's `requestAnimationFrame` pump is a **poll** that was reaching the
+   * same entry point every 100 ms, and a poll asking again on identical inputs
+   * cannot learn anything.
+   *
+   * So the fix belongs at the poll, and the poll needs a question only the node
+   * can answer. Measured 2026-09-08 by MW-OBSERVATORY-ART against a live sketch:
+   * selecting a failing node produced 93 errors in 10 s — 9.3/sec, median gap
+   * 103.7 ms, identical stack every time — each one a full `scheduler.flush()`
+   * re-running the failing execute and re-fetching its inputs over the network,
+   * for as long as the node stayed selected. `markDirty` is not on that path,
+   * which is why auditing its call sites came back clean, and the Viewer's
+   * overlap guard is why it held 61 fps and never looked like a hang.
+   *
+   * `hasExecuted` is deliberately not consulted: a node that throws on its very
+   * first cook never sets it, and that is the reproduction case.
+   */
+  get hasSettledFailure() {
+    if (this.cookState !== "error" || this.failedInputHash === null) return false;
+    return this.calculateInputHash() === this.failedInputHash;
+  }
+  /**
+   * Mark all downstream nodes as dirty (lazy propagation)
+   */
+  markDownstreamDirty() {
+    this.graph.scheduler.markDownstreamStale(this);
+  }
+  /**
+   * Request this node's output - triggers lazy evaluation
+   * Executes dirty upstream dependencies first, then this node
+   */
+  async requestOutput() {
+    if (!this.isDirty) return;
+    if (this.cookState === "clean") this.markDirty();
+    await this.graph.scheduler.flush();
+  }
+  // ============ Lifecycle ============
+  setup() {
+  }
+  setFunction(fn) {
+    this.nodeFunction = fn;
+    this.hasExecuted = false;
+    this.markDirty();
+  }
+  async execute() {
+    const hasExecution = !!this.nodeFunction || this.onCook !== _Node.prototype.onCook;
+    if (!hasExecution) {
+      this.hasExecuted = true;
+      this.setCookState("clean");
+      return;
+    }
+    const needsInitialization = !this.hasExecuted;
+    if (!this.shouldExecute() && !needsInitialization && !this.isDirty) {
+      this.executeBypass();
+      this.setCookState("clean");
+      return;
+    }
+    if (!needsInitialization && !this.isDirty) {
+      return;
+    }
+    this.evaluateAllExpressions();
+    const startTime = performance.now();
+    const startMemory = performance.memory?.usedJSHeapSize ?? 0;
+    const generation = this.cookGeneration;
+    const staging = /* @__PURE__ */ new Map();
+    this.stagingStack.push(staging);
+    const abort = new AbortController();
+    this.cookAborts.add(abort);
+    this.setCookState("cooking");
+    let timeoutId;
+    try {
+      await Promise.race([
+        Promise.resolve(this.onCook()),
+        new Promise((_, reject) => {
+          timeoutId = setTimeout(
+            () => reject(new Error(`Node execution timeout after ${this.executionTimeout}ms`)),
+            this.executionTimeout
+          );
+        })
+      ]);
+      if (generation === this.cookGeneration) {
+        await this.callLifecycleHooks(needsInitialization);
+        for (const [port, value] of staging) {
+          this.commitOutputValue(port, value);
+        }
+        for (const output of this.outputs) {
+          if (!staging.has(output)) this.bumpOutputVersion(output.id);
+        }
+        this.cutoffKey = this.inputVersionKey();
+        this.selfDirty = false;
+        this.error = null;
+        this.hasExecuted = true;
+        this.lastInputHash = this.cutoffKey ?? this.calculateInputHash();
+        this.failedInputHash = null;
+        const carryReport = this.finishParameterCarryOver();
+        if (carryReport) _Node.onParametersRetargeted?.(this.id, carryReport);
+        this.setCookState("clean");
+      } else {
+        this.setCookState("stale");
+      }
+      this.updateCookInfo(startTime, startMemory);
+    } catch (thrown) {
+      const err = asError(thrown);
+      if (generation === this.cookGeneration) {
+        this.cutoffKey = null;
+        this.error = err;
+        this.failedInputHash = this.calculateInputHash();
+        this.setCookState("error");
+      } else {
+        this.setCookState("stale");
+      }
+      this.updateCookInfo(startTime, startMemory);
+      const cancelled = err.message.includes("timeout") || generation !== this.cookGeneration;
+      if (!cancelled) {
+        console.error(`Error executing node ${this.id}: ${err.message}`, err);
+      }
+    } finally {
+      if (timeoutId !== void 0) clearTimeout(timeoutId);
+      const index = this.stagingStack.indexOf(staging);
+      if (index >= 0) this.stagingStack.splice(index, 1);
+      this.cookAborts.delete(abort);
+    }
+  }
+  /**
+   * Override this method in class-based nodes to implement cooking logic.
+   * Base implementation calls nodeFunction if set (for code-based nodes).
+   * Cook timing is handled automatically by execute().
+   */
+  onCook() {
+    if (this.nodeFunction) {
+      return this.nodeFunction(this, this.graph);
+    }
+  }
+  /**
+   * Update cook info after execution
+   * Protected so subclasses can call it for manual cook tracking
+   */
+  updateCookInfo(startTime, startMemory = 0) {
+    const endTime = performance.now();
+    const cookTime = endTime - startTime;
+    this.cookInfo.lastCookTime = cookTime;
+    this.cookInfo.totalCookTime += cookTime;
+    this.cookInfo.cookCount++;
+    this.cookInfo.averageCookTime = this.cookInfo.totalCookTime / this.cookInfo.cookCount;
+    this.cookInfo.lastCookTimestamp = Date.now();
+    const endMemory = performance.memory?.usedJSHeapSize ?? 0;
+    if (startMemory && endMemory) {
+      const memoryUsed = endMemory - startMemory;
+      if (memoryUsed > this.cookInfo.peakMemory) {
+        this.cookInfo.peakMemory = memoryUsed;
+      }
+    }
+  }
+  /**
+   * Start cook timing - returns start time to pass to endCook()
+   * Use for class-based nodes that don't go through execute()
+   */
+  startCook() {
+    return performance.now();
+  }
+  /**
+   * End cook timing - call with the value returned from startCook()
+   */
+  endCook(startTime) {
+    this.updateCookInfo(startTime, 0);
+  }
+  /**
+   * Reset cook statistics
+   */
+  resetCookInfo() {
+    this.cookInfo = {
+      lastCookTime: 0,
+      totalCookTime: 0,
+      cookCount: 0,
+      averageCookTime: 0,
+      lastCookTimestamp: 0,
+      peakMemory: 0
+    };
+  }
+  async callLifecycleHooks(isFirstRun) {
+    const isBrowserAPIError = (err) => {
+      const msg = err?.message || String(err);
+      return msg.includes("document is not defined") || msg.includes("window is not defined") || msg.includes("HTMLCanvasElement") || msg.includes("HTMLImageElement");
+    };
+    if (isFirstRun && this.onSetup) {
+      try {
+        await this.onSetup();
+      } catch (err) {
+        if (!isBrowserAPIError(err)) console.error(`Error in onSetup for ${this.id}:`, err);
+      }
+    }
+    if (this.onUpdate) {
+      try {
+        await this.onUpdate();
+      } catch (err) {
+        if (!isBrowserAPIError(err)) console.error(`Error in onUpdate for ${this.id}:`, err);
+      }
+    }
+    if (this.onRender) {
+      try {
+        await this.onRender();
+      } catch (err) {
+        if (!isBrowserAPIError(err)) console.error(`Error in onRender for ${this.id}:`, err);
+      }
+    }
+    if (isFirstRun && this.onReady) {
+      try {
+        this.onReady();
+      } catch (err) {
+        if (!isBrowserAPIError(err)) console.error(`Error in onReady for ${this.id}:`, err);
+      }
+    }
+  }
+  // ============ Rename ============
+  rename(newId) {
+    if (!newId?.trim()) return this.id;
+    const sanitizedId = newId.trim().replace(/\s+/g, "");
+    if (!sanitizedId) return this.id;
+    const uniqueId = this.graph.generateUniqueNodeId(sanitizedId, this.id);
+    if (this.graph.renameElement(this.id, uniqueId)) this.markDirty();
+    return this.id;
+  }
+  isPreviewValue(value) {
+    return typeof HTMLCanvasElement !== "undefined" && value instanceof HTMLCanvasElement || typeof HTMLImageElement !== "undefined" && value instanceof HTMLImageElement;
+  }
+  // ============ Package Manager ============
+  async require(packageName, version) {
+    if (!this.graph.packageManager) throw new Error("PackageManager not initialized");
+    return this.graph.packageManager.load(packageName, version);
+  }
+  get assets() {
+    return this.graph.assetManager;
+  }
+  // ============ Utilities ============
+  log(...args) {
+    console.log(`[${this.id}]`, ...args);
+  }
+  resetPortTracking() {
+    this.portsUsedDuringSetup.clear();
+  }
+  // ============ State Preservation ============
+  preserveState() {
+    return {
+      inputs: this.inputs.map((p) => ({ id: p.id, name: p.name, value: p.value, connections: p.connections.map((c) => c.id) })),
+      outputs: this.outputs.map((p) => ({ id: p.id, name: p.name, value: p.value, connections: p.connections.map((c) => c.id) })),
+      props: Object.fromEntries(Object.entries(this.props).map(([k, p]) => [k, p.value])),
+      bypass: this.bypass,
+      cook: this.cook
+    };
+  }
+  restoreState(state) {
+    state.inputs?.forEach((s) => {
+      const port = this.inputs.find((p) => p.id === s.id || p.name === s.name);
+      if (port) port.value = s.value;
+    });
+    state.outputs?.forEach((s) => {
+      const port = this.outputs.find((p) => p.id === s.id || p.name === s.name);
+      if (port) port.value = s.value;
+    });
+    if (state.props) {
+      Object.entries(state.props).forEach(([k, v]) => {
+        if (this.props[k]) this.props[k].value = v;
+      });
+    }
+    if (state.bypass !== void 0) this.setBypass(state.bypass);
+    if (state.cook !== void 0) this.setCook(state.cook);
+  }
+  // ============ Port Cleanup ============
+  cleanupUnusedPorts() {
+    const used = this.portsUsedDuringSetup;
+    this.inputs = this.inputs.filter((port) => {
+      if (!used.has(`input_${port.name}`)) {
+        port.connections.forEach((c) => this.graph.disconnect(c.id));
+        this._portMap.delete(port.id);
+        return false;
+      }
+      return true;
+    });
+    this.outputs = this.outputs.filter((port) => {
+      if (!used.has(`output_${port.name}`)) {
+        port.connections.forEach((c) => this.graph.disconnect(c.id));
+        this._portMap.delete(port.id);
+        return false;
+      }
+      return true;
+    });
+    this.portsUsedDuringSetup.clear();
+  }
+  // ============ Serialization ============
+  toJSON() {
+    const fullType = typeToPackagePath(this.type);
+    const result = {
+      id: this.id,
+      type: fullType,
+      position: [this.position.x, this.position.y]
+    };
+    if (!isStandardLibraryNode(fullType) && this.code) {
+      result.code = this.code;
+    }
+    if (this.comment?.trim()) result.comment = this.comment;
+    const props = Object.fromEntries(
+      Object.entries(this.props).map(([k, p]) => {
+        let v = p.value;
+        if (p.type === "color" && isColorValue(v)) {
+          const n = normalizeColor(v);
+          v = [n.r, n.g, n.b, n.a ?? 1];
+        }
+        if (p.expression) {
+          return [k, { value: v, expression: p.expression }];
+        }
+        return [k, v];
+      })
+    );
+    if (Object.keys(props).length > 0) result.props = props;
+    if (this.bypass) result.bypass = true;
+    if (this.cook) result.cook = true;
+    return result;
+  }
+};
+
+export {
+  registerNodeMetadata,
+  getNodeDisplayName,
+  registerNodeClasses,
+  packagePathToType,
+  isStandardLibraryNode,
+  getNodeClass,
+  normalizeColor,
+  isColorValue,
+  CORE_TYPES2 as CORE_TYPES,
+  isCoreType,
+  normalizeType,
+  canConnect,
+  Node
+};
+//# sourceMappingURL=chunk-CTPLRSWF.js.map