@particle-academy/fancy-flow 0.10.1 → 0.12.0

package/dist/index.d.cts

@@ -1,12 +1,12 @@
 import * as react from 'react';
 import { ReactNode, CSSProperties, ComponentType } from 'react';
 import { ReactFlowProps, Edge, BackgroundVariant, NodeProps, NodeTypes } from '@xyflow/react';
-import { F as FlowNode, a as FlowGraph, b as NodeRunStatus, E as ExecutorRegistry } from './types-BS3Gwnkq.cjs';
-export { A as ActionNodeData, B as BaseNodeData, D as DecisionNodeData, c as FlowEdge, d as FlowNodeData, e as FlowNodeKind, N as NodeExecutor, f as NoteNodeData, O as OutputNodeData, P as PortDescriptor, R as RunEvent, S as SubgraphNodeData, T as TriggerNodeData } from './types-BS3Gwnkq.cjs';
+import { F as FlowNode, a as FlowGraph, b as NodeRunStatus, E as ExecutorRegistry } from './types-Dg2REAz5.cjs';
+export { A as ActionNodeData, B as BaseNodeData, D as DecisionNodeData, c as FlowEdge, d as FlowNodeData, e as FlowNodeKind, N as NodeExecutor, f as NoteNodeData, O as OutputNodeData, P as PortDescriptor, R as RunEvent, S as SubgraphNodeData, T as TriggerNodeData } from './types-Dg2REAz5.cjs';
 import { WorkflowSchema, WorkflowMetadata } from './schema/index.cjs';
 export { ImportIssue, ImportOptions, ImportResult, WORKFLOW_SCHEMA_URL, WORKFLOW_SCHEMA_VERSION, WorkflowSchemaEdge, WorkflowSchemaNode, exportWorkflow, importWorkflow, workflowToBlob } from './schema/index.cjs';
-import { N as NodeCategory, a as NodeKindDefinition, C as ConfigField } from './types-DKqaUjF_.cjs';
-export { D as DocumentConfigField, K as KeyValueConfigField, P as PortSpec, R as RenderBodyContext, d as RepeaterConfigField, e as RepeaterRowField } from './types-DKqaUjF_.cjs';
+import { N as NodeCategory, a as NodeKindDefinition, C as ConfigField } from './types-DnQ4TEHN.cjs';
+export { D as DocumentConfigField, K as KeyValueConfigField, P as PortSpec, R as RenderBodyContext, d as RepeaterConfigField, e as RepeaterRowField } from './types-DnQ4TEHN.cjs';
 import { FlowRunFeedEntry } from './runtime/index.cjs';
 export { UseFlowRunOptions, UseFlowRunReturn, UseFlowStateReturn, applyStatusesToNodes, useFlowRun, useFlowState } from './runtime/index.cjs';
 export { BUILTIN_KINDS, RegistryNode, RichInputAdapter, RichInputPreview, buildNodeTypes, categoryAccent, defaultConfigFor, getNodeKind, getRichInputAdapter, isRichInputEnabled, listNodeKinds, onNodeKindsChanged, onRichInputAdapterChanged, registerBuiltinKinds, registerNodeKind, registerRichInputAdapter, resolveNodePorts, resolvePortSpec, validateConfig } from './registry/index.cjs';

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 import * as react from 'react';
 import { ReactNode, CSSProperties, ComponentType } from 'react';
 import { ReactFlowProps, Edge, BackgroundVariant, NodeProps, NodeTypes } from '@xyflow/react';
-import { F as FlowNode, a as FlowGraph, b as NodeRunStatus, E as ExecutorRegistry } from './types-BS3Gwnkq.js';
-export { A as ActionNodeData, B as BaseNodeData, D as DecisionNodeData, c as FlowEdge, d as FlowNodeData, e as FlowNodeKind, N as NodeExecutor, f as NoteNodeData, O as OutputNodeData, P as PortDescriptor, R as RunEvent, S as SubgraphNodeData, T as TriggerNodeData } from './types-BS3Gwnkq.js';
+import { F as FlowNode, a as FlowGraph, b as NodeRunStatus, E as ExecutorRegistry } from './types-Dg2REAz5.js';
+export { A as ActionNodeData, B as BaseNodeData, D as DecisionNodeData, c as FlowEdge, d as FlowNodeData, e as FlowNodeKind, N as NodeExecutor, f as NoteNodeData, O as OutputNodeData, P as PortDescriptor, R as RunEvent, S as SubgraphNodeData, T as TriggerNodeData } from './types-Dg2REAz5.js';
 import { WorkflowSchema, WorkflowMetadata } from './schema/index.js';
 export { ImportIssue, ImportOptions, ImportResult, WORKFLOW_SCHEMA_URL, WORKFLOW_SCHEMA_VERSION, WorkflowSchemaEdge, WorkflowSchemaNode, exportWorkflow, importWorkflow, workflowToBlob } from './schema/index.js';
-import { N as NodeCategory, a as NodeKindDefinition, C as ConfigField } from './types-BocBFh6l.js';
-export { D as DocumentConfigField, K as KeyValueConfigField, P as PortSpec, R as RenderBodyContext, d as RepeaterConfigField, e as RepeaterRowField } from './types-BocBFh6l.js';
+import { N as NodeCategory, a as NodeKindDefinition, C as ConfigField } from './types-DtXOwXjA.js';
+export { D as DocumentConfigField, K as KeyValueConfigField, P as PortSpec, R as RenderBodyContext, d as RepeaterConfigField, e as RepeaterRowField } from './types-DtXOwXjA.js';
 import { FlowRunFeedEntry } from './runtime/index.js';
 export { UseFlowRunOptions, UseFlowRunReturn, UseFlowStateReturn, applyStatusesToNodes, useFlowRun, useFlowState } from './runtime/index.js';
 export { BUILTIN_KINDS, RegistryNode, RichInputAdapter, RichInputPreview, buildNodeTypes, categoryAccent, defaultConfigFor, getNodeKind, getRichInputAdapter, isRichInputEnabled, listNodeKinds, onNodeKindsChanged, onRichInputAdapterChanged, registerBuiltinKinds, registerNodeKind, registerRichInputAdapter, resolveNodePorts, resolvePortSpec, validateConfig } from './registry/index.js';

package/dist/index.js

@@ -1,14 +1,14 @@
-import { useFlowState, useFlowRun, applyStatusesToNodes } from './chunk-VEI743ZX.js';
-export { applyStatusesToNodes, useFlowRun, useFlowState } from './chunk-VEI743ZX.js';
-export { runFlow } from './chunk-HNBO4HP3.js';
-import { buildNodeTypes, registerBuiltinKinds } from './chunk-NCPQDVUE.js';
-export { BUILTIN_KINDS, RegistryNode, buildNodeTypes, registerBuiltinKinds } from './chunk-NCPQDVUE.js';
+import { useFlowState, useFlowRun, applyStatusesToNodes } from './chunk-MFMRTRPO.js';
+export { applyStatusesToNodes, useFlowRun, useFlowState } from './chunk-MFMRTRPO.js';
+import { buildNodeTypes, registerBuiltinKinds } from './chunk-IK5DS5JP.js';
+export { BUILTIN_KINDS, RegistryNode, buildNodeTypes, registerBuiltinKinds } from './chunk-IK5DS5JP.js';
 import { ReactFlowProvider, useReactFlow, addEdge, applyEdgeChanges, applyNodeChanges, Position, Handle, index, BackgroundVariant, Background, Controls, MiniMap } from './chunk-NF6NPY5N.js';
-import { workflowToBlob, importWorkflow, exportWorkflow } from './chunk-2DMBJN2O.js';
-export { WORKFLOW_SCHEMA_URL, WORKFLOW_SCHEMA_VERSION, exportWorkflow, importWorkflow, workflowToBlob } from './chunk-2DMBJN2O.js';
+export { runFlow } from './chunk-L4AX73Q6.js';
+import { workflowToBlob, importWorkflow, exportWorkflow } from './chunk-D6W5FMCT.js';
+export { WORKFLOW_SCHEMA_URL, WORKFLOW_SCHEMA_VERSION, exportWorkflow, importWorkflow, workflowToBlob } from './chunk-D6W5FMCT.js';
 export { resolveNodePorts, resolvePortSpec } from './chunk-TITD5W4Y.js';
-import { onNodeKindsChanged, listNodeKinds, getNodeKind, defaultConfigFor, validateConfig, categoryAccent } from './chunk-CPSOC27D.js';
-export { categoryAccent, defaultConfigFor, getNodeKind, listNodeKinds, onNodeKindsChanged, registerNodeKind, validateConfig } from './chunk-CPSOC27D.js';
+import { onNodeKindsChanged, listNodeKinds, getNodeKind, defaultConfigFor, validateConfig, categoryAccent } from './chunk-U5F22BHV.js';
+export { categoryAccent, defaultConfigFor, getNodeKind, listNodeKinds, onNodeKindsChanged, registerNodeKind, validateConfig } from './chunk-U5F22BHV.js';
 import { getRichInputAdapter } from './chunk-F5RPRB7A.js';
 export { RichInputPreview, getRichInputAdapter, isRichInputEnabled, onRichInputAdapterChanged, registerRichInputAdapter } from './chunk-F5RPRB7A.js';
 import { memo, createContext, forwardRef, useState, useEffect, useMemo, useCallback, useImperativeHandle, useRef, useContext } from 'react';

package/dist/registry/index.d.cts

@@ -1,6 +1,6 @@
-import { a as NodeKindDefinition, P as PortSpec } from '../types-DKqaUjF_.cjs';
-export { C as ConfigField, b as CredentialConfigField, D as DocumentConfigField, E as ExpressionConfigField, J as JsonConfigField, K as KeyValueConfigField, N as NodeCategory, c as NumberConfigField, R as RenderBodyContext, d as RepeaterConfigField, e as RepeaterRowField, S as SelectConfigField, f as SwitchConfigField, T as TextConfigField, g as TextareaConfigField } from '../types-DKqaUjF_.cjs';
-import { F as FlowNode, P as PortDescriptor } from '../types-BS3Gwnkq.cjs';
+import { a as NodeKindDefinition, P as PortSpec } from '../types-DnQ4TEHN.cjs';
+export { C as ConfigField, b as CredentialConfigField, D as DocumentConfigField, E as ExpressionConfigField, J as JsonConfigField, K as KeyValueConfigField, N as NodeCategory, c as NumberConfigField, R as RenderBodyContext, d as RepeaterConfigField, e as RepeaterRowField, S as SelectConfigField, f as SwitchConfigField, T as TextConfigField, g as TextareaConfigField } from '../types-DnQ4TEHN.cjs';
+import { F as FlowNode, P as PortDescriptor, a as FlowGraph, N as NodeExecutor } from '../types-Dg2REAz5.cjs';
 import * as react from 'react';
 import { ComponentType, ReactNode } from 'react';
 import { NodeProps, NodeTypes } from '@xyflow/react';
@@ -44,6 +44,134 @@ declare function resolveNodePorts(node: Pick<FlowNode, "data">, kind?: Pick<Node
     outputs?: PortDescriptor[];
 };
 
+/**
+ * Host capabilities — the services core nodes need but must never depend on.
+ *
+ * A node that imports a provider SDK forces every consumer to install it: a
+ * workflow app that never calls a model should not inherit an LLM dependency.
+ * So core declares the CONTRACT and the host supplies the implementation, the
+ * same arrangement `renderDocumentField` already uses for documents.
+ *
+ * That keeps opinionated nodes in core without their opinions: `llm_branch`
+ * ships the routing semantics, port derivation and config UI, while whichever
+ * client the host registers — Prism, an OpenAI SDK, a local model, a fake in a
+ * test — decides how the question actually gets asked.
+ *
+ * Registration is deliberately explicit and typed per capability rather than a
+ * stringly-keyed bag, so a missing one is a clear error at the seam instead of
+ * an undefined somewhere downstream.
+ */
+type LlmRoute = {
+    port: string;
+    description?: string;
+};
+type LlmRouteRequest = {
+    /** Optional framing for the decision. */
+    system?: string;
+    /** What the model is deciding about. */
+    prompt: string;
+    /** The ports it must choose between. */
+    routes: LlmRoute[];
+    provider?: string;
+    model?: string;
+    /** Host-resolved credential reference, never a raw key. */
+    credential?: string;
+};
+type LlmRouteChoice = {
+    /** Must be one of the requested route ports. */
+    port: string;
+    /** Why — carried down the chosen port so a run is explainable afterwards. */
+    reason?: string;
+};
+/**
+ * The only thing core asks of an LLM: given routes, pick one.
+ *
+ * Deliberately not a general chat interface. A narrow contract is one a host
+ * can satisfy in a few lines over any SDK, and it keeps the choice
+ * machine-checkable — an implementation should constrain the model to the
+ * declared ports (structured output / enum) rather than parsing prose.
+ */
+type LlmClient = {
+    chooseRoute: (request: LlmRouteRequest) => Promise<LlmRouteChoice> | LlmRouteChoice;
+};
+/** Install the host's LLM client. Returns an unregister function. */
+declare function registerLlmClient(client: LlmClient): () => void;
+declare function getLlmClient(): LlmClient | null;
+/**
+ * Resolve a workflow reference to a runnable graph.
+ *
+ * `subflow` names another workflow rather than embedding it, so the host owns
+ * where workflows live — a database, a file, an API. Returning null means "no
+ * such workflow", which the node reports as an error rather than silently
+ * running nothing.
+ */
+type WorkflowResolver = (ref: string) => Promise<FlowGraph | null> | FlowGraph | null;
+/** Install the host's workflow resolver. Returns an unregister function. */
+declare function registerWorkflowResolver(resolver: WorkflowResolver): () => void;
+declare function getWorkflowResolver(): WorkflowResolver | null;
+type CapabilityId = "llm" | "workflow_resolver" | "document";
+/**
+ * Which capabilities are currently satisfied.
+ *
+ * Exists so a host (or the CLI, or an agent over MCP) can answer "what does
+ * this graph need that I haven't wired?" BEFORE a run fails halfway through.
+ */
+declare function capabilityStatus(): Record<CapabilityId, boolean>;
+
+/**
+ * `@fancy/subflow` — run another workflow and bring its result home.
+ *
+ * Core, not marketplace: it introduces no third-party dependency. It runs a
+ * child graph through the very same engine, so the only thing it needs from the
+ * host is where workflows live (`registerWorkflowResolver`).
+ *
+ * Three output modes, because both halves are genuinely useful:
+ *
+ *   - `output` — the child's outputs arrive on `out` when it finishes.
+ *   - `stream` — the child's events are forwarded live on `stream` as they
+ *     happen, so a parent can show progress instead of a spinner.
+ *   - `both`   — stream while running AND deliver the final outputs.
+ *
+ * Recursion is guarded by depth. A workflow that references itself (directly or
+ * through a chain) would otherwise recurse until the stack dies, which surfaces
+ * as an opaque crash rather than "you built a loop".
+ */
+declare const DEFAULT_MAX_DEPTH = 8;
+type SubflowMode = "output" | "stream" | "both";
+declare function subflowMode(config: Record<string, unknown>): SubflowMode;
+/** Ports follow the mode — `stream` only exists when something streams. */
+declare function subflowPorts(config: Record<string, unknown>): {
+    id: string;
+    label: string;
+}[];
+declare const subflowExecutor: NodeExecutor;
+
+/**
+ * `@fancy/llm_branch` — a SHUTTLE, not an engine.
+ *
+ * It carries the declared routes and the decision prompt out to whatever LLM
+ * client the host registered, and carries the chosen port back down the graph.
+ * It contains no provider SDK, no prompt engineering, no response parsing and
+ * no retry policy — all of that belongs to the host's client, which is what
+ * lets this node live in core without every consumer inheriting an LLM
+ * dependency.
+ *
+ * The one thing it does own is graph integrity, because that is a workflow
+ * concern rather than an AI one: a port the model invents must never route.
+ */
+/** Read the node's declared routes out of config. */
+declare function declaredRoutes(config: Record<string, unknown>): LlmRoute[];
+/**
+ * Where a run goes when the model returns a port that was never offered.
+ *
+ * Emitting on a port with no edge silently ends the branch — the worst failure
+ * mode in a workflow engine, because the run reports success having done
+ * nothing. So: the `fallback` port when it exists, else the first declared
+ * route, and always loudly.
+ */
+declare function resolveFallbackPort(routes: LlmRoute[], fallbackEnabled: boolean): string;
+declare const llmBranchExecutor: NodeExecutor;
+
 /**
  * Rich user input — the injection point.
  *
@@ -116,10 +244,26 @@ declare function RichInputPreview({ config }: {
  * 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;
-/** Get a single kind by name, or null. */
+/**
+ * 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. */
@@ -158,4 +302,4 @@ declare const BUILTIN_KINDS: NodeKindDefinition[];
  */
 declare function buildNodeTypes(): NodeTypes;
 
-export { BUILTIN_KINDS, NodeKindDefinition, PortSpec, RegistryNode, type RichInputAdapter, RichInputPreview, buildNodeTypes, categoryAccent, defaultConfigFor, getNodeKind, getRichInputAdapter, isRichInputEnabled, listNodeKinds, nodeConfig, onNodeKindsChanged, onRichInputAdapterChanged, registerBuiltinKinds, registerNodeKind, registerRichInputAdapter, resolveNodePorts, resolvePortSpec, validateConfig };
+export { BUILTIN_KINDS, type CapabilityId, DEFAULT_MAX_DEPTH, type LlmClient, type LlmRoute, type LlmRouteChoice, type LlmRouteRequest, NodeKindDefinition, PortSpec, RegistryNode, type RichInputAdapter, RichInputPreview, type SubflowMode, type WorkflowResolver, buildNodeTypes, capabilityStatus, categoryAccent, declaredRoutes, defaultConfigFor, getLlmClient, getNodeKind, getRichInputAdapter, getWorkflowResolver, isRichInputEnabled, kindIds, listNodeKinds, llmBranchExecutor, nodeConfig, onNodeKindsChanged, onRichInputAdapterChanged, registerBuiltinKinds, registerLlmClient, registerNodeKind, registerRichInputAdapter, registerWorkflowResolver, resolveFallbackPort, resolveKindId, resolveNodePorts, resolvePortSpec, subflowExecutor, subflowMode, subflowPorts, validateConfig };

package/dist/registry/index.d.ts

@@ -1,6 +1,6 @@
-import { a as NodeKindDefinition, P as PortSpec } from '../types-BocBFh6l.js';
-export { C as ConfigField, b as CredentialConfigField, D as DocumentConfigField, E as ExpressionConfigField, J as JsonConfigField, K as KeyValueConfigField, N as NodeCategory, c as NumberConfigField, R as RenderBodyContext, d as RepeaterConfigField, e as RepeaterRowField, S as SelectConfigField, f as SwitchConfigField, T as TextConfigField, g as TextareaConfigField } from '../types-BocBFh6l.js';
-import { F as FlowNode, P as PortDescriptor } from '../types-BS3Gwnkq.js';
+import { a as NodeKindDefinition, P as PortSpec } from '../types-DtXOwXjA.js';
+export { C as ConfigField, b as CredentialConfigField, D as DocumentConfigField, E as ExpressionConfigField, J as JsonConfigField, K as KeyValueConfigField, N as NodeCategory, c as NumberConfigField, R as RenderBodyContext, d as RepeaterConfigField, e as RepeaterRowField, S as SelectConfigField, f as SwitchConfigField, T as TextConfigField, g as TextareaConfigField } from '../types-DtXOwXjA.js';
+import { F as FlowNode, P as PortDescriptor, a as FlowGraph, N as NodeExecutor } from '../types-Dg2REAz5.js';
 import * as react from 'react';
 import { ComponentType, ReactNode } from 'react';
 import { NodeProps, NodeTypes } from '@xyflow/react';
@@ -44,6 +44,134 @@ declare function resolveNodePorts(node: Pick<FlowNode, "data">, kind?: Pick<Node
     outputs?: PortDescriptor[];
 };
 
+/**
+ * Host capabilities — the services core nodes need but must never depend on.
+ *
+ * A node that imports a provider SDK forces every consumer to install it: a
+ * workflow app that never calls a model should not inherit an LLM dependency.
+ * So core declares the CONTRACT and the host supplies the implementation, the
+ * same arrangement `renderDocumentField` already uses for documents.
+ *
+ * That keeps opinionated nodes in core without their opinions: `llm_branch`
+ * ships the routing semantics, port derivation and config UI, while whichever
+ * client the host registers — Prism, an OpenAI SDK, a local model, a fake in a
+ * test — decides how the question actually gets asked.
+ *
+ * Registration is deliberately explicit and typed per capability rather than a
+ * stringly-keyed bag, so a missing one is a clear error at the seam instead of
+ * an undefined somewhere downstream.
+ */
+type LlmRoute = {
+    port: string;
+    description?: string;
+};
+type LlmRouteRequest = {
+    /** Optional framing for the decision. */
+    system?: string;
+    /** What the model is deciding about. */
+    prompt: string;
+    /** The ports it must choose between. */
+    routes: LlmRoute[];
+    provider?: string;
+    model?: string;
+    /** Host-resolved credential reference, never a raw key. */
+    credential?: string;
+};
+type LlmRouteChoice = {
+    /** Must be one of the requested route ports. */
+    port: string;
+    /** Why — carried down the chosen port so a run is explainable afterwards. */
+    reason?: string;
+};
+/**
+ * The only thing core asks of an LLM: given routes, pick one.
+ *
+ * Deliberately not a general chat interface. A narrow contract is one a host
+ * can satisfy in a few lines over any SDK, and it keeps the choice
+ * machine-checkable — an implementation should constrain the model to the
+ * declared ports (structured output / enum) rather than parsing prose.
+ */
+type LlmClient = {
+    chooseRoute: (request: LlmRouteRequest) => Promise<LlmRouteChoice> | LlmRouteChoice;
+};
+/** Install the host's LLM client. Returns an unregister function. */
+declare function registerLlmClient(client: LlmClient): () => void;
+declare function getLlmClient(): LlmClient | null;
+/**
+ * Resolve a workflow reference to a runnable graph.
+ *
+ * `subflow` names another workflow rather than embedding it, so the host owns
+ * where workflows live — a database, a file, an API. Returning null means "no
+ * such workflow", which the node reports as an error rather than silently
+ * running nothing.
+ */
+type WorkflowResolver = (ref: string) => Promise<FlowGraph | null> | FlowGraph | null;
+/** Install the host's workflow resolver. Returns an unregister function. */
+declare function registerWorkflowResolver(resolver: WorkflowResolver): () => void;
+declare function getWorkflowResolver(): WorkflowResolver | null;
+type CapabilityId = "llm" | "workflow_resolver" | "document";
+/**
+ * Which capabilities are currently satisfied.
+ *
+ * Exists so a host (or the CLI, or an agent over MCP) can answer "what does
+ * this graph need that I haven't wired?" BEFORE a run fails halfway through.
+ */
+declare function capabilityStatus(): Record<CapabilityId, boolean>;
+
+/**
+ * `@fancy/subflow` — run another workflow and bring its result home.
+ *
+ * Core, not marketplace: it introduces no third-party dependency. It runs a
+ * child graph through the very same engine, so the only thing it needs from the
+ * host is where workflows live (`registerWorkflowResolver`).
+ *
+ * Three output modes, because both halves are genuinely useful:
+ *
+ *   - `output` — the child's outputs arrive on `out` when it finishes.
+ *   - `stream` — the child's events are forwarded live on `stream` as they
+ *     happen, so a parent can show progress instead of a spinner.
+ *   - `both`   — stream while running AND deliver the final outputs.
+ *
+ * Recursion is guarded by depth. A workflow that references itself (directly or
+ * through a chain) would otherwise recurse until the stack dies, which surfaces
+ * as an opaque crash rather than "you built a loop".
+ */
+declare const DEFAULT_MAX_DEPTH = 8;
+type SubflowMode = "output" | "stream" | "both";
+declare function subflowMode(config: Record<string, unknown>): SubflowMode;
+/** Ports follow the mode — `stream` only exists when something streams. */
+declare function subflowPorts(config: Record<string, unknown>): {
+    id: string;
+    label: string;
+}[];
+declare const subflowExecutor: NodeExecutor;
+
+/**
+ * `@fancy/llm_branch` — a SHUTTLE, not an engine.
+ *
+ * It carries the declared routes and the decision prompt out to whatever LLM
+ * client the host registered, and carries the chosen port back down the graph.
+ * It contains no provider SDK, no prompt engineering, no response parsing and
+ * no retry policy — all of that belongs to the host's client, which is what
+ * lets this node live in core without every consumer inheriting an LLM
+ * dependency.
+ *
+ * The one thing it does own is graph integrity, because that is a workflow
+ * concern rather than an AI one: a port the model invents must never route.
+ */
+/** Read the node's declared routes out of config. */
+declare function declaredRoutes(config: Record<string, unknown>): LlmRoute[];
+/**
+ * Where a run goes when the model returns a port that was never offered.
+ *
+ * Emitting on a port with no edge silently ends the branch — the worst failure
+ * mode in a workflow engine, because the run reports success having done
+ * nothing. So: the `fallback` port when it exists, else the first declared
+ * route, and always loudly.
+ */
+declare function resolveFallbackPort(routes: LlmRoute[], fallbackEnabled: boolean): string;
+declare const llmBranchExecutor: NodeExecutor;
+
 /**
  * Rich user input — the injection point.
  *
@@ -116,10 +244,26 @@ declare function RichInputPreview({ config }: {
  * 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;
-/** Get a single kind by name, or null. */
+/**
+ * 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. */
@@ -158,4 +302,4 @@ declare const BUILTIN_KINDS: NodeKindDefinition[];
  */
 declare function buildNodeTypes(): NodeTypes;
 
-export { BUILTIN_KINDS, NodeKindDefinition, PortSpec, RegistryNode, type RichInputAdapter, RichInputPreview, buildNodeTypes, categoryAccent, defaultConfigFor, getNodeKind, getRichInputAdapter, isRichInputEnabled, listNodeKinds, nodeConfig, onNodeKindsChanged, onRichInputAdapterChanged, registerBuiltinKinds, registerNodeKind, registerRichInputAdapter, resolveNodePorts, resolvePortSpec, validateConfig };
+export { BUILTIN_KINDS, type CapabilityId, DEFAULT_MAX_DEPTH, type LlmClient, type LlmRoute, type LlmRouteChoice, type LlmRouteRequest, NodeKindDefinition, PortSpec, RegistryNode, type RichInputAdapter, RichInputPreview, type SubflowMode, type WorkflowResolver, buildNodeTypes, capabilityStatus, categoryAccent, declaredRoutes, defaultConfigFor, getLlmClient, getNodeKind, getRichInputAdapter, getWorkflowResolver, isRichInputEnabled, kindIds, listNodeKinds, llmBranchExecutor, nodeConfig, onNodeKindsChanged, onRichInputAdapterChanged, registerBuiltinKinds, registerLlmClient, registerNodeKind, registerRichInputAdapter, registerWorkflowResolver, resolveFallbackPort, resolveKindId, resolveNodePorts, resolvePortSpec, subflowExecutor, subflowMode, subflowPorts, validateConfig };