@particle-academy/fancy-flow 0.44.0 → 0.46.0

package/dist/runtime.js

@@ -1,7 +1,7 @@
-export { applyOutputsToNodes, applyStatusesToNodes, createHistory, useFlowHistory, useFlowRun, useFlowState } from './chunk-A6RFLGWV.js';
-export { runCohort } from './chunk-QZTGV3ZL.js';
+export { applyOutputsToNodes, applyStatusesToNodes, createHistory, useFlowHistory, useFlowRun, useFlowState } from './chunk-MH4ZW4DJ.js';
+export { runCohort } from './chunk-P5SYH6M6.js';
 import './chunk-OWENS2H5.js';
-export { runFlow } from './chunk-VLATLVGH.js';
+export { RunIdentity, escapeSegment, runFlow } from './chunk-L43CWD63.js';
 import './chunk-TITD5W4Y.js';
 import './chunk-PVROYW7C.js';
 //# sourceMappingURL=runtime.js.map

package/dist/schema/index.d.cts

@@ -1,4 +1,4 @@
-import { P as PortDescriptor, F as FlowGraph } from '../types-sOmpCitB.cjs';
+import { P as PortDescriptor, F as FlowGraph } from '../types-Jx1TwehV.cjs';
 import '@xyflow/react';
 
 /** Schema version. Bump on breaking shape changes; add migrations as needed. */

package/dist/schema/index.d.ts

@@ -1,4 +1,4 @@
-import { P as PortDescriptor, F as FlowGraph } from '../types-sOmpCitB.js';
+import { P as PortDescriptor, F as FlowGraph } from '../types-Jx1TwehV.js';
 import '@xyflow/react';
 
 /** Schema version. Bump on breaking shape changes; add migrations as needed. */

package/dist/screens.d.cts

@@ -1,6 +1,6 @@
-export { F as FlowNodeStatus, a as FlowViewer, b as FlowViewerClassNames, c as FlowViewerProps } from './FlowViewer-nLqo7s2E.cjs';
+export { F as FlowNodeStatus, a as FlowViewer, b as FlowViewerClassNames, c as FlowViewerProps } from './FlowViewer-CY3_vHSg.cjs';
 import 'react';
-import './types-sOmpCitB.cjs';
+import './types-Jx1TwehV.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-C4QAVgWv.js';
+export { F as FlowNodeStatus, a as FlowViewer, b as FlowViewerClassNames, c as FlowViewerProps } from './FlowViewer-DGW6t-80.js';
 import 'react';
-import './types-sOmpCitB.js';
+import './types-Jx1TwehV.js';
 import '@xyflow/react';
 
 /**

package/dist/screens.js

@@ -1,13 +1,13 @@
-import { FlowViewer } from './chunk-DHUFUDEX.js';
-export { FlowViewer } from './chunk-DHUFUDEX.js';
-import './chunk-WBXGZVLB.js';
+import { FlowViewer } from './chunk-HFUBVT7W.js';
+export { FlowViewer } from './chunk-HFUBVT7W.js';
+import './chunk-RMU6YCIQ.js';
+import './chunk-F5RPRB7A.js';
 import './chunk-OWENS2H5.js';
-import './chunk-UEOE6B52.js';
 import './chunk-USL4FMFU.js';
-import './chunk-VLATLVGH.js';
+import './chunk-UEOE6B52.js';
+import './chunk-L43CWD63.js';
 import './chunk-TITD5W4Y.js';
 import './chunk-PVROYW7C.js';
-import './chunk-F5RPRB7A.js';
 import { registerSchemaComponents } from '@particle-academy/fancy-screens';
 
 function registerFlowSchema() {

package/dist/{types-JViq8reb.d.ts → types--S2Kzx7w.d.cts}

@@ -1,6 +1,7 @@
 import { ReactNode, ComponentType } from 'react';
-import { F as FlowGraph, b as FlowNode, P as PortDescriptor, N as NodeExecutor } from './types-sOmpCitB.js';
+import { F as FlowGraph, a as FlowNode, P as PortDescriptor, N as NodeExecutor } from './types-Jx1TwehV.cjs';
 import { NodeProps } from '@xyflow/react';
+import { P as PauseAwaiting } from './pause-9iT4tCEV.cjs';
 
 /**
  * What a node emits, described well enough for an author to reference it.
@@ -71,101 +72,6 @@ type ExpressionGrammarHelp = {
  */
 declare function describeExpressionGrammar(): ExpressionGrammarHelp;
 
-/**
- * The human-pause contract.
- *
- * A workflow that waits for a person is not an error, but it travels the same
- * channel as one: the executor aborts, the engine records a reason string, and
- * the durable runner decides whether that string meant "failed" or "waiting".
- *
- * That seam existed before this module, as two `str_starts_with` checks in the
- * Laravel run job against constants owned by two BUILTIN executors. It worked,
- * and it was invisible: a third-party human-input node had no way to announce
- * that it pauses, and nothing stopped a refactor from removing the mechanism
- * out from under published packages. Reported by the MOIC Suite consumer, who
- * needed exactly that and had to reach for a private constant to get it.
- *
- * So the encoding is now public, typed, and versioned by prefix rather than
- * implied. The wire format stays a plain string on purpose — it survives the
- * existing abort → `RunResult.error` path unchanged, crosses a queue boundary,
- * and decodes identically in PHP, none of which a thrown class would do.
- *
- * @see decodePause — the one function a durable runner needs.
- */
-/**
- * What the run is waiting for.
- *
- * `approval` and `input` are the shapes both runtimes ship. The type stays open
- * because the whole point is that a marketplace node can define its own —
- * a signature step, a payment confirmation, a review queue — and a runner that
- * does not recognise one should report it rather than guess.
- */
-type PauseAwaiting = "approval" | "input" | (string & {});
-/** A run halted, waiting for a person. */
-type PauseSignal = {
-    /** The node that paused — where a submission gets injected on resume. */
-    nodeId: string;
-    awaiting: PauseAwaiting;
-    /**
-     * Kind-supplied context for whoever renders the wait — a form schema, the
-     * question being asked, a diff to approve. Must be JSON-serializable: it
-     * crosses a queue boundary and, for durable runs, a database column.
-     */
-    detail?: unknown;
-};
-/** Marks a reason string as a pause rather than a failure. */
-declare const PAUSE_PREFIX = "fancy-flow:pause:";
-/**
- * Reason prefixes shipped before this contract, kept decodable forever.
- *
- * These are what `DurableApprovalExecutor` and `DurableUserInputExecutor`
- * emitted, and they are written into the `error` column of every run that
- * paused under an older version. Dropping them would strand those runs
- * mid-flight — a resume path that only works for new runs is not a resume path.
- */
-declare const LEGACY_PAUSE_PREFIXES: ReadonlyArray<readonly [string, PauseAwaiting]>;
-/**
- * Encode a pause as the reason string an executor aborts with.
- *
- * The payload is JSON rather than delimited fields because a node id may
- * contain a colon, and a positional encoding that breaks on user data is the
- * kind of bug that only shows up in someone else's graph.
- */
-declare function encodePause(signal: PauseSignal): string;
-/**
- * Decode a run's error reason into a pause, or null if it was a real failure.
- *
- * This is the whole contract from a runner's side: call it on `result.error`,
- * and if it returns non-null, persist the run as waiting on `signal.nodeId`
- * instead of failing it. Accepts the legacy prefixes, so a runner written
- * against this handles runs that paused under an older version.
- */
-declare function decodePause(reason: string | null | undefined): PauseSignal | null;
-/** True when a run's error reason is actually a pause. */
-declare function isPause(reason: string | null | undefined): boolean;
-/**
- * Abort the current node as a pause.
- *
- * Called from inside an executor with its own context. Node authors should
- * reach for this rather than hand-encoding a reason, so the format stays ours
- * to change:
- *
- * ```ts
- * const values = ctx.inputs.values;
- * if (values === undefined) pauseForHuman(ctx, "input", { fields });
- * return values;
- * ```
- *
- * Note the `undefined` check — an empty submission (`{}`) is a real answer and
- * must resume. Truthiness here pauses forever on an empty form.
- */
-declare function pauseForHuman(ctx: {
-    node: {
-        id: string;
-    };
-    abort: (reason?: string) => never;
-}, awaiting: PauseAwaiting, detail?: unknown): never;
-
 /**
  * The node package manifest — what a marketplace node declares about itself.
  *
@@ -715,4 +621,4 @@ type NodeKindDefinition<TConfig = Record<string, unknown>, TIn = any, TOut = any
     reactive?: boolean;
 };
 
-export { type AvailableVariable as A, type ExpressionGrammarHelp as B, type CapabilityRequirement as C, type DocumentConfigField as D, type ExpressionConfigField as E, type OutputShape as F, availableVariables as G, baseVariables as H, describeExpressionGrammar as I, type JsonConfigField as J, type KeyValueConfigField as K, LEGACY_PAUSE_PREFIXES as L, type ManifestProblem as M, NODE_MANIFEST_SCHEMA_VERSION as N, type OutputField as O, type PauseAwaiting as P, outputFieldsFor as Q, type RenderBodyContext as R, type SideEffects as S, type TextConfigField as T, type ConfigField as a, type ManifestValidation as b, type NodeCategory as c, type NodeKindDefinition as d, type NodePackageManifest as e, type NodeRuntimeId as f, type NodeRuntimeSpec as g, PAUSE_PREFIX as h, type PauseSignal as i, type PortSpec as j, checkCapabilities as k, checkRuntimeSupport as l, decodePause as m, encodePause as n, isPause as o, pauseForHuman as p, type CredentialConfigField as q, type NumberConfigField as r, satisfiesRange as s, type RepeaterConfigField as t, type RepeaterRowField as u, validateNodeManifest as v, type SelectConfigField as w, type SwitchConfigField as x, type TextareaConfigField as y, type ExpressionForm as z };
+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, checkCapabilities as h, checkRuntimeSupport as i, type CredentialConfigField as j, type NumberConfigField as k, type RepeaterConfigField as l, type RepeaterRowField as m, type SelectConfigField as n, type SwitchConfigField as o, type TextareaConfigField as p, type ExpressionForm as q, type ExpressionGrammarHelp as r, satisfiesRange as s, type OutputShape as t, availableVariables as u, validateNodeManifest as v, baseVariables as w, describeExpressionGrammar as x, outputFieldsFor as y };

package/dist/{types-B78Rm69S.d.cts → types-ChkCRonF.d.ts}

@@ -1,6 +1,7 @@
 import { ReactNode, ComponentType } from 'react';
-import { F as FlowGraph, b as FlowNode, P as PortDescriptor, N as NodeExecutor } from './types-sOmpCitB.cjs';
+import { F as FlowGraph, a as FlowNode, P as PortDescriptor, N as NodeExecutor } from './types-Jx1TwehV.js';
 import { NodeProps } from '@xyflow/react';
+import { P as PauseAwaiting } from './pause-9iT4tCEV.js';
 
 /**
  * What a node emits, described well enough for an author to reference it.
@@ -71,101 +72,6 @@ type ExpressionGrammarHelp = {
  */
 declare function describeExpressionGrammar(): ExpressionGrammarHelp;
 
-/**
- * The human-pause contract.
- *
- * A workflow that waits for a person is not an error, but it travels the same
- * channel as one: the executor aborts, the engine records a reason string, and
- * the durable runner decides whether that string meant "failed" or "waiting".
- *
- * That seam existed before this module, as two `str_starts_with` checks in the
- * Laravel run job against constants owned by two BUILTIN executors. It worked,
- * and it was invisible: a third-party human-input node had no way to announce
- * that it pauses, and nothing stopped a refactor from removing the mechanism
- * out from under published packages. Reported by the MOIC Suite consumer, who
- * needed exactly that and had to reach for a private constant to get it.
- *
- * So the encoding is now public, typed, and versioned by prefix rather than
- * implied. The wire format stays a plain string on purpose — it survives the
- * existing abort → `RunResult.error` path unchanged, crosses a queue boundary,
- * and decodes identically in PHP, none of which a thrown class would do.
- *
- * @see decodePause — the one function a durable runner needs.
- */
-/**
- * What the run is waiting for.
- *
- * `approval` and `input` are the shapes both runtimes ship. The type stays open
- * because the whole point is that a marketplace node can define its own —
- * a signature step, a payment confirmation, a review queue — and a runner that
- * does not recognise one should report it rather than guess.
- */
-type PauseAwaiting = "approval" | "input" | (string & {});
-/** A run halted, waiting for a person. */
-type PauseSignal = {
-    /** The node that paused — where a submission gets injected on resume. */
-    nodeId: string;
-    awaiting: PauseAwaiting;
-    /**
-     * Kind-supplied context for whoever renders the wait — a form schema, the
-     * question being asked, a diff to approve. Must be JSON-serializable: it
-     * crosses a queue boundary and, for durable runs, a database column.
-     */
-    detail?: unknown;
-};
-/** Marks a reason string as a pause rather than a failure. */
-declare const PAUSE_PREFIX = "fancy-flow:pause:";
-/**
- * Reason prefixes shipped before this contract, kept decodable forever.
- *
- * These are what `DurableApprovalExecutor` and `DurableUserInputExecutor`
- * emitted, and they are written into the `error` column of every run that
- * paused under an older version. Dropping them would strand those runs
- * mid-flight — a resume path that only works for new runs is not a resume path.
- */
-declare const LEGACY_PAUSE_PREFIXES: ReadonlyArray<readonly [string, PauseAwaiting]>;
-/**
- * Encode a pause as the reason string an executor aborts with.
- *
- * The payload is JSON rather than delimited fields because a node id may
- * contain a colon, and a positional encoding that breaks on user data is the
- * kind of bug that only shows up in someone else's graph.
- */
-declare function encodePause(signal: PauseSignal): string;
-/**
- * Decode a run's error reason into a pause, or null if it was a real failure.
- *
- * This is the whole contract from a runner's side: call it on `result.error`,
- * and if it returns non-null, persist the run as waiting on `signal.nodeId`
- * instead of failing it. Accepts the legacy prefixes, so a runner written
- * against this handles runs that paused under an older version.
- */
-declare function decodePause(reason: string | null | undefined): PauseSignal | null;
-/** True when a run's error reason is actually a pause. */
-declare function isPause(reason: string | null | undefined): boolean;
-/**
- * Abort the current node as a pause.
- *
- * Called from inside an executor with its own context. Node authors should
- * reach for this rather than hand-encoding a reason, so the format stays ours
- * to change:
- *
- * ```ts
- * const values = ctx.inputs.values;
- * if (values === undefined) pauseForHuman(ctx, "input", { fields });
- * return values;
- * ```
- *
- * Note the `undefined` check — an empty submission (`{}`) is a real answer and
- * must resume. Truthiness here pauses forever on an empty form.
- */
-declare function pauseForHuman(ctx: {
-    node: {
-        id: string;
-    };
-    abort: (reason?: string) => never;
-}, awaiting: PauseAwaiting, detail?: unknown): never;
-
 /**
  * The node package manifest — what a marketplace node declares about itself.
  *
@@ -715,4 +621,4 @@ type NodeKindDefinition<TConfig = Record<string, unknown>, TIn = any, TOut = any
     reactive?: boolean;
 };
 
-export { type AvailableVariable as A, type ExpressionGrammarHelp as B, type CapabilityRequirement as C, type DocumentConfigField as D, type ExpressionConfigField as E, type OutputShape as F, availableVariables as G, baseVariables as H, describeExpressionGrammar as I, type JsonConfigField as J, type KeyValueConfigField as K, LEGACY_PAUSE_PREFIXES as L, type ManifestProblem as M, NODE_MANIFEST_SCHEMA_VERSION as N, type OutputField as O, type PauseAwaiting as P, outputFieldsFor as Q, type RenderBodyContext as R, type SideEffects as S, type TextConfigField as T, type ConfigField as a, type ManifestValidation as b, type NodeCategory as c, type NodeKindDefinition as d, type NodePackageManifest as e, type NodeRuntimeId as f, type NodeRuntimeSpec as g, PAUSE_PREFIX as h, type PauseSignal as i, type PortSpec as j, checkCapabilities as k, checkRuntimeSupport as l, decodePause as m, encodePause as n, isPause as o, pauseForHuman as p, type CredentialConfigField as q, type NumberConfigField as r, satisfiesRange as s, type RepeaterConfigField as t, type RepeaterRowField as u, validateNodeManifest as v, type SelectConfigField as w, type SwitchConfigField as x, type TextareaConfigField as y, type ExpressionForm as z };
+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, checkCapabilities as h, checkRuntimeSupport as i, type CredentialConfigField as j, type NumberConfigField as k, type RepeaterConfigField as l, type RepeaterRowField as m, type SelectConfigField as n, type SwitchConfigField as o, type TextareaConfigField as p, type ExpressionForm as q, type ExpressionGrammarHelp as r, satisfiesRange as s, type OutputShape as t, availableVariables as u, validateNodeManifest as v, baseVariables as w, describeExpressionGrammar as x, outputFieldsFor as y };

package/dist/types-Jx1TwehV.d.cts

@@ -0,0 +1,247 @@
+import { Node, Edge } from '@xyflow/react';
+
+/**
+ * Who is running, which step this is, and how many times it has been tried.
+ *
+ * ## Why an engine needs this at all
+ *
+ * A node that WRITES to somebody else's system — charge a card, send a message,
+ * open a pull request — can only survive a retry if the retry carries the same
+ * idempotency key the first attempt did. Otherwise the provider treats the
+ * second call as a new request and the customer is charged twice.
+ *
+ * Until this existed the executor context was `{ node, inputs, emit, abort }`,
+ * which is not enough to derive one. Both obvious fallbacks are worse than
+ * sending no key at all:
+ *
+ * - **the node id alone** is stable across retries, and also across RUNS — two
+ *   legitimate payments share a key and the provider silently collapses the
+ *   second into the first. A payment that never happened, reported as success;
+ * - **a fresh random value** is unique per run, and also per ATTEMPT — a retry
+ *   creates a second charge, which is the thing being avoided.
+ *
+ * ## What actually identifies a step
+ *
+ * Not `(run, node)`. A node legitimately executes more than once inside one
+ * run: once per subflow invocation, once per iteration of a loop an executor
+ * drives itself. `(run, node)` would give every one of those the same key, and
+ * a provider would honour exactly one of them.
+ *
+ * So a step is identified by the **path of invocations that led to it**, plus
+ * an optional **occurrence** for repetition at the same level:
+ *
+ * ```text
+ * runKey ":" segment ("/" segment)*        segment := escape(id) ["#" occurrence]
+ * ```
+ *
+ * And the part that is easy to get backwards: **`attempt` is NOT in the key.**
+ * It is carried here for logging and for {@link RunIdentity.isReplaySafe}, and
+ * putting it in the key would restore the exact bug the key exists to prevent.
+ *
+ * Pinned cross-runtime by `shared/flow-run-identity` in
+ * `@particle-academy/fancy-conformance`.
+ */
+/** The wire shape — what a queue job payload carries. */
+type RunIdentityJson = {
+    runKey: string;
+    path?: string[];
+    attempt?: number;
+    firstAttemptAt?: string;
+};
+/**
+ * Escape one segment so the composition is injective.
+ *
+ * `%` FIRST, or the escaping is not reversible: escaping `/` before `%` turns a
+ * literal `a%2Fb` into the same text as the escaped form of `a/b`, which is the
+ * collision this exists to prevent, reintroduced by its own fix.
+ */
+declare function escapeSegment(value: string): string;
+/**
+ * A run, a position inside it, and how many times this position has been tried.
+ *
+ * Immutable. {@link descend} returns a new identity rather than mutating, so an
+ * executor cannot change what its siblings see.
+ */
+declare class RunIdentity {
+    /** Stable for the whole run: same across retries, resumes, workers and hosts. */
+    readonly runKey: string;
+    /**
+     * Enclosing invocation segments, outermost first, ALREADY RENDERED.
+     *
+     * Empty at the top level. A subflow pushes the invoking node's id; an
+     * executor that loops pushes `id#i`.
+     */
+    readonly path: readonly string[];
+    /**
+     * 1-based attempt of THIS logical step. Never part of the key.
+     *
+     * The durable driver sets it from the node's claim row, which is exact. A
+     * plain in-process `runFlow` gets whatever the host passed, which is
+     * run-scoped and therefore conservative — see `isReplaySafe`.
+     */
+    readonly attempt: number;
+    /** ISO-8601 UTC instant of attempt 1 of this step. */
+    readonly firstAttemptAt: string;
+    constructor(runKey: string, path?: readonly string[], attempt?: number, firstAttemptAt?: string);
+    /**
+     * 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: string, occurrence?: number | null): string;
+    /**
+     * 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: string, occurrence?: number | null): RunIdentity;
+    /** A copy on a different attempt, first-attempt clock preserved. */
+    withAttempt(attempt: number, firstAttemptAt?: string): RunIdentity;
+    /**
+     * 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: number | null | undefined, now?: Date | string): boolean;
+    toJSON(): Required<RunIdentityJson>;
+    /** Rebuild from a queue payload. */
+    static from(value: RunIdentity | RunIdentityJson | string): RunIdentity;
+}
+
+/**
+ * Public domain types for fancy-flow. Built-in nodes are layered on top of
+ * @xyflow/react's `Node` so consumers can mix custom xyflow nodes alongside
+ * the kit. Edges remain xyflow's standard `Edge`.
+ */
+
+type FlowNodeKind = "trigger" | "action" | "decision" | "output" | "note" | "subgraph";
+/** Status surfaced on the node while a run is in progress. */
+type NodeRunStatus = "idle" | "queued" | "running" | "done" | "error";
+/** Port description on a node. Ports are visual handles xyflow can connect. */
+type PortDescriptor = {
+    id: string;
+    label?: string;
+    /** Optional logical type for hosts that want to validate connections. */
+    type?: string;
+};
+/** Common shape every kit node carries in its `data` slot. */
+type BaseNodeData = {
+    label: string;
+    description?: string;
+    /** Free-form configuration the host owns (form values, code, parameters). */
+    config?: Record<string, unknown>;
+    /** Set by the runner; hosts shouldn't edit this directly. */
+    status?: NodeRunStatus;
+    /** Optional human-readable status detail (e.g. error message, current step). */
+    statusText?: string;
+    /** Per-node accent override, e.g. for theming a custom subclass. */
+    color?: string;
+    /** Input ports rendered on the node. Defaults vary by kind. */
+    inputs?: PortDescriptor[];
+    /** Output ports rendered on the node. Defaults vary by kind. */
+    outputs?: PortDescriptor[];
+};
+type TriggerNodeData = BaseNodeData & {
+    kind: "trigger";
+};
+type ActionNodeData = BaseNodeData & {
+    kind: "action";
+};
+type DecisionNodeData = BaseNodeData & {
+    kind: "decision";
+};
+type OutputNodeData = BaseNodeData & {
+    kind: "output";
+};
+type NoteNodeData = BaseNodeData & {
+    kind: "note";
+    body?: string;
+};
+type SubgraphNodeData = BaseNodeData & {
+    kind: "subgraph";
+    /** Ids of the nodes contained in this subgraph. */
+    childIds?: string[];
+    /** Whether the subgraph is shown collapsed (default true — children hidden). */
+    collapsed?: boolean;
+};
+type FlowNodeData = TriggerNodeData | ActionNodeData | DecisionNodeData | OutputNodeData | NoteNodeData | SubgraphNodeData;
+type FlowNode = Node<FlowNodeData>;
+type FlowEdge = Edge;
+/** A serializable graph — what hosts persist, what agents read/write. */
+type FlowGraph = {
+    nodes: FlowNode[];
+    edges: FlowEdge[];
+};
+/** Per-node executor signature. Inputs are keyed by input-port id. */
+type NodeExecutor<TIn = Record<string, unknown>, TOut = unknown> = (ctx: {
+    node: FlowNode;
+    inputs: TIn;
+    /** Stops the run if called. */
+    abort: (reason?: string) => never;
+    /** Lets the executor stream status updates and partial outputs. */
+    emit: (event: RunEvent) => void;
+    /**
+     * How deep this run is nested. 0 for a top-level run; `subflow` passes
+     * depth + 1 to its child, so runaway recursion can be reported by name
+     * rather than as a stack overflow.
+     */
+    depth?: number;
+    /**
+     * Who is running, and which attempt of which step this is.
+     *
+     * `ctx.run.stepKey(ctx.node.id)` is the idempotency key for a node that
+     * writes to somebody else's system — stable across retries of this step,
+     * distinct for every other execution of the same node.
+     *
+     * `undefined` when the host supplied no identity, and that is a real
+     * answer: a write with no key must decline or accept one attempt, never
+     * invent a key. See `RunIdentity`.
+     */
+    run?: RunIdentity;
+}) => Promise<TOut> | TOut;
+type ExecutorRegistry = Partial<Record<FlowNodeKind | string, NodeExecutor>>;
+type RunEvent = {
+    type: "node-status";
+    nodeId: string;
+    status: NodeRunStatus;
+    text?: string;
+} | {
+    type: "node-output";
+    nodeId: string;
+    portId: string;
+    value: unknown;
+} | {
+    type: "log";
+    nodeId?: string;
+    level: "info" | "warn" | "error";
+    message: string;
+    detail?: unknown;
+} | {
+    type: "run-start";
+} | {
+    type: "run-end";
+    ok: boolean;
+} | {
+    type: "run-error";
+    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 };