@grafloria/element 0.3.18 → 0.3.20

package/src/libs/engine/src/models/DiagramModel.d.ts

@@ -0,0 +1,960 @@
+import { DiagramEntity } from './DiagramEntity';
+import { NodeModel, SerializedNode, type DetachedParentAnchor } from './NodeModel';
+import { LinkModel, SerializedLink } from './LinkModel';
+import { PortModel } from './PortModel';
+import { GroupModel, SerializedGroup } from './GroupModel';
+import { StrokeModel, SerializedStroke } from './StrokeModel';
+import type { SerializedEntity, Point } from '../types';
+import type { Rectangle } from '../types/geometry.types';
+import type { LODLevel, EntityWithLOD, LODConfig, LODTier, LODFeature } from '../types/performance.types';
+import { LayoutManager } from '../layout/LayoutManager';
+import type { LayoutAlgorithmType, LayoutConfiguration } from '../layout/types';
+import { type DiagramIncremental } from '../serialization/Incremental';
+import type { CommentRegisterTree } from '../comments/types';
+/**
+ * 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.
+ */
+export declare const DEFAULT_PORT_SNAP_RADIUS = 24;
+/** Options for {@link DiagramModel.findNearestPort}. */
+export interface NearestPortOptions {
+    /** Maximum distance, in world units (default {@link DEFAULT_PORT_SNAP_RADIUS}). */
+    radius?: number;
+    /** Consider only the ports this accepts (e.g. valid targets for the dragged link). */
+    filter?: (port: PortModel, node: NodeModel) => boolean;
+    /**
+     * Where a port actually IS. Defaults to the bounding-box edge midpoint. Callers
+     * inside a renderer must pass the SHAPE-AWARE resolver (`portWorldPosition`) —
+     * see the note on `findNearestPort`.
+     */
+    portPosition?: (port: PortModel, node: NodeModel) => Point;
+}
+/** What {@link DiagramModel.findNearestPort} found. */
+export interface NearestPortHit {
+    port: PortModel;
+    node: NodeModel;
+    /** Distance from the query point to the port, in world units. */
+    distance: number;
+}
+export interface SerializedDiagram extends SerializedEntity {
+    /**
+     * Document schema version (shape of THIS payload), distinct from the
+     * per-entity mutation counter `version`. Absent on pre-versioning
+     * documents, which are treated as schemaVersion 1 and migrated on load.
+     */
+    schemaVersion?: number;
+    name: string;
+    nodes: SerializedNode[];
+    links: SerializedLink[];
+    groups: SerializedGroup[];
+    /**
+     * wave10/whiteboard: freehand ink.
+     *
+     * OMITTED when there is none — the same rule (and for the same load-bearing reason)
+     * as `comments` below. A diagram with no ink serializes to EXACTLY the bytes it did
+     * before this wave: no churn in any existing document, snapshot or golden file, and
+     * the op log's byte-identical replay oracle keeps comparing the same bytes it always
+     * compared. An always-present `strokes: []` would have quietly rewritten every
+     * serialized diagram in the world to say nothing.
+     */
+    strokes?: SerializedStroke[];
+    viewport: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        zoom: number;
+    };
+    /**
+     * wave9/comments (Card 6): anchored comment threads. Document data, saved with the
+     * document — a comment that does not survive a save is a comment that does not exist.
+     *
+     * OMITTED when there are none, rather than written as `{}`. Two reasons, one of them
+     * load-bearing: a diagram with no comments serializes to EXACTLY the bytes it did
+     * before this card (no churn in any existing document, snapshot or golden file), and
+     * the op log's byte-identical replay oracle keeps comparing the same bytes it always
+     * compared. An always-present empty object would have quietly rewritten every
+     * serialized diagram in the world to say nothing.
+     */
+    comments?: CommentRegisterTree;
+}
+export interface DiagramLoadOptions {
+    /**
+     * Structural integrity policy for the incoming document:
+     *  - 'off'    (default) skip validation
+     *  - 'warn'   validate and console.warn a one-line summary with the report
+     *  - 'strict' validate and throw DiagramValidationError on any error
+     */
+    validate?: 'off' | 'warn' | 'strict';
+}
+export declare class DiagramModel extends DiagramEntity {
+    name: string;
+    nodes: Map<string, NodeModel>;
+    links: Map<string, LinkModel>;
+    groups: Map<string, GroupModel>;
+    /** wave10/whiteboard: freehand ink strokes. See StrokeModel for why these are not nodes. */
+    strokes: Map<string, StrokeModel>;
+    /**
+     * 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.
+     */
+    private readonlyLock;
+    private portIndex;
+    /**
+     * 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.
+     */
+    private detachedAnchors;
+    /**
+     * 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.
+     */
+    linkIntegrityOwner: 'model' | 'external';
+    private _comments;
+    /** The comment register tree. Read-only in spirit: write through writeCommentRegister. */
+    get comments(): CommentRegisterTree;
+    /**
+     * 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: CommentRegisterTree);
+    /**
+     * 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: string, value: unknown): boolean;
+    /** Read one register. Returns undefined for any missing segment — never throws. */
+    readCommentRegister(path: string): unknown;
+    viewport: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        zoom: number;
+    };
+    private nodeSpatialIndex;
+    private linkSpatialIndex;
+    private _layoutManager;
+    private _autoLayoutEnabled;
+    private _pendingEvents;
+    private _lodConfig;
+    private _lodTiersDesc;
+    constructor(name?: string, options?: {
+        lodConfig?: LODConfig;
+        id?: string;
+        uuid?: string;
+    });
+    /**
+     * 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.
+     */
+    private computeLinkBounds;
+    /**
+     * 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: LinkModel): void;
+    /**
+     * Add node to diagram
+     */
+    /** Is this document locked against edits? */
+    isReadonly(): boolean;
+    /**
+     * 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: boolean): void;
+    /** True when a document mutation must be refused right now. */
+    blocksDocumentWrite(): boolean;
+    /**
+     * 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(): boolean;
+    /**
+     * 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<T>(fn: () => T): T;
+    addNode(node: NodeModel): void;
+    /**
+     * 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.
+     */
+    private installNode;
+    /**
+     * 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: string): NodeModel | undefined;
+    /**
+     * 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: string): LinkModel[];
+    /**
+     * Restore node from serialized data (Phase 1.8)
+     */
+    restoreNode(data: any): NodeModel | undefined;
+    /**
+     * Get node by ID
+     */
+    getNode(nodeId: string): NodeModel | undefined;
+    /**
+     * Get all nodes
+     */
+    getNodes(): NodeModel[];
+    /**
+     * 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: string): NodeModel | undefined;
+    /**
+     * 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: string): PortModel | undefined;
+    /**
+     * 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: string): DetachedParentAnchor | undefined;
+    /**
+     * 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.
+     */
+    private indexNodePorts;
+    /**
+     * Drop a node's ports from the index (called on removeNode).
+     */
+    private unindexNodePorts;
+    /**
+     * Clear all nodes
+     */
+    clearNodes(): void;
+    /**
+     * Add link to diagram
+     */
+    addLink(link: LinkModel): void;
+    /**
+     * 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.
+     */
+    private installLink;
+    /**
+     * Remove link from diagram
+     */
+    removeLink(linkId: string): LinkModel | undefined;
+    /**
+     * Restore link from serialized data (Phase 1.8)
+     */
+    restoreLink(data: any): LinkModel | undefined;
+    /**
+     * Get link by ID
+     */
+    getLink(linkId: string): LinkModel | undefined;
+    /**
+     * Get all links
+     */
+    getLinks(): LinkModel[];
+    /**
+     * Phase 0.2: Get all links connected to a specific port
+     */
+    getLinksForPort(portId: string): LinkModel[];
+    /**
+     * Clear all links
+     */
+    clearLinks(): void;
+    /**
+     * 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: NodeModel, targetNode: NodeModel, pathType?: 'direct' | 'orthogonal' | 'smooth' | 'bezier'): LinkModel | undefined;
+    /**
+     * 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: NodeModel, targetNode: NodeModel, pathType?: 'direct' | 'orthogonal' | 'smooth' | 'bezier'): boolean;
+    /**
+     * 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: NodeModel): {
+        incoming: LinkModel[];
+        outgoing: LinkModel[];
+        all: LinkModel[];
+    };
+    /**
+     * 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: NodeModel, targetNode: NodeModel): number;
+    /**
+     * Add group (Phase 1.6c)
+     */
+    addGroup(group: GroupModel): void;
+    /**
+     * 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.
+     */
+    private installGroup;
+    /**
+     * Remove group (Phase 1.6c)
+     */
+    removeGroup(groupId: string): GroupModel | undefined;
+    /**
+     * Restore group from serialized data (Phase 1.8)
+     */
+    restoreGroup(data: any): GroupModel | undefined;
+    /**
+     * Get group by ID (Phase 1.6c)
+     */
+    getGroup(groupId: string): GroupModel | undefined;
+    /**
+     * Get all groups (Phase 1.6c)
+     */
+    getGroups(): GroupModel[];
+    /**
+     * 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(): GroupModel[];
+    /**
+     * 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: string): NodeModel | undefined;
+    /** Wave-5 Card 4: is this node a collapsed-group placeholder? */
+    isProxyNode(node: NodeModel): boolean;
+    /**
+     * Clear all groups (Phase 1.6c)
+     */
+    clearGroups(): void;
+    addStroke(stroke: StrokeModel): void;
+    /** THE single per-stroke install path (see installNode) — authored, restored, or replayed. */
+    private installStroke;
+    removeStroke(strokeId: string): StrokeModel | undefined;
+    restoreStroke(data: SerializedStroke): StrokeModel | undefined;
+    getStroke(strokeId: string): StrokeModel | undefined;
+    getStrokes(): StrokeModel[];
+    clearStrokes(): void;
+    /** Strokes whose bounds overlap `viewport`. The ink layer's culling query. */
+    getVisibleStrokes(viewport: Rectangle): StrokeModel[];
+    /**
+     * 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: Point, b: Point, tolerance?: number): StrokeModel[];
+    /**
+     * 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: string): GroupModel[];
+    /**
+     * Get every group nested (directly or transitively) inside `groupId`.
+     * Breadth-first over the parentGroupId back-pointers.
+     */
+    getDescendants(groupId: string): GroupModel[];
+    /**
+     * Nesting depth of a group: number of ancestors (0 for a top-level group).
+     */
+    getDepth(groupId: string): number;
+    /**
+     * Selection Management
+     */
+    /**
+     * Get all selected nodes
+     */
+    getSelectedNodes(): NodeModel[];
+    /**
+     * Select a single node (clears previous selection)
+     * @param node - Node to select
+     */
+    selectNode(node: NodeModel): void;
+    /**
+     * Add node to selection (multi-select)
+     * @param node - Node to add to selection
+     */
+    addToSelection(node: NodeModel): void;
+    /**
+     * Remove node from selection
+     * @param node - Node to remove from selection
+     */
+    removeFromSelection(node: NodeModel): void;
+    /**
+     * Toggle node selection (add if not selected, remove if selected)
+     * @param node - Node to toggle
+     */
+    toggleNodeSelection(node: NodeModel): void;
+    /**
+     * Clear all selections
+     */
+    clearSelection(): void;
+    /**
+     * Select all nodes
+     */
+    selectAll(): void;
+    /**
+     * Delete all selected nodes and their connected links
+     * @returns Number of nodes deleted
+     */
+    deleteSelected(): number;
+    /**
+     * 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: number, y: number): NodeModel | 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: number, y: number, nodeId: string): boolean;
+    /** Is `ancestorId` anywhere up `node`'s parent chain? Cycle-guarded. */
+    private hasAncestor;
+    /**
+     * Option 3: Lock/pin selected nodes
+     * Locked nodes will not move during layout operations
+     */
+    lockSelected(): number;
+    /**
+     * Option 3: Unlock selected nodes
+     */
+    unlockSelected(): number;
+    /**
+     * Option 3: Get locked nodes
+     */
+    getLockedNodes(): NodeModel[];
+    /**
+     * Option 3: Unlock all nodes
+     */
+    unlockAll(): number;
+    /**
+     * Set viewport (Phase 0.5 - Viewport-Aware Layout)
+     */
+    setViewport(x: number, y: number, width: number, height: number, zoom?: number): void;
+    /**
+     * Get current viewport
+     */
+    getViewport(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        zoom: number;
+    };
+    /**
+     * Pan viewport
+     */
+    pan(dx: number, dy: number): void;
+    /**
+     * Zoom viewport (relative adjustment)
+     */
+    zoom(delta: number, center?: Point): void;
+    /**
+     * 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: number, center?: Point): void;
+    /**
+     * 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?: number): void;
+    /**
+     * 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: number, targetHeight: number, padding?: number): void;
+    /**
+     * Clear all nodes, links, and groups (Phase 1.6c)
+     */
+    clear(): void;
+    /**
+     * 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: Rectangle): NodeModel[];
+    /**
+     * 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: Rectangle): LinkModel[];
+    /**
+     * 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: Point, options?: NearestPortOptions): NearestPortHit | null;
+    /**
+     * 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: Rectangle): Rectangle | null;
+    /**
+     * Get all dirty nodes (Phase 5.2)
+     * Returns nodes that need re-rendering
+     */
+    getDirtyNodes(): NodeModel[];
+    /**
+     * Get all dirty links (Phase 5.2)
+     * Returns links that need re-rendering
+     */
+    getDirtyLinks(): LinkModel[];
+    /**
+     * Get all dirty groups (Phase 5.2)
+     * Returns groups that need re-rendering
+     */
+    getDirtyGroups(): GroupModel[];
+    /**
+     * Mark all entities as clean (Phase 5.2)
+     * Call this after rendering to reset dirty flags
+     */
+    markAllClean(): void;
+    /**
+     * Get total count of dirty entities (Phase 5.2)
+     * Useful for monitoring render performance
+     */
+    getDirtyCount(): number;
+    /**
+     * 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: Rectangle): NodeModel[];
+    /**
+     * 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: Rectangle): LinkModel[];
+    /**
+     * 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: number): LODLevel;
+    /**
+     * 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: LODFeature, lod: LODLevel): boolean;
+    /** Get the current Level-of-Detail policy. */
+    getLODConfig(): LODConfig;
+    /**
+     * Replace the Level-of-Detail policy wholesale. Apps use this to define
+     * their own tiers (names, breakpoints and feature sets).
+     */
+    setLODConfig(config: LODConfig): void;
+    /**
+     * 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: LODTier): void;
+    /** Keep the highest-minZoom-first tier cache in sync with _lodConfig. */
+    private _resortLODTiers;
+    /**
+     * 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: Rectangle, zoom: number): EntityWithLOD<NodeModel>[];
+    /**
+     * 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: Rectangle, zoom: number): EntityWithLOD<LinkModel>[];
+    /**
+     * 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: LODLevel): boolean;
+    /**
+     * 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: LODLevel): boolean;
+    /**
+     * 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: LODLevel): boolean;
+    /**
+     * 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: LODLevel): boolean;
+    /**
+     * Get the layout manager for this diagram
+     */
+    getLayoutManager(): LayoutManager;
+    /**
+     * Set layout algorithm
+     * @param type - Algorithm type ('grid', 'force-directed', 'hierarchical', 'hybrid')
+     * @param config - Optional configuration
+     */
+    setLayoutAlgorithm(type: LayoutAlgorithmType, config?: LayoutConfiguration): void;
+    /**
+     * Get current layout algorithm type
+     */
+    getLayoutAlgorithm(): LayoutAlgorithmType;
+    /**
+     * Configure current layout algorithm
+     */
+    configureLayout(config: LayoutConfiguration): void;
+    /**
+     * Get layout configuration
+     */
+    getLayoutConfiguration(): LayoutConfiguration;
+    /**
+     * Enable or disable automatic layout for new nodes
+     * When enabled, newly added nodes will be automatically positioned using the current layout algorithm
+     */
+    setAutoLayout(enabled: boolean): void;
+    /**
+     * Check if auto-layout is enabled
+     */
+    isAutoLayoutEnabled(): boolean;
+    /**
+     * Re-layout all nodes using current algorithm
+     * This will recalculate positions for all nodes in the diagram
+     */
+    reLayout(config?: LayoutConfiguration): Promise<void>;
+    /**
+     * Override: End batch update mode
+     * Fires accumulated events when all batches complete
+     */
+    endBatch(): void;
+    /**
+     * Emit event, respecting batch mode
+     * During batch mode, events are queued instead of fired immediately
+     */
+    private emitOrQueue;
+    /**
+     * Serialize to JSON
+     */
+    serialize(): SerializedDiagram;
+    /**
+     * 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(): Array<{
+        linkId: string;
+        portId: string;
+        end: 'source' | 'target';
+    }>;
+    /**
+     * 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: DiagramIncremental): void;
+    /** In-place node update from serialized data (identity preserved). */
+    private applySerializedNode;
+    /** In-place link update from serialized data (identity preserved). */
+    private applySerializedLink;
+    /** In-place group update from serialized data (identity preserved). */
+    private applySerializedGroup;
+    /**
+     * 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: SerializedDiagram, options?: DiagramLoadOptions): DiagramModel;
+    /**
+     * 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(): void;
+}