@peter.prib/renderengine 0.0.0-stage → 0.2.0

package/src/charting/diagrams/NodeGeometry.js

@@ -0,0 +1,158 @@
+import { Glyph, glyphFor, drawGlyph } from '../glyphs/index.js';
+import { GraphMetrics } from './GraphMetrics.js';
+import { LabelHelper } from './LabelHelper.js';
+
+/**
+ * NodeGeometry — pure, stateless helpers for graph node sizing, corners,
+ * resize-handle math, and table-node geometry.
+ *
+ * These used to live on RenderEngine; they are collected here so diagram
+ * classes can compute node geometry without going through the engine façade.
+ */
+export class NodeGeometry {
+    static TABLE_NODE = { width: 170, headerH: 26, rowH: 18, pad: 6 };
+
+    /** Bounding box a node occupies, centred on its (x,y) — {w:2R,h:2R} for
+     *  the plain default (sized by GraphMetrics.effectiveNodeRadius when a
+     *  `sizeDomain` is supplied), the real card size for a `shape:'table'`
+     *  node (see NodeGeometry.tableNodeSize), or, for any OTHER shape, an
+     *  explicit `node.width`/`node.height` override for a wider-than-tall box. */
+    static nodeSize(node, R, sizeDomain, sizeOptions) {
+        if (node?.shape === 'table') return NodeGeometry.tableNodeSize(node);
+        const radius = GraphMetrics ? GraphMetrics.effectiveNodeRadius(node, R, sizeDomain, sizeOptions) : R;
+        if (Number.isFinite(node?.width) || Number.isFinite(node?.height)) {
+            return {
+                w: Number.isFinite(node.width) ? node.width : radius * 2,
+                h: Number.isFinite(node.height) ? node.height : radius * 2,
+            };
+        }
+        return { w: radius * 2, h: radius * 2 };
+    }
+
+    /** Size of a `shape:'table'` node — column-count-driven, never affected
+     *  by node.size/sizeDomain. */
+    static tableNodeSize(node) {
+        const { width, headerH, rowH, pad } = NodeGeometry.TABLE_NODE;
+        const cols = node.columns?.length ?? 0;
+        return { w: node.width || width, h: headerH + cols * rowH + pad };
+    }
+
+    /** World-space Y of a named column's row within a table node, for edge anchoring. */
+    static tableColumnY(node, posEntry, size, colName) {
+        const { headerH, rowH } = NodeGeometry.TABLE_NODE;
+        const idx = Math.max(0, (node.columns ?? []).findIndex(c => c.name === colName));
+        return posEntry.y - size.h / 2 + headerH + idx * rowH + rowH / 2;
+    }
+
+    /** Draws a table-card node's header + one row per column into wrapper `g`. */
+    static buildTableNodeContent(renderer, g, node) {
+        const { headerH, rowH } = NodeGeometry.TABLE_NODE;
+        const { w, h } = NodeGeometry.tableNodeSize(node);
+        const cols = node.columns ?? [];
+        const x0 = -w / 2, y0 = -h / 2;
+        const borderColor = node.selected ? '#4f8ef7' : '#cfd8dc';
+        const borderWidth = node.selected ? 2 : 1;
+
+        const TYPE_COLORS = { NUMBER: '#74b9ff', TEXT: '#a29bfe', TIMESTAMP: '#55efc4', BOOLEAN: '#ffeaa7', JSON: '#fd79a8', UNKNOWN: '#dfe6e9' };
+        g.appendChild(renderer.rect(x0, y0, w, h, '#ffffff', { color: borderColor, width: borderWidth }));
+        g.appendChild(renderer.rect(x0, y0, w, headerH, '#1976d2', null));
+        g.appendChild(renderer.text(LabelHelper.resolveNodeLabel(node), x0 + 8, y0 + headerH / 2, {
+            fill: '#fff', textAnchor: 'start', verticalAlign: 'middle', fontSize: '11px', fontWeight: 'bold', 'pointer-events': 'none',
+        }));
+        if (node.rowCount != null) {
+            g.appendChild(renderer.text(String(node.rowCount), x0 + w - 8, y0 + headerH / 2, {
+                fill: '#cfe3fb', textAnchor: 'end', verticalAlign: 'middle', fontSize: '9px', 'pointer-events': 'none',
+            }));
+        }
+
+        cols.forEach((col, i) => {
+            const rowY = y0 + headerH + i * rowH;
+            g.appendChild(renderer.circle(x0 + 12, rowY + rowH / 2, 3.5, TYPE_COLORS[col.typeGroup] ?? TYPE_COLORS.UNKNOWN, null));
+            g.appendChild(renderer.text(col.name, x0 + 20, rowY + rowH / 2, {
+                fill: '#333', textAnchor: 'start', verticalAlign: 'middle', fontSize: '10px', 'pointer-events': 'none',
+            }));
+            let badgeX = x0 + w - 8;
+            if (col.isFK) {
+                g.appendChild(renderer.text('FK', badgeX, rowY + rowH / 2, {
+                    fill: '#e67e22', textAnchor: 'end', verticalAlign: 'middle', fontSize: '8px', fontWeight: 'bold', 'pointer-events': 'none',
+                }));
+                badgeX -= 18;
+            }
+            if (col.isPK) {
+                g.appendChild(renderer.text('PK', badgeX, rowY + rowH / 2, {
+                    fill: '#00b894', textAnchor: 'end', verticalAlign: 'middle', fontSize: '8px', fontWeight: 'bold', 'pointer-events': 'none',
+                }));
+            }
+        });
+    }
+
+    /** Pure. The point at a given corner of a `size` (`{w,h}`) box centred on
+     *  `pos` — shared by the resize handle's screen positioning and a node's
+     *  icon-badge placement. */
+    static cornerPoint(pos, size, corner) {
+        return {
+            x: pos.x + (corner.includes('right') ? size.w / 2 : -size.w / 2),
+            y: pos.y + (corner.includes('bottom') ? size.h / 2 : -size.h / 2),
+        };
+    }
+
+    /** Pure. Generic 3-tier corner resolution — 'top-left'|'top-right'|
+     *  'bottom-left'|'bottom-right': a per-node `node[nodeKey]` override,
+     *  then a per-shape entry in `byShape` (keyed by `node.shape`, default
+     *  shape 'circle'), then `defaultCorner`. */
+    static resolveNodeCorner(node, nodeKey, byShape, defaultCorner) {
+        if (node?.[nodeKey]) return node[nodeKey];
+        const shapeCorner = byShape?.[node?.shape || 'circle'];
+        return shapeCorner || defaultCorner;
+    }
+
+    /** Pure. Which corner a node's resize handle sits at/drags from. */
+    static nodeResizeCorner(node, resizeCornerByShape, defaultCorner = 'top-right') {
+        return NodeGeometry.resolveNodeCorner(node, 'resizeCorner', resizeCornerByShape, defaultCorner);
+    }
+
+    /** Pure. Which corner a node's icon badge sits at when `iconPosition`
+     *  is `'corner'`. */
+    static nodeIconCorner(node, iconCornerByShape, defaultCorner = 'top-right') {
+        return NodeGeometry.resolveNodeCorner(node, 'iconCorner', iconCornerByShape, defaultCorner);
+    }
+
+    /** Pure. What dragging a node's resize handle to `mousePos` should set on
+     *  the node. */
+    static resizedNodeValue(node, corner, center, mousePos) {
+        const signX = corner.includes('right') ? 1 : -1;
+        const signY = corner.includes('bottom') ? 1 : -1;
+        if (node?.shape === 'table') {
+            const MIN_TABLE_WIDTH = 80;
+            return { width: Math.max(MIN_TABLE_WIDTH, Math.round(Math.abs(mousePos.x - center.x) * 2)) };
+        }
+        if (node?.shape === 'rect') {
+            const MIN_RECT_SIZE = 24;
+            const width = Math.max(MIN_RECT_SIZE, Math.round((mousePos.x - center.x) * signX * 2));
+            const height = Math.max(MIN_RECT_SIZE, Math.round((mousePos.y - center.y) * signY * 2));
+            return { width, height };
+        }
+        const MIN_RADIUS = 4;
+        const projected = ((mousePos.x - center.x) * signX + (mousePos.y - center.y) * signY) / 2;
+        return { radius: Math.max(MIN_RADIUS, Math.round(projected)) };
+    }
+
+    /** Pure. SVG path `d` for a `w`x`h` rectangle centred on the origin with
+     *  all four corners cut at 45° (an octagon) — see nodeShapeEl's
+     *  'chamfered' cornerStyle. `chamfer` (the cut's size) defaults to a
+     *  fraction of the box's smaller dimension so it scales sensibly with
+     *  the box rather than needing its own per-node configuration. */
+    static chamferedRectPath(w, h, chamfer) {
+        return Glyph.chamferedRectPath(w, h, chamfer);
+    }
+
+    /** Build the SVG element for a node's shape. Returns `{el, suppressInner}`
+     *  where `suppressInner` tells the caller not to draw a centred icon or
+     *  initials on top of busy distinct shapes. The shapes themselves are
+     *  Glyphs (src/charting/glyphs), shared with the editor's templates. */
+    static nodeShapeEl(renderer, shape, R, color, size, cornerStyle, strokeColor = '#fff', strokeWidth = 2, iconUrl = null, icon = null) {
+        const glyph = glyphFor(shape);
+        const ctx = Glyph.context({ R, size, color, cornerStyle, strokeColor, strokeWidth, iconUrl, icon });
+        return { el: drawGlyph(renderer, glyph.parts(ctx)), suppressInner: glyph.constructor.ownsInterior };
+    }
+}

package/src/charting/diagrams/PlaceItemsCommand.js

@@ -0,0 +1,77 @@
+import { Command } from '../CommandHistory.js';
+import { BackgroundCommand } from '../arrangement/index.js';
+import { pinnedBehind } from '../zOrder.js';
+
+/**
+ * PlaceItemsCommand — put new boxes and lines on an ArchiMate view (a
+ * template placed on a canvas, a paste), as one undo step: relationships
+ * drawn between the boxes too, and the model elements and relationships they
+ * show when the model lacks them (a paste from another model). They stack in front of
+ * what is there; given `background`, they become one locked background group
+ * instead (BackgroundGroup: behind everything not pinned, in front of any
+ * older background).
+ */
+export class PlaceItemsCommand extends Command {
+    /**
+     * @param {ArchimateView} view
+     * @param {Object} items
+     * @param {Array<ElementInstance>} items.elementInstances
+     * @param {Array<ViewConnectionInstance>} [items.viewConnections]
+     * @param {Array<RelationshipInstance>} [items.relationshipInstances]
+     * @param {Array<Object>} [items.elements] - Model elements to add with them
+     * @param {Array<Object>} [items.relationships] - Model relationships to add with them
+     * @param {Object} [options]
+     * @param {{name?: string}|null} [options.background] - Make them a locked background group
+     * @param {string} [options.label]
+     */
+    constructor(view, { elementInstances, viewConnections = [], relationshipInstances = [], elements = [], relationships = [] }, { background = null, label = 'Place template' } = {}) {
+        super(label);
+        this.view = view;
+        this.elementInstances = elementInstances;
+        this.viewConnections = viewConnections;
+        this.relationshipInstances = relationshipInstances;
+        this.elements = elements;
+        this.relationships = relationships;
+        this._widened = [];
+        this.background = background;
+        /** The background group's id, once placed. */
+        this.groupId = null;
+        this._before = null;
+    }
+
+    execute() {
+        const { view } = this;
+        this._before = { arrangement: view.arrangement.toJSON(), z: new Map(view.layerItems().map(i => [i.id, i.zIndex])) };
+        for (const element of this.elements) view.model.addElement(JSON.parse(JSON.stringify(element)));
+        for (const relationship of this.relationships) view.model.addRelationship(JSON.parse(JSON.stringify(relationship)));
+        // A view that lists the elements it draws lists these too (mutated: others hold the array).
+        this._widened = view.elementIds ? [...new Set(this.elementInstances.map(i => i.elementId))].filter(id => view.model.getElement(id) && !view.elementIds.includes(id)) : [];
+        if (view.elementIds) view.elementIds.push(...this._widened);
+        // In front of everything there now, in their own order.
+        let z = Math.max(-1, ...view.layerItems().map(i => i.zIndex || 0)) + 1;
+        for (const inst of [...this.elementInstances].sort((a, b) => (a.zIndex || 0) - (b.zIndex || 0))) {
+            inst.zIndex = z++;
+            view.addElementInstance(inst);
+        }
+        for (const line of this.viewConnections) view.viewConnections.set(line.id, line);
+        for (const line of this.relationshipInstances) view.addRelationshipInstance(line);
+        if (!this.background) return;
+        const cmd = new BackgroundCommand(view.arrangement, this.elementInstances.map(i => i.id), { ...this.background, ...(this.groupId && { id: this.groupId }) });
+        cmd.apply();
+        this.groupId = cmd.groupId;
+        const stack = pinnedBehind(view.layerItems(), (id) => view.arrangement.isPinnedToBack(id));
+        for (const item of view.layerItems()) item.zIndex = stack.get(item.id);
+    }
+
+    undo() {
+        const { view } = this;
+        for (const inst of this.elementInstances) view.removeElementInstance(inst.id);
+        for (const line of this.viewConnections) view.viewConnections.delete(line.id);
+        for (const line of this.relationshipInstances) view.removeRelationshipInstance(line.id);
+        for (const id of this._widened) { const at = view.elementIds.indexOf(id); if (at >= 0) view.elementIds.splice(at, 1); }
+        for (const relationship of this.relationships) view.model.removeRelationship(relationship.id);
+        for (const element of this.elements) view.model.removeElement(element.id);
+        view.arrangement.restore(this._before.arrangement);
+        for (const item of view.layerItems()) if (this._before.z.has(item.id)) item.zIndex = this._before.z.get(item.id);
+    }
+}

package/src/charting/diagrams/RadialLayout.js

@@ -0,0 +1,101 @@
+/**
+ * RadialLayout — compute node positions for a radial tree view.
+ *
+ * Centers a primary element at origin, arranges related elements in a circle.
+ * Pure function, no side effects.
+ */
+export class RadialLayout {
+    /**
+     * Compute radial layout for an element and its connected neighbors.
+     *
+     * @param {string} centerElementId - the element to center
+     * @param {ArchimateModel} model - the model to query for relationships
+     * @param {object} options - { radius: 150, fontSize: 12 }
+     * @returns {object} { nodes, edges } ready for graphDiagram
+     */
+    static compute(centerElementId, model, options = {}) {
+        const { radius = 120, centerX = 150, centerY = 150 } = options;
+
+        const centerElement = model.getElement(centerElementId);
+        if (!centerElement) {
+            return { nodes: [], edges: [] };
+        }
+
+        // Find all elements connected via relationships
+        const connectedIds = new Set([centerElementId]);
+        const edges = [];
+        const relationships = model.relationships();
+
+        for (const rel of relationships) {
+            if (rel.source === centerElementId) {
+                connectedIds.add(rel.target);
+                edges.push({
+                    source: centerElementId,
+                    target: rel.target,
+                    kind: rel.kind,
+                    id: rel.id,
+                    label: rel.label,
+                    arrowhead: rel.arrowhead,
+                    arrowheadStart: rel.arrowheadStart,
+                });
+            } else if (rel.target === centerElementId) {
+                connectedIds.add(rel.source);
+                edges.push({
+                    source: rel.source,
+                    target: centerElementId,
+                    kind: rel.kind,
+                    id: rel.id,
+                    label: rel.label,
+                    arrowhead: rel.arrowhead,
+                    arrowheadStart: rel.arrowheadStart,
+                });
+            }
+        }
+
+        // Position nodes: center element in middle, neighbors in circle
+        const nodes = [];
+        const connectedArray = Array.from(connectedIds);
+        const centerIndex = connectedArray.indexOf(centerElementId);
+
+        for (let i = 0; i < connectedArray.length; i++) {
+            const id = connectedArray[i];
+            const elem = model.getElement(id);
+
+            if (id === centerElementId) {
+                // Center element in viewport center
+                nodes.push({
+                    id,
+                    label: elem.name || id,
+                    x: centerX,
+                    y: centerY,
+                    shape: 'rect',
+                    type: elem.type,
+                    layer: elem.layer,
+                    specialization: elem.specialization,
+                    properties: elem.properties,
+                });
+            } else {
+                // Arrange neighbors in circle around center
+                const neighborIndex = i < centerIndex ? i : i - 1;
+                const neighborCount = connectedArray.length - 1;
+                const angle = (neighborIndex / neighborCount) * 2 * Math.PI;
+                const x = centerX + Math.cos(angle) * radius;
+                const y = centerY + Math.sin(angle) * radius;
+
+                nodes.push({
+                    id,
+                    label: elem.name || id,
+                    x,
+                    y,
+                    shape: 'rect',
+                    type: elem.type,
+                    layer: elem.layer,
+                    specialization: elem.specialization,
+                    properties: elem.properties,
+                });
+            }
+        }
+
+        return { nodes, edges };
+    }
+}

package/src/charting/diagrams/RelationshipInstance.js

@@ -0,0 +1,93 @@
+/**
+ * RelationshipInstance — A projection of a model relationship into a specific view.
+ * Represents a single occurrence of a relationship with its own routing and
+ * visibility state. A view may have multiple instances of the same relationship,
+ * and each keeps its own route.
+ */
+export class RelationshipInstance {
+    /**
+     * Create a new relationship instance.
+     * @param {string} relationshipId - Reference to the model relationship (immutable)
+     * @param {Array<{x: number, y: number}>|null} [waypoints] - Bend points for this instance.
+     *   `null` inherits the model relationship's; `[]` is a deliberately straight line.
+     * @param {string} [sourceInstanceId] - ID of the specific source element instance this connects
+     * @param {string} [targetInstanceId] - ID of the specific target element instance this connects
+     */
+    constructor(relationshipId, waypoints = null, sourceInstanceId = null, targetInstanceId = null) {
+        if (!relationshipId) {
+            throw new Error('RelationshipInstance requires relationshipId');
+        }
+        this.relationshipId = relationshipId;
+        this.waypoints = waypoints ? waypoints.map(wp => ({ x: wp.x, y: wp.y })) : null;
+        /** Pinned attachment side at each end ('top'|'right'|'bottom'|'left'); null = automatic. */
+        this.sourceSide = null;
+        this.targetSide = null;
+        /** Line style set on this view (routing, attach, strokeColor, strokeWidth); empty = inherited. */
+        this.appearance = {};
+        /** What an Archi file said about this line that the model does not use; null when not imported. */
+        this.archi = null;
+        this.visible = true;
+        this.sourceInstanceId = sourceInstanceId;
+        this.targetInstanceId = targetInstanceId;
+
+        // Generate stable instance ID
+        this.id = RelationshipInstance.generateId(relationshipId, sourceInstanceId, targetInstanceId);
+    }
+
+    /**
+     * Generate a stable, deterministic instance ID.
+     * Includes source and target instance IDs to uniquely identify each relationship instance pairing.
+     * @param {string} relationshipId
+     * @param {string} [sourceInstanceId]
+     * @param {string} [targetInstanceId]
+     * @returns {string}
+     */
+    static generateId(relationshipId, sourceInstanceId = null, targetInstanceId = null) {
+        if (sourceInstanceId && targetInstanceId) {
+            return `${relationshipId}_${sourceInstanceId}_${targetInstanceId}`;
+        }
+        return `rel_${relationshipId}`;
+    }
+
+    /**
+     * Resolve this instance to the actual model relationship.
+     * @param {ArchimateModel} model
+     * @returns {ArchimateRelationship}
+     */
+    getModelRelationship(model) {
+        return model.getRelationship(this.relationshipId);
+    }
+
+    /**
+     * Serialize to plain object (for JSON, storage, export).
+     * @returns {Object}
+     */
+    toJSON() {
+        return {
+            relationshipId: this.relationshipId,
+            waypoints: this.waypoints ?? undefined,
+            sourceSide: this.sourceSide ?? undefined,
+            targetSide: this.targetSide ?? undefined,
+            appearance: Object.keys(this.appearance).length ? { ...this.appearance } : undefined,
+            visible: this.visible,
+            sourceInstanceId: this.sourceInstanceId,
+            targetInstanceId: this.targetInstanceId,
+            archi: this.archi ? JSON.parse(JSON.stringify(this.archi)) : undefined,
+        };
+    }
+
+    /**
+     * Create an instance from plain object.
+     * @param {Object} data
+     * @returns {RelationshipInstance}
+     */
+    static fromJSON(data) {
+        const inst = new RelationshipInstance(data.relationshipId, data.waypoints, data.sourceInstanceId, data.targetInstanceId);
+        inst.sourceSide = data.sourceSide ?? null;
+        inst.targetSide = data.targetSide ?? null;
+        inst.appearance = { ...(data.appearance ?? {}) };
+        inst.visible = data.visible !== false;
+        inst.archi = data.archi ? JSON.parse(JSON.stringify(data.archi)) : null;
+        return inst;
+    }
+}

package/src/charting/diagrams/RemoveGroupFromViewCommand.js

@@ -0,0 +1,28 @@
+import { Command } from '../CommandHistory.js';
+
+/**
+ * RemoveGroupFromViewCommand — take a group off a view: its layout entry
+ * goes, and what was drawn in it stays where it is (on the view, or in the
+ * group around it). The model folder stays. Undo puts the same entry back.
+ */
+export class RemoveGroupFromViewCommand extends Command {
+    /**
+     * @param {ArchimateView} view
+     * @param {string} folderId - The folder the group draws
+     */
+    constructor(view, folderId) {
+        super('Remove group from view');
+        this.view = view;
+        this.folderId = folderId;
+        this._entry = null;
+    }
+
+    execute() {
+        this._entry = this.view.folderLayout[this.folderId] ?? null;
+        delete this.view.folderLayout[this.folderId];
+    }
+
+    undo() {
+        if (this._entry) this.view.folderLayout[this.folderId] = this._entry;
+    }
+}

package/src/charting/diagrams/RemoveLineCommand.js

@@ -0,0 +1,27 @@
+import { Command } from '../CommandHistory.js';
+
+/**
+ * RemoveLineCommand — take a plain line (ViewConnectionInstance: no
+ * relationship behind it) off a view, as one undo step.
+ */
+export class RemoveLineCommand extends Command {
+    /**
+     * @param {ArchimateView} view
+     * @param {string} lineId
+     */
+    constructor(view, lineId) {
+        super('Delete line');
+        this.view = view;
+        this.lineId = lineId;
+        this.line = null;
+    }
+
+    execute() {
+        this.line = this.view.viewConnections.get(this.lineId) ?? null;
+        this.view.viewConnections.delete(this.lineId);
+    }
+
+    undo() {
+        if (this.line) this.view.viewConnections.set(this.lineId, this.line);
+    }
+}

package/src/charting/diagrams/ShowElementCommand.js

@@ -0,0 +1,43 @@
+import { Command } from '../CommandHistory.js';
+import { AddToViewCommand } from './ArchimateCommands.js';
+
+/**
+ * ShowElementCommand — put an existing model element on a view (dropped from
+ * the model tree), with its relationships to the elements already there, as
+ * one undo step: what Archi does by default when an element is added to a
+ * view. Only lines to or from the new box are added; a line the view leaves
+ * out between boxes already there stays out. Redo adds the same lines again,
+ * so later steps that refer to them still find them.
+ */
+export class ShowElementCommand extends Command {
+    /**
+     * @param {ArchimateView} view
+     * @param {ElementInstance} instance - The new box, for an element the model has
+     * @param {Object} [options]
+     * @param {boolean} [options.withRelationships=true]
+     */
+    constructor(view, instance, { withRelationships = true, label = 'Show in View' } = {}) {
+        super(label);
+        this.view = view;
+        this.instance = instance;
+        this.withRelationships = withRelationships;
+        this._add = new AddToViewCommand(view, instance);
+        /** The relationship lines added with it, found on first execute. */
+        this.lines = null;
+    }
+
+    execute() {
+        const { view, instance } = this;
+        this._add.execute();
+        this.lines ??= this.withRelationships
+            ? view.missingRelationshipInstances(instance.elementId)
+                .filter(line => line.sourceInstanceId === instance.id || line.targetInstanceId === instance.id)
+            : [];
+        for (const line of this.lines) view.addRelationshipInstance(line);
+    }
+
+    undo() {
+        for (const line of this.lines ?? []) this.view.removeRelationshipInstance(line.id);
+        this._add.undo();
+    }
+}

package/src/charting/diagrams/SvgCoordinate.js

@@ -0,0 +1,17 @@
+/**
+ * SvgCoordinate — screen-to-SVG coordinate conversion helpers.
+ *
+ * These used to live on RenderEngine; they are collected here so diagram
+ * classes can translate DOM mouse events into SVG user-space without going
+ * through the engine façade.
+ */
+export class SvgCoordinate {
+    /** Screen (clientX/clientY) → SVG user-space coordinates, honoring the
+     *  current pan/zoom viewBox. Shared by drag, add-node, and edge-creation
+     *  — all of which need a graph-space point, not a raw screen pixel. */
+    static clientToSvgPoint(svg, clientX, clientY) {
+        const CTM = svg?.getScreenCTM();
+        if (!CTM) return { x: 0, y: 0 };
+        return { x: (clientX - CTM.e) / CTM.a, y: (clientY - CTM.f) / CTM.d };
+    }
+}

package/src/charting/diagrams/SvgZoom.js

@@ -0,0 +1,127 @@
+import { ViewFit } from '../ViewFit.js';
+
+/**
+ * SvgZoom — pan/zoom controller for an SVG container.
+ *
+ * The wheel/mouse logic used to live inside RenderEngine._addZoomListeners;
+ * it is collected here so diagram classes can attach their own pan/zoom
+ * without going through the engine façade.
+ */
+export class SvgZoom {
+    constructor(container, svg, { clientToSvgPoint, hitTest, is3D } = {}) {
+        this.container = container;
+        this.svg = svg;
+        this.clientToSvgPoint = clientToSvgPoint;
+        this.hitTest = hitTest;
+        this.is3D = is3D;
+        this._initialViewBox = null;
+        this._isPanning = false;
+        this._panMoved = false;
+        this._lastMousePos = { x: 0, y: 0 };
+
+        this._onWheel = this._onWheel.bind(this);
+        this._onMouseDown = this._onMouseDown.bind(this);
+        this._onMouseMove = this._onMouseMove.bind(this);
+        this._onMouseUp = this._onMouseUp.bind(this);
+
+        container.addEventListener('wheel', this._onWheel, { passive: false });
+        container.addEventListener('mousedown', this._onMouseDown);
+        container.addEventListener('mousemove', this._onMouseMove);
+        container.addEventListener('mouseup', this._onMouseUp);
+        container.addEventListener('mouseleave', this._onMouseUp);
+        // A right-drag that panned is not a right-click: no menu.
+        this._onContextMenu = (e) => {
+            if (!this._panMoved) return;
+            this._panMoved = false;
+            e.preventDefault();
+            e.stopPropagation();
+        };
+        container.addEventListener('contextmenu', this._onContextMenu, true);
+
+        this._captureInitialViewBox();
+    }
+
+    _captureInitialViewBox() {
+        const viewBox = this.svg?.viewBox?.baseVal;
+        if (!viewBox) return;
+        this._initialViewBox = { x: viewBox.x, y: viewBox.y, width: viewBox.width, height: viewBox.height };
+    }
+
+    get initialViewBox() {
+        return this._initialViewBox;
+    }
+
+    /** Zoom and pan so `bounds` (SVG coordinates) fills the view (ViewFit.viewBox). */
+    fit(bounds, { margin = 20 } = {}) {
+        if (!this.svg || !bounds) return;
+        const rect = this.svg.getBoundingClientRect?.() ?? { width: 0, height: 0 };
+        const box = ViewFit.viewBox(bounds, rect, margin);
+        const viewBox = this.svg.viewBox.baseVal;
+        viewBox.x = box.x;
+        viewBox.y = box.y;
+        viewBox.width = box.width;
+        viewBox.height = box.height;
+    }
+
+    reset() {
+        if (!this._initialViewBox || !this.svg) return;
+        const viewBox = this.svg.viewBox.baseVal;
+        viewBox.x = this._initialViewBox.x;
+        viewBox.y = this._initialViewBox.y;
+        viewBox.width = this._initialViewBox.width;
+        viewBox.height = this._initialViewBox.height;
+    }
+
+    _onWheel(event) {
+        if (this.is3D?.()) return;
+        event.preventDefault();
+
+        const scaleFactor = event.deltaY > 0 ? 1.1 : 1 / 1.1;
+        const pointer = this.clientToSvgPoint(event.clientX, event.clientY);
+        const viewBox = this.svg.viewBox.baseVal;
+
+        viewBox.x = pointer.x - (pointer.x - viewBox.x) * scaleFactor;
+        viewBox.y = pointer.y - (pointer.y - viewBox.y) * scaleFactor;
+        viewBox.width *= scaleFactor;
+        viewBox.height *= scaleFactor;
+    }
+
+    /**
+     * Pan with the right button (a right-click that does not move still opens
+     * the menu), the middle one, or Alt+left. A plain left drag on empty space
+     * is the editor's: a selection box.
+     */
+    _onMouseDown(event) {
+        if (this.is3D?.()) return;
+        if (event.button === 2 || event.button === 1 || (event.button === 0 && event.altKey)) {
+            this._isPanning = true;
+            this._panMoved = false;
+            this._downPos = { x: event.clientX, y: event.clientY };
+            this._lastMousePos = { x: event.clientX, y: event.clientY };
+            if (event.button !== 2) event.preventDefault();
+        }
+    }
+
+    _onMouseMove(event) {
+        if (!this._isPanning) return;
+        if (!this._panMoved) {
+            if (Math.hypot(event.clientX - this._downPos.x, event.clientY - this._downPos.y) < 4) return;
+            this._panMoved = true;
+            this.svg.style.cursor = 'grabbing';
+        }
+        const dx = event.clientX - this._lastMousePos.x;
+        const dy = event.clientY - this._lastMousePos.y;
+        this._lastMousePos = { x: event.clientX, y: event.clientY };
+
+        const CTM = this.svg.getScreenCTM();
+        const viewBox = this.svg.viewBox.baseVal;
+        viewBox.x -= dx / CTM.a;
+        viewBox.y -= dy / CTM.d;
+    }
+
+    _onMouseUp() {
+        if (!this._isPanning) return;
+        this._isPanning = false;
+        this.svg.style.cursor = 'default';
+    }
+}