@particle-academy/fancy-flow 0.45.0 → 0.47.0

package/dist/layout/index.d.cts

@@ -1,4 +1,4 @@
-import { F as FlowGraph, a as FlowNode } from '../types-CMSrWVYM.cjs';
+import { F as FlowGraph, a as FlowNode } from '../types-Jx1TwehV.cjs';
 import '@xyflow/react';
 
 type AutoLayoutDirection = "LR" | "TB" | "RL" | "BT";

package/dist/layout/index.d.ts

@@ -1,4 +1,4 @@
-import { F as FlowGraph, a as FlowNode } from '../types-CMSrWVYM.js';
+import { F as FlowGraph, a as FlowNode } from '../types-Jx1TwehV.js';
 import '@xyflow/react';
 
 type AutoLayoutDirection = "LR" | "TB" | "RL" | "BT";

package/dist/llm/prism.d.cts

@@ -1,5 +1,5 @@
-import { L as LlmClient } from '../capabilities-CYCeIx6I.cjs';
-import '../types-CMSrWVYM.cjs';
+import { L as LlmClient } from '../capabilities-Dmd26aAs.cjs';
+import '../types-Jx1TwehV.cjs';
 import '@xyflow/react';
 
 /**

package/dist/llm/prism.d.ts

@@ -1,5 +1,5 @@
-import { L as LlmClient } from '../capabilities-Brn74URS.js';
-import '../types-CMSrWVYM.js';
+import { L as LlmClient } from '../capabilities-DMUhnyZD.js';
+import '../types-Jx1TwehV.js';
 import '@xyflow/react';
 
 /**

package/dist/llm/vercel-ai.d.cts

@@ -1,6 +1,6 @@
 import { LanguageModel } from 'ai';
-import { a as LlmRouteRequest, L as LlmClient } from '../capabilities-CYCeIx6I.cjs';
-import '../types-CMSrWVYM.cjs';
+import { a as LlmRouteRequest, L as LlmClient } from '../capabilities-Dmd26aAs.cjs';
+import '../types-Jx1TwehV.cjs';
 import '@xyflow/react';
 
 /**

package/dist/llm/vercel-ai.d.ts

@@ -1,6 +1,6 @@
 import { LanguageModel } from 'ai';
-import { a as LlmRouteRequest, L as LlmClient } from '../capabilities-Brn74URS.js';
-import '../types-CMSrWVYM.js';
+import { a as LlmRouteRequest, L as LlmClient } from '../capabilities-DMUhnyZD.js';
+import '../types-Jx1TwehV.js';
 import '@xyflow/react';
 
 /**

package/dist/pause-9iT4tCEV.d.cts

@@ -0,0 +1,96 @@
+/**
+ * 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;
+
+export { LEGACY_PAUSE_PREFIXES as L, type PauseAwaiting as P, PAUSE_PREFIX as a, type PauseSignal as b, decodePause as d, encodePause as e, isPause as i, pauseForHuman as p };

package/dist/pause-9iT4tCEV.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 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;
+
+export { LEGACY_PAUSE_PREFIXES as L, type PauseAwaiting as P, PAUSE_PREFIX as a, type PauseSignal as b, decodePause as d, encodePause as e, isPause as i, pauseForHuman as p };

package/dist/registry/index.d.cts

@@ -1,12 +1,13 @@
-import { N as NodeKindDefinition, j as PortSpec } from '../types-nQOA8jpk.cjs';
-export { C as ConfigField, q as CredentialConfigField, D as DocumentConfigField, E as ExpressionConfigField, J as JsonConfigField, K as KeyValueConfigField, L as LEGACY_PAUSE_PREFIXES, a as NodeCategory, r as NumberConfigField, h as PAUSE_PREFIX, P as PauseAwaiting, i as PauseSignal, R as RenderBodyContext, t as RepeaterConfigField, u as RepeaterRowField, w as SelectConfigField, x as SwitchConfigField, T as TextConfigField, y as TextareaConfigField, m as decodePause, n as encodePause, o as isPause, p as pauseForHuman } from '../types-nQOA8jpk.cjs';
-import { P as PortDescriptor, a as FlowNode, N as NodeExecutor } from '../types-CMSrWVYM.cjs';
+import { N as NodeKindDefinition, P as PortSpec } from '../types--S2Kzx7w.cjs';
+export { C as ConfigField, j as CredentialConfigField, D as DocumentConfigField, E as ExpressionConfigField, J as JsonConfigField, K as KeyValueConfigField, a as NodeCategory, k as NumberConfigField, R as RenderBodyContext, l as RepeaterConfigField, m as RepeaterRowField, n as SelectConfigField, o as SwitchConfigField, T as TextConfigField, p as TextareaConfigField } from '../types--S2Kzx7w.cjs';
+import { P as PortDescriptor, a as FlowNode, N as NodeExecutor } from '../types-Jx1TwehV.cjs';
 import { Connection, Edge, NodeProps, NodeTypes } from '@xyflow/react';
-import { b as LlmRoute } from '../capabilities-CYCeIx6I.cjs';
-export { C as CapabilityId, L as LlmClient, c as LlmRouteChoice, a as LlmRouteRequest, d as WorkflowResolution, e as WorkflowResolutionFailure, W as WorkflowResolver, f as capabilityStatus, g as getLlmClient, h as getWorkflowResolver, i as isResolutionFailure, r as registerLlmClient, j as registerWorkflowResolver } from '../capabilities-CYCeIx6I.cjs';
+import { b as LlmRoute } from '../capabilities-Dmd26aAs.cjs';
+export { C as CapabilityId, L as LlmClient, c as LlmRouteChoice, a as LlmRouteRequest, d as WorkflowResolution, e as WorkflowResolutionFailure, W as WorkflowResolver, f as capabilityStatus, g as getLlmClient, h as getWorkflowResolver, i as isResolutionFailure, r as registerLlmClient, j as registerWorkflowResolver } from '../capabilities-Dmd26aAs.cjs';
+export { L as LEGACY_PAUSE_PREFIXES, a as PAUSE_PREFIX, P as PauseAwaiting, b as PauseSignal, d as decodePause, e as encodePause, i as isPause, p as pauseForHuman } from '../pause-9iT4tCEV.cjs';
 import * as react from 'react';
 import { ComponentType, ReactNode } from 'react';
-export { N as NodeKindPresentation, c as categoryAccent, b as clearNodeKindOverrides, d as defaultConfigFor, g as getNodeKind, k as kindIds, l as listNodeKinds, o as onNodeKindsChanged, e as overrideNodeKind, r as registerNodeKind, a as resolveKindId, v as validateConfig } from '../registry-Budds73w.cjs';
+export { N as NodeKindPresentation, c as categoryAccent, b as clearNodeKindOverrides, d as defaultConfigFor, e as ensureBuiltinKinds, g as getNodeKind, k as kindIds, l as listNodeKinds, o as onNodeKindsChanged, f as overrideNodeKind, r as registerNodeKind, a as resolveKindId, v as validateConfig } from '../registry-CkcSwmfR.cjs';
 
 /**
  * Connection validation — the single rule that decides whether an edge between

package/dist/registry/index.d.ts

@@ -1,12 +1,13 @@
-import { N as NodeKindDefinition, j as PortSpec } from '../types-D6ZSKBly.js';
-export { C as ConfigField, q as CredentialConfigField, D as DocumentConfigField, E as ExpressionConfigField, J as JsonConfigField, K as KeyValueConfigField, L as LEGACY_PAUSE_PREFIXES, a as NodeCategory, r as NumberConfigField, h as PAUSE_PREFIX, P as PauseAwaiting, i as PauseSignal, R as RenderBodyContext, t as RepeaterConfigField, u as RepeaterRowField, w as SelectConfigField, x as SwitchConfigField, T as TextConfigField, y as TextareaConfigField, m as decodePause, n as encodePause, o as isPause, p as pauseForHuman } from '../types-D6ZSKBly.js';
-import { P as PortDescriptor, a as FlowNode, N as NodeExecutor } from '../types-CMSrWVYM.js';
+import { N as NodeKindDefinition, P as PortSpec } from '../types-ChkCRonF.js';
+export { C as ConfigField, j as CredentialConfigField, D as DocumentConfigField, E as ExpressionConfigField, J as JsonConfigField, K as KeyValueConfigField, a as NodeCategory, k as NumberConfigField, R as RenderBodyContext, l as RepeaterConfigField, m as RepeaterRowField, n as SelectConfigField, o as SwitchConfigField, T as TextConfigField, p as TextareaConfigField } from '../types-ChkCRonF.js';
+import { P as PortDescriptor, a as FlowNode, N as NodeExecutor } from '../types-Jx1TwehV.js';
 import { Connection, Edge, NodeProps, NodeTypes } from '@xyflow/react';
-import { b as LlmRoute } from '../capabilities-Brn74URS.js';
-export { C as CapabilityId, L as LlmClient, c as LlmRouteChoice, a as LlmRouteRequest, d as WorkflowResolution, e as WorkflowResolutionFailure, W as WorkflowResolver, f as capabilityStatus, g as getLlmClient, h as getWorkflowResolver, i as isResolutionFailure, r as registerLlmClient, j as registerWorkflowResolver } from '../capabilities-Brn74URS.js';
+import { b as LlmRoute } from '../capabilities-DMUhnyZD.js';
+export { C as CapabilityId, L as LlmClient, c as LlmRouteChoice, a as LlmRouteRequest, d as WorkflowResolution, e as WorkflowResolutionFailure, W as WorkflowResolver, f as capabilityStatus, g as getLlmClient, h as getWorkflowResolver, i as isResolutionFailure, r as registerLlmClient, j as registerWorkflowResolver } from '../capabilities-DMUhnyZD.js';
+export { L as LEGACY_PAUSE_PREFIXES, a as PAUSE_PREFIX, P as PauseAwaiting, b as PauseSignal, d as decodePause, e as encodePause, i as isPause, p as pauseForHuman } from '../pause-9iT4tCEV.js';
 import * as react from 'react';
 import { ComponentType, ReactNode } from 'react';
-export { N as NodeKindPresentation, c as categoryAccent, b as clearNodeKindOverrides, d as defaultConfigFor, g as getNodeKind, k as kindIds, l as listNodeKinds, o as onNodeKindsChanged, e as overrideNodeKind, r as registerNodeKind, a as resolveKindId, v as validateConfig } from '../registry-D0I20HJ3.js';
+export { N as NodeKindPresentation, c as categoryAccent, b as clearNodeKindOverrides, d as defaultConfigFor, e as ensureBuiltinKinds, g as getNodeKind, k as kindIds, l as listNodeKinds, o as onNodeKindsChanged, f as overrideNodeKind, r as registerNodeKind, a as resolveKindId, v as validateConfig } from '../registry-Bt55f63_.js';
 
 /**
  * Connection validation — the single rule that decides whether an edge between

package/dist/{registry-Budds73w.d.cts → registry-Bt55f63_.d.ts}

@@ -1,5 +1,24 @@
-import { N as NodeKindDefinition } from './types-nQOA8jpk.cjs';
+import { N as NodeKindDefinition } from './types-ChkCRonF.js';
 
+/**
+ * Put the builtin kit in the registry before anyone reads or writes it.
+ *
+ * Registration used to be a bare `registerBuiltinKinds()` in `src/index.ts`, so
+ * it fired ONLY as an import side effect of that one entry. Every other route in
+ * — the `/engine` and `/registry` subpaths, or a root import that TypeScript
+ * erases because it only took types — got an empty registry, and an empty
+ * registry is silent: `getNodeKind()` returns null, `FlowViewer` falls through
+ * its title chain, and the canvas shows `@particle-academy/llm_call` where a
+ * name belongs.
+ *
+ * Doing it here instead means correctness no longer depends on which entry a
+ * consumer imported, or on a bundler agreeing to keep a top-level statement.
+ *
+ * The flag is set BEFORE the call so a listener that reads the registry from
+ * inside `notify()` cannot recurse. `registerNodeKind` ensures too, so builtins
+ * are always in place before a host registers over one of them.
+ */
+declare function ensureBuiltinKinds(): void;
 /**
  * The presentation fields a consumer may override on someone else's node kind.
  *
@@ -82,4 +101,4 @@ declare function validateConfig(kind: NodeKindDefinition, config: Record<string,
 /** Default accents per category. */
 declare function categoryAccent(category: string): string;
 
-export { type NodeKindPresentation as N, resolveKindId as a, clearNodeKindOverrides as b, categoryAccent as c, defaultConfigFor as d, overrideNodeKind as e, getNodeKind as g, kindIds as k, listNodeKinds as l, onNodeKindsChanged as o, registerNodeKind as r, validateConfig as v };
+export { type NodeKindPresentation as N, resolveKindId as a, clearNodeKindOverrides as b, categoryAccent as c, defaultConfigFor as d, ensureBuiltinKinds as e, overrideNodeKind as f, getNodeKind as g, kindIds as k, listNodeKinds as l, onNodeKindsChanged as o, registerNodeKind as r, validateConfig as v };

package/dist/{registry-D0I20HJ3.d.ts → registry-CkcSwmfR.d.cts}

@@ -1,5 +1,24 @@
-import { N as NodeKindDefinition } from './types-D6ZSKBly.js';
+import { N as NodeKindDefinition } from './types--S2Kzx7w.cjs';
 
+/**
+ * Put the builtin kit in the registry before anyone reads or writes it.
+ *
+ * Registration used to be a bare `registerBuiltinKinds()` in `src/index.ts`, so
+ * it fired ONLY as an import side effect of that one entry. Every other route in
+ * — the `/engine` and `/registry` subpaths, or a root import that TypeScript
+ * erases because it only took types — got an empty registry, and an empty
+ * registry is silent: `getNodeKind()` returns null, `FlowViewer` falls through
+ * its title chain, and the canvas shows `@particle-academy/llm_call` where a
+ * name belongs.
+ *
+ * Doing it here instead means correctness no longer depends on which entry a
+ * consumer imported, or on a bundler agreeing to keep a top-level statement.
+ *
+ * The flag is set BEFORE the call so a listener that reads the registry from
+ * inside `notify()` cannot recurse. `registerNodeKind` ensures too, so builtins
+ * are always in place before a host registers over one of them.
+ */
+declare function ensureBuiltinKinds(): void;
 /**
  * The presentation fields a consumer may override on someone else's node kind.
  *
@@ -82,4 +101,4 @@ declare function validateConfig(kind: NodeKindDefinition, config: Record<string,
 /** Default accents per category. */
 declare function categoryAccent(category: string): string;
 
-export { type NodeKindPresentation as N, resolveKindId as a, clearNodeKindOverrides as b, categoryAccent as c, defaultConfigFor as d, overrideNodeKind as e, getNodeKind as g, kindIds as k, listNodeKinds as l, onNodeKindsChanged as o, registerNodeKind as r, validateConfig as v };
+export { type NodeKindPresentation as N, resolveKindId as a, clearNodeKindOverrides as b, categoryAccent as c, defaultConfigFor as d, ensureBuiltinKinds as e, overrideNodeKind as f, getNodeKind as g, kindIds as k, listNodeKinds as l, onNodeKindsChanged as o, registerNodeKind as r, validateConfig as v };