@gntik-ai/blocks 0.0.0-stage → 0.5.0

package/src/builders/FlowBuilder/FlowBuilder.tsx

@@ -0,0 +1,343 @@
+import { useEffect, useRef, useState, useSyncExternalStore, type ReactNode } from 'react';
+import { Play } from '@gntik-ai/icons';
+import { FlowCanvas, useFlowState, type FlowNode, type FlowNodeData, type FlowNodeKind } from '@gntik-ai/flow';
+import { Button, ResizablePanel, ResizablePanelGroup, ResizeHandle, cn } from '@gntik-ai/ui';
+import {
+  builderConsole,
+  builderEdges,
+  builderNodes,
+  builderPalette,
+  type ConsoleEntry,
+  type FlowEdge,
+  type PaletteItem,
+} from './fixtures';
+import type { FlowBuilderExtensions } from './extensions';
+import { useDecoratedNodes } from './decorated-nodes';
+import { useConnections } from './connections';
+import { FlowProblems } from './problems';
+import { NodeInspector, NodePalette, RunConsole } from './parts';
+
+export type { ConsoleEntry, FlowEdge, PaletteItem } from './fixtures';
+/** Graph types re-exported so apps can type nodes without depending on @gntik-ai/flow. */
+export type { FlowNode, FlowNodeData, FlowNodeKind, FlowTone } from '@gntik-ai/flow';
+
+export type { FlowConnection, FlowConnectionRejection, FlowValidationIssue } from './extensions';
+export type { FlowNodeRenderer, FlowHandle, FlowNodeRenderProps } from '@gntik-ai/flow';
+
+export interface FlowBuilderProps<Kind extends string = FlowNodeKind> extends FlowBuilderExtensions {
+  title?: string;
+  nodes?: FlowNode<Kind | FlowNodeKind>[];
+  edges?: FlowEdge[];
+  palette?: PaletteItem[];
+  /**
+   * Console output (controlled). Run and Clear then report the next list through
+   * `onConsoleChange` instead of updating it internally.
+   */
+  consoleEntries?: ConsoleEntry[];
+  /** Initial console output (uncontrolled). Defaults to the sample entries. */
+  defaultConsoleEntries?: ConsoleEntry[];
+  /** Called with the next console list after a run appends to it or it is cleared. */
+  onConsoleChange?: (entries: ConsoleEntry[]) => void;
+  /** Called when the console's Clear button is pressed. */
+  onConsoleClear?: () => void;
+  /** Heading level of the builder title (default h2); panel titles use the next level. */
+  titleAs?: 'h2' | 'h3' | 'h4';
+  /** Total height of the builder on wide screens (px). */
+  height?: number;
+  /**
+   * Called with the current graph when Run is pressed. Return console entries (or a promise
+   * of them) to log the real run; return nothing to log a simulated run. While a returned
+   * promise is pending the Run button shows a loading state; a rejection is logged as an error.
+   */
+  onRun?: (graph: {
+    nodes: FlowNode<Kind | FlowNodeKind>[];
+    edges: FlowEdge[];
+  }) => FlowRunResult | Promise<FlowRunResult>;
+  className?: string;
+}
+
+/** What `onRun` may return: entries to append, or nothing for the simulated run. */
+export type FlowRunResult = ConsoleEntry[] | void | undefined;
+
+const NO_ISSUES: NonNullable<FlowBuilderProps['validationIssues']> = [];
+const WIDE_QUERY = '(min-width: 768px)';
+
+function subscribeWide(onChange: () => void) {
+  if (typeof window === 'undefined' || !window.matchMedia) return () => {};
+  const mql = window.matchMedia(WIDE_QUERY);
+  mql.addEventListener?.('change', onChange);
+  return () => mql.removeEventListener?.('change', onChange);
+}
+
+function useIsWide() {
+  return useSyncExternalStore(
+    subscribeWide,
+    () => (typeof window !== 'undefined' && window.matchMedia ? window.matchMedia(WIDE_QUERY).matches : true),
+    () => true,
+  );
+}
+
+function clock() {
+  return new Date().toLocaleTimeString('en-GB', { hour12: false });
+}
+
+/**
+ * Visual flow builder: node palette, brand React Flow canvas (drag, connect, zoom/pan),
+ * inspector for the selected node and a run console, in resizable panels. On small screens
+ * the panels stack.
+ */
+export function FlowBuilder<Kind extends string = FlowNodeKind>({
+  title = 'Untitled flow',
+  nodes: initialNodes = builderNodes,
+  edges: initialEdges = builderEdges,
+  palette = builderPalette,
+  consoleEntries,
+  defaultConsoleEntries = builderConsole,
+  onConsoleChange,
+  onConsoleClear,
+  titleAs: TitleTag = 'h2',
+  height = 600,
+  onRun,
+  nodeTypes,
+  onConnectEdge,
+  onConnect: onConnected,
+  isValidConnection,
+  onConnectionRejected,
+  validationIssues,
+  mode = 'edit',
+  nodeStatus,
+  onNodeSelect,
+  className,
+}: FlowBuilderProps<Kind>) {
+  const runMode = mode === 'run';
+  const root = useRef<HTMLElement>(null);
+  const wide = useIsWide();
+  const panelAs = TitleTag === 'h2' ? 'h3' : TitleTag === 'h3' ? 'h4' : 'h5';
+  const {
+    nodes,
+    edges,
+    setNodes,
+    setEdges,
+    onNodesChange,
+    onEdgesChange,
+    onConnect: defaultConnect,
+  } = useFlowState<FlowNode<Kind | FlowNodeKind>, FlowEdge>(initialNodes, initialEdges);
+  const [innerLog, setInnerLog] = useState<ConsoleEntry[]>(defaultConsoleEntries);
+  const log = consoleEntries ?? innerLog;
+  const latestLog = useRef(log);
+  useEffect(() => {
+    latestLog.current = log;
+  });
+  const [running, setRunning] = useState(false);
+  const seq = useRef(0);
+  const runs = useRef(0);
+  const selected = nodes.find((n) => n.selected);
+
+  const addNode = (item: PaletteItem) => {
+    seq.current += 1;
+    const id = `${item.kind}-${seq.current}`;
+    const right = nodes.reduce((max, n) => Math.max(max, n.position.x), -256);
+    const slim = item.kind === 'trigger' || item.kind === 'router';
+    const node: FlowNode = {
+      id,
+      type: item.kind,
+      position: { x: right + 256, y: 112 + (seq.current % 3) * 32 },
+      width: 208,
+      height: slim ? 56 : 90,
+      selected: true,
+      data: { title: `New ${item.title.toLowerCase()}`, subtitle: item.description },
+    };
+    setNodes((ns) => [...ns.map((n) => (n.selected ? { ...n, selected: false } : n)), node]);
+  };
+
+  const updateNode = (id: string, patch: Partial<FlowNodeData>) =>
+    setNodes((ns) => ns.map((n) => (n.id === id ? { ...n, data: { ...n.data, ...patch } } : n)));
+
+  const deleteNode = (id: string) => {
+    setNodes((ns) => ns.filter((n) => n.id !== id));
+    setEdges((es) => es.filter((e) => e.source !== id && e.target !== id));
+  };
+
+  const commitLog = (next: ConsoleEntry[]) => {
+    latestLog.current = next;
+    if (consoleEntries === undefined) setInnerLog(next);
+    onConsoleChange?.(next);
+  };
+
+  const simulate = (n: number): ConsoleEntry[] => {
+    const ordered = [...nodes].sort((a, b) => a.position.x - b.position.x || a.position.y - b.position.y);
+    const t = clock();
+    return [
+      { id: `run-${n}-start`, time: t, level: 'info', message: `Run #${n} started · ${nodes.length} nodes` },
+      ...ordered.map<ConsoleEntry>((node, i) => ({
+        id: `run-${n}-${node.id}`,
+        time: t,
+        level: node.data.tone === 'failed' ? 'error' : node.data.tone === 'degraded' ? 'warn' : 'success',
+        message: `${node.data.title} ${node.data.tone === 'failed' ? 'failed' : 'completed'} in ${40 + ((i * 37) % 160)}ms`,
+      })),
+      { id: `run-${n}-end`, time: t, level: 'info', message: `Run #${n} finished` },
+    ];
+  };
+
+  const run = async () => {
+    runs.current += 1;
+    const n = runs.current;
+    const result = onRun?.({ nodes, edges });
+    let added: ConsoleEntry[];
+    if (result instanceof Promise) {
+      setRunning(true);
+      try {
+        added = (await result) ?? simulate(n);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        added = [{ id: `run-${n}-error`, time: clock(), level: 'error', message: `Run #${n} failed: ${message}` }];
+      } finally {
+        setRunning(false);
+      }
+    } else {
+      added = result ?? simulate(n);
+    }
+    commitLog([...latestLog.current, ...added]);
+  };
+
+  const clearLog = () => {
+    onConsoleClear?.();
+    commitLog([]);
+  };
+
+  const connections = useConnections(nodes, setEdges, defaultConnect, {
+    onConnect: onConnected,
+    onConnectEdge,
+    isValidConnection,
+    onConnectionRejected,
+  });
+
+  const issues = validationIssues ?? NO_ISSUES;
+  const displayedNodes = useDecoratedNodes(nodes, issues, nodeStatus, runMode);
+  const selectNode = (id: string) => {
+    setNodes((ns) => ns.map((n) => ({ ...n, selected: n.id === id })));
+    // Focus only within this builder; graph ids may repeat across independent canvases.
+    const element = root.current?.querySelector<HTMLElement>(`.react-flow__node[data-id="${CSS.escape(id)}"]`);
+    element?.focus();
+    onNodeSelect?.(id);
+  };
+
+  const canvas = (h: number | string) => (
+    <FlowCanvas<FlowNode<Kind | FlowNodeKind>, FlowEdge>
+      aria-label={`${title} canvas`}
+      height={h}
+      nodes={displayedNodes}
+      edges={edges}
+      onNodesChange={(changes) =>
+        onNodesChange(
+          runMode ? changes.filter((change) => change.type === 'select' || change.type === 'dimensions') : changes,
+        )
+      }
+      onEdgesChange={(changes) =>
+        onEdgesChange(runMode ? changes.filter((change) => change.type === 'select') : changes)
+      }
+      nodeRenderers={nodeTypes}
+      showInteractiveControls={!runMode}
+      elementsSelectable
+      nodesFocusable
+      nodesDraggable={!runMode}
+      nodesConnectable={!runMode}
+      deleteKeyCode={runMode ? null : 'Backspace'}
+      onNodeClick={(_, node) => onNodeSelect?.(node.id)}
+      onKeyDown={(event) => {
+        if (event.key !== 'Enter' && event.key !== ' ') return;
+        const element = (event.target as HTMLElement).closest('.react-flow__node');
+        const id = element?.getAttribute('data-id');
+        if (id) onNodeSelect?.(id);
+      }}
+      ariaLabelConfig={
+        runMode
+          ? {
+              'node.a11yDescription.default': 'Press enter or space to select a node.',
+            }
+          : undefined
+      }
+      onConnect={runMode ? undefined : connections.connect}
+      isValidConnection={runMode ? () => false : connections.validate}
+      onConnectStart={connections.reset}
+      onClickConnectStart={connections.reset}
+      onConnectEnd={(_, state) => (state.toNode ? connections.finish() : connections.reset())}
+      onClickConnectEnd={connections.finish}
+      showMiniMap={wide}
+    />
+  );
+  const palettePanel = <NodePalette items={palette} onAdd={addNode} titleAs={panelAs} />;
+  const inspector = <NodeInspector node={selected} onChange={updateNode} onDelete={deleteNode} titleAs={panelAs} />;
+  const consolePanel = (
+    <div className="flex h-full min-h-0 flex-col">
+      <FlowProblems issues={issues} onSelect={selectNode} titleAs={panelAs} />
+      <RunConsole entries={log} onClear={clearLog} titleAs={panelAs} />
+    </div>
+  );
+
+  let body: ReactNode;
+  if (runMode) {
+    body = (
+      <div className="flex flex-col divide-y divide-border">
+        {canvas(wide ? height - 180 : 360)}
+        <div className="h-40">{consolePanel}</div>
+      </div>
+    );
+  } else if (wide) {
+    body = (
+      <ResizablePanelGroup direction="vertical" style={{ height }}>
+        <ResizablePanel defaultSize={72} minSize={40}>
+          <ResizablePanelGroup className="h-full">
+            <ResizablePanel defaultSize={18} minSize={12} maxSize={32} collapsible>
+              {palettePanel}
+            </ResizablePanel>
+            <ResizeHandle aria-label="Resize node palette" />
+            <ResizablePanel defaultSize={58} minSize={30}>
+              {canvas('100%')}
+            </ResizablePanel>
+            <ResizeHandle aria-label="Resize inspector" />
+            <ResizablePanel defaultSize={24} minSize={16} maxSize={40} collapsible>
+              {inspector}
+            </ResizablePanel>
+          </ResizablePanelGroup>
+        </ResizablePanel>
+        <ResizeHandle aria-label="Resize run console" />
+        <ResizablePanel defaultSize={28} minSize={12} collapsible>
+          {consolePanel}
+        </ResizablePanel>
+      </ResizablePanelGroup>
+    );
+  } else {
+    body = (
+      <div className="flex flex-col divide-y divide-border">
+        <div className="max-h-56">{palettePanel}</div>
+        {canvas(360)}
+        <div>{inspector}</div>
+        <div className="h-48">{consolePanel}</div>
+      </div>
+    );
+  }
+
+  return (
+    <section
+      ref={root}
+      aria-label={title}
+      className={cn('overflow-hidden rounded-lg border border-border bg-card shadow-sm', className)}
+    >
+      <header className="flex items-center justify-between gap-3 border-b border-border bg-secondary/35 px-3 py-2">
+        <div className="min-w-0">
+          <TitleTag className="truncate text-[13.5px] font-semibold text-foreground">{title}</TitleTag>
+          <p className="font-mono text-[11px] text-muted-foreground">
+            {nodes.length} nodes · {edges.length} edges
+          </p>
+        </div>
+        {!runMode && (
+          <Button size="sm" icon={Play} loading={running} onClick={() => void run()}>
+            Run
+          </Button>
+        )}
+      </header>
+      {body}
+    </section>
+  );
+}

package/src/builders/FlowBuilder/block.meta.ts

@@ -0,0 +1,20 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'Flow builder',
+  family: 'builders',
+  status: 'beta',
+  description:
+    'Visual flow editor with optional nodeTypes for named handles (branch-arm, parallel and sequence examples), onConnectEdge for edge type/data mapping, isValidConnection and onConnectionRejected for rules, onConnect for accepted connections, validationIssues for node/flow problems, mode="run" for a read-only canvas, nodeStatus for live badges, and onNodeSelect for pointer/keyboard selection. Optional nodeTypes registers kit-owned {type, handles:[{id,kind,position?,label?}], render, decorations?} definitions (no React Flow NodeProps). Keep nodeTypes and its renderer definitions stable (module scope or useMemo) across nodeStatus updates: recreating the array rebuilds custom node components and remounts them, defeating per-node memoization. onConnectEdge({source,target,sourceType,targetType,sourceHandle,targetHandle}) returns {type,data}; examples/extensions.tsx maps branch arm-0 to {kind: "branch-arm", armIndex: 0}, parallel branch to {kind: "parallel"}, and sequence next to {kind: "sequence"}. isValidConnection returns true, false, or {code,nodeId?,message}; onConnectionRejected reports {code,nodeId,message} once (nodeId defaults to the source) so consumers can forward it into validationIssues and control its lifetime, while onConnect reports accepted connections only. validationIssues decorates nodes with an icon and accessible text; node issues select and focus their node, and flow issues have no node link. mode="run" removes the Run action, palette, inspector and graph mutation while keeping labelled keyboard-selectable nodes, pan/zoom, fit controls and the wide-screen minimap. nodeStatus maps node IDs to FlowTone badges (running, degraded, failed, paused, done, handoff, review); onNodeSelect(id) handles pointer and keyboard selection. RunFlowExample shows live updates with per-node memoization. FlowNode defaults to the built-in FlowNodeKind union; use FlowNode<string> (or a custom kind union) for custom graphs, inferred by FlowBuilder and WorkflowBuilderPage. Custom renderers use kit status overlays and issue decorations by default; set decorations:"consumer" when render owns them, using data.decoration with accessible text and icons (for example, render:({data}) => <NodeCard title={data.title} tone={data.decoration?.status} />). FlowCanvas showInteractiveControls=false retains zoom/fit without the editing toggle. Named handles are keyboard controls: Enter or Space starts or completes a connection in edit mode; handles are disabled in run mode.',
+  uses: [
+    'FlowCanvas',
+    'useFlowState',
+    'ResizablePanelGroup',
+    'ResizablePanel',
+    'ResizeHandle',
+    'Button',
+    'Field',
+    'Input',
+    'SimpleSelect',
+  ],
+};

package/src/builders/FlowBuilder/connections.ts

@@ -0,0 +1,67 @@
+import { useRef, type Dispatch, type SetStateAction } from 'react';
+import type { FlowCanvasProps, FlowNode } from '@gntik-ai/flow';
+import type { FlowBuilderExtensions, FlowConnection, FlowConnectionRejection } from './extensions';
+import type { FlowEdge } from './fixtures';
+
+type Connect = NonNullable<FlowCanvasProps<FlowNode<string>, FlowEdge>['onConnect']>;
+type Candidate = Parameters<NonNullable<FlowCanvasProps<FlowNode<string>, FlowEdge>['isValidConnection']>>[0];
+
+export function useConnections(
+  nodes: FlowNode<string>[],
+  setEdges: Dispatch<SetStateAction<FlowEdge[]>>,
+  defaultConnect: Connect,
+  props: FlowBuilderExtensions,
+) {
+  const pending = useRef<FlowConnectionRejection | null>(null);
+  const seq = useRef(0);
+  const describe = (c: Candidate): FlowConnection => ({
+    source: c.source,
+    target: c.target,
+    sourceHandle: c.sourceHandle ?? null,
+    targetHandle: c.targetHandle ?? null,
+    sourceType: nodes.find((n) => n.id === c.source)?.type ?? 'step',
+    targetType: nodes.find((n) => n.id === c.target)?.type ?? 'step',
+  });
+  const reset = () => {
+    pending.current = null;
+  };
+  const validate = (c: Candidate) => {
+    const result = props.isValidConnection?.(describe(c)) ?? true;
+    pending.current =
+      result === true
+        ? null
+        : result === false
+          ? {
+              code: 'invalid-connection',
+              nodeId: c.source,
+              message: 'This connection is not allowed.',
+            }
+          : { ...result, nodeId: result.nodeId ?? c.source };
+    return result === true;
+  };
+  const finish = () => {
+    const issue = pending.current;
+    reset();
+    if (!issue) return;
+    props.onConnectionRejected?.(issue);
+  };
+  const connect: Connect = (c) => {
+    if (!validate(c)) {
+      finish();
+      return;
+    }
+    if (props.onConnectEdge) {
+      const mapped = props.onConnectEdge(describe(c));
+      setEdges((es) => [
+        ...es,
+        {
+          ...c,
+          ...mapped,
+          id: `edge-${++seq.current}-${c.source}-${c.target}`,
+        },
+      ]);
+    } else defaultConnect(c);
+    props.onConnect?.(describe(c));
+  };
+  return { connect, validate, finish, reset };
+}

package/src/builders/FlowBuilder/decorated-nodes.ts

@@ -0,0 +1,80 @@
+import { useState } from 'react';
+import type { FlowNode, FlowTone } from '@gntik-ai/flow';
+import type { FlowValidationIssue } from './extensions';
+
+type Statuses = Readonly<Record<string, FlowTone | undefined>> | undefined;
+interface CachedNode<Kind extends string> {
+  original: FlowNode<Kind>;
+  status: FlowTone | undefined;
+  issuesKey: string;
+  runMode: boolean;
+  node: FlowNode<Kind>;
+}
+
+function project<Kind extends string>(
+  nodes: FlowNode<Kind>[],
+  issues: readonly FlowValidationIssue[],
+  statuses: Statuses,
+  runMode: boolean,
+  previous: ReadonlyMap<string, CachedNode<Kind>>,
+) {
+  const cache = new Map<string, CachedNode<Kind>>();
+  const displayed = nodes.map((original) => {
+    const nodeIssues = issues.filter((issue) => issue.nodeId === original.id);
+    const issuesKey = JSON.stringify(nodeIssues);
+    const status = statuses?.[original.id];
+    const old = previous.get(original.id);
+    if (old?.original === original && old.status === status && old.issuesKey === issuesKey && old.runMode === runMode) {
+      cache.set(original.id, old);
+      return old.node;
+    }
+    const node: FlowNode<Kind> = {
+      ...original,
+      ...(runMode
+        ? {
+            draggable: false,
+            connectable: false,
+            deletable: false,
+            focusable: true,
+            selectable: true,
+            ariaLabel: original.data.title,
+          }
+        : {}),
+      data:
+        nodeIssues.length || status
+          ? {
+              ...original.data,
+              decoration: {
+                ...original.data.decoration,
+                status,
+                issues: nodeIssues,
+              },
+            }
+          : original.data,
+    };
+    cache.set(original.id, { original, status, issuesKey, runMode, node });
+    return node;
+  });
+  return { nodes, issues, statuses, runMode, cache, displayed };
+}
+
+/** Derive a snapshot when inputs change; preserve other nodes' identities without mutating a render cache. */
+export function useDecoratedNodes<Kind extends string>(
+  nodes: FlowNode<Kind>[],
+  issues: readonly FlowValidationIssue[],
+  statuses: Statuses,
+  runMode: boolean,
+) {
+  const [snapshot, setSnapshot] = useState(() => project(nodes, issues, statuses, runMode, new Map()));
+  if (
+    snapshot.nodes !== nodes ||
+    snapshot.issues !== issues ||
+    snapshot.statuses !== statuses ||
+    snapshot.runMode !== runMode
+  ) {
+    const next = project(nodes, issues, statuses, runMode, snapshot.cache);
+    setSnapshot(next);
+    return next.displayed;
+  }
+  return snapshot.displayed;
+}

package/src/builders/FlowBuilder/examples/extensions.tsx

@@ -0,0 +1,120 @@
+import { useState } from 'react';
+import { NodeCard, type FlowNodeRenderer } from '@gntik-ai/flow';
+import { Button } from '@gntik-ai/ui';
+import { FlowBuilder, type FlowConnection, type FlowNode, type FlowTone } from '../FlowBuilder';
+
+const nodeTypes: FlowNodeRenderer[] = [
+  {
+    type: 'branch',
+    handles: [
+      { id: 'input', kind: 'target' },
+      { id: 'arm-0', kind: 'source' },
+      { id: 'arm-1', kind: 'source' },
+    ],
+    render: ({ data, selected }) => <NodeCard title={data.title} selected={selected} />,
+  },
+  {
+    type: 'parallel',
+    handles: [
+      { id: 'input', kind: 'target' },
+      { id: 'branch', kind: 'source' },
+    ],
+    render: ({ data, selected }) => <NodeCard title={data.title} selected={selected} />,
+  },
+  {
+    type: 'sequence',
+    handles: [
+      { id: 'input', kind: 'target' },
+      { id: 'next', kind: 'source' },
+    ],
+    render: ({ data, selected }) => <NodeCard title={data.title} selected={selected} />,
+  },
+];
+const nodes: FlowNode<string>[] = [
+  {
+    id: 'branch',
+    type: 'branch',
+    position: { x: 0, y: 64 },
+    data: { title: 'Branch' },
+  },
+  {
+    id: 'parallel',
+    type: 'parallel',
+    position: { x: 256, y: 0 },
+    data: { title: 'Parallel' },
+  },
+  {
+    id: 'sequence',
+    type: 'sequence',
+    position: { x: 256, y: 160 },
+    data: { title: 'Sequence' },
+  },
+];
+
+function mapEdge(c: FlowConnection) {
+  if (c.sourceType === 'branch')
+    return {
+      type: 'smoothstep',
+      data: {
+        kind: 'branch-arm',
+        armIndex: Number(c.sourceHandle?.split('-')[1]),
+      },
+    };
+  if (c.sourceType === 'parallel') return { type: 'smoothstep', data: { kind: 'parallel', branch: 'first' } };
+  return { type: 'smoothstep', data: { kind: 'sequence', step: 1 } };
+}
+
+/** Named branch arms, parallel and sequence handles. Edge payloads remain consumer-owned. */
+export default function CustomFlowExample() {
+  const [rejected, setRejected] = useState('');
+  return (
+    <>
+      <FlowBuilder
+        nodes={nodes}
+        edges={[]}
+        nodeTypes={nodeTypes}
+        onConnectEdge={mapEdge}
+        isValidConnection={(c) =>
+          c.source !== c.target || {
+            code: 'self-loop',
+            nodeId: c.source,
+            message: 'Choose another target node.',
+          }
+        }
+        onConnectionRejected={(issue) => setRejected(issue.message)}
+        validationIssues={[
+          {
+            code: 'required',
+            nodeId: 'branch',
+            message: 'Choose a branch condition.',
+          },
+          { code: 'terminal', message: 'Add a terminal step.' },
+        ]}
+      />
+      <p aria-live="polite">{rejected}</p>
+    </>
+  );
+}
+
+export function RunFlowExample() {
+  const [status, setStatus] = useState<Record<string, FlowTone>>({
+    branch: 'running',
+    parallel: 'paused',
+    sequence: 'paused',
+  });
+  const [selected, setSelected] = useState('');
+  return (
+    <>
+      <FlowBuilder
+        nodes={nodes}
+        edges={[]}
+        nodeTypes={nodeTypes}
+        mode="run"
+        nodeStatus={status}
+        onNodeSelect={setSelected}
+      />
+      <Button onClick={() => setStatus((s) => ({ ...s, branch: 'done' }))}>Complete branch</Button>
+      <p aria-live="polite">{selected && `Selected node: ${selected}`}</p>
+    </>
+  );
+}

package/src/builders/FlowBuilder/extensions.ts

@@ -0,0 +1,37 @@
+import type { FlowNodeRenderer, FlowTone } from '@gntik-ai/flow';
+import type { FlowEdge } from './fixtures';
+
+/** Connection plus node type identifiers, for consumer edge mapping and validation. */
+export interface FlowConnection {
+  source: string;
+  target: string;
+  sourceHandle: string | null;
+  targetHandle: string | null;
+  sourceType: string;
+  targetType: string;
+}
+
+export interface FlowValidationIssue {
+  code: string;
+  nodeId?: string;
+  message: string;
+}
+
+export interface FlowConnectionRejection extends FlowValidationIssue {
+  nodeId: string;
+}
+
+export interface FlowBuilderExtensions {
+  mode?: 'edit' | 'run';
+  nodeStatus?: Readonly<Record<string, FlowTone | undefined>>;
+  onNodeSelect?: (id: string) => void;
+  validationIssues?: readonly FlowValidationIssue[];
+  nodeTypes?: readonly FlowNodeRenderer[];
+  /** Return edge kind and payload; endpoints always come from the connection. */
+  onConnectEdge?: (connection: FlowConnection) => Pick<FlowEdge, 'type' | 'data'>;
+  /** Return true to accept, false for a generic rejection, or an issue for a specific reason. Pure: called during dragging. */
+  isValidConnection?: (connection: FlowConnection) => boolean | FlowValidationIssue;
+  onConnectionRejected?: (issue: FlowConnectionRejection) => void;
+  /** Called only after an accepted connection has been added. */
+  onConnect?: (connection: FlowConnection) => void;
+}