@particle-academy/fancy-flow 0.56.0 → 0.58.0

package/dist/screens.js

@@ -1,8 +1,8 @@
-import { FlowViewer } from './chunk-HMEI2LFU.js';
-export { FlowViewer } from './chunk-HMEI2LFU.js';
-import './chunk-E3AGYTHP.js';
+import { FlowViewer } from './chunk-MX4SJDNI.js';
+export { FlowViewer } from './chunk-MX4SJDNI.js';
+import './chunk-M7M6GLFV.js';
 import './chunk-UEOE6B52.js';
-import './chunk-22OJOD4X.js';
+import './chunk-HBE4LVPX.js';
 import './chunk-F5RPRB7A.js';
 import './chunk-USL4FMFU.js';
 import { registerSchemaComponents } from '@particle-academy/fancy-screens';

package/dist/{types-3sPauVRT.d.cts → types-BLVpNNLN.d.cts}

@@ -485,6 +485,13 @@ type RenderBodyContext<TConfig = unknown> = {
     config: TConfig;
     selected: boolean;
 };
+/**
+ * How a kind's output relates to its input. See `NodeKindDefinition.emits`.
+ *
+ * Every value is TOP-LEVEL by construction — a relation cannot describe a value
+ * nested under a key, which is why `wait` declares a field list instead.
+ */
+type EmitsRelation = "input" | "inputs-merged" | `expression:${string}`;
 /**
  * NodeKindDefinition — declares an authorable node type. Register one
  * via `registerNodeKind()`. Hosts (and the agent bridge) introspect the
@@ -538,6 +545,38 @@ type NodeKindDefinition<TConfig = Record<string, unknown>, TIn = any, TOut = any
      * emits the field keys its author defined, which no static list can know.
      */
     outputShape?: OutputShape<TConfig>;
+    /**
+     * How this kind's output RELATES to its input, when the relation is what is
+     * knowable rather than a field list.
+     *
+     * `outputShape` answers *which fields*; this answers *where they come from*.
+     * Separate because they are separate questions, and one field carrying
+     * sometimes-a-list-sometimes-a-keyword is one a reader handles only in the
+     * form it met first.
+     *
+     * - `"input"` — emits its input unchanged
+     * - `"inputs-merged"` — the union of every input's fields
+     * - `` `expression:${string}` `` — the shape the expression in THAT CONFIG KEY
+     *   names. The key is part of the value because a consumer hardcoding "the
+     *   field called expression" has copied our knowledge one level down, which is
+     *   the thing this removes: `transform` reads `expression`, `variable` reads
+     *   `value`.
+     * - a function of config, for a kind whose relation depends on how it was
+     *   configured.
+     *
+     * **A relation with no destination can only express a TOP-LEVEL merge.**
+     * `wait` returns `{ waited, duration, input }` — it NESTS its input under a
+     * key. `emits: "input"` there would make a reader accept
+     * `{{ in.<any inbound field> }}` at top level, which resolves to nothing at
+     * run time. It keeps a static `outputShape` with an opaque `input` field
+     * instead. Read the executor and ask *merge or nest* before assigning one;
+     * under-claiming is free.
+     *
+     * An `expression` relation is knowable only when the whole config string is a
+     * SINGLE reference. Interpolating several yields a string with no addressable
+     * fields, and a reader that expands it anyway over-permits.
+     */
+    emits?: EmitsRelation | ((config: TConfig) => EmitsRelation | null);
     /** Optional custom body rendered inside the node card. */
     renderBody?: (ctx: RenderBodyContext<TConfig>) => ReactNode;
     /**
@@ -621,4 +660,4 @@ type NodeKindDefinition<TConfig = Record<string, unknown>, TIn = any, TOut = any
     reactive?: boolean;
 };
 
-export { type AvailableVariable as A, type ConfigField as C, type DocumentConfigField as D, type ExpressionConfigField as E, type JsonConfigField as J, type KeyValueConfigField as K, type ManifestProblem as M, type NodeKindDefinition as N, type OutputField as O, type PortSpec as P, type RenderBodyContext as R, type SideEffects as S, type TextConfigField as T, type NodeCategory as a, type CapabilityRequirement as b, type ManifestValidation as c, NODE_MANIFEST_SCHEMA_VERSION as d, type NodePackageManifest as e, type NodeRuntimeId as f, type NodeRuntimeSpec as g, type OutputShape as h, checkCapabilities as i, checkRuntimeSupport as j, type CredentialConfigField as k, type NumberConfigField as l, type RepeaterConfigField as m, type RepeaterRowField as n, type SelectConfigField as o, type SwitchConfigField as p, type TextareaConfigField as q, type ExpressionForm as r, satisfiesRange as s, type ExpressionGrammarHelp as t, availableVariables as u, validateNodeManifest as v, baseVariables as w, describeExpressionGrammar as x, outputFieldsFor as y };
+export { type AvailableVariable as A, type ConfigField as C, type DocumentConfigField as D, type EmitsRelation as E, type JsonConfigField as J, type KeyValueConfigField as K, type ManifestProblem as M, type NodeKindDefinition as N, type OutputField as O, type PortSpec as P, type RenderBodyContext as R, type SideEffects as S, type TextConfigField as T, type NodeCategory as a, type CapabilityRequirement as b, type ManifestValidation as c, NODE_MANIFEST_SCHEMA_VERSION as d, type NodePackageManifest as e, type NodeRuntimeId as f, type NodeRuntimeSpec as g, type OutputShape as h, checkCapabilities as i, checkRuntimeSupport as j, type CredentialConfigField as k, type ExpressionConfigField as l, type NumberConfigField as m, type RepeaterConfigField as n, type RepeaterRowField as o, type SelectConfigField as p, type SwitchConfigField as q, type TextareaConfigField as r, satisfiesRange as s, type ExpressionForm as t, type ExpressionGrammarHelp as u, validateNodeManifest as v, availableVariables as w, baseVariables as x, describeExpressionGrammar as y, outputFieldsFor as z };

package/dist/{types-s643U1Hi.d.ts → types-CLSUZW8c.d.ts}

@@ -485,6 +485,13 @@ type RenderBodyContext<TConfig = unknown> = {
     config: TConfig;
     selected: boolean;
 };
+/**
+ * How a kind's output relates to its input. See `NodeKindDefinition.emits`.
+ *
+ * Every value is TOP-LEVEL by construction — a relation cannot describe a value
+ * nested under a key, which is why `wait` declares a field list instead.
+ */
+type EmitsRelation = "input" | "inputs-merged" | `expression:${string}`;
 /**
  * NodeKindDefinition — declares an authorable node type. Register one
  * via `registerNodeKind()`. Hosts (and the agent bridge) introspect the
@@ -538,6 +545,38 @@ type NodeKindDefinition<TConfig = Record<string, unknown>, TIn = any, TOut = any
      * emits the field keys its author defined, which no static list can know.
      */
     outputShape?: OutputShape<TConfig>;
+    /**
+     * How this kind's output RELATES to its input, when the relation is what is
+     * knowable rather than a field list.
+     *
+     * `outputShape` answers *which fields*; this answers *where they come from*.
+     * Separate because they are separate questions, and one field carrying
+     * sometimes-a-list-sometimes-a-keyword is one a reader handles only in the
+     * form it met first.
+     *
+     * - `"input"` — emits its input unchanged
+     * - `"inputs-merged"` — the union of every input's fields
+     * - `` `expression:${string}` `` — the shape the expression in THAT CONFIG KEY
+     *   names. The key is part of the value because a consumer hardcoding "the
+     *   field called expression" has copied our knowledge one level down, which is
+     *   the thing this removes: `transform` reads `expression`, `variable` reads
+     *   `value`.
+     * - a function of config, for a kind whose relation depends on how it was
+     *   configured.
+     *
+     * **A relation with no destination can only express a TOP-LEVEL merge.**
+     * `wait` returns `{ waited, duration, input }` — it NESTS its input under a
+     * key. `emits: "input"` there would make a reader accept
+     * `{{ in.<any inbound field> }}` at top level, which resolves to nothing at
+     * run time. It keeps a static `outputShape` with an opaque `input` field
+     * instead. Read the executor and ask *merge or nest* before assigning one;
+     * under-claiming is free.
+     *
+     * An `expression` relation is knowable only when the whole config string is a
+     * SINGLE reference. Interpolating several yields a string with no addressable
+     * fields, and a reader that expands it anyway over-permits.
+     */
+    emits?: EmitsRelation | ((config: TConfig) => EmitsRelation | null);
     /** Optional custom body rendered inside the node card. */
     renderBody?: (ctx: RenderBodyContext<TConfig>) => ReactNode;
     /**
@@ -621,4 +660,4 @@ type NodeKindDefinition<TConfig = Record<string, unknown>, TIn = any, TOut = any
     reactive?: boolean;
 };
 
-export { type AvailableVariable as A, type ConfigField as C, type DocumentConfigField as D, type ExpressionConfigField as E, type JsonConfigField as J, type KeyValueConfigField as K, type ManifestProblem as M, type NodeKindDefinition as N, type OutputField as O, type PortSpec as P, type RenderBodyContext as R, type SideEffects as S, type TextConfigField as T, type NodeCategory as a, type CapabilityRequirement as b, type ManifestValidation as c, NODE_MANIFEST_SCHEMA_VERSION as d, type NodePackageManifest as e, type NodeRuntimeId as f, type NodeRuntimeSpec as g, type OutputShape as h, checkCapabilities as i, checkRuntimeSupport as j, type CredentialConfigField as k, type NumberConfigField as l, type RepeaterConfigField as m, type RepeaterRowField as n, type SelectConfigField as o, type SwitchConfigField as p, type TextareaConfigField as q, type ExpressionForm as r, satisfiesRange as s, type ExpressionGrammarHelp as t, availableVariables as u, validateNodeManifest as v, baseVariables as w, describeExpressionGrammar as x, outputFieldsFor as y };
+export { type AvailableVariable as A, type ConfigField as C, type DocumentConfigField as D, type EmitsRelation as E, type JsonConfigField as J, type KeyValueConfigField as K, type ManifestProblem as M, type NodeKindDefinition as N, type OutputField as O, type PortSpec as P, type RenderBodyContext as R, type SideEffects as S, type TextConfigField as T, type NodeCategory as a, type CapabilityRequirement as b, type ManifestValidation as c, NODE_MANIFEST_SCHEMA_VERSION as d, type NodePackageManifest as e, type NodeRuntimeId as f, type NodeRuntimeSpec as g, type OutputShape as h, checkCapabilities as i, checkRuntimeSupport as j, type CredentialConfigField as k, type ExpressionConfigField as l, type NumberConfigField as m, type RepeaterConfigField as n, type RepeaterRowField as o, type SelectConfigField as p, type SwitchConfigField as q, type TextareaConfigField as r, satisfiesRange as s, type ExpressionForm as t, type ExpressionGrammarHelp as u, validateNodeManifest as v, availableVariables as w, baseVariables as x, describeExpressionGrammar as y, outputFieldsFor as z };

package/dist/ux.cjs

@@ -9694,6 +9694,8 @@ var KINDS = [
   // ───────────── Triggers ─────────────
   {
     name: "@particle-academy/manual_trigger",
+    // returns the inputs it was started with
+    emits: "input",
     aliases: ["manual_trigger", "@fancy/manual_trigger"],
     category: "trigger",
     label: "Manual",
@@ -9722,6 +9724,12 @@ var KINDS = [
   },
   {
     name: "@particle-academy/schedule_trigger",
+    outputShape: [
+      { path: "cron", type: "string", description: "The cron expression that fired." },
+      { path: "timezone", type: "string", description: "The timezone it was evaluated in." }
+    ],
+    // merges its inputs into the TOP level beside cron/timezone
+    emits: "inputs-merged",
     aliases: ["schedule_trigger", "@fancy/schedule_trigger"],
     category: "trigger",
     label: "Schedule",
@@ -9909,6 +9917,8 @@ var KINDS = [
   // ───────────── Logic ─────────────
   {
     name: "@particle-academy/branch",
+    // returns its input on the chosen port
+    emits: "input",
     aliases: ["branch", "@fancy/branch"],
     category: "logic",
     label: "Branch",
@@ -9972,6 +9982,8 @@ var KINDS = [
   },
   {
     name: "@particle-academy/switch_case",
+    // returns its input on the chosen port
+    emits: "input",
     aliases: ["switch_case", "@fancy/switch_case"],
     category: "logic",
     label: "Switch",
@@ -10018,6 +10030,12 @@ var KINDS = [
   },
   {
     name: "@particle-academy/merge",
+    // `merge` mode unions every object input at the TOP level; `concat` builds
+    // a list instead, whose elements are not addressable as fields. So concat
+    // declares NOTHING rather than an empty list -- `[]` would claim "emits no
+    // fields" of a kind that emits a list, which is false and refuses every
+    // reference.
+    emits: (config) => (config?.mode ?? "merge") === "concat" ? null : "inputs-merged",
     aliases: ["merge", "@fancy/merge"],
     category: "logic",
     label: "Merge",
@@ -10037,6 +10055,11 @@ var KINDS = [
   },
   {
     name: "@particle-academy/wait",
+    outputShape: [
+      { path: "waited", type: "string", description: "Which wait mode ran." },
+      { path: "duration", type: "number", description: "How long it waited." },
+      { path: "input", type: "unknown", description: "The value that arrived, carried forward." }
+    ],
     aliases: ["wait", "@fancy/wait"],
     category: "logic",
     label: "Wait",
@@ -10055,6 +10078,9 @@ var KINDS = [
   },
   {
     name: "@particle-academy/transform",
+    // Two behaviours: the input unchanged when no expression is configured,
+    // else the shape that expression names. So the RELATION is config-dependent.
+    emits: (config) => (config?.expression ?? "") === "" ? "input" : "expression:expression",
     aliases: ["transform", "@fancy/transform"],
     category: "logic",
     label: "Transform",
@@ -10154,6 +10180,8 @@ var KINDS = [
   },
   {
     name: "@particle-academy/variable",
+    // evaluates the expression in config.value
+    emits: "expression:value",
     aliases: ["variable", "@fancy/variable"],
     category: "data",
     label: "Variable",
@@ -10234,6 +10262,11 @@ var KINDS = [
   },
   {
     name: "@particle-academy/llm_router",
+    outputShape: [
+      { path: "route", type: "string", description: "The port the model chose." },
+      { path: "reason", type: "string", description: "Why the model chose it." },
+      { path: "input", type: "unknown", description: "The value that arrived, carried forward." }
+    ],
     // Every id this node has ever shipped under keeps resolving — MOIC's saved
     // flows carry the bare `llm_branch`.
     aliases: ["llm_router", "llm_branch", "@fancy/llm_branch", "@fancy/llm_router"],
@@ -10372,6 +10405,11 @@ var KINDS = [
   },
   {
     name: "@particle-academy/webhook_out",
+    outputShape: [
+      { path: "sent", type: "boolean", description: "True once the request was made." },
+      { path: "status", type: "number", description: "HTTP status, when the transport reported one." },
+      { path: "response", type: "unknown", description: "The response body, when there was one." }
+    ],
     aliases: ["webhook_out", "@fancy/webhook_out"],
     category: "io",
     label: "Send Webhook",
@@ -10393,6 +10431,8 @@ var KINDS = [
   // ───────────── Human ─────────────
   {
     name: "@particle-academy/human_approval",
+    // returns its input on approved/denied
+    emits: "input",
     aliases: ["human_approval", "@fancy/human_approval"],
     pausesForHuman: "approval",
     category: "human",
@@ -10409,6 +10449,12 @@ var KINDS = [
   },
   {
     name: "@particle-academy/notify",
+    outputShape: [
+      { path: "sent", type: "boolean", description: "True once the message was handed to the channel." },
+      { path: "channel", type: "string", description: "The channel it went to." },
+      { path: "to", type: "string", description: "The recipient." },
+      { path: "message", type: "string", description: "The rendered message." }
+    ],
     aliases: ["notify", "@fancy/notify"],
     category: "human",
     label: "Notify",
@@ -10434,6 +10480,8 @@ var KINDS = [
   // ───────────── Output ─────────────
   {
     name: "@particle-academy/output",
+    // returns its input unchanged
+    emits: "input",
     aliases: ["output", "@fancy/output"],
     category: "output",
     label: "Output",
@@ -10444,6 +10492,10 @@ var KINDS = [
   },
   {
     name: "@particle-academy/log",
+    outputShape: [
+      { path: "logged", type: "string", description: "The message that was written." },
+      { path: "level", type: "string", description: "The level it was written at." }
+    ],
     aliases: ["log", "@fancy/log"],
     category: "output",
     label: "Log",