@vanduo-oss/vd3-flowchart 1.2.0 → 1.4.0

package/dist/index.js

@@ -185,6 +185,134 @@ function computeLayout(documentData, mode = "tree", options = {}) {
 }
 var LAYOUT_MODES = ["tree", "radial", "grid"];
 
+// src/mindmap.js
+var DIRECTION_PORTS = { right: "right", left: "left", down: "bottom", up: "top" };
+var PORT_DIRECTIONS = { right: "right", left: "left", bottom: "down", top: "up" };
+var OPPOSITE_DIRECTIONS = { right: "left", left: "right", down: "up", up: "down" };
+var DIRECTION_VECTORS = {
+  right: { x: 1, y: 0 },
+  left: { x: -1, y: 0 },
+  down: { x: 0, y: 1 },
+  up: { x: 0, y: -1 }
+};
+var BRANCH_GAP = 72;
+var SIBLING_GAP = 24;
+var COLLISION_GAP = 12;
+var COLLISION_STEP = 12;
+var MAX_COLLISION_STEPS = 400;
+var BRANCH_RING_STEP = 48;
+var MAX_BRANCH_RINGS = 8;
+var NAVIGATION_CONE = Math.tan(Math.PI / 3);
+function centerOf(node) {
+  return { x: node.x + node.width / 2, y: node.y + node.height / 2 };
+}
+function oppositeDirection(direction) {
+  return OPPOSITE_DIRECTIONS[direction] || "left";
+}
+function findSpatialNeighbor(nodes, fromNode, direction) {
+  const vector = DIRECTION_VECTORS[direction];
+  if (!vector || !fromNode) return null;
+  const origin = centerOf(fromNode);
+  let bestCone = null;
+  let bestPlane = null;
+  nodes.forEach((node) => {
+    if (node.id === fromNode.id) return;
+    const center = centerOf(node);
+    const dx = center.x - origin.x;
+    const dy = center.y - origin.y;
+    const along = dx * vector.x + dy * vector.y;
+    if (along <= 0) return;
+    const across = Math.abs(dx * vector.y - dy * vector.x);
+    const score = along + across * 2;
+    if (across <= along * NAVIGATION_CONE && (!bestCone || score < bestCone.score)) {
+      bestCone = { node, score };
+    }
+    if (!bestPlane || score < bestPlane.score) bestPlane = { node, score };
+  });
+  return (bestCone || bestPlane)?.node ?? null;
+}
+function findNearestNode(nodes, point) {
+  let best = null;
+  nodes.forEach((node) => {
+    const center = centerOf(node);
+    const distance = Math.hypot(center.x - point.x, center.y - point.y);
+    if (!best || distance < best.distance) best = { node, distance };
+  });
+  return best?.node ?? null;
+}
+function overlapsAny(rect, nodes) {
+  return nodes.some(
+    (node) => rect.x < node.x + node.width + COLLISION_GAP && rect.x + rect.width + COLLISION_GAP > node.x && rect.y < node.y + node.height + COLLISION_GAP && rect.y + rect.height + COLLISION_GAP > node.y
+  );
+}
+function placeBranchNode({
+  nodes,
+  parent,
+  siblings = [],
+  direction,
+  size,
+  anchor = null,
+  before = false
+}) {
+  const horizontal = direction === "right" || direction === "left";
+  const cross = horizontal ? "y" : "x";
+  const crossSize = horizontal ? "height" : "width";
+  const lastSibling = siblings.reduce(
+    (last, node) => !last || node[cross] + node[crossSize] > last[cross] + last[crossSize] ? node : last,
+    null
+  );
+  const reference = anchor || lastSibling;
+  const rect = { x: 0, y: 0, width: size.width, height: size.height };
+  if (reference) {
+    if (direction === "right") rect.x = reference.x;
+    if (direction === "left") rect.x = reference.x + reference.width - size.width;
+    if (direction === "down") rect.y = reference.y;
+    if (direction === "up") rect.y = reference.y + reference.height - size.height;
+    rect[cross] = before ? reference[cross] - SIBLING_GAP - size[crossSize] : reference[cross] + reference[crossSize] + SIBLING_GAP;
+  } else {
+    if (direction === "right") rect.x = parent.x + parent.width + BRANCH_GAP;
+    if (direction === "left") rect.x = parent.x - BRANCH_GAP - size.width;
+    if (direction === "down") rect.y = parent.y + parent.height + BRANCH_GAP;
+    if (direction === "up") rect.y = parent.y - BRANCH_GAP - size.height;
+    rect[cross] = parent[cross] + parent[crossSize] / 2 - size[crossSize] / 2;
+  }
+  const crossSign = reference ? before ? -1 : 1 : 0;
+  const result = nearestFreeSlot(
+    rect,
+    nodes,
+    cross,
+    horizontal ? "x" : "y",
+    DIRECTION_VECTORS[direction],
+    crossSign
+  );
+  return { x: Math.round(result.x * 100) / 100, y: Math.round(result.y * 100) / 100 };
+}
+function crossOffsetAt(index, crossSign) {
+  if (crossSign) return crossSign * COLLISION_STEP * index;
+  return COLLISION_STEP * Math.ceil(index / 2) * (index % 2 ? 1 : -1);
+}
+function nearestFreeSlot(rect, nodes, cross, main, vector, crossSign) {
+  const origin = { ...rect };
+  const outward = vector.x + vector.y;
+  let best = null;
+  for (let ring = 0; ring <= MAX_BRANCH_RINGS; ring += 1) {
+    const mainOffset = ring * BRANCH_RING_STEP;
+    if (best && mainOffset >= best.cost) break;
+    const candidate = { ...origin, [main]: origin[main] + outward * mainOffset };
+    for (let index = 0; index <= MAX_COLLISION_STEPS; index += 1) {
+      const crossOffset = crossOffsetAt(index, crossSign);
+      const cost = Math.hypot(mainOffset, crossOffset);
+      if (best && cost >= best.cost) break;
+      candidate[cross] = origin[cross] + crossOffset;
+      if (!overlapsAny(candidate, nodes)) {
+        best = { rect: { ...candidate }, cost };
+        break;
+      }
+    }
+  }
+  return best ? best.rect : origin;
+}
+
 // src/core.js
 var SVG_NS = "http://www.w3.org/2000/svg";
 var TOOLBAR_ICON_PATHS = {
@@ -194,6 +322,7 @@ var TOOLBAR_ICON_PATHS = {
   "fit-view": "M216,48V88a8,8,0,0,1-16,0V67.31l-42.34,42.35a8,8,0,0,1-11.32-11.32L188.69,56H168a8,8,0,0,1,0-16h40A8,8,0,0,1,216,48ZM98.34,146.34,56,188.69V168a8,8,0,0,0-16,0v40a8,8,0,0,0,8,8H88a8,8,0,0,0,0-16H67.31l42.35-42.34a8,8,0,0,0-11.32-11.32Zm11.32-36.68L67.31,56H88a8,8,0,0,0,0-16H48a8,8,0,0,0-8,8V88a8,8,0,0,0,16,0V67.31l42.34,42.35a8,8,0,0,0,11.32-11.32ZM208,160a8,8,0,0,0-8,8v20.69l-42.34-42.35a8,8,0,0,0-11.32,11.32L188.69,200H168a8,8,0,0,0,0,16h40a8,8,0,0,0,8-8V168A8,8,0,0,0,208,160Z",
   undo: "M224,128a96,96,0,0,1-94.71,96H128A95.38,95.38,0,0,1,62.1,197.8a8,8,0,0,1,11-11.63A80,80,0,1,0,71.43,71.39a3.07,3.07,0,0,1-.26.25L44.59,96H72a8,8,0,0,1,0,16H24a8,8,0,0,1-8-8V56a8,8,0,0,1,16,0V85.8L60.25,60A96,96,0,0,1,224,128Z",
   redo: "M240,56v48a8,8,0,0,1-8,8H184a8,8,0,0,1,0-16H211.4L184.81,71.64l-.25-.24a80,80,0,1,0-1.67,114.78,8,8,0,0,1,11,11.63A95.44,95.44,0,0,1,128,224h-1.32A96,96,0,1,1,195.75,60L224,85.8V56a8,8,0,1,1,16,0Z",
+  minimap: "M228.92,49.69a8,8,0,0,0-6.86-1.45L160.93,63.52,99.58,32.84a8,8,0,0,0-5.52-.6l-64,16A8,8,0,0,0,24,56V200a8,8,0,0,0,9.94,7.76l61.13-15.28,61.35,30.68A8.15,8.15,0,0,0,160,224a8,8,0,0,0,1.94-.24l64-16A8,8,0,0,0,232,200V56A8,8,0,0,0,228.92,49.69ZM104,52.94l48,24V203.06l-48-24ZM40,62.25l48-12v127.5l-48,12Zm176,131.5-48,12V78.25l48-12Z",
   clear: "M216,48H176V40a24,24,0,0,0-24-24H104A24,24,0,0,0,80,40v8H40a8,8,0,0,0,0,16h8V208a16,16,0,0,0,16,16H192a16,16,0,0,0,16-16V64h8a8,8,0,0,0,0-16ZM96,40a8,8,0,0,1,8-8h48a8,8,0,0,1,8,8v8H96Zm96,168H64V64H192ZM112,104v64a8,8,0,0,1-16,0V104a8,8,0,0,1,16,0Zm48,0v64a8,8,0,0,1-16,0V104a8,8,0,0,1,16,0Z"
 };
 var TOOLBAR_ACTIONS = [
@@ -245,20 +374,32 @@ var DEFAULT_EDGE_STROKE_WIDTH = 2.25;
 var MIN_EDGE_STROKE_WIDTH = 1.25;
 var MAX_EDGE_STROKE_WIDTH = 6;
 var CONNECTION_PORT_RADIUS = 6;
+var PORT_HANDLE_OFFSET = 12;
 var CONNECTION_PORT_HIT_RADIUS = 14;
+var PORT_CLICK_SLOP = 4;
+var RESIZE_HANDLE_SIZE = 9;
+var SELECTION_OUTSET = 4;
+var GUIDE_SNAP_DISTANCE = 6;
+var GUIDE_OVERHANG = 12;
+var COLLAPSE_TOGGLE_OFFSET = 36;
+var MINIMAP_WIDTH = 180;
+var MINIMAP_HEIGHT = 120;
+var MINIMAP_MIN_CANVAS_WIDTH = 480;
+var SELECTION_BOX_TYPES = /* @__PURE__ */ new Set(["circle", "diamond", "label"]);
 var RECONNECT_ENDPOINT_RADIUS = 7;
 var RECONNECT_ENDPOINT_HIT_RADIUS = 12;
 var EDGE_HIT_STROKE_MIN = 16;
 var CONNECTION_SNAP_PADDING = 36;
 var CONNECTION_HYSTERESIS = 16;
 var CONNECTION_CENTER_LOCK_RADIUS = 18;
-var RESIZE_PORT_GAP = 34;
+var RESIZE_PORT_GAP = 28;
 var EDGE_STROKE_PRESETS = [
   { id: "thin", label: "Thin", width: 1.75 },
   { id: "medium", label: "Medium", width: DEFAULT_EDGE_STROKE_WIDTH },
   { id: "bold", label: "Bold", width: 3.5 }
 ];
-var VD_FLOWCHART_VERSION = "1.2.0";
+var VD_FLOWCHART_VERSION = "1.4.0";
+var FLOWCHART_DOCUMENT_VERSION = "1.3.0";
 var FLOWCHART_NODE_TYPES = [
   "rounded-rect",
   "rect",
@@ -271,7 +412,65 @@ var FLOWCHART_NODE_TYPES = [
 var FLOWCHART_PORTS = ["top", "right", "bottom", "left"];
 var FLOWCHART_EDGE_MARKERS = ["none", "arrow", "dot"];
 var FLOWCHART_EDGE_ROUTES = ["curve", "straight", "orthogonal"];
-var COALESCING_REASONS = /* @__PURE__ */ new Set(["node:update", "edge:update"]);
+var FLOWCHART_KEYBOARD_SHORTCUTS = ["mindmap", "basic"];
+function normalizeKeyboardShortcuts(value) {
+  return value === "basic" ? "basic" : "mindmap";
+}
+var ARROW_DIRECTIONS = {
+  ArrowRight: "right",
+  ArrowLeft: "left",
+  ArrowDown: "down",
+  ArrowUp: "up"
+};
+function getShortcutRows(mode, readonly) {
+  const navigation = [
+    ["Arrow keys", "Select the nearest node in that direction"],
+    ["Shift + Arrow", "Select a connection on that side (repeat to cycle)"],
+    ["Shift + click, Shift + drag", "Add nodes to the selection, or select with a box"],
+    ["Cmd/Ctrl + A", "Select all nodes"]
+  ];
+  const view = [
+    ["Cmd/Ctrl + = or -", "Zoom in or out"],
+    ["Cmd/Ctrl + 0", "Zoom to 100%"],
+    ["Shift + 1", "Fit the diagram to the view"]
+  ];
+  const help = [["?", "Show or hide this list"]];
+  if (readonly) {
+    return [...navigation, ...view, ...help, ["Tab", "Leave the canvas"]];
+  }
+  const mindmap = mode === "mindmap" ? [
+    ["Tab", "Add a child node"],
+    ["Enter", "Add a sibling below (Shift + Enter: above)"],
+    ["F2, Space, or type", "Edit the label"],
+    ["Enter while editing", "Save the label (Shift + Enter: new line)"],
+    ["Tab while editing", "Save and add a child"]
+  ] : [
+    ["Enter or F2", "Edit the label"],
+    ["Cmd/Ctrl + Enter", "Save the label"]
+  ];
+  return [
+    ...navigation,
+    ...mindmap,
+    [
+      mode === "mindmap" ? "Enter, F2, or type on a connection" : "Enter or F2 on a connection",
+      "Edit the connection label"
+    ],
+    ["Cmd/Ctrl + /", "Collapse or expand the branch"],
+    ["Alt + Arrow", "Nudge the node (add Shift for 1 px)"],
+    ["Delete or Backspace", "Delete the selection"],
+    ["Cmd/Ctrl + D", "Duplicate the node"],
+    ["Cmd/Ctrl + Z, Shift + Cmd/Ctrl + Z", "Undo, redo"],
+    ["Cmd/Ctrl + C, X, V", "Copy, cut, paste"],
+    ...view,
+    ["Esc", "Cancel editing, then the tool, then deselect"],
+    [
+      mode === "mindmap" ? "Shift + Tab, or Esc then Tab" : "Tab or Shift + Tab",
+      "Leave the canvas"
+    ],
+    ...help
+  ];
+}
+var COALESCING_REASONS = /* @__PURE__ */ new Set(["node:update", "edge:update", "node:nudge"]);
 var DEFAULT_EDGE_ROUTE = "curve";
 var ORTHOGONAL_STUB_LENGTH = 32;
 var ORTHOGONAL_CORNER_RADIUS = 12;
@@ -445,7 +644,7 @@ function normalizeViewport(viewport) {
 function normalizeNode(rawNode, index, usedIds) {
   const type = normalizeNodeType(rawNode?.type);
   const spec = getNodeSpec(type);
-  return {
+  const node = {
     id: ensureUniqueId(rawNode?.id, "node", usedIds),
     type,
     x: toFiniteNumber(rawNode?.x, index * 28),
@@ -455,6 +654,37 @@ function normalizeNode(rawNode, index, usedIds) {
     text: rawNode?.text == null ? spec.text : String(rawNode.text),
     data: isPlainObject(rawNode?.data) ? deepClone(rawNode.data) : {}
   };
+  if (rawNode?.collapsed === true) node.collapsed = true;
+  return node;
+}
+function computeHiddenNodeIds(nodes, edges) {
+  const collapsed = new Set(nodes.filter((node) => node.collapsed).map((node) => node.id));
+  if (!collapsed.size) return /* @__PURE__ */ new Set();
+  const outgoing = new Map(nodes.map((node) => [node.id, []]));
+  edges.forEach((edge) => {
+    if (edge.from.nodeId === edge.to.nodeId) return;
+    outgoing.get(edge.from.nodeId)?.push(edge.to.nodeId);
+  });
+  const candidates = /* @__PURE__ */ new Set();
+  collapsed.forEach((rootId) => {
+    const queue2 = [...outgoing.get(rootId) || []];
+    for (let index = 0; index < queue2.length; index += 1) {
+      const id = queue2[index];
+      if (id === rootId || candidates.has(id)) continue;
+      candidates.add(id);
+      queue2.push(...outgoing.get(id) || []);
+    }
+  });
+  const queue = nodes.filter((node) => !candidates.has(node.id) && !collapsed.has(node.id)).map((node) => node.id);
+  for (let index = 0; index < queue.length; index += 1) {
+    const id = queue[index];
+    (outgoing.get(id) || []).forEach((childId) => {
+      if (!candidates.has(childId)) return;
+      candidates.delete(childId);
+      if (!collapsed.has(childId)) queue.push(childId);
+    });
+  }
+  return candidates;
 }
 function normalizeEndpoint(rawEndpoint, fallbackPort) {
   return {
@@ -495,17 +725,45 @@ function normalizeEdge(rawEdge, index, nodeIds, usedIds) {
   syncEdgeKind(edge);
   return edge;
 }
+function parseDocumentVersion(value) {
+  const raw = typeof value === "number" && Number.isFinite(value) ? String(value) : typeof value === "string" ? value.trim() : "";
+  const match = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(raw);
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2] ?? 0),
+    patch: Number(match[3] ?? 0)
+  };
+}
+function isSupportedDocumentVersion(value) {
+  const parsed = parseDocumentVersion(value);
+  const max = parseDocumentVersion(FLOWCHART_DOCUMENT_VERSION);
+  if (!parsed || !max || parsed.major !== max.major) return false;
+  if (parsed.minor > max.minor) return false;
+  if (parsed.minor === max.minor && parsed.patch > max.patch) return false;
+  return true;
+}
 function normalizeDocument(input) {
   let source = input;
   if (typeof source === "string") {
     try {
       source = JSON.parse(source);
     } catch {
-      source = {};
+      throw new TypeError("Invalid flowchart JSON. The current document was not changed.");
     }
   }
   if (!isPlainObject(source)) {
-    source = {};
+    throw new TypeError("A flowchart document must be an object.");
+  }
+  if (source.version !== void 0 && !isSupportedDocumentVersion(source.version)) {
+    throw new RangeError(
+      `Unsupported flowchart document version: ${String(source.version)}. Supported through ${FLOWCHART_DOCUMENT_VERSION}.`
+    );
+  }
+  for (const key of ["nodes", "edges"]) {
+    if (source[key] !== void 0 && !Array.isArray(source[key])) {
+      throw new TypeError(`Flowchart ${key} must be an array.`);
+    }
   }
   const usedNodeIds = /* @__PURE__ */ new Set();
   const nodes = (Array.isArray(source.nodes) ? source.nodes : []).slice(0, MAX_NODES).map((node, index) => normalizeNode(node, index, usedNodeIds));
@@ -513,7 +771,7 @@ function normalizeDocument(input) {
   const usedEdgeIds = /* @__PURE__ */ new Set();
   const edges = (Array.isArray(source.edges) ? source.edges : []).slice(0, MAX_EDGES).map((edge, index) => normalizeEdge(edge, index, nodeIds, usedEdgeIds)).filter(Boolean);
   return {
-    version: VD_FLOWCHART_VERSION,
+    version: FLOWCHART_DOCUMENT_VERSION,
     viewport: normalizeViewport(source.viewport),
     nodes,
     edges
@@ -579,6 +837,15 @@ function getPortPosition(node, port) {
       return { x: node.x, y: node.y + node.height / 2 };
   }
 }
+function getPortHandlePosition(node, port, scale = 1) {
+  const point = getPortPosition(node, port);
+  const normal = getPortNormal(port);
+  const offset = PORT_HANDLE_OFFSET / scale;
+  return {
+    x: formatNumber(point.x + normal.x * offset),
+    y: formatNumber(point.y + normal.y * offset)
+  };
+}
 function getNearestPort(node, point) {
   return FLOWCHART_PORTS.reduce((best, port) => {
     const portPoint = getPortPosition(node, port);
@@ -946,6 +1213,68 @@ function getResizeCursor(handle) {
   if (handle === "ne" || handle === "sw") return "nesw-resize";
   return "nwse-resize";
 }
+function collectGuideLines(nodes) {
+  const x = [];
+  const y = [];
+  nodes.forEach((node) => {
+    const right = node.x + node.width;
+    const bottom = node.y + node.height;
+    [node.x, node.x + node.width / 2, right].forEach(
+      (value) => x.push({ value, start: node.y, end: bottom })
+    );
+    [node.y, node.y + node.height / 2, bottom].forEach(
+      (value) => y.push({ value, start: node.x, end: right })
+    );
+  });
+  const byValue = (a, b) => a.value - b.value;
+  return { x: x.sort(byValue), y: y.sort(byValue) };
+}
+function lowerBound(lines, value) {
+  let low = 0;
+  let high = lines.length;
+  while (low < high) {
+    const middle = low + high >> 1;
+    if (lines[middle].value < value) low = middle + 1;
+    else high = middle;
+  }
+  return low;
+}
+function snapToGuides(lines, candidates, threshold) {
+  let best = null;
+  candidates.forEach((candidate) => {
+    const index = lowerBound(lines, candidate);
+    [lines[index - 1], lines[index]].forEach((line) => {
+      if (!line) return;
+      const offset = line.value - candidate;
+      if (Math.abs(offset) <= threshold && (!best || Math.abs(offset) < Math.abs(best.offset))) {
+        best = { offset };
+      }
+    });
+  });
+  if (!best) return null;
+  const positions = candidates.map((candidate) => candidate + best.offset);
+  best.lines = lines.filter(
+    (line) => positions.some((position) => Math.abs(line.value - position) < 0.5)
+  );
+  return best;
+}
+function guideSegments(axis, lines, box) {
+  const byValue = /* @__PURE__ */ new Map();
+  lines.forEach((line) => {
+    const current = byValue.get(line.value);
+    byValue.set(line.value, {
+      start: Math.min(current?.start ?? Infinity, line.start),
+      end: Math.max(current?.end ?? -Infinity, line.end)
+    });
+  });
+  const boxStart = axis === "x" ? box.top : box.left;
+  const boxEnd = boxStart + (axis === "x" ? box.height : box.width);
+  return [...byValue].map(([value, extent]) => {
+    const start = Math.min(extent.start, boxStart) - GUIDE_OVERHANG;
+    const end = Math.max(extent.end, boxEnd) + GUIDE_OVERHANG;
+    return axis === "x" ? { x1: value, y1: start, x2: value, y2: end } : { x1: start, y1: value, x2: end, y2: value };
+  });
+}
 function getBounds(nodes) {
   if (!nodes.length) {
     return { left: 0, top: 0, right: 0, bottom: 0 };
@@ -968,6 +1297,8 @@ function getBounds(nodes) {
 function createField(labelText, control) {
   const wrapper = createElement("div", { className: "vd-flowchart-field" });
   const label = createElement("label", { text: labelText });
+  control.id || (control.id = nextId("flowchart-field"));
+  label.htmlFor = control.id;
   wrapper.appendChild(label);
   wrapper.appendChild(control);
   return wrapper;
@@ -1100,6 +1431,7 @@ var VdFlowchart = class {
     this.documentData = normalizeDocument(options.data || {});
     this.listeners = {};
     this.selection = null;
+    this.selectedNodeIds = /* @__PURE__ */ new Set();
     this.interaction = null;
     this.activeTool = null;
     this.layoutMode = "tree";
@@ -1107,6 +1439,7 @@ var VdFlowchart = class {
     this.destroyed = false;
     this.lastNodePointer = null;
     this.reconnectEdgeId = null;
+    this.edgeCycleAnchor = null;
     this.clipboard = null;
     this.gridPatternId = nextId("flowchart-grid");
     this.markerIds = /* @__PURE__ */ new Map();
@@ -1116,6 +1449,16 @@ var VdFlowchart = class {
     this.history = [];
     this.historyIndex = -1;
     this.isApplyingHistory = false;
+    this.historyBatchDepth = 0;
+    this.historyBatchDirty = false;
+    this.coalesceInsertedText = false;
+    this.keyboardShortcuts = normalizeKeyboardShortcuts(options.keyboardShortcuts);
+    this.snapGuides = options.snapGuides !== false;
+    this.minimapEnabled = options.minimap !== false;
+    this.autoLayout = Boolean(options.autoLayout);
+    this.minimapFrame = 0;
+    this.minimapDrag = null;
+    this.shortcutsHelpOpen = false;
     this.autoFit = Boolean(options.autoFit);
     this.readyEmitted = false;
     this.resizeObserver = null;
@@ -1156,6 +1499,7 @@ var VdFlowchart = class {
       if (!ready) return false;
       this.readyEmitted = true;
       if (this.autoFit) this.fitView();
+      else this.scheduleMinimap();
       this.emit("ready", this);
       return true;
     };
@@ -1225,8 +1569,25 @@ var VdFlowchart = class {
       className: "vd-flowchart-toolbar-label",
       text: "100%"
     });
+    this.shortcutsButton = createElement("button", {
+      className: "vd-flowchart-btn vd-flowchart-icon-btn vd-flowchart-shortcuts-btn",
+      title: "Keyboard shortcuts (?)",
+      text: "?"
+    });
+    this.shortcutsButton.setAttribute("type", "button");
+    this.shortcutsButton.setAttribute("data-flowchart-action", "shortcuts");
+    this.shortcutsButton.setAttribute("aria-label", "Keyboard shortcuts");
+    this.shortcutsButton.setAttribute("aria-expanded", "false");
+    this.minimapButton = createToolbarButton({
+      action: "minimap",
+      label: "Toggle minimap",
+      icon: "minimap"
+    });
+    this.minimapButton.setAttribute("aria-pressed", this.minimapEnabled ? "true" : "false");
     toolbarLeft.appendChild(this.arrangeSelect);
     toolbarLeft.appendChild(this.clearButton);
+    toolbarRight.appendChild(this.minimapButton);
+    toolbarRight.appendChild(this.shortcutsButton);
     toolbarRight.appendChild(this.zoomLabel);
     this.toolbar.appendChild(toolbarLeft);
     this.toolbar.appendChild(toolbarRight);
@@ -1305,13 +1666,40 @@ var VdFlowchart = class {
     this.previewLayer = svgEl("g", { class: "vd-flowchart-preview" });
     this.nodesLayer = svgEl("g", { class: "vd-flowchart-nodes" });
     this.overlayLayer = svgEl("g", { class: "vd-flowchart-overlay" });
+    this.guidesLayer = svgEl("g", { class: "vd-flowchart-guides" });
     this.world.appendChild(this.gridRect);
     this.world.appendChild(this.edgesLayer);
     this.world.appendChild(this.previewLayer);
     this.world.appendChild(this.nodesLayer);
     this.world.appendChild(this.overlayLayer);
+    this.world.appendChild(this.guidesLayer);
     this.svg.appendChild(this.world);
     this.canvasEl.appendChild(this.svg);
+    this.shortcutsHelp = createElement("div", { className: "vd-flowchart-shortcuts" });
+    this.shortcutsHelp.id = nextId("flowchart-shortcuts");
+    this.shortcutsHelp.setAttribute("role", "dialog");
+    this.shortcutsHelp.setAttribute("aria-label", "Keyboard shortcuts");
+    this.shortcutsHelp.hidden = true;
+    this.shortcutsHelp.addEventListener("pointerdown", (event) => event.stopPropagation());
+    this.shortcutsHelp.addEventListener("wheel", (event) => event.stopPropagation());
+    this.shortcutsButton.setAttribute("aria-controls", this.shortcutsHelp.id);
+    this.canvasEl.appendChild(this.shortcutsHelp);
+    this.minimapEl = createElement("div", { className: "vd-flowchart-minimap" });
+    this.minimapEl.setAttribute("aria-hidden", "true");
+    this.minimapEl.hidden = true;
+    this.minimapSvg = svgEl("svg", {
+      class: "vd-flowchart-minimap-svg",
+      width: MINIMAP_WIDTH,
+      height: MINIMAP_HEIGHT,
+      viewBox: `0 0 ${MINIMAP_WIDTH} ${MINIMAP_HEIGHT}`
+    });
+    this.minimapEl.appendChild(this.minimapSvg);
+    this.minimapEl.addEventListener("pointerdown", (event) => this.handleMinimapPointer(event));
+    this.minimapEl.addEventListener("pointermove", (event) => this.handleMinimapPointer(event));
+    this.minimapEl.addEventListener("pointerup", (event) => this.endMinimapDrag(event));
+    this.minimapEl.addEventListener("pointercancel", (event) => this.endMinimapDrag(event));
+    this.minimapEl.addEventListener("wheel", (event) => event.stopPropagation());
+    this.canvasEl.appendChild(this.minimapEl);
     this.inspectorPanel = createElement("aside", {
       className: "vd-flowchart-panel vd-flowchart-panel--inspector"
     });
@@ -1352,14 +1740,134 @@ var VdFlowchart = class {
     this.jsonActions.appendChild(this.loadJsonButton);
     this.jsonPanel.appendChild(this.jsonTextarea);
     this.jsonPanel.appendChild(this.jsonActions);
+    this.jsonStatus = createElement("p", { className: "vd-flowchart-json-status" });
+    this.jsonStatus.setAttribute("role", "status");
+    this.jsonPanel.appendChild(this.jsonStatus);
     this.inspectorPanel.appendChild(this.jsonPanel);
     this.body.appendChild(this.palettePanel);
     this.body.appendChild(this.canvasEl);
     this.body.appendChild(this.inspectorPanel);
     this.root.appendChild(this.toolbar);
     this.root.appendChild(this.body);
+    this.buildGraphOutline();
     this.element.appendChild(this.root);
   }
+  buildGraphOutline() {
+    this.graphOutline = createElement("details", { className: "vd-flowchart-outline" });
+    this.graphOutline.appendChild(createElement("summary", { text: "Graph outline" }));
+    this.graphOutline.addEventListener("toggle", () => {
+      if (this.graphOutline.open) this.renderGraphOutline();
+    });
+    this.graphStatus = createElement("p", { className: "vd-flowchart-sr-only" });
+    this.graphStatus.setAttribute("role", "status");
+    this.canvasEl.appendChild(this.graphStatus);
+    this.graphControls = createElement("div", { className: "vd-flowchart-outline-controls" });
+    this.graphNodeSelect = createElement("select");
+    this.graphNodeSelect.setAttribute("aria-label", "Selected node");
+    this.graphNodeSelect.addEventListener(
+      "change",
+      () => this.selectNode(this.graphNodeSelect.value)
+    );
+    this.graphTargetSelect = createElement("select");
+    this.graphTargetSelect.setAttribute("aria-label", "Connection target");
+    this.graphTargetSelect.addEventListener("change", () => this.renderGraphOutline());
+    this.graphConnectButton = createElement("button", {
+      text: "Connect nodes",
+      type: "button",
+      className: "vd-flowchart-btn"
+    });
+    this.graphConnectButton.addEventListener("click", () => {
+      if (this.readonly || this.graphNodeSelect.value === this.graphTargetSelect.value) {
+        return;
+      }
+      this.addEdge({
+        from: this.graphNodeSelect.value,
+        to: this.graphTargetSelect.value,
+        autoPort: true
+      });
+    });
+    this.graphEditButton = createElement("button", {
+      text: "Edit selected label",
+      type: "button",
+      className: "vd-flowchart-btn"
+    });
+    this.graphEditButton.addEventListener(
+      "click",
+      () => this.startTextEdit(this.graphNodeSelect.value)
+    );
+    this.graphControls.append(
+      createField("Selected node", this.graphNodeSelect),
+      createField("Connection target", this.graphTargetSelect),
+      this.graphConnectButton,
+      this.graphEditButton
+    );
+    this.graphOutline.appendChild(this.graphControls);
+    this.graphList = createElement("ul");
+    this.graphList.setAttribute("aria-label", "Nodes and connections");
+    this.graphOutline.appendChild(this.graphList);
+    this.root.appendChild(this.graphOutline);
+    this.canvasEl.setAttribute("role", "group");
+    this.syncCanvasLabel();
+    this.jsonTextarea.setAttribute("aria-label", "Flowchart JSON");
+  }
+  syncCanvasLabel() {
+    const keys = this.readonly || this.keyboardShortcuts === "basic" ? "Arrow keys select nodes; Enter or F2 edits a label." : "Arrow keys select nodes; Tab adds a child, Enter adds a sibling, F2 edits a label.";
+    this.canvasEl.setAttribute(
+      "aria-label",
+      `Diagram canvas. ${keys} Press ? for all shortcuts. Graph outline provides connections.`
+    );
+  }
+  renderGraphOutline() {
+    if (!this.graphOutline) return;
+    const nodes = this.documentData.nodes;
+    const edges = this.documentData.edges;
+    const labels = new Map(nodes.map((node) => [node.id, node.text || node.id]));
+    const selected = this.selection?.kind === "node" ? this.selection.id : null;
+    this.graphStatus.textContent = selected ? `Selected: ${labels.get(selected)}. ${nodes.length} nodes, ${edges.length} connections.` : `${nodes.length} nodes, ${edges.length} connections.`;
+    if (!this.graphOutline.open) return;
+    const hidden = this.getHiddenNodeIds();
+    const signature = JSON.stringify([
+      nodes.map((node) => [node.id, node.text, Boolean(node.collapsed), hidden.has(node.id)]),
+      edges.map((edge) => [edge.id, edge.from.nodeId, edge.to.nodeId, edge.label])
+    ]);
+    if (signature !== this.graphSignature) {
+      this.graphSignature = signature;
+      for (const select of [this.graphNodeSelect, this.graphTargetSelect]) {
+        const previous = select.value;
+        select.replaceChildren();
+        for (const node of nodes)
+          select.appendChild(
+            createElement("option", { value: node.id, text: labels.get(node.id) })
+          );
+        if (labels.has(previous)) select.value = previous;
+      }
+      this.graphList.replaceChildren();
+      const outgoing = new Map(nodes.map((node) => [node.id, []]));
+      const incoming = new Map(nodes.map((node) => [node.id, []]));
+      for (const edge of edges) {
+        outgoing.get(edge.from.nodeId)?.push(`${labels.get(edge.to.nodeId)}${edge.label ? ` (${edge.label})` : ""}`);
+        incoming.get(edge.to.nodeId)?.push(labels.get(edge.from.nodeId));
+      }
+      for (const node of nodes) {
+        const to = outgoing.get(node.id);
+        const from = incoming.get(node.id);
+        const relationships = [
+          to.length ? `Connects to ${to.join(", ")}.` : "No outgoing connections.",
+          from.length ? `Connected from ${from.join(", ")}.` : "",
+          node.collapsed ? "Branch collapsed." : "",
+          hidden.has(node.id) ? "Hidden in a collapsed branch." : ""
+        ].filter(Boolean);
+        this.graphList.appendChild(
+          createElement("li", { text: `${labels.get(node.id)}. ${relationships.join(" ")}` })
+        );
+      }
+    }
+    if (selected) this.graphNodeSelect.value = selected;
+    this.graphNodeSelect.disabled = nodes.length === 0;
+    this.graphTargetSelect.disabled = this.readonly || nodes.length < 2;
+    this.graphConnectButton.disabled = this.readonly || nodes.length < 2 || this.graphNodeSelect.value === this.graphTargetSelect.value;
+    this.graphEditButton.disabled = this.readonly || nodes.length === 0;
+  }
   bindEvents() {
     this.toolbar.addEventListener("click", this.handleToolbarClick);
     this.arrangeSelect.addEventListener("change", this.handleArrangeChange);
@@ -1433,6 +1941,157 @@ var VdFlowchart = class {
     if (action === "undo") this.undo();
     if (action === "redo") this.redo();
     if (action === "clear" && !this.readonly) this.clear();
+    if (action === "shortcuts") this.toggleShortcutsHelp();
+    if (action === "minimap") this.setMinimapEnabled(!this.minimapEnabled);
+  }
+  setMinimapEnabled(enabled) {
+    this.minimapEnabled = Boolean(enabled);
+    this.minimapButton.setAttribute("aria-pressed", this.minimapEnabled ? "true" : "false");
+    this.drawMinimap();
+    return this;
+  }
+  scheduleMinimap() {
+    if (this.minimapFrame || !hasWindow()) return;
+    const raf = typeof requestAnimationFrame === "function" ? requestAnimationFrame : (callback) => setTimeout(callback, 16);
+    this.minimapFrame = raf(() => {
+      this.minimapFrame = 0;
+      this.drawMinimap();
+    });
+  }
+  // World-to-minimap mapping covering every visible node and the viewport.
+  getMinimapTransform() {
+    const viewport = this.documentData.viewport;
+    const width = this.canvasEl.clientWidth;
+    const height = this.canvasEl.clientHeight;
+    const view = {
+      left: -viewport.x / viewport.scale,
+      top: -viewport.y / viewport.scale,
+      right: (width - viewport.x) / viewport.scale,
+      bottom: (height - viewport.y) / viewport.scale
+    };
+    const content = getBounds(this.getVisibleNodes());
+    const left = Math.min(content.left, view.left);
+    const top = Math.min(content.top, view.top);
+    const spanX = Math.max(1, Math.max(content.right, view.right) - left);
+    const spanY = Math.max(1, Math.max(content.bottom, view.bottom) - top);
+    const padding = 8;
+    const scale = Math.min(
+      (MINIMAP_WIDTH - padding * 2) / spanX,
+      (MINIMAP_HEIGHT - padding * 2) / spanY
+    );
+    return {
+      scale,
+      offsetX: (MINIMAP_WIDTH - spanX * scale) / 2 - left * scale,
+      offsetY: (MINIMAP_HEIGHT - spanY * scale) / 2 - top * scale,
+      view
+    };
+  }
+  drawMinimap() {
+    if (this.destroyed || !this.minimapEl) return;
+    const nodes = this.getVisibleNodes();
+    const visible = this.minimapEnabled && nodes.length > 0 && this.canvasEl.clientWidth >= MINIMAP_MIN_CANVAS_WIDTH;
+    this.minimapEl.hidden = !visible;
+    if (!visible) return;
+    const transform = this.minimapDrag?.transform || this.getMinimapTransform();
+    const view = this.getMinimapTransform().view;
+    const map = (x, y) => ({
+      x: formatNumber(x * transform.scale + transform.offsetX),
+      y: formatNumber(y * transform.scale + transform.offsetY)
+    });
+    clearChildren(this.minimapSvg);
+    nodes.forEach((node) => {
+      const point = map(node.x, node.y);
+      const selected = this.isNodeSelected(node.id);
+      this.minimapSvg.appendChild(
+        svgEl("rect", {
+          class: `vd-flowchart-minimap-node${selected ? " is-selected" : ""}`,
+          x: point.x,
+          y: point.y,
+          width: formatNumber(Math.max(1.5, node.width * transform.scale)),
+          height: formatNumber(Math.max(1.5, node.height * transform.scale)),
+          rx: 1.5
+        })
+      );
+    });
+    const corner = map(view.left, view.top);
+    this.minimapSvg.appendChild(
+      svgEl("rect", {
+        class: "vd-flowchart-minimap-viewport",
+        x: corner.x,
+        y: corner.y,
+        width: formatNumber((view.right - view.left) * transform.scale),
+        height: formatNumber((view.bottom - view.top) * transform.scale)
+      })
+    );
+  }
+  // Centre the main view on the world point under the minimap pointer. The
+  // mapping is frozen for the whole drag so the map does not shift under it.
+  handleMinimapPointer(event) {
+    event.stopPropagation();
+    if (event.type === "pointerdown") {
+      if (event.button != null && event.button !== 0) return;
+      event.preventDefault();
+      this.minimapDrag = { pointerId: event.pointerId, transform: this.getMinimapTransform() };
+      try {
+        this.minimapEl.setPointerCapture?.(event.pointerId);
+      } catch {
+      }
+    }
+    if (!this.minimapDrag || this.minimapDrag.pointerId !== event.pointerId) return;
+    const rect = this.minimapEl.getBoundingClientRect();
+    const { transform } = this.minimapDrag;
+    this.centerViewOn(
+      (event.clientX - rect.left - transform.offsetX) / transform.scale,
+      (event.clientY - rect.top - transform.offsetY) / transform.scale
+    );
+  }
+  endMinimapDrag(event) {
+    event.stopPropagation();
+    if (!this.minimapDrag || this.minimapDrag.pointerId !== event.pointerId) return;
+    this.minimapDrag = null;
+    this.syncJsonTextarea();
+    this.emitViewportChange("viewport:pan");
+    this.drawMinimap();
+  }
+  centerViewOn(worldX, worldY) {
+    const viewport = this.documentData.viewport;
+    const width = this.canvasEl.clientWidth || 800;
+    const height = this.canvasEl.clientHeight || 560;
+    viewport.x = formatNumber(width / 2 - worldX * viewport.scale);
+    viewport.y = formatNumber(height / 2 - worldY * viewport.scale);
+    this.render({ inspector: false, json: false });
+    return this;
+  }
+  toggleShortcutsHelp(force) {
+    const open = typeof force === "boolean" ? force : !this.shortcutsHelpOpen;
+    this.shortcutsHelpOpen = open;
+    this.shortcutsButton.setAttribute("aria-expanded", open ? "true" : "false");
+    if (open) this.renderShortcutsHelp();
+    this.shortcutsHelp.hidden = !open;
+    if (!open && this.shortcutsHelp.contains(document.activeElement)) this.canvasEl.focus();
+    return this;
+  }
+  renderShortcutsHelp() {
+    clearChildren(this.shortcutsHelp);
+    const header = createElement("div", { className: "vd-flowchart-shortcuts-header" });
+    header.appendChild(
+      createElement("h4", { className: "vd-flowchart-panel-title", text: "Keyboard shortcuts" })
+    );
+    const close = createElement("button", {
+      className: "vd-flowchart-btn vd-flowchart-icon-btn",
+      text: "\xD7"
+    });
+    close.setAttribute("type", "button");
+    close.setAttribute("aria-label", "Close keyboard shortcuts");
+    close.addEventListener("click", () => this.toggleShortcutsHelp(false));
+    header.appendChild(close);
+    this.shortcutsHelp.appendChild(header);
+    const list = createElement("dl", { className: "vd-flowchart-shortcuts-list" });
+    getShortcutRows(this.keyboardShortcuts, this.readonly).forEach(([keys, action]) => {
+      list.appendChild(createElement("dt", { text: keys }));
+      list.appendChild(createElement("dd", { text: action }));
+    });
+    this.shortcutsHelp.appendChild(list);
   }
   handleArrangeChange(event) {
     if (this.readonly) return;
@@ -1466,7 +2125,12 @@ var VdFlowchart = class {
       return;
     }
     if (action === "load" && !this.readonly) {
-      this.load(this.jsonTextarea.value);
+      try {
+        this.load(this.jsonTextarea.value);
+        this.jsonStatus.textContent = "";
+      } catch (error) {
+        this.jsonStatus.textContent = error.message;
+      }
     }
   }
   handleSelectionFieldInput(event) {
@@ -1536,17 +2200,48 @@ var VdFlowchart = class {
       );
     }
   }
+  // Keys the editor consumes stop here, so page-level shortcuts (a docs
+  // site's "/" search, a host's Escape handler) do not also fire.
   handleKeyDown(event) {
-    if (this.readonly) return;
-    if (event.target && (event.target.tagName === "INPUT" || event.target.tagName === "TEXTAREA" || event.target.tagName === "SELECT")) {
+    const alreadyHandled = event.defaultPrevented;
+    this.handleEditorKey(event);
+    if (!alreadyHandled && event.defaultPrevented) event.stopPropagation();
+  }
+  handleEditorKey(event) {
+    const target = event.target;
+    if (target && (target.tagName === "INPUT" || target.tagName === "TEXTAREA" || target.tagName === "SELECT" || target.isContentEditable)) {
       return;
     }
-    if (event.key === "Escape" && this.activeTool) {
+    if (event.isComposing) return;
+    const key = event.key;
+    const modKey = event.metaKey || event.ctrlKey;
+    if (key === "Escape" && this.shortcutsHelpOpen) {
       event.preventDefault();
-      this.setActiveTool(null);
+      this.toggleShortcutsHelp(false);
+      return;
+    }
+    if (target === this.canvasEl && this.handleCanvasKeyDown(event)) {
+      event.preventDefault();
+      return;
+    }
+    if (this.readonly) return;
+    if (key === "Escape") {
+      if (this.activeTool) this.setActiveTool(null);
+      else if (this.reconnectEdgeId) {
+        this.reconnectEdgeId = null;
+        this.render({ inspector: false, json: false });
+      } else if (this.selection) this.select(null);
+      else return;
+      event.preventDefault();
+      return;
+    }
+    if (modKey && (key === "d" || key === "D")) {
+      if (this.selection?.kind === "node") {
+        event.preventDefault();
+        this.duplicateSelection();
+      }
       return;
     }
-    const modKey = event.metaKey || event.ctrlKey;
     if (modKey && (event.key === "z" || event.key === "Z")) {
       event.preventDefault();
       if (event.shiftKey) {
@@ -1585,11 +2280,248 @@ var VdFlowchart = class {
     if (!this.selection) return;
     if (event.key === "Backspace" || event.key === "Delete") {
       event.preventDefault();
+      if (this.selection.kind === "node" && !this.hasMultiSelection()) {
+        const removedId = this.selection.id;
+        const parent = this.getParentNode(removedId);
+        const sibling = parent ? this.getChildNodes(parent.id).find((node) => node.id !== removedId) : null;
+        if (this.deleteSelection()) {
+          const next = parent && this.findNode(parent.id) || sibling;
+          if (next) this.select({ kind: "node", id: next.id });
+        }
+        return;
+      }
       this.deleteSelection();
     }
   }
+  // Keys that only apply while the canvas itself has focus. Returns true when
+  // the key was handled (the caller prevents the default action).
+  handleCanvasKeyDown(event) {
+    const key = event.key;
+    const modKey = event.metaKey || event.ctrlKey;
+    const mindmap = this.keyboardShortcuts === "mindmap";
+    const selectedNode = this.selection?.kind === "node" ? this.findNode(this.selection.id) : null;
+    const selectedEdge = this.selection?.kind === "edge" ? this.findEdge(this.selection.id) : null;
+    const movable = !this.readonly && Boolean(selectedNode);
+    const editable = movable && !this.hasMultiSelection();
+    if (key === "?" && !modKey && !event.altKey) {
+      this.toggleShortcutsHelp();
+      return true;
+    }
+    if (modKey && !event.altKey) {
+      if (key === "=" || key === "+") return Boolean(this.zoomIn());
+      if (key === "-" || key === "_") return Boolean(this.zoomOut());
+      if (key === "0") return Boolean(this.zoomTo(1));
+      if (key === "a" || key === "A") {
+        this.selectNodes(this.getVisibleNodes().map((node) => node.id));
+        return true;
+      }
+      if (key === "/" && selectedNode && !this.hasMultiSelection()) {
+        this.toggleCollapsed(selectedNode.id);
+        return true;
+      }
+      return false;
+    }
+    if (event.shiftKey && !event.altKey && (key === "!" || event.code === "Digit1")) {
+      return Boolean(this.fitView());
+    }
+    const direction = ARROW_DIRECTIONS[key];
+    if (direction) {
+      if (event.altKey) {
+        if (movable) {
+          this.nudgeNodes(this.getSelectedNodeIds(), direction, event.shiftKey ? 1 : this.gridSize);
+        }
+        return true;
+      }
+      if (event.shiftKey) {
+        const anchorId = selectedNode?.id ?? (selectedEdge ? this.edgeCycleAnchor : null);
+        return anchorId ? this.selectSideEdge(anchorId, direction) : false;
+      }
+      this.navigateSelection(direction);
+      return true;
+    }
+    const nodes = this.getVisibleNodes();
+    if ((key === "Home" || key === "End") && nodes.length) {
+      this.selectNode(nodes[key === "Home" ? 0 : nodes.length - 1].id);
+      return true;
+    }
+    if (selectedEdge && !this.readonly && !event.altKey) {
+      if (key === "F2" || key === "Enter" || key === " " && mindmap) {
+        return this.startEdgeLabelEdit(selectedEdge.id);
+      }
+      if (mindmap && key.length === 1 && key !== " ") {
+        return this.startEdgeLabelEdit(selectedEdge.id, { initialText: key });
+      }
+      return false;
+    }
+    if (!editable || event.altKey) return false;
+    if (key === "F2" || key === "Enter" && !mindmap || key === " " && mindmap) {
+      this.startTextEdit(selectedNode.id);
+      return true;
+    }
+    if (!mindmap) return false;
+    if (key === "Tab" && !event.shiftKey) {
+      this.insertBranchNode(selectedNode.id, { edit: true });
+      return true;
+    }
+    if (key === "Enter") {
+      this.insertSiblingNode(selectedNode.id, { before: event.shiftKey, edit: true });
+      return true;
+    }
+    if (key.length === 1 && key !== " " && isNodeTextEditable(selectedNode)) {
+      this.startTextEdit(selectedNode.id, { initialText: key });
+      return true;
+    }
+    return false;
+  }
+  // Move the selection to the nearest node in `direction`; with nothing (or an
+  // edge) selected, start from the node closest to the centre of the view.
+  navigateSelection(direction) {
+    const nodes = this.getVisibleNodes();
+    if (!nodes.length) return false;
+    const current = this.selection?.kind === "node" ? this.findNode(this.selection.id) : null;
+    const edge = this.selection?.kind === "edge" ? this.findEdge(this.selection.id) : null;
+    const next = current ? findSpatialNeighbor(nodes, current, direction) : edge ? this.getEdgeEndInDirection(edge, direction) : findNearestNode(nodes, this.getViewportCenter());
+    if (!next) return false;
+    this.selectNode(next.id);
+    this.revealNode(next.id);
+    return true;
+  }
+  // The end of `edge` that best matches `direction`, measured from the label
+  // anchor so either end can be reached from a selected connection.
+  getEdgeEndInDirection(edge, direction) {
+    const fromNode = this.findNode(edge.from.nodeId);
+    const toNode = this.findNode(edge.to.nodeId);
+    if (!fromNode || !toNode) return fromNode || toNode;
+    const { labelX, labelY } = buildEdgePath(edge, fromNode, toNode);
+    const vector = { right: [1, 0], left: [-1, 0], down: [0, 1], up: [0, -1] }[direction];
+    const score = (node) => (node.x + node.width / 2 - labelX) * vector[0] + (node.y + node.height / 2 - labelY) * vector[1];
+    return score(toNode) >= score(fromNode) ? toNode : fromNode;
+  }
+  // Connections attached to `nodeId` on the `direction` side, outgoing or
+  // incoming, in document order.
+  getSideEdges(nodeId, direction) {
+    const port = DIRECTION_PORTS[direction];
+    return this.documentData.edges.filter(
+      (edge) => edge.from.nodeId === nodeId && edge.from.port === port || edge.to.nodeId === nodeId && edge.to.port === port
+    );
+  }
+  // Select a connection on one side of a node; repeating cycles through them.
+  selectSideEdge(nodeId, direction) {
+    const edges = this.getSideEdges(nodeId, direction);
+    if (!edges.length) return false;
+    const currentIndex = this.selection?.kind === "edge" ? edges.findIndex((edge) => edge.id === this.selection.id) : -1;
+    const next = edges[(currentIndex + 1) % edges.length];
+    this.select({ kind: "edge", id: next.id });
+    this.edgeCycleAnchor = nodeId;
+    return true;
+  }
+  nudgeNode(nodeId, direction, distance) {
+    const [node] = this.nudgeNodes([nodeId], direction, distance);
+    return node || null;
+  }
+  // Move nodes together; repeated nudges of the same selection coalesce into
+  // one undo step.
+  nudgeNodes(nodeIds, direction, distance) {
+    const step = { right: [1, 0], left: [-1, 0], down: [0, 1], up: [0, -1] }[direction];
+    if (this.readonly || !step) return [];
+    const nodes = nodeIds.map((id) => this.findNode(id)).filter(Boolean);
+    if (!nodes.length) return [];
+    nodes.forEach((node) => {
+      node.x = formatNumber(node.x + step[0] * distance);
+      node.y = formatNumber(node.y + step[1] * distance);
+    });
+    this.render({ inspector: true, json: true });
+    this.emitChange(
+      "node:nudge",
+      nodes.length > 1 ? { nodeIds: nodes.map((node) => node.id) } : { node: deepClone(nodes[0]) }
+    );
+    return nodes.map((node) => deepClone(node));
+  }
+  zoomTo(scale) {
+    const viewport = this.documentData.viewport;
+    const width = this.canvasEl.clientWidth || 800;
+    const height = this.canvasEl.clientHeight || 560;
+    this.scaleAround(
+      clamp(scale, MIN_SCALE, MAX_SCALE) / viewport.scale,
+      width / 2,
+      height / 2,
+      "viewport:zoom"
+    );
+    return this;
+  }
+  duplicateSelection() {
+    if (this.readonly || this.selection?.kind !== "node") return null;
+    if (this.hasMultiSelection()) return this.pasteNodeGroup(this.captureNodeGroup());
+    const node = this.findNode(this.selection.id);
+    return node ? this.pasteNodeData(node) : null;
+  }
+  // Selected nodes plus the connections that run between them.
+  captureNodeGroup() {
+    const ids = new Set(this.getSelectedNodeIds());
+    return {
+      nodes: deepClone(this.documentData.nodes.filter((node) => ids.has(node.id))),
+      edges: deepClone(
+        this.documentData.edges.filter(
+          (edge) => ids.has(edge.from.nodeId) && ids.has(edge.to.nodeId)
+        )
+      )
+    };
+  }
+  // Paste a captured group offset by one step, remapping ids so internal
+  // connections follow their copies. One change, one undo step.
+  pasteNodeGroup(group) {
+    if (this.readonly || !group?.nodes?.length) return [];
+    const usedNodeIds = new Set(this.documentData.nodes.map((node) => node.id));
+    const idMap = /* @__PURE__ */ new Map();
+    const nodes = group.nodes.map((data, index) => {
+      const node = normalizeNode(
+        { ...data, id: void 0, x: data.x + 24, y: data.y + 24 },
+        this.documentData.nodes.length + index,
+        usedNodeIds
+      );
+      idMap.set(data.id, node.id);
+      return node;
+    });
+    this.documentData.nodes.push(...nodes);
+    const nodeIds = new Set(this.documentData.nodes.map((node) => node.id));
+    const usedEdgeIds = new Set(this.documentData.edges.map((edge) => edge.id));
+    group.edges.forEach((data, index) => {
+      const edge = normalizeEdge(
+        {
+          ...data,
+          id: void 0,
+          from: { ...data.from, nodeId: idMap.get(data.from.nodeId) },
+          to: { ...data.to, nodeId: idMap.get(data.to.nodeId) }
+        },
+        this.documentData.edges.length + index,
+        nodeIds,
+        usedEdgeIds
+      );
+      if (edge) this.documentData.edges.push(edge);
+    });
+    const ids = nodes.map((node) => node.id);
+    this.selectNodes(ids);
+    this.emitChange("nodes:add", { nodeIds: ids });
+    return nodes.map((node) => deepClone(node));
+  }
+  pasteNodeData(data) {
+    const usedIds = new Set(this.documentData.nodes.map((node2) => node2.id));
+    const node = normalizeNode(
+      { ...data, id: void 0, collapsed: void 0, x: data.x + 24, y: data.y + 24 },
+      this.documentData.nodes.length,
+      usedIds
+    );
+    this.documentData.nodes.push(node);
+    this.select({ kind: "node", id: node.id });
+    this.emitChange("node:add", { node: deepClone(node) });
+    return deepClone(node);
+  }
   copySelection() {
     if (!this.selection) return false;
+    if (this.hasMultiSelection()) {
+      this.clipboard = { kind: "nodes", data: this.captureNodeGroup() };
+      return true;
+    }
     if (this.selection.kind === "node") {
       const node = this.findNode(this.selection.id);
       if (!node) return false;
@@ -1604,22 +2536,14 @@ var VdFlowchart = class {
   pasteClipboard() {
     if (!this.clipboard || this.readonly) return false;
     if (this.clipboard.kind === "node") {
-      const usedIds2 = new Set(this.documentData.nodes.map((node2) => node2.id));
-      const node = normalizeNode(
-        {
-          ...this.clipboard.data,
-          id: void 0,
-          x: this.clipboard.data.x + 24,
-          y: this.clipboard.data.y + 24
-        },
-        this.documentData.nodes.length,
-        usedIds2
-      );
-      this.documentData.nodes.push(node);
-      this.select({ kind: "node", id: node.id });
-      this.emitChange("node:add", { node: deepClone(node) });
+      this.pasteNodeData(this.clipboard.data);
       return true;
     }
+    if (this.clipboard.kind === "nodes") {
+      const pasted = this.pasteNodeGroup(this.clipboard.data);
+      this.clipboard = { kind: "nodes", data: this.captureNodeGroup() };
+      return pasted.length > 0;
+    }
     const usedIds = new Set(this.documentData.edges.map((edge2) => edge2.id));
     const nodeIds = new Set(this.documentData.nodes.map((node) => node.id));
     const edge = normalizeEdge(
@@ -1646,16 +2570,16 @@ var VdFlowchart = class {
     const edgeTarget = event.target.closest("[data-edge-id]");
     if (edgeTarget && !event.target.closest("[data-edge-endpoint]")) {
       const edgeId = edgeTarget.getAttribute("data-edge-id");
-      if (edgeId && this.findEdge(edgeId)) {
-        this.reconnectEdgeId = edgeId;
-        this.select({ kind: "edge", id: edgeId });
+      if (edgeId && this.startEdgeLabelEdit(edgeId)) {
         event.preventDefault();
         event.stopPropagation();
         return;
       }
     }
     const nodeTarget = event.target.closest("[data-node-id]");
-    if (!nodeTarget || event.target.closest("[data-edge-id]")) return;
+    if (!nodeTarget || event.target.closest("[data-edge-id]") || event.target.closest("[data-collapse-toggle]")) {
+      return;
+    }
     const nodeId = nodeTarget.getAttribute("data-node-id");
     if (this.startTextEdit(nodeId)) {
       event.preventDefault();
@@ -1665,7 +2589,7 @@ var VdFlowchart = class {
   handleClick(event) {
     if (this.readonly || event.detail < 2) return;
     const nodeTarget = event.target.closest("[data-node-id]");
-    if (!nodeTarget || event.target.closest("[data-port]") || event.target.closest("[data-resize-handle]"))
+    if (!nodeTarget || event.target.closest("[data-port]") || event.target.closest("[data-resize-handle]") || event.target.closest("[data-collapse-toggle]"))
       return;
     if (this.startTextEdit(nodeTarget.getAttribute("data-node-id"))) {
       event.preventDefault();
@@ -1678,6 +2602,13 @@ var VdFlowchart = class {
       this.stopTextEdit({ commit: true });
     }
     this.canvasEl.focus();
+    const collapseTarget = event.target.closest("[data-collapse-toggle]");
+    if (collapseTarget) {
+      this.lastNodePointer = null;
+      this.toggleCollapsed(collapseTarget.getAttribute("data-collapse-toggle"));
+      event.preventDefault();
+      return;
+    }
     const nodeTarget = event.target.closest("[data-node-id]");
     const portTarget = event.target.closest("[data-port]");
     const resizeTarget = event.target.closest("[data-resize-handle]");
@@ -1713,6 +2644,13 @@ var VdFlowchart = class {
       event.preventDefault();
       return;
     }
+    if (nodeTarget && !portTarget && !resizeTarget && !edgeTarget && event.shiftKey) {
+      this.reconnectEdgeId = null;
+      this.lastNodePointer = null;
+      this.toggleNodeSelection(nodeTarget.getAttribute("data-node-id"));
+      event.preventDefault();
+      return;
+    }
     if (nodeTarget && !portTarget && !resizeTarget && !edgeTarget && !this.readonly) {
       if (this.activeTool === "arrow") {
         this.select({ kind: "node", id: nodeTarget.getAttribute("data-node-id") });
@@ -1739,6 +2677,9 @@ var VdFlowchart = class {
       this.interaction = {
         kind: "connect",
         pointerId: event.pointerId,
+        startClientX: event.clientX,
+        startClientY: event.clientY,
+        moved: false,
         source: { nodeId, port },
         target: null,
         previousSnap: null,
@@ -1789,22 +2730,27 @@ var VdFlowchart = class {
     if (nodeTarget) {
       this.reconnectEdgeId = null;
       const nodeId = nodeTarget.getAttribute("data-node-id");
-      this.select({ kind: "node", id: nodeId });
+      const groupIds = this.hasMultiSelection() && this.isNodeSelected(nodeId) ? this.getSelectedNodeIds() : [nodeId];
+      if (groupIds.length > 1) this.selectNodes(groupIds, { primary: nodeId });
+      else this.select({ kind: "node", id: nodeId });
       if (!this.readonly) {
-        const node = this.findNode(nodeId);
-        const world = this.clientToWorld(event.clientX, event.clientY);
-        this.interaction = {
-          kind: "drag-node",
-          pointerId: event.pointerId,
-          nodeId,
-          offsetX: world.x - node.x,
-          offsetY: world.y - node.y,
-          moved: false
-        };
+        this.interaction = this.createDragInteraction(event, nodeId, groupIds);
         this.capturePointer(event.pointerId);
       }
       return;
     }
+    if (event.shiftKey) {
+      const startWorld = this.clientToWorld(event.clientX, event.clientY);
+      this.interaction = {
+        kind: "marquee",
+        pointerId: event.pointerId,
+        startWorld,
+        baseIds: this.selection?.kind === "node" ? this.getSelectedNodeIds() : []
+      };
+      this.capturePointer(event.pointerId);
+      event.preventDefault();
+      return;
+    }
     this.select(null);
     this.reconnectEdgeId = null;
     this.interaction = {
@@ -1819,20 +2765,123 @@ var VdFlowchart = class {
     this.capturePointer(event.pointerId);
     event.preventDefault();
   }
+  createDragInteraction(event, nodeId, nodeIds) {
+    const nodes = nodeIds.map((id) => this.findNode(id)).filter(Boolean);
+    const moving = new Set(nodes.map((node) => node.id));
+    return {
+      kind: "drag-node",
+      pointerId: event.pointerId,
+      nodeId,
+      nodeIds: nodes.map((node) => node.id),
+      startWorld: this.clientToWorld(event.clientX, event.clientY),
+      origins: new Map(nodes.map((node) => [node.id, { x: node.x, y: node.y }])),
+      bounds: getBounds(nodes),
+      guideLines: this.snapGuides ? collectGuideLines(this.getVisibleNodes().filter((node) => !moving.has(node.id))) : null,
+      snapDisabled: false,
+      moved: false
+    };
+  }
+  // Translate every dragged node by the pointer delta, snapping the group's
+  // bounds to the nearest alignment guide on each axis. Alt turns snapping
+  // off for the rest of the gesture.
+  moveDraggedNodes(event) {
+    const interaction = this.interaction;
+    const world = this.clientToWorld(event.clientX, event.clientY);
+    let dx = world.x - interaction.startWorld.x;
+    let dy = world.y - interaction.startWorld.y;
+    if (event.altKey) interaction.snapDisabled = true;
+    let guides = [];
+    if (interaction.guideLines && !interaction.snapDisabled) {
+      const box = interaction.bounds;
+      const threshold = GUIDE_SNAP_DISTANCE / this.documentData.viewport.scale;
+      const left = box.left + dx;
+      const top = box.top + dy;
+      const width = box.right - box.left;
+      const height = box.bottom - box.top;
+      const snapX = snapToGuides(
+        interaction.guideLines.x,
+        [left, left + width / 2, left + width],
+        threshold
+      );
+      const snapY = snapToGuides(
+        interaction.guideLines.y,
+        [top, top + height / 2, top + height],
+        threshold
+      );
+      if (snapX) dx += snapX.offset;
+      if (snapY) dy += snapY.offset;
+      const snapped = { left: box.left + dx, top: box.top + dy, width, height };
+      if (snapX) guides = guides.concat(guideSegments("x", snapX.lines, snapped));
+      if (snapY) guides = guides.concat(guideSegments("y", snapY.lines, snapped));
+    }
+    let changed = false;
+    interaction.nodeIds.forEach((id) => {
+      const node = this.findNode(id);
+      const origin = interaction.origins.get(id);
+      if (!node || !origin) return;
+      const nextX = formatNumber(origin.x + dx);
+      const nextY = formatNumber(origin.y + dy);
+      if (nextX === node.x && nextY === node.y) return;
+      node.x = nextX;
+      node.y = nextY;
+      changed = true;
+      this.renderDraggedNode(node);
+    });
+    if (changed) interaction.moved = true;
+    this.renderGuides(guides);
+  }
+  // Live marquee: select every visible node the box touches, added to the
+  // selection the gesture started from.
+  updateMarquee(event) {
+    const interaction = this.interaction;
+    const world = this.clientToWorld(event.clientX, event.clientY);
+    const box = {
+      left: Math.min(interaction.startWorld.x, world.x),
+      top: Math.min(interaction.startWorld.y, world.y),
+      right: Math.max(interaction.startWorld.x, world.x),
+      bottom: Math.max(interaction.startWorld.y, world.y)
+    };
+    clearChildren(this.guidesLayer);
+    this.guidesLayer.appendChild(
+      svgEl("rect", {
+        class: "vd-flowchart-marquee",
+        x: formatNumber(box.left),
+        y: formatNumber(box.top),
+        width: formatNumber(box.right - box.left),
+        height: formatNumber(box.bottom - box.top)
+      })
+    );
+    const hits = this.getVisibleNodes().filter(
+      (node) => node.x <= box.right && node.x + node.width >= box.left && node.y <= box.bottom && node.y + node.height >= box.top
+    ).map((node) => node.id);
+    const ids = [.../* @__PURE__ */ new Set([...interaction.baseIds, ...hits])];
+    const key = ids.join(",");
+    if (key === interaction.lastKey) return;
+    interaction.lastKey = key;
+    this.selectNodes(ids, { primary: hits[hits.length - 1] });
+  }
+  renderGuides(guides) {
+    clearChildren(this.guidesLayer);
+    guides.forEach((guide) => {
+      this.guidesLayer.appendChild(
+        svgEl("line", {
+          class: "vd-flowchart-guide",
+          x1: guide.x1,
+          y1: guide.y1,
+          x2: guide.x2,
+          y2: guide.y2
+        })
+      );
+    });
+  }
   handlePointerMove(event) {
     if (!this.interaction || this.interaction.pointerId !== event.pointerId) return;
     if (this.interaction.kind === "drag-node") {
-      const node = this.findNode(this.interaction.nodeId);
-      if (!node) return;
-      const world = this.clientToWorld(event.clientX, event.clientY);
-      const nextX = formatNumber(world.x - this.interaction.offsetX);
-      const nextY = formatNumber(world.y - this.interaction.offsetY);
-      if (nextX !== node.x || nextY !== node.y) {
-        node.x = nextX;
-        node.y = nextY;
-        this.interaction.moved = true;
-        this.render({ inspector: false, json: false });
-      }
+      this.moveDraggedNodes(event);
+      return;
+    }
+    if (this.interaction.kind === "marquee") {
+      this.updateMarquee(event);
       return;
     }
     if (this.interaction.kind === "resize-node") {
@@ -1867,6 +2916,14 @@ var VdFlowchart = class {
       return;
     }
     if (this.interaction.kind === "connect") {
+      if (!this.interaction.moved) {
+        const travel = Math.hypot(
+          event.clientX - this.interaction.startClientX,
+          event.clientY - this.interaction.startClientY
+        );
+        if (!(travel > PORT_CLICK_SLOP)) return;
+        this.interaction.moved = true;
+      }
       const world = this.clientToWorld(event.clientX, event.clientY);
       const snapTarget = this.findConnectionTarget(
         world,
@@ -1953,10 +3010,19 @@ var VdFlowchart = class {
       }
       return;
     }
+    if (interaction.kind === "marquee") {
+      clearChildren(this.guidesLayer);
+      return;
+    }
     if (interaction.kind === "drag-node") {
+      clearChildren(this.guidesLayer);
       if (interaction.moved) {
         this.render({ inspector: true, json: true });
-        this.emitChange("node:move", { node: deepClone(this.findNode(interaction.nodeId)) });
+        if (interaction.nodeIds.length > 1) {
+          this.emitChange("nodes:move", { nodeIds: [...interaction.nodeIds] });
+        } else {
+          this.emitChange("node:move", { node: deepClone(this.findNode(interaction.nodeId)) });
+        }
       } else {
         this.render({ inspector: false, json: false });
       }
@@ -1972,6 +3038,14 @@ var VdFlowchart = class {
       return;
     }
     if (interaction.kind === "connect") {
+      if (!interaction.moved && this.activeTool !== "arrow") {
+        this.render({ inspector: false, json: false });
+        this.insertBranchNode(interaction.source.nodeId, {
+          direction: PORT_DIRECTIONS[interaction.source.port],
+          edit: true
+        });
+        return;
+      }
       const world = this.clientToWorld(event.clientX || 0, event.clientY || 0);
       const snapTarget = interaction.target ? { node: this.findNode(interaction.target.nodeId), port: interaction.target.port } : this.findConnectionTarget(
         world,
@@ -2047,7 +3121,7 @@ var VdFlowchart = class {
     if (this.readonly) return false;
     if (this.interaction?.kind === "connect" || this.interaction?.kind === "reconnect") return true;
     if (this.activeTool === "arrow") return true;
-    return this.selection?.kind === "node" && this.selection.id === node.id;
+    return this.selection?.kind === "node" && this.selection.id === node.id && !this.hasMultiSelection();
   }
   getMarkerId(markerType, position, strokeWidth) {
     const width = normalizeEdgeStrokeWidth(strokeWidth);
@@ -2070,7 +3144,7 @@ var VdFlowchart = class {
   findConnectionTarget(worldPoint, excludeNodeId, previousSnap = null, referencePoint = null) {
     const snapPadding = CONNECTION_SNAP_PADDING / this.documentData.viewport.scale;
     const hysteresisMargin = CONNECTION_HYSTERESIS / this.documentData.viewport.scale;
-    const best = this.documentData.nodes.reduce((candidate, node) => {
+    const best = this.getVisibleNodes().reduce((candidate, node) => {
       if (node.id === excludeNodeId) return candidate;
       const distanceToBounds2 = getDistanceToNodeBounds(node, worldPoint);
       if (distanceToBounds2 > snapPadding) return candidate;
@@ -2179,7 +3253,10 @@ var VdFlowchart = class {
   updateToolbarLabel() {
     this.zoomLabel.textContent = `${Math.round(this.documentData.viewport.scale * 100)}%`;
   }
-  startTextEdit(nodeId) {
+  // Options: `initialText` replaces the label with typed text (type-to-edit);
+  // `inserted` marks a node created by a keyboard/handle insertion so naming it
+  // shares the insertion's undo step.
+  startTextEdit(nodeId, options = {}) {
     if (this.readonly) return false;
     const node = this.findNode(nodeId);
     if (!node || !isNodeTextEditable(node)) return false;
@@ -2191,9 +3268,10 @@ var VdFlowchart = class {
     }
     this.stopTextEdit({ commit: true });
     this.select({ kind: "node", id: node.id });
+    const replacing = typeof options.initialText === "string";
     const textarea = createElement("textarea", {
       className: `vd-flowchart-text-editor vd-flowchart-text-editor--${node.type}`,
-      value: node.text,
+      value: replacing ? options.initialText : node.text,
       rows: 1
     });
     textarea.setAttribute("data-node-id", node.id);
@@ -2202,17 +3280,7 @@ var VdFlowchart = class {
     textarea.addEventListener("input", () => this.positionTextEditor());
     textarea.addEventListener("pointerdown", (event) => event.stopPropagation());
     textarea.addEventListener("dblclick", (event) => event.stopPropagation());
-    textarea.addEventListener("keydown", (event) => {
-      if (event.key === "Escape") {
-        event.preventDefault();
-        this.stopTextEdit({ commit: false });
-        return;
-      }
-      if (event.key === "Enter" && (event.ctrlKey || event.metaKey)) {
-        event.preventDefault();
-        this.stopTextEdit({ commit: true });
-      }
-    });
+    textarea.addEventListener("keydown", (event) => this.handleTextEditorKeyDown(event, node));
     textarea.addEventListener("blur", () => {
       if (this.textEditor?.textarea === textarea) {
         this.stopTextEdit({ commit: true });
@@ -2221,18 +3289,97 @@ var VdFlowchart = class {
     this.textEditor = {
       nodeId: node.id,
       previousText: node.text,
+      inserted: Boolean(options.inserted),
       textarea
     };
     this.canvasEl.appendChild(textarea);
     this.render({ inspector: true, json: false });
-    window.requestAnimationFrame(() => {
-      if (this.textEditor?.textarea === textarea) {
-        textarea.focus();
+    const focusEditor = () => {
+      if (this.textEditor?.textarea !== textarea) return;
+      textarea.focus();
+      if (replacing) {
+        textarea.setSelectionRange(textarea.value.length, textarea.value.length);
+      } else {
         textarea.select();
       }
+    };
+    focusEditor();
+    window.requestAnimationFrame(() => {
+      if (document.activeElement !== textarea) focusEditor();
+    });
+    return true;
+  }
+  // Inline label editor for a connection, placed on the label anchor
+  // (curve midpoint). Labels render on one line, so Enter always saves.
+  startEdgeLabelEdit(edgeId, options = {}) {
+    if (this.readonly) return false;
+    const edge = this.findEdge(sanitizeId(edgeId));
+    if (!edge) return false;
+    this.stopTextEdit({ commit: true });
+    this.select({ kind: "edge", id: edge.id });
+    const replacing = typeof options.initialText === "string";
+    const textarea = createElement("textarea", {
+      className: "vd-flowchart-text-editor vd-flowchart-text-editor--edge",
+      value: replacing ? options.initialText : edge.label,
+      rows: 1
+    });
+    textarea.setAttribute("data-edge-id", edge.id);
+    textarea.setAttribute("aria-label", "Edit connection label");
+    textarea.spellcheck = false;
+    textarea.addEventListener("input", () => this.positionTextEditor());
+    textarea.addEventListener("pointerdown", (event) => event.stopPropagation());
+    textarea.addEventListener("dblclick", (event) => event.stopPropagation());
+    textarea.addEventListener("keydown", (event) => {
+      if (event.isComposing) return;
+      if (event.key === "Escape" || event.key === "Enter") {
+        event.preventDefault();
+        this.stopTextEdit({ commit: event.key === "Enter" });
+        this.canvasEl.focus();
+      }
+    });
+    textarea.addEventListener("blur", () => {
+      if (this.textEditor?.textarea === textarea) this.stopTextEdit({ commit: true });
+    });
+    this.textEditor = { nodeId: null, edgeId: edge.id, previousText: edge.label, textarea };
+    this.canvasEl.appendChild(textarea);
+    this.render({ inspector: true, json: false });
+    const focusEditor = () => {
+      if (this.textEditor?.textarea !== textarea) return;
+      textarea.focus();
+      if (replacing) textarea.setSelectionRange(textarea.value.length, textarea.value.length);
+      else textarea.select();
+    };
+    focusEditor();
+    window.requestAnimationFrame(() => {
+      if (document.activeElement !== textarea) focusEditor();
     });
     return true;
   }
+  handleTextEditorKeyDown(event, node) {
+    if (event.isComposing) return;
+    const mindmap = this.keyboardShortcuts === "mindmap";
+    if (event.key === "Escape") {
+      event.preventDefault();
+      this.stopTextEdit({ commit: false });
+      this.canvasEl.focus();
+      return;
+    }
+    if (event.key === "Enter") {
+      const modKey = event.ctrlKey || event.metaKey;
+      const commits = modKey || mindmap && node.type !== "textbox" && !event.shiftKey;
+      if (!commits) return;
+      event.preventDefault();
+      this.stopTextEdit({ commit: true });
+      this.canvasEl.focus();
+      return;
+    }
+    if (event.key === "Tab" && mindmap && !event.shiftKey && !event.altKey && !event.ctrlKey) {
+      event.preventDefault();
+      this.stopTextEdit({ commit: true });
+      this.canvasEl.focus();
+      this.insertBranchNode(node.id, { edit: true });
+    }
+  }
   stopTextEdit(options = {}) {
     if (!this.textEditor) return false;
     const commit = options.commit !== false;
@@ -2240,12 +3387,26 @@ var VdFlowchart = class {
     const nextText = editor.textarea.value;
     this.textEditor = null;
     editor.textarea.remove();
+    if (editor.edgeId) {
+      const label = nextText.replace(/\s*\n\s*/g, " ").trim();
+      if (commit && !this.readonly && label !== editor.previousText) {
+        this.updateEdge(editor.edgeId, { label }, { inspector: true, reason: "edge:update" });
+      } else {
+        this.render({ scene: true, inspector: false, json: false });
+      }
+      return true;
+    }
     if (commit && !this.readonly && nextText !== editor.previousText) {
-      this.updateNode(
-        editor.nodeId,
-        { text: nextText },
-        { inspector: true, reason: "node:update" }
-      );
+      this.coalesceInsertedText = editor.inserted;
+      try {
+        this.updateNode(
+          editor.nodeId,
+          { text: nextText },
+          { inspector: true, reason: "node:update" }
+        );
+      } finally {
+        this.coalesceInsertedText = false;
+      }
     } else {
       this.render({ scene: true, inspector: false, json: false });
     }
@@ -2253,6 +3414,10 @@ var VdFlowchart = class {
   }
   positionTextEditor() {
     if (!this.textEditor) return;
+    if (this.textEditor.edgeId) {
+      this.positionEdgeLabelEditor();
+      return;
+    }
     const node = this.findNode(this.textEditor.nodeId);
     if (!node) {
       this.stopTextEdit({ commit: false });
@@ -2276,6 +3441,28 @@ var VdFlowchart = class {
     textarea.style.lineHeight = `${formatNumber(lineHeight)}px`;
     textarea.style.padding = `${formatNumber(verticalPadding)}px ${formatNumber(horizontalPadding)}px`;
   }
+  positionEdgeLabelEditor() {
+    const edge = this.findEdge(this.textEditor.edgeId);
+    const fromNode = edge && this.findNode(edge.from.nodeId);
+    const toNode = edge && this.findNode(edge.to.nodeId);
+    if (!edge || !fromNode || !toNode) {
+      this.stopTextEdit({ commit: false });
+      return;
+    }
+    const { labelX, labelY } = buildEdgePath(edge, fromNode, toNode);
+    const viewport = this.documentData.viewport;
+    const textarea = this.textEditor.textarea;
+    const fontSize = Math.max(11, 13 * viewport.scale);
+    const width = clamp(textarea.value.length * fontSize * 0.62 + 28, 96, 280);
+    const height = fontSize * 1.4 + 12;
+    textarea.style.left = `${formatNumber(viewport.x + labelX * viewport.scale - width / 2)}px`;
+    textarea.style.top = `${formatNumber(viewport.y + (labelY - 8) * viewport.scale - height / 2)}px`;
+    textarea.style.width = `${formatNumber(width)}px`;
+    textarea.style.height = `${formatNumber(height)}px`;
+    textarea.style.fontSize = `${formatNumber(fontSize)}px`;
+    textarea.style.lineHeight = `${formatNumber(fontSize * 1.4)}px`;
+    textarea.style.padding = "6px 10px";
+  }
   render(options = {}) {
     if (this.destroyed) return;
     const shouldRenderScene = options.scene !== false;
@@ -2284,11 +3471,14 @@ var VdFlowchart = class {
     if (shouldRenderScene) this.renderScene();
     if (shouldRenderInspector) this.renderSelectionPanel();
     if (shouldRenderJson) this.syncJsonTextarea();
+    if (shouldRenderInspector) this.renderGraphOutline();
     this.updateToolbarLabel();
     this.updatePaletteState();
     this.positionTextEditor();
+    this.scheduleMinimap();
   }
   renderScene() {
+    this.syncSelectedNodeIds();
     const viewport = this.documentData.viewport;
     this.world.setAttribute(
       "transform",
@@ -2298,16 +3488,35 @@ var VdFlowchart = class {
     clearChildren(this.previewLayer);
     clearChildren(this.nodesLayer);
     clearChildren(this.overlayLayer);
-    const nodeMap = new Map(this.documentData.nodes.map((node) => [node.id, node]));
+    const hidden = this.getHiddenNodeIds();
+    this.sceneHidden = hidden;
+    this.sceneOutgoing = this.getOutgoingMap();
+    const nodeMap = new Map(
+      this.documentData.nodes.filter((node) => !hidden.has(node.id)).map((node) => [node.id, node])
+    );
+    this.sceneNodeMap = nodeMap;
+    this.nodeElements = /* @__PURE__ */ new Map();
+    this.edgeElements = /* @__PURE__ */ new Map();
+    this.incidentEdges = /* @__PURE__ */ new Map();
     this.documentData.edges.forEach((edge) => {
       const edgeElement = this.renderEdge(edge, nodeMap);
-      if (edgeElement) this.edgesLayer.appendChild(edgeElement);
+      if (edgeElement) {
+        this.edgesLayer.appendChild(edgeElement);
+        this.edgeElements.set(edge.id, edgeElement);
+        for (const id of /* @__PURE__ */ new Set([edge.from.nodeId, edge.to.nodeId])) {
+          if (!this.incidentEdges.has(id)) this.incidentEdges.set(id, []);
+          this.incidentEdges.get(id).push(edge);
+        }
+      }
     });
     if (this.interaction?.kind === "connect" || this.interaction?.kind === "reconnect") {
       this.previewLayer.appendChild(this.renderPreviewEdge(this.interaction));
     }
     this.documentData.nodes.forEach((node) => {
-      this.nodesLayer.appendChild(this.renderNode(node));
+      if (hidden.has(node.id)) return;
+      const element = this.renderNode(node);
+      this.nodesLayer.appendChild(element);
+      this.nodeElements.set(node.id, element);
     });
     if (this.reconnectEdgeId && !this.readonly) {
       const reconnectEdge = this.findEdge(this.reconnectEdgeId);
@@ -2323,6 +3532,25 @@ var VdFlowchart = class {
     }
     this.syncConnectingState();
   }
+  // Drag frames change one translation and its connected paths. Keep unrelated
+  // SVG elements intact; the release event still refreshes inspector/history.
+  renderDraggedNode(node) {
+    const element = this.nodeElements?.get(node.id);
+    if (!element) {
+      this.render({ inspector: false, json: false });
+      return;
+    }
+    element.setAttribute("transform", `translate(${formatNumber(node.x)} ${formatNumber(node.y)})`);
+    element.classList.add("is-dragging");
+    for (const edge of this.incidentEdges.get(node.id) || []) {
+      const previous = this.edgeElements.get(edge.id);
+      const next = this.renderEdge(edge, this.sceneNodeMap);
+      if (previous && next) {
+        previous.replaceWith(next);
+        this.edgeElements.set(edge.id, next);
+      }
+    }
+  }
   applyEdgeMarkers(pathElement, edge) {
     if (edge.startMarker && edge.startMarker !== "none") {
       pathElement.setAttribute(
@@ -2373,7 +3601,7 @@ var VdFlowchart = class {
     });
     group.appendChild(visiblePath);
     group.appendChild(hitPath);
-    if (edge.label) {
+    if (edge.label && this.textEditor?.edgeId !== edge.id) {
       const label = svgEl("text", {
         class: "vd-flowchart-edge-label",
         x: edgePath.labelX,
@@ -2434,8 +3662,9 @@ var VdFlowchart = class {
     });
   }
   renderNode(node) {
-    const selected = this.selection?.kind === "node" && this.selection.id === node.id;
-    const dragging = this.interaction?.kind === "drag-node" && this.interaction.nodeId === node.id;
+    const selected = this.isNodeSelected(node.id);
+    const soloSelected = selected && !this.hasMultiSelection();
+    const dragging = this.interaction?.kind === "drag-node" && this.interaction.nodeIds.includes(node.id);
     const resizing = this.interaction?.kind === "resize-node" && this.interaction.nodeId === node.id;
     const editing = this.textEditor?.nodeId === node.id;
     const group = svgEl("g", {
@@ -2456,12 +3685,29 @@ var VdFlowchart = class {
     group.appendChild(hitbox);
     group.appendChild(this.renderNodeShape(node));
     group.appendChild(this.renderNodeText(node));
-    if (selected && !this.readonly && isNodeResizable(node)) {
+    const scale = this.documentData.viewport.scale || 1;
+    if (soloSelected && !this.readonly && SELECTION_BOX_TYPES.has(node.type)) {
+      const outset = SELECTION_OUTSET / scale;
+      group.appendChild(
+        svgEl("rect", {
+          class: "vd-flowchart-selection-box",
+          x: -outset,
+          y: -outset,
+          width: node.width + outset * 2,
+          height: node.height + outset * 2
+        })
+      );
+    }
+    if (soloSelected && !this.readonly && isNodeResizable(node)) {
       group.appendChild(this.renderResizeControls(node));
     }
-    const scale = this.documentData.viewport.scale || 1;
+    const collapseToggle = this.renderCollapseToggle(node, soloSelected);
+    if (this.readonly) {
+      if (collapseToggle) group.appendChild(collapseToggle);
+      return group;
+    }
     FLOWCHART_PORTS.forEach((port) => {
-      const position = getPortPosition({ ...node, x: 0, y: 0 }, port);
+      const position = getPortHandlePosition({ ...node, x: 0, y: 0 }, port, scale);
       const portGroup = svgEl("g", {
         class: `vd-flowchart-port-group${portsVisible ? " is-visible" : ""}`,
         "data-node-id": node.id,
@@ -2483,15 +3729,68 @@ var VdFlowchart = class {
           r: CONNECTION_PORT_RADIUS / scale
         })
       );
+      const arm = (CONNECTION_PORT_RADIUS - 2.5) / scale;
+      portGroup.appendChild(
+        svgEl("path", {
+          class: "vd-flowchart-port-plus",
+          d: `M ${formatNumber(position.x - arm)} ${formatNumber(position.y)} H ${formatNumber(position.x + arm)} M ${formatNumber(position.x)} ${formatNumber(position.y - arm)} V ${formatNumber(position.y + arm)}`
+        })
+      );
       group.appendChild(portGroup);
     });
+    if (collapseToggle) group.appendChild(collapseToggle);
+    return group;
+  }
+  // "+N" on a collapsed node, or "−" on a single selected node with children,
+  // placed beyond the connection handle on the side its branch leaves from.
+  renderCollapseToggle(node, soloSelected) {
+    const outgoing = this.sceneOutgoing || this.getOutgoingMap();
+    const childIds = (outgoing.get(node.id) || []).filter((id) => id !== node.id);
+    if (!childIds.length) return null;
+    const count = node.collapsed ? this.countCollapsedDescendants(
+      node.id,
+      this.sceneHidden || this.getHiddenNodeIds(),
+      outgoing
+    ) : 0;
+    if (!node.collapsed && !(soloSelected && !this.readonly)) return null;
+    const sides = /* @__PURE__ */ new Map();
+    this.documentData.edges.forEach((edge) => {
+      if (edge.from.nodeId !== node.id || edge.to.nodeId === node.id) return;
+      sides.set(edge.from.port, (sides.get(edge.from.port) || 0) + 1);
+    });
+    const port = [...sides].sort((a, b) => b[1] - a[1])[0]?.[0] || DIRECTION_PORTS[this.getGrowthDirection(node)];
+    const scale = this.documentData.viewport.scale || 1;
+    const anchor = getPortPosition({ ...node, x: 0, y: 0 }, port);
+    const normal = getPortNormal(port);
+    const offset = COLLAPSE_TOGGLE_OFFSET / scale;
+    const cx = formatNumber(anchor.x + normal.x * offset);
+    const cy = formatNumber(anchor.y + normal.y * offset);
+    const label = node.collapsed ? `+${count}` : "\u2212";
+    const radius = (node.collapsed && label.length > 2 ? 12 : 9) / scale;
+    const group = svgEl("g", {
+      class: `vd-flowchart-collapse-toggle${node.collapsed ? " is-collapsed" : ""}`,
+      "data-collapse-toggle": node.id
+    });
+    const title = svgEl("title");
+    title.textContent = node.collapsed ? `Expand ${count} hidden nodes` : "Collapse branch";
+    group.appendChild(title);
+    group.appendChild(svgEl("circle", { cx, cy, r: formatNumber(radius) }));
+    const text = svgEl("text", {
+      x: cx,
+      y: cy,
+      "font-size": formatNumber(10 / scale),
+      "text-anchor": "middle",
+      "dominant-baseline": "central"
+    });
+    text.textContent = label;
+    group.appendChild(text);
     return group;
   }
   renderResizeControls(node) {
     const scale = this.documentData.viewport.scale || 1;
     const zone = 14 / scale;
     const cornerZone = 22 / scale;
-    const handleSize = 9 / scale;
+    const handleSize = RESIZE_HANDLE_SIZE / scale;
     const gap = RESIZE_PORT_GAP / scale;
     const group = svgEl("g", { class: "vd-flowchart-resize-controls" });
     const zones = {
@@ -2521,12 +3820,6 @@ var VdFlowchart = class {
     };
     RESIZE_HANDLES.forEach((handle) => {
       const zoneRect = zones[handle];
-      const position = getResizeHandlePosition(node, handle);
-      const dotOffset = 8 / scale;
-      if (handle.includes("e")) position.x += dotOffset;
-      if (handle.includes("w")) position.x -= dotOffset;
-      if (handle.includes("n")) position.y -= dotOffset;
-      if (handle.includes("s")) position.y += dotOffset;
       const cursor = getResizeCursor(handle);
       const zoneSegments = [];
       if (handle === "e" || handle === "w") {
@@ -2561,14 +3854,19 @@ var VdFlowchart = class {
         });
         group.appendChild(hit);
       });
+      if (handle.length === 1) return;
+      const position = getResizeHandlePosition(node, handle);
+      const outset = SELECTION_OUTSET / scale;
+      position.x += handle.includes("e") ? outset : -outset;
+      position.y += handle.includes("s") ? outset : -outset;
       const dot = svgEl("rect", {
         class: "vd-flowchart-resize-handle",
         x: position.x - handleSize / 2,
         y: position.y - handleSize / 2,
         width: handleSize,
         height: handleSize,
-        rx: handleSize / 3,
-        ry: handleSize / 3,
+        rx: handleSize / 5,
+        ry: handleSize / 5,
         "data-node-id": node.id,
         "data-resize-handle": handle,
         style: `cursor: ${cursor}`
@@ -2697,6 +3995,16 @@ var VdFlowchart = class {
       );
       return;
     }
+    if (this.hasMultiSelection()) {
+      this.selectionMeta.textContent = `${this.selectedNodeIds.size} nodes selected`;
+      this.selectionFields.appendChild(
+        createElement("p", {
+          className: "vd-flowchart-selection-empty",
+          text: "Drag, nudge with Alt+Arrow, copy, duplicate, or delete them together."
+        })
+      );
+      return;
+    }
     if (this.selection.kind === "node") {
       const node = this.findNode(this.selection.id);
       if (!node) {
@@ -2811,16 +4119,69 @@ var VdFlowchart = class {
   }
   select(selection) {
     const next = selection && selection.id && selection.kind ? { kind: selection.kind, id: selection.id } : null;
-    const previousKey = this.selection ? `${this.selection.kind}:${this.selection.id}` : "";
-    const nextKey = next ? `${next.kind}:${next.id}` : "";
-    this.selection = next;
-    if (previousKey !== nextKey) {
+    this.applySelection(next, next?.kind === "node" ? [next.id] : []);
+  }
+  // Single funnel for selection changes: `selection` is the primary item and
+  // `selectedNodeIds` every selected node (the primary one included).
+  applySelection(primary, nodeIds) {
+    const previousKey = this.getSelectionKey();
+    this.selection = primary;
+    this.selectedNodeIds = new Set(nodeIds);
+    if (primary?.kind === "node") this.selectedNodeIds.add(primary.id);
+    if (previousKey !== this.getSelectionKey()) {
+      this.edgeCycleAnchor = null;
       this.render({ scene: true, inspector: true, json: false });
-      this.emit("select", { selection: this.getSelectionSnapshot() });
+      this.emit("select", {
+        selection: this.getSelectionSnapshot(),
+        nodeIds: this.getSelectedNodeIds()
+      });
       return;
     }
     this.render({ scene: true, inspector: false, json: false });
   }
+  getSelectionKey() {
+    const primary = this.selection ? `${this.selection.kind}:${this.selection.id}` : "";
+    return `${primary}|${[...this.selectedNodeIds || []].sort().join(",")}`;
+  }
+  // Keep the set valid after mutations that bypass applySelection (undo,
+  // load, removal): drop missing nodes and keep the primary node in the set.
+  syncSelectedNodeIds() {
+    if (this.selection?.kind !== "node") {
+      this.selectedNodeIds = /* @__PURE__ */ new Set();
+      return;
+    }
+    const existing = new Set(this.documentData.nodes.map((node) => node.id));
+    const hidden = this.getHiddenNodeIds();
+    this.selectedNodeIds = new Set(
+      [...this.selectedNodeIds || []].filter((id) => existing.has(id) && !hidden.has(id))
+    );
+    this.selectedNodeIds.add(this.selection.id);
+  }
+  getSelectedNodeIds() {
+    return [...this.selectedNodeIds || []];
+  }
+  isNodeSelected(nodeId) {
+    return Boolean(this.selectedNodeIds?.has(nodeId));
+  }
+  hasMultiSelection() {
+    return (this.selectedNodeIds?.size || 0) > 1;
+  }
+  /** Select several nodes; `primary` (default: the last id) drives single-node UI. */
+  selectNodes(nodeIds, options = {}) {
+    const existing = new Set(this.documentData.nodes.map((node) => node.id));
+    const ids = [...new Set((nodeIds || []).map(sanitizeId))].filter((id) => existing.has(id));
+    const primaryId = ids.includes(options.primary) ? options.primary : ids[ids.length - 1];
+    this.applySelection(primaryId ? { kind: "node", id: primaryId } : null, ids);
+    return this;
+  }
+  toggleNodeSelection(nodeId) {
+    const ids = this.selection?.kind === "node" ? this.getSelectedNodeIds() : [];
+    if (ids.includes(nodeId)) {
+      const rest = ids.filter((id) => id !== nodeId);
+      return this.selectNodes(rest, { primary: rest[rest.length - 1] });
+    }
+    return this.selectNodes([...ids, nodeId], { primary: nodeId });
+  }
   selectNode(nodeId) {
     this.select({ kind: "node", id: sanitizeId(nodeId) });
     return this;
@@ -2841,6 +4202,69 @@ var VdFlowchart = class {
   findNode(nodeId) {
     return this.documentData.nodes.find((node) => node.id === nodeId) || null;
   }
+  getHiddenNodeIds() {
+    return computeHiddenNodeIds(this.documentData.nodes, this.documentData.edges);
+  }
+  getVisibleNodes() {
+    const hidden = this.getHiddenNodeIds();
+    return hidden.size ? this.documentData.nodes.filter((node) => !hidden.has(node.id)) : this.documentData.nodes;
+  }
+  isNodeHidden(nodeId) {
+    return this.getHiddenNodeIds().has(nodeId);
+  }
+  getOutgoingMap() {
+    const outgoing = /* @__PURE__ */ new Map();
+    this.documentData.edges.forEach((edge) => {
+      if (!outgoing.has(edge.from.nodeId)) outgoing.set(edge.from.nodeId, []);
+      outgoing.get(edge.from.nodeId).push(edge.to.nodeId);
+    });
+    return outgoing;
+  }
+  // Hidden nodes under one collapsed node (its "+N" count).
+  countCollapsedDescendants(nodeId, hidden = this.getHiddenNodeIds(), outgoing = this.getOutgoingMap()) {
+    const seen = /* @__PURE__ */ new Set();
+    const queue = [nodeId];
+    for (let index = 0; index < queue.length; index += 1) {
+      (outgoing.get(queue[index]) || []).forEach((childId) => {
+        if (seen.has(childId) || !hidden.has(childId)) return;
+        seen.add(childId);
+        queue.push(childId);
+      });
+    }
+    return seen.size;
+  }
+  setCollapsed(nodeId, collapsed) {
+    if (this.readonly) return false;
+    const node = this.findNode(sanitizeId(nodeId));
+    if (!node) return false;
+    const next = Boolean(collapsed);
+    if (Boolean(node.collapsed) === next) return false;
+    if (next && !this.getChildNodes(node.id).length) return false;
+    if (next) node.collapsed = true;
+    else delete node.collapsed;
+    if (this.selection?.kind === "node") {
+      const hidden = this.getHiddenNodeIds();
+      const visibleIds = this.getSelectedNodeIds().filter((id) => !hidden.has(id));
+      if (hidden.has(this.selection.id)) {
+        this.select({ kind: "node", id: node.id });
+      } else if (visibleIds.length !== this.selectedNodeIds.size) {
+        this.selectNodes(visibleIds, { primary: this.selection.id });
+      }
+    } else if (this.selection?.kind === "edge") {
+      const edge = this.findEdge(this.selection.id);
+      const hidden = this.getHiddenNodeIds();
+      if (edge && (hidden.has(edge.from.nodeId) || hidden.has(edge.to.nodeId))) {
+        this.select({ kind: "node", id: node.id });
+      }
+    }
+    this.render({ inspector: true, json: true });
+    this.emitChange("node:collapse", { node: deepClone(node) });
+    return true;
+  }
+  toggleCollapsed(nodeId) {
+    const node = this.findNode(sanitizeId(nodeId));
+    return node ? this.setCollapsed(node.id, !node.collapsed) : false;
+  }
   findEdge(edgeId) {
     return this.documentData.edges.find((edge) => edge.id === edgeId) || null;
   }
@@ -2851,7 +4275,8 @@ var VdFlowchart = class {
   }
   emitChange(reason, extra = {}) {
     if (this.historyEnabled && !this.isApplyingHistory) {
-      this.recordHistory(reason);
+      if (this.historyBatchDepth > 0) this.historyBatchDirty = true;
+      else this.recordHistory(reason);
     }
     this.syncJsonTextarea();
     this.emit("change", {
@@ -2895,7 +4320,9 @@ var VdFlowchart = class {
     const snapshot = this.toJSON();
     const targetKey = this.selection ? `${this.selection.kind}:${this.selection.id}` : "";
     const top = this.history[this.historyIndex];
-    const canCoalesce = Boolean(top) && this.historyIndex === this.history.length - 1 && COALESCING_REASONS.has(reason) && top.reason === reason && top.targetKey === targetKey;
+    const atTip = Boolean(top) && this.historyIndex === this.history.length - 1;
+    const namesInsertedNode = this.coalesceInsertedText && top?.reason === "node:insert" && reason === "node:update";
+    const canCoalesce = atTip && top.targetKey === targetKey && (namesInsertedNode || COALESCING_REASONS.has(reason) && top.reason === reason);
     if (canCoalesce) {
       top.snapshot = snapshot;
       return;
@@ -3011,19 +4438,180 @@ var VdFlowchart = class {
     const parent = this.findNode(sanitizeId(parentId));
     if (!parent) return null;
     const { direction = "right", distance, angle, edge: edgeOptions, ...nodeOptions } = options;
-    const node = this.addNode({
-      ...nodeOptions,
-      relativeTo: { node: parent.id, direction, distance, angle }
+    return this.batchHistory("node:add-child", () => {
+      const node = this.addNode({
+        ...nodeOptions,
+        relativeTo: { node: parent.id, direction, distance, angle }
+      });
+      const edge = this.addEdge({
+        from: parent.id,
+        to: node.id,
+        autoPort: true,
+        endMarker: "arrow",
+        ...isPlainObject(edgeOptions) ? edgeOptions : {}
+      });
+      this.select({ kind: "node", id: node.id });
+      return { node, edge };
     });
-    const edge = this.addEdge({
-      from: parent.id,
-      to: node.id,
-      autoPort: true,
-      endMarker: "arrow",
-      ...isPlainObject(edgeOptions) ? edgeOptions : {}
+  }
+  // Run `fn` with history recording suspended, then record a single entry for
+  // everything it changed (change events still fire for each mutation).
+  batchHistory(reason, fn) {
+    this.historyBatchDepth += 1;
+    let result;
+    try {
+      result = fn();
+    } finally {
+      this.historyBatchDepth -= 1;
+    }
+    if (this.historyBatchDepth === 0 && this.historyBatchDirty) {
+      this.historyBatchDirty = false;
+      if (this.historyEnabled && !this.isApplyingHistory) this.recordHistory(reason);
+    }
+    return result;
+  }
+  // Mind-map structure: a node's parent is the source of its first incoming
+  // edge; its children are the targets of its outgoing edges. The side a
+  // branch is on is the port its edge leaves the parent from, which is what
+  // the user sees (centre geometry is ambiguous for diagonal nodes).
+  getParentEdge(nodeId) {
+    return this.documentData.edges.find(
+      (edge) => edge.to.nodeId === nodeId && edge.from.nodeId !== nodeId
+    ) || null;
+  }
+  getParentNode(nodeId) {
+    const edge = this.getParentEdge(nodeId);
+    return edge ? this.findNode(edge.from.nodeId) : null;
+  }
+  getChildNodes(nodeId, direction = null) {
+    const port = direction ? DIRECTION_PORTS[direction] : null;
+    const ids = /* @__PURE__ */ new Set();
+    this.documentData.edges.forEach((edge) => {
+      if (edge.from.nodeId !== nodeId || edge.to.nodeId === nodeId) return;
+      if (!port || edge.from.port === port) ids.add(edge.to.nodeId);
     });
-    this.select({ kind: "node", id: node.id });
-    return { node, edge };
+    return this.documentData.nodes.filter((node) => ids.has(node.id));
+  }
+  // Direction a branch grows from `node`: the side its parent edge leaves
+  // from, or the emptier horizontal side for a root.
+  getGrowthDirection(node) {
+    const parentEdge = this.getParentEdge(node.id);
+    if (parentEdge) return PORT_DIRECTIONS[parentEdge.from.port] || "right";
+    const right = this.getChildNodes(node.id, "right").length;
+    const left = this.getChildNodes(node.id, "left").length;
+    return left < right ? "left" : "right";
+  }
+  // Shape for a new branch node: copy a sibling when there is one, otherwise
+  // the parent's box shape, falling back to a rounded step.
+  getBranchTemplate(parent, sibling) {
+    const source = sibling || (["rounded-rect", "rect", "textbox"].includes(parent.type) ? parent : null) || null;
+    if (source) return { type: source.type, width: source.width, height: source.height };
+    const spec = DEFAULT_NODE_SPECS["rounded-rect"];
+    return { type: "rounded-rect", width: spec.width, height: spec.height };
+  }
+  /**
+   * Add a node connected from `parentId` on the `direction` side (default: the
+   * branch's growth direction), stacked after `anchorId` or the last sibling on
+   * that side. The node and its edge are one undo step; the new edge copies a
+   * sibling's (or the parent's incoming) edge style. With `edit: true` the
+   * label editor opens with the text selected.
+   */
+  insertBranchNode(parentId, options = {}) {
+    if (this.readonly) return null;
+    const parent = this.findNode(sanitizeId(parentId));
+    if (!parent) return null;
+    const direction = DIRECTION_PORTS[options.direction] ? options.direction : this.getGrowthDirection(parent);
+    const siblings = this.getChildNodes(parent.id, direction);
+    const anchor = options.anchorId ? this.findNode(sanitizeId(options.anchorId)) : null;
+    const lastSibling = siblings[siblings.length - 1] || null;
+    const template = this.getBranchTemplate(parent, anchor || lastSibling);
+    const position = placeBranchNode({
+      nodes: this.documentData.nodes,
+      parent,
+      siblings,
+      direction,
+      size: template,
+      anchor,
+      before: Boolean(options.before)
+    });
+    const styleSource = this.documentData.edges.find(
+      (edge) => edge.from.nodeId === parent.id && edge.to.nodeId === (anchor || lastSibling)?.id
+    ) || this.documentData.edges.find((edge) => edge.to.nodeId === parent.id);
+    const edgeStyle = styleSource ? {
+      route: styleSource.route,
+      strokeWidth: styleSource.strokeWidth,
+      startMarker: styleSource.startMarker,
+      endMarker: styleSource.endMarker
+    } : { endMarker: "arrow" };
+    const result = this.batchHistory("node:insert", () => {
+      if (parent.collapsed) delete parent.collapsed;
+      const node = this.addNode({ ...template, x: position.x, y: position.y });
+      const edge = this.addEdge({
+        from: { nodeId: parent.id, port: DIRECTION_PORTS[direction] },
+        to: { nodeId: node.id, port: DIRECTION_PORTS[oppositeDirection(direction)] },
+        ...edgeStyle
+      });
+      if (edge && anchor) this.placeEdgeBySibling(edge.id, parent.id, anchor.id, options.before);
+      if (this.autoLayout && this.layoutMode !== "grid") this.layout(this.layoutMode);
+      this.select({ kind: "node", id: node.id });
+      return { node, edge };
+    });
+    this.revealNode(result.node.id);
+    if (options.edit) this.startTextEdit(result.node.id, { inserted: true });
+    return result;
+  }
+  // Tree and radial layouts order children by connection order, so a sibling's
+  // connection goes right after (or before) its anchor's instead of last.
+  placeEdgeBySibling(edgeId, parentId, anchorId, before = false) {
+    const edges = this.documentData.edges;
+    const fromIndex = edges.findIndex((edge) => edge.id === edgeId);
+    if (fromIndex === -1) return;
+    const [moved] = edges.splice(fromIndex, 1);
+    const anchorIndex = edges.findIndex(
+      (edge) => edge.from.nodeId === parentId && edge.to.nodeId === anchorId
+    );
+    if (anchorIndex === -1) edges.push(moved);
+    else edges.splice(before ? anchorIndex : anchorIndex + 1, 0, moved);
+  }
+  // Insert a sibling after (or before) `nodeId`; a node without a parent gets a
+  // child instead, which is what Enter on a mind-map root means.
+  insertSiblingNode(nodeId, options = {}) {
+    if (this.readonly) return null;
+    const node = this.findNode(sanitizeId(nodeId));
+    if (!node) return null;
+    const parentEdge = this.getParentEdge(node.id);
+    const parent = parentEdge ? this.findNode(parentEdge.from.nodeId) : null;
+    if (!parent) return this.insertBranchNode(node.id, { edit: options.edit });
+    return this.insertBranchNode(parent.id, {
+      direction: PORT_DIRECTIONS[parentEdge.from.port],
+      anchorId: node.id,
+      before: Boolean(options.before),
+      edit: options.edit
+    });
+  }
+  // Pan just enough to bring a node fully into view (with a small margin).
+  revealNode(nodeId) {
+    const node = this.findNode(nodeId);
+    const width = this.canvasEl.clientWidth;
+    const height = this.canvasEl.clientHeight;
+    if (!node || !width || !height) return;
+    const viewport = this.documentData.viewport;
+    const margin = 32;
+    const left = viewport.x + node.x * viewport.scale;
+    const top = viewport.y + node.y * viewport.scale;
+    const right = left + node.width * viewport.scale;
+    const bottom = top + node.height * viewport.scale;
+    let dx = 0;
+    let dy = 0;
+    if (right > width - margin) dx = width - margin - right;
+    if (left + dx < margin) dx = margin - left;
+    if (bottom > height - margin) dy = height - margin - bottom;
+    if (top + dy < margin) dy = margin - top;
+    if (!dx && !dy) return;
+    viewport.x = formatNumber(viewport.x + dx);
+    viewport.y = formatNumber(viewport.y + dy);
+    this.render({ inspector: false, json: true });
+    this.emitViewportChange("viewport:pan");
   }
   // Arrange nodes with a built-in layout. Positions are computed by the pure
   // computeLayout() module, then applied in place (NOT via load(), which would
@@ -3271,6 +4859,9 @@ var VdFlowchart = class {
   }
   deleteSelection() {
     if (!this.selection || this.readonly) return false;
+    if (this.hasMultiSelection()) {
+      return this.removeNodeIds(new Set(this.getSelectedNodeIds()), "node:remove");
+    }
     if (this.selection.kind === "node") return this.removeNode(this.selection.id);
     return this.removeEdge(this.selection.id);
   }
@@ -3299,10 +4890,11 @@ var VdFlowchart = class {
     return this;
   }
   fitView() {
-    if (!this.documentData.nodes.length) {
+    const nodes = this.getVisibleNodes();
+    if (!nodes.length) {
       return this.resetView();
     }
-    const bounds = getBounds(this.documentData.nodes);
+    const bounds = getBounds(nodes);
     const width = this.canvasEl.clientWidth || 800;
     const height = this.canvasEl.clientHeight || 560;
     const padding = 80;
@@ -3337,20 +4929,77 @@ var VdFlowchart = class {
     this.emitChange("clear");
     return this;
   }
+  updateOptions(options = {}) {
+    if (this.destroyed) return this;
+    if ("readonly" in options) {
+      if (options.readonly && !this.readonly) {
+        this.stopTextEdit({ commit: true });
+        this.interaction = null;
+        this.activeTool = null;
+        this.reconnectEdgeId = null;
+      }
+      this.readonly = Boolean(options.readonly);
+      this.root.classList.toggle("vd-flowchart-readonly", this.readonly);
+      this.arrangeSelect.disabled = this.readonly;
+      this.clearButton.disabled = this.readonly;
+      this.loadJsonButton.disabled = this.readonly;
+    }
+    if ("gridSize" in options) {
+      this.gridSize = clamp(toFiniteNumber(options.gridSize, DEFAULT_GRID_SIZE), 12, 64);
+      const pattern = this.svg.querySelector("pattern");
+      pattern.setAttribute("width", this.gridSize);
+      pattern.setAttribute("height", this.gridSize);
+      pattern.querySelector("path").setAttribute("d", `M ${this.gridSize} 0 L 0 0 0 ${this.gridSize}`);
+    }
+    if ("autoFit" in options) this.autoFit = Boolean(options.autoFit);
+    if ("keyboardShortcuts" in options) {
+      this.keyboardShortcuts = normalizeKeyboardShortcuts(options.keyboardShortcuts);
+    }
+    if ("snapGuides" in options) this.snapGuides = options.snapGuides !== false;
+    if ("minimap" in options) this.setMinimapEnabled(options.minimap !== false);
+    if ("autoLayout" in options) this.autoLayout = Boolean(options.autoLayout);
+    this.syncCanvasLabel();
+    if (this.shortcutsHelpOpen) this.renderShortcutsHelp();
+    if ("history" in options && options.history !== false !== this.historyEnabled) {
+      this.historyEnabled = options.history !== false;
+      this.history = [];
+      this.historyIndex = -1;
+      this.seedHistory();
+    }
+    if ("historyLimit" in options) {
+      this.historyLimit = Math.max(1, Math.floor(toFiniteNumber(options.historyLimit, 100)));
+      if (this.history.length > this.historyLimit) {
+        const start = Math.max(0, this.historyIndex - this.historyLimit + 1);
+        this.history = this.history.slice(start, start + this.historyLimit);
+        this.historyIndex -= start;
+      }
+    }
+    this.render();
+    this.updateHistoryButtons();
+    return this;
+  }
   load(data, options = {}) {
+    const documentData = normalizeDocument(data);
+    if (options.silent && JSON.stringify(documentData) === JSON.stringify(this.documentData)) {
+      return this;
+    }
     this.stopTextEdit({ commit: false });
     this.activeTool = null;
     this.reconnectEdgeId = null;
     const previousSelection = this.selection;
-    this.documentData = normalizeDocument(data);
+    this.documentData = documentData;
     this.selection = this.resolvePreservedSelection(previousSelection, options.preserveSelection);
     this.render();
-    this.emitChange("load");
+    if (options.silent) {
+      if (this.historyEnabled) this.recordHistory("load");
+    } else {
+      this.emitChange("load");
+    }
     return this;
   }
   toJSON() {
     return deepClone({
-      version: VD_FLOWCHART_VERSION,
+      version: FLOWCHART_DOCUMENT_VERSION,
       viewport: this.documentData.viewport,
       nodes: this.documentData.nodes,
       edges: this.documentData.edges
@@ -3359,11 +5008,19 @@ var VdFlowchart = class {
   destroy() {
     if (this.destroyed) return;
     this.destroyed = true;
+    if (this.minimapFrame && typeof cancelAnimationFrame === "function") {
+      cancelAnimationFrame(this.minimapFrame);
+    }
+    this.minimapFrame = 0;
     this.activeTool = null;
     this.stopTextEdit({ commit: false });
     this.resizeObserver?.disconnect();
     this.resizeObserver = null;
     this.unbindEvents();
+    this.sceneNodeMap?.clear();
+    this.nodeElements?.clear();
+    this.edgeElements?.clear();
+    this.incidentEdges?.clear();
     this.element.innerHTML = "";
     this.element.classList.remove("vd-flowchart-host");
   }
@@ -3371,6 +5028,17 @@ var VdFlowchart = class {
 
 // src/vue.js
 var FORWARDED_EVENTS = ["change", "select", "viewport", "connect", "ready"];
+var EDITOR_OPTION_KEYS = [
+  "readonly",
+  "gridSize",
+  "autoFit",
+  "history",
+  "historyLimit",
+  "keyboardShortcuts",
+  "snapGuides",
+  "minimap",
+  "autoLayout"
+];
 var VdFlowchart2 = defineComponent({
   name: "VdFlowchart",
   props: {
@@ -3387,21 +5055,26 @@ var VdFlowchart2 = defineComponent({
     /** Enable the built-in undo/redo history (default true). */
     history: { type: Boolean, default: true },
     /** Maximum number of history entries to retain. */
-    historyLimit: { type: Number, default: void 0 }
+    historyLimit: { type: Number, default: void 0 },
+    /** Keyboard model: 'mindmap' (Tab child, Enter sibling) or 'basic'. */
+    keyboardShortcuts: { type: String, default: "mindmap" },
+    /** Snap dragged nodes to other nodes' edges and centres (default true). */
+    snapGuides: { type: Boolean, default: true },
+    /** Show the overview minimap in the canvas corner (default true). */
+    minimap: { type: Boolean, default: true },
+    /** Re-run the current layout after keyboard or handle insertions (default false). */
+    autoLayout: { type: Boolean, default: false }
   },
   emits: ["change", "select", "viewport", "connect", "ready"],
   setup(props, { emit, expose }) {
     const el = ref(null);
     let instance = null;
+    const editorOptions = () => Object.fromEntries(EDITOR_OPTION_KEYS.map((key) => [key, props[key]]));
     const create = () => {
       instance = new VdFlowchart({
         element: el.value,
         data: props.data,
-        readonly: props.readonly,
-        gridSize: props.gridSize,
-        autoFit: props.autoFit,
-        history: props.history,
-        historyLimit: props.historyLimit
+        ...editorOptions()
       });
       FORWARDED_EVENTS.forEach((name) => {
         instance.on(name, (payload) => emit(name, payload));
@@ -3415,17 +5088,15 @@ var VdFlowchart2 = defineComponent({
       () => props.data,
       (next) => {
         if (instance && typeof instance.load === "function") {
-          instance.load(next, { preserveSelection: props.preserveSelection });
+          instance.load(next, { preserveSelection: props.preserveSelection, silent: true });
         }
       },
       { deep: true }
     );
     watch(
-      () => [props.readonly, props.gridSize, props.autoFit, props.history, props.historyLimit],
+      () => EDITOR_OPTION_KEYS.map((key) => props[key]),
       () => {
-        if (!instance) return;
-        instance.destroy();
-        create();
+        if (instance) instance.updateOptions(editorOptions());
       }
     );
     onBeforeUnmount(() => {
@@ -3446,8 +5117,10 @@ var VdFlowchart2 = defineComponent({
   }
 });
 export {
+  FLOWCHART_DOCUMENT_VERSION,
   FLOWCHART_EDGE_MARKERS,
   FLOWCHART_EDGE_ROUTES,
+  FLOWCHART_KEYBOARD_SHORTCUTS,
   FLOWCHART_NODE_TYPES,
   FLOWCHART_PORTS,
   LAYOUT_MODES,