@grafloria/element 0.3.17 → 0.3.19

package/src/libs/engine/src/engine/DiagramEngine.d.ts

@@ -0,0 +1,917 @@
+import { EventBus } from '../events/EventBus';
+import { TemplateRegistry } from '../templates/TemplateRegistry';
+import { DiagramStore } from '../state/DiagramStore';
+import { CommandManager } from '../commands/CommandManager';
+import { PluginManager } from '../plugins/PluginManager';
+import { TypeRegistry } from '../validation/TypeRegistry';
+import { ValidationEngine } from '../validation/ValidationEngine';
+import { DiagramSerializer, SerializedDiagram } from '../serialization/Serializer';
+import { PerformanceMonitor, PerformanceReport } from '../performance/PerformanceMonitor';
+import { DiagramModel } from '../models/DiagramModel';
+import { NodeModel } from '../models/NodeModel';
+import { LinkModel } from '../models/LinkModel';
+import { GroupModel } from '../models/GroupModel';
+import type { CollapseOptions } from '../interaction/GroupCollapseService';
+import { ClipboardManager } from '../clipboard/ClipboardManager';
+import { SelectionManager } from '../selection/SelectionManager';
+import { DiagramMode } from './DiagramMode';
+import { ModeManager } from './ModeManager';
+import { ConnectionStateManager } from '../state/ConnectionStateManager';
+import type { InteractionConfig } from '../config/InteractionConfig';
+import { RoutingEngine } from '../routing/RoutingEngine';
+import { LiveReroutingEngine } from '../routing/LiveReroutingEngine';
+import type { ModeGuardFunction, ModeViewportSettings, ModeHistoryEntry, ModeAnalytics, ModeChangeHook } from './DiagramModeTypes';
+import type { Point, Size, Viewport } from '../types';
+import type { Plugin } from '../types';
+import type { ValidationResult } from '../validation/ValidationEngine';
+import type { NodeTypeDefinition, LinkTypeDefinition, PortTypeDefinition, GroupTypeDefinition } from '../validation/TypeRegistry';
+import { LayoutRegistry, type UnifiedLayoutOptions, type UnifiedLayoutResult } from '../layout/layout-registry';
+import { type IncrementalOptions, type MovementReport, type TweenPlan } from '../layout/incremental/mental-map';
+import { type LayoutPort } from '../layout/layout-host';
+import type { LayoutType, LayoutConfig, FlexItemConfig, GridItemConfig } from '../types/layout.types';
+export interface DiagramEngineConfig {
+    plugins?: Plugin[];
+    mode?: DiagramMode;
+    performance?: {
+        enableMonitoring?: boolean;
+        enableProfiling?: boolean;
+        warnThreshold?: number;
+    };
+    validation?: {
+        realTime?: boolean;
+        strict?: boolean;
+    };
+    history?: {
+        maxCommands?: number;
+        maxSnapshots?: number;
+    };
+    interaction?: Partial<InteractionConfig>;
+}
+/**
+ * Wave 2 (Edges & links): transient state for the endpoint-reconnection live
+ * preview. Set by the interaction layer while an endpoint handle is being
+ * dragged; read by the renderer to draw a ghost link from the stationary
+ * endpoint to the cursor. Deliberately separate from {@link ConnectionStateManager}
+ * (which owns NEW-link creation) so the two previews never double-render.
+ */
+export interface ReconnectionPreview {
+    /** Id of the link whose endpoint is being reconnected. */
+    linkId: string;
+    /** Which endpoint the cursor is dragging (the OTHER end stays fixed). */
+    endpoint: 'source' | 'target';
+    /** Current cursor position in world coordinates. */
+    mousePoint: Point;
+    /** Whether the port/node currently under the cursor is a valid drop target. */
+    isValid: boolean;
+}
+/**
+ * wave12/connect-ergonomics: the port pair a proximity-connect DROP would link,
+ * while a node drag is inside the radius. The renderer reads this to draw the
+ * proposed wire itself — highlighting only the two ports left the proposal
+ * nearly invisible (live report: "the wire isn't showing"). Same seam shape as
+ * {@link ReconnectionPreview}: interaction layer writes, renderer reads,
+ * cleared on drop/cancel.
+ */
+export interface ProximityPreview {
+    sourceNodeId: string;
+    sourcePortId: string;
+    targetNodeId: string;
+    targetPortId: string;
+}
+/**
+ * wave15/helper-lines: one drawable snap-guide segment, in world coordinates.
+ * The interaction layer computes alignment / equal-spacing guides during a
+ * node drag and publishes them here; the renderer draws them as dashed
+ * overlay lines (spacing segments may carry a gap label). Cleared (null) when
+ * the drag ends or nothing is within snapping distance.
+ */
+export interface SnapGuideSegment {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    kind: 'alignment' | 'spacing';
+    label?: string;
+}
+export declare class DiagramEngine {
+    readonly eventBus: EventBus;
+    readonly store: DiagramStore;
+    readonly commandManager: CommandManager;
+    readonly pluginManager: PluginManager;
+    readonly typeRegistry: TypeRegistry;
+    readonly validationEngine: ValidationEngine;
+    readonly serializer: DiagramSerializer;
+    readonly performanceMonitor: PerformanceMonitor;
+    readonly modeManager: ModeManager;
+    readonly clipboardManager: ClipboardManager;
+    readonly selectionManager: SelectionManager;
+    readonly routingEngine: RoutingEngine;
+    readonly templateRegistry: TemplateRegistry;
+    private liveReroutingEngine;
+    private diagram;
+    private diagramDisposers;
+    private config;
+    private interactionConfig;
+    private connectionStateManager;
+    private reconcilingDynamicPorts;
+    private reconnectionPreview;
+    private proximityPreview;
+    private snapGuides;
+    private initialized;
+    private destroyed;
+    constructor(config?: DiagramEngineConfig);
+    /**
+     * Get current diagram
+     */
+    getDiagram(): DiagramModel | null;
+    /**
+     * Get configuration (Phase 1 - Critical Fixes)
+     */
+    getConfig(): DiagramEngineConfig;
+    /**
+     * Phase 1: Get interaction configuration
+     * Returns the current interaction mode settings
+     */
+    getInteractionConfig(): InteractionConfig;
+    /**
+     * Phase 1: Set interaction configuration
+     * Updates interaction mode settings and emits event
+     */
+    setInteractionConfig(config: Partial<InteractionConfig>): void;
+    /**
+     * Phase 1: Get connection state manager
+     * Used for managing connection drag operations
+     */
+    getConnectionStateManager(): ConnectionStateManager;
+    /**
+     * Wave 2 (Edges & links): current endpoint-reconnection preview, or null when
+     * no endpoint is being dragged. The renderer reads this to draw a ghost link.
+     */
+    getReconnectionPreview(): ReconnectionPreview | null;
+    /**
+     * Wave 2 (Edges & links): set (or clear, with null) the endpoint-reconnection
+     * preview. Called by the interaction layer on start/move/end of an endpoint
+     * drag. Does not emit — the interaction layer already triggers re-render.
+     */
+    setReconnectionPreview(preview: ReconnectionPreview | null): void;
+    /** The proximity-connect proposal the renderer draws as a live wire, or null. */
+    getProximityPreview(): ProximityPreview | null;
+    /** Set (or clear, with null) the proximity-connect proposal. Does not emit —
+     *  the node drag that drives it already triggers re-renders. */
+    setProximityPreview(preview: ProximityPreview | null): void;
+    /** The live snap-guide segments a node drag is showing, or null. */
+    getSnapGuides(): SnapGuideSegment[] | null;
+    /** Set (or clear, with null) the live snap guides. Does not emit — the node
+     *  drag that drives them already triggers re-renders. */
+    setSnapGuides(guides: SnapGuideSegment[] | null): void;
+    /**
+     * Get routing engine
+     * Used for calculating link paths with various algorithms
+     */
+    getRoutingEngine(): RoutingEngine;
+    /**
+     * Phase 0.2: Enable live rerouting
+     * Automatically updates link paths when nodes move or resize
+     */
+    enableLiveRerouting(): void;
+    /**
+     * Phase 0.2: Disable live rerouting
+     */
+    disableLiveRerouting(): void;
+    /**
+     * Phase 0.2: Get live rerouting engine
+     */
+    getLiveReroutingEngine(): LiveReroutingEngine | null;
+    /**
+     * Set diagram
+     */
+    setDiagram(diagram: DiagramModel | null): void;
+    /**
+     * Create new diagram
+     */
+    createDiagram(name?: string): DiagramModel;
+    /**
+     * Clear diagram
+     */
+    clearDiagram(): void;
+    /**
+     * Add node (from config)
+     */
+    addNode(config: {
+        type: string;
+        position: Point;
+        size?: Size;
+        data?: any;
+    }): Promise<NodeModel>;
+    /**
+     * Add node (pre-created NodeModel) (Phase 1.6b)
+     */
+    addNode(node: NodeModel): Promise<NodeModel>;
+    /**
+     * Remove node
+     *
+     * Wave 14: async + awaited, mirroring removeGroup(). The execute() promise
+     * used to float — a command failure became an unhandled rejection (fatal
+     * under Node), and callers could not sequence on the removal completing.
+     */
+    removeNode(nodeId: string): Promise<void>;
+    /**
+     * Wave 6 (Card 7): top up (or trim) the dynamic port groups on the nodes at
+     * either end of `link`.
+     *
+     * Runs through the COMMAND layer, so a spawned port is undoable and arrives
+     * with the same events and dirty-tracking as any other model change. Guarded
+     * against re-entry: an AddPortCommand does not itself add a link, but a host
+     * validator could, and a self-feeding allocator would be a delightful way to
+     * hang the app.
+     */
+    private reconcileDynamicPorts;
+    /** The nodes a link touches — resolved by id, or by searching for its ports. */
+    private reconcileDynamicPortsFor;
+    /**
+     * Add link
+     */
+    addLink(config: {
+        sourcePortId: string;
+        targetPortId: string;
+        type?: string;
+        data?: any;
+    }): Promise<LinkModel>;
+    /**
+     * Remove link
+     *
+     * Wave 14: async + awaited, mirroring removeGroup() — see removeNode().
+     */
+    removeLink(linkId: string): Promise<void>;
+    /**
+     * Add group (Phase 1.6c)
+     */
+    addGroup(config: {
+        name: string;
+    }): Promise<GroupModel>;
+    /**
+     * Remove group (Phase 1.6c)
+     */
+    removeGroup(groupId: string): Promise<void>;
+    /**
+     * Add entity to group (Phase 1.6c)
+     */
+    addToGroup(groupId: string, entityId: string): Promise<void>;
+    /**
+     * Remove entity from group (Phase 1.6c)
+     */
+    removeFromGroup(groupId: string, entityId: string): Promise<void>;
+    /**
+     * Expand group (Phase 1.6c)
+     */
+    expandGroup(groupId: string): Promise<void>;
+    /**
+     * Collapse group (Phase 1.6c)
+     */
+    collapseGroup(groupId: string, options?: CollapseOptions): Promise<void>;
+    /**
+     * Get group by ID (Phase 1.6c)
+     */
+    getGroup(groupId: string): GroupModel | undefined;
+    /**
+     * Get all groups (Phase 1.6c)
+     */
+    getGroups(): GroupModel[];
+    /**
+     * Set layout configuration on a group (Phase 1.7)
+     */
+    setLayout(groupId: string, layoutType: 'flexbox' | 'grid', layoutConfig: LayoutConfig): Promise<void>;
+    /**
+     * Clear layout configuration from a group (Phase 1.7)
+     */
+    clearLayout(groupId: string): Promise<void>;
+    /**
+     * Get layout configuration from a group (Phase 1.7)
+     */
+    getLayout(groupId: string): {
+        type: LayoutType;
+        config?: LayoutConfig;
+    } | undefined;
+    /**
+     * Set flex item configuration on a node (Phase 1.7)
+     */
+    setFlexItem(nodeId: string, flexConfig: FlexItemConfig): Promise<void>;
+    /**
+     * Set grid item configuration on a node (Phase 1.7)
+     */
+    setGridItem(nodeId: string, gridConfig: GridItemConfig): Promise<void>;
+    /**
+     * Copy selected entities to clipboard (Phase 1.8)
+     */
+    copy(options?: {
+        includeGroups?: boolean;
+        includeLinks?: boolean;
+    }): Promise<void>;
+    /**
+     * Paste entities from clipboard (Phase 1.8)
+     */
+    paste(options?: {
+        offset?: Point;
+        selectPasted?: boolean;
+    }): Promise<void>;
+    /**
+     * Duplicate selected entities (Phase 1.8)
+     */
+    duplicate(options?: {
+        offset?: Point;
+        selectDuplicated?: boolean;
+    }): Promise<void>;
+    /**
+     * Delete selected entities (Phase 1.8)
+     */
+    deleteSelection(options?: {
+        deleteChildren?: boolean;
+        deleteLinks?: boolean;
+    }): Promise<void>;
+    /**
+     * Get clipboard data (Phase 1.8)
+     */
+    getClipboardData(): import("../clipboard/ClipboardManager").ClipboardData | null;
+    /**
+     * Check if clipboard has data (Phase 1.8)
+     */
+    hasClipboardData(): boolean;
+    /**
+     * Clear clipboard (Phase 1.8)
+     */
+    clearClipboard(): void;
+    /**
+     * Get clipboard statistics (Phase 1.8)
+     */
+    getClipboardStats(): {
+        nodeCount: number;
+        linkCount: number;
+        groupCount: number;
+        timestamp: number | null;
+    };
+    /**
+     * Validate the entire diagram
+     * @param options Validation options
+     * @returns Validation result with errors and warnings
+     */
+    validateDiagram(options?: {
+        validateTypes?: boolean;
+        validateConnections?: boolean;
+        validatePorts?: boolean;
+        strict?: boolean;
+    }): ValidationResult;
+    /**
+     * Validate a specific node
+     * @param nodeId Node ID to validate
+     * @param options Validation options
+     * @returns Validation result with errors and warnings
+     */
+    validateNode(nodeId: string, options?: {
+        validateTypes?: boolean;
+        validateConnections?: boolean;
+        validatePorts?: boolean;
+        strict?: boolean;
+    }): ValidationResult;
+    /**
+     * Validate a specific link
+     * @param linkId Link ID to validate
+     * @param options Validation options
+     * @returns Validation result with errors and warnings
+     */
+    validateLink(linkId: string, options?: {
+        validateTypes?: boolean;
+        validateConnections?: boolean;
+        validatePorts?: boolean;
+        strict?: boolean;
+    }): ValidationResult;
+    /**
+     * Validate a specific port
+     * @param portId Port ID to validate
+     * @param nodeId Node ID containing the port
+     * @param options Validation options
+     * @returns Validation result with errors and warnings
+     */
+    validatePort(portId: string, nodeId: string, options?: {
+        validateTypes?: boolean;
+        validateConnections?: boolean;
+        validatePorts?: boolean;
+        strict?: boolean;
+    }): ValidationResult;
+    /**
+     * Validate layout configuration for a group (Phase 3 - Layout validation)
+     */
+    validateLayout(groupId: string, options?: {
+        strict?: boolean;
+    }): ValidationResult;
+    /**
+     * Register a node type definition
+     * @param definition Node type definition
+     */
+    registerNodeType(definition: NodeTypeDefinition): void;
+    /**
+     * Register a port type definition
+     * @param definition Port type definition
+     */
+    registerPortType(definition: PortTypeDefinition): void;
+    /**
+     * Register a link type definition
+     * @param definition Link type definition
+     */
+    registerLinkType(definition: LinkTypeDefinition): void;
+    /**
+     * Register a group type definition (Phase 2 - Group validation)
+     * @param definition Group type definition
+     */
+    registerGroupType(definition: GroupTypeDefinition): void;
+    /**
+     * Enable real-time validation
+     */
+    enableRealTimeValidation(): void;
+    /**
+     * Disable real-time validation
+     */
+    disableRealTimeValidation(): void;
+    /**
+     * Check if real-time validation is enabled
+     */
+    isRealTimeValidationEnabled(): boolean;
+    /**
+     * Select nodes
+     */
+    selectNodes(nodeIds: string[]): void;
+    /**
+     * Select links
+     */
+    selectLinks(linkIds: string[]): void;
+    /**
+     * Clear selection
+     */
+    clearSelection(): void;
+    /**
+     * Undo
+     */
+    undo(): Promise<void>;
+    /**
+     * Redo
+     */
+    redo(): Promise<void>;
+    /**
+     * Can undo
+     */
+    canUndo(): boolean;
+    /**
+     * Can redo
+     */
+    canRedo(): boolean;
+    /**
+     * Validate diagram
+     */
+    validate(): ValidationResult;
+    /**
+     * Serialize diagram (with mode)
+     */
+    serialize(): SerializedDiagram | null;
+    /**
+     * Deserialize diagram (with mode)
+     */
+    deserialize(data: SerializedDiagram, options?: import('../models/DiagramModel').DiagramLoadOptions): DiagramModel;
+    /**
+     * Load diagram from JSON (with mode)
+     */
+    loadFromJSON(json: string | SerializedDiagram, options?: import('../models/DiagramModel').DiagramLoadOptions): DiagramModel;
+    /**
+     * Save diagram to JSON
+     */
+    saveToJSON(): string | null;
+    /**
+     * Register a plugin AND bring it to life.
+     *
+     * `PluginManager.register()` only RECORDS a plugin; `install()` and
+     * `activate()` are separate steps. Calling register alone — which both of
+     * this engine's entry points used to do — left every plugin permanently
+     * inert: its hooks never fired, though `getPlugin()` happily returned it.
+     * "Register a plugin" can only sensibly mean "make it run", so this drives
+     * the full lifecycle. A plugin that throws is reported and skipped rather
+     * than taking the host down with it.
+     */
+    registerPlugin(plugin: Plugin): Promise<void>;
+    /**
+     * Get plugin
+     */
+    getPlugin(name: string): Plugin | undefined;
+    /**
+     * Set viewport
+     */
+    setViewport(viewport: Viewport): void;
+    /**
+     * Set zoom
+     */
+    setZoom(zoom: number): void;
+    /**
+     * Get performance report
+     */
+    getPerformanceReport(): PerformanceReport;
+    /**
+     * Get current diagram mode
+     */
+    getMode(): DiagramMode;
+    /**
+     * Set diagram mode
+     */
+    setMode(mode: DiagramMode): void;
+    /**
+     * Wave 9 — Card 7. Push the mode's read-only verdict down onto the DOCUMENT.
+     *
+     * Before this wave `DiagramMode.VIEW` / `PRESENTATION` and `isReadOnlyMode()`
+     * existed, were documented as "all editing disabled" — and gated NOTHING. Not a
+     * command, not a model mutator, not the event binder. They were a boolean nobody
+     * asked. This is the line that makes the mode real: the model holds the lock, and
+     * the model is where mutation actually happens.
+     *
+     * Call it after any mode change, and whenever a diagram is attached (a diagram
+     * loaded into an engine that is ALREADY in presentation mode must come up locked,
+     * or read-only would depend on the order the host happened to call things in).
+     */
+    private syncReadonlyLock;
+    /**
+     * Check if in designer mode
+     */
+    isDesignerMode(): boolean;
+    /**
+     * Check if in running mode
+     */
+    isRunningMode(): boolean;
+    /**
+     * Check if in view mode
+     */
+    isViewMode(): boolean;
+    /**
+     * Check if in debug mode
+     */
+    isDebugMode(): boolean;
+    /**
+     * Check if in presentation mode
+     */
+    isPresentationMode(): boolean;
+    /**
+     * Check if in read-only mode (any mode except designer)
+     */
+    isReadOnlyMode(): boolean;
+    /**
+     * Add mode transition guard
+     */
+    addModeGuard(name: string, guard: ModeGuardFunction): void;
+    /**
+     * Remove mode transition guard
+     */
+    removeModeGuard(name: string): void;
+    /**
+     * Clear all mode transition guards
+     */
+    clearModeGuards(): void;
+    /**
+     * Configure viewport settings for specific mode
+     */
+    configureModeViewport(mode: DiagramMode, settings: ModeViewportSettings): void;
+    /**
+     * Get viewport settings for specific mode
+     */
+    getModeViewportSettings(mode: DiagramMode): ModeViewportSettings;
+    /**
+     * Get mode history
+     */
+    getModeHistory(): ModeHistoryEntry[];
+    /**
+     * Clear mode history
+     */
+    clearModeHistory(): void;
+    /**
+     * Navigate to previous mode
+     */
+    previousMode(): void;
+    /**
+     * Navigate to next mode
+     */
+    nextMode(): void;
+    /**
+     * Push mode onto stack (save current, switch to new)
+     */
+    pushMode(mode: DiagramMode): void;
+    /**
+     * Pop mode from stack (return to previous)
+     */
+    popMode(): void;
+    /**
+     * Get mode analytics
+     */
+    getModeAnalytics(): ModeAnalytics;
+    /**
+     * Register before mode change hook
+     */
+    beforeModeChange(hook: ModeChangeHook): () => void;
+    /**
+     * Register after mode change hook
+     */
+    afterModeChange(hook: ModeChangeHook): () => void;
+    /**
+     * Get link behavior adjusted for current mode
+     */
+    getLinkBehaviorForMode(baseBehavior: Partial<{
+        deletable: boolean;
+        selectable: boolean;
+    }>): {
+        deletable: boolean;
+        selectable: boolean;
+    };
+    /**
+     * Initialize the engine
+     */
+    initialize(): void;
+    /**
+     * Get the store
+     */
+    getStore(): DiagramStore;
+    /**
+     * Subscribe to events
+     */
+    on(event: string, listener: (...args: any[]) => void): void;
+    /**
+     * Unsubscribe from events
+     */
+    off(event: string, listener: (...args: any[]) => void): void;
+    /**
+     * Destroy engine
+     */
+    destroy(): void;
+    /**
+     * Configure systems
+     */
+    private configureSystems;
+    /**
+     * Install plugins
+     */
+    private installPlugins;
+    /**
+     * Register a node as an obstacle in the routing engine
+     */
+    private registerNodeAsObstacle;
+    /**
+     * Wave 5 (Edge routing) — Card 6: reconcile the shared ObstacleMap with the
+     * diagram's GROUP state, idempotently:
+     *
+     *   - a COLLAPSED group (with geometry) is ONE solid obstacle;
+     *   - members hidden under a collapsed group (at any depth) are NOT obstacles
+     *     — they are not visible, and routing around invisible things produces
+     *     inexplicable detours;
+     *   - expanding restores the members and removes the group block.
+     *
+     * Runs on every group add/remove/collapse/expand. Public so the grouping
+     * feature (which owns collapse SEMANTICS but not the ObstacleMap) can force a
+     * reconcile after batch operations.
+     */
+    refreshGroupObstacles(): void;
+    private groupObstacleRect;
+    /**
+     * Update a node's obstacle when it moves or resizes
+     * Also invalidates all links so they recalculate paths with new obstacle positions
+     */
+    private updateNodeObstacle;
+    /**
+     * Unregister a node obstacle when node is removed
+     */
+    private unregisterNodeObstacle;
+    /**
+     * Attach diagram
+     */
+    private attachDiagram;
+    /**
+     * Detach diagram
+     */
+    private detachDiagram;
+    /**
+     * Find port in diagram
+     */
+    private findPort;
+    /**
+     * Get node that owns a port (Phase 1.6b)
+     */
+    private getNodeForPort;
+    /**
+     * Get port position in global coordinates (Phase 1.6b)
+     * @param portId Port ID
+     * @returns Global position of the port
+     */
+    private getPortGlobalPosition;
+    /**
+     * Compute link path using specified routing algorithm (Phase 1.6b)
+     * @param linkId Link ID
+     * @param algorithm Routing algorithm to use
+     * @param options Routing options
+     * @returns Array of points forming the path
+     */
+    private computeLinkPath;
+    /**
+     * Generate link path using RoutingEngine with obstacle avoidance
+     * This ensures the final link respects the routing algorithm setting (A*, none, etc.)
+     */
+    private generateLinkPathWithRouting;
+    private layoutService?;
+    /**
+     * Set layout service for diagram layouts
+     *
+     * @param service - Layout service instance
+     */
+    setLayoutService(service: {
+        applyLayout(diagram: DiagramModel, config: any): Promise<any>;
+    }): void;
+    /** Lazily-built registry of the built-in layout engines. */
+    private _layoutRegistry?;
+    /**
+     * The named-algorithm registry, with the built-ins already registered.
+     *
+     * THE BUG THIS CLOSES: `applyLayout()` below requires `setLayoutService()` —
+     * and NOTHING in the codebase ever called it (the only mention is a doc comment
+     * in layout/index.ts). So dagre, ELK, force, spectral and community — thousands
+     * of lines, several of them untested — were UNREACHABLE from the engine. That
+     * is the whole "auto-layout is fragmented" finding. Layout now works out of the
+     * box, with no setup call.
+     */
+    getLayoutRegistry(): LayoutRegistry;
+    /**
+     * Lay out the whole diagram.
+     *
+     *     await engine.layout('dagre', { direction: 'LR' });
+     *
+     * DETERMINISTIC and IDEMPOTENT: the same graph and seed produce byte-identical
+     * coordinates, and running it twice changes nothing the second time. (The seed
+     * defaults to a fixed constant, so an author who never thinks about seeds still
+     * gets the same picture on every reload; randomness is opt-in.)
+     *
+     * NOT to be confused with `DiagramModel.getLayoutManager()`, which answers a
+     * DIFFERENT question — "where should this ONE newly-added node go?" — and is a
+     * placement strategy, not a graph layout. The audit called them "two parallel
+     * stacks" and asked for them to be merged; they are not parallel, and merging
+     * them would force a single-node placer to pretend it can lay out a graph.
+     */
+    layout(name?: string, options?: UnifiedLayoutOptions): Promise<UnifiedLayoutResult>;
+    /**
+     * Wave 7 — Card 6: mental-map-preserving incremental layout.
+     *
+     *     await engine.layoutIncremental({ changed: [newNode.id], budget: { maxPerNode: 60 } });
+     *
+     * Mermaid re-renders the whole diagram from scratch on every edit and destroys the
+     * user's spatial memory of their own diagram. This does the opposite:
+     *
+     *   1. everything outside the affected region becomes a Card-5 ANCHOR — an
+     *      immovable obstacle the layout works AROUND (impossible before Card 5, when
+     *      "constraints" were positions clamped after an unconstrained run);
+     *   2. the result is RE-ALIGNED onto the previous layout by matching centroids —
+     *      exactly the translation that minimises squared displacement, because a
+     *      layered layout is defined only up to translation, so one new node widening
+     *      a rank slides the whole picture sideways and makes every node "move" while
+     *      the drawing is unchanged;
+     *   3. movement is MEASURED against an explicit budget and reported.
+     *
+     * Returns a tween PLAN rather than animating: the engine says where things go at
+     * time t, the host drives t — which is what keeps this runnable in a worker, in
+     * SSR and in a test.
+     *
+     * ONE SEMANTIC, STATED PLAINLY. This runs the `layered` engine, because it is the
+     * only one that honours anchors DURING coordinate assignment. If the diagram's
+     * current positions came from a DIFFERENT engine, the first incremental pass
+     * necessarily re-draws it — and that is not a bug to paper over: "move as little
+     * as possible" is ill-posed across engines, because there is no meaningful small
+     * move between two engines' idea of the same graph.
+     */
+    layoutIncremental(options?: IncrementalOptions & {
+        name?: string;
+    } & UnifiedLayoutOptions): Promise<UnifiedLayoutResult & {
+        movement: MovementReport;
+        tween: TweenPlan;
+    }>;
+    /** Every node's current position, keyed by id — the pre-layout baseline. */
+    private snapshotNodePositions;
+    /**
+     * THE FIX for the stale-polyline bug: layout moves NODES, but each link keeps
+     * the polyline it was routed on before. The renderer treats a non-empty
+     * `link.points` as painted geometry and edge LABELS are placed by walking it
+     * (LabelRenderer via `link.getPointAtPosition`) — so after `engine.layout()`
+     * the labels sat at PRE-layout midpoints, observed live as "yes"/"no"
+     * stranded off-canvas at the old world coordinates while the nodes moved.
+     *
+     * Emptying the polyline is the canonical "re-route me" state: the renderer's
+     * frame pre-pass recomputes the route from the CURRENT node/port geometry on
+     * the next paint, and `setPoints` marks the link dirty so the cached VNode
+     * cannot be reused. Only links whose endpoint nodes actually MOVED are
+     * touched — an anchored subgraph's links keep their (still valid) routes.
+     *
+     * Manual waypoints are cleared with the route, same as `setPathType` /
+     * `setRouter` do: they were authored against the pre-layout coordinates, and
+     * an empty polyline with the manual flag still set would send the renderer
+     * down its keep-the-interior-waypoints branch with no interior to keep.
+     */
+    private invalidateStaleLinkRoutes;
+    /**
+     * Commit computed positions onto the real nodes.
+     *
+     * `setPosition()` rather than a raw write, so the spatial index, the routing
+     * obstacle map and the renderer all see the move — the wave-5 lesson: a
+     * subscription to an event nobody emits is a subscription to nothing.
+     *
+     * This is also the reason a partial result is USEFUL rather than merely
+     * honest: the best-so-far positions land on the diagram exactly like final
+     * ones, so a cancelled layout leaves a real, coherent picture behind.
+     */
+    private commitLayoutPositions;
+    /**
+     * Run layout off the main thread.
+     *
+     * The engine does NOT construct the Worker — that would bake one bundler's URL
+     * scheme into the engine, which is exactly what the old (never-instantiated)
+     * `LayoutWorkerPool` did with its hardcoded `/assets/workers/layout.worker.js`.
+     * The caller builds the worker however its toolchain likes and hands it in:
+     *
+     *     const worker = new Worker(new URL('./layout.worker', import.meta.url),
+     *                               { type: 'module' });
+     *     engine.setLayoutPort(worker as unknown as LayoutPort);
+     *
+     * Pass `undefined` to go back to running inline.
+     */
+    setLayoutPort(port?: LayoutPort): void;
+    private layoutPort?;
+    private layoutHost?;
+    private getLayoutHost;
+    /**
+     * Apply layout to current diagram
+     *
+     * @param config - Layout configuration
+     * @returns Layout result with positions and metadata
+     * @throws Error if no diagram is loaded or layout service is not initialized
+     * @deprecated Wave 7 Card 0 — use {@link layout} instead. This path requires a
+     * `setLayoutService()` call that nothing ever made, so it always threw.
+     */
+    applyLayout(config: {
+        adapter: string | any;
+        options?: any;
+        animate?: boolean;
+        animationDuration?: number;
+        fit?: boolean;
+        canvasDimensions?: {
+            width: number;
+            height: number;
+        };
+    }): Promise<{
+        nodePositions: Map<string, {
+            x: number;
+            y: number;
+        }>;
+        bounds: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        metadata?: any;
+    }>;
+    /**
+     * Quick helper: Apply Dagre layout
+     *
+     * @param options - Dagre layout options
+     * @param canvasDimensions - Optional canvas dimensions for viewport fitting
+     * @returns Layout result
+     */
+    applyDagreLayout(options?: {
+        rankdir?: 'TB' | 'BT' | 'LR' | 'RL';
+        align?: 'UL' | 'UR' | 'DL' | 'DR';
+        nodesep?: number;
+        edgesep?: number;
+        ranksep?: number;
+        marginx?: number;
+        marginy?: number;
+        ranker?: 'network-simplex' | 'tight-tree' | 'longest-path';
+    }, canvasDimensions?: {
+        width: number;
+        height: number;
+    }): Promise<any>;
+    /**
+     * Quick helper: Apply ELK layout
+     *
+     * @param options - ELK layout options
+     * @param canvasDimensions - Optional canvas dimensions for viewport fitting
+     * @returns Layout result
+     */
+    applyELKLayout(options?: {
+        algorithm?: 'layered' | 'force' | 'stress' | 'mrtree' | 'radial' | 'disco';
+        'elk.direction'?: 'RIGHT' | 'LEFT' | 'DOWN' | 'UP';
+        'elk.spacing.nodeNode'?: number;
+        [key: string]: any;
+    }, canvasDimensions?: {
+        width: number;
+        height: number;
+    }): Promise<any>;
+    /**
+     * Cleanup and dispose of all resources
+     * Should be called when the engine is no longer needed
+     */
+    dispose(): void;
+}