@particle-academy/fancy-flow 0.17.0 → 0.19.0

package/dist/registry/index.d.cts

@@ -1,12 +1,61 @@
 import { a as NodeKindDefinition, P as PortSpec } from '../types-D_jOR3Z2.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-D_jOR3Z2.cjs';
-import { b as FlowNode, P as PortDescriptor, N as NodeExecutor } from '../types-sOmpCitB.cjs';
+import { P as PortDescriptor, b as FlowNode, N as NodeExecutor } from '../types-sOmpCitB.cjs';
+import { Connection, Edge, NodeProps, NodeTypes } from '@xyflow/react';
 import { b as LlmRoute } from '../capabilities-ChE3Xi8R.cjs';
 export { C as CapabilityId, a as LlmClient, c as LlmRouteChoice, L as LlmRouteRequest, W as WorkflowResolution, d as WorkflowResolutionFailure, e as WorkflowResolver, f as capabilityStatus, g as getLlmClient, h as getWorkflowResolver, i as isResolutionFailure, r as registerLlmClient, j as registerWorkflowResolver } from '../capabilities-ChE3Xi8R.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';
-import { NodeProps, NodeTypes } from '@xyflow/react';
+
+/**
+ * Connection validation — the single rule that decides whether an edge between
+ * two ports is allowed. Lives here (React-free, registry-adjacent) so BOTH the
+ * canvas (`<FlowCanvas isValidConnection>`) and the agent bridge's
+ * `flow_connect` tool call the same function: a connection the canvas refuses
+ * is a connection an agent cannot sneak past, and vice versa — no drift.
+ *
+ * `PortDescriptor.type` has always documented itself as being "for hosts that
+ * want to validate connections", but nothing consumed it. This wires it up.
+ */
+/**
+ * Wildcard port type — matches any other type. A port that declares no `type`
+ * is treated as a wildcard too, so existing flows (whose ports are untyped)
+ * validate exactly as before.
+ */
+declare const ANY_PORT_TYPE = "any";
+/** Decides whether a source-output port may feed a target-input port. */
+type PortCompatibility = (source: PortDescriptor | undefined, target: PortDescriptor | undefined) => boolean;
+/**
+ * Default compatibility rule: allow the connection UNLESS both ports declare a
+ * concrete, differing type. An absent type or the `any` wildcard matches
+ * anything — so typed ports get enforced while untyped ports stay permissive,
+ * making this a safe default that never breaks an existing untyped graph.
+ */
+declare const defaultPortCompatibility: PortCompatibility;
+type ConnectionValidatorOptions = {
+    /** Override the type-compatibility rule. Defaults to {@link defaultPortCompatibility}. */
+    compatible?: PortCompatibility;
+    /**
+     * Allow a node's own output to feed its own input (a self-loop). Default
+     * false — self-connections are almost always an accident, and the rare flow
+     * that wants one can opt in.
+     */
+    allowSelfConnection?: boolean;
+};
+/**
+ * Build an `isValidConnection` predicate that enforces port-type compatibility
+ * against a live node list. Pass it straight to `<FlowCanvas isValidConnection>`
+ * or reuse it to gate an agent's `flow_connect`.
+ *
+ * `getNodes` is called on every check so the validator always sees the current
+ * graph (wire it to a ref/state getter, not a snapshot).
+ *
+ * A connection is rejected when: an endpoint is missing; it is a self-loop and
+ * `allowSelfConnection` is off; either node is unknown; or the resolved ports
+ * are type-incompatible. Nodes/ports with no declared type validate as before.
+ */
+declare function createConnectionValidator(getNodes: () => FlowNode[], options?: ConnectionValidatorOptions): (connection: Connection | Edge) => boolean;
 
 /**
  * Port resolution — the single place a node's ports are derived, shared by
@@ -231,4 +280,4 @@ declare const BUILTIN_KINDS: NodeKindDefinition[];
  */
 declare function buildNodeTypes(): NodeTypes;
 
-export { BUILTIN_KINDS, DEFAULT_MAX_DEPTH, LlmRoute, NodeKindDefinition, PortSpec, RegistryNode, type RichInputAdapter, RichInputPreview, type SubflowMode, buildNodeTypes, categoryAccent, declaredRoutes, defaultConfigFor, getNodeKind, getRichInputAdapter, isRichInputEnabled, kindIds, listNodeKinds, llmRouterExecutor as llmBranchExecutor, llmRouterExecutor, nodeConfig, onNodeKindsChanged, onRichInputAdapterChanged, registerBuiltinKinds, registerNodeKind, registerRichInputAdapter, resolveFallbackPort, resolveKindId, resolveNodePorts, resolvePortSpec, subflowExecutor, subflowMode, subflowPorts, validateConfig };
+export { ANY_PORT_TYPE, BUILTIN_KINDS, type ConnectionValidatorOptions, DEFAULT_MAX_DEPTH, LlmRoute, NodeKindDefinition, type PortCompatibility, PortSpec, RegistryNode, type RichInputAdapter, RichInputPreview, type SubflowMode, buildNodeTypes, categoryAccent, createConnectionValidator, declaredRoutes, defaultConfigFor, defaultPortCompatibility, getNodeKind, getRichInputAdapter, isRichInputEnabled, kindIds, listNodeKinds, llmRouterExecutor as llmBranchExecutor, llmRouterExecutor, nodeConfig, onNodeKindsChanged, onRichInputAdapterChanged, registerBuiltinKinds, registerNodeKind, registerRichInputAdapter, resolveFallbackPort, resolveKindId, resolveNodePorts, resolvePortSpec, subflowExecutor, subflowMode, subflowPorts, validateConfig };

package/dist/registry/index.d.ts

@@ -1,12 +1,61 @@
 import { a as NodeKindDefinition, P as PortSpec } from '../types-NerkPtHS.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-NerkPtHS.js';
-import { b as FlowNode, P as PortDescriptor, N as NodeExecutor } from '../types-sOmpCitB.js';
+import { P as PortDescriptor, b as FlowNode, N as NodeExecutor } from '../types-sOmpCitB.js';
+import { Connection, Edge, NodeProps, NodeTypes } from '@xyflow/react';
 import { b as LlmRoute } from '../capabilities-DUhAc-EJ.js';
 export { C as CapabilityId, a as LlmClient, c as LlmRouteChoice, L as LlmRouteRequest, W as WorkflowResolution, d as WorkflowResolutionFailure, e as WorkflowResolver, f as capabilityStatus, g as getLlmClient, h as getWorkflowResolver, i as isResolutionFailure, r as registerLlmClient, j as registerWorkflowResolver } from '../capabilities-DUhAc-EJ.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';
-import { NodeProps, NodeTypes } from '@xyflow/react';
+
+/**
+ * Connection validation — the single rule that decides whether an edge between
+ * two ports is allowed. Lives here (React-free, registry-adjacent) so BOTH the
+ * canvas (`<FlowCanvas isValidConnection>`) and the agent bridge's
+ * `flow_connect` tool call the same function: a connection the canvas refuses
+ * is a connection an agent cannot sneak past, and vice versa — no drift.
+ *
+ * `PortDescriptor.type` has always documented itself as being "for hosts that
+ * want to validate connections", but nothing consumed it. This wires it up.
+ */
+/**
+ * Wildcard port type — matches any other type. A port that declares no `type`
+ * is treated as a wildcard too, so existing flows (whose ports are untyped)
+ * validate exactly as before.
+ */
+declare const ANY_PORT_TYPE = "any";
+/** Decides whether a source-output port may feed a target-input port. */
+type PortCompatibility = (source: PortDescriptor | undefined, target: PortDescriptor | undefined) => boolean;
+/**
+ * Default compatibility rule: allow the connection UNLESS both ports declare a
+ * concrete, differing type. An absent type or the `any` wildcard matches
+ * anything — so typed ports get enforced while untyped ports stay permissive,
+ * making this a safe default that never breaks an existing untyped graph.
+ */
+declare const defaultPortCompatibility: PortCompatibility;
+type ConnectionValidatorOptions = {
+    /** Override the type-compatibility rule. Defaults to {@link defaultPortCompatibility}. */
+    compatible?: PortCompatibility;
+    /**
+     * Allow a node's own output to feed its own input (a self-loop). Default
+     * false — self-connections are almost always an accident, and the rare flow
+     * that wants one can opt in.
+     */
+    allowSelfConnection?: boolean;
+};
+/**
+ * Build an `isValidConnection` predicate that enforces port-type compatibility
+ * against a live node list. Pass it straight to `<FlowCanvas isValidConnection>`
+ * or reuse it to gate an agent's `flow_connect`.
+ *
+ * `getNodes` is called on every check so the validator always sees the current
+ * graph (wire it to a ref/state getter, not a snapshot).
+ *
+ * A connection is rejected when: an endpoint is missing; it is a self-loop and
+ * `allowSelfConnection` is off; either node is unknown; or the resolved ports
+ * are type-incompatible. Nodes/ports with no declared type validate as before.
+ */
+declare function createConnectionValidator(getNodes: () => FlowNode[], options?: ConnectionValidatorOptions): (connection: Connection | Edge) => boolean;
 
 /**
  * Port resolution — the single place a node's ports are derived, shared by
@@ -231,4 +280,4 @@ declare const BUILTIN_KINDS: NodeKindDefinition[];
  */
 declare function buildNodeTypes(): NodeTypes;
 
-export { BUILTIN_KINDS, DEFAULT_MAX_DEPTH, LlmRoute, NodeKindDefinition, PortSpec, RegistryNode, type RichInputAdapter, RichInputPreview, type SubflowMode, buildNodeTypes, categoryAccent, declaredRoutes, defaultConfigFor, getNodeKind, getRichInputAdapter, isRichInputEnabled, kindIds, listNodeKinds, llmRouterExecutor as llmBranchExecutor, llmRouterExecutor, nodeConfig, onNodeKindsChanged, onRichInputAdapterChanged, registerBuiltinKinds, registerNodeKind, registerRichInputAdapter, resolveFallbackPort, resolveKindId, resolveNodePorts, resolvePortSpec, subflowExecutor, subflowMode, subflowPorts, validateConfig };
+export { ANY_PORT_TYPE, BUILTIN_KINDS, type ConnectionValidatorOptions, DEFAULT_MAX_DEPTH, LlmRoute, NodeKindDefinition, type PortCompatibility, PortSpec, RegistryNode, type RichInputAdapter, RichInputPreview, type SubflowMode, buildNodeTypes, categoryAccent, createConnectionValidator, declaredRoutes, defaultConfigFor, defaultPortCompatibility, getNodeKind, getRichInputAdapter, isRichInputEnabled, kindIds, listNodeKinds, llmRouterExecutor as llmBranchExecutor, llmRouterExecutor, nodeConfig, onNodeKindsChanged, onRichInputAdapterChanged, registerBuiltinKinds, registerNodeKind, registerRichInputAdapter, resolveFallbackPort, resolveKindId, resolveNodePorts, resolvePortSpec, subflowExecutor, subflowMode, subflowPorts, validateConfig };

package/dist/registry.cjs

@@ -31,80 +31,6 @@ function resolveNodePorts(node, kind) {
   };
 }
 
-// src/registry/capabilities.ts
-var llmClient = null;
-function registerLlmClient(client) {
-  llmClient = client;
-  return () => {
-    if (llmClient === client) llmClient = null;
-  };
-}
-function getLlmClient() {
-  return llmClient;
-}
-function isResolutionFailure(value) {
-  return typeof value === "object" && value !== null && "reason" in value && value.reason !== void 0;
-}
-var workflowResolver = null;
-function registerWorkflowResolver(resolver) {
-  workflowResolver = resolver;
-  return () => {
-    if (workflowResolver === resolver) workflowResolver = null;
-  };
-}
-function getWorkflowResolver() {
-  return workflowResolver;
-}
-function capabilityStatus() {
-  let documentReady = false;
-  try {
-    documentReady = Boolean(globalThis.__fancyFlowDocumentAdapter);
-  } catch {
-    documentReady = false;
-  }
-  return {
-    llm: llmClient !== null,
-    workflow_resolver: workflowResolver !== null,
-    document: documentReady
-  };
-}
-
-// src/registry/pause.ts
-var PAUSE_PREFIX = "fancy-flow:pause:";
-var LEGACY_PAUSE_PREFIXES = [
-  ["awaiting-approval:", "approval"],
-  ["awaiting-input:", "input"]
-];
-function encodePause(signal) {
-  const { nodeId, awaiting, detail } = signal;
-  return PAUSE_PREFIX + JSON.stringify(detail === void 0 ? { nodeId, awaiting } : { nodeId, awaiting, detail });
-}
-function decodePause(reason) {
-  if (typeof reason !== "string") return null;
-  if (reason.startsWith(PAUSE_PREFIX)) {
-    const body = reason.slice(PAUSE_PREFIX.length);
-    try {
-      const parsed = JSON.parse(body);
-      if (typeof parsed?.nodeId !== "string" || typeof parsed?.awaiting !== "string") return null;
-      return "detail" in parsed ? { nodeId: parsed.nodeId, awaiting: parsed.awaiting, detail: parsed.detail } : { nodeId: parsed.nodeId, awaiting: parsed.awaiting };
-    } catch {
-      return null;
-    }
-  }
-  for (const [prefix, awaiting] of LEGACY_PAUSE_PREFIXES) {
-    if (reason.startsWith(prefix)) {
-      return { nodeId: reason.slice(prefix.length), awaiting };
-    }
-  }
-  return null;
-}
-function isPause(reason) {
-  return decodePause(reason) !== null;
-}
-function pauseForHuman(ctx, awaiting, detail) {
-  return ctx.abort(encodePause({ nodeId: ctx.node.id, awaiting, detail }));
-}
-
 // src/registry/registry.ts
 var kinds = /* @__PURE__ */ new Map();
 var aliases = /* @__PURE__ */ new Map();
@@ -258,6 +184,114 @@ function categoryAccent(category) {
   }
 }
 
+// src/registry/connection.ts
+var ANY_PORT_TYPE = "any";
+var defaultPortCompatibility = (source, target) => {
+  const s = source?.type;
+  const t = target?.type;
+  if (!s || !t) return true;
+  if (s === ANY_PORT_TYPE || t === ANY_PORT_TYPE) return true;
+  return s === t;
+};
+function portsFor(node, side) {
+  const kind = getNodeKind(node.data?.kind ?? node.type);
+  const resolved = resolveNodePorts(node, kind ?? void 0);
+  return resolved[side] ?? [];
+}
+function findPort(ports, handleId) {
+  if (handleId == null) return ports.length === 1 ? ports[0] : void 0;
+  return ports.find((p) => p.id === handleId);
+}
+function createConnectionValidator(getNodes, options = {}) {
+  const compatible = options.compatible ?? defaultPortCompatibility;
+  return (connection) => {
+    const { source, target, sourceHandle, targetHandle } = connection;
+    if (!source || !target) return false;
+    if (!options.allowSelfConnection && source === target) return false;
+    const nodes = getNodes();
+    const src = nodes.find((n) => n.id === source);
+    const tgt = nodes.find((n) => n.id === target);
+    if (!src || !tgt) return false;
+    const outPort = findPort(portsFor(src, "outputs"), sourceHandle);
+    const inPort = findPort(portsFor(tgt, "inputs"), targetHandle);
+    return compatible(outPort, inPort);
+  };
+}
+
+// src/registry/capabilities.ts
+var llmClient = null;
+function registerLlmClient(client) {
+  llmClient = client;
+  return () => {
+    if (llmClient === client) llmClient = null;
+  };
+}
+function getLlmClient() {
+  return llmClient;
+}
+function isResolutionFailure(value) {
+  return typeof value === "object" && value !== null && "reason" in value && value.reason !== void 0;
+}
+var workflowResolver = null;
+function registerWorkflowResolver(resolver) {
+  workflowResolver = resolver;
+  return () => {
+    if (workflowResolver === resolver) workflowResolver = null;
+  };
+}
+function getWorkflowResolver() {
+  return workflowResolver;
+}
+function capabilityStatus() {
+  let documentReady = false;
+  try {
+    documentReady = Boolean(globalThis.__fancyFlowDocumentAdapter);
+  } catch {
+    documentReady = false;
+  }
+  return {
+    llm: llmClient !== null,
+    workflow_resolver: workflowResolver !== null,
+    document: documentReady
+  };
+}
+
+// src/registry/pause.ts
+var PAUSE_PREFIX = "fancy-flow:pause:";
+var LEGACY_PAUSE_PREFIXES = [
+  ["awaiting-approval:", "approval"],
+  ["awaiting-input:", "input"]
+];
+function encodePause(signal) {
+  const { nodeId, awaiting, detail } = signal;
+  return PAUSE_PREFIX + JSON.stringify(detail === void 0 ? { nodeId, awaiting } : { nodeId, awaiting, detail });
+}
+function decodePause(reason) {
+  if (typeof reason !== "string") return null;
+  if (reason.startsWith(PAUSE_PREFIX)) {
+    const body = reason.slice(PAUSE_PREFIX.length);
+    try {
+      const parsed = JSON.parse(body);
+      if (typeof parsed?.nodeId !== "string" || typeof parsed?.awaiting !== "string") return null;
+      return "detail" in parsed ? { nodeId: parsed.nodeId, awaiting: parsed.awaiting, detail: parsed.detail } : { nodeId: parsed.nodeId, awaiting: parsed.awaiting };
+    } catch {
+      return null;
+    }
+  }
+  for (const [prefix, awaiting] of LEGACY_PAUSE_PREFIXES) {
+    if (reason.startsWith(prefix)) {
+      return { nodeId: reason.slice(prefix.length), awaiting };
+    }
+  }
+  return null;
+}
+function isPause(reason) {
+  return decodePause(reason) !== null;
+}
+function pauseForHuman(ctx, awaiting, detail) {
+  return ctx.abort(encodePause({ nodeId: ctx.node.id, awaiting, detail }));
+}
+
 // src/runtime/run-flow.ts
 async function runFlow(graph, executors, onEvent = () => {
 }, options = {}) {
@@ -10359,6 +10393,7 @@ function buildNodeTypes() {
   return map;
 }
 
+exports.ANY_PORT_TYPE = ANY_PORT_TYPE;
 exports.BUILTIN_KINDS = BUILTIN_KINDS;
 exports.DEFAULT_MAX_DEPTH = DEFAULT_MAX_DEPTH;
 exports.LEGACY_PAUSE_PREFIXES = LEGACY_PAUSE_PREFIXES;
@@ -10368,9 +10403,11 @@ exports.RichInputPreview = RichInputPreview;
 exports.buildNodeTypes = buildNodeTypes;
 exports.capabilityStatus = capabilityStatus;
 exports.categoryAccent = categoryAccent;
+exports.createConnectionValidator = createConnectionValidator;
 exports.declaredRoutes = declaredRoutes;
 exports.decodePause = decodePause;
 exports.defaultConfigFor = defaultConfigFor;
+exports.defaultPortCompatibility = defaultPortCompatibility;
 exports.encodePause = encodePause;
 exports.getLlmClient = getLlmClient;
 exports.getNodeKind = getNodeKind;