@particle-academy/fancy-flow 0.77.1 → 0.79.0

package/dist/screens.d.cts

@@ -1,6 +1,6 @@
-export { F as FlowNodeStatus, a as FlowViewer, b as FlowViewerClassNames, c as FlowViewerProps } from './FlowViewer-Ak8kbY0e.cjs';
+export { F as FlowNodeStatus, a as FlowViewer, b as FlowViewerClassNames, c as FlowViewerProps } from './FlowViewer-BqYQl2vS.cjs';
 import 'react';
-import './types-B-Syk9-M.cjs';
+import './types-E48Dpesq.cjs';
 import '@xyflow/react';
 
 /**

package/dist/screens.d.ts

@@ -1,6 +1,6 @@
-export { F as FlowNodeStatus, a as FlowViewer, b as FlowViewerClassNames, c as FlowViewerProps } from './FlowViewer-BAV29Zpi.js';
+export { F as FlowNodeStatus, a as FlowViewer, b as FlowViewerClassNames, c as FlowViewerProps } from './FlowViewer-_Fq8AX9V.js';
 import 'react';
-import './types-B-Syk9-M.js';
+import './types-E48Dpesq.js';
 import '@xyflow/react';
 
 /**

package/dist/screens.js

@@ -1,9 +1,9 @@
-import { FlowViewer } from './chunk-EGXA4SYJ.js';
-export { FlowViewer } from './chunk-EGXA4SYJ.js';
-import './chunk-T6WIIGSK.js';
+import { FlowViewer } from './chunk-J66LOLJR.js';
+export { FlowViewer } from './chunk-J66LOLJR.js';
+import './chunk-I5EPWHNM.js';
 import './chunk-F5RPRB7A.js';
 import './chunk-OWENS2H5.js';
-import './chunk-EEIWAIXW.js';
+import './chunk-OZHBAXMA.js';
 import './chunk-2QXKDLGT.js';
 import { registerSchemaComponents } from '@particle-academy/fancy-screens';
 

package/dist/terminal/fancy-term-host.d.cts

@@ -1,4 +1,4 @@
-import { T as TerminalHost } from '../types-B-Syk9-M.cjs';
+import { T as TerminalHost } from '../types-E48Dpesq.cjs';
 import '@xyflow/react';
 
 /**

package/dist/terminal/fancy-term-host.d.ts

@@ -1,4 +1,4 @@
-import { T as TerminalHost } from '../types-B-Syk9-M.js';
+import { T as TerminalHost } from '../types-E48Dpesq.js';
 import '@xyflow/react';
 
 /**

package/dist/{types-BdkXxjFh.d.cts → types-B1jftRa9.d.cts}

@@ -1,5 +1,5 @@
 import { ReactNode, ComponentType } from 'react';
-import { F as FlowGraph, a as FlowNode, P as PortDescriptor, N as NodeExecutor } from './types-B-Syk9-M.cjs';
+import { F as FlowGraph, a as FlowNode, P as PortDescriptor, N as NodeExecutor } from './types-E48Dpesq.cjs';
 import { NodeProps } from '@xyflow/react';
 import { P as PauseAwaiting } from './pause-9iT4tCEV.cjs';
 

package/dist/{types-CbekKMMO.d.ts → types-D5SBBpbe.d.ts}

@@ -1,5 +1,5 @@
 import { ReactNode, ComponentType } from 'react';
-import { F as FlowGraph, a as FlowNode, P as PortDescriptor, N as NodeExecutor } from './types-B-Syk9-M.js';
+import { F as FlowGraph, a as FlowNode, P as PortDescriptor, N as NodeExecutor } from './types-E48Dpesq.js';
 import { NodeProps } from '@xyflow/react';
 import { P as PauseAwaiting } from './pause-9iT4tCEV.js';
 

package/dist/{types-B-Syk9-M.d.ts → types-E48Dpesq.d.cts}

@@ -538,6 +538,26 @@ type NodeExecutor<TIn = Record<string, unknown>, TOut = unknown> = (ctx: {
      * invent a key. See `RunIdentity`.
      */
     run?: RunIdentity;
+    /**
+     * The graph this node belongs to.
+     *
+     * A STRUCTURAL executor needs it: `for_each`'s `item` port fans out over a
+     * lane derived from the graph — the nodes reachable from `item`, stopping
+     * at anything also reachable from `done` — and that lane cannot be computed
+     * from `node` and `inputs` alone.
+     *
+     * Without it the `item` port was accepted by the schema, drawn by the
+     * editor, and silently ignored at run time on this runtime: downstream
+     * nodes ran ONCE against the whole collection instead of once per item,
+     * with no error. The PHP twin derives the same lane from `$ctx->graph` and
+     * has since 0.6; parity was measured against a reference graph where the
+     * two disagreed.
+     *
+     * Optional, because a host may construct a context by hand. An executor
+     * that needs it must degrade rather than throw — `for_each` falls back to
+     * publishing the collection, which is what it did everywhere before.
+     */
+    graph?: FlowGraph;
     /**
      * The terminal this node's lane owns, if it is inside a terminal lane.
      *

package/dist/{types-B-Syk9-M.d.cts → types-E48Dpesq.d.ts}

@@ -538,6 +538,26 @@ type NodeExecutor<TIn = Record<string, unknown>, TOut = unknown> = (ctx: {
      * invent a key. See `RunIdentity`.
      */
     run?: RunIdentity;
+    /**
+     * The graph this node belongs to.
+     *
+     * A STRUCTURAL executor needs it: `for_each`'s `item` port fans out over a
+     * lane derived from the graph — the nodes reachable from `item`, stopping
+     * at anything also reachable from `done` — and that lane cannot be computed
+     * from `node` and `inputs` alone.
+     *
+     * Without it the `item` port was accepted by the schema, drawn by the
+     * editor, and silently ignored at run time on this runtime: downstream
+     * nodes ran ONCE against the whole collection instead of once per item,
+     * with no error. The PHP twin derives the same lane from `$ctx->graph` and
+     * has since 0.6; parity was measured against a reference graph where the
+     * two disagreed.
+     *
+     * Optional, because a host may construct a context by hand. An executor
+     * that needs it must degrade rather than throw — `for_each` falls back to
+     * publishing the collection, which is what it did everywhere before.
+     */
+    graph?: FlowGraph;
     /**
      * The terminal this node's lane owns, if it is inside a terminal lane.
      *

package/dist/ux.cjs

@@ -729,6 +729,9 @@ async function runFlow(graph, executors, onEvent = () => {
             executors,
             depth,
             run,
+            // Structural executors derive a nested lane from the graph they are
+            // in; `for_each`'s `item` port cannot be implemented without it.
+            graph,
             terminal: terminalAccessorFor(node)
           })
         );
@@ -1163,6 +1166,7 @@ var branchExecutor = (ctx) => {
   const inputs = ctx.inputs;
   let taken;
   const raw = config.condition;
+  validateRoutingExpression(ctx, raw, "branch", "condition");
   if (typeof raw === "string" && raw.trim() !== "") {
     taken = truthy(resolve(raw, inputs));
     warnIfUnresolved(ctx, raw, taken ? "true" : "false");
@@ -1217,14 +1221,102 @@ var mergeExecutor = (ctx) => {
   }
   return merged;
 };
-var forEachExecutor = (ctx) => {
-  const source = resolve(configOf(ctx.node).source, ctx.inputs);
+var FOR_EACH_DEFAULT_MAX_ITEMS = 1e3;
+var FOR_EACH_HARD_MAX_ITEMS = 1e4;
+function reachable(adjacency, starts) {
+  const seen = /* @__PURE__ */ new Set();
+  const queue = [...starts];
+  for (let cursor = 0; cursor < queue.length; cursor += 1) {
+    const id = queue[cursor];
+    if (seen.has(id)) continue;
+    seen.add(id);
+    for (const target of adjacency.get(id) ?? []) queue.push(target);
+  }
+  return seen;
+}
+function forEachLane(graph, nodeId) {
+  const handleOf = (edge) => edge.sourceHandle ?? "out";
+  const itemEdges = graph.edges.filter((e) => e.source === nodeId && handleOf(e) === "item");
+  if (itemEdges.length === 0) return null;
+  const adjacency = /* @__PURE__ */ new Map();
+  for (const edge of graph.edges) {
+    const list = adjacency.get(edge.source) ?? [];
+    list.push(edge.target);
+    adjacency.set(edge.source, list);
+  }
+  const done = reachable(
+    adjacency,
+    graph.edges.filter((e) => e.source === nodeId && handleOf(e) === "done").map((e) => e.target)
+  );
+  const body = new Set(
+    [...reachable(adjacency, itemEdges.map((e) => e.target))].filter(
+      (id) => !done.has(id) && id !== nodeId
+    )
+  );
+  return {
+    graph: {
+      nodes: graph.nodes.filter((n) => body.has(n.id)),
+      edges: graph.edges.filter((e) => body.has(e.source) && body.has(e.target)),
+      ...graph.inputs === void 0 ? {} : { inputs: graph.inputs }
+    },
+    entries: itemEdges.filter((e) => body.has(e.target))
+  };
+}
+var forEachExecutor = async (ctx) => {
+  const config = configOf(ctx.node);
+  const source = resolve(config.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 };
+  const lane = ctx.graph ? forEachLane(ctx.graph, ctx.node.id) : null;
+  if (lane === null || config.mode === "collect") {
+    return { items, count: items.length };
+  }
+  if (lane.graph.nodes.length === 0) {
+    ctx.abort(`for_each "${ctx.node.id}" has an item edge but its derived lane is empty`);
+  }
+  const maxItems = Number(config.maxItems ?? FOR_EACH_DEFAULT_MAX_ITEMS);
+  if (!Number.isFinite(maxItems) || maxItems < 1 || maxItems > FOR_EACH_HARD_MAX_ITEMS) {
+    ctx.abort(`for_each "${ctx.node.id}" maxItems must be between 1 and ${FOR_EACH_HARD_MAX_ITEMS}`);
+  }
+  if (items.length > maxItems) {
+    ctx.abort(
+      `for_each "${ctx.node.id}" resolved ${items.length} items exceeds its maxItems cap of ${maxItems}`
+    );
+  }
+  const results = [];
+  const failures = [];
+  for (const [index, item] of items.entries()) {
+    const initialInputs = {};
+    for (const edge of lane.entries) {
+      initialInputs[edge.target] = {
+        ...initialInputs[edge.target] ?? {},
+        [edge.targetHandle ?? "in"]: item
+      };
+    }
+    const nested = await runFlow(lane.graph, { ...ctx.executors ?? {} }, () => {
+    }, {
+      initialInputs,
+      depth: (ctx.depth ?? 0) + 1,
+      // The index rides on the identity, so a node in iteration 3 cannot share
+      // an idempotency key with the same node in iteration 4.
+      run: ctx.run?.descend(ctx.node.id, index)
+    });
+    if (!nested.ok) {
+      const reason = nested.error ?? "unknown error";
+      if (decodePause(reason)) ctx.abort(reason);
+      results.push(null);
+      failures.push({ index, item, error: reason });
+      continue;
+    }
+    results.push(nested.outputs);
+  }
+  return {
+    __port: "done",
+    value: { items, results, failures, count: items.length }
+  };
 };
 var manualTriggerExecutor = (ctx) => ctx.inputs;
 var outputExecutor = (ctx) => {
@@ -1244,6 +1336,7 @@ var switchCaseExecutor = (ctx) => {
   const config = configOf(ctx.node);
   const inputs = ctx.inputs;
   const expression = config.value;
+  validateRoutingExpression(ctx, expression, "switch_case", "value");
   const value = text(resolve(expression, inputs));
   const cases = config.cases ?? {};
   const matched = Object.prototype.hasOwnProperty.call(cases, value);
@@ -1251,6 +1344,21 @@ var switchCaseExecutor = (ctx) => {
   warnIfUnresolved(ctx, expression, port, "value");
   return { __port: port, value: inputs.in ?? inputs };
 };
+function validateRoutingExpression(ctx, value, kind, field) {
+  if (typeof value !== "string" || value.trim() === "") return;
+  const bare = value.trim();
+  const subject = `${kind} "${ctx.node.id}" ${field} "${bare}"`;
+  if (!value.includes("{{")) {
+    ctx.abort(`${subject} is not an expression -- wrap it: {{ ${bare} }}`);
+  }
+  let open = 0;
+  for (const [delimiter] of value.matchAll(/\{\{|\}\}/g)) {
+    open = delimiter === "{{" ? open + 1 : Math.max(0, open - 1);
+  }
+  if (open > 0) {
+    ctx.abort(`${subject} has an unclosed expression -- close every {{ with }}`);
+  }
+}
 
 // src/registry/terminal-nodes.ts
 var DEFAULT_TIMEOUT_MS = 12e4;
@@ -1742,7 +1850,7 @@ var KINDS = [
         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."
+        description: "Escape hatch for logic the builder can't express. Overrides the conditions above when set. String values must be {{ }}-wrapped expressions; bare strings and unclosed templates abort the run."
       }
     ]
   },
@@ -1762,7 +1870,7 @@ var KINDS = [
     // 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: "expression", key: "value", label: "Switch on", description: "String values must be {{ }}-wrapped expressions; bare strings and unclosed templates abort the run.", example: "{{ $json.kind }}", required: true },
       {
         type: "keyvalue",
         key: "cases",
@@ -1781,6 +1889,15 @@ var KINDS = [
     name: "@particle-academy/for_each",
     outputShape: [
       { path: "items", type: "array" },
+      // `results` and `failures` are the WIRED shape -- what a lane produces
+      // when the `item` port is connected. Declared unconditionally because a
+      // declaration describes the kind, not one graph's use of it, and because
+      // the shared table requires them: fancy-conformance 0.30.0 added
+      // `results` and 0.31.0 added `failures`, both BREAKING, both so that a
+      // runtime which has not implemented iteration fails here rather than
+      // reporting surface parity it does not have.
+      { path: "results", type: "array" },
+      { path: "failures", type: "array" },
       { path: "count", type: "number" }
     ],
     aliases: ["for_each", "@fancy/for_each"],
@@ -1789,7 +1906,7 @@ var KINDS = [
     executor: forEachExecutor,
     category: "logic",
     label: "For Each",
-    description: "Publishes the resolved list and its size on BOTH `item` and `done`. Fan-out as DATA, not as jobs -- nothing runs per item.",
+    description: "Wire `item` to a lane and it runs once per item, aggregating `results` and `failures` on `done`. Leave `item` unwired (or set `mode: collect`) and it just publishes the list and its size -- one node, one checkpoint.",
     icon: "\u21BB",
     inputs: [{ id: "in" }],
     outputs: [{ id: "item", label: "item" }, { id: "done", label: "done" }],