@field/cascade 0.10.0 → 0.12.0

package/dist/cli/chunk-BZ63XQ3I.js

@@ -0,0 +1,1301 @@
+import {
+  canConnectTypes
+} from "./chunk-FWMSGKEH.js";
+
+// packages/runtime/src/edit/document.ts
+var SUBNET = "cascade.core.Subnet";
+var INPUT = "cascade.core.Input";
+var OUTPUT = "cascade.core.Output";
+function readWire(raw) {
+  if (Array.isArray(raw) && raw.length === 2 && Array.isArray(raw[0]) && Array.isArray(raw[1])) {
+    const [from, to] = raw;
+    if (typeof from[0] !== "string" || typeof to[0] !== "string") return null;
+    return {
+      from: { node: from[0], index: Number(from[1] ?? 0), port: String(from[2] ?? "") },
+      to: { node: to[0], index: Number(to[1] ?? 0), port: String(to[2] ?? "") }
+    };
+  }
+  if (raw && typeof raw === "object" && "source" in raw && "target" in raw) {
+    const { source, target } = raw;
+    return {
+      from: { node: source.nodeId, port: source.outputName, index: 0 },
+      to: { node: target.nodeId, port: target.inputName, index: 0 }
+    };
+  }
+  return null;
+}
+function writeWire(wire, style) {
+  if (style === "object") {
+    return {
+      source: { nodeId: wire.from.node, outputName: wire.from.port },
+      target: { nodeId: wire.to.node, inputName: wire.to.port }
+    };
+  }
+  return [
+    [wire.from.node, wire.from.index, wire.from.port],
+    [wire.to.node, wire.to.index, wire.to.port]
+  ];
+}
+function wireStyleOf(document) {
+  const first = document.connections?.[0];
+  return first && !Array.isArray(first) ? "object" : "tuple";
+}
+function wireLabel(wire) {
+  return `${wire.from.node}.${wire.from.port} -> ${wire.to.node}.${wire.to.port}`;
+}
+function sameEndpoint(a, b) {
+  return a.node === b.node && a.port === b.port;
+}
+function moduleOf(node) {
+  return String(node.module ?? node.type ?? "");
+}
+function parentOf(node) {
+  return typeof node.parent === "string" && node.parent ? node.parent : null;
+}
+function positionOf(node) {
+  const position = node.position;
+  if (Array.isArray(position)) return { x: Number(position[0]) || 0, y: Number(position[1]) || 0 };
+  if (position && typeof position === "object") {
+    const { x, y } = position;
+    return { x: Number(x) || 0, y: Number(y) || 0 };
+  }
+  return { x: 0, y: 0 };
+}
+function setPosition(node, point) {
+  const position = node.position;
+  const value = position && typeof position === "object" && !Array.isArray(position) ? { x: point.x, y: point.y } : [point.x, point.y];
+  setOrderedKey(node, "position", value, NODE_KEY_ORDER);
+}
+var NODE_KEY_ORDER = [
+  "id",
+  "module",
+  "type",
+  "position",
+  "source",
+  "file",
+  "code",
+  "comment",
+  "color",
+  "parent",
+  "params",
+  "promotions",
+  "inputs",
+  "props",
+  "bypass",
+  "cook",
+  "state"
+];
+function setOrderedKey(target, key, value, order) {
+  if (key in target) {
+    target[key] = value;
+    return;
+  }
+  const rank = order.indexOf(key);
+  const entries = Object.entries(target);
+  const at = rank === -1 ? -1 : entries.findIndex(([name]) => {
+    const other = order.indexOf(name);
+    return other > rank;
+  });
+  if (at === -1) {
+    target[key] = value;
+    return;
+  }
+  for (const [name] of entries) delete target[name];
+  entries.splice(at, 0, [key, value]);
+  for (const [name, entry] of entries) target[name] = entry;
+}
+function portsFromDefinition(definition) {
+  const list = (record) => Object.entries(record ?? {}).map(([name, port], index) => {
+    const value = port;
+    return {
+      name,
+      index,
+      kind: value.kind === "trigger" ? "trigger" : "data",
+      type: value.type ?? "any",
+      variadic: value.variadic === true
+    };
+  });
+  return {
+    inputs: list(definition.inputs),
+    outputs: list(definition.outputs)
+  };
+}
+function subnetPorts(children) {
+  const boundary = (module, indexProp, prefix) => {
+    const found = children.filter((child) => moduleOf(child) === module).map((child) => ({ index: integer(child.props?.[indexProp]), type: String(child.props?.dataType || "any") })).filter((entry) => entry.index >= 0);
+    const max = found.length ? Math.max(...found.map((entry) => entry.index)) : -1;
+    return Array.from({ length: max + 1 }, (_, index) => ({
+      name: `${prefix}_${index}`,
+      index,
+      kind: "data",
+      type: found.find((entry) => entry.index === index)?.type ?? "any",
+      variadic: false
+    }));
+  };
+  return {
+    inputs: boundary(INPUT, "inputIndex", "input"),
+    outputs: boundary(OUTPUT, "outputIndex", "output")
+  };
+}
+function typesConnect(from, to) {
+  if (!from || !to) return true;
+  if (from.kind !== to.kind) return false;
+  return from.kind === "trigger" || canConnectTypes(from.type, to.type);
+}
+function integer(value) {
+  const number = Number(value ?? 0);
+  return Number.isInteger(number) ? number : -1;
+}
+function jsonEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a !== typeof b || a === null || b === null || typeof a !== "object") return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a)) {
+    const other = b;
+    return a.length === other.length && a.every((value, index) => jsonEqual(value, other[index]));
+  }
+  const left = a;
+  const right = b;
+  const keys = Object.keys(left);
+  return keys.length === Object.keys(right).length && keys.every((key) => key in right && jsonEqual(left[key], right[key]));
+}
+
+// packages/runtime/src/edit/layout.ts
+var DEFAULT_STEP = Object.freeze({ x: 0, y: 190 });
+var COLUMN_GAP = 260;
+var ROW_GAP = 190;
+var ORIGIN = Object.freeze({ x: 40, y: 40 });
+var CLEARANCE = Object.freeze({ x: 210, y: 120 });
+var MAX_LANES = 24;
+function flowStep(wires) {
+  const deltas = wires.map(({ from, to }) => ({ x: to.x - from.x, y: to.y - from.y })).filter((delta) => Math.hypot(delta.x, delta.y) >= 60);
+  if (!deltas.length) return DEFAULT_STEP;
+  const step = { x: median(deltas.map((d) => d.x)), y: median(deltas.map((d) => d.y)) };
+  const down = Math.abs(step.y) >= Math.abs(step.x);
+  const across = deltas.map((d) => down ? d.x : d.y);
+  const agree = across.every((value) => Math.sign(value) === Math.sign(across[0]) && Math.abs(value - median(across)) <= Math.abs(median(across)) * 0.25);
+  if (agree) return step;
+  return down ? { x: 0, y: step.y } : { x: step.x, y: 0 };
+}
+function placeNode({ siblings, upstream, downstream, step }) {
+  const anchor = anchorFor(siblings, upstream, downstream, step);
+  const lane = laneStep(step);
+  for (let attempt = 0; attempt <= MAX_LANES * 2; attempt += 1) {
+    const offset = attempt === 0 ? 0 : (attempt % 2 === 1 ? 1 : -1) * Math.ceil(attempt / 2);
+    const candidate = round({ x: anchor.x + lane.x * offset, y: anchor.y + lane.y * offset });
+    if (!siblings.some((other) => overlaps(other, candidate))) return candidate;
+  }
+  return round(anchor);
+}
+function isOccupied(siblings, point) {
+  return siblings.some((other) => overlaps(other, point));
+}
+function anchorFor(siblings, upstream, downstream, step) {
+  const unit = normalise(step);
+  if (upstream.length) {
+    return add(alongFlow(mean(upstream), unit, Math.max(...upstream.map((p) => dot(p, unit)))), step);
+  }
+  if (downstream.length) {
+    return subtract(alongFlow(mean(downstream), unit, Math.min(...downstream.map((p) => dot(p, unit)))), step);
+  }
+  if (!siblings.length) return ORIGIN;
+  const lane = laneStep(step);
+  const across = normalise(lane);
+  const furthest = Math.max(...siblings.map((p) => dot(p, across)));
+  const start = Math.min(...siblings.map((p) => dot(p, unit)));
+  return {
+    x: across.x * furthest + unit.x * start + lane.x,
+    y: across.y * furthest + unit.y * start + lane.y
+  };
+}
+function laneStep(step) {
+  return Math.abs(step.y) >= Math.abs(step.x) ? { x: COLUMN_GAP, y: 0 } : { x: 0, y: ROW_GAP };
+}
+function alongFlow(point, unit, target) {
+  const shift = target - dot(point, unit);
+  return { x: point.x + unit.x * shift, y: point.y + unit.y * shift };
+}
+function overlaps(a, b) {
+  return Math.abs(a.x - b.x) < CLEARANCE.x && Math.abs(a.y - b.y) < CLEARANCE.y;
+}
+function median(values) {
+  const sorted = [...values].sort((a, b) => a - b);
+  const middle = Math.floor(sorted.length / 2);
+  return sorted.length % 2 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2;
+}
+function mean(points) {
+  return {
+    x: points.reduce((sum, p) => sum + p.x, 0) / points.length,
+    y: points.reduce((sum, p) => sum + p.y, 0) / points.length
+  };
+}
+function normalise(p) {
+  const length = Math.hypot(p.x, p.y) || 1;
+  return { x: p.x / length, y: p.y / length };
+}
+var dot = (a, b) => a.x * b.x + a.y * b.y;
+var add = (a, b) => ({ x: a.x + b.x, y: a.y + b.y });
+var subtract = (a, b) => ({ x: a.x - b.x, y: a.y - b.y });
+var round = (p) => ({ x: Math.round(p.x), y: Math.round(p.y) });
+
+// packages/runtime/src/edit/parameters.ts
+function parameterSlot(definition, name) {
+  if (!definition) {
+    return { field: "props", type: void 0, default: void 0, hasDefault: false, defaultExpression: false, options: void 0 };
+  }
+  const prop = definition.props?.[name];
+  if (prop) {
+    return {
+      field: "props",
+      type: String(prop.type),
+      default: prop.default,
+      hasDefault: "default" in prop,
+      defaultExpression: typeof prop.expression === "string",
+      options: Array.isArray(prop.options) ? prop.options.map(optionValue) : void 0
+    };
+  }
+  const input = definition.inputs?.[name];
+  if (input && input.kind === "data") {
+    return {
+      field: "inputs",
+      type: String(input.type),
+      default: input.default,
+      hasDefault: "default" in input,
+      defaultExpression: false,
+      options: Array.isArray(input.options) ? input.options.map(optionValue) : void 0
+    };
+  }
+  const props = Object.keys(definition.props ?? {});
+  const inputs = Object.entries(definition.inputs ?? {}).filter(([, port]) => port.kind === "data").map(([portName]) => portName);
+  return {
+    error: `has no parameter "${name}"` + (props.length ? `; props: ${props.join(", ")}` : "") + (inputs.length ? `; inputs: ${inputs.join(", ")}` : "")
+  };
+}
+function applyParameterChange(node, name, slot, change) {
+  if (slot.field === "inputs" && (change.expression !== void 0 || change.keys?.length || change.removeKeys?.length)) {
+    throw new Error(`${node.id}.${name} is an input; expressions and keyframes bind props only. Wire a node into it instead.`);
+  }
+  const before = readStored(node, name, slot.field);
+  if (change.unset) {
+    writeStored(node, name, slot.field, void 0, slot);
+    return { before, after: void 0 };
+  }
+  let binding = toBinding(before, slot);
+  if (change.value !== void 0) {
+    binding = { ...binding, value: coerceValue(change.value, slot, change.fromText === true, `${node.id}.${name}`) };
+  }
+  if (change.expression !== void 0) {
+    binding = { ...binding, expression: change.expression || void 0 };
+  }
+  if (change.keys?.length || change.removeKeys?.length) {
+    binding = { ...binding, keys: updateKeys(binding.keys, change) };
+  }
+  const after = fromBinding(binding, slot);
+  writeStored(node, name, slot.field, after, slot);
+  return { before, after: readStored(node, name, slot.field) };
+}
+function readStored(node, name, field) {
+  if (field === "props") return node.props?.[name];
+  const inputs = node.inputs;
+  if (Array.isArray(inputs)) {
+    const entry = inputs.find((item) => item?.name === name);
+    return entry ? "defaultValue" in entry ? entry.defaultValue : entry.value : void 0;
+  }
+  return inputs && typeof inputs === "object" ? inputs[name] : void 0;
+}
+function isBoundValue(stored) {
+  return !!stored && typeof stored === "object" && !Array.isArray(stored) && "value" in stored && ("expression" in stored || "channel" in stored);
+}
+function toBinding(stored, slot) {
+  if (isBoundValue(stored)) {
+    return {
+      value: stored.value,
+      expression: stored.expression,
+      keys: Array.isArray(stored.channel?.keys) ? stored.channel.keys : []
+    };
+  }
+  return { value: stored === void 0 ? slot.default : stored, keys: [] };
+}
+function fromBinding(binding, slot) {
+  if (binding.expression || binding.keys.length) {
+    return {
+      value: binding.value,
+      ...binding.expression ? { expression: binding.expression } : {},
+      ...binding.keys.length ? { channel: { keys: binding.keys } } : {}
+    };
+  }
+  if (binding.value === void 0) return void 0;
+  if (slot.hasDefault && !slot.defaultExpression && jsonEqual(binding.value, slot.default)) return void 0;
+  return binding.value;
+}
+function updateKeys(keys, change) {
+  const byFrame = new Map(keys.map((key) => [key.frame, key]));
+  for (const frame of change.removeKeys ?? []) byFrame.delete(frame);
+  for (const key of change.keys ?? []) {
+    if (!Number.isFinite(key.frame) || !Number.isFinite(key.value)) {
+      throw new Error(`A keyframe needs a numeric frame and value (got ${key.frame}=${key.value})`);
+    }
+    const interpolation = change.interpolation ?? byFrame.get(key.frame)?.interpolation;
+    byFrame.set(key.frame, interpolation && interpolation !== "smooth" ? { frame: key.frame, value: key.value, interpolation } : { frame: key.frame, value: key.value });
+  }
+  return [...byFrame.values()].sort((a, b) => a.frame - b.frame);
+}
+function writeStored(node, name, field, value, slot) {
+  if (field === "props") {
+    const props = node.props ?? {};
+    if (value === void 0) delete props[name];
+    else props[name] = value;
+    if (Object.keys(props).length) setOrderedKey(node, "props", props, NODE_KEY_ORDER);
+    else delete node.props;
+    return;
+  }
+  const inputs = node.inputs;
+  if (inputs && typeof inputs === "object" && !Array.isArray(inputs)) {
+    const record = inputs;
+    if (value === void 0) delete record[name];
+    else record[name] = value;
+    if (!Object.keys(record).length) delete node.inputs;
+    return;
+  }
+  const list = Array.isArray(inputs) ? inputs : [];
+  const at = list.findIndex((item) => item?.name === name);
+  if (value === void 0) {
+    if (at !== -1) list.splice(at, 1);
+  } else if (at !== -1) {
+    const entry = list[at];
+    const key = "value" in entry && !("defaultValue" in entry) ? "value" : "defaultValue";
+    list[at] = { ...entry, [key]: value };
+  } else {
+    list.push({ name, defaultValue: value, ...slot.type ? { dataType: slot.type } : {} });
+  }
+  if (list.length) setOrderedKey(node, "inputs", list, NODE_KEY_ORDER);
+  else delete node.inputs;
+}
+function coerceValue(raw, slot, fromText, where) {
+  const type = slot.type;
+  let value = raw;
+  if (fromText && typeof raw === "string") {
+    value = type === "string" ? unquote(raw) : parseText(raw, type);
+  }
+  if (!type) return value;
+  const fail = (expected) => {
+    throw new Error(`${where} expects ${expected} (got ${JSON.stringify(value)})`);
+  };
+  switch (type) {
+    case "float":
+      if (typeof value !== "number" || !Number.isFinite(value)) fail("a number");
+      break;
+    case "int":
+      if (typeof value !== "number" || !Number.isInteger(value)) fail("an integer");
+      break;
+    case "bool":
+      if (typeof value !== "boolean") fail("true or false");
+      break;
+    case "string":
+      if (typeof value !== "string") value = String(value);
+      break;
+    case "color":
+      value = colorValue(value) ?? fail("a colour: #rrggbb, #rrggbbaa or [r, g, b, a] in 0..1");
+      break;
+    default: {
+      const size = /^(?:vec|mat)(\d)i?$/.exec(type);
+      if (size) {
+        const length = type.startsWith("mat") ? Number(size[1]) ** 2 : Number(size[1]);
+        if (!Array.isArray(value) || value.length !== length || !value.every((n) => typeof n === "number" && Number.isFinite(n))) {
+          fail(`${length} numbers, e.g. ${Array.from({ length }, () => "0").join(",")}`);
+        }
+        if (type.endsWith("i") && !value.every(Number.isInteger)) fail(`${length} integers`);
+      }
+    }
+  }
+  if (slot.options && !slot.options.some((option) => jsonEqual(option, value))) {
+    fail(`one of ${slot.options.map((option) => JSON.stringify(option)).join(", ")}`);
+  }
+  return value;
+}
+function parseText(text, type) {
+  const trimmed = text.trim();
+  if (type && /^(?:vec|mat)\d/.test(type) && !trimmed.startsWith("[")) {
+    return trimmed.split(",").map((part) => Number(part.trim()));
+  }
+  if (type === "color" && trimmed.startsWith("#")) return trimmed;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return trimmed;
+  }
+}
+function unquote(text) {
+  if (text.length >= 2 && text.startsWith('"') && text.endsWith('"')) {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+  return text;
+}
+function colorValue(value) {
+  if (typeof value === "string") {
+    const hex = /^#([0-9a-f]{6})([0-9a-f]{2})?$/i.exec(value.trim());
+    if (!hex) return null;
+    const digits = hex[1] + (hex[2] ?? "ff");
+    return [0, 2, 4, 6].map((at) => Math.round(parseInt(digits.slice(at, at + 2), 16) / 255 * 1e4) / 1e4);
+  }
+  if (Array.isArray(value) && (value.length === 3 || value.length === 4) && value.every((n) => typeof n === "number")) {
+    return value.length === 3 ? [...value, 1] : [...value];
+  }
+  return null;
+}
+function optionValue(option) {
+  return option && typeof option === "object" && !Array.isArray(option) && "value" in option ? option.value : option;
+}
+
+// packages/runtime/src/edit/graphEditor.ts
+var GraphEditError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "GraphEditError";
+  }
+};
+var GraphEditor = class {
+  constructor(document, options) {
+    this.document = document;
+    this.options = options;
+    this.warnings = [];
+    if (!Array.isArray(document.nodes)) throw new GraphEditError("Graph document must contain a nodes array");
+  }
+  // -------------------------------------------------------------------------
+  // Nodes
+  addNode(input) {
+    const parent = input.parent ? this.requireContainer(input.parent) : null;
+    const id = input.id ?? this.uniqueId(defaultIdFor(input.module));
+    assertValidId(id);
+    if (this.findNode(id)) throw new GraphEditError(`A node with id "${id}" already exists`);
+    const source = sourceFor(input.module);
+    const node = { id, module: input.module, position: [0, 0] };
+    if (source) node.source = source;
+    if (input.comment) node.comment = input.comment;
+    if (parent) node.parent = parent.id;
+    this.insertNode(node, parent?.id ?? null);
+    for (const [name, value] of Object.entries(input.props ?? {})) {
+      this.setParameterOn(node, name, { value, fromText: input.fromText === true });
+    }
+    setPosition(node, input.position ?? this.placeFor(node));
+    return { node: this.summary(node) };
+  }
+  /**
+   * Remove a node and every wire touching it. A subnet with children is
+   * refused unless `recursive`, because removing a container silently would
+   * remove everything in it.
+   */
+  removeNode(id, options = {}) {
+    const node = this.requireNode(id);
+    const descendants2 = this.descendantsOf(id);
+    if (descendants2.length && !options.recursive) {
+      throw new GraphEditError(`${id} contains ${descendants2.length} node${descendants2.length === 1 ? "" : "s"}; remove with --recursive, or dissolve it with "subnet dissolve"`);
+    }
+    const parent = parentOf(node);
+    const boundary = parent ? this.boundaryIndex(node) : null;
+    if (boundary && parent) {
+      return { removed: [id], wires: this.removeBoundary(this.requireNode(parent), boundary.kind, boundary.index) };
+    }
+    const removed = /* @__PURE__ */ new Set([id, ...descendants2.map((child) => child.id)]);
+    const wires = this.wires().filter(({ wire }) => wire && (removed.has(wire.from.node) || removed.has(wire.to.node))).map(({ index, wire }) => ({ index, label: wireLabel(wire) }));
+    this.removeWires(wires.map((wire) => wire.index));
+    this.document.nodes = this.document.nodes.filter((candidate) => !removed.has(candidate.id));
+    this.forgetInAnnotations(removed);
+    if (this.document.editor && JSON.stringify(this.document.editor).includes(JSON.stringify(id))) {
+      this.warnings.push(`The editor section still names ${id}; republish or unpublish its parameters`);
+    }
+    return { removed: [...removed], wires: wires.map((wire) => wire.label) };
+  }
+  // -------------------------------------------------------------------------
+  // Wires
+  /**
+   * Wire `from` (`node.output`) to `to` (`node.input`). A port name may be
+   * left off when the node has exactly one port on that side.
+   *
+   * The two nodes may be in different subnets: the wire is then routed
+   * through the subnets' `Output` and `Input` nodes, which are created (or
+   * reused) as needed, so no wire ever crosses a boundary directly.
+   *
+   * A node wired for the first time is moved next to its new neighbour, so a
+   * node created by `node add` and then connected ends up where a person would
+   * have put it. Pass `layout: false` to leave positions alone.
+   */
+  connect(from, to, options = {}) {
+    const source = this.resolveEndpoint(from, "output");
+    const target = this.resolveEndpoint(to, "input");
+    const targetNode = this.requireNode(target.endpoint.node);
+    if (!typesConnect(source.info, target.info)) {
+      throw new GraphEditError(`${from} (${source.info?.type}) cannot feed ${to} (${target.info?.type})`);
+    }
+    const routed = this.routeAcross(source.endpoint, parentOf(targetNode));
+    const sourceNode = this.requireNode(routed.node);
+    const wires = this.wires();
+    const wire = { from: routed, to: target.endpoint };
+    if (wires.some(({ wire: other }) => other && sameEndpoint(other.from, wire.from) && sameEndpoint(other.to, wire.to))) {
+      this.warnings.push(`${wireLabel(wire)} was already connected`);
+      return { wire: wireLabel(wire) };
+    }
+    const sourceWasFree = routed === source.endpoint && !this.isWired(routed.node);
+    const targetWasFree = !this.isWired(target.endpoint.node);
+    let replaced;
+    const existing = target.info?.variadic ? void 0 : wires.find(({ wire: other }) => other && sameEndpoint(other.to, wire.to));
+    if (existing?.wire) {
+      replaced = wireLabel(existing.wire);
+      this.document.connections[existing.index] = writeWire(wire, wireStyleOf(this.document));
+      this.warnings.push(`${target.endpoint.node}.${target.endpoint.port} was fed by ${existing.wire.from.node}.${existing.wire.from.port}; replaced`);
+    } else {
+      this.appendWire(wire);
+    }
+    let moved;
+    if (options.layout !== false) {
+      if (targetWasFree && !sourceWasFree) moved = this.relayout(targetNode);
+      else if (sourceWasFree && !targetWasFree) moved = this.relayout(sourceNode);
+      else if (sourceWasFree && targetWasFree) moved = this.relayout(targetNode);
+    }
+    return { wire: wireLabel(wire), ...replaced ? { replaced } : {}, ...moved ? { moved } : {} };
+  }
+  /**
+   * The endpoint on `level`'s canvas that carries `source`: the source itself
+   * when it is already there, otherwise a subnet port reached by passing out
+   * through `Output` nodes to the common ancestor and in through `Input` nodes
+   * to `level`. Existing boundaries carrying the same value are reused.
+   */
+  routeAcross(source, level) {
+    const start = parentOf(this.requireNode(source.node));
+    if (start === level) return source;
+    const down = [...this.ancestorsOf(level), ...level ? [level] : []];
+    const up = [...this.ancestorsOf(start), ...start ? [start] : []];
+    let common = 0;
+    while (common < down.length && common < up.length && down[common] === up[common]) common += 1;
+    let current = source;
+    const touched = /* @__PURE__ */ new Map();
+    for (const subnetId of up.slice(common).reverse()) {
+      const subnet = this.requireNode(subnetId);
+      const created = touched.get(subnetId) ?? [];
+      const { node: output, isNew } = this.outputFor(subnet, current, created);
+      if (isNew) this.appendWire({ from: current, to: { node: output.id, port: "input", index: 0 } });
+      touched.set(subnetId, created);
+      current = this.subnetPort(subnet, "output", output);
+    }
+    let lastInput;
+    for (const subnetId of down.slice(common)) {
+      const subnet = this.requireNode(subnetId);
+      const created = touched.get(subnetId) ?? [];
+      const existing = this.inputCarrying(subnet, current, /* @__PURE__ */ new Set());
+      lastInput = existing ?? this.createBoundary(subnet, "input", current, created);
+      if (!existing) this.appendWire({ from: current, to: this.subnetPort(subnet, "input", lastInput) });
+      touched.set(subnetId, created);
+      current = { node: lastInput.id, port: "output", index: 0 };
+    }
+    for (const [subnetId, created] of touched) {
+      this.nameBoundaries(this.requireNode(subnetId), created);
+      for (const node of created) setPosition(node, this.placeFor(node));
+    }
+    if (lastInput) current = { node: lastInput.id, port: "output", index: 0 };
+    return current;
+  }
+  /**
+   * Remove wires. `disconnect a.out b.in` removes that wire; `disconnect b.in`
+   * removes whatever feeds that input; `disconnect a.out` removes everything
+   * that output feeds.
+   */
+  disconnect(first, second) {
+    let matches;
+    if (second !== void 0) {
+      const source = this.resolveEndpoint(first, "output").endpoint;
+      const target = this.resolveEndpoint(second, "input").endpoint;
+      matches = (wire) => sameEndpoint(wire.from, source) && sameEndpoint(wire.to, target);
+    } else {
+      const { node, port } = splitEndpoint(first);
+      this.requireNode(node);
+      matches = (wire) => wire.to.node === node && (!port || wire.to.port === port) || wire.from.node === node && (!port || wire.from.port === port) && !!port;
+    }
+    const found = this.wires().filter(({ wire }) => wire && matches(wire));
+    if (!found.length) throw new GraphEditError(`No wire matches ${second === void 0 ? first : `${first} -> ${second}`}`);
+    this.removeWires(found.map(({ index }) => index));
+    return { removed: found.map(({ wire }) => wireLabel(wire)) };
+  }
+  // -------------------------------------------------------------------------
+  // Parameters
+  /** Change `node.param`: its value, expression or keyframes. */
+  setParameter(target, change) {
+    const { node: id, port: name } = splitEndpoint(target);
+    if (!name) throw new GraphEditError(`Name a parameter: ${target}.<param>`);
+    const node = this.requireNode(id);
+    const result = this.setParameterOn(node, name, change);
+    if (result.field === "inputs" && this.wires().some(({ wire }) => wire && wire.to.node === id && wire.to.port === name)) {
+      this.warnings.push(`${id}.${name} is wired; the stored value is used only when the wire is removed`);
+    }
+    return { node: id, param: name, field: result.field, before: result.before ?? null, after: result.after ?? null };
+  }
+  // -------------------------------------------------------------------------
+  // Subnets
+  /**
+   * Group sibling nodes into a new subnet. Wires that now cross its boundary
+   * are routed through new `Input` and `Output` nodes, named after the port
+   * they carry, so the subnet's ports read as what flows through them.
+   */
+  createSubnet(input) {
+    const members = this.requireSiblings(input.nodes);
+    const parent = parentOf(members[0]);
+    const id = input.id ?? this.uniqueId(input.label ? slug(input.label) : "subnet");
+    assertValidId(id);
+    if (this.findNode(id)) throw new GraphEditError(`A node with id "${id}" already exists`);
+    const step = this.stepIn(parent);
+    const first = members.reduce((best, node) => along(positionOf(node), step) < along(positionOf(best), step) ? node : best);
+    const subnet = { id, module: SUBNET, position: [0, 0], source: "stdlib" };
+    if (input.label) subnet.comment = input.label;
+    if (parent) subnet.parent = parent;
+    setPosition(subnet, positionOf(first));
+    const at = Math.min(...members.map((node) => this.document.nodes.indexOf(node)));
+    this.document.nodes.splice(at, 0, subnet);
+    const created = this.moveIn(new Set(members.map((node) => node.id)), subnet);
+    return {
+      subnet: this.summary(subnet),
+      inputs: created.filter((node) => moduleOf(node) === INPUT).map((node) => node.id),
+      outputs: created.filter((node) => moduleOf(node) === OUTPUT).map((node) => node.id)
+    };
+  }
+  /** The inverse of `createSubnet`: lift the children out and remove the subnet. */
+  dissolveSubnet(id) {
+    const subnet = this.requireNode(id);
+    if (moduleOf(subnet) !== SUBNET) throw new GraphEditError(`${id} is not a subnet`);
+    const members = this.childrenOf(id).filter((node) => !isBoundary(node));
+    if (members.length) this.moveOut(new Set(members.map((node) => node.id)), subnet);
+    for (const leftover of this.childrenOf(id)) {
+      this.warnings.push(`${leftover.id} carried nothing after the dissolve and was removed`);
+    }
+    this.removeNode(id, { recursive: true });
+    return { lifted: members.map((node) => node.id) };
+  }
+  /**
+   * Move sibling nodes to another subnet (`null` for the top level), one level
+   * at a time — out to the common ancestor, then in — rewiring through each
+   * boundary on the way.
+   */
+  moveNodes(ids, to) {
+    const members = this.requireSiblings(ids);
+    const target = to ? this.requireNode(to) : null;
+    if (target && moduleOf(target) !== SUBNET) throw new GraphEditError(`${to} is not a subnet`);
+    const memberIds = new Set(members.map((node) => node.id));
+    if (target && (memberIds.has(target.id) || this.ancestorsOf(target.id).some((id) => memberIds.has(id)))) {
+      throw new GraphEditError(`Cannot move ${target.id} into itself`);
+    }
+    const destination = target?.id ?? null;
+    const targetPath = [...this.ancestorsOf(destination), ...destination ? [destination] : []];
+    let current = parentOf(members[0]);
+    while (current !== null && !targetPath.includes(current)) {
+      const container = this.requireNode(current);
+      this.moveOut(memberIds, container);
+      current = parentOf(container);
+    }
+    while (current !== destination) {
+      const next = targetPath[targetPath.indexOf(current) + 1];
+      this.moveIn(memberIds, this.requireNode(next));
+      current = next;
+    }
+    const placed = [];
+    for (const node of members) {
+      const others = this.childrenOf(destination).filter((other) => !memberIds.has(other.id)).map(positionOf);
+      const moved = isOccupied(others, positionOf(node)) ? this.relayout(node) : void 0;
+      if (moved) placed.push(moved);
+    }
+    return { moved: [...memberIds], to: destination, placed };
+  }
+  // -------------------------------------------------------------------------
+  // Internals: boundary rewiring
+  /**
+   * Move sibling nodes from the subnet's parent into the subnet.
+   *
+   * A wire from a member to the subnet's own input collapses (the member is
+   * now inside, so it feeds that input's consumers directly), and a wire from
+   * outside to a member is routed through an `Input` — reusing one that
+   * already carries the same source. The mirror holds for outputs. Wires are
+   * rewritten in place where possible, which is what lets `moveOut` restore
+   * the original file exactly.
+   */
+  moveIn(members, subnet) {
+    for (const id of members) setOrderedKey(this.requireNode(id), "parent", subnet.id, NODE_KEY_ORDER);
+    const created = [];
+    const removed = /* @__PURE__ */ new Set();
+    const total = this.connections().length;
+    for (let index = 0; index < total; index += 1) {
+      const wire = readWire(this.connections()[index]);
+      if (!wire || removed.has(index)) continue;
+      const fromMember = members.has(wire.from.node);
+      const toMember = members.has(wire.to.node);
+      if (fromMember === toMember) continue;
+      if (fromMember && wire.to.node === subnet.id) {
+        const k = portNumber(wire.to.port);
+        const boundary = this.boundaryNode(subnet, "input", k);
+        if (boundary) {
+          for (const consumer of this.wires().filter(({ wire: w }) => w?.from.node === boundary.id)) {
+            this.replaceWire(consumer.index, { from: wire.from, to: consumer.wire.to });
+          }
+        }
+        removed.add(index);
+        this.removeBoundaryNode(subnet, "input", k, removed);
+      } else if (fromMember) {
+        const { node: output, isNew } = this.outputFor(subnet, wire.from, created);
+        this.replaceWire(index, { from: this.subnetPort(subnet, "output", output), to: wire.to });
+        if (isNew) this.appendWire({ from: wire.from, to: { node: output.id, port: "input", index: 0 } });
+      } else if (wire.from.node === subnet.id) {
+        const k = portNumber(wire.from.port);
+        const boundary = this.boundaryNode(subnet, "output", k);
+        const feed = boundary && this.wires().find(({ wire: w }) => w?.to.node === boundary.id);
+        if (feed?.wire) this.replaceWire(index, { from: feed.wire.from, to: wire.to });
+        else removed.add(index);
+        const stillUsed = this.wires().some(({ index: i, wire: w }) => !removed.has(i) && w?.from.node === subnet.id && w.from.port === wire.from.port && i !== index);
+        if (!stillUsed && boundary) {
+          if (feed) removed.add(feed.index);
+          this.removeBoundaryNode(subnet, "output", k, removed);
+        }
+      } else {
+        const existing = this.inputCarrying(subnet, wire.from, removed);
+        if (existing) {
+          removed.add(index);
+          this.appendWire({ from: { node: existing.id, port: "output", index: 0 }, to: wire.to });
+        } else {
+          const input = this.createBoundary(subnet, "input", wire.from, created);
+          this.replaceWire(index, { from: wire.from, to: this.subnetPort(subnet, "input", input) });
+          this.appendWire({ from: { node: input.id, port: "output", index: 0 }, to: wire.to });
+        }
+      }
+    }
+    this.removeWires([...removed]);
+    this.nameBoundaries(subnet, created);
+    for (const node of created) setPosition(node, this.placeFor(node));
+    return created;
+  }
+  /** Move nodes out of a subnet into its parent. The mirror of `moveIn`. */
+  moveOut(members, subnet) {
+    const created = [];
+    const removed = /* @__PURE__ */ new Set();
+    const total = this.connections().length;
+    for (let index = 0; index < total; index += 1) {
+      const wire = readWire(this.connections()[index]);
+      if (!wire || removed.has(index)) continue;
+      const fromMember = members.has(wire.from.node);
+      const toMember = members.has(wire.to.node);
+      if (fromMember === toMember) continue;
+      const other = this.findNode(fromMember ? wire.to.node : wire.from.node);
+      if (fromMember && other && moduleOf(other) === OUTPUT && parentOf(other) === subnet.id) {
+        const k = integer(other.props?.outputIndex);
+        for (const consumer of this.wires().filter(({ wire: w }) => w?.from.node === subnet.id && w.from.port === `output_${k}`)) {
+          this.replaceWire(consumer.index, { from: wire.from, to: consumer.wire.to });
+        }
+        removed.add(index);
+        this.removeBoundaryNode(subnet, "output", k, removed);
+      } else if (fromMember) {
+        const existing = this.inputCarrying(subnet, wire.from, removed);
+        const input = existing ?? this.createBoundary(subnet, "input", wire.from, created);
+        this.replaceWire(index, { from: { node: input.id, port: "output", index: 0 }, to: wire.to });
+        if (!existing) this.appendWire({ from: wire.from, to: this.subnetPort(subnet, "input", input) });
+      } else if (other && moduleOf(other) === INPUT && parentOf(other) === subnet.id) {
+        const k = integer(other.props?.inputIndex);
+        const feed = this.wires().find(({ index: i, wire: w }) => !removed.has(i) && w?.to.node === subnet.id && w.to.port === `input_${k}`);
+        const otherConsumers = this.wires().some(({ index: i, wire: w }) => i !== index && !removed.has(i) && w?.from.node === other.id);
+        if (!feed?.wire) {
+          removed.add(index);
+          this.warnings.push(`${wire.to.node}.${wire.to.port} was fed by an unwired subnet input; it is now unwired`);
+        } else if (!otherConsumers) {
+          this.replaceWire(feed.index, { from: feed.wire.from, to: wire.to });
+          removed.add(index);
+        } else {
+          this.replaceWire(index, { from: feed.wire.from, to: wire.to });
+        }
+        if (!otherConsumers) this.removeBoundaryNode(subnet, "input", k, removed);
+      } else {
+        const { node: output, isNew } = this.outputFor(subnet, wire.from, created);
+        this.replaceWire(index, { from: this.subnetPort(subnet, "output", output), to: wire.to });
+        if (isNew) this.appendWire({ from: wire.from, to: { node: output.id, port: "input", index: 0 } });
+      }
+    }
+    this.removeWires([...removed]);
+    const parent = parentOf(subnet);
+    for (const id of members) {
+      const node = this.requireNode(id);
+      if (parent) setOrderedKey(node, "parent", parent, NODE_KEY_ORDER);
+      else delete node.parent;
+    }
+    this.nameBoundaries(subnet, created);
+    for (const node of created) setPosition(node, this.placeFor(node));
+    return created;
+  }
+  /** An `Output` in the subnet already fed by `source`, or a new one. */
+  outputFor(subnet, source, created) {
+    const existing = this.childrenOf(subnet.id).find((node) => moduleOf(node) === OUTPUT && this.wires().some(({ wire }) => wire?.to.node === node.id && sameEndpoint(wire.from, source)));
+    return existing ? { node: existing, isNew: false } : { node: this.createBoundary(subnet, "output", source, created), isNew: true };
+  }
+  /** An `Input` in the subnet whose outside feed is `source`. */
+  inputCarrying(subnet, source, removed) {
+    const feed = this.wires().find(({ index, wire }) => !removed.has(index) && wire?.to.node === subnet.id && sameEndpoint(wire.from, source));
+    return feed ? this.boundaryNode(subnet, "input", portNumber(feed.wire.to.port)) : void 0;
+  }
+  createBoundary(subnet, kind, carries, created) {
+    const ports = subnetPorts(this.childrenOf(subnet.id));
+    const index = (kind === "input" ? ports.inputs : ports.outputs).length;
+    const label = this.labelOf(carries);
+    const type = this.portInfo(carries.node, carries.port, "output")?.type ?? "any";
+    const id = this.uniqueId(`${subnet.id}-${kind === "input" ? "in" : "out"}-${slug(label)}`);
+    const node = {
+      id,
+      module: kind === "input" ? INPUT : OUTPUT,
+      position: [0, 0],
+      source: "stdlib",
+      comment: label,
+      parent: subnet.id,
+      props: kind === "input" ? { inputIndex: index, inputName: "", dataType: type } : { outputIndex: index, outputName: "", dataType: type }
+    };
+    this.insertNode(node, subnet.id);
+    created.push(node);
+    return node;
+  }
+  /**
+   * Name new boundary nodes after what they carry, readably. A port name is
+   * the natural label (`moment`, `canvas`), but not when it says nothing
+   * (`value`, `output`) or when two ports of the subnet would share it — three
+   * `mask` outputs read as one. Then the producing node's id is the label:
+   * `masks-out-cloud-mask` beside `masks-out-primary-lobe`.
+   */
+  nameBoundaries(subnet, created) {
+    const carried = (node) => {
+      const wire = moduleOf(node) === INPUT ? this.wires().find(({ wire: w }) => w?.to.node === subnet.id && w.to.port === `input_${integer(node.props?.inputIndex)}`)?.wire : this.wires().find(({ wire: w }) => w?.to.node === node.id)?.wire;
+      return wire?.from;
+    };
+    const relabel = created.flatMap((node) => {
+      const label = String(node.comment ?? "");
+      const sameSide = this.childrenOf(subnet.id).filter((other) => moduleOf(other) === moduleOf(node));
+      const shared = sameSide.filter((other) => other.comment === label).length > 1;
+      const source = carried(node);
+      return source && (shared || GENERIC_PORTS.has(label)) ? [{ node, label: source.node }] : [];
+    });
+    for (const { node, label } of relabel) this.relabelBoundary(subnet, node, label);
+  }
+  relabelBoundary(subnet, node, label) {
+    const kind = moduleOf(node) === INPUT ? "in" : "out";
+    const id = this.uniqueId(`${subnet.id}-${kind}-${slug(label)}`);
+    const previous = node.id;
+    node.id = id;
+    node.comment = label;
+    for (const { index, wire } of this.wires()) {
+      if (!wire || wire.from.node !== previous && wire.to.node !== previous) continue;
+      const rename = (end) => end.node === previous ? { ...end, node: id } : end;
+      this.replaceWire(index, { from: rename(wire.from), to: rename(wire.to) });
+    }
+  }
+  /** What a value is called: its port name, or for a subnet's own port, the name of the boundary behind it. */
+  labelOf(endpoint) {
+    const node = this.findNode(endpoint.node);
+    const port = /^(input|output)_(\d+)$/.exec(endpoint.port);
+    if (node && moduleOf(node) === SUBNET && port) {
+      const boundary = this.boundaryNode(node, port[1], Number(port[2]));
+      const name = boundary?.comment || boundary?.props?.[port[1] === "input" ? "inputName" : "outputName"];
+      if (typeof name === "string" && name) return name;
+    }
+    return endpoint.port || endpoint.node;
+  }
+  /**
+   * Remove boundary node k and keep the subnet's ports contiguous: the ports
+   * above it shift down one, and so do the wires that use them. Wires to the
+   * removed port itself are marked in `removed` for the caller to drop.
+   */
+  removeBoundaryNode(subnet, kind, k, removed) {
+    const node = this.boundaryNode(subnet, kind, k);
+    if (!node) return;
+    const indexProp = kind === "input" ? "inputIndex" : "outputIndex";
+    const port = `${kind}_${k}`;
+    for (const { index, wire } of this.wires()) {
+      if (!wire) continue;
+      const touchesPort = kind === "input" ? wire.to.node === subnet.id && wire.to.port === port : wire.from.node === subnet.id && wire.from.port === port;
+      if (touchesPort || wire.from.node === node.id || wire.to.node === node.id) removed.add(index);
+    }
+    this.document.nodes.splice(this.document.nodes.indexOf(node), 1);
+    for (const sibling of this.childrenOf(subnet.id)) {
+      if (moduleOf(sibling) !== (kind === "input" ? INPUT : OUTPUT)) continue;
+      const index = integer(sibling.props?.[indexProp]);
+      if (index > k) sibling.props[indexProp] = index - 1;
+    }
+    for (const { index, wire } of this.wires()) {
+      if (!wire || removed.has(index)) continue;
+      const end = kind === "input" ? wire.to : wire.from;
+      if (end.node !== subnet.id) continue;
+      const n = portNumber(end.port);
+      if (n <= k) continue;
+      const shifted = { node: subnet.id, port: `${kind}_${n - 1}`, index: n - 1 };
+      this.replaceWire(index, kind === "input" ? { from: wire.from, to: shifted } : { from: shifted, to: wire.to });
+    }
+  }
+  /** `rm` of a boundary node: the subnet loses that port. */
+  removeBoundary(subnet, kind, k) {
+    const removed = /* @__PURE__ */ new Set();
+    const before = this.wires();
+    this.removeBoundaryNode(subnet, kind, k, removed);
+    const labels = before.filter(({ index }) => removed.has(index)).map(({ wire }) => wireLabel(wire));
+    this.removeWires([...removed]);
+    this.warnings.push(`${subnet.id} lost its ${kind}_${k} port; higher ports were renumbered`);
+    return labels;
+  }
+  boundaryIndex(node) {
+    if (moduleOf(node) === INPUT) return { kind: "input", index: integer(node.props?.inputIndex) };
+    if (moduleOf(node) === OUTPUT) return { kind: "output", index: integer(node.props?.outputIndex) };
+    return null;
+  }
+  boundaryNode(subnet, kind, k) {
+    const module = kind === "input" ? INPUT : OUTPUT;
+    const indexProp = kind === "input" ? "inputIndex" : "outputIndex";
+    return this.childrenOf(subnet.id).find((node) => moduleOf(node) === module && integer(node.props?.[indexProp]) === k);
+  }
+  subnetPort(subnet, kind, boundary) {
+    const k = integer(boundary.props?.[kind === "input" ? "inputIndex" : "outputIndex"]);
+    return { node: subnet.id, port: `${kind}_${k}`, index: k };
+  }
+  // -------------------------------------------------------------------------
+  // Internals: lookup
+  findNode(id) {
+    return this.document.nodes.find((node) => node.id === id);
+  }
+  requireNode(id) {
+    const node = this.findNode(id);
+    if (node) return node;
+    const near = this.document.nodes.map((candidate) => candidate.id).filter((candidate) => candidate.includes(id) || id.includes(candidate)).slice(0, 5);
+    throw new GraphEditError(`No node "${id}"${near.length ? `; did you mean ${near.join(", ")}?` : ""}`);
+  }
+  childrenOf(parent) {
+    return this.document.nodes.filter((node) => parentOf(node) === parent);
+  }
+  descendantsOf(id) {
+    const result = [];
+    const queue = [id];
+    while (queue.length) {
+      const current = queue.shift();
+      for (const child of this.childrenOf(current)) {
+        result.push(child);
+        queue.push(child.id);
+      }
+    }
+    return result;
+  }
+  ancestorsOf(id) {
+    const chain = [];
+    let current = id ? parentOf(this.requireNode(id)) : null;
+    while (current) {
+      chain.unshift(current);
+      current = parentOf(this.requireNode(current));
+    }
+    return chain;
+  }
+  requireContainer(id) {
+    const node = this.requireNode(id);
+    const definition = this.options.definitionOf(moduleOf(node));
+    if (moduleOf(node) !== SUBNET && !definition?.container) throw new GraphEditError(`${id} is not a subnet`);
+    return node;
+  }
+  requireSiblings(ids) {
+    if (!ids.length) throw new GraphEditError("Name at least one node");
+    const nodes = [...new Set(ids)].map((id) => this.requireNode(id));
+    const parent = parentOf(nodes[0]);
+    const stray = nodes.find((node) => parentOf(node) !== parent);
+    if (stray) throw new GraphEditError(`${stray.id} is not in the same subnet as ${nodes[0].id}; move nodes from one subnet at a time`);
+    const boundary = nodes.find(isBoundary);
+    if (boundary && parent) throw new GraphEditError(`${boundary.id} is ${parent}'s ${moduleOf(boundary) === INPUT ? "input" : "output"}; it stays with its subnet`);
+    return nodes;
+  }
+  /** The ports a node has, or `null` when they are not statically known. */
+  portsOf(node) {
+    if (moduleOf(node) === SUBNET) return subnetPorts(this.childrenOf(node.id));
+    const definition = this.options.definitionOf(moduleOf(node));
+    return definition ? portsFromDefinition(definition) : null;
+  }
+  portInfo(nodeId, port, side) {
+    const node = this.findNode(nodeId);
+    const ports = node && this.portsOf(node);
+    return ports ? (side === "input" ? ports.inputs : ports.outputs).find((info) => info.name === port) : void 0;
+  }
+  /** `node.port` to a checked endpoint. A missing port name is filled in when only one would fit. */
+  resolveEndpoint(text, side) {
+    const { node: id, port } = splitEndpoint(text);
+    const node = this.requireNode(id);
+    const ports = this.portsOf(node);
+    if (!ports) {
+      if (!port) throw new GraphEditError(`${id} declares no static ports; name one: ${id}.<${side}>`);
+      this.warnings.push(`${id} (${moduleOf(node)}) has no static definition; ${port} is not checked`);
+      return { endpoint: { node: id, port, index: this.indexFromExistingWires(id, port, side) } };
+    }
+    const list = side === "input" ? ports.inputs : ports.outputs;
+    const info = port ? list.find((candidate) => candidate.name === port) : list.length === 1 ? list[0] : void 0;
+    if (!info) {
+      const names = list.map((candidate) => candidate.name).join(", ") || "none";
+      throw new GraphEditError(port ? `${id} has no ${side} "${port}"; ${side}s: ${names}` : `${id} has several ${side}s; name one: ${names}`);
+    }
+    return { endpoint: { node: id, port: info.name, index: info.index }, info };
+  }
+  indexFromExistingWires(node, port, side) {
+    for (const { wire } of this.wires()) {
+      const end = wire && (side === "input" ? wire.to : wire.from);
+      if (end && end.node === node && end.port === port) return end.index;
+    }
+    return 0;
+  }
+  isWired(id) {
+    return this.wires().some(({ wire }) => wire && (wire.from.node === id || wire.to.node === id));
+  }
+  setParameterOn(node, name, change) {
+    const slot = parameterSlot(this.options.definitionOf(moduleOf(node)), name);
+    if ("error" in slot) throw new GraphEditError(`${node.id} ${slot.error}`);
+    if (!this.options.definitionOf(moduleOf(node))) {
+      this.warnings.push(`${node.id} (${moduleOf(node)}) has no static definition; ${name} is stored as a prop unchecked`);
+    }
+    try {
+      return { field: slot.field, ...applyParameterChange(node, name, slot, change) };
+    } catch (error) {
+      throw new GraphEditError(error instanceof Error ? error.message : String(error));
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Internals: the connections array
+  connections() {
+    return this.document.connections ??= [];
+  }
+  /** Every connection with its array index; unreadable ones have `wire: null` and are left alone. */
+  wires() {
+    return this.connections().map((raw, index) => ({ index, wire: readWire(raw) }));
+  }
+  appendWire(wire) {
+    const style = wireStyleOf(this.document);
+    if (!this.document.connections) setOrderedKey(this.document, "connections", [], ["version", "metadata", "annotations", "nodes", "connections", "editor"]);
+    this.connections().push(writeWire(wire, style));
+  }
+  replaceWire(index, wire) {
+    this.connections()[index] = writeWire(wire, wireStyleOf(this.document));
+  }
+  removeWires(indices) {
+    const drop = new Set(indices);
+    if (!drop.size) return;
+    this.document.connections = this.connections().filter((_, index) => !drop.has(index));
+    if (!this.document.connections.length) delete this.document.connections;
+  }
+  // -------------------------------------------------------------------------
+  // Internals: placement and housekeeping
+  /** Insert after the last node of the same subnet, so a subnet's children stay together in the file. */
+  insertNode(node, parent) {
+    if (parent === null) {
+      this.document.nodes.push(node);
+      return;
+    }
+    const family = /* @__PURE__ */ new Set([parent, ...this.descendantsOf(parent).map((child) => child.id)]);
+    let at = -1;
+    this.document.nodes.forEach((candidate, index) => {
+      if (family.has(candidate.id)) at = index;
+    });
+    this.document.nodes.splice(at + 1, 0, node);
+  }
+  placeFor(node) {
+    const parent = parentOf(node);
+    const siblings = this.childrenOf(parent).filter((other) => other.id !== node.id);
+    const upstream = [];
+    const downstream = [];
+    for (const { wire } of this.wires()) {
+      if (!wire) continue;
+      if (wire.to.node === node.id && wire.from.node !== node.id) {
+        const source = this.findNode(wire.from.node);
+        if (source && parentOf(source) === parent) upstream.push(positionOf(source));
+      }
+      if (wire.from.node === node.id && wire.to.node !== node.id) {
+        const target = this.findNode(wire.to.node);
+        if (target && parentOf(target) === parent) downstream.push(positionOf(target));
+      }
+    }
+    return placeNode({ siblings: siblings.map(positionOf), upstream, downstream, step: this.stepIn(parent, node.id) });
+  }
+  relayout(node) {
+    const before = positionOf(node);
+    const after = this.placeFor(node);
+    if (before.x === after.x && before.y === after.y) return void 0;
+    setPosition(node, after);
+    return this.summary(node);
+  }
+  /** The flow of one canvas: the median offset along its wires. */
+  stepIn(parent, exclude) {
+    const wires = [];
+    for (const { wire } of this.wires()) {
+      if (!wire || wire.from.node === exclude || wire.to.node === exclude) continue;
+      const source = this.findNode(wire.from.node);
+      const target = this.findNode(wire.to.node);
+      if (!source || !target || parentOf(source) !== parent || parentOf(target) !== parent) continue;
+      wires.push({ from: positionOf(source), to: positionOf(target) });
+    }
+    return flowStep(wires);
+  }
+  forgetInAnnotations(removed) {
+    const annotations = this.document.annotations;
+    if (!Array.isArray(annotations)) return;
+    this.document.annotations = annotations.filter((annotation) => !removed.has(String(annotation.parent ?? "")));
+    for (const annotation of this.document.annotations) {
+      if (Array.isArray(annotation.containedElements)) {
+        annotation.containedElements = annotation.containedElements.filter((id) => !removed.has(String(id)));
+      }
+    }
+    if (!this.document.annotations.length && annotations.length) delete this.document.annotations;
+  }
+  uniqueId(base) {
+    if (!this.findNode(base)) return base;
+    for (let n = 2; ; n += 1) if (!this.findNode(`${base}-${n}`)) return `${base}-${n}`;
+  }
+  summary(node) {
+    return { id: node.id, module: moduleOf(node), parent: parentOf(node), position: positionOf(node) };
+  }
+};
+function splitEndpoint(text) {
+  const at = text.lastIndexOf(".");
+  return at === -1 ? { node: text, port: "" } : { node: text.slice(0, at), port: text.slice(at + 1) };
+}
+function defaultIdFor(module) {
+  return slug(module.slice(module.lastIndexOf(".") + 1)) || "node";
+}
+function slug(text) {
+  return text.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[^A-Za-z0-9]+/g, "-").replace(/^-+|-+$/g, "").toLowerCase();
+}
+function assertValidId(id) {
+  if (!/^[A-Za-z_][A-Za-z0-9_-]*$/.test(id)) {
+    throw new GraphEditError(`"${id}" is not a usable node id: letters, digits, - and _, starting with a letter`);
+  }
+}
+function sourceFor(module) {
+  if (module.startsWith("cascade.")) return "stdlib";
+  if (module.startsWith("project.")) return "project";
+  return void 0;
+}
+var GENERIC_PORTS = /* @__PURE__ */ new Set(["value", "output", "out", "input", "in", "result", "data"]);
+function isBoundary(node) {
+  return moduleOf(node) === INPUT || moduleOf(node) === OUTPUT;
+}
+function portNumber(port) {
+  const match = /_(\d+)$/.exec(port);
+  return match ? Number(match[1]) : -1;
+}
+function along(point, step) {
+  return point.x * step.x + point.y * step.y;
+}
+
+// packages/runtime/src/edit/operations.ts
+var GRAPH_EDIT_OPERATIONS = [
+  "node.add",
+  "node.remove",
+  "connect",
+  "disconnect",
+  "set",
+  "subnet.create",
+  "subnet.move",
+  "subnet.dissolve"
+];
+function applyOperation(editor, operation) {
+  switch (operation.op) {
+    case "node.add":
+      return editor.addNode({
+        module: operation.module,
+        ...operation.id ? { id: operation.id } : {},
+        ...operation.in ? { parent: operation.in } : {},
+        ...operation.position ? { position: operation.position } : {},
+        ...operation.set ? { props: operation.set } : {},
+        ...operation.fromText ? { fromText: true } : {},
+        ...operation.comment ? { comment: operation.comment } : {}
+      });
+    case "node.remove":
+      return editor.removeNode(operation.id, { recursive: operation.recursive === true });
+    case "connect":
+      return editor.connect(operation.from, operation.to, { layout: operation.layout !== false });
+    case "disconnect":
+      return operation.from ? editor.disconnect(operation.from, operation.to) : editor.disconnect(operation.to);
+    case "set": {
+      const { op: _op, target, ...change } = operation;
+      return editor.setParameter(target, change);
+    }
+    case "subnet.create":
+      return editor.createSubnet({
+        nodes: operation.nodes,
+        ...operation.id ? { id: operation.id } : {},
+        ...operation.label ? { label: operation.label } : {}
+      });
+    case "subnet.move":
+      return editor.moveNodes(operation.nodes, operation.to === "root" ? null : operation.to);
+    case "subnet.dissolve":
+      return editor.dissolveSubnet(operation.id);
+    default: {
+      const unknown = operation.op;
+      throw new Error(`Unknown edit operation ${JSON.stringify(unknown)}; expected one of ${GRAPH_EDIT_OPERATIONS.join(", ")}`);
+    }
+  }
+}
+
+// packages/runtime/src/edit/read.ts
+function readGraph(document, options = {}) {
+  const scope = options.in ?? null;
+  const inScope = new Set(scope === null ? document.nodes.map((node) => node.id) : descendants(document, scope));
+  const nodes = document.nodes.filter((node) => inScope.has(node.id)).map((node) => {
+    const children = document.nodes.filter((child) => parentOf(child) === node.id);
+    const labelled = (prefix, indexProp, nameProp) => (port) => {
+      const boundary = children.find((child) => Number(child.props?.[indexProp]) === port.index && moduleOf(child) === `cascade.core.${prefix}`);
+      const label = boundary?.comment || boundary?.props?.[nameProp];
+      return label ? `${port.name} (${label})` : port.name;
+    };
+    const ports = moduleOf(node) === SUBNET ? subnetPorts(children) : null;
+    return {
+      id: node.id,
+      module: moduleOf(node),
+      parent: parentOf(node),
+      position: positionOf(node),
+      ...typeof node.comment === "string" && node.comment ? { comment: node.comment } : {},
+      ...node.props && Object.keys(node.props).length ? { props: node.props } : {},
+      ...node.inputs !== void 0 ? { inputs: node.inputs } : {},
+      ...ports ? {
+        ports: {
+          inputs: ports.inputs.map(labelled("Input", "inputIndex", "inputName")),
+          outputs: ports.outputs.map(labelled("Output", "outputIndex", "outputName"))
+        }
+      } : {}
+    };
+  });
+  const wires = (document.connections ?? []).map(readWire).filter((wire) => wire && inScope.has(wire.from.node) && inScope.has(wire.to.node)).map((wire) => wireLabel(wire));
+  const metadata = document.metadata;
+  return {
+    name: typeof metadata?.name === "string" ? metadata.name : null,
+    nodes,
+    wires,
+    top: nodes.filter((node) => node.parent === scope).map((node) => node.id)
+  };
+}
+function descendants(document, id) {
+  if (!document.nodes.some((node) => node.id === id)) throw new Error(`No node "${id}"`);
+  const result = [];
+  const queue = [id];
+  while (queue.length) {
+    const current = queue.shift();
+    for (const child of document.nodes) {
+      if (parentOf(child) === current) {
+        result.push(child.id);
+        queue.push(child.id);
+      }
+    }
+  }
+  return result;
+}
+
+export {
+  readWire,
+  wireLabel,
+  flowStep,
+  placeNode,
+  GraphEditError,
+  GraphEditor,
+  splitEndpoint,
+  defaultIdFor,
+  GRAPH_EDIT_OPERATIONS,
+  applyOperation,
+  readGraph
+};
+//# sourceMappingURL=chunk-BZ63XQ3I.js.map