living-documentation 7.0.0

package/dist/src/frontend/diagram/edge-panel.js

@@ -0,0 +1,260 @@
+// ── Edge panel ────────────────────────────────────────────────────────────────
+// Floating formatting toolbar for selected edges (arrow type, line style, font size).
+
+import { st, markDirty } from './state.js';
+import { visEdgeProps }  from './edge-rendering.js';
+import { pushSnapshot }  from './history.js';
+
+const DEFAULT_EDGE_COLOR = '#a8a29e';
+const FREE_ARROW_STYLE_KEY = 'ld-free-arrow-style';
+
+// Persist the style of the first free arrow (anchor→anchor) in the current
+// selection so the next double-click creation reuses it.
+function persistFreeArrowStyle() {
+  const freeId = st.selectedEdgeIds.find((id) => {
+    const e = st.edges.get(id);
+    if (!e) return false;
+    const fromN = st.nodes && st.nodes.get(e.from);
+    const toN   = st.nodes && st.nodes.get(e.to);
+    return fromN && fromN.shapeType === 'anchor' && toN && toN.shapeType === 'anchor';
+  });
+  if (!freeId) return;
+  const e = st.edges.get(freeId);
+  localStorage.setItem(FREE_ARROW_STYLE_KEY, JSON.stringify({
+    arrowDir:  e.arrowDir  || 'to',
+    dashes:    e.dashes    || false,
+    edgeColor: e.edgeColor || null,
+    edgeWidth: e.edgeWidth || null,
+  }));
+}
+
+export function getLastFreeArrowStyle() {
+  try { return JSON.parse(localStorage.getItem(FREE_ARROW_STYLE_KEY)) || {}; }
+  catch { return {}; }
+}
+
+export function showEdgePanel() {
+  if (!st.selectedEdgeIds.length) return;
+  const e = st.edges.get(st.selectedEdgeIds[0]);
+  if (!e) return;
+
+  document.getElementById('btnEdgeLock').classList.remove('tool-active');
+  document.getElementById('edgePanelControls').classList.remove('hidden');
+
+  const dir    = e.arrowDir ?? 'to';
+  const dashes = e.dashes   ?? false;
+
+  ['edgeBtnNone', 'edgeBtnTo', 'edgeBtnBoth'].forEach((id) =>
+    document.getElementById(id).classList.remove('edge-btn-active'));
+  document.getElementById({ none: 'edgeBtnNone', to: 'edgeBtnTo', both: 'edgeBtnBoth' }[dir] || 'edgeBtnTo')
+    .classList.add('edge-btn-active');
+
+  ['edgeBtnSolid', 'edgeBtnDashed'].forEach((id) =>
+    document.getElementById(id).classList.remove('edge-btn-active'));
+  document.getElementById(dashes ? 'edgeBtnDashed' : 'edgeBtnSolid').classList.add('edge-btn-active');
+
+  // Highlight active color dot.
+  const activeColor = (e.edgeColor || DEFAULT_EDGE_COLOR).toLowerCase();
+  document.querySelectorAll('#edgePanel [data-edge-color]').forEach((btn) => {
+    const isActive = btn.dataset.edgeColor.toLowerCase() === activeColor;
+    btn.style.outline       = isActive ? '2px solid #f97316' : '';
+    btn.style.outlineOffset = isActive ? '2px' : '';
+  });
+
+  // Show/hide the clear-ports button based on whether this edge has ports.
+  const hasPorts = !!(e.fromPort || e.toPort);
+  document.getElementById('btnEdgeClearPorts').classList.toggle('edge-btn-active', hasPorts);
+
+  document.getElementById('edgePanel').classList.remove('hidden');
+}
+
+export function toggleEdgeLock() {
+  if (!st.selectedEdgeIds.length) return;
+  pushSnapshot();
+  // Locking is a one-way UI action — once locked, the only way back is the
+  // long-press on the shape itself (see unlock-hold.js).
+  st.selectedEdgeIds.forEach((id) => {
+    const e = st.edges.get(id);
+    if (!e) return;
+    const fromN = st.nodes && st.nodes.get(e.from);
+    const toN   = st.nodes && st.nodes.get(e.to);
+    const isFreeArrow = fromN && fromN.shapeType === 'anchor' && toN && toN.shapeType === 'anchor';
+    if (isFreeArrow) {
+      [e.from, e.to].forEach((nodeId) => {
+        st.nodes.update({ id: nodeId, locked: true, fixed: { x: true, y: true }, draggable: false });
+        const bn = st.network && st.network.body.nodes[nodeId];
+        if (bn) bn.refreshNeeded = true;
+      });
+    } else {
+      st.edges.update({ id, edgeLocked: true });
+    }
+  });
+  if (st.network) {
+    st.network.unselectAll();
+    st.network.redraw();
+  }
+  st.selectedNodeIds = [];
+  st.selectedEdgeIds = [];
+  hideEdgePanel();
+  markDirty();
+}
+
+export function resetEdgeLabelWidth() {
+  if (!st.selectedEdgeIds.length) return;
+  pushSnapshot();
+  st.selectedEdgeIds.forEach((id) => {
+    st.edges.update({ id, edgeLabelWidth: null });
+  });
+  markDirty();
+}
+
+export function clearEdgePorts() {
+  if (!st.selectedEdgeIds.length) return;
+  pushSnapshot();
+  st.selectedEdgeIds.forEach((id) => {
+    const e = st.edges.get(id);
+    if (!e) return;
+    const color = e.edgeColor || DEFAULT_EDGE_COLOR;
+    // Restore vis-network's default edge rendering, preserving custom color/width.
+    st.edges.update({
+      id,
+      fromPort: null,
+      toPort: null,
+      color: { color, highlight: '#f97316', hover: '#f97316' },
+      width: e.edgeWidth || 1.5,
+      ...visEdgeProps(e.arrowDir ?? 'to', e.dashes ?? false),
+    });
+  });
+  showEdgePanel();
+  markDirty();
+}
+
+export function setEdgeColor(hex) {
+  if (!st.selectedEdgeIds.length) return;
+  pushSnapshot();
+  st.selectedEdgeIds.forEach((id) => {
+    const e = st.edges.get(id);
+    if (!e) return;
+    const update = { id, edgeColor: hex };
+    // For non-port edges, also update vis-network's native color property.
+    if (!(e.fromPort || e.toPort)) {
+      update.color = { color: hex, highlight: '#f97316', hover: '#f97316' };
+    }
+    st.edges.update(update);
+  });
+  persistFreeArrowStyle();
+  showEdgePanel();
+  markDirty();
+}
+
+export function changeEdgeWidth(delta) {
+  if (!st.selectedEdgeIds.length) return;
+  pushSnapshot();
+  st.selectedEdgeIds.forEach((id) => {
+    const e = st.edges.get(id);
+    if (!e) return;
+    const newWidth = Math.max(1, Math.min(8, (e.edgeWidth || 1.5) + delta));
+    const update = { id, edgeWidth: newWidth };
+    // For non-port edges, also update vis-network's native width property.
+    if (!(e.fromPort || e.toPort)) {
+      update.width = newWidth;
+    }
+    st.edges.update(update);
+  });
+  persistFreeArrowStyle();
+  markDirty();
+}
+
+export function hideEdgePanel() {
+  document.getElementById('edgePanel').classList.add('hidden');
+}
+
+export function setEdgeArrow(dir) {
+  if (!st.selectedEdgeIds.length) return;
+  pushSnapshot();
+  st.selectedEdgeIds.forEach((id) => {
+    const e = st.edges.get(id);
+    if (!e) return;
+    const update = { id, arrowDir: dir };
+    // For port edges, vis-network arrows stay disabled; drawPortEdge handles them.
+    if (!(e.fromPort || e.toPort)) Object.assign(update, visEdgeProps(dir, e.dashes ?? false));
+    st.edges.update(update);
+  });
+  persistFreeArrowStyle();
+  showEdgePanel();
+  markDirty();
+}
+
+export function setEdgeDashes(dashes) {
+  if (!st.selectedEdgeIds.length) return;
+  pushSnapshot();
+  st.selectedEdgeIds.forEach((id) => {
+    const e = st.edges.get(id);
+    if (!e) return;
+    const update = { id, dashes };
+    // For port edges, vis-network arrows stay disabled; drawPortEdge handles them.
+    if (!(e.fromPort || e.toPort)) Object.assign(update, visEdgeProps(e.arrowDir ?? 'to', dashes));
+    st.edges.update(update);
+  });
+  persistFreeArrowStyle();
+  showEdgePanel();
+  markDirty();
+}
+
+export function changeEdgeFontSize(delta) {
+  if (!st.selectedEdgeIds.length) return;
+  pushSnapshot();
+  st.selectedEdgeIds.forEach((id) => {
+    const e = st.edges.get(id);
+    if (!e) return;
+    const newSize = Math.max(8, Math.min(48, (e.fontSize || 11) + delta));
+    // Keep native label transparent — drawEdgeLabels() is the single render path.
+    st.edges.update({ id, fontSize: newSize, font: { size: newSize, align: 'middle', color: 'rgba(0,0,0,0)' } });
+  });
+  markDirty();
+}
+
+export function stepEdgeLabelRotation(delta) {
+  if (!st.selectedEdgeIds.length) return;
+  pushSnapshot();
+  st.selectedEdgeIds.forEach((id) => {
+    const e = st.edges.get(id);
+    if (!e) return;
+    const newRotation = (e.labelRotation || 0) + delta;
+    // Keep native label transparent — drawEdgeLabels() is the single render path.
+    st.edges.update({
+      id,
+      labelRotation: newRotation,
+      font: { size: e.fontSize || 11, align: 'middle', color: 'rgba(0,0,0,0)' },
+    });
+  });
+  markDirty();
+}
+
+const LABEL_OFFSET_STEP = 5;
+
+export function stepEdgeLabelOffset(dx, dy) {
+  if (!st.selectedEdgeIds.length) return;
+  pushSnapshot();
+  st.selectedEdgeIds.forEach((id) => {
+    const e = st.edges.get(id);
+    if (!e) return;
+    st.edges.update({
+      id,
+      edgeLabelOffsetX: (e.edgeLabelOffsetX || 0) + dx * LABEL_OFFSET_STEP,
+      edgeLabelOffsetY: (e.edgeLabelOffsetY || 0) + dy * LABEL_OFFSET_STEP,
+    });
+  });
+  if (st.network) st.network.redraw();
+  markDirty();
+}
+
+export function resetEdgeLabelOffset() {
+  if (!st.selectedEdgeIds.length) return;
+  pushSnapshot();
+  st.selectedEdgeIds.forEach((id) => {
+    st.edges.update({ id, edgeLabelOffsetX: 0, edgeLabelOffsetY: 0 });
+  });
+  if (st.network) st.network.redraw();
+  markDirty();
+}

package/dist/src/frontend/diagram/edge-rendering.js

@@ -0,0 +1,12 @@
+// ── Edge rendering ────────────────────────────────────────────────────────────
+// Builds vis.js edge property objects (arrows, dashes).
+
+export function visEdgeProps(arrowDir, dashes) {
+  return {
+    arrows: {
+      to:   { enabled: arrowDir === 'to'   || arrowDir === 'both', scaleFactor: 0.7 },
+      from: { enabled: arrowDir === 'both',                        scaleFactor: 0.7 },
+    },
+    dashes: dashes === true,
+  };
+}

package/dist/src/frontend/diagram/grid.js

@@ -0,0 +1,78 @@
+// ── Grid & snap ───────────────────────────────────────────────────────────────
+// Grid rendering (beforeDrawing), snap-to-grid (dragEnd).
+
+import { st, markDirty }    from './state.js';
+import { GRID_SIZE }         from './constants.js';
+import { t }                 from './t.js';
+import { pushSnapshot }      from './history.js';
+import { snapToAlignGuides } from './alignment.js';
+
+
+
+export function applyGridState(enabled) {
+  st.gridEnabled = enabled;
+  const btn = document.getElementById('btnGrid');
+  btn.classList.toggle('tool-active', enabled);
+  btn.title = t('diagram.toolbar.grid');
+}
+
+export function toggleGrid() {
+  applyGridState(!st.gridEnabled);
+  markDirty();
+  if (st.network) st.network.redraw();
+}
+
+// Called on network "beforeDrawing" — draws grid lines in physical pixel space.
+export function drawGrid(ctx) {
+  if (!st.gridEnabled || !st.network) return;
+  const isDark = document.documentElement.classList.contains('dark');
+  const color  = isDark ? 'rgba(255,255,255,0.18)' : 'rgba(0,0,0,0.15)';
+  const scale  = st.network.getScale();
+  const center = st.network.getViewPosition();
+  const canvas = ctx.canvas;
+  const W = canvas.width, H = canvas.height;
+
+  // vis.js coordinates (center.x, scale) are in CSS pixels; must multiply by DPR
+  // so the grid aligns correctly on Retina/HiDPI displays.
+  const dpr    = window.devicePixelRatio || 1;
+  const step   = GRID_SIZE * scale * dpr;
+  const offsetX = (((W / 2 - center.x * scale * dpr) % step) + step) % step;
+  const offsetY = (((H / 2 - center.y * scale * dpr) % step) + step) % step;
+
+  ctx.save();
+  ctx.setTransform(1, 0, 0, 1, 0, 0); // physical pixel space
+  ctx.strokeStyle = color;
+  ctx.lineWidth   = 1;
+  ctx.beginPath();
+  for (let x = offsetX; x < W; x += step) { ctx.moveTo(x, 0); ctx.lineTo(x, H); }
+  for (let y = offsetY; y < H; y += step) { ctx.moveTo(0, y); ctx.lineTo(W, y); }
+  ctx.stroke();
+  ctx.restore();
+}
+
+// Snap a canvas position to the nearest grid intersection.
+export function snapToGrid(x, y) {
+  return {
+    x: Math.round(x / GRID_SIZE) * GRID_SIZE,
+    y: Math.round(y / GRID_SIZE) * GRID_SIZE,
+  };
+}
+
+// Called on network "dragEnd" — alignment snap, then grid snap.
+export function onDragEnd(params) {
+  if (!params.nodes || !params.nodes.length) return;
+  pushSnapshot();
+  snapToAlignGuides(params);
+  if (st.gridEnabled) {
+    params.nodes.forEach((id) => {
+      const bodyNode = st.network.body.nodes[id];
+      if (!bodyNode) return;
+      const cx = bodyNode.x, cy = bodyNode.y;
+      // Snap the center of the shape to grid intersections
+      const snappedX = Math.round(cx / GRID_SIZE) * GRID_SIZE;
+      const snappedY = Math.round(cy / GRID_SIZE) * GRID_SIZE;
+      st.network.moveNode(id, snappedX, snappedY);
+    });
+  }
+  markDirty();
+}

package/dist/src/frontend/diagram/groups.js

@@ -0,0 +1,102 @@
+// ── Group management ──────────────────────────────────────────────────────────
+
+import { st, markDirty } from './state.js';
+import { pushSnapshot }  from './history.js';
+import { SHAPE_DEFAULTS } from './node-rendering.js';
+
+// ── Create / destroy ──────────────────────────────────────────────────────────
+
+export function groupNodes() {
+  if (st.selectedNodeIds.length < 2) return;
+  pushSnapshot();
+  const groupId = 'g' + Date.now();
+  st.selectedNodeIds.forEach((id) => st.nodes.update({ id, groupId }));
+  markDirty();
+}
+
+export function ungroupNodes() {
+  if (!st.selectedNodeIds.length) return;
+  pushSnapshot();
+  // Collect all members of any group touched by the selection
+  const groupIds = new Set(
+    st.selectedNodeIds.map((id) => { const n = st.nodes.get(id); return n && n.groupId; }).filter(Boolean)
+  );
+  st.nodes.get().forEach((n) => {
+    if (n.groupId && groupIds.has(n.groupId)) st.nodes.update({ id: n.id, groupId: null });
+  });
+  markDirty();
+}
+
+// ── Selection expansion ───────────────────────────────────────────────────────
+// Called from onSelectNode — expands selection to all group members.
+
+export function expandSelectionToGroup(nodeIds) {
+  const groupIds = new Set();
+  nodeIds.forEach((id) => {
+    const n = st.nodes.get(id);
+    if (n && n.groupId) groupIds.add(n.groupId);
+  });
+  if (!groupIds.size) return nodeIds;
+
+  const expanded = new Set(nodeIds);
+  st.nodes.get().forEach((n) => {
+    if (n.groupId && groupIds.has(n.groupId)) expanded.add(n.id);
+  });
+  return [...expanded];
+}
+
+// ── Group outline (drawn on canvas in afterDrawing) ───────────────────────────
+
+function nodeBounds(id) {
+  const n        = st.nodes.get(id);
+  const bodyNode = st.network.body.nodes[id];
+  if (!bodyNode) return null;
+  const shape    = (n && n.shapeType) || 'box';
+  const defaults = SHAPE_DEFAULTS[shape] || [100, 40];
+  const W   = (n && n.nodeWidth)  || defaults[0];
+  const H   = (n && n.nodeHeight) || defaults[1];
+  const rot = (n && n.rotation)   || 0;
+  const cx = bodyNode.x, cy = bodyNode.y;
+  if (rot === 0) {
+    return { minX: cx - W / 2, minY: cy - H / 2, maxX: cx + W / 2, maxY: cy + H / 2 };
+  }
+  const cos = Math.abs(Math.cos(rot)); const sin = Math.abs(Math.sin(rot));
+  const hw = (W * cos + H * sin) / 2;
+  const hh = (W * sin + H * cos) / 2;
+  return { minX: cx - hw, minY: cy - hh, maxX: cx + hw, maxY: cy + hh };
+}
+
+export function drawGroupOutlines(ctx) {
+  if (!st.network || !st.selectedNodeIds.length) return;
+
+  // Find groupIds that have at least one selected member
+  const selectedSet = new Set(st.selectedNodeIds);
+  const activeGroups = new Set();
+  st.selectedNodeIds.forEach((id) => {
+    const n = st.nodes.get(id);
+    if (n && n.groupId) activeGroups.add(n.groupId);
+  });
+  if (!activeGroups.size) return;
+
+  // For each active group, compute bounding box over ALL members
+  activeGroups.forEach((groupId) => {
+    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+    st.nodes.get().forEach((n) => {
+      if (n.groupId !== groupId) return;
+      const b = nodeBounds(n.id);
+      if (!b) return;
+      minX = Math.min(minX, b.minX); minY = Math.min(minY, b.minY);
+      maxX = Math.max(maxX, b.maxX); maxY = Math.max(maxY, b.maxY);
+    });
+    if (minX === Infinity) return;
+
+    const PAD = 14;
+    ctx.save();
+    ctx.strokeStyle = '#6366f1';
+    ctx.lineWidth   = 1.5;
+    ctx.setLineDash([6, 4]);
+    ctx.strokeRect(minX - PAD, minY - PAD, maxX - minX + PAD * 2, maxY - minY + PAD * 2);
+    ctx.setLineDash([]);
+    ctx.restore();
+  });
+}

package/dist/src/frontend/diagram/history.js

@@ -0,0 +1,153 @@
+// ── Undo / Redo history ────────────────────────────────────────────────────────
+// Snapshot-based undo/redo. Captures semantic node/edge data (same format as
+// saveDiagram) so vis-network rendering props are reconstructed cleanly on
+// restore. History is scoped to the current diagram — call resetHistory() on
+// every diagram switch so stacks don't bleed across diagrams.
+
+import { st, markDirty } from './state.js';
+import { visNodeProps }   from './node-rendering.js';
+import { visEdgeProps }   from './edge-rendering.js';
+
+const MAX_HISTORY = 50;
+
+let _undoStack = [];
+let _redoStack = [];
+
+// ── State capture ──────────────────────────────────────────────────────────────
+
+function captureState() {
+  if (!st.nodes || !st.edges || !st.network) return null;
+  const positions = st.network.getPositions();
+  const nodes = st.nodes.get().map((n) => ({
+    id: n.id, label: n.label,
+    shapeType: n.shapeType || 'box', colorKey: n.colorKey || 'c-gray',
+    nodeWidth: n.nodeWidth || null, nodeHeight: n.nodeHeight || null,
+    fontSize: n.fontSize || null, textAlign: n.textAlign || null, textValign: n.textValign || null,
+    bgOpacity: n.bgOpacity ?? null,
+    rotation: n.rotation || 0, labelRotation: n.labelRotation || 0,
+    imageSrc: n.imageSrc || null, groupId: n.groupId || null,
+    nodeLink: n.nodeLink || null, locked: n.locked || false,
+    x: positions[n.id]?.x ?? n.x, y: positions[n.id]?.y ?? n.y,
+  }));
+  const edges = st.edges.get().map((e) => ({
+    id: e.id, from: e.from, to: e.to,
+    label: e.label || '', arrowDir: e.arrowDir || 'to',
+    dashes: e.dashes || false, fontSize: e.fontSize || null,
+    labelRotation: e.labelRotation || 0,
+    fromPort: e.fromPort || null, toPort: e.toPort || null,
+    edgeColor: e.edgeColor || null, edgeWidth: e.edgeWidth || null,
+    edgeLocked: e.edgeLocked || false,
+  }));
+  return {
+    nodes,
+    edges,
+    canonicalOrder: [...st.canonicalOrder],
+    edgesStraight: st.edgesStraight,
+  };
+}
+
+// ── Public API ─────────────────────────────────────────────────────────────────
+
+/**
+ * Call BEFORE any mutating operation to record the current state for undo.
+ * Clears the redo stack (new action invalidates any undone future).
+ */
+export function pushSnapshot() {
+  const snap = captureState();
+  if (!snap) return;
+  _undoStack.push(snap);
+  if (_undoStack.length > MAX_HISTORY) _undoStack.shift();
+  _redoStack = [];
+}
+
+/** Reset both stacks — call whenever a new diagram is opened. */
+export function resetHistory() {
+  _undoStack = [];
+  _redoStack = [];
+}
+
+/** Undo the last action. No-op if stack is empty. */
+export function undo() {
+  if (!_undoStack.length) return;
+  const before  = _undoStack.pop();
+  const current = captureState();
+  if (current) _redoStack.push(current);
+  _restoreState(before);
+}
+
+/** Redo the last undone action. No-op if stack is empty. */
+export function redo() {
+  if (!_redoStack.length) return;
+  const after   = _redoStack.pop();
+  const current = captureState();
+  if (current) _undoStack.push(current);
+  _restoreState(after);
+}
+
+// ── State restore ──────────────────────────────────────────────────────────────
+
+function _restoreState(snapshot) {
+  if (!st.network || !st.nodes || !st.edges || !snapshot) return;
+
+  const pos   = st.network.getViewPosition();
+  const scale = st.network.getScale();
+
+  // Clear edges first: the edge-remove listener detects orphaned anchors and
+  // removes them from st.nodes, which avoids cascade issues when clearing nodes.
+  st.edges.clear();
+  st.nodes.clear();
+
+  // Restore edge-straight flag + toolbar button
+  if (snapshot.edgesStraight !== undefined) {
+    st.edgesStraight = snapshot.edgesStraight;
+    document.getElementById('btnEdgeStraight').classList.toggle('tool-active', st.edgesStraight);
+  }
+  const edgeSmooth = st.edgesStraight ? { enabled: false } : { type: 'continuous' };
+
+  st.nodes.add(snapshot.nodes.map((n) => ({
+    ...n,
+    ...visNodeProps(
+      n.shapeType || 'box', n.colorKey || 'c-gray',
+      n.nodeWidth, n.nodeHeight, n.fontSize, n.textAlign, n.textValign,
+    ),
+    ...(n.locked ? { fixed: { x: true, y: true }, draggable: false } : {}),
+  })));
+
+  st.edges.add(snapshot.edges.map((e) => {
+    const toNode   = snapshot.nodes.find((n) => n.id === e.to);
+    const isAnchor = toNode && toNode.shapeType === 'anchor';
+    const edgeObj  = {
+      ...e,
+      ...visEdgeProps(e.arrowDir ?? 'to', e.dashes ?? false),
+      smooth: isAnchor ? { enabled: false } : edgeSmooth,
+      ...(e.edgeColor ? { color: { color: e.edgeColor, highlight: '#f97316', hover: '#f97316' } } : {}),
+      ...(e.edgeWidth ? { width: e.edgeWidth } : {}),
+      ...(e.fontSize || e.labelRotation ? {
+        font: {
+          size: e.fontSize || 11,
+          align: 'middle',
+          color: (e.labelRotation && Math.abs(e.labelRotation) > 0.001) ? 'rgba(0,0,0,0)' : '#6b7280',
+        },
+      } : {}),
+    };
+    if (e.fromPort || e.toPort) {
+      edgeObj.color  = { color: 'rgba(0,0,0,0)', highlight: 'rgba(0,0,0,0)', hover: 'rgba(0,0,0,0)' };
+      edgeObj.arrows = { to: { enabled: false }, from: { enabled: false } };
+    }
+    return edgeObj;
+  }));
+
+  // Override the canonical order that the add-listener built in insertion order
+  st.canonicalOrder = [...snapshot.canonicalOrder];
+
+  // Force all nodes to re-render (custom shapes cache ctx closures)
+  Object.keys(st.network.body.nodes).forEach((id) => {
+    const bn = st.network.body.nodes[id];
+    if (bn) bn.refreshNeeded = true;
+  });
+
+  // Restore viewport without animation
+  st.network.moveTo({ position: pos, scale, animation: false });
+  markDirty();
+  st.network.redraw();
+}

package/dist/src/frontend/diagram/image-name-modal.js

@@ -0,0 +1,48 @@
+// ── Image filename modal ───────────────────────────────────────────────────────
+// Returns a Promise<string|null>:
+//   string (possibly empty) → user confirmed (empty = use auto name)
+//   null                    → user cancelled
+
+const IMAGE_NAME_RE = /^[a-z0-9_-]*$/i;
+
+export function promptImageName() {
+  return new Promise((resolve) => {
+    const modal   = document.getElementById('imageNameModal');
+    const input   = document.getElementById('imageNameInput');
+    const error   = document.getElementById('imageNameError');
+    const confirm = document.getElementById('imageNameConfirm');
+    const cancel  = document.getElementById('imageNameCancel');
+
+    input.value = '';
+    error.classList.add('hidden');
+    modal.style.display = 'flex';
+    setTimeout(() => input.focus(), 50);
+
+    function validate() {
+      const val = input.value.trim();
+      const ok  = val === '' || IMAGE_NAME_RE.test(val);
+      error.classList.toggle('hidden', ok);
+      return ok;
+    }
+
+    function close(name) {
+      modal.style.display = 'none';
+      confirm.removeEventListener('click',  onConfirm);
+      cancel.removeEventListener('click',   onCancel);
+      input.removeEventListener('input',    validate);
+      input.removeEventListener('keydown',  onKey);
+      resolve(name);
+    }
+    function onConfirm() { if (validate()) close(input.value.trim()); }
+    function onCancel()  { close(null); }
+    function onKey(e) {
+      if (e.key === 'Enter')  { e.preventDefault(); if (validate()) close(input.value.trim()); }
+      if (e.key === 'Escape') { e.preventDefault(); close(null); }
+    }
+
+    confirm.addEventListener('click',  onConfirm);
+    cancel.addEventListener('click',   onCancel);
+    input.addEventListener('input',    validate);
+    input.addEventListener('keydown',  onKey);
+  });
+}

package/dist/src/frontend/diagram/image-upload.js

@@ -0,0 +1,36 @@
+// ── Image upload helper ───────────────────────────────────────────────────────
+// Converts a File or Blob to base64 and uploads it via POST /api/images/upload.
+// Returns the absolute URL path usable in an <img> or ctx.drawImage(), e.g. "/images/foo.png".
+
+async function toBase64(blob) {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload  = () => resolve(reader.result);
+    reader.onerror = reject;
+    reader.readAsDataURL(blob);
+  });
+}
+
+export async function uploadImageFile(file, name = '') {
+  const ext    = (file.name.split('.').pop() || 'png').toLowerCase();
+  const base64 = await toBase64(file);
+  return _upload(base64, ext, name);
+}
+
+export async function uploadImageBlob(blob, ext = 'png', name = '') {
+  const base64 = await toBase64(blob);
+  return _upload(base64, ext, name);
+}
+
+async function _upload(base64, ext, name = '') {
+  const body = { data: base64, ext };
+  if (name) body.name = name;
+  const res  = await fetch('/api/images/upload', {
+    method:  'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body:    JSON.stringify(body),
+  });
+  if (!res.ok) throw new Error('Upload failed');
+  const { filename } = await res.json();
+  return `/images/${filename}`;
+}