@peter.prib/renderengine 0.0.0-stage → 0.2.0

package/src/charting/diagrams/ArchimateModel.js

@@ -0,0 +1,1155 @@
+import { ElementInstance } from './ElementInstance.js';
+import { ViewObjectInstance, instanceFromJSON } from './ViewObjectInstance.js';
+import { RelationshipInstance } from './RelationshipInstance.js';
+import { ViewConnectionInstance } from './ViewConnectionInstance.js';
+import { DiagramEditorState } from '../DiagramEditorState.js';
+import { ViewSetModel } from '../diagramModel/ViewSetModel.js';
+import { ArchimateModelChecker } from './ArchimateModelChecker.js';
+import { ArchimateModelReport } from './ArchimateModelReport.js';
+import { ArchimateModelSearch } from './ArchimateModelSearch.js';
+import { MergeElementsCommand } from './MergeElementsCommand.js';
+import { roadmapPlan, parseDate } from './roadmap.js';
+import { PlaceItemsCommand } from './PlaceItemsCommand.js';
+import { DIAGRAM_BOX_KINDS } from '../canvas/diagramBoxKinds.js';
+import { RemoveLineCommand } from './RemoveLineCommand.js';
+import { CompositeCommand } from '../CommandHistory.js';
+import { AddToViewCommand, DeleteElementCommand, AddRelationshipToViewCommand, RemoveRelationshipFromViewCommand } from './ArchimateCommands.js';
+
+/**
+ * Canonical, id-indexed home for ArchiMate model data (elements, relationships, views).
+ * Replaces ad-hoc flat-array handling and fixes multi-view import flattening.
+ *
+ * ARCHITECTURE: Model layer is view-agnostic. Elements and relationships have NO x/y/labelOverride/
+ * or visibility properties. Those belong in ElementInstance/RelationshipInstance (view layer).
+ */
+
+export class ArchimateModel extends ViewSetModel {
+    constructor({ id = undefined, name = '', elements = [], relationships = [], folders = [], elementFolders = [], views = [], documentation = undefined, properties = [], archi = null } = {}) {
+        // Views (create, duplicate, rename, delete, switch, change listeners) come from ViewSetModel.
+        super({ idPrefix: 'view', viewNoun: 'View' });
+        this.name = name;
+        this._elements = new Map();      // id -> element object
+        this._relationships = new Map(); // id -> relationship object
+        this._folders = new Map();       // id -> folder object {id, name, documentation, parentId, children[]}
+        /** The model's id (an Archi file's, kept on export); undefined for a new model. */
+        this.id = id;
+        /** The model's own documentation (Archi's "purpose") and properties ([{key, value}], keys may repeat). */
+        this.documentation = documentation;
+        this.properties = properties.map(p => ({ ...p }));
+        /** What an Archi file said about the model that it does not use (profiles, ...), written back on export. */
+        this.archi = archi;
+        this._elementFolder = new Map(); // elementId -> folderId (which folder contains this element)
+
+        // Ingest elements
+        for (const el of elements) {
+            if (!el.id) throw new TypeError('Element must have an id');
+            this._validateElementNoViewProperties(el);
+            this._elements.set(el.id, { ...el });
+        }
+
+        // Ingest relationships; auto-assign id if missing
+        for (let i = 0; i < relationships.length; i++) {
+            const rel = relationships[i];
+            const id = rel.id ?? `rel-${i}`;
+            if (this._relationships.has(id)) {
+                throw new TypeError(`Duplicate relationship id: "${id}"`);
+            }
+            this._relationships.set(id, { ...rel, id });
+        }
+
+        // Ingest folders (top-level only; hierarchy maintained in folder.children)
+        for (const folder of folders) {
+            if (!folder.id) throw new TypeError('Folder must have an id');
+            this._folders.set(folder.id, { ...folder });
+        }
+
+        // Ingest element-to-folder mappings
+        for (const [elementId, folderId] of elementFolders) {
+            this._elementFolder.set(elementId, folderId);
+        }
+
+        // Ingest views; the first is current.
+        for (const viewSpec of views) {
+            const view = this._adopt(this._createView(viewSpec));
+            this._views.set(view.id, view);
+        }
+        this.currentViewId = views.length ? this.views()[0].id : null;
+    }
+
+    /** A new view starts empty: elements are added to it, not inherited. */
+    _newView(id, title) {
+        return new ArchimateView(this, { id, name: title, elementIds: [] });
+    }
+
+    /**
+     * The view for a spec: the class registered for its Archi view type
+     * (registerViewType: CanvasView for 'canvas-model'), else an ArchimateView.
+     * @protected
+     */
+    _createView(spec) {
+        const ViewClass = ArchimateModel.VIEW_TYPES.get(spec?.archiViewType) ?? ArchimateView;
+        return new ViewClass(this, spec);
+    }
+
+    /** A view class for an Archi view type ('canvas-model', ...). A subclass of ArchimateView registers itself. */
+    static registerViewType(archiViewType, ViewClass) {
+        ArchimateModel.VIEW_TYPES.set(archiViewType, ViewClass);
+    }
+
+    /** Canvas views that are not templates, in order. */
+    canvases() {
+        return this.views().filter(v => v.constructor.kind === 'canvas' && !v.template);
+    }
+
+    /** The model's own templates (canvas views kept to copy from), in order. */
+    templates() {
+        return this.views().filter(v => v.template);
+    }
+
+    /** ArchiMate (and sketch) views: every view that is not a canvas or a template. */
+    diagramViews() {
+        return this.views().filter(v => v.constructor.kind !== 'canvas' && !v.template);
+    }
+
+    /**
+     * A new canvas made from a template: a model template (a view) or a library
+     * entry's `view` (CanvasView JSON). It gets new ids and the template's boxes and
+     * lines; the boxes are its background (one BackgroundGroup: behind everything
+     * added later, moved as one, locked until unlocked). It becomes the current view.
+     * @param {ArchimateView|Object} template - A template view, or CanvasView JSON
+     * @param {string} [title]
+     * @returns {ArchimateView}
+     */
+    newCanvasFromTemplate(template, title) {
+        const canvas = this._canvasFrom(template, title);
+        // What the template draws is the canvas's background: one group, behind everything, locked.
+        canvas.arrangeAsBackground(canvas.elementInstances.keys(), { name: `${template.name ?? template.title ?? 'Template'} (template)` });
+        return this._add(canvas);
+    }
+
+    /**
+     * A new view of some elements and what they are related to (Archi's
+     * "Generate View For"): the elements in the middle, each related element
+     * around them, and every relationship between what is shown (a view made
+     * from a layout draws them all). It becomes
+     * the current view.
+     * @param {Array<string>} elementIds
+     * @param {Object} [options]
+     * @param {string} [options.name] - Defaults to the first element's name
+     * @param {boolean} [options.related] - Bring in the elements they are related to (default true)
+     * @returns {ArchimateView|null} the view, or null if no element is known
+     */
+    generateView(elementIds, { name, related = true } = {}) {
+        const focus = [...new Set(elementIds)].filter(id => this.getElement(id));
+        if (!focus.length) return null;
+        const neighbours = [];
+        if (related) {
+            const seen = new Set(focus);
+            for (const id of focus) {
+                const { incoming, outgoing } = this.relationshipsFor(id);
+                for (const r of [...incoming, ...outgoing]) {
+                    const other = r.source === id ? r.target : r.source;
+                    if (!seen.has(other) && this.getElement(other)) { seen.add(other); neighbours.push(other); }
+                }
+            }
+        }
+        // The focus in a row through the middle; the related ones on a circle around it.
+        const GAP = 180, centre = { x: 500, y: 400 };
+        const radius = Math.max(260, (focus.length * GAP) / 2 + 160, (neighbours.length * 150) / (2 * Math.PI));
+        const layout = {};
+        focus.forEach((id, i) => { layout[id] = { x: centre.x + (i - (focus.length - 1) / 2) * GAP, y: centre.y }; });
+        neighbours.forEach((id, i) => {
+            const angle = -Math.PI / 2 + (2 * Math.PI * i) / neighbours.length;
+            layout[id] = { x: Math.round(centre.x + radius * Math.cos(angle)), y: Math.round(centre.y + radius * Math.sin(angle)) };
+        });
+        const view = this._createView({
+            id: this._newId(),
+            name: name ?? `${this.getElement(focus[0]).name || 'Element'} (generated)`,
+            elementIds: [...focus, ...neighbours],
+            layout,
+        });
+        return this._add(view);
+    }
+
+    /**
+     * A new view of elements on a time line (a roadmap): each element with a
+     * start and an end date (its `startProperty` and `endProperty` properties,
+     * ISO or day/month/year) a bar from one to the other, under a header of
+     * years and months; bars that overlap in time in lanes below each other.
+     * Elements without both dates (or ending before they start) are left out
+     * and listed. It becomes the current view; one undo step.
+     * @param {Array<string>} elementIds
+     * @param {Object} [options]
+     * @param {string} [options.startProperty] - Default 'Start Date'
+     * @param {string} [options.endProperty] - Default 'End Date'
+     * @param {string} [options.name] - The view's name
+     * @param {'short'|'full'} [options.monthNames]
+     * @returns {{view: (ArchimateView|null), skipped: Array<Object>}} the view (null when no element has dates), and the elements left out
+     */
+    generateRoadmap(elementIds, { startProperty = 'Start Date', endProperty = 'End Date', name = 'Roadmap', monthNames = 'short' } = {}) {
+        const prop = (e, key) => (e.properties ?? []).find(p => (p.name ?? p.key) === key)?.value;
+        const elements = [...new Set(elementIds)].map(id => this.getElement(id)).filter(Boolean);
+        const items = elements.map(e => ({ id: e.id, element: e, start: parseDate(prop(e, startProperty)), end: parseDate(prop(e, endProperty)) }));
+        const dated = items.filter(i => i.start && i.end && i.end >= i.start);
+        const skipped = items.filter(i => !dated.includes(i)).map(i => i.element);
+        if (!dated.length) return { view: null, skipped };
+        const plan = roadmapPlan(dated, { monthNames, monthWidth: monthNames === 'full' ? 90 : 60 });
+        const view = this._createView({ id: this._newId(), name, elementIds: dated.map(i => i.id) });
+        const note = (key, label, box, extra = {}) => {
+            const inst = new ViewObjectInstance({ id: `${view.id}-${key}`, name: label, label, shape: 'note' }, box.x + box.width / 2, box.y + box.height / 2);
+            inst.size = { width: box.width, height: box.height };
+            inst.appearance = { fillColor: '#ffffff', textAlign: 'center', ...extra };
+            inst.zIndex = -1;
+            return inst;
+        };
+        view.elementInstances.clear();
+        plan.years.forEach((y, i) => { const n = note(`year-${i}`, y.label, y, { fontWeight: 'bold' }); view.elementInstances.set(n.id, n); });
+        plan.months.forEach((m, i) => {
+            const header = note(`month-${i}`, m.label, m);
+            const column = note(`column-${i}`, '', { x: m.x, y: m.y + m.height, width: m.width, height: plan.height - 2 * m.height });
+            column.appearance = { fillColor: i % 2 ? '#f5f5f5' : '#ffffff', strokeColor: '#dddddd' };
+            column.zIndex = -2;
+            view.elementInstances.set(header.id, header);
+            view.elementInstances.set(column.id, column);
+        });
+        for (const bar of plan.bars) {
+            const inst = new ElementInstance(bar.id, bar.x + bar.width / 2, bar.y + bar.height / 2);
+            inst.size = { width: bar.width, height: bar.height };
+            inst.appearance = { fontSize: 9 };
+            view.elementInstances.set(inst.id, inst);
+        }
+        view.relationshipInstances?.clear?.();
+        return { view: this._add(view), skipped };
+    }
+
+    /**
+     * The checks this model is held to: the view-set ones and ArchiMate's own
+     * (ArchimateModelChecker).
+     * @param {{version?: string}} [options] - The ArchiMate version for the relationship check
+     */
+    checker(options) {
+        return new ArchimateModelChecker(this, options);
+    }
+
+    /**
+     * Make elements that are one thing twice into one: `keepId` takes the
+     * others' relationships, boxes, missing documentation and properties
+     * (MergeElementsCommand, not yet executed; put it on `history`).
+     */
+    mergeCommand(keepId, otherIds) {
+        return new MergeElementsCommand(this, keepId, otherIds);
+    }
+
+    /** Find and replace: the views, notes, elements and relationships (ArchimateModelSearch). */
+    search() {
+        return new ArchimateModelSearch(this);
+    }
+
+    /** The model's report: its views, elements and relationships (ArchimateModelReport). */
+    report(options) {
+        return new ArchimateModelReport(this, options);
+    }
+
+    /** A new, empty canvas; it becomes the current view. */
+    createCanvas(title = `Canvas ${this.canvases().length + 1}`) {
+        return this._add(this._createView({ id: this._newId(), name: title, archiViewType: 'canvas-model' }));
+    }
+
+    /**
+     * Keep a copy of a canvas as one of the model's templates. The current
+     * view stays as it is.
+     * @param {string} viewId - A canvas
+     * @param {string} [title] - Defaults to the canvas's name
+     * @param {{itemIds?: Iterable<string>}} [options] - Only these boxes (and the lines between them)
+     * @returns {ArchimateView|null} the template, or null if `viewId` is not a canvas
+     */
+    saveAsTemplate(viewId, title, { itemIds = null } = {}) {
+        const view = this.getView(viewId);
+        if (view?.constructor.kind !== 'canvas') return null;
+        // Some of its boxes only (a selection, a group): their JSON, with the lines between them.
+        return this.addTemplate(itemIds ? view.toJSON({ itemIds }) : view, title ?? (itemIds ? `${view.name} (part)` : view.name));
+    }
+
+    /**
+     * A model template copied from a canvas, a template, or a library entry's
+     * `view` (CanvasView JSON). The current view stays as it is.
+     * @param {ArchimateView|Object} source
+     * @param {string} [title]
+     * @returns {ArchimateView}
+     */
+    addTemplate(source, title) {
+        const template = this._canvasFrom(source, title);
+        template.template = true;
+        return this._add(template, { current: false });
+    }
+
+    /** A new canvas (not a template) copied from a view or from CanvasView JSON. @private */
+    _canvasFrom(source, title) {
+        const id = this._newId();
+        const name = title ?? source.name ?? source.title ?? 'Canvas';
+        return typeof source.copy === 'function'
+            ? source.copy(id, name)
+            : ArchimateModel.VIEW_TYPES.get('canvas-model').fromJSON(this, source, { id, name });
+    }
+
+    /** Get element by id, or undefined. */
+    getElement(id) {
+        return this._elements.get(id);
+    }
+
+    /**
+     * Add an element to the model. Position and other per-view state belong on
+     * the ElementInstance, so they are not kept here.
+     * @returns {Object} the stored element
+     */
+    addElement(el) {
+        if (!el?.id) throw new TypeError('Element must have an id');
+        if (this._elements.has(el.id)) throw new TypeError(`Duplicate element id: "${el.id}"`);
+        const { x, y, labelOverride, visible, diagramInstanceId, ...modelEl } = el;
+        this._elements.set(el.id, modelEl);
+        return modelEl;
+    }
+
+    /** Remove an element from the model (views keep any instances; they no longer resolve). */
+    removeElement(id) {
+        this._elements.delete(id);
+        this._elementFolder.delete(id);
+    }
+
+    /** Add a relationship to the model. @returns {Object} the stored relationship */
+    addRelationship(rel) {
+        if (!rel?.id) throw new TypeError('Relationship must have an id');
+        if (this._relationships.has(rel.id)) throw new TypeError(`Duplicate relationship id: "${rel.id}"`);
+        const stored = { ...rel };
+        this._relationships.set(rel.id, stored);
+        return stored;
+    }
+
+    /** Remove a relationship from the model (views keep any instances; they no longer resolve). */
+    removeRelationship(id) {
+        this._relationships.delete(id);
+    }
+
+    /** Get relationship by id, or undefined. */
+    getRelationship(id) {
+        return this._relationships.get(id);
+    }
+
+    /** Get folder by id, or undefined. */
+    getFolder(id) {
+        return this._folders.get(id);
+    }
+
+    /** Get the folder id containing an element, or undefined. */
+    getElementFolder(elementId) {
+        return this._elementFolder.get(elementId);
+    }
+
+    /** Set which folder contains an element. */
+    setElementFolder(elementId, folderId) {
+        if (folderId) {
+            this._elementFolder.set(elementId, folderId);
+        } else {
+            this._elementFolder.delete(elementId);
+        }
+    }
+
+    /** Get all elements in a folder (direct children only, not recursive). */
+    getElementsInFolder(folderId) {
+        const result = [];
+        for (const [elementId, folderIdForElement] of this._elementFolder.entries()) {
+            if (folderIdForElement === folderId) {
+                const el = this._elements.get(elementId);
+                if (el) result.push(el);
+            }
+        }
+        return result;
+    }
+
+    /** All elements, as a flat array. */
+    elements() {
+        return Array.from(this._elements.values());
+    }
+
+    /** All relationships, as a flat array. */
+    relationships() {
+        return Array.from(this._relationships.values());
+    }
+
+    /** Top-level folders only (children tracked within folder.children). */
+    folders() {
+        return Array.from(this._folders.values()).filter(f => !f.parentId);
+    }
+
+    /** All folders including nested (flat array), each after its parent. Nesting
+     *  is read from `parentId`, which every folder carries (`children` may not be kept). */
+    allFolders() {
+        const all = Array.from(this._folders.values());
+        const byParent = new Map();
+        for (const f of all) {
+            if (f.parentId) byParent.set(f.parentId, [...(byParent.get(f.parentId) ?? []), f]);
+        }
+        const result = [];
+        const walk = (folder) => {
+            result.push(folder);
+            (byParent.get(folder.id) ?? []).forEach(walk);
+        };
+        all.filter(f => !f.parentId || !this._folders.has(f.parentId)).forEach(walk);
+        return result;
+    }
+
+    /** Incoming and outgoing relationships for an element. */
+    relationshipsFor(elementId) {
+        const rels = Array.from(this._relationships.values());
+        return {
+            incoming: rels.filter(r => r.target === elementId),
+            outgoing: rels.filter(r => r.source === elementId),
+        };
+    }
+
+    /**
+     * Validate that an element has no view-specific properties.
+     * View-specific state (position, label override, visibility) belongs in ElementInstance,
+     * not in base model elements.
+     * @private
+     */
+    _validateElementNoViewProperties(el) {
+        const viewProps = ['x', 'y', 'labelOverride', 'visible', 'diagramInstanceId'];
+        for (const prop of viewProps) {
+            if (prop in el) {
+                console.warn(`WARNING: Element "${el.id}" has view-property "${prop}"; this should be in ElementInstance, not the model.`);
+            }
+        }
+    }
+
+    /** Add a view from a spec (as the constructor takes them) and make it current. */
+    addView(viewSpec) {
+        return this._add(this._createView(viewSpec));
+    }
+
+    /** Views that include a given element (or all views if elementId is null). */
+    viewsContaining(elementId) {
+        if (!elementId) return this.views();
+        return this.views().filter(v => v.includesElement(elementId));
+    }
+
+    /** Convert from an Archi-format parsed model (with .elements, .relationships, .folders, .views). */
+    static fromArchiModel(archiModel, mappers = {}) {
+        const { mapElement = el => el, mapRelationship = rel => rel } = mappers;
+        const elements = (archiModel.elements || []).map(mapElement);
+        const relationships = (archiModel.relationships || []).map(mapRelationship);
+        const folders = archiModel.folders || [];
+        const elementFolders = archiModel.elementFolders || [];
+        const views = (archiModel.views || []).map(view => ({
+            id: view.id,
+            name: view.name,
+            elementIds: view.elementIds,
+            viewpoint: view.viewpoint,
+            viewpointMode: view.viewpointMode,
+            layout: view.layout || {},
+            edgeLayout: view.edgeLayout || {},
+            folderLayout: view.folderLayout || {},
+            diagramInstances: view.diagramInstances || [],
+        }));
+        return new ArchimateModel({ elements, relationships, folders, elementFolders, views });
+    }
+}
+
+/** View classes by Archi view type; see ArchimateModel.registerViewType. */
+ArchimateModel.VIEW_TYPES = new Map();
+
+/**
+ * New boxes like these, for a copied view: each gets a new id and loses its
+ * Archi id (Archi's ids are unique in a model), and a box drawn inside another
+ * stays inside that box's copy.
+ * @param {Array<Object>} items - Instances' JSON (toJSON), each with its `id`
+ * @returns {{ elementInstances: Map<string, Object>, instanceIds: Map<string, string> }}
+ *   the copies by id, and each source id's copy id
+ */
+export function copyViewInstances(items) {
+    const instanceIds = new Map();
+    const elementInstances = new Map();
+    const copyIdOfArchiId = new Map();
+    for (const item of items) {
+        const twin = instanceFromJSON(JSON.parse(JSON.stringify(item)));
+        if (twin.archi?.id) {
+            copyIdOfArchiId.set(twin.archi.id, twin.id);
+            delete twin.archi.id;
+        }
+        instanceIds.set(item.id, twin.id);
+        elementInstances.set(twin.id, twin);
+    }
+    // A nested box names its parent's Archi id; the parent's copy is exported as diag-<its id>.
+    for (const twin of elementInstances.values()) {
+        const parent = twin.archi?.parent;
+        if (parent && copyIdOfArchiId.has(parent)) twin.archi.parent = `diag-${copyIdOfArchiId.get(parent)}`;
+    }
+    return { elementInstances, instanceIds };
+}
+
+export class ArchimateView extends DiagramEditorState {
+    /** A counter for ids of boxes placed in this page (with the time, unique). */
+    static placed = 1;
+
+    /** Fields the view adds to what it hands the renderer (`elements`/`relationships`): bookkeeping, not properties. */
+    /** The kind of view: 'archimate' here, 'canvas' for a CanvasView. */
+    static kind = 'archimate';
+
+    /** The boxes this kind of view adds besides elements (CanvasBoxKind): Archi's Note and Image here. */
+    static BOX_KINDS = DIAGRAM_BOX_KINDS;
+
+    /** Archi's class for a plain line drawn on this kind of view. */
+    static LINE_TYPE = 'diagram-model-connection';
+
+    /** Lines drawn so far: part of each new line's id. @private */
+    static _lines = 1;
+
+    static PROJECTION_KEYS = ['elementId', 'relationshipId', 'diagramInstanceId', 'visible', 'zIndex', 'viewObject', 'locked', 'moveWith', 'resizable'];
+
+    constructor(model, { id = null, name = '', elementIds = null, viewpoint = null, viewpointMode = null, layout = {}, edgeLayout = {}, folderLayout = {}, diagramInstances = [], elementInstances = null, relationshipInstances = null, viewObjects = [], viewConnections = [], archiViewType = 'archimate-diagram-model', properties = [], archiFolder = undefined, archi = null, arrangement = null, documentation = undefined, settings = undefined } = {}) {
+        super({ arrangement });
+        if (!id) throw new TypeError('View must have an id');
+        this.model = model;
+        /** @type {Map<string, ElementInstance>} what this view draws, by instance id */
+        this.elementInstances = new Map();
+        /** @type {Map<string, RelationshipInstance>} */
+        this.relationshipInstances = new Map();
+        this.id = id;
+        this.name = name;
+        this.documentation = documentation;
+        // This view's level of the settings cascade (SettingsManager reads and writes it).
+        if (settings) this._settings = { ...settings };
+        this.elementIds = elementIds; // null = "all elements"
+        this.viewpoint = viewpoint;
+        this.viewpointMode = viewpointMode;
+        this.folderLayout = folderLayout; // { folderId -> {x,y,width,height,collapsed}, etc } — per-view folder bounds/state
+
+        // Migrate old formats to new instance-based approach
+        this._migrateToInstances(layout, edgeLayout, diagramInstances, elementInstances, relationshipInstances);
+
+        // Notes and images that belong to this view only ({content, x, y}, e.g. from an Archi import).
+        for (const { content, x = 0, y = 0 } of viewObjects) {
+            const inst = new ViewObjectInstance(content, x, y);
+            this.elementInstances.set(inst.id, inst);
+        }
+
+        /** @type {Map<string, ViewConnectionInstance>} lines on this view with no relationship behind them */
+        this.viewConnections = new Map();
+        for (const c of viewConnections) {
+            const inst = c instanceof ViewConnectionInstance ? c : ViewConnectionInstance.fromJSON(c);
+            this.viewConnections.set(inst.id, inst);
+        }
+        /** Archi's class for the view ('archimate-diagram-model', 'canvas-model', 'sketch-model'), kept for export. */
+        this.archiViewType = archiViewType;
+        /** The view's properties, [{key, value}] (keys may repeat). */
+        this.properties = properties.map(p => ({ ...p }));
+        /** The Views sub-folders an Archi file kept it in ([{id, name, ...}]), kept for export. */
+        this.archiFolder = archiFolder;
+        /** What an Archi file said about the view that the model does not use (hintTitle, viewpoint, ...). */
+        this.archi = archi;
+
+        // Legacy property kept for backward compatibility (read-only)
+        this.layout = layout;
+    }
+
+    /**
+     * Migrate from old layout/diagramInstances format to new ElementInstance/RelationshipInstance collections.
+     * @private
+     */
+    _migrateToInstances(layout, edgeLayout, diagramInstances, elementInstances, relationshipInstances) {
+        // If new instance maps provided, use them
+        if (elementInstances instanceof Map) {
+            this.elementInstances = new Map(elementInstances);
+        } else if (elementInstances && typeof elementInstances === 'object') {
+            // If array or object provided, convert to Map
+            if (Array.isArray(elementInstances)) {
+                for (const data of elementInstances) {
+                    const inst = instanceFromJSON(data);
+                    this.elementInstances.set(inst.id, inst);
+                }
+            }
+        }
+
+        // Migrate old diagramInstances array
+        if (Array.isArray(diagramInstances) && diagramInstances.length > 0) {
+            for (const inst of diagramInstances) {
+                const elInst = new ElementInstance(inst.elementId, inst.x, inst.y, inst.labelOverride);
+                this.elementInstances.set(elInst.id, elInst);
+            }
+        }
+
+        // Migrate old layout object (fallback if no instances yet)
+        if (layout && Object.keys(layout).length > 0 && this.elementInstances.size === 0) {
+            for (const [elementId, pos] of Object.entries(layout)) {
+                const inst = new ElementInstance(elementId, pos.x || 0, pos.y || 0);
+                this.elementInstances.set(inst.id, inst);
+            }
+        }
+
+        // Migrate old edgeLayout to relationship instances
+        if (relationshipInstances instanceof Map) {
+            this.relationshipInstances = new Map(relationshipInstances);
+        } else if (relationshipInstances && typeof relationshipInstances === 'object') {
+            if (Array.isArray(relationshipInstances)) {
+                for (const data of relationshipInstances) {
+                    const inst = RelationshipInstance.fromJSON(data);
+                    this.relationshipInstances.set(inst.id, inst);
+                }
+            }
+        }
+
+        // A view given its instances (an import, a copy) draws exactly those, even
+        // none; otherwise it draws its filter's elements and the lines between them.
+        if (elementInstances == null && this.elementInstances.size === 0) {
+            this._createDefaultElementInstances();
+        }
+        if (relationshipInstances == null && this.relationshipInstances.size === 0) {
+            this._createDefaultRelationshipInstances();
+        }
+
+        this._applyEdgeLayout(edgeLayout);
+    }
+
+    /**
+     * An imported `edgeLayout` ({relationshipId: {waypoints}}) gives a route to
+     * every instance of that relationship that has none of its own. An entry
+     * whose waypoints are absent means "straight", not "inherit".
+     * @private
+     */
+    _applyEdgeLayout(edgeLayout = {}) {
+        for (const [relationshipId, entry] of Object.entries(edgeLayout ?? {})) {
+            if (!entry || !('waypoints' in entry)) continue;
+            for (const inst of this.relationshipInstancesFor(relationshipId)) {
+                if (inst.waypoints === null) inst.waypoints = (entry.waypoints ?? []).map(wp => ({ x: wp.x, y: wp.y }));
+            }
+        }
+    }
+
+    /**
+     * Create default element instances for all elements in the view (on first creation).
+     * Uses layout if available, otherwise positions at 0,0.
+     * @private
+     */
+    _createDefaultElementInstances() {
+        const elements = this.model.elements();
+        const filtered = this.elementIds !== null ? elements.filter(el => this.elementIds.includes(el.id)) : elements;
+
+        for (const el of filtered) {
+            // Don't overwrite existing instances - they contain user modifications!
+            // Only create if no instances exist for this element
+            const existingInstances = Array.from(this.elementInstances.values())
+                .filter(inst => inst.elementId === el.id);
+            if (existingInstances.length > 0) {
+                continue; // Skip - instances already exist for this element
+            }
+
+            const layoutPos = (this.layout && this.layout[el.id]) || {};
+            const x = layoutPos.x !== undefined ? layoutPos.x : 0;
+            const y = layoutPos.y !== undefined ? layoutPos.y : 0;
+            const inst = new ElementInstance(el.id, x, y);
+            this.elementInstances.set(inst.id, inst);
+        }
+    }
+
+    /**
+     * Create default relationship instances for all relationships in the view (on first creation).
+     * Skips if view has no elements yet (new empty view) - relationships will be added via confirmation prompt.
+     * @private
+     */
+    _createDefaultRelationshipInstances() {
+        const relationships = this.model.relationships();
+        for (const rel of relationships) {
+            if (this.includesElement(rel.source) && this.includesElement(rel.target)) {
+                const inst = new RelationshipInstance(rel.id);
+                this.relationshipInstances.set(inst.id, inst);
+            }
+        }
+    }
+
+    // ==================== Instance Management ====================
+
+    /**
+     * Get element instance by ID.
+     * @param {string} instanceId - The stable diagram instance ID
+     * @returns {ElementInstance|undefined}
+     */
+    getElementInstance(instanceId) {
+        return this.elementInstances.get(instanceId);
+    }
+
+    /**
+     * Get relationship instance by ID.
+     * @param {string} instanceId - The stable diagram instance ID
+     * @returns {RelationshipInstance|undefined}
+     */
+    getRelationshipInstance(instanceId) {
+        return this.relationshipInstances.get(instanceId);
+    }
+
+    /**
+     * Add an element instance to this view.
+     * @param {ElementInstance} instance
+     */
+    addElementInstance(instance) {
+        if (!(instance instanceof ElementInstance)) {
+            throw new TypeError('Expected ElementInstance');
+        }
+        this.elementInstances.set(instance.id, instance);
+    }
+
+    /**
+     * Remove an element instance from this view.
+     * @param {string} instanceId
+     */
+    removeElementInstance(instanceId) {
+        this.elementInstances.delete(instanceId);
+    }
+
+    /**
+     * Add a relationship instance to this view.
+     * @param {RelationshipInstance} instance
+     */
+    addRelationshipInstance(instance) {
+        if (!(instance instanceof RelationshipInstance)) {
+            throw new TypeError('Expected RelationshipInstance');
+        }
+        this.relationshipInstances.set(instance.id, instance);
+    }
+
+    /**
+     * Remove a relationship instance from this view.
+     * @param {string} instanceId
+     */
+    removeRelationshipInstance(instanceId) {
+        this.relationshipInstances.delete(instanceId);
+    }
+
+    /**
+     * Get all instances of a specific model element in this view.
+     * @param {string} elementId - The model element ID
+     * @returns {ElementInstance[]}
+     */
+    elementInstancesFor(elementId) {
+        return Array.from(this.elementInstances.values())
+            .filter(inst => inst.elementId === elementId);
+    }
+
+    /**
+     * Get all instances of a specific relationship in this view.
+     * @param {string} relationshipId - The model relationship ID
+     * @returns {RelationshipInstance[]}
+     */
+    relationshipInstancesFor(relationshipId) {
+        return Array.from(this.relationshipInstances.values())
+            .filter(inst => inst.relationshipId === relationshipId);
+    }
+
+    /**
+     * Clear all element instances.
+     */
+    clearElementInstances() {
+        this.elementInstances.clear();
+    }
+
+    /**
+     * Clear all relationship instances.
+     */
+    clearRelationshipInstances() {
+        this.relationshipInstances.clear();
+    }
+
+    /** A view's title is its name (ViewSetModel works with titles). */
+    get title() { return this.name; }
+    set title(value) { this.name = value; }
+
+    /**
+     * An independent copy under a new id: every element and relationship
+     * instance is copied (new instance ids, relationships re-linked to the
+     * copied ends), with the element filter, viewpoint, documentation, view
+     * settings and folder layout.
+     * History starts empty.
+     */
+    copy(id, title) {
+        const { elementInstances, instanceIds } = copyViewInstances([...this.elementInstances.values()].map(i => ({ ...i.toJSON(), id: i.id })));
+        const relink = (instanceId) => instanceId == null ? null : (instanceIds.get(instanceId) ?? instanceId);
+        const relationshipInstances = new Map();
+        for (const inst of this.relationshipInstances.values()) {
+            const data = JSON.parse(JSON.stringify(inst.toJSON()));
+            const twin = RelationshipInstance.fromJSON({ ...data, sourceInstanceId: relink(data.sourceInstanceId), targetInstanceId: relink(data.targetInstanceId) });
+            if (twin.archi) delete twin.archi.id;
+            relationshipInstances.set(twin.id, twin);
+        }
+        const viewConnections = [...this.viewConnections.values()].map(c => {
+            const twin = ViewConnectionInstance.fromJSON({
+                ...JSON.parse(JSON.stringify(c.toJSON())),
+                id: `${c.id}-${id}`,
+                sourceInstanceId: relink(c.sourceInstanceId),
+                targetInstanceId: relink(c.targetInstanceId),
+            });
+            if (twin.archi) delete twin.archi.id;
+            return twin;
+        });
+        return new this.constructor(this.model, {
+            id,
+            name: title,
+            elementIds: this.elementIds ? [...this.elementIds] : null,
+            viewpoint: this.viewpoint,
+            viewpointMode: this.viewpointMode,
+            documentation: this.documentation,
+            settings: this._settings,
+            folderLayout: JSON.parse(JSON.stringify(this.folderLayout ?? {})),
+            elementInstances,
+            relationshipInstances,
+            viewConnections,
+            archiViewType: this.archiViewType,
+            properties: this.properties,
+            archiFolder: this.archiFolder,
+            archi: this.archi ? JSON.parse(JSON.stringify(this.archi)) : null,
+            arrangement: this.arrangement.copy(relink),   // the copy's instances have new ids
+        });
+    }
+
+    /** Element instances stack (relationships are drawn between them). */
+    layerItems() {
+        return Array.from(this.elementInstances.values());
+    }
+
+    /** True if this view includes the element (null elementIds = all). */
+    includesElement(id) {
+        if (!this.elementIds) return true;
+        return this.elementIds.includes(id);
+    }
+
+    /**
+     * Whether a line drawn between two items here is a relationship (both ends
+     * show model elements) or a plain line (a note, a canvas box or an image at
+     * either end), as in Archi.
+     */
+    linesAreRelationships(sourceId, targetId) {
+        const ends = [sourceId, targetId].map(id => this.getElementInstance(id));
+        return ends.every(inst => inst && !inst.content && this.model.getElement(inst.elementId));
+    }
+
+    /** A new plain line between two items, of this view's line class (not yet on the view). */
+    newLine(sourceId, targetId, { label = '' } = {}) {
+        const id = `line-${Date.now().toString(36)}-${ArchimateView._lines++}`;
+        return new ViewConnectionInstance({ id, sourceInstanceId: sourceId, targetInstanceId: targetId, label, archiType: this.constructor.LINE_TYPE });
+    }
+
+    /** Draw a plain line between two items: one undo step. @returns {ViewConnectionInstance} */
+    connect(sourceId, targetId, options = {}) {
+        const line = this.newLine(sourceId, targetId, options);
+        this.history.execute(new PlaceItemsCommand(this, { elementInstances: [], viewConnections: [line] }, { label: 'Connect' }));
+        return line;
+    }
+
+    /** Elements in this view, resolved from instances. Each instance is a fresh, independent projection. */
+    get elements() {
+        const result = [];
+
+        for (const instance of this.elementInstances.values()) {
+            // The element filter (null = all) applies to model elements, not view objects.
+            if (!instance.shownIn(this)) continue;
+            // A fresh copy each time: what the instance draws, placed for this view.
+            const viewElement = instance.project(this.model);
+            if (!viewElement) continue;
+            // Fixed in place (the view's arrangement): the renderer will not drag or resize it.
+            if (this.arrangement.isLocked(instance.id)) Object.assign(viewElement, { locked: true, resizable: false });
+            // In a group: the renderer drags its members with it.
+            const together = this.arrangement.movingWith(instance.id);
+            if (together.size > 1) viewElement.moveWith = [...together];
+            result.push(viewElement);
+        }
+
+        // Sort by zIndex so elements render in correct stacking order (lower zIndex first = background)
+        result.sort((a, b) => (a.zIndex || 0) - (b.zIndex || 0));
+
+        return result;
+    }
+
+    /** Relationships in this view, resolved from instances. Returns fresh copies to prevent mutations. */
+    get relationships() {
+        const result = [];
+
+        for (const instance of this.relationshipInstances.values()) {
+            const baseRel = this.model.getRelationship(instance.relationshipId);
+            if (!baseRel) {
+                continue;
+            }
+
+            // Skip if endpoints aren't in this view
+            if (!this.includesElement(baseRel.source) || !this.includesElement(baseRel.target)) {
+                continue;
+            }
+
+            const viewRel = { ...baseRel };
+            viewRel.id = instance.id;  // Use instance ID so rendering engine can track each relationship instance uniquely
+            viewRel.relationshipId = baseRel.id;  // Keep base relationship ID for reference
+
+            // Update source/target to use instance IDs
+            // If this relationship instance tracks specific source/target instances, use those
+            if (instance.sourceInstanceId && instance.targetInstanceId) {
+                viewRel.source = instance.sourceInstanceId;
+                viewRel.target = instance.targetInstanceId;
+            } else {
+                // Fallback: use first instance of each element (for backward compatibility)
+                const sourceInstances = this.elementInstancesFor(baseRel.source);
+                const targetInstances = this.elementInstancesFor(baseRel.target);
+                if (sourceInstances.length > 0) {
+                    viewRel.source = sourceInstances[0].id;
+                }
+                if (targetInstances.length > 0) {
+                    viewRel.target = targetInstances[0].id;
+                }
+            }
+
+            // This instance's own route wins; null inherits the model's. A deliberately
+            // straight line ([]) reads as no waypoints at all.
+            if (instance.waypoints) {
+                viewRel.waypoints = instance.waypoints.length ? instance.waypoints.map(wp => ({ ...wp })) : undefined;
+            } else {
+                viewRel.waypoints = baseRel.waypoints ? baseRel.waypoints.map(wp => ({ ...wp })) : [];
+            }
+            if (instance.sourceSide) viewRel.sourceSide = instance.sourceSide;
+            if (instance.targetSide) viewRel.targetSide = instance.targetSide;
+            // This view's line colour, in the renderer's name for it.
+            if (instance.appearance?.strokeColor) viewRel.color = instance.appearance.strokeColor;
+
+            viewRel.visible = instance.visible;
+            viewRel.diagramInstanceId = instance.id;
+            result.push(viewRel);
+        }
+
+        // Plain lines (no relationship behind them), drawn while both their boxes are.
+        for (const connection of this.viewConnections.values()) {
+            const edge = connection.project(this);
+            if (edge) result.push(edge);
+        }
+        return result;
+    }
+
+    /** Top-level folders in this view, with per-view folderLayout applied.
+     *  Returns fresh copies with bounds/state from folderLayout. */
+    get folders() {
+        const topLevel = this.model.folders();
+        return topLevel.map(folder => {
+            const viewFolder = { ...folder };
+            // Apply per-view folder layout (bounds, collapsed state, etc.)
+            const folderOverride = this.folderLayout[folder.id];
+            if (folderOverride) {
+                Object.assign(viewFolder, folderOverride);
+            }
+            return viewFolder;
+        });
+    }
+
+    /**
+     * The folders drawn on this view as groups: those with bounds in its
+     * `folderLayout`, bounds applied, each after its parent. `parentId` is the
+     * nearest ancestor that is also drawn here (a group inside an undrawn
+     * folder sits on the view itself).
+     */
+    get placedFolders() {
+        const placed = this.model.allFolders().filter(f => this.folderLayout[f.id]);
+        const drawn = new Set(placed.map(f => f.id));
+        return placed.map(folder => ({
+            ...folder,
+            ...this.folderLayout[folder.id],
+            parentId: this._nearestPlaced(folder.parentId, drawn),
+        }));
+    }
+
+    /** The group on this view an element is drawn in: its folder, or that folder's nearest drawn ancestor. */
+    placedFolderOf(elementId) {
+        const drawn = new Set(this.model.allFolders().filter(f => this.folderLayout[f.id]).map(f => f.id));
+        return this._nearestPlaced(this.model.getElementFolder(elementId), drawn);
+    }
+
+    /** @private */
+    _nearestPlaced(folderId, drawn) {
+        for (let id = folderId; id; id = this.model.getFolder(id)?.parentId) {
+            if (drawn.has(id)) return id;
+        }
+        return undefined;
+    }
+
+    // ===== Undoable edits (this view's history) =====
+
+    /**
+     * Everything needed to make this view's items again elsewhere: its boxes
+     * (with their ids), the lines and relationships drawn between them, their
+     * groups and locks, and the model elements and relationships they show (so
+     * another model can be given them); its documentation, properties and what
+     * Archi said besides. Plain JSON. A canvas template is this; so is what is
+     * copied to the clipboard.
+     * @param {Object} [options]
+     * @param {Iterable<string>} [options.itemIds] - Only these boxes (a selection): the lines
+     *   between them, and their groups and locks
+     */
+    toJSON({ itemIds = null } = {}) {
+        const copy = (value) => (value === undefined ? undefined : JSON.parse(JSON.stringify(value)));
+        const keep = itemIds ? new Set(itemIds) : null;
+        const kept = (id) => !keep || keep.has(id);
+        const boxes = [...this.elementInstances.values()].filter(i => kept(i.id));
+        // A line's ends: the boxes it names, or (none named) its elements' first boxes, as it is drawn.
+        const endsOf = (r) => {
+            const rel = this.model.getRelationship(r.relationshipId);
+            return [r.sourceInstanceId ?? this.elementInstancesFor(rel?.source)[0]?.id, r.targetInstanceId ?? this.elementInstancesFor(rel?.target)[0]?.id];
+        };
+        const lines = [...this.relationshipInstances.values()]
+            .map(r => ({ r, ends: endsOf(r) }))
+            .filter(({ ends: [from, to] }) => from && to && kept(from) && kept(to))
+            .map(({ r, ends: [from, to] }) => Object.assign(RelationshipInstance.fromJSON(r.toJSON()), { sourceInstanceId: from, targetInstanceId: to }));
+        const elementIds = new Set(boxes.map(b => b.elementId).filter(id => this.model.getElement(id)));
+        return {
+            name: this.name,
+            documentation: this.documentation,
+            properties: copy(this.properties),
+            archi: copy(this.archi ?? undefined),
+            elementInstances: boxes.map(i => ({ ...copy(i.toJSON()), id: i.id })),
+            viewConnections: [...this.viewConnections.values()]
+                .filter(c => kept(c.sourceInstanceId) && kept(c.targetInstanceId)).map(c => copy(c.toJSON())),
+            relationshipInstances: lines.map(r => copy(r.toJSON())),
+            elements: [...elementIds].map(id => copy(this.model.getElement(id))),
+            relationships: [...new Set(lines.map(r => r.relationshipId))].map(id => this.model.getRelationship(id)).filter(Boolean).map(copy),
+            arrangement: (keep ? this.arrangement.only(keep) : this.arrangement).toJSON(),
+        };
+    }
+
+    /**
+     * New boxes and lines like a view's JSON (toJSON): new ids, Archi's ids
+     * left with the source, each line and relationship joined to the copies of
+     * its ends.
+     * @param {Object} data
+     * @param {string} salt - Makes the lines' ids new
+     * @returns {{ elementInstances: Map, viewConnections: Array, relationshipInstances: Array, mapId: Function }}
+     */
+    static copyItems(data, salt) {
+        const { elementInstances, instanceIds } = copyViewInstances(data.elementInstances ?? []);
+        const mapId = (old) => instanceIds.get(old) ?? old;
+        const viewConnections = (data.viewConnections ?? []).map(c => {
+            const line = ViewConnectionInstance.fromJSON({ ...c, id: `${c.id}-${salt}`, sourceInstanceId: mapId(c.sourceInstanceId), targetInstanceId: mapId(c.targetInstanceId) });
+            if (line.archi) delete line.archi.id;
+            return line;
+        });
+        const relationshipInstances = (data.relationshipInstances ?? []).map(r => {
+            const line = RelationshipInstance.fromJSON({ ...r, sourceInstanceId: mapId(r.sourceInstanceId), targetInstanceId: mapId(r.targetInstanceId) });
+            if (line.archi) delete line.archi.id;
+            return line;
+        });
+        return { elementInstances, viewConnections, relationshipInstances, mapId };
+    }
+
+    /**
+     * Put copies of a view's items (toJSON of a selection, from this view or
+     * any other, of this model or another) on this view, moved by dx, dy: new
+     * boxes for the same elements, the lines and relationships between them;
+     * an element or relationship this model lacks is added with them. In front
+     * of what is there. The command is returned, not run.
+     * @param {Object} data
+     * @param {{dx?: number, dy?: number, label?: string}} [options]
+     * @returns {{ command: PlaceItemsCommand, ids: Array<string> }} the command, and the new boxes' ids
+     */
+    pasteCommand(data, { dx = 0, dy = 0, label = 'Paste' } = {}) {
+        const salt = `${this.id}-${Date.now().toString(36)}-${ArchimateView.placed++}`;
+        const { elementInstances, viewConnections, relationshipInstances } = ArchimateView.copyItems(data, salt);
+        const boxes = [...elementInstances.values()];
+        const move = (points) => points?.map(p => ({ x: p.x + dx, y: p.y + dy })) ?? points;
+        for (const b of boxes) { b.x += dx; b.y += dy; }
+        for (const line of viewConnections) line.waypoints = move(line.waypoints) ?? [];
+        for (const line of relationshipInstances) line.waypoints = move(line.waypoints) ?? null;
+        const elements = (data.elements ?? []).filter(e => !this.model.getElement(e.id));
+        const has = (id) => !!this.model.getElement(id) || elements.some(e => e.id === id);
+        const relationships = (data.relationships ?? []).filter(r => !this.model.getRelationship(r.id) && has(r.source) && has(r.target));
+        const known = (id) => !!this.model.getRelationship(id) || relationships.some(r => r.id === id);
+        const command = new PlaceItemsCommand(this, {
+            elementInstances: boxes, viewConnections, relationshipInstances: relationshipInstances.filter(r => known(r.relationshipId)),
+            elements, relationships,
+        }, { label });
+        return { command, ids: boxes.map(b => b.id) };
+    }
+
+
+    /**
+     * Add a box of one of this view's kinds (BOX_KINDS: a note or image here;
+     * a canvas's block, sticky or image) centred at `at`: one undo step, in
+     * front of what is there.
+     * @param {string} kindKey
+     * @param {{x: number, y: number}} at
+     * @param {{name?: string, iconUrl?: string}} [options] - Its text, its picture
+     * @returns {ViewObjectInstance}
+     */
+    addBox(kindKey, at, options = {}) {
+        const kind = this.constructor.BOX_KINDS.find(k => k.key === kindKey);
+        if (!kind) throw new TypeError(`No box kind "${kindKey}" on a ${this.constructor.kind} view`);
+        const id = `${kind.key}-${Date.now().toString(36)}-${ArchimateView.placed++}`;
+        const box = new ViewObjectInstance(kind.content(id, options), at.x, at.y);
+        box.size = { width: kind.width, height: kind.height };
+        box.appearance = { ...kind.appearance };
+        this.history.execute(new PlaceItemsCommand(this, { elementInstances: [box] }, { label: `Add ${kind.label}` }));
+        return box;
+    }
+
+
+    /**
+     * Put an instance on this view, creating its model element first when
+     * `element` is given. One undo step.
+     * @param {ElementInstance} instance
+     * @param {Object} [options]
+     * @param {Object} [options.element] - A new model element the instance shows
+     */
+    addToView(instance, { element = null } = {}) {
+        this.history.execute(new AddToViewCommand(this, instance, { element }));
+    }
+
+    /** Take an instance off this view (the model element stays). One undo step. */
+    deleteElement(instanceId) {
+        this.history.execute(new DeleteElementCommand(this, instanceId));
+    }
+
+    /**
+     * Relationship instances this view could show but does not: one per pairing
+     * of an instance of the element with an instance at the other end of each of
+     * its relationships, where both ends are in the view.
+     * @param {string} elementId - Model element id
+     * @returns {RelationshipInstance[]}
+     */
+    missingRelationshipInstances(elementId) {
+        const { incoming, outgoing } = this.model.relationshipsFor(elementId);
+        const shown = new Set([...this.relationshipInstances.values()].map(inst => this._pairing(inst)));
+        const missing = [];
+        for (const rel of [...incoming, ...outgoing]) {
+            if (!this.includesElement(rel.source) || !this.includesElement(rel.target)) continue;
+            for (const src of this.elementInstancesFor(rel.source)) {
+                for (const tgt of this.elementInstancesFor(rel.target)) {
+                    const inst = new RelationshipInstance(rel.id, null, src.id, tgt.id);
+                    if (!shown.has(this._pairing(inst))) {
+                        shown.add(this._pairing(inst));
+                        missing.push(inst);
+                    }
+                }
+            }
+        }
+        return missing;
+    }
+
+    /** "relationship|source instance|target instance" an instance draws between. @private */
+    _pairing(inst) {
+        const rel = this.model.getRelationship(inst.relationshipId);
+        const source = inst.sourceInstanceId ?? this.elementInstancesFor(rel?.source)[0]?.id;
+        const target = inst.targetInstanceId ?? this.elementInstancesFor(rel?.target)[0]?.id;
+        return `${inst.relationshipId}|${source}|${target}`;
+    }
+
+    /** Show these relationship instances, as one undo step. */
+    addRelationshipsToView(instances, label = 'Add Relationships to View') {
+        if (!instances.length) return;
+        this.history.execute(new CompositeCommand(label, instances.map(inst => new AddRelationshipToViewCommand(this, inst))));
+    }
+
+    /** Take a relationship instance, or a plain line, off this view (the model relationship stays). One undo step. */
+    removeRelationship(instanceId) {
+        if (this.viewConnections.has(instanceId)) this.history.execute(new RemoveLineCommand(this, instanceId));
+        else this.history.execute(new RemoveRelationshipFromViewCommand(this, instanceId));
+    }
+}