@peter.prib/renderengine 0.0.0-stage → 0.1.0

package/src/charting/diagramModel/ViewSetModel.js

@@ -0,0 +1,243 @@
+import { ViewSetChecker } from './ViewSetChecker.js';
+import { ModelReport } from './ModelReport.js';
+import { ModelSearch } from './ModelSearch.js';
+import { ModelHistory } from './ModelHistory.js';
+import { AddViewCommand } from './AddViewCommand.js';
+import { RemoveViewCommand } from './RemoveViewCommand.js';
+import { RenameViewCommand } from './RenameViewCommand.js';
+
+/**
+ * ViewSetModel — a model edited as several views (diagrams), with one current.
+ * Owns what every such model does with its views: create, duplicate, rename,
+ * delete, switch, and telling listeners after each change, so a UI only has to
+ * re-render on notification. It has one undo history (`history`, a
+ * ModelHistory, as Archi has one command stack per model) that every view of
+ * it shares: adding, renaming and deleting views are undoable steps on it too.
+ *
+ * Subclasses make their own kind of view through `_newView(id, title)`; a view
+ * has an `id`, a `title`, and `copy(id, title)` for duplication. DiagramModel
+ * (the template editor) and ArchimateModel extend it.
+ */
+export class ViewSetModel {
+    /**
+     * @param {Object} [options]
+     * @param {string} [options.idPrefix] - Prefix for generated view ids
+     * @param {string} [options.viewNoun] - What a view is called in default titles ('Diagram', 'View')
+     */
+    constructor({ idPrefix = 'view', viewNoun = 'View' } = {}) {
+        if (new.target === ViewSetModel) throw new TypeError('ViewSetModel is abstract — subclass it');
+        /** @type {Map<string, Object>} in tab order */
+        this._views = new Map();
+        this.currentViewId = null;
+        this.idPrefix = idPrefix;
+        this.viewNoun = viewNoun;
+        this._nextId = 1;
+        this._listeners = [];
+        /** Bumped by every change to the set of views (new, duplicated, renamed, deleted). */
+        this._structure = 0;
+        this._saved = null;
+        this._editListeners = [];
+        this._watched = new WeakSet();
+    }
+
+    /** The model's one undo history, which every view of it shares (ModelHistory). */
+    get history() {
+        return (this._history ??= new ModelHistory(this, this.historyOptions ?? {}));
+    }
+
+    /** Make a view one of this model's: its edits go on the model's history. @protected */
+    _adopt(view) {
+        view.history = this.history;
+        return view;
+    }
+
+    // ===== Saved or not =====
+
+    /** Remember this state as the saved one (after opening or saving a file). */
+    markSaved() {
+        this._saved = { structure: this._structure, token: this.history.stateToken };
+        this._emitEdit();
+    }
+
+    /**
+     * Whether anything changed since markSaved: an edit on the model's history
+     * (any view's, or to the views themselves) not undone back again.
+     */
+    isDirty() {
+        const saved = this._saved ?? { structure: 0, token: 0 };
+        return this._structure !== saved.structure || this.history.stateToken !== saved.token;
+    }
+
+    /** Call `fn(model)` after every edit (any view's history, or the set of views). Returns an unsubscribe function. */
+    onEdit(fn) {
+        this._editListeners.push(fn);
+        this._watchHistories();
+        return () => { this._editListeners = this._editListeners.filter(l => l !== fn); };
+    }
+
+    /** Listen to the model's history (and any view's own, for one not adopted). @private */
+    _watchHistories() {
+        for (const history of [this.history, ...this.views().map(v => v.history)]) {
+            if (!history?.onChange || this._watched.has(history)) continue;
+            this._watched.add(history);
+            history.onChange(() => this._emitEdit());
+        }
+    }
+
+    /** @private */
+    _emitEdit() {
+        for (const fn of this._editListeners) fn(this);
+    }
+
+    /** A new, empty view of this model's kind. @protected */
+    _newView(id, title) {
+        throw new Error(`${this.constructor.name} must implement _newView()`);
+    }
+
+    /** Subscribe to changes; returns an unsubscribe function. */
+    onChange(fn) {
+        this._listeners.push(fn);
+        return () => { this._listeners = this._listeners.filter(l => l !== fn); };
+    }
+
+    /** All views, in order. */
+    views() {
+        return [...this._views.values()];
+    }
+
+    get viewCount() {
+        return this._views.size;
+    }
+
+    get currentView() {
+        return this._views.get(this.currentViewId) ?? null;
+    }
+
+    getView(id) {
+        return this._views.get(id) ?? null;
+    }
+
+    /** Title offered for the next new view. */
+    nextViewTitle() {
+        return `${this.viewNoun} ${this._views.size + 1}`;
+    }
+
+    /** Add an empty view and make it current. */
+    createView(title = this.nextViewTitle()) {
+        return this._add(this._newView(this._newId(), title));
+    }
+
+    /** Add an independent copy of a view and make it current. */
+    duplicateView(id) {
+        const original = this._views.get(id);
+        if (!original) return null;
+        return this._add(original.copy(this._newId(), `${original.title} (copy)`));
+    }
+
+    /** Give a view a new title (not an empty one). One undo step. */
+    renameView(id, title) {
+        const view = this._views.get(id);
+        if (!view || !title || title === view.title) return false;
+        this.history.execute(new RenameViewCommand(this, view, title));
+        return true;
+    }
+
+    /** A view's title set, as RenameViewCommand and replace do it (not undoable by itself). @protected */
+    _retitle(id, title) {
+        const view = this._views.get(id);
+        if (!view) return;
+        view.title = title;
+        this._notify();
+    }
+
+    /** The checks this model is held to (ViewSetChecker; a notation's model returns its own). */
+    checker() {
+        return new ViewSetChecker(this);
+    }
+
+    /** Find and replace over the model's texts (ModelSearch; a notation's model returns its own). */
+    search() {
+        return new ModelSearch(this);
+    }
+
+    /** The model's report (ModelReport; a notation's model returns its own), for reportHtml. */
+    report(options) {
+        return new ModelReport(this, options);
+    }
+
+    /** Whether a view may be deleted: the last one stays. */
+    canDeleteView(id) {
+        return this._views.has(id) && this._views.size > 1;
+    }
+
+    /** Remove a view; the last one cannot be removed. The neighbour becomes current. One undo step. */
+    deleteView(id) {
+        if (!this.canDeleteView(id)) return false;
+        this.history.execute(new RemoveViewCommand(this, this._views.get(id)));
+        return true;
+    }
+
+    switchTo(id) {
+        if (!this._views.has(id) || id === this.currentViewId) return false;
+        this.currentViewId = id;
+        this._notify();
+        return true;
+    }
+
+    /**
+     * Add a view (last), shown unless `current` is false: one undo step on the
+     * model's history (AddViewCommand).
+     * @protected
+     */
+    _add(view, { current = true } = {}) {
+        this.history.execute(new AddViewCommand(this, this._adopt(view), { current }));
+        return view;
+    }
+
+    /**
+     * Put a view in the model at `index` (default last), current if asked; as
+     * AddViewCommand and RemoveViewCommand's undo do it.
+     * @protected
+     */
+    _insertView(view, { index = this._views.size, current = true } = {}) {
+        const entries = [...this._views].filter(([id]) => id !== view.id);
+        entries.splice(Math.min(index, entries.length), 0, [view.id, view]);
+        this._views = new Map(entries);
+        if (current || !this.currentViewId) this.currentViewId = view.id;
+        this._notify();
+    }
+
+    /**
+     * Take a view out of the model; the one in front becomes `next` (if given
+     * and still there) or, when it was this one, its neighbour.
+     * @returns {{index: number, current: boolean}} where it was, and whether it was in front
+     * @protected
+     */
+    _removeView(id, { next = null } = {}) {
+        const ids = [...this._views.keys()];
+        const index = ids.indexOf(id);
+        const current = this.currentViewId === id;
+        this._views.delete(id);
+        if (next && this._views.has(next)) this.currentViewId = next;
+        else if (current) this.currentViewId = ids[index + 1] ?? ids[index - 1] ?? null;
+        this._notify();
+        return { index, current };
+    }
+
+    _newId() {
+        let id;
+        do { id = `${this.idPrefix}-${this._nextId++}`; } while (this._views.has(id));
+        return id;
+    }
+
+    _notify() {
+        for (const fn of this._listeners) fn(this);
+        this._watchHistories();
+    }
+
+    /** A change to the set of views: the model is no longer as saved. @protected */
+    _changedStructure() {
+        this._structure++;
+        this._emitEdit();
+    }
+}

package/src/charting/diagramModel/index.js

@@ -0,0 +1,6 @@
+export { DiagramModel } from './DiagramModel.js';
+export { DiagramView } from './DiagramView.js';
+export { ViewSetModel } from './ViewSetModel.js';
+export { ModelSearch, SEARCH_FIELDS } from './ModelSearch.js';
+export { DiagramModelSearch } from './DiagramModelSearch.js';
+export { ReplaceTextCommand } from './ReplaceTextCommand.js';

package/src/charting/diagramModel/nameTransforms.js

@@ -0,0 +1,29 @@
+/**
+ * Ways to rewrite a name (the nameTransform jArchi script): Title Case,
+ * Sentence case, splitting camelCase into words and back, squeezing spaces,
+ * upper and lower case. Pure; ModelSearch#transformCommand applies one to
+ * a model's names.
+ */
+
+const words = (s) => String(s ?? '').trim().split(/\s+/).filter(Boolean);
+/** Words not capitalised inside a title. */
+const SMALL = new Set(['a', 'an', 'and', 'as', 'at', 'but', 'by', 'for', 'in', 'of', 'on', 'or', 'the', 'to', 'with']);
+const capital = (w) => w.charAt(0).toUpperCase() + w.slice(1);
+
+/** The transforms, in menu order: [key, label, (name) => name]. */
+export const NAME_TRANSFORMS = Object.freeze([
+    ['title', 'Title Case', (s) => words(s).map((w, i) => (i && SMALL.has(w.toLowerCase()) ? w.toLowerCase() : capital(w.toLowerCase()))).join(' ')],
+    ['sentence', 'Sentence case', (s) => { const t = words(s).join(' ').toLowerCase(); return capital(t); }],
+    ['split-camel', 'Split camelCase (OrderService → Order Service)', (s) => String(s ?? '').replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2').replace(/[_-]+/g, ' ').replace(/\s+/g, ' ').trim()],
+    ['camel', 'camelCase (Order Service → orderService)', (s) => words(String(s ?? '').replace(/[_-]+/g, ' ')).map((w, i) => (i ? capital(w.toLowerCase()) : w.toLowerCase())).join('')],
+    ['squeeze', 'Remove extra spaces', (s) => words(s).join(' ')],
+    ['upper', 'UPPER CASE', (s) => String(s ?? '').trim().toUpperCase()],
+    ['lower', 'lower case', (s) => String(s ?? '').trim().toLowerCase()],
+]);
+
+/** A name transformed (`key` one of NAME_TRANSFORMS'). */
+export function transformName(key, name) {
+    const fn = NAME_TRANSFORMS.find(([k]) => k === key)?.[2];
+    if (!fn) throw new RangeError(`No such name transform: ${key}`);
+    return fn(name);
+}

package/src/charting/diagrams/ArchimateCommands.js

@@ -0,0 +1,141 @@
+import { Command } from '../CommandHistory.js';
+
+/**
+ * AddToViewCommand — put one element instance on a view, as one undo step.
+ * Given a new model `element` too, the element is created with it (and goes
+ * with it on undo). The view's element filter is widened to the element if
+ * it was not already in it.
+ */
+export class AddToViewCommand extends Command {
+    /**
+     * @param {ArchimateView} view
+     * @param {ElementInstance} instance
+     * @param {Object} [options]
+     * @param {Object} [options.element] - A new model element the instance shows
+     */
+    constructor(view, instance, { element = null, label = 'Add to View' } = {}) {
+        super(label);
+        this.view = view;
+        this.instance = instance;
+        this.element = element;
+        this._createdElement = false;
+        this._widenedFilter = false;
+    }
+
+    execute() {
+        const { view, instance, element } = this;
+        this._createdElement = !!element && !view.model.getElement(element.id);
+        if (this._createdElement) view.model.addElement(element);
+        this._widenedFilter = !!view.elementIds && !instance.shownIn(view);
+        // Mutate rather than replace: other holders keep a reference to this array.
+        if (this._widenedFilter) view.elementIds.push(instance.elementId);
+        view.addElementInstance(instance);
+    }
+
+    undo() {
+        const { view, instance } = this;
+        view.removeElementInstance(instance.id);
+        if (this._widenedFilter) {
+            const at = view.elementIds.indexOf(instance.elementId);
+            if (at >= 0) view.elementIds.splice(at, 1);
+        }
+        if (this._createdElement) view.model.removeElement(this.element.id);
+    }
+}
+
+/**
+ * AddRelationshipToViewCommand — show one relationship instance on a view,
+ * as one undo step. Given a new model `relationship` too, it is created with
+ * it (and goes with it on undo).
+ */
+export class AddRelationshipToViewCommand extends Command {
+    /**
+     * @param {ArchimateView} view
+     * @param {RelationshipInstance} instance
+     * @param {Object} [options]
+     * @param {Object} [options.relationship] - A new model relationship the instance shows
+     */
+    constructor(view, instance, { relationship = null, label = 'Add Relationship to View' } = {}) {
+        super(label);
+        this.view = view;
+        this.instance = instance;
+        this.relationship = relationship;
+        this._createdRelationship = false;
+    }
+
+    execute() {
+        const { view, relationship } = this;
+        this._createdRelationship = !!relationship && !view.model.getRelationship(relationship.id);
+        if (this._createdRelationship) view.model.addRelationship(relationship);
+        view.addRelationshipInstance(this.instance);
+    }
+
+    undo() {
+        this.view.removeRelationshipInstance(this.instance.id);
+        if (this._createdRelationship) this.view.model.removeRelationship(this.relationship.id);
+    }
+}
+
+/**
+ * AddRelationshipCommand — a new relationship in the model, drawn on no view
+ * (one a nesting expresses, as Archi adds them). Undo removes it.
+ */
+export class AddRelationshipCommand extends Command {
+    constructor(model, relationship, label = `Add ${relationship.kind ?? 'relationship'}`) {
+        super(label);
+        this.model = model;
+        this.relationship = relationship;
+    }
+
+    execute() {
+        this.model.addRelationship(this.relationship);
+    }
+
+    undo() {
+        this.model.removeRelationship(this.relationship.id);
+    }
+}
+
+/**
+ * RemoveRelationshipFromViewCommand — take one relationship instance off a
+ * view (the model relationship stays). Undo puts the same instance back.
+ */
+export class RemoveRelationshipFromViewCommand extends Command {
+    constructor(view, instanceId) {
+        super('Remove Relationship from View');
+        this.view = view;
+        this.instanceId = instanceId;
+        this.removed = null;
+    }
+
+    execute() {
+        this.removed = this.view.getRelationshipInstance(this.instanceId) ?? null;
+        if (this.removed) this.view.removeRelationshipInstance(this.instanceId);
+    }
+
+    undo() {
+        if (this.removed) this.view.addRelationshipInstance(this.removed);
+    }
+}
+
+/**
+ * DeleteElementCommand — take one element instance off a view (the model
+ * element stays). Undo puts the same instance back, id and all.
+ */
+export class DeleteElementCommand extends Command {
+    constructor(view, instanceId) {
+        super('Delete Element');
+        this.view = view;
+        this.instanceId = instanceId;
+        this.removed = null;
+    }
+
+    execute() {
+        this.removed = this.view.getElementInstance(this.instanceId) ?? null;
+        if (this.removed) this.view.removeElementInstance(this.instanceId);
+    }
+
+    undo() {
+        if (this.removed) this.view.addElementInstance(this.removed);
+    }
+}

package/src/charting/diagrams/ArchimateDiagram.js

@@ -0,0 +1,263 @@
+import { Diagram } from '../Diagram.js';
+import { ArchimateNotation, ArchimateViewpoints } from '../../archimate.js';
+import { ITIconNotation } from '../../itIcons.js';
+import { ArchimateValidator } from './ArchimateValidator.js';
+import { ArchimateSpecializationRegistry } from '../../archimateSpecializations.js';
+
+/**
+ * ArchimateDiagram — builds ArchiMate-notation nodes/edges and renders them
+ * through the shared GraphDiagram engine.
+ */
+export class ArchimateDiagram extends Diagram {
+    static diagramType = 'archimate';
+
+    constructor(renderer, elements, relationships, options = {}, engine = null) {
+        super(renderer, { elements, relationships }, options);
+        this.engine = engine;
+    }
+
+    render() {
+        const { elements, relationships } = this.data;
+        const options = this.options;
+        const {
+            layerColors, relationshipStyles, defaultIcons, iconChoiceIndex = 0, elementWidth = 120, elementHeight = 55,
+            archimateVersion = '4', useDistinctShapes = false, iconSet = 'glyph',
+            validate = true, invalidRelationships = 'highlight', onValidationWarning, annotations = [], viewpoint = null,
+            viewpointMode = 'fade', customViewpoints = [], ...rest
+        } = options;
+        const nodeOpts = {
+            layerColors, defaultIcons, iconChoiceIndex, elementWidth, elementHeight,
+            archimateVersion, useDistinctShapes, iconSet,
+        };
+        const nodes = elements.map(element => ArchimateDiagram.buildNode(element, nodeOpts));
+
+        // Viewpoint filtering: hide or fade element types that do not belong to
+        // the active viewpoint. Annotations are never affected.
+        const effectiveViewpoint = viewpoint && viewpoint !== 'All' ? viewpoint : null;
+        const allowedTypes = effectiveViewpoint
+            ? new Set(ArchimateViewpoints.allowedElementTypes(viewpoint, archimateVersion, customViewpoints))
+            : null;
+        let visibleNodes = nodes;
+        let visibleEdges = relationships;
+        if (effectiveViewpoint) {
+            const isAllowed = (type) => allowedTypes.has(type);
+            const allowedNodeIds = new Set();
+            for (const node of nodes) {
+                if (isAllowed(node.type)) allowedNodeIds.add(node.id);
+            }
+            visibleNodes = [];
+            for (const node of nodes) {
+                const allowed = allowedNodeIds.has(node.id);
+                if (allowed) {
+                    visibleNodes.push(node);
+                } else if (viewpointMode === 'fade') {
+                    node.opacity = 0.2;
+                    visibleNodes.push(node);
+                }
+                // viewpointMode === 'hide' drops the node entirely.
+            }
+            visibleEdges = [];
+            for (const rel of relationships) {
+                const sourceAllowed = allowedNodeIds.has(rel.source);
+                const targetAllowed = allowedNodeIds.has(rel.target);
+                if (sourceAllowed && targetAllowed) {
+                    visibleEdges.push(rel);
+                } else if (viewpointMode === 'fade' && (sourceAllowed || targetAllowed)) {
+                    rel.opacity = 0.2;
+                    visibleEdges.push(rel);
+                }
+                // In hide mode, drop edges touching a hidden node.
+            }
+        }
+
+        // Annotations are diagram-only sticky-note comments, not part of the
+        // ArchiMate model. They are appended as plain graphDiagram nodes so they
+        // get drag/resize/delete/properties for free; mutating them in place
+        // keeps the caller's annotations array in sync across rerenders.
+        for (const annotation of annotations) {
+            if (!annotation.id) annotation.id = `note_${Math.random().toString(36).slice(2, 9)}`;
+            annotation.shape = 'note';
+            annotation.labelPosition = annotation.labelPosition || 'inside';
+            annotation.resizable = annotation.resizable !== false;
+            visibleNodes.push(annotation);
+        }
+
+        // Validate the model before building edges so warnings can be attached
+        // to the edges that GraphDiagram will actually draw.
+        // 'off' checks nothing; 'tooltip' warns on hover only; 'highlight' also draws the line red and dashed.
+        const warnings = validate && invalidRelationships !== 'off'
+            // A plain line on a view (viewConnection) is no ArchiMate relationship: nothing to check.
+            ? ArchimateValidator.validateModel(elements, relationships.filter(r => !r.viewConnection), archimateVersion, viewpoint, customViewpoints)
+            : [];
+        const warningByEdge = new Map();
+        for (const w of warnings) {
+            if (w.type === 'relationship' && w.relationship) {
+                warningByEdge.set(w.relationship, w);
+            }
+            if (typeof onValidationWarning === 'function') {
+                onValidationWarning(w);
+            }
+        }
+
+        // Build edges in place on the caller's relationships array so drag-to-
+        // create and property-edits persist back into the source array across
+        // rerenders (e.g. after switching ArchiMate version or applying a style).
+        for (let i = 0; i < visibleEdges.length; i++) {
+            ArchimateDiagram.buildEdge(visibleEdges[i], { relationshipStyles, warningByEdge, highlight: invalidRelationships === 'highlight' });
+        }
+
+        // ArchiMate tools draw relationships over elements (a line into a nested element stays visible).
+        this.engine.graphDiagram(visibleNodes, visibleEdges, { edgeColor: '#666666', edgesOnTop: true, ...rest });
+
+        // Expose warnings on the engine so callers can read them back after render.
+        if (this.engine) {
+            this.engine._archimateWarnings = warnings;
+        }
+
+        // Diagram-wide ArchiMate settings survive a rerender so live icon-choice
+        // changes can be applied later (see RenderEngine._archimateSetIconChoiceIndex).
+        this.engine._archimateOptions = {
+            layerColors, defaultIcons, iconChoiceIndex, relationshipStyles, elementWidth, elementHeight,
+            archimateVersion, useDistinctShapes, iconSet, viewpoint,
+            viewpointMode, customViewpoints,
+        };
+    }
+
+    static elementLayer(element, version) {
+        // An explicit `element.layer` always wins, then a known official or IT
+        // extension type, then the prefix heuristic for custom names.
+        if (element?.layer) return element.layer;
+        const itType = typeof element?.type === 'string' ? ITIconNotation.elementType(element.type) : undefined;
+        if (itType?.layer?.name) return itType.layer.name;
+        return ArchimateNotation.elementLayer(element, version);
+    }
+
+    static layerColor(layer, layerColors, ownColor) {
+        return layerColors?.[layer] || ownColor || ArchimateNotation.layer(layer)?.color || ArchimateNotation.layer('other').color;
+    }
+
+    static defaultIcon(element, layer, defaultIcons, iconChoiceIndex = 0, version) {
+        if (defaultIcons?.[layer]) return defaultIcons[layer];
+        const type = typeof element?.type === 'string'
+            ? ArchimateDiagram.resolveElementType(element.type, version)
+            : undefined;
+        if (type) {
+            // IT extension types carry a single icon, not a choice list.
+            if (!type.iconChoices) return type.icon;
+            const choices = type.iconChoices;
+            return choices[iconChoiceIndex] ?? choices[0];
+        }
+        return ArchimateNotation.layer(layer)?.defaultIcon || ArchimateNotation.layer('other').defaultIcon;
+    }
+
+    static relationshipStyle(kind, relationshipStyles) {
+        return relationshipStyles?.[kind] || ArchimateNotation.relationshipType(kind);
+    }
+
+    /** Live diagram-wide setting: which choice in each element type's own
+     *  `iconChoices` is used as the DEFAULT icon for a node that doesn't carry
+     *  its own explicit `icon`/`iconUrl`. Changing it re-derives the icon for
+     *  every node that hasn't been individually customised, leaving any node
+     *  whose icon was deliberately picked untouched. No-op if this isn't (or
+     *  is no longer) an ArchiMate diagram. */
+    static setIconChoiceIndex(engine, newIndex) {
+        const opts = engine?._archimateOptions;
+        if (!opts || !engine._chartState?.nodes) return;
+        const oldIndex = opts.iconChoiceIndex ?? 0;
+        for (const node of engine._chartState.nodes) {
+            if (node.iconUrl) continue;
+            const layer = ArchimateDiagram.elementLayer(node, opts.archimateVersion);
+            const wasAuto = node.icon === ArchimateDiagram.defaultIcon(node, layer, opts.defaultIcons, oldIndex, opts.archimateVersion);
+            if (wasAuto) node.icon = ArchimateDiagram.defaultIcon(node, layer, opts.defaultIcons, newIndex, opts.archimateVersion);
+        }
+        opts.iconChoiceIndex = newIndex;
+        engine._graphDiagram?._rerenderGraph();
+    }
+
+    static cornerStyle(element, layer, version) {
+        if (element?.cornerStyle) return element.cornerStyle;
+        if (layer === 'motivation') return 'chamfered';
+        const type = typeof element?.type === 'string'
+            ? ArchimateDiagram.resolveElementType(element.type, version)
+            : undefined;
+        const aspect = element?.aspect || type?.aspect;
+        return aspect === 'behavior' ? 'rounded' : 'sharp';
+    }
+
+    /** Resolve an element `type` to either an official ArchiMate type or an
+     *  IT/infrastructure extension type. Returns the matching descriptor object
+     *  (which has the same `layer`/`aspect`/`icon`/`notationShape`/`description`
+     *  shape in both cases) or undefined. */
+    static resolveElementType(typeName, archimateVersion = '4') {
+        if (typeof typeName !== 'string') return undefined;
+        return ArchimateNotation.elementType(typeName, archimateVersion)
+            || ITIconNotation.elementType(typeName);
+    }
+
+    static buildNode(element, {
+        layerColors, defaultIcons, iconChoiceIndex = 0, elementWidth = 120, elementHeight = 55,
+        archimateVersion = '4', useDistinctShapes = false, iconSet = 'glyph',
+    } = {}) {
+        const resolved = archimateVersion === '4' ? ArchimateNotation.migrateElementToV4(element) : element;
+        ArchimateSpecializationRegistry.applyToNode(resolved);
+        const layer = ArchimateDiagram.elementLayer(resolved, archimateVersion);
+        const type = ArchimateDiagram.resolveElementType(resolved.type, archimateVersion);
+        const useDistinctShape = resolved.useDistinctShape ?? useDistinctShapes;
+        const notationShape = useDistinctShape ? type?.notationShape : undefined;
+        const glyphBadges = (resolved.iconSet ?? iconSet) !== 'emoji';
+
+        // CRITICAL: Use diagramInstanceId (not elementId) as the node's unique ID
+        // This allows multiple instances of the same element to render as separate visual nodes
+        const nodeId = resolved.diagramInstanceId || resolved.id;
+        // A view-only box (note, image, canvas or sketch box) has no ArchiMate type: no type
+        // icon, and a plain white fill unless it sets one (a note keeps its own default).
+        const viewBox = resolved.viewObject && resolved.shape !== 'note';
+
+        return {
+            ...resolved,
+            id: nodeId,  // Override to use diagramInstanceId for uniqueness
+            layer,
+            shape: resolved.shape || notationShape || 'rect',
+            color: resolved.color || (viewBox ? '#ffffff' : ArchimateDiagram.layerColor(layer, layerColors, type?.ownColor)),
+            width: resolved.width ?? elementWidth,
+            height: resolved.height ?? elementHeight,
+            strokeColor: resolved.strokeColor || '#000000',
+            strokeWidth: resolved.strokeWidth ?? 1.2,
+            // The ArchiMate notation draws a Grouping with a dashed outline.
+            ...(type?.name === 'grouping' && { strokeDasharray: resolved.strokeDasharray ?? '6 3' }),
+            labelPosition: resolved.labelPosition || (notationShape ? 'below' : 'inside'),
+            iconPosition: resolved.iconPosition || 'corner',
+            cornerStyle: ArchimateDiagram.cornerStyle(resolved, layer, archimateVersion),
+            iconShape: resolved.viewObject ? undefined : resolved.iconShape || ((resolved.icon || resolved.iconUrl) && glyphBadges ? undefined : (notationShape || !glyphBadges ? undefined : type?.notationShape)),
+            icon: resolved.viewObject ? resolved.icon : resolved.icon || (resolved.iconUrl || notationShape || (glyphBadges && type?.notationShape)
+                ? undefined
+                : ArchimateDiagram.defaultIcon(resolved, layer, defaultIcons, iconChoiceIndex, archimateVersion)),
+        };
+    }
+
+    static buildEdge(relationship, { relationshipStyles, warningByEdge, highlight = true } = {}) {
+        const style = ArchimateDiagram.relationshipStyle(relationship.kind, relationshipStyles);
+        // Mutate the caller's original relationship object rather than returning
+        // a shallow copy, so edits made via the context-menu Properties dialog
+        // persist back into the source array (engine._chartState.relationships).
+        relationship.lineStyle = relationship.lineStyle || style.lineStyle;
+        relationship.arrowhead = relationship.arrowhead || style.arrowhead || 'none';
+        relationship.arrowheadStart = relationship.arrowheadStart || style.arrowheadStart;
+
+        const warning = warningByEdge?.get(relationship);
+        if (warning) {
+            relationship._archimateWarning = warning.message;
+            if (highlight) {
+                relationship.color = relationship.color || '#e74c3c';
+                relationship.dasharray = relationship.dasharray || '4 3';
+            }
+            const existingTooltip = relationship.tooltip || '';
+            const warningTooltip = `⚠️ ${warning.message}`;
+            relationship.tooltip = existingTooltip
+                ? `${existingTooltip}\n${warningTooltip}`
+                : warningTooltip;
+        }
+
+        return relationship;
+    }
+}