@particle-academy/fancy-flow 0.18.0 → 0.19.0

package/dist/runtime.js

@@ -1,4 +1,4 @@
-export { applyStatusesToNodes, useFlowRun, useFlowState } from './chunk-MFMRTRPO.js';
+export { applyStatusesToNodes, createHistory, useFlowHistory, useFlowRun, useFlowState } from './chunk-PHX4SBOD.js';
 import './chunk-NF6NPY5N.js';
 export { runFlow } from './chunk-L4AX73Q6.js';
 import './chunk-TITD5W4Y.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/fancy-flow",
-  "version": "0.18.0",
+  "version": "0.19.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",
@@ -99,9 +99,9 @@
   "peerDependencies": {
     "@particle-academy/fancy-cms-ui": ">=0.2",
     "@particle-academy/react-fancy": ">=3",
+    "ai": ">=5",
     "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0",
-    "ai": ">=5"
+    "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
     "@particle-academy/fancy-auto-common": "^0.1.0"
@@ -109,11 +109,14 @@
   "devDependencies": {
     "@particle-academy/fancy-cms-ui": "^0.2.0",
     "@particle-academy/react-fancy": "^4.15.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@xyflow/react": "^12.4.0",
     "ai": "^7.0.31",
     "clsx": "^2.1.0",
+    "jsdom": "^29.1.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "tsup": "^8.0.0",

package/dist/chunk-MFMRTRPO.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/runtime/use-flow-run.ts","../src/runtime/use-flow-state.ts"],"names":["useState","useCallback"],"mappings":"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","file":"chunk-MFMRTRPO.js","sourcesContent":["import { useCallback, useRef, useState } from \"react\";\nimport { runFlow, type RunOptions, type RunResult } from \"./run-flow\";\nimport type {\n  ExecutorRegistry,\n  FlowGraph,\n  NodeRunStatus,\n  RunEvent,\n} from \"../types\";\n\nexport type FlowRunFeedEntry = {\n  id: string;\n  at: number;\n  level: \"info\" | \"warn\" | \"error\" | \"status\";\n  text: string;\n  nodeId?: string;\n  detail?: unknown;\n};\n\nexport type UseFlowRunReturn = {\n  /** Status keyed by nodeId — drive the UI overlay from this. */\n  statuses: Record<string, NodeRunStatus>;\n  /** Per-node status text (e.g. error message). */\n  statusText: Record<string, string | undefined>;\n  /** Live event log (capped to last N). */\n  feed: FlowRunFeedEntry[];\n  /** Whether a run is currently in progress. */\n  running: boolean;\n  /** Last run result, or null. */\n  lastResult: RunResult | null;\n  /** Kick off a run with the provided graph + executors. */\n  run: (graph: FlowGraph, executors: ExecutorRegistry, options?: RunOptions) => Promise<RunResult>;\n  /** Cancel the current run (if any). */\n  cancel: () => void;\n  /** Reset all runtime state (statuses, feed, lastResult). */\n  reset: () => void;\n};\n\nexport type UseFlowRunOptions = {\n  /** Cap the in-memory feed to this many entries. Default 200. */\n  maxFeed?: number;\n};\n\n/**\n * useFlowRun — drives `runFlow` + maintains observability state. Pair with\n * `applyStatusesToNodes` (below) before passing nodes to `<FlowCanvas>` so\n * the per-node status badge renders.\n */\nexport function useFlowRun({ maxFeed = 200 }: UseFlowRunOptions = {}): UseFlowRunReturn {\n  const [statuses, setStatuses] = useState<Record<string, NodeRunStatus>>({});\n  const [statusText, setStatusText] = useState<Record<string, string | undefined>>({});\n  const [feed, setFeed] = useState<FlowRunFeedEntry[]>([]);\n  const [running, setRunning] = useState(false);\n  const [lastResult, setLastResult] = useState<RunResult | null>(null);\n  const abortRef = useRef<AbortController | null>(null);\n\n  const handleEvent = useCallback(\n    (e: RunEvent) => {\n      switch (e.type) {\n        case \"node-status\":\n          setStatuses((s) => ({ ...s, [e.nodeId]: e.status }));\n          setStatusText((t) => ({ ...t, [e.nodeId]: e.text }));\n          appendFeed({ level: \"status\", text: `${e.nodeId} → ${e.status}${e.text ? ` (${e.text})` : \"\"}`, nodeId: e.nodeId });\n          break;\n        case \"node-output\":\n          appendFeed({ level: \"info\", text: `${e.nodeId}.${e.portId} = ${preview(e.value)}`, nodeId: e.nodeId, detail: e.value });\n          break;\n        case \"log\":\n          appendFeed({ level: e.level, text: e.message, nodeId: e.nodeId, detail: e.detail });\n          break;\n        case \"run-start\":\n          appendFeed({ level: \"info\", text: \"▶ run started\" });\n          break;\n        case \"run-end\":\n          appendFeed({ level: e.ok ? \"info\" : \"error\", text: e.ok ? \"✓ run complete\" : \"✗ run failed\" });\n          break;\n        case \"run-error\":\n          appendFeed({ level: \"error\", text: e.error });\n          break;\n      }\n      function appendFeed(partial: Omit<FlowRunFeedEntry, \"id\" | \"at\">) {\n        setFeed((f) => {\n          const entry: FlowRunFeedEntry = { id: `${Date.now()}_${f.length}`, at: Date.now(), ...partial };\n          const next = [...f, entry];\n          return next.length > maxFeed ? next.slice(next.length - maxFeed) : next;\n        });\n      }\n    },\n    [maxFeed],\n  );\n\n  const run = useCallback(\n    async (graph: FlowGraph, executors: ExecutorRegistry, options: RunOptions = {}) => {\n      if (running) {\n        return { ok: false, outputs: {}, error: \"another run is already in progress\" } satisfies RunResult;\n      }\n      const controller = new AbortController();\n      abortRef.current = controller;\n      // Reset previous statuses for the nodes we're about to run.\n      const idleStatuses: Record<string, NodeRunStatus> = {};\n      for (const n of graph.nodes) idleStatuses[n.id] = \"idle\";\n      setStatuses(idleStatuses);\n      setStatusText({});\n      setRunning(true);\n      try {\n        const result = await runFlow(graph, executors, handleEvent, { ...options, signal: controller.signal });\n        setLastResult(result);\n        return result;\n      } finally {\n        setRunning(false);\n        abortRef.current = null;\n      }\n    },\n    [handleEvent, running],\n  );\n\n  const cancel = useCallback(() => abortRef.current?.abort(), []);\n\n  const reset = useCallback(() => {\n    setStatuses({});\n    setStatusText({});\n    setFeed([]);\n    setLastResult(null);\n  }, []);\n\n  return { statuses, statusText, feed, running, lastResult, run, cancel, reset };\n}\n\n/** Merge runtime statuses into nodes for rendering. */\nexport function applyStatusesToNodes<TNode extends { id: string; data: any }>(\n  nodes: TNode[],\n  statuses: Record<string, NodeRunStatus>,\n  statusText: Record<string, string | undefined>,\n): TNode[] {\n  return nodes.map((n) => ({\n    ...n,\n    data: {\n      ...n.data,\n      status: statuses[n.id] ?? n.data?.status ?? \"idle\",\n      statusText: statusText[n.id] ?? n.data?.statusText,\n    },\n  }));\n}\n\nfunction preview(v: unknown): string {\n  try {\n    const s = JSON.stringify(v);\n    return s && s.length > 60 ? s.slice(0, 57) + \"…\" : (s ?? String(v));\n  } catch {\n    return String(v);\n  }\n}\n","import { useCallback, useState } from \"react\";\nimport {\n  addEdge,\n  applyEdgeChanges,\n  applyNodeChanges,\n  type Connection,\n  type Edge,\n  type EdgeChange,\n  type NodeChange,\n} from \"@xyflow/react\";\nimport type { FlowEdge, FlowGraph, FlowNode } from \"../types\";\n\nexport type UseFlowStateReturn = {\n  nodes: FlowNode[];\n  edges: FlowEdge[];\n  setNodes: React.Dispatch<React.SetStateAction<FlowNode[]>>;\n  setEdges: React.Dispatch<React.SetStateAction<FlowEdge[]>>;\n  onNodesChange: (changes: NodeChange[]) => void;\n  onEdgesChange: (changes: EdgeChange[]) => void;\n  onConnect: (connection: Connection) => void;\n  /** Snapshot the current graph (suitable for serialization). */\n  toGraph: () => FlowGraph;\n};\n\n/**\n * useFlowState — React Flow's standard controlled-state plumbing in one hook.\n * Spread into <FlowCanvas>.\n */\nexport function useFlowState(initial: FlowGraph): UseFlowStateReturn {\n  const [nodes, setNodes] = useState<FlowNode[]>(initial.nodes);\n  const [edges, setEdges] = useState<FlowEdge[]>(initial.edges);\n\n  const onNodesChange = useCallback((changes: NodeChange[]) => {\n    setNodes((ns) => applyNodeChanges(changes, ns) as FlowNode[]);\n  }, []);\n  const onEdgesChange = useCallback((changes: EdgeChange[]) => {\n    setEdges((es) => applyEdgeChanges(changes, es));\n  }, []);\n  const onConnect = useCallback((connection: Connection) => {\n    setEdges((es) => addEdge(connection, es) as Edge[]);\n  }, []);\n\n  const toGraph = useCallback(() => ({ nodes, edges }), [nodes, edges]);\n\n  return { nodes, edges, setNodes, setEdges, onNodesChange, onEdgesChange, onConnect, toGraph };\n}\n"]}