@particle-academy/fancy-flow 0.65.2 → 0.66.0

package/dist/registry.cjs

@@ -2216,38 +2216,38 @@ function attrRemoveNS2(fullname) {
     this.removeAttributeNS(fullname.space, fullname.local);
   };
 }
-function attrConstant2(name, interpolate, value1) {
+function attrConstant2(name, interpolate2, value1) {
   var string00, string1 = value1 + "", interpolate0;
   return function() {
     var string0 = this.getAttribute(name);
-    return string0 === string1 ? null : string0 === string00 ? interpolate0 : interpolate0 = interpolate(string00 = string0, value1);
+    return string0 === string1 ? null : string0 === string00 ? interpolate0 : interpolate0 = interpolate2(string00 = string0, value1);
   };
 }
-function attrConstantNS2(fullname, interpolate, value1) {
+function attrConstantNS2(fullname, interpolate2, value1) {
   var string00, string1 = value1 + "", interpolate0;
   return function() {
     var string0 = this.getAttributeNS(fullname.space, fullname.local);
-    return string0 === string1 ? null : string0 === string00 ? interpolate0 : interpolate0 = interpolate(string00 = string0, value1);
+    return string0 === string1 ? null : string0 === string00 ? interpolate0 : interpolate0 = interpolate2(string00 = string0, value1);
   };
 }
-function attrFunction2(name, interpolate, value) {
+function attrFunction2(name, interpolate2, value) {
   var string00, string10, interpolate0;
   return function() {
     var string0, value1 = value(this), string1;
     if (value1 == null) return void this.removeAttribute(name);
     string0 = this.getAttribute(name);
     string1 = value1 + "";
-    return string0 === string1 ? null : string0 === string00 && string1 === string10 ? interpolate0 : (string10 = string1, interpolate0 = interpolate(string00 = string0, value1));
+    return string0 === string1 ? null : string0 === string00 && string1 === string10 ? interpolate0 : (string10 = string1, interpolate0 = interpolate2(string00 = string0, value1));
   };
 }
-function attrFunctionNS2(fullname, interpolate, value) {
+function attrFunctionNS2(fullname, interpolate2, value) {
   var string00, string10, interpolate0;
   return function() {
     var string0, value1 = value(this), string1;
     if (value1 == null) return void this.removeAttributeNS(fullname.space, fullname.local);
     string0 = this.getAttributeNS(fullname.space, fullname.local);
     string1 = value1 + "";
-    return string0 === string1 ? null : string0 === string00 && string1 === string10 ? interpolate0 : (string10 = string1, interpolate0 = interpolate(string00 = string0, value1));
+    return string0 === string1 ? null : string0 === string00 && string1 === string10 ? interpolate0 : (string10 = string1, interpolate0 = interpolate2(string00 = string0, value1));
   };
 }
 function attr_default2(name, value) {
@@ -2457,11 +2457,11 @@ function selection_default2() {
 }
 
 // node_modules/d3-transition/src/transition/style.js
-function styleNull(name, interpolate) {
+function styleNull(name, interpolate2) {
   var string00, string10, interpolate0;
   return function() {
     var string0 = styleValue(this, name), string1 = (this.style.removeProperty(name), styleValue(this, name));
-    return string0 === string1 ? null : string0 === string00 && string1 === string10 ? interpolate0 : interpolate0 = interpolate(string00 = string0, string10 = string1);
+    return string0 === string1 ? null : string0 === string00 && string1 === string10 ? interpolate0 : interpolate0 = interpolate2(string00 = string0, string10 = string1);
   };
 }
 function styleRemove2(name) {
@@ -2469,19 +2469,19 @@ function styleRemove2(name) {
     this.style.removeProperty(name);
   };
 }
-function styleConstant2(name, interpolate, value1) {
+function styleConstant2(name, interpolate2, value1) {
   var string00, string1 = value1 + "", interpolate0;
   return function() {
     var string0 = styleValue(this, name);
-    return string0 === string1 ? null : string0 === string00 ? interpolate0 : interpolate0 = interpolate(string00 = string0, value1);
+    return string0 === string1 ? null : string0 === string00 ? interpolate0 : interpolate0 = interpolate2(string00 = string0, value1);
   };
 }
-function styleFunction2(name, interpolate, value) {
+function styleFunction2(name, interpolate2, value) {
   var string00, string10, interpolate0;
   return function() {
     var string0 = styleValue(this, name), value1 = value(this), string1 = value1 + "";
     if (value1 == null) string1 = value1 = (this.style.removeProperty(name), styleValue(this, name));
-    return string0 === string1 ? null : string0 === string00 && string1 === string10 ? interpolate0 : (string10 = string1, interpolate0 = interpolate(string00 = string0, value1));
+    return string0 === string1 ? null : string0 === string00 && string1 === string10 ? interpolate0 : (string10 = string1, interpolate0 = interpolate2(string00 = string0, value1));
   };
 }
 function styleMaybeRemove(id2, name) {
@@ -2583,9 +2583,9 @@ function transition_default() {
 // node_modules/d3-transition/src/transition/end.js
 function end_default() {
   var on0, on1, that = this, id2 = that._id, size = that.size();
-  return new Promise(function(resolve, reject) {
+  return new Promise(function(resolve2, reject) {
     var cancel = { value: reject }, end = { value: function() {
-      if (--size === 0) resolve();
+      if (--size === 0) resolve2();
     } };
     that.each(function() {
       var schedule = set2(this, id2), on = schedule.on;
@@ -2597,7 +2597,7 @@ function end_default() {
       }
       schedule.on = on1;
     });
-    if (size === 0) resolve();
+    if (size === 0) resolve2();
   });
 }
 
@@ -2799,7 +2799,7 @@ function defaultConstrain(transform2, extent, translateExtent) {
   );
 }
 function zoom_default2() {
-  var filter2 = defaultFilter2, extent = defaultExtent, constrain = defaultConstrain, wheelDelta2 = defaultWheelDelta, touchable = defaultTouchable2, scaleExtent = [0, Infinity], translateExtent = [[-Infinity, -Infinity], [Infinity, Infinity]], duration = 250, interpolate = zoom_default, listeners3 = dispatch_default("start", "zoom", "end"), touchstarting, touchfirst, touchending, touchDelay = 500, wheelDelay = 150, clickDistance2 = 0, tapDistance = 10;
+  var filter2 = defaultFilter2, extent = defaultExtent, constrain = defaultConstrain, wheelDelta2 = defaultWheelDelta, touchable = defaultTouchable2, scaleExtent = [0, Infinity], translateExtent = [[-Infinity, -Infinity], [Infinity, Infinity]], duration = 250, interpolate2 = zoom_default, listeners3 = dispatch_default("start", "zoom", "end"), touchstarting, touchfirst, touchending, touchDelay = 500, wheelDelay = 150, clickDistance2 = 0, tapDistance = 10;
   function zoom(selection2) {
     selection2.property("__zoom", defaultTransform).on("wheel.zoom", wheeled, { passive: false }).on("mousedown.zoom", mousedowned).on("dblclick.zoom", dblclicked).filter(touchable).on("touchstart.zoom", touchstarted).on("touchmove.zoom", touchmoved).on("touchend.zoom touchcancel.zoom", touchended).style("-webkit-tap-highlight-color", "rgba(0,0,0,0)");
   }
@@ -2860,7 +2860,7 @@ function zoom_default2() {
     }).on("interrupt.zoom end.zoom", function() {
       gesture(this, arguments).event(event).end();
     }).tween("zoom", function() {
-      var that = this, args = arguments, g = gesture(that, args).event(event), e = extent.apply(that, args), p = point == null ? centroid(e) : typeof point === "function" ? point.apply(that, args) : point, w = Math.max(e[1][0] - e[0][0], e[1][1] - e[0][1]), a = that.__zoom, b = typeof transform2 === "function" ? transform2.apply(that, args) : transform2, i = interpolate(a.invert(p).concat(w / a.k), b.invert(p).concat(w / b.k));
+      var that = this, args = arguments, g = gesture(that, args).event(event), e = extent.apply(that, args), p = point == null ? centroid(e) : typeof point === "function" ? point.apply(that, args) : point, w = Math.max(e[1][0] - e[0][0], e[1][1] - e[0][1]), a = that.__zoom, b = typeof transform2 === "function" ? transform2.apply(that, args) : transform2, i = interpolate2(a.invert(p).concat(w / a.k), b.invert(p).concat(w / b.k));
       return function(t) {
         if (t === 1) t = b;
         else {
@@ -3065,7 +3065,7 @@ function zoom_default2() {
     return arguments.length ? (duration = +_, zoom) : duration;
   };
   zoom.interpolate = function(_) {
-    return arguments.length ? (interpolate = _, zoom) : interpolate;
+    return arguments.length ? (interpolate2 = _, zoom) : interpolate2;
   };
   zoom.on = function() {
     var value = listeners3.on.apply(listeners3, arguments);
@@ -3558,13 +3558,13 @@ function areSetsEqual(a, b) {
   return true;
 }
 function withResolvers() {
-  let resolve;
+  let resolve2;
   let reject;
   const promise = new Promise((res, rej) => {
-    resolve = res;
+    resolve2 = res;
     reject = rej;
   });
-  return { promise, resolve, reject };
+  return { promise, resolve: resolve2, reject };
 }
 function mergeAriaLabelConfig(partial) {
   return { ...defaultAriaLabelConfig, ...partial || {} };
@@ -5214,8 +5214,8 @@ function XYPanZoom({ domNode, minZoom, maxZoom, translateExtent, viewport, onPan
   d3ZoomInstance.wheelDelta(wheelDelta);
   async function setTransform(transform2, options) {
     if (d3Selection) {
-      return new Promise((resolve) => {
-        d3ZoomInstance?.interpolate(options?.interpolate === "linear" ? value_default : zoom_default).transform(getD3Transition(d3Selection, options?.duration, options?.ease, () => resolve(true)), transform2);
+      return new Promise((resolve2) => {
+        d3ZoomInstance?.interpolate(options?.interpolate === "linear" ? value_default : zoom_default).transform(getD3Transition(d3Selection, options?.duration, options?.ease, () => resolve2(true)), transform2);
       });
     }
     return false;
@@ -5317,16 +5317,16 @@ function XYPanZoom({ domNode, minZoom, maxZoom, translateExtent, viewport, onPan
   }
   async function scaleTo(zoom, options) {
     if (d3Selection) {
-      return new Promise((resolve) => {
-        d3ZoomInstance?.interpolate(options?.interpolate === "linear" ? value_default : zoom_default).scaleTo(getD3Transition(d3Selection, options?.duration, options?.ease, () => resolve(true)), zoom);
+      return new Promise((resolve2) => {
+        d3ZoomInstance?.interpolate(options?.interpolate === "linear" ? value_default : zoom_default).scaleTo(getD3Transition(d3Selection, options?.duration, options?.ease, () => resolve2(true)), zoom);
       });
     }
     return false;
   }
   async function scaleBy(factor, options) {
     if (d3Selection) {
-      return new Promise((resolve) => {
-        d3ZoomInstance?.interpolate(options?.interpolate === "linear" ? value_default : zoom_default).scaleBy(getD3Transition(d3Selection, options?.duration, options?.ease, () => resolve(true)), factor);
+      return new Promise((resolve2) => {
+        d3ZoomInstance?.interpolate(options?.interpolate === "linear" ? value_default : zoom_default).scaleBy(getD3Transition(d3Selection, options?.duration, options?.ease, () => resolve2(true)), factor);
       });
     }
     return false;
@@ -9170,11 +9170,11 @@ function NoteNodeInner(props) {
   const config = data.config ?? {};
   const api = useFlowEditorOptional();
   const hasConfigText = typeof config.text === "string" && config.text.length > 0;
-  const text = hasConfigText ? String(config.text) : typeof data.body === "string" ? data.body : typeof data.text === "string" ? data.text : "";
+  const text3 = hasConfigText ? String(config.text) : typeof data.body === "string" ? data.body : typeof data.text === "string" ? data.text : "";
   const title = typeof config.title === "string" && config.title || (!hasConfigText && typeof data.body === "string" && typeof data.label === "string" ? data.label : "");
   const skin = NOTE_COLORS[coerceColor(config.color)];
   const [editing, setEditing] = ReactExports.useState(false);
-  const [draft, setDraft] = ReactExports.useState(text);
+  const [draft, setDraft] = ReactExports.useState(text3);
   const areaRef = ReactExports.useRef(null);
   ReactExports.useEffect(() => {
     if (editing && areaRef.current) {
@@ -9185,7 +9185,7 @@ function NoteNodeInner(props) {
   }, [editing]);
   const commit = () => {
     setEditing(false);
-    if (!api || draft === text) return;
+    if (!api || draft === text3) return;
     const current = api.nodes.find((n) => n.id === props.id);
     if (!current) return;
     api.updateNode({
@@ -9199,7 +9199,7 @@ function NoteNodeInner(props) {
       className: ["ff-note", props.selected ? "ff-note--selected" : ""].filter(Boolean).join(" "),
       style: { background: skin.bg, borderColor: skin.border },
       onDoubleClick: api ? () => {
-        setDraft(text);
+        setDraft(text3);
         setEditing(true);
       } : void 0,
       children: [
@@ -9218,7 +9218,7 @@ function NoteNodeInner(props) {
               if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) commit();
             }
           }
-        ) : /* @__PURE__ */ jsxRuntime.jsx("div", { className: "ff-note__body", children: text || /* @__PURE__ */ jsxRuntime.jsx("span", { className: "ff-note__placeholder", children: api ? "Double-click to write a note\u2026" : "Note" }) })
+        ) : /* @__PURE__ */ jsxRuntime.jsx("div", { className: "ff-note__body", children: text3 || /* @__PURE__ */ jsxRuntime.jsx("span", { className: "ff-note__placeholder", children: api ? "Double-click to write a note\u2026" : "Note" }) })
       ]
     }
   );
@@ -9236,6 +9236,16 @@ function registerLlmClient(client) {
 function getLlmClient() {
   return llmClient;
 }
+var terminalHost = null;
+function registerTerminalHost(host) {
+  terminalHost = host;
+  return () => {
+    if (terminalHost === host) terminalHost = null;
+  };
+}
+function getTerminalHost() {
+  return terminalHost;
+}
 function isResolutionFailure(value) {
   return typeof value === "object" && value !== null && "reason" in value && value.reason !== void 0;
 }
@@ -9259,7 +9269,14 @@ function capabilityStatus() {
   return {
     llm: llmClient !== null,
     workflow_resolver: workflowResolver !== null,
-    document: documentReady
+    document: documentReady,
+    // Listed here for the reason this function exists at all. A graph with a
+    // terminal lane and no host registered fails PART WAY THROUGH — after the
+    // nodes before it have already run and possibly written somewhere — and the
+    // whole point of asking up front is to learn that before starting. Leaving
+    // it out would have made the one check designed to catch this report
+    // all-clear for exactly the case it was built for.
+    terminal: terminalHost !== null
   };
 }
 
@@ -9421,6 +9438,249 @@ var RunIdentity = class _RunIdentity {
   }
 };
 
+// src/runtime/terminal-transcript.ts
+var ESC = String.fromCharCode(27);
+var CSI = String.fromCharCode(155);
+var BEL = String.fromCharCode(7);
+var ANSI = new RegExp(
+  `[${ESC}${CSI}](?:\\[[0-?]*[ -/]*[@-~]|\\][^${BEL}${ESC}]*(?:${BEL}|${ESC}\\\\)|[@-Z\\\\-_])`,
+  "g"
+);
+var MAX_PENDING_ESCAPE = 1024;
+var MAX_BUFFER = 1e6;
+var TerminalTranscript = class {
+  constructor() {
+    /** Stripped, complete text not yet consumed by a wait. */
+    this.text = "";
+    /** Raw bytes held back because they may be the start of an escape sequence. */
+    this.tail = "";
+    this.waiters = /* @__PURE__ */ new Set();
+  }
+  /** Feed raw terminal output in. Safe to call with any chunking. */
+  append(chunk) {
+    this.tail += chunk;
+    const safe = this.safeLength();
+    if (safe > 0) {
+      this.text += this.tail.slice(0, safe).replace(ANSI, "");
+      this.tail = this.tail.slice(safe);
+    }
+    if (this.text.length > MAX_BUFFER) {
+      this.text = this.text.slice(this.text.length - MAX_BUFFER);
+    }
+    for (const wake2 of [...this.waiters]) wake2();
+  }
+  /**
+   * How much of `tail` can be stripped now.
+   *
+   * Everything, unless the final `ESC` has not yet been terminated — in which
+   * case processing stops there and resumes when the rest arrives.
+   */
+  safeLength() {
+    const lastEsc = Math.max(this.tail.lastIndexOf(ESC), this.tail.lastIndexOf(CSI));
+    if (lastEsc === -1) return this.tail.length;
+    ANSI.lastIndex = lastEsc;
+    const match = ANSI.exec(this.tail);
+    ANSI.lastIndex = 0;
+    if (match && match.index === lastEsc) return this.tail.length;
+    if (this.tail.length - lastEsc > MAX_PENDING_ESCAPE) return this.tail.length;
+    return lastEsc;
+  }
+  /** Unconsumed output, escape sequences removed. */
+  peek() {
+    return this.text;
+  }
+  /** Drop everything currently buffered — used before typing a new command. */
+  clear() {
+    this.text = "";
+    this.tail = "";
+  }
+  /**
+   * Wait until `pattern` matches the unconsumed text.
+   *
+   * Checks what has ALREADY arrived before subscribing, because the common case
+   * is that the process answered while the previous node was still finishing.
+   *
+   * `exited` is raced deliberately. Without it, a shell that dies reports as
+   * "timed out waiting for X" — sending whoever reads it to lengthen a timeout
+   * for a process that is not running. Naming the exit is the difference
+   * between a diagnosis and a wrong lead.
+   */
+  waitFor(pattern, options) {
+    return new Promise((resolve2) => {
+      let settled = false;
+      let timer2;
+      const finish = (result) => {
+        if (settled) return;
+        settled = true;
+        this.waiters.delete(check);
+        if (timer2) clearTimeout(timer2);
+        resolve2(result);
+      };
+      const check = () => {
+        pattern.lastIndex = 0;
+        const match = pattern.exec(this.text);
+        if (!match) return;
+        const through = match.index + (match[0].length || 1);
+        const text3 = this.text.slice(0, through);
+        this.text = this.text.slice(through);
+        finish({ status: "matched", text: text3, match });
+      };
+      this.waiters.add(check);
+      check();
+      if (settled) return;
+      if (options.timeoutMs > 0) {
+        timer2 = setTimeout(() => {
+          const text3 = this.text;
+          this.text = "";
+          finish({ status: "timeout", text: text3 });
+        }, options.timeoutMs);
+        timer2.unref?.();
+      }
+      options.exited?.then(
+        (exit) => {
+          if (settled) return;
+          const text3 = this.text;
+          this.text = "";
+          finish({ status: "exited", text: text3, exitCode: exit.exitCode, signal: exit.signal });
+        },
+        () => {
+        }
+      );
+    });
+  }
+};
+
+// src/runtime/terminal-sessions.ts
+var TerminalSessions = class {
+  constructor(graph) {
+    this.graph = graph;
+    this.open = /* @__PURE__ */ new Map();
+    this.laneOf = /* @__PURE__ */ new Map();
+    this.transcripts = /* @__PURE__ */ new Map();
+    this.listening = /* @__PURE__ */ new Map();
+  }
+  /**
+   * The terminal lane a node belongs to, or null.
+   *
+   * Walks up `parentId` rather than checking only the immediate parent, and
+   * caches per node id — a graph is walked once per run, and the answer cannot
+   * change while it runs.
+   */
+  laneFor(nodeId, isTerminalLane) {
+    const cached = this.laneOf.get(nodeId);
+    if (cached !== void 0) return cached;
+    const byId = new Map(this.graph.nodes.map((n) => [n.id, n]));
+    const seen = /* @__PURE__ */ new Set();
+    let current = byId.get(nodeId);
+    let answer = null;
+    while (current) {
+      if (seen.has(current.id)) break;
+      seen.add(current.id);
+      if (current.id !== nodeId && isTerminalLane(current)) {
+        answer = current.id;
+        break;
+      }
+      const parentId = current.parentId;
+      current = parentId ? byId.get(parentId) : void 0;
+    }
+    this.laneOf.set(nodeId, answer);
+    return answer;
+  }
+  /**
+   * The session for a lane, opening it on first use.
+   *
+   * The PROMISE is cached, not the resolved session. Two nodes cannot run
+   * concurrently in the current engine, but a caller that awaits a
+   * half-finished open would otherwise start a second process — and two shells
+   * where a graph says one is the failure this class exists to prevent, arriving
+   * only under concurrency and therefore only sometimes.
+   */
+  session(laneId, spec) {
+    const existing = this.open.get(laneId);
+    if (existing) return existing;
+    const host = getTerminalHost();
+    if (!host) {
+      const failed = Promise.reject(
+        new Error(
+          "No terminal host is registered. A terminal lane needs one \u2014 call registerTerminalHost() from the desktop app, or install @particle-academy/fancy-flow/terminal/fancy-term-host."
+        )
+      );
+      this.open.set(laneId, failed);
+      failed.catch(() => {
+      });
+      return failed;
+    }
+    const opening = Promise.resolve(host.open(spec)).then((session) => {
+      const transcript = this.transcriptFor(laneId);
+      this.listening.set(laneId, session.onData((chunk) => transcript.append(chunk)));
+      return session;
+    });
+    this.open.set(laneId, opening);
+    opening.catch(() => {
+    });
+    return opening;
+  }
+  /**
+   * The accumulated output for a lane.
+   *
+   * Created on demand and kept for the run, so it exists before the session
+   * resolves and survives every node that reads it. Consuming is the reader's
+   * job — see `TerminalTranscript.waitFor`.
+   */
+  transcriptFor(laneId) {
+    const existing = this.transcripts.get(laneId);
+    if (existing) return existing;
+    const created = new TerminalTranscript();
+    this.transcripts.set(laneId, created);
+    return created;
+  }
+  /** True once a lane has a session — used to avoid opening one during teardown. */
+  isOpen(laneId) {
+    return this.open.has(laneId);
+  }
+  /**
+   * Close every session this run opened.
+   *
+   * Every close is attempted even if one throws: a host that fails to close one
+   * PTY must not strand the others, which would leave processes alive after the
+   * run reported that it had finished. Errors are returned rather than thrown,
+   * because teardown runs in a `finally` and throwing there would replace the
+   * run's real error with a cleanup error.
+   */
+  async closeAll() {
+    const errors = [];
+    for (const [laneId, pending] of this.open) {
+      try {
+        this.listening.get(laneId)?.();
+        this.listening.delete(laneId);
+        const session = await pending;
+        await session.close();
+      } catch (e) {
+        errors.push(e instanceof Error ? e : new Error(`${laneId}: ${String(e)}`));
+      }
+    }
+    this.open.clear();
+    this.listening.clear();
+    this.transcripts.clear();
+    return errors;
+  }
+};
+function specForLane(lane) {
+  const config = lane.data?.config ?? {};
+  const text3 = (key) => {
+    const value = config[key];
+    return typeof value === "string" && value !== "" ? value : void 0;
+  };
+  const env = config.env;
+  return {
+    command: text3("command"),
+    cwd: text3("cwd"),
+    env: env && typeof env === "object" && !Array.isArray(env) ? Object.fromEntries(
+      Object.entries(env).map(([k, v]) => [k, String(v)])
+    ) : void 0
+  };
+}
+
 // src/runtime/workflow-props.ts
 function typeOf(value) {
   if (value === null) return "null";
@@ -9499,6 +9759,25 @@ async function runFlow(graph, executors, onEvent = () => {
   const props = propsCheck.props;
   const declaresProps = (graph.inputs?.length ?? 0) > 0;
   const incomingByNode = indexIncoming(graph.edges);
+  const sessions = new TerminalSessions(graph);
+  const isTerminalLane = (candidate) => getNodeKind(candidate.type ?? "")?.name === "@particle-academy/terminal_lane";
+  const terminalAccessorFor = (node) => {
+    const laneId = sessions.laneFor(node.id, isTerminalLane);
+    if (laneId === null) return void 0;
+    const lane = graph.nodes.find((n) => n.id === laneId);
+    if (!lane) return void 0;
+    return {
+      session: () => sessions.session(laneId, specForLane(lane)),
+      // Awaits the session first on purpose. A transcript handed out before
+      // anything is feeding it would look perfectly healthy and match nothing,
+      // and "waited and nothing came" is the hardest failure here to tell apart
+      // from a process that is simply slow.
+      transcript: async () => {
+        await sessions.session(laneId, specForLane(lane));
+        return sessions.transcriptFor(laneId);
+      }
+    };
+  };
   const timer2 = timeoutMs ? setTimeout(() => errors.push(`Run timed out after ${timeoutMs}ms`), timeoutMs) : null;
   onEvent({ type: "run-start" });
   try {
@@ -9564,7 +9843,8 @@ async function runFlow(graph, executors, onEvent = () => {
             emit: onEvent,
             executors,
             depth,
-            run
+            run,
+            terminal: terminalAccessorFor(node)
           })
         );
         outputs[node.id] = result;
@@ -9586,6 +9866,9 @@ async function runFlow(graph, executors, onEvent = () => {
     }
   } finally {
     if (timer2) clearTimeout(timer2);
+    for (const error of await sessions.closeAll()) {
+      onEvent({ type: "log", level: "warn", message: `terminal close failed: ${error.message}` });
+    }
   }
   const ok = errors.length === 0;
   onEvent({ type: "run-end", ok });
@@ -9664,7 +9947,7 @@ function pickExecutor(executors, node) {
   for (const id2 of executorLookupIds(node)) {
     if (executors[id2]) return executors[id2];
   }
-  return void 0;
+  return getNodeKind(node.type ?? "")?.executor;
 }
 function activatedPorts(node, result) {
   if (result && typeof result === "object") {
@@ -9774,6 +10057,366 @@ var subflowExecutor = async (ctx) => {
   return { __port: "out", value: result.outputs };
 };
 
+// src/expressions/expr.ts
+function wholeExpression(trimmed) {
+  if (trimmed.length < 4) return null;
+  if (!trimmed.startsWith("{{") || !trimmed.endsWith("}}")) return null;
+  return trimmed.slice(2, -2);
+}
+function interpolate(template, resolve2) {
+  let out = "";
+  let i = 0;
+  for (; ; ) {
+    const open = template.indexOf("{{", i);
+    if (open === -1) return out + template.slice(i);
+    const close = template.indexOf("}}", open + 2);
+    if (close === -1) return out + template.slice(i);
+    out += template.slice(i, open) + resolve2(template.slice(open + 2, close));
+    i = close + 2;
+  }
+}
+var FALSY_STRINGS = /* @__PURE__ */ new Set(["", "0", "false", "no", "off", "null"]);
+var UnresolvedPathError = class extends Error {
+  constructor(path) {
+    super(
+      `Expression path "${path}" did not resolve. Under the "throw" policy an unresolvable path is an error rather than an empty string.`
+    );
+    this.path = path;
+    this.name = "UnresolvedPathError";
+  }
+};
+function tryResolvePath(path, context) {
+  const unresolved = { resolved: false, value: null };
+  const trimmed = path.trim();
+  if (trimmed === "") return unresolved;
+  const segments = trimmed.split(".");
+  let cursor;
+  const head = segments[0];
+  if (head === "$json" || head === "$input") {
+    cursor = context !== null && typeof context === "object" && "in" in context ? context.in : context;
+    segments.shift();
+  } else {
+    cursor = context;
+  }
+  for (const segment of segments) {
+    if (cursor === null || cursor === void 0) return unresolved;
+    if (typeof cursor !== "object") return unresolved;
+    const next = cursor[segment];
+    if (next === void 0) return unresolved;
+    cursor = next;
+  }
+  return { resolved: true, value: cursor === void 0 ? null : cursor };
+}
+function evaluateExpression(template, context, options = {}) {
+  if (typeof template !== "string") return template;
+  const policy = options.onUnresolved ?? "empty";
+  const whole = wholeExpression(template.trim());
+  if (whole !== null) {
+    const r = tryResolvePath(whole, context);
+    if (r.resolved) return r.value;
+    if (policy === "throw") throw new UnresolvedPathError(whole);
+    return policy === "keep" ? template : null;
+  }
+  return interpolate(template, (path) => {
+    const r = tryResolvePath(path, context);
+    if (r.resolved) return stringify(r.value);
+    if (policy === "throw") throw new UnresolvedPathError(path);
+    return policy === "keep" ? `{{${path}}}` : "";
+  });
+}
+function truthy(value) {
+  if (typeof value === "boolean") return value;
+  if (value === null || value === void 0) return false;
+  if (typeof value === "string") return !FALSY_STRINGS.has(value.trim().toLowerCase());
+  if (Array.isArray(value)) return value.length > 0;
+  if (typeof value === "number") return value !== 0;
+  return Boolean(value);
+}
+function text(value) {
+  return stringify(value);
+}
+function stringify(value) {
+  if (typeof value === "string") return value;
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (value === null || value === void 0) return "";
+  if (typeof value === "number" || typeof value === "bigint") return String(value);
+  try {
+    return JSON.stringify(value) ?? "";
+  } catch {
+    return "";
+  }
+}
+
+// src/registry/logic.ts
+function configOf(node) {
+  return node?.data?.config ?? {};
+}
+function contextOf(inputs) {
+  return inputs;
+}
+function resolve(value, inputs) {
+  if (typeof value !== "string") return value;
+  return evaluateExpression(value, contextOf(inputs));
+}
+function conditionHolds(row, inputs) {
+  const left = resolve(row.left, inputs);
+  const right = resolve(row.right, inputs);
+  const operator = typeof row.operator === "string" ? row.operator : "eq";
+  const asText = (v) => text(v);
+  const asNumber = (v) => {
+    const n = typeof v === "number" ? v : Number(asText(v));
+    return Number.isFinite(n) ? n : NaN;
+  };
+  const numeric = (fn) => {
+    const a = asNumber(left);
+    const b = asNumber(right);
+    return Number.isFinite(a) && Number.isFinite(b) ? fn(a, b) : false;
+  };
+  const isEmpty = (v) => v === null || v === void 0 || v === "" || Array.isArray(v) && v.length === 0 || typeof v === "object" && !Array.isArray(v) && Object.keys(v).length === 0;
+  switch (operator) {
+    // Compared as TEXT, deliberately. `right` is a text field in the schema, so
+    // `status == "2"` must match the number 2 an upstream node produced —
+    // strict equality there would fail on a difference the author cannot see.
+    case "eq":
+      return asText(left) === asText(right);
+    case "neq":
+      return asText(left) !== asText(right);
+    case "contains":
+      return asText(left).includes(asText(right));
+    case "not_contains":
+      return !asText(left).includes(asText(right));
+    case "gt":
+      return numeric((a, b) => a > b);
+    case "gte":
+      return numeric((a, b) => a >= b);
+    case "lt":
+      return numeric((a, b) => a < b);
+    case "lte":
+      return numeric((a, b) => a <= b);
+    case "truthy":
+      return truthy(left);
+    case "falsy":
+      return !truthy(left);
+    case "empty":
+      return isEmpty(left);
+    case "not_empty":
+      return !isEmpty(left);
+    default:
+      return false;
+  }
+}
+var branchExecutor = (ctx) => {
+  const config = configOf(ctx.node);
+  const inputs = ctx.inputs;
+  let taken;
+  const raw = config.condition;
+  if (typeof raw === "string" && raw.trim() !== "") {
+    taken = truthy(resolve(raw, inputs));
+  } else {
+    const rows = Array.isArray(config.conditions) ? config.conditions : [];
+    if (rows.length === 0) {
+      taken = false;
+    } else {
+      const results = rows.map((row) => conditionHolds(row, inputs));
+      taken = config.match === "any" ? results.some(Boolean) : results.every(Boolean);
+    }
+  }
+  return { __port: taken ? "true" : "false", value: ctx.inputs.in ?? ctx.inputs };
+};
+var transformExecutor = (ctx) => {
+  const config = configOf(ctx.node);
+  const inputs = ctx.inputs;
+  const passthrough = ctx.inputs.in ?? ctx.inputs;
+  if (config.mode === "expression") {
+    const expression = config.expression;
+    if (typeof expression !== "string" || expression.trim() === "") return passthrough;
+    return resolve(expression, inputs);
+  }
+  const rows = Array.isArray(config.fields) ? config.fields : [];
+  if (rows.length === 0) return passthrough;
+  const out = {};
+  let wrote = false;
+  for (const row of rows) {
+    const key = typeof row.key === "string" ? row.key.trim() : "";
+    if (key === "") continue;
+    out[key] = resolve(row.value, inputs);
+    wrote = true;
+  }
+  return wrote ? out : passthrough;
+};
+var mergeExecutor = (ctx) => {
+  const entries = Object.entries(ctx.inputs);
+  if (configOf(ctx.node).mode === "concat") {
+    const out = [];
+    for (const [, value] of entries) {
+      if (value === null || value === void 0) continue;
+      if (Array.isArray(value)) out.push(...value);
+      else out.push(value);
+    }
+    return out;
+  }
+  const merged = {};
+  for (const [port, value] of entries) {
+    if (value === null || value === void 0) continue;
+    if (typeof value === "object" && !Array.isArray(value)) Object.assign(merged, value);
+    else merged[port] = value;
+  }
+  return merged;
+};
+var forEachExecutor = (ctx) => {
+  const source = resolve(configOf(ctx.node).source, ctx.inputs);
+  let items;
+  if (Array.isArray(source)) items = source;
+  else if (source === null || source === void 0) items = [];
+  else if (typeof source === "object") items = Object.values(source);
+  else items = [source];
+  return { items, count: items.length };
+};
+
+// src/registry/terminal-nodes.ts
+var DEFAULT_TIMEOUT_MS = 12e4;
+var ENTER = "\r";
+function configOf2(node) {
+  return node?.data?.config ?? {};
+}
+function text2(config, key) {
+  const value = config[key];
+  return typeof value === "string" ? value : "";
+}
+function millis(config, key, fallback) {
+  const value = Number(config[key]);
+  return Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+function exitMarker(nonce) {
+  const token = `__fancy_flow_exit_${nonce}__`;
+  return {
+    token,
+    // The expanded status is required to be digits. The shell ECHOES the typed
+    // command back first, and that echo contains the marker with `$?`
+    // unexpanded — so requiring digits is what stops the node matching its own
+    // command line and reporting success before anything has run.
+    pattern: new RegExp(`${token}:(\\d+)`)
+  };
+}
+var counter = 0;
+function newNonce() {
+  counter += 1;
+  return `${Date.now().toString(36)}${counter.toString(36)}${Math.random().toString(36).slice(2, 8)}`;
+}
+function withoutMarker(output, token) {
+  return output.split("\n").filter((line) => !line.includes(token)).join("\n").trim();
+}
+function fail(ctx, message) {
+  ctx.abort(message);
+  throw new Error(message);
+}
+function requireTerminal(ctx) {
+  if (!ctx.terminal) {
+    fail(
+      ctx,
+      `"${String(ctx.node.data?.label ?? ctx.node.id)}" is a terminal node but is not inside a terminal lane. Drag it into one \u2014 a terminal node outside a lane has no session to talk to, and opening a private shell for it would defeat the point of the lane.`
+    );
+  }
+  return ctx.terminal;
+}
+function compilePattern(ctx, raw, config) {
+  const flags = typeof config.flags === "string" ? config.flags.replace(/[gy]/g, "") : "";
+  try {
+    return config.mode === "regex" ? new RegExp(raw, flags) : new RegExp(raw.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), flags);
+  } catch (e) {
+    return fail(ctx, `terminal_await has an invalid regex: ${e instanceof Error ? e.message : String(e)}`);
+  }
+}
+var terminalRunExecutor = async (ctx) => {
+  const config = configOf2(ctx.node);
+  const command = text2(config, "command").trim();
+  if (!command) fail(ctx, "terminal_run has no command configured");
+  const terminal = requireTerminal(ctx);
+  const session = await terminal.session();
+  const transcript = await terminal.transcript();
+  const { token, pattern } = exitMarker(newNonce());
+  const timeoutMs = millis(config, "timeoutMs", DEFAULT_TIMEOUT_MS);
+  transcript.clear();
+  await session.write(`${command}; printf '${token}:%s\\n' "$?"${ENTER}`);
+  const result = await transcript.waitFor(pattern, { timeoutMs, exited: session.exited });
+  if (result.status === "exited") {
+    fail(
+      ctx,
+      `The terminal exited (code ${result.exitCode}${result.signal ? `, signal ${result.signal}` : ""}) while running "${command}". The lane's session is gone, so every later node in this lane would fail too.`
+    );
+  }
+  if (result.status === "timeout") {
+    fail(
+      ctx,
+      `"${command}" did not finish within ${timeoutMs}ms. Raise the node's timeout if it is genuinely slow \u2014 but a command that waits for input never finishes at all, and needs terminal_send + terminal_await.`
+    );
+  }
+  const exitCode = Number(result.match[1]);
+  const output = withoutMarker(result.text, token);
+  const failOnNonZero = config.failOnNonZero !== false;
+  if (failOnNonZero && exitCode !== 0) {
+    ctx.abort(`"${command}" exited ${exitCode}.
+${output}`);
+  }
+  return { output, exitCode, command };
+};
+var terminalSendExecutor = async (ctx) => {
+  const config = configOf2(ctx.node);
+  const terminal = requireTerminal(ctx);
+  const session = await terminal.session();
+  const body = text2(config, "text");
+  const submit = config.submit !== false;
+  if (config.clearFirst === true) {
+    (await terminal.transcript()).clear();
+  }
+  await session.write(submit ? `${body}${ENTER}` : body);
+  return { sent: body, submitted: submit };
+};
+var terminalAwaitExecutor = async (ctx) => {
+  const config = configOf2(ctx.node);
+  const terminal = requireTerminal(ctx);
+  const session = await terminal.session();
+  const transcript = await terminal.transcript();
+  const raw = text2(config, "pattern").trim();
+  if (!raw) fail(ctx, "terminal_await has no pattern configured \u2014 there is nothing for it to wait for");
+  const pattern = compilePattern(ctx, raw, config);
+  const timeoutMs = millis(config, "timeoutMs", DEFAULT_TIMEOUT_MS);
+  const result = await transcript.waitFor(pattern, {
+    timeoutMs,
+    exited: session.exited
+  });
+  if (result.status === "exited") {
+    fail(
+      ctx,
+      `The terminal exited (code ${result.exitCode}${result.signal ? `, signal ${result.signal}` : ""}) while waiting for ${JSON.stringify(raw)}. It never appeared, and the lane's session is gone.`
+    );
+  }
+  if (result.status === "timeout") {
+    if (config.onTimeout === "continue") {
+      ctx.emit({
+        type: "log",
+        nodeId: ctx.node.id,
+        level: "warn",
+        message: `terminal_await: ${JSON.stringify(raw)} did not appear within ${timeoutMs}ms; continuing as configured.`
+      });
+      return { matched: false, output: result.text, groups: [] };
+    }
+    fail(
+      ctx,
+      `${JSON.stringify(raw)} did not appear within ${timeoutMs}ms. Last output:
+${result.text.slice(-2e3)}`
+    );
+  }
+  return {
+    matched: true,
+    output: result.text,
+    matchedText: result.match[0],
+    // Capture groups are the reason to use regex mode at all — a prompt that
+    // reports a session id or a file path is only useful if the value comes out.
+    groups: result.match.slice(1)
+  };
+};
+
 // src/registry/builtin.ts
 var HUMAN_FIELD_OUTPUT_TYPE = {
   text: "string",
@@ -10063,6 +10706,9 @@ var KINDS = [
     // returns its input on the chosen port
     emits: "input",
     aliases: ["branch", "@fancy/branch"],
+    // Pure logic: no I/O to choose, so a default is safe. A host
+    // executor still wins -- pickExecutor consults the registry first.
+    executor: branchExecutor,
     category: "logic",
     label: "Branch",
     description: "Multi-way branch on a condition or value.",
@@ -10160,6 +10806,9 @@ var KINDS = [
       { path: "count", type: "number" }
     ],
     aliases: ["for_each", "@fancy/for_each"],
+    // Pure logic: no I/O to choose, so a default is safe. A host
+    // executor still wins -- pickExecutor consults the registry first.
+    executor: forEachExecutor,
     category: "logic",
     label: "For Each",
     description: "Iterate over a list, emitting each item on `item`.",
@@ -10180,6 +10829,9 @@ var KINDS = [
     // reference.
     emits: (config) => (config?.mode ?? "merge") === "concat" ? null : "inputs-merged",
     aliases: ["merge", "@fancy/merge"],
+    // Pure logic: no I/O to choose, so a default is safe. A host
+    // executor still wins -- pickExecutor consults the registry first.
+    executor: mergeExecutor,
     category: "logic",
     label: "Merge",
     description: "Combine multiple inputs into one object or array.",
@@ -10225,6 +10877,9 @@ var KINDS = [
     // else the shape that expression names. So the RELATION is config-dependent.
     emits: (config) => (config?.expression ?? "") === "" ? "input" : "expression:expression",
     aliases: ["transform", "@fancy/transform"],
+    // Pure logic: no I/O to choose, so a default is safe. A host
+    // executor still wins -- pickExecutor consults the registry first.
+    executor: transformExecutor,
     category: "logic",
     label: "Transform",
     description: "Reshape data with an expression.",
@@ -10683,6 +11338,179 @@ var KINDS = [
     resizable: { minWidth: 160, minHeight: 72 },
     component: LaneNode
   },
+  {
+    // Terminal lane — a lane that OWNS a terminal for the length of the run.
+    //
+    // Visually a swimlane, and `layout` for the same reason the plain lane is:
+    // a lane is not a step, so it never executes and never appears in topo
+    // order. What is new is that it DECLARES a resource. The runtime opens its
+    // terminal lazily, when the first terminal node inside it runs, and closes
+    // it in the run's `finally` — so a graph that never reaches a terminal node
+    // never spawns a process, and one that does gets exactly one session no
+    // matter how many nodes use it.
+    //
+    // Membership is `parentId`, which already persists into the WorkflowSchema.
+    // That is what lets a headless runtime resolve the same grouping the canvas
+    // shows, without a second association to keep in sync.
+    name: "@particle-academy/terminal_lane",
+    aliases: ["terminal_lane", "@fancy/terminal_lane"],
+    category: "layout",
+    label: "Terminal lane",
+    description: "A lane that owns one terminal. Opens at the first terminal node, closes when the run ends.",
+    icon: "\u25A3",
+    inputs: [],
+    outputs: [],
+    configSchema: [
+      { type: "text", key: "title", label: "Title", default: "Terminal" },
+      {
+        type: "text",
+        key: "command",
+        label: "Command",
+        placeholder: "Leave empty for the default shell"
+      },
+      { type: "text", key: "cwd", label: "Working directory", placeholder: "Host default" },
+      { type: "keyvalue", key: "env", label: "Environment" },
+      {
+        type: "select",
+        key: "orientation",
+        label: "Orientation",
+        default: "horizontal",
+        options: [
+          { value: "horizontal", label: "Row" },
+          { value: "vertical", label: "Column" }
+        ]
+      }
+    ],
+    defaultConfig: { title: "Terminal", orientation: "horizontal" },
+    resizable: { minWidth: 220, minHeight: 120 },
+    component: LaneNode
+  },
+  {
+    // Terminal nodes. All three live inside a terminal lane and talk to the
+    // session that lane owns; outside one they abort by name rather than
+    // opening a shell of their own.
+    name: "@particle-academy/terminal_run",
+    aliases: ["terminal_run", "@fancy/terminal_run"],
+    category: "io",
+    label: "Run in terminal",
+    description: "Run a shell command in the lane's terminal and wait for its exit code.",
+    icon: "$",
+    inputs: [{ id: "in" }],
+    outputs: [{ id: "out", label: "output" }],
+    executor: terminalRunExecutor,
+    configSchema: [
+      {
+        type: "textarea",
+        key: "command",
+        label: "Command",
+        rows: 3,
+        required: true,
+        placeholder: "npm test",
+        description: "Runs in the lane's shell, so `cd` and exported variables persist between nodes. SHELL ONLY \u2014 a TUI never returns to a prompt, so use Send + Await for one."
+      },
+      {
+        type: "number",
+        key: "timeoutMs",
+        label: "Timeout (ms)",
+        default: 12e4,
+        description: "How long to wait for the command to finish before failing the run."
+      },
+      {
+        type: "switch",
+        key: "failOnNonZero",
+        label: "Fail the run on a non-zero exit",
+        default: true,
+        description: "On by default. Turning it off means a failed command lets the run report success \u2014 read the exit code on the output port and branch on it instead."
+      }
+    ],
+    defaultConfig: { command: "", timeoutMs: 12e4, failOnNonZero: true }
+  },
+  {
+    name: "@particle-academy/terminal_send",
+    aliases: ["terminal_send", "@fancy/terminal_send"],
+    category: "io",
+    label: "Send to terminal",
+    description: "Type text at whatever is running in the lane's terminal, without waiting.",
+    icon: "\u2328",
+    inputs: [{ id: "in" }],
+    outputs: [{ id: "out", label: "sent" }],
+    executor: terminalSendExecutor,
+    configSchema: [
+      {
+        type: "textarea",
+        key: "text",
+        label: "Text",
+        rows: 4,
+        placeholder: "Summarise the failing test and propose a fix.",
+        description: "What to type. This is how a graph prompts an agent TUI such as Claude Code or Codex."
+      },
+      {
+        type: "switch",
+        key: "submit",
+        label: "Press Enter",
+        default: true,
+        description: "Off leaves the text on the input line \u2014 useful for building one up across several nodes."
+      },
+      {
+        type: "switch",
+        key: "clearFirst",
+        label: "Forget earlier output first",
+        default: false,
+        description: "Discards anything the terminal said before this send, so a following Await cannot match a prompt left over from the previous exchange."
+      }
+    ],
+    defaultConfig: { text: "", submit: true, clearFirst: false }
+  },
+  {
+    name: "@particle-academy/terminal_await",
+    aliases: ["terminal_await", "@fancy/terminal_await"],
+    category: "io",
+    label: "Await terminal output",
+    description: "Wait until the lane's terminal prints something that matches.",
+    icon: "\u23F1",
+    inputs: [{ id: "in" }],
+    outputs: [{ id: "out", label: "output" }],
+    executor: terminalAwaitExecutor,
+    configSchema: [
+      {
+        type: "text",
+        key: "pattern",
+        label: "Wait for",
+        required: true,
+        placeholder: "esc to interrupt",
+        description: "Matched against the output with colour codes already stripped, so match what you SEE."
+      },
+      {
+        type: "select",
+        key: "mode",
+        label: "Match as",
+        default: "text",
+        options: [
+          { value: "text", label: "Plain text" },
+          { value: "regex", label: "Regular expression" }
+        ],
+        description: "Regex mode also returns capture groups, which is how a value gets out of a prompt."
+      },
+      {
+        type: "number",
+        key: "timeoutMs",
+        label: "Timeout (ms)",
+        default: 12e4
+      },
+      {
+        type: "select",
+        key: "onTimeout",
+        label: "If it never appears",
+        default: "fail",
+        options: [
+          { value: "fail", label: "Fail the run" },
+          { value: "continue", label: "Continue with matched: false" }
+        ],
+        description: "Failing is the default. Continuing lets the next node type at a process that never became ready while the run still reports success, so it has to be asked for."
+      }
+    ],
+    defaultConfig: { pattern: "", mode: "text", timeoutMs: 12e4, onTimeout: "fail" }
+  },
   {
     // Note — a sticky-note annotation. Portless + visual-only: the runtime skips
     // the `annotation` category, so a note's text NEVER reaches a runner — it
@@ -11157,6 +11985,7 @@ exports.ensureBuiltinKinds = ensureBuiltinKinds;
 exports.getLlmClient = getLlmClient;
 exports.getNodeKind = getNodeKind;
 exports.getRichInputAdapter = getRichInputAdapter;
+exports.getTerminalHost = getTerminalHost;
 exports.getWorkflowResolver = getWorkflowResolver;
 exports.isPause = isPause;
 exports.isResolutionFailure = isResolutionFailure;
@@ -11174,6 +12003,7 @@ exports.registerBuiltinKinds = registerBuiltinKinds;
 exports.registerLlmClient = registerLlmClient;
 exports.registerNodeKind = registerNodeKind;
 exports.registerRichInputAdapter = registerRichInputAdapter;
+exports.registerTerminalHost = registerTerminalHost;
 exports.registerWorkflowResolver = registerWorkflowResolver;
 exports.resolveFallbackPort = resolveFallbackPort;
 exports.resolveKindId = resolveKindId;