@peter.prib/renderengine 0.0.0-stage → 0.2.0

package/src/charting/ArchimateDiagramEditor.js

@@ -0,0 +1,1624 @@
+import { DiagramEditor } from './DiagramEditor.js';
+import { FilterSystem } from './FilterSystem.js';
+import { ElementInstance } from './diagrams/ElementInstance.js';
+import { ViewObjectInstance } from './diagrams/ViewObjectInstance.js';
+import { GraphDiagram } from './diagrams/GraphDiagram.js';
+import { NODE_SIZE_KEYS } from './diagrams/commands/index.js';
+import { RelationshipInstance } from './diagrams/RelationshipInstance.js';
+import { EditViewItemCommand, viewItemChanges, hasViewItemChanges } from './diagrams/EditViewItemCommand.js';
+import { arrangeMenuItems } from './arrangement/index.js';
+import { canvasBoxMenuItems } from './canvas/canvasBoxMenuItems.js';
+import { hintMenuItems } from './canvas/hintMenuItems.js';
+import { HintPanel } from './HintPanel.js';
+import { MenuBar } from './MenuBar.js';
+import { MODEL_ELEMENT_MIME } from './modelTree/ModelTreePanel.js';
+import { ViewMenu } from './ViewMenu.js';
+import { CanvasTemplateLibrary } from './canvas/CanvasTemplateLibrary.js';
+import { CanvasTemplateMenu } from './canvas/CanvasTemplateMenu.js';
+import { SettingsViewPropertiesDialog } from './SettingsViewPropertiesDialog.js';
+import { EditorShell } from '../workspace/EditorShell.js';
+import { SPECIALIZATIONS_STORE } from '../archimateSpecializations.js';
+import { FormDialog } from './FormDialog.js';
+import { ToolbarMenu, ToolbarSeparator, ToolbarText } from './toolbar/index.js';
+import { ArchimateViewpoints } from '../archimate.js';
+import { modelFileMenuItems } from './ModelFileFormat.js';
+import { elementMenuItems } from './archimate/elementMenuItems.js';
+import { editElementProperties } from './archimate/elementProperties.js';
+import { ShowElementCommand } from './diagrams/ShowElementCommand.js';
+import { specializationCatalogDialog } from './archimate/specializationCatalogDialog.js';
+import { CustomViewpoints } from './archimate/CustomViewpoints.js';
+import { ARCHIMATE_FILE_FORMATS } from './archimate/archimateFileFormats.js';
+import { ArchiFileFormat } from './archimate/ArchiFileFormat.js';
+import { ExchangeFileFormat } from './archimate/ExchangeFileFormat.js';
+import { ArchimateCsvFileFormat } from './archimate/ArchimateCsvFileFormat.js';
+
+/**
+ * ArchimateDiagramEditor — ArchiMate-specific diagram editor extending DiagramEditor base.
+ *
+ * Encapsulates: ArchiMate model, tree navigator, diagram tabs, rendering, controls wiring.
+ * Inherits: common rendering, drag/drop, toolbar, tree, filtering from DiagramEditor.
+ * Delegates: filtering to FilterSystem, tree rendering to ModelTree/TreeBuilder.
+ * Separates concerns: common logic (base class) from ArchiMate-specific logic (this class).
+ */
+/** Specializations, kept per browser. */
+
+/** dataTransfer type a tree element carries while dragged onto the diagram. */
+
+export class ArchimateDiagramEditor extends DiagramEditor {
+    constructor(options = {}) {
+        const {
+            elements = [],
+            relationships = [],
+            views = [],
+            document,
+            appContainerId = 'app',
+            treeContainerId = 'tree',
+            diagramContainerId = 'diagram',
+            analysisContainerId,
+            toolbarContainerId = 'toolbar',
+            features = null,
+            workspace,
+            settingsManager = null,
+            fullPage = true,
+            model = null,
+            templateLibrary = undefined,
+            fileFormats = ARCHIMATE_FILE_FORMATS,
+        } = options;
+
+        super({
+            diagramContainerId,
+            // GraphDiagram (via RenderEngine.archimateDiagram) owns zoom, pan and canvas clicks.
+            enableCanvasInteractions: false,
+        });
+        this.document = document;
+        this.appContainerId = appContainerId;
+        this.treeContainerId = treeContainerId;
+        this.analysisContainerId = analysisContainerId;
+        this.toolbarContainerId = toolbarContainerId;
+        /** Fill the viewport (a page of its own) or the app container (e.g. inside a workbench part). */
+        this.fullPage = fullPage;
+        this.features = features;
+        this.workspace = workspace;
+        this.settingsManager = settingsManager || (workspace?.SettingsManager ? new workspace.SettingsManager() : null);
+        /**
+         * Canvas templates kept across models (a CanvasTemplateLibrary): by default
+         * this browser's; pass another, or null for none.
+         */
+        this.templateLibrary = templateLibrary === undefined ? new CanvasTemplateLibrary() : templateLibrary;
+        /** The file formats the File menu exports and imports (ModelFileFormat), each on when its features flags are. */
+        this.fileFormats = fileFormats;
+
+        // Initialize dependencies with defaults (can be overridden via setDependencies)
+        this.setDependencies();
+
+        // Inject styles (generated by class, not hardcoded in HTML)
+        this._injectStyles();
+
+        // Create DOM structure if not already present
+        this._createStructure();
+
+        // Initialize toolbar if features are specified
+        if (this.features) {
+            this._initializeToolbar();
+        }
+
+        // Core model state
+        this.model = null;
+        this.currentEngine = null;
+        // A host (e.g. ArchimateEditorPart) may hand in the model; otherwise it is built from the data.
+        this._bindModel(model ?? new workspace.ArchimateModel({ elements, relationships, views }));
+        this.renderFunction = null;
+
+        // Filtering system (owns all filter UI and logic)
+        this.filterSystem = new FilterSystem({
+            doc: document,
+            model: this.model,
+            onFilterChange: (result) => this._onFilterChange(result),
+        });
+
+        // Specialize registry (load/save with localStorage)
+        this._initializeSpecializations();
+
+        // Tab/diagram system
+        this._initializeDiagrams();
+
+        // Tree panel rendering
+        this._renderTreePanel();
+
+        // Tab initialization
+        this._initializeTabs();
+
+        // Set render function for tabs to call
+        if (this.diagrams) {
+            this.diagrams.setRenderFunction(() => this.render());
+        }
+
+        // The tree lists the library's templates.
+        this._unsubscribeLibrary = this.templateLibrary?.onChange(() => {
+            if (this.document?.getElementById(this.treeContainerId)) this._renderTreePanel();
+        });
+
+        // Enable tree drag-drop (delayed to allow DOM to be ready)
+        setTimeout(() => this.enableTreeDragDrop(), 100);
+
+        // Wire controls if not using auto-toolbar
+        if (!this.features) {
+            this.wireControls();
+        }
+    }
+
+    /**
+     * Undo history of the view being shown: each ArchimateView keeps its own,
+     * so the base's undo/redo shortcuts and commands follow the current tab.
+     */
+    get history() {
+        return this.currentView?.history ?? null;
+    }
+
+    set history(_history) {
+        throw new TypeError('ArchimateDiagramEditor history is the model\'s (currentView.history)');
+    }
+
+    /** Groups and locks are per view too: the current view's arrangement. */
+    get arrangement() {
+        return this.currentView?.arrangement ?? this._arrangement;
+    }
+
+    set arrangement(arrangement) {
+        this._arrangement = arrangement;
+    }
+
+    /** Group / Ungroup / Lock / Unlock for a drawn item (arrangeMenuItems), on the current view. */
+    nodeArrangeMenuItems(itemId) {
+        const view = this.currentView;
+        if (!view?.getElementInstance(itemId)) return [];
+        const after = (fn) => (...args) => { fn(...args); this.render(); };
+        return arrangeMenuItems(view.arrangement, [itemId], {
+            ungroup: after((id) => view.ungroup(id)),
+            setLocked: after((ids, locked) => view.setLocked(ids, locked)),
+        });
+    }
+
+    /** The graph engine's drawing. */
+    drawingHost() {
+        return this.currentEngine?.container ?? null;
+    }
+
+    /** The graph engine draws without the base's grid and handles: nothing to hide. @protected */
+    _withPlainDrawing(fn) {
+        return fn();
+    }
+
+    /** Zoom and pan the graph engine's view so everything drawn is in sight. @returns {boolean} whether it zoomed */
+    zoomToFit({ margin = 20 } = {}) {
+        const engine = this.currentEngine;
+        const svg = engine?.renderer?.svg;
+        if (!engine?._svgZoom || !svg) return false;
+        const rects = [...svg.querySelectorAll('[nodeId], [edgeId]')].map(n => n.getBoundingClientRect()).filter(r => r.width || r.height);
+        if (!rects.length) {
+            engine._svgZoom.reset();
+            return false;
+        }
+        // Screen corners to drawing coordinates.
+        const topLeft = engine._clientToSvgPoint(Math.min(...rects.map(r => r.left)), Math.min(...rects.map(r => r.top)));
+        const bottomRight = engine._clientToSvgPoint(Math.max(...rects.map(r => r.right)), Math.max(...rects.map(r => r.bottom)));
+        engine._svgZoom.fit({ x: topLeft.x, y: topLeft.y, width: bottomRight.x - topLeft.x, height: bottomRight.y - topLeft.y }, { margin });
+        return true;
+    }
+
+    /** The notation version the checks use. */
+    checkerOptions() {
+        return { version: this.getOption('archimate-version', '4') };
+    }
+
+    /** A view opens in its tab; an element or relationship is shown in the tree. */
+    revealFinding(finding) {
+        const [id] = finding.ids;
+        if (finding.kind === 'view') {
+            const view = this.model.getView(id);
+            if (view) this._showView(view);
+        } else {
+            this.tree.select(id, finding.kind);
+        }
+    }
+
+    /** Back to the zoom the view was drawn at. */
+    resetZoom() {
+        this.currentEngine?._svgZoom?.reset();
+    }
+
+    /**
+     * What right-clicking empty space on a view offers: on a canvas, Archi's
+     * canvas palette (canvasBoxMenuItems) and Place template; on an ArchiMate
+     * view, a new element, note or image. Then the view's properties.
+     * @param {ArchimateView} view
+     */
+    canvasContextMenuItemsFor(view) {
+        const viewProperties = { label: 'View Properties…', action: () => this.deps.showViewPropertiesDialog(this.currentView, () => this.render()) };
+        if (view?.constructor.kind === 'canvas') {
+            return [
+                ...canvasBoxMenuItems(view, { x: 0, y: 0 }).map((item, i) => ({
+                    label: item.label,
+                    // At the point clicked: the items are made again there.
+                    action: (point) => canvasBoxMenuItems(view, point, { onAdded: () => this.render(), document: this.document })[i].action(),
+                })),
+                { label: 'Place template', items: (point) => this.templateMenu.placeTemplateItems(view.id, point) },
+                ...hintMenuItems(view, null, { onChange: () => this.render(), document: this.document }),
+                viewProperties,
+            ];
+        }
+        return [
+            { label: 'Add ArchiMate Element…', action: (point, engine) => this.deps.showAddArchimateElementDialog(engine, point, this.currentView, this.model) },
+            { label: 'Add Note…', action: (point, engine) => this.deps.showAddNoteDialog(engine, point, this.currentView, this.model) },
+            { label: 'Add Image…', action: (point, engine) => this.deps.showAddImageDialog(engine, point) },
+            viewProperties,
+        ];
+    }
+
+    /**
+     * Show the hint for an item on a canvas (its own, else the canvas's) in the
+     * hint panel; none for other views. Called on every render and when a box
+     * is clicked.
+     * @param {string|null} [itemId]
+     */
+    showHintFor(itemId = null) {
+        const view = this.currentView;
+        const container = this.document?.getElementById(this.diagramContainerId);
+        if (!container) return;
+        this.hintPanel ??= new HintPanel({ document: this.document });
+        const hint = view?.constructor.kind === 'canvas' ? (itemId ? view.hintFor(itemId) : view.hint) : null;
+        this.hintPanel.mount(container).show(hint);
+    }
+
+    /** Undo, and bring the model tree in line (an undone edit may rename an element). */
+    undo() {
+        const undone = super.undo();
+        if (undone) this._renderTreePanel();
+        return undone;
+    }
+
+    /** Redo, and bring the model tree in line. */
+    redo() {
+        const redone = super.redo();
+        if (redone) this._renderTreePanel();
+        return redone;
+    }
+
+    /**
+     * Edit this model: a model tree and view menu over it, and follow its
+     * changes (views created, duplicated, renamed, deleted or switched,
+     * whether from a tab, the tree or code). Used at construction and when
+     * an import replaces the model.
+     * @private
+     */
+    _bindModel(model) {
+        this._unsubscribeModel?.();
+        this.model = model;
+        this.viewMenu = new ViewMenu(model, {
+            document: () => this.document,
+            noun: 'view',
+            editProperties: (view) => this.showViewProperties(view),
+        });
+        this.templateMenu = new CanvasTemplateMenu(model, {
+            library: this.templateLibrary,
+            document: () => this.document,
+        });
+        this.tree = new this.workspace.ModelTree(model, { mode: 'byLayer' });
+        this.currentView = model.currentView ?? this.tree.getSelectedView();
+        this._wireTreeSelection();
+        this._unsubscribeModel = model.onChange(() => this._onModelChange());
+    }
+
+    /** Open a view's properties: name, documentation and its own settings (routing, grid, background). */
+    showViewProperties(view = this.currentView) {
+        if (!view) return null;
+        return new SettingsViewPropertiesDialog({
+            model: this.model, view, settingsManager: this.settingsManager, modelId: 'default', document: this.document,
+        }).open();
+    }
+
+    /** Run `fn` without reacting to the model changes it makes (the editor made them itself). @private */
+    _quietly(fn) {
+        this._quiet = true;
+        try { return fn(); } finally { this._quiet = false; }
+    }
+
+    /**
+     * Bring the tabs, the tree and the canvas in line with the model: close
+     * the tabs of deleted views and show the current view (opening its tab).
+     * @private
+     */
+    _onModelChange() {
+        if (this._quiet || !this.diagrams) return;
+        for (const id of this.diagrams.openViewIds()) {
+            if (!this.model.getView(id)) this._quietly(() => this.diagrams.closeTab(id));
+        }
+        this._renderTreePanel();
+        // Showing the current view also redraws the tab bar, so renamed tabs follow.
+        const view = this.model.currentView;
+        if (view) this._showView(view);
+    }
+
+    /** Open (or focus) a view's tab and select it in the tree, which makes it current. @private */
+    _showView(view) {
+        this.diagrams.show(view, () => this.tree.select(view.id, 'view'));
+        this.tree.select(view.id, 'view');
+    }
+
+    /** Restack an element instance on the current view: one undo step on the view's history. */
+    executeOrderCommand(instanceId, operation) {
+        const method = { front: 'bringToFront', back: 'sendToBack', raise: 'raise', lower: 'lower' }[operation];
+        if (!method || !this.currentView?.getElementInstance(instanceId)) return;
+        this.currentView[method](instanceId);
+        this.render();
+    }
+
+    /** The current tab's engine SVG, for the base's coordinate helpers. @protected */
+    _canvasSvg() {
+        return this.currentEngine?.renderer?.svg ?? null;
+    }
+
+    /**
+     * Lay out the app in the shared workbench EditorShell (toolbar, tree,
+     * diagram, optional analysis panel) — only when the host gave an app
+     * container and no diagram container of its own.
+     */
+    _createStructure() {
+        const appEl = this.document.getElementById(this.appContainerId);
+        if (!appEl || this.document.getElementById(this.diagramContainerId)) return;
+        new EditorShell({
+            document: this.document,
+            fullPage: this.fullPage,
+            aside: !!this.analysisContainerId,
+            ids: { toolbar: this.toolbarContainerId, side: this.treeContainerId, main: this.diagramContainerId, aside: this.analysisContainerId },
+        }).mount(appEl);
+    }
+    /**
+     * Tree and filter styling, scoped to this editor's own containers: hosts
+     * (e.g. a gallery page with other diagrams) are left untouched.
+     */
+    _injectStyles() {
+        const styleId = `archimate-editor-styles-${this.treeContainerId}-${this.diagramContainerId}`;
+        if (this.document.getElementById(styleId)) return;
+        const tree = `#${CSS.escape(this.treeContainerId)}`;
+        const diagram = `#${CSS.escape(this.diagramContainerId)}`;
+        const style = this.document.createElement('style');
+        style.id = styleId;
+        style.textContent = `
+            ${tree} .archimate-tree-node { padding: 4px 8px; cursor: pointer; user-select: none; }
+            ${tree} .archimate-tree-node:hover { background: #e8e8e8; }
+            ${tree} .archimate-tree-node.selected { background: #5470c6; color: white; }
+            ${tree} .filter-hidden { display: none; }
+            ${tree}.tree-filtered::before {
+                content: "🔍 filtered"; display: block; padding: 4px 8px; background: #fff3cd;
+                border-bottom: 1px solid #ffc107; font-size: 12px; color: #856404; font-weight: bold;
+            }
+            ${diagram} svg [nodeId]:not(.filter-highlight) { opacity: 0.3; }
+            /* ModelTree's own filter button: this editor has its own above the tree. */
+            ${tree} > div > div:first-child button { display: none !important; }
+        `;
+        this.document.head.appendChild(style);
+    }
+    /**
+     * The toolbar: the shared MenuBar, rendering the items from menuBarItems().
+     */
+    _initializeToolbar() {
+        const container = this.document.getElementById(this.toolbarContainerId);
+        if (!container) return;
+        this.menuBar = new MenuBar({ container, items: this.menuBarItems(), editor: this, document: this.document }).render();
+        if (this.features?.search) this._initializeTreeFilter();
+    }
+
+    /**
+     * ArchiMate's toolbar items, each gated by its `features` flag. Option
+     * values live in the editor (getOption/setOption) and re-render on change.
+     * @returns {Array<ToolbarItem>}
+     */
+    menuBarItems() {
+        const f = this.features || {};
+        const value = (key, fallback) => () => this.getOption(key, fallback);
+        const update = (key) => (v) => { this.setOption(key, v); this.render(); };
+        const items = [
+            new ToolbarText(() => '🏛️ ArchiMate', { fontWeight: 'bold', color: '#333', fontSize: '13px' }),
+            new ToolbarSeparator(),
+        ];
+
+        // Read when the menu opens: the current view and the model (an import replaces it) change.
+        const viewItems = () => {
+            const saveAs = this.currentView ? this.templateMenu.saveAsTemplateItems(this.currentView.id) : [];
+            const importTemplate = this.templateMenu.importItem();
+            return [
+                this.viewMenu.newViewItem(),
+                ...this.templateMenu.newCanvasItems(),
+                ...(this.currentView ? [{ separator: true }, ...this.viewMenu.items(this.currentView.id)] : []),
+                ...(saveAs.length || importTemplate ? [{ separator: true }, ...saveAs, ...(importTemplate ? [importTemplate] : [])] : []),
+            ];
+        };
+        // Export and import, one group per file format its features flags switch on.
+        const file = modelFileMenuItems(this.fileFormats, {
+            model: () => this.model,
+            onImport: (model) => this.replaceModel(model),
+            enabled: (format, direction) => !!f[direction + format.featureName],
+            document: () => this.document,
+        });
+        // The current view as a picture (on unless features.exportImage is false).
+        const image = f.exportImage === false ? [] : this.imageMenuItems();
+        items.push(new ToolbarMenu('File', () => [
+            ...viewItems(),
+            ...(file.length ? [{ separator: true }, ...file] : []),
+            ...(image.length ? [{ separator: true }, ...image] : []),
+        ]));
+        items.push(new ToolbarMenu('View', () => this.viewMenuItems()));
+        // Model and notation settings live under the cog, as in the template editor.
+        items.push(new ToolbarMenu('⚙ Settings', () => this.settingsMenuItems()));
+        return items;
+    }
+
+    /**
+     * The ⚙ Settings menu: the notation (version, viewpoint and its mode,
+     * distinct shapes, derived relationships), each gated by `features`, then
+     * the model settings dialog (routing, grid, watermark).
+     */
+    settingsMenuItems() {
+        const f = this.features || {};
+        const set = (key, v) => { this.setOption(key, v); this.render(); };
+        /** A submenu of choices with the current one ticked. */
+        const choose = (label, key, fallback, choices) => {
+            const current = this.getOption(key, fallback);
+            const shown = choices.find(([v]) => v === current)?.[1] ?? current;
+            return { label: `${label}: ${shown}`, items: choices.map(([v, text]) => ({ label: text, checked: v === current, action: () => set(key, v) })) };
+        };
+        const toggle = (label, key) => {
+            const on = !!this.getOption(key, false);
+            return { label: `${label}: ${on ? 'on' : 'off'}`, action: () => set(key, !on) };
+        };
+        const notation = [
+            f.version && choose('Version', 'archimate-version', '4', [['4', 'ArchiMate 4'], ['3.2', 'ArchiMate 3.2']]),
+            f.viewpoint && choose('Viewpoint', 'archimate-viewpoint', 'All',
+                ArchimateViewpoints.all(this.deps?.customViewpoints ?? []).map(vp => [vp.name, vp.name])),
+            f.viewpoint && choose('Viewpoint mode', 'archimate-viewpoint-mode', 'fade', [['fade', 'Fade'], ['hide', 'Hide']]),
+            f.distinctShapes && toggle('Distinct shapes', 'archimate-distinct-shapes'),
+            f.showDerived && toggle('Show derived', 'archimate-show-derived'),
+        ].filter(Boolean);
+        // The catalogs a user keeps: shared with the canvas editor, saved in this browser.
+        const catalogs = [
+            { label: 'Specializations…', action: () => specializationCatalogDialog({ version: this.getOption('archimate-version', '4'), document: this.document, onChange: () => this.render() }).open() },
+            f.viewpoint && { label: 'Viewpoints…', action: () => CustomViewpoints.dialog({ version: this.getOption('archimate-version', '4'), document: this.document, onChange: (viewpoints) => { this.deps.customViewpoints = viewpoints; this.render(); } }).open() },
+        ].filter(Boolean);
+        return [
+            ...notation,
+            ...(notation.length ? [{ separator: true }] : []),
+            ...catalogs,
+            { separator: true },
+            { label: 'Model settings…', action: () => this.showModelSettings() },
+        ];
+    }
+
+    /** Open the model settings dialog (grid, routing, watermark, …). */
+    showModelSettings() {
+        if (!this.settingsManager || !this.workspace?.showGlobalSettingsDialog) {
+            console.warn('Cannot open settings - missing settingsManager or showGlobalSettingsDialog');
+            return;
+        }
+        this.workspace.showGlobalSettingsDialog(this.document, this.settingsManager, 'default');
+    }
+
+    /** The file format of class `Format` among this editor's (or a new one). @private */
+    _format(Format) {
+        return this.fileFormats.find(f => f instanceof Format) ?? new Format();
+    }
+
+    /** Import the combined CSV that exportCSV() writes (elements, then relationships), replacing the model. */
+    importCSVText(text) {
+        this.replaceModel(this._format(ArchimateCsvFileFormat).import(text));
+    }
+
+    /** Filter box and options above the model tree. */
+    _initializeTreeFilter() {
+        setTimeout(() => {
+            const treeEl = this.document.getElementById(this.treeContainerId);
+            if (treeEl && !this.document.getElementById('tree-controls-wrapper')) {
+                const controlsWrapper = this.document.createElement('div');
+                controlsWrapper.id = 'tree-controls-wrapper';
+                controlsWrapper.style.cssText = 'padding:8px;background:#f5f5f5;border-bottom:1px solid #ddd;display:flex;gap:6px;align-items:center;position:relative;';
+
+                // Filter input (from FilterSystem)
+                const filterInput = this.document.createElement('input');
+                filterInput.id = 'tree-filter-input';
+                filterInput.type = 'text';
+                filterInput.placeholder = '🔍 Filter';
+                filterInput.title = 'Filter elements and tree';
+                filterInput.style.cssText = 'padding:6px 12px;border:1px solid #ccc;border-radius:3px;flex:1;font-size:13px;';
+                filterInput.addEventListener('input', () => {
+                    this.filterSystem.setPattern(filterInput.value);
+                });
+
+                // Settings button
+                const settingsBtn = this.document.createElement('button');
+                settingsBtn.id = 'tree-settings-btn';
+                settingsBtn.type = 'button';
+                settingsBtn.textContent = '⚙️';
+                settingsBtn.title = 'Filter options';
+                settingsBtn.style.cssText = 'padding:6px 12px;border:1px solid #ccc;border-radius:3px;background:white;cursor:pointer;font-size:13px;';
+                settingsBtn.addEventListener('click', (e) => {
+                    e.stopPropagation();
+                    this.filterSystem.togglePopup();
+                });
+
+                // Popup from FilterSystem
+                const popup = this.filterSystem.createPopupUI();
+
+                // Close document click handler
+                this.document.addEventListener('click', () => {
+                    this.filterSystem.togglePopup(false);
+                });
+                popup.addEventListener('click', (e) => {
+                    e.stopPropagation();
+                });
+
+                // Assemble and insert
+                controlsWrapper.appendChild(filterInput);
+                controlsWrapper.appendChild(settingsBtn);
+                controlsWrapper.appendChild(popup);
+                treeEl.insertBefore(controlsWrapper, treeEl.firstChild);
+            }
+        }, 100);
+    }
+
+    _initializeSpecializations() {
+        this.workspace.RenderEngine.ArchimateSpecializationRegistry.loadFrom(SPECIALIZATIONS_STORE);
+    }
+    _initializeDiagrams() {
+        const containerEl = this.document.getElementById(this.diagramContainerId);
+        this.diagrams = new this.workspace.DiagramTabs(this.document, {
+            RenderEngine: this.workspace.RenderEngine,
+            settingsManager: this.settingsManager,
+            menuItems: (viewId) => this.viewMenu.items(viewId),
+        });
+        const tabsEl = this.diagrams.build();
+        containerEl.appendChild(tabsEl);
+    }
+
+    _wireTreeSelection() {
+        this.tree.onSelectionChange((data) => {
+            if (data.kind === 'view') {
+                if (!this.diagrams.hasTab(data.view.id)) {
+                    this.diagrams.show(data.view, () => {
+                        this.tree.select(data.view.id, 'view');
+                    });
+                    this.diagrams.switchTo(data.view);
+                } else {
+                    this.diagrams.switchTo(data.view);
+                }
+                this.currentEngine = this.diagrams.getActiveEngine();
+                this.currentView = data.view;
+                this._quietly(() => this.model.switchTo(data.view.id));
+                this.render();
+            } else if (data.kind === 'element') {
+                this._highlightElement(data.id);
+                this._renderAnalysisPanel(data.id);
+            } else if (data.kind === 'relationship') {
+                this._highlightElement(data.id, 'relationship');
+                this._clearAnalysisPanel();
+            } else {
+                // Deselection (e.g., clicking on empty canvas)
+                // Clear visual selection but keep filter state intact
+                this._clearDiagramSelection();
+                this._clearAnalysisPanel();
+            }
+        });
+    }
+
+    _renderTreePanel() {
+        const treeEl = this.document.getElementById(this.treeContainerId);
+        const treePanel = this.workspace.buildModelTreePanel(this.document, {
+            modelTree: this.tree,
+            treeDivId: `${this.treeContainerId}-content`,
+            viewMenu: this.viewMenu,
+            templateMenu: this.templateMenu,
+            elementMenu: (element) => elementMenuItems(element, {
+                model: this.model, view: this.currentView,
+                editProperties: (el) => editElementProperties(el, {
+                    history: this.currentView?.history, version: this.getOption('archimate-version', '4'), document: this.document,
+                    onSaved: () => { this.render(); this._renderTreePanel(); },
+                }),
+                showIn: (view, instanceId) => {
+                    if (view.id !== this.model.currentViewId) this.model.switchTo(view.id);
+                    this._highlightElement(instanceId);
+                },
+                addToView: (el) => {
+                    const at = this._snapToGrid(this.visibleCentre());
+                    this.currentView.history.execute(new ShowElementCommand(this.currentView, new ElementInstance(el.id, at.x, at.y)));
+                    this.render();
+                },
+            }),
+        });
+        treeEl.innerHTML = '';
+        treeEl.appendChild(treePanel);
+    }
+
+    _initializeTabs() {
+        const views = this.model.views();
+        for (const view of views) {
+            this.diagrams.show(view, () => {
+                this.tree.select(view.id, 'view');
+            });
+        }
+        this.currentEngine = this.diagrams.getActiveEngine();
+    }
+
+    _highlightElement(id, kind = 'element') {
+        this._clearDiagramSelection();
+        if (!this.currentEngine?.renderer?.svg) return;
+
+        if (kind === 'element') {
+            const el = this.currentEngine.renderer.svg.querySelector(`[nodeId="${CSS.escape(id)}"]`);
+            if (el) {
+                el.classList.add('selected');
+                el.scrollIntoView({ behavior: 'smooth', block: 'nearest', inline: 'nearest' });
+            }
+        } else if (kind === 'relationship') {
+            const edgeEl = this.currentEngine.renderer.svg.querySelector(`[edgeId="${CSS.escape(id)}"]`);
+            if (edgeEl) {
+                edgeEl.classList.add('selected-edge');
+                edgeEl.scrollIntoView({ behavior: 'smooth', block: 'nearest', inline: 'nearest' });
+            }
+        }
+    }
+
+    _clearDiagramSelection() {
+        this.currentEngine?.renderer?.svg?.querySelectorAll?.('.selected, .selected-edge')?.forEach(el => {
+            el.classList.remove('selected', 'selected-edge');
+        });
+    }
+
+    _renderAnalysisPanel(elementId) {
+        const analysisEl = this.document.getElementById(this.analysisContainerId);
+        if (!analysisEl) return;
+
+        const panel = this.workspace.buildAnalysisPanel(this.document, {
+            model: this.model,
+            elementId,
+            onSelectItem: (info) => this.tree.select(info.id, info.kind),
+        });
+        analysisEl.innerHTML = '';
+        analysisEl.appendChild(panel);
+    }
+
+    _clearAnalysisPanel() {
+        const analysisEl = this.document.getElementById(this.analysisContainerId);
+        if (analysisEl) analysisEl.innerHTML = '';
+    }
+
+    /**
+     * Set dependencies: dialog functions and other callbacks.
+     * Optional—uses bundled workspace dialogs by default.
+     */
+    setDependencies(deps = {}) {
+        this.deps = {
+            showPropertiesDialog: deps.showPropertiesDialog || this._defaultShowPropertiesDialog.bind(this),
+            showAddArchimateElementDialog: deps.showAddArchimateElementDialog || this._defaultShowAddArchimateElementDialog.bind(this),
+            showAddNoteDialog: deps.showAddNoteDialog || this._defaultShowAddNoteDialog.bind(this),
+            showAddImageDialog: deps.showAddImageDialog || this._defaultShowAddImageDialog.bind(this),
+            showViewPropertiesDialog: deps.showViewPropertiesDialog || this._defaultShowViewPropertiesDialog.bind(this),
+            showPickRelationshipKindDialog: deps.showPickRelationshipKindDialog || this._defaultShowPickRelationshipKindDialog.bind(this),
+            showDiagramPropertiesDialog: deps.showDiagramPropertiesDialog || this._defaultShowDiagramPropertiesDialog.bind(this),
+            customViewpoints: deps.customViewpoints || CustomViewpoints.load(),
+        };
+    }
+
+    _defaultShowPickRelationshipKindDialog(engine, edge) {
+        try {
+            const ArchimateValidator = engine.constructor.ArchimateValidator;
+            const archimateVersion = engine._archimateOptions?.archimateVersion || '4';
+            const nodes = engine._chartState?.nodes ?? [];
+            const sourceNode = nodes.find(n => n.id === edge.source) || { id: edge.source };
+            const targetNode = nodes.find(n => n.id === edge.target) || { id: edge.target };
+            const allowed = ArchimateValidator
+                ? ArchimateValidator.allowedKinds(sourceNode, targetNode, archimateVersion)
+                : ['composition', 'aggregation', 'assignment', 'realization', 'serving', 'access', 'influence', 'triggering', 'flow', 'specialization', 'association'];
+            const kinds = allowed.includes('association') ? allowed : [...allowed, 'association'];
+            new FormDialog({
+                title: `New relationship: ${edge.source} → ${edge.target}`,
+                description: `${sourceNode.type || 'unknown'} → ${targetNode.type || 'unknown'}: ${kinds.length} allowed kind${kinds.length === 1 ? '' : 's'}`,
+                fields: [{ key: 'kind', label: 'Kind', type: 'select', choices: kinds.map(k => [k, k]), value: kinds[0] }],
+                submitLabel: 'Set',
+                cancelLabel: 'Leave as association',
+                idPrefix: 'archimate-relationship-',
+                document: this.document,
+                onApply: ({ kind }) => {
+                    Object.assign(edge, engine._archimateBuildEdge({ ...edge, kind }));
+                    const relationship = this.model.getRelationship(edge.relationshipId);
+                    if (relationship) relationship.kind = kind;
+                    engine._rerenderGraph();
+                    setTimeout(() => this._applyFilterHighlighting(), 0);
+                },
+            }).open();
+        } catch (err) {
+            console.error('showPickRelationshipKindDialog failed:', err);
+        }
+    }
+
+    _defaultShowPropertiesDialog(subject, engine, kind, options) {
+        // Delegate to workspace's bundled properties dialog
+        const bundledDialog = this.workspace?.showPropertiesDialog;
+        if (bundledDialog) {
+            return bundledDialog(subject, engine, kind, { document: this.document, ...options });
+        }
+    }
+
+    /**
+     * Open the properties of a drawn element, note or line, and keep what is
+     * changed: the concept's fields in the model (or a note's or plain line's
+     * own), and fill, line and text colour, font, text size and label on this
+     * view. One undo step on the view.
+     * @param {Object} item - The drawn node or edge
+     * @param {'node'|'edge'} kind
+     * @param {RenderEngine} [engine]
+     */
+    editItemProperties(item, kind, engine = this.currentEngine) {
+        if (kind === 'node' && this.isFixed(item.id)) return this.tellLocked(`"${item.name || 'This'}"`, item.id);
+        // The dialog calls an element's documentation its description.
+        if (kind === 'node' && item.description === undefined && item.documentation !== undefined) item.description = item.documentation;
+        const before = JSON.parse(JSON.stringify(item));
+        return this.deps.showPropertiesDialog(item, engine, kind, {
+            onSave: () => this.saveItemEdit(item, kind, before),
+        });
+    }
+
+    /**
+     * Keep an edit made to a drawn item (see editItemProperties).
+     * @param {Object} item - The drawn item, edited
+     * @param {'node'|'edge'} kind
+     * @param {Object} before - The drawn item as it was
+     * @returns {boolean} whether anything changed
+     */
+    saveItemEdit(item, kind, before) {
+        const view = this.currentView;
+        if (!view) return false;
+        const changes = viewItemChanges(kind, before, item);
+        let targets = null;
+        if (kind === 'edge') {
+            const connection = view.viewConnections.get(item.id);
+            const instance = connection ?? view.getRelationshipInstance(item.id);
+            const concept = connection ?? (instance && this.model.getRelationship(instance.relationshipId));
+            if (concept) targets = { concept, instance };
+        } else {
+            const instance = view.getElementInstance(item.id);
+            const concept = instance && (instance.content ?? this.model.getElement(instance.elementId));
+            if (concept) targets = { concept, instance };
+        }
+        if (!targets) return false;
+        // A new layer or type redraws in its layer's colour: the element's own, not a colour set on this view.
+        if (kind === 'node' && changes.appearance.fillColor && !targets.instance.appearance?.fillColor
+            && changes.appearance.fillColor === this.currentEngine?._archimateLayerColor?.(item.layer)) {
+            delete changes.appearance.fillColor;
+        }
+        if (!hasViewItemChanges(changes)) return false;
+        view.history.execute(new EditViewItemCommand(targets, changes, `Edit ${item.name || item.label || kind}`));
+        this.render();
+        this._renderTreePanel();
+        return true;
+    }
+
+    _defaultShowDiagramPropertiesDialog(engine) {
+        // Delegate to workspace's bundled diagram properties dialog
+        const bundledDialog = this.workspace?.showDiagramPropertiesDialog;
+        if (bundledDialog) {
+            return bundledDialog(engine);
+        }
+    }
+
+    _defaultShowViewPropertiesDialog(view) {
+        this.showViewProperties(view);
+    }
+
+    _createImageNode(point, dataURL, href = '') {
+        this._addViewObject({
+            id: this._newViewObjectId('image'), name: 'Image', shape: 'image', iconUrl: dataURL,
+            width: 160, height: 120, resizable: true, href,
+        }, point);
+    }
+
+    /**
+     * The part of a node's drawn size that differs from what its element draws
+     * at by default, so a resize undone back to the default leaves no override.
+     * @private
+     */
+    _sizeOverride(instance, node) {
+        const drawn = instance.resolve(this.model) ?? {};
+        const defaults = this.currentEngine._archimateBuildNode({ ...drawn }, this.currentEngine._archimateOptions ?? {});
+        return Object.fromEntries(NODE_SIZE_KEYS
+            .filter(key => node[key] != null && node[key] !== defaults[key])
+            .map(key => [key, node[key]]));
+    }
+
+    /** An element id not yet used in the model, derived from a label. @private */
+    _newElementId(label) {
+        return GraphDiagram.generateNodeId(label, this.model.elements().map(e => e.id));
+    }
+
+    /**
+     * Create a model element and show it on the current view at `point`
+     * (snapped to the grid), as one undo step.
+     * @returns {ElementInstance|null}
+     * @private
+     */
+    _addNewElement(element, point) {
+        return this._placeOnView(element.id, point, { element });
+    }
+
+    /**
+     * Show a model element on the current view at `point` (snapped to the
+     * grid) and redraw. One undo step; with `element`, it is created too.
+     * @returns {ElementInstance|null}
+     * @private
+     */
+    _placeOnView(elementId, point, { element = null } = {}) {
+        if (!this.currentView) return null;
+        const snapped = this._snapToGrid(point);
+        return this._show(new ElementInstance(elementId, snapped.x, snapped.y), { element });
+    }
+
+    /**
+     * Put a note or image on the current view only (it is not a model element)
+     * at `point`, snapped to the grid. One undo step.
+     * @returns {ViewObjectInstance|null}
+     * @private
+     */
+    _addViewObject(content, point) {
+        if (!this.currentView) return null;
+        const snapped = this._snapToGrid(point);
+        return this._show(new ViewObjectInstance(content, snapped.x, snapped.y));
+    }
+
+    /** Add an instance to the current view as one undo step and redraw. @private */
+    _show(instance, { element = null } = {}) {
+        this.currentView.addToView(instance, { element });
+        this.render();
+        return instance;
+    }
+
+    /** A view-object id clear of every model element and every view's objects. @private */
+    _newViewObjectId(label) {
+        const taken = [
+            ...this.model.elements().map(e => e.id),
+            ...this.model.views().flatMap(v => [...v.elementInstances.values()].map(i => i.elementId)),
+        ];
+        return GraphDiagram.generateNodeId(label, taken);
+    }
+
+    _defaultShowAddArchimateElementDialog(engine, point) {
+        try {
+            const RenderEngineClass = engine.constructor;
+            const archimateVersion = engine._archimateOptions?.archimateVersion || '4';
+            const viewpoint = engine._archimateOptions?.viewpoint || 'All';
+            const customViewpoints = engine._archimateOptions?.customViewpoints || [];
+            const typeChoices = [
+                ...RenderEngineClass.ArchimateViewpoints.allowedElementTypes(viewpoint, archimateVersion, customViewpoints),
+                ...RenderEngineClass.ITIconNotation.elementTypeNames(),
+            ].sort();
+            const specSelect = new this.workspace.ArchimateSpecializationSelector(RenderEngineClass.ArchimateSpecializationRegistry, { doc: this.document })
+                .buildSelect({ elementType: '' });
+
+            const dialog = new FormDialog({
+                title: 'Add ArchiMate Element',
+                description: viewpoint === 'All'
+                    ? 'Type picks the layer/colour automatically (e.g. business-actor, node, goal).'
+                    : `Viewpoint "${viewpoint}" restricts the type list; type picks layer/colour automatically.`,
+                fields: [
+                    { key: 'name', label: 'Name', type: 'text' },
+                    { key: 'type', label: 'Type', type: 'text', suggestions: typeChoices },
+                    { key: 'specialization', label: 'Specialization', type: 'custom', element: specSelect, read: () => specSelect.value || undefined },
+                ],
+                submitLabel: 'Add',
+                idPrefix: 'archimate-add-element-',
+                document: this.document,
+                validate: ({ name, type }) => (name.trim() && !type.trim() ? 'Type is required' : null),
+                onApply: ({ name, type, specialization }) => {
+                    name = name.trim();
+                    type = type.trim();
+                    if (!name) return;
+                    const id = this._newElementId(name);
+                    this._addNewElement(engine._archimateBuildNode({ id, name, type, specialization }, { archimateVersion }), point);
+                    this._checkAndPromptForRelationships(id);
+                },
+            }).open();
+
+            const typeInput = dialog.controls.type;
+            for (const event of ['input', 'change']) {
+                typeInput.addEventListener(event, () => specSelect._onTypeChanged(typeInput.value));
+            }
+            dialog.controls.name.focus();
+        } catch (err) {
+            console.error('showAddArchimateElementDialog failed:', err);
+        }
+    }
+
+    _defaultShowAddNoteDialog(engine, point) {
+        try {
+            new FormDialog({
+                title: 'Add Note',
+                fields: [{ key: 'text', label: 'Text', type: 'textarea' }],
+                submitLabel: 'Add',
+                idPrefix: 'archimate-add-note-',
+                document: this.document,
+                onApply: ({ text }) => {
+                    text = text.trim();
+                    if (!text) return;
+                    this._addViewObject({
+                        id: this._newViewObjectId(text), name: text, label: text, shape: 'note',
+                        width: 140, height: 90, resizable: true,
+                    }, point);
+                },
+            }).open();
+        } catch (err) {
+            console.error('showAddNoteDialog failed:', err);
+        }
+    }
+
+    _defaultShowAddImageDialog(engine, point) {
+        try {
+            new FormDialog({
+                title: 'Add Image',
+                fields: [
+                    { key: 'file', label: 'File', type: 'file', accept: 'image/*' },
+                    { key: 'href', label: 'Link', type: 'text', placeholder: 'optional URL opened on click' },
+                ],
+                submitLabel: 'Add',
+                idPrefix: 'archimate-add-image-',
+                document: this.document,
+                onApply: ({ file, href }) => {
+                    if (!file) return;
+                    const reader = new this.document.defaultView.FileReader();
+                    reader.onload = (e) => this._createImageNode(point, e.target.result, href.trim());
+                    reader.readAsDataURL(file);
+                },
+            }).open();
+        } catch (err) {
+            console.error('showAddImageDialog failed:', err);
+        }
+    }
+
+    /**
+     * Render the current view's diagram.
+     * Gets elements from view, calls rendering engine, applies UI styling.
+     */
+    render(options = {}) {
+        if (!this.currentEngine || !this.currentView) return;
+
+        console.log(`[render] START - currentView id: ${this.currentView.id}, instances count: ${this.currentView.elementInstances.size}`);
+
+        // Get elements and relationships to render
+        let elementsToRender = this.currentView?.elements;
+        let relationshipsToRender = this.currentView?.relationships || [];
+
+        // Log what we're about to render
+        const zIndices = Array.from(this.currentView.elementInstances.values()).map(i => `${i.id}:${i.zIndex}`).join(', ');
+        console.log(`[render] instances zIndex: ${zIndices}`);
+        const renderZIndexes = elementsToRender?.map(e => `${e.id}:${e.zIndex}`).join(', ');
+        console.log(`[render] elementsToRender zIndex: ${renderZIndexes}`);
+
+        if (!Array.isArray(elementsToRender)) {
+            console.warn('render: currentView.elements is not an array', {
+                viewName: this.currentView?.name,
+                elements: elementsToRender,
+            });
+            return;
+        }
+
+        // Compute and include derived relationships if toggle is on
+        if (this.getOption('archimate-show-derived', false)) {
+            const { derived } = this.workspace.DerivedRelationships.compute(this.model, { maxHops: 2 });
+            const derivedWithInstances = derived.map(rel => {
+                const mapped = { ...rel, lineStyle: 'dotted', label: `${rel.pathSummary}` };
+                // Map source/target to diagramInstanceId (same as view relationships)
+                const sourceInstances = this.currentView.elementInstancesFor(rel.source);
+                const targetInstances = this.currentView.elementInstancesFor(rel.target);
+                if (sourceInstances.length > 0) mapped.source = sourceInstances[0].id;
+                if (targetInstances.length > 0) mapped.target = targetInstances[0].id;
+                return mapped;
+            });
+            relationshipsToRender = [...relationshipsToRender, ...derivedWithInstances];
+        }
+
+        try {
+            // Initialize model settings on first render if needed
+            if (this.settingsManager && !this.settingsManager._modelSettings['default']) {
+                this.settingsManager.initModelSettings('default');
+            }
+
+            // Get effective settings (hierarchy: view > model > tool)
+            const effectiveSettings = this.settingsManager?.getEffectiveSettings(this.currentView, 'default') || {};
+            const gridSize = effectiveSettings.gridSize || 20;
+            const edgeRouting = effectiveSettings.edgeRouting || 'orthogonal';
+            const showGrid = effectiveSettings.showGrid !== false;
+            // Shared with the base's snapping (_snapToGrid) for drops onto the canvas.
+            this.gridSize = gridSize;
+            this.showGrid = showGrid;
+
+            const deps = this.deps || {};
+            const currentArchimateViewpoint = () => this.getOption('archimate-viewpoint', 'All');
+            const currentArchimateViewpointMode = () => this.getOption('archimate-viewpoint-mode', 'fade');
+
+            this.currentEngine.archimateDiagram(elementsToRender, relationshipsToRender, {
+                // The groups drawn on this view (an Archi import's groups), parents first.
+                folders: this.currentView?.placedFolders ?? [],
+                archimateVersion: this.getOption('archimate-version', '4'),
+                useDistinctShapes: this.getOption('archimate-distinct-shapes', false),
+                // How an invalid relationship shows: diagram, then model, then tool setting.
+                invalidRelationships: effectiveSettings.invalidRelationships,
+                viewpoint: currentArchimateViewpoint(),
+                viewpointMode: currentArchimateViewpointMode(),
+                customViewpoints: deps.customViewpoints || [],
+                editable: true,
+                resizable: true,
+                gridSize,
+                showGrid,
+                edgeRouting,
+                // The engine records moves and bends into this view's history, so
+                // they undo across re-renders; these hooks fire on every apply.
+                history: this.currentView.history,
+                internalKeys: this.currentView.constructor.PROJECTION_KEYS,
+                onNodeMove: (nodeId, pos) => {
+                    const instance = this.currentView?.getElementInstance(nodeId);
+                    if (instance) {
+                        instance.x = pos.x;
+                        instance.y = pos.y;
+                    }
+                },
+                onNodeResize: (node) => {
+                    const instance = this.currentView?.getElementInstance(node.id);
+                    if (instance) instance.size = this._sizeOverride(instance, node);
+                },
+                // Each relationship instance keeps its own route and pinned sides.
+                onEdgeWaypointsChange: (edge, waypoints) => {
+                    const instance = this.currentView?.getRelationshipInstance(edge.id);
+                    if (instance) instance.waypoints = (waypoints ?? []).map(wp => ({ x: wp.x, y: wp.y }));
+                },
+                onEdgeSideChange: (edge, endpoint, side) => {
+                    const instance = this.currentView?.getRelationshipInstance(edge.id);
+                    if (instance) instance[endpoint === 'source' ? 'sourceSide' : 'targetSide'] = side ?? null;
+                },
+                onEdgeAdd: (edge) => this._relationshipDrawn(edge),
+                onEdgeRemove: (edge) => this._relationshipUndrawn(edge),
+                contextMenuItems: [
+                    { label: 'Show/Edit Properties…', action: (node, engine) => this.editItemProperties(node, 'node', engine) },
+                    { label: 'Add Missing Relationships…', action: (node, engine) => {
+                        const instance = this.currentView?.getElementInstance(node.id);
+                        if (instance) this._checkAndPromptForRelationships(instance.elementId);
+                    }},
+                    { label: 'Generate View For This', action: (node) => {
+                        const instance = this.currentView?.getElementInstance(node.id);
+                        if (instance && this.model.getElement(instance.elementId)) this.model.generateView([instance.elementId]);
+                    }},
+                    // The same Order submenu as the template editor's (DiagramEditor.ORDER_OPERATIONS).
+                    {
+                        label: DiagramEditor.ORDER_MENU_LABEL,
+                        items: DiagramEditor.ORDER_OPERATIONS.map(([operation, label]) => ({
+                            label, action: (node) => this.executeOrderCommand(node.id, operation),
+                        })),
+                    },
+                    // Group / Ungroup / Lock / Unlock (a template's background is unlocked here).
+                    { label: 'Arrange', items: (node) => this.nodeArrangeMenuItems(node.id) },
+                    // A canvas box: its hint (shown in the Hints panel).
+                    { label: 'Hint', items: (node) => hintMenuItems(this.currentView, node.id, { onChange: () => { this.render(); this.showHintFor(node.id); }, document: this.document }) },
+                    // A canvas: this box and its group as a template.
+                    { label: 'Save as template', items: (node) => this.templateMenu.saveAsTemplateItems(this.currentView?.id, { itemIds: [...(this.currentView?.arrangement.movingWith(node.id) ?? [])] }) },
+                    { label: 'Delete', action: (node) => {
+                        if (this.isFixed(node.id)) return this.tellLocked(`"${node.name || 'This'}"`, node.id);
+                        this.currentView?.deleteElement(node.id);
+                        this.render();
+                    }},
+                ],
+                edgeContextMenuItems: [
+                    { label: 'Show/Edit Properties…', action: (edge, engine) => this.editItemProperties(edge, 'edge', engine) },
+                    { label: 'Add Waypoint Here', action: (edge, engine, point) => engine._activeDiagram._insertEdgeWaypoint(edge, point) },
+                    { label: 'Delete from View', action: (edge) => {
+                        this.currentView?.removeRelationship(edge.diagramInstanceId || edge.id);
+                        this.render();
+                    }},
+                ],
+                canvasContextMenuItems: this.canvasContextMenuItemsFor(this.currentView),
+                onNodeClick: (node) => {
+                    this.tree.select(node.id, 'element');
+                    this.showHintFor(node.id);
+                    setTimeout(() => this._applyFilterHighlighting(), 0);
+                },
+                onEdgeClick: (edge) => {
+                    if (edge.id) this.tree.select(edge.id, 'relationship');
+                    setTimeout(() => this._applyFilterHighlighting(), 0);
+                },
+                onNodeDoubleClick: (node) => {
+                    this.editItemProperties(node, 'node');
+                    setTimeout(() => this._applyFilterHighlighting(), 0);
+                },
+                onEdgeDoubleClick: (edge) => {
+                    this.editItemProperties(edge, 'edge');
+                    setTimeout(() => this._applyFilterHighlighting(), 0);
+                },
+                // Empty canvas is the view itself: its properties.
+                onCanvasDoubleClick: () => this.deps.showViewPropertiesDialog(this.currentView, () => this.render()),
+            });
+
+            // Wrap diagram handlers once - only if not already wrapped to avoid nested wrappers
+            this._wrapDiagramHandlers();
+        } catch (err) {
+            console.error('ERROR calling archimateDiagram():', err.message, err.stack);
+        }
+
+
+
+        // Apply filter highlighting to diagram
+        this._applyFilterHighlighting();
+
+        // Background, title band and watermark come from the view's resolved settings.
+        this.decorateView(this.diagrams?.containerFor(this.currentView.id) ?? null,
+            this.settingsManager?.getEffectiveSettings(this.currentView, 'default') ?? {});
+
+        // Save element positions to model
+        this._savePositions(elementsToRender);
+
+        // A canvas shows its hints.
+        this.showHintFor();
+
+        console.log(`[render] END - render complete`);
+        this._notifyRendered();
+    }
+
+    /**
+     * Wrap diagram handlers (onClick, _rerenderGraph) to restore highlighting.
+     * Only wraps once - tracks wrapping state to avoid nested wrappers on each render.
+     * @private
+     */
+    _wrapDiagramHandlers() {
+        if (!this.currentEngine?._activeDiagram) return;
+        if (this.currentEngine._activeDiagram._handlersWrapped) return; // Already wrapped
+        this.currentEngine._activeDiagram._handlersWrapped = true;
+
+        // Wrap onClick to restore filter highlighting after clicks
+        const originalOnClick = this.currentEngine._activeDiagram.onClick;
+        if (originalOnClick) {
+            this.currentEngine._activeDiagram.onClick = (event, hitShape) => {
+                originalOnClick.call(this.currentEngine._activeDiagram, event, hitShape);
+                setTimeout(() => this._applyFilterHighlighting(), 0);
+            };
+        }
+
+        // Wrap _rerenderGraph to restore highlighting after any re-render (e.g., dragging elements)
+        const originalRerenderGraph = this.currentEngine._activeDiagram._rerenderGraph;
+        if (originalRerenderGraph) {
+            this.currentEngine._activeDiagram._rerenderGraph = () => {
+                originalRerenderGraph.call(this.currentEngine._activeDiagram);
+                setTimeout(() => this._applyFilterHighlighting(), 0);
+            };
+        }
+    }
+
+    /**
+     * Apply visual highlighting to filtered elements in diagram.
+     * If no filter, highlight all elements (opacity: normal).
+     * If filter active, highlight only matching elements OR elements that appear in diagramInstances.
+     * Elements added to the diagram stay bright even when filtered, showing they're "in use".
+     */
+    _applyFilterHighlighting() {
+        const svg = this.currentEngine?.renderer?.svg;
+        if (!svg) return;
+        for (const node of svg.querySelectorAll('[nodeId]')) {
+            node.classList.toggle('filter-highlight', this._passesFilter(node.getAttribute('nodeId')));
+        }
+    }
+
+    /**
+     * Whether a drawn node stays lit under the active filter. The filter names
+     * model elements, and a node is an instance of one, so every view (a
+     * duplicate included) is judged by what it shows. Notes and images are not
+     * model elements, so a filter never dims them.
+     * @private
+     */
+    _passesFilter(nodeId) {
+        if (!this._elementFilter) return true;
+        const instance = this.currentView?.getElementInstance(nodeId);
+        if (!instance || !this.model.getElement(instance.elementId)) return true;
+        return this._elementFilter.has(instance.elementId);
+    }
+
+    /**
+     * Save element positions from engine back to ElementInstances (not legacy layout).
+     * IMPORTANT: With ElementInstances, positions are source of truth - don't override them.
+     * This method is deprecated with new architecture; instances should drive rendering.
+     * Only called for backward compatibility with diagram engine repositioning.
+     */
+    _savePositions(elementsToRender) {
+        // With new ElementInstance architecture, instances are the source of truth
+        // Don't override instance positions based on what the diagram engine computed
+        // The instances define where elements should be rendered
+        // This method is kept for future compatibility but should not modify instances
+    }
+
+    /**
+     * Save positions before view switch (e.g., when user clicks another tab).
+     * IMPORTANT: With ElementInstances, instances are the source of truth.
+     * Don't override instance positions based on diagram engine computations.
+     */
+    savePositions() {
+        // With new ElementInstance architecture, instances define positions
+        // Don't override them based on diagram engine repositioning
+        // This method is kept for backward compatibility
+    }
+
+    /** Take elements dragged from the model tree (MODEL_ELEMENT_MIME, which the tree panel sets) onto the diagram. */
+    enableTreeDragDrop() {
+        if (this._treeDragDropBound) return;
+        this._treeDragDropBound = true;
+        this.addDropHandler({
+            accepts: (dt) => Array.from(dt.types).includes(MODEL_ELEMENT_MIME),
+            drop: (dt, point) => this._createDiagramInstance(dt.getData(MODEL_ELEMENT_MIME), point.x, point.y),
+        });
+    }
+
+    /**
+     * Offer the element's relationships to elements already on the view, and
+     * add the ones the user accepts as one undo step.
+     * @private
+     */
+    _checkAndPromptForRelationships(elementId) {
+        const view = this.currentView;
+        if (!view) return;
+        const missing = view.missingRelationshipInstances(elementId);
+        if (!missing.length) return;
+        const nameOf = (instanceId) => {
+            const inst = view.getElementInstance(instanceId);
+            return inst?.getDisplayName(this.model) || inst?.elementId || instanceId;
+        };
+        const lines = missing.map(inst => `${nameOf(inst.sourceInstanceId)} → ${nameOf(inst.targetInstanceId)}`).join('\n');
+        const msg = `Found ${missing.length} relationship(s) connecting these elements:\n\n${lines}\n\nAdd them to the diagram?`;
+        if (!this.document.defaultView?.confirm(msg)) return;
+        view.addRelationshipsToView(missing);
+        this.render();
+    }
+
+    /**
+     * A relationship drawn on the canvas: the engine records the gesture as one
+     * undo step and reports each apply here, so the model and view follow it.
+     * The first time, the user picks its kind.
+     * @private
+     */
+    _relationshipDrawn(edge) {
+        const view = this.currentView;
+        const source = view?.getElementInstance(edge.source);
+        const target = view?.getElementInstance(edge.target);
+        if (!source || !target) return;
+        if (!view.linesAreRelationships(source.id, target.id)) {
+            // The engine's own command draws it (and undoes it): the line joins the view directly.
+            // The same line again on redo, kept by the editor rather than on the drawn edge (whose fields are data).
+            this._drawnLines ??= new WeakMap();
+            if (!this._drawnLines.has(edge)) this._drawnLines.set(edge, view.newLine(source.id, target.id));
+            const line = this._drawnLines.get(edge);
+            edge.id = line.id;
+            view.viewConnections.set(line.id, line);
+            return;
+        }
+        const firstTime = !edge.relationshipId;
+        edge.relationshipId ??= GraphDiagram.generateNodeId(
+            `${source.elementId}-${target.elementId}`, this.model.relationships().map(r => r.id));
+        if (!this.model.getRelationship(edge.relationshipId)) {
+            this.model.addRelationship({ id: edge.relationshipId, source: source.elementId, target: target.elementId, kind: edge.kind ?? 'association' });
+        }
+        const instance = new RelationshipInstance(edge.relationshipId, null, source.id, target.id);
+        // The id the view draws it under, so undo finds it after a re-render.
+        edge.id = instance.id;
+        view.addRelationshipInstance(instance);
+        if (firstTime) this.deps.showPickRelationshipKindDialog(this.currentEngine, edge);
+    }
+
+    /** Undo of a drawn relationship: it leaves the view and the model. @private */
+    _relationshipUndrawn(edge) {
+        if (this.currentView?.viewConnections.has(edge.id)) {
+            this.currentView.viewConnections.delete(edge.id);
+            return;
+        }
+        this.currentView?.removeRelationshipInstance(edge.id);
+        if (edge.relationshipId) this.model.removeRelationship(edge.relationshipId);
+    }
+
+    /**
+     * Show an existing model element (dropped from the tree) on the current
+     * view at (x, y), then offer its relationships to elements already shown.
+     * @private
+     */
+    _createDiagramInstance(elementId, x, y) {
+        if (!this.model.getElement(elementId)) {
+            console.warn(`Element not found: ${elementId}`);
+            return;
+        }
+        if (this._placeOnView(elementId, { x, y })) this._checkAndPromptForRelationships(elementId);
+    }
+
+    /**
+     * Get a control value from the DOM.
+     */
+    getOption(controlId, defaultValue) {
+        if (this._options?.has(controlId)) return super.getOption(controlId, defaultValue);
+        // Hosts that bring their own controls (wireControls) keep them in the DOM.
+        try {
+            const el = this.document.getElementById(controlId);
+            if (!el) return defaultValue;
+            if (el.type === 'checkbox') return el.checked;
+            return el.value || defaultValue;
+        } catch {
+            return defaultValue;
+        }
+    }
+
+    /** Save specializations to localStorage. */
+    saveSpecializations() {
+        SPECIALIZATIONS_STORE.save(this.workspace.ArchimateSpecializationRegistry.serialize());
+    }
+    /**
+     * Export model to CSV format (elements + relationships).
+     * Returns a Blob ready to download.
+     */
+    exportCSV() {
+        const { data, mimeType } = this._format(ArchimateCsvFileFormat).export(this.model);
+        return new this.document.defaultView.Blob([data], { type: mimeType });
+    }
+
+    /**
+     * Import the two CSV tables, replacing the model: its elements and
+     * relationships, with one view of them all (a CSV holds no views).
+     */
+    importCSV(elementsCSV, relationshipsCSV) {
+        this.importCSVText(`=== elements.csv ===\n${elementsCSV}\n\n=== relationships.csv ===\n${relationshipsCSV}`);
+    }
+
+    /**
+     * Filter diagram elements by name using regex pattern.
+     * @param {string} pattern - Regex pattern to match element names (case-insensitive)
+     */
+    /**
+     * Filter elements by name/documentation.
+     * Hides non-matching in tree, highlights matching in diagram.
+     * @param {string} pattern - Regex pattern (case-insensitive)
+     * @param {Object} options - {searchDocs: boolean} - also search documentation property
+     */
+    /**
+     * Filter tree by element name only (separate from diagram filtering).
+     * Hides non-matching nodes in tree.
+     */
+
+    /**
+     * Apply unified filter to diagram and/or tree based on mode.
+     */
+
+    /**
+     * Hide non-matching nodes in the tree and show filter indicator
+     */
+    _filterTreeNodes(matchingIds) {
+        const treeEl = this.document.getElementById(this.treeContainerId);
+        if (!treeEl) {
+            return;
+        }
+
+
+        // Remove previous filter hiding
+        for (const node of treeEl.querySelectorAll('.filter-hidden')) {
+            node.classList.remove('filter-hidden');
+        }
+
+        // Update filter indicator
+        if (matchingIds) {
+            treeEl.classList.add('tree-filtered');
+        } else {
+            treeEl.classList.remove('tree-filtered');
+        }
+
+        if (!matchingIds) return;
+
+        // Hide non-matching element nodes
+        const elementNodes = treeEl.querySelectorAll('[data-element-id]');
+        for (const node of elementNodes) {
+            const elementId = node.getAttribute('data-element-id');
+            if (!matchingIds.has(elementId)) {
+                node.classList.add('filter-hidden');
+            }
+        }
+
+        // Hide parent layer nodes if all their children are hidden
+        const allNodes = treeEl.querySelectorAll('[data-node-id]');
+        for (const node of allNodes) {
+            // Only consider nodes that are NOT element nodes (i.e., layers/categories)
+            if (!node.hasAttribute('data-element-id')) {
+                // Check if this node has any visible children
+                const childContainer = node.querySelector(':scope > div');
+                if (childContainer) {
+                    const visibleChildren = Array.from(childContainer.children).filter(
+                        child => !child.classList.contains('filter-hidden')
+                    );
+                    if (visibleChildren.length === 0) {
+                        // All children hidden, hide this parent too
+                        node.classList.add('filter-hidden');
+                    }
+                }
+            }
+        }
+    }
+
+    /**
+     * Filter change callback from FilterSystem.
+     * Updates diagram highlighting and tree visibility.
+     */
+    _onFilterChange(result) {
+        const { matchingIds, filterMode } = result;
+
+        // Update diagram highlighting
+        // Model element ids, or null for no filter; applied per node by _passesFilter.
+        this._elementFilter = (filterMode === 'both' || filterMode === 'diagram') ? matchingIds : null;
+        this._applyFilterHighlighting();
+
+        // Update tree visibility
+        if (filterMode === 'both' || filterMode === 'tree') {
+            this._filterTreeNodes(matchingIds);
+        } else {
+            // Show all in tree
+            this._filterTreeNodes(null);
+        }
+    }
+
+    /**
+     * Export the model, with every view, as Archi's XML format.
+     * Returns XML string ready to download.
+     */
+    exportArchimate() {
+        return this.workspace.RenderEngine.exportArchiXML(...this.workspace.toArchiExport(this.model));
+    }
+
+    /**
+     * Export the model as Archi saves it: plain XML, or, when a view holds
+     * pictures, a zip archive with them under images/ (toArchiFile).
+     * @returns {{ data: string|Uint8Array, archive: boolean, mimeType: string }}
+     */
+    exportArchimateFile() {
+        return this._format(ArchiFileFormat).export(this.model);
+    }
+
+    /**
+     * Export the model as an Open Group Exchange Format file (XML text), the
+     * standard route to other ArchiMate tools. Its ArchiMate views are written;
+     * canvases and sketches are not (the format has none).
+     */
+    exportExchange() {
+        return this._format(ExchangeFileFormat).export(this.model).data;
+    }
+
+    /**
+     * Import an Archi file into the model, replacing it: XML text, or the
+     * file's bytes (plain XML, or the zip archive Archi saves when there are
+     * pictures).
+     * @param {string|Uint8Array|ArrayBuffer} file
+     */
+    importArchimate(file) {
+        this.replaceModel(this._format(ArchiFileFormat).import(file));
+    }
+
+    /**
+     * Import an Open Group Exchange Format file into the model, replacing it.
+     * @param {string} xml
+     */
+    importExchange(xml) {
+        this.replaceModel(this._format(ExchangeFileFormat).import(xml));
+    }
+
+    /** Edit another model (an imported one) in place of this one, closing its views' tabs. */
+    replaceModel(model) {
+        for (const id of this.diagrams.openViewIds()) this._quietly(() => this.diagrams.closeTab(id));
+        this._bindModel(model);
+        this.filterSystem.model = this.model;
+        this._renderTreePanel();
+        if (this.currentView) this._showView(this.currentView);
+    }
+
+    /**
+     * Drop or paste image files onto the diagram; each is handed to
+     * `deps.onImageDrop(engine, point, dataURL)`.
+     */
+    setupImageDragDrop() {
+        this.enableImageDrop((dataURL, point) => this.deps?.onImageDrop?.(this.currentEngine, point, dataURL));
+    }
+
+    /**
+     * Wire up all control event listeners (version, viewpoint, distinct shapes, etc.).
+     * Triggers render on change. Optional: provide custom handler functions.
+     */
+    wireControls(options = {}) {
+        const {
+            onVersionChange,
+            onViewpointChange,
+            onViewpointModeChange,
+            onDistinctShapesChange,
+            onShowDerivedChange,
+            onManageViewpoints,
+            onManageSpecializations,
+            populateViewpointSelect,
+        } = options;
+
+        // Version selector
+        const versionEl = this.document.getElementById('archimate-version');
+        if (versionEl) {
+            versionEl.addEventListener('change', () => {
+                if (onVersionChange) onVersionChange();
+                this.render();
+            });
+        }
+
+        // Viewpoint selector and mode
+        const viewpointEl = this.document.getElementById('archimate-viewpoint');
+        const viewpointModeEl = this.document.getElementById('archimate-viewpoint-mode');
+        if (viewpointEl) {
+            viewpointEl.addEventListener('change', () => {
+                if (onViewpointChange) onViewpointChange();
+                this.render();
+            });
+        }
+        if (viewpointModeEl) {
+            viewpointModeEl.addEventListener('change', () => {
+                if (onViewpointModeChange) onViewpointModeChange();
+                this.render();
+            });
+        }
+
+        // Distinct shapes checkbox
+        const distinctShapesEl = this.document.getElementById('archimate-distinct-shapes');
+        if (distinctShapesEl) {
+            distinctShapesEl.addEventListener('change', () => {
+                if (onDistinctShapesChange) onDistinctShapesChange();
+                this.render();
+            });
+        }
+
+        // Show derived relationships checkbox
+        const showDerivedEl = this.document.getElementById('archimate-show-derived');
+        if (showDerivedEl) {
+            showDerivedEl.addEventListener('change', () => {
+                if (onShowDerivedChange) onShowDerivedChange();
+                this.render();
+            });
+        }
+
+        // Manage viewpoints dialog
+        const manageVpEl = this.document.getElementById('archimate-manage-viewpoints');
+        if (manageVpEl && onManageViewpoints) {
+            manageVpEl.addEventListener('click', onManageViewpoints);
+        }
+
+        // Manage specializations dialog
+        const manageSpecEl = this.document.getElementById('archimate-manage-specializations');
+        if (manageSpecEl && onManageSpecializations) {
+            manageSpecEl.addEventListener('click', onManageSpecializations);
+        }
+
+        // Settings dialog
+        const settingsEl = this.document.getElementById('archimate-settings');
+        if (settingsEl) {
+            settingsEl.addEventListener('click', () => {
+                this.workspace.showGlobalSettingsDialog(this.document, this.settingsManager, 'default');
+            });
+        }
+
+        // Filter controls
+        const filterInput = this.document.getElementById('archimate-filter');
+        const filterClearEl = this.document.getElementById('archimate-filter-clear');
+        if (filterInput && this.currentEngine) {
+            const applyFilter = () => {
+                this.currentEngine.filterGraphNodes(filterInput.value);
+            };
+            filterInput.addEventListener('input', applyFilter);
+            if (filterClearEl) {
+                filterClearEl.addEventListener('click', () => {
+                    filterInput.value = '';
+                    applyFilter();
+                });
+            }
+        }
+    }
+}