diff --git a/apps/web/package.json b/apps/web/package.json
index 522a20e..0323fed 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -17,6 +17,7 @@
     "@codemirror/lang-markdown": "6.3.3",
     "@codemirror/state": "6.5.2",
     "@codemirror/view": "6.38.6",
+    "@xyflow/react": "^12.11.0",
     "codemirror": "6.0.2",
     "fast-diff": "^1.3.0",
     "lucide-react": "^1.8.0",
diff --git a/apps/web/src/app/globals.css b/apps/web/src/app/globals.css
index 485e991..be3ed3c 100644
--- a/apps/web/src/app/globals.css
+++ b/apps/web/src/app/globals.css
@@ -1,3 +1,5 @@
+@import '@xyflow/react/dist/style.css';
+
 :root {
   color-scheme: dark;
   --background: #08101f;
@@ -576,6 +578,223 @@ code {
   color: #8b949e;
 }
 
+.diagram-canvas-svg--reactflow svg g.node,
+.diagram-canvas-svg--reactflow svg .edgePaths,
+.diagram-canvas-svg--reactflow svg .edgeLabels,
+.diagram-canvas-svg--reactflow svg g.edgePath,
+.diagram-canvas-svg--reactflow svg g.edgeLabel,
+.diagram-canvas-svg--reactflow svg path.flowchart-link {
+  opacity: 0;
+}
+
+.diagram-reactflow-layer {
+  inset: 0;
+  position: absolute;
+  z-index: 5;
+}
+
+.diagram-reactflow-layer .react-flow {
+  height: 100%;
+  width: 100%;
+}
+
+.diagram-reactflow-layer .react-flow,
+.diagram-reactflow-layer .react-flow__renderer,
+.diagram-reactflow-layer .react-flow__pane {
+  background: transparent;
+}
+
+.diagram-reactflow-layer .react-flow__node {
+  background: transparent;
+  border: none;
+  box-shadow: none;
+  padding: 0;
+}
+
+.diagram-reactflow-layer .react-flow__edge-path {
+  stroke: #e2e8f0;
+  stroke-width: 1.8;
+}
+
+.diagram-reactflow-layer .react-flow__edge.selected .react-flow__edge-path,
+.diagram-reactflow-layer .react-flow__edge:focus .react-flow__edge-path {
+  filter: drop-shadow(0 0 5px rgba(56, 189, 248, 0.7));
+  stroke: #38bdf8;
+}
+
+.diagram-reactflow-layer .react-flow__edge:hover .react-flow__edge-path {
+  stroke: #7dd3fc;
+}
+
+.diagram-reactflow-layer .react-flow__edge-interaction {
+  cursor: pointer;
+}
+
+.diagram-reactflow-layer .react-flow__edge-textbg {
+  fill: #0d1117;
+}
+
+.diagram-reactflow-layer .react-flow__edge-text {
+  fill: #e2e8f0;
+  font-family: var(--font-mono);
+  font-size: 11px;
+}
+
+.diagram-reactflow-layer .react-flow__handle {
+  background: #38bdf8;
+  border: 1px solid #0d1117;
+  height: 8px;
+  width: 8px;
+}
+
+.diagram-reactflow-layer .mermaid-flow-handle--target {
+  opacity: 0;
+  pointer-events: auto;
+}
+
+.diagram-reactflow-layer .mermaid-flow-handle--source {
+  opacity: 0.95;
+  z-index: 2;
+}
+
+.diagram-reactflow-layer .react-flow__node:hover .mermaid-flow-handle--target,
+.diagram-reactflow-layer .react-flow__node.selected .mermaid-flow-handle--target,
+.diagram-reactflow-layer .react-flow__node:hover .mermaid-flow-handle--source,
+.diagram-reactflow-layer .react-flow__node.selected .mermaid-flow-handle--source {
+  opacity: 1;
+}
+
+.diagram-reactflow-layer .mermaid-flow-handle--left,
+.diagram-reactflow-layer .mermaid-flow-handle--right {
+  cursor: ew-resize;
+}
+
+.diagram-reactflow-layer .mermaid-flow-handle--top,
+.diagram-reactflow-layer .mermaid-flow-handle--bottom {
+  cursor: ns-resize;
+}
+
+.mermaid-flow-node {
+  align-items: center;
+  background: #161b22;
+  border: 1px solid #30363d;
+  box-shadow: 0 10px 28px rgba(2, 6, 23, 0.35);
+  color: #e2e8f0;
+  display: flex;
+  font-size: 13px;
+  font-weight: 600;
+  height: 100%;
+  justify-content: center;
+  line-height: 1.25;
+  min-height: 28px;
+  min-width: 48px;
+  padding: 8px 12px;
+  position: relative;
+  text-align: center;
+  width: 100%;
+}
+
+.mermaid-flow-node.is-selected {
+  border-color: #38bdf8;
+  box-shadow: 0 0 0 4px rgba(56, 189, 248, 0.25), 0 10px 28px rgba(2, 6, 23, 0.35);
+}
+
+.mermaid-flow-node.is-focused {
+  outline: 2px solid rgba(56, 189, 248, 0.85);
+  outline-offset: 3px;
+}
+
+.mermaid-flow-node > span {
+  position: relative;
+  z-index: 1;
+}
+
+.mermaid-flow-node--round,
+.mermaid-flow-node--stadium {
+  border-radius: 999px;
+}
+
+.mermaid-flow-node--circle,
+.mermaid-flow-node--doublecircle,
+.mermaid-flow-node--ellipse {
+  border-radius: 50%;
+}
+
+.mermaid-flow-node--diamond {
+  clip-path: polygon(50% 0, 100% 50%, 50% 100%, 0 50%);
+  padding: 14px;
+}
+
+.mermaid-flow-node--hexagon {
+  clip-path: polygon(18% 0, 82% 0, 100% 50%, 82% 100%, 18% 100%, 0 50%);
+}
+
+.mermaid-flow-node--trapezoid {
+  clip-path: polygon(12% 0, 88% 0, 100% 100%, 0 100%);
+}
+
+.mermaid-flow-node--inv_trapezoid {
+  clip-path: polygon(0 0, 100% 0, 88% 100%, 12% 100%);
+}
+
+.mermaid-flow-node--lean_right {
+  clip-path: polygon(12% 0, 100% 0, 88% 100%, 0 100%);
+}
+
+.mermaid-flow-node--lean_left {
+  clip-path: polygon(0 0, 88% 0, 100% 100%, 12% 100%);
+}
+
+.mermaid-flow-node--odd {
+  clip-path: polygon(0 0, 88% 0, 100% 50%, 88% 100%, 0 100%);
+}
+
+.mermaid-flow-node--cylinder {
+  border-bottom-color: transparent;
+  border-radius: 50% / 14%;
+  padding-top: 12px;
+}
+
+.mermaid-flow-node--cylinder::before,
+.mermaid-flow-node--cylinder::after {
+  border: 1px solid #30363d;
+  border-radius: 50%;
+  content: '';
+  height: 22%;
+  left: -1px;
+  pointer-events: none;
+  position: absolute;
+  right: -1px;
+}
+
+.mermaid-flow-node--cylinder::before {
+  background: rgba(13, 17, 23, 0.18);
+  top: -1px;
+}
+
+.mermaid-flow-node--cylinder::after {
+  border-top-color: transparent;
+  bottom: -1px;
+}
+
+.mermaid-flow-node--subroutine::before,
+.mermaid-flow-node--subroutine::after {
+  background: #30363d;
+  content: '';
+  height: 100%;
+  position: absolute;
+  top: 0;
+  width: 1px;
+}
+
+.mermaid-flow-node--subroutine::before {
+  left: 10px;
+}
+
+.mermaid-flow-node--subroutine::after {
+  right: 10px;
+}
+
 .activity-list {
   list-style: none;
   margin: 0;
diff --git a/apps/web/src/components/diagram-canvas.tsx b/apps/web/src/components/diagram-canvas.tsx
index 12b7c44..2de74e8 100644
--- a/apps/web/src/components/diagram-canvas.tsx
+++ b/apps/web/src/components/diagram-canvas.tsx
@@ -1,18 +1,41 @@
 'use client';
 
-import type { CSSProperties, PointerEvent as ReactPointerEvent } from 'react';
+import type { CSSProperties, KeyboardEvent as ReactKeyboardEvent, PointerEvent as ReactPointerEvent, ReactNode } from 'react';
+import {
+  ConnectionLineType,
+  Handle,
+  MarkerType,
+  Position,
+  ReactFlow,
+  type Connection,
+  type Edge,
+  type FinalConnectionState,
+  type Node,
+  type NodeChange,
+  type NodeProps,
+  type NodeTypes,
+  type OnConnectEnd,
+  type OnConnectStart,
+  type OnNodeDrag,
+  type Viewport,
+} from '@xyflow/react';
 import {
   ArrowRightFromLine,
   Pencil,
   Plus,
+  RotateCcw,
   ScanSearch,
   Shapes,
   Trash2,
   ZoomIn,
   ZoomOut,
 } from 'lucide-react';
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import type { DiagramLinkType, DiagramNode, DiagramNodeShape, DiagramSubgraph, FlowchartSnapshot } from '../lib/diagram-mutations';
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import type { DiagramEdgeIdentity, DiagramLink, DiagramLinkType, DiagramNode, DiagramNodeShape, DiagramSubgraph, FlowchartSnapshot } from '../lib/diagram-mutations';
+import { getDiagramEdgeIdentity, resolveDiagramEdgeIndex } from '../lib/diagram-mutations';
+import { getDiagramEdgeIdentityForFlowEdge, getFlowEdgeId, getVisibleDiagramLinks } from '../lib/diagram-flow-identity';
+import type { DiagramNodePositions, NodePositionsSyncMode } from '../lib/diagram-layout';
+import { getConnectNodeActivation } from '../lib/diagram-connect-state';
 import {
   buildSvgHitMap,
   getBoundsCenter,
@@ -29,17 +52,21 @@ export interface DiagramCanvasProps {
   graph: FlowchartSnapshot | null;
   interactionMode?: 'select' | 'connect';
   isFlowchart?: boolean;
+  nodePositions?: DiagramNodePositions;
   readOnly?: boolean;
   selectedNodeIds?: string[];
   svg: string;
   onAddEdge?: (source: string, target: string, label?: string, type?: DiagramLinkType) => void;
   onAddNode?: (label: string, shape: DiagramNodeShape) => void;
+  onAddConnectedNode?: (source: string, label: string, shape: DiagramNodeShape, position: SvgPoint, type: DiagramLinkType) => void;
   onChangeNodeShape?: (nodeId: string, newShape: DiagramNodeShape) => void;
-  onDeleteEdge?: (edgeKey: string) => void;
+  onDeleteEdge?: (edge: DiagramEdgeIdentity) => void;
   onDeleteNodes?: (nodeIds: string[]) => void;
+  onEditEdgeLabel?: (edge: DiagramEdgeIdentity, label?: string) => void;
   onEditNodeLabel?: (nodeId: string, newLabel: string) => void;
   onGroupNodes?: (nodeIds: string[], label: string) => void;
   onInteractionModeChange?: (mode: 'select' | 'connect') => void;
+  onNodePositionsChange?: (positions: DiagramNodePositions, mode?: NodePositionsSyncMode) => void;
   onSelectedNodeIdsChange?: (nodeIds: string[]) => void;
   onUngroupNodes?: (subgraphId: string) => void;
 }
@@ -58,10 +85,39 @@ interface PendingEdge {
   target: string;
 }
 
+interface MermaidFlowNodeData extends Record<string, unknown> {
+  ariaLabel: string;
+  label: string;
+  shape: DiagramNodeShape;
+}
+
+type MermaidFlowNode = Node<MermaidFlowNodeData, 'mermaidFlowNode'>;
+
+interface FlowNodeInteractionContextValue {
+  focusedNodeId: string | null;
+  onFocus: (nodeId: string) => void;
+  onKeyDown: (nodeId: string, event: ReactKeyboardEvent<HTMLElement>) => void;
+  registerNodeElement: (nodeId: string, element: HTMLElement | null) => void;
+}
+
+const FLOW_NODE_TYPES: NodeTypes = {
+  mermaidFlowNode: MermaidReactFlowNode,
+};
+const FLOW_PRO_OPTIONS = { hideAttribution: true };
+const FLOW_EDGE_COLOR = '#e2e8f0';
+const FLOW_EDGE_MARKER_CIRCLE_ID = 'arielcharts-flow-edge-circle';
+const FLOW_EDGE_MARKER_CROSS_ID = 'arielcharts-flow-edge-cross';
+const FLOW_HANDLE_POSITIONS = [Position.Top, Position.Right, Position.Bottom, Position.Left] as const;
+const GHOST_NODE_WIDTH = 144;
+const GHOST_NODE_HEIGHT = 56;
+const FlowNodeInteractionContext = createContext<FlowNodeInteractionContextValue | null>(null);
+
 const MIN_ZOOM = 0.1;
 const MAX_ZOOM = 4;
 const EDITOR_MIN_ZOOM = 0.4;
 const FIT_PADDING = 64;
+const DEFAULT_NEW_NODE_LABEL = 'New Node';
+const DEFAULT_NEW_NODE_SHAPE: DiagramNodeShape = 'rect';
 const SHAPE_OPTIONS: Array<{ label: string; value: DiagramNodeShape }> = [
   { label: 'rect', value: 'rect' },
   { label: 'round', value: 'round' },
@@ -100,13 +156,18 @@ export function DiagramCanvas({
   graph,
   interactionMode,
   isFlowchart = true,
+  nodePositions,
   onAddEdge,
   onAddNode,
+  onAddConnectedNode,
   onChangeNodeShape,
+  onDeleteEdge,
   onDeleteNodes,
+  onEditEdgeLabel,
   onEditNodeLabel,
   onGroupNodes,
   onInteractionModeChange,
+  onNodePositionsChange,
   onSelectedNodeIdsChange,
   onUngroupNodes,
   readOnly = false,
@@ -115,9 +176,19 @@ export function DiagramCanvas({
 }: DiagramCanvasProps) {
   const containerRef = useRef<HTMLDivElement | null>(null);
   const svgContainerRef = useRef<HTMLDivElement | null>(null);
-  const nodeButtonRefs = useRef(new Map<string, HTMLButtonElement | null>());
+  const nodeButtonRefs = useRef(new Map<string, HTMLElement | null>());
   const [hitMap, setHitMap] = useState<SvgHitMap | null>(null);
+  const [uncontrolledNodePositions, setUncontrolledNodePositions] = useState<DiagramNodePositions>({});
+  const [liveNodePositions, setLiveNodePositions] = useState<DiagramNodePositions>({});
+  const persistedNodePositions = nodePositions ?? uncontrolledNodePositions;
+  const persistedNodePositionsRef = useRef<DiagramNodePositions>(persistedNodePositions);
+  const hasAutoFitInitialRenderRef = useRef(false);
+  const visibleNodePositions = useMemo(
+    () => ({ ...persistedNodePositions, ...liveNodePositions }),
+    [liveNodePositions, persistedNodePositions],
+  );
   const dragStateRef = useRef<{ originX: number; originY: number; startPanX: number; startPanY: number } | null>(null);
+  const connectionStartNodeIdRef = useRef<string | null>(null);
   const isControlledSelection = selectedNodeIds !== undefined;
   const [internalSelection, setInternalSelection] = useState<string[]>(selectedNodeIds ?? []);
   const selection = isControlledSelection ? selectedNodeIds : internalSelection;
@@ -129,24 +200,76 @@ export function DiagramCanvas({
   const [spacePressed, setSpacePressed] = useState(false);
   const [editingNodeId, setEditingNodeId] = useState<string | null>(null);
   const [editingLabel, setEditingLabel] = useState('');
+  const [selectedEdgeIdentity, setSelectedEdgeIdentity] = useState<DiagramEdgeIdentity | null>(null);
+  const [editingEdgeIdentity, setEditingEdgeIdentity] = useState<DiagramEdgeIdentity | null>(null);
+  const [editingEdgeLabel, setEditingEdgeLabel] = useState('');
   const [shapePickerOpen, setShapePickerOpen] = useState(false);
   const [connectSourceId, setConnectSourceId] = useState<string | null>(null);
+  const [connectionPreviewSourceId, setConnectionPreviewSourceId] = useState<string | null>(null);
   const [cursorPoint, setCursorPoint] = useState<SvgPoint | null>(null);
   const [pendingEdge, setPendingEdge] = useState<PendingEdge | null>(null);
   const [pendingEdgeLabel, setPendingEdgeLabel] = useState('');
   const [groupPromptValue, setGroupPromptValue] = useState('');
   const [showGroupPrompt, setShowGroupPrompt] = useState(false);
+  const [newNodeLabel, setNewNodeLabel] = useState('');
+  const [newNodeShape, setNewNodeShape] = useState<DiagramNodeShape>(DEFAULT_NEW_NODE_SHAPE);
   const [selectedConnectionType, setSelectedConnectionType] = useState<DiagramLinkType>('arrow_point');
   const [focusedNodeId, setFocusedNodeId] = useState<string | null>(null);
   const [toolbarOpen, setToolbarOpen] = useState(false);
 
+  const setNodePositions = useCallback((
+    update: (current: DiagramNodePositions) => DiagramNodePositions,
+    mode: NodePositionsSyncMode = 'merge',
+    syncPositions?: DiagramNodePositions | null,
+  ) => {
+    const currentPositions = persistedNodePositionsRef.current;
+    const next = update(currentPositions);
+    if (next === currentPositions) {
+      return;
+    }
+
+    persistedNodePositionsRef.current = next;
+    if (nodePositions === undefined) {
+      setUncontrolledNodePositions(next);
+    }
+    if (syncPositions !== null) {
+      onNodePositionsChange?.(syncPositions ?? (mode === 'remove' ? {} : next), mode);
+    }
+  }, [nodePositions, onNodePositionsChange]);
+
+  useEffect(() => {
+    persistedNodePositionsRef.current = persistedNodePositions;
+  }, [persistedNodePositions]);
+
+  const interactiveNodeBounds = useMemo(() => {
+    if (!hitMap) {
+      return null;
+    }
+
+    const boundsByNodeId = new Map(hitMap.nodes);
+    Object.entries(visibleNodePositions).forEach(([nodeId, position]) => {
+      const bounds = boundsByNodeId.get(nodeId);
+      if (!bounds) {
+        return;
+      }
+
+      boundsByNodeId.set(nodeId, {
+        ...bounds,
+        x: position.x,
+        y: position.y,
+      });
+    });
+
+    return boundsByNodeId;
+  }, [hitMap, visibleNodePositions]);
+
   const orderedNodeIds = useMemo(() => {
     if (graph?.nodes.length) {
-      return graph.nodes.map((node) => node.id).filter((nodeId) => hitMap?.nodes.has(nodeId) ?? false);
+      return graph.nodes.map((node) => node.id).filter((nodeId) => interactiveNodeBounds?.has(nodeId) ?? false);
     }
 
-    return hitMap ? [...hitMap.nodes.keys()] : [];
-  }, [graph?.nodes, hitMap]);
+    return interactiveNodeBounds ? [...interactiveNodeBounds.keys()] : [];
+  }, [graph?.nodes, interactiveNodeBounds]);
 
   const connectionMap = useMemo(() => {
     const incoming = new Map<string, string[]>();
@@ -160,31 +283,114 @@ export function DiagramCanvas({
     return { incoming, outgoing };
   }, [graph?.links]);
 
+  const nodeById = useMemo(() => new Map(graph?.nodes.map((node) => [node.id, node]) ?? []), [graph?.nodes]);
+  const selectedEdgeIndex = useMemo(() => (
+    graph && selectedEdgeIdentity ? resolveDiagramEdgeIndex(graph.links, selectedEdgeIdentity, { includeLabel: false }) : null
+  ), [graph, selectedEdgeIdentity]);
+  const editingEdgeIndex = useMemo(() => (
+    graph && editingEdgeIdentity ? resolveDiagramEdgeIndex(graph.links, editingEdgeIdentity, { includeLabel: false }) : null
+  ), [editingEdgeIdentity, graph]);
+  const selectedCurrentEdgeIdentity = useMemo(() => {
+    if (!graph || selectedEdgeIndex === null) {
+      return null;
+    }
+
+    const edge = graph.links[selectedEdgeIndex];
+    return edge ? getDiagramEdgeIdentity(edge, selectedEdgeIndex) : null;
+  }, [graph, selectedEdgeIndex]);
+
   const selectedBounds = useMemo(() => {
     if (!hitMap || selection.length === 0) {
       return null;
     }
 
     const boundsList = selection
-      .map((nodeId) => hitMap.nodes.get(nodeId))
+      .map((nodeId) => interactiveNodeBounds?.get(nodeId))
       .filter((bounds): bounds is SvgBounds => bounds !== undefined);
 
     return getBoundsUnion(boundsList);
-  }, [hitMap, selection]);
+  }, [hitMap, interactiveNodeBounds, selection]);
 
   const graphBounds = useMemo(() => {
     if (!hitMap) {
       return null;
     }
 
-    const allBounds = [
-      ...hitMap.nodes.values(),
-      ...hitMap.subgraphs.values(),
-      ...[...hitMap.edges.values()].map((edge) => edge.bounds),
-    ];
+    const nodeBounds = interactiveNodeBounds ? [...interactiveNodeBounds.values()] : [...hitMap.nodes.values()];
+    const allBounds = nodeBounds.length > 0
+      ? [...nodeBounds, ...hitMap.subgraphs.values()]
+      : [...hitMap.subgraphs.values(), ...[...hitMap.edges.values()].map((edge) => edge.bounds)];
 
     return getBoundsUnion(allBounds);
-  }, [hitMap]);
+  }, [hitMap, interactiveNodeBounds]);
+
+  const flowNodes = useMemo<MermaidFlowNode[]>(() => {
+    if (!graph || !interactiveNodeBounds) {
+      return [];
+    }
+
+    const nextNodes: MermaidFlowNode[] = [];
+    graph.nodes.forEach((node) => {
+      const bounds = interactiveNodeBounds.get(node.id);
+      if (!bounds) {
+        return;
+      }
+
+      const nodeLabel = getNodeText(node);
+      const ariaLabel = getNodeAriaLabel(node.shape, nodeLabel);
+      nextNodes.push({
+        ariaLabel,
+        data: {
+          ariaLabel,
+          label: nodeLabel,
+          shape: node.shape,
+        },
+        draggable: !readOnly,
+        focusable: false,
+        id: node.id,
+        position: { x: bounds.x, y: bounds.y },
+        selectable: true,
+        selected: selection.includes(node.id),
+        style: {
+          height: bounds.height,
+          width: bounds.width,
+        },
+        type: 'mermaidFlowNode',
+      });
+    });
+
+    return nextNodes;
+  }, [graph, interactiveNodeBounds, readOnly, selection]);
+
+  const hasPersistedLayout = Object.keys(persistedNodePositions).length > 0;
+
+  const flowEdges = useMemo<Edge[]>(() => {
+    if (!graph || !interactiveNodeBounds) {
+      return [];
+    }
+
+    return getVisibleDiagramLinks(graph.links, interactiveNodeBounds)
+      .map(({ graphIndex, link }) => ({
+        animated: false,
+        data: { index: graphIndex },
+        id: getFlowEdgeId(graphIndex),
+        label: getLinkText(link),
+        selectable: true,
+        selected: selectedEdgeIndex === graphIndex,
+        ...getFlowEdgeHandles(link, interactiveNodeBounds, graph.direction),
+        ...getFlowEdgePresentation(link),
+        source: link.source,
+        target: link.target,
+        type: 'smoothstep',
+      }));
+  }, [graph, interactiveNodeBounds, selectedEdgeIndex]);
+
+  const useReactFlowRenderer = isFlowchart && flowNodes.length > 0;
+  const flowViewport = useMemo<Viewport>(() => ({
+    x: viewport.panX,
+    y: viewport.panY,
+    zoom: viewport.zoom,
+  }), [viewport.panX, viewport.panY, viewport.zoom]);
 
   const screenSelectionBounds = useMemo(() => {
     if (!selectedBounds) {
@@ -199,25 +405,39 @@ export function DiagramCanvas({
       return null;
     }
 
-    return graph.nodes.find((node) => node.id === editingNodeId) ?? null;
-  }, [editingNodeId, graph]);
+    return nodeById.get(editingNodeId) ?? null;
+  }, [editingNodeId, graph, nodeById]);
 
   const editingNodeBounds = useMemo(() => {
     if (!hitMap || !editingNodeId) {
       return null;
     }
 
-    const bounds = hitMap.nodes.get(editingNodeId);
+    const bounds = interactiveNodeBounds?.get(editingNodeId);
     return bounds ? toScreenRect(bounds, viewport) : null;
-  }, [editingNodeId, hitMap, viewport]);
+  }, [editingNodeId, hitMap, interactiveNodeBounds, viewport]);
+
+  const selectedEdge = selectedEdgeIndex === null ? null : graph?.links[selectedEdgeIndex] ?? null;
+  const selectedEdgeMidpoint = useMemo(() => (
+    selectedEdge && interactiveNodeBounds ? getEdgeMidpoint(selectedEdge, interactiveNodeBounds) : null
+  ), [interactiveNodeBounds, selectedEdge]);
+
+  const editingEdgeMidpoint = useMemo(() => {
+    if (editingEdgeIndex === null || !graph || !interactiveNodeBounds) {
+      return null;
+    }
+
+    const edge = graph.links[editingEdgeIndex];
+    return edge ? getEdgeMidpoint(edge, interactiveNodeBounds) : null;
+  }, [editingEdgeIndex, graph, interactiveNodeBounds]);
 
   const connectSourceBounds = useMemo(() => {
-    if (!connectSourceId || !hitMap) {
+    if (!connectSourceId || !interactiveNodeBounds) {
       return null;
     }
 
-    return hitMap.nodes.get(connectSourceId) ?? null;
-  }, [connectSourceId, hitMap]);
+    return interactiveNodeBounds.get(connectSourceId) ?? null;
+  }, [connectSourceId, interactiveNodeBounds]);
 
   const connectSourcePort = useMemo(() => {
     if (!connectSourceBounds) {
@@ -238,6 +458,19 @@ export function DiagramCanvas({
     };
   }, [connectSourcePort, cursorPoint, viewport]);
 
+  const connectionGhostRect = useMemo(() => {
+    if (!connectionPreviewSourceId || !cursorPoint || readOnly) {
+      return null;
+    }
+
+    return toScreenRect({
+      height: GHOST_NODE_HEIGHT,
+      width: GHOST_NODE_WIDTH,
+      x: cursorPoint.x - (GHOST_NODE_WIDTH / 2),
+      y: cursorPoint.y - (GHOST_NODE_HEIGHT / 2),
+    }, viewport);
+  }, [connectionPreviewSourceId, cursorPoint, readOnly, viewport]);
+
   const displayedToolbarRect = screenSelectionBounds ?? { height: 0, width: 0, x: 16, y: 16 };
   const toolbarStyle: CSSProperties = {
     alignItems: 'center',
@@ -269,26 +502,34 @@ export function DiagramCanvas({
     }
   }, [interactionMode, onInteractionModeChange]);
 
-  const fitToDiagram = useCallback((animated: boolean) => {
+  const fitBoundsToViewport = useCallback((bounds: SvgBounds, animated: boolean) => {
     const container = containerRef.current;
-    if (!container || !graphBounds) {
+    if (!container) {
       return;
     }
 
     const availableWidth = Math.max(1, container.clientWidth - (FIT_PADDING * 2));
     const availableHeight = Math.max(1, container.clientHeight - (FIT_PADDING * 2));
     const zoom = clamp(
-      Math.min(availableWidth / Math.max(graphBounds.width, 1), availableHeight / Math.max(graphBounds.height, 1)),
+      Math.min(availableWidth / Math.max(bounds.width, 1), availableHeight / Math.max(bounds.height, 1)),
       MIN_ZOOM,
       MAX_ZOOM,
     );
 
-    const panX = ((container.clientWidth - (graphBounds.width * zoom)) / 2) - (graphBounds.x * zoom);
-    const panY = ((container.clientHeight - (graphBounds.height * zoom)) / 2) - (graphBounds.y * zoom);
+    const panX = ((container.clientWidth - (bounds.width * zoom)) / 2) - (bounds.x * zoom);
+    const panY = ((container.clientHeight - (bounds.height * zoom)) / 2) - (bounds.y * zoom);
 
     setAnimateTransform(animated);
     setViewport({ panX, panY, zoom });
-  }, [graphBounds]);
+  }, []);
+
+  const fitToDiagram = useCallback((animated: boolean) => {
+    if (!graphBounds) {
+      return;
+    }
+
+    fitBoundsToViewport(graphBounds, animated);
+  }, [fitBoundsToViewport, graphBounds]);
 
   const focusNode = useCallback((nodeId: string | null) => {
     if (!nodeId) {
@@ -302,11 +543,11 @@ export function DiagramCanvas({
   }, []);
 
   const moveFocus = useCallback((currentNodeId: string, direction: 'up' | 'down' | 'left' | 'right') => {
-    if (!hitMap) {
+    if (!interactiveNodeBounds) {
       return;
     }
 
-    const currentBounds = hitMap.nodes.get(currentNodeId);
+    const currentBounds = interactiveNodeBounds.get(currentNodeId);
     if (!currentBounds) {
       return;
     }
@@ -319,11 +560,11 @@ export function DiagramCanvas({
       ...directionalCandidates,
       ...(connectionMap.incoming.get(currentNodeId) ?? []),
       ...(connectionMap.outgoing.get(currentNodeId) ?? []),
-    ])).filter((candidateId) => candidateId !== currentNodeId && hitMap.nodes.has(candidateId));
+    ])).filter((candidateId) => candidateId !== currentNodeId && interactiveNodeBounds.has(candidateId));
 
     const ranked = connectedCandidates
       .map((candidateId) => {
-        const bounds = hitMap.nodes.get(candidateId);
+        const bounds = interactiveNodeBounds.get(candidateId);
         if (!bounds) {
           return null;
         }
@@ -359,7 +600,7 @@ export function DiagramCanvas({
       });
 
     focusNode(ranked[0]?.candidateId ?? null);
-  }, [connectionMap.incoming, connectionMap.outgoing, focusNode, hitMap]);
+  }, [connectionMap.incoming, connectionMap.outgoing, focusNode, interactiveNodeBounds]);
 
   useEffect(() => {
     if (!selectedNodeIds) {
@@ -397,6 +638,32 @@ export function DiagramCanvas({
     };
   }, [svg]);
 
+  useEffect(() => {
+    if (!graph) {
+      setNodePositions((current) => (Object.keys(current).length > 0 ? {} : current), 'merge', null);
+      setLiveNodePositions({});
+      return;
+    }
+
+    const currentNodeIds = new Set(graph.nodes.map((node) => node.id));
+    const removedPositions: DiagramNodePositions = {};
+    setNodePositions((current) => {
+      const next: DiagramNodePositions = {};
+      for (const [nodeId, position] of Object.entries(current)) {
+        if (currentNodeIds.has(nodeId)) {
+          next[nodeId] = position;
+        } else {
+          removedPositions[nodeId] = position;
+        }
+      }
+
+      return Object.keys(next).length === Object.keys(current).length ? current : next;
+    }, 'remove', removedPositions);
+    setLiveNodePositions((current) => Object.fromEntries(
+      Object.entries(current).filter(([nodeId]) => currentNodeIds.has(nodeId)),
+    ));
+  }, [graph, setNodePositions]);
+
   useEffect(() => {
     if (selection.length === 0) {
       setToolbarOpen(false);
@@ -408,6 +675,22 @@ export function DiagramCanvas({
     }
   }, [focusedNodeId, selection]);
 
+  useEffect(() => {
+    if (selectedEdgeIdentity && selectedEdgeIndex === null) {
+      setSelectedEdgeIdentity(null);
+    }
+    if (editingEdgeIdentity && editingEdgeIndex === null) {
+      setEditingEdgeIdentity(null);
+      setEditingEdgeLabel('');
+    }
+  }, [editingEdgeIdentity, editingEdgeIndex, selectedEdgeIdentity, selectedEdgeIndex]);
+
+  useEffect(() => {
+    if (orderedNodeIds.length === 0 && graph) {
+      hasAutoFitInitialRenderRef.current = false;
+    }
+  }, [graph, orderedNodeIds.length]);
+
   useEffect(() => {
     if (!orderedNodeIds.length) {
       setFocusedNodeId(null);
@@ -420,12 +703,13 @@ export function DiagramCanvas({
   }, [focusedNodeId, orderedNodeIds]);
 
   useEffect(() => {
-    if (!graphBounds || !svg) {
+    if (!graphBounds || !svg || hasAutoFitInitialRenderRef.current) {
       return;
     }
 
-    fitToDiagram(false);
-  }, [fitToDiagram, graphBounds, svg]);
+    hasAutoFitInitialRenderRef.current = true;
+    fitBoundsToViewport(graphBounds, false);
+  }, [fitBoundsToViewport, graphBounds, svg]);
 
   useEffect(() => {
     if (!animateTransform) {
@@ -457,8 +741,13 @@ export function DiagramCanvas({
         setPendingEdgeLabel('');
         setShowGroupPrompt(false);
         setConnectSourceId(null);
+        connectionStartNodeIdRef.current = null;
+        setConnectionPreviewSourceId(null);
         setCursorPoint(null);
         setToolbarOpen(false);
+        setSelectedEdgeIdentity(null);
+        setEditingEdgeIdentity(null);
+        setEditingEdgeLabel('');
         setMode('select');
         containerRef.current?.focus();
       }
@@ -478,9 +767,18 @@ export function DiagramCanvas({
         setShowGroupPrompt(true);
       }
 
-      if ((event.key === 'Delete' || event.key === 'Backspace') && selection.length > 0 && !readOnly) {
-        event.preventDefault();
-        onDeleteNodes?.(selection);
+      if ((event.key === 'Delete' || event.key === 'Backspace') && !readOnly) {
+        if (selection.length > 0) {
+          event.preventDefault();
+          onDeleteNodes?.(selection);
+          return;
+        }
+
+        if (selectedCurrentEdgeIdentity) {
+          event.preventDefault();
+          onDeleteEdge?.(selectedCurrentEdgeIdentity);
+          setSelectedEdgeIdentity(null);
+        }
       }
     };
 
@@ -497,7 +795,7 @@ export function DiagramCanvas({
       window.removeEventListener('keydown', handleKeyDown);
       window.removeEventListener('keyup', handleKeyUp);
     };
-  }, [editingNodeId, graph, onDeleteNodes, onUngroupNodes, readOnly, selection, setMode]);
+  }, [editingNodeId, graph, onDeleteEdge, onDeleteNodes, onUngroupNodes, readOnly, selectedCurrentEdgeIdentity, selection, setMode]);
 
   useEffect(() => {
     if (viewport.zoom >= EDITOR_MIN_ZOOM) {
@@ -583,6 +881,8 @@ export function DiagramCanvas({
     }
 
     setSelection([]);
+    setSelectedEdgeIdentity(null);
+    setEditingEdgeIdentity(null);
     setToolbarOpen(false);
     setShapePickerOpen(false);
     setEditingNodeId(null);
@@ -590,29 +890,23 @@ export function DiagramCanvas({
 
   const handleNodeClick = useCallback((nodeId: string, shiftKey: boolean) => {
     setShapePickerOpen(false);
+    setSelectedEdgeIdentity(null);
+    setEditingEdgeIdentity(null);
     setFocusedNodeId(nodeId);
     setToolbarOpen(true);
 
     if (mode === 'connect') {
-      if (!connectSourceId) {
-        setConnectSourceId(nodeId);
+      const activation = getConnectNodeActivation(nodeId, connectSourceId, interactiveNodeBounds);
+      if (activation.kind === 'choose-source') {
+        setConnectSourceId(activation.nodeId);
         return;
       }
 
-      if (connectSourceId === nodeId) {
+      if (activation.kind === 'noop') {
         return;
       }
 
-      const sourceBounds = hitMap?.nodes.get(connectSourceId);
-      const targetBounds = hitMap?.nodes.get(nodeId);
-      const midpoint = sourceBounds && targetBounds
-        ? {
-            x: (getBoundsCenter(sourceBounds).x + getBoundsCenter(targetBounds).x) / 2,
-            y: (getBoundsCenter(sourceBounds).y + getBoundsCenter(targetBounds).y) / 2,
-          }
-        : { x: 0, y: 0 };
-
-      setPendingEdge({ midpoint, source: connectSourceId, target: nodeId });
+      setPendingEdge(activation.edge);
       setPendingEdgeLabel('');
       setConnectSourceId(null);
       return;
@@ -626,7 +920,7 @@ export function DiagramCanvas({
     }
 
     setSelection([nodeId]);
-  }, [connectSourceId, hitMap?.nodes, mode, selection, setSelection]);
+  }, [connectSourceId, interactiveNodeBounds, mode, selection, setSelection]);
 
   const commitNodeEdit = useCallback(() => {
     if (!editingNodeId) {
@@ -637,6 +931,27 @@ export function DiagramCanvas({
     setEditingNodeId(null);
   }, [editingLabel, editingNodeId, onEditNodeLabel]);
 
+  const commitEdgeEdit = useCallback(() => {
+    if (!editingEdgeIdentity) {
+      return;
+    }
+
+    onEditEdgeLabel?.(editingEdgeIdentity, editingEdgeLabel.trim() || undefined);
+    setEditingEdgeIdentity(null);
+    setEditingEdgeLabel('');
+  }, [editingEdgeIdentity, editingEdgeLabel, onEditEdgeLabel]);
+
+  const openEdgeEditor = useCallback((edge: DiagramEdgeIdentity) => {
+    const edgeIndex = graph ? resolveDiagramEdgeIndex(graph.links, edge, { includeLabel: false }) : null;
+    const currentEdge = edgeIndex === null ? null : graph?.links[edgeIndex];
+    if (!currentEdge || readOnly) {
+      return;
+    }
+
+    setEditingEdgeIdentity(edge);
+    setEditingEdgeLabel(getLinkText(currentEdge) ?? '');
+  }, [graph, readOnly]);
+
   const commitPendingEdge = useCallback((label?: string) => {
     if (!pendingEdge) {
       return;
@@ -648,12 +963,150 @@ export function DiagramCanvas({
     setMode('select');
   }, [onAddEdge, pendingEdge, selectedConnectionType, setMode]);
 
+  const handleFlowNodesChange = useCallback((changes: NodeChange<MermaidFlowNode>[]) => {
+    const movedNodes = changes.filter((change) => change.type === 'position' && change.position);
+    if (movedNodes.length === 0) {
+      return;
+    }
+
+    setLiveNodePositions((current) => {
+      const next = { ...current };
+      movedNodes.forEach((change) => {
+        if (change.type === 'position' && change.position) {
+          next[change.id] = change.position;
+        }
+      });
+      return next;
+    });
+  }, []);
+
+  const handleFlowNodeDragStop = useCallback<OnNodeDrag<MermaidFlowNode>>((_event, node) => {
+    setNodePositions((current) => ({
+      ...current,
+      [node.id]: node.position,
+    }), 'merge', { [node.id]: node.position });
+    setLiveNodePositions((current) => {
+      const next = { ...current };
+      delete next[node.id];
+      return next;
+    });
+  }, [setNodePositions]);
+
+  const handleFlowConnectStart = useCallback<OnConnectStart>((_event, params) => {
+    connectionStartNodeIdRef.current = params.nodeId ?? null;
+    setConnectionPreviewSourceId(params.nodeId ?? null);
+    setToolbarOpen(false);
+  }, []);
+
+  const handleFlowConnectEnd = useCallback<OnConnectEnd>((event, connectionState: FinalConnectionState) => {
+    const sourceNodeId = connectionStartNodeIdRef.current;
+    connectionStartNodeIdRef.current = null;
+    setConnectionPreviewSourceId(null);
+
+    if (!sourceNodeId || readOnly || connectionState.isValid) {
+      return;
+    }
+
+    const clientPoint = getClientPoint(event);
+    if (!clientPoint || !containerRef.current) {
+      return;
+    }
+
+    const rect = containerRef.current.getBoundingClientRect();
+    const dropPoint = {
+      x: (clientPoint.x - rect.left - viewport.panX) / viewport.zoom,
+      y: (clientPoint.y - rect.top - viewport.panY) / viewport.zoom,
+    };
+    const nodePosition = {
+      x: dropPoint.x - (GHOST_NODE_WIDTH / 2),
+      y: dropPoint.y - (GHOST_NODE_HEIGHT / 2),
+    };
+
+    onAddConnectedNode?.(sourceNodeId, DEFAULT_NEW_NODE_LABEL, DEFAULT_NEW_NODE_SHAPE, nodePosition, selectedConnectionType);
+  }, [onAddConnectedNode, readOnly, selectedConnectionType, viewport.panX, viewport.panY, viewport.zoom]);
+
+  const handleFlowConnect = useCallback((connection: Connection) => {
+    connectionStartNodeIdRef.current = null;
+    setConnectionPreviewSourceId(null);
+    if (!connection.source || !connection.target || connection.source === connection.target || !interactiveNodeBounds) {
+      return;
+    }
+
+    const midpoint = getEdgeMidpoint({
+      source: connection.source,
+      target: connection.target,
+    }, interactiveNodeBounds) ?? { x: 0, y: 0 };
+
+    setPendingEdge({ midpoint, source: connection.source, target: connection.target });
+    setPendingEdgeLabel('');
+  }, [interactiveNodeBounds]);
+
+  const addDefaultNode = useCallback(() => {
+    onAddNode?.(DEFAULT_NEW_NODE_LABEL, DEFAULT_NEW_NODE_SHAPE);
+  }, [onAddNode]);
+
+  const addNodeFromToolbar = useCallback(() => {
+    onAddNode?.(newNodeLabel.trim() || DEFAULT_NEW_NODE_LABEL, newNodeShape);
+    setNewNodeLabel('');
+  }, [newNodeLabel, newNodeShape, onAddNode]);
+
   const openNodeEditor = useCallback((node: DiagramNode) => {
     setToolbarOpen(false);
     setEditingNodeId(node.id);
     setEditingLabel(getNodeText(node));
   }, []);
 
+  const registerNodeElement = useCallback((nodeId: string, element: HTMLElement | null) => {
+    if (element) {
+      nodeButtonRefs.current.set(nodeId, element);
+      return;
+    }
+
+    nodeButtonRefs.current.delete(nodeId);
+  }, []);
+
+  const handleNodeKeyDown = useCallback((nodeId: string, event: ReactKeyboardEvent<HTMLElement>) => {
+    if (event.key === 'ArrowUp') {
+      event.preventDefault();
+      moveFocus(nodeId, 'up');
+    }
+    if (event.key === 'ArrowDown') {
+      event.preventDefault();
+      moveFocus(nodeId, 'down');
+    }
+    if (event.key === 'ArrowLeft') {
+      event.preventDefault();
+      moveFocus(nodeId, 'left');
+    }
+    if (event.key === 'ArrowRight') {
+      event.preventDefault();
+      moveFocus(nodeId, 'right');
+    }
+    if (event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault();
+      handleNodeClick(nodeId, false);
+    }
+    if (event.key === 'F2') {
+      event.preventDefault();
+      const node = nodeById.get(nodeId);
+      if (node && !readOnly) {
+        openNodeEditor(node);
+      }
+    }
+    if (event.key === 'Escape') {
+      event.preventDefault();
+      setToolbarOpen(false);
+      containerRef.current?.focus();
+    }
+  }, [handleNodeClick, moveFocus, nodeById, openNodeEditor, readOnly]);
+
+  const flowNodeInteraction = useMemo<FlowNodeInteractionContextValue>(() => ({
+    focusedNodeId,
+    onFocus: setFocusedNodeId,
+    onKeyDown: handleNodeKeyDown,
+    registerNodeElement,
+  }), [focusedNodeId, handleNodeKeyDown, registerNodeElement]);
+
   const transformStyle: CSSProperties = {
     inset: 0,
     position: 'absolute',
@@ -705,20 +1158,22 @@ export function DiagramCanvas({
         {svg ? (
           <div
             aria-hidden="true"
-            className="diagram-canvas-svg"
+            className={useReactFlowRenderer
+              ? 'diagram-canvas-svg diagram-canvas-svg--reactflow'
+              : 'diagram-canvas-svg'}
             dangerouslySetInnerHTML={{ __html: svg }}
             ref={svgContainerRef}
             style={{ pointerEvents: 'none' }}
           />
         ) : null}
 
-        {isFlowchart && hitMap ? (
+        {isFlowchart && hitMap && !useReactFlowRenderer ? (
           <div style={{ inset: 0, position: 'absolute' }}>
             {[...hitMap.nodes.entries()].map(([nodeId, bounds]) => {
-              const node = graph?.nodes.find((candidate) => candidate.id === nodeId) ?? null;
+              const node = nodeById.get(nodeId) ?? null;
               const selected = selection.includes(nodeId);
               const focused = focusedNodeId === nodeId;
-              const ariaLabel = `${node?.shape ?? 'node'}: ${node ? getNodeText(node) : nodeId}`;
+              const ariaLabel = node ? getNodeAriaLabel(node.shape, getNodeText(node)) : getNodeAriaLabel('node', nodeId);
 
               return (
                 <button
@@ -737,37 +1192,8 @@ export function DiagramCanvas({
                     }
                     openNodeEditor(node);
                   }}
-                  onKeyDown={(event) => {
-                    if (event.key === 'ArrowUp') {
-                      event.preventDefault();
-                      moveFocus(nodeId, 'up');
-                    }
-                    if (event.key === 'ArrowDown') {
-                      event.preventDefault();
-                      moveFocus(nodeId, 'down');
-                    }
-                    if (event.key === 'ArrowLeft') {
-                      event.preventDefault();
-                      moveFocus(nodeId, 'left');
-                    }
-                    if (event.key === 'ArrowRight') {
-                      event.preventDefault();
-                      moveFocus(nodeId, 'right');
-                    }
-                    if (event.key === 'Enter' || event.key === ' ') {
-                      event.preventDefault();
-                      setSelection([nodeId]);
-                      setToolbarOpen(true);
-                    }
-                    if (event.key === 'Escape') {
-                      event.preventDefault();
-                      setToolbarOpen(false);
-                      containerRef.current?.focus();
-                    }
-                  }}
-                  ref={(element) => {
-                    nodeButtonRefs.current.set(nodeId, element);
-                  }}
+                  onKeyDown={(event) => { handleNodeKeyDown(nodeId, event); }}
+                  ref={(element) => { registerNodeElement(nodeId, element); }}
                   role="button"
                   style={{
                     background: selected ? 'rgba(56, 189, 248, 0.08)' : focused ? 'rgba(148, 163, 184, 0.06)' : 'rgba(255, 255, 255, 0.01)',
@@ -819,7 +1245,84 @@ export function DiagramCanvas({
         ) : null}
       </div>
 
-      <div aria-hidden="true" style={{ inset: 0, pointerEvents: 'none', position: 'absolute' }}>
+      {useReactFlowRenderer ? (
+        <div className="diagram-reactflow-layer">
+          <FlowEdgeMarkers />
+          <FlowNodeInteractionContext.Provider value={flowNodeInteraction}>
+            <ReactFlow
+              colorMode="dark"
+              autoPanOnConnect
+              autoPanOnNodeDrag
+              connectOnClick={false}
+              connectionLineStyle={{ stroke: '#38bdf8', strokeWidth: 2 }}
+              connectionLineType={ConnectionLineType.SmoothStep}
+              edges={flowEdges}
+              fitView={false}
+              maxZoom={MAX_ZOOM}
+              minZoom={MIN_ZOOM}
+              nodes={flowNodes}
+              nodesConnectable={!readOnly}
+              nodesDraggable={!readOnly}
+              nodeTypes={FLOW_NODE_TYPES}
+              onConnect={handleFlowConnect}
+              onConnectEnd={handleFlowConnectEnd}
+              onConnectStart={handleFlowConnectStart}
+              onEdgeClick={(event, edge) => {
+                event.stopPropagation();
+                const edgeIdentity = graph ? getDiagramEdgeIdentityForFlowEdge(graph.links, edge.id) : null;
+                if (!edgeIdentity) {
+                  return;
+                }
+                setSelection([]);
+                setToolbarOpen(false);
+                setShapePickerOpen(false);
+                setEditingNodeId(null);
+                setSelectedEdgeIdentity(edgeIdentity);
+              }}
+              onEdgeDoubleClick={(event, edge) => {
+                event.stopPropagation();
+                const edgeIdentity = graph ? getDiagramEdgeIdentityForFlowEdge(graph.links, edge.id) : null;
+                if (edgeIdentity) {
+                  setSelectedEdgeIdentity(edgeIdentity);
+                  openEdgeEditor(edgeIdentity);
+                }
+              }}
+              onNodeClick={(event, node) => {
+                event.stopPropagation();
+                handleNodeClick(node.id, event.shiftKey);
+              }}
+              onNodeDoubleClick={(event, node) => {
+                event.stopPropagation();
+                const diagramNode = nodeById.get(node.id);
+                if (diagramNode && !readOnly) {
+                  openNodeEditor(diagramNode);
+                }
+              }}
+              onNodeDragStop={handleFlowNodeDragStop}
+              onNodesChange={handleFlowNodesChange}
+              onMove={(_event, nextViewport) => {
+                setAnimateTransform(false);
+                setViewport((current) => ({
+                  panX: nextViewport.x,
+                  panY: nextViewport.y,
+                  zoom: current.zoom,
+                }));
+              }}
+              onPaneClick={handleCanvasClick}
+              panOnDrag={false}
+              preventScrolling={false}
+              proOptions={FLOW_PRO_OPTIONS}
+              selectionOnDrag={false}
+              viewport={flowViewport}
+              zoomOnDoubleClick={false}
+              zoomOnPinch={false}
+              zoomOnScroll={false}
+            />
+          </FlowNodeInteractionContext.Provider>
+        </div>
+      ) : null}
+
+      <div aria-hidden="true" style={{ inset: 0, pointerEvents: 'none', position: 'absolute', zIndex: 10 }}>
         {rubberBandPoints ? (
           <svg style={{ height: '100%', width: '100%' }}>
             <line
@@ -834,6 +1337,29 @@ export function DiagramCanvas({
           </svg>
         ) : null}
 
+        {connectionGhostRect ? (
+          <div
+            style={{
+              alignItems: 'center',
+              background: 'rgba(22, 27, 34, 0.72)',
+              border: '1px dashed #38bdf8',
+              borderRadius: 10,
+              color: '#e2e8f0',
+              display: 'flex',
+              fontSize: 13,
+              fontWeight: 600,
+              height: connectionGhostRect.height,
+              justifyContent: 'center',
+              left: connectionGhostRect.x,
+              position: 'absolute',
+              top: connectionGhostRect.y,
+              width: connectionGhostRect.width,
+            }}
+          >
+            {DEFAULT_NEW_NODE_LABEL}
+          </div>
+        ) : null}
+
         {mode === 'connect' ? (
           <div
             style={{
@@ -855,7 +1381,73 @@ export function DiagramCanvas({
         ) : null}
       </div>
 
-      <div onClick={(event) => { event.stopPropagation(); }} style={{ inset: 0, pointerEvents: 'none', position: 'absolute' }}>
+      <div onClick={(event) => { event.stopPropagation(); }} style={{ inset: 0, pointerEvents: 'none', position: 'absolute', zIndex: 20 }}>
+        {isFlowchart && !readOnly ? (
+          <form
+            aria-label="Add Mermaid node"
+            onSubmit={(event) => {
+              event.preventDefault();
+              addNodeFromToolbar();
+            }}
+            style={{
+              alignItems: 'center',
+              background: '#161b22',
+              border: '1px solid #30363d',
+              borderRadius: 10,
+              boxShadow: '0 12px 32px rgba(2, 6, 23, 0.35)',
+              color: '#8b949e',
+              display: 'flex',
+              gap: 8,
+              left: 12,
+              padding: '8px 10px',
+              pointerEvents: 'auto',
+              position: 'absolute',
+              bottom: 12,
+              zIndex: 20,
+            }}
+          >
+            <span style={{ fontFamily: 'var(--font-mono)', fontSize: 11 }}>add node</span>
+            <input
+              aria-label="New node label"
+              onChange={(event) => { setNewNodeLabel(event.target.value); }}
+              placeholder="label"
+              style={{
+                background: '#0d1117',
+                border: '1px solid #30363d',
+                borderRadius: 6,
+                color: '#c9d1d9',
+                fontFamily: 'var(--font-mono)',
+                fontSize: 11,
+                outline: 'none',
+                padding: '5px 7px',
+                width: 140,
+              }}
+              value={newNodeLabel}
+            />
+            <select
+              aria-label="New node shape"
+              onChange={(event) => { setNewNodeShape(event.target.value as DiagramNodeShape); }}
+              style={{
+                background: '#0d1117',
+                border: '1px solid #30363d',
+                borderRadius: 6,
+                color: '#c9d1d9',
+                fontFamily: 'var(--font-mono)',
+                fontSize: 11,
+                padding: '5px 7px',
+              }}
+              value={newNodeShape}
+            >
+              {SHAPE_OPTIONS.map((shape) => (
+                <option key={shape.value} value={shape.value}>{shape.label}</option>
+              ))}
+            </select>
+            <ToolbarButton label="Add node to Mermaid text" onClick={addNodeFromToolbar}>
+              <Plus size={16} />
+            </ToolbarButton>
+          </form>
+        ) : null}
+
         {(!hasGraphNodes && isFlowchart && !readOnly) ? (
           <div
             style={{
@@ -867,7 +1459,7 @@ export function DiagramCanvas({
             }}
           >
             <button
-              onClick={() => { onAddNode?.('New Node', 'rect'); }}
+              onClick={addDefaultNode}
               style={{
                 background: '#161b22',
                 border: '1px solid #30363d',
@@ -891,7 +1483,7 @@ export function DiagramCanvas({
           <div style={toolbarStyle}>
             {selection.length === 1 ? (
               <ToolbarButton label="Edit label" onClick={() => {
-                const selectedNode = graph?.nodes.find((node) => node.id === selection[0]);
+                const selectedNode = selection[0] ? nodeById.get(selection[0]) : undefined;
                 if (selectedNode) {
                   openNodeEditor(selectedNode);
                 }
@@ -918,7 +1510,7 @@ export function DiagramCanvas({
                 <Trash2 size={16} />
               </ToolbarButton>
             ) : null}
-            <ToolbarButton label="Add node" onClick={() => { onAddNode?.('New Node', 'rect'); }}>
+            <ToolbarButton label="Add node" onClick={addDefaultNode}>
               <Plus size={16} />
             </ToolbarButton>
 
@@ -940,7 +1532,7 @@ export function DiagramCanvas({
                 }}
               >
                 {SHAPE_OPTIONS.map((shape) => {
-                  const currentNode = graph?.nodes.find((node) => node.id === selection[0]);
+                  const currentNode = selection[0] ? nodeById.get(selection[0]) : undefined;
                   const active = currentNode?.shape === shape.value;
 
                   return (
@@ -974,6 +1566,37 @@ export function DiagramCanvas({
           </div>
         ) : null}
 
+        {isFlowchart && !readOnly && selectedCurrentEdgeIdentity && selectedEdgeMidpoint ? (
+          <div
+            aria-label="Selected edge toolbar"
+            style={{
+              alignItems: 'center',
+              background: '#161b22',
+              border: '1px solid #30363d',
+              borderRadius: 8,
+              boxShadow: '0 12px 32px rgba(2, 6, 23, 0.45)',
+              display: 'inline-flex',
+              gap: 6,
+              left: toScreenPoint(selectedEdgeMidpoint, viewport).x - 42,
+              padding: '4px 6px',
+              pointerEvents: 'auto',
+              position: 'absolute',
+              top: toScreenPoint(selectedEdgeMidpoint, viewport).y - 40,
+              zIndex: 30,
+            }}
+          >
+            <ToolbarButton label="Edit edge label" onClick={() => { openEdgeEditor(selectedCurrentEdgeIdentity); }}>
+              <Pencil size={16} />
+            </ToolbarButton>
+            <ToolbarButton label="Delete selected edge" onClick={() => {
+              onDeleteEdge?.(selectedCurrentEdgeIdentity);
+              setSelectedEdgeIdentity(null);
+            }}>
+              <Trash2 size={16} />
+            </ToolbarButton>
+          </div>
+        ) : null}
+
         {!readOnly ? (
           <div
             style={{
@@ -991,6 +1614,11 @@ export function DiagramCanvas({
               right: 12,
             }}
           >
+            {hasPersistedLayout ? (
+              <ToolbarButton label="Reset shared layout to Mermaid" onClick={() => { setNodePositions(() => ({}), 'replace'); }}>
+                <RotateCcw size={16} />
+              </ToolbarButton>
+            ) : null}
             <ToolbarButton label="Zoom out" onClick={() => {
               setViewport((current) => ({ ...current, zoom: clamp(current.zoom * 0.9, MIN_ZOOM, MAX_ZOOM) }));
             }}>
@@ -1049,6 +1677,49 @@ export function DiagramCanvas({
           </div>
         ) : null}
 
+        {editingEdgeIndex !== null && editingEdgeMidpoint ? (
+          <div
+            style={{
+              left: toScreenPoint(editingEdgeMidpoint, viewport).x - 90,
+              pointerEvents: 'auto',
+              position: 'absolute',
+              top: toScreenPoint(editingEdgeMidpoint, viewport).y - 18,
+              width: 180,
+            }}
+          >
+            <input
+              aria-label="Edge label"
+              autoFocus
+              onBlur={commitEdgeEdit}
+              onChange={(event) => { setEditingEdgeLabel(event.target.value); }}
+              onFocus={(event) => { event.currentTarget.select(); }}
+              onKeyDown={(event) => {
+                if (event.key === 'Enter') {
+                  commitEdgeEdit();
+                }
+                if (event.key === 'Escape') {
+                  setEditingEdgeIdentity(null);
+                  setEditingEdgeLabel('');
+                }
+              }}
+              placeholder="edge label"
+              style={{
+                background: '#0d1117',
+                border: '1px solid #30363d',
+                borderBottomColor: '#38bdf8',
+                borderRadius: 8,
+                color: '#c9d1d9',
+                fontFamily: 'var(--font-mono)',
+                fontSize: 12,
+                outline: 'none',
+                padding: '8px 10px',
+                width: '100%',
+              }}
+              value={editingEdgeLabel}
+            />
+          </div>
+        ) : null}
+
         {pendingEdge ? (
           <div
             style={{
@@ -1173,7 +1844,79 @@ export function DiagramCanvas({
   );
 }
 
-function ToolbarButton({ children, label, onClick }: { children: React.ReactNode; label: string; onClick: () => void }) {
+function FlowEdgeMarkers() {
+  return (
+    <svg aria-hidden="true" focusable="false" style={{ height: 0, position: 'absolute', width: 0 }}>
+      <defs>
+        <marker
+          id={FLOW_EDGE_MARKER_CIRCLE_ID}
+          markerHeight="10"
+          markerUnits="strokeWidth"
+          markerWidth="10"
+          orient="auto"
+          refX="9"
+          refY="5"
+          viewBox="0 0 10 10"
+        >
+          <circle cx="5" cy="5" fill="#0d1117" r="3" stroke={FLOW_EDGE_COLOR} strokeWidth="1.6" />
+        </marker>
+        <marker
+          id={FLOW_EDGE_MARKER_CROSS_ID}
+          markerHeight="10"
+          markerUnits="strokeWidth"
+          markerWidth="10"
+          orient="auto"
+          refX="9"
+          refY="5"
+          viewBox="0 0 10 10"
+        >
+          <path d="M3 3 L7 7 M7 3 L3 7" fill="none" stroke={FLOW_EDGE_COLOR} strokeLinecap="round" strokeWidth="1.8" />
+        </marker>
+      </defs>
+    </svg>
+  );
+}
+
+function MermaidReactFlowNode({ data, id, selected }: NodeProps<MermaidFlowNode>) {
+  const interaction = useContext(FlowNodeInteractionContext);
+  const focused = interaction?.focusedNodeId === id;
+  const label = data.ariaLabel;
+
+  return (
+    <div
+      aria-label={label}
+      aria-pressed={selected}
+      className={`mermaid-flow-node mermaid-flow-node--${getShapeClassName(data.shape)}${selected ? ' is-selected' : ''}${focused ? ' is-focused' : ''}`}
+      onFocus={() => { interaction?.onFocus(id); }}
+      onKeyDown={(event) => { interaction?.onKeyDown(id, event); }}
+      ref={(element) => { interaction?.registerNodeElement(id, element); }}
+      role="button"
+      tabIndex={focused ? 0 : -1}
+    >
+      {FLOW_HANDLE_POSITIONS.map((position) => (
+        <Handle
+          className={`mermaid-flow-handle mermaid-flow-handle--${position} mermaid-flow-handle--target`}
+          id={getFlowHandleId('target', position)}
+          key={`target-${position}`}
+          position={position}
+          type="target"
+        />
+      ))}
+      <span>{data.label}</span>
+      {FLOW_HANDLE_POSITIONS.map((position) => (
+        <Handle
+          className={`mermaid-flow-handle mermaid-flow-handle--${position} mermaid-flow-handle--source`}
+          id={getFlowHandleId('source', position)}
+          key={`source-${position}`}
+          position={position}
+          type="source"
+        />
+      ))}
+    </div>
+  );
+}
+
+function ToolbarButton({ children, label, onClick }: { children: ReactNode; label: string; onClick: () => void }) {
   return (
     <button aria-label={label} onClick={onClick} style={TOOLBAR_BUTTON_STYLE} title={label} type="button">
       {children}
@@ -1185,6 +1928,44 @@ function getNodeText(node: DiagramNode): string {
   return typeof node.text === 'string' ? node.text : node.text?.text ?? node.id;
 }
 
+function getLinkText(link: { text?: string | { text?: string } }): string | undefined {
+  if (typeof link.text === 'string') {
+    return link.text;
+  }
+
+  return link.text?.text;
+}
+
+function getFlowEdgePresentation(link: DiagramLink): Pick<Edge, 'markerEnd' | 'style'> {
+  const strokeWidth = link.stroke === 'thick' ? 3 : 1.8;
+  const strokeDasharray = link.stroke === 'dotted' ? '5 5' : undefined;
+  const style: CSSProperties = {
+    stroke: FLOW_EDGE_COLOR,
+    strokeDasharray,
+    strokeWidth,
+  };
+
+  switch (link.type) {
+    case 'arrow_open':
+      return { markerEnd: { color: FLOW_EDGE_COLOR, type: MarkerType.Arrow }, style };
+    case 'arrow_circle':
+      return { markerEnd: FLOW_EDGE_MARKER_CIRCLE_ID, style };
+    case 'arrow_cross':
+      return { markerEnd: FLOW_EDGE_MARKER_CROSS_ID, style };
+    case 'arrow_point':
+    default:
+      return { markerEnd: { color: FLOW_EDGE_COLOR, type: MarkerType.ArrowClosed }, style };
+  }
+}
+
+function getNodeAriaLabel(shape: string | undefined, label: string): string {
+  return `${shape ?? 'node'}: ${label}`;
+}
+
+function getShapeClassName(shape?: DiagramNodeShape): string {
+  return shape?.replace(/[^a-z0-9_-]/gi, '').toLowerCase() || 'rect';
+}
+
 function isTypingElement(target: EventTarget | null): boolean {
   if (!(target instanceof HTMLElement)) {
     return false;
@@ -1243,6 +2024,83 @@ function renderShape(shape: DiagramNodeShape) {
   }
 }
 
+function getEdgeMidpoint(edge: Pick<DiagramLink, 'source' | 'target'>, nodeBounds: Map<string, SvgBounds>): SvgPoint | null {
+  const sourceBounds = nodeBounds.get(edge.source);
+  const targetBounds = nodeBounds.get(edge.target);
+  if (!sourceBounds || !targetBounds) {
+    return null;
+  }
+
+  const sourceCenter = getBoundsCenter(sourceBounds);
+  const targetCenter = getBoundsCenter(targetBounds);
+  return {
+    x: (sourceCenter.x + targetCenter.x) / 2,
+    y: (sourceCenter.y + targetCenter.y) / 2,
+  };
+}
+
+function getFlowHandleId(type: 'source' | 'target', position: Position): string {
+  return `${type}-${position}`;
+}
+
+function getFlowEdgeHandles(
+  link: DiagramLink,
+  nodeBounds: Map<string, SvgBounds>,
+  direction: FlowchartSnapshot['direction'],
+): Pick<Edge, 'sourceHandle' | 'targetHandle'> {
+  const sourceBounds = nodeBounds.get(link.source);
+  const targetBounds = nodeBounds.get(link.target);
+  let sourcePosition: Position;
+  let targetPosition: Position;
+
+  if (sourceBounds && targetBounds) {
+    const sourceCenter = getBoundsCenter(sourceBounds);
+    const targetCenter = getBoundsCenter(targetBounds);
+    const dx = targetCenter.x - sourceCenter.x;
+    const dy = targetCenter.y - sourceCenter.y;
+
+    if (Math.abs(dx) >= Math.abs(dy)) {
+      sourcePosition = dx >= 0 ? Position.Right : Position.Left;
+      targetPosition = dx >= 0 ? Position.Left : Position.Right;
+    } else {
+      sourcePosition = dy >= 0 ? Position.Bottom : Position.Top;
+      targetPosition = dy >= 0 ? Position.Top : Position.Bottom;
+    }
+  } else {
+    const fallback = getFlowPortPositions(direction);
+    sourcePosition = fallback.source;
+    targetPosition = fallback.target;
+  }
+
+  return {
+    sourceHandle: getFlowHandleId('source', sourcePosition),
+    targetHandle: getFlowHandleId('target', targetPosition),
+  };
+}
+
+function getFlowPortPositions(direction: FlowchartSnapshot['direction']): { source: Position; target: Position } {
+  switch (direction) {
+    case 'BT':
+      return { source: Position.Top, target: Position.Bottom };
+    case 'LR':
+      return { source: Position.Right, target: Position.Left };
+    case 'RL':
+      return { source: Position.Left, target: Position.Right };
+    case 'TD':
+    default:
+      return { source: Position.Bottom, target: Position.Top };
+  }
+}
+
+function getClientPoint(event: MouseEvent | TouchEvent): SvgPoint | null {
+  if ('changedTouches' in event) {
+    const touch = event.changedTouches[0];
+    return touch ? { x: touch.clientX, y: touch.clientY } : null;
+  }
+
+  return { x: event.clientX, y: event.clientY };
+}
+
 function toScreenRect(bounds: SvgBounds, viewport: ViewportState): ScreenRect {
   return {
     height: bounds.height * viewport.zoom,
diff --git a/apps/web/src/components/session-workspace.tsx b/apps/web/src/components/session-workspace.tsx
index 35b0ba0..5116508 100644
--- a/apps/web/src/components/session-workspace.tsx
+++ b/apps/web/src/components/session-workspace.tsx
@@ -12,10 +12,25 @@ import { yCollab, yUndoManagerKeymap } from 'y-codemirror.next';
 import { WebsocketProvider } from 'y-websocket';
 import * as Y from 'yjs';
 import { DiagramCanvas } from './diagram-canvas';
-import { MutationQueue, parseFlowchartSnapshot, type FlowchartSnapshot } from '../lib/diagram-mutations';
+import {
+  MutationQueue,
+  observeMutationFailure,
+  parseFlowchartSnapshot,
+  type DiagramLinkType,
+  type DiagramNodeShape,
+  type FlowchartSnapshot,
+} from '../lib/diagram-mutations';
+import {
+  readNodePositions,
+  writeNodePositions,
+  type DiagramNodePosition,
+  type DiagramNodePositions,
+  type NodePositionsSyncMode,
+} from '../lib/diagram-layout';
 import { getSessionPath, getWebsocketServerUrl } from '../lib/session';
 
 const MERMAID_TEXT_KEY = 'mermaid';
+const NODE_POSITIONS_KEY = 'nodePositions';
 const ACTIVITY_KEY = 'activity';
 const MAX_ACTIVITY_EVENTS = 100;
 const EDIT_ACTIVITY_DEBOUNCE_MS = 900;
@@ -36,10 +51,13 @@ type CollaborationState = {
   activityArray: Y.Array<ActivityEvent>;
   awareness: AwarenessLike;
   doc: Y.Doc;
+  nodePositionsMap: Y.Map<NodePosition>;
   provider: WebsocketProvider;
   yText: Y.Text;
 };
 
+type NodePosition = DiagramNodePosition;
+
 type AwarenessLike = {
   getStates: () => Map<number, unknown>;
   off: (eventName: string, handler: (...args: unknown[]) => void) => void;
@@ -157,6 +175,10 @@ function isFlowchartSyntax(text: string): boolean {
   return trimmed.startsWith('flowchart') || trimmed.startsWith('graph');
 }
 
+function canBuildFlowchartFromCanvas(text: string): boolean {
+  return text.trim().length === 0 || isFlowchartSyntax(text);
+}
+
 function stripParticipantTabSuffix(name: string): string {
   return name.replace(/-[a-z0-9]{2}$/i, '');
 }
@@ -250,12 +272,14 @@ export function SessionWorkspace({ sessionId }: { sessionId: string }) {
   const [activity, setActivity] = useState<ActivityEvent[]>([]);
   const [lastValidSvg, setLastValidSvg] = useState('');
   const [renderError, setRenderError] = useState<string | null>(null);
+  const [mutationError, setMutationError] = useState<string | null>(null);
   const [shareCopyState, setShareCopyState] = useState<'idle' | 'copied' | 'error'>('idle');
   const [sessionIdCopyState, setSessionIdCopyState] = useState<'idle' | 'copied' | 'error'>('idle');
   const [promptCopyState, setPromptCopyState] = useState<'idle' | 'copied' | 'error'>('idle');
   const [shareUrl, setShareUrl] = useState(() => getSessionPath(sessionId));
   const [showConnectModal, setShowConnectModal] = useState(false);
   const [flowchartSnapshot, setFlowchartSnapshot] = useState<FlowchartSnapshot | null>(null);
+  const [nodePositions, setNodePositions] = useState<DiagramNodePositions>({});
   const [selectedNodeIds, setSelectedNodeIds] = useState<string[]>([]);
   const [interactionMode, setInteractionMode] = useState<'select' | 'connect'>('select');
   const [renamingParticipantName, setRenamingParticipantName] = useState<string | null>(null);
@@ -281,6 +305,7 @@ export function SessionWorkspace({ sessionId }: { sessionId: string }) {
     });
     const awareness = provider.awareness as AwarenessLike;
     const yText = doc.getText(MERMAID_TEXT_KEY);
+    const nodePositionsMap = doc.getMap<NodePosition>(NODE_POSITIONS_KEY);
     const queue = new MutationQueue(yText, { transactionOrigin: 'visual' });
     mutationQueueRef.current = queue;
     const activityArray = doc.getArray<ActivityEvent>(ACTIVITY_KEY);
@@ -296,6 +321,10 @@ export function SessionWorkspace({ sessionId }: { sessionId: string }) {
       setActivity(activityArray.toArray().slice().reverse());
     };
 
+    const syncNodePositions = () => {
+      setNodePositions(readNodePositions(nodePositionsMap));
+    };
+
     const syncParticipants = () => {
       setParticipants(getParticipantsFromAwareness(awareness));
     };
@@ -342,10 +371,12 @@ export function SessionWorkspace({ sessionId }: { sessionId: string }) {
 
     syncText();
     syncActivity();
+    syncNodePositions();
     syncParticipants();
 
     yText.observe(syncText);
     activityArray.observe(syncActivity);
+    nodePositionsMap.observe(syncNodePositions);
     awareness.on('change', syncParticipants);
     provider.on('status', handleStatus);
     provider.on('connection-close', handleReconnectSignal);
@@ -357,7 +388,7 @@ export function SessionWorkspace({ sessionId }: { sessionId: string }) {
       }
     });
 
-    setCollaboration({ activityArray, awareness, doc, provider, yText });
+    setCollaboration({ activityArray, awareness, doc, nodePositionsMap, provider, yText });
 
     return () => {
       if (editDebounceRef.current !== null) {
@@ -372,6 +403,7 @@ export function SessionWorkspace({ sessionId }: { sessionId: string }) {
       provider.off('connection-error', handleReconnectSignal);
       yText.unobserve(syncText);
       activityArray.unobserve(syncActivity);
+      nodePositionsMap.unobserve(syncNodePositions);
       awareness.setLocalState(null);
       provider.destroy();
       doc.destroy();
@@ -631,6 +663,59 @@ export function SessionWorkspace({ sessionId }: { sessionId: string }) {
     setRenamingParticipantName(null);
   }, [collaboration, displayNameDraft]);
 
+  const handleNodePositionsChange = useCallback((positions: DiagramNodePositions, mode: NodePositionsSyncMode = 'merge') => {
+    setNodePositions((current) => {
+      if (mode === 'replace') {
+        return positions;
+      }
+
+      if (mode === 'remove') {
+        const next = { ...current };
+        for (const nodeId of Object.keys(positions)) {
+          delete next[nodeId];
+        }
+        return next;
+      }
+
+      return { ...current, ...positions };
+    });
+
+    if (!collaboration) {
+      return;
+    }
+
+    collaboration.doc.transact(() => {
+      writeNodePositions(collaboration.nodePositionsMap, positions, mode);
+    }, 'visual-layout');
+  }, [collaboration]);
+
+  const handleSingleNodePositionChange = useCallback((nodeId: string, position: NodePosition) => {
+    handleNodePositionsChange({ [nodeId]: position }, 'merge');
+  }, [handleNodePositionsChange]);
+
+  const runMutation = useCallback((mutation: Promise<unknown>) => {
+    setMutationError(null);
+    observeMutationFailure(mutation, (error) => {
+      setMutationError(error instanceof Error ? error.message : 'The diagram update could not be applied.');
+    });
+  }, []);
+
+  const handleAddConnectedNode = useCallback((source: string, label: string, shape: DiagramNodeShape, position: NodePosition, type: DiagramLinkType) => {
+    const queue = mutationQueueRef.current;
+    if (!queue) {
+      return;
+    }
+
+    runMutation(queue.addConnectedNode(source, label, { shape, type })
+      .then(({ nodeId }) => {
+        if (!nodeId) {
+          return;
+        }
+        handleSingleNodePositionChange(nodeId, position);
+        setSelectedNodeIds([nodeId]);
+      }));
+  }, [handleSingleNodePositionChange, runMutation]);
+
   return (
     <main className="workspace-shell">
       <header className="workspace-topbar">
@@ -763,23 +848,45 @@ export function SessionWorkspace({ sessionId }: { sessionId: string }) {
             </div>
           ) : null}
 
+          {mutationError ? (
+            <div data-testid="mutation-error-banner" className="error-banner" role="status">
+              <strong>diagram update not applied</strong>
+              <span>{mutationError}</span>
+            </div>
+          ) : null}
+
           <DiagramCanvas
             className="diagram-canvas"
             emptyMessage={mermaidText.trim() ? 'rendering preview…' : 'start typing mermaid syntax'}
             graph={flowchartSnapshot}
             interactionMode={interactionMode}
-            isFlowchart={isFlowchartSyntax(mermaidText)}
+            isFlowchart={canBuildFlowchartFromCanvas(mermaidText)}
+            nodePositions={nodePositions}
             onAddEdge={(source, target, label, type) => mutationQueueRef.current?.addEdge(source, target, { label, type })}
             onAddNode={(label, shape) => mutationQueueRef.current?.addNode(label, { shape })}
+            onAddConnectedNode={handleAddConnectedNode}
             onChangeNodeShape={(nodeId, shape) => mutationQueueRef.current?.changeNodeShape(nodeId, shape)}
             onDeleteNodes={(ids) => {
               for (const id of ids) {
                 void mutationQueueRef.current?.removeNode(id);
               }
             }}
+            onDeleteEdge={(edge) => {
+              const queue = mutationQueueRef.current;
+              if (queue) {
+                runMutation(queue.removeEdgeByIdentity(edge));
+              }
+            }}
+            onEditEdgeLabel={(edge, label) => {
+              const queue = mutationQueueRef.current;
+              if (queue) {
+                runMutation(queue.editEdgeLabelByIdentity(edge, label));
+              }
+            }}
             onEditNodeLabel={(nodeId, label) => mutationQueueRef.current?.editNodeLabel(nodeId, label)}
             onGroupNodes={(ids, label) => mutationQueueRef.current?.groupNodes(ids, label)}
             onInteractionModeChange={setInteractionMode}
+            onNodePositionsChange={handleNodePositionsChange}
             onSelectedNodeIdsChange={setSelectedNodeIds}
             onUngroupNodes={(id) => mutationQueueRef.current?.ungroupSubgraph(id)}
             selectedNodeIds={selectedNodeIds}
diff --git a/apps/web/src/lib/diagram-connect-state.test.ts b/apps/web/src/lib/diagram-connect-state.test.ts
new file mode 100644
index 0000000..cc1a3de
--- /dev/null
+++ b/apps/web/src/lib/diagram-connect-state.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+import { getConnectNodeActivation } from './diagram-connect-state';
+
+describe('getConnectNodeActivation', () => {
+  it('runs source and target selections through one activation flow', () => {
+    const nodeBounds = new Map([
+      ['source', { height: 20, width: 40, x: 10, y: 20 }],
+      ['target', { height: 40, width: 20, x: 110, y: 100 }],
+    ]);
+
+    expect(getConnectNodeActivation('source', null, nodeBounds)).toEqual({
+      kind: 'choose-source',
+      nodeId: 'source',
+    });
+    expect(getConnectNodeActivation('target', 'source', nodeBounds)).toEqual({
+      edge: {
+        midpoint: { x: 75, y: 75 },
+        source: 'source',
+        target: 'target',
+      },
+      kind: 'choose-target',
+    });
+  });
+
+  it('does not turn a repeated source activation into a self edge', () => {
+    expect(getConnectNodeActivation('source', 'source', null)).toEqual({ kind: 'noop' });
+  });
+});
diff --git a/apps/web/src/lib/diagram-connect-state.ts b/apps/web/src/lib/diagram-connect-state.ts
new file mode 100644
index 0000000..9ec4083
--- /dev/null
+++ b/apps/web/src/lib/diagram-connect-state.ts
@@ -0,0 +1,41 @@
+import { getBoundsCenter, type SvgBounds, type SvgPoint } from './svg-hit-map';
+
+export type ConnectNodeActivation =
+  | { kind: 'choose-source'; nodeId: string }
+  | { kind: 'choose-target'; edge: { midpoint: SvgPoint; source: string; target: string } }
+  | { kind: 'noop' };
+
+/** Resolve a node activation while the canvas is in connect mode. */
+export function getConnectNodeActivation(
+  nodeId: string,
+  sourceNodeId: string | null,
+  nodeBounds: ReadonlyMap<string, SvgBounds> | null,
+): ConnectNodeActivation {
+  if (!sourceNodeId) {
+    return { kind: 'choose-source', nodeId };
+  }
+
+  if (sourceNodeId === nodeId) {
+    return { kind: 'noop' };
+  }
+
+  const sourceBounds = nodeBounds?.get(sourceNodeId);
+  const targetBounds = nodeBounds?.get(nodeId);
+  const sourceCenter = sourceBounds ? getBoundsCenter(sourceBounds) : null;
+  const targetCenter = targetBounds ? getBoundsCenter(targetBounds) : null;
+  const midpoint = sourceCenter && targetCenter
+    ? {
+        x: (sourceCenter.x + targetCenter.x) / 2,
+        y: (sourceCenter.y + targetCenter.y) / 2,
+      }
+    : { x: 0, y: 0 };
+
+  return {
+    edge: {
+      midpoint,
+      source: sourceNodeId,
+      target: nodeId,
+    },
+    kind: 'choose-target',
+  };
+}
diff --git a/apps/web/src/lib/diagram-flow-identity.test.ts b/apps/web/src/lib/diagram-flow-identity.test.ts
new file mode 100644
index 0000000..52bb1aa
--- /dev/null
+++ b/apps/web/src/lib/diagram-flow-identity.test.ts
@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest';
+import * as Y from 'yjs';
+import { MutationQueue, parseFlowchartSnapshot } from './diagram-mutations';
+import { getDiagramEdgeIdentityForFlowEdge, getFlowEdgeId, getVisibleDiagramLinks } from './diagram-flow-identity';
+
+function setText(yText: Y.Text, text: string) {
+  yText.delete(0, yText.length);
+  yText.insert(0, text);
+}
+
+const threeEdgeDiagram = 'flowchart LR\n  A --> B\n  B --> C\n  C --> D\n';
+const boundsMissingFirstEdgeSource = new Map<string, unknown>([
+  ['B', {}],
+  ['C', {}],
+  ['D', {}],
+]);
+
+describe('React Flow edge identity', () => {
+  it('keeps the canonical graph link index when earlier links are filtered', () => {
+    const snapshot = parseFlowchartSnapshot(threeEdgeDiagram);
+
+    const visibleLinks = getVisibleDiagramLinks(snapshot.links, boundsMissingFirstEdgeSource);
+
+    expect(visibleLinks).toHaveLength(2);
+    expect(visibleLinks[0]?.graphIndex).toBe(1);
+    expect(getFlowEdgeId(visibleLinks[0]!.graphIndex)).toBe('edge-1');
+    expect(visibleLinks[0]?.link.source).toBe('B');
+    expect(visibleLinks[0]?.link.target).toBe('C');
+  });
+
+  it('selects, edits, and deletes the visible edge by canonical identity instead of filtered index', async () => {
+    const doc = new Y.Doc();
+    const yText = doc.getText('mermaid');
+    setText(yText, threeEdgeDiagram);
+
+    const snapshot = parseFlowchartSnapshot(yText.toString());
+    const visibleLinks = getVisibleDiagramLinks(snapshot.links, boundsMissingFirstEdgeSource);
+    const visibleEdgeId = getFlowEdgeId(visibleLinks[0]!.graphIndex);
+    const selected = getDiagramEdgeIdentityForFlowEdge(snapshot.links, visibleEdgeId);
+    expect(selected?.index).toBe(1);
+    expect(selected?.source).toBe('B');
+    expect(selected?.target).toBe('C');
+
+    const queue = new MutationQueue(yText);
+    const edited = await queue.editEdgeLabelByIdentity(selected!, 'visible');
+
+    expect(edited.snapshot.links[0]?.source).toBe('A');
+    expect(edited.snapshot.links[0]?.target).toBe('B');
+    expect(edited.snapshot.links[0]?.text?.text).toBeUndefined();
+    expect(edited.snapshot.links[1]?.source).toBe('B');
+    expect(edited.snapshot.links[1]?.target).toBe('C');
+    expect(edited.snapshot.links[1]?.text?.text).toBe('visible');
+
+    const refreshed = getDiagramEdgeIdentityForFlowEdge(edited.snapshot.links, visibleEdgeId);
+    const deleted = await queue.removeEdgeByIdentity(refreshed!);
+
+    expect(deleted.snapshot.links).toHaveLength(2);
+    expect(deleted.snapshot.links[0]?.source).toBe('A');
+    expect(deleted.snapshot.links[0]?.target).toBe('B');
+    expect(deleted.snapshot.links[1]?.source).toBe('C');
+    expect(deleted.snapshot.links[1]?.target).toBe('D');
+  });
+});
diff --git a/apps/web/src/lib/diagram-flow-identity.ts b/apps/web/src/lib/diagram-flow-identity.ts
new file mode 100644
index 0000000..38c04b6
--- /dev/null
+++ b/apps/web/src/lib/diagram-flow-identity.ts
@@ -0,0 +1,42 @@
+import type { FlowchartLink } from 'mermaid-ast';
+import { getDiagramEdgeIdentity } from './diagram-mutations';
+import type { DiagramEdgeIdentity } from './diagram-mutations';
+
+export interface IndexedDiagramLink<TLink extends Pick<FlowchartLink, 'source' | 'target'> = FlowchartLink> {
+  graphIndex: number;
+  link: TLink;
+}
+
+export function getFlowEdgeId(index: number): string {
+  return `edge-${index}`;
+}
+
+export function getFlowEdgeIndex(edgeId: string): number | null {
+  const match = /^edge-(\d+)$/.exec(edgeId);
+  if (!match) {
+    return null;
+  }
+
+  return Number.parseInt(match[1]!, 10);
+}
+
+export function getVisibleDiagramLinks<TLink extends Pick<FlowchartLink, 'source' | 'target'>>(
+  links: readonly TLink[],
+  nodeBounds: Pick<ReadonlyMap<string, unknown>, 'has'>,
+): Array<IndexedDiagramLink<TLink>> {
+  return links
+    .map((link, graphIndex) => ({ graphIndex, link }))
+    .filter(({ link }) => nodeBounds.has(link.source) && nodeBounds.has(link.target));
+}
+
+export function getDiagramEdgeIdentityForFlowEdge(
+  links: readonly FlowchartLink[],
+  edgeId: string,
+): DiagramEdgeIdentity | null {
+  const edgeIndex = getFlowEdgeIndex(edgeId);
+  const diagramEdge = edgeIndex === null ? null : links[edgeIndex];
+
+  return edgeIndex === null || !diagramEdge
+    ? null
+    : getDiagramEdgeIdentity(diagramEdge, edgeIndex);
+}
diff --git a/apps/web/src/lib/diagram-layout.test.ts b/apps/web/src/lib/diagram-layout.test.ts
new file mode 100644
index 0000000..44b4404
--- /dev/null
+++ b/apps/web/src/lib/diagram-layout.test.ts
@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+import * as Y from 'yjs';
+import { readNodePositions, writeNodePositions } from './diagram-layout';
+
+describe('collaborative node position writes', () => {
+  it('merges a single position without deleting concurrent collaborator positions', () => {
+    const doc = new Y.Doc();
+    const positions = doc.getMap<{ x: number; y: number }>('nodePositions');
+    positions.set('A', { x: 1, y: 2 });
+    positions.set('B', { x: 3, y: 4 });
+
+    writeNodePositions(positions, { C: { x: 5, y: 6 } }, 'merge');
+
+    expect(readNodePositions(positions)).toEqual({
+      A: { x: 1, y: 2 },
+      B: { x: 3, y: 4 },
+      C: { x: 5, y: 6 },
+    });
+  });
+
+  it('only deletes missing positions for explicit replace/reset writes', () => {
+    const doc = new Y.Doc();
+    const positions = doc.getMap<{ x: number; y: number }>('nodePositions');
+    positions.set('A', { x: 1, y: 2 });
+    positions.set('B', { x: 3, y: 4 });
+
+    writeNodePositions(positions, { A: { x: 10, y: 20 } }, 'replace');
+
+    expect(readNodePositions(positions)).toEqual({
+      A: { x: 10, y: 20 },
+    });
+  });
+
+  it('removes only scoped deleted-node positions while preserving stale-local collaborator positions', () => {
+    const doc = new Y.Doc();
+    const positions = doc.getMap<{ x: number; y: number }>('nodePositions');
+    positions.set('deleted', { x: 1, y: 2 });
+    positions.set('local-existing', { x: 3, y: 4 });
+    positions.set('collaborator-existing', { x: 5, y: 6 });
+
+    writeNodePositions(positions, { deleted: { x: 1, y: 2 } }, 'remove');
+
+    expect(readNodePositions(positions)).toEqual({
+      'local-existing': { x: 3, y: 4 },
+      'collaborator-existing': { x: 5, y: 6 },
+    });
+  });
+});
diff --git a/apps/web/src/lib/diagram-layout.ts b/apps/web/src/lib/diagram-layout.ts
new file mode 100644
index 0000000..1dc4b0d
--- /dev/null
+++ b/apps/web/src/lib/diagram-layout.ts
@@ -0,0 +1,53 @@
+import * as Y from 'yjs';
+
+export type DiagramNodePosition = { x: number; y: number };
+export type DiagramNodePositions = Record<string, DiagramNodePosition>;
+export type NodePositionsSyncMode = 'merge' | 'remove' | 'replace';
+
+export function isNodePosition(value: unknown): value is DiagramNodePosition {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+
+  const position = value as Partial<DiagramNodePosition>;
+  return typeof position.x === 'number'
+    && Number.isFinite(position.x)
+    && typeof position.y === 'number'
+    && Number.isFinite(position.y);
+}
+
+export function readNodePositions(positionMap: Y.Map<DiagramNodePosition>): DiagramNodePositions {
+  const positions = Object.create(null) as DiagramNodePositions;
+  for (const [nodeId, position] of Array.from(positionMap.entries())) {
+    if (isNodePosition(position)) {
+      positions[nodeId] = { x: position.x, y: position.y };
+    }
+  }
+  return positions;
+}
+
+export function writeNodePositions(
+  positionMap: Y.Map<DiagramNodePosition>,
+  positions: DiagramNodePositions,
+  mode: NodePositionsSyncMode = 'merge',
+): void {
+  if (mode === 'remove') {
+    for (const nodeId of Object.keys(positions)) {
+      positionMap.delete(nodeId);
+    }
+
+    return;
+  }
+
+  if (mode === 'replace') {
+    for (const nodeId of Array.from(positionMap.keys())) {
+      if (!Object.prototype.hasOwnProperty.call(positions, nodeId)) {
+        positionMap.delete(nodeId);
+      }
+    }
+  }
+
+  for (const [nodeId, position] of Object.entries(positions)) {
+    positionMap.set(nodeId, { x: position.x, y: position.y });
+  }
+}
diff --git a/apps/web/src/lib/diagram-mutations.test.ts b/apps/web/src/lib/diagram-mutations.test.ts
new file mode 100644
index 0000000..4e22e28
--- /dev/null
+++ b/apps/web/src/lib/diagram-mutations.test.ts
@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest';
+import * as Y from 'yjs';
+import {
+  MutationQueue,
+  getDiagramEdgeIdentity,
+  observeMutationFailure,
+  parseFlowchartSnapshot,
+} from './diagram-mutations';
+
+function setText(yText: Y.Text, text: string) {
+  yText.delete(0, yText.length);
+  yText.insert(0, text);
+}
+
+describe('collaborative edge mutations', () => {
+  it('resolves a selected edge after concurrent inserts before the original index', async () => {
+    const doc = new Y.Doc();
+    const yText = doc.getText('mermaid');
+    setText(yText, 'flowchart LR\n  A --> B\n  B --> C\n');
+    const selected = getDiagramEdgeIdentity(parseFlowchartSnapshot(yText.toString()).links[1]!, 1);
+    setText(yText, 'flowchart LR\n  X --> Y\n  A --> B\n  B --> C\n');
+
+    const queue = new MutationQueue(yText);
+    const result = await queue.editEdgeLabelByIdentity(selected, 'safe');
+
+    expect(result.snapshot.links[2]?.source).toBe('B');
+    expect(result.snapshot.links[2]?.target).toBe('C');
+    expect(result.snapshot.links[2]?.text?.text).toBe('safe');
+    expect(result.snapshot.links[1]?.source).toBe('A');
+    expect(result.snapshot.links[1]?.target).toBe('B');
+  });
+
+  it('rejects stale edge edits instead of mutating the edge currently at the stale index', async () => {
+    const doc = new Y.Doc();
+    const yText = doc.getText('mermaid');
+    setText(yText, 'flowchart LR\n  A --> B\n  B --> C\n');
+    const selected = getDiagramEdgeIdentity(parseFlowchartSnapshot(yText.toString()).links[1]!, 1);
+    setText(yText, 'flowchart LR\n  A --> B\n  C --> D\n');
+
+    const queue = new MutationQueue(yText);
+    await expect(queue.removeEdgeByIdentity(selected)).rejects.toThrow('selected edge changed');
+
+    const links = parseFlowchartSnapshot(yText.toString()).links;
+    expect(links).toHaveLength(2);
+    expect(links[1]?.source).toBe('C');
+    expect(links[1]?.target).toBe('D');
+  });
+
+  it('reports a stale edge edit rejection to its event boundary', async () => {
+    const doc = new Y.Doc();
+    const yText = doc.getText('mermaid');
+    setText(yText, 'flowchart LR\n  A --> B\n  B --> C\n');
+    const selected = getDiagramEdgeIdentity(parseFlowchartSnapshot(yText.toString()).links[1]!, 1);
+    setText(yText, 'flowchart LR\n  A --> B\n  C --> D\n');
+
+    const queue = new MutationQueue(yText);
+    const failures: unknown[] = [];
+    observeMutationFailure(queue.editEdgeLabelByIdentity(selected, 'safe'), (error) => { failures.push(error); });
+    await new Promise<void>((resolve) => { setTimeout(resolve, 0); });
+
+    expect(failures).toHaveLength(1);
+    expect(failures[0]).toBeInstanceOf(Error);
+    expect((failures[0] as Error).message).toContain('selected edge changed');
+  });
+
+  it('uses the effective node id when a preferred id is claimed before a connected-node mutation runs', async () => {
+    const doc = new Y.Doc();
+    const yText = doc.getText('mermaid');
+    setText(yText, 'flowchart LR\n  A[Source]\n');
+
+    const queue = new MutationQueue(yText);
+    await queue.addNode('Claimed', { id: 'new_node' });
+    const result = await queue.addConnectedNode('A', 'New Node', { id: 'new_node' });
+
+    expect(result.nodeId).toBe('new_node_2');
+    expect(result.snapshot.nodeIds).toContain('new_node_2');
+    expect(result.snapshot.links).toEqual(expect.arrayContaining([
+      expect.objectContaining({ source: 'A', target: 'new_node_2' }),
+    ]));
+  });
+});
diff --git a/apps/web/src/lib/diagram-mutations.ts b/apps/web/src/lib/diagram-mutations.ts
index 9c8e3a5..ce1bc1f 100644
--- a/apps/web/src/lib/diagram-mutations.ts
+++ b/apps/web/src/lib/diagram-mutations.ts
@@ -24,7 +24,20 @@ export interface FlowchartSnapshot {
   subgraphs: FlowchartSubgraph[];
 }
 
+export interface DiagramEdgeIdentity {
+  id?: string;
+  index: number;
+  label?: string;
+  length: number;
+  source: string;
+  stroke: FlowchartLink['stroke'];
+  target: string;
+  type: FlowchartLinkType;
+}
+
 export interface MutationResult {
+  /** The node created by a node-creation mutation, when applicable. */
+  nodeId?: string;
   nextText: string;
   previousText: string;
   snapshot: FlowchartSnapshot;
@@ -51,6 +64,8 @@ export interface AddEdgeOptions {
   type?: FlowchartLinkType;
 }
 
+export interface AddConnectedNodeOptions extends AddNodeOptions, AddEdgeOptions {}
+
 export interface GroupNodesOptions {
   id?: string;
 }
@@ -79,6 +94,47 @@ export function parseFlowchartSnapshot(text: string): FlowchartSnapshot {
   return getFlowchartSnapshot(Flowchart.parse(text));
 }
 
+export function getDiagramEdgeIdentity(link: FlowchartLink, index: number): DiagramEdgeIdentity {
+  return {
+    id: link.id,
+    index,
+    label: link.text?.text,
+    length: link.length,
+    source: link.source,
+    stroke: link.stroke,
+    target: link.target,
+    type: link.type,
+  };
+}
+
+export function isSameDiagramEdge(link: FlowchartLink, identity: DiagramEdgeIdentity, options: { includeLabel?: boolean } = {}): boolean {
+  const includeLabel = options.includeLabel ?? true;
+  return link.id === identity.id
+    && link.source === identity.source
+    && link.target === identity.target
+    && (!includeLabel || link.text?.text === identity.label)
+    && link.stroke === identity.stroke
+    && link.type === identity.type
+    && link.length === identity.length;
+}
+
+export function resolveDiagramEdgeIndex(
+  links: readonly FlowchartLink[],
+  identity: DiagramEdgeIdentity,
+  options: { includeLabel?: boolean } = {},
+): number | null {
+  const indexedLink = links[identity.index];
+  if (indexedLink && isSameDiagramEdge(indexedLink, identity, options)) {
+    return identity.index;
+  }
+
+  const matches = links
+    .map((link, index) => ({ index, link }))
+    .filter(({ link }) => isSameDiagramEdge(link, identity, options));
+
+  return matches.length === 1 ? matches[0]?.index ?? null : null;
+}
+
 export function applyDiff(yText: Y.Text, newText: string, oldText = yText.toString()): void {
   const changes = diff(oldText, newText) as Array<[number, string]>;
   let offset = 0;
@@ -105,6 +161,14 @@ export function applyDiff(yText: Y.Text, newText: string, oldText = yText.toStri
   }
 }
 
+/**
+ * Observe a mutation started from an event handler so a rejected asynchronous
+ * mutation is reported instead of becoming an unhandled rejection.
+ */
+export function observeMutationFailure<T>(mutation: Promise<T>, onFailure: (error: unknown) => void): void {
+  void mutation.catch(onFailure);
+}
+
 export class MutationQueue {
   private readonly queue: QueuedMutation[] = [];
 
@@ -153,6 +217,30 @@ export class MutationQueue {
     }, { createIfEmpty: true, direction: options.direction });
   }
 
+  /**
+   * Add a node and its incoming edge in one queued mutation. Computing the
+   * effective node id from the same chart snapshot prevents a collaborator
+   * claiming the preferred id between a UI gesture and mutation execution.
+   */
+  async addConnectedNode(source: string, label = DEFAULT_NODE_LABEL, options: AddConnectedNodeOptions = {}): Promise<MutationResult> {
+    return this.enqueueResult((currentText) => {
+      const chart = getMutableFlowchart(currentText, { createIfEmpty: true, direction: options.direction });
+      const nodeId = ensureUniqueId(chart.nodeIds, options.id ?? createNodeId(label));
+      chart.addNode(nodeId, label, { shape: options.shape ?? DEFAULT_NODE_SHAPE });
+      chart.addLink(source, nodeId, {
+        text: options.label,
+        type: options.type ?? DEFAULT_LINK_TYPE,
+      });
+
+      return {
+        nextText: chart.render(),
+        nodeId,
+        previousText: currentText,
+        snapshot: getFlowchartSnapshot(chart),
+      };
+    });
+  }
+
   async removeNode(nodeId: string): Promise<MutationResult> {
     return this.enqueueFlowchartMutation((chart) => {
       chart.removeNode(nodeId, { reconnect: true });
@@ -174,6 +262,28 @@ export class MutationQueue {
     });
   }
 
+  async removeEdgeByIdentity(edge: DiagramEdgeIdentity): Promise<MutationResult> {
+    return this.enqueueFlowchartMutation((chart) => {
+      const index = resolveDiagramEdgeIndex(chart.links, edge);
+      if (index === null) {
+        throw new Error('Cannot delete edge because the selected edge changed.');
+      }
+
+      chart.removeLink(index);
+    });
+  }
+
+  async editEdgeLabelByIdentity(edge: DiagramEdgeIdentity, label?: string): Promise<MutationResult> {
+    return this.enqueueFlowchartMutation((chart) => {
+      const index = resolveDiagramEdgeIndex(chart.links, edge);
+      if (index === null) {
+        throw new Error('Cannot edit edge because the selected edge changed.');
+      }
+
+      chart.setLinkText(index, label);
+    });
+  }
+
   async groupNodes(nodeIds: string[], label = DEFAULT_SUBGRAPH_LABEL, options: GroupNodesOptions = {}): Promise<MutationResult> {
     return this.enqueueFlowchartMutation((chart) => {
       const subgraphId = ensureUniqueId(chart.subgraphs.map((subgraph) => subgraph.id), options.id ?? createSubgraphId(label));
diff --git a/e2e-validate.ts b/e2e-validate.ts
index 74a101c..463d68c 100644
--- a/e2e-validate.ts
+++ b/e2e-validate.ts
@@ -1,23 +1,107 @@
-import { chromium } from '@playwright/test';
+import { existsSync } from 'node:fs';
+import { chromium, type Locator, type Page } from '@playwright/test';
+
+interface SemanticState {
+  circleMarker: string | null;
+  crossMarker: string | null;
+  cylinderAria: string | null;
+  cylinderPseudoRadius: string;
+  dottedDasharray: string | null;
+  edgeOpacity: string | null;
+  edgePaths: number;
+  openMarker: string | null;
+  reactFlowEdges: number;
+  thickStrokeWidth: string | null;
+}
+
+interface ManualLayoutEdgeState {
+  mermaidEdgeOpacity: string | null;
+  reactFlowEdgeHeight: number;
+  reactFlowEdges: number;
+  reactFlowEdgeWidth: number;
+}
+
+function nodeTargetLocator(page: Page): Locator {
+  return page.locator('.mermaid-flow-node[role="button"], .diagram-node-target');
+}
+
+async function clickFirstNodeTarget(page: Page) {
+  await nodeTargetLocator(page).first().click({ timeout: 5000 });
+}
+
+async function clickFirstVisibleEdge(page: Page): Promise<boolean> {
+  const point = await page.evaluate(() => {
+    const edges = Array.from(document.querySelectorAll('.react-flow__edge'));
+
+    for (const edge of edges) {
+      const path = edge.querySelector('.react-flow__edge-interaction, .react-flow__edge-path') as SVGGeometryElement | null;
+      const matrix = path?.getScreenCTM();
+      const totalLength = path && 'getTotalLength' in path ? path.getTotalLength() : 0;
+
+      if (path && matrix && totalLength > 0) {
+        for (const ratio of [0.2, 0.35, 0.65, 0.8, 0.5]) {
+          const pathPoint = path.getPointAtLength(totalLength * ratio);
+          const x = (pathPoint.x * matrix.a) + (pathPoint.y * matrix.c) + matrix.e;
+          const y = (pathPoint.x * matrix.b) + (pathPoint.y * matrix.d) + matrix.f;
+          const hit = document.elementFromPoint(x, y);
+
+          if (hit?.closest('.react-flow__edge') === edge) {
+            return { x, y };
+          }
+        }
+      }
+
+      const bounds = edge.getBoundingClientRect();
+      if (bounds.width > 0 || bounds.height > 0) {
+        return { x: bounds.left + bounds.width / 2, y: bounds.top + bounds.height / 2 };
+      }
+    }
+
+    return null;
+  });
+
+  if (!point) {
+    return false;
+  }
+
+  await page.mouse.click(point.x, point.y);
+  return true;
+}
 
 async function validate() {
-  const browser = await chromium.launch({ headless: true });
+  const chromiumPath = process.env.PLAYWRIGHT_CHROMIUM_PATH ?? (existsSync('/usr/bin/chromium') ? '/usr/bin/chromium' : undefined);
+  const browser = await chromium.launch({ executablePath: chromiumPath, headless: true });
   const page = await browser.newPage({ viewport: { width: 1400, height: 900 } });
   const results: Array<{ test: string; pass: boolean }> = [];
+  const baseUrl = process.env.E2E_BASE_URL ?? 'http://localhost:3003';
+  const sessionName = `e2e-diag-${Date.now()}`;
 
   page.on('console', (msg) => {
     if (msg.type() === 'error') console.log(`[console.error] ${msg.text()}`);
   });
 
   console.log('1. Loading page...');
-  await page.goto('http://localhost:3003/s/e2e-diag01', { waitUntil: 'load', timeout: 30000 });
+  await page.goto(`${baseUrl}/s/${sessionName}`, { waitUntil: 'domcontentloaded', timeout: 30000 });
   await page.waitForSelector('.cm-content', { timeout: 15000 });
   await page.waitForTimeout(2000);
-
-  console.log('2. Typing flowchart...');
   const editor = page.locator('.cm-content');
+
+  console.log('2. Checking empty-canvas builder...');
+  const emptyBuilderVisible = await page.locator('button', { hasText: 'Add your first node' }).isVisible({ timeout: 5000 });
+  results.push({ test: 'empty canvas shows first-node builder', pass: emptyBuilderVisible });
+  console.log(`   Empty first-node builder visible: ${emptyBuilderVisible} — ${emptyBuilderVisible ? 'PASS' : 'FAIL'}`);
+  await page.locator('button', { hasText: 'Add your first node' }).click({ timeout: 5000 });
+  await page.waitForTimeout(3000);
+  const emptyBuilderEditorText = await editor.textContent();
+  const emptyBuilderCreated = (emptyBuilderEditorText?.includes('flowchart') ?? false)
+    && (emptyBuilderEditorText?.includes('New Node') ?? false)
+    && (await page.locator('.react-flow__node, .diagram-node-target').count()) > 0;
+  results.push({ test: 'empty canvas first node creates mermaid text', pass: emptyBuilderCreated });
+  console.log(`   Empty builder created Mermaid text: ${emptyBuilderCreated} — ${emptyBuilderCreated ? 'PASS' : 'FAIL'}`);
+
+  console.log('2b. Typing flowchart...');
   await editor.click();
-  await page.keyboard.press('Meta+a');
+  await page.keyboard.press('Control+A');
   await page.keyboard.type(`flowchart TD
     A[Start] --> B{Bug?}
     B -->|Yes| C[Fix]
@@ -31,7 +115,7 @@ async function validate() {
     if (!svg) return { error: 'no svg' };
 
     const nodes = svg.querySelectorAll('g.node');
-    const overlays = document.querySelectorAll('.diagram-node-target');
+    const overlays = document.querySelectorAll('.react-flow__node, .diagram-node-target');
 
     const matches: Array<{ nodeId: string; svgCenter: string; overlayCenter: string; offsetPx: number }> = [];
     nodes.forEach((n, i) => {
@@ -63,6 +147,110 @@ async function validate() {
   results.push({ test: 'overlay alignment', pass: alignPass });
   console.log(`   Max offset: ${maxOffset}px — ${alignPass ? 'PASS' : 'FAIL'}`);
 
+  // --- Test: canonical Mermaid edge semantics + React Flow shape fidelity ---
+  console.log('\n3b. Checking Mermaid semantics in React Flow mode...');
+  await editor.click();
+  await page.keyboard.press('Control+A');
+  await page.keyboard.type(`flowchart TD
+    A[(Database)] --> B{Decision}
+    B -.-> C[Retry]
+    B ==>|thick| D[Done]
+    A --o E((Circle))
+    E --x F[/Trap/]
+    C --- G[Open]`, { delay: 10 });
+  await page.waitForTimeout(3000);
+
+  const semanticState = await page.evaluate<SemanticState>(() => {
+    const svg = document.querySelector('.diagram-canvas-svg--reactflow svg') as SVGSVGElement | null;
+    const edgePath = svg?.querySelector('path.flowchart-link') as SVGPathElement | null;
+    const cylinder = document.querySelector('.mermaid-flow-node--cylinder') as HTMLElement | null;
+    const reactFlowEdges = Array.from(document.querySelectorAll('.react-flow__edge'));
+    const edgePaths = reactFlowEdges
+      .map((edge) => edge.querySelector('path.react-flow__edge-path') as SVGPathElement | null)
+      .filter((path): path is SVGPathElement => path !== null);
+    const circleEdge = edgePaths.find((path) => path.getAttribute('marker-end')?.includes('circle')) ?? null;
+    const crossEdge = edgePaths.find((path) => path.getAttribute('marker-end')?.includes('cross')) ?? null;
+    const openEdge = edgePaths.find((path) => {
+      const marker = path.getAttribute('marker-end') ?? '';
+      return marker.includes('type=arrow') && !marker.includes('arrowclosed');
+    }) ?? null;
+    const dottedEdge = edgePaths.find((path) => window.getComputedStyle(path).strokeDasharray !== 'none') ?? null;
+    const thickEdge = edgePaths.find((path) => Number.parseFloat(window.getComputedStyle(path).strokeWidth) >= 3) ?? null;
+
+    return {
+      circleMarker: circleEdge?.getAttribute('marker-end') ?? null,
+      crossMarker: crossEdge?.getAttribute('marker-end') ?? null,
+      cylinderAria: cylinder?.getAttribute('aria-label') ?? null,
+      cylinderPseudoRadius: cylinder ? window.getComputedStyle(cylinder, '::before').borderRadius : '',
+      dottedDasharray: dottedEdge ? window.getComputedStyle(dottedEdge).strokeDasharray : null,
+      edgeOpacity: edgePath ? window.getComputedStyle(edgePath).opacity : null,
+      edgePaths: svg?.querySelectorAll('path.flowchart-link').length ?? 0,
+      openMarker: openEdge?.getAttribute('marker-end') ?? null,
+      reactFlowEdges: reactFlowEdges.length,
+      thickStrokeWidth: thickEdge ? window.getComputedStyle(thickEdge).strokeWidth : null,
+    };
+  });
+  const edgeSemanticsPass = semanticState.edgePaths >= 6
+    && semanticState.edgeOpacity === '0'
+    && semanticState.reactFlowEdges >= 6
+    && !!semanticState.circleMarker
+    && !!semanticState.crossMarker
+    && !!semanticState.openMarker
+    && !!semanticState.dottedDasharray
+    && !!semanticState.thickStrokeWidth;
+  results.push({ test: 'reactflow edges preserve mermaid markers and stroke styles', pass: edgeSemanticsPass });
+  console.log(`   Mermaid edge paths: ${semanticState.edgePaths}, React Flow edges: ${semanticState.reactFlowEdges}, Mermaid opacity: ${semanticState.edgeOpacity} — ${edgeSemanticsPass ? 'PASS' : 'FAIL'}`);
+  console.log(`   Markers circle/cross/open: ${semanticState.circleMarker}/${semanticState.crossMarker}/${semanticState.openMarker}; dotted=${semanticState.dottedDasharray}; thick=${semanticState.thickStrokeWidth}`);
+
+  const shapeFidelityPass = typeof semanticState.cylinderAria === 'string'
+    && semanticState.cylinderAria.includes('cylinder:')
+    && semanticState.cylinderPseudoRadius.includes('%');
+  results.push({ test: 'reactflow cylinder shape fidelity', pass: shapeFidelityPass });
+  console.log(`   Cylinder aria: ${semanticState.cylinderAria}, pseudo radius: ${semanticState.cylinderPseudoRadius} — ${shapeFidelityPass ? 'PASS' : 'FAIL'}`);
+
+  await page.keyboard.press('Escape');
+  await editor.focus();
+  let keyboardFocusState: {
+    activeLabel: string | null;
+    activeRole: string | null;
+    focusedInner: boolean;
+    focusedWrapper: boolean;
+  } | null = null;
+  for (let index = 0; index < 24; index += 1) {
+    await page.keyboard.press('Tab');
+    await page.waitForTimeout(50);
+    const state = await page.evaluate(() => {
+      const activeElement = document.activeElement as HTMLElement | null;
+
+      return {
+        activeLabel: activeElement?.getAttribute('aria-label') ?? null,
+        activeRole: activeElement?.getAttribute('role') ?? null,
+        focusedInner: activeElement?.matches('.mermaid-flow-node[role="button"]') ?? false,
+        focusedWrapper: activeElement?.classList.contains('react-flow__node') ?? false,
+      };
+    });
+    if (state.activeLabel?.includes('Database')) {
+      keyboardFocusState = state;
+      break;
+    }
+  }
+  await page.keyboard.press('Enter');
+  await page.waitForTimeout(300);
+  const keyboardToolbarVisible = await page.locator('button[aria-label="Edit label"]').count();
+  const keyboardPass = keyboardToolbarVisible > 0
+    && keyboardFocusState?.focusedInner === true
+    && keyboardFocusState.focusedWrapper === false;
+  results.push({ test: 'reactflow node keyboard selection', pass: keyboardPass });
+  console.log(`   Keyboard focus ${keyboardFocusState?.activeRole}/${keyboardFocusState?.activeLabel}, toolbar opened: ${keyboardToolbarVisible > 0} — ${keyboardPass ? 'PASS' : 'FAIL'}`);
+
+  const sideHandleState = await page.evaluate(() => ({
+    leftSources: document.querySelectorAll('.mermaid-flow-handle--left.mermaid-flow-handle--source').length,
+    rightSources: document.querySelectorAll('.mermaid-flow-handle--right.mermaid-flow-handle--source').length,
+  }));
+  const sideHandlesPass = sideHandleState.leftSources > 0 && sideHandleState.rightSources > 0;
+  results.push({ test: 'reactflow exposes left/right drag-out handles', pass: sideHandlesPass });
+  console.log(`   Side handles L/R: ${sideHandleState.leftSources}/${sideHandleState.rightSources} — ${sideHandlesPass ? 'PASS' : 'FAIL'}`);
+
   // --- Test: fit-to-diagram ---
   console.log('\n4. Testing fit-to-diagram...');
   await page.locator('button[aria-label="Fit diagram"]').click();
@@ -75,8 +263,7 @@ async function validate() {
 
   // --- Test: node click / toolbar ---
   console.log('\n5. Testing node click...');
-  const firstOverlay = page.locator('.diagram-node-target').first();
-  await firstOverlay.click({ timeout: 5000 });
+  await clickFirstNodeTarget(page);
   await page.waitForTimeout(300);
   const toolbarVisible = await page.evaluate(() => {
     return document.querySelectorAll('button[aria-label="Edit label"]').length > 0;
@@ -85,17 +272,125 @@ async function validate() {
   console.log(`   Toolbar appeared: ${toolbarVisible} — ${toolbarVisible ? 'PASS' : 'FAIL'}`);
   await page.screenshot({ path: '/tmp/arielcharts-click.png' });
 
+  // --- Test: React Flow drag + reset layout ---
+  console.log('\n6. Testing React Flow drag/reset...');
+  const dragTarget = nodeTargetLocator(page).first();
+  const beforeDragEditorText = await editor.textContent();
+  const beforeDragZoomText = await page.locator('span').filter({ hasText: /^\d+%$/ }).first().textContent();
+  const beforeDrag = await dragTarget.boundingBox();
+  if (beforeDrag) {
+    await page.mouse.move(beforeDrag.x + beforeDrag.width / 2, beforeDrag.y + beforeDrag.height / 2);
+    await page.mouse.down();
+    await page.mouse.move(beforeDrag.x + beforeDrag.width / 2 + 260, beforeDrag.y + beforeDrag.height / 2 + 40, { steps: 16 });
+    await page.mouse.up();
+  }
+  await page.waitForTimeout(500);
+  const afterDrag = await dragTarget.boundingBox();
+  const afterDragEditorText = await editor.textContent();
+  const afterDragZoomText = await page.locator('span').filter({ hasText: /^\d+%$/ }).first().textContent();
+  const dragMoved = !!beforeDrag && !!afterDrag && Math.abs(afterDrag.x - beforeDrag.x) > 20;
+  const dragKeptMermaidText = afterDragEditorText === beforeDragEditorText;
+  const dragKeptZoom = afterDragZoomText === beforeDragZoomText;
+  results.push({ test: 'reactflow drag nodes', pass: dragMoved });
+  results.push({ test: 'reactflow drag keeps mermaid text canonical', pass: dragKeptMermaidText });
+  results.push({ test: 'reactflow drag does not change zoom', pass: dragKeptZoom });
+  console.log(`   Node moved: ${dragMoved} — ${dragMoved ? 'PASS' : 'FAIL'}`);
+  console.log(`   Mermaid text unchanged by drag: ${dragKeptMermaidText} — ${dragKeptMermaidText ? 'PASS' : 'FAIL'}`);
+  console.log(`   Zoom before/after drag: ${beforeDragZoomText}/${afterDragZoomText} — ${dragKeptZoom ? 'PASS' : 'FAIL'}`);
+
+  const manualEdgeState = await page.evaluate<ManualLayoutEdgeState>(() => {
+    const mermaidEdgePath = document.querySelector('.diagram-canvas-svg--reactflow path.flowchart-link') as SVGPathElement | null;
+    const reactFlowEdgePath = document.querySelector('.react-flow__edge path.react-flow__edge-path') as SVGPathElement | null;
+    const reactFlowEdgeBounds = reactFlowEdgePath?.getBoundingClientRect();
+
+    return {
+      mermaidEdgeOpacity: mermaidEdgePath ? window.getComputedStyle(mermaidEdgePath).opacity : null,
+      reactFlowEdgeHeight: Math.round(reactFlowEdgeBounds?.height ?? 0),
+      reactFlowEdges: document.querySelectorAll('.react-flow__edge').length,
+      reactFlowEdgeWidth: Math.round(reactFlowEdgeBounds?.width ?? 0),
+    };
+  });
+  const manualEdgesPass = manualEdgeState.mermaidEdgeOpacity === '0'
+    && manualEdgeState.reactFlowEdges > 0
+    && (manualEdgeState.reactFlowEdgeWidth > 0 || manualEdgeState.reactFlowEdgeHeight > 0);
+  results.push({ test: 'manual layout edges follow React Flow nodes', pass: manualEdgesPass });
+  console.log(`   Manual layout edges: RF=${manualEdgeState.reactFlowEdges}, Mermaid opacity=${manualEdgeState.mermaidEdgeOpacity}, bbox=${manualEdgeState.reactFlowEdgeWidth}x${manualEdgeState.reactFlowEdgeHeight} — ${manualEdgesPass ? 'PASS' : 'FAIL'}`);
+
+  const resetButton = page.locator('button[aria-label="Reset shared layout to Mermaid"]');
+  const hasResetButton = await resetButton.count() > 0;
+  let resetPass = false;
+  if (hasResetButton) {
+    await resetButton.click({ timeout: 5000 });
+    await page.waitForTimeout(500);
+    const afterReset = await dragTarget.boundingBox();
+    resetPass = !!beforeDrag && !!afterReset && Math.abs(afterReset.x - beforeDrag.x) <= 5;
+  }
+  results.push({ test: 'reactflow reset layout', pass: resetPass });
+  console.log(`   Node reset: ${resetPass} — ${resetPass ? 'PASS' : 'FAIL'}`);
+
+  // --- Test: fixed add-node toolbar ---
+  console.log('\n7. Testing fixed add-node toolbar...');
+  const toolbarCountBefore = await nodeTargetLocator(page).count();
+  await page.locator('input[aria-label="New node label"]').fill('UI Node');
+  await page.locator('select[aria-label="New node shape"]').selectOption('round');
+  await page.locator('button[aria-label="Add node to Mermaid text"]').click({ timeout: 5000 });
+  await page.waitForTimeout(3000);
+  const toolbarCountAfter = await nodeTargetLocator(page).count();
+  const toolbarEditorText = await page.locator('.cm-content').textContent();
+  const fixedToolbarPass = toolbarCountAfter > toolbarCountBefore && (toolbarEditorText?.includes('UI Node') ?? false);
+  results.push({ test: 'fixed add-node toolbar', pass: fixedToolbarPass });
+  console.log(`   Nodes before/after: ${toolbarCountBefore}/${toolbarCountAfter}`);
+  console.log(`   Editor contains "UI Node": ${toolbarEditorText?.includes('UI Node') ?? false}`);
+  console.log(`   Fixed toolbar added node: ${fixedToolbarPass} — ${fixedToolbarPass ? 'PASS' : 'FAIL'}`);
+
+  // --- Test: node label edit syncs to Mermaid text ---
+  console.log('\n8. Testing node label edit sync...');
+  await clickFirstNodeTarget(page);
+  await page.locator('button[aria-label="Edit label"]').click({ timeout: 5000 });
+  await page.locator('input[placeholder="node label"]').fill('Launch');
+  await page.keyboard.press('Enter');
+  await page.waitForTimeout(2000);
+  const editedText = await page.locator('.cm-content').textContent();
+  const editSyncPass = editedText?.includes('Launch') ?? false;
+  results.push({ test: 'node label edit sync', pass: editSyncPass });
+  console.log(`   Editor contains edited label: ${editSyncPass} — ${editSyncPass ? 'PASS' : 'FAIL'}`);
+
+  // --- Test: edge select/edit/delete ---
+  console.log('\n8b. Testing edge select/edit/delete...');
+  const edgeCountBeforeEdit = await page.locator('.react-flow__edge').count();
+  const edgeClicked = await clickFirstVisibleEdge(page);
+  await page.waitForTimeout(300);
+  const edgeToolbarVisible = edgeClicked && await page.locator('div[aria-label="Selected edge toolbar"]').isVisible({ timeout: 5000 });
+  if (edgeToolbarVisible) {
+    await page.locator('button[aria-label="Edit edge label"]').click({ timeout: 5000 });
+    await page.locator('input[aria-label="Edge label"]').fill('Critical');
+    await page.keyboard.press('Enter');
+    await page.waitForTimeout(2000);
+  }
+  const edgeLabelText = await page.locator('.cm-content').textContent();
+  const edgeLabelPass = edgeToolbarVisible && (edgeLabelText?.includes('Critical') ?? false);
+  results.push({ test: 'edge label edit sync', pass: edgeLabelPass });
+  console.log(`   Edge toolbar visible: ${edgeToolbarVisible}, editor contains Critical: ${edgeLabelText?.includes('Critical') ?? false} — ${edgeLabelPass ? 'PASS' : 'FAIL'}`);
+
+  await page.locator('button[aria-label="Delete selected edge"]').click({ timeout: 5000 });
+  await page.waitForTimeout(2000);
+  const edgeCountAfterDelete = await page.locator('.react-flow__edge').count();
+  const edgeDeletePass = edgeCountAfterDelete < edgeCountBeforeEdit;
+  results.push({ test: 'edge click delete', pass: edgeDeletePass });
+  console.log(`   Edges before/after delete: ${edgeCountBeforeEdit}/${edgeCountAfterDelete} — ${edgeDeletePass ? 'PASS' : 'FAIL'}`);
+
   // --- Test: add node ---
-  console.log('\n6. Testing add node...');
-  const nodeCountBefore = await page.locator('.diagram-node-target').count();
+  console.log('\n9. Testing add node...');
+  const nodeCountBefore = await nodeTargetLocator(page).count();
   console.log(`   Nodes before: ${nodeCountBefore}`);
 
-  // Click "Add node" button on the toolbar
+  // Click "Add node" button on the node toolbar
+  await clickFirstNodeTarget(page);
   await page.locator('button[aria-label="Add node"]').click({ timeout: 5000 });
   // Wait for mermaid to re-render with the new node
   await page.waitForTimeout(3000);
 
-  const nodeCountAfter = await page.locator('.diagram-node-target').count();
+  const nodeCountAfter = await nodeTargetLocator(page).count();
   console.log(`   Nodes after: ${nodeCountAfter}`);
 
   // Verify the editor text now contains the new node
@@ -108,14 +403,39 @@ async function validate() {
   console.log(`   ${addNodePass ? 'PASS' : 'FAIL'}`);
   await page.screenshot({ path: '/tmp/arielcharts-addnode.png' });
 
+  // --- Test: drag connector to create connected node ---
+  console.log('\n9b. Testing drag-out connected node creation...');
+  const connectedNodeCountBefore = await page.locator('.react-flow__node').count();
+  const connectedEdgeCountBefore = await page.locator('.react-flow__edge').count();
+  const sourceHandle = page.locator('.mermaid-flow-handle--right.mermaid-flow-handle--source').first();
+  const sourceBox = await sourceHandle.boundingBox();
+  if (sourceBox) {
+    const startX = sourceBox.x + sourceBox.width / 2;
+    const startY = sourceBox.y + sourceBox.height / 2;
+    await page.mouse.move(startX, startY);
+    await page.mouse.down();
+    await page.mouse.move(startX + 220, startY + 120, { steps: 12 });
+    await page.mouse.up();
+  }
+  await page.waitForTimeout(3000);
+  const connectedNodeCountAfter = await page.locator('.react-flow__node').count();
+  const connectedEdgeCountAfter = await page.locator('.react-flow__edge').count();
+  const dragOutPass = !!sourceBox
+    && connectedNodeCountAfter > connectedNodeCountBefore
+    && connectedEdgeCountAfter > connectedEdgeCountBefore;
+  results.push({ test: 'drag connector creates connected ghost node', pass: dragOutPass });
+  console.log(`   Nodes before/after: ${connectedNodeCountBefore}/${connectedNodeCountAfter}`);
+  console.log(`   Edges before/after: ${connectedEdgeCountBefore}/${connectedEdgeCountAfter}`);
+  console.log(`   Drag-out connected node: ${dragOutPass ? 'PASS' : 'FAIL'}`);
+
   // --- Test: new node overlay alignment ---
-  console.log('\n7. Checking new node overlay alignment...');
+  console.log('\n10. Checking new node overlay alignment...');
   const newAlignment = await page.evaluate(() => {
     const svg = document.querySelector('.diagram-canvas-svg svg') as SVGSVGElement | null;
     if (!svg) return { error: 'no svg' };
 
     const nodes = svg.querySelectorAll('g.node');
-    const overlays = document.querySelectorAll('.diagram-node-target');
+    const overlays = document.querySelectorAll('.react-flow__node, .diagram-node-target');
 
     const matches: Array<{ nodeId: string; offsetPx: number }> = [];
     nodes.forEach((n, i) => {
@@ -154,6 +474,13 @@ async function validate() {
   console.log(allPassed ? 'ALL TESTS PASSED' : 'SOME TESTS FAILED');
 
   await browser.close();
+
+  if (!allPassed) {
+    process.exit(1);
+  }
 }
 
-validate().catch(console.error);
+validate().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 747430c..2f1ed9c 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -72,6 +72,9 @@ importers:
       '@codemirror/view':
         specifier: 6.38.6
         version: 6.38.6
+      '@xyflow/react':
+        specifier: ^12.11.0
+        version: 12.11.0(@types/react-dom@19.1.9(@types/react@19.1.13))(@types/react@19.1.13)(react-dom@19.1.1(react@19.1.1))(react@19.1.1)
       codemirror:
         specifier: 6.0.2
         version: 6.0.2
@@ -1026,6 +1029,22 @@ packages:
   '@vitest/utils@3.2.4':
     resolution: {integrity: sha512-fB2V0JFrQSMsCo9HiSq3Ezpdv4iYaXRG1Sx8edX3MwxfyNn83mKiGzOcH+Fkxt4MHxr3y42fQi1oeAInqgX2QA==}
 
+  '@xyflow/react@12.11.0':
+    resolution: {integrity: sha512-na4IO33FSs2OS72hASgZDmTYwFAkef7Z74uBUVrong3ARmQQHfnRUVaCFn1kTt5LbS6pK03TbYjCPGLjLFfziA==}
+    peerDependencies:
+      '@types/react': '>=17'
+      '@types/react-dom': '>=17'
+      react: '>=17'
+      react-dom: '>=17'
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@xyflow/system@0.0.77':
+    resolution: {integrity: sha512-qCDCMCQAAgUu8yHnhloHG9F5mwPX5E+Wl8McpYIOPSSXfzFJJoZcwOcsDiAjitVKIg2de1WmJbCHfpcvxprsgg==}
+
   abstract-level@3.1.1:
     resolution: {integrity: sha512-CW2gKbJFTuX1feMvOrvsVMmijAOgI9kg2Ie9Dq3gOcMt/dVVoVmqNlLcEUCT13NxHFMEajcUcVBIplbyDroDiw==}
     engines: {node: '>=18'}
@@ -1123,6 +1142,9 @@ packages:
   chevrotain@11.0.3:
     resolution: {integrity: sha512-ci2iJH6LeIkvP9eJW6gpueU8cnZhv85ELY8w8WiFtNjMHA5ad6pQLaJo9mEly/9qUyCpvqX8/POVUTf18/HFdw==}
 
+  classcat@5.0.5:
+    resolution: {integrity: sha512-JhZUT7JFcQy/EzW605k/ktHtncoo9vnyW/2GspNYwFlN1C/WmjuV/xtS04e9SOkL2sTdw0VAZ2UGCcQ9lR6p6w==}
+
   classic-level@3.0.0:
     resolution: {integrity: sha512-yGy8j8LjPbN0Bh3+ygmyYvrmskVita92pD/zCoalfcC9XxZj6iDtZTAnz+ot7GG8p9KLTG+MZ84tSA4AhkgVZQ==}
     engines: {node: '>=18'}
@@ -2065,6 +2087,11 @@ packages:
     resolution: {integrity: sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==}
     engines: {node: '>= 0.8'}
 
+  use-sync-external-store@1.6.0:
+    resolution: {integrity: sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
   util-deprecate@1.0.2:
     resolution: {integrity: sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==}
 
@@ -2249,6 +2276,21 @@ packages:
   zod@4.3.6:
     resolution: {integrity: sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==}
 
+  zustand@4.5.7:
+    resolution: {integrity: sha512-CHOUy7mu3lbD6o6LJLfllpjkzhHXSBlX8B9+qPddUsIfeF5S/UZ5q0kmCsnRqT1UHFQZchNFDDzMbQsuesHWlw==}
+    engines: {node: '>=12.7.0'}
+    peerDependencies:
+      '@types/react': '>=16.8'
+      immer: '>=9.0.6'
+      react: '>=16.8'
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      immer:
+        optional: true
+      react:
+        optional: true
+
 snapshots:
 
   '@antfu/install-pkg@1.1.0':
@@ -2992,6 +3034,31 @@ snapshots:
       loupe: 3.2.1
       tinyrainbow: 2.0.0
 
+  '@xyflow/react@12.11.0(@types/react-dom@19.1.9(@types/react@19.1.13))(@types/react@19.1.13)(react-dom@19.1.1(react@19.1.1))(react@19.1.1)':
+    dependencies:
+      '@xyflow/system': 0.0.77
+      classcat: 5.0.5
+      react: 19.1.1
+      react-dom: 19.1.1(react@19.1.1)
+      zustand: 4.5.7(@types/react@19.1.13)(react@19.1.1)
+    optionalDependencies:
+      '@types/react': 19.1.13
+      '@types/react-dom': 19.1.9(@types/react@19.1.13)
+    transitivePeerDependencies:
+      - immer
+
+  '@xyflow/system@0.0.77':
+    dependencies:
+      '@types/d3-drag': 3.0.7
+      '@types/d3-interpolate': 3.0.4
+      '@types/d3-selection': 3.0.11
+      '@types/d3-transition': 3.0.9
+      '@types/d3-zoom': 3.0.8
+      d3-drag: 3.0.0
+      d3-interpolate: 3.0.1
+      d3-selection: 3.0.0
+      d3-zoom: 3.0.0
+
   abstract-level@3.1.1:
     dependencies:
       buffer: 6.0.3
@@ -3115,6 +3182,8 @@ snapshots:
       '@chevrotain/utils': 11.0.3
       lodash-es: 4.17.21
 
+  classcat@5.0.5: {}
+
   classic-level@3.0.0:
     dependencies:
       abstract-level: 3.1.1
@@ -4181,6 +4250,10 @@ snapshots:
 
   unpipe@1.0.0: {}
 
+  use-sync-external-store@1.6.0(react@19.1.1):
+    dependencies:
+      react: 19.1.1
+
   util-deprecate@1.0.2:
     optional: true
 
@@ -4344,3 +4417,10 @@ snapshots:
       zod: 4.3.6
 
   zod@4.3.6: {}
+
+  zustand@4.5.7(@types/react@19.1.13)(react@19.1.1):
+    dependencies:
+      use-sync-external-store: 1.6.0(react@19.1.1)
+    optionalDependencies:
+      '@types/react': 19.1.13
+      react: 19.1.1