9Visual Canvas Editor

Every other capability page in this section describes a backend mechanism. This one is about the surface researchers actually touch: the in-browser canvas where graphs are authored, run, and observed. The editor is a single React app that talks to the backend over HTTP for state-changing actions and a single multiplexed WebSocket for live execution traffic. The same canvas is used to drill into composite subgraphs, configure nodes via auto-rendered forms, and replay finished episodes — no mode switching.

Design docs: Canvas System · Graph System · Execution Logs

1. Problem

An agent-graph authoring tool needs four things that don't combine easily:

• Edit topology — drag/drop nodes, draw typed wires, validate connections before submit.
• Configure nodes — every node ships its own settings (model name, temperature, image grid size); these can't be hand-coded panels per node type.
• Run and watch — show port-by-port output while the executor is running, not just a final summary.
• Drill in / out — open a composite, edit its inner graph, save back, without losing the outer canvas context.

If any of these is split across a separate page, the round-trip cost dominates. The unified editor folds all four into one ReactFlow canvas backed by a single WebSocket stream.

2. Three-Layer Architecture

+-------------------+   HTTP /api/*       +--------------------------+
|  Browser (React)  | ------------------> |  FastAPI backend         |
|  - ReactFlow      |                     |  - WorkspaceComponentRegistry     |
|  - Zustand store  | <-- WS /ws -------- |  - GraphExecutor      |
|  - WSManager      |   nav_step,         |  - ErrorBus              |
+-------------------+   viewer_data,      +--------------------------+
                        nav_status,
                        error_event

• React Flow (@xyflow/react) renders nodes and edges; it owns geometry (positions, viewport, drag state).
• Zustand store (useFlowStore) owns graph semantics (typed wires, port resolution, composite drill-stack, per-node live output). Tab-aware: each open tab is an independent slice with its own nodes/edges/nodeOutputs; top-level selectors are projections of the active tab so older components keep working.
• WSManager (ws.ts) is one singleton WebSocket with auto-reconnect (exponential backoff 1s → 30s), a typed handler map, and a wildcard channel. Every panel that needs live data subscribes by frame type — no per-feature socket.

State-changing actions (load nodeset, run graph, cancel run) are HTTP because they need a synchronous result. Live execution is WS because it's a high-volume one-way fan-out.

3. Graph Editor

UnifiedGraphEditor is the same component at the root canvas and inside a composite's inner graph:

Both modes share the drag-drop pipeline, typed-wire compatibility check (isCompatibleWireConnection), and the same proxiedNodeTypes registry, so a composite editor looks and behaves identically to the root — only the persistence model differs.

3.1 Typed Wire Compatibility

Connections go through useFlowStore.onConnect → isCompatibleWireConnection. The check pulls each port's wire_type from portResolution (which walks _schema + live config.ports overrides for instance-derived ports such as iterIn, stateContainer, imageViewer) and rejects mismatches before the edge enters the store. This means the canvas can never reach the backend in a state that would only be caught by validate_graph_connectivity.

3.2 Node Library and Catalog

The left-side NodeLibrary reads from unifiedCatalog, which merges three sources:

• Built-in nodes from the bundled buildBuiltinEntries table (iterIn/Out, graphIn/Out, viewers, state containers, composite, graphNode) — their default_config mirrors backend BaseCanvasNode.default_config so a freshly dropped node validates immediately.
• Loaded nodeset tools fetched from GET /api/components/loaded after any load/unload — each tool's node_type, input_ports, output_ports, and configSchema drive both the palette entry and the dropped node's initial state.
• Composite graphs registered as nodeset graph_nodes — they appear as a single drop-tile and expand into a subgraph editor when opened.

4. Configuration Panel

Selecting a node opens PropertiesPanel, which renders fields straight from the node's ui_config.config_fields (or, for non-customised nodes, infers them from configSchema). One renderer (ConfigFieldRenderer) covers the common widgets:

• text / textarea / select / slider / checkbox — primitive fields
• port_list — used by iterIn/iterOut/stateContainer/imageViewer to add/remove typed ports; edits feed back into portResolution so the node's handle row updates live
• llmRef — picker bound to the loaded profile list (GET /api/profiles)

There is no per-node React form. Adding a new node type means adding its ui_config and configSchema on the Python side; the UI is automatic.

5. Live Execution View

While the executor runs, the editor consumes four WS frame types from state.broadcast:

Each node's shell (NodeShell + HandleDot) renders a per-handle status dot driven by nodeOutputs[node_id]; receiving a value flips the handle to "filled", emitting flips the output handle to "fresh". Composite nodes overlay their inner-graph progress as a small badge so you can see iteration depth without opening them.

6. Composite Drill-Down

Double-clicking a composite node opens its inner graph in a modal UnifiedGraphEditor mode="subgraph". The subgraph editor is seeded from the composite's NodeDef.subgraph, edits live in local React state, and on Save writes back via onSave — the parent canvas stays mounted underneath, so positions, selection, and run state are preserved. The drill stack is recorded on the store's canvasStack so multi-level dives keep their crumb trail.

Live execution is rendered through the drill: when the executor enters a composite's expanded child scope, the inner editor's nodes light up with the same per-handle status dots as the root.

7. Panels

The canvas is wrapped by a tab-aware shell with one resizable bottom drawer and a stack of right-side tabs. Every panel is a thin Zustand consumer:

8. Run Flow

Pressing Run in the toolbar fires runPipeline(graph):

1. Convert the live ReactFlow nodes/edges back to a GraphDefinition via fromFlowNodes + fromFlowEdges.
2. Client-side pre-flight: for eval_graph: true (default), require ≥1 graphOut node. Surfaces a clearer error than waiting for the backend's validate_graph_connectivity.
3. Build the LoopDefinition wire payload (nodes, edges, containers, access_grants, step_budget, terminationCondition, presetId, hooks).
4. POST to /api/navigate/run (ADR-platform-002 — single endpoint) with an optional execution_id and step_delay_ms.
5. The backend acknowledges with { execution_id } and starts emitting nav_status / nav_step / viewer_data / error_event frames over the already-open WS — no new connection.

Cancel goes through POST /api/navigate/run/stop; the toolbar disables itself based on nav_status.status.

9. Related Pages and Tools

The visual editor is one of several React surfaces backed by the same store and WS:

• NodeSet Manager (pages/NodeSetManager.tsx) — load/unload nodesets, pick local vs server mode, view manifest. Updates to loaded nodesets reflow the editor's catalog.
• Eval page (eval/EvalPage.tsx) — submit / monitor / cancel batch runs (see capability 8); reuses the same WSManager for per-episode nav_step.
• Replay page (replay/ReplayPage.tsx) — scrub through stored per-episode logs (ADR-eval-004); renders the same node shells with frozen data.
• Log viewer (logs/LogViewerPage.tsx) — historic execution logs with the canvas re-rendered from the saved graph; per-node inner_logs are filtered, paginated, and clickable.

10. Key Files

Status