@particle-academy/fancy-flow 0.29.0 → 0.30.0

package/dist/registry-qv4gRiuQ.d.cts

@@ -0,0 +1,45 @@
+import { N as NodeKindDefinition } from './types-DEmDSByY.cjs';
+
+/**
+ * registerNodeKind — install a node kind in the global registry. Returns
+ * an `unregister` function. Calling with the same name replaces the prior
+ * registration (handy for HMR).
+ *
+ * A kind's `name` is its CANONICAL id and is what gets written into saved
+ * documents. Publish namespaced (`@fancy/llm_branch`, `@acme/salesforce_upsert`)
+ * and list any previous bare names in `aliases`, so graphs saved before the
+ * rename keep resolving.
+ */
+declare function registerNodeKind<TC = any, TI = any, TO = any>(definition: NodeKindDefinition<TC, TI, TO>): () => void;
+/**
+ * Resolve any id — canonical or alias — to the canonical one, or null.
+ *
+ * `kind` is persisted inside every saved graph, so a bare name that two
+ * packages could both claim is unfixable after the fact: the ambiguous string
+ * is already in the document. Canonical ids are namespaced; aliases exist so
+ * documents written before namespacing keep opening.
+ */
+declare function resolveKindId(id: string): string | null;
+/** Get a single kind by canonical id or alias, or null. */
+declare function getNodeKind(name: string): NodeKindDefinition | null;
+/** Every id a kind answers to — canonical first. Used to key node-type maps. */
+declare function kindIds(kind: NodeKindDefinition): string[];
+/** List every registered kind, optionally filtered by category. */
+declare function listNodeKinds(category?: string): NodeKindDefinition[];
+/** Subscribe to registry changes. Returns an unsubscribe function. */
+declare function onNodeKindsChanged(listener: () => void): () => void;
+/** Fill in defaults from a kind's configSchema for newly-created nodes. */
+declare function defaultConfigFor(kind: NodeKindDefinition): Record<string, unknown>;
+/**
+ * Validate a config object against a kind's schema. Returns an array of
+ * issues (empty = valid). Validation is intentionally light — type
+ * coercion + required-field checks. Hosts can layer Zod / Ajv on top.
+ */
+declare function validateConfig(kind: NodeKindDefinition, config: Record<string, unknown>): Array<{
+    key: string;
+    message: string;
+}>;
+/** Default accents per category. */
+declare function categoryAccent(category: string): string;
+
+export { resolveKindId as a, categoryAccent as c, defaultConfigFor as d, getNodeKind as g, kindIds as k, listNodeKinds as l, onNodeKindsChanged as o, registerNodeKind as r, validateConfig as v };

package/dist/{types-BGtR3k9J.d.ts → types-Bj_ZHwqG.d.ts}

@@ -1,7 +1,101 @@
 import { ReactNode, ComponentType } from 'react';
 import { NodeProps } from '@xyflow/react';
 import { P as PortDescriptor, N as NodeExecutor, a as FlowNode } from './types-CMSrWVYM.js';
-import { P as PauseAwaiting } from './pause-9iT4tCEV.js';
+
+/**
+ * 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;
 
 /** Categories used by the palette for grouping. */
 type NodeCategory = "trigger" | "logic" | "data" | "ai" | "io" | "human" | "output" | "layout" | "annotation" | "custom";
@@ -280,4 +374,4 @@ type NodeKindDefinition<TConfig = Record<string, unknown>, TIn = any, TOut = any
     reactive?: boolean;
 };
 
-export type { ConfigField as C, DocumentConfigField as D, ExpressionConfigField as E, JsonConfigField as J, KeyValueConfigField as K, NodeCategory as N, PortSpec as P, RenderBodyContext as R, SelectConfigField as S, TextConfigField as T, NodeKindDefinition as a, CredentialConfigField as b, NumberConfigField as c, RepeaterConfigField as d, RepeaterRowField as e, SwitchConfigField as f, TextareaConfigField as g };
+export { type ConfigField as C, type DocumentConfigField as D, type ExpressionConfigField as E, type JsonConfigField as J, type KeyValueConfigField as K, LEGACY_PAUSE_PREFIXES as L, type NodeKindDefinition as N, type PauseAwaiting as P, type RenderBodyContext as R, type SelectConfigField as S, type TextConfigField as T, type NodeCategory as a, PAUSE_PREFIX as b, type PauseSignal as c, type PortSpec as d, decodePause as e, encodePause as f, type CredentialConfigField as g, type NumberConfigField as h, isPause as i, type RepeaterConfigField as j, type RepeaterRowField as k, type SwitchConfigField as l, type TextareaConfigField as m, pauseForHuman as p };

package/dist/{types-B_pxRqfw.d.cts → types-DEmDSByY.d.cts}

@@ -1,7 +1,101 @@
 import { ReactNode, ComponentType } from 'react';
 import { NodeProps } from '@xyflow/react';
 import { P as PortDescriptor, N as NodeExecutor, a as FlowNode } from './types-CMSrWVYM.cjs';
-import { P as PauseAwaiting } from './pause-9iT4tCEV.cjs';
+
+/**
+ * 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;
 
 /** Categories used by the palette for grouping. */
 type NodeCategory = "trigger" | "logic" | "data" | "ai" | "io" | "human" | "output" | "layout" | "annotation" | "custom";
@@ -280,4 +374,4 @@ type NodeKindDefinition<TConfig = Record<string, unknown>, TIn = any, TOut = any
     reactive?: boolean;
 };
 
-export type { ConfigField as C, DocumentConfigField as D, ExpressionConfigField as E, JsonConfigField as J, KeyValueConfigField as K, NodeCategory as N, PortSpec as P, RenderBodyContext as R, SelectConfigField as S, TextConfigField as T, NodeKindDefinition as a, CredentialConfigField as b, NumberConfigField as c, RepeaterConfigField as d, RepeaterRowField as e, SwitchConfigField as f, TextareaConfigField as g };
+export { type ConfigField as C, type DocumentConfigField as D, type ExpressionConfigField as E, type JsonConfigField as J, type KeyValueConfigField as K, LEGACY_PAUSE_PREFIXES as L, type NodeKindDefinition as N, type PauseAwaiting as P, type RenderBodyContext as R, type SelectConfigField as S, type TextConfigField as T, type NodeCategory as a, PAUSE_PREFIX as b, type PauseSignal as c, type PortSpec as d, decodePause as e, encodePause as f, type CredentialConfigField as g, type NumberConfigField as h, isPause as i, type RepeaterConfigField as j, type RepeaterRowField as k, type SwitchConfigField as l, type TextareaConfigField as m, pauseForHuman as p };

package/dist/ux.d.cts

@@ -1,10 +1,9 @@
 import { EffectRegistry, DispatchActor } from '@particle-academy/fancy-auto-common';
 export { AutoActivityEvent } from '@particle-academy/fancy-auto-common';
-import { N as NodeCategory, C as ConfigField } from './types-B_pxRqfw.cjs';
+import { a as NodeCategory, C as ConfigField } from './types-DEmDSByY.cjs';
 import { E as ExecutorRegistry } from './types-CMSrWVYM.cjs';
 import 'react';
 import '@xyflow/react';
-import './pause-9iT4tCEV.cjs';
 
 /** Per-effect presentation for the palette node kind that drives it. */
 type UxEffectMeta = {

package/dist/ux.d.ts

@@ -1,10 +1,9 @@
 import { EffectRegistry, DispatchActor } from '@particle-academy/fancy-auto-common';
 export { AutoActivityEvent } from '@particle-academy/fancy-auto-common';
-import { N as NodeCategory, C as ConfigField } from './types-BGtR3k9J.js';
+import { a as NodeCategory, C as ConfigField } from './types-Bj_ZHwqG.js';
 import { E as ExecutorRegistry } from './types-CMSrWVYM.js';
 import 'react';
 import '@xyflow/react';
-import './pause-9iT4tCEV.js';
 
 /** Per-effect presentation for the palette node kind that drives it. */
 type UxEffectMeta = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/fancy-flow",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "Workflow editor + runner. Six built-in node kits (trigger / action / decision / output / note / subgraph), tokenized theme, topological execution with per-node status. React-flow bundled; consumers npm install fancy-flow and get nothing extra.",
   "repository": {
     "type": "git",

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

@@ -1,96 +0,0 @@
-/**
- * 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

@@ -1,96 +0,0 @@
-/**
- * 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 };