The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
Rust agent-orchestrationai-agentsai-assistantdesktopllmlocal-firstmcppersonal-aiprivacyrustsecond-braintauri
/**
* EditableFlowCanvas — the mutable Workflow Canvas (issue B5b.2 / Phase 3a).
* Wraps `@xyflow/react`'s `<ReactFlow>` in *controlled* mode: node/edge state
* is lifted into `useNodesState`/`useEdgesState` seeded once from the incoming
* graph, so drags, connections, additions, and deletions mutate local state
* rather than the read-only viewer's static props.
*
* What it wires on top of the read-only `FlowCanvas`:
* - **drag / move** — `nodesDraggable` on; `onNodesChange` persists positions.
* - **connect** — `onConnect` is port-aware: it accepts a new edge only when
* {@link isValidFlowConnection} approves it (reusing the canvas's derived
* input/output ports), and rejects self-loops, unknown handles, and dupes.
* - **delete** — Backspace/Delete removes the selection (React Flow default),
* plus an explicit "Delete selected" toolbar button as a discoverable
* affordance; deleting a node also drops its incident edges.
* - **add** — a {@link NodePalette} inserts any of the 15 node kinds by click
* (default cascade position) or drag-drop (under the cursor).
* - **save** — a "Save" button serializes the live canvas back to a
* `WorkflowGraph` via {@link xyflowToWorkflowGraph} and hands it to `onSave`.
* The dirty-guard / persistence call lives one layer up (Phase 3d).
*/
import {
addEdge,
Background,
BackgroundVariant,
type Connection,
ReactFlow,
type ReactFlowInstance,
useEdgesState,
useNodesState,
type Viewport,
} from '@xyflow/react';
import '@xyflow/react/dist/style.css';
import createDebug from 'debug';
import {
type ForwardedRef,
forwardRef,
memo,
useCallback,
useEffect,
useImperativeHandle,
useMemo,
useRef,
useState,
} from 'react';
import { FLOW_RUN_NODE_STATUS_CLASS, useFlowRunProgress } from '../../../hooks/useFlowRunProgress';
import { erroredNodeIds } from '../../../lib/flows/flowValidation';
import {
connectionEdgeId,
createFlowNode,
FLOW_NODE_TYPE,
type FlowEdge,
type FlowNode,
isValidFlowConnection,
stepNumbersForFlow,
type WorkflowGraphMeta,
xyflowToWorkflowGraph,
} from '../../../lib/flows/graphAdapter';
import { PALETTE_ENTRIES, type PaletteEntry } from '../../../lib/flows/nodeKindMeta';
import type { NodeKind, WorkflowGraph } from '../../../lib/flows/types';
import { useT } from '../../../lib/i18n/I18nContext';
import { type FlowConnection, listFlowConnections } from '../../../services/api/flowsApi';
import { type CanvasActions, CanvasActionsContext } from './canvasActions';
import CanvasToolbar from './CanvasToolbar';
import { FLOW_FIT_VIEW_OPTIONS } from './fitView';
import './flowCanvasStyles.css';
import FlowNodeComponent from './FlowNodeComponent';
import FlowValidationBanner from './FlowValidationBanner';
import NodeConfigDrawer, { type NodeConfigPatch } from './nodeConfig/NodeConfigDrawer';
import NodePalette, { PALETTE_DND_MIME } from './NodePalette';
import { StepNumberContext } from './stepNumbers';
import { useFlowValidation } from './useFlowValidation';
const log = createDebug('app:flows:canvas:edit');
const NODE_TYPES = { [FLOW_NODE_TYPE]: FlowNodeComponent };
const DELETE_KEYS = ['Backspace', 'Delete'];
/** Where a click-added palette node lands (canvas coords) before cascade. */
const CLICK_ADD_ORIGIN = { x: 80, y: 80 };
/** Per-click cascade so repeated palette clicks don't stack on one spot. */
const CLICK_ADD_STEP = 32;
interface EditableFlowCanvasProps {
nodes: FlowNode[];
edges: FlowEdge[];
/** Graph-level metadata xyflow doesn't carry, needed to re-serialize on save. */
meta: WorkflowGraphMeta;
/**
* Called with the current canvas serialized to a `WorkflowGraph` when the
* user clicks Save. The caller owns the `flows_update` RPC (Phase 3d); this
* component runs validation and gates Save on hard errors before invoking it.
* May return a promise — Save awaits it, and only advances the dirty baseline
* (clearing unsaved state) once it resolves. A rejection surfaces inline.
*/
onSave?: (graph: WorkflowGraph) => void | Promise<void>;
/** Fired when a drawn connection is rejected as invalid (for a toast in 3c). */
onInvalidConnection?: (connection: Connection) => void;
/**
* Reports the draft's dirty state (unsaved edits vs the last saved baseline)
* so the host page can gate navigation-away (Phase 3d).
*/
onDirtyChange?: (dirty: boolean) => void;
/**
* Id of the currently-executing run (== thread_id) to overlay live per-node
* status on the canvas (Phase 3e). `null`/absent means no run is in flight,
* so no overlay is drawn. The live feed is best-effort — the durable
* `flow_runs` row + {@link useFlowRunPoller} remain the source of truth.
*/
activeRunId?: string | null;
/**
* Reports the canvas's live graph on every edit (Phase 5c) so the host can
* feed the current draft to the copilot as context and diff a proposal
* against it. Fires with the same serialization Save uses.
*/
onGraphChange?: (graph: WorkflowGraph) => void;
/**
* Node ids the copilot's pending proposal ADDS — ringed sage as a diff
* highlight (Phase 5c). Empty/absent when not previewing a proposal.
*/
addedNodeIds?: ReadonlySet<string>;
/**
* Node ids the copilot's pending proposal REMOVES — ghosted (Phase 5c). These
* nodes are still rendered (carried over by the host) so the removal is
* visible before Accept/Reject.
*/
removedNodeIds?: ReadonlySet<string>;
/**
* Force-disable Save (Phase 5c) — set while a copilot proposal is under
* review so the ghosted preview graph can't be persisted; Accept/Reject in
* the copilot panel is the gate instead.
*/
saveDisabled?: boolean;
/**
* Seed the dirty flag as already-unsaved at mount (Phase 5c fix). This
* component's dirty baseline is seeded from `nodes`/`edges` at mount, so
* whenever the host remounts the canvas with a new key (e.g. accepting a
* copilot proposal, `FlowCanvasPage`'s `canvasVersion` bump) the freshly
* mounted graph would otherwise instantly read as "clean" even though it
* was never actually persisted via `onSave` — losing the accepted changes
* on back/reload instead of gating them behind Save. The host computes
* this by comparing the incoming graph against its own last-persisted
* snapshot and passes the result through, independent of any canvas
* remount.
*/
initialDirty?: boolean;
/** Show the drag-and-drop node palette ("Legend"). Defaults to `true`. */
showPalette?: boolean;
/**
* When set, the canvas toolbar shows a "reopen side panel" button — the host
* passes it only while its side panel (copilot / palette) is collapsed.
*/
onOpenPanel?: () => void;
/**
* Reports Save-button state up so the host can render Save/Discard in its own
* header (the canvas keeps only undo/redo). Fires whenever any field changes.
*/
onSaveMetaChange?: (meta: EditorSaveMeta) => void;
/**
* The viewport (pan/zoom) to restore on mount, captured from a previous
* mount of this same logical canvas via `onViewportChange` (F4/F5 fix). The
* host (`FlowCanvasPage`) keeps this in a ref that survives the `canvasVersion`
* remounts Save/Accept/Reject trigger, so a remount can restore the user's
* pan/zoom instead of `fitView` silently resetting it. `null`/absent means no
* prior viewport is known (first-ever mount) — `fitView` runs normally.
*/
savedViewport?: Viewport | null;
/**
* Fired on every viewport change (pan/zoom) so the host can capture the
* latest value for `savedViewport` on the next remount (F4/F5 fix).
*/
onViewportChange?: (viewport: Viewport) => void;
}
/** Save/Discard state the host header needs to render + gate its own buttons. */
export interface EditorSaveMeta {
dirty: boolean;
hasErrors: boolean;
saving: boolean;
}
/** Imperative handle so the host header's Save/Discard buttons drive the canvas. */
export interface EditableFlowCanvasHandle {
save: () => void;
discard: () => void;
/**
* Clear the forced-dirty flag and advance the baseline to the CURRENT live
* graph, without going through `save()` / `onSave` (the host has already
* persisted the graph itself — see `handleAcceptProposal` in
* `FlowCanvasPage.tsx`). Needed for the Accept path: it calls the page's
* `handleSave` directly (bypassing this canvas's own `save()`, whose ref is
* stale mid-remount) and only remounts a SECOND time when the server
* actually normalized the graph. When it doesn't (the common "echoed back
* unchanged" case), this already-mounted instance's `forcedDirty` — seeded
* `true` by Accept's own remount, before the persist resolved — would
* otherwise never clear, since only this canvas's own `save()`/`discard()`
* do that. Call this after such an out-of-band persist succeeds to sync it.
*/
clearForcedDirty: () => void;
/** Add a node from the palette, for a palette the host renders outside the canvas. */
addPaletteEntry: (entry: PaletteEntry) => void;
}
const EMPTY_ID_SET: ReadonlySet<string> = new Set();
function EditableFlowCanvas(
{
nodes: initialNodes,
edges: initialEdges,
meta,
onSave,
onInvalidConnection,
onDirtyChange,
activeRunId = null,
onGraphChange,
addedNodeIds = EMPTY_ID_SET,
removedNodeIds = EMPTY_ID_SET,
saveDisabled = false,
initialDirty = false,
showPalette = true,
onOpenPanel,
onSaveMetaChange,
savedViewport = null,
onViewportChange,
}: EditableFlowCanvasProps,
ref: ForwardedRef<EditableFlowCanvasHandle>
) {
const { t } = useT();
const [nodes, setNodes, onNodesChange] = useNodesState<FlowNode>(initialNodes);
const [edges, setEdges, onEdgesChange] = useEdgesState<FlowEdge>(initialEdges);
const rfRef = useRef<ReactFlowInstance<FlowNode, FlowEdge> | null>(null);
// F4/F5 fix diagnostic: log once per mount whether this instance restores a
// caller-supplied viewport (`savedViewport`, threaded through from
// `FlowCanvasPage`'s `viewportRef`) or falls back to React Flow's own
// `fitView` (first-ever mount, or a host that doesn't track viewport).
useEffect(() => {
log(
'mount: viewport %s x=%s y=%s zoom=%s',
savedViewport ? 'restored' : 'fitView-fallback',
savedViewport?.x,
savedViewport?.y,
savedViewport?.zoom
);
// Mount-only — a later `savedViewport` prop change (from panning) must
// not re-log; only a fresh mount (new instance) should.
// eslint-disable-next-line react-hooks/exhaustive-deps
}, []);
// ── Undo / redo history ───────────────────────────────────────────────────
// A bounded past/future stack of {nodes, edges} snapshots so structural edits
// (add / connect / delete / move) and config edits are recoverable without
// nuking ALL edits via Discard. Every mutating action snapshots the PRE-change
// state via `pushHistory` before it mutates; undo/redo swap the current state
// with the neighbouring snapshot. Consecutive config edits to the same node
// coalesce into one history entry (see `lastConfigNodeRef`) so typing in the
// config drawer doesn't produce a per-keystroke undo trail.
type FlowSnapshot = { nodes: FlowNode[]; edges: FlowEdge[] };
const HISTORY_LIMIT = 50;
const [history, setHistory] = useState<{ past: FlowSnapshot[]; future: FlowSnapshot[] }>({
past: [],
future: [],
});
const nodesRef = useRef(nodes);
const edgesRef = useRef(edges);
nodesRef.current = nodes;
edgesRef.current = edges;
// Node id whose config edits are currently being coalesced into one entry, or
// `null` when the last snapshot was any other kind of change.
const lastConfigNodeRef = useRef<string | null>(null);
// True while a drag is in flight so we snapshot the pre-drag positions exactly
// once per drag, not on every intermediate position change.
const draggingRef = useRef(false);
const pushHistory = useCallback((kind: 'config' | 'structural', nodeId?: string) => {
// Coalesce a run of config edits to the same node into a single undo step.
if (kind === 'config' && lastConfigNodeRef.current === nodeId) return;
lastConfigNodeRef.current = kind === 'config' ? (nodeId ?? null) : null;
setHistory(h => ({
past: [...h.past, { nodes: nodesRef.current, edges: edgesRef.current }].slice(-HISTORY_LIMIT),
future: [],
}));
}, []);
const undo = useCallback(() => {
lastConfigNodeRef.current = null;
setHistory(h => {
if (h.past.length === 0) return h;
const previous = h.past[h.past.length - 1];
const current = { nodes: nodesRef.current, edges: edgesRef.current };
setNodes(previous.nodes);
setEdges(previous.edges);
log(
'undo: restored snapshot nodes=%d edges=%d',
previous.nodes.length,
previous.edges.length
);
return { past: h.past.slice(0, -1), future: [...h.future, current].slice(-HISTORY_LIMIT) };
});
}, [setNodes, setEdges]);
const redo = useCallback(() => {
lastConfigNodeRef.current = null;
setHistory(h => {
if (h.future.length === 0) return h;
const next = h.future[h.future.length - 1];
const current = { nodes: nodesRef.current, edges: edgesRef.current };
setNodes(next.nodes);
setEdges(next.edges);
log('redo: restored snapshot nodes=%d edges=%d', next.nodes.length, next.edges.length);
return { past: [...h.past, current].slice(-HISTORY_LIMIT), future: h.future.slice(0, -1) };
});
}, [setNodes, setEdges]);
const canUndo = history.past.length > 0;
const canRedo = history.future.length > 0;
// First-run hint visibility: a near-empty canvas (≤1 node, no edges, and no
// copilot diff preview in flight) is almost certainly a fresh scratch flow.
const showOnboarding =
nodes.length <= 1 && edges.length === 0 && addedNodeIds.size === 0 && removedNodeIds.size === 0;
const addCounter = useRef(0);
// Id of the single selected node whose config the drawer edits (`null` when
// zero or multiple nodes — or any edge — are selected).
const [configNodeId, setConfigNodeId] = useState<string | null>(null);
const [connections, setConnections] = useState<FlowConnection[]>([]);
// ── Draft / dirty state (Phase 3d) ────────────────────────────────────────
// The last *saved* snapshot: the graph is "dirty" whenever the live canvas
// serializes to something different. Seeded from the incoming graph and
// advanced on every successful Save so post-save the canvas reads clean.
const [baseline, setBaseline] = useState<{ nodes: FlowNode[]; edges: FlowEdge[] }>(() => ({
nodes: initialNodes,
edges: initialEdges,
}));
const [saving, setSaving] = useState(false);
const [saveError, setSaveError] = useState<string | null>(null);
// Host-computed "already unsaved at mount" override (Phase 5c fix, see
// `initialDirty`'s doc comment) — cleared once a real Save/Discard
// resolves this instance's baseline, same as the self-computed `dirty`.
const [forcedDirty, setForcedDirty] = useState(initialDirty);
const currentGraph = useMemo(
() => xyflowToWorkflowGraph(nodes, edges, meta),
[nodes, edges, meta]
);
const currentKey = useMemo(() => JSON.stringify(currentGraph), [currentGraph]);
// Report the live graph up (Phase 5c) so the copilot always has the current
// draft to build on. Keyed on `currentKey` so it fires once per real change,
// not on every render.
useEffect(() => {
onGraphChange?.(currentGraph);
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [currentKey]);
const baselineKey = useMemo(
() => JSON.stringify(xyflowToWorkflowGraph(baseline.nodes, baseline.edges, meta)),
[baseline, meta]
);
const dirty = forcedDirty || currentKey !== baselineKey;
// Notify the host page so it can gate navigation-away while dirty.
useEffect(() => {
onDirtyChange?.(dirty);
}, [dirty, onDirtyChange]);
// ── Validation (Phase 3c) ─────────────────────────────────────────────────
const { validation, validating, validateNow } = useFlowValidation(currentGraph, currentKey);
// Only a *present, failed* validation blocks Save — a null result (not yet
// run, or the RPC failed) fails open, since the server re-validates on update.
const hasErrors = validation ? !validation.valid : false;
// Ids named by a hard error, so the canvas can ring the offending node(s).
const erroredIds = useMemo(
() =>
erroredNodeIds(
validation && !validation.valid ? validation.errors : [],
nodes.map(n => n.id)
),
[validation, nodes]
);
// ── Live run overlay (Phase 3e) ───────────────────────────────────────────
// Subscribe to the core's per-step progress feed for the active run and map
// each node id to a live-status ring class. This CLOSES Phase 1's deferred
// "frontend consumes FlowRunProgress" follow-up. The 2s poller in
// `useFlowRunPoller` stays as the durable fallback; this just makes it live.
const runProgress = useFlowRunProgress(activeRunId);
// Derive the render array (never stored in draft, so it can't dirty the graph):
// tag errored nodes with the `flow-node-error` class the canvas CSS rings, and
// overlay each node's live run status (`flow-node-running`/`-success`/`-failed`).
const hasRunOverlay = Object.keys(runProgress).length > 0;
const hasDiffOverlay = addedNodeIds.size > 0 || removedNodeIds.size > 0;
const displayNodes = useMemo(() => {
if (erroredIds.size === 0 && !hasRunOverlay && !hasDiffOverlay) return nodes;
return nodes.map(n => {
const extra: string[] = [];
if (erroredIds.has(n.id)) extra.push('flow-node-error');
const runClass = FLOW_RUN_NODE_STATUS_CLASS[runProgress[n.id]];
if (runClass) extra.push(runClass);
// Copilot diff overlay (Phase 5c): sage ring on added, ghost on removed.
if (addedNodeIds.has(n.id)) extra.push('flow-node-added');
if (removedNodeIds.has(n.id)) extra.push('flow-node-removed');
if (extra.length === 0) return n;
return { ...n, className: `${n.className ?? ''} ${extra.join(' ')}`.trim() };
});
// `runProgress` is a stable-enough dependency (new object only on a real
// status change, see the hook's setState guard).
}, [nodes, erroredIds, runProgress, hasRunOverlay, hasDiffOverlay, addedNodeIds, removedNodeIds]);
// Load the secret-free credential refs once for the node-config credential
// picker (http_request / tool_call). Guarded: outside Tauri (or if the RPC
// fails) the picker just shows its empty state rather than throwing.
useEffect(() => {
let cancelled = false;
void (async () => {
try {
const list = await listFlowConnections();
if (cancelled) return;
log('connections loaded: count=%d', list.length);
setConnections(list);
} catch (err) {
if (cancelled) return;
log('connections load failed (non-fatal): %o', err);
}
})();
return () => {
cancelled = true;
};
}, []);
const nextNodeId = useCallback((kind: NodeKind): string => {
// Prefix keeps palette-added ids from ever colliding with loaded graph ids
// (which are arbitrary backend strings); the counter keeps them unique
// within a session even for same-kind, same-millisecond clicks.
return `new-${kind}-${addCounter.current++}`;
}, []);
// Snapshot on structural node/edge removals (covers xyflow's own
// Backspace/Delete path, which bypasses `handleDeleteSelected`) and once at
// the start of a drag (pre-drag positions), so both are undoable.
const handleNodesChange = useCallback(
(changes: Parameters<typeof onNodesChange>[0]) => {
if (changes.some(c => c.type === 'remove')) {
pushHistory('structural');
} else {
const dragging = changes.some(c => c.type === 'position' && c.dragging === true);
const dragEnded = changes.some(c => c.type === 'position' && c.dragging === false);
if (dragging && !draggingRef.current) {
draggingRef.current = true;
pushHistory('structural');
}
if (dragEnded) draggingRef.current = false;
}
onNodesChange(changes);
},
[onNodesChange, pushHistory]
);
const handleEdgesChange = useCallback(
(changes: Parameters<typeof onEdgesChange>[0]) => {
if (changes.some(c => c.type === 'remove')) pushHistory('structural');
onEdgesChange(changes);
},
[onEdgesChange, pushHistory]
);
const onConnect = useCallback(
(connection: Connection) => {
if (!isValidFlowConnection(connection, nodes, edges)) {
log('onConnect: rejected %o', connection);
onInvalidConnection?.(connection);
return;
}
log('onConnect: accepted %o', connection);
pushHistory('structural');
// Use the adapter's collision-free id (matches what a reload would
// assign via workflowGraphToXyflow → edgeId), not React Flow's default
// concatenated id — see connectionEdgeId's doc.
setEdges(current => addEdge({ ...connection, id: connectionEdgeId(connection) }, current));
},
[nodes, edges, setEdges, onInvalidConnection, pushHistory]
);
// Live drag feedback: React Flow calls this while dragging a new connection
// and paints the target handle valid/invalid before the drop commits.
const isValidConnection = useCallback(
(connection: Connection | FlowEdge) =>
isValidFlowConnection(connection as Connection, nodes, edges),
[nodes, edges]
);
const addNode = useCallback(
(entry: PaletteEntry, position: { x: number; y: number }) => {
const id = nextNodeId(entry.kind);
const name = t(entry.labelKey, entry.kind);
const node = createFlowNode(entry.kind, position, id, name);
// Merge the palette entry's preset config (e.g. tool_call provider) so the
// two tool nodes (App action / Tool) start in the right mode.
const withPreset = entry.preset
? { ...node, data: { ...node.data, config: { ...node.data.config, ...entry.preset } } }
: node;
log('addNode: key=%s kind=%s id=%s at %o', entry.key, entry.kind, id, position);
pushHistory('structural');
setNodes(current => [...current, withPreset]);
},
[nextNodeId, setNodes, t, pushHistory]
);
const handlePaletteAdd = useCallback(
(entry: PaletteEntry) => {
const step = addCounter.current * CLICK_ADD_STEP;
addNode(entry, { x: CLICK_ADD_ORIGIN.x + step, y: CLICK_ADD_ORIGIN.y + step });
},
[addNode]
);
const handleDrop = useCallback(
(event: React.DragEvent) => {
event.preventDefault();
const key = event.dataTransfer.getData(PALETTE_DND_MIME);
const entry = PALETTE_ENTRIES.find(e => e.key === key);
if (!entry) return;
const instance = rfRef.current;
const position = instance
? instance.screenToFlowPosition({ x: event.clientX, y: event.clientY })
: { ...CLICK_ADD_ORIGIN };
addNode(entry, position);
},
[addNode]
);
const handleDragOver = useCallback((event: React.DragEvent) => {
event.preventDefault();
event.dataTransfer.dropEffect = 'copy';
}, []);
// Delete a single node (the selected node card's Delete action) plus its
// incident edges. Keyboard Backspace/Delete still removes the multi-selection
// through React Flow's native `deleteKeyCode` (snapshotted for undo in
// `handleNodesChange`), so this is the only explicit delete affordance left.
const deleteNode = useCallback(
(nodeId: string) => {
log('deleteNode: id=%s', nodeId);
pushHistory('structural');
setNodes(current => current.filter(n => n.id !== nodeId));
setEdges(current => current.filter(e => e.source !== nodeId && e.target !== nodeId));
},
[setNodes, setEdges, pushHistory]
);
// Detach a single edge (from the config drawer's connections list).
const removeEdge = useCallback(
(edgeId: string) => {
log('removeEdge: id=%s', edgeId);
pushHistory('structural');
setEdges(current => current.filter(e => e.id !== edgeId));
},
[setEdges, pushHistory]
);
// Node id → display name, for labelling the other end of each connection.
const nodeLabelById = useMemo(
() => Object.fromEntries(nodes.map(n => [n.id, n.data.name])),
[nodes]
);
const handleSave = useCallback(async () => {
// Hard errors block Save (warnings are allowed through). Belt-and-braces:
// the button is also disabled in this state.
if (hasErrors) {
log('save: blocked — graph has validation errors');
return;
}
const graph = xyflowToWorkflowGraph(nodes, edges, meta);
log('save: nodes=%d edges=%d', graph.nodes.length, graph.edges.length);
setSaving(true);
setSaveError(null);
try {
await onSave?.(graph);
// Advance the dirty baseline to the just-saved snapshot so the canvas
// reads clean (and the nav guard stands down) until the next edit.
setBaseline({ nodes, edges });
setForcedDirty(false);
log('save: succeeded — baseline advanced');
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
log('save: failed err=%o', err);
setSaveError(message);
} finally {
setSaving(false);
}
}, [hasErrors, nodes, edges, meta, onSave]);
// Discard all unsaved edits, resetting the canvas to the last saved baseline.
const handleDiscard = useCallback(() => {
log(
'discard: resetting to baseline nodes=%d edges=%d',
baseline.nodes.length,
baseline.edges.length
);
// Snapshot pre-discard so Discard itself is undoable.
pushHistory('structural');
setNodes(baseline.nodes);
setEdges(baseline.edges);
setConfigNodeId(null);
setSaveError(null);
setForcedDirty(false);
}, [baseline, setNodes, setEdges, pushHistory]);
// Expose Save/Discard so the host header can drive them (the canvas now shows
// only undo/redo). Guarded internally by the same dirty/error/saving gates.
useImperativeHandle(
ref,
() => ({
save: () => {
if (!dirty || hasErrors || saving || saveDisabled) return;
void handleSave();
},
discard: () => {
if (!dirty || saving) return;
handleDiscard();
},
clearForcedDirty: () => {
log('clearForcedDirty: host persisted externally — syncing baseline');
setBaseline({ nodes, edges });
setForcedDirty(false);
},
addPaletteEntry: entry => handlePaletteAdd(entry),
}),
[
dirty,
hasErrors,
saving,
saveDisabled,
handleSave,
handleDiscard,
nodes,
edges,
handlePaletteAdd,
]
);
// Mirror the Save-button state up so the header can render + gate its buttons.
useEffect(() => {
onSaveMetaChange?.({ dirty, hasErrors, saving });
}, [dirty, hasErrors, saving, onSaveMetaChange]);
// Canvas actions surfaced on the selected node card (delete this node /
// validate the graph) — see `canvasActions.ts`. Memoised so the context
// value is stable across renders that don't change validation state.
const canvasActions = useMemo<CanvasActions>(
() => ({ deleteNode, validate: () => void validateNow(), validating }),
[deleteNode, validateNow, validating]
);
// Open the config drawer on an explicit node CLICK only. React Flow doesn't
// fire `onNodeClick` for a drag (dragging emits drag events instead), so
// grabbing a node to move it no longer pops the drawer open — the fix for
// "dragging the card opens the sidebar".
const onNodeClick = useCallback((_event: React.MouseEvent, node: FlowNode) => {
log('nodeClick: id=%s — opening config', node.id);
setConfigNodeId(node.id);
}, []);
const onSelectionChange = useCallback(
({ nodes: selNodes, edges: selEdges }: { nodes: FlowNode[]; edges: FlowEdge[] }) => {
// Selection only CLOSES the drawer now (opening is `onNodeClick`'s job):
// clicking empty canvas, selecting an edge, or multi-selecting drops the
// single-node config context. A lone node stays as-is (opened by a click,
// left closed after a drag).
const isSingleNode = selEdges.length === 0 && selNodes.length === 1;
if (!isSingleNode) {
log(
'selectionChange: nodes=%d edges=%d — closing config',
selNodes.length,
selEdges.length
);
setConfigNodeId(null);
}
},
[]
);
// Apply a name/config edit from the drawer to the live node state (controlled).
const updateNode = useCallback(
(nodeId: string, patch: NodeConfigPatch) => {
log(
'updateNode: id=%s name=%s config=%s',
nodeId,
patch.name ?? '(unchanged)',
patch.config ? 'present' : '(unchanged)'
);
// Coalesce consecutive edits to the same node into one undo step.
pushHistory('config', nodeId);
setNodes(current =>
current.map(n =>
n.id === nodeId
? {
...n,
data: {
...n.data,
...(patch.name !== undefined ? { name: patch.name } : {}),
...(patch.config !== undefined ? { config: patch.config } : {}),
},
}
: n
)
);
},
[setNodes, pushHistory]
);
// Keyboard undo/redo: Cmd/Ctrl+Z undoes, Cmd/Ctrl+Shift+Z (or Ctrl+Y) redoes.
// Ignored while typing in the config drawer / any field so text-edit undo in a
// focused input isn't hijacked.
const handleCanvasKeyDown = useCallback(
(event: React.KeyboardEvent) => {
const target = event.target as HTMLElement | null;
const tag = target?.tagName;
if (tag === 'INPUT' || tag === 'TEXTAREA' || target?.isContentEditable) return;
const mod = event.metaKey || event.ctrlKey;
if (!mod) return;
const key = event.key.toLowerCase();
if (key === 'z' && !event.shiftKey) {
event.preventDefault();
undo();
} else if ((key === 'z' && event.shiftKey) || key === 'y') {
event.preventDefault();
redo();
}
},
[undo, redo]
);
// Close the drawer AND clear the selection, so re-clicking the same node
// re-fires `onSelectionChange` and reopens it.
const handleCloseConfig = useCallback(() => {
log('closeConfig: deselecting all nodes');
setConfigNodeId(null);
setNodes(current =>
current.some(n => n.selected) ? current.map(n => ({ ...n, selected: false })) : current
);
}, [setNodes]);
// Execution-order numbers, derived from the LIVE nodes/edges rather than
// baked into node `data` at adapt time. `workflowGraphToXyflow` runs once at
// mount; every edit after that goes through `setNodes`/`setEdges`, so an
// adapt-time number would be missing on any node added mid-edit and stale on
// the rest as soon as a connection changed.
const stepNumberMap = useMemo(() => stepNumbersForFlow(nodes, edges), [nodes, edges]);
const configNode = configNodeId ? (nodes.find(n => n.id === configNodeId) ?? null) : null;
return (
<CanvasActionsContext.Provider value={canvasActions}>
<StepNumberContext.Provider value={stepNumberMap}>
<div
className="flow-canvas relative h-full w-full"
data-testid="flow-canvas"
data-editable="true"
data-viewport-restored={savedViewport ? 'true' : 'false'}
onDrop={handleDrop}
onDragOver={handleDragOver}
onKeyDown={handleCanvasKeyDown}>
{showPalette && <NodePalette onAdd={handlePaletteAdd} />}
{/* First-run hint: a near-empty canvas (a fresh scratch flow opens with
just its trigger) gets a non-blocking nudge toward the palette. Hides
itself as soon as a second node lands. */}
{showOnboarding && (
<div
className="pointer-events-none absolute inset-0 z-0 flex items-center justify-center px-6"
data-testid="flow-editor-onboarding">
<div className="max-w-xs rounded-2xl border border-dashed border-line bg-surface/70 px-5 py-4 text-center backdrop-blur-sm">
<p className="text-sm font-semibold text-content">
{t('flows.editor.onboardingTitle')}
</p>
<p className="mt-1 text-xs leading-relaxed text-content-muted">
{t('flows.editor.onboardingBody')}
</p>
</div>
</div>
)}
<div className="pointer-events-none absolute inset-x-3 bottom-3 z-10 flex justify-center">
<div className="pointer-events-auto w-full max-w-md">
<FlowValidationBanner validation={validation} saveError={saveError} />
</div>
</div>
<ReactFlow
nodes={displayNodes}
edges={edges}
nodeTypes={NODE_TYPES}
onInit={instance => {
rfRef.current = instance;
}}
onNodesChange={handleNodesChange}
onEdgesChange={handleEdgesChange}
onConnect={onConnect}
isValidConnection={isValidConnection}
onNodeClick={onNodeClick}
onSelectionChange={onSelectionChange}
deleteKeyCode={DELETE_KEYS}
nodesDraggable
nodesConnectable
elementsSelectable
fitView={!savedViewport}
fitViewOptions={FLOW_FIT_VIEW_OPTIONS}
defaultViewport={savedViewport ?? undefined}
onViewportChange={onViewportChange}
panOnScroll
zoomOnScroll>
<Background variant={BackgroundVariant.Dots} gap={20} size={1.25} />
<CanvasToolbar
history={{ canUndo, canRedo, onUndo: undo, onRedo: redo }}
onOpenPanel={onOpenPanel}
/>
</ReactFlow>
<NodeConfigDrawer
node={configNode}
onClose={handleCloseConfig}
onChange={updateNode}
connections={connections}
nodes={nodes}
edges={edges}
nodeLabelById={nodeLabelById}
onRemoveEdge={removeEdge}
/>
</div>
</StepNumberContext.Provider>
</CanvasActionsContext.Provider>
);
}
export default memo(forwardRef(EditableFlowCanvas));