@peter.prib/renderengine 0.0.0-stage → 0.2.0

package/src/charting/diagrams/GraphDiagram.js

@@ -0,0 +1,1340 @@
+import { TextStyle } from '../TextStyle.js';
+import { Diagram } from '../Diagram.js';
+import { CommandHistory } from '../CommandHistory.js';
+import { GraphMetrics } from './GraphMetrics.js';
+import { LabelHelper } from './LabelHelper.js';
+import { NodeGeometry } from './NodeGeometry.js';
+import { SvgCoordinate } from './SvgCoordinate.js';
+import { EdgeGeometry } from './EdgeGeometry.js';
+import { ContextMenu } from './ContextMenu.js';
+import { GridOverlay } from './GridOverlay.js';
+import { LINE_STYLE_DASH } from '../edgeStyle/EdgeStyleSchema.js';
+import {
+    AddNodeCommand, DeleteNodeCommand,
+    AddEdgeCommand, DeleteEdgeCommand, InvertEdgeCommand,
+    RenameNodeCommand, RenameEdgeCommand,
+    AddWaypointCommand,
+} from './commands/index.js';
+
+/**
+ * GraphDiagram — renders an interactive 2D node/edge graph diagram.
+ */
+
+/** Marks a selected line's end and bend-point handles (removed when the line is deselected). */
+const EDGE_HANDLE_ATTR = 'data-edge-handle';
+
+export class GraphDiagram extends Diagram {
+    static diagramType = 'graph';
+
+    constructor(renderer, nodes, edges, options = {}, engine = null, folders = []) {
+        super(renderer, { nodes, edges, folders }, options);
+        this.engine = engine;
+        this._chartState = { type: 'graph', nodes, edges, folders, options };
+        this._graph = null;
+        this._graphCollapsedNodes = new Set();
+        this._graphFilterKeyword = '';
+        this._graphFixedPos = new Set();
+        this._hiddenGraphNodes = new Set();
+        this._hiddenGraphGroups = new Set();
+        this._collapsedFolders = new Set(); // Track which folders are collapsed
+        // A host that re-renders the diagram hands in its own history so undo
+        // outlives this instance; that host then owns the undo/redo keys too.
+        this.hostOwnsHistory = !!options.history;
+        this.history = options.history ?? new CommandHistory({
+            maxSize: options.historySize ?? 200,
+            onChange: (canUndo, canRedo) => {
+                options?.onHistoryChange?.(canUndo, canRedo);
+            },
+        });
+    }
+
+    /**
+     * Fields that are not caller "extra data" for tooltips, search and the
+     * properties dialog: the engine's own, plus the host's `internalKeys`
+     * (bookkeeping a host adds to the items it hands in).
+     * @param {'node'|'table'|'edge'} kind
+     * @returns {Set<string>}
+     */
+    structuralKeys(kind) {
+        const E = this.engine?.constructor ?? {};
+        const own = { node: E.NODE_STRUCTURAL_KEYS, table: E.TABLE_NODE_STRUCTURAL_KEYS, edge: E.EDGE_STRUCTURAL_KEYS }[kind];
+        return new Set([...(own ?? []), ...(this.options?.internalKeys ?? [])]);
+    }
+
+    _render() {
+        const { nodes, edges } = this.data;
+        const options = this.options;
+        this._chartState = { type: 'graph', nodes, edges, options };
+        if (!this.renderer || !this.renderer.supportsSceneGraph) {
+            console.warn('Advanced graph diagram is only supported in SVG renderer.');
+            return;
+        }
+        this.renderer.clear();
+
+        const { nodeRadius = 14, onNodeClick, onEdgeClick, legend: showLegend = false, colors = ['#5470c6', '#91cc75', '#fac858', '#ee6666', '#73c0de', '#3ba272', '#fc8452'], edgeColor: defaultEdgeColor = '#bdc3c7', contextMenuItems, edgeContextMenuItems, canvasContextMenuItems, editable = false } = options;
+        const { compactness = 1.0 } = options;
+        // Default auto-routing for edges that don't set their own `edge.routing`
+        // — 'straight' (default), 'curved', 'orthogonal', or 'polyline' (basic
+        // node-avoidance). See _computeEdgePath. Editable diagrams also let
+        // the user drag a manual bend point onto any edge (double-click to
+        // add/remove, drag to reposition — see _addDragListeners), which
+        // always wins over whatever routing style is set.
+        const { edgeRouting: defaultEdgeRouting = 'straight' } = options;
+        // Resize handle (see _addResizeListeners): off unless `resizable` is
+        // true (a node can still opt out/in individually via its own
+        // `node.resizable`), corner defaults to 'top-right', overridable per
+        // shape (`resizeCornerByShape: {shape: corner}`) or per node
+        // (`node.resizeCorner`) — see _nodeResizeCorner.
+        const { resizable = false, resizeCorner = 'top-right', resizeCornerByShape } = options;
+        // Where a node's icon (icon/iconUrl, see the nodes param doc above)
+        // sits: 'center' (default — replaces the initials) or 'corner' (a
+        // small badge, positioned like the resize handle via the same
+        // node > per-shape > diagram-wide precedence — see _nodeIconCorner).
+        // A node's own `node.iconPosition` overrides this diagram default.
+        const { iconPosition: defaultIconPosition = 'center', iconCorner = 'top-right', iconCornerByShape } = options;
+        // 'below' (default, the original caption-under-the-shape convention)
+        // or 'inside' (label left-aligned inside the box — see the render
+        // loop below). A node's own `node.labelPosition` overrides this.
+        const { labelPosition: defaultLabelPosition = 'below' } = options;
+        // Horizontal alignment of the label: 'left' | 'center' | 'right'.
+        // Default keeps the existing behaviour: centred for captions below the
+        // shape, left-aligned for wrapped labels inside a box. Per-node values
+        // override the diagram default.
+        const { textAlign: defaultTextAlign = null } = options;
+        // Lines over boxes (Archi's connection layer) instead of under them.
+        const { edgesOnTop = false } = options;
+        // Vertical alignment, only meaningful for `labelPosition: 'inside'`:
+        // 'top' | 'middle' | 'bottom'. Default 'top' preserves existing layout.
+        const { verticalAlign: defaultVerticalAlign = null } = options;
+        // `sizeBy: 'degree'` sizes nodes by connection count instead of the
+        // caller pre-populating `node.size` — see _computeNodeDegrees.
+        const { minRadius = nodeRadius, maxRadius = nodeRadius * 2.5, sizeScale = 'linear', sizeBy } = options;
+        // Same pattern, for edge thickness — `edge.weight` drives stroke width.
+        const { minEdgeWidth = 1.4, maxEdgeWidth = minEdgeWidth * 4, edgeWidthScale = 'linear' } = options;
+        // Grid: `gridSize` > 0 snaps user-driven positions (drag, add node) to
+        // this many SVG units; `showGrid` draws the grid behind the diagram.
+        const { gridSize = 0, showGrid = false } = options;
+
+        // Initialize GridOverlay for responsive grid rendering
+        if (showGrid && gridSize > 0) {
+            if (!this._gridOverlay) {
+                this._gridOverlay = new GridOverlay(this.renderer.container, { gridSize, color: '#e5e5e5', width: 0.5 });
+            } else {
+                this._gridOverlay.setGridSize(gridSize);
+            }
+        } else if (this._gridOverlay) {
+            this._gridOverlay.destroy();
+            this._gridOverlay = null;
+        }
+
+        const W = this.renderer.width, H = this.renderer.height;
+        const R = nodeRadius;
+        const PAD = R + 6;
+        // Degree is computed from the caller's own `edges`, not whatever
+        // `effectiveEdges` layout inference below may substitute — "number of
+        // connections" means the graph the caller described, not an internal
+        // tree-layout artifact.
+        const degreeMap = sizeBy === 'degree' ? GraphMetrics.computeNodeDegrees(nodes, edges) : null;
+        const sizeDomain = GraphMetrics.computeSizeDomain(nodes, { sizeBy, degreeMap });
+        const sizeOptions = { minRadius, maxRadius, sizeScale, sizeBy, degreeMap };
+
+        // A hierarchical-key node set (see _inferHierarchyEdges) replaces the
+        // caller's edges with the inferred parent/child structure (plus any
+        // "quasi-leaf" edges it chose to keep) and switches layout from
+        // force-directed to a top-down tree — the two layouts don't blend.
+        const hierarchyEdges = this._inferHierarchyEdges(nodes, edges);
+        const useTreeLayout = hierarchyEdges !== null;
+        const effectiveEdges = useTreeLayout ? hierarchyEdges : edges;
+        const childrenMap = useTreeLayout ? this._hierarchyChildrenMap(effectiveEdges) : null;
+        // Over effectiveEdges, not the caller's raw edges — this is the domain
+        // for what actually gets drawn below, and in tree-layout mode that's a
+        // synthesized edge set the caller's `.weight` values don't apply to.
+        const edgeWidthDomain = GraphMetrics.computeEdgeWidthDomain(effectiveEdges);
+        const edgeWidthOptions = { minEdgeWidth, maxEdgeWidth, widthScale: edgeWidthScale };
+        // Collapsed subtrees (toggled via each node's +/− badge, see nodeEls
+        // below) hide their descendants — not the collapsed node itself,
+        // whose badge must stay visible/clickable to re-expand it.
+        const hiddenByCollapse = useTreeLayout
+            ? this._collapsedDescendantIds(this._graphCollapsedNodes, childrenMap)
+            : new Set();
+        // Live keyword filter (see filterGraphNodes) — recomputed every render
+        // so typing in a search box just calls filterGraphNodes and re-renders.
+        const filterKeyword = (this._graphFilterKeyword || '').trim();
+        const hiddenByFilter = this._hiddenByKeywordFilter(nodes, filterKeyword, childrenMap);
+
+        // Initialize positions, respecting any fixed positions from the input
+        this._graphFixedPos = new Set(nodes.filter(n => n.x != null || n.y != null).map(n => n.id));
+        let pos;
+        if (useTreeLayout) {
+            pos = this._computeTreeLayout(nodes, effectiveEdges, W, H, PAD);
+            nodes.forEach(n => { // an explicit x/y still overrides the computed tree slot
+                if (this._graphFixedPos.has(n.id)) {
+                    const p = pos.get(n.id);
+                    if (n.x != null) p.x = n.x;
+                    if (n.y != null) p.y = n.y;
+                }
+            });
+        } else {
+            pos = new Map(nodes.map(n => [n.id, {
+                x: n.x ?? (Math.random() * (W - 2 * PAD) + PAD),
+                y: n.y ?? (Math.random() * (H - 2 * PAD) + PAD),
+                vx: 0, vy: 0 }]));
+            const K_FR = Math.sqrt((W * H) / Math.max(nodes.length, 1)) * 0.9 * compactness;
+            const frStep = (temp) => {
+                nodes.forEach(n => { if (!this._graphFixedPos.has(n.id)) { const p = pos.get(n.id); p.vx = 0; p.vy = 0; } });
+                for (let i = 0; i < nodes.length; i++) {
+                    for (let j = i + 1; j < nodes.length; j++) {
+                        const a = pos.get(nodes[i].id), b = pos.get(nodes[j].id);
+                        const dx = b.x - a.x, dy = b.y - a.y;
+                        const dist = Math.sqrt(dx * dx + dy * dy) || 0.01;
+                        const f = K_FR * K_FR / dist;
+                        a.vx -= dx / dist * f; a.vy -= dy / dist * f;
+                        b.vx += dx / dist * f; b.vy += dy / dist * f;
+                    }
+                }
+                effectiveEdges.forEach(e => {
+                    const a = pos.get(e.source), b = pos.get(e.target);
+                    if (!a || !b) return;
+                    const dx = b.x - a.x, dy = b.y - a.y;
+                    const dist = Math.sqrt(dx * dx + dy * dy) || 0.01;
+                    const f = (dist * dist) / (K_FR * 1.5);
+                    a.vx += dx / dist * f; a.vy += dy / dist * f;
+                    b.vx -= dx / dist * f; b.vy -= dy / dist * f;
+                });
+                nodes.forEach(n => {
+                    if (this._graphFixedPos.has(n.id)) return;
+                    const p = pos.get(n.id);
+                    p.vx += (W / 2 - p.x) * 0.006;
+                    p.vy += (H / 2 - p.y) * 0.006;
+                    const mag = Math.sqrt(p.vx * p.vx + p.vy * p.vy) || 1;
+                    const dt = Math.min(mag, temp) / mag;
+                    p.x = Math.max(PAD, Math.min(W - PAD, p.x + p.vx * dt));
+                    p.y = Math.max(PAD, Math.min(H - PAD, p.y + p.vy * dt));
+                });
+            };
+
+            if (!this._graph) { // Only run full simulation on initial draw
+                // Run simulation synchronously before drawing
+                for (let iter = 0; iter < 180; iter++) {
+                    frStep(K_FR * (1 - iter / 180) * 0.25);
+                }
+            }
+        }
+
+        // Other nodes as circular obstacles for 'polyline' routing (see
+        // _polylineEdgePath) — computed once per render, source/target of
+        // each edge excluded per-edge below rather than filtered out here.
+        const routingObstacles = nodes.map(n => {
+            const p = pos.get(n.id);
+            if (!p) return null;
+            const size = NodeGeometry.nodeSize(n, R, sizeDomain, sizeOptions);
+            return { id: n.id, x: p.x, y: p.y, r: Math.max(size.w, size.h) / 2 };
+        }).filter(Boolean);
+
+        // The selected line's handles are drawn after the nodes: an end handle
+        // sits on a node's rim, and a node drawn over it would hide half of it.
+        const selectionHandles = [];
+        const svgRoot = this.renderer.svg;
+        const edgesFrom = svgRoot?.childNodes?.length ?? 0;
+        const edgeEls = effectiveEdges.map(edge => {
+            const sourceNode = pos.get(edge.source);
+            const targetNode = pos.get(edge.target);
+            if (!sourceNode || !targetNode) return null;
+            const sourceInfo = nodes.find(n => n.id === edge.source);
+            const targetInfo = nodes.find(n => n.id === edge.target);
+            const sourceSize = this.engine._nodeSize(sourceInfo, R, sizeDomain, sizeOptions);
+            const targetSize = this.engine._nodeSize(targetInfo, R, sizeDomain, sizeOptions);
+            const edgeObstacles = routingObstacles.filter(o => o.id !== edge.source && o.id !== edge.target);
+
+            const { x1, y1, x2, y2, d } = EdgeGeometry.computeEdgePath(
+                sourceInfo, sourceNode, sourceSize, targetInfo, targetNode, targetSize, edge, defaultEdgeRouting, edgeObstacles
+            );
+
+            const edgeColor = edge.color || defaultEdgeColor;
+            const arrowhead = edge.arrowhead || 'arrow'; // default to 'arrow'
+            const markerId = arrowhead === 'none' ? '' : this.renderer.markerUrl(arrowhead);
+            const edgeWidth = GraphMetrics.effectiveEdgeWidth(edge, 1.4, edgeWidthDomain, edgeWidthOptions);
+            const path = this.renderer.path(d, 'none', { color: edgeColor, width: edgeWidth }, { isEdge: true, edge, tooltip: this._edgeTooltipText(edge) });
+            if (edge.id) path.setAttribute('edgeId', edge.id);
+            if (edge.opacity != null && edge.opacity !== 1) {
+                path.setAttribute('opacity', String(edge.opacity));
+            }
+            if (markerId) path.setAttribute('marker-end', markerId);
+            // marker-start — a second, independent arrowhead/glyph at the
+            // SOURCE end (e.g. ArchiMate's composition/aggregation diamond,
+            // or assignment's filled ball, both drawn at the "whole"/source
+            // end while marker-end carries a different glyph or none at all).
+            // Existing edges that only ever set `arrowhead` are unaffected —
+            // this is purely additive.
+            if (edge.arrowheadStart && edge.arrowheadStart !== 'none') path.setAttribute('marker-start', this.renderer.markerUrl(edge.arrowheadStart));
+            // `lineStyle` ('solid'|'dashed'|'dotted') is the general form of
+            // the older boolean `edge.dashed` (kept working, still meaning
+            // 'dashed', for callers who never adopted lineStyle) — 'dotted'
+            // is the extra case neither `dashed` nor the old fixed pattern
+            // could express (ArchiMate's realization/access relationships).
+            const dashArray = LINE_STYLE_DASH[edge.lineStyle ?? (edge.dashed ? 'dashed' : 'solid')] ?? null;
+            if (dashArray) path.setAttribute('stroke-dasharray', dashArray);
+            // onEdgeClick was accepted as an option but never actually wired
+            // up to anything — direct DOM listener, same pattern node click
+            // already uses (bubbles fine regardless of hitTest).
+            if (onEdgeClick) path.style.cursor = 'pointer';
+            if (onEdgeClick) path.addEventListener('click', () => onEdgeClick(edge));
+
+            // Track edge selection for waypoint visibility (only show waypoints on selected edge)
+            path.addEventListener('click', (e) => {
+                e.stopPropagation(); // Prevent canvas deselection
+                this._selectedEdge = edge;
+                this._rerenderGraph(); // Redraw to update waypoint visibility
+            });
+
+            // A collapsed ancestor or the keyword filter hides some nodes
+            // (see nodeEls below) — hide their connecting edges too, or
+            // they'd dangle toward an invisible node instead of disappearing
+            // with it.
+            const edgeHidden = hiddenByCollapse.has(edge.source) || hiddenByCollapse.has(edge.target)
+                || hiddenByFilter.has(edge.source) || hiddenByFilter.has(edge.target);
+            if (edgeHidden) path.setAttribute('visibility', 'hidden');
+
+            if (edge.label) {
+                const midX = (x1 + x2) / 2;
+                const midY = (y1 + y2) / 2;
+                const defaultTooltip = `${sourceInfo.label} → ${targetInfo.label}: ${edge.label}`;
+
+                const labelEl = this.renderer.text(edge.label, midX, midY, { textAnchor: 'middle', fontSize: '9px', fill: '#636e72', paintOrder: 'stroke', stroke: '#fafbfc', 'stroke-width': '2px', 'stroke-linecap': 'butt', 'stroke-linejoin': 'miter', tooltip: edge.tooltip || defaultTooltip });
+                if (edgeHidden) labelEl.setAttribute('visibility', 'hidden');
+            }
+
+            // Independent end labels — a UML association's multiplicity
+            // ('0..1', '1..*', ...) shown near EACH end, distinct from the
+            // one midpoint `edge.label` above (e.g. the relationship's own
+            // name) — see dataModelDiagram's 'uml' notation, though this is
+            // a plain graphDiagram field, not data-model-specific. Placed
+            // 18% of the way in from each anchor, not right at it, so the
+            // text doesn't sit on top of an arrowhead/cardinality glyph.
+            if (edge.sourceLabel) {
+                const lx = x1 + (x2 - x1) * 0.18, ly = y1 + (y2 - y1) * 0.18;
+                const labelEl = this.renderer.text(edge.sourceLabel, lx, ly, { textAnchor: 'middle', fontSize: '9px', fill: '#636e72', paintOrder: 'stroke', stroke: '#fafbfc', 'stroke-width': '2px', 'stroke-linecap': 'butt', 'stroke-linejoin': 'miter' });
+                if (edgeHidden) labelEl.setAttribute('visibility', 'hidden');
+            }
+            if (edge.targetLabel) {
+                const lx = x2 + (x1 - x2) * 0.18, ly = y2 + (y1 - y2) * 0.18;
+                const labelEl = this.renderer.text(edge.targetLabel, lx, ly, { textAnchor: 'middle', fontSize: '9px', fill: '#636e72', paintOrder: 'stroke', stroke: '#fafbfc', 'stroke-width': '2px', 'stroke-linecap': 'butt', 'stroke-linejoin': 'miter' });
+                if (edgeHidden) labelEl.setAttribute('visibility', 'hidden');
+            }
+
+            // Manual bend points (see _computeEdgePath's waypoints branch and
+            // the drag/double-click handlers in _addDragListeners) only need a
+            // visible/draggable handle in editable mode — a non-editable
+            // diagram still routes through them, it just can't gain new ones.
+            // Only show waypoints when this edge is selected (reduces clutter).
+            if (editable && this._selectedEdge === edge) selectionHandles.push(() => {
+                // Endpoint handles (source and target) — red circles, draggable to reposition on node rim
+                const endpointHandleColor = '#ff6b6b';
+                {
+                    const sourceHandle = this.renderer.circle(x1, y1, 5, '#ffffff', { color: endpointHandleColor, width: 2 }, { draggable: true, isEndpoint: true, edge, endpointType: 'source' });
+                    sourceHandle.style.cursor = 'grab';
+                    sourceHandle.setAttribute(EDGE_HANDLE_ATTR, '');
+                    if (edgeHidden) sourceHandle.setAttribute('visibility', 'hidden');
+
+                    const targetHandle = this.renderer.circle(x2, y2, 5, '#ffffff', { color: endpointHandleColor, width: 2 }, { draggable: true, isEndpoint: true, edge, endpointType: 'target' });
+                    targetHandle.style.cursor = 'grab';
+                    targetHandle.setAttribute(EDGE_HANDLE_ATTR, '');
+                    if (edgeHidden) targetHandle.setAttribute('visibility', 'hidden');
+                }
+
+                // Waypoint handles (blue circles for manual bends)
+                if (edge.waypoints?.length) {
+                    edge.waypoints.forEach((wp, waypointIndex) => {
+                        const handle = this.renderer.circle(wp.x, wp.y, 4, '#ffffff', { color: '#4f8ef7', width: 2 }, { draggable: true, isWaypoint: true, edge, waypointIndex });
+                        handle.style.cursor = 'move';
+                        handle.setAttribute(EDGE_HANDLE_ATTR, '');
+                        if (edgeHidden) handle.setAttribute('visibility', 'hidden');
+                    });
+                }
+            });
+            return path;
+        }).filter(Boolean);
+
+        // Draw edge-crossing bridges (small arcs where edges cross)
+        const edgePaths = edgeEls.map(el => el ? el.getAttribute('d') : null).filter(Boolean);
+        if (edgePaths.length > 1) {
+            // Detect all pairwise crossings
+            const allCrossings = [];
+            for (let i = 0; i < edgePaths.length; i++) {
+                for (let j = i + 1; j < edgePaths.length; j++) {
+                    const crossings = EdgeGeometry.findEdgeCrossings(edgePaths[i], [edgePaths[j]]);
+                    allCrossings.push(...crossings);
+                }
+            }
+
+            // Draw bridges at each crossing (small semicircle arcs)
+            for (const crossing of allCrossings) {
+                const bridgeRadius = 6;
+                const dx = Math.cos(crossing.angle);
+                const dy = Math.sin(crossing.angle);
+                const px = crossing.x - dy * bridgeRadius;
+                const py = crossing.y + dx * bridgeRadius;
+                const qx = crossing.x + dy * bridgeRadius;
+                const qy = crossing.y - dx * bridgeRadius;
+
+                const bridgePath = `M${px},${py} A${bridgeRadius},${bridgeRadius} 0 0,1 ${qx},${qy}`;
+                this.renderer.path(bridgePath, 'none', {
+                    color: '#ffffff',
+                    width: 8,
+                    opacity: 0.8
+                });
+                // Draw a thin line on top for visibility
+                this.renderer.path(bridgePath, 'none', {
+                    color: '#bdc3c7',
+                    width: 2,
+                    opacity: 1
+                });
+            }
+        }
+
+        const groups = new Map();
+        nodes.forEach(node => {
+            if (node.group && !groups.has(node.group)) {
+                groups.set(node.group, colors[groups.size % colors.length]);
+            }
+        });
+
+        // Get nodes hidden by collapsed folders
+        const { folders = [] } = this.data;
+        const hiddenByCollapsedFolders = this._getHiddenByCollapsedFolders(folders);
+
+        // Filter out nodes from hidden groups, collapsed subtrees, keyword filter, and collapsed folders
+            const visibleNodes = nodes.filter(node =>
+                (!node.group || !this._hiddenGraphGroups.has(node.group)) && !this._hiddenGraphNodes.has(node.id)
+                && !hiddenByCollapse.has(node.id) && !hiddenByFilter.has(node.id)
+                && !hiddenByCollapsedFolders.has(node.id)
+            );
+        const visibleNodeIds = new Set(visibleNodes.map(n => n.id));
+            const visibleEdges = effectiveEdges.filter(edge => visibleNodeIds.has(edge.source) && visibleNodeIds.has(edge.target));
+
+        const edgesTo = svgRoot?.childNodes?.length ?? 0;
+        // Render folders (visual containers) before nodes so they appear behind
+        this._renderFolders(this.renderer.svg, folders);
+
+        const nodeEls = nodes.map(node => {
+                const isHidden = this._hiddenGraphGroups.has(node.group) || this._hiddenGraphNodes.has(node.id)
+                    || hiddenByCollapse.has(node.id) || hiddenByFilter.has(node.id)
+                    || hiddenByCollapsedFolders.has(node.id);
+            const p = pos.get(node.id);
+
+            // Table nodes previously got just the bare label as a tooltip —
+            // real detail (column/row counts) already exists on the node
+            // object at this point but wasn't being surfaced on hover. Either
+            // way, any extra caller-supplied field not in the structural set
+            // (e.g. {owner:'Alice'}) is appended as its own "key: value" line.
+            const resolvedLabel = LabelHelper.resolveNodeLabel(node);
+            const tooltip = node.shape === 'table'
+                ? [
+                    `${resolvedLabel} — ${node.columns?.length ?? 0} column${node.columns?.length === 1 ? '' : 's'}` +
+                      (Number.isFinite(node.rowCount) ? ` · ${node.rowCount.toLocaleString()} row${node.rowCount === 1 ? '' : 's'}` : ''),
+                    ...LabelHelper.nodeExtraDataLines(node, this.structuralKeys('table')),
+                  ].join('\n')
+                : [`Node ${resolvedLabel}`, ...LabelHelper.nodeExtraDataLines(node, this.structuralKeys('node'))].join('\n');
+            const g = this.renderer.group({ transform: `translate(${p.x},${p.y})`, draggable: true, nodeId: node.id, tooltip });
+            if (node.opacity != null && node.opacity !== 1) {
+                g.setAttribute('opacity', String(node.opacity));
+            }
+
+                if (isHidden) {
+                g.setAttribute('visibility', 'hidden');
+            }
+
+            if (node.shape === 'table') {
+                NodeGeometry.buildTableNodeContent(this.renderer, g, node);
+            } else {
+                const nodeColor = node.color || (node.group ? groups.get(node.group) : (options.nodeColor || '#2ecc71'));
+                // A 'rect' node's own width/height (like a table node's, see
+                // _nodeSize) override the plain square-of-radius box every
+                // other shape still uses — needed for ArchiMate-style wider-
+                // than-tall boxes (archimateDiagram). nodeR (still used below
+                // for icon sizing/badge placement on non-rect shapes) is the
+                // radius that SAME square would have had, so nothing changes
+                // for a 'rect' node that never sets width/height.
+                const nodeSize = NodeGeometry.nodeSize(node, R, sizeDomain, sizeOptions);
+                const nodeR = Math.max(nodeSize.w, nodeSize.h) / 2;
+                const { el: shapeEl, suppressInner } = NodeGeometry.nodeShapeEl(this.renderer, node.shape, nodeR, nodeColor, nodeSize, node.cornerStyle, node.strokeColor, node.strokeWidth, node.iconUrl, node.icon);
+                if (node.strokeDasharray) shapeEl.setAttribute?.('stroke-dasharray', node.strokeDasharray);
+                g.appendChild(shapeEl);
+
+                // `iconShape` — a shape NAME (any _nodeShapeEl one) drawn
+                // small in the corner as line art, instead of an emoji/image
+                // badge. This is how the real ArchiMate notation works: the
+                // corner badge is the element's own standalone glyph at badge
+                // size (see archimateDiagram/_archimateBuildNode), so one
+                // vector glyph serves both. Drawn unfilled with a dark
+                // outline so it reads on top of the node's own fill.
+                // The icon is drawn in the outline colour; with no outline ('none') it stays black, as in Archi.
+                const markColor = node.strokeColor === 'none' ? '#000000' : node.strokeColor;
+                if (node.iconShape) {
+                    const badge = Math.max(10, Math.round(Math.min(nodeSize.w, nodeSize.h) * 0.3));
+                    const corner = NodeGeometry.nodeIconCorner(node, iconCornerByShape, iconCorner);
+                    const cp = NodeGeometry.cornerPoint({ x: 0, y: 0 }, nodeSize, corner);
+                    const inset = badge / 2 + 3;
+                    const bx = cp.x + (corner.includes('right') ? -inset : inset);
+                    const by = cp.y + (corner.includes('bottom') ? -inset : inset);
+                    const { el: badgeEl } = NodeGeometry.nodeShapeEl(
+                        this.renderer, node.iconShape, badge / 2, 'none', { w: badge, h: badge * 0.78 }, undefined,
+                        markColor || '#000000', 1,
+                    );
+                    badgeEl.setAttribute('transform', `translate(${bx},${by})`);
+                    badgeEl.setAttribute('pointer-events', 'none');
+                    g.appendChild(badgeEl);
+                }
+
+                const iconPosition = node.iconPosition || defaultIconPosition;
+                // A custom icon (an emoji/glyph string, or an image/SVG file via
+                // iconUrl) — centred on the shape (replacing the plain initials,
+                // 'center', the default) or a small corner badge ('corner', see
+                // _nodeIconCorner) alongside whatever else is in the box.
+                // suppressInner still gates 'center' mode only — a 'person'
+                // shape (which draws its own head/body glyph) stays uncluttered
+                // there, but a corner badge sits well clear of that glyph.
+                if (iconPosition === 'corner' && (node.icon || node.iconUrl)) {
+                    // Sized off the box's SMALLER dimension, not nodeR (which
+                    // is max(w,h)/2 — for a wide-but-short ArchiMate-style
+                    // box that would badly oversize the corner badge).
+                    const badgeSize = Math.max(12, Math.round(Math.min(nodeSize.w, nodeSize.h) * 0.3));
+                    const corner = NodeGeometry.nodeIconCorner(node, iconCornerByShape, iconCorner);
+                    const cp = NodeGeometry.cornerPoint({ x: 0, y: 0 }, nodeSize, corner);
+                    const inset = badgeSize / 2 + 2; // keep the badge inside the box, not straddling its edge
+                    const bx = cp.x + (corner.includes('right') ? -inset : inset);
+                    const by = cp.y + (corner.includes('bottom') ? -inset : inset);
+                    if (node.iconUrl) {
+                        g.appendChild(this.renderer.image(node.iconUrl, bx - badgeSize / 2, by - badgeSize / 2, badgeSize, badgeSize, { 'pointer-events': 'none' }));
+                    } else {
+                        // Badge colour follows the node's own outline colour —
+                        // white reads on plain graphDiagram's saturated node
+                        // fills, but vanishes on an ArchiMate box's pastel one
+                        // (which sets strokeColor: '#000').
+                        g.appendChild(this.renderer.text(node.icon, bx, by, { fill: markColor || '#fff', textAnchor: 'middle', verticalAlign: 'middle', fontSize: `${badgeSize}px`, 'pointer-events': 'none' }));
+                    }
+                    // A node with a real glyph badge (iconShape, drawn above)
+                    // must not ALSO get the centred initials fallback below —
+                    // that's what put a stray "RE"/"CA" in the middle of every
+                    // ArchiMate box once emoji badges gave way to glyphs.
+                } else if (!suppressInner && !node.iconShape && (!node.viewObject || node.iconUrl)) {
+                    // (A view-only box shows its own text: no initials, but its picture if it has one.)
+                    if (node.iconUrl) {
+                        const iconSize = nodeR * 1.3;
+                        g.appendChild(this.renderer.image(node.iconUrl, -iconSize / 2, -iconSize / 2, iconSize, iconSize, { 'pointer-events': 'none' }));
+                    } else {
+                        const centerText = node.icon || resolvedLabel.slice(0, 2).toUpperCase() || (node.id ?? '').slice(0, 2).toUpperCase();
+                        const fontSize = node.icon ? Math.max(12, Math.round(nodeR * 1.1)) : 10;
+                        g.appendChild(this.renderer.text(centerText, 0, 0, { fill: '#fff', textAnchor: 'middle', verticalAlign: 'middle', fontSize: `${fontSize}px`, fontWeight: node.icon ? 'normal' : 'bold', 'pointer-events': 'none' }));
+                    }
+                }
+
+                // 'below' (default) keeps the original single-line caption-
+                // under-the-shape convention; 'inside' (ArchiMate-style
+                // boxes) left-aligns the label near the box's own top-left
+                // instead, WORD-WRAPPED (_wrapLabelLines) to as many lines as
+                // fit inside the real box (nodeSize, not the icon-sizing
+                // nodeR above — a wide-but-short rect must not push it far
+                // below) rather than a single line overflowing the edges.
+                // Image objects draw their own visual, so they skip labels.
+                if (node.shape !== 'image') {
+                    const labelPosition = node.labelPosition || (node.shape === 'note' ? 'inside' : defaultLabelPosition);
+                    const inside = labelPosition === 'inside';
+                    const textAlign = node.textAlign || defaultTextAlign || (inside ? 'left' : 'center');
+                    const verticalAlign = node.verticalAlign || defaultVerticalAlign || 'top';
+                    const anchorByAlign = { left: 'start', center: 'middle', right: 'end' };
+                    const textAnchor = anchorByAlign[textAlign] || 'start';
+                    if (inside) {
+                        // The node's own font when it has one (an Archi import: points, as Archi sizes them).
+                        const FONT_SIZE = GraphDiagram.fontPixels(node.fontSize) ?? 10;
+                        const PAD = 6, LINE_HEIGHT = Math.round(FONT_SIZE * 1.2);
+                        const font = {
+                            fill: node.textColor || '#222', fontSize: `${FONT_SIZE}px`,
+                            ...(node.fontFamily && { fontFamily: node.fontFamily }),
+                            ...(node.fontWeight && { fontWeight: node.fontWeight }),
+                            ...(node.fontStyle && { fontStyle: node.fontStyle }),
+                        };
+                        // A badge in a top corner takes its width off that side of the text, as in Archi.
+                        const hasBadge = node.iconShape || (iconPosition === 'corner' && (node.icon || node.iconUrl));
+                        const badgeCorner = hasBadge ? NodeGeometry.nodeIconCorner(node, iconCornerByShape, iconCorner) : '';
+                        const badgeWidth = hasBadge && badgeCorner.includes('top') ? Math.max(12, Math.round(Math.min(nodeSize.w, nodeSize.h) * 0.3)) + 4 : 0;
+                        const insetLeft = badgeCorner.includes('left') ? badgeWidth : 0;
+                        const insetRight = badgeCorner.includes('right') ? badgeWidth : 0;
+                        const lines = LabelHelper.wrapLabelLines(resolvedLabel, nodeSize.w - PAD * 2 - insetLeft - insetRight, FONT_SIZE, nodeSize.h - PAD * 2, LINE_HEIGHT,
+                            this.renderer.measureText ? (s) => this.renderer.measureText(s, font) : null);
+                        const { x, baseline: y0 } = TextStyle.block({ textAlign, textPosition: verticalAlign },
+                            { left: -nodeSize.w / 2 + insetLeft, right: nodeSize.w / 2 - insetRight, top: -nodeSize.h / 2, bottom: nodeSize.h / 2 },
+                            lines.length, { pixels: FONT_SIZE, lineHeight: LINE_HEIGHT, pad: PAD });
+                        lines.forEach((line, i) => {
+                            g.appendChild(this.renderer.text(line, x, y0 + i * LINE_HEIGHT, { ...font, textAnchor, 'pointer-events': 'none' }));
+                        });
+                    } else {
+                        // nodeSize.h/2 (the shape's own real bottom edge), not
+                        // nodeR (max(w,h)/2 — for a wide-but-short shape, e.g. any
+                        // archimateDiagram distinct notation shape at its usual
+                        // 120x55-ish box footprint, nodeR badly overshoots the
+                        // shape's actual visual height, sitting the label so far
+                        // down it lands on top of the NEXT row in a dense grid
+                        // instead of just under this node). For a shape that
+                        // ignores non-square `size` entirely (person/diamond/the
+                        // plain default circle — always rendered from R alone),
+                        // nodeSize.h still equals 2*R when no explicit
+                        // width/height override is set, so this is a no-op there.
+                        let x;
+                        if (textAlign === 'left') x = -nodeSize.w / 2;
+                        else if (textAlign === 'right') x = nodeSize.w / 2;
+                        else x = 0;
+                        g.appendChild(this.renderer.text(resolvedLabel, x, nodeSize.h / 2 + 9, { fill: '#333', textAnchor, fontSize: '9px', 'pointer-events': 'none' }));
+                    }
+                }
+
+                // Hierarchical-key mode only: a +/− badge on any node with
+                // children toggles its subtree's visibility (_graphCollapsedNodes,
+                // read back into hiddenByCollapse above on the next render).
+                // stopPropagation keeps this click from also bubbling to the
+                // node's own onNodeClick listener below.
+                if (childrenMap?.get(node.id)?.length) {
+                    const collapsed = this._graphCollapsedNodes.has(node.id);
+                    const badgeY = nodeR + 20; // below the label (at nodeR+9) so it doesn't overlap the node circle or its text
+                    const badge = this.renderer.circle(0, badgeY, 6, '#ffffff', { color: '#888', width: 1.2 });
+                    const badgeGlyph = this.renderer.text(collapsed ? '+' : '−', 0, badgeY, {
+                        textAnchor: 'middle', verticalAlign: 'middle', fontSize: '9px', fontWeight: 'bold', fill: '#555', 'pointer-events': 'none',
+                    });
+                    badge.style.cursor = 'pointer';
+                    badge.addEventListener('click', (event) => {
+                        event.stopPropagation();
+                        if (collapsed) this._graphCollapsedNodes.delete(node.id);
+                        else this._graphCollapsedNodes.add(node.id);
+                        this._rerenderGraph();
+                    });
+                    g.appendChild(badge);
+                    g.appendChild(badgeGlyph);
+                }
+            }
+
+            if (onNodeClick) {
+                g.addEventListener('click', () => onNodeClick(node));
+            }
+            return g;
+        });
+        if (edgesOnTop && svgRoot?.childNodes) {
+            // Re-append the lines (and their labels and bridges), in order, above every box.
+            for (const el of Array.from(svgRoot.childNodes).slice(edgesFrom, edgesTo)) svgRoot.appendChild(el);
+        }
+        for (const draw of selectionHandles) draw();
+
+        if (showLegend && groups.size > 0) {
+            const legendX = W - 120;
+            let legendY = 40;
+            const legendItemHeight = 20;
+            const legendMarkerRadius = 6;
+
+            const legendGroup = this.renderer.group({ class: 'legend' });
+
+            groups.forEach((color, groupName) => {
+                const isHidden = this._hiddenGraphGroups.has(groupName);
+                const legendItemAttrs = { legendItem: true, graphLegend: true, groupName };
+                const itemColor = isHidden ? '#ccc' : color;
+                const textColor = isHidden ? '#ccc' : '#333';
+
+                const marker = this.renderer.circle(legendX, legendY, legendMarkerRadius, itemColor, { color: 'white', width: 1.5 }, legendItemAttrs);
+                const label = this.renderer.text(groupName, legendX + legendMarkerRadius + 8, legendY, {
+                    textAnchor: 'start',
+                    verticalAlign: 'middle',
+                    fontSize: '12px',
+                    fill: textColor,
+                    ...legendItemAttrs
+                });
+                marker.addEventListener('click', () => this._onLegendClick(groupName));
+                label.addEventListener('click', () => this._onLegendClick(groupName));
+                legendY += legendItemHeight;
+            });
+        }
+
+        // A click anywhere but on the selected line's handles deselects it: empty canvas, a shape, the
+        // grid, a group. Listened in the capture phase (a shape stops its own click from bubbling); a
+        // click on a line selects that one (its own listener). The handles are removed in place rather
+        // than by redrawing, which would replace a shape under a double-click.
+        if (this.renderer.svg) {
+            this.renderer.svg.removeEventListener('click', this._handleCanvasClick, true);
+            this._handleCanvasClick = (e) => this.deselectEdgeOnClick(e.target);
+            this.renderer.svg.addEventListener('click', this._handleCanvasClick, true);
+        }
+
+        // The engine keeps the selection (several nodes), so it outlives a redraw.
+        this._showNodeSelection(nodeEls);
+
+        this._graph = {
+            nodes, edges: visibleEdges, pos, nodeEls, edgeEls, nodeRadius: R, groups,
+            contextMenuItems, edgeContextMenuItems, canvasContextMenuItems, editable,
+            sizeDomain, sizeOptions,
+            resizableDefault: resizable, resizeCorner, resizeCornerByShape,
+        };
+    }
+
+    static inferHierarchyEdges(nodes, explicitEdges = []) {
+        const HIER_KEY_RE = /^\d+(?:[./-]\d+)+$/;
+        if (!nodes.some(n => HIER_KEY_RE.test(String(n.id)))) return null;
+        const isHierId = (id) => /^\d+(?:[./-]\d+)*$/.test(String(id));
+        const nodeIds = new Set(nodes.map(n => n.id));
+        const edges = [];
+        const seen = new Set();
+        nodes.forEach(n => {
+            const m = String(n.id).match(/^(.+)[./-]\d+$/);
+            const parentId = m ? m[1] : null;
+            if (parentId && nodeIds.has(parentId)) {
+                edges.push({ source: parentId, target: n.id });
+                seen.add(`${parentId}\u0000${n.id}`);
+            }
+        });
+        explicitEdges.forEach(e => {
+            if (isHierId(e.source) && isHierId(e.target)) return; // superseded by the inferred parent/child above
+            const key = `${e.source}\u0000${e.target}`;
+            if (seen.has(key)) return;
+            seen.add(key);
+            edges.push(e);
+        });
+        return edges;
+    }
+    _inferHierarchyEdges(nodes, explicitEdges = []) {
+        return GraphDiagram.inferHierarchyEdges(nodes, explicitEdges);
+    }
+
+    static hierarchyChildrenMap(edges) {
+        const map = new Map();
+        edges.forEach(e => {
+            if (!map.has(e.source)) map.set(e.source, []);
+            map.get(e.source).push(e.target);
+        });
+        return map;
+    }
+    _hierarchyChildrenMap(edges) {
+        return GraphDiagram.hierarchyChildrenMap(edges);
+    }
+
+    static collapsedDescendantIds(collapsedIds, childrenMap) {
+        const hidden = new Set();
+        const visit = (id) => {
+            for (const child of (childrenMap.get(id) || [])) {
+                if (!hidden.has(child)) { hidden.add(child); visit(child); }
+            }
+        };
+        collapsedIds.forEach(visit);
+        return hidden;
+    }
+    _collapsedDescendantIds(collapsedIds, childrenMap) {
+        return GraphDiagram.collapsedDescendantIds(collapsedIds, childrenMap);
+    }
+
+    static computeTreeLayout(nodes, edges, W, H, PAD) {
+        const childrenMap = GraphDiagram.hierarchyChildrenMap(edges);
+        const hasParent = new Set(edges.map(e => e.target));
+        const roots = nodes.filter(n => !hasParent.has(n.id)).map(n => n.id);
+
+        const depth = new Map();
+        const leafOrder = [];
+        const visited = new Set();
+        const visit = (id, d) => {
+            if (visited.has(id)) return;
+            visited.add(id);
+            depth.set(id, d);
+            const kids = childrenMap.get(id) || [];
+            if (kids.length === 0) leafOrder.push(id);
+            else kids.forEach(k => visit(k, d + 1));
+        };
+        roots.forEach(id => visit(id, 0));
+        nodes.forEach(n => { if (!visited.has(n.id)) visit(n.id, 0); }); // any node an edge cycle left unreached becomes its own root
+
+        const slot = new Map();
+        leafOrder.forEach((id, i) => slot.set(id, i));
+        const computeSlot = (id, seen) => {
+            if (slot.has(id)) return slot.get(id);
+            if (seen.has(id)) return 0; // guards a malformed/cyclic edge set
+            seen.add(id);
+            const kids = childrenMap.get(id) || [];
+            const s = kids.reduce((sum, k) => sum + computeSlot(k, seen), 0) / kids.length;
+            slot.set(id, s);
+            return s;
+        };
+        nodes.forEach(n => computeSlot(n.id, new Set()));
+
+        const maxDepth = Math.max(0, ...Array.from(depth.values()));
+        const numLeaves = Math.max(1, leafOrder.length);
+        const pos = new Map();
+        nodes.forEach(n => {
+            const d = depth.get(n.id) ?? 0;
+            const s = slot.get(n.id) ?? 0;
+            const x = numLeaves === 1 ? W / 2 : PAD + (s / (numLeaves - 1)) * (W - 2 * PAD);
+            const y = maxDepth === 0 ? H / 2 : PAD + (d / maxDepth) * (H - 2 * PAD);
+            pos.set(n.id, { x, y, vx: 0, vy: 0 });
+        });
+        return pos;
+    }
+    _computeTreeLayout(nodes, edges, W, H, PAD) {
+        return GraphDiagram.computeTreeLayout(nodes, edges, W, H, PAD);
+    }
+
+    static nodeMatchesKeyword(node, keyword, { nodeStructuralKeys, tableNodeStructuralKeys }) {
+        const structuralKeys = node.shape === 'table' ? tableNodeStructuralKeys : nodeStructuralKeys;
+        const haystack = [LabelHelper.resolveNodeLabel(node), ...LabelHelper.nodeExtraDataLines(node, structuralKeys)].join(' ').toLowerCase();
+        return haystack.includes(String(keyword).toLowerCase());
+    }
+    _nodeMatchesKeyword(node, keyword) {
+        return GraphDiagram.nodeMatchesKeyword(node, keyword, {
+            nodeStructuralKeys: this.structuralKeys('node'),
+            tableNodeStructuralKeys: this.structuralKeys('table'),
+        });
+    }
+
+    static hiddenByKeywordFilter(nodes, keyword, childrenMap = null, { nodeStructuralKeys, tableNodeStructuralKeys }) {
+        const hidden = new Set();
+        if (!keyword) return hidden;
+        const matchedIds = nodes.filter(n => GraphDiagram.nodeMatchesKeyword(n, keyword, { nodeStructuralKeys, tableNodeStructuralKeys })).map(n => n.id);
+        let keepVisible;
+        if (childrenMap) {
+            const parentOf = new Map();
+            childrenMap.forEach((kids, parent) => kids.forEach(kid => parentOf.set(kid, parent)));
+            keepVisible = new Set();
+            matchedIds.forEach(id => {
+                let cur = id;
+                while (cur != null && !keepVisible.has(cur)) {
+                    keepVisible.add(cur);
+                    cur = parentOf.get(cur);
+                }
+            });
+        } else {
+            keepVisible = new Set(matchedIds);
+        }
+        nodes.forEach(n => { if (!keepVisible.has(n.id)) hidden.add(n.id); });
+        return hidden;
+    }
+    _hiddenByKeywordFilter(nodes, keyword, childrenMap = null) {
+        return GraphDiagram.hiddenByKeywordFilter(nodes, keyword, childrenMap, {
+            nodeStructuralKeys: this.structuralKeys('node'),
+            tableNodeStructuralKeys: this.structuralKeys('table'),
+        });
+    }
+
+    static edgeTooltipText(edge, { edgeStructuralKeys }) {
+        const lines = LabelHelper.nodeExtraDataLines(edge, edgeStructuralKeys);
+        if (!lines.length) return undefined;
+        return [`Edge ${edge.source} → ${edge.target}`, ...lines].join('\n');
+    }
+    _edgeTooltipText(edge) {
+        return GraphDiagram.edgeTooltipText(edge, {
+            edgeStructuralKeys: this.structuralKeys('edge'),
+        });
+    }
+
+    static generateNodeId(label, existingIds = []) {
+        const base = (label || 'node').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-+|-+$)/g, '') || 'node';
+        const existing = new Set(existingIds);
+        if (!existing.has(base)) return base;
+        let i = 2;
+        while (existing.has(`${base}-${i}`)) i++;
+        return `${base}-${i}`;
+    }
+    _generateNodeId(label) {
+        const existingIds = (this._chartState?.nodes ?? []).map(n => n.id);
+        return GraphDiagram.generateNodeId(label, existingIds);
+    }
+    _insertEdgeWaypoint(edge, point) {
+        const sourcePos = this._graph?.pos?.get(edge.source), targetPos = this._graph?.pos?.get(edge.target);
+        if (!sourcePos || !targetPos) return;
+        const oldWaypoints = edge.waypoints ? edge.waypoints.slice() : [];
+        const waypoints = EdgeGeometry.edgeWaypointsWithInsertion(edge, sourcePos, targetPos, point);
+        // Find where the new point landed in the recomputed array.
+        let insertedIndex = -1;
+        for (let i = 0; i < waypoints.length; i++) {
+            if (i >= oldWaypoints.length || waypoints[i] !== oldWaypoints[i]) {
+                insertedIndex = i;
+                break;
+            }
+        }
+        if (insertedIndex < 0) insertedIndex = waypoints.length - 1;
+        // Keep edge selected after adding waypoint so endpoints remain visible
+        this._selectedEdge = edge;
+        this.history.execute(new AddWaypointCommand(edge, waypoints[insertedIndex], { diagram: this, index: insertedIndex }));
+    }
+    /** The nodes selected together (a selection box, Ctrl-click): their ids. */
+    get selectedNodeIds() {
+        return this.engine?._selectedNodeIds ?? new Set();
+    }
+
+    /** Select these nodes (or add them, with `extend`), and show it. */
+    selectNodes(ids, { extend = false } = {}) {
+        if (!this.engine) return;
+        const next = extend ? new Set([...this.selectedNodeIds, ...ids]) : new Set(ids);
+        this.engine._selectedNodeIds = next;
+        this._showNodeSelection(this._graph?.nodeEls ?? []);
+    }
+
+    /** Mark the selected nodes' elements (an outline glow), and unmark the rest. @private */
+    _showNodeSelection(nodeEls) {
+        const selected = this.selectedNodeIds;
+        if (!selected.size && !this._showingSelection) return;   // nothing to mark or unmark
+        this._showingSelection = selected.size > 0;
+        for (const el of nodeEls) {
+            if (typeof el?.getAttribute !== 'function') continue;
+            const on = selected.has(el.getAttribute('nodeId'));
+            el.classList?.toggle('multi-selected', on);
+            el.style.filter = on ? 'drop-shadow(0 0 3px #0066cc) drop-shadow(0 0 1px #0066cc)' : '';
+        }
+    }
+
+    /**
+     * After a click on `target`: unless it is one of the selected line's
+     * handles, the line is no longer selected and its handles go.
+     * @returns {boolean} whether a line was deselected
+     */
+    deselectEdgeOnClick(target) {
+        if (!this._selectedEdge || target?.closest?.(`[${EDGE_HANDLE_ATTR}]`)) return false;
+        this._selectedEdge = null;
+        this.renderer.svg?.querySelectorAll(`[${EDGE_HANDLE_ATTR}]`).forEach(n => n.remove());
+        return true;
+    }
+
+    _updateGraphLayout() {
+        if (!this._graph) return;
+
+        const { nodes, edges, pos, nodeEls, edgeEls, nodeRadius: R, sizeDomain, sizeOptions } = this._graph;
+        const defaultEdgeRouting = this._chartState?.options?.edgeRouting || 'straight';
+
+        // Update node positions
+        nodeEls.forEach(g => {
+            const nodeId = g.getAttribute('nodeId');
+            const p = pos.get(nodeId);
+            g.setAttribute('transform', `translate(${p.x},${p.y})`);
+        });
+
+        const routingObstacles = nodes.map(n => {
+            const p = pos.get(n.id);
+            if (!p) return null;
+            const size = NodeGeometry.nodeSize(n, R, sizeDomain, sizeOptions);
+            return { id: n.id, x: p.x, y: p.y, r: Math.max(size.w, size.h) / 2 };
+        }).filter(Boolean);
+
+        // Update edge positions — routes through the same _computeEdgePath the
+        // initial draw in graphDiagram() uses, so a live drag frame doesn't
+        // visibly snap between two different geometry calculations.
+        edges.forEach((edge, i) => {
+            const edgeEl = edgeEls[i];
+            if (!edgeEl) return;
+            const sourceNode = pos.get(edge.source);
+            const targetNode = pos.get(edge.target);
+            if (!sourceNode || !targetNode) return;
+            const sourceInfo = nodes.find(n => n.id === edge.source);
+            const targetInfo = nodes.find(n => n.id === edge.target);
+            const sourceSize = this.engine._nodeSize(sourceInfo, R, sizeDomain, sizeOptions);
+            const targetSize = this.engine._nodeSize(targetInfo, R, sizeDomain, sizeOptions);
+            const edgeObstacles = routingObstacles.filter(o => o.id !== edge.source && o.id !== edge.target);
+            const { d } = EdgeGeometry.computeEdgePath(
+                sourceInfo, sourceNode, sourceSize, targetInfo, targetNode, targetSize, edge, defaultEdgeRouting, edgeObstacles
+            );
+            edgeEl.setAttribute('d', d);
+        });
+    }
+
+    /** Find the edge whose rendered path passes closest to (x,y), within
+     *  `tolerance` SVG units. Returns the edge object or null. Used to make
+     *  thin or angled lines easier to select/hover when the renderer's own
+     *  pixel-exact hitTest misses the actual stroke. */
+    findNearestEdge(x, y, tolerance = 14) {
+        if (!this._graph) return null;
+        const { nodes, edges, pos, nodeRadius: R, sizeDomain, sizeOptions } = this._graph;
+        const defaultEdgeRouting = this._chartState?.options?.edgeRouting || 'straight';
+        const tol2 = tolerance * tolerance;
+
+        const routingObstacles = nodes.map(n => {
+            const p = pos.get(n.id);
+            if (!p) return null;
+            const size = NodeGeometry.nodeSize(n, R, sizeDomain, sizeOptions);
+            return { id: n.id, x: p.x, y: p.y, r: Math.max(size.w, size.h) / 2 };
+        }).filter(Boolean);
+
+        let bestEdge = null;
+        let bestDist2 = Infinity;
+
+        for (const edge of edges) {
+            const sourcePos = pos.get(edge.source);
+            const targetPos = pos.get(edge.target);
+            if (!sourcePos || !targetPos) continue;
+            const sourceInfo = nodes.find(n => n.id === edge.source);
+            const targetInfo = nodes.find(n => n.id === edge.target);
+            const sourceSize = this.engine._nodeSize(sourceInfo, R, sizeDomain, sizeOptions);
+            const targetSize = this.engine._nodeSize(targetInfo, R, sizeDomain, sizeOptions);
+            const edgeObstacles = routingObstacles.filter(o => o.id !== edge.source && o.id !== edge.target);
+            const { d } = EdgeGeometry.computeEdgePath(
+                sourceInfo, sourcePos, sourceSize, targetInfo, targetPos, targetSize, edge, defaultEdgeRouting, edgeObstacles
+            );
+            const dist2 = EdgeGeometry.pathDistance2(d, x, y);
+            if (dist2 < tol2 && dist2 < bestDist2) {
+                bestDist2 = dist2;
+                bestEdge = edge;
+            }
+        }
+        return bestEdge;
+    }
+
+    _getContextMenu() {
+        if (!this._contextMenu && this.engine?.container) {
+            this._contextMenu = new ContextMenu(this.engine.container);
+        }
+        return this._contextMenu;
+    }
+
+    _showNodeContextMenu(event, nodeId) {
+        const node = this._graph.nodes.find(n => n.id === nodeId);
+        if (!node) return;
+
+        const userItems = this._graph.contextMenuItems;
+        let menuItems;
+        if (userItems) {
+            menuItems = userItems;
+        } else {
+            menuItems = [
+                {
+                    label: (node) => this._graphFixedPos.has(node.id) ? 'Unpin Node' : 'Pin Node',
+                    action: (node) => {
+                        this._graphFixedPos.has(node.id)
+                            ? this._graphFixedPos.delete(node.id)
+                            : this._graphFixedPos.add(node.id);
+                    }
+                },
+                ...(this._graph.editable ? [{
+                    label: 'Rename Node',
+                    action: (node) => {
+                        const next = window.prompt('Rename node:', node.label ?? '');
+                        if (next == null) return;
+                        const trimmed = next.trim();
+                        if (trimmed === (node.label ?? '')) return;
+                        this.history.execute(new RenameNodeCommand(
+                            node.id, node.label ?? '', trimmed,
+                            { diagram: this, onRename: this._chartState?.options?.onNodeRename }
+                        ));
+                    }
+                }] : []),
+                {
+                    label: 'Show Details in Console',
+                    action: (node) => console.log('Node Details:', node)
+                },
+                {
+                    label: 'Hide Node',
+                    action: (node) => {
+                        this._hiddenGraphNodes.add(node.id);
+                        this._rerenderGraph();
+                    }
+                },
+                {
+                    label: 'Delete Node',
+                    action: (node) => {
+                        const dangling = this._chartState.edges.filter(e => e.source === node.id || e.target === node.id);
+                        this.history.execute(new DeleteNodeCommand(node, dangling, { diagram: this }));
+                    }
+                }
+            ];
+
+            if (this._hiddenGraphNodes.size > 0) {
+                menuItems.push({ separator: true });
+                menuItems.push({
+                    label: 'Show All Hidden Nodes',
+                    action: () => {
+                        this._hiddenGraphNodes.clear();
+                        this._rerenderGraph();
+                    }
+                });
+            }
+        }
+
+        this._getContextMenu()?.show(event, menuItems, node, (clientX, clientY) => SvgCoordinate.clientToSvgPoint(this.renderer?.svg, clientX, clientY), this.engine);
+    }
+    _showEdgeContextMenu(event, edge) {
+        const menuItems = this._graph.edgeContextMenuItems || [
+            {
+                label: 'Rename Edge',
+                action: (edge) => {
+                    const next = window.prompt('Rename edge:', edge.label ?? '');
+                    if (next == null) return;
+                    const trimmed = next.trim();
+                    if (trimmed === (edge.label ?? '')) return;
+                    this.history.execute(new RenameEdgeCommand(
+                        edge, edge.label ?? '', trimmed,
+                        { diagram: this, onRename: this._chartState?.options?.onEdgeRename }
+                    ));
+                }
+            },
+            {
+                label: 'Invert Direction',
+                action: (edge) => {
+                    this.history.execute(new InvertEdgeCommand(
+                        edge,
+                        { diagram: this, onInvert: this._chartState?.options?.onEdgeInvert }
+                    ));
+                }
+            },
+            // Where adding a bend point moved to once double-clicking the
+            // line itself was repurposed for onEdgeDoubleClick (see
+            // graphDiagram's own doc comment) — `point` is the right-click
+            // location _buildAndShowContextMenu now passes to every action.
+            { label: 'Add Waypoint Here', action: (edge, engine, point) => this._insertEdgeWaypoint(edge, point) },
+            {
+                label: 'Delete Edge',
+                action: (edge) => {
+                    this.history.execute(new DeleteEdgeCommand(
+                        edge,
+                        { diagram: this, onDelete: this._chartState?.options?.onEdgeDelete }
+                    ));
+                }
+            }
+        ];
+        this._getContextMenu()?.show(event, menuItems, edge, (clientX, clientY) => SvgCoordinate.clientToSvgPoint(this.renderer?.svg, clientX, clientY), this.engine);
+    }
+    _showCanvasContextMenu(event) {
+        const point = SvgCoordinate.clientToSvgPoint(this.renderer?.svg, event.clientX, event.clientY);
+        const menuItems = this._graph.canvasContextMenuItems || [
+            {
+                label: 'Add Node',
+                action: (point) => {
+                    const label = window.prompt('New node label:', '');
+                    if (label == null) return;
+                    const trimmed = label.trim();
+                    if (!trimmed) return;
+                    const gridSize = this._chartState?.options?.gridSize ?? 0;
+                    const id = this._generateNodeId(trimmed);
+                    const newNode = {
+                        id,
+                        label: trimmed,
+                        x: GraphDiagram.snapToGrid(point.x, gridSize),
+                        y: GraphDiagram.snapToGrid(point.y, gridSize),
+                    };
+                    this.history.execute(new AddNodeCommand(
+                        newNode,
+                        { diagram: this, onAdd: this._chartState?.options?.onNodeAdd }
+                    ));
+                }
+            },
+            {
+                label: 'Add Folder',
+                action: (point) => {
+                    const name = window.prompt('New folder name:', 'New Folder');
+                    if (name == null) return;
+                    const trimmed = name.trim();
+                    if (!trimmed) return;
+                    const gridSize = this._chartState?.options?.gridSize ?? 0;
+                    const folderId = `folder-${Math.random().toString(36).slice(2, 9)}`;
+                    const newFolder = {
+                        id: folderId,
+                        name: trimmed,
+                        x: GraphDiagram.snapToGrid(point.x, gridSize),
+                        y: GraphDiagram.snapToGrid(point.y, gridSize),
+                        width: 200,
+                        height: 150,
+                        collapsed: false,
+                    };
+                    // Add to folders in data
+                    if (!this.data.folders) this.data.folders = [];
+                    this.data.folders.push(newFolder);
+                    this._rerenderGraph();
+                }
+            }
+        ];
+        this._getContextMenu()?.show(event, menuItems, point, (clientX, clientY) => SvgCoordinate.clientToSvgPoint(this.renderer?.svg, clientX, clientY), this.engine);
+    }
+    _onLegendClick(groupName) {
+        if (this._hiddenGraphGroups.has(groupName)) {
+            this._hiddenGraphGroups.delete(groupName);
+        } else {
+            this._hiddenGraphGroups.add(groupName);
+        }
+        this._rerenderGraph();
+    }
+
+    /**
+     * Handle clicks on diagram chrome (e.g. the group legend).
+     * @param {MouseEvent} event
+     * @param {object} hitShape
+     */
+    onClick(event, hitShape) {
+        if (hitShape && hitShape.graphLegend) {
+            this._onLegendClick(hitShape.groupName);
+        }
+    }
+    filterGraphNodes(keyword) {
+        this._graphFilterKeyword = keyword ? String(keyword).trim() : '';
+        this._rerenderGraph();
+    }
+
+    /** Snap a coordinate to the nearest grid multiple. `gridSize <= 0` means no
+     *  snapping. Exposed as a static helper so drag/add-node code outside this
+     *  class can reuse the same rounding rule. */
+    static snapToGrid(value, gridSize) {
+        if (!gridSize || gridSize <= 0) return value;
+        return Math.round(value / gridSize) * gridSize;
+    }
+
+    /** A single path string covering a W×H area with a grid of `gridSize`
+     *  spacing — rendered as one cheap background path. */
+    static _gridPath(W, H, gridSize) {
+        const parts = [];
+        for (let x = gridSize; x < W; x += gridSize) parts.push(`M${x},0 L${x},${H}`);
+        for (let y = gridSize; y < H; y += gridSize) parts.push(`M0,${y} L${W},${y}`);
+        return parts.join(' ');
+    }
+
+    _rerenderGraph() {
+        // graphDiagram() reseeds every node's position from `n.x ?? Math.random()`
+        // on each call — nothing else ever writes the live/simulated/dragged
+        // position back onto the node object itself. Without carrying it
+        // forward here, a node being actively dragged would snap back to its
+        // pre-drag spot on the very next re-render (this is called on every
+        // drag mousemove), and any node without an explicit x/y would jump to
+        // a brand-new random position on every hide/show, delete, or legend
+        // toggle. Copying this._graph.pos back onto the node objects before
+        // re-invoking graphDiagram makes it a true "redraw with current state"
+        // instead of "reroll positions and redraw".
+        if (this._graph?.pos) {
+            for (const node of this._chartState.nodes) {
+                const p = this._graph.pos.get(node.id);
+                if (p) { node.x = p.x; node.y = p.y; }
+            }
+        }
+        this.data.nodes = this._chartState.nodes;
+        this.data.edges = this._chartState.edges;
+        this.options = this._chartState.options;
+        this.render();
+    }
+
+    /** Render folder containers (before nodes so they appear behind) */
+    _renderFolders(svg, folders = []) {
+        if (!folders.length || !svg) return;
+        for (const folder of folders) {
+            this._renderFolderContainer(svg, folder);
+        }
+    }
+
+    /** Render a single folder container with border, header, and collapse toggle */
+    _renderFolderContainer(svg, folder) {
+        // A group needs a place; 0 is one.
+        if (!Number.isFinite(folder.x) || !Number.isFinite(folder.y)) return;
+        const HEADER_HEIGHT = 24;
+        const BORDER_COLOR = this._dragOverFolderId === folder.id ? '#44aa44' : '#999';
+        const FILL_COLOR = this._dragOverFolderId === folder.id ? 'rgba(68, 170, 68, 0.15)' : 'rgba(150, 150, 200, 0.08)';
+        const isCollapsed = this._collapsedFolders.has(folder.id);
+
+        // Folder background rectangle
+        const bgRect = this.renderer.rect(
+            folder.x, folder.y, folder.width || 150, folder.height || 100,
+            FILL_COLOR, { color: BORDER_COLOR, width: 1.5 }
+        );
+        svg.appendChild(bgRect);
+
+        // Folder header bar
+        const headerRect = this.renderer.rect(
+            folder.x, folder.y, folder.width || 150, HEADER_HEIGHT,
+            'rgba(150, 150, 200, 0.3)', { color: BORDER_COLOR, width: 1.5 }
+        );
+        headerRect.setAttribute('folderId', folder.id);
+        headerRect.setAttribute('class', 'folder-header');
+        headerRect.style.cursor = 'pointer';
+        svg.appendChild(headerRect);
+
+        // Collapse/expand indicator
+        const indicator = isCollapsed ? '▶' : '▼';
+        const indicatorText = this.renderer.text(indicator, folder.x + 4, folder.y + 16,
+            { fontSize: '12px', fill: '#333', cursor: 'pointer' }
+        );
+        indicatorText.setAttribute('folderId', folder.id);
+        indicatorText.setAttribute('class', 'folder-toggle');
+        svg.appendChild(indicatorText);
+
+        // Folder name label
+        const label = this.renderer.text(
+            LabelHelper.resolveNodeLabel({ label: folder.name }) || 'Folder',
+            folder.x + 22, folder.y + 16,
+            { fontSize: '12px', fontWeight: 'bold', fill: '#333', cursor: 'pointer' }
+        );
+        label.setAttribute('folderId', folder.id);
+        label.setAttribute('class', 'folder-label');
+        svg.appendChild(label);
+
+        // Add click handlers
+        headerRect.addEventListener('click', (e) => this._onFolderHeaderClick(e, folder.id));
+        headerRect.addEventListener('dblclick', (e) => this._onFolderRename(e, folder));
+        indicatorText.addEventListener('click', (e) => this._onFolderHeaderClick(e, folder.id));
+        label.addEventListener('click', (e) => this._onFolderHeaderClick(e, folder.id));
+        label.addEventListener('dblclick', (e) => this._onFolderRename(e, folder));
+    }
+
+    /** Handle folder header click — toggle collapse state */
+    _onFolderHeaderClick(event, folderId) {
+        event.stopPropagation();
+        if (this._collapsedFolders.has(folderId)) {
+            this._collapsedFolders.delete(folderId);
+        } else {
+            this._collapsedFolders.add(folderId);
+        }
+        this._rerenderGraph();
+    }
+
+    /** Handle folder rename (double-click) */
+    _onFolderRename(event, folder) {
+        event.stopPropagation();
+        const newName = window.prompt('Rename folder:', folder.name || 'Folder');
+        if (newName == null) return;
+        const trimmed = newName.trim();
+        if (!trimmed || trimmed === folder.name) return;
+
+        // Update folder name
+        folder.name = trimmed;
+        this._rerenderGraph();
+    }
+
+    /** Return IDs of all nodes within a given folder (recursively including nested folders) */
+    _getNodesInFolder(folderId) {
+        const nodeIds = new Set();
+        const elementFolderMap = this._chartState?.options?.elementFolderMap;
+        if (!elementFolderMap) return nodeIds;
+
+        const folders = this._chartState?.folders || [];
+
+        // Find all elements in this folder directly
+        for (const [elementId, folderIdForElement] of elementFolderMap.entries()) {
+            if (folderIdForElement === folderId) {
+                nodeIds.add(elementId);
+            }
+        }
+
+        // Recursively add elements in nested folders
+        for (const folder of folders) {
+            if (folder.parentId === folderId) {
+                for (const nodeId of this._getNodesInFolder(folder.id)) {
+                    nodeIds.add(nodeId);
+                }
+            }
+        }
+
+        return nodeIds;
+    }
+
+    /** Return IDs of all nodes hidden due to collapsed folders */
+    _getHiddenByCollapsedFolders(folders) {
+        if (!folders.length && !this._collapsedFolders.size) return new Set();
+        const hidden = new Set();
+        for (const folderId of this._collapsedFolders) {
+            const nodesInFolder = this._getNodesInFolder(folderId);
+            for (const nodeId of nodesInFolder) {
+                hidden.add(nodeId);
+            }
+        }
+        return hidden;
+    }
+
+}
+
+/**
+ * A font size in pixels: a number, "12px" or "9pt" (1pt = 4/3 px). Undefined when there is none.
+ * @param {number|string} [size]
+ * @returns {number|undefined}
+ */
+/** A font size in pixels (TextStyle.pixels: points are 4/3 of a pixel). */
+GraphDiagram.fontPixels = (size) => TextStyle.pixels(size);