@particle-academy/fancy-flow 0.66.0 → 0.66.1

package/dist/chunk-27RZJAE2.js

@@ -0,0 +1,2586 @@
+import { getLlmClient, getWorkflowResolver, isResolutionFailure, getTerminalHost } from './chunk-2QXKDLGT.js';
+
+// src/registry/llm-router.ts
+function declaredRoutes(config) {
+  const raw = config.routes;
+  if (!Array.isArray(raw)) return [];
+  return raw.map((r) => ({ port: String(r?.port ?? "").trim(), description: r?.description })).filter((r) => r.port !== "");
+}
+function resolveFallbackPort(routes, fallbackEnabled) {
+  if (fallbackEnabled) return "fallback";
+  return routes[0]?.port ?? "out";
+}
+var llmRouterExecutor = async (ctx) => {
+  const config = ctx.node.data?.config ?? {};
+  const routes = declaredRoutes(config);
+  if (routes.length === 0) {
+    ctx.abort("llm_router has no routes configured");
+  }
+  const client = getLlmClient();
+  if (!client) {
+    ctx.abort(
+      "No LLM client registered. Call registerLlmClient() with your provider adapter \u2014 fancy-flow ships the routing, not the model call."
+    );
+  }
+  const fallbackEnabled = config.fallback !== false;
+  const choice = await client.chooseRoute({
+    system: typeof config.system === "string" ? config.system : void 0,
+    prompt: String(config.prompt ?? ctx.inputs ?? ""),
+    routes,
+    provider: typeof config.provider === "string" ? config.provider : void 0,
+    model: typeof config.model === "string" ? config.model : void 0,
+    credential: typeof config.credential === "string" ? config.credential : void 0
+  });
+  const offered = new Set(routes.map((r) => r.port));
+  let port = choice?.port ?? "";
+  let reason = choice?.reason;
+  if (!offered.has(port)) {
+    const safe = resolveFallbackPort(routes, fallbackEnabled);
+    ctx.emit({
+      type: "log",
+      nodeId: ctx.node.id,
+      level: "warn",
+      message: `llm_router: model returned "${port || "(nothing)"}", which is not a declared route. Routing to "${safe}".`
+    });
+    reason = reason ?? `unrecognised route "${port}"`;
+    port = safe;
+  }
+  return { __port: port, value: { route: port, reason, input: ctx.inputs } };
+};
+
+// src/registry/ports.ts
+function resolvePortSpec(spec, config) {
+  if (spec === void 0) return void 0;
+  if (typeof spec !== "function") return spec;
+  try {
+    const resolved = spec(config);
+    return Array.isArray(resolved) ? resolved : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function nodeConfig(node) {
+  return node.data?.config ?? {};
+}
+function resolveNodePorts(node, kind) {
+  const config = nodeConfig(node);
+  const data = node.data;
+  return {
+    inputs: data?.inputs ?? resolvePortSpec(kind?.inputs, config),
+    outputs: data?.outputs ?? resolvePortSpec(kind?.outputs, config)
+  };
+}
+
+// src/runtime/run-identity.ts
+function escapeSegment(value) {
+  return value.replace(/%/g, "%25").replace(/\//g, "%2F").replace(/#/g, "%23");
+}
+function renderSegment(value, occurrence) {
+  const escaped = escapeSegment(value);
+  return occurrence === void 0 || occurrence === null ? escaped : `${escaped}#${occurrence}`;
+}
+function instant(value) {
+  const ms = Date.parse(value);
+  if (Number.isNaN(ms)) {
+    throw new Error(
+      `RunIdentity: firstAttemptAt is not a parseable timestamp: ${JSON.stringify(value)}`
+    );
+  }
+  return ms;
+}
+var RunIdentity = class _RunIdentity {
+  constructor(runKey, path = [], attempt = 1, firstAttemptAt = (/* @__PURE__ */ new Date()).toISOString()) {
+    if (!runKey || runKey.trim() === "") {
+      throw new Error("RunIdentity: runKey must be a non-empty string.");
+    }
+    this.runKey = runKey;
+    this.path = Object.freeze([...path]);
+    this.attempt = Math.max(1, Math.trunc(attempt));
+    this.firstAttemptAt = firstAttemptAt;
+    Object.freeze(this);
+  }
+  /**
+   * The identity of one execution of one node — stable across retries of that
+   * execution, distinct from every other execution of the same node.
+   *
+   * Pass `occurrence` when an executor runs the same node more than once at the
+   * same level (a loop body, one item of a fan-out it drives itself).
+   */
+  stepKey(nodeId, occurrence) {
+    return `${this.runKey}:${[...this.path, renderSegment(nodeId, occurrence)].join("/")}`;
+  }
+  /**
+   * A child identity for work nested inside this step.
+   *
+   * `subflow` pushes the invoking node's id, so a node inside the child graph
+   * cannot collide with a same-named node in the parent. Attempt and
+   * `firstAttemptAt` are carried down unchanged: the nested work happens inside
+   * this step's attempt, and shares its clock.
+   */
+  descend(segment, occurrence) {
+    return new _RunIdentity(
+      this.runKey,
+      [...this.path, renderSegment(segment, occurrence)],
+      this.attempt,
+      this.firstAttemptAt
+    );
+  }
+  /** A copy on a different attempt, first-attempt clock preserved. */
+  withAttempt(attempt, firstAttemptAt) {
+    return new _RunIdentity(
+      this.runKey,
+      this.path,
+      attempt,
+      firstAttemptAt ?? this.firstAttemptAt
+    );
+  }
+  /**
+   * May this attempt reuse the step key and still be deduplicated?
+   *
+   * Providers forget idempotency keys — Stripe after 24 hours. Past that
+   * window, resending the key creates a second charge and sending a fresh one
+   * creates a second charge, so **the caller must refuse rather than pick
+   * between them**: a loud stuck run beats a silent double write.
+   *
+   * `true` on attempt 1 whatever the elapsed time — nothing was sent on an
+   * earlier attempt, so there is nothing for the provider to have forgotten.
+   * That is what lets a run park on a human gate for a week and then write.
+   *
+   * `windowSeconds: null` means the provider does not expire keys. `0` means
+   * it does not dedupe at all, so no retry may reuse a key — it is a real
+   * window, not an absent one, and the two must not be conflated: reading `0`
+   * as `null` turns "this provider does not dedupe" into "this provider
+   * dedupes forever", which is the more dangerous of the two by a distance.
+   */
+  isReplaySafe(windowSeconds, now = /* @__PURE__ */ new Date()) {
+    if (this.attempt <= 1) return true;
+    if (windowSeconds === null || windowSeconds === void 0) return true;
+    if (windowSeconds <= 0) return false;
+    const nowMs = typeof now === "string" ? instant(now) : now.getTime();
+    const elapsedSeconds = Math.max(0, (nowMs - instant(this.firstAttemptAt)) / 1e3);
+    return elapsedSeconds <= windowSeconds;
+  }
+  toJSON() {
+    return {
+      runKey: this.runKey,
+      path: [...this.path],
+      attempt: this.attempt,
+      firstAttemptAt: this.firstAttemptAt
+    };
+  }
+  /** Rebuild from a queue payload. */
+  static from(value) {
+    if (value instanceof _RunIdentity) return value;
+    if (typeof value === "string") return new _RunIdentity(value);
+    return new _RunIdentity(
+      value.runKey,
+      value.path ?? [],
+      value.attempt ?? 1,
+      value.firstAttemptAt ?? (/* @__PURE__ */ new Date()).toISOString()
+    );
+  }
+};
+
+// src/components/FlowEditor/human-fields.ts
+var HUMAN_FIELD_TYPE_ALIASES = {
+  text: "text",
+  string: "text",
+  str: "text",
+  input: "text",
+  textarea: "textarea",
+  long_text: "textarea",
+  longtext: "textarea",
+  "long-text": "textarea",
+  multiline: "textarea",
+  paragraph: "textarea",
+  markdown: "textarea",
+  number: "number",
+  numeric: "number",
+  integer: "number",
+  int: "number",
+  float: "number",
+  decimal: "number",
+  select: "select",
+  enum: "select",
+  choice: "select",
+  choices: "select",
+  dropdown: "select",
+  options: "select",
+  radio: "select",
+  switch: "switch",
+  bool: "switch",
+  boolean: "switch",
+  checkbox: "switch",
+  toggle: "switch",
+  date: "date",
+  datetime: "datetime",
+  "datetime-local": "datetime",
+  datetimelocal: "datetime",
+  timestamp: "datetime",
+  time: "time",
+  email: "email",
+  "e-mail": "email",
+  url: "url",
+  uri: "url",
+  link: "url",
+  tel: "tel",
+  phone: "tel",
+  telephone: "tel",
+  password: "password",
+  secret: "password"
+};
+function humanFieldType(raw) {
+  if (typeof raw !== "string") return "text";
+  return HUMAN_FIELD_TYPE_ALIASES[raw.trim().toLowerCase()] ?? "text";
+}
+function humanFieldOptions(raw) {
+  const entries = [];
+  if (Array.isArray(raw)) {
+    for (const item of raw) {
+      if (typeof item === "string" || typeof item === "number") {
+        const value = String(item);
+        if (value !== "") entries.push({ value, label: value });
+        continue;
+      }
+      if (item && typeof item === "object") {
+        const value = item.value;
+        if (value === void 0 || value === null || value === "") continue;
+        const label = item.label;
+        entries.push({
+          value: String(value),
+          label: typeof label === "string" && label !== "" ? label : String(value)
+        });
+      }
+    }
+  } else if (raw && typeof raw === "object") {
+    for (const [value, label] of Object.entries(raw)) {
+      if (value === "") continue;
+      entries.push({ value, label: typeof label === "string" && label !== "" ? label : value });
+    }
+  }
+  return entries.length ? entries : void 0;
+}
+function humanInputFields(config) {
+  const raw = Array.isArray(config?.fields) ? config.fields : [];
+  const fields = raw.filter((f) => f && typeof f === "object" && typeof f.key === "string" && f.key).map((f) => ({
+    key: f.key,
+    label: typeof f.label === "string" && f.label ? f.label : f.key,
+    type: humanFieldType(f.type),
+    required: !!f.required,
+    placeholder: typeof f.placeholder === "string" ? f.placeholder : void 0,
+    options: humanFieldOptions(f.options ?? f.choices),
+    default: f.default
+  }));
+  if (fields.length) return fields;
+  const title = typeof config?.title === "string" && config.title ? config.title : "Your answer";
+  return [{ key: "value", label: title, type: "textarea", required: true }];
+}
+
+// src/registry/subflow.ts
+var DEFAULT_MAX_DEPTH = 8;
+function subflowMode(config) {
+  const mode = config.mode;
+  return mode === "stream" || mode === "both" ? mode : "output";
+}
+function subflowPorts(config) {
+  const mode = subflowMode(config);
+  const ports = [{ id: "out", label: "result" }];
+  if (mode === "stream" || mode === "both") ports.unshift({ id: "stream", label: "stream" });
+  return ports;
+}
+var subflowExecutor = async (ctx) => {
+  const config = ctx.node.data?.config ?? {};
+  const ref = String(config.workflow ?? "").trim();
+  if (!ref) ctx.abort("subflow has no workflow reference configured");
+  const resolver = getWorkflowResolver();
+  if (!resolver) {
+    ctx.abort(
+      "No workflow resolver registered. Call registerWorkflowResolver() so subflow can find the workflow it references."
+    );
+  }
+  const maxDepth = Number.isFinite(config.maxDepth) ? Number(config.maxDepth) : DEFAULT_MAX_DEPTH;
+  const depth = ctx.depth ?? 0;
+  if (depth + 1 > maxDepth) {
+    ctx.abort(
+      `subflow depth limit reached (${maxDepth}) at "${ref}" \u2014 a workflow is referencing itself, directly or through a chain.`
+    );
+  }
+  const pinned = config.version === void 0 || config.version === "" ? void 0 : Number(config.version);
+  if (pinned !== void 0 && !Number.isInteger(pinned)) {
+    ctx.abort(`subflow "${ref}" has a non-integer version pin (${String(config.version)}).`);
+  }
+  const resolved = await resolver(ref, pinned);
+  const child = isResolutionFailure(resolved) ? ctx.abort(
+    resolved.reason === "version-mismatch" ? resolved.message ?? `subflow "${ref}" is pinned to version ${pinned}, but the host has ${resolved.available ?? "a different version"}.` : resolved.message ?? `subflow could not resolve workflow "${ref}"`
+  ) : resolved;
+  if (!child) ctx.abort(`subflow could not resolve workflow "${ref}"`);
+  const mode = subflowMode(config);
+  const streaming = mode === "stream" || mode === "both";
+  const forward = (event) => {
+    if (!streaming) return;
+    const detail = event.type === "node-status" ? `${event.nodeId} ${event.status}` : event.type === "run-end" ? `finished (${event.ok ? "ok" : "failed"})` : event.type;
+    ctx.emit({
+      type: "log",
+      nodeId: ctx.node.id,
+      level: "info",
+      message: `[${ref}] ${detail}`
+    });
+  };
+  const result = await runFlow(
+    child,
+    // Inherit the parent's registry, then let the graph layer its own on top.
+    // The inherited half is the fix; the layered half keeps a graph that
+    // deliberately hands its child extra or different executors working.
+    { ...ctx.executors ?? {}, ...config.executors ?? {} },
+    forward,
+    {
+      initialInputs: config.inputs ?? {
+        // With no explicit mapping, hand the parent's inputs to the child's
+        // entry points — the obvious default, and it makes the simple case
+        // require no configuration at all.
+        __parent: ctx.inputs
+      },
+      depth: depth + 1,
+      // Push THIS node onto the identity path, so a node inside the child graph
+      // cannot share an idempotency key with a same-named node in the parent —
+      // or with the same child graph invoked from a different parent node.
+      // Attempt and the first-attempt clock ride down unchanged: the child's
+      // work happens inside this node's attempt.
+      run: ctx.run?.descend(ctx.node.id)
+    }
+  );
+  if (!result.ok) {
+    ctx.abort(`subflow "${ref}" failed: ${result.error ?? "unknown error"}`);
+  }
+  if (mode === "stream") {
+    return { __port: "stream", value: result.outputs };
+  }
+  if (mode === "both") {
+    return result.outputs;
+  }
+  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 [key, value] of Object.entries(config)) {
+    out[key] = 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 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-kinds.ts
+var HUMAN_FIELD_OUTPUT_TYPE = {
+  text: "string",
+  textarea: "string",
+  select: "string",
+  date: "string",
+  datetime: "string",
+  time: "string",
+  email: "string",
+  url: "string",
+  tel: "string",
+  password: "string",
+  number: "number",
+  switch: "boolean"
+};
+function casePorts(cases) {
+  const byPort = /* @__PURE__ */ new Map();
+  if (cases && typeof cases === "object" && !Array.isArray(cases)) {
+    for (const [match, port] of Object.entries(cases)) {
+      if (typeof port !== "string" || port === "" || port === "default") continue;
+      const matches = byPort.get(port) ?? [];
+      matches.push(match);
+      byPort.set(port, matches);
+    }
+  }
+  const ports = [...byPort].map(([id, matches]) => ({
+    id,
+    label: matches.join("|")
+  }));
+  return [...ports, { id: "default", label: "default" }];
+}
+function routePorts(routes, fallback) {
+  const ports = [];
+  const seen = /* @__PURE__ */ new Set();
+  if (Array.isArray(routes)) {
+    for (const route of routes) {
+      const id = route?.port;
+      if (typeof id !== "string" || id.trim() === "" || seen.has(id)) continue;
+      seen.add(id);
+      ports.push({ id, label: id });
+    }
+  }
+  if (fallback !== false && !seen.has("fallback")) {
+    ports.push({ id: "fallback", label: "fallback" });
+  }
+  if (ports.length === 0) ports.push({ id: "out" });
+  return ports;
+}
+var HTTP_METHODS = [
+  { type: "select", key: "method", label: "Method", options: [
+    { value: "GET", label: "GET" },
+    { value: "POST", label: "POST" },
+    { value: "PUT", label: "PUT" },
+    { value: "PATCH", label: "PATCH" },
+    { value: "DELETE", label: "DELETE" }
+  ], default: "GET", required: true }
+];
+var KINDS = [
+  // ───────────── Triggers ─────────────
+  {
+    name: "@particle-academy/manual_trigger",
+    // Returns the raw inputs MAP, not the `in` port -- flat at an entry
+    // point, port-keyed the moment the node has an inbound edge.
+    emits: "input-map-merged",
+    aliases: ["manual_trigger", "@fancy/manual_trigger"],
+    category: "trigger",
+    label: "Manual",
+    description: "Entry point fired when the user clicks Run.",
+    icon: "\u26A1",
+    inputs: [],
+    outputs: [{ id: "out" }]
+  },
+  {
+    name: "@particle-academy/webhook_trigger",
+    aliases: ["webhook_trigger", "@fancy/webhook_trigger"],
+    category: "trigger",
+    label: "Webhook",
+    description: "Triggered by an inbound HTTP request to a host-provided URL.",
+    icon: "\u{1F4E1}",
+    inputs: [],
+    outputs: [{ id: "out", label: "payload" }],
+    configSchema: [
+      { type: "text", key: "path", label: "Path", placeholder: "/hooks/my-flow", required: true },
+      { type: "select", key: "method", label: "Method", options: [
+        { value: "POST", label: "POST" },
+        { value: "GET", label: "GET" }
+      ], default: "POST" },
+      { type: "credential", key: "secret", label: "Verifying secret", credentialType: "webhook_secret" }
+    ]
+  },
+  {
+    name: "@particle-academy/schedule_trigger",
+    outputShape: [
+      { path: "cron", type: "string", description: "The cron expression that fired." },
+      { path: "timezone", type: "string", description: "The timezone it was evaluated in." }
+    ],
+    // Merges $ctx->inputs ITSELF beside cron/timezone -- the MAP, whose
+    // shape depends on position, not each port's payload the way `merge` does.
+    emits: "input-map-merged",
+    aliases: ["schedule_trigger", "@fancy/schedule_trigger"],
+    category: "trigger",
+    label: "Schedule",
+    description: "Fires on a cron schedule (host-implemented).",
+    icon: "\u23F1",
+    inputs: [],
+    outputs: [{ id: "out" }],
+    configSchema: [
+      {
+        type: "text",
+        key: "cron",
+        label: "Cron",
+        placeholder: "*/5 * * * *",
+        required: true,
+        description: "Standard 5-field cron expression."
+      },
+      { type: "text", key: "timezone", label: "Timezone", placeholder: "UTC", default: "UTC" }
+    ]
+  },
+  {
+    name: "@particle-academy/user_input",
+    // The keys an author declared on THIS node — the case a static list cannot
+    // express, and the one issue #5 named.
+    //
+    // The TYPE comes from the same normalizer the form renders with, so the
+    // variable picker agrees with what the run actually resolves. It used to say
+    // `string` for every field, which was wrong the moment a field was a number
+    // or a switch — the picker told an author `{{ $json.age }}` was text while
+    // the form handed the next node a number.
+    outputShape: (config) => (config.fields ?? []).filter((f) => typeof f.key === "string" && f.key !== "").map((f) => ({
+      path: f.key,
+      type: HUMAN_FIELD_OUTPUT_TYPE[humanFieldType(f.type)],
+      description: f.label
+    })),
+    aliases: ["user_input", "@fancy/user_input"],
+    pausesForHuman: "input",
+    category: "human",
+    label: "User Input",
+    description: "Pause the flow until the user submits the configured form.",
+    icon: "\u270E",
+    inputs: [{ id: "in" }],
+    outputs: [{ id: "out", label: "values" }],
+    configSchema: [
+      { type: "text", key: "title", label: "Form title", default: "Need your input" },
+      {
+        type: "repeater",
+        key: "fields",
+        label: "Fields",
+        description: "The form the run pauses on.",
+        titleKey: "label",
+        addLabel: "Add field",
+        minItems: 1,
+        fields: [
+          { type: "text", key: "key", label: "Key", required: true, placeholder: "answer" },
+          { type: "text", key: "label", label: "Label", required: true, placeholder: "Your answer" },
+          {
+            type: "select",
+            key: "type",
+            label: "Type",
+            default: "text",
+            // Every control `HumanPrompt` can render. A type the form supports
+            // but the panel cannot select is reachable only by hand-editing the
+            // workflow JSON — which is the audience this panel exists for.
+            options: [
+              { value: "text", label: "Text" },
+              { value: "textarea", label: "Long text" },
+              { value: "number", label: "Number" },
+              { value: "select", label: "Select" },
+              { value: "switch", label: "Switch (yes / no)" },
+              { value: "date", label: "Date" },
+              { value: "datetime", label: "Date + time" },
+              { value: "time", label: "Time" },
+              { value: "email", label: "Email" },
+              { value: "url", label: "URL" },
+              { value: "tel", label: "Phone" },
+              { value: "password", label: "Password" }
+            ]
+          },
+          {
+            // Without this a panel-authored select had nothing to choose from,
+            // so it rendered an empty dropdown — the type was declarable and
+            // unusable in the same breath.
+            type: "keyvalue",
+            key: "options",
+            label: "Choices",
+            description: "Select fields only. Left is the value the flow receives, right is what the person sees.",
+            keyLabel: "Value",
+            valueLabel: "Label",
+            keyPlaceholder: "small",
+            valuePlaceholder: "Small",
+            addLabel: "Add choice"
+          },
+          { type: "switch", key: "required", label: "Required", default: false }
+        ],
+        default: [{ key: "answer", label: "Your answer", type: "textarea", required: true }]
+      }
+    ]
+  },
+  {
+    name: "@particle-academy/rich_user_input",
+    aliases: ["rich_user_input", "@fancy/rich_user_input"],
+    pausesForHuman: "input",
+    category: "human",
+    label: "Rich User Input",
+    description: "Pause the flow on a fully authored page \u2014 content, required reading, multi-section forms.",
+    icon: "\u25A4",
+    inputs: [{ id: "in" }],
+    outputs: [{ id: "out", label: "values" }],
+    configSchema: [
+      { type: "text", key: "title", label: "Step title", default: "Please review" },
+      {
+        type: "document",
+        key: "document",
+        label: "Page content",
+        documentType: "stages",
+        description: "Authored with the host's document editor (fancy-cms Stages)."
+      },
+      { type: "switch", key: "requireConfirm", label: "Require explicit confirmation", default: true },
+      { type: "text", key: "submitLabel", label: "Submit button", default: "Continue" }
+    ]
+  },
+  {
+    name: "@particle-academy/subflow",
+    aliases: ["subflow", "@fancy/subflow"],
+    category: "logic",
+    label: "SubFlow",
+    description: "Run another workflow and bring its result \u2014 or its live progress \u2014 back into this one.",
+    icon: "\u29C9",
+    inputs: [{ id: "in" }],
+    // The stream port only exists when something actually streams.
+    outputs: (config) => subflowPorts(config ?? {}),
+    // Core, not marketplace: it runs a child graph through this same engine and
+    // needs nothing from outside except where workflows live.
+    executor: subflowExecutor,
+    configSchema: [
+      {
+        type: "text",
+        key: "workflow",
+        label: "Workflow",
+        required: true,
+        placeholder: "onboarding-v2",
+        description: "Reference resolved by the host's registerWorkflowResolver()."
+      },
+      {
+        type: "number",
+        key: "version",
+        label: "Pin to version",
+        description: "Optional. Leave blank to always run the child's current version. Pinning fails the run loudly if the child has moved on \u2014 without it, someone edits the child and this flow silently runs different logic."
+      },
+      {
+        type: "select",
+        key: "mode",
+        label: "Return",
+        default: "output",
+        options: [
+          { value: "output", label: "Output when it finishes" },
+          { value: "stream", label: "Stream progress as it runs" },
+          { value: "both", label: "Both \u2014 stream, then output" }
+        ],
+        description: "Streaming adds a second port so a parent can show progress instead of a spinner."
+      },
+      {
+        type: "keyvalue",
+        key: "inputs",
+        label: "Input mapping",
+        description: "Values handed to the child's entry points. Omit to pass this node's inputs straight through.",
+        keyLabel: "Name",
+        valueLabel: "Value",
+        addLabel: "Add input"
+      },
+      {
+        type: "number",
+        key: "maxDepth",
+        label: "Max nesting depth",
+        default: DEFAULT_MAX_DEPTH,
+        min: 1,
+        max: 32,
+        description: "Guards against a workflow referencing itself."
+      }
+    ]
+  },
+  // ───────────── Logic ─────────────
+  {
+    name: "@particle-academy/branch",
+    // 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.",
+    icon: "\u25C7",
+    inputs: [{ id: "in" }],
+    outputs: [{ id: "true", label: "true" }, { id: "false", label: "false" }],
+    configSchema: [
+      {
+        type: "select",
+        key: "match",
+        label: "Match",
+        default: "all",
+        options: [
+          { value: "all", label: "All conditions (AND)" },
+          { value: "any", label: "Any condition (OR)" }
+        ]
+      },
+      {
+        type: "repeater",
+        key: "conditions",
+        label: "Conditions",
+        description: "Routes to `true` when these match, otherwise `false`.",
+        titleKey: "left",
+        addLabel: "Add condition",
+        minItems: 1,
+        fields: [
+          { type: "expression", key: "left", label: "Value", example: "{{ $json.status }}", required: true },
+          {
+            type: "select",
+            key: "operator",
+            label: "Is",
+            default: "eq",
+            options: [
+              { value: "eq", label: "equal to" },
+              { value: "neq", label: "not equal to" },
+              { value: "contains", label: "contains" },
+              { value: "not_contains", label: "does not contain" },
+              { value: "gt", label: "greater than" },
+              { value: "gte", label: "greater than or equal to" },
+              { value: "lt", label: "less than" },
+              { value: "lte", label: "less than or equal to" },
+              { value: "truthy", label: "true" },
+              { value: "falsy", label: "false" },
+              { value: "empty", label: "empty" },
+              { value: "not_empty", label: "not empty" }
+            ]
+          },
+          { type: "text", key: "right", label: "Compared to", placeholder: "active" }
+        ],
+        default: [{ left: "", operator: "eq", right: "" }]
+      },
+      {
+        type: "expression",
+        key: "condition",
+        label: "Raw expression (advanced)",
+        example: "{{ $json.active && $json.score > 10 }}",
+        description: "Escape hatch for logic the builder can't express. Overrides the conditions above when set."
+      }
+    ]
+  },
+  {
+    name: "@particle-academy/switch_case",
+    // returns its input on the chosen port
+    emits: "input",
+    aliases: ["switch_case", "@fancy/switch_case"],
+    category: "logic",
+    label: "Switch",
+    description: "Route to one of N labelled outputs based on a key.",
+    icon: "\u2933",
+    inputs: [{ id: "in" }],
+    // Ports ARE the config: every distinct port a case routes to becomes an
+    // output handle, plus the always-present `default`. Editing the cases map
+    // moves the ports on the canvas and the ports the runtime activates.
+    outputs: (config) => casePorts(config?.cases),
+    configSchema: [
+      { type: "expression", key: "value", label: "Switch on", example: "{{ $json.kind }}", required: true },
+      {
+        type: "keyvalue",
+        key: "cases",
+        label: "Cases",
+        description: "Match value \u2192 output port. Unmatched input takes `default`.",
+        keyLabel: "When value is",
+        valueLabel: "Route to port",
+        keyPlaceholder: "a",
+        valuePlaceholder: "case_a",
+        addLabel: "Add case",
+        default: { a: "case_a", b: "case_b" }
+      }
+    ]
+  },
+  {
+    name: "@particle-academy/for_each",
+    outputShape: [
+      { path: "items", type: "array" },
+      { 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`.",
+    icon: "\u21BB",
+    inputs: [{ id: "in" }],
+    outputs: [{ id: "item", label: "item" }, { id: "done", label: "done" }],
+    configSchema: [
+      { type: "expression", key: "source", label: "List", example: "{{ $json.users }}", required: true },
+      { type: "number", key: "concurrency", label: "Concurrency", default: 1, min: 1, max: 50 }
+    ]
+  },
+  {
+    name: "@particle-academy/merge",
+    // `merge` mode unions every object input at the TOP level; `concat` builds
+    // a list instead, whose elements are not addressable as fields. So concat
+    // declares NOTHING rather than an empty list -- `[]` would claim "emits no
+    // fields" of a kind that emits a list, which is false and refuses every
+    // 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.",
+    icon: "\u2295",
+    inputs: [{ id: "a" }, { id: "b" }],
+    outputs: [{ id: "out" }],
+    configSchema: [
+      {
+        type: "select",
+        key: "mode",
+        label: "Mode",
+        default: "merge",
+        options: [{ value: "merge", label: "Object merge" }, { value: "concat", label: "Array concat" }]
+      }
+    ]
+  },
+  {
+    name: "@particle-academy/wait",
+    outputShape: [
+      { path: "waited", type: "string", description: "Which wait mode ran." },
+      { path: "duration", type: "number", description: "How long it waited." },
+      { path: "input", type: "unknown", description: "The value that arrived, carried forward." }
+    ],
+    aliases: ["wait", "@fancy/wait"],
+    category: "logic",
+    label: "Wait",
+    description: "Sleep or wait for an external event.",
+    icon: "\u23F8",
+    configSchema: [
+      {
+        type: "select",
+        key: "mode",
+        label: "Mode",
+        default: "duration",
+        options: [{ value: "duration", label: "Duration" }, { value: "until", label: "Until timestamp" }, { value: "event", label: "External event" }]
+      },
+      { type: "text", key: "duration", label: "Duration", placeholder: "5s, 10m, 1h", description: "Used when mode = duration." }
+    ]
+  },
+  {
+    name: "@particle-academy/transform",
+    // Two behaviours: the input unchanged when no expression is configured,
+    // 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.",
+    icon: "\u0192",
+    configSchema: [
+      {
+        type: "select",
+        key: "mode",
+        label: "Build the output",
+        default: "fields",
+        options: [
+          { value: "fields", label: "Field by field" },
+          { value: "expression", label: "One expression" }
+        ]
+      },
+      {
+        type: "repeater",
+        key: "fields",
+        label: "Output fields",
+        description: "Each row becomes a key on the result.",
+        titleKey: "key",
+        addLabel: "Add field",
+        fields: [
+          { type: "text", key: "key", label: "Key", required: true, placeholder: "name" },
+          { type: "expression", key: "value", label: "Value", example: "{{ $json.first }}", required: true }
+        ],
+        default: [{ key: "", value: "" }]
+      },
+      {
+        type: "expression",
+        key: "expression",
+        label: "Expression (advanced)",
+        example: "{{ { id: $json.id, name: $json.first + ' ' + $json.last } }}",
+        description: "Used when the mode above is set to one expression."
+      }
+    ]
+  },
+  // ───────────── Data ─────────────
+  {
+    name: "@particle-academy/memory_store",
+    aliases: ["memory_store", "@fancy/memory_store"],
+    category: "data",
+    label: "Memory Store",
+    description: "Read or write per-conversation memory.",
+    icon: "\u{1F9E0}",
+    configSchema: [
+      {
+        type: "select",
+        key: "operation",
+        label: "Operation",
+        required: true,
+        default: "read",
+        options: [{ value: "read", label: "Read" }, { value: "write", label: "Write" }, { value: "append", label: "Append" }]
+      },
+      { type: "text", key: "key", label: "Key", placeholder: "user.preferences", required: true },
+      { type: "expression", key: "value", label: "Value (write/append only)", example: "{{ $json }}" },
+      { type: "credential", key: "store", label: "Memory store", credentialType: "memory_store" }
+    ]
+  },
+  {
+    name: "@particle-academy/data_store",
+    aliases: ["data_store", "@fancy/data_store"],
+    category: "data",
+    label: "Data Store",
+    description: "Key-value or table read/write against a host store.",
+    icon: "\u{1F5C3}",
+    configSchema: [
+      {
+        type: "select",
+        key: "operation",
+        label: "Operation",
+        required: true,
+        default: "get",
+        options: [
+          { value: "get", label: "Get" },
+          { value: "set", label: "Set" },
+          { value: "delete", label: "Delete" },
+          { value: "query", label: "Query" },
+          { value: "list", label: "List" }
+        ]
+      },
+      { type: "text", key: "table", label: "Table / collection", required: true },
+      { type: "text", key: "key", label: "Key" },
+      {
+        type: "keyvalue",
+        key: "where",
+        label: "Where",
+        description: "Field/value pairs to match. For query and list operations.",
+        keyLabel: "Field",
+        valueLabel: "Equals",
+        addLabel: "Add filter"
+      },
+      { type: "expression", key: "value", label: "Value (set only)", example: "{{ $json }}" },
+      { type: "credential", key: "store", label: "Data store", credentialType: "data_store" }
+    ]
+  },
+  {
+    name: "@particle-academy/variable",
+    // evaluates the expression in config.value
+    emits: "expression:value",
+    aliases: ["variable", "@fancy/variable"],
+    category: "data",
+    label: "Variable",
+    description: "Workflow-scoped value used by other nodes.",
+    icon: "\u{1D4CD}",
+    configSchema: [
+      { type: "text", key: "name", label: "Name", required: true },
+      { type: "expression", key: "value", label: "Value", required: true }
+    ]
+  },
+  // ───────────── AI ─────────────
+  {
+    name: "@particle-academy/llm_call",
+    // LlmClient::complete() -> array{text:string,data?:mixed,usage?:array,raw?:mixed}
+    //
+    // A FUNCTION of config, because `data` exists only when this node was asked
+    // for a schema. Declaring it statically would offer `{{ $json.data }}` on
+    // every llm_call in the kit, including the ones that emit nothing of the
+    // sort — and a suggestion that resolves to null at runtime is worse than no
+    // suggestion, since the picker is exactly what gave the author confidence.
+    outputShape: (config) => {
+      const asked = config?.response_schema != null && config.response_schema !== "" && !(Array.isArray(config.response_schema) && config.response_schema.length === 0);
+      return [
+        { path: "text", type: "string", description: "The model's completion." },
+        ...asked ? [{ path: "data", type: "unknown", description: "The parsed, schema-checked result." }] : [],
+        { path: "usage", type: "object", description: "Token counts, when the provider reports them." },
+        { path: "raw", type: "unknown", description: "The provider's untouched response." }
+      ];
+    },
+    aliases: ["llm_call", "@fancy/llm_call"],
+    category: "ai",
+    label: "LLM Call",
+    description: "Send a prompt + context to a model and receive a response.",
+    icon: "\u2726",
+    configSchema: [
+      {
+        type: "select",
+        key: "provider",
+        label: "Provider",
+        default: "anthropic",
+        options: [
+          { value: "anthropic", label: "Anthropic" },
+          { value: "openai", label: "OpenAI" },
+          { value: "custom", label: "Custom" }
+        ]
+      },
+      { type: "text", key: "model", label: "Model", placeholder: "claude-sonnet-4-5", required: true },
+      { type: "textarea", key: "system", label: "System prompt", rows: 4 },
+      { type: "expression", key: "prompt", label: "User prompt", example: "{{ $json.question }}", required: true },
+      { type: "number", key: "temperature", label: "Temperature", min: 0, max: 2, step: 0.1, default: 0.7 },
+      { type: "number", key: "max_tokens", label: "Max tokens", min: 1, max: 8192, default: 1024 },
+      {
+        type: "repeater",
+        key: "tools",
+        label: "Tools",
+        description: "Tools the model may call.",
+        titleKey: "name",
+        addLabel: "Add tool",
+        fields: [
+          { type: "text", key: "name", label: "Name", required: true, placeholder: "search_index" },
+          { type: "text", key: "description", label: "When to use it" },
+          {
+            type: "json",
+            key: "input_schema",
+            label: "Input schema",
+            description: "JSON Schema for the tool's arguments."
+          }
+        ]
+      },
+      {
+        type: "json",
+        key: "response_schema",
+        label: "Response schema",
+        description: "Optional JSON Schema. When set, the runtime asks the provider for schema-valid JSON and the node emits the parsed value as `data` \u2014 reference it as {{ $json.data }}. A response that cannot be parsed or does not match FAILS the node rather than passing an empty value downstream."
+      },
+      { type: "credential", key: "credential", label: "API credential", credentialType: "llm_credential" }
+    ]
+  },
+  {
+    name: "@particle-academy/llm_router",
+    outputShape: [
+      { path: "route", type: "string", description: "The port the model chose." },
+      { path: "reason", type: "string", description: "Why the model chose it." },
+      { path: "input", type: "unknown", description: "The value that arrived, carried forward." }
+    ],
+    // Every id this node has ever shipped under keeps resolving — MOIC's saved
+    // flows carry the bare `llm_branch`.
+    aliases: ["llm_router", "llm_branch", "@fancy/llm_branch", "@fancy/llm_router"],
+    category: "ai",
+    label: "LLM Router",
+    description: "Let a model choose which route the flow takes.",
+    icon: "\u2727",
+    inputs: [{ id: "in" }],
+    // Each declared route is a port. The executor returns `{ __port: id }`
+    // (or `Port.only(id)` on the PHP runtime) to pick one.
+    outputs: (config) => routePorts(config?.routes, config?.fallback),
+    // A shuttle, not an engine: it carries the routes out to whatever LLM
+    // client the host registered and carries the choice back. No provider SDK
+    // reaches core, so this stays a builtin without adding a dependency.
+    executor: llmRouterExecutor,
+    configSchema: [
+      {
+        type: "textarea",
+        key: "system",
+        label: "System prompt",
+        rows: 3,
+        description: "Optional framing for the routing decision."
+      },
+      {
+        type: "expression",
+        key: "prompt",
+        label: "What to route on",
+        example: "{{ $json.message }}",
+        required: true
+      },
+      {
+        type: "repeater",
+        key: "routes",
+        label: "Routes",
+        description: "The model picks exactly one. Descriptions are what it chooses between \u2014 make them distinct.",
+        titleKey: "port",
+        addLabel: "Add route",
+        minItems: 2,
+        fields: [
+          { type: "text", key: "port", label: "Port", required: true, placeholder: "billing" },
+          {
+            type: "text",
+            key: "description",
+            label: "When to choose it",
+            required: true,
+            placeholder: "The user is asking about an invoice, refund, or payment."
+          }
+        ],
+        default: [
+          { port: "a", description: "Describe when the model should pick this route." },
+          { port: "b", description: "Describe when the model should pick this route." }
+        ]
+      },
+      {
+        type: "select",
+        key: "provider",
+        label: "Provider",
+        default: "anthropic",
+        options: [
+          { value: "anthropic", label: "Anthropic" },
+          { value: "openai", label: "OpenAI" },
+          { value: "custom", label: "Custom" }
+        ]
+      },
+      { type: "text", key: "model", label: "Model", placeholder: "claude-sonnet-4-5" },
+      {
+        type: "switch",
+        key: "fallback",
+        label: "Add a `fallback` port",
+        default: true,
+        description: "Where the flow goes if the model returns no usable route."
+      },
+      { type: "credential", key: "credential", label: "API credential", credentialType: "llm_credential" }
+    ]
+  },
+  {
+    name: "@particle-academy/tool_use",
+    aliases: ["tool_use", "@fancy/tool_use"],
+    category: "ai",
+    label: "Tool Use",
+    description: "Hand control to a host-registered tool by name.",
+    icon: "\u{1F6E0}",
+    configSchema: [
+      { type: "text", key: "tool", label: "Tool name", placeholder: "search_index", required: true },
+      { type: "expression", key: "args", label: "Arguments", example: "{{ { query: $json.q } }}" }
+    ]
+  },
+  {
+    name: "@particle-academy/embed_search",
+    outputShape: [
+      { path: "query", type: "string" },
+      { path: "matches", type: "array", description: "Ranked results from the vector store." }
+    ],
+    aliases: ["embed_search", "@fancy/embed_search"],
+    category: "ai",
+    label: "Embed & Search",
+    description: "Embed a query and search a vector store.",
+    icon: "\u273A",
+    configSchema: [
+      { type: "expression", key: "query", label: "Query", required: true, example: "{{ $json.question }}" },
+      { type: "number", key: "topK", label: "Top K", default: 5, min: 1, max: 50 },
+      { type: "credential", key: "vectorStore", label: "Vector store", credentialType: "vector_store" }
+    ]
+  },
+  // ───────────── IO ─────────────
+  {
+    name: "@particle-academy/api_request",
+    // HttpClient::send() -> array{status:int,headers:array,body:mixed}
+    outputShape: [
+      { path: "status", type: "number", description: "HTTP status code." },
+      { path: "headers", type: "object" },
+      { path: "body", type: "unknown", description: "Decoded JSON when the response is JSON, otherwise the raw body." }
+    ],
+    aliases: ["api_request", "@fancy/api_request"],
+    category: "io",
+    label: "API Request",
+    description: "HTTP request to any URL.",
+    icon: "\u2194",
+    configSchema: [
+      ...HTTP_METHODS,
+      { type: "text", key: "url", label: "URL", placeholder: "https://api.example.com/...", required: true },
+      {
+        type: "keyvalue",
+        key: "headers",
+        label: "Headers",
+        keyLabel: "Header",
+        valueLabel: "Value",
+        keyPlaceholder: "content-type",
+        valuePlaceholder: "application/json",
+        addLabel: "Add header",
+        default: { "content-type": "application/json" }
+      },
+      { type: "json", key: "body", label: "Body" },
+      { type: "credential", key: "auth", label: "Auth", credentialType: "api_credential" }
+    ]
+  },
+  {
+    name: "@particle-academy/webhook_out",
+    outputShape: [
+      { path: "sent", type: "boolean", description: "True once the request was made." },
+      { path: "status", type: "number", description: "HTTP status, when the transport reported one." },
+      { path: "response", type: "unknown", description: "The response body, when there was one." }
+    ],
+    aliases: ["webhook_out", "@fancy/webhook_out"],
+    category: "io",
+    label: "Send Webhook",
+    description: "POST a payload to a configured URL.",
+    icon: "\u2197",
+    configSchema: [
+      { type: "text", key: "url", label: "URL", required: true },
+      {
+        type: "keyvalue",
+        key: "headers",
+        label: "Headers",
+        keyLabel: "Header",
+        valueLabel: "Value",
+        addLabel: "Add header"
+      },
+      { type: "expression", key: "payload", label: "Payload", required: true, example: "{{ $json }}" }
+    ]
+  },
+  // ───────────── Human ─────────────
+  {
+    name: "@particle-academy/human_approval",
+    // returns its input on approved/denied
+    emits: "input",
+    aliases: ["human_approval", "@fancy/human_approval"],
+    pausesForHuman: "approval",
+    category: "human",
+    label: "Human Approval",
+    description: "Pause until a human approves or denies.",
+    icon: "\u2713",
+    inputs: [{ id: "in" }],
+    outputs: [{ id: "approved", label: "approved" }, { id: "denied", label: "denied" }],
+    configSchema: [
+      { type: "text", key: "title", label: "Approval title", default: "Approve action" },
+      { type: "textarea", key: "description", label: "Description for approver", rows: 3 },
+      { type: "credential", key: "channel", label: "Notify channel", credentialType: "notify_channel" }
+    ]
+  },
+  {
+    name: "@particle-academy/notify",
+    outputShape: [
+      { path: "sent", type: "boolean", description: "True once the message was handed to the channel." },
+      { path: "channel", type: "string", description: "The channel it went to." },
+      { path: "to", type: "string", description: "The recipient." },
+      { path: "message", type: "string", description: "The rendered message." }
+    ],
+    aliases: ["notify", "@fancy/notify"],
+    category: "human",
+    label: "Notify",
+    description: "Send a message via Slack / email / SMS / etc.",
+    icon: "\u{1F514}",
+    configSchema: [
+      {
+        type: "select",
+        key: "channel",
+        label: "Channel",
+        default: "slack",
+        options: [
+          { value: "slack", label: "Slack" },
+          { value: "email", label: "Email" },
+          { value: "sms", label: "SMS" },
+          { value: "discord", label: "Discord" }
+        ]
+      },
+      { type: "text", key: "to", label: "To", required: true },
+      { type: "expression", key: "message", label: "Message", required: true, example: "{{ $json.summary }}" }
+    ]
+  },
+  // ───────────── Output ─────────────
+  {
+    name: "@particle-academy/output",
+    // returns its input unchanged
+    emits: "input",
+    aliases: ["output", "@fancy/output"],
+    category: "output",
+    label: "Output",
+    description: "Terminal node \u2014 captures the workflow's result.",
+    icon: "\u25CF",
+    inputs: [{ id: "in" }],
+    outputs: []
+  },
+  {
+    name: "@particle-academy/log",
+    outputShape: [
+      { path: "logged", type: "string", description: "The message that was written." },
+      { path: "level", type: "string", description: "The level it was written at." }
+    ],
+    aliases: ["log", "@fancy/log"],
+    category: "output",
+    label: "Log",
+    description: "Send to the run feed.",
+    icon: "\u2261",
+    inputs: [{ id: "in" }],
+    outputs: [],
+    configSchema: [
+      {
+        type: "select",
+        key: "level",
+        label: "Level",
+        default: "info",
+        options: [{ value: "info", label: "info" }, { value: "warn", label: "warn" }, { value: "error", label: "error" }]
+      },
+      { type: "expression", key: "message", label: "Message", required: true, example: "{{ $json }}" }
+    ]
+  },
+  {
+    // Swimlane — a portless, resizable container. Child nodes are parented into
+    // it; it never runs (the runtime skips the `layout` category). Uses its own
+    // renderer (LaneNode) instead of the default card.
+    name: "@particle-academy/lane",
+    aliases: ["lane", "@fancy/lane"],
+    category: "layout",
+    label: "Lane",
+    description: "A resizable swimlane \u2014 drop nodes into it to group them.",
+    icon: "\u25A4",
+    inputs: [],
+    outputs: [],
+    configSchema: [
+      { type: "text", key: "title", label: "Title", default: "Lane" },
+      {
+        type: "select",
+        key: "orientation",
+        label: "Orientation",
+        default: "horizontal",
+        options: [{ value: "horizontal", label: "Row" }, { value: "vertical", label: "Column" }]
+      }
+    ],
+    defaultConfig: { title: "Lane", orientation: "horizontal" },
+    resizable: { minWidth: 160, minHeight: 72 }
+  },
+  {
+    // 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 }
+  },
+  {
+    // 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
+    // rides in the document purely for people, editors, and MCP tools. Uses its
+    // own renderer (NoteNode); double-click on the canvas to edit in place.
+    name: "@particle-academy/note",
+    aliases: ["note", "@fancy/note"],
+    category: "annotation",
+    label: "Note",
+    description: "A sticky note that documents the canvas. Never runs \u2014 editor + agent only.",
+    icon: "\u{1F5D2}",
+    inputs: [],
+    outputs: [],
+    configSchema: [
+      { type: "text", key: "title", label: "Title", placeholder: "Optional heading" },
+      { type: "textarea", key: "text", label: "Note", rows: 5, placeholder: "What does this part of the flow do?" },
+      { type: "select", key: "color", label: "Color", default: "amber", options: [
+        { value: "amber", label: "Amber" },
+        { value: "sky", label: "Sky" },
+        { value: "violet", label: "Violet" },
+        { value: "emerald", label: "Emerald" },
+        { value: "rose", label: "Rose" },
+        { value: "slate", label: "Slate" }
+      ] }
+    ],
+    defaultConfig: { text: "", color: "amber" },
+    resizable: { minWidth: 140, minHeight: 80 }
+  }
+];
+function registerBuiltinKindData() {
+  for (const k of KINDS) registerNodeKind(k);
+}
+var BUILTIN_KIND_DATA = KINDS;
+
+// src/registry/registry.ts
+var kinds = /* @__PURE__ */ new Map();
+var aliases = /* @__PURE__ */ new Map();
+var listeners = /* @__PURE__ */ new Set();
+var overrides = /* @__PURE__ */ new Map();
+var builtinsEnsured = false;
+function ensureBuiltinKinds() {
+  if (builtinsEnsured) return;
+  builtinsEnsured = true;
+  registerBuiltinKindData();
+}
+function registerNodeKind(definition) {
+  ensureBuiltinKinds();
+  kinds.set(definition.name, definition);
+  for (const alias of definition.aliases ?? []) aliases.set(alias, definition.name);
+  notify();
+  return () => {
+    if (kinds.get(definition.name) === definition) {
+      kinds.delete(definition.name);
+      for (const alias of definition.aliases ?? []) {
+        if (aliases.get(alias) === definition.name) aliases.delete(alias);
+      }
+      notify();
+    }
+  };
+}
+function resolveKindId(id) {
+  ensureBuiltinKinds();
+  if (kinds.has(id)) return id;
+  const canonical = aliases.get(id);
+  return canonical && kinds.has(canonical) ? canonical : null;
+}
+function overrideNodeKind(name, patch) {
+  const canonical = resolveKindId(name) ?? name;
+  const previous = overrides.get(canonical);
+  overrides.set(canonical, { ...previous, ...patch });
+  notify();
+  return () => {
+    if (previous) {
+      overrides.set(canonical, previous);
+    } else {
+      overrides.delete(canonical);
+    }
+    notify();
+  };
+}
+function clearNodeKindOverrides() {
+  if (overrides.size === 0) return;
+  overrides.clear();
+  notify();
+}
+function withOverride(kind) {
+  if (!kind) return null;
+  const patch = overrides.get(kind.name);
+  return patch ? { ...kind, ...patch } : kind;
+}
+function getNodeKind(name) {
+  const canonical = resolveKindId(name);
+  return canonical ? withOverride(kinds.get(canonical)) : null;
+}
+function kindIds(kind) {
+  return [kind.name, ...kind.aliases ?? []];
+}
+function listNodeKinds(category) {
+  ensureBuiltinKinds();
+  const all = Array.from(kinds.values()).map(
+    (k) => withOverride(k)
+  );
+  return category ? all.filter((k) => k.category === category) : all;
+}
+function onNodeKindsChanged(listener) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+function notify() {
+  for (const l of listeners) l();
+}
+function defaultConfigFor(kind) {
+  const fromKind = kind.defaultConfig ? { ...kind.defaultConfig } : {};
+  for (const field of kind.configSchema ?? []) {
+    if (fromKind[field.key] !== void 0) continue;
+    if ("default" in field && field.default !== void 0) {
+      fromKind[field.key] = field.default;
+    }
+  }
+  return fromKind;
+}
+function validateConfig(kind, config) {
+  const issues = [];
+  for (const field of kind.configSchema ?? []) {
+    const value = config[field.key];
+    if (field.required && (value === void 0 || value === null || value === "")) {
+      issues.push({ key: field.key, message: `${field.label} is required` });
+      continue;
+    }
+    if (value === void 0 || value === null) continue;
+    const issue = validateField(field, value);
+    if (issue) issues.push({ key: field.key, message: issue });
+  }
+  return issues;
+}
+function validateField(field, value) {
+  switch (field.type) {
+    case "text":
+    case "textarea":
+    case "expression":
+    case "credential":
+      return typeof value === "string" ? null : `${field.label} must be a string`;
+    case "number": {
+      if (typeof value !== "number" || !Number.isFinite(value)) return `${field.label} must be a number`;
+      if (field.min !== void 0 && value < field.min) return `${field.label} must be >= ${field.min}`;
+      if (field.max !== void 0 && value > field.max) return `${field.label} must be <= ${field.max}`;
+      return null;
+    }
+    case "switch":
+      return typeof value === "boolean" ? null : `${field.label} must be a boolean`;
+    case "select": {
+      const allowed = field.options.map((o) => o.value);
+      return allowed.includes(String(value)) ? null : `${field.label} must be one of ${allowed.join(", ")}`;
+    }
+    case "json":
+      return null;
+    // permissive — just JSON-shaped
+    case "repeater": {
+      if (!Array.isArray(value)) return `${field.label} must be a list`;
+      if (field.minItems !== void 0 && value.length < field.minItems) {
+        return `${field.label} needs at least ${field.minItems}`;
+      }
+      if (field.maxItems !== void 0 && value.length > field.maxItems) {
+        return `${field.label} allows at most ${field.maxItems}`;
+      }
+      for (let i = 0; i < value.length; i++) {
+        const row = value[i];
+        if (!row || typeof row !== "object" || Array.isArray(row)) {
+          return `${field.label} item ${i + 1} must be an object`;
+        }
+        for (const sub of field.fields) {
+          const cell = row[sub.key];
+          if (sub.required && (cell === void 0 || cell === null || cell === "")) {
+            return `${field.label} item ${i + 1}: ${sub.label} is required`;
+          }
+          if (cell === void 0 || cell === null) continue;
+          const issue = validateField(sub, cell);
+          if (issue) return `${field.label} item ${i + 1}: ${issue}`;
+        }
+      }
+      return null;
+    }
+    case "keyvalue": {
+      if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return `${field.label} must be a key/value map`;
+      }
+      const allowed = field.valueOptions?.map((o) => o.value);
+      for (const [k, v] of Object.entries(value)) {
+        if (typeof v !== "string") return `${field.label}: "${k}" must be a string`;
+        if (allowed && !allowed.includes(v)) {
+          return `${field.label}: "${k}" must be one of ${allowed.join(", ")}`;
+        }
+      }
+      return null;
+    }
+    case "document":
+      return null;
+    // opaque to fancy-flow — the host's editor owns its shape
+    default:
+      return null;
+  }
+}
+function categoryAccent(category) {
+  switch (category) {
+    case "trigger":
+      return "#10b981";
+    case "logic":
+      return "#f59e0b";
+    case "data":
+      return "#0ea5e9";
+    case "ai":
+      return "#8b5cf6";
+    case "io":
+      return "#3b82f6";
+    case "human":
+      return "#ec4899";
+    case "output":
+      return "#a855f7";
+    case "layout":
+      return "#64748b";
+    case "annotation":
+      return "#eab308";
+    default:
+      return "#71717a";
+  }
+}
+
+// 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 wake of [...this.waiters]) wake();
+  }
+  /**
+   * 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 timer;
+      const finish = (result) => {
+        if (settled) return;
+        settled = true;
+        this.waiters.delete(check);
+        if (timer) clearTimeout(timer);
+        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) {
+        timer = setTimeout(() => {
+          const text3 = this.text;
+          this.text = "";
+          finish({ status: "timeout", text: text3 });
+        }, options.timeoutMs);
+        timer.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";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+function resolveWorkflowProps(declared, passed) {
+  const inputs = declared ?? [];
+  const given = passed ?? {};
+  const byName = new Map(inputs.map((input) => [input.name, input]));
+  for (const name of Object.keys(given)) {
+    if (!byName.has(name)) {
+      const known = inputs.map((input) => input.name);
+      const suffix = known.length === 0 ? "this workflow declares no inputs" : `known inputs: ${known.join(", ")}`;
+      return {
+        ok: false,
+        code: "unknown_input",
+        error: `Unknown workflow input "${name}" \u2014 ${suffix}.`
+      };
+    }
+  }
+  const resolved = {};
+  for (const input of inputs) {
+    const supplied = Object.prototype.hasOwnProperty.call(given, input.name);
+    const hasDefault = Object.prototype.hasOwnProperty.call(input, "default");
+    if (!supplied) {
+      if (hasDefault) {
+        resolved[input.name] = input.default;
+        continue;
+      }
+      if (input.required) {
+        return {
+          ok: false,
+          code: "missing_required",
+          error: `Missing required workflow input "${input.name}"${input.type ? ` (${input.type})` : ""}.`
+        };
+      }
+      continue;
+    }
+    const value = given[input.name];
+    if (input.type !== void 0) {
+      const actual = typeOf(value);
+      if (actual !== input.type) {
+        return {
+          ok: false,
+          code: "type_mismatch",
+          error: `Workflow input "${input.name}" expects ${input.type}, got ${actual}.`
+        };
+      }
+    }
+    resolved[input.name] = value;
+  }
+  return { ok: true, props: resolved };
+}
+
+// src/runtime/run-flow.ts
+async function runFlow(graph, executors, onEvent = () => {
+}, options = {}) {
+  const { signal, initialInputs = {}, timeoutMs, depth = 0, resumeOutputs = {}, entryNodes } = options;
+  const run = options.run === void 0 ? void 0 : RunIdentity.from(options.run);
+  const outputs = {};
+  const portValues = /* @__PURE__ */ new Map();
+  const completed = /* @__PURE__ */ new Set();
+  const errors = [];
+  const order = topoSort(graph);
+  if (order === null) {
+    const msg = "Cycle detected in flow graph \u2014 aborting.";
+    onEvent({ type: "run-error", error: msg });
+    return { ok: false, outputs, error: msg };
+  }
+  const propsCheck = resolveWorkflowProps(graph.inputs, options.props);
+  if (!propsCheck.ok) {
+    onEvent({ type: "run-error", error: propsCheck.error });
+    return { ok: false, outputs, error: propsCheck.error };
+  }
+  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 timer = timeoutMs ? setTimeout(() => errors.push(`Run timed out after ${timeoutMs}ms`), timeoutMs) : null;
+  onEvent({ type: "run-start" });
+  try {
+    for (const node of order) {
+      if (signal?.aborted) throw new Error("aborted");
+      if (errors.length) break;
+      if (Object.prototype.hasOwnProperty.call(resumeOutputs, node.id)) {
+        const stored = resumeOutputs[node.id];
+        outputs[node.id] = stored;
+        const activated = activatedPorts(node, stored);
+        for (const portId of activated.ports) {
+          portValues.set(`${node.id}:${portId}`, activated.value);
+          onEvent({ type: "node-output", nodeId: node.id, portId, value: activated.value });
+        }
+        completed.add(node.id);
+        onEvent({ type: "node-status", nodeId: node.id, status: "done", text: "resumed" });
+        continue;
+      }
+      const incoming = incomingByNode.get(node.id) ?? [];
+      if (incoming.length === 0 && entryNodes !== void 0 && !entryNodes.includes(node.id)) {
+        onEvent({ type: "node-status", nodeId: node.id, status: "idle", text: "skipped" });
+        continue;
+      }
+      if (incoming.length > 0) {
+        const anyActive = incoming.some((e) => portValues.has(`${e.source}:${e.sourceHandle ?? "out"}`));
+        if (!anyActive) {
+          onEvent({ type: "node-status", nodeId: node.id, status: "idle", text: "skipped" });
+          continue;
+        }
+      }
+      const visualKind = getNodeKind(node.type ?? "");
+      const isLayout = visualKind?.category === "layout";
+      const isAnnotation = node.type === "note" || visualKind?.category === "annotation";
+      if (isLayout || isAnnotation) {
+        onEvent({
+          type: "node-status",
+          nodeId: node.id,
+          status: "idle",
+          text: isLayout ? "lane" : "annotation"
+        });
+        continue;
+      }
+      onEvent({ type: "node-status", nodeId: node.id, status: "running" });
+      announce(onEvent, node, "start");
+      const inputs = collectInputs(node, incoming, portValues, initialInputs, props, declaresProps);
+      const exec = pickExecutor(executors, node);
+      if (!exec) {
+        const tried = executorLookupIds(node);
+        const msg = `No executor registered for kind=${node.type} \u2014 tried ${tried.map((id) => `"${id}"`).join(", ")}. Key your registry by one of those.`;
+        errors.push(msg);
+        onEvent({ type: "node-status", nodeId: node.id, status: "error", text: msg });
+        onEvent({ type: "log", nodeId: node.id, level: "error", message: msg });
+        break;
+      }
+      try {
+        const result = await Promise.resolve(
+          exec({
+            node,
+            inputs,
+            abort: (reason) => {
+              throw new Error(reason ?? "aborted");
+            },
+            emit: onEvent,
+            executors,
+            depth,
+            run,
+            terminal: terminalAccessorFor(node)
+          })
+        );
+        outputs[node.id] = result;
+        const activated = activatedPorts(node, result);
+        for (const portId of activated.ports) {
+          portValues.set(`${node.id}:${portId}`, activated.value);
+          onEvent({ type: "node-output", nodeId: node.id, portId, value: activated.value });
+        }
+        completed.add(node.id);
+        onEvent({ type: "node-status", nodeId: node.id, status: "done" });
+        announce(onEvent, node, "end");
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        errors.push(msg);
+        onEvent({ type: "node-status", nodeId: node.id, status: "error", text: msg });
+        onEvent({ type: "log", nodeId: node.id, level: "error", message: msg });
+        break;
+      }
+    }
+  } finally {
+    if (timer) clearTimeout(timer);
+    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 });
+  return ok ? { ok, outputs } : { ok, outputs, error: errors[0] };
+}
+function indexIncoming(edges) {
+  const map = /* @__PURE__ */ new Map();
+  for (const e of edges) {
+    const list = map.get(e.target) ?? [];
+    list.push(e);
+    map.set(e.target, list);
+  }
+  return map;
+}
+function topoSort(graph) {
+  const inDegree = /* @__PURE__ */ new Map();
+  for (const n of graph.nodes) inDegree.set(n.id, 0);
+  for (const e of graph.edges) inDegree.set(e.target, (inDegree.get(e.target) ?? 0) + 1);
+  const queue = [];
+  for (const [id, d] of inDegree) if (d === 0) queue.push(id);
+  const ordered = [];
+  while (queue.length) {
+    const id = queue.shift();
+    ordered.push(id);
+    for (const e of graph.edges) {
+      if (e.source !== id) continue;
+      const next = (inDegree.get(e.target) ?? 0) - 1;
+      inDegree.set(e.target, next);
+      if (next === 0) queue.push(e.target);
+    }
+  }
+  if (ordered.length !== graph.nodes.length) return null;
+  const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+  return ordered.map((id) => byId.get(id)).filter(Boolean);
+}
+function collectInputs(node, incoming, portValues, initial, props, declaresProps) {
+  const inputs = { ...initial[node.id] ?? {} };
+  if (incoming.length === 0) {
+    for (const [name, value] of Object.entries(props)) {
+      if (!(name in inputs)) inputs[name] = value;
+    }
+  }
+  for (const e of incoming) {
+    const portId = e.targetHandle ?? "in";
+    const key = `${e.source}:${e.sourceHandle ?? "out"}`;
+    if (!portValues.has(key)) continue;
+    inputs[portId] = portValues.get(key);
+    if (e.targetHandle == null && !(e.source in inputs)) {
+      inputs[e.source] = portValues.get(key);
+    }
+  }
+  if (declaresProps) inputs.$props = props;
+  return inputs;
+}
+function executorLookupIds(node) {
+  const ids = [node.id];
+  if (node.type) ids.push(node.type);
+  const typeKind = node.type ? getNodeKind(node.type) : null;
+  if (typeKind) {
+    for (const id of kindIds(typeKind)) ids.push(id);
+  } else {
+    const declared = node.data?.kind;
+    const kindName = typeof declared === "string" && declared !== "" ? declared : null;
+    if (kindName) {
+      ids.push(kindName);
+      const dataKind = getNodeKind(kindName);
+      if (dataKind) {
+        for (const id of kindIds(dataKind)) ids.push(id);
+      }
+    }
+  }
+  ids.push("*");
+  return [...new Set(ids)];
+}
+function pickExecutor(executors, node) {
+  for (const id of executorLookupIds(node)) {
+    if (executors[id]) return executors[id];
+  }
+  return getNodeKind(node.type ?? "")?.executor;
+}
+function activatedPorts(node, result) {
+  if (result && typeof result === "object") {
+    const r = result;
+    if (typeof r.__port === "string") {
+      return { ports: [r.__port], value: r.value };
+    }
+    if (typeof r.branch === "string") {
+      return { ports: [r.branch], value: Object.prototype.hasOwnProperty.call(r, "value") ? r.value : r };
+    }
+  }
+  const kind = getNodeKind(node.data?.kind ?? node.type ?? "") ?? void 0;
+  const declared = resolveNodePorts(node, kind).outputs?.map((p) => p.id);
+  return { ports: declared?.length ? declared : ["out"], value: result };
+}
+function announce(onEvent, node, phase) {
+  const data = node.data;
+  const raw = phase === "start" ? data?.startingMsg : data?.stoppingMsg;
+  if (typeof raw !== "string") return;
+  const message = raw.trim();
+  if (message === "") return;
+  onEvent({ type: "node-message", nodeId: node.id, phase, message });
+}
+
+export { BUILTIN_KIND_DATA, DEFAULT_MAX_DEPTH, RunIdentity, UnresolvedPathError, categoryAccent, clearNodeKindOverrides, declaredRoutes, defaultConfigFor, ensureBuiltinKinds, escapeSegment, evaluateConfig, evaluateExpression, getNodeKind, humanInputFields, kindIds, listNodeKinds, llmRouterExecutor, nodeConfig, onNodeKindsChanged, overrideNodeKind, registerNodeKind, resolveFallbackPort, resolveKindId, resolveNodePorts, resolvePath, resolvePortSpec, runFlow, subflowExecutor, subflowMode, subflowPorts, text, truthy, tryResolvePath, validateConfig };
+//# sourceMappingURL=chunk-27RZJAE2.js.map
+//# sourceMappingURL=chunk-27RZJAE2.js.map