@grafloria/element 0.3.17 → 0.3.19

package/src/libs/engine/src/engine/DiagramEngine.js

@@ -0,0 +1,2190 @@
+"use strict";
+// DiagramEngine - Main orchestrator for diagram functionality
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiagramEngine = void 0;
+const tslib_1 = require("tslib");
+const EventBus_1 = require("../events/EventBus");
+const TemplateRegistry_1 = require("../templates/TemplateRegistry");
+const DiagramEntity_1 = require("../models/DiagramEntity");
+const DiagramStore_1 = require("../state/DiagramStore");
+const CommandManager_1 = require("../commands/CommandManager");
+const PluginManager_1 = require("../plugins/PluginManager");
+const TypeRegistry_1 = require("../validation/TypeRegistry");
+const ValidationEngine_1 = require("../validation/ValidationEngine");
+const Serializer_1 = require("../serialization/Serializer");
+const PerformanceMonitor_1 = require("../performance/PerformanceMonitor");
+const DiagramModel_1 = require("../models/DiagramModel");
+const NodeModel_1 = require("../models/NodeModel");
+const LinkModel_1 = require("../models/LinkModel");
+const GroupModel_1 = require("../models/GroupModel"); // Phase 1.6c
+const AddNodeCommand_1 = require("../commands/basic/AddNodeCommand");
+const RemoveNodeCommand_1 = require("../commands/basic/RemoveNodeCommand");
+const dynamic_ports_1 = require("../ports/dynamic-ports");
+const AddLinkCommand_1 = require("../commands/basic/AddLinkCommand");
+const RemoveLinkCommand_1 = require("../commands/basic/RemoveLinkCommand");
+const basic_1 = require("../commands/basic"); // Phase 1.6c
+const basic_2 = require("../commands/basic"); // Phase 1.7
+const basic_3 = require("../commands/basic"); // Phase 1.8
+const ClipboardManager_1 = require("../clipboard/ClipboardManager"); // Phase 1.8
+const SelectionManager_1 = require("../selection/SelectionManager"); // Phase 1.8a
+const DiagramMode_1 = require("./DiagramMode");
+const ModeManager_1 = require("./ModeManager");
+// Phase 1: Interaction modes
+const ConnectionStateManager_1 = require("../state/ConnectionStateManager");
+const InteractionConfig_1 = require("../config/InteractionConfig");
+// Routing imports
+const RoutingEngine_1 = require("../routing/RoutingEngine");
+const LiveReroutingEngine_1 = require("../routing/LiveReroutingEngine"); // Phase 0.2
+const ObstacleMapBuilder_1 = require("../routing/ObstacleMapBuilder");
+const StraightRouter_1 = require("../routing/algorithms/StraightRouter");
+const OrthogonalRouter_1 = require("../routing/algorithms/OrthogonalRouter");
+const AStarRouter_1 = require("../routing/algorithms/AStarRouter");
+const DijkstraRouter_1 = require("../routing/algorithms/DijkstraRouter");
+const VisibilityGraphRouter_1 = require("../routing/algorithms/VisibilityGraphRouter");
+// Wave 7 (Auto-layout) — Card 0: the unified layout entry point.
+const layout_registry_1 = require("../layout/layout-registry");
+const rng_1 = require("../layout/rng");
+const mental_map_1 = require("../layout/incremental/mental-map");
+// Wave 7 — Card 4: nested container / subgraph layout.
+const CompoundLayoutService_1 = require("../layout/CompoundLayoutService");
+// Wave 7 — Card 3: off-main-thread layout.
+const layout_host_1 = require("../layout/layout-host");
+const layout_graph_1 = require("../layout/layout-graph");
+class DiagramEngine {
+    constructor(config = {}) {
+        // Phase 0.2: Live rerouting engine
+        this.liveReroutingEngine = null;
+        // Current diagram
+        this.diagram = null;
+        // Disposer functions for the engine's own listeners on the attached diagram.
+        // Stored on attach and invoked on detach so switching diagrams unsubscribes
+        // cleanly without accumulating duplicate handlers (and without touching the
+        // diagram's contents).
+        this.diagramDisposers = [];
+        // Wave 6 (Card 7): re-entry guard for the dynamic-port allocator.
+        this.reconcilingDynamicPorts = false;
+        // Wave 2 (Edges & links): transient endpoint-reconnection preview (see type).
+        this.reconnectionPreview = null;
+        this.proximityPreview = null;
+        this.snapGuides = null;
+        // State
+        this.initialized = false;
+        this.destroyed = false;
+        this.config = config;
+        // Initialize core systems
+        this.eventBus = new EventBus_1.EventBus();
+        this.store = new DiagramStore_1.DiagramStore();
+        // Empty by default (a plain app pays nothing); registerTemplateLibrary() /
+        // registerGeneratedTemplates() populate it. Closes the documented-but-absent
+        // `engine.templateRegistry` the template-library integration already targets.
+        this.templateRegistry = new TemplateRegistry_1.TemplateRegistry(this.eventBus);
+        // Phase 1: Initialize interaction config
+        this.interactionConfig = Object.assign(Object.assign({}, InteractionConfig_1.DEFAULT_INTERACTION_CONFIG), config.interaction);
+        // Phase 1: Initialize connection state manager
+        this.connectionStateManager = new ConnectionStateManager_1.ConnectionStateManager(this.eventBus);
+        // CRITICAL FIX: Listen for connection complete events and create the actual link
+        this.eventBus.on('connection:complete', (event) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            if (this.diagram && event.sourcePort && event.targetPort) {
+                const sourcePort = event.sourcePort;
+                const targetPort = event.targetPort;
+                // Find the nodes that own these ports
+                const nodes = this.diagram.getNodes();
+                let sourceNode = null;
+                let targetNode = null;
+                for (const node of nodes) {
+                    if (node.getPort(sourcePort.id)) {
+                        sourceNode = node;
+                    }
+                    if (node.getPort(targetPort.id)) {
+                        targetNode = node;
+                    }
+                    if (sourceNode && targetNode)
+                        break;
+                }
+                if (sourceNode && targetNode) {
+                    // Determine path type from config
+                    // Map ConnectionLineStyle enum to LinkModel pathType
+                    let pathType = 'smooth';
+                    switch (this.interactionConfig.connectionLineStyle) {
+                        case 'bezier':
+                            pathType = 'bezier';
+                            break;
+                        case 'step':
+                            pathType = 'orthogonal';
+                            break;
+                        case 'straight':
+                            pathType = 'direct';
+                            break;
+                        default:
+                            pathType = 'smooth';
+                    }
+                    console.log(`🔗 Creating link with pathType: ${pathType} (from connectionLineStyle: ${this.interactionConfig.connectionLineStyle})`);
+                    // Create the link manually (same logic as createSmartLink)
+                    const link = new LinkModel_1.LinkModel(sourcePort.id, targetPort.id, pathType);
+                    link.sourceNodeId = sourceNode.id;
+                    link.targetNodeId = targetNode.id;
+                    // Register connections in ports
+                    sourcePort.addConnection(link.id, 'source');
+                    targetPort.addConnection(link.id, 'target');
+                    // Calculate initial path using RoutingEngine
+                    const sourcePos = sourcePort.getAbsolutePosition(sourceNode.getBoundingBox());
+                    const targetPos = targetPort.getAbsolutePosition(targetNode.getBoundingBox());
+                    // Get port directions for routing
+                    const sourceDirection = (_a = sourcePort.alignment) === null || _a === void 0 ? void 0 : _a.side;
+                    const targetDirection = (_b = targetPort.alignment) === null || _b === void 0 ? void 0 : _b.side;
+                    // Use RoutingEngine to calculate path with obstacle avoidance
+                    yield this.generateLinkPathWithRouting(link, sourcePos, targetPos, sourceDirection, targetDirection, sourceNode, targetNode);
+                    // Add link THROUGH THE COMMAND MANAGER — one undoable step, like every
+                    // other edit. This used to call diagram.addLink() directly, so a link
+                    // the user DREW (the port-drag gesture) was the one mutation Ctrl+Z
+                    // could not take back (visio audit). The command serializes the link
+                    // AFTER routing, so the routed path is what redo restores.
+                    const command = new AddLinkCommand_1.AddLinkCommand(link);
+                    if (this.commandManager) {
+                        yield this.commandManager.execute(command);
+                    }
+                    else {
+                        this.diagram.addLink(link); // constructor-time fallback; unreachable in practice
+                    }
+                    console.log('✅ Link created successfully:', link.id, 'from', sourcePort.id, 'to', targetPort.id);
+                }
+                else {
+                    console.error('❌ Failed to find nodes for ports');
+                }
+            }
+        }));
+        // Initialize ModeManager with context provider
+        this.modeManager = new ModeManager_1.ModeManager(this.eventBus, () => ({
+            engine: this,
+            diagram: this.diagram,
+        }), config.mode);
+        const context = {
+            diagram: this.diagram,
+            eventBus: this.eventBus,
+            store: this.store,
+            engine: this,
+        };
+        this.commandManager = new CommandManager_1.CommandManager(context, this.eventBus);
+        this.pluginManager = new PluginManager_1.PluginManager(this, this.eventBus);
+        this.typeRegistry = new TypeRegistry_1.TypeRegistry();
+        this.validationEngine = new ValidationEngine_1.ValidationEngine(this.typeRegistry, this.eventBus); // Phase 1 - Pass EventBus
+        this.serializer = new Serializer_1.DiagramSerializer();
+        this.performanceMonitor = new PerformanceMonitor_1.PerformanceMonitor(config.performance);
+        this.routingEngine = new RoutingEngine_1.RoutingEngine(); // Initialize routing engine with LRU cache
+        this.clipboardManager = new ClipboardManager_1.ClipboardManager(); // Phase 1.8
+        this.selectionManager = new SelectionManager_1.SelectionManager(null, this.store, this.eventBus); // Phase 1.8a
+        // Configure systems
+        this.configureSystems();
+        // Install plugins
+        this.installPlugins();
+        // Mark as initialized
+        this.initialized = true;
+        this.eventBus.emit('engine:initialized');
+    }
+    /**
+     * Get current diagram
+     */
+    getDiagram() {
+        return this.diagram;
+    }
+    /**
+     * Get configuration (Phase 1 - Critical Fixes)
+     */
+    getConfig() {
+        return this.config;
+    }
+    /**
+     * Phase 1: Get interaction configuration
+     * Returns the current interaction mode settings
+     */
+    getInteractionConfig() {
+        return Object.assign({}, this.interactionConfig);
+    }
+    /**
+     * Phase 1: Set interaction configuration
+     * Updates interaction mode settings and emits event
+     */
+    setInteractionConfig(config) {
+        const oldConfig = Object.assign({}, this.interactionConfig);
+        this.interactionConfig = Object.assign(Object.assign({}, this.interactionConfig), config);
+        this.eventBus.emit('config:interaction-changed', {
+            oldConfig,
+            newConfig: this.interactionConfig,
+        });
+    }
+    /**
+     * Phase 1: Get connection state manager
+     * Used for managing connection drag operations
+     */
+    getConnectionStateManager() {
+        return this.connectionStateManager;
+    }
+    /**
+     * Wave 2 (Edges & links): current endpoint-reconnection preview, or null when
+     * no endpoint is being dragged. The renderer reads this to draw a ghost link.
+     */
+    getReconnectionPreview() {
+        return this.reconnectionPreview;
+    }
+    /**
+     * Wave 2 (Edges & links): set (or clear, with null) the endpoint-reconnection
+     * preview. Called by the interaction layer on start/move/end of an endpoint
+     * drag. Does not emit — the interaction layer already triggers re-render.
+     */
+    setReconnectionPreview(preview) {
+        this.reconnectionPreview = preview;
+        // A bare field write bumps no epoch, and the renderer's frame-skip gate
+        // dropped every repaint during an endpoint drag — the ghost line froze at
+        // the grab point while the model tracked the cursor perfectly (live
+        // audit). Overlay state IS picture state; say so.
+        (0, DiagramEntity_1.bumpMutationEpoch)();
+    }
+    /** The proximity-connect proposal the renderer draws as a live wire, or null. */
+    getProximityPreview() {
+        return this.proximityPreview;
+    }
+    /** Set (or clear, with null) the proximity-connect proposal. Does not emit —
+     *  the node drag that drives it already triggers re-renders. */
+    setProximityPreview(preview) {
+        this.proximityPreview = preview;
+        (0, DiagramEntity_1.bumpMutationEpoch)(); // overlay state is picture state — see setReconnectionPreview
+    }
+    /** The live snap-guide segments a node drag is showing, or null. */
+    getSnapGuides() {
+        return this.snapGuides;
+    }
+    /** Set (or clear, with null) the live snap guides. Does not emit — the node
+     *  drag that drives them already triggers re-renders. */
+    setSnapGuides(guides) {
+        this.snapGuides = guides;
+        (0, DiagramEntity_1.bumpMutationEpoch)(); // overlay state is picture state — see setReconnectionPreview
+    }
+    /**
+     * Get routing engine
+     * Used for calculating link paths with various algorithms
+     */
+    getRoutingEngine() {
+        return this.routingEngine;
+    }
+    /**
+     * Phase 0.2: Enable live rerouting
+     * Automatically updates link paths when nodes move or resize
+     */
+    enableLiveRerouting() {
+        if (!this.diagram) {
+            console.warn('Cannot enable live rerouting: No diagram loaded');
+            return;
+        }
+        if (!this.liveReroutingEngine) {
+            this.liveReroutingEngine = new LiveReroutingEngine_1.LiveReroutingEngine(this.routingEngine, this.diagram);
+        }
+        this.liveReroutingEngine.enable();
+        console.log('✅ Live rerouting enabled');
+    }
+    /**
+     * Phase 0.2: Disable live rerouting
+     */
+    disableLiveRerouting() {
+        if (this.liveReroutingEngine) {
+            this.liveReroutingEngine.disable();
+            console.log('⚠️ Live rerouting disabled');
+        }
+    }
+    /**
+     * Phase 0.2: Get live rerouting engine
+     */
+    getLiveReroutingEngine() {
+        return this.liveReroutingEngine;
+    }
+    /**
+     * Set diagram
+     */
+    setDiagram(diagram) {
+        const oldDiagram = this.diagram;
+        if (oldDiagram) {
+            this.detachDiagram(oldDiagram);
+        }
+        this.diagram = diagram;
+        if (diagram) {
+            this.attachDiagram(diagram);
+            // Wave 9 — Card 7: a diagram attached to an engine that is ALREADY in
+            // VIEW/PRESENTATION mode must come up LOCKED. Without this, read-only would
+            // depend on whether the host happened to call setMode() before or after
+            // loading the document — a race the host cannot see.
+            this.syncReadonlyLock();
+        }
+        this.store.set('diagram', diagram);
+        this.eventBus.emit('diagram:changed', { oldDiagram, newDiagram: diagram });
+        // Update command context
+        this.commandManager.updateContext({ diagram });
+        // Update selection manager diagram reference (Phase 1.8a)
+        this.selectionManager.setDiagram(diagram);
+        // Wave 6 (Card 6): the connection manager needs the graph to work out which
+        // ports are valid targets. Without this its `calculateValidTargets()` has
+        // nothing to walk — which is exactly why that method was a no-op stub and
+        // `validTargetPorts` was empty for the whole life of the feature.
+        this.connectionStateManager.setDiagram(diagram);
+    }
+    /**
+     * Create new diagram
+     */
+    createDiagram(name = 'Untitled') {
+        const diagram = new DiagramModel_1.DiagramModel(name);
+        this.setDiagram(diagram);
+        this.eventBus.emit('diagram:created', diagram);
+        return diagram;
+    }
+    /**
+     * Clear diagram
+     */
+    clearDiagram() {
+        if (this.diagram) {
+            this.diagram.clear();
+            this.store.set('selectedNodes', new Set());
+            this.store.set('selectedLinks', new Set());
+            this.commandManager.clear();
+            this.eventBus.emit('diagram:cleared');
+        }
+    }
+    /**
+     * Add node implementation
+     */
+    addNode(configOrNode) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            if (!this.diagram) {
+                throw new Error('No diagram loaded');
+            }
+            return this.performanceMonitor.measure('addNode', () => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                var _a, _b;
+                // Determine if we received a config or a NodeModel
+                let node;
+                if (configOrNode instanceof NodeModel_1.NodeModel) {
+                    node = configOrNode;
+                }
+                else {
+                    node = new NodeModel_1.NodeModel(configOrNode);
+                }
+                // Validate
+                if ((_a = this.config.validation) === null || _a === void 0 ? void 0 : _a.strict) {
+                    const validation = this.validationEngine.validateNode(node);
+                    if (!validation.valid) {
+                        throw new Error(`Invalid node: ${(_b = validation.errors[0]) === null || _b === void 0 ? void 0 : _b.message}`);
+                    }
+                }
+                // Add via command
+                const command = new AddNodeCommand_1.AddNodeCommand(node);
+                yield this.commandManager.execute(command);
+                // Return the node that was actually added (might be deserialized)
+                return (this.diagram && this.diagram.getNode(node.id)) || node;
+            }));
+        });
+    }
+    /**
+     * Remove node
+     *
+     * Wave 14: async + awaited, mirroring removeGroup(). The execute() promise
+     * used to float — a command failure became an unhandled rejection (fatal
+     * under Node), and callers could not sequence on the removal completing.
+     */
+    removeNode(nodeId) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            if (!this.diagram) {
+                throw new Error('No diagram loaded');
+            }
+            const node = this.diagram.getNode(nodeId);
+            if (!node) {
+                throw new Error(`Node ${nodeId} not found`);
+            }
+            const command = new RemoveNodeCommand_1.RemoveNodeCommand(nodeId);
+            yield this.commandManager.execute(command);
+        });
+    }
+    /**
+     * Wave 6 (Card 7): top up (or trim) the dynamic port groups on the nodes at
+     * either end of `link`.
+     *
+     * Runs through the COMMAND layer, so a spawned port is undoable and arrives
+     * with the same events and dirty-tracking as any other model change. Guarded
+     * against re-entry: an AddPortCommand does not itself add a link, but a host
+     * validator could, and a self-feeding allocator would be a delightful way to
+     * hang the app.
+     */
+    reconcileDynamicPorts(nodeIds) {
+        if (this.reconcilingDynamicPorts || !this.diagram)
+            return;
+        // The LINKS are the source of truth for "is this port free" — the port's
+        // own connection registry is derived state that `addLink()` never updates.
+        const links = this.diagram.getLinks();
+        const commands = [];
+        for (const nodeId of new Set(nodeIds)) {
+            const node = this.diagram.getNode(nodeId);
+            if (node)
+                commands.push(...(0, dynamic_ports_1.buildDynamicPortCommands)(node, links));
+        }
+        if (commands.length === 0)
+            return;
+        this.reconcilingDynamicPorts = true;
+        try {
+            for (const command of commands) {
+                // Port add/remove is synchronous; `execute` returns a promise only
+                // because the Command contract allows async ones. Nothing here awaits it,
+                // so the port is on the node by the time this returns — which is what the
+                // renderer, mid-frame, is entitled to assume.
+                void this.commandManager.execute(command);
+            }
+        }
+        finally {
+            this.reconcilingDynamicPorts = false;
+        }
+    }
+    /** The nodes a link touches — resolved by id, or by searching for its ports. */
+    reconcileDynamicPortsFor(link) {
+        var _a;
+        const diagram = this.diagram;
+        if (!diagram)
+            return;
+        const nodeIds = [];
+        for (const [nodeId, portId] of [
+            [link.sourceNodeId, link.sourcePortId],
+            [link.targetNodeId, link.targetPortId],
+        ]) {
+            if (nodeId) {
+                nodeIds.push(nodeId);
+            }
+            else if (portId) {
+                const owner = (_a = diagram.getNodeByPortId) === null || _a === void 0 ? void 0 : _a.call(diagram, portId);
+                if (owner)
+                    nodeIds.push(owner.id);
+            }
+        }
+        this.reconcileDynamicPorts(nodeIds);
+    }
+    /**
+     * Add link
+     */
+    addLink(config) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            if (!this.diagram) {
+                throw new Error('No diagram loaded');
+            }
+            return this.performanceMonitor.measure('addLink', () => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                var _a;
+                // Check ports exist
+                const sourcePort = this.findPort(config.sourcePortId);
+                const targetPort = this.findPort(config.targetPortId);
+                if (!sourcePort || !targetPort) {
+                    throw new Error('Invalid ports');
+                }
+                const link = new LinkModel_1.LinkModel(config.sourcePortId, config.targetPortId, config.type);
+                // Validate
+                const validation = this.validationEngine.validateLink(link, this.diagram);
+                if (!validation.valid) {
+                    throw new Error(`Invalid link: ${(_a = validation.errors[0]) === null || _a === void 0 ? void 0 : _a.message}`);
+                }
+                // Add via command
+                const command = new AddLinkCommand_1.AddLinkCommand(link);
+                yield this.commandManager.execute(command);
+                // Return the link that was actually added (might be deserialized)
+                return (this.diagram && this.diagram.getLink(link.id)) || link;
+            }));
+        });
+    }
+    /**
+     * Remove link
+     *
+     * Wave 14: async + awaited, mirroring removeGroup() — see removeNode().
+     */
+    removeLink(linkId) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            if (!this.diagram) {
+                throw new Error('No diagram loaded');
+            }
+            const link = this.diagram.getLink(linkId);
+            if (!link) {
+                throw new Error(`Link ${linkId} not found`);
+            }
+            const command = new RemoveLinkCommand_1.RemoveLinkCommand(linkId);
+            yield this.commandManager.execute(command);
+        });
+    }
+    /**
+     * Add group (Phase 1.6c)
+     */
+    addGroup(config) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            if (!this.diagram) {
+                throw new Error('No diagram loaded');
+            }
+            return this.performanceMonitor.measure('addGroup', () => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                const group = new GroupModel_1.GroupModel(config);
+                // Add via command
+                const command = new basic_1.AddGroupCommand(group);
+                yield this.commandManager.execute(command);
+                // Return the group that was actually added
+                return (this.diagram && this.diagram.getGroup(group.id)) || group;
+            }));
+        });
+    }
+    /**
+     * Remove group (Phase 1.6c)
+     */
+    removeGroup(groupId) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            if (!this.diagram) {
+                throw new Error('No diagram loaded');
+            }
+            const group = this.diagram.getGroup(groupId);
+            if (!group) {
+                throw new Error(`Group ${groupId} not found`);
+            }
+            const command = new basic_1.RemoveGroupCommand(groupId);
+            yield this.commandManager.execute(command);
+        });
+    }
+    /**
+     * Add entity to group (Phase 1.6c)
+     */
+    addToGroup(groupId, entityId) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            if (!this.diagram) {
+                throw new Error('No diagram loaded');
+            }
+            const command = new basic_1.AddToGroupCommand(groupId, entityId);
+            yield this.commandManager.execute(command);
+        });
+    }
+    /**
+     * Remove entity from group (Phase 1.6c)
+     */
+    removeFromGroup(groupId, entityId) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            if (!this.diagram) {
+                throw new Error('No diagram loaded');
+            }
+            const command = new basic_1.RemoveFromGroupCommand(groupId, entityId);
+            yield this.commandManager.execute(command);
+        });
+    }
+    /**
+     * Expand group (Phase 1.6c)
+     */
+    expandGroup(groupId) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            if (!this.diagram) {
+                throw new Error('No diagram loaded');
+            }
+            const command = new basic_1.ExpandGroupCommand(groupId);
+            yield this.commandManager.execute(command);
+        });
+    }
+    /**
+     * Collapse group (Phase 1.6c)
+     */
+    collapseGroup(groupId, options) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            if (!this.diagram) {
+                throw new Error('No diagram loaded');
+            }
+            const command = new basic_1.CollapseGroupCommand(groupId, options);
+            yield this.commandManager.execute(command);
+        });
+    }
+    /**
+     * Get group by ID (Phase 1.6c)
+     */
+    getGroup(groupId) {
+        var _a;
+        return (_a = this.diagram) === null || _a === void 0 ? void 0 : _a.getGroup(groupId);
+    }
+    /**
+     * Get all groups (Phase 1.6c)
+     */
+    getGroups() {
+        var _a;
+        return ((_a = this.diagram) === null || _a === void 0 ? void 0 : _a.getGroups()) || [];
+    }
+    /**
+     * Set layout configuration on a group (Phase 1.7)
+     */
+    setLayout(groupId, layoutType, layoutConfig) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            if (!this.diagram) {
+                throw new Error('No diagram loaded');
+            }
+            const group = this.diagram.getGroup(groupId);
+            if (!group) {
+                throw new Error(`Group ${groupId} not found`);
+            }
+            const command = new basic_2.SetLayoutCommand(groupId, layoutType, layoutConfig);
+            yield this.commandManager.execute(command);
+        });
+    }
+    /**
+     * Clear layout configuration from a group (Phase 1.7)
+     */
+    clearLayout(groupId) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            if (!this.diagram) {
+                throw new Error('No diagram loaded');
+            }
+            const group = this.diagram.getGroup(groupId);
+            if (!group) {
+                throw new Error(`Group ${groupId} not found`);
+            }
+            // Clear layout by setting to 'none' (this triggers a command internally through the model)
+            group.clearLayout();
+        });
+    }
+    /**
+     * Get layout configuration from a group (Phase 1.7)
+     */
+    getLayout(groupId) {
+        var _a;
+        const group = (_a = this.diagram) === null || _a === void 0 ? void 0 : _a.getGroup(groupId);
+        return group === null || group === void 0 ? void 0 : group.getLayout();
+    }
+    /**
+     * Set flex item configuration on a node (Phase 1.7)
+     */
+    setFlexItem(nodeId, flexConfig) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            if (!this.diagram) {
+                throw new Error('No diagram loaded');
+            }
+            const node = this.diagram.getNode(nodeId);
+            if (!node) {
+                throw new Error(`Node ${nodeId} not found`);
+            }
+            const command = new basic_2.SetFlexItemCommand(nodeId, flexConfig);
+            yield this.commandManager.execute(command);
+        });
+    }
+    /**
+     * Set grid item configuration on a node (Phase 1.7)
+     */
+    setGridItem(nodeId, gridConfig) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            if (!this.diagram) {
+                throw new Error('No diagram loaded');
+            }
+            const node = this.diagram.getNode(nodeId);
+            if (!node) {
+                throw new Error(`Node ${nodeId} not found`);
+            }
+            const command = new basic_2.SetGridItemCommand(nodeId, gridConfig);
+            yield this.commandManager.execute(command);
+        });
+    }
+    /**
+     * Copy selected entities to clipboard (Phase 1.8)
+     */
+    copy(options) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            if (!this.diagram) {
+                throw new Error('No diagram loaded');
+            }
+            const command = new basic_3.CopyCommand(this.clipboardManager, options);
+            yield this.commandManager.execute(command);
+        });
+    }
+    /**
+     * Paste entities from clipboard (Phase 1.8)
+     */
+    paste(options) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            if (!this.diagram) {
+                throw new Error('No diagram loaded');
+            }
+            if (!this.clipboardManager.hasData()) {
+                throw new Error('Clipboard is empty');
+            }
+            const command = new basic_3.PasteCommand(this.clipboardManager, options);
+            yield this.commandManager.execute(command);
+        });
+    }
+    /**
+     * Duplicate selected entities (Phase 1.8)
+     */
+    duplicate(options) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            if (!this.diagram) {
+                throw new Error('No diagram loaded');
+            }
+            // Diagram selection first — a mouse click selects through
+            // diagram.selectNode() and never writes the store's set, so gating on the
+            // store alone made this helper throw for every mouse-selected node while
+            // DuplicateCommand itself (which checks both) would have succeeded.
+            const diagramSelection = this.diagram.getSelectedNodes();
+            const selectedNodeIds = this.store.get('selectedNodes');
+            if (diagramSelection.length === 0 && (!selectedNodeIds || selectedNodeIds.size === 0)) {
+                throw new Error('No nodes selected');
+            }
+            const command = new basic_3.DuplicateCommand(options);
+            yield this.commandManager.execute(command);
+        });
+    }
+    /**
+     * Delete selected entities (Phase 1.8)
+     */
+    deleteSelection(options) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            if (!this.diagram) {
+                throw new Error('No diagram loaded');
+            }
+            const selectedNodeIds = this.store.get('selectedNodes');
+            const selectedLinkIds = this.store.get('selectedLinks');
+            if ((!selectedNodeIds || selectedNodeIds.size === 0) &&
+                (!selectedLinkIds || selectedLinkIds.size === 0)) {
+                throw new Error('No entities selected');
+            }
+            const command = new basic_3.DeleteSelectionCommand(options);
+            yield this.commandManager.execute(command);
+        });
+    }
+    /**
+     * Get clipboard data (Phase 1.8)
+     */
+    getClipboardData() {
+        return this.clipboardManager.get();
+    }
+    /**
+     * Check if clipboard has data (Phase 1.8)
+     */
+    hasClipboardData() {
+        return this.clipboardManager.hasData();
+    }
+    /**
+     * Clear clipboard (Phase 1.8)
+     */
+    clearClipboard() {
+        this.clipboardManager.clear();
+    }
+    /**
+     * Get clipboard statistics (Phase 1.8)
+     */
+    getClipboardStats() {
+        return this.clipboardManager.getStats();
+    }
+    // ============================================================================
+    // Validation API (Phase 1 - Critical Fixes)
+    // ============================================================================
+    /**
+     * Validate the entire diagram
+     * @param options Validation options
+     * @returns Validation result with errors and warnings
+     */
+    validateDiagram(options) {
+        if (!this.diagram) {
+            return {
+                valid: false,
+                errors: [{
+                        path: 'diagram',
+                        message: 'No diagram loaded',
+                        code: 'NO_DIAGRAM',
+                        severity: 'error'
+                    }],
+                warnings: []
+            };
+        }
+        return this.validationEngine.validateDiagram(this.diagram, options);
+    }
+    /**
+     * Validate a specific node
+     * @param nodeId Node ID to validate
+     * @param options Validation options
+     * @returns Validation result with errors and warnings
+     */
+    validateNode(nodeId, options) {
+        if (!this.diagram) {
+            return {
+                valid: false,
+                errors: [{
+                        path: `node.${nodeId}`,
+                        message: 'No diagram loaded',
+                        code: 'NO_DIAGRAM',
+                        severity: 'error'
+                    }],
+                warnings: []
+            };
+        }
+        const node = this.diagram.getNode(nodeId);
+        if (!node) {
+            return {
+                valid: false,
+                errors: [{
+                        path: `node.${nodeId}`,
+                        message: `Node ${nodeId} not found`,
+                        code: 'NODE_NOT_FOUND',
+                        severity: 'error'
+                    }],
+                warnings: []
+            };
+        }
+        return this.validationEngine.validateNode(node, options);
+    }
+    /**
+     * Validate a specific link
+     * @param linkId Link ID to validate
+     * @param options Validation options
+     * @returns Validation result with errors and warnings
+     */
+    validateLink(linkId, options) {
+        if (!this.diagram) {
+            return {
+                valid: false,
+                errors: [{
+                        path: `link.${linkId}`,
+                        message: 'No diagram loaded',
+                        code: 'NO_DIAGRAM',
+                        severity: 'error'
+                    }],
+                warnings: []
+            };
+        }
+        const link = this.diagram.getLink(linkId);
+        if (!link) {
+            return {
+                valid: false,
+                errors: [{
+                        path: `link.${linkId}`,
+                        message: `Link ${linkId} not found`,
+                        code: 'LINK_NOT_FOUND',
+                        severity: 'error'
+                    }],
+                warnings: []
+            };
+        }
+        return this.validationEngine.validateLink(link, this.diagram, options);
+    }
+    /**
+     * Validate a specific port
+     * @param portId Port ID to validate
+     * @param nodeId Node ID containing the port
+     * @param options Validation options
+     * @returns Validation result with errors and warnings
+     */
+    validatePort(portId, nodeId, options) {
+        if (!this.diagram) {
+            return {
+                valid: false,
+                errors: [{
+                        path: `node.${nodeId}.port.${portId}`,
+                        message: 'No diagram loaded',
+                        code: 'NO_DIAGRAM',
+                        severity: 'error'
+                    }],
+                warnings: []
+            };
+        }
+        const node = this.diagram.getNode(nodeId);
+        if (!node) {
+            return {
+                valid: false,
+                errors: [{
+                        path: `node.${nodeId}.port.${portId}`,
+                        message: `Node ${nodeId} not found`,
+                        code: 'NODE_NOT_FOUND',
+                        severity: 'error'
+                    }],
+                warnings: []
+            };
+        }
+        const port = node.getPorts().find(p => p.id === portId);
+        if (!port) {
+            return {
+                valid: false,
+                errors: [{
+                        path: `node.${nodeId}.port.${portId}`,
+                        message: `Port ${portId} not found`,
+                        code: 'PORT_NOT_FOUND',
+                        severity: 'error'
+                    }],
+                warnings: []
+            };
+        }
+        return this.validationEngine.validatePort(port, node, options);
+    }
+    /**
+     * Validate layout configuration for a group (Phase 3 - Layout validation)
+     */
+    validateLayout(groupId, options) {
+        if (!this.diagram) {
+            return {
+                valid: false,
+                errors: [{
+                        path: `group.${groupId}.layout`,
+                        message: 'No diagram loaded',
+                        code: 'NO_DIAGRAM',
+                        severity: 'error'
+                    }],
+                warnings: []
+            };
+        }
+        const group = this.diagram.getGroup(groupId);
+        if (!group) {
+            return {
+                valid: false,
+                errors: [{
+                        path: `group.${groupId}.layout`,
+                        message: `Group ${groupId} not found`,
+                        code: 'GROUP_NOT_FOUND',
+                        severity: 'error'
+                    }],
+                warnings: []
+            };
+        }
+        return this.validationEngine.validateLayout(group, this.diagram, options);
+    }
+    /**
+     * Register a node type definition
+     * @param definition Node type definition
+     */
+    registerNodeType(definition) {
+        this.typeRegistry.registerNodeType(definition);
+    }
+    /**
+     * Register a port type definition
+     * @param definition Port type definition
+     */
+    registerPortType(definition) {
+        this.typeRegistry.registerPortType(definition);
+    }
+    /**
+     * Register a link type definition
+     * @param definition Link type definition
+     */
+    registerLinkType(definition) {
+        this.typeRegistry.registerLinkType(definition);
+    }
+    /**
+     * Register a group type definition (Phase 2 - Group validation)
+     * @param definition Group type definition
+     */
+    registerGroupType(definition) {
+        this.typeRegistry.registerGroupType(definition);
+    }
+    /**
+     * Enable real-time validation
+     */
+    enableRealTimeValidation() {
+        this.validationEngine.enableRealTimeValidation();
+    }
+    /**
+     * Disable real-time validation
+     */
+    disableRealTimeValidation() {
+        this.validationEngine.disableRealTimeValidation();
+    }
+    /**
+     * Check if real-time validation is enabled
+     */
+    isRealTimeValidationEnabled() {
+        return this.validationEngine.isRealTimeValidationEnabled();
+    }
+    // ============================================================================
+    // End Validation API
+    // ============================================================================
+    /**
+     * Select nodes
+     */
+    selectNodes(nodeIds) {
+        const selectedNodes = new Set(nodeIds);
+        this.store.set('selectedNodes', selectedNodes);
+        // Update node states
+        if (this.diagram) {
+            this.diagram.getNodes().forEach((node) => {
+                node.setState({ selected: selectedNodes.has(node.id) });
+            });
+        }
+        this.eventBus.emit('selection:changed', { nodes: nodeIds });
+    }
+    /**
+     * Select links
+     */
+    selectLinks(linkIds) {
+        const selectedLinks = new Set(linkIds);
+        this.store.set('selectedLinks', selectedLinks);
+        // Update link states
+        if (this.diagram) {
+            this.diagram.getLinks().forEach((link) => {
+                link.setState(selectedLinks.has(link.id) ? 'selected' : 'default');
+            });
+        }
+        this.eventBus.emit('selection:changed', { links: linkIds });
+    }
+    /**
+     * Clear selection
+     */
+    clearSelection() {
+        this.selectNodes([]);
+        this.selectLinks([]);
+        this.eventBus.emit('selection:cleared');
+    }
+    /**
+     * Undo
+     */
+    undo() {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            yield this.commandManager.undo();
+        });
+    }
+    /**
+     * Redo
+     */
+    redo() {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            yield this.commandManager.redo();
+        });
+    }
+    /**
+     * Can undo
+     */
+    canUndo() {
+        return this.commandManager.canUndo();
+    }
+    /**
+     * Can redo
+     */
+    canRedo() {
+        return this.commandManager.canRedo();
+    }
+    /**
+     * Validate diagram
+     */
+    validate() {
+        if (!this.diagram) {
+            return {
+                valid: true,
+                errors: [],
+                warnings: [],
+            };
+        }
+        return this.validationEngine.validateDiagram(this.diagram);
+    }
+    /**
+     * Serialize diagram (with mode)
+     */
+    serialize() {
+        if (!this.diagram) {
+            return null;
+        }
+        const serialized = this.serializer.serialize(this.diagram);
+        // Include current mode
+        serialized.mode = this.modeManager.serialize();
+        return serialized;
+    }
+    /**
+     * Deserialize diagram (with mode)
+     */
+    deserialize(data, options) {
+        const diagram = this.serializer.deserialize(data, options);
+        this.setDiagram(diagram);
+        // Restore mode if present
+        this.modeManager.restore(data.mode);
+        return diagram;
+    }
+    /**
+     * Load diagram from JSON (with mode)
+     */
+    loadFromJSON(json, options) {
+        const data = typeof json === 'string' ? JSON.parse(json) : json;
+        return this.deserialize(data, options);
+    }
+    /**
+     * Save diagram to JSON
+     */
+    saveToJSON() {
+        const data = this.serialize();
+        return data ? JSON.stringify(data, null, 2) : null;
+    }
+    /**
+     * Register a plugin AND bring it to life.
+     *
+     * `PluginManager.register()` only RECORDS a plugin; `install()` and
+     * `activate()` are separate steps. Calling register alone — which both of
+     * this engine's entry points used to do — left every plugin permanently
+     * inert: its hooks never fired, though `getPlugin()` happily returned it.
+     * "Register a plugin" can only sensibly mean "make it run", so this drives
+     * the full lifecycle. A plugin that throws is reported and skipped rather
+     * than taking the host down with it.
+     */
+    registerPlugin(plugin) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const name = (_a = plugin.metadata) === null || _a === void 0 ? void 0 : _a.name;
+            this.pluginManager.register(plugin);
+            if (!name)
+                return;
+            try {
+                yield this.pluginManager.install(name);
+                yield this.pluginManager.activate(name);
+            }
+            catch (error) {
+                (_b = this.eventBus) === null || _b === void 0 ? void 0 : _b.emit('plugin:error', { name, error });
+            }
+        });
+    }
+    /**
+     * Get plugin
+     */
+    getPlugin(name) {
+        return this.pluginManager.get(name);
+    }
+    /**
+     * Set viewport
+     */
+    setViewport(viewport) {
+        this.store.set('viewport', viewport);
+        this.eventBus.emit('viewport:changed', viewport);
+    }
+    /**
+     * Set zoom
+     */
+    setZoom(zoom) {
+        const clampedZoom = Math.max(0.1, Math.min(5, zoom));
+        this.store.set('zoom', clampedZoom);
+        this.eventBus.emit('viewport:zoomed', clampedZoom);
+    }
+    /**
+     * Get performance report
+     */
+    getPerformanceReport() {
+        return this.performanceMonitor.getReport();
+    }
+    // ============================================================================
+    // Mode Management (Delegation to ModeManager)
+    // ============================================================================
+    /**
+     * Get current diagram mode
+     */
+    getMode() {
+        return this.modeManager.getMode();
+    }
+    /**
+     * Set diagram mode
+     */
+    setMode(mode) {
+        this.modeManager.setMode(mode);
+        this.syncReadonlyLock();
+    }
+    /**
+     * Wave 9 — Card 7. Push the mode's read-only verdict down onto the DOCUMENT.
+     *
+     * Before this wave `DiagramMode.VIEW` / `PRESENTATION` and `isReadOnlyMode()`
+     * existed, were documented as "all editing disabled" — and gated NOTHING. Not a
+     * command, not a model mutator, not the event binder. They were a boolean nobody
+     * asked. This is the line that makes the mode real: the model holds the lock, and
+     * the model is where mutation actually happens.
+     *
+     * Call it after any mode change, and whenever a diagram is attached (a diagram
+     * loaded into an engine that is ALREADY in presentation mode must come up locked,
+     * or read-only would depend on the order the host happened to call things in).
+     */
+    syncReadonlyLock() {
+        var _a;
+        (_a = this.diagram) === null || _a === void 0 ? void 0 : _a.setReadonly(this.modeManager.isReadOnlyMode());
+    }
+    /**
+     * Check if in designer mode
+     */
+    isDesignerMode() {
+        return this.modeManager.isDesignerMode();
+    }
+    /**
+     * Check if in running mode
+     */
+    isRunningMode() {
+        return this.modeManager.isRunningMode();
+    }
+    /**
+     * Check if in view mode
+     */
+    isViewMode() {
+        return this.modeManager.isViewMode();
+    }
+    /**
+     * Check if in debug mode
+     */
+    isDebugMode() {
+        return this.modeManager.isDebugMode();
+    }
+    /**
+     * Check if in presentation mode
+     */
+    isPresentationMode() {
+        return this.modeManager.isPresentationMode();
+    }
+    /**
+     * Check if in read-only mode (any mode except designer)
+     */
+    isReadOnlyMode() {
+        return this.modeManager.isReadOnlyMode();
+    }
+    /**
+     * Add mode transition guard
+     */
+    addModeGuard(name, guard) {
+        this.modeManager.addModeGuard(name, guard);
+    }
+    /**
+     * Remove mode transition guard
+     */
+    removeModeGuard(name) {
+        this.modeManager.removeModeGuard(name);
+    }
+    /**
+     * Clear all mode transition guards
+     */
+    clearModeGuards() {
+        this.modeManager.clearModeGuards();
+    }
+    /**
+     * Configure viewport settings for specific mode
+     */
+    configureModeViewport(mode, settings) {
+        this.modeManager.configureModeViewport(mode, settings);
+    }
+    /**
+     * Get viewport settings for specific mode
+     */
+    getModeViewportSettings(mode) {
+        return this.modeManager.getModeViewportSettings(mode);
+    }
+    /**
+     * Get mode history
+     */
+    getModeHistory() {
+        return this.modeManager.getModeHistory();
+    }
+    /**
+     * Clear mode history
+     */
+    clearModeHistory() {
+        this.modeManager.clearModeHistory();
+    }
+    /**
+     * Navigate to previous mode
+     */
+    previousMode() {
+        this.modeManager.previousMode();
+    }
+    /**
+     * Navigate to next mode
+     */
+    nextMode() {
+        this.modeManager.nextMode();
+    }
+    /**
+     * Push mode onto stack (save current, switch to new)
+     */
+    pushMode(mode) {
+        this.modeManager.pushMode(mode);
+    }
+    /**
+     * Pop mode from stack (return to previous)
+     */
+    popMode() {
+        this.modeManager.popMode();
+    }
+    /**
+     * Get mode analytics
+     */
+    getModeAnalytics() {
+        return this.modeManager.getModeAnalytics();
+    }
+    /**
+     * Register before mode change hook
+     */
+    beforeModeChange(hook) {
+        return this.modeManager.beforeModeChange(hook);
+    }
+    /**
+     * Register after mode change hook
+     */
+    afterModeChange(hook) {
+        return this.modeManager.afterModeChange(hook);
+    }
+    // wave14/model — `getNodeBehaviorForMode` DELETED along with NodeModel.behaviorOverrides.
+    // It had no caller outside its own spec; the real mode enforcement is the wave-9
+    // ReadonlyLock on the model (see models/readonly-lock.ts), which every mutator actually
+    // consults. (Its sibling getLinkBehaviorForMode below is equally caller-less — left in
+    // place because it is outside this card's chain, flagged for a future sweep.)
+    /**
+     * Get link behavior adjusted for current mode
+     */
+    getLinkBehaviorForMode(baseBehavior) {
+        const defaults = {
+            deletable: true,
+            selectable: true,
+        };
+        // Merge base behavior with defaults
+        const merged = Object.assign(Object.assign({}, defaults), baseBehavior);
+        // Apply mode restrictions
+        const currentMode = this.modeManager.getMode();
+        switch (currentMode) {
+            case DiagramMode_1.DiagramMode.DESIGNER:
+                // In designer mode, respect all base behavior settings
+                return merged;
+            case DiagramMode_1.DiagramMode.RUNNING:
+            case DiagramMode_1.DiagramMode.VIEW:
+            case DiagramMode_1.DiagramMode.DEBUG:
+            case DiagramMode_1.DiagramMode.PRESENTATION:
+                // In all other modes, disable editing but keep selectable
+                return {
+                    deletable: false,
+                    selectable: merged.selectable,
+                };
+            default:
+                return merged;
+        }
+    }
+    /**
+     * Initialize the engine
+     */
+    initialize() {
+        if (this.initialized) {
+            return;
+        }
+        this.initialized = true;
+        this.destroyed = false;
+        this.eventBus.emit('engine:initialized');
+    }
+    /**
+     * Get the store
+     */
+    getStore() {
+        return this.store;
+    }
+    /**
+     * Subscribe to events
+     */
+    on(event, listener) {
+        this.eventBus.on(event, listener);
+    }
+    /**
+     * Unsubscribe from events
+     */
+    off(event, listener) {
+        this.eventBus.off(event, listener);
+    }
+    /**
+     * Destroy engine
+     */
+    destroy() {
+        if (this.destroyed)
+            return;
+        this.destroyed = true;
+        // Emit destroyed event BEFORE removing listeners
+        this.eventBus.emit('engine:destroyed');
+        // Cleanup
+        if (this.diagram) {
+            this.detachDiagram(this.diagram);
+        }
+        // Reset mode through ModeManager
+        this.modeManager.restore(DiagramMode_1.DiagramMode.DESIGNER);
+        this.initialized = false;
+        // Note: PluginManager doesn't have destroy method yet
+        // this.pluginManager.destroy();
+        this.eventBus.removeAllListeners();
+        this.store.reset();
+    }
+    /**
+     * Configure systems
+     */
+    configureSystems() {
+        var _a, _b, _c;
+        // Configure command manager
+        if ((_a = this.config.history) === null || _a === void 0 ? void 0 : _a.maxCommands) {
+            this.commandManager.setMaxHistorySize(this.config.history.maxCommands);
+        }
+        // Configure validation
+        if ((_b = this.config.validation) === null || _b === void 0 ? void 0 : _b.realTime) {
+            this.validationEngine.enableRealTimeValidation();
+        }
+        // Configure performance monitoring
+        if ((_c = this.config.performance) === null || _c === void 0 ? void 0 : _c.warnThreshold) {
+            this.performanceMonitor.setWarnThreshold(this.config.performance.warnThreshold);
+        }
+    }
+    /**
+     * Install plugins
+     */
+    installPlugins() {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            if (this.config.plugins) {
+                // Same contract as registerPlugin(): a configured plugin is a LIVE one.
+                for (const plugin of this.config.plugins) {
+                    yield this.registerPlugin(plugin);
+                }
+            }
+        });
+    }
+    /**
+     * Register a node as an obstacle in the routing engine
+     */
+    registerNodeAsObstacle(node) {
+        const obstacle = {
+            id: node.id,
+            x: node.position.x,
+            y: node.position.y,
+            width: node.size.width,
+            height: node.size.height,
+        };
+        this.routingEngine.addObstacle(obstacle);
+    }
+    /**
+     * Wave 5 (Edge routing) — Card 6: reconcile the shared ObstacleMap with the
+     * diagram's GROUP state, idempotently:
+     *
+     *   - a COLLAPSED group (with geometry) is ONE solid obstacle;
+     *   - members hidden under a collapsed group (at any depth) are NOT obstacles
+     *     — they are not visible, and routing around invisible things produces
+     *     inexplicable detours;
+     *   - expanding restores the members and removes the group block.
+     *
+     * Runs on every group add/remove/collapse/expand. Public so the grouping
+     * feature (which owns collapse SEMANTICS but not the ObstacleMap) can force a
+     * reconcile after batch operations.
+     */
+    refreshGroupObstacles() {
+        if (!this.diagram)
+            return;
+        const groups = this.diagram.getGroups();
+        // ids of members hidden under a collapsed group at any depth
+        const hidden = new Set();
+        for (const g of groups) {
+            // a group's members are hidden if IT or any of its ancestors is collapsed
+            let cur = g;
+            let effectiveCollapsed = false;
+            const guard = new Set();
+            while (cur && !guard.has(cur.id)) {
+                guard.add(cur.id);
+                if (cur.isCollapsed) {
+                    effectiveCollapsed = true;
+                    break;
+                }
+                cur = cur.parentGroupId ? this.diagram.getGroup(cur.parentGroupId) : undefined;
+            }
+            if (!effectiveCollapsed)
+                continue;
+            for (const memberId of g.members)
+                hidden.add(memberId);
+        }
+        // hidden members: out of the map; visible ones: (re)registered
+        for (const node of this.diagram.getNodes()) {
+            if (hidden.has(node.id)) {
+                this.routingEngine.removeObstacle(node.id);
+            }
+            else {
+                this.routingEngine.updateObstacle({
+                    id: node.id,
+                    x: node.position.x,
+                    y: node.position.y,
+                    width: node.size.width,
+                    height: node.size.height,
+                    kind: 'node',
+                });
+            }
+        }
+        // group blocks: only VISIBLE collapsed groups block (a collapsed group
+        // nested inside another collapsed group is itself hidden)
+        for (const g of groups) {
+            const rect = this.groupObstacleRect(g);
+            if (g.isCollapsed && !hidden.has(g.id) && rect) {
+                this.routingEngine.updateObstacle(Object.assign(Object.assign({ id: g.id }, rect), { kind: 'group' }));
+            }
+            else {
+                this.routingEngine.removeObstacle(g.id);
+            }
+        }
+    }
+    groupObstacleRect(g) {
+        if (g.size) {
+            return { x: g.position.x, y: g.position.y, width: g.size.width, height: g.size.height };
+        }
+        if (g.bounds)
+            return Object.assign({}, g.bounds);
+        return null;
+    }
+    /**
+     * Update a node's obstacle when it moves or resizes
+     * Also invalidates all links so they recalculate paths with new obstacle positions
+     */
+    updateNodeObstacle(node) {
+        const obstacle = {
+            id: node.id,
+            x: node.position.x,
+            y: node.position.y,
+            width: node.size.width,
+            height: node.size.height,
+        };
+        this.routingEngine.updateObstacle(obstacle);
+        // NOTE: this method used to also mark EVERY link dirty "so they recalculate"
+        // — a sledgehammer that was dead code while the subscription bug hid it
+        // (see attachDiagram) and became a live perf regression the moment the fix
+        // woke it up: one node move invalidated every link VNode in the diagram.
+        // Link invalidation is owned by the renderer's per-frame route pre-pass +
+        // markLinksWhoseFrameChanged (wave 4), which re-renders exactly the links
+        // whose GEOMETRY actually changed.
+    }
+    /**
+     * Unregister a node obstacle when node is removed
+     */
+    unregisterNodeObstacle(nodeId) {
+        this.routingEngine.removeObstacle(nodeId);
+    }
+    /**
+     * Attach diagram
+     */
+    attachDiagram(diagram) {
+        // Subscribe to diagram events. Every subscription returns a disposer which
+        // we store so detachDiagram can unsubscribe the engine's own listeners
+        // without accumulating duplicates across attach/detach cycles.
+        this.diagramDisposers.push(diagram.on('node:added', (node) => {
+            this.eventBus.emit('node:added', node);
+            // Register node as obstacle for routing
+            this.registerNodeAsObstacle(node);
+            // Listen for node position/size changes
+            this.diagramDisposers.push(
+            // BUGFIX (wave 5, found by the nodes agent): NodeModel emits
+            // `change:position` (via trackChange) — never bare `position`. This
+            // listener had NEVER fired, so the shared ObstacleMap went stale on
+            // every node move; only the renderer's per-request obstacle list kept
+            // visible routing honest, while the a-star/dijkstra/visibility
+            // adapters — which read the SHARED map — routed around yesterday's
+            // positions.
+            node.on('change:position', () => {
+                this.updateNodeObstacle(node);
+            }));
+            this.diagramDisposers.push(node.on('change:size', () => {
+                this.updateNodeObstacle(node);
+            }));
+        }));
+        this.diagramDisposers.push(diagram.on('node:removed', (node) => {
+            this.eventBus.emit('node:removed', node);
+            // Unregister node obstacle
+            this.unregisterNodeObstacle(node.id);
+        }));
+        this.diagramDisposers.push(diagram.on('link:added', (link) => {
+            this.eventBus.emit('link:added', link);
+            // Wave 6 (Card 7): wiring up the last free port in a dynamic group must
+            // conjure the next one. This is the whole feature — a `dynamic` group
+            // whose allocator never runs is just a group.
+            this.reconcileDynamicPortsFor(link);
+        }));
+        // Wave 5 — Card 6: group state drives the obstacle map. `group:added` also
+        // subscribes to that group's own collapse/expand emitter (DiagramModel does
+        // not forward those); existing groups are wired below.
+        const wireGroup = (group) => {
+            this.diagramDisposers.push(group.on('collapsed', () => this.refreshGroupObstacles()));
+            this.diagramDisposers.push(group.on('expanded', () => this.refreshGroupObstacles()));
+        };
+        this.diagramDisposers.push(diagram.on('group:added', (group) => {
+            wireGroup(group);
+            this.refreshGroupObstacles();
+        }));
+        this.diagramDisposers.push(diagram.on('group:removed', () => this.refreshGroupObstacles()));
+        this.diagramDisposers.push(diagram.on('group:changed', () => this.refreshGroupObstacles()));
+        diagram.getGroups().forEach(wireGroup);
+        if (diagram.getGroups().length > 0)
+            this.refreshGroupObstacles();
+        this.diagramDisposers.push(diagram.on('link:removed', (link) => {
+            this.eventBus.emit('link:removed', link);
+            // Unwiring frees a port, which may leave the group with a SURPLUS of
+            // spares — the allocator retires the ones it spawned.
+            this.reconcileDynamicPortsFor(link);
+        }));
+        // Register all existing nodes as obstacles
+        diagram.getNodes().forEach((node) => {
+            this.registerNodeAsObstacle(node);
+            // Listen for node position/size changes
+            this.diagramDisposers.push(node.on('change:position', () => {
+                this.updateNodeObstacle(node);
+            }));
+            this.diagramDisposers.push(node.on('change:size', () => {
+                this.updateNodeObstacle(node);
+            }));
+        });
+    }
+    /**
+     * Detach diagram
+     */
+    detachDiagram(diagram) {
+        // Unregister all node obstacles from routing engine so the old diagram's
+        // nodes don't remain as obstacles affecting the newly attached diagram.
+        // This only touches the routing engine's obstacle registry, not the diagram.
+        diagram.getNodes().forEach((node) => {
+            this.unregisterNodeObstacle(node.id);
+        });
+        // Unsubscribe the engine's own listeners that were registered in
+        // attachDiagram. We deliberately do NOT clear() or otherwise mutate the old
+        // diagram: it must stay fully intact so it can be re-attached later with all
+        // of its nodes and links preserved. Disposing the stored handlers also
+        // prevents duplicate handlers from accumulating across attach/detach cycles.
+        for (const dispose of this.diagramDisposers) {
+            dispose();
+        }
+        this.diagramDisposers = [];
+    }
+    /**
+     * Find port in diagram
+     */
+    findPort(portId) {
+        if (!this.diagram) {
+            return undefined;
+        }
+        for (const node of this.diagram.getNodes()) {
+            const port = node.getPort(portId);
+            if (port) {
+                return port;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Get node that owns a port (Phase 1.6b)
+     */
+    getNodeForPort(portId) {
+        if (!this.diagram) {
+            return undefined;
+        }
+        for (const node of this.diagram.getNodes()) {
+            if (node.getPort(portId)) {
+                return node;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Get port position in global coordinates (Phase 1.6b)
+     * @param portId Port ID
+     * @returns Global position of the port
+     */
+    getPortGlobalPosition(portId) {
+        var _a, _b, _c, _d;
+        const port = this.findPort(portId);
+        if (!port) {
+            return { x: 0, y: 0 };
+        }
+        const node = this.getNodeForPort(portId);
+        if (!node) {
+            return { x: 0, y: 0 };
+        }
+        // Port position is normalized (0-1) relative to node size
+        const localPortPos = {
+            x: ((_b = (_a = port.position) === null || _a === void 0 ? void 0 : _a.x) !== null && _b !== void 0 ? _b : 0.5) * node.size.width,
+            y: ((_d = (_c = port.position) === null || _c === void 0 ? void 0 : _c.y) !== null && _d !== void 0 ? _d : 0.5) * node.size.height,
+        };
+        // Transform to global using node's global position
+        const nodeGlobalPos = node.getGlobalPosition();
+        return {
+            x: nodeGlobalPos.x + localPortPos.x,
+            y: nodeGlobalPos.y + localPortPos.y,
+        };
+    }
+    /**
+     * Compute link path using specified routing algorithm (Phase 1.6b)
+     * @param linkId Link ID
+     * @param algorithm Routing algorithm to use
+     * @param options Routing options
+     * @returns Array of points forming the path
+     */
+    computeLinkPath(linkId, algorithm, options = {}) {
+        var _a, _b;
+        const link = (_a = this.diagram) === null || _a === void 0 ? void 0 : _a.getLink(linkId);
+        if (!link) {
+            return [];
+        }
+        // Build obstacle map (excluding source and target nodes)
+        const sourceNode = this.getNodeForPort(link.sourcePortId);
+        const targetNode = this.getNodeForPort(link.targetPortId);
+        const excludeIds = [sourceNode === null || sourceNode === void 0 ? void 0 : sourceNode.id, targetNode === null || targetNode === void 0 ? void 0 : targetNode.id].filter((id) => id !== undefined);
+        const obstacleMap = ObstacleMapBuilder_1.ObstacleMapBuilder.fromDiagramExcluding(this.diagram, excludeIds, { margin: (_b = options.obstacleMargin) !== null && _b !== void 0 ? _b : 5 });
+        // Get port positions (in global coordinates)
+        const start = this.getPortGlobalPosition(link.sourcePortId);
+        const end = this.getPortGlobalPosition(link.targetPortId);
+        // Route based on algorithm
+        let points;
+        switch (algorithm) {
+            case 'straight': {
+                const router = new StraightRouter_1.StraightRouter();
+                const result = router.route({ start, end, obstacles: obstacleMap.getObstacles(), options });
+                points = (result === null || result === void 0 ? void 0 : result.points) || [start, end];
+                break;
+            }
+            case 'orthogonal': {
+                const router = new OrthogonalRouter_1.OrthogonalRouter();
+                const result = router.route({ start, end, obstacles: obstacleMap.getObstacles(), options });
+                points = (result === null || result === void 0 ? void 0 : result.points) || [start, end];
+                break;
+            }
+            case 'astar': {
+                const router = new AStarRouter_1.AStarRouter(obstacleMap, options);
+                points = router.route(start, end);
+                // Fallback to direct path if no path found
+                if (points.length === 0) {
+                    points = [start, end];
+                }
+                break;
+            }
+            case 'dijkstra': {
+                const router = new DijkstraRouter_1.DijkstraRouter(obstacleMap, options);
+                points = router.route(start, end);
+                // Fallback to direct path if no path found
+                if (points.length === 0) {
+                    points = [start, end];
+                }
+                break;
+            }
+            case 'visibility': {
+                const router = new VisibilityGraphRouter_1.VisibilityGraphRouter(obstacleMap, options);
+                points = router.route(start, end);
+                // Fallback to direct path if no path found
+                if (points.length === 0) {
+                    points = [start, end];
+                }
+                break;
+            }
+            default:
+                throw new Error(`Unknown routing algorithm: ${algorithm}`);
+        }
+        return points;
+    }
+    /**
+     * Generate link path using RoutingEngine with obstacle avoidance
+     * This ensures the final link respects the routing algorithm setting (A*, none, etc.)
+     */
+    generateLinkPathWithRouting(link, sourcePos, targetPos, sourceDirection, targetDirection, sourceNode, targetNode) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            // Get obstacles from diagram (INCLUDE ALL nodes, even source and target)
+            // The routing algorithm uses gap offset to ensure paths start/end outside node boundaries
+            const obstacles = [];
+            if (this.diagram) {
+                this.diagram.getNodes().forEach(node => {
+                    // Include ALL nodes as obstacles - the gap offset ensures we start/end outside
+                    obstacles.push({
+                        id: node.id,
+                        x: node.position.x,
+                        y: node.position.y,
+                        width: node.size.width,
+                        height: node.size.height,
+                    });
+                });
+            }
+            // Use the routing engine's default algorithm
+            const algorithm = this.routingEngine.getDefaultAlgorithm();
+            // Route the path with obstacle avoidance
+            // IMPORTANT: avoidObstacles should be based on whether obstacles exist, not on the algorithm
+            // - 'orthogonal' algorithm with avoidObstacles=true uses A* with orthogonal-only movement
+            // - 'a-star', 'dijkstra', etc. also use obstacle avoidance
+            // - 'straight' never avoids obstacles (direct line)
+            const shouldAvoidObstacles = obstacles.length > 0 && algorithm !== 'straight';
+            const routedPath = yield this.routingEngine.routeAsync({
+                start: sourcePos,
+                end: targetPos,
+                sourceDirection,
+                targetDirection,
+                obstacles,
+                options: {
+                    algorithm,
+                    avoidObstacles: shouldAvoidObstacles,
+                    obstacleMargin: 20,
+                    gridSize: 10, // Grid size for A* pathfinding
+                }
+            });
+            // Set the link points from the routed path.
+            // Wave 9 — Card 7: a SYSTEM write. These points are DERIVED from geometry the
+            // document already has; a read-only diagram must still route its links or it
+            // renders with no path at all. Not reachable from user input.
+            if (routedPath && routedPath.points.length > 0) {
+                const points = routedPath.points;
+                this.diagram
+                    ? this.diagram.runSystemWrite(() => link.setPoints(points))
+                    : link.setPoints(points);
+            }
+            else {
+                // Fallback to simple path generation if routing failed
+                link.generatePath(sourcePos, targetPos, sourceDirection, targetDirection);
+            }
+        });
+    }
+    /**
+     * Set layout service for diagram layouts
+     *
+     * @param service - Layout service instance
+     */
+    setLayoutService(service) {
+        this.layoutService = service;
+    }
+    /**
+     * The named-algorithm registry, with the built-ins already registered.
+     *
+     * THE BUG THIS CLOSES: `applyLayout()` below requires `setLayoutService()` —
+     * and NOTHING in the codebase ever called it (the only mention is a doc comment
+     * in layout/index.ts). So dagre, ELK, force, spectral and community — thousands
+     * of lines, several of them untested — were UNREACHABLE from the engine. That
+     * is the whole "auto-layout is fragmented" finding. Layout now works out of the
+     * box, with no setup call.
+     */
+    getLayoutRegistry() {
+        if (!this._layoutRegistry) {
+            // ONE factory, shared with the preset applicator: adapters, then the Card-2
+            // portfolio, then our layered engine, then the auto-selector (which takes the
+            // registry, so its candidate pool is whatever is actually registered).
+            this._layoutRegistry = (0, layout_registry_1.createDefaultLayoutRegistry)();
+        }
+        return this._layoutRegistry;
+    }
+    /**
+     * Lay out the whole diagram.
+     *
+     *     await engine.layout('dagre', { direction: 'LR' });
+     *
+     * DETERMINISTIC and IDEMPOTENT: the same graph and seed produce byte-identical
+     * coordinates, and running it twice changes nothing the second time. (The seed
+     * defaults to a fixed constant, so an author who never thinks about seeds still
+     * gets the same picture on every reload; randomness is opt-in.)
+     *
+     * NOT to be confused with `DiagramModel.getLayoutManager()`, which answers a
+     * DIFFERENT question — "where should this ONE newly-added node go?" — and is a
+     * placement strategy, not a graph layout. The audit called them "two parallel
+     * stacks" and asked for them to be merged; they are not parallel, and merging
+     * them would force a single-node placer to pretend it can lay out a graph.
+     */
+    layout() {
+        return tslib_1.__awaiter(this, arguments, void 0, function* (name = layout_registry_1.DEFAULT_LAYOUT_NAME, options = {}) {
+            var _a, _b;
+            if (!this.diagram) {
+                throw new Error('No diagram loaded');
+            }
+            const registered = this.getLayoutRegistry().get(name);
+            if (!registered) {
+                const available = this.getLayoutRegistry().names().join(', ');
+                throw new Error(`Unknown layout '${name}'. Registered layouts: ${available}`);
+            }
+            const seed = (_a = options.seed) !== null && _a !== void 0 ? _a : rng_1.DEFAULT_LAYOUT_SEED;
+            // Snapshot BEFORE any positions are committed: every return path below must
+            // invalidate the routed polyline of links whose endpoints moved. See
+            // invalidateStaleLinkRoutes for why leaving them is a real, observed bug.
+            const positionsBeforeLayout = this.snapshotNodePositions();
+            // Wave 7 Card 4 — nested container layout. On by default whenever the
+            // diagram has containers, because the flat path is not just worse there, it
+            // is WRONG: it interleaves members of different groups and never updates a
+            // single group frame, so every container is left behind pointing at where
+            // its members used to be. Opt out with `nested: false`.
+            const hasGroups = this.diagram.getGroups().length > 0;
+            if (((_b = options.nested) !== null && _b !== void 0 ? _b : hasGroups) && hasGroups) {
+                const result = yield new CompoundLayoutService_1.CompoundLayoutService(this.diagram, {
+                    defaultAlgorithm: name,
+                    adapters: this.getLayoutRegistry().adapters(),
+                    layoutTopLevel: true,
+                    defaultPadding: options.containerPadding,
+                    gridGap: options.groupSpacing,
+                    layoutOptions: Object.assign(Object.assign({}, options), { seed }),
+                }).layout();
+                // CompoundLayoutService commits through setPosition/setFrame as it goes
+                // (it has to — each level reads the geometry the level below produced).
+                this.invalidateStaleLinkRoutes(positionsBeforeLayout);
+                return {
+                    nodePositions: result.nodePositions,
+                    bounds: result.bounds,
+                    metadata: {
+                        algorithm: name,
+                        executionTime: 0,
+                        nested: true,
+                        containersLaidOut: result.laidOut,
+                        containersSkipped: result.skipped,
+                        containersCollapsed: result.collapsed,
+                    },
+                    algorithm: name,
+                    seed,
+                    // Card 3's run-status fields. A nested layout is a complete, synchronous
+                    // walk of the container tree — it is never cut short, so it reports itself
+                    // honestly as a finished single-pass run rather than leaving the caller to
+                    // guess from `undefined`.
+                    partial: false,
+                    iteration: 1,
+                    totalIterations: 1,
+                };
+            }
+            // ---- the flat path -----------------------------------------------------
+            //
+            // Card 3 routes it through the layout HOST, which runs the algorithm inline
+            // through the very same message loop a worker would run — so there is no second
+            // code path to drift, and a test proves the two produce byte-identical
+            // coordinates. (This replaces the direct runLayout() call: runLayout remains the
+            // shared apply-and-commit path used by the preset applicator, and the host
+            // commits through the same setPosition() route.)
+            // A hand-rolled RegisteredLayout is an opaque closure over a DiagramModel.
+            // A closure cannot cross a thread boundary, so it runs inline — not a
+            // policy, just physics. Every built-in exposes its adapter and takes the
+            // worker path below.
+            if (!registered.adapter) {
+                const result = yield registered.apply(this.diagram, Object.assign(Object.assign({}, options), { seed }));
+                this.commitLayoutPositions(result.nodePositions);
+                this.invalidateStaleLinkRoutes(positionsBeforeLayout);
+                return Object.assign(Object.assign({}, result), { algorithm: name, seed, partial: false, iteration: 1, totalIterations: 1 });
+            }
+            // Wave 7 Card 3: ONE path, whether or not a worker port is attached. The
+            // host runs the algorithm inline through the very same message loop the
+            // worker would run, so there is no second code path to drift — and a test
+            // proves the two produce byte-identical coordinates.
+            const graph = (0, layout_graph_1.serializeGraph)(this.diagram.getNodes(), this.diagram.getLinks());
+            const result = yield this.getLayoutHost().run(name, graph, (0, layout_registry_1.translateOptions)(name, Object.assign(Object.assign({}, options), { seed })), {
+                signal: options.signal,
+                onProgress: options.onProgress,
+                timeBudgetMs: options.timeBudgetMs,
+                sliceMs: options.sliceMs,
+                stopAfterIteration: options.stopAfterIteration,
+            });
+            this.commitLayoutPositions(result.nodePositions);
+            this.invalidateStaleLinkRoutes(positionsBeforeLayout);
+            return Object.assign(Object.assign({}, result), { algorithm: name, seed });
+        });
+    }
+    /**
+     * Wave 7 — Card 6: mental-map-preserving incremental layout.
+     *
+     *     await engine.layoutIncremental({ changed: [newNode.id], budget: { maxPerNode: 60 } });
+     *
+     * Mermaid re-renders the whole diagram from scratch on every edit and destroys the
+     * user's spatial memory of their own diagram. This does the opposite:
+     *
+     *   1. everything outside the affected region becomes a Card-5 ANCHOR — an
+     *      immovable obstacle the layout works AROUND (impossible before Card 5, when
+     *      "constraints" were positions clamped after an unconstrained run);
+     *   2. the result is RE-ALIGNED onto the previous layout by matching centroids —
+     *      exactly the translation that minimises squared displacement, because a
+     *      layered layout is defined only up to translation, so one new node widening
+     *      a rank slides the whole picture sideways and makes every node "move" while
+     *      the drawing is unchanged;
+     *   3. movement is MEASURED against an explicit budget and reported.
+     *
+     * Returns a tween PLAN rather than animating: the engine says where things go at
+     * time t, the host drives t — which is what keeps this runnable in a worker, in
+     * SSR and in a test.
+     *
+     * ONE SEMANTIC, STATED PLAINLY. This runs the `layered` engine, because it is the
+     * only one that honours anchors DURING coordinate assignment. If the diagram's
+     * current positions came from a DIFFERENT engine, the first incremental pass
+     * necessarily re-draws it — and that is not a bug to paper over: "move as little
+     * as possible" is ill-posed across engines, because there is no meaningful small
+     * move between two engines' idea of the same graph.
+     */
+    layoutIncremental() {
+        return tslib_1.__awaiter(this, arguments, void 0, function* (options = {}) {
+            var _a, _b, _c, _d;
+            if (!this.diagram)
+                throw new Error('No diagram loaded');
+            // The baseline EXCLUDES the just-added nodes. A node the user has only now
+            // created has no meaningful "previous position" — it sits wherever the model
+            // defaulted it (usually 0,0). Counting it is not a cosmetic error in the report:
+            // it DRAGS THE CENTROID, so the re-alignment translates the whole diagram to
+            // accommodate a position that never meant anything.
+            const changed = new Set((_a = options.changed) !== null && _a !== void 0 ? _a : []);
+            const before = new Map(this.diagram
+                .getNodes()
+                .filter((n) => !changed.has(n.id))
+                .map((n) => [n.id, { x: n.position.x, y: n.position.y }]));
+            const semantic = (0, mental_map_1.constraintsForStrategy)(this.diagram, before, options);
+            const result = yield this.layout((_b = options.name) !== null && _b !== void 0 ? _b : 'layered', Object.assign(Object.assign({}, options), { semantic }));
+            // Re-align onto the previous picture — but ONLY when the layout was FREE.
+            // Alignment cancels the arbitrary translation of a free layout; if a node is
+            // anchored the frame of reference is already pinned, and translating on top of
+            // that DRAGS THE ANCHORED NODES, which is the one thing they exist to prevent.
+            const raw = new Map(result.nodePositions);
+            const anchored = Object.keys((_c = semantic.anchors) !== null && _c !== void 0 ? _c : {}).length > 0;
+            const naive = (0, mental_map_1.measureMovement)(before, raw, options.budget);
+            const aligned = anchored ? raw : (0, mental_map_1.alignToPrevious)(raw, before).positions;
+            const settled = (0, mental_map_1.measureMovement)(before, aligned, options.budget);
+            const movement = Object.assign(Object.assign({}, settled), { savedByAlignment: Math.max(0, naive.total - settled.total) });
+            // The alignment translation below moves nodes AGAIN after layout()'s own
+            // commit — so its own snapshot/invalidate pair, or the translated picture
+            // keeps polylines routed for the pre-alignment coordinates.
+            const beforeAlign = this.snapshotNodePositions();
+            for (const [id, p] of aligned) {
+                (_d = this.diagram.getNode(id)) === null || _d === void 0 ? void 0 : _d.setPosition(p.x, p.y);
+            }
+            this.invalidateStaleLinkRoutes(beforeAlign);
+            return Object.assign(Object.assign({}, result), { nodePositions: aligned, movement, tween: (0, mental_map_1.planTween)(before, aligned) });
+        });
+    }
+    /** Every node's current position, keyed by id — the pre-layout baseline. */
+    snapshotNodePositions() {
+        var _a, _b;
+        const snapshot = new Map();
+        for (const node of (_b = (_a = this.diagram) === null || _a === void 0 ? void 0 : _a.getNodes()) !== null && _b !== void 0 ? _b : []) {
+            snapshot.set(node.id, { x: node.position.x, y: node.position.y });
+        }
+        return snapshot;
+    }
+    /**
+     * THE FIX for the stale-polyline bug: layout moves NODES, but each link keeps
+     * the polyline it was routed on before. The renderer treats a non-empty
+     * `link.points` as painted geometry and edge LABELS are placed by walking it
+     * (LabelRenderer via `link.getPointAtPosition`) — so after `engine.layout()`
+     * the labels sat at PRE-layout midpoints, observed live as "yes"/"no"
+     * stranded off-canvas at the old world coordinates while the nodes moved.
+     *
+     * Emptying the polyline is the canonical "re-route me" state: the renderer's
+     * frame pre-pass recomputes the route from the CURRENT node/port geometry on
+     * the next paint, and `setPoints` marks the link dirty so the cached VNode
+     * cannot be reused. Only links whose endpoint nodes actually MOVED are
+     * touched — an anchored subgraph's links keep their (still valid) routes.
+     *
+     * Manual waypoints are cleared with the route, same as `setPathType` /
+     * `setRouter` do: they were authored against the pre-layout coordinates, and
+     * an empty polyline with the manual flag still set would send the renderer
+     * down its keep-the-interior-waypoints branch with no interior to keep.
+     */
+    invalidateStaleLinkRoutes(before) {
+        var _a, _b;
+        if (!this.diagram)
+            return;
+        const moved = new Set();
+        for (const node of this.diagram.getNodes()) {
+            const prev = before.get(node.id);
+            if (!prev || prev.x !== node.position.x || prev.y !== node.position.y) {
+                moved.add(node.id);
+            }
+        }
+        if (moved.size === 0)
+            return;
+        const nodeIdForPort = (portId) => { var _a; return (_a = this.diagram.getNodes().find((n) => n.getPorts().some((p) => p.id === portId))) === null || _a === void 0 ? void 0 : _a.id; };
+        for (const link of this.diagram.getLinks()) {
+            const sourceId = (_a = link.sourceNodeId) !== null && _a !== void 0 ? _a : nodeIdForPort(link.sourcePortId);
+            const targetId = (_b = link.targetNodeId) !== null && _b !== void 0 ? _b : nodeIdForPort(link.targetPortId);
+            if (!(sourceId && moved.has(sourceId)) && !(targetId && moved.has(targetId))) {
+                continue;
+            }
+            if (link.points.length > 0) {
+                link.setPoints([]);
+            }
+            if (link.getMetadata('hasManualWaypoints') === true) {
+                link.setMetadata('hasManualWaypoints', false);
+            }
+        }
+    }
+    /**
+     * Commit computed positions onto the real nodes.
+     *
+     * `setPosition()` rather than a raw write, so the spatial index, the routing
+     * obstacle map and the renderer all see the move — the wave-5 lesson: a
+     * subscription to an event nobody emits is a subscription to nothing.
+     *
+     * This is also the reason a partial result is USEFUL rather than merely
+     * honest: the best-so-far positions land on the diagram exactly like final
+     * ones, so a cancelled layout leaves a real, coherent picture behind.
+     */
+    commitLayoutPositions(nodePositions) {
+        var _a, _b;
+        for (const [nodeId, position] of nodePositions) {
+            (_b = (_a = this.diagram) === null || _a === void 0 ? void 0 : _a.getNode(nodeId)) === null || _b === void 0 ? void 0 : _b.setPosition(position.x, position.y);
+        }
+    }
+    /**
+     * Run layout off the main thread.
+     *
+     * The engine does NOT construct the Worker — that would bake one bundler's URL
+     * scheme into the engine, which is exactly what the old (never-instantiated)
+     * `LayoutWorkerPool` did with its hardcoded `/assets/workers/layout.worker.js`.
+     * The caller builds the worker however its toolchain likes and hands it in:
+     *
+     *     const worker = new Worker(new URL('./layout.worker', import.meta.url),
+     *                               { type: 'module' });
+     *     engine.setLayoutPort(worker as unknown as LayoutPort);
+     *
+     * Pass `undefined` to go back to running inline.
+     */
+    setLayoutPort(port) {
+        this.layoutPort = port;
+        this.layoutHost = undefined; // rebuilt lazily against the new port
+    }
+    getLayoutHost() {
+        if (!this.layoutHost) {
+            this.layoutHost = new layout_host_1.LayoutHost(this.layoutPort, {
+                // Inline runs resolve against the LIVE registry, so a layout registered
+                // at runtime (or a built-in that a host has replaced) is honoured. A
+                // real worker cannot: functions do not survive postMessage.
+                resolve: (layoutName) => { var _a; return (_a = this.getLayoutRegistry().get(layoutName)) === null || _a === void 0 ? void 0 : _a.adapter; },
+            });
+        }
+        return this.layoutHost;
+    }
+    /**
+     * Apply layout to current diagram
+     *
+     * @param config - Layout configuration
+     * @returns Layout result with positions and metadata
+     * @throws Error if no diagram is loaded or layout service is not initialized
+     * @deprecated Wave 7 Card 0 — use {@link layout} instead. This path requires a
+     * `setLayoutService()` call that nothing ever made, so it always threw.
+     */
+    applyLayout(config) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            if (!this.diagram) {
+                throw new Error('No diagram loaded');
+            }
+            if (!this.layoutService) {
+                throw new Error('LayoutService not initialized. Call setLayoutService() first.');
+            }
+            return this.layoutService.applyLayout(this.diagram, config);
+        });
+    }
+    /**
+     * Quick helper: Apply Dagre layout
+     *
+     * @param options - Dagre layout options
+     * @param canvasDimensions - Optional canvas dimensions for viewport fitting
+     * @returns Layout result
+     */
+    applyDagreLayout(options, canvasDimensions) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return this.applyLayout({
+                adapter: 'dagre',
+                options,
+                animate: true,
+                fit: false, // Don't auto-fit by default to allow user control
+                canvasDimensions,
+            });
+        });
+    }
+    /**
+     * Quick helper: Apply ELK layout
+     *
+     * @param options - ELK layout options
+     * @param canvasDimensions - Optional canvas dimensions for viewport fitting
+     * @returns Layout result
+     */
+    applyELKLayout(options, canvasDimensions) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return this.applyLayout({
+                adapter: 'elk',
+                options,
+                animate: true,
+                fit: false, // Don't auto-fit by default to allow user control
+                canvasDimensions,
+            });
+        });
+    }
+    /**
+     * Cleanup and dispose of all resources
+     * Should be called when the engine is no longer needed
+     */
+    dispose() {
+        // Clear diagram
+        if (this.diagram) {
+            this.diagram.clear();
+            this.diagram = null;
+        }
+        // Clear command history
+        this.commandManager.clear();
+        // Clear performance data
+        this.performanceMonitor.clear();
+        // Clear clipboard
+        this.clipboardManager.clear();
+    }
+}
+exports.DiagramEngine = DiagramEngine;
+//# sourceMappingURL=DiagramEngine.js.map