@startsimpli/ui 0.4.14 → 0.4.16

package/src/components/workflows/__tests__/WorkflowRunViewer.test.tsx

@@ -0,0 +1,138 @@
+import { render, screen, fireEvent } from '@testing-library/react';
+import { WorkflowRunViewer } from '../WorkflowRunViewer';
+import { ExecNodeDetails } from '../ExecNodeDetails';
+import type { WfExecutionView, NodeExecView } from '../types';
+
+// jsdom lacks matchMedia, which DualPaneWorkspace uses for its `auto` layout.
+beforeAll(() => {
+  Object.defineProperty(window, 'matchMedia', {
+    writable: true,
+    value: (query: string) => ({
+      matches: false,
+      media: query,
+      onchange: null,
+      addEventListener: () => {},
+      removeEventListener: () => {},
+      addListener: () => {},
+      removeListener: () => {},
+      dispatchEvent: () => false,
+    }),
+  });
+});
+
+function makeExecution(overrides: Partial<WfExecutionView> = {}): WfExecutionView {
+  const nodeA: NodeExecView = {
+    nodeId: 'a',
+    name: 'Fetch data',
+    type: 'trigger.event',
+    status: 'success',
+    executionOrder: 0,
+    executionTimeMs: 1000,
+    inputData: { foo: 'in' },
+    outputData: { foo: 'out' },
+  };
+  const nodeB: NodeExecView = {
+    nodeId: 'b',
+    name: 'Transform',
+    type: 'transform.set',
+    status: 'running',
+    executionOrder: 1,
+  };
+  return {
+    executionId: 'exec-1',
+    status: 'running',
+    nodes: { a: nodeA, b: nodeB },
+    ...overrides,
+  };
+}
+
+describe('WorkflowRunViewer', () => {
+  it('renders the run status header badge', () => {
+    render(<WorkflowRunViewer execution={makeExecution({ status: 'completed' })} />);
+    expect(screen.getByText('Completed')).toBeInTheDocument();
+  });
+
+  it('renders the timeline with a row per node, ordered by executionOrder', () => {
+    render(<WorkflowRunViewer execution={makeExecution()} />);
+    const rows = screen.getAllByRole('listitem');
+    expect(rows).toHaveLength(2);
+    expect(rows[0]).toHaveTextContent('Fetch data');
+    expect(rows[1]).toHaveTextContent('Transform');
+  });
+
+  it('shows selected-node details when a timeline row is selected', () => {
+    render(<WorkflowRunViewer execution={makeExecution()} />);
+    fireEvent.click(screen.getByText('Fetch data'));
+    // detail panel shows the selected node name as a heading + pretty JSON
+    expect(
+      screen.getByRole('heading', { name: 'Fetch data' })
+    ).toBeInTheDocument();
+    expect(screen.getByText(/"foo": "out"/)).toBeInTheDocument();
+  });
+
+  it('updates the selected-node details when a new snapshot is passed', () => {
+    const { rerender } = render(<WorkflowRunViewer execution={makeExecution()} />);
+    fireEvent.click(screen.getByText('Transform'));
+    // node b selected; detail panel headed by its name
+    expect(
+      screen.getByRole('heading', { name: 'Transform' })
+    ).toBeInTheDocument();
+
+    const next = makeExecution({ status: 'completed' });
+    next.nodes.b = {
+      ...next.nodes.b,
+      status: 'success',
+      executionTimeMs: 250,
+      outputData: { done: true },
+    };
+    rerender(<WorkflowRunViewer execution={next} />);
+    // detail panel reflects the new snapshot for the still-selected node b
+    expect(screen.getByText(/"done": true/)).toBeInTheDocument();
+  });
+
+  it('renders an empty state when there are no node executions', () => {
+    render(
+      <WorkflowRunViewer
+        execution={{ executionId: 'x', status: 'pending', nodes: {} }}
+      />
+    );
+    expect(screen.queryAllByRole('listitem')).toHaveLength(0);
+    expect(screen.getByText('Pending')).toBeInTheDocument();
+  });
+});
+
+describe('ExecNodeDetails', () => {
+  const node: NodeExecView = {
+    nodeId: 'a',
+    name: 'Fetch data',
+    type: 'trigger.event',
+    status: 'error',
+    executionOrder: 0,
+    error: 'boom',
+    inputData: { a: 1 },
+    outputData: { b: 2 },
+  };
+
+  it('renders node name, type and status', () => {
+    render(<ExecNodeDetails node={node} />);
+    expect(screen.getByText('Fetch data')).toBeInTheDocument();
+    expect(screen.getByText('trigger.event')).toBeInTheDocument();
+    expect(screen.getByText('Error')).toBeInTheDocument();
+  });
+
+  it('pretty-prints input and output JSON', () => {
+    render(<ExecNodeDetails node={node} />);
+    expect(screen.getByText(/"a": 1/)).toBeInTheDocument();
+    expect(screen.getByText(/"b": 2/)).toBeInTheDocument();
+  });
+
+  it('renders error message when present', () => {
+    render(<ExecNodeDetails node={node} />);
+    expect(screen.getByText('boom')).toBeInTheDocument();
+  });
+
+  it('renders an empty state when no node is selected', () => {
+    render(<ExecNodeDetails node={null} />);
+    expect(screen.getByText(/select a node/i)).toBeInTheDocument();
+  });
+});

package/src/components/workflows/__tests__/auto-layout.test.ts

@@ -0,0 +1,107 @@
+import { autoLayout } from '../layout/auto-layout';
+import { graphToFlow } from '../serialization';
+import type { WorkflowGraph } from '../types';
+
+function noOverlap(
+  nodes: { id: string; position: { x: number; y: number }; width?: number; height?: number }[]
+): boolean {
+  for (let i = 0; i < nodes.length; i++) {
+    for (let j = i + 1; j < nodes.length; j++) {
+      const a = nodes[i];
+      const b = nodes[j];
+      const aw = a.width ?? 180;
+      const ah = a.height ?? 60;
+      const bw = b.width ?? 180;
+      const bh = b.height ?? 60;
+      const overlapX = a.position.x < b.position.x + bw && a.position.x + aw > b.position.x;
+      const overlapY = a.position.y < b.position.y + bh && a.position.y + ah > b.position.y;
+      if (overlapX && overlapY) return false;
+    }
+  }
+  return true;
+}
+
+const chainGraph: WorkflowGraph = {
+  nodes: [
+    { id: 'a', name: 'A', type: 't' },
+    { id: 'b', name: 'B', type: 't' },
+    { id: 'c', name: 'C', type: 't' },
+  ],
+  edges: [
+    { source: 'a', target: 'b' },
+    { source: 'b', target: 'c' },
+  ],
+};
+
+describe('auto-layout', () => {
+  it('assigns non-overlapping positions (LR)', () => {
+    const { nodes, edges } = graphToFlow(chainGraph);
+    const laid = autoLayout(nodes, edges, { direction: 'LR' });
+    expect(laid.nodes).toHaveLength(3);
+    expect(noOverlap(laid.nodes)).toBe(true);
+  });
+
+  it('LR lays out left-to-right (x increases along the chain)', () => {
+    const { nodes, edges } = graphToFlow(chainGraph);
+    const laid = autoLayout(nodes, edges, { direction: 'LR' });
+    const byId = Object.fromEntries(laid.nodes.map((n) => [n.id, n]));
+    expect(byId.b.position.x).toBeGreaterThan(byId.a.position.x);
+    expect(byId.c.position.x).toBeGreaterThan(byId.b.position.x);
+  });
+
+  it('TB lays out top-to-bottom (y increases along the chain)', () => {
+    const { nodes, edges } = graphToFlow(chainGraph);
+    const laid = autoLayout(nodes, edges, { direction: 'TB' });
+    const byId = Object.fromEntries(laid.nodes.map((n) => [n.id, n]));
+    expect(byId.b.position.y).toBeGreaterThan(byId.a.position.y);
+    expect(byId.c.position.y).toBeGreaterThan(byId.b.position.y);
+  });
+
+  it('preserves explicit positions when preservePositions is set', () => {
+    const graph: WorkflowGraph = {
+      nodes: [
+        { id: 'a', name: 'A', type: 't', position: { x: 500, y: 500 } },
+        { id: 'b', name: 'B', type: 't' },
+      ],
+      edges: [{ source: 'a', target: 'b' }],
+    };
+    const { nodes, edges } = graphToFlow(graph);
+    const laid = autoLayout(nodes, edges, { direction: 'LR', preservePositions: true });
+    const byId = Object.fromEntries(laid.nodes.map((n) => [n.id, n]));
+    expect(byId.a.position).toEqual({ x: 500, y: 500 });
+    // b still gets a computed position
+    expect(byId.b.position).toBeDefined();
+  });
+
+  it('places an edgeless / orphan node (still gets a position, no overlap)', () => {
+    const graph: WorkflowGraph = {
+      nodes: [
+        { id: 'a', name: 'A', type: 't' },
+        { id: 'b', name: 'B', type: 't' },
+        { id: 'orphan', name: 'O', type: 't' },
+      ],
+      edges: [{ source: 'a', target: 'b' }],
+    };
+    const { nodes, edges } = graphToFlow(graph);
+    const laid = autoLayout(nodes, edges, { direction: 'LR' });
+    const orphan = laid.nodes.find((n) => n.id === 'orphan');
+    expect(orphan).toBeDefined();
+    expect(orphan!.position).toBeDefined();
+    expect(Number.isFinite(orphan!.position.x)).toBe(true);
+    expect(Number.isFinite(orphan!.position.y)).toBe(true);
+    expect(noOverlap(laid.nodes)).toBe(true);
+  });
+
+  it('handles an empty node set', () => {
+    const laid = autoLayout([], [], { direction: 'TB' });
+    expect(laid.nodes).toEqual([]);
+    expect(laid.edges).toEqual([]);
+  });
+
+  it('defaults to TB when no direction is given', () => {
+    const { nodes, edges } = graphToFlow(chainGraph);
+    const laid = autoLayout(nodes, edges);
+    const byId = Object.fromEntries(laid.nodes.map((n) => [n.id, n]));
+    expect(byId.c.position.y).toBeGreaterThan(byId.a.position.y);
+  });
+});

package/src/components/workflows/__tests__/serialization.test.ts

@@ -0,0 +1,278 @@
+import { graphToFlow, flowToGraph } from '../serialization';
+import type { WorkflowGraph, BackendConnections } from '../types';
+
+/**
+ * Build the LOCKED backend connections shape directly so we test against
+ * the exact format the Django test suite constructs:
+ *
+ *   { sourceId: { "main": [[{ node, type, index }]] } }
+ */
+
+describe('serialization — graphToFlow', () => {
+  it('converts a single-output edge to one flow edge', () => {
+    const graph: WorkflowGraph = {
+      nodes: [
+        { id: 'a', name: 'A', type: 'trigger.event' },
+        { id: 'b', name: 'B', type: 'transform.set' },
+      ],
+      edges: [{ source: 'a', target: 'b' }],
+    };
+    const { nodes, edges } = graphToFlow(graph);
+    expect(nodes).toHaveLength(2);
+    expect(edges).toHaveLength(1);
+    expect(edges[0]).toMatchObject({
+      source: 'a',
+      target: 'b',
+      sourceHandle: '0',
+      targetHandle: '0',
+    });
+    expect(edges[0].id).toBeTruthy();
+    // node data carries the original WfNode
+    expect(nodes[0].id).toBe('a');
+    expect(nodes[0].position).toBeDefined();
+  });
+
+  it('encodes multi-output (if/else) via distinct sourceHandles', () => {
+    const graph: WorkflowGraph = {
+      nodes: [
+        { id: 'cond', name: 'Check', type: 'condition.if' },
+        { id: 'pass', name: 'Pass', type: 'transform.set' },
+        { id: 'fail', name: 'Fail', type: 'transform.set' },
+      ],
+      edges: [
+        { source: 'cond', target: 'pass', sourceOutput: 0 },
+        { source: 'cond', target: 'fail', sourceOutput: 1 },
+      ],
+    };
+    const { edges } = graphToFlow(graph);
+    const passEdge = edges.find((e) => e.target === 'pass');
+    const failEdge = edges.find((e) => e.target === 'fail');
+    expect(passEdge?.sourceHandle).toBe('0');
+    expect(failEdge?.sourceHandle).toBe('1');
+  });
+
+  it('preserves explicit node positions', () => {
+    const graph: WorkflowGraph = {
+      nodes: [{ id: 'a', name: 'A', type: 't', position: { x: 42, y: 99 } }],
+      edges: [],
+    };
+    const { nodes } = graphToFlow(graph);
+    expect(nodes[0].position).toEqual({ x: 42, y: 99 });
+  });
+
+  it('handles an empty graph', () => {
+    const { nodes, edges } = graphToFlow({ nodes: [], edges: [] });
+    expect(nodes).toEqual([]);
+    expect(edges).toEqual([]);
+  });
+});
+
+describe('serialization — flowToGraph produces LOCKED backend shape', () => {
+  it('single-output edge', () => {
+    const graph: WorkflowGraph = {
+      nodes: [
+        { id: 'a', name: 'A', type: 'trigger.event' },
+        { id: 'b', name: 'B', type: 'transform.set' },
+      ],
+      edges: [{ source: 'a', target: 'b' }],
+    };
+    const { nodes, edges } = graphToFlow(graph);
+    const { connections } = flowToGraph(nodes, edges);
+    const expected: BackendConnections = {
+      a: { main: [[{ node: 'b', type: 'main', index: 0 }]] },
+    };
+    expect(connections).toEqual(expected);
+  });
+
+  it('multi-output if/else — output 0 and 1', () => {
+    const graph: WorkflowGraph = {
+      nodes: [
+        { id: 'cond', name: 'Check', type: 'condition.if' },
+        { id: 'pass', name: 'Pass', type: 'transform.set' },
+        { id: 'fail', name: 'Fail', type: 'transform.set' },
+      ],
+      edges: [
+        { source: 'cond', target: 'pass', sourceOutput: 0 },
+        { source: 'cond', target: 'fail', sourceOutput: 1 },
+      ],
+    };
+    const { nodes, edges } = graphToFlow(graph);
+    const { connections } = flowToGraph(nodes, edges);
+    expect(connections).toEqual({
+      cond: {
+        main: [
+          [{ node: 'pass', type: 'main', index: 0 }],
+          [{ node: 'fail', type: 'main', index: 0 }],
+        ],
+      },
+    });
+  });
+
+  it('parallel fan-out — one source output to multiple targets', () => {
+    const graph: WorkflowGraph = {
+      nodes: [
+        { id: 's', name: 'S', type: 'trigger.event' },
+        { id: 't1', name: 'T1', type: 'transform.set' },
+        { id: 't2', name: 'T2', type: 'transform.set' },
+      ],
+      edges: [
+        { source: 's', target: 't1' },
+        { source: 's', target: 't2' },
+      ],
+    };
+    const { nodes, edges } = graphToFlow(graph);
+    const { connections } = flowToGraph(nodes, edges);
+    expect(connections).toEqual({
+      s: {
+        main: [
+          [
+            { node: 't1', type: 'main', index: 0 },
+            { node: 't2', type: 'main', index: 0 },
+          ],
+        ],
+      },
+    });
+  });
+
+  it('empty graph yields empty connections', () => {
+    const { nodes, edges } = graphToFlow({ nodes: [], edges: [] });
+    const { connections } = flowToGraph(nodes, edges);
+    expect(connections).toEqual({});
+  });
+
+  it('dangling node with no edges produces no connection entry but is kept as a node', () => {
+    const graph: WorkflowGraph = {
+      nodes: [
+        { id: 'a', name: 'A', type: 'trigger.event' },
+        { id: 'orphan', name: 'Orphan', type: 'transform.set' },
+        { id: 'b', name: 'B', type: 'transform.set' },
+      ],
+      edges: [{ source: 'a', target: 'b' }],
+    };
+    const { nodes, edges } = graphToFlow(graph);
+    const result = flowToGraph(nodes, edges);
+    expect(result.connections).toEqual({
+      a: { main: [[{ node: 'b', type: 'main', index: 0 }]] },
+    });
+    expect(result.nodes.map((n) => n.id).sort()).toEqual(['a', 'b', 'orphan']);
+  });
+
+  it('respects a non-zero targetInput index', () => {
+    const graph: WorkflowGraph = {
+      nodes: [
+        { id: 'a', name: 'A', type: 'x' },
+        { id: 'm', name: 'Merge', type: 'x' },
+      ],
+      edges: [{ source: 'a', target: 'm', sourceOutput: 0, targetInput: 1 }],
+    };
+    const { nodes, edges } = graphToFlow(graph);
+    const { connections } = flowToGraph(nodes, edges);
+    expect(connections).toEqual({
+      a: { main: [[{ node: 'm', type: 'main', index: 1 }]] },
+    });
+  });
+
+  it('back-fills empty earlier outputs when only output 1 is connected', () => {
+    // n8n main is positional: output index 1 connected, index 0 empty.
+    const graph: WorkflowGraph = {
+      nodes: [
+        { id: 'cond', name: 'C', type: 'condition.if' },
+        { id: 'fail', name: 'F', type: 'x' },
+      ],
+      edges: [{ source: 'cond', target: 'fail', sourceOutput: 1 }],
+    };
+    const { nodes, edges } = graphToFlow(graph);
+    const { connections } = flowToGraph(nodes, edges);
+    expect(connections).toEqual({
+      cond: {
+        main: [[], [{ node: 'fail', type: 'main', index: 0 }]],
+      },
+    });
+  });
+});
+
+describe('serialization — round-trip', () => {
+  const roundtrip = (graph: WorkflowGraph): BackendConnections => {
+    const { nodes, edges } = graphToFlow(graph);
+    return flowToGraph(nodes, edges).connections;
+  };
+
+  it('flowToGraph(graphToFlow(g)) connections equal direct conversion', () => {
+    const graph: WorkflowGraph = {
+      nodes: [
+        { id: 'trigger', name: 'Start', type: 'trigger.event' },
+        { id: 'transform', name: 'Set', type: 'transform.set' },
+        { id: 'condition', name: 'Check', type: 'condition.if' },
+        { id: 'pass_node', name: 'Pass', type: 'transform.set' },
+        { id: 'fail_node', name: 'Fail', type: 'transform.set' },
+      ],
+      edges: [
+        { source: 'trigger', target: 'transform' },
+        { source: 'transform', target: 'condition' },
+        { source: 'condition', target: 'pass_node', sourceOutput: 0 },
+        { source: 'condition', target: 'fail_node', sourceOutput: 1 },
+      ],
+    };
+    // This is the exact shape from the backend test_models.py fixture.
+    const expected: BackendConnections = {
+      trigger: { main: [[{ node: 'transform', type: 'main', index: 0 }]] },
+      transform: { main: [[{ node: 'condition', type: 'main', index: 0 }]] },
+      condition: {
+        main: [
+          [{ node: 'pass_node', type: 'main', index: 0 }],
+          [{ node: 'fail_node', type: 'main', index: 0 }],
+        ],
+      },
+    };
+    expect(roundtrip(graph)).toEqual(expected);
+  });
+
+  it('round-trips connections -> graph -> connections losslessly', () => {
+    const connections: BackendConnections = {
+      trigger: { main: [[{ node: 'transform', type: 'main', index: 0 }]] },
+      transform: { main: [[{ node: 'condition', type: 'main', index: 0 }]] },
+      condition: {
+        main: [
+          [{ node: 'pass_node', type: 'main', index: 0 }],
+          [{ node: 'fail_node', type: 'main', index: 0 }],
+        ],
+      },
+    };
+    const nodes = [
+      { id: 'trigger', name: 'Start', type: 'trigger.event' },
+      { id: 'transform', name: 'Set', type: 'transform.set' },
+      { id: 'condition', name: 'Check', type: 'condition.if' },
+      { id: 'pass_node', name: 'Pass', type: 'transform.set' },
+      { id: 'fail_node', name: 'Fail', type: 'transform.set' },
+    ];
+    const graph: WorkflowGraph = {
+      nodes,
+      edges: [],
+    };
+    // hydrate edges from backend connections then re-serialize
+    const hydrated = { ...graph, edges: connectionsToEdgesForTest(connections) };
+    expect(roundtrip(hydrated)).toEqual(connections);
+  });
+});
+
+// Helper mirroring how a consumer would hydrate edges from backend
+// connections (kept local to the test to avoid coupling to impl detail).
+function connectionsToEdgesForTest(connections: BackendConnections) {
+  const edges = [];
+  for (const [source, outputs] of Object.entries(connections)) {
+    for (const [type, outputLists] of Object.entries(outputs)) {
+      outputLists.forEach((conns, outputIndex) => {
+        for (const conn of conns) {
+          edges.push({
+            source,
+            target: conn.node,
+            sourceOutput: outputIndex,
+            targetInput: conn.index,
+            type,
+          });
+        }
+      });
+    }
+  }
+  return edges;
+}

package/src/components/workflows/exec-status.ts

@@ -0,0 +1,90 @@
+/**
+ * Shared status presentation for the execution monitor: NodeStatus /
+ * RunStatus → StatusBadge config, plus a human duration formatter.
+ *
+ * Kept as a tiny pure module so both ExecutionTimeline and
+ * WorkflowRunViewer/ExecNodeDetails render statuses identically and the
+ * mapping stays test-covered in one place.
+ */
+import type { StatusBadgeConfig } from '../badge/StatusBadge';
+import type { NodeStatus, RunStatus } from './types';
+
+/** NodeStatus → badge label + tailwind color classes. */
+export const NODE_STATUS_BADGE: Record<NodeStatus, StatusBadgeConfig> = {
+  idle: {
+    label: 'Idle',
+    className: 'bg-gray-100 text-gray-600 border border-gray-200',
+  },
+  pending: {
+    label: 'Pending',
+    className: 'bg-amber-100 text-amber-800 border border-amber-200',
+  },
+  running: {
+    label: 'Running',
+    className: 'bg-blue-100 text-blue-800 border border-blue-200',
+  },
+  success: {
+    label: 'Success',
+    className: 'bg-green-100 text-green-800 border border-green-200',
+  },
+  error: {
+    label: 'Error',
+    className: 'bg-red-100 text-red-800 border border-red-200',
+  },
+  skipped: {
+    label: 'Skipped',
+    className: 'bg-gray-100 text-gray-500 border border-gray-200',
+  },
+};
+
+/** RunStatus → badge label + tailwind color classes. */
+export const RUN_STATUS_BADGE: Record<RunStatus, StatusBadgeConfig> = {
+  pending: {
+    label: 'Pending',
+    className: 'bg-amber-100 text-amber-800 border border-amber-200',
+  },
+  running: {
+    label: 'Running',
+    className: 'bg-blue-100 text-blue-800 border border-blue-200',
+  },
+  completed: {
+    label: 'Completed',
+    className: 'bg-green-100 text-green-800 border border-green-200',
+  },
+  failed: {
+    label: 'Failed',
+    className: 'bg-red-100 text-red-800 border border-red-200',
+  },
+  cancelled: {
+    label: 'Cancelled',
+    className: 'bg-gray-100 text-gray-600 border border-gray-200',
+  },
+  waiting: {
+    label: 'Waiting',
+    className: 'bg-purple-100 text-purple-800 border border-purple-200',
+  },
+};
+
+/** Statuses that are still in flight (warrant a live indicator). */
+const NON_TERMINAL: ReadonlySet<NodeStatus> = new Set(['running']);
+
+export function isLiveStatus(status: NodeStatus): boolean {
+  return NON_TERMINAL.has(status);
+}
+
+/**
+ * Format a millisecond duration as a compact human string:
+ * `42ms`, `1.23s`, `1m 5s`. Returns `null` for nullish/negative input.
+ */
+export function formatDuration(ms?: number | null): string | null {
+  if (ms == null || ms < 0 || Number.isNaN(ms)) return null;
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  const totalSeconds = ms / 1000;
+  if (totalSeconds < 60) {
+    // up to 2 decimal places, trimming trailing zeros
+    return `${parseFloat(totalSeconds.toFixed(2))}s`;
+  }
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = Math.round(totalSeconds % 60);
+  return seconds > 0 ? `${minutes}m ${seconds}s` : `${minutes}m`;
+}

package/src/components/workflows/hooks/useCanvasGraph.ts

@@ -0,0 +1,70 @@
+'use client';
+
+import * as React from 'react';
+import { graphToFlow, type FlowNode, type FlowEdge } from '../serialization';
+import { autoLayout, type LayoutDirection } from '../layout/auto-layout';
+import type { WorkflowGraph, NodeTypeDef } from '../types';
+import type { WorkflowNodeData } from '../WorkflowNode';
+
+export interface UseCanvasGraphOptions {
+  /** Node-type catalog used to enrich nodes with category + port metadata. */
+  nodeTypes?: NodeTypeDef[];
+  /** Layout direction for nodes without an explicit position. Default 'LR'. */
+  direction?: LayoutDirection;
+  /** Inline-rename callback wired onto every node's data. */
+  onRename?: (nodeId: string, name: string) => void;
+}
+
+/** Index a node-type catalog by slug for O(1) lookup. */
+function indexNodeTypes(
+  nodeTypes: NodeTypeDef[] | undefined
+): Record<string, NodeTypeDef> {
+  const index: Record<string, NodeTypeDef> = {};
+  for (const nt of nodeTypes ?? []) index[nt.slug] = nt;
+  return index;
+}
+
+/**
+ * Derive laid-out xyflow nodes/edges from a {@link WorkflowGraph}, enriching
+ * each node with its category, output ports/labels (from the node-type
+ * catalog), and the rename callback. Auto-layout fills positions for nodes
+ * that don't carry an explicit one (explicit positions are preserved).
+ */
+export function useCanvasGraph(
+  graph: WorkflowGraph,
+  options: UseCanvasGraphOptions = {}
+): { nodes: FlowNode[]; edges: FlowEdge[] } {
+  const { nodeTypes, direction = 'LR', onRename } = options;
+
+  return React.useMemo(() => {
+    const typeIndex = indexNodeTypes(nodeTypes);
+    const { nodes, edges } = graphToFlow(graph);
+
+    const enriched: FlowNode[] = nodes.map((n) => {
+      const wf = n.data.node;
+      const def = typeIndex[wf.type];
+      const category = def?.category ?? wf.type.split('.')[0];
+      const outputCount = def?.outputCount ?? 1;
+      const data: WorkflowNodeData = {
+        node: wf,
+        category,
+        outputCount,
+        outputLabels: def?.outputLabels,
+        onRename,
+        status: 'idle',
+      };
+      return { ...n, type: 'workflowNode', data };
+    });
+
+    const typedEdges: FlowEdge[] = edges.map((e) => ({
+      ...e,
+      type: 'workflowEdge',
+    }));
+
+    const laid = autoLayout(enriched, typedEdges, {
+      direction,
+      preservePositions: true,
+    });
+    return { nodes: laid.nodes, edges: typedEdges };
+  }, [graph, nodeTypes, direction, onRename]);
+}