@particle-academy/fancy-flow 0.45.0 → 0.47.0

package/dist/screens.cjs

@@ -1000,7 +1000,7 @@ function defaultTouchable() {
   return navigator.maxTouchPoints || "ontouchstart" in this;
 }
 function drag_default() {
-  var filter2 = defaultFilter, container = defaultContainer, subject = defaultSubject, touchable = defaultTouchable, gestures = {}, listeners = dispatch_default("start", "drag", "end"), active = 0, mousedownx, mousedowny, mousemoving, touchending, clickDistance2 = 0;
+  var filter2 = defaultFilter, container = defaultContainer, subject = defaultSubject, touchable = defaultTouchable, gestures = {}, listeners2 = dispatch_default("start", "drag", "end"), active = 0, mousedownx, mousedowny, mousemoving, touchending, clickDistance2 = 0;
   function drag(selection2) {
     selection2.on("mousedown.drag", mousedowned).filter(touchable).on("touchstart.drag", touchstarted).on("touchmove.drag", touchmoved, nonpassive).on("touchend.drag touchcancel.drag", touchended).style("touch-action", "none").style("-webkit-tap-highlight-color", "rgba(0,0,0,0)");
   }
@@ -1063,7 +1063,7 @@ function drag_default() {
     }
   }
   function beforestart(that, container2, event, d, identifier, touch) {
-    var dispatch2 = listeners.copy(), p = pointer_default(touch || event, container2), dx, dy, s;
+    var dispatch2 = listeners2.copy(), p = pointer_default(touch || event, container2), dx, dy, s;
     if ((s = subject.call(that, new DragEvent("beforestart", {
       sourceEvent: event,
       target: drag,
@@ -1122,8 +1122,8 @@ function drag_default() {
     return arguments.length ? (touchable = typeof _ === "function" ? _ : constant_default2(!!_), drag) : touchable;
   };
   drag.on = function() {
-    var value = listeners.on.apply(listeners, arguments);
-    return value === listeners ? drag : value;
+    var value = listeners2.on.apply(listeners2, arguments);
+    return value === listeners2 ? drag : value;
   };
   drag.clickDistance = function(_) {
     return arguments.length ? (clickDistance2 = (_ = +_) * _, drag) : Math.sqrt(clickDistance2);
@@ -2677,7 +2677,7 @@ function defaultConstrain(transform2, extent, translateExtent) {
   );
 }
 function zoom_default2() {
-  var filter2 = defaultFilter2, extent = defaultExtent, constrain = defaultConstrain, wheelDelta2 = defaultWheelDelta, touchable = defaultTouchable2, scaleExtent = [0, Infinity], translateExtent = [[-Infinity, -Infinity], [Infinity, Infinity]], duration = 250, interpolate = zoom_default, listeners = dispatch_default("start", "zoom", "end"), touchstarting, touchfirst, touchending, touchDelay = 500, wheelDelay = 150, clickDistance2 = 0, tapDistance = 10;
+  var filter2 = defaultFilter2, extent = defaultExtent, constrain = defaultConstrain, wheelDelta2 = defaultWheelDelta, touchable = defaultTouchable2, scaleExtent = [0, Infinity], translateExtent = [[-Infinity, -Infinity], [Infinity, Infinity]], duration = 250, interpolate = zoom_default, listeners2 = dispatch_default("start", "zoom", "end"), touchstarting, touchfirst, touchending, touchDelay = 500, wheelDelay = 150, clickDistance2 = 0, tapDistance = 10;
   function zoom(selection2) {
     selection2.property("__zoom", defaultTransform).on("wheel.zoom", wheeled, { passive: false }).on("mousedown.zoom", mousedowned).on("dblclick.zoom", dblclicked).filter(touchable).on("touchstart.zoom", touchstarted).on("touchmove.zoom", touchmoved).on("touchend.zoom touchcancel.zoom", touchended).style("-webkit-tap-highlight-color", "rgba(0,0,0,0)");
   }
@@ -2789,14 +2789,14 @@ function zoom_default2() {
     },
     emit: function(type) {
       var d = select_default2(this.that).datum();
-      listeners.call(
+      listeners2.call(
         type,
         this.that,
         new ZoomEvent(type, {
           sourceEvent: this.sourceEvent,
           target: zoom,
           transform: this.that.__zoom,
-          dispatch: listeners
+          dispatch: listeners2
         }),
         d
       );
@@ -2946,8 +2946,8 @@ function zoom_default2() {
     return arguments.length ? (interpolate = _, zoom) : interpolate;
   };
   zoom.on = function() {
-    var value = listeners.on.apply(listeners, arguments);
-    return value === listeners ? zoom : value;
+    var value = listeners2.on.apply(listeners2, arguments);
+    return value === listeners2 ? zoom : value;
   };
   zoom.clickDistance = function(_) {
     return arguments.length ? (clickDistance2 = (_ = +_) * _, zoom) : Math.sqrt(clickDistance2);
@@ -5656,20 +5656,20 @@ var use_sync_external_store_with_selector_default = { useSyncExternalStoreWithSe
 // node_modules/zustand/esm/vanilla.mjs
 var createStoreImpl = (createState) => {
   let state;
-  const listeners = /* @__PURE__ */ new Set();
+  const listeners2 = /* @__PURE__ */ new Set();
   const setState = (partial, replace) => {
     const nextState = typeof partial === "function" ? partial(state) : partial;
     if (!Object.is(nextState, state)) {
       const previousState = state;
       state = (replace != null ? replace : typeof nextState !== "object" || nextState === null) ? nextState : Object.assign({}, state, nextState);
-      listeners.forEach((listener) => listener(state, previousState));
+      listeners2.forEach((listener) => listener(state, previousState));
     }
   };
   const getState = () => state;
   const getInitialState2 = () => initialState;
   const subscribe = (listener) => {
-    listeners.add(listener);
-    return () => listeners.delete(listener);
+    listeners2.add(listener);
+    return () => listeners2.delete(listener);
   };
   const destroy = () => {
     if ((undefined ? undefined.MODE : void 0) !== "production") {
@@ -5677,7 +5677,7 @@ var createStoreImpl = (createState) => {
         "[DEPRECATED] The `destroy` method will be unsupported in a future version. Instead use unsubscribe function returned by subscribe. Everything will be garbage-collected if store is garbage-collected."
       );
     }
-    listeners.clear();
+    listeners2.clear();
   };
   const api = { setState, getState, getInitialState: getInitialState2, subscribe, destroy };
   const initialState = state = createState(setState, getState, api);
@@ -9196,12 +9196,1338 @@ function SubgraphNodeInner(props) {
   ] }) });
 }
 var SubgraphNode = ReactExports.memo(SubgraphNodeInner);
+function RichInputPreview({ config }) {
+  const title = typeof config.title === "string" && config.title.trim() !== "" ? config.title : "Untitled step";
+  config.document;
+  {
+    return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "ff-rich-preview", children: [
+      /* @__PURE__ */ jsxRuntime.jsx("span", { className: "ff-rich-preview__title", children: title }),
+      /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "ff-rich-preview__unavailable", children: [
+        "Add ",
+        /* @__PURE__ */ jsxRuntime.jsx("code", { children: "@particle-academy/fancy-cms-ui" }),
+        " +",
+        " ",
+        /* @__PURE__ */ jsxRuntime.jsx("code", { children: "@particle-academy/react-fancy" }),
+        ", then",
+        " ",
+        /* @__PURE__ */ jsxRuntime.jsx("code", { children: 'import "@particle-academy/fancy-flow/rich-input"' }),
+        "."
+      ] })
+    ] });
+  }
+}
+
+// src/registry/capabilities.ts
+var llmClient = null;
+function getLlmClient() {
+  return llmClient;
+}
+function isResolutionFailure(value) {
+  return typeof value === "object" && value !== null && "reason" in value && value.reason !== void 0;
+}
+var workflowResolver = null;
+function getWorkflowResolver() {
+  return workflowResolver;
+}
+
+// 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();
+  {
+    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, now2 = /* @__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 now2 === "string" ? instant(now2) : now2.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/runtime/run-flow.ts
+async function runFlow(graph, executors, onEvent = () => {
+}, options = {}) {
+  const { signal, initialInputs = {}, timeoutMs, depth = 0, resumeOutputs = {} } = 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 incomingByNode = indexIncoming(graph.edges);
+  const timer2 = 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) {
+        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" });
+      const inputs = collectInputs(node, incoming, portValues, initialInputs);
+      const exec = pickExecutor(executors, node);
+      if (!exec) {
+        const msg = `No executor registered for kind=${node.type}`;
+        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,
+            depth,
+            run
+          })
+        );
+        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" });
+      } 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 (timer2) clearTimeout(timer2);
+  }
+  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 [id2, d] of inDegree) if (d === 0) queue.push(id2);
+  const ordered = [];
+  while (queue.length) {
+    const id2 = queue.shift();
+    ordered.push(id2);
+    for (const e of graph.edges) {
+      if (e.source !== id2) 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((id2) => byId.get(id2)).filter(Boolean);
+}
+function collectInputs(node, incoming, portValues, initial) {
+  const inputs = { ...initial[node.id] ?? {} };
+  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);
+  }
+  return inputs;
+}
+function pickExecutor(executors, node) {
+  if (executors[node.id]) return executors[node.id];
+  if (node.type && executors[node.type]) return executors[node.type];
+  const kind = node.type ? getNodeKind(node.type) : null;
+  if (kind) {
+    for (const id2 of kindIds(kind)) {
+      if (executors[id2]) return executors[id2];
+    }
+  }
+  return executors["*"];
+}
+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: 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 };
+}
+
+// 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();
+  {
+    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,
+    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/registry/builtin.ts
+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(([id2, matches]) => ({
+    id: id2,
+    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 id2 = route?.port;
+      if (typeof id2 !== "string" || id2.trim() === "" || seen.has(id2)) continue;
+      seen.add(id2);
+      ports.push({ id: id2, label: id2 });
+    }
+  }
+  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",
+    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",
+    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.
+    outputShape: (config) => (config.fields ?? []).filter((f) => typeof f.key === "string" && f.key !== "").map((f) => ({ path: f.key, type: "string", 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",
+            options: [
+              { value: "text", label: "Text" },
+              { value: "textarea", label: "Long text" },
+              { value: "number", label: "Number" },
+              { value: "select", label: "Select" },
+              { value: "switch", label: "Switch" }
+            ]
+          },
+          { 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" }
+    ],
+    // Preview the authored page inside a FauxClient frame, so the canvas shows
+    // what the person hitting this step will actually see.
+    renderBody: (ctx) => ReactExports.createElement(RichInputPreview, { config: ctx.config ?? {} })
+  },
+  {
+    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",
+    aliases: ["branch", "@fancy/branch"],
+    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",
+    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"],
+    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",
+    aliases: ["merge", "@fancy/merge"],
+    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",
+    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",
+    aliases: ["transform", "@fancy/transform"],
+    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",
+    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",
+    // 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",
+    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",
+    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",
+    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",
+    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",
+    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 },
+    component: LaneNode
+  },
+  {
+    // 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 },
+    component: NoteNode
+  }
+];
+function registerBuiltinKinds() {
+  for (const k of KINDS) registerNodeKind(k);
+}
 
 // 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;
+  registerBuiltinKinds();
+}
+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(id2) {
+  ensureBuiltinKinds();
   if (kinds.has(id2)) return id2;
   const canonical = aliases.get(id2);
   return canonical && kinds.has(canonical) ? canonical : null;
@@ -9219,11 +10545,15 @@ 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 notify() {
+  for (const l of listeners) l();
+}
 function categoryAccent(category) {
   switch (category) {
     case "trigger":
@@ -9248,6 +10578,25 @@ function categoryAccent(category) {
       return "#71717a";
   }
 }
+function LaneNodeInner(props) {
+  const data = props.data;
+  const config = data.config ?? {};
+  const title = config.title ?? data.label ?? "Lane";
+  const orientation = config.orientation ?? "horizontal";
+  const accent = config.color ?? data.color ?? categoryAccent("layout");
+  return /* @__PURE__ */ jsxRuntime.jsxs(
+    "div",
+    {
+      className: ["ff-lane", `ff-lane--${orientation}`, props.selected ? "ff-lane--selected" : ""].filter(Boolean).join(" "),
+      style: { borderColor: props.selected ? accent : void 0 },
+      children: [
+        /* @__PURE__ */ jsxRuntime.jsx(NodeResizer, { isVisible: props.selected ?? false, color: accent, minWidth: 160, minHeight: 72 }),
+        /* @__PURE__ */ jsxRuntime.jsx("div", { className: "ff-lane__header", style: { background: accent }, children: /* @__PURE__ */ jsxRuntime.jsx("span", { className: "ff-lane__title", children: title }) })
+      ]
+    }
+  );
+}
+var LaneNode = ReactExports.memo(LaneNodeInner);
 
 // src/components/nodes/index.ts
 var defaultNodeTypes = {
@@ -9259,29 +10608,6 @@ var defaultNodeTypes = {
   subgraph: SubgraphNode
 };
 
-// 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/registry/connection.ts
 var ANY_PORT_TYPE = "any";
 var defaultPortCompatibility = (source, target) => {
@@ -9750,7 +11076,9 @@ function FlowViewer({
       return {
         node,
         index: index2,
-        title: kind?.label ?? node.data?.label ?? node.data?.kind ?? node.id,
+        // The node's own label is the name the AUTHOR gave THIS node ("Summarize");
+        // the kind label is the generic type name ("LLM Call"). Specific wins.
+        title: node.data?.label ?? kind?.label ?? node.data?.kind ?? node.id,
         description: kind?.description ?? null,
         accent: kind?.accent ?? categoryAccent(kind?.category ?? "custom"),
         status: statuses?.[node.id] ?? null