@peter.prib/renderengine 0.0.0-stage → 0.2.0

package/src/charting/diagrams/GraphDiagram3D.js

@@ -0,0 +1,152 @@
+import { Diagram3D } from '../Diagram3D.js';
+import { OrbitCamera } from '../../OrbitCamera.js';
+import { GraphMetrics } from './GraphMetrics.js';
+import { LabelHelper } from './LabelHelper.js';
+
+/**
+ * GraphDiagram3D — interactive 3D node/edge graph viewed through the orbit camera.
+ */
+export class GraphDiagram3D extends Diagram3D {
+    static diagramType = 'graph3d';
+
+    constructor(renderer, nodes, edges, options = {}, camera = null, engine = null) {
+        super(renderer, { nodes, edges }, options);
+        this.camera = camera;
+        this.engine = engine;
+        this._graph3DPos = null;
+    }
+
+    render() {
+        if (!this.renderer || !this.renderer.supportsSceneGraph) {
+            console.warn('3D graph diagram is only supported in SVG renderer.');
+            return;
+        }
+        super.render();
+    }
+
+    _render() {
+        const { nodes, edges } = this.data;
+        const options = this.options;
+        const renderer = this.renderer;
+
+        if (!renderer || !renderer.supportsSceneGraph) {
+            console.warn('3D graph diagram is only supported in SVG renderer.');
+            return;
+        }
+
+        const {
+            onNodeClick, nodeRadius = 8,
+            colors = ['#5470c6', '#91cc75', '#fac858', '#ee6666', '#73c0de', '#3ba272', '#fc8452'],
+            edgeColor: defaultEdgeColor = '#bdc3c7',
+            initialTheta = -0.6, initialPhi = 0.35, initialDistance = 2.2,
+            sizeBy, minRadius = nodeRadius, maxRadius = nodeRadius * 2.5, sizeScale = 'linear',
+            minEdgeWidth = 1.2, maxEdgeWidth = minEdgeWidth * 4, edgeWidthScale = 'linear',
+        } = options;
+
+        const degreeMap = sizeBy === 'degree' ? GraphMetrics.computeNodeDegrees(nodes, edges) : null;
+        const sizeDomain = GraphMetrics.computeSizeDomain(nodes, { sizeBy, degreeMap });
+        const sizeOptions = { minRadius, maxRadius, sizeScale, sizeBy, degreeMap };
+        const edgeWidthDomain = GraphMetrics.computeEdgeWidthDomain(edges);
+        const edgeWidthOptions = { minEdgeWidth, maxEdgeWidth, widthScale: edgeWidthScale };
+
+        this.seedCamera({ theta: initialTheta, phi: initialPhi, distance: initialDistance });
+
+        // Layout: simulate once per distinct node set, not on every camera-only redraw.
+        if (!this._graph3DPos || !nodes.every(n => this._graph3DPos.has(n.id))) {
+            this._graph3DPos = GraphDiagram3D.layoutForce3D(nodes, edges);
+        }
+        const pos = this._graph3DPos;
+
+        const W = renderer.width, H = renderer.height;
+        const cx = W / 2, cy = H / 2;
+        const pixelRadius = Math.min(W, H) / 2 - 20;
+        const camera = new OrbitCamera(this.camera);
+        const toScreen = (p) => {
+            const proj = camera.project(p, 1);
+            return { x: cx + proj.sx * pixelRadius, y: cy - proj.sy * pixelRadius, depth: proj.depth, scale: proj.scale };
+        };
+
+        const groups = new Map();
+        nodes.forEach(n => { if (n.group && !groups.has(n.group)) groups.set(n.group, colors[groups.size % colors.length]); });
+
+        const nodeItems = nodes.map(n => {
+            const p = pos.get(n.id);
+            const screen = toScreen(p);
+            const color = n.color || (n.group ? groups.get(n.group) : (options.nodeColor || '#4f8ef7'));
+            return { kind: 'node', node: n, screen, color, depth: screen.depth };
+        });
+        const edgeItems = edges.map(e => {
+            const a = pos.get(e.source), b = pos.get(e.target);
+            if (!a || !b) return null;
+            const sa = toScreen(a), sb = toScreen(b);
+            return { kind: 'edge', edge: e, sa, sb, depth: (sa.depth + sb.depth) / 2 };
+        }).filter(Boolean);
+
+        const scene = [...edgeItems, ...nodeItems].sort((a, b) => b.depth - a.depth);
+        const nodeEls = [];
+        for (const item of scene) {
+            if (item.kind === 'edge') {
+                const edgeWidth = GraphMetrics.effectiveEdgeWidth(item.edge, 1.2, edgeWidthDomain, edgeWidthOptions);
+                renderer.path(`M${item.sa.x},${item.sa.y} L${item.sb.x},${item.sb.y}`, 'none',
+                    { color: item.edge.color || defaultEdgeColor, width: edgeWidth });
+            } else {
+                const { node, screen, color } = item;
+                const baseR = GraphMetrics.effectiveNodeRadius(node, nodeRadius, sizeDomain, sizeOptions);
+                const r = Math.max(2, baseR * screen.scale);
+                const label3D = LabelHelper.resolveNodeLabel(node) || node.id;
+                const g = renderer.group({ transform: `translate(${screen.x},${screen.y})`, nodeId: node.id, tooltip: label3D });
+                g.appendChild(renderer.circle(0, 0, r, color, { color: '#fff', width: 1.5 }));
+                g.appendChild(renderer.text(label3D, 0, r + 9, { fill: '#333', textAnchor: 'middle', fontSize: '9px', 'pointer-events': 'none' }));
+                if (onNodeClick) g.addEventListener('click', () => onNodeClick(node));
+                nodeEls.push(g);
+            }
+        }
+        this._graph3D = { nodes, edges, pos, nodeEls };
+    }
+
+    static layoutForce3D(nodes, edges, { iterations = 150 } = {}) {
+        const fixed = new Set(nodes.filter(n => n.x != null || n.y != null || n.z != null).map(n => n.id));
+        const pos = new Map(nodes.map(n => [n.id, {
+            x: n.x ?? (Math.random() * 2 - 1),
+            y: n.y ?? (Math.random() * 2 - 1),
+            z: n.z ?? (Math.random() * 2 - 1),
+            vx: 0, vy: 0, vz: 0,
+        }]));
+        const K = 1 / Math.cbrt(Math.max(nodes.length, 1));
+        let temp = 0.2;
+        for (let iter = 0; iter < iterations; iter++) {
+            nodes.forEach(n => { if (!fixed.has(n.id)) { const p = pos.get(n.id); p.vx = 0; p.vy = 0; p.vz = 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, dz = b.z - a.z;
+                    const dist = Math.sqrt(dx * dx + dy * dy + dz * dz) || 0.01;
+                    const f = (K * K) / dist;
+                    const ux = dx / dist, uy = dy / dist, uz = dz / dist;
+                    a.vx -= ux * f; a.vy -= uy * f; a.vz -= uz * f;
+                    b.vx += ux * f; b.vy += uy * f; b.vz += uz * f;
+                }
+            }
+            edges.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, dz = b.z - a.z;
+                const dist = Math.sqrt(dx * dx + dy * dy + dz * dz) || 0.01;
+                const f = (dist * dist) / (K * 1.5);
+                const ux = dx / dist, uy = dy / dist, uz = dz / dist;
+                a.vx += ux * f; a.vy += uy * f; a.vz += uz * f;
+                b.vx -= ux * f; b.vy -= uy * f; b.vz -= uz * f;
+            });
+            nodes.forEach(n => {
+                if (fixed.has(n.id)) return;
+                const p = pos.get(n.id);
+                p.vx += -p.x * 0.02; p.vy += -p.y * 0.02; p.vz += -p.z * 0.02; // pull toward origin — no pixel container to center within, in 3D
+                const mag = Math.sqrt(p.vx * p.vx + p.vy * p.vy + p.vz * p.vz) || 1;
+                const dt = Math.min(mag, temp) / mag;
+                p.x += p.vx * dt; p.y += p.vy * dt; p.z += p.vz * dt;
+            });
+            temp *= 0.97;
+        }
+        return pos;
+    }
+}

package/src/charting/diagrams/GraphMetrics.js

@@ -0,0 +1,81 @@
+/**
+ * GraphMetrics — pure, stateless helpers for graph-diagram sizing and scaling.
+ *
+ * These functions used to live on RenderEngine; they are collected here so
+ * GraphDiagram, GraphDiagram3D, and any future diagram can use them without
+ * going through the engine façade.
+ */
+export class GraphMetrics {
+    /** Pure — no DOM/renderer access. Map<nodeId, connectionCount> — how many
+     *  edge ENDPOINTS touch each node (a self-loop, where source===target,
+     *  counts twice — it really does attach to that node twice). Nodes with
+     *  no edges at all still get an entry (0), so a domain computed over this
+     *  always includes them rather than treating "no data" as "not sized". */
+    static computeNodeDegrees(nodes, edges) {
+        const degrees = new Map(nodes.map(n => [n.id, 0]));
+        for (const e of edges) {
+            if (degrees.has(e.source)) degrees.set(e.source, degrees.get(e.source) + 1);
+            if (degrees.has(e.target)) degrees.set(e.target, degrees.get(e.target) + 1);
+        }
+        return degrees;
+    }
+
+    /** Pure. What a node's own size VALUE is, before it's mapped to a radius —
+     *  `node.size` (the default), or that node's connection count when
+     *  `sizeBy: 'degree'` is in play (`degreeMap` from computeNodeDegrees). */
+    static nodeSizeValue(node, sizeBy, degreeMap) {
+        return sizeBy === 'degree' ? (degreeMap?.get(node?.id) ?? 0) : node?.size;
+    }
+
+    /** Pure — no DOM/renderer access. {min,max} of every node's size VALUE
+     *  (see nodeSizeValue) across all nodes, or null if none carry a finite
+     *  one (keeps effectiveNodeRadius's fixed-R behavior when the feature
+     *  isn't in use at all). `{sizeBy, degreeMap}` switches the value source
+     *  from `node.size` to connection count — same {min,max} shape either way. */
+    static computeSizeDomain(nodes, { sizeBy, degreeMap } = {}) {
+        const values = nodes.map(n => GraphMetrics.nodeSizeValue(n, sizeBy, degreeMap)).filter(Number.isFinite);
+        if (!values.length) return null;
+        return { min: Math.min(...values), max: Math.max(...values) };
+    }
+
+    /** Pure. Maps a node's size value (see nodeSizeValue) into
+     *  [minRadius,maxRadius] given a precomputed domain; falls back to R
+     *  unchanged when this node isn't part of the sizing (no domain, or its
+     *  value not finite). `node.radius` — set by dragging that node's own
+     *  resize handle — is a hard per-node override and wins over all of that
+     *  (sizeBy/domain/plain R alike), the same way an explicit `node.x`/
+     *  `node.y` already overrides computed layout. */
+    static effectiveNodeRadius(node, R, sizeDomain, sizeOptions = {}) {
+        if (Number.isFinite(node?.radius)) return node.radius;
+        const { minRadius = R, maxRadius = R * 2.5, sizeScale = 'linear', sizeBy, degreeMap } = sizeOptions;
+        const value = GraphMetrics.nodeSizeValue(node, sizeBy, degreeMap);
+        if (!sizeDomain || !Number.isFinite(value)) return R;
+        const { min, max } = sizeDomain;
+        if (max === min) return maxRadius;
+        let t = (value - min) / (max - min);
+        if (sizeScale === 'sqrt') t = Math.sqrt(t);
+        return minRadius + t * (maxRadius - minRadius);
+    }
+
+    /** Pure. {min,max} of edge.weight across all edges, or null if none carry
+     *  a finite one — the edge-thickness counterpart of computeSizeDomain. */
+    static computeEdgeWidthDomain(edges) {
+        const values = edges.map(e => e.weight).filter(Number.isFinite);
+        if (!values.length) return null;
+        return { min: Math.min(...values), max: Math.max(...values) };
+    }
+
+    /** Pure. Maps edge.weight into [minEdgeWidth,maxEdgeWidth] given a
+     *  precomputed domain; falls back to `defaultWidth` when this edge isn't
+     *  part of the sizing (no domain, or edge.weight not finite) — the
+     *  edge-thickness counterpart of effectiveNodeRadius. */
+    static effectiveEdgeWidth(edge, defaultWidth, widthDomain, widthOptions = {}) {
+        if (!widthDomain || !Number.isFinite(edge?.weight)) return defaultWidth;
+        const { minEdgeWidth = defaultWidth, maxEdgeWidth = defaultWidth * 4, widthScale = 'linear' } = widthOptions;
+        const { min, max } = widthDomain;
+        if (max === min) return maxEdgeWidth;
+        let t = (edge.weight - min) / (max - min);
+        if (widthScale === 'sqrt') t = Math.sqrt(t);
+        return minEdgeWidth + t * (maxEdgeWidth - minEdgeWidth);
+    }
+}

package/src/charting/diagrams/GridOverlay.js

@@ -0,0 +1,137 @@
+/**
+ * GridOverlay — renders a dynamically scaled grid that responds to pan/zoom.
+ * Creates a separate SVG layer that redraw whenever the viewBox changes.
+ */
+export class GridOverlay {
+    constructor(svgContainer, { gridSize = 20, color = '#e5e5e5', width = 0.5 } = {}) {
+        this.svgContainer = svgContainer;
+        this.gridSize = gridSize;
+        this.color = color;
+        this.width = width;
+
+        // Create overlay SVG
+        this.overlayElement = this._createOverlay();
+        // Prepend so it renders behind other SVGs
+        this.svgContainer.insertBefore(this.overlayElement, this.svgContainer.firstChild);
+
+        // Find the main SVG and listen for viewBox changes
+        this.mainSvg = null;
+        this._observeViewBoxChanges();
+    }
+
+    /**
+     * Create the grid overlay SVG element.
+     */
+    _createOverlay() {
+        const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+        svg.setAttribute('class', 'grid-overlay');
+        svg.style.cssText = `
+            position: absolute;
+            top: 0;
+            left: 0;
+            width: 100%;
+            height: 100%;
+            pointer-events: none;
+            z-index: 0;
+        `;
+        return svg;
+    }
+
+    /**
+     * Find main SVG and observe its viewBox changes.
+     */
+    _observeViewBoxChanges() {
+        // Find the main SVG element
+        const svgs = this.svgContainer.querySelectorAll('svg');
+        for (const svg of svgs) {
+            if (svg !== this.overlayElement && svg.viewBox?.baseVal) {
+                this.mainSvg = svg;
+                break;
+            }
+        }
+
+        if (!this.mainSvg) return;
+
+        // The overlay is positioned (absolute, z-index 0), and CSS paints positioned boxes over
+        // unpositioned ones whatever their order: lift the drawing above it, so the grid stays behind.
+        GridOverlay.stackAbove(this.mainSvg);
+
+        // Watch for viewBox attribute changes
+        const observer = new MutationObserver(() => {
+            this._updateGrid();
+        });
+
+        observer.observe(this.mainSvg, { attributes: true, attributeFilter: ['viewBox'] });
+
+        // Initial draw
+        this._updateGrid();
+    }
+
+    /**
+     * Update grid based on current viewBox.
+     */
+    _updateGrid() {
+        if (!this.mainSvg) return;
+
+        const viewBox = this.mainSvg.viewBox.baseVal;
+        const W = viewBox.width;
+        const H = viewBox.height;
+        const x0 = viewBox.x;
+        const y0 = viewBox.y;
+
+        // Clear existing grid
+        this.overlayElement.innerHTML = '';
+
+        // Sync overlay viewBox with main SVG
+        this.overlayElement.setAttribute('viewBox', `${x0} ${y0} ${W} ${H}`);
+
+        // Generate grid path aligned to grid
+        const lines = [];
+        const { gridSize } = this;
+
+        // Vertical lines
+        const firstX = Math.floor(x0 / gridSize) * gridSize;
+        for (let x = firstX; x < x0 + W; x += gridSize) {
+            lines.push(`M${x},${y0} L${x},${y0 + H}`);
+        }
+
+        // Horizontal lines
+        const firstY = Math.floor(y0 / gridSize) * gridSize;
+        for (let y = firstY; y < y0 + H; y += gridSize) {
+            lines.push(`M${x0},${y} L${x0 + W},${y}`);
+        }
+
+        // Create path element
+        if (lines.length > 0) {
+            const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+            path.setAttribute('d', lines.join(' '));
+            path.setAttribute('stroke', this.color);
+            path.setAttribute('stroke-width', this.width);
+            path.setAttribute('fill', 'none');
+            this.overlayElement.appendChild(path);
+        }
+    }
+
+    /** Make `drawing` paint above the overlay (z-index 0): positioned, one level up. A drawing already given a stacking order keeps it. */
+    static stackAbove(drawing) {
+        if (!drawing.style.position || drawing.style.position === 'static') drawing.style.position = 'relative';
+        if (!drawing.style.zIndex) drawing.style.zIndex = '1';
+    }
+
+    /**
+     * Update grid size and redraw.
+     */
+    setGridSize(gridSize) {
+        this.gridSize = gridSize;
+        this._updateGrid();
+    }
+
+    /**
+     * Remove the grid overlay.
+     */
+    destroy() {
+        if (this.overlayElement && this.overlayElement.parentNode) {
+            this.overlayElement.parentNode.removeChild(this.overlayElement);
+        }
+    }
+}

package/src/charting/diagrams/ImportRowsCommand.js

@@ -0,0 +1,62 @@
+import { Command } from '../CommandHistory.js';
+import { ElementInstance } from './ElementInstance.js';
+
+/**
+ * ImportRowsCommand — a planned import (csvMapping.js's planCsvImport) carried
+ * out as one undo step: the new elements and relationships added, the
+ * elements it updates given their new documentation and properties, and,
+ * with `view`, a box for each new element on it in a grid from `at`.
+ * Undo takes it all back.
+ */
+export class ImportRowsCommand extends Command {
+    /**
+     * @param {ArchimateModel} model
+     * @param {{creates, updates, relationships}} plan
+     * @param {{view?: ArchimateView, at?: {x, y}, columns?: number}} [options]
+     */
+    constructor(model, plan, { view = null, at = { x: 60, y: 60 }, columns = 6 } = {}) {
+        super(`Import ${plan.creates.length} new, ${plan.updates.length} updated`);
+        this.model = model;
+        this.plan = plan;
+        this.view = view;
+        this.at = at;
+        this.columns = columns;
+        this._before = null;
+        this._instances = [];
+    }
+
+    execute() {
+        const { model, plan, view } = this;
+        this._before = {
+            updates: plan.updates.map(({ element }) => [element, { documentation: element.documentation, properties: element.properties }]),
+            elementIds: Array.isArray(view?.elementIds) ? [...view.elementIds] : null,
+        };
+        for (const element of plan.creates) model.addElement(structured(element));
+        for (const { element, changes } of plan.updates) Object.assign(element, structured(changes));
+        for (const rel of plan.relationships) if (!model.getRelationship(rel.id)) model.addRelationship({ ...rel });
+        if (view) {
+            this._instances = plan.creates.map((e, i) => {
+                const inst = new ElementInstance(e.id, this.at.x + (i % this.columns) * 160 + 60, this.at.y + Math.floor(i / this.columns) * 90 + 28);
+                view.addElementInstance(inst);
+                return inst;
+            });
+            if (Array.isArray(view.elementIds)) view.elementIds = [...new Set([...view.elementIds, ...plan.creates.map(e => e.id)])];
+        }
+    }
+
+    undo() {
+        const { model, plan, view } = this;
+        for (const inst of this._instances) view.removeElementInstance(inst.id);
+        this._instances = [];
+        if (view && this._before.elementIds) view.elementIds = this._before.elementIds;
+        for (const rel of plan.relationships) model.removeRelationship(rel.id);
+        for (const [element, before] of this._before.updates) {
+            for (const k of ['documentation', 'properties']) {
+                if (before[k] === undefined) delete element[k]; else element[k] = before[k];
+            }
+        }
+        for (const element of plan.creates) model.removeElement(element.id);
+    }
+}
+
+const structured = (v) => JSON.parse(JSON.stringify(v));

package/src/charting/diagrams/LabelHelper.js

@@ -0,0 +1,108 @@
+/**
+ * LabelHelper — pure, stateless helpers for resolving node labels, word-
+ * wrapping them, and surfacing caller-supplied "extra data" lines.
+ *
+ * These used to live on RenderEngine; they are collected here so diagram
+ * classes and property dialogs can use them without going through the engine
+ * façade.
+ */
+export class LabelHelper {
+    /** Pure. The text that actually renders for a node's label — resolved
+     *  BEFORE wrapping. `node.label`:
+     *  - a function `(node) => string` — called directly.
+     *  - a string with `${field}` (Archi-style) or `{field}` placeholders — each
+     *    is replaced with that field's own value straight off the node.
+     *  - falsy/unset — falls back to `node.name`, then `''`.
+     *  Table nodes' header text and graphDiagram3D's node caption both read
+     *  this too, not just the 2D `shape:'rect'` box. */
+    static resolveNodeLabel(node) {
+        if (typeof node?.label === 'function') return String(node.label(node) ?? '');
+        const raw = node?.label || node?.name || '';
+        if (typeof raw !== 'string') return String(raw);
+        if (!raw.includes('{') && !raw.includes('$')) return raw;
+        let result = raw;
+        result = result.replace(/\$\{(\w+)\}/g, (_match, field) => {
+            const value = node[field];
+            return value == null ? '' : String(value);
+        });
+        result = result.replace(/\{(\w+)\}/g, (_match, field) => {
+            const value = node[field];
+            return value == null ? '' : String(value);
+        });
+        return result;
+    }
+
+    /** Pure. Word-wraps `text` to fit within `maxWidth` px at `fontSize` px,
+     *  returning as many `lineHeight`-px lines as fit within `maxHeight` — a
+     *  single word wider than `maxWidth` is hard-broken rather than left
+     *  overflowing. The last line gets an ellipsis appended if more text existed
+     *  than fit. Widths come from `measure(text)` (px) when given, e.g. the
+     *  renderer's measureText; otherwise from an average character width. */
+    static wrapLabelLines(text, maxWidth, fontSize, maxHeight, lineHeight, measure = null) {
+        const AVG_CHAR_WIDTH_RATIO = 0.55; // rough sans-serif average
+        const width = measure ?? ((s) => s.length * fontSize * AVG_CHAR_WIDTH_RATIO);
+        const fits = (s) => width(s) <= maxWidth;
+        /** The longest prefix of a word that fits (at least one character). */
+        const fittingPrefix = (word) => {
+            let n = 1;
+            while (n < word.length && fits(word.slice(0, n + 1))) n++;
+            return n;
+        };
+        const maxLines = Math.max(1, Math.floor(maxHeight / lineHeight));
+        const words = String(text ?? '').split(/\s+/).filter(Boolean);
+
+        const lines = [];
+        let current = '';
+        let truncated = false;
+        for (let i = 0; i < words.length; i++) {
+            if (lines.length >= maxLines) { truncated = true; break; }
+            const word = words[i];
+            const candidate = current ? `${current} ${word}` : word;
+            if (fits(candidate)) {
+                current = candidate;
+                continue;
+            }
+            if (current) lines.push(current);
+            if (lines.length >= maxLines) { truncated = true; current = ''; break; }
+            if (!fits(word)) {
+                let rest = word;
+                while (!fits(rest) && lines.length < maxLines) {
+                    const n = fittingPrefix(rest);
+                    lines.push(rest.slice(0, n));
+                    rest = rest.slice(n);
+                }
+                current = lines.length >= maxLines ? '' : rest;
+                if (lines.length >= maxLines && rest) truncated = true;
+            } else {
+                current = word;
+            }
+        }
+        if (current) {
+            if (lines.length < maxLines) lines.push(current);
+            else truncated = true;
+        }
+        if (!truncated && lines.length === 0 && String(text ?? '').trim() === '') return [];
+
+        if (truncated && lines.length) {
+            const last = lines[lines.length - 1];
+            lines[lines.length - 1] = last.length > 1 ? `${last.slice(0, -1)}…` : `${last}…`;
+        }
+        return lines;
+    }
+
+    /** Pure. "key: value" lines for any of an object's own fields not in
+     *  knownKeys and not undefined — surfaces caller-supplied extra data
+     *  (e.g. `{owner:'Alice', headcount:12}`) in the hover tooltip without
+     *  the caller having to build a bespoke tooltip string themselves. */
+    /** Whether a value is data a person reads and edits as text: a string, number or boolean, or a list of them (not an object). */
+    static isDataValue(value) {
+        const plain = (v) => ['string', 'number', 'boolean'].includes(typeof v);
+        return plain(value) || (Array.isArray(value) && value.every(plain));
+    }
+
+    static nodeExtraDataLines(node, knownKeys) {
+        return Object.entries(node)
+            .filter(([k, v]) => !knownKeys.has(k) && LabelHelper.isDataValue(v))
+            .map(([k, v]) => `${k}: ${Array.isArray(v) ? v.join(', ') : v}`);
+    }
+}

package/src/charting/diagrams/MergeElementsCommand.js

@@ -0,0 +1,101 @@
+import { Command } from '../CommandHistory.js';
+import { structuredCopy } from './ElementInstance.js';
+
+/**
+ * MergeElementsCommand — elements that are one thing twice made into one
+ * (Archi's merge): the one kept takes the others' relationships, their boxes
+ * on every view, the documentation it lacks and the properties it lacks; the
+ * others go. A relationship left joining the kept element to itself, or the
+ * same as another (kind and ends), goes too, its lines drawn as the other.
+ * Undo puts everything back as it was.
+ */
+export class MergeElementsCommand extends Command {
+    /**
+     * @param {ArchimateModel} model
+     * @param {string} keepId - The element kept
+     * @param {Array<string>} otherIds - The elements merged into it
+     */
+    constructor(model, keepId, otherIds, label = `Merge ${otherIds.length + 1} elements into "${model.getElement(keepId)?.name || keepId}"`) {
+        super(label);
+        this.model = model;
+        this.keepId = keepId;
+        this.otherIds = otherIds.filter(id => id !== keepId && model.getElement(id));
+        this._before = null;
+    }
+
+    execute() {
+        const { model, keepId } = this;
+        const keep = model.getElement(keepId);
+        if (!keep || !this.otherIds.length) return;
+        this._before = this._snapshot();
+        const merged = new Set(this.otherIds);
+        const into = (id) => (merged.has(id) ? keepId : id);
+        for (const other of this.otherIds.map(id => model.getElement(id))) {
+            if (other.documentation && !(keep.documentation ?? '').includes(other.documentation)) {
+                keep.documentation = keep.documentation ? `${keep.documentation}\n\n${other.documentation}` : other.documentation;
+            }
+            const own = new Set((keep.properties ?? []).map(p => p.name ?? p.key));
+            const added = (other.properties ?? []).filter(p => !own.has(p.name ?? p.key));
+            if (added.length) keep.properties = [...(keep.properties ?? []), ...added.map(p => ({ ...p }))];
+            if (!keep.specialization && other.specialization) keep.specialization = other.specialization;
+        }
+        // Relationships end at the kept element; one left joining it to itself, or doubling another, goes.
+        const seen = new Map();
+        const replaced = new Map();   // removed relationship id -> the one its lines now draw
+        for (const rel of model.relationships()) {
+            const touched = merged.has(rel.source) || merged.has(rel.target);
+            rel.source = into(rel.source);
+            rel.target = into(rel.target);
+            if (touched && rel.source === keepId && rel.target === keepId) { replaced.set(rel.id, null); continue; }
+            const key = `${rel.kind} ${rel.source} ${rel.target} ${rel.name ?? ''}`;
+            if (touched && seen.has(key)) replaced.set(rel.id, seen.get(key));
+            else if (!seen.has(key)) seen.set(key, rel.id);
+        }
+        for (const id of replaced.keys()) model.removeRelationship(id);
+        for (const view of model.views()) {
+            if (Array.isArray(view.elementIds)) view.elementIds = [...new Set(view.elementIds.map(into))];
+            for (const inst of view.elementInstances?.values() ?? []) if (merged.has(inst.elementId)) inst.elementId = keepId;
+            for (const inst of [...(view.relationshipInstances?.values() ?? [])]) {
+                if (!replaced.has(inst.relationshipId)) continue;
+                const now = replaced.get(inst.relationshipId);
+                if (now) inst.relationshipId = now;
+                else view.relationshipInstances.delete(inst.id);
+            }
+        }
+        for (const id of this.otherIds) model.removeElement(id);
+    }
+
+    undo() {
+        if (!this._before) return;
+        const { model } = this;
+        const b = this._before;
+        model._elements = new Map(b.elements.map(([id, el]) => [id, el]));
+        const keep = model._elements.get(this.keepId);
+        Object.keys(keep).forEach(k => delete keep[k]);   // what the merge added too
+        Object.assign(keep, structuredCopy(b.keep));
+        model._elementFolder = new Map(b.folders);
+        model._relationships = new Map(b.relationships.map(([id, rel, ends]) => [id, Object.assign(rel, ends)]));
+        for (const v of b.views) {
+            v.view.elementIds = v.elementIds;
+            for (const [inst, elementId] of v.instances) inst.elementId = elementId;
+            v.view.relationshipInstances = new Map(v.lines.map(([inst, relationshipId]) => { inst.relationshipId = relationshipId; return [inst.id, inst]; }));
+        }
+    }
+
+    /** Everything the merge changes, to put back. @private */
+    _snapshot() {
+        const { model } = this;
+        return {
+            elements: [...model._elements],
+            keep: structuredCopy(model.getElement(this.keepId)),
+            folders: [...model._elementFolder],
+            relationships: [...model._relationships].map(([id, rel]) => [id, rel, { source: rel.source, target: rel.target }]),
+            views: model.views().map(view => ({
+                view,
+                elementIds: Array.isArray(view.elementIds) ? [...view.elementIds] : view.elementIds,
+                instances: [...(view.elementInstances?.values() ?? [])].map(inst => [inst, inst.elementId]),
+                lines: [...(view.relationshipInstances?.values() ?? [])].map(inst => [inst, inst.relationshipId]),
+            })),
+        };
+    }
+}

package/src/charting/diagrams/NestInstanceCommand.js

@@ -0,0 +1,34 @@
+import { Command } from '../CommandHistory.js';
+import { structuredCopy } from './ElementInstance.js';
+
+/**
+ * NestInstanceCommand — draw a box inside another on its view, or take it out
+ * (Archi's nesting): the instance's `archi.parent` becomes the parent's
+ * visual id, so it moves with the parent and an Archi file nests it there. A
+ * box nested under one drawn above it is raised just above its parent, so it
+ * stays in sight. Undo restores both.
+ */
+export class NestInstanceCommand extends Command {
+    /**
+     * @param {ElementInstance} instance - The box
+     * @param {ElementInstance|null} parent - The box it goes in; null takes it out
+     */
+    constructor(instance, parent, label = parent ? 'Nest' : 'Take out') {
+        super(label);
+        this.instance = instance;
+        this.parent = parent;
+        this._before = { archi: instance.archi ? structuredCopy(instance.archi) : null, zIndex: instance.zIndex };
+    }
+
+    execute() {
+        const { instance, parent } = this;
+        const { parent: _was, ...rest } = instance.archi ?? {};
+        instance.archi = parent ? { ...rest, parent: parent.visualId } : (Object.keys(rest).length ? rest : null);
+        if (parent && (instance.zIndex ?? 0) <= (parent.zIndex ?? 0)) instance.zIndex = (parent.zIndex ?? 0) + 1;
+    }
+
+    undo() {
+        this.instance.archi = this._before.archi ? structuredCopy(this._before.archi) : null;
+        this.instance.zIndex = this._before.zIndex;
+    }
+}