@particle-academy/fancy-flow 0.49.0 → 0.51.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-CFSMlCqi.cjs';
+export { F as FlowNodeStatus, a as FlowViewer, b as FlowViewerClassNames, c as FlowViewerProps } from './FlowViewer-DABx-6A-.cjs';
 import 'react';
-import './types-7cXcSQlx.cjs';
+import './types-JFYjPJAG.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-DRgjeWJ7.js';
+export { F as FlowNodeStatus, a as FlowViewer, b as FlowViewerClassNames, c as FlowViewerProps } from './FlowViewer-BI_AyyvU.js';
 import 'react';
-import './types-7cXcSQlx.js';
+import './types-JFYjPJAG.js';
 import '@xyflow/react';
 
 /**

package/dist/screens.js

@@ -1,8 +1,8 @@
-import { FlowViewer } from './chunk-AVRGZFXG.js';
-export { FlowViewer } from './chunk-AVRGZFXG.js';
-import './chunk-6XKR65XM.js';
+import { FlowViewer } from './chunk-7XTTXMGB.js';
+export { FlowViewer } from './chunk-7XTTXMGB.js';
+import './chunk-6AI6CBNL.js';
 import './chunk-UEOE6B52.js';
-import './chunk-6FP3F5YR.js';
+import './chunk-XCT2CJ5O.js';
 import './chunk-F5RPRB7A.js';
 import './chunk-USL4FMFU.js';
 import { registerSchemaComponents } from '@particle-academy/fancy-screens';

package/dist/{types-BtMOnb9I.d.cts → types-3sPauVRT.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-7cXcSQlx.cjs';
+import { F as FlowGraph, a as FlowNode, P as PortDescriptor, N as NodeExecutor } from './types-JFYjPJAG.cjs';
 import { NodeProps } from '@xyflow/react';
 import { P as PauseAwaiting } from './pause-9iT4tCEV.cjs';
 

package/dist/{types-7cXcSQlx.d.ts → types-JFYjPJAG.d.cts}

@@ -202,10 +202,46 @@ type SubgraphNodeData = BaseNodeData & {
 type FlowNodeData = TriggerNodeData | ActionNodeData | DecisionNodeData | OutputNodeData | NoteNodeData | SubgraphNodeData;
 type FlowNode = Node<FlowNodeData>;
 type FlowEdge = Edge;
+/**
+ * One value a workflow DECLARES that it accepts at run start.
+ *
+ * The declaration is the point. Before this existed, a caller passed
+ * `initialInputs` keyed BY NODE ID — so they had to know the trigger happened
+ * to be called `t`, and renaming that node broke every caller while the graph
+ * itself stayed valid. Nothing reported it.
+ *
+ * And nothing said what a workflow accepted at all: no names, no types, no
+ * defaults. An agent composing a call had nothing to read, and a misspelled key
+ * did not fail — the value simply sat unused while the run reported success.
+ */
+type WorkflowInput = {
+    /** What a caller passes it as. */
+    name: string;
+    /**
+     * Optional. Omitting it means "I am not asserting a shape", which must not
+     * degrade into "nothing is allowed" — an undeclared type accepts anything.
+     */
+    type?: "string" | "number" | "boolean" | "object" | "array";
+    /**
+     * The run needs a value. Satisfied by a `default`, so `required` means
+     * "this must resolve to something" rather than "the caller must type it".
+     */
+    required?: boolean;
+    /** Used when the caller omits the key. An explicit value always wins. */
+    default?: unknown;
+    description?: string;
+};
 /** A serializable graph — what hosts persist, what agents read/write. */
 type FlowGraph = {
     nodes: FlowNode[];
     edges: FlowEdge[];
+    /**
+     * What this workflow accepts. Callers pass a flat object BY NAME.
+     *
+     * Omitted entirely when a graph takes none, so existing saved graphs are
+     * unchanged byte for byte and every diff stays readable.
+     */
+    inputs?: WorkflowInput[];
 };
 /** Per-node executor signature. Inputs are keyed by input-port id. */
 type NodeExecutor<TIn = Record<string, unknown>, TOut = unknown> = (ctx: {
@@ -294,4 +330,4 @@ type RunEvent = {
     error: string;
 };
 
-export { type ActionNodeData as A, type BaseNodeData as B, type DecisionNodeData as D, type ExecutorRegistry as E, type FlowGraph as F, type NodeExecutor as N, type OutputNodeData as O, type PortDescriptor as P, type RunEvent as R, type SubgraphNodeData as S, type TriggerNodeData as T, type FlowNode as a, RunIdentity as b, type RunIdentityJson as c, type FlowEdge as d, type FlowNodeData as e, type FlowNodeKind as f, type NodeRunStatus as g, type NoteNodeData as h, escapeSegment as i };
+export { type ActionNodeData as A, type BaseNodeData as B, type DecisionNodeData as D, type ExecutorRegistry as E, type FlowGraph as F, type NodeExecutor as N, type OutputNodeData as O, type PortDescriptor as P, type RunEvent as R, type SubgraphNodeData as S, type TriggerNodeData as T, type WorkflowInput as W, type FlowNode as a, RunIdentity as b, type RunIdentityJson as c, type FlowEdge as d, type FlowNodeData as e, type FlowNodeKind as f, type NodeRunStatus as g, type NoteNodeData as h, escapeSegment as i };

package/dist/{types-7cXcSQlx.d.cts → types-JFYjPJAG.d.ts}

@@ -202,10 +202,46 @@ type SubgraphNodeData = BaseNodeData & {
 type FlowNodeData = TriggerNodeData | ActionNodeData | DecisionNodeData | OutputNodeData | NoteNodeData | SubgraphNodeData;
 type FlowNode = Node<FlowNodeData>;
 type FlowEdge = Edge;
+/**
+ * One value a workflow DECLARES that it accepts at run start.
+ *
+ * The declaration is the point. Before this existed, a caller passed
+ * `initialInputs` keyed BY NODE ID — so they had to know the trigger happened
+ * to be called `t`, and renaming that node broke every caller while the graph
+ * itself stayed valid. Nothing reported it.
+ *
+ * And nothing said what a workflow accepted at all: no names, no types, no
+ * defaults. An agent composing a call had nothing to read, and a misspelled key
+ * did not fail — the value simply sat unused while the run reported success.
+ */
+type WorkflowInput = {
+    /** What a caller passes it as. */
+    name: string;
+    /**
+     * Optional. Omitting it means "I am not asserting a shape", which must not
+     * degrade into "nothing is allowed" — an undeclared type accepts anything.
+     */
+    type?: "string" | "number" | "boolean" | "object" | "array";
+    /**
+     * The run needs a value. Satisfied by a `default`, so `required` means
+     * "this must resolve to something" rather than "the caller must type it".
+     */
+    required?: boolean;
+    /** Used when the caller omits the key. An explicit value always wins. */
+    default?: unknown;
+    description?: string;
+};
 /** A serializable graph — what hosts persist, what agents read/write. */
 type FlowGraph = {
     nodes: FlowNode[];
     edges: FlowEdge[];
+    /**
+     * What this workflow accepts. Callers pass a flat object BY NAME.
+     *
+     * Omitted entirely when a graph takes none, so existing saved graphs are
+     * unchanged byte for byte and every diff stays readable.
+     */
+    inputs?: WorkflowInput[];
 };
 /** Per-node executor signature. Inputs are keyed by input-port id. */
 type NodeExecutor<TIn = Record<string, unknown>, TOut = unknown> = (ctx: {
@@ -294,4 +330,4 @@ type RunEvent = {
     error: string;
 };
 
-export { type ActionNodeData as A, type BaseNodeData as B, type DecisionNodeData as D, type ExecutorRegistry as E, type FlowGraph as F, type NodeExecutor as N, type OutputNodeData as O, type PortDescriptor as P, type RunEvent as R, type SubgraphNodeData as S, type TriggerNodeData as T, type FlowNode as a, RunIdentity as b, type RunIdentityJson as c, type FlowEdge as d, type FlowNodeData as e, type FlowNodeKind as f, type NodeRunStatus as g, type NoteNodeData as h, escapeSegment as i };
+export { type ActionNodeData as A, type BaseNodeData as B, type DecisionNodeData as D, type ExecutorRegistry as E, type FlowGraph as F, type NodeExecutor as N, type OutputNodeData as O, type PortDescriptor as P, type RunEvent as R, type SubgraphNodeData as S, type TriggerNodeData as T, type WorkflowInput as W, type FlowNode as a, RunIdentity as b, type RunIdentityJson as c, type FlowEdge as d, type FlowNodeData as e, type FlowNodeKind as f, type NodeRunStatus as g, type NoteNodeData as h, escapeSegment as i };

package/dist/{types-CDgIIj4c.d.ts → types-s643U1Hi.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-7cXcSQlx.js';
+import { F as FlowGraph, a as FlowNode, P as PortDescriptor, N as NodeExecutor } from './types-JFYjPJAG.js';
 import { NodeProps } from '@xyflow/react';
 import { P as PauseAwaiting } from './pause-9iT4tCEV.js';
 

package/dist/ux.cjs

@@ -9227,6 +9227,61 @@ var RunIdentity = class _RunIdentity {
   }
 };
 
+// src/runtime/workflow-props.ts
+function typeOf(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+function resolveWorkflowProps(declared, passed) {
+  const inputs = declared ?? [];
+  const given = passed ?? {};
+  const byName = new Map(inputs.map((input) => [input.name, input]));
+  for (const name of Object.keys(given)) {
+    if (!byName.has(name)) {
+      const known = inputs.map((input) => input.name);
+      const suffix = known.length === 0 ? "this workflow declares no inputs" : `known inputs: ${known.join(", ")}`;
+      return {
+        ok: false,
+        code: "unknown_input",
+        error: `Unknown workflow input "${name}" \u2014 ${suffix}.`
+      };
+    }
+  }
+  const resolved = {};
+  for (const input of inputs) {
+    const supplied = Object.prototype.hasOwnProperty.call(given, input.name);
+    const hasDefault = Object.prototype.hasOwnProperty.call(input, "default");
+    if (!supplied) {
+      if (hasDefault) {
+        resolved[input.name] = input.default;
+        continue;
+      }
+      if (input.required) {
+        return {
+          ok: false,
+          code: "missing_required",
+          error: `Missing required workflow input "${input.name}"${input.type ? ` (${input.type})` : ""}.`
+        };
+      }
+      continue;
+    }
+    const value = given[input.name];
+    if (input.type !== void 0) {
+      const actual = typeOf(value);
+      if (actual !== input.type) {
+        return {
+          ok: false,
+          code: "type_mismatch",
+          error: `Workflow input "${input.name}" expects ${input.type}, got ${actual}.`
+        };
+      }
+    }
+    resolved[input.name] = value;
+  }
+  return { ok: true, props: resolved };
+}
+
 // src/runtime/run-flow.ts
 async function runFlow(graph, executors, onEvent = () => {
 }, options = {}) {
@@ -9242,6 +9297,13 @@ async function runFlow(graph, executors, onEvent = () => {
     onEvent({ type: "run-error", error: msg });
     return { ok: false, outputs, error: msg };
   }
+  const propsCheck = resolveWorkflowProps(graph.inputs, options.props);
+  if (!propsCheck.ok) {
+    onEvent({ type: "run-error", error: propsCheck.error });
+    return { ok: false, outputs, error: propsCheck.error };
+  }
+  const props = propsCheck.props;
+  const declaresProps = (graph.inputs?.length ?? 0) > 0;
   const incomingByNode = indexIncoming(graph.edges);
   const timer2 = timeoutMs ? setTimeout(() => errors.push(`Run timed out after ${timeoutMs}ms`), timeoutMs) : null;
   onEvent({ type: "run-start" });
@@ -9283,7 +9345,7 @@ async function runFlow(graph, executors, onEvent = () => {
       }
       onEvent({ type: "node-status", nodeId: node.id, status: "running" });
       announce(onEvent, node, "start");
-      const inputs = collectInputs(node, incoming, portValues, initialInputs);
+      const inputs = collectInputs(node, incoming, portValues, initialInputs, props, declaresProps);
       const exec = pickExecutor(executors, node);
       if (!exec) {
         const msg = `No executor registered for kind=${node.type}`;
@@ -9360,14 +9422,23 @@ function topoSort(graph) {
   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) {
+function collectInputs(node, incoming, portValues, initial, props, declaresProps) {
   const inputs = { ...initial[node.id] ?? {} };
+  if (incoming.length === 0) {
+    for (const [name, value] of Object.entries(props)) {
+      if (!(name in inputs)) inputs[name] = value;
+    }
+  }
   for (const e of incoming) {
     const portId = e.targetHandle ?? "in";
     const key = `${e.source}:${e.sourceHandle ?? "out"}`;
     if (!portValues.has(key)) continue;
     inputs[portId] = portValues.get(key);
+    if (e.targetHandle == null && !(e.source in inputs)) {
+      inputs[e.source] = portValues.get(key);
+    }
   }
+  if (declaresProps) inputs.$props = props;
   return inputs;
 }
 function pickExecutor(executors, node) {