reactflow-expert

ReactFlow エキスパート

カスタムエージェントノード、ELKjs による自動レイアウト、Zustand による状態管理、実行状態のリアルタイム更新を使用して、DAG の可視化を構築します。

---

使用する場面

✅ 次の用途に使用：

• ワークフロー／DAG 可視化ダッシュボードの構築
• エージェントの状態を表示するカスタム ReactFlow ノードコンポーネントの作成
• グラフを自動配置する ELKjs 自動レイアウトの統合
• WebSocket の実行イベントを ReactFlow の状態に接続
• ズーム、パン、選択、ノード操作の実装

❌ 次の用途には使用しない：

• 静的な Mermaid 図（mermaid-graph-writer を使用）
• 一般的な React コンポーネントの開発
• グラフ以外の可視化（チャート、テーブル）

---

アーキテクチャ

flowchart TD
  subgraph "State Layer"
    Z[Zustand Store] --> N[nodes + edges]
    Z --> U[updateNodeData]
    Z --> A[applyNodeChanges / applyEdgeChanges]
  end
  
  subgraph "Layout Layer"
    E[ELKjs] --> P[Compute positions]
    P --> Z
  end
  
  subgraph "Data Layer"
    WS[WebSocket] --> Z
    API[REST API] --> Z
  end
  
  subgraph "Render Layer"
    Z --> RF[ReactFlow component]
    RF --> CN[Custom AgentNode]
    RF --> CE[Custom edges]
    RF --> PA[Panel controls]
  end

---

コアパターン（ReactFlow v12）

Zustand ストア（複雑なエディターでは useNodesState より推奨）

import { create } from 'zustand';
import { applyNodeChanges, applyEdgeChanges, type Node, type Edge } from '@xyflow/react';

interface DAGStore {
  nodes: Node[];
  edges: Edge[];
  onNodesChange: (changes: any) => void;
  onEdgesChange: (changes: any) => void;
  setNodes: (nodes: Node[]) => void;
  setEdges: (edges: Edge[]) => void;
  updateNodeData: (nodeId: string, data: Record<string, any>) => void;
}

const useDAGStore = create<DAGStore>((set, get) => ({
  nodes: [],
  edges: [],
  onNodesChange: (changes) => set({ nodes: applyNodeChanges(changes, get().nodes) }),
  onEdgesChange: (changes) => set({ edges: applyEdgeChanges(changes, get().edges) }),
  setNodes: (nodes) => set({ nodes }),
  setEdges: (edges) => set({ edges }),
  // CRITICAL: create NEW object to trigger ReactFlow re-render
  updateNodeData: (nodeId, data) => set({
    nodes: get().nodes.map((n) =>
      n.id === nodeId ? { ...n, data: { ...n.data, ...data } } : n
    ),
  }),
}));

カスタムエージェントノード

import { Handle, Position, type NodeProps } from '@xyflow/react';

const STATUS_COLORS = {
  pending: '#9CA3AF', scheduled: '#60A5FA', running: '#3B82F6',
  completed: '#10B981', failed: '#EF4444', retrying: '#F59E0B',
  paused: '#8B5CF6', skipped: '#D1D5DB', mutated: '#EAB308',
};

function AgentNode({ data }: NodeProps) {
  return (
    <div className={`agent-node status-${data.status}`}
         style={{ borderColor: STATUS_COLORS[data.status] }}>
      <Handle type="target" position={Position.Top} />
      <div className="node-header">
        <span className={`status-dot ${data.status}`} />
        <span>{data.role}</span>
      </div>
      {data.skills && (
        <div className="node-skills">
          {data.skills.map((s: string) => <span key={s} className="badge">{s}</span>)}
        </div>
      )}
      {data.status === 'completed' && data.output?.summary && (
        <div className="node-output">{data.output.summary.slice(0, 60)}...</div>
      )}
      {data.metrics?.cost_usd > 0 && (
        <div className="node-meta">${data.metrics.cost_usd.toFixed(3)}</div>
      )}
      <Handle type="source" position={Position.Bottom} />
    </div>
  );
}

// MUST define outside component (or useMemo) to avoid re-registration
const nodeTypes = { agentNode: AgentNode };

ELKjs 自動レイアウトフック

import ELK from 'elkjs/lib/elk.bundled.js';
import { useCallback } from 'react';
import { useReactFlow } from '@xyflow/react';

const elk = new ELK();

export function useAutoLayout() {
  const { fitView } = useReactFlow();

  return useCallback(async (nodes: Node[], edges: Edge[], direction = 'DOWN') => {
    const isHorizontal = direction === 'RIGHT';
    const layouted = await elk.layout({
      id: 'root',
      layoutOptions: {
        'elk.algorithm': 'layered',
        'elk.direction': direction,
        'elk.spacing.nodeNode': '80',
        'elk.layered.spacing.nodeNodeBetweenLayers': '100',
        'elk.edgeRouting': 'ORTHOGONAL',
      },
      children: nodes.map((n) => ({
        ...n,
        targetPosition: isHorizontal ? 'left' : 'top',
        sourcePosition: isHorizontal ? 'right' : 'bottom',
        width: n.measured?.width ?? 220,
        height: n.measured?.height ?? 120,
      })),
      edges,
    });
    const result = layouted.children!.map((elkN) => ({
      ...nodes.find((n) => n.id === elkN.id)!,
      position: { x: elkN.x!, y: elkN.y! },
    }));
    window.requestAnimationFrame(() => fitView());
    return result;
  }, [fitView]);
}

ダッシュボードの組み立て

import { ReactFlow, ReactFlowProvider, Panel } from '@xyflow/react';
import '@xyflow/react/dist/style.css';

function DAGDashboard({ dagId }: { dagId: string }) {
  const { nodes, edges, onNodesChange, onEdgesChange } = useDAGStore();
  const layout = useAutoLayout();

  // WebSocket → Zustand (see websocket-streaming skill)
  useDAGStream(dagId);

  return (
    <ReactFlow nodes={nodes} edges={edges} nodeTypes={nodeTypes}
      onNodesChange={onNodesChange} onEdgesChange={onEdgesChange} fitView>
      <Panel position="top-right">
        <button onClick={() => layout(nodes, edges, 'DOWN')}>↓ Vertical</button>
        <button onClick={() => layout(nodes, edges, 'RIGHT')}>→ Horizontal</button>
      </Panel>
    </ReactFlow>
  );
}

export default function DAGPage({ dagId }: { dagId: string }) {
  return <ReactFlowProvider><DAGDashboard dagId={dagId} /></ReactFlowProvider>;
}

---

v12 の注意点

落とし穴	解決方法
nodeTypes をコンポーネント内で定義 → 無限に再レンダリングされる	コンポーネントの外で定義するか、useMemo でラップする
状態を更新しても再レンダリングされない	新しいノードオブジェクトを作成する必要があります：{ ...node, data: { ...node.data, ...update } }
カスタムノード内の xPos／yPos → 未定義	positionAbsoluteX／positionAbsoluteY を使用する（v12 で名称変更）
nodeInternals → 未定義	nodeLookup を使用する（v12 で名称変更）
ELK レイアウトでノードサイズが無視される	node.measured?.width と height を明示的に渡す
DOM の描画前に fitView が実行される	requestAnimationFrame(() => fitView()) でラップする
インタラクティブ要素を操作するとノードがドラッグされる	入力欄、ボタン、セレクトに className="nodrag" を追加する

---

アンチパターン

デバッグにキャンバス描画を使用

誤り：開発ツールでノードを検査できない、キャンバスベースのライブラリ（GoJS）を使用すること。 正しい方法：ReactFlow は SVG と HTML を描画します。すべてのノードを React DevTools と DOM で検査できます。

状態を更新するたびにレイアウトを再実行

誤り：ノードのステータスが変わるたびに ELK レイアウトを呼び出すこと（コストが高く、表示が揺れる原因になります）。 正しい方法：トポロジーが変化したとき（ノード／エッジの追加・削除）にのみレイアウトを再実行します。ステータスの色変更は単なるデータ更新であり、レイアウトは不要です。

モノリシックなノードコンポーネント

誤り：すべてのノードタイプを処理する、巨大なノードコンポーネントを1つ作ること。 正しい方法：agentNode、humanGateNode、pluripotentNode など、ノードタイプごとに個別に登録します。それぞれを目的に特化した React コンポーネントにします。