@particle-academy/fancy-flow 0.65.1 → 0.66.0

package/dist/engine.cjs

@@ -2533,9 +2533,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;
@@ -2547,7 +2547,7 @@ function end_default() {
       }
       schedule.on = on1;
     });
-    if (size === 0) resolve();
+    if (size === 0) resolve2();
   });
 }
 
@@ -3508,13 +3508,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 || {} };
@@ -5130,8 +5130,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;
@@ -5233,16 +5233,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;
@@ -9030,11 +9030,11 @@ function NoteNodeInner(props) {
   const config = data.config ?? {};
   const api = useFlowEditorOptional();
   const hasConfigText = typeof config.text === "string" && config.text.length > 0;
-  const text2 = 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(text2);
+  const [draft, setDraft] = ReactExports.useState(text3);
   const areaRef = ReactExports.useRef(null);
   ReactExports.useEffect(() => {
     if (editing && areaRef.current) {
@@ -9045,7 +9045,7 @@ function NoteNodeInner(props) {
   }, [editing]);
   const commit = () => {
     setEditing(false);
-    if (!api || draft === text2) return;
+    if (!api || draft === text3) return;
     const current = api.nodes.find((n) => n.id === props.id);
     if (!current) return;
     api.updateNode({
@@ -9059,7 +9059,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(text2);
+        setDraft(text3);
         setEditing(true);
       } : void 0,
       children: [
@@ -9078,7 +9078,7 @@ function NoteNodeInner(props) {
               if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) commit();
             }
           }
-        ) : /* @__PURE__ */ jsxRuntime.jsx("div", { className: "ff-note__body", children: text2 || /* @__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" }) })
       ]
     }
   );
@@ -9243,6 +9243,376 @@ 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 resolvePath(path, context) {
+  return tryResolvePath(path, context).value;
+}
+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 "";
+  }
+}
+function evaluateConfig(config, context, options = {}) {
+  const out = {};
+  for (const [key2, value] of Object.entries(config)) {
+    out[key2] = Array.isArray(value) ? value.map((v) => evaluateExpression(v, context, options)) : value !== null && typeof value === "object" ? evaluateConfig(value, context, options) : evaluateExpression(value, context, options);
+  }
+  return out;
+}
+
+// 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 key2 = typeof row.key === "string" ? row.key.trim() : "";
+    if (key2 === "") continue;
+    out[key2] = 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, key2) {
+  const value = config[key2];
+  return typeof value === "string" ? value : "";
+}
+function millis(config, key2, fallback) {
+  const value = Number(config[key2]);
+  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",
@@ -9532,6 +9902,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.",
@@ -9629,6 +10002,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`.",
@@ -9649,6 +10025,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.",
@@ -9694,6 +10073,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.",
@@ -10152,6 +10534,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
@@ -10489,6 +11044,239 @@ 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 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;
+    }
+  }
+  /**
+   * 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 = (key2) => {
+    const value = config[key2];
+    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";
@@ -10567,6 +11355,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 {
@@ -10632,7 +11439,8 @@ async function runFlow(graph, executors, onEvent = () => {
             emit: onEvent,
             executors,
             depth,
-            run
+            run,
+            terminal: terminalAccessorFor(node)
           })
         );
         outputs[node.id] = result;
@@ -10654,6 +11462,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 });
@@ -10732,7 +11543,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") {
@@ -10802,106 +11613,6 @@ function errorText(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
-// 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, resolve) {
-  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) + resolve(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 resolvePath(path, context) {
-  return tryResolvePath(path, context).value;
-}
-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 "";
-  }
-}
-function evaluateConfig(config, context, options = {}) {
-  const out = {};
-  for (const [key2, value] of Object.entries(config)) {
-    out[key2] = Array.isArray(value) ? value.map((v) => evaluateExpression(v, context, options)) : value !== null && typeof value === "object" ? evaluateConfig(value, context, options) : evaluateExpression(value, context, options);
-  }
-  return out;
-}
-
 // src/registry/pause.ts
 var PAUSE_PREFIX = "fancy-flow:pause:";
 var LEGACY_PAUSE_PREFIXES = [
@@ -11345,31 +12056,31 @@ async function runFixtures(file, executor) {
     }
     const result = await runFlow(graph, executors, (e) => events.push(e));
     releaseStubs();
-    const fail = (message) => failures.push({ case: testCase.name, message });
+    const fail2 = (message) => failures.push({ case: testCase.name, message });
     const expected = testCase.expect;
     let caseOk = true;
     if (expected.pause) {
       const paused = decodePause(result.error);
       if (!paused) {
         caseOk = false;
-        fail(`expected a pause awaiting "${expected.pause.awaiting}", got ${result.ok ? "a completed run" : `error: ${result.error}`}`);
+        fail2(`expected a pause awaiting "${expected.pause.awaiting}", got ${result.ok ? "a completed run" : `error: ${result.error}`}`);
       } else {
         if (paused.awaiting !== expected.pause.awaiting) {
           caseOk = false;
-          fail(`expected pause awaiting "${expected.pause.awaiting}", got "${paused.awaiting}"`);
+          fail2(`expected pause awaiting "${expected.pause.awaiting}", got "${paused.awaiting}"`);
         }
         if ("detail" in expected.pause && !deepEqual(paused.detail, expected.pause.detail)) {
           caseOk = false;
-          fail(`pause detail mismatch: expected ${JSON.stringify(expected.pause.detail)}, got ${JSON.stringify(paused.detail)}`);
+          fail2(`pause detail mismatch: expected ${JSON.stringify(expected.pause.detail)}, got ${JSON.stringify(paused.detail)}`);
         }
       }
     } else if (expected.error !== void 0) {
       if (result.ok) {
         caseOk = false;
-        fail(`expected an error containing "${expected.error}", but the run succeeded`);
+        fail2(`expected an error containing "${expected.error}", but the run succeeded`);
       } else if (!String(result.error ?? "").includes(expected.error)) {
         caseOk = false;
-        fail(`expected an error containing "${expected.error}", got "${result.error}"`);
+        fail2(`expected an error containing "${expected.error}", got "${result.error}"`);
       }
     } else {
       if (expected.ports !== void 0) {
@@ -11377,34 +12088,34 @@ async function runFixtures(file, executor) {
         const want = [...expected.ports].sort();
         if (!deepEqual(got, want)) {
           caseOk = false;
-          fail(
+          fail2(
             `expected these ports to reach a downstream node: [${want.join(", ")}], but [${got.join(", ")}] did` + (result.ok ? "" : ` (run error: ${result.error})`)
           );
         }
       }
       if ("value" in expected && !deepEqual(carried, expected.value)) {
         caseOk = false;
-        fail(`expected the value carried downstream to be ${JSON.stringify(expected.value)}, got ${JSON.stringify(carried)}`);
+        fail2(`expected the value carried downstream to be ${JSON.stringify(expected.value)}, got ${JSON.stringify(carried)}`);
       }
     }
     for (const want of expected.events ?? []) {
       if (!events.some((e) => matchesEvent(e, want))) {
         caseOk = false;
-        fail(`expected an emitted event matching ${JSON.stringify(want)}, but none of the ${events.length} emitted events did`);
+        fail2(`expected an emitted event matching ${JSON.stringify(want)}, but none of the ${events.length} emitted events did`);
       }
     }
     if (expected.afterResume) {
       const paused = decodePause(result.error);
       if (!paused) {
         caseOk = false;
-        fail("expected the run to pause before resuming, but it never paused");
+        fail2("expected the run to pause before resuming, but it never paused");
       } else {
         const resumed = await resume(kindId, testCase, executor, paused.nodeId, expected.afterResume.submit);
         const want = expected.afterResume;
         if (want.error !== void 0) {
           if (resumed.ok || !String(resumed.error ?? "").includes(want.error)) {
             caseOk = false;
-            fail(`after resume: expected an error containing "${want.error}", got ${resumed.ok ? "success" : `"${resumed.error}"`}`);
+            fail2(`after resume: expected an error containing "${want.error}", got ${resumed.ok ? "success" : `"${resumed.error}"`}`);
           }
         }
         if (want.ports !== void 0) {
@@ -11412,12 +12123,12 @@ async function runFixtures(file, executor) {
           const wanted = [...want.ports].sort();
           if (!deepEqual(got, wanted)) {
             caseOk = false;
-            fail(`after resume: expected ports [${wanted.join(", ")}] to reach a downstream node, but [${got.join(", ")}] did`);
+            fail2(`after resume: expected ports [${wanted.join(", ")}] to reach a downstream node, but [${got.join(", ")}] did`);
           }
         }
         if ("value" in want && !deepEqual(resumed.carried, want.value)) {
           caseOk = false;
-          fail(`after resume: expected the value carried downstream to be ${JSON.stringify(want.value)}, got ${JSON.stringify(resumed.carried)}`);
+          fail2(`after resume: expected the value carried downstream to be ${JSON.stringify(want.value)}, got ${JSON.stringify(resumed.carried)}`);
         }
       }
     }