@particle-academy/fancy-flow 0.59.0 → 0.64.0

package/dist/expr-BfXDrs4H.d.cts

@@ -0,0 +1,149 @@
+/**
+ * `{{ }}` resolution — the TypeScript twin of `FancyFlow\Nodes\Support\Expr`.
+ *
+ * ## Why this is opt-in and not wired into `runFlow`
+ *
+ * The PHP runtime resolves expressions inside its batteries-included executors.
+ * The JS runtime never has: `runFlow` hands `node.data.config` to your executor
+ * verbatim, so every host that uses `{{ }}` today already resolves it itself.
+ * Turning resolution on inside `runFlow` would interpolate a second time over
+ * values those hosts had already substituted — silently, and only for graphs
+ * that happen to contain `{{` in their DATA.
+ *
+ * So this exports the semantics and changes no behaviour. Call it yourself:
+ *
+ * ```ts
+ * const url = evaluateExpression(node.data.config.url, inputs);
+ * ```
+ *
+ * ## The semantics are the PHP file's, deliberately
+ *
+ * This is not a general expression language and must not grow into one. It
+ * resolves a dot-path against a context and nothing else — no arithmetic, no
+ * comparisons, no calls. Hosts that want real expressions override the executor
+ * (the PHP docblock points at symfony/expression-language for the same reason).
+ *
+ * Divergence here is a correctness bug rather than a style difference: the same
+ * graph is authored once and may run on either runtime. `suites/shared/expr`
+ * in `@particle-academy/fancy-conformance` is the fixture table both sides run,
+ * so parity is a test result instead of a claim.
+ */
+/** Anything a context or a resolved value can be. */
+type ExprValue = unknown;
+/** The context an expression resolves against — the executor's `inputs`. */
+type ExprContext = Record<string, ExprValue>;
+/**
+ * What a resolution attempt ANSWERS — did the path resolve, and to what.
+ *
+ * `resolvePath` cannot express this, and that is the defect it exists to fix:
+ * it returns `null` both for "this path does not exist" and for "this path
+ * exists and holds null". One value standing for two states.
+ *
+ * At the interpolation layer the collapse is worse, because `null` stringifies
+ * to `""`. A consumer put it exactly:
+ *
+ * > "An unresolvable path yields `''`, so a wrong field is indistinguishable
+ * > from an empty one at runtime."
+ *
+ * A misspelled field renders as an empty string, which looks precisely like a
+ * field that is legitimately empty. The graph runs, the node succeeds, and the
+ * output is quietly missing a value nobody is told about — worst on
+ * LLM-authored graphs, where the field name was guessed in the first place.
+ *
+ * Same shape as the four `??` collapses fixed across all four runtimes on
+ * 2026-08-26 (absent vs null), one layer up: **presence is the only correct
+ * test, and a return value that cannot express presence cannot be tested for
+ * it.** Hence a second return channel rather than a cleverer sentinel — every
+ * sentinel is a legal value for somebody.
+ */
+interface Resolution {
+    /** Whether the path resolved at all. `false` means it does not exist. */
+    resolved: boolean;
+    /** The value, when `resolved`. `null` when not — do not read it blind. */
+    value: ExprValue;
+}
+/** Thrown by the `"throw"` policy when a path does not resolve. */
+declare class UnresolvedPathError extends Error {
+    readonly path: string;
+    constructor(path: string);
+}
+/**
+ * What evaluation does with a path that does not resolve.
+ *
+ * - `"empty"` — today's behaviour, and the DEFAULT. Interpolates to `""`; a
+ *   whole expression yields `null`. Unchanged so that widening this API breaks
+ *   nobody: 40 call sites across the runtimes assume it.
+ * - `"keep"` — leave the `{{ … }}` text in place. The failure becomes VISIBLE
+ *   in the output without stopping the run, which is what you want for
+ *   human-reviewed content: a rendered `{{ in.recipient_naem }}` is self-
+ *   diagnosing in a way an absence never is.
+ * - `"throw"` — refuse. For hosts that would rather fail a run than deliver a
+ *   silently incomplete result.
+ *
+ * Opt-in before default at the request of the consumer who reported it — the
+ * host with the most LLM-authored graphs, and so both the biggest beneficiary
+ * and the right place for it to break first if it is going to.
+ */
+type UnresolvedPolicy = "empty" | "keep" | "throw";
+/** Options for {@link evaluateExpression} / {@link evaluateConfig}. */
+interface EvaluateOptions {
+    /** What to do with a path that does not resolve. Default `"empty"`. */
+    onUnresolved?: UnresolvedPolicy;
+}
+/**
+ * Resolve a dot-path, reporting WHETHER it resolved.
+ *
+ * The same walk as `resolvePath` — deliberately, so the two can never disagree
+ * about what resolves; `resolvePath` is defined in terms of this one below.
+ *
+ * A note on JS having two absent values: a key present with the value
+ * `undefined` reports `resolved: false`, matching `resolvePath`'s long-standing
+ * behaviour. It cannot arise from graph data (JSON has no `undefined`), and
+ * changing it would make the two functions disagree for no reachable gain.
+ */
+declare function tryResolvePath(path: string, context: ExprContext): Resolution;
+/**
+ * Resolve a dot-path against the context, honouring the `$json` / `$input`
+ * alias.
+ *
+ * Both aliases point at the `in` port value when the context has one, and at
+ * the whole context otherwise — the same fallback the PHP does, which is what
+ * makes `{{ $json.x }}` work on a trigger node that has no upstream input.
+ *
+ * A path that does not resolve returns `null`, never `undefined`: PHP has one
+ * absent value and JS has two, and letting the difference leak would make the
+ * two runtimes disagree about `{{ missing }}` for no useful reason.
+ */
+declare function resolvePath(path: string, context: ExprContext): ExprValue;
+/**
+ * Evaluate a template against a context.
+ *
+ * A string that is EXACTLY one expression returns the resolved value with its
+ * type intact — `{{ $json.count }}` gives you a number, not `"3"`. Anything
+ * else interpolates each run as text. That distinction is load-bearing: it is
+ * what lets a config field carry either a value or a sentence.
+ *
+ * Non-string templates pass through untouched, so this is safe to map over a
+ * whole config object.
+ */
+declare function evaluateExpression(template: ExprValue, context: ExprContext, options?: EvaluateOptions): ExprValue;
+/**
+ * Truthiness for branch / switch decisions.
+ *
+ * Mirrors PHP's rules rather than JavaScript's, because the graph is authored
+ * once and may run on either side. The two disagree in exactly the places a
+ * workflow hits: `"0"` and `"false"` are truthy in JS and falsy here, and an
+ * empty array is truthy in JS and falsy here.
+ */
+declare function truthy(value: ExprValue): boolean;
+/** Coerce a value to text the way interpolation does. */
+declare function text(value: ExprValue): string;
+/**
+ * Resolve every string in a config object, one level of nesting at a time.
+ *
+ * The convenience most hosts actually want, and the shape their hand-rolled
+ * version usually takes. Opt-in like the rest of this module.
+ */
+declare function evaluateConfig<T extends Record<string, ExprValue>>(config: T, context: ExprContext, options?: EvaluateOptions): T;
+
+export { type EvaluateOptions as E, type Resolution as R, UnresolvedPathError as U, type ExprContext as a, type ExprValue as b, type UnresolvedPolicy as c, evaluateExpression as d, evaluateConfig as e, truthy as f, tryResolvePath as g, resolvePath as r, text as t };

package/dist/expr-BfXDrs4H.d.ts

@@ -0,0 +1,149 @@
+/**
+ * `{{ }}` resolution — the TypeScript twin of `FancyFlow\Nodes\Support\Expr`.
+ *
+ * ## Why this is opt-in and not wired into `runFlow`
+ *
+ * The PHP runtime resolves expressions inside its batteries-included executors.
+ * The JS runtime never has: `runFlow` hands `node.data.config` to your executor
+ * verbatim, so every host that uses `{{ }}` today already resolves it itself.
+ * Turning resolution on inside `runFlow` would interpolate a second time over
+ * values those hosts had already substituted — silently, and only for graphs
+ * that happen to contain `{{` in their DATA.
+ *
+ * So this exports the semantics and changes no behaviour. Call it yourself:
+ *
+ * ```ts
+ * const url = evaluateExpression(node.data.config.url, inputs);
+ * ```
+ *
+ * ## The semantics are the PHP file's, deliberately
+ *
+ * This is not a general expression language and must not grow into one. It
+ * resolves a dot-path against a context and nothing else — no arithmetic, no
+ * comparisons, no calls. Hosts that want real expressions override the executor
+ * (the PHP docblock points at symfony/expression-language for the same reason).
+ *
+ * Divergence here is a correctness bug rather than a style difference: the same
+ * graph is authored once and may run on either runtime. `suites/shared/expr`
+ * in `@particle-academy/fancy-conformance` is the fixture table both sides run,
+ * so parity is a test result instead of a claim.
+ */
+/** Anything a context or a resolved value can be. */
+type ExprValue = unknown;
+/** The context an expression resolves against — the executor's `inputs`. */
+type ExprContext = Record<string, ExprValue>;
+/**
+ * What a resolution attempt ANSWERS — did the path resolve, and to what.
+ *
+ * `resolvePath` cannot express this, and that is the defect it exists to fix:
+ * it returns `null` both for "this path does not exist" and for "this path
+ * exists and holds null". One value standing for two states.
+ *
+ * At the interpolation layer the collapse is worse, because `null` stringifies
+ * to `""`. A consumer put it exactly:
+ *
+ * > "An unresolvable path yields `''`, so a wrong field is indistinguishable
+ * > from an empty one at runtime."
+ *
+ * A misspelled field renders as an empty string, which looks precisely like a
+ * field that is legitimately empty. The graph runs, the node succeeds, and the
+ * output is quietly missing a value nobody is told about — worst on
+ * LLM-authored graphs, where the field name was guessed in the first place.
+ *
+ * Same shape as the four `??` collapses fixed across all four runtimes on
+ * 2026-08-26 (absent vs null), one layer up: **presence is the only correct
+ * test, and a return value that cannot express presence cannot be tested for
+ * it.** Hence a second return channel rather than a cleverer sentinel — every
+ * sentinel is a legal value for somebody.
+ */
+interface Resolution {
+    /** Whether the path resolved at all. `false` means it does not exist. */
+    resolved: boolean;
+    /** The value, when `resolved`. `null` when not — do not read it blind. */
+    value: ExprValue;
+}
+/** Thrown by the `"throw"` policy when a path does not resolve. */
+declare class UnresolvedPathError extends Error {
+    readonly path: string;
+    constructor(path: string);
+}
+/**
+ * What evaluation does with a path that does not resolve.
+ *
+ * - `"empty"` — today's behaviour, and the DEFAULT. Interpolates to `""`; a
+ *   whole expression yields `null`. Unchanged so that widening this API breaks
+ *   nobody: 40 call sites across the runtimes assume it.
+ * - `"keep"` — leave the `{{ … }}` text in place. The failure becomes VISIBLE
+ *   in the output without stopping the run, which is what you want for
+ *   human-reviewed content: a rendered `{{ in.recipient_naem }}` is self-
+ *   diagnosing in a way an absence never is.
+ * - `"throw"` — refuse. For hosts that would rather fail a run than deliver a
+ *   silently incomplete result.
+ *
+ * Opt-in before default at the request of the consumer who reported it — the
+ * host with the most LLM-authored graphs, and so both the biggest beneficiary
+ * and the right place for it to break first if it is going to.
+ */
+type UnresolvedPolicy = "empty" | "keep" | "throw";
+/** Options for {@link evaluateExpression} / {@link evaluateConfig}. */
+interface EvaluateOptions {
+    /** What to do with a path that does not resolve. Default `"empty"`. */
+    onUnresolved?: UnresolvedPolicy;
+}
+/**
+ * Resolve a dot-path, reporting WHETHER it resolved.
+ *
+ * The same walk as `resolvePath` — deliberately, so the two can never disagree
+ * about what resolves; `resolvePath` is defined in terms of this one below.
+ *
+ * A note on JS having two absent values: a key present with the value
+ * `undefined` reports `resolved: false`, matching `resolvePath`'s long-standing
+ * behaviour. It cannot arise from graph data (JSON has no `undefined`), and
+ * changing it would make the two functions disagree for no reachable gain.
+ */
+declare function tryResolvePath(path: string, context: ExprContext): Resolution;
+/**
+ * Resolve a dot-path against the context, honouring the `$json` / `$input`
+ * alias.
+ *
+ * Both aliases point at the `in` port value when the context has one, and at
+ * the whole context otherwise — the same fallback the PHP does, which is what
+ * makes `{{ $json.x }}` work on a trigger node that has no upstream input.
+ *
+ * A path that does not resolve returns `null`, never `undefined`: PHP has one
+ * absent value and JS has two, and letting the difference leak would make the
+ * two runtimes disagree about `{{ missing }}` for no useful reason.
+ */
+declare function resolvePath(path: string, context: ExprContext): ExprValue;
+/**
+ * Evaluate a template against a context.
+ *
+ * A string that is EXACTLY one expression returns the resolved value with its
+ * type intact — `{{ $json.count }}` gives you a number, not `"3"`. Anything
+ * else interpolates each run as text. That distinction is load-bearing: it is
+ * what lets a config field carry either a value or a sentence.
+ *
+ * Non-string templates pass through untouched, so this is safe to map over a
+ * whole config object.
+ */
+declare function evaluateExpression(template: ExprValue, context: ExprContext, options?: EvaluateOptions): ExprValue;
+/**
+ * Truthiness for branch / switch decisions.
+ *
+ * Mirrors PHP's rules rather than JavaScript's, because the graph is authored
+ * once and may run on either side. The two disagree in exactly the places a
+ * workflow hits: `"0"` and `"false"` are truthy in JS and falsy here, and an
+ * empty array is truthy in JS and falsy here.
+ */
+declare function truthy(value: ExprValue): boolean;
+/** Coerce a value to text the way interpolation does. */
+declare function text(value: ExprValue): string;
+/**
+ * Resolve every string in a config object, one level of nesting at a time.
+ *
+ * The convenience most hosts actually want, and the shape their hand-rolled
+ * version usually takes. Opt-in like the rest of this module.
+ */
+declare function evaluateConfig<T extends Record<string, ExprValue>>(config: T, context: ExprContext, options?: EvaluateOptions): T;
+
+export { type EvaluateOptions as E, type Resolution as R, UnresolvedPathError as U, type ExprContext as a, type ExprValue as b, type UnresolvedPolicy as c, evaluateExpression as d, evaluateConfig as e, truthy as f, tryResolvePath as g, resolvePath as r, text as t };

package/dist/fields/react-fancy.d.cts

@@ -1,8 +1,8 @@
-import { H as HumanFieldRenderers, C as ConfigFieldRenderFn } from '../HumanPrompt-DV5-xnDa.cjs';
+import { H as HumanFieldRenderers, C as ConfigFieldRenderFn } from '../HumanPrompt-Bpp3JiVH.cjs';
 import 'react';
 import '../types-JFYjPJAG.cjs';
 import '@xyflow/react';
-import '../types-BLVpNNLN.cjs';
+import '../types-D71SKA5A.cjs';
 import '../pause-9iT4tCEV.cjs';
 
 /**

package/dist/fields/react-fancy.d.ts

@@ -1,8 +1,8 @@
-import { H as HumanFieldRenderers, C as ConfigFieldRenderFn } from '../HumanPrompt-Bw09OyS3.js';
+import { H as HumanFieldRenderers, C as ConfigFieldRenderFn } from '../HumanPrompt-BKThiyjB.js';
 import 'react';
 import '../types-JFYjPJAG.js';
 import '@xyflow/react';
-import '../types-CLSUZW8c.js';
+import '../types-Ckhz-YwC.js';
 import '../pause-9iT4tCEV.js';
 
 /**

package/dist/index.cjs

@@ -11445,7 +11445,7 @@ function activatedPorts(node, result) {
       return { ports: [r.__port], value: r.value };
     }
     if (typeof r.branch === "string") {
-      return { ports: [r.branch], value: r.value ?? r };
+      return { ports: [r.branch], value: Object.prototype.hasOwnProperty.call(r, "value") ? r.value : r };
     }
   }
   const kind = getNodeKind(node.data?.kind ?? node.type ?? "") ?? void 0;
@@ -11607,8 +11607,9 @@ var KINDS = [
   // ───────────── Triggers ─────────────
   {
     name: "@particle-academy/manual_trigger",
-    // returns the inputs it was started with
-    emits: "input",
+    // 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",
@@ -11641,8 +11642,9 @@ var KINDS = [
       { path: "cron", type: "string", description: "The cron expression that fired." },
       { path: "timezone", type: "string", description: "The timezone it was evaluated in." }
     ],
-    // merges its inputs into the TOP level beside cron/timezone
-    emits: "inputs-merged",
+    // 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",
@@ -14388,6 +14390,55 @@ function preview(v2) {
   }
 }
 
+// src/analysis/graph-connectivity.ts
+function checkGraphConnectivity(graph) {
+  const { nodes, edges } = graph;
+  const issues = [];
+  const hasIncoming = /* @__PURE__ */ new Set();
+  const hasOutgoing = /* @__PURE__ */ new Set();
+  for (const edge of edges) {
+    hasIncoming.add(edge.target);
+    hasOutgoing.add(edge.source);
+  }
+  const single = nodes.length === 1;
+  for (const node of nodes) {
+    if (single || mayFloat(node)) continue;
+    if (!hasIncoming.has(node.id) && !hasOutgoing.has(node.id)) {
+      issues.push({
+        level: "error",
+        nodeId: node.id,
+        message: `Node "${node.id}" is connected to nothing \u2014 no inbound edge and no outbound edge. It still RUNS (a node with no inbound edge is a root), but it receives nothing from the graph and reaches nobody in it, so it is either unwired or left behind by a deletion. Only a note, an annotation or a lane may float.`
+      });
+    }
+  }
+  const byId = new Map(nodes.map((n) => [n.id, n]));
+  for (const edge of edges) {
+    const source = byId.get(edge.source);
+    if (!source || !isTerminator(source)) continue;
+    issues.push({
+      level: "error",
+      edgeId: edge.id,
+      message: `Edge "${edge.id}" reads from "${edge.source}", which is a TERMINAL node and publishes no output ports at all. Nothing can ever travel this edge: it does not fail at run time, it delivers nothing, and "${edge.target}" runs anyway with an empty input.`
+    });
+  }
+  return issues;
+}
+function mayFloat(node) {
+  const type = node.type;
+  if (!type) return false;
+  if (type === "note") return true;
+  const kind = getNodeKind(type);
+  if (!kind) return true;
+  return kindIds(kind).includes("note") || kind.category === "annotation" || kind.category === "layout";
+}
+function isTerminator(node) {
+  const own = node.data?.outputs;
+  if (Array.isArray(own)) return own.length === 0;
+  const kind = node.type ? getNodeKind(node.type) : null;
+  if (!kind) return false;
+  return Array.isArray(kind.outputs) && kind.outputs.length === 0;
+}
+
 // src/schema/workflow-schema.ts
 var WORKFLOW_SCHEMA_VERSION = 1;
 var WORKFLOW_SCHEMA_URL = "https://particle.academy/schemas/workflow/v1.json";
@@ -14535,6 +14586,7 @@ function importWorkflow(schema, options = {}) {
       label: e.label
     };
   }).filter((e) => e !== null);
+  issues.push(...checkGraphConnectivity({ nodes, edges }));
   const ok = issues.every((i) => i.level !== "error");
   const declaredInputs = Array.isArray(s.inputs) ? s.inputs.filter(
     (input) => input !== null && typeof input === "object" && typeof input.name === "string"
@@ -15874,9 +15926,19 @@ function interpolate(template, resolve) {
   }
 }
 var FALSY_STRINGS = /* @__PURE__ */ new Set(["", "0", "false", "no", "off", "null"]);
-function resolvePath(path, context) {
+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 null;
+  if (trimmed === "") return unresolved;
   const segments = trimmed.split(".");
   let cursor;
   const head = segments[0];
@@ -15887,19 +15949,33 @@ function resolvePath(path, context) {
     cursor = context;
   }
   for (const segment of segments) {
-    if (cursor === null || cursor === void 0) return null;
-    if (typeof cursor !== "object") return null;
+    if (cursor === null || cursor === void 0) return unresolved;
+    if (typeof cursor !== "object") return unresolved;
     const next = cursor[segment];
-    if (next === void 0) return null;
+    if (next === void 0) return unresolved;
     cursor = next;
   }
-  return cursor === void 0 ? null : cursor;
+  return { resolved: true, value: cursor === void 0 ? null : cursor };
 }
-function evaluateExpression(template, context) {
+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) return resolvePath(whole, context);
-  return interpolate(template, (path) => stringify(resolvePath(path, context)));
+  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;
@@ -15923,10 +15999,10 @@ function stringify(value) {
     return "";
   }
 }
-function evaluateConfig(config, context) {
+function evaluateConfig(config, context, options = {}) {
   const out = {};
   for (const [key, value] of Object.entries(config)) {
-    out[key] = Array.isArray(value) ? value.map((v2) => evaluateExpression(v2, context)) : value !== null && typeof value === "object" ? evaluateConfig(value, context) : evaluateExpression(value, context);
+    out[key] = Array.isArray(value) ? value.map((v2) => evaluateExpression(v2, context, options)) : value !== null && typeof value === "object" ? evaluateConfig(value, context, options) : evaluateExpression(value, context, options);
   }
   return out;
 }
@@ -15963,6 +16039,7 @@ exports.RegistryNode = RegistryNode;
 exports.RichInputPreview = RichInputPreview;
 exports.SubgraphNode = SubgraphNode;
 exports.TriggerNode = TriggerNode;
+exports.UnresolvedPathError = UnresolvedPathError;
 exports.WORKFLOW_SCHEMA_URL = WORKFLOW_SCHEMA_URL;
 exports.WORKFLOW_SCHEMA_VERSION = WORKFLOW_SCHEMA_VERSION;
 exports.alignNodes = alignNodes;
@@ -16014,6 +16091,7 @@ exports.runCohort = runCohort;
 exports.runFlow = runFlow;
 exports.text = text;
 exports.truthy = truthy;
+exports.tryResolvePath = tryResolvePath;
 exports.useFlowEditor = useFlowEditor;
 exports.useFlowEditorOptional = useFlowEditorOptional;
 exports.useFlowHistory = useFlowHistory;