@grafloria/element 0.3.19 → 0.3.21

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

@@ -1,960 +0,0 @@
-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;
-}