@grafloria/element 0.3.18 → 0.3.20

package/src/libs/engine/src/models/DiagramModel.js

@@ -0,0 +1,2416 @@
+"use strict";
+// DiagramModel - Root container for all diagram entities
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiagramModel = exports.DEFAULT_PORT_SNAP_RADIUS = void 0;
+const tslib_1 = require("tslib");
+const DiagramEntity_1 = require("./DiagramEntity");
+const readonly_lock_1 = require("./readonly-lock"); // Wave 9 — Card 7
+const NodeModel_1 = require("./NodeModel");
+const LinkModel_1 = require("./LinkModel");
+const PortModel_1 = require("./PortModel");
+const GroupModel_1 = require("./GroupModel"); // Phase 1.6c
+const StrokeModel_1 = require("./StrokeModel"); // wave10/whiteboard
+const SpatialIndex_1 = require("../performance/SpatialIndex"); // Phase 5.1
+const performance_types_1 = require("../types/performance.types"); // wave2/rendering
+const LayoutManager_1 = require("../layout/LayoutManager"); // Layout system
+const geometry_1 = require("../utils/geometry"); // Phase 3.3
+const DiagramMigrations_1 = require("../serialization/DiagramMigrations");
+const DiagramValidator_1 = require("../serialization/DiagramValidator");
+const Incremental_1 = require("../serialization/Incremental");
+const deep_clone_1 = require("../utils/deep-clone");
+/**
+ * How near a port must be to a point for {@link DiagramModel.findNearestPort} to
+ * consider it, in world units. Roughly a fingertip at 100% zoom.
+ */
+exports.DEFAULT_PORT_SNAP_RADIUS = 24;
+/**
+ * Slack added to the node-candidate search in {@link DiagramModel.findNearestPort},
+ * to cover ports pushed off their node's bounding box by `port.offset`.
+ */
+const PORT_OFFSET_PAD = 64;
+class DiagramModel extends DiagramEntity_1.DiagramEntity {
+    /** The comment register tree. Read-only in spirit: write through writeCommentRegister. */
+    get comments() {
+        return this._comments;
+    }
+    /**
+     * The landing pad for `applyOp`'s whole-tree write (remote ops, replay, load).
+     *
+     * Coarse ON PURPOSE at this level: applyOp hands us the rebuilt tree, and all we owe
+     * the world is "the comments changed". The FINE-grained registers — the thing that
+     * decides whether two concurrent replies both survive — are cut in the OPS, not here
+     * (see writeCommentRegister and comments/types.ts).
+     */
+    set comments(next) {
+        const old = this._comments;
+        if (old === next)
+            return;
+        this._comments = next !== null && next !== void 0 ? next : {};
+        this.trackChange('comments', old, this._comments);
+    }
+    /**
+     * Write ONE comment register — `t1.status`, `t1.messages.m3` — and nothing else.
+     *
+     * This is the LOCAL authoring path, and the granularity here becomes the granularity
+     * of the emitted op (OpCapture turns `trackChange('comments.t1.messages.m3')` into
+     * `set(diagram, path='comments.t1.messages.m3')`), which becomes the granularity of
+     * the LWW register, which is what decides whether your colleague's simultaneous reply
+     * survives. The dotted path is not a convenience. It is the concurrency semantics.
+     *
+     * Returns false when the write changes nothing — so a redundant resolve is not an op,
+     * not a broadcast, and not a frame.
+     */
+    writeCommentRegister(path, value) {
+        const parts = path.split('.');
+        if (parts.length < 2 || parts.some((p) => !p)) {
+            throw new Error(`invalid comment register path: '${path}'`);
+        }
+        // A WRITE THAT CHANGES NOTHING MUST DO NOTHING — the same discipline applySet keeps,
+        // and for the same reason: a redundant register write would otherwise mint an op,
+        // broadcast it, bump the version and force a frame, forever, on every duplicate
+        // delivery and every re-resolve of an already-resolved thread.
+        const cur = this.readCommentRegister(path);
+        const cloned = value === undefined ? undefined : (0, deep_clone_1.deepClone)(value);
+        if ((0, deep_clone_1.deepEqual)(cur, cloned))
+            return false;
+        let holder = this._comments;
+        for (let i = 0; i < parts.length - 1; i++) {
+            const k = parts[i];
+            const child = holder[k];
+            holder[k] =
+                typeof child === 'object' && child !== null && !Array.isArray(child) ? child : {};
+            holder = holder[k];
+        }
+        holder[parts[parts.length - 1]] = cloned;
+        // The funnel. `comments.<path>` is exactly the op path OpCapture will emit.
+        this.trackChange(`comments.${path}`, cur, cloned);
+        return true;
+    }
+    /** Read one register. Returns undefined for any missing segment — never throws. */
+    readCommentRegister(path) {
+        let cur = this._comments;
+        for (const part of path.split('.')) {
+            if (typeof cur !== 'object' || cur === null)
+                return undefined;
+            cur = cur[part];
+        }
+        return cur;
+    }
+    constructor(name, options) {
+        var _a;
+        // id/uuid pass-through exists so deserialization can reproduce the SAVED
+        // diagram identity instead of minting a new one (lossless round-trip).
+        super(options === null || options === void 0 ? void 0 : options.id, options === null || options === void 0 ? void 0 : options.uuid);
+        this.name = 'Untitled Diagram';
+        this.nodes = new Map();
+        this.links = new Map();
+        this.groups = new Map(); // Phase 1.6c
+        /** wave10/whiteboard: freehand ink strokes. See StrokeModel for why these are not nodes. */
+        this.strokes = new Map();
+        /**
+         * Wave 9 — Card 7. The read-only lock. THE enforcement point for
+         * `DiagramMode.VIEW` / `PRESENTATION`, which before this wave were advisory flags
+         * that gated nothing at all (see ./readonly-lock.ts).
+         *
+         * Kept on the model rather than the engine because the model is what the mutators
+         * live on, and a lock the mutator cannot see is not a lock. `NodeModel` reaches it
+         * via its `diagram` back-reference; `LinkModel` via the one this wave added
+         * (`installLink`), without which every waypoint / label / reconnect edit — all of
+         * which are `LinkModel` methods — would have been an unguardable hole.
+         */
+        this.readonlyLock = new readonly_lock_1.ReadonlyLock();
+        // O(1) port -> owning node/port lookup. Maintained whenever nodes or ports
+        // are added/removed so callers (renderer per-frame link resolution, routing,
+        // connection validation) never linear-scan every node's ports.
+        this.portIndex = new Map();
+        /**
+         * wave14/model — LAST-KNOWN ANCHORS of removed nodes. The tolerant-reader half of the
+         * soft-reference (quarantine) design; see {@link DetachedParentAnchor} for the shape and
+         * {@link removeNode} for the design argument.
+         *
+         * DERIVED, SESSION-LOCAL STATE — never serialized, never on the wire. In collab, each
+         * peer records the anchor when IT applies the removal; since the parent's registers are
+         * LWW-converged before either peer applies the remove, peers freeze orphans at the same
+         * spot. (The one divergence window: a move-parent op racing the delete-parent op can be
+         * applied on one peer and refused-as-late on another, so their anchors — a reading taken
+         * at apply time — can differ until the parent is restored. The DOCUMENT still converges;
+         * only the derived freeze can briefly disagree, the same tier of divergence as any other
+         * derived presentation state.)
+         *
+         * Lifecycle: written by removeNode (every removal path funnels through it — Delete key,
+         * setNodes diffs, collab remove ops, patches), erased by installNode the moment the id
+         * comes back (undo, redo, remote resurrect), cleared wholesale by clearNodes/dispose.
+         * Bounded by the number of distinct ids removed-and-not-restored in a session.
+         */
+        this.detachedAnchors = new Map();
+        /**
+         * Wave 10 — who owns the invariant "a link whose node is gone is not a link"?
+         *
+         * `'model'` (the default): {@link removeNode} CASCADES — it removes the links attached
+         * to the node it removes. This is the right answer for an ordinary single-user document,
+         * and its absence was a real bug: deleting a node left its edges in `getLinks()` and on
+         * the screen, through every removal path there is.
+         *
+         * `'external'`: something with a BETTER answer owns it, and the cascade must keep its
+         * hands off. Specifically {@link ReferentialIntegrity} (wave 9, collab), which derives
+         * liveness from the presence registers and QUARANTINES an orphaned link instead of
+         * destroying it — so undoing the node delete, or a peer resurrecting the node, brings the
+         * links back too, including links this peer never saw. A hard cascade there would be
+         * irreversible (a `remove link` op puts "removed" in the register for good), chatty (N
+         * derived ops on the wire), and still wrong in the only case that matters — the
+         * concurrent one, where it cannot see the link a colleague is drawing right now.
+         *
+         * The Replica sets this when it attaches. Nothing else should touch it.
+         */
+        this.linkIntegrityOwner = 'model';
+        // =========================================================================
+        // wave9/comments — Card 6: THE COMMENT REGISTER NAMESPACE.
+        //
+        // Comment threads are DOCUMENT DATA and they live here, on the model, as a plain
+        // JSON tree — so that they ride the Card 0 op log exactly like a node's position
+        // does, and inherit its convergence, transport, persistence and undo without a
+        // single line of parallel machinery. `libs/engine/src/comments` owns the shape;
+        // this class owns only the storage and the change funnel.
+        //
+        // WHY AN ACCESSOR PAIR AND NOT A PLAIN FIELD — this is the load-bearing part, and
+        // it is not obvious:
+        //
+        //   A remote comment op is applied by `applyOp` → `setDiagramProp`, whose generic
+        //   branch ends in `holder['comments'] = next`, a RAW ASSIGNMENT. A raw assignment
+        //   to a plain field mutates the model INVISIBLY: no trackChange, no version bump,
+        //   no markDirty, and therefore no bump of the renderer's global mutation epoch.
+        //   And the renderer's frame gate (wave 8) skips a frame outright when the epoch
+        //   and the viewport are unchanged. A teammate's comment would land in the model
+        //   and NEVER BE DRAWN — the exact class of bug the frame gate has already caused
+        //   on three branches.
+        //
+        //   Making `comments` an accessor turns that raw assignment into the model's own
+        //   change funnel. The op lands, trackChange fires, the epoch moves, the gate opens,
+        //   the pin appears. No renderer-side special case, no `invalidateFrame()` sprinkled
+        //   at call sites that will be forgotten — the mechanism that already exists is made
+        //   to see the write.
+        // =========================================================================
+        this._comments = {};
+        this.viewport = {
+            x: 0,
+            y: 0,
+            width: 1200, // Default viewport width
+            height: 800, // Default viewport height
+            zoom: 1,
+        };
+        this._autoLayoutEnabled = false;
+        // Batch update support for event queueing
+        this._pendingEvents = [];
+        // Tiers pre-sorted highest-minZoom first so getLODLevel() is a linear scan,
+        // not a per-call sort. Kept in sync whenever _lodConfig changes.
+        this._lodTiersDesc = [];
+        if (name)
+            this.name = name;
+        // wave2/rendering: install the LOD policy (custom or default).
+        this._lodConfig = (_a = options === null || options === void 0 ? void 0 : options.lodConfig) !== null && _a !== void 0 ? _a : (0, performance_types_1.createDefaultLODConfig)();
+        this._resortLODTiers();
+        // Initialize layout manager
+        this._layoutManager = new LayoutManager_1.LayoutManager(this, 'grid');
+        // Phase 5.1: Initialize spatial indices
+        this.nodeSpatialIndex = new SpatialIndex_1.SpatialIndex({
+            cellSize: 100,
+            getBounds: (node) => {
+                // Get bounds considering rotation and scale
+                const bounds = node.getBoundingBox();
+                return {
+                    x: bounds.left,
+                    y: bounds.top,
+                    width: bounds.width,
+                    height: bounds.height,
+                };
+            },
+        });
+        this.linkSpatialIndex = new SpatialIndex_1.SpatialIndex({
+            cellSize: 100,
+            getBounds: (link) => this.computeLinkBounds(link),
+        });
+    }
+    /**
+     * Bounding box of a link, for viewport culling (`getVisibleLinks`).
+     *
+     * It is the union of TWO things, and it needs both:
+     *
+     *  - `link.points` — the routed path (including orthogonal detours). Renderers
+     *    write this back per frame, so for anything that has been drawn it is the
+     *    real geometry.
+     *  - the LIVE endpoints, resolved O(1) through the port index. Points alone are
+     *    not trustworthy: a link built with `new LinkModel()` + `addLink()` has NO
+     *    points until something routes it (it would otherwise be indexed as a
+     *    zero-size box at the world origin and get culled everywhere except there),
+     *    and points go stale the moment a node moves without a reroute. The drawn
+     *    path always runs between the live ports, so folding them in keeps the box
+     *    a correct SUPERSET of what will actually be painted.
+     *
+     * Being a superset is the safe direction: culling too little costs a few
+     * VNodes, culling too much makes edges vanish off-screen.
+     */
+    computeLinkBounds(link) {
+        let minX = Infinity;
+        let minY = Infinity;
+        let maxX = -Infinity;
+        let maxY = -Infinity;
+        const include = (point) => {
+            minX = Math.min(minX, point.x);
+            minY = Math.min(minY, point.y);
+            maxX = Math.max(maxX, point.x);
+            maxY = Math.max(maxY, point.y);
+        };
+        for (const point of link.points) {
+            include(point);
+        }
+        const source = this.portIndex.get(link.sourcePortId);
+        if (source) {
+            include(source.port.getAbsolutePosition(source.node.getBoundingBox()));
+        }
+        const target = this.portIndex.get(link.targetPortId);
+        if (target) {
+            include(target.port.getAbsolutePosition(target.node.getBoundingBox()));
+        }
+        if (minX === Infinity) {
+            // Nothing to go on (no points, no resolvable ports).
+            return { x: 0, y: 0, width: 0, height: 0 };
+        }
+        return {
+            x: minX,
+            y: minY,
+            width: maxX - minX,
+            height: maxY - minY,
+        };
+    }
+    /**
+     * Re-index a link after its geometry changed WITHOUT a `change:points` event.
+     *
+     * Renderers route links per frame and assign `link.points` directly (using
+     * `setPoints()` would emit `change` → `link:changed` → another render, i.e. a
+     * render loop). The spatial index therefore never hears about the routed path,
+     * and its grid cells would keep pointing at the geometry the link had when it
+     * was added. Call this after writing points directly.
+     */
+    refreshLinkBounds(link) {
+        if (!this.links.has(link.id))
+            return;
+        this.linkSpatialIndex.update(link);
+    }
+    /**
+     * Add node to diagram
+     */
+    // ==========================================================================
+    // Wave 9 — Card 7: the read-only lock (see ./readonly-lock.ts).
+    // ==========================================================================
+    /** Is this document locked against edits? */
+    isReadonly() {
+        return this.readonlyLock.isReadonly();
+    }
+    /**
+     * Lock / unlock the document. Normally driven by `DiagramEngine.setMode()` —
+     * VIEW and PRESENTATION lock, DESIGNER unlocks — so `DiagramMode` finally means
+     * something. Can also be set directly for a host that has no mode concept.
+     */
+    setReadonly(value) {
+        if (this.readonlyLock.isReadonly() === value)
+            return;
+        this.readonlyLock.setReadonly(value);
+        this.emitOrQueue('readonly:change', value);
+    }
+    /** True when a document mutation must be refused right now. */
+    blocksDocumentWrite() {
+        return this.readonlyLock.blocksDocumentWrite();
+    }
+    /**
+     * True while a SYSTEM write is in flight. Read by the PER-NODE geometry lock
+     * (`NodeState.locked`) so it exempts measured writes exactly as the document
+     * lock does — see readonly-lock.ts.
+     */
+    inSystemWrite() {
+        return this.readonlyLock.inSystemWrite();
+    }
+    /**
+     * Run a SYSTEM write — a derived/measured value (auto-size, portal placement)
+     * the engine needs in order to render the document as it already is. Permitted
+     * even while locked. NOT reachable from user input; see readonly-lock.ts.
+     */
+    runSystemWrite(fn) {
+        return this.readonlyLock.runSystemWrite(fn);
+    }
+    addNode(node) {
+        this.assertNotDisposed(); // Phase 5.4
+        if (this.blocksDocumentWrite())
+            return;
+        if (this.nodes.has(node.id)) {
+            throw new Error(`Node with id ${node.id} already exists`);
+        }
+        this.installNode(node);
+    }
+    /**
+     * THE single per-node install path — every route a node takes into the
+     * diagram (interactive addNode, undo restoreNode, document fromJSON) runs
+     * through here, so a restored node is wired IDENTICALLY to an authored one:
+     * diagram back-reference, change tracking, events, port index, spatial
+     * index, and change-forwarding listeners.
+     */
+    installNode(node) {
+        // Set diagram reference (Phase 1.6a)
+        node.diagram = this;
+        // wave14/model — the id is LIVE again (undo, redo, remote resurrect): drop its
+        // last-known anchor so parent chains resolve through the real node, not the freeze.
+        this.detachedAnchors.delete(node.id);
+        this.nodes.set(node.id, node);
+        this.trackChange('nodes', null, node);
+        this.emitOrQueue('node:added', node);
+        // Maintain O(1) port -> node index (covers ports added before AND after
+        // the node joins the diagram)
+        this.indexNodePorts(node);
+        // Phase 5.1: Add to spatial index and listen for spatial changes
+        // Do this AFTER trackChange to avoid cloning issues
+        this.nodeSpatialIndex.add(node);
+        const updateSpatialIndex = () => this.nodeSpatialIndex.update(node);
+        node.on('change:position', updateSpatialIndex);
+        node.on('change:size', updateSpatialIndex);
+        node.on('change:rotation', updateSpatialIndex);
+        node.on('change:scale', updateSpatialIndex);
+        // Phase 0.2: Forward position and size changes as diagram-level events for LiveReroutingEngine
+        node.on('change:position', () => {
+            this.emitOrQueue('node:moved', { nodeId: node.id, position: node.position });
+        });
+        node.on('change:size', () => {
+            this.emitOrQueue('node:resized', { nodeId: node.id, size: node.size });
+        });
+        // Listen for any node changes and forward as diagram-level 'node:changed' event
+        // This allows components like diagram-canvas to re-render when node properties change
+        node.on('change', () => {
+            this.emitOrQueue('node:changed', node);
+        });
+        // A transform on a parent MOVES its relative children in the world without
+        // touching their own properties. The node already announces exactly who is
+        // affected ('transform-propagated', Phase 1.6a Part 4) — but nothing ever
+        // consumed it, so renderers kept stale child VNodes and the spatial index
+        // kept stale child bounds. markDirty (not trackChange: nothing on the child
+        // itself changed — no version bump, no change-log entry, no collab op)
+        // rebakes the picture; the index update and node:moved keep culling,
+        // hit-testing and live link rerouting truthful.
+        node.on('transform-propagated', (payload) => {
+            var _a;
+            for (const desc of (_a = payload === null || payload === void 0 ? void 0 : payload.affectedNodes) !== null && _a !== void 0 ? _a : []) {
+                if (desc === node)
+                    continue;
+                desc.markDirty('incremental');
+                this.nodeSpatialIndex.update(desc);
+                this.emitOrQueue('node:moved', { nodeId: desc.id, position: desc.getWorldPosition() });
+                this.emitOrQueue('node:changed', desc);
+            }
+        });
+    }
+    /**
+     * Remove node from diagram — AND every link attached to it.
+     *
+     * Wave 10 BUG FIX. This used to delete the node and nothing else, so every link that
+     * touched it survived: still in `getLinks()`, still in the spatial index, and still
+     * PAINTED — two edges hanging off a node that no longer existed. `deleteSelected()`
+     * carried the comment "this will also trigger link cleanup via events"; nothing
+     * listened to `node:removed` for cleanup, so that cleanup never happened, anywhere.
+     *
+     * It matters because EVERY removal path funnels through here:
+     *   - `deleteSelected()` — what the Delete key calls;
+     *   - `applyNodes()` — what `setNodes()` calls, so dropping a node from a React-shaped
+     *     spec left the dangling links behind;
+     *   - `RemoveNodeCommand`.
+     *
+     * A link's endpoints are the invariant that makes it a link; a link to nowhere is not
+     * a link. So the cascade belongs at the choke point, not at each of the three call
+     * sites that would each have to remember it.
+     *
+     * UNLESS someone better owns that invariant — see {@link linkIntegrityOwner}.
+     */
+    removeNode(nodeId) {
+        if (this.blocksDocumentWrite())
+            return undefined;
+        const node = this.nodes.get(nodeId);
+        if (node) {
+            // wave14/model — record the LAST-KNOWN ANCHOR before any teardown, while the
+            // node can still resolve its own parent chain.
+            //
+            // Removal deliberately leaves soft refs dangling: children's `parentId` and the
+            // id inside `GroupModel.members` keep pointing here. THE DANGLE IS THE DESIGN,
+            // not an oversight — the two alternatives are both worse:
+            //
+            //   • HARD-CLEARING the refs at delete time is irreversible under collab/undo.
+            //     Undo-of-parent-delete restores children exactly BECAUSE the ref dangles
+            //     and re-resolves; clearing it would need a compensating write per child,
+            //     and a peer that never saw those writes diverges. It is the cascade trap
+            //     collab/integrity.ts documents for links, in parentId form.
+            //   • RE-ANCHORING children here via tracked position writes (position +=
+            //     parentWorld, parentId = undefined) mutates entities the user did not
+            //     touch: in collab each rewrite becomes an op that races a peer's real
+            //     concurrent drag of that child (LWW picks one whole write — either the
+            //     re-anchor clobbers the drag or the drag re-interprets its offset in a
+            //     frame that no longer exists), and undo of the delete is no longer one
+            //     inverse op but 1+N that nothing transacts across the remote/patch paths.
+            //
+            //   So: QUARANTINE the refs (keep them, derived readers tolerate them) — the
+            //   document is never touched, undo re-adds the parent and the chain re-resolves
+            //   byte-identically by construction. The anchor below is what the tolerant
+            //   readers freeze orphaned children at, so they stop jumping to raw offsets.
+            this.detachedAnchors.set(nodeId, {
+                world: node.getWorldPosition(),
+                global: node.getGlobalPosition(),
+                rotation: node.rotation,
+                scale: Object.assign({}, node.scale),
+                matrix: node.getGlobalTransformMatrix(),
+            });
+            // Links first, while the node's ports are still in the index — removeLink()
+            // resolves them to release the ports' connection bookkeeping.
+            if (this.linkIntegrityOwner === 'model') {
+                for (const link of this.getLinksForNode(nodeId)) {
+                    this.removeLink(link.id);
+                }
+            }
+            this.nodes.delete(nodeId);
+            // Drop this node's ports from the O(1) port index
+            this.unindexNodePorts(node);
+            // Phase 5.1: Remove from spatial index
+            this.nodeSpatialIndex.remove(nodeId);
+            this.trackChange('nodes', node, null);
+            this.emitOrQueue('node:removed', node);
+            // wave14/model — mirror of installNode's `node.diagram = this` (dispose() already
+            // clears it; this was the one detach path that did not). Deliberately LAST:
+            // OpCapture serializes the node's full removal snapshot and unwatches it inside the
+            // trackChange emission above (capture.ts), and synchronous 'node:removed' listeners
+            // may still resolve through the owning diagram — so the ref must survive both.
+            // (Under batch mode the queued 'node:removed' flushes after this line and sees a
+            // detached node — correct by then: the node no longer belongs to any diagram.)
+            // Clearing restores the documented "detached node" status: freely mutable, no stale
+            // read-only lock, no strong ref pinning the whole diagram, re-addable anywhere.
+            node.diagram = undefined;
+        }
+        return node;
+    }
+    /**
+     * Every link with an endpoint on `nodeId` (either end, including a self-loop).
+     *
+     * Resolved through the port index rather than the cached `sourceNodeId`/`targetNodeId`,
+     * because those are a backfill that can be absent on a link built by hand.
+     */
+    getLinksForNode(nodeId) {
+        var _a, _b, _c, _d;
+        const out = [];
+        for (const link of this.links.values()) {
+            const source = (_b = (_a = this.getNodeByPortId(link.sourcePortId)) === null || _a === void 0 ? void 0 : _a.id) !== null && _b !== void 0 ? _b : link.sourceNodeId;
+            const target = (_d = (_c = this.getNodeByPortId(link.targetPortId)) === null || _c === void 0 ? void 0 : _c.id) !== null && _d !== void 0 ? _d : link.targetNodeId;
+            if (source === nodeId || target === nodeId)
+                out.push(link);
+        }
+        return out;
+    }
+    /**
+     * Restore node from serialized data (Phase 1.8)
+     */
+    restoreNode(data) {
+        try {
+            const node = NodeModel_1.NodeModel.fromJSON(data);
+            this.installNode(node);
+            return node;
+        }
+        catch (error) {
+            console.error('Failed to restore node:', error);
+            return undefined;
+        }
+    }
+    /**
+     * Get node by ID
+     */
+    getNode(nodeId) {
+        return this.nodes.get(nodeId);
+    }
+    /**
+     * Get all nodes
+     */
+    getNodes() {
+        return Array.from(this.nodes.values());
+    }
+    /**
+     * Phase 3: Get node that owns a specific port
+     * Used for connection group validation and other port-based queries.
+     * O(1) via the portIndex (was an O(nodes×ports) linear scan).
+     */
+    getNodeByPortId(portId) {
+        var _a;
+        return (_a = this.portIndex.get(portId)) === null || _a === void 0 ? void 0 : _a.node;
+    }
+    /**
+     * Get the port model for a port id, O(1) via the portIndex.
+     * Companion to getNodeByPortId for callers that need the port itself.
+     */
+    getPortById(portId) {
+        var _a;
+        return (_a = this.portIndex.get(portId)) === null || _a === void 0 ? void 0 : _a.port;
+    }
+    /**
+     * wave14/model — the last-known anchor of a REMOVED node, or undefined if the id is
+     * live, was never here, or the anchor was wholesale-cleared. The tolerant readers in
+     * NodeModel (getWorldPosition / getGlobalPosition / getGlobalTransformMatrix /
+     * setGlobalPosition) resolve an unresolvable parent through this so orphaned relative
+     * children freeze in place instead of jumping to their raw offsets. See
+     * {@link detachedAnchors} and the design argument on {@link removeNode}.
+     */
+    getDetachedAnchor(nodeId) {
+        return this.detachedAnchors.get(nodeId);
+    }
+    /**
+     * Index every current port of a node and keep the index current as ports are
+     * added/removed on that node. Called from addNode/restoreNode/fromJSON.
+     * Listeners are guarded so a removed node can never re-pollute the index.
+     */
+    indexNodePorts(node) {
+        for (const port of node.getPorts()) {
+            this.portIndex.set(port.id, { node, port });
+        }
+        // Keep the index correct when ports change AFTER the node is in the diagram.
+        node.on('port:added', (port) => {
+            // Ignore late additions from a node that is no longer this diagram's.
+            if (this.nodes.get(node.id) === node) {
+                this.portIndex.set(port.id, { node, port });
+            }
+        });
+        node.on('port:removed', (port) => {
+            const entry = this.portIndex.get(port.id);
+            if (entry && entry.node === node) {
+                this.portIndex.delete(port.id);
+            }
+        });
+    }
+    /**
+     * Drop a node's ports from the index (called on removeNode).
+     */
+    unindexNodePorts(node) {
+        for (const port of node.getPorts()) {
+            const entry = this.portIndex.get(port.id);
+            if (entry && entry.node === node) {
+                this.portIndex.delete(port.id);
+            }
+        }
+    }
+    /**
+     * Clear all nodes
+     */
+    clearNodes() {
+        if (this.blocksDocumentWrite())
+            return;
+        this.nodes.clear();
+        this.portIndex.clear();
+        // Wholesale reset: no nodes remain to read a frozen frame through.
+        this.detachedAnchors.clear();
+        this.emitOrQueue('nodes:cleared');
+    }
+    /**
+     * Add link to diagram
+     */
+    addLink(link) {
+        this.assertNotDisposed(); // Phase 5.4
+        if (this.blocksDocumentWrite())
+            return;
+        if (this.links.has(link.id)) {
+            throw new Error(`Link with id ${link.id} already exists`);
+        }
+        this.installLink(link);
+    }
+    /**
+     * THE single per-link install path (see installNode) — interactive add,
+     * undo restore, and document load all wire links identically, including
+     * the owning-node-id backfill renderers resolve port sides through.
+     */
+    installLink(link) {
+        var _a, _b, _c, _d;
+        // Wave 9 — Card 7. The diagram back-reference. NodeModel has had one since
+        // Phase 1.6a; LinkModel never did — which meant every waypoint, control-point,
+        // label and reconnect edit (all LinkModel methods) could not see a read-only
+        // lock and was therefore unguardable. Symmetric with installNode.
+        link.diagram = this;
+        // Cache the owning node ids (renderers resolve port sides through them —
+        // without this, links built via `new LinkModel()` + addLink never resolve
+        // port direction, unlike connectNodes() which sets the ids itself)
+        if (!link.sourceNodeId) {
+            link.sourceNodeId = (_a = this.getNodeByPortId(link.sourcePortId)) === null || _a === void 0 ? void 0 : _a.id;
+        }
+        if (!link.targetNodeId) {
+            link.targetNodeId = (_b = this.getNodeByPortId(link.targetPortId)) === null || _b === void 0 ? void 0 : _b.id;
+        }
+        // Wave 10 BUG FIX — register the link on its PORTS.
+        //
+        // This is the single install path, and it was the ONE place that did not do the
+        // connection bookkeeping. `createSmartLink()`, `DiagramEngine`'s interactive connect
+        // and `LayoutManager` each called `port.addConnection()` by hand; a link built the
+        // ordinary way — `new LinkModel()` + `addLink()`, which is exactly what the public
+        // spec path (`setNodes`/`setEdges` → `applyEdges` → `buildEdge`) does — registered on
+        // neither port.
+        //
+        // So `port.getConnectionCount()` was 0 for every link in every spec-built diagram,
+        // and `maxConnections` — whose ONLY enforcement is `evaluatePortConnection()` reading
+        // that counter — could never fire. A port declared `maxConnections: 1` that already
+        // had its one link from the spec still believed it had none, and accepted a second.
+        //
+        // `restoreConnection`, not `addConnection`: registering an EXISTING link is a load,
+        // not a new connection, so it must not throw when a persisted graph legitimately
+        // exceeds a since-tightened limit (that is what the method was written for). It is
+        // Set-backed and therefore idempotent, so the hand-rolled call sites above — which
+        // register before calling addLink() — stay correct and do not double-count.
+        (_c = this.getPortById(link.sourcePortId)) === null || _c === void 0 ? void 0 : _c.restoreConnection(link.id, 'source');
+        (_d = this.getPortById(link.targetPortId)) === null || _d === void 0 ? void 0 : _d.restoreConnection(link.id, 'target');
+        this.links.set(link.id, link);
+        this.trackChange('links', null, link);
+        this.emitOrQueue('link:added', link);
+        // Phase 5.1: Add to spatial index and listen - AFTER trackChange
+        this.linkSpatialIndex.add(link);
+        link.on('change:points', () => this.linkSpatialIndex.update(link));
+        // generatePath() (layout, live-rerouting, node drag) rewrites `points` in
+        // place and only emits 'link:path-changed' — without this the index keeps the
+        // grid cells the link had when it was added and viewport culling loses it.
+        link.on('link:path-changed', () => this.linkSpatialIndex.update(link));
+        // Listen for any link changes and forward as diagram-level 'link:changed' event
+        link.on('change', () => {
+            this.emitOrQueue('link:changed', link);
+        });
+    }
+    /**
+     * Remove link from diagram
+     */
+    removeLink(linkId) {
+        var _a, _b;
+        if (this.blocksDocumentWrite())
+            return undefined;
+        const link = this.links.get(linkId);
+        if (link) {
+            // Wave 10 — the mirror of installLink()'s registration. Without it a removed link
+            // would keep occupying its ports' connection budget forever, and a port with a
+            // maxConnections cap would silently jam after enough add/remove churn.
+            (_a = this.getPortById(link.sourcePortId)) === null || _a === void 0 ? void 0 : _a.removeConnection(link.id);
+            (_b = this.getPortById(link.targetPortId)) === null || _b === void 0 ? void 0 : _b.removeConnection(link.id);
+            this.links.delete(linkId);
+            // Phase 5.1: Remove from spatial index
+            this.linkSpatialIndex.remove(linkId);
+            this.trackChange('links', link, null);
+            this.emitOrQueue('link:removed', link);
+        }
+        return link;
+    }
+    /**
+     * Restore link from serialized data (Phase 1.8)
+     */
+    restoreLink(data) {
+        try {
+            const link = LinkModel_1.LinkModel.fromJSON(data);
+            this.installLink(link);
+            return link;
+        }
+        catch (error) {
+            console.error('Failed to restore link:', error);
+            return undefined;
+        }
+    }
+    /**
+     * Get link by ID
+     */
+    getLink(linkId) {
+        return this.links.get(linkId);
+    }
+    /**
+     * Get all links
+     */
+    getLinks() {
+        return Array.from(this.links.values());
+    }
+    /**
+     * Phase 0.2: Get all links connected to a specific port
+     */
+    getLinksForPort(portId) {
+        return this.getLinks().filter(link => link.sourcePortId === portId || link.targetPortId === portId);
+    }
+    /**
+     * Clear all links
+     */
+    clearLinks() {
+        if (this.blocksDocumentWrite())
+            return;
+        this.links.clear();
+        this.emitOrQueue('links:cleared');
+    }
+    /**
+     * Phase 0.5.3: Create a smart link with automatic port selection
+     *
+     * This high-level API simplifies link creation by:
+     * - Automatically selecting optimal ports based on node geometry
+     * - Creating the link with proper port connections
+     * - Registering connections in port models
+     * - Generating the initial path
+     *
+     * @param sourceNode - The source node
+     * @param targetNode - The target node
+     * @param pathType - Path rendering type (default: 'smooth')
+     * @returns The created link, or undefined if port selection failed
+     *
+     * @example
+     * ```typescript
+     * const link = diagram.createSmartLink(node1, node2, 'smooth');
+     * if (link) {
+     *   console.log('Connected with optimal ports!');
+     * }
+     * ```
+     */
+    createSmartLink(sourceNode, targetNode, pathType = 'smooth') {
+        var _a, _b;
+        // Use layout manager's intelligent port selection
+        const optimalPorts = this._layoutManager.selectOptimalPorts(sourceNode, targetNode);
+        if (!optimalPorts) {
+            console.warn(`⚠️ Could not select optimal ports for nodes ${sourceNode.id} → ${targetNode.id}`);
+            return undefined;
+        }
+        const { sourcePort, targetPort } = optimalPorts;
+        // Validate port compatibility
+        if (!sourcePort.canConnectTo(targetPort)) {
+            console.warn(`⚠️ Ports are not compatible: ${sourcePort.type} → ${targetPort.type}`);
+            return undefined;
+        }
+        // Create the link
+        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
+        const sourceBounds = sourceNode.getBoundingBox();
+        const targetBounds = targetNode.getBoundingBox();
+        const sourcePoint = sourcePort.getAbsolutePosition(sourceBounds);
+        const targetPoint = targetPort.getAbsolutePosition(targetBounds);
+        // Get port directions for orthogonal 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;
+        link.generatePath(sourcePoint, targetPoint, sourceDirection, targetDirection);
+        // Add to diagram
+        this.addLink(link);
+        return link;
+    }
+    /**
+     * Phase 0.5.3: High-level API to connect two nodes
+     *
+     * Convenience method that creates a smart link and returns success status.
+     * This is the simplest way to connect nodes.
+     *
+     * @param sourceNode - The source node
+     * @param targetNode - The target node
+     * @param pathType - Path rendering type (default: 'smooth')
+     * @returns true if connection was successful, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (diagram.connectNodes(node1, node2)) {
+     *   console.log('Nodes connected successfully!');
+     * }
+     * ```
+     */
+    connectNodes(sourceNode, targetNode, pathType = 'smooth') {
+        const link = this.createSmartLink(sourceNode, targetNode, pathType);
+        return link !== undefined;
+    }
+    /**
+     * Phase 0.5.3: Get all connections for a node
+     *
+     * Returns all links where the node is either source or target.
+     * Useful for querying node connectivity.
+     *
+     * @param node - The node to query
+     * @returns Object containing incoming and outgoing links
+     *
+     * @example
+     * ```typescript
+     * const connections = diagram.getNodeConnections(node);
+     * console.log(`Incoming: ${connections.incoming.length}`);
+     * console.log(`Outgoing: ${connections.outgoing.length}`);
+     * console.log(`Total: ${connections.all.length}`);
+     * ```
+     */
+    getNodeConnections(node) {
+        const incoming = [];
+        const outgoing = [];
+        // Get node's port IDs
+        const portIds = new Set(node.getPorts().map((p) => p.id));
+        // Check all links
+        for (const link of this.links.values()) {
+            const isTarget = portIds.has(link.targetPortId);
+            const isSource = portIds.has(link.sourcePortId);
+            if (isTarget) {
+                incoming.push(link);
+            }
+            if (isSource) {
+                outgoing.push(link);
+            }
+        }
+        return {
+            incoming,
+            outgoing,
+            all: [...incoming, ...outgoing],
+        };
+    }
+    /**
+     * Phase 0.5.3: Disconnect two nodes
+     *
+     * Removes all links between the specified nodes.
+     * Handles cleanup of port connections.
+     *
+     * @param sourceNode - The source node
+     * @param targetNode - The target node
+     * @returns Number of links removed
+     *
+     * @example
+     * ```typescript
+     * const removed = diagram.disconnectNodes(node1, node2);
+     * console.log(`Removed ${removed} connections`);
+     * ```
+     */
+    disconnectNodes(sourceNode, targetNode) {
+        const sourcePortIds = new Set(sourceNode.getPorts().map((p) => p.id));
+        const targetPortIds = new Set(targetNode.getPorts().map((p) => p.id));
+        const linksToRemove = [];
+        // Find all links between these nodes
+        for (const link of this.links.values()) {
+            const hasSourcePort = sourcePortIds.has(link.sourcePortId);
+            const hasTargetPort = targetPortIds.has(link.targetPortId);
+            if (hasSourcePort && hasTargetPort) {
+                linksToRemove.push(link.id);
+            }
+        }
+        // Remove the links
+        for (const linkId of linksToRemove) {
+            const link = this.getLink(linkId);
+            if (link) {
+                // Clean up port connections
+                const sourcePort = sourceNode.getPorts().find((p) => p.id === link.sourcePortId);
+                const targetPort = targetNode.getPorts().find((p) => p.id === link.targetPortId);
+                if (sourcePort) {
+                    sourcePort.removeConnection(link.id);
+                }
+                if (targetPort) {
+                    targetPort.removeConnection(link.id);
+                }
+                // Remove link from diagram
+                this.removeLink(linkId);
+            }
+        }
+        return linksToRemove.length;
+    }
+    /**
+     * Add group (Phase 1.6c)
+     */
+    addGroup(group) {
+        if (this.blocksDocumentWrite())
+            return;
+        this.assertNotDisposed(); // Phase 5.4
+        if (this.groups.has(group.id)) {
+            throw new Error(`Group with id ${group.id} already exists`);
+        }
+        this.installGroup(group);
+    }
+    /**
+     * THE single per-group install path (see installNode). The diagram
+     * back-reference is RUNTIME wiring: GroupModel.serialize() deliberately
+     * excludes it from payloads, and this re-stashes it on every install so a
+     * loaded group can resolve its diagram exactly like an authored one.
+     */
+    installGroup(group) {
+        // Store diagram reference for layout operations. Written to the map
+        // DIRECTLY (not setMetadata): this is runtime wiring, not a user
+        // mutation — it must not bump the group's version or land in its change
+        // log, or a loaded group would report a different version than it was
+        // saved with (and every install would count as an edit).
+        group.metadata.set('diagram', this);
+        this.groups.set(group.id, group);
+        this.trackChange('groups', null, group);
+        this.emitOrQueue('group:added', group);
+        // Mirror of installNode's 'change' forwarding. Without it a group mutation
+        // (setFrame/fitToContents, membership, collapse) was invisible at the
+        // diagram level: renderers subscribed to node:/link: events repainted on
+        // every node twitch but never on a group's — the screenshot audit caught a
+        // frame that stayed 40×40 on screen after fitToContents had grown it.
+        group.on('change', () => {
+            this.emitOrQueue('group:changed', group);
+        });
+    }
+    /**
+     * Remove group (Phase 1.6c)
+     */
+    removeGroup(groupId) {
+        if (this.blocksDocumentWrite())
+            return undefined;
+        const group = this.groups.get(groupId);
+        if (group) {
+            this.groups.delete(groupId);
+            this.trackChange('groups', group, null);
+            this.emitOrQueue('group:removed', group);
+        }
+        return group;
+    }
+    /**
+     * Restore group from serialized data (Phase 1.8)
+     */
+    restoreGroup(data) {
+        try {
+            const group = GroupModel_1.GroupModel.fromJSON(data);
+            this.installGroup(group);
+            return group;
+        }
+        catch (error) {
+            console.error('Failed to restore group:', error);
+            return undefined;
+        }
+    }
+    /**
+     * Get group by ID (Phase 1.6c)
+     */
+    getGroup(groupId) {
+        return this.groups.get(groupId);
+    }
+    /**
+     * Get all groups (Phase 1.6c)
+     */
+    getGroups() {
+        return Array.from(this.groups.values());
+    }
+    /**
+     * Wave-5 Card 3: groups in deterministic back-to-front stacking order —
+     * ascending `zIndex`, ties broken by Map insertion order (a STABLE sort keeps
+     * it). This is the model-level z-order story that replaces "stacking == Map
+     * insertion order" as the only determinant; a renderer paints groups in this
+     * order (behind their members) instead of relying on iteration order.
+     */
+    getGroupsInRenderOrder() {
+        return this.getGroups().sort((a, b) => a.zIndex - b.zIndex);
+    }
+    /**
+     * Wave-5 Card 4: the placeholder "group-as-node" for a collapsed group, if
+     * present. Placeholder nodes are ordinary NodeModels tagged with the group id
+     * so callers can filter them out of exports / counts.
+     */
+    getProxyNodeForGroup(groupId) {
+        for (const node of this.nodes.values()) {
+            if (node.getMetadata('__collapsedGroupId') === groupId) {
+                return node;
+            }
+        }
+        return undefined;
+    }
+    /** Wave-5 Card 4: is this node a collapsed-group placeholder? */
+    isProxyNode(node) {
+        return node.getMetadata('__isGroupProxy') === true;
+    }
+    /**
+     * Clear all groups (Phase 1.6c)
+     */
+    clearGroups() {
+        this.groups.clear();
+        this.emitOrQueue('groups:cleared');
+    }
+    // =========================================================================
+    // wave10/whiteboard — INK
+    //
+    // Deliberately the THINNEST collection in this model. A stroke has no ports, no
+    // parent, no children, no layout participation and no obstacle registration — the
+    // four things that made "a stroke is just a node" the wrong answer (see StrokeModel).
+    // It is not spatially indexed either: strokes are annotation, they are rare compared
+    // to nodes (a busy whiteboard has tens, not tens of thousands), and the ink layer
+    // culls them with a linear bounds scan that costs microseconds at 500 strokes. If
+    // that ever stops being true, add a third SpatialIndex here — the seam is the same.
+    // =========================================================================
+    addStroke(stroke) {
+        if (this.blocksDocumentWrite())
+            return;
+        this.assertNotDisposed();
+        if (this.strokes.has(stroke.id)) {
+            throw new Error(`Stroke with id ${stroke.id} already exists`);
+        }
+        this.installStroke(stroke);
+    }
+    /** THE single per-stroke install path (see installNode) — authored, restored, or replayed. */
+    installStroke(stroke) {
+        this.strokes.set(stroke.id, stroke);
+        // The op-capture funnel. `trackChange('strokes', null, stroke)` is what makes an
+        // added stroke reach OpCapture (which maps it to an `add` op), the mutation epoch
+        // (which makes the frame gate repaint), and the dirty tracker. All three for free,
+        // and all three ONLY because a stroke is a real DiagramEntity in a real collection.
+        this.trackChange('strokes', null, stroke);
+        this.emitOrQueue('stroke:added', stroke);
+    }
+    removeStroke(strokeId) {
+        if (this.blocksDocumentWrite())
+            return undefined;
+        const stroke = this.strokes.get(strokeId);
+        if (stroke) {
+            this.strokes.delete(strokeId);
+            this.trackChange('strokes', stroke, null);
+            this.emitOrQueue('stroke:removed', stroke);
+        }
+        return stroke;
+    }
+    restoreStroke(data) {
+        try {
+            const stroke = StrokeModel_1.StrokeModel.fromJSON(data);
+            this.installStroke(stroke);
+            return stroke;
+        }
+        catch (error) {
+            console.error('Failed to restore stroke:', error);
+            return undefined;
+        }
+    }
+    getStroke(strokeId) {
+        return this.strokes.get(strokeId);
+    }
+    getStrokes() {
+        return Array.from(this.strokes.values());
+    }
+    clearStrokes() {
+        this.strokes.clear();
+        this.emitOrQueue('strokes:cleared');
+    }
+    /** Strokes whose bounds overlap `viewport`. The ink layer's culling query. */
+    getVisibleStrokes(viewport) {
+        const out = [];
+        for (const stroke of this.strokes.values()) {
+            const b = stroke.getBounds();
+            if (b.x <= viewport.x + viewport.width &&
+                b.x + b.width >= viewport.x &&
+                b.y <= viewport.y + viewport.height &&
+                b.y + b.height >= viewport.y) {
+                out.push(stroke);
+            }
+        }
+        return out;
+    }
+    /**
+     * Every stroke the pointer swept across travelling `a`→`b`. THE ERASER'S QUERY.
+     *
+     * Segment-based, not point-based: a fast flick puts 80px between two pointermove
+     * samples, and an eraser that only tested the samples would jump clean over a stroke
+     * it visibly wiped through. Ask what the pointer TRAVELLED THROUGH, not where it
+     * happened to land.
+     */
+    getStrokesAlongSegment(a, b, tolerance = 0) {
+        const out = [];
+        for (const stroke of this.strokes.values()) {
+            if (stroke.intersectsSegment(a, b, tolerance))
+                out.push(stroke);
+        }
+        return out;
+    }
+    /**
+     * Compound-graph containment (Wave-2)
+     *
+     * These derive the nesting tree from each GroupModel.parentGroupId pointer,
+     * which addMember/removeMember/setParent keep authoritative. Coordinates stay
+     * ABSOLUTE across the codebase; nesting is purely a logical containment tree.
+     */
+    /**
+     * Get a group's ancestor chain (nearest parent first), walking parentGroupId
+     * upward. Robust against malformed self/looping pointers.
+     */
+    getAncestors(groupId) {
+        const result = [];
+        const seen = new Set([groupId]);
+        let current = this.groups.get(groupId);
+        while (current && current.parentGroupId) {
+            if (seen.has(current.parentGroupId)) {
+                break; // defensive: never loop on a corrupt pointer
+            }
+            const parent = this.groups.get(current.parentGroupId);
+            if (!parent) {
+                break;
+            }
+            result.push(parent);
+            seen.add(parent.id);
+            current = parent;
+        }
+        return result;
+    }
+    /**
+     * Get every group nested (directly or transitively) inside `groupId`.
+     * Breadth-first over the parentGroupId back-pointers.
+     */
+    getDescendants(groupId) {
+        const result = [];
+        const seen = new Set([groupId]);
+        const queue = [groupId];
+        while (queue.length > 0) {
+            const currentId = queue.shift();
+            for (const group of this.groups.values()) {
+                if (group.parentGroupId === currentId && !seen.has(group.id)) {
+                    seen.add(group.id);
+                    result.push(group);
+                    queue.push(group.id);
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Nesting depth of a group: number of ancestors (0 for a top-level group).
+     */
+    getDepth(groupId) {
+        return this.getAncestors(groupId).length;
+    }
+    /**
+     * Selection Management
+     */
+    /**
+     * Get all selected nodes
+     */
+    getSelectedNodes() {
+        return this.getNodes().filter((node) => node.isSelected());
+    }
+    /**
+     * Select a single node (clears previous selection)
+     * @param node - Node to select
+     */
+    selectNode(node) {
+        if (!node.isSelectable()) {
+            return;
+        }
+        // Clear previous selection
+        this.clearSelection();
+        // Select the node
+        node.setSelected(true);
+        // Emit selection changed event
+        this.emitOrQueue('selection:changed', {
+            selected: [node],
+            deselected: []
+        });
+    }
+    /**
+     * Add node to selection (multi-select)
+     * @param node - Node to add to selection
+     */
+    addToSelection(node) {
+        if (!node.isSelectable() || node.isSelected()) {
+            return;
+        }
+        node.setSelected(true);
+        this.emitOrQueue('selection:changed', {
+            selected: [node],
+            deselected: []
+        });
+    }
+    /**
+     * Remove node from selection
+     * @param node - Node to remove from selection
+     */
+    removeFromSelection(node) {
+        if (!node.isSelected()) {
+            return;
+        }
+        node.setSelected(false);
+        this.emitOrQueue('selection:changed', {
+            selected: [],
+            deselected: [node]
+        });
+    }
+    /**
+     * Toggle node selection (add if not selected, remove if selected)
+     * @param node - Node to toggle
+     */
+    toggleNodeSelection(node) {
+        if (!node.isSelectable()) {
+            return;
+        }
+        if (node.isSelected()) {
+            this.removeFromSelection(node);
+        }
+        else {
+            this.addToSelection(node);
+        }
+    }
+    /**
+     * Clear all selections
+     */
+    clearSelection() {
+        const selectedNodes = this.getSelectedNodes();
+        if (selectedNodes.length === 0) {
+            return;
+        }
+        selectedNodes.forEach((node) => node.setSelected(false));
+        this.emitOrQueue('selection:changed', {
+            selected: [],
+            deselected: selectedNodes
+        });
+    }
+    /**
+     * Select all nodes
+     */
+    selectAll() {
+        const selectableNodes = this.getNodes().filter((node) => node.isSelectable());
+        const previouslySelected = this.getSelectedNodes();
+        const newlySelected = selectableNodes.filter((node) => !node.isSelected());
+        newlySelected.forEach((node) => node.setSelected(true));
+        if (newlySelected.length > 0) {
+            this.emitOrQueue('selection:changed', {
+                selected: newlySelected,
+                deselected: []
+            });
+        }
+    }
+    /**
+     * Delete all selected nodes and their connected links
+     * @returns Number of nodes deleted
+     */
+    deleteSelected() {
+        if (this.blocksDocumentWrite())
+            return 0;
+        const selectedNodes = this.getSelectedNodes();
+        if (selectedNodes.length === 0) {
+            return 0;
+        }
+        // Delete nodes (this will also trigger link cleanup via events)
+        selectedNodes.forEach((node) => {
+            this.removeNode(node.id);
+        });
+        return selectedNodes.length;
+    }
+    /**
+     * Get node at position (for click detection)
+     * Returns the topmost node at the given position
+     * @param x - X coordinate
+     * @param y - Y coordinate
+     * @returns Node at position, or undefined if none found
+     * Phase 3.3: Uses shape-aware hit detection
+     */
+    getNodeAtPosition(x, y) {
+        const nodes = this.getNodes();
+        // Iterate in reverse order (topmost node first)
+        for (let i = nodes.length - 1; i >= 0; i--) {
+            const node = nodes[i];
+            const bounds = node.getBoundingBox();
+            // Phase 3.3: Use shape-aware hit detection
+            const shapeConfig = node.getMetadata('shape');
+            if ((0, geometry_1.isPointInShape)(x, y, bounds, shapeConfig)) {
+                return node;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Is (x, y) inside any node ABOVE `nodeId` in z-order?
+     *
+     * Same z contract as {@link getNodeAtPosition} (array order, topmost last),
+     * same shape-aware containment. This is the occlusion oracle for PORTS: a
+     * port whose anchor a higher node covers must neither paint nor accept
+     * input — pre-fix, an overlapped node's port glyphs floated on top of the
+     * covering node's body, and its hidden ports still won the hover/press race
+     * through it (live report from stacked pasted nodes).
+     */
+    isPointCoveredAbove(x, y, nodeId) {
+        const nodes = this.getNodes();
+        let ownerIndex = -1;
+        for (let i = nodes.length - 1; i >= 0; i--) {
+            if (nodes[i].id === nodeId) {
+                ownerIndex = i;
+                break;
+            }
+        }
+        if (ownerIndex < 0)
+            return false;
+        for (let i = nodes.length - 1; i > ownerIndex; i--) {
+            const node = nodes[i];
+            // A node's own DESCENDANTS never occlude it: a composite's chrome (a
+            // title-bar child covering the parent's top strip) is part of the same
+            // widget, and the parent's ports deliberately ride above it — that is
+            // why ports paint in an overlay at all (see create-diagram.spec "port
+            // glyphs paint above overlapping nodes"). Only STRANGERS above cover.
+            if (this.hasAncestor(node, nodeId))
+                continue;
+            const bounds = node.getBoundingBox();
+            if (x < bounds.left || x > bounds.right || y < bounds.top || y > bounds.bottom)
+                continue;
+            if ((0, geometry_1.isPointInShape)(x, y, bounds, node.getMetadata('shape'))) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /** Is `ancestorId` anywhere up `node`'s parent chain? Cycle-guarded. */
+    hasAncestor(node, ancestorId) {
+        var _a;
+        const seen = new Set();
+        let parentId = node.parentId;
+        while (parentId && !seen.has(parentId)) {
+            if (parentId === ancestorId)
+                return true;
+            seen.add(parentId);
+            parentId = (_a = this.getNode(parentId)) === null || _a === void 0 ? void 0 : _a.parentId;
+        }
+        return false;
+    }
+    /**
+     * Option 3: Lock/pin selected nodes
+     * Locked nodes will not move during layout operations
+     */
+    lockSelected() {
+        const selectedNodes = this.getSelectedNodes();
+        if (selectedNodes.length === 0) {
+            return 0;
+        }
+        selectedNodes.forEach((node) => {
+            node.setState({ locked: true });
+        });
+        return selectedNodes.length;
+    }
+    /**
+     * Option 3: Unlock selected nodes
+     */
+    unlockSelected() {
+        const selectedNodes = this.getSelectedNodes();
+        if (selectedNodes.length === 0) {
+            return 0;
+        }
+        selectedNodes.forEach((node) => {
+            node.setState({ locked: false });
+        });
+        return selectedNodes.length;
+    }
+    /**
+     * Option 3: Get locked nodes
+     */
+    getLockedNodes() {
+        return this.getNodes().filter((node) => node.state.locked);
+    }
+    /**
+     * Option 3: Unlock all nodes
+     */
+    unlockAll() {
+        const lockedNodes = this.getLockedNodes();
+        lockedNodes.forEach((node) => {
+            node.setState({ locked: false });
+        });
+        return lockedNodes.length;
+    }
+    /**
+     * Set viewport (Phase 0.5 - Viewport-Aware Layout)
+     */
+    setViewport(x, y, width, height, zoom) {
+        const oldViewport = Object.assign({}, this.viewport);
+        this.viewport = {
+            x,
+            y,
+            width,
+            height,
+            zoom: zoom !== undefined ? zoom : this.viewport.zoom
+        };
+        this.trackChange('viewport', oldViewport, this.viewport);
+        this.emitOrQueue('viewport:changed', this.viewport);
+    }
+    /**
+     * Get current viewport
+     */
+    getViewport() {
+        return Object.assign({}, this.viewport);
+    }
+    /**
+     * Pan viewport
+     */
+    pan(dx, dy) {
+        this.setViewport(this.viewport.x + dx, this.viewport.y + dy, this.viewport.width, this.viewport.height, this.viewport.zoom);
+    }
+    /**
+     * Zoom viewport (relative adjustment)
+     */
+    zoom(delta, center) {
+        const newZoom = Math.max(0.1, Math.min(10, this.viewport.zoom + delta));
+        this.setViewport(this.viewport.x, this.viewport.y, this.viewport.width, this.viewport.height, newZoom);
+    }
+    /**
+     * Set absolute zoom level
+     * Phase 0.5 - Option B: Pan/Zoom controls
+     * @param level - Zoom level (0.1 to 10.0)
+     * @param center - Optional center point for zoom (defaults to viewport center)
+     */
+    setZoom(level, center) {
+        const newZoom = Math.max(0.1, Math.min(10, level));
+        this.setViewport(this.viewport.x, this.viewport.y, this.viewport.width, this.viewport.height, newZoom);
+    }
+    /**
+     * Fit viewport to show all nodes (without changing zoom level)
+     * Phase 0.5 - Option B: Pan/Zoom controls
+     * @param padding - Padding around content (default 100)
+     */
+    fitToView(padding = 100) {
+        const nodes = this.getNodes();
+        if (nodes.length === 0) {
+            // No nodes - reset to default viewport
+            this.setViewport(0, 0, 1200, 800, this.viewport.zoom);
+            return;
+        }
+        // Calculate bounding box of all nodes
+        let minX = Infinity;
+        let minY = Infinity;
+        let maxX = -Infinity;
+        let maxY = -Infinity;
+        nodes.forEach(node => {
+            const bounds = node.getBoundingBox();
+            minX = Math.min(minX, bounds.left);
+            minY = Math.min(minY, bounds.top);
+            maxX = Math.max(maxX, bounds.right);
+            maxY = Math.max(maxY, bounds.bottom);
+        });
+        // Calculate content dimensions
+        const contentWidth = maxX - minX;
+        const contentHeight = maxY - minY;
+        // Calculate viewport size to fit content with padding
+        const viewportWidth = contentWidth + padding * 2;
+        const viewportHeight = contentHeight + padding * 2;
+        // Center the viewport on the content
+        const centerX = (minX + maxX) / 2;
+        const centerY = (minY + maxY) / 2;
+        this.setViewport(centerX - viewportWidth / 2, centerY - viewportHeight / 2, viewportWidth, viewportHeight, this.viewport.zoom);
+        console.log(`📐 Fit to view: ${nodes.length} nodes, bounds=(${minX.toFixed(1)}, ${minY.toFixed(1)}) to (${maxX.toFixed(1)}, ${maxY.toFixed(1)})`);
+    }
+    /**
+     * Fit viewport to show all nodes AND adjust zoom to fit screen
+     * Phase 0.5 - Option B: Pan/Zoom controls
+     * @param targetWidth - Target viewport width (e.g. screen width)
+     * @param targetHeight - Target viewport height (e.g. screen height)
+     * @param padding - Padding around content (default 100)
+     */
+    zoomToFit(targetWidth, targetHeight, padding = 100) {
+        const nodes = this.getNodes();
+        if (nodes.length === 0) {
+            // No nodes - reset to default
+            this.setViewport(0, 0, targetWidth, targetHeight, 1.0);
+            return;
+        }
+        // Calculate bounding box of all nodes
+        let minX = Infinity;
+        let minY = Infinity;
+        let maxX = -Infinity;
+        let maxY = -Infinity;
+        nodes.forEach(node => {
+            const bounds = node.getBoundingBox();
+            minX = Math.min(minX, bounds.left);
+            minY = Math.min(minY, bounds.top);
+            maxX = Math.max(maxX, bounds.right);
+            maxY = Math.max(maxY, bounds.bottom);
+        });
+        // Calculate content dimensions
+        const contentWidth = maxX - minX;
+        const contentHeight = maxY - minY;
+        // Calculate zoom level to fit content in target viewport
+        const availableWidth = targetWidth - padding * 2;
+        const availableHeight = targetHeight - padding * 2;
+        const scaleX = availableWidth / contentWidth;
+        const scaleY = availableHeight / contentHeight;
+        const newZoom = Math.min(scaleX, scaleY, 1.0); // Don't zoom in beyond 1.0, only zoom out
+        // Center the content in the target viewport
+        const centerX = (minX + maxX) / 2;
+        const centerY = (minY + maxY) / 2;
+        this.setViewport(centerX - targetWidth / 2, centerY - targetHeight / 2, targetWidth, targetHeight, Math.max(0.1, Math.min(10, newZoom)));
+        console.log(`🔍 Zoom to fit: ${nodes.length} nodes, zoom=${newZoom.toFixed(2)}, content=${contentWidth.toFixed(1)}x${contentHeight.toFixed(1)}`);
+    }
+    /**
+     * Clear all nodes, links, and groups (Phase 1.6c)
+     */
+    clear() {
+        // Remove all links first
+        const linkIds = Array.from(this.links.keys());
+        for (const linkId of linkIds) {
+            this.removeLink(linkId);
+        }
+        // Remove all nodes
+        const nodeIds = Array.from(this.nodes.keys());
+        for (const nodeId of nodeIds) {
+            this.removeNode(nodeId);
+        }
+        // Remove all groups (Phase 1.6c)
+        const groupIds = Array.from(this.groups.keys());
+        for (const groupId of groupIds) {
+            this.removeGroup(groupId);
+        }
+        // wave10/whiteboard: ink is document content, so clear() clears it. Removed one by
+        // one (not `strokes.clear()`) so each emits its trackChange — otherwise clearing a
+        // collaborative document would wipe the ink locally and NOT tell the other peers,
+        // and their next edit would resurrect it all.
+        const strokeIds = Array.from(this.strokes.keys());
+        for (const strokeId of strokeIds) {
+            this.removeStroke(strokeId);
+        }
+        // Phase 5.1: Clear spatial indices
+        this.nodeSpatialIndex.clear();
+        this.linkSpatialIndex.clear();
+        this.emitOrQueue('diagram:cleared');
+    }
+    /**
+     * Get nodes visible in viewport (Phase 5.1)
+     * This enables viewport virtualization - only render visible nodes
+     *
+     * @param viewport - Rectangular viewport region in world coordinates
+     * @returns Array of nodes that intersect with the viewport
+     *
+     * @example
+     * ```typescript
+     * const viewport = {
+     *   x: camera.x,
+     *   y: camera.y,
+     *   width: canvas.width / camera.zoom,
+     *   height: canvas.height / camera.zoom,
+     * };
+     * const visibleNodes = diagram.getVisibleNodes(viewport);
+     * // Only render visibleNodes instead of all nodes
+     * ```
+     */
+    getVisibleNodes(viewport) {
+        return this.nodeSpatialIndex.queryRegion(viewport, {
+            filter: (node) => node.state.visible !== false,
+        });
+    }
+    /**
+     * Get links visible in viewport (Phase 5.1)
+     * This enables viewport virtualization - only render visible links
+     *
+     * @param viewport - Rectangular viewport region in world coordinates
+     * @returns Array of links that intersect with the viewport
+     */
+    getVisibleLinks(viewport) {
+        return this.linkSpatialIndex.queryRegion(viewport);
+    }
+    /**
+     * The nearest port to a world point, served BY THE SPATIAL INDEX.
+     *
+     * wave8/culling — Card 2. This is the query a link drag makes on every
+     * pointermove, so it is the one query that must never be a scan: the existing
+     * answer (`PortModel.findNearestPort`) could only search ONE node — the one the
+     * pointer happened to be over — because searching more would have meant walking
+     * every node in the diagram. The index turns "which port am I near" into a
+     * bounded region query, so a drag can snap to a port it is merely NEAR, not one
+     * it is already on top of, without paying O(nodes) sixty times a second.
+     *
+     * `portPosition` is injectable because THE ENGINE DOES NOT KNOW WHERE PORTS ARE.
+     * Its default (`getAbsolutePosition`) walks the bounding box — edge midpoints,
+     * blind to the silhouette and to how many ports share a side — while the
+     * renderer draws them shape-aware (`portWorldPosition`). Wave 6 fixed exactly
+     * this divergence for the port hit-test and the magnet, and it is why callers
+     * inside the renderer MUST pass the shape-aware resolver: otherwise you snap to
+     * a point several pixels from the circle you can see.
+     *
+     * @param point   World-space point (usually the drag position).
+     * @param options radius (default 24 world units), an optional port filter, and
+     *                the port-position resolver described above.
+     */
+    findNearestPort(point, options) {
+        var _a, _b;
+        const radius = (_a = options === null || options === void 0 ? void 0 : options.radius) !== null && _a !== void 0 ? _a : exports.DEFAULT_PORT_SNAP_RADIUS;
+        const positionOf = (_b = options === null || options === void 0 ? void 0 : options.portPosition) !== null && _b !== void 0 ? _b : ((port, node) => port.getAbsolutePosition(node.getBoundingBox()));
+        // A port normally sits ON its node's bounding box, so any port within
+        // `radius` belongs to a node whose box is within `radius`. `port.offset` can
+        // push it outside, though, so the CANDIDATE search is padded — a few extra
+        // candidate nodes cost nothing (they fail the real distance test below),
+        // whereas missing one silently loses a snap target.
+        const candidates = this.nodeSpatialIndex.queryNear(point, radius + PORT_OFFSET_PAD, { filter: (node) => node.state.visible !== false });
+        let best = null;
+        for (const node of candidates) {
+            for (const port of node.getPorts()) {
+                if ((options === null || options === void 0 ? void 0 : options.filter) && !options.filter(port, node))
+                    continue;
+                const p = positionOf(port, node);
+                const dx = point.x - p.x;
+                const dy = point.y - p.y;
+                const distance = Math.sqrt(dx * dx + dy * dy);
+                if (distance > radius)
+                    continue;
+                if (!best || distance < best.distance) {
+                    best = { port, node, distance };
+                }
+            }
+        }
+        return best;
+    }
+    /**
+     * Get bounding box of all visible entities (Phase 5.1)
+     * Useful for "fit to viewport" operations
+     *
+     * @param viewport - Rectangular viewport region
+     * @returns Bounding rectangle of visible entities, or null if none visible
+     */
+    getVisibleBounds(viewport) {
+        const visibleNodes = this.getVisibleNodes(viewport);
+        const visibleLinks = this.getVisibleLinks(viewport);
+        if (visibleNodes.length === 0 && visibleLinks.length === 0) {
+            return null;
+        }
+        let minX = Infinity;
+        let minY = Infinity;
+        let maxX = -Infinity;
+        let maxY = -Infinity;
+        // Include visible nodes
+        for (const node of visibleNodes) {
+            const bounds = node.getBoundingBox();
+            minX = Math.min(minX, bounds.left);
+            minY = Math.min(minY, bounds.top);
+            maxX = Math.max(maxX, bounds.right);
+            maxY = Math.max(maxY, bounds.bottom);
+        }
+        // Include visible links
+        for (const link of visibleLinks) {
+            for (const point of link.points) {
+                minX = Math.min(minX, point.x);
+                minY = Math.min(minY, point.y);
+                maxX = Math.max(maxX, point.x);
+                maxY = Math.max(maxY, point.y);
+            }
+        }
+        return {
+            x: minX,
+            y: minY,
+            width: maxX - minX,
+            height: maxY - minY,
+        };
+    }
+    /**
+     * Get all dirty nodes (Phase 5.2)
+     * Returns nodes that need re-rendering
+     */
+    getDirtyNodes() {
+        return this.getNodes().filter((node) => node.isDirty);
+    }
+    /**
+     * Get all dirty links (Phase 5.2)
+     * Returns links that need re-rendering
+     */
+    getDirtyLinks() {
+        return this.getLinks().filter((link) => link.isDirty);
+    }
+    /**
+     * Get all dirty groups (Phase 5.2)
+     * Returns groups that need re-rendering
+     */
+    getDirtyGroups() {
+        return this.getGroups().filter((group) => group.isDirty);
+    }
+    /**
+     * Mark all entities as clean (Phase 5.2)
+     * Call this after rendering to reset dirty flags
+     */
+    markAllClean() {
+        // Mark all nodes clean
+        for (const node of this.nodes.values()) {
+            node.markClean();
+        }
+        // Mark all links clean
+        for (const link of this.links.values()) {
+            link.markClean();
+        }
+        // Mark all groups clean
+        for (const group of this.groups.values()) {
+            group.markClean();
+        }
+        // Emit event
+        this.emitOrQueue('dirty:cleared');
+    }
+    /**
+     * Get total count of dirty entities (Phase 5.2)
+     * Useful for monitoring render performance
+     */
+    getDirtyCount() {
+        let count = 0;
+        for (const node of this.nodes.values()) {
+            if (node.isDirty)
+                count++;
+        }
+        for (const link of this.links.values()) {
+            if (link.isDirty)
+                count++;
+        }
+        for (const group of this.groups.values()) {
+            if (group.isDirty)
+                count++;
+        }
+        return count;
+    }
+    /**
+     * Get visible dirty nodes (Phase 5.2)
+     * Combines viewport virtualization with dirty marking
+     * Only returns nodes that are both visible AND need re-rendering
+     *
+     * @param viewport - Rectangular viewport region
+     * @returns Array of nodes that are visible and dirty
+     *
+     * @example
+     * ```typescript
+     * const viewport = { x: 0, y: 0, width: 800, height: 600 };
+     * const dirtyVisible = diagram.getVisibleDirtyNodes(viewport);
+     * // Only re-render these nodes - maximum efficiency!
+     * ```
+     */
+    getVisibleDirtyNodes(viewport) {
+        return this.getVisibleNodes(viewport).filter((node) => node.isDirty);
+    }
+    /**
+     * Get visible dirty links (Phase 5.2)
+     * Combines viewport virtualization with dirty marking
+     * Only returns links that are both visible AND need re-rendering
+     *
+     * @param viewport - Rectangular viewport region
+     * @returns Array of links that are visible and dirty
+     */
+    getVisibleDirtyLinks(viewport) {
+        return this.getVisibleLinks(viewport).filter((link) => link.isDirty);
+    }
+    /**
+     * Get LOD level based on zoom (Phase 5.3)
+     *
+     * wave2/rendering: driven by the declarative {@link LODConfig}. Picks the
+     * tier whose `minZoom` the zoom crosses — tiers are pre-sorted highest-first,
+     * so the first match wins. With the default config this is exactly:
+     *   zoom >= 1.0        -> 'high'
+     *   0.5 <= zoom < 1.0  -> 'medium'
+     *   zoom <  0.5        -> 'low'
+     *
+     * (wave8/culling moved the medium/low breakpoint 0.2 → 0.5 — see
+     * {@link createDefaultLODConfig} for why.)
+     *
+     * @param zoom - Current zoom level
+     * @returns Tier name (default policy: 'high' | 'medium' | 'low')
+     */
+    getLODLevel(zoom) {
+        const tiers = this._lodTiersDesc;
+        for (const tier of tiers) {
+            if (zoom >= tier.minZoom) {
+                return tier.name;
+            }
+        }
+        // Below every tier's minZoom → fall back to the coarsest (last) tier.
+        return tiers.length > 0 ? tiers[tiers.length - 1].name : 'low';
+    }
+    /**
+     * wave2/rendering: single feature gate that reads the active LOD tier's
+     * feature set. Renderers call this instead of hardcoding `lod === 'high'`
+     * checks, so custom tiers work automatically.
+     *
+     * @param feature - Visual feature being considered
+     * @param lod - Current tier name (from {@link getLODLevel})
+     * @returns true if the tier renders that feature
+     */
+    shouldRender(feature, lod) {
+        const tier = this._lodConfig.tiers.find((t) => t.name === lod);
+        return tier ? tier.features.has(feature) : false;
+    }
+    // =========================================================================
+    // LOD configuration API (wave2/rendering)
+    // =========================================================================
+    /** Get the current Level-of-Detail policy. */
+    getLODConfig() {
+        return this._lodConfig;
+    }
+    /**
+     * Replace the Level-of-Detail policy wholesale. Apps use this to define
+     * their own tiers (names, breakpoints and feature sets).
+     */
+    setLODConfig(config) {
+        this._lodConfig = config;
+        this._resortLODTiers();
+    }
+    /**
+     * Register (or replace, by name) a single LOD tier. Lets apps extend the
+     * default policy with an extra tier without rebuilding the whole config.
+     */
+    registerLODTier(tier) {
+        const idx = this._lodConfig.tiers.findIndex((t) => t.name === tier.name);
+        if (idx >= 0) {
+            this._lodConfig.tiers[idx] = tier;
+        }
+        else {
+            this._lodConfig.tiers.push(tier);
+        }
+        this._resortLODTiers();
+    }
+    /** Keep the highest-minZoom-first tier cache in sync with _lodConfig. */
+    _resortLODTiers() {
+        this._lodTiersDesc = [...this._lodConfig.tiers].sort((a, b) => b.minZoom - a.minZoom);
+    }
+    /**
+     * Get visible nodes with LOD information (Phase 5.3)
+     * Combines viewport virtualization with Level of Detail
+     *
+     * @param viewport - Rectangular viewport region
+     * @param zoom - Current zoom level
+     * @returns Array of nodes with LOD level
+     */
+    getNodesWithLOD(viewport, zoom) {
+        const lod = this.getLODLevel(zoom);
+        const visibleNodes = this.getVisibleNodes(viewport);
+        return visibleNodes.map((node) => ({
+            entity: node,
+            lod,
+        }));
+    }
+    /**
+     * Get visible links with LOD information (Phase 5.3)
+     * Combines viewport virtualization with Level of Detail
+     *
+     * @param viewport - Rectangular viewport region
+     * @param zoom - Current zoom level
+     * @returns Array of links with LOD level
+     */
+    getLinksWithLOD(viewport, zoom) {
+        const lod = this.getLODLevel(zoom);
+        const visibleLinks = this.getVisibleLinks(viewport);
+        return visibleLinks.map((link) => ({
+            entity: link,
+            lod,
+        }));
+    }
+    /**
+     * Check if labels should be rendered at this LOD level (Phase 5.3)
+     * wave2/rendering: now reads the LOD tier's feature set.
+     */
+    shouldRenderLabels(lod) {
+        return this.shouldRender('labels', lod);
+    }
+    /**
+     * Check if icons should be rendered at this LOD level (Phase 5.3)
+     * wave2/rendering: now reads the LOD tier's feature set.
+     */
+    shouldRenderIcons(lod) {
+        return this.shouldRender('icons', lod);
+    }
+    /**
+     * Check if borders should be rendered at this LOD level (Phase 5.3)
+     * wave2/rendering: now reads the LOD tier's feature set.
+     */
+    shouldRenderBorders(lod) {
+        return this.shouldRender('borders', lod);
+    }
+    /**
+     * Check if shadows should be rendered at this LOD level (Phase 5.3)
+     * wave2/rendering: now reads the LOD tier's feature set.
+     */
+    shouldRenderShadows(lod) {
+        return this.shouldRender('shadows', lod);
+    }
+    // =============================================================================
+    // Layout Management API
+    // =============================================================================
+    /**
+     * Get the layout manager for this diagram
+     */
+    getLayoutManager() {
+        return this._layoutManager;
+    }
+    /**
+     * Set layout algorithm
+     * @param type - Algorithm type ('grid', 'force-directed', 'hierarchical', 'hybrid')
+     * @param config - Optional configuration
+     */
+    setLayoutAlgorithm(type, config) {
+        this._layoutManager.setAlgorithm(type, config);
+    }
+    /**
+     * Get current layout algorithm type
+     */
+    getLayoutAlgorithm() {
+        return this._layoutManager.getCurrentAlgorithmType();
+    }
+    /**
+     * Configure current layout algorithm
+     */
+    configureLayout(config) {
+        this._layoutManager.configure(config);
+    }
+    /**
+     * Get layout configuration
+     */
+    getLayoutConfiguration() {
+        return this._layoutManager.getConfiguration();
+    }
+    /**
+     * Enable or disable automatic layout for new nodes
+     * When enabled, newly added nodes will be automatically positioned using the current layout algorithm
+     */
+    setAutoLayout(enabled) {
+        this._autoLayoutEnabled = enabled;
+    }
+    /**
+     * Check if auto-layout is enabled
+     */
+    isAutoLayoutEnabled() {
+        return this._autoLayoutEnabled;
+    }
+    /**
+     * Re-layout all nodes using current algorithm
+     * This will recalculate positions for all nodes in the diagram
+     */
+    reLayout(config) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return this._layoutManager.reLayout(config);
+        });
+    }
+    /**
+     * Override: End batch update mode
+     * Fires accumulated events when all batches complete
+     */
+    endBatch() {
+        // Call parent to handle dirty state
+        super.endBatch();
+        // When all batches complete (check parent's isBatching), fire queued events
+        if (!this.isBatching() && this._pendingEvents.length > 0) {
+            // Fire all queued events individually
+            const events = [...this._pendingEvents];
+            this._pendingEvents = [];
+            for (const event of events) {
+                this.emitter.emit(event.type, event.data);
+            }
+            // Also fire a batch:complete event for listeners that want to know
+            this.emitter.emit('batch:complete', {
+                eventCount: events.length,
+                events: events
+            });
+        }
+    }
+    /**
+     * Emit event, respecting batch mode
+     * During batch mode, events are queued instead of fired immediately
+     */
+    emitOrQueue(eventType, data) {
+        const batching = this.isBatching();
+        if (batching) {
+            // Queue event for later
+            this._pendingEvents.push({ type: eventType, data });
+        }
+        else {
+            // Emit immediately
+            this.emitter.emit(eventType, data);
+        }
+    }
+    /**
+     * Serialize to JSON
+     */
+    serialize() {
+        const doc = {
+            schemaVersion: DiagramMigrations_1.DIAGRAM_SCHEMA_VERSION,
+            id: this.id,
+            uuid: this.uuid,
+            type: 'diagram',
+            version: this.version,
+            metadata: Object.fromEntries(this.metadata),
+            name: this.name,
+            nodes: Array.from(this.nodes.values()).map((n) => n.serialize()),
+            links: Array.from(this.links.values()).map((l) => l.serialize()),
+            groups: Array.from(this.groups.values()).map((g) => g.serialize()), // Phase 1.6c
+            viewport: Object.assign({}, this.viewport),
+        };
+        // wave10/whiteboard: present only when there is ink — see SerializedDiagram.strokes.
+        if (this.strokes.size > 0) {
+            doc.strokes = Array.from(this.strokes.values()).map((s) => s.serialize());
+        }
+        // wave9/comments: present only when there are comments — see SerializedDiagram.
+        if (Object.keys(this._comments).length > 0) {
+            doc.comments = (0, deep_clone_1.deepClone)(this._comments);
+        }
+        return doc;
+    }
+    /**
+     * Rebuild the derived port-connection registries from the diagram's links.
+     *
+     * `PortModel.currentConnections` is DERIVED state (which links touch this
+     * port). It is never serialized; instead it is reconstructed
+     * deterministically here so `canConnect()` / `maxConnections` enforcement
+     * survive save/load. Runs inside fromJSON, and is safe to re-run at any
+     * time — existing registries are reset first, so the result is always
+     * exactly the current links.
+     *
+     * A self-loop (source === target port) registers once — the Set dedupes —
+     * so it counts as ONE connection on that port.
+     *
+     * @returns endpoints that resolve to no known port (corrupt/dangling links),
+     *          for callers that want to surface them.
+     */
+    reconcilePortConnections() {
+        // Reset: the registry must be exactly what the links imply, not a merge
+        // of stale + current.
+        for (const { port } of this.portIndex.values()) {
+            port.currentConnections.clear();
+            // Wave 6: the DIRECTIONAL registry is derived state too — rebuilt here, or
+            // `fromMaxLinks`/`toMaxLinks` would count stale roles after a reload.
+            port.linkRoles.clear();
+        }
+        const dangling = [];
+        for (const link of this.links.values()) {
+            for (const [end, portId] of [
+                ['source', link.sourcePortId],
+                ['target', link.targetPortId],
+            ]) {
+                const entry = this.portIndex.get(portId);
+                if (entry) {
+                    entry.port.restoreConnection(link.id, end);
+                }
+                else {
+                    dangling.push({ linkId: link.id, portId, end });
+                }
+            }
+        }
+        return dangling;
+    }
+    /**
+     * Apply an incremental patch (see serialization/Incremental.ts) — the
+     * receive side of toIncremental/apply. Added entities are installed through
+     * the SAME unified restore path as document load (fully wired); modified
+     * entities are updated IN PLACE so object identity is preserved for
+     * renderers holding references; normal change events fire (an applied
+     * patch IS a mutation, unlike a document load).
+     */
+    applyIncremental(patch) {
+        var _a, _b, _c;
+        this.assertNotDisposed();
+        if (patch.format !== Incremental_1.INCREMENTAL_FORMAT) {
+            throw new Error(`Not an incremental patch (format '${patch === null || patch === void 0 ? void 0 : patch.format}')`);
+        }
+        if (patch.schemaVersion > DiagramMigrations_1.DIAGRAM_SCHEMA_VERSION) {
+            throw new Error(`Incremental patch has schemaVersion ${patch.schemaVersion}, newer than this ` +
+                `runtime (${DiagramMigrations_1.DIAGRAM_SCHEMA_VERSION}) — refusing to apply.`);
+        }
+        this.beginBatch();
+        try {
+            // Removals first — links before the nodes they reference.
+            for (const id of patch.removed.links)
+                this.removeLink(id);
+            for (const id of patch.removed.nodes)
+                this.removeNode(id);
+            for (const id of patch.removed.groups)
+                this.removeGroup(id);
+            // wave10/whiteboard. Ink references nothing and nothing references it, so its
+            // position in this ordering is free — which is one of the quieter dividends of
+            // strokes not being nodes.
+            for (const id of (_a = patch.removed.strokes) !== null && _a !== void 0 ? _a : [])
+                this.removeStroke(id);
+            // Additions through the unified restore path (fully wired entities).
+            for (const nodeData of patch.added.nodes)
+                this.restoreNode(nodeData);
+            for (const linkData of patch.added.links)
+                this.restoreLink(linkData);
+            for (const groupData of patch.added.groups)
+                this.restoreGroup(groupData);
+            for (const strokeData of (_b = patch.added.strokes) !== null && _b !== void 0 ? _b : [])
+                this.restoreStroke(strokeData);
+            // In-place modifications (a modified-but-locally-missing entity is
+            // treated as an add — patches may arrive against divergent replicas).
+            for (const nodeData of patch.modified.nodes)
+                this.applySerializedNode(nodeData);
+            for (const linkData of patch.modified.links)
+                this.applySerializedLink(linkData);
+            for (const groupData of patch.modified.groups)
+                this.applySerializedGroup(groupData);
+            // A stroke is immutable geometry: "modify" is remove-and-replace, which is also
+            // exactly what a REPLACE-semantics patch means. No in-place applySerializedStroke
+            // exists because nothing holds a reference to a stroke across a patch.
+            for (const strokeData of (_c = patch.modified.strokes) !== null && _c !== void 0 ? _c : []) {
+                this.removeStroke(strokeData.id);
+                this.restoreStroke(strokeData);
+            }
+            if (patch.diagram) {
+                if (patch.diagram.name !== undefined)
+                    this.name = patch.diagram.name;
+                if (patch.diagram.viewport)
+                    this.viewport = Object.assign({}, patch.diagram.viewport);
+                if (patch.diagram.metadata) {
+                    this.metadata = new Map(Object.entries(patch.diagram.metadata));
+                }
+            }
+            // Derived state follows the links.
+            this.reconcilePortConnections();
+        }
+        finally {
+            this.endBatch(); // queued events flush here — normal mutation semantics
+        }
+        // Converge the mutation counter to the SOURCE's — the replica must
+        // serialize identically to the diagram the patch came from, and apply's
+        // own internal trackChange bumps are implementation noise, not edits.
+        if (typeof patch.targetVersion === 'number') {
+            this.version = patch.targetVersion;
+        }
+        this.emitter.emit('diagram:incremental-applied', {
+            added: patch.added.nodes.length + patch.added.links.length + patch.added.groups.length,
+            removed: patch.removed.nodes.length + patch.removed.links.length + patch.removed.groups.length,
+            modified: patch.modified.nodes.length + patch.modified.links.length + patch.modified.groups.length,
+        });
+    }
+    /** In-place node update from serialized data (identity preserved). */
+    applySerializedNode(data) {
+        var _a;
+        const node = this.nodes.get(data.id);
+        if (!node) {
+            this.restoreNode(data);
+            return;
+        }
+        node.position = Object.assign({}, data.position);
+        node.size = Object.assign({}, data.size);
+        node.rotation = data.rotation;
+        node.scale = data.scale;
+        node.parentId = data.parentId;
+        node.children = new Set(data.children);
+        node.state = data.state;
+        node.behavior = data.behavior;
+        node.style = data.style;
+        node.data = data.data;
+        node.positionMode = data.positionMode || 'absolute';
+        node.transformOrigin = data.transformOrigin || { x: 0.5, y: 0.5 };
+        node.metadata = new Map(Object.entries((_a = data.metadata) !== null && _a !== void 0 ? _a : {}));
+        // Replace ports, keeping the O(1) index exact WITHOUT re-running
+        // indexNodePorts (which would stack another pair of port listeners).
+        if (Array.isArray(data.ports)) {
+            for (const port of node.getPorts()) {
+                const entry = this.portIndex.get(port.id);
+                if ((entry === null || entry === void 0 ? void 0 : entry.node) === node)
+                    this.portIndex.delete(port.id);
+            }
+            node.ports.clear();
+            for (const portData of data.ports) {
+                const port = PortModel_1.PortModel.fromJSON(portData);
+                node.ports.set(port.id, port);
+                this.portIndex.set(port.id, { node, port });
+            }
+        }
+        if (typeof data.version === 'number')
+            node.version = data.version;
+        this.nodeSpatialIndex.update(node);
+        node.markDirty('incremental');
+        this.emitOrQueue('node:changed', node);
+        this.emitOrQueue('node:moved', { nodeId: node.id, position: node.position });
+    }
+    /** In-place link update from serialized data (identity preserved). */
+    applySerializedLink(data) {
+        var _a, _b, _c, _d, _e, _f, _g, _h;
+        const link = this.links.get(data.id);
+        if (!link) {
+            this.restoreLink(data);
+            return;
+        }
+        link.sourcePortId = data.sourcePortId;
+        link.targetPortId = data.targetPortId;
+        link.sourceNodeId = (_a = data.sourceNodeId) !== null && _a !== void 0 ? _a : (_b = this.getNodeByPortId(data.sourcePortId)) === null || _b === void 0 ? void 0 : _b.id;
+        link.targetNodeId = (_c = data.targetNodeId) !== null && _c !== void 0 ? _c : (_d = this.getNodeByPortId(data.targetPortId)) === null || _d === void 0 ? void 0 : _d.id;
+        link.pathType = data.pathType;
+        link.points = ((_e = data.points) !== null && _e !== void 0 ? _e : []).map((point) => (Object.assign({}, point)));
+        link.segments = ((_f = data.segments) !== null && _f !== void 0 ? _f : []).map((segment) => (Object.assign({}, segment)));
+        link.labels = ((_g = data.labels) !== null && _g !== void 0 ? _g : []).map((label) => (Object.assign({}, label)));
+        link.state = data.state;
+        link.style = data.style;
+        link.data = data.data;
+        link.metadata = new Map(Object.entries((_h = data.metadata) !== null && _h !== void 0 ? _h : {}));
+        if (typeof data.version === 'number')
+            link.version = data.version;
+        this.linkSpatialIndex.update(link);
+        link.markDirty('incremental');
+        this.emitOrQueue('link:changed', link);
+    }
+    /** In-place group update from serialized data (identity preserved). */
+    applySerializedGroup(data) {
+        var _a, _b, _c, _d, _e;
+        const group = this.groups.get(data.id);
+        if (!group) {
+            this.restoreGroup(data);
+            return;
+        }
+        group.name = data.name;
+        group.members = new Set((_a = data.members) !== null && _a !== void 0 ? _a : []);
+        group.isCollapsed = data.isCollapsed;
+        group.bounds = data.bounds;
+        if (data.layoutType)
+            group.layoutType = data.layoutType;
+        if (data.layoutConfig)
+            group.layoutConfig = data.layoutConfig;
+        if (data.position)
+            group.position = { x: data.position.x, y: data.position.y };
+        if (data.size)
+            group.size = Object.assign({}, data.size);
+        group.parentGroupId = data.parentGroupId;
+        // Wave-5 Card 3: keep the incremental in-place path lossless for the new
+        // subflow geometry (absent keys reset to their defaults, matching fromJSON).
+        // Absent keys pin to 0 (legacy engines wrote 0 as absence) — see fromJSON;
+        // leaving padding undefined would resolve to the authored default instead.
+        group.padding = (_b = data.padding) !== null && _b !== void 0 ? _b : 0;
+        group.headerHeight = typeof data.headerHeight === 'number' ? data.headerHeight : 0;
+        group.zIndex = typeof data.zIndex === 'number' ? data.zIndex : 0;
+        group.fitMode = (_c = data.fitMode) !== null && _c !== void 0 ? _c : 'exact';
+        group.constrainChildren = (_d = data.constrainChildren) !== null && _d !== void 0 ? _d : false;
+        // Wave-5 Card 4: collapsed-state payload (proxy wiring + saved layout).
+        group.collapsedState = data.collapsedState;
+        // Wave-5 Card 5: per-group compound-layout intent.
+        group.subgraphLayout = data.subgraphLayout;
+        // Wave-5 Card 6: swimlane/pool band config.
+        group.laneConfig = data.laneConfig;
+        // Wave-5 Card 7: declarative membership rule + capacity/WIP limit.
+        group.membershipRule = data.membershipRule;
+        group.capacity = data.capacity;
+        // Replace metadata CONTENT but keep the runtime diagram back-ref wired.
+        group.metadata = new Map(Object.entries((_e = data.metadata) !== null && _e !== void 0 ? _e : {}));
+        group.metadata.set('diagram', this);
+        if (typeof data.version === 'number')
+            group.version = data.version;
+        group.markDirty('incremental');
+        this.emitOrQueue('group:changed', group);
+    }
+    /**
+     * Deserialize from JSON — THE document load path.
+     *
+     * Contract: a loaded diagram behaves identically to an authored one.
+     * Every entity is installed through the same install* wiring as
+     * interactive creation (diagram back-refs, spatial indices, port index,
+     * change-forwarding listeners), port registries are reconciled, and the
+     * document is migrated to the current schema first. The load itself is
+     * NOT a user mutation: per-entity events queued during the restore are
+     * dropped, the change log ends empty, and `version` reports the SAVED
+     * counter — then a single 'diagram:loaded' event fires.
+     */
+    static fromJSON(data, options) {
+        var _a, _b, _c;
+        // 1) Upgrade older documents (throws on newer-than-runtime or a gap).
+        const doc = (0, DiagramMigrations_1.runDiagramMigrations)(data);
+        // 2) Optional structural validation with caller-chosen policy.
+        let report;
+        const policy = (_a = options === null || options === void 0 ? void 0 : options.validate) !== null && _a !== void 0 ? _a : 'off';
+        if (policy !== 'off') {
+            report = (0, DiagramValidator_1.validateSerializedDiagram)(doc);
+            if (policy === 'strict' && !report.ok) {
+                throw new DiagramValidator_1.DiagramValidationError(report);
+            }
+            if (policy === 'warn' && (report.errors.length || report.warnings.length)) {
+                console.warn(`Diagram '${doc.name}' loaded with ${report.errors.length} integrity error(s) ` +
+                    `and ${report.warnings.length} warning(s)`, report);
+            }
+        }
+        // 3) Reproduce the saved identity — a load must not mint a new diagram.
+        const diagram = new DiagramModel(doc.name, { id: doc.id, uuid: doc.uuid });
+        // Restore viewport with backward compatibility
+        diagram.viewport = {
+            x: doc.viewport.x,
+            y: doc.viewport.y,
+            width: doc.viewport.width || 1200, // Default for old diagrams
+            height: doc.viewport.height || 800, // Default for old diagrams
+            zoom: doc.viewport.zoom
+        };
+        // wave9/comments: threads outlive everything they point at, including the entities
+        // in this very document — so they are restored WITHOUT reference to whether their
+        // anchor still resolves. A thread whose node was deleted before the save comes back
+        // orphaned, which is exactly what it was. Assigned to the private field rather than
+        // through the accessor: a LOAD is not a CHANGE, and firing trackChange here would
+        // make OpCapture (if one is attached to this fresh model) broadcast the entire
+        // comment tree as a local edit.
+        if (doc.comments) {
+            diagram._comments = (0, deep_clone_1.deepClone)(doc.comments);
+        }
+        // 4) Install every entity through the SAME wiring as interactive
+        //    creation, inside a batch window so the restore doesn't fire an
+        //    O(entities) event storm. Nodes go first so link node-id backfill
+        //    and port resolution work; groups after links (members reference
+        //    both).
+        diagram.beginBatch();
+        try {
+            for (const nodeData of doc.nodes) {
+                diagram.restoreNode(nodeData);
+            }
+            for (const linkData of doc.links) {
+                diagram.restoreLink(linkData);
+            }
+            if (doc.groups) {
+                for (const groupData of doc.groups) {
+                    diagram.restoreGroup(groupData);
+                }
+            }
+            // wave10/whiteboard. Guarded exactly like `groups` above: an absent `strokes` key
+            // means a document written before this wave (or one with no ink), and it means
+            // zero strokes — NOT a broken document. That guard is the whole reason this
+            // capability needed no schema bump and no migration: bumping
+            // DIAGRAM_SCHEMA_VERSION would have made every newly-saved document unloadable
+            // by any older runtime (runDiagramMigrations throws on newer-than-runtime), which
+            // is a brutal price for a key that can simply be optional.
+            if (doc.strokes) {
+                for (const strokeData of doc.strokes) {
+                    diagram.restoreStroke(strokeData);
+                }
+            }
+            // Restore metadata
+            for (const [key, value] of Object.entries(doc.metadata)) {
+                diagram.metadata.set(key, value);
+            }
+            // 5) Rebuild derived state (port connection registries).
+            diagram.reconcilePortConnections();
+        }
+        finally {
+            // A load is not N user mutations: drop the queued per-entity events
+            // (node:added × N, …) instead of firing them, then close the batch.
+            diagram._pendingEvents = [];
+            diagram.endBatch();
+        }
+        // 6) Version parity + clean change state: the loaded model reports the
+        //    SAVED mutation counter and an empty change log, exactly like the
+        //    diagram that was serialized. (Render-dirty state is untouched — a
+        //    fresh load must still paint.)
+        diagram.changeLog.length = 0;
+        diagram.version = (_b = doc.version) !== null && _b !== void 0 ? _b : 1;
+        // 7) One document-level event replaces the storm.
+        diagram.emitter.emit('diagram:loaded', {
+            nodeCount: diagram.nodes.size,
+            linkCount: diagram.links.size,
+            groupCount: diagram.groups.size,
+            schemaVersion: (_c = doc.schemaVersion) !== null && _c !== void 0 ? _c : DiagramMigrations_1.DIAGRAM_SCHEMA_VERSION,
+            validation: report,
+        });
+        return diagram;
+    }
+    /**
+     * Dispose diagram and all child entities (Phase 5.4)
+     * Prevents memory leaks by:
+     * - Disposing all nodes, links, and groups
+     * - Breaking circular references
+     * - Clearing spatial indices
+     * - Calling parent dispose()
+     */
+    dispose() {
+        this.assertNotDisposed();
+        // Dispose all child entities first (children before parent)
+        // This ensures proper cleanup order and prevents orphaned listeners
+        // Dispose all nodes
+        for (const node of this.nodes.values()) {
+            // Break circular reference before disposal
+            node.diagram = undefined;
+            node.dispose();
+        }
+        // Dispose all links
+        for (const link of this.links.values()) {
+            link.dispose();
+        }
+        // Dispose all groups
+        for (const group of this.groups.values()) {
+            group.dispose();
+        }
+        // wave10/whiteboard: strokes are DiagramEntities and hold an EventEmitter each —
+        // OpCapture subscribes to every one of them. Not disposing them leaks that listener
+        // for the life of the process.
+        for (const stroke of this.strokes.values()) {
+            stroke.dispose();
+        }
+        // Clear collections
+        this.nodes.clear();
+        this.links.clear();
+        this.groups.clear();
+        this.strokes.clear();
+        this.portIndex.clear();
+        this.detachedAnchors.clear(); // wave14/model — nothing left to freeze against
+        // Clear spatial indices (prevents memory leaks from indexed entities)
+        this.nodeSpatialIndex.clear();
+        this.linkSpatialIndex.clear();
+        // Dispose layout manager
+        this._layoutManager.dispose();
+        // Call parent dispose (removes listeners, clears metadata, etc.)
+        super.dispose();
+    }
+}
+exports.DiagramModel = DiagramModel;
+//# sourceMappingURL=DiagramModel.js.map