@realflow/core 0.1.0

package/dist/store.js

@@ -0,0 +1,1610 @@
+import { clamp, expandRect, fitRect, rectContainsRect, rectCenter, rectUnion, sideAnchor, snapToGrid, visibleRect, zoomAt, } from './geometry.js';
+import { SpatialIndex } from './spatial.js';
+import { computeGuides } from './guides.js';
+import { setsEqual, uid } from './utils.js';
+export const DEFAULT_NODE_WIDTH = 172;
+export const DEFAULT_NODE_HEIGHT = 44;
+/** Synthetic default-handle ids are internal; store them as undefined. */
+const normalizeHandleId = (id) => id == null || id === '__source' || id === '__target' ? undefined : id;
+const rafSchedule = (fn) => {
+    if (typeof requestAnimationFrame !== 'undefined')
+        requestAnimationFrame(fn);
+    else
+        fn();
+};
+/**
+ * FlowStore is ReFlow's reactive heart: a Map-backed graph store with
+ * fine-grained topic subscriptions.
+ *
+ * Every mutation notifies only the topics it touches (`node:<id>`,
+ * `edge:<id>`, `viewport`, ...), so a renderer can subscribe each component
+ * to exactly the state it draws — dragging one node re-renders one node,
+ * not the whole flow.
+ */
+export class FlowStore {
+    nodes = new Map();
+    edges = new Map();
+    nodeOrder = [];
+    edgeOrder = [];
+    viewport = { x: 0, y: 0, zoom: 1 };
+    selectedNodes = new Set();
+    selectedEdges = new Set();
+    connection = null;
+    /** Set while dragging an existing edge's endpoint to a new handle. */
+    reconnecting = null;
+    guides = [];
+    /** Node ids inside the culling viewport (all depths). */
+    visibleNodes = new Set();
+    /** Root node ids that should be mounted by a renderer. */
+    visibleRoots = new Set();
+    visibleEdges = new Set();
+    /** When false (small graphs / no screen yet), everything renders. */
+    cullingActive = false;
+    /** Bumped whenever node membership/order changes ('nodes' topic). */
+    nodesVersion = 0;
+    /** Bumped whenever edge membership/order changes ('edges' topic). */
+    edgesVersion = 0;
+    /** Bumped on every committed mutation boundary ('commit' topic). */
+    commitVersion = 0;
+    /** Bumped whenever any node geometry changes ('graph' topic) — lets
+     *  obstacle-dependent renderers (orthogonal edges) re-route live. */
+    graphVersion = 0;
+    screen = { width: 0, height: 0 };
+    options;
+    spatial = new SpatialIndex();
+    /** Renderer-measured sizes, kept apart from node objects so measuring
+     *  never re-creates (and re-renders) a node. node.width/height wins. */
+    measured = new Map();
+    nodeEdges = new Map();
+    children = new Map();
+    handles = new Map();
+    /** Per-edge render versions: bumped when the edge object OR the
+     *  geometry it depends on (endpoint nodes, handles) changes. */
+    edgeVer = new Map();
+    listeners = new Map();
+    pending = new Set();
+    batchDepth = 0;
+    undoStack = [];
+    redoStack = [];
+    txn = null;
+    recording = true;
+    drag = null;
+    cullScheduled = false;
+    cullForced = false;
+    /** Hysteresis: skip viewport-only re-culls while the raw view stays
+     *  inside the last culled region (minus a half-margin buffer). */
+    lastCullRect = null;
+    /** Zoom at the last cull. Containment hysteresis only applies while zoom
+     *  is unchanged — zooming IN from an overview shrinks the view inside the
+     *  old region, which must still re-cull or nothing gets culled. */
+    lastCullZoom = 0;
+    vpAnim = null;
+    constructor(options = {}) {
+        this.options = options;
+        if (options.viewport)
+            this.viewport = { ...options.viewport };
+        if (options.nodes || options.edges) {
+            this.recording = false;
+            this.batch(() => {
+                for (const n of options.nodes ?? [])
+                    this._insertNode({ ...n });
+                for (const e of options.edges ?? [])
+                    this._insertEdge({ ...e });
+            });
+            this.recording = true;
+        }
+        this.cull();
+    }
+    // ── events ────────────────────────────────────────────────────────────
+    subscribe(topic, fn) {
+        let set = this.listeners.get(topic);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(topic, set);
+        }
+        set.add(fn);
+        return () => {
+            set.delete(fn);
+            if (set.size === 0)
+                this.listeners.delete(topic);
+        };
+    }
+    /** Monotonic version for an edge's rendered output. */
+    edgeVersion(id) {
+        return this.edgeVer.get(id) ?? 0;
+    }
+    bumpEdge(id) {
+        this.edgeVer.set(id, (this.edgeVer.get(id) ?? 0) + 1);
+        this.emit(`edge:${id}`);
+    }
+    bumpNodes() {
+        this.nodesVersion++;
+        this.emit('nodes');
+        this.emit('graph');
+    }
+    bumpEdges() {
+        this.edgesVersion++;
+        this.emit('edges');
+        this.emit('graph');
+    }
+    emit(topic) {
+        if (topic === 'graph')
+            this.graphVersion++;
+        if (this.batchDepth > 0) {
+            this.pending.add(topic);
+            return;
+        }
+        const set = this.listeners.get(topic);
+        if (set)
+            for (const fn of [...set])
+                fn();
+    }
+    /** Group mutations; duplicate notifications are coalesced. */
+    batch(fn) {
+        this.batchDepth++;
+        try {
+            fn();
+        }
+        finally {
+            this.batchDepth--;
+            if (this.batchDepth === 0) {
+                const topics = [...this.pending];
+                this.pending.clear();
+                for (const t of topics) {
+                    const set = this.listeners.get(t);
+                    if (set)
+                        for (const l of [...set])
+                            l();
+                }
+            }
+        }
+    }
+    commit() {
+        this.commitVersion++;
+        this.emit('commit');
+    }
+    // ── history ───────────────────────────────────────────────────────────
+    record(label, op) {
+        if (!this.recording)
+            return;
+        if (this.txn) {
+            this.txn.ops.push(op);
+        }
+        else {
+            this.undoStack.push({ label, ops: [op] });
+            const limit = this.options.historyLimit ?? 200;
+            if (this.undoStack.length > limit)
+                this.undoStack.shift();
+            this.redoStack = [];
+            this.emit('history');
+        }
+    }
+    /** Group several mutations into a single undo entry. */
+    transact(label, fn) {
+        if (this.txn) {
+            fn();
+            return;
+        }
+        this.txn = { label, ops: [] };
+        try {
+            this.batch(fn);
+        }
+        finally {
+            const entry = this.txn;
+            this.txn = null;
+            if (entry.ops.length > 0 && this.recording) {
+                this.undoStack.push(entry);
+                const limit = this.options.historyLimit ?? 200;
+                if (this.undoStack.length > limit)
+                    this.undoStack.shift();
+                this.redoStack = [];
+                this.emit('history');
+            }
+        }
+    }
+    get canUndo() {
+        return this.undoStack.length > 0;
+    }
+    get canRedo() {
+        return this.redoStack.length > 0;
+    }
+    undo() {
+        const entry = this.undoStack.pop();
+        if (!entry)
+            return;
+        this.recording = false;
+        this.batch(() => {
+            for (let i = entry.ops.length - 1; i >= 0; i--)
+                entry.ops[i].undo();
+        });
+        this.recording = true;
+        this.redoStack.push(entry);
+        this.cull();
+        this.emit('history');
+        this.commit();
+    }
+    redo() {
+        const entry = this.redoStack.pop();
+        if (!entry)
+            return;
+        this.recording = false;
+        this.batch(() => {
+            for (const op of entry.ops)
+                op.redo();
+        });
+        this.recording = true;
+        this.undoStack.push(entry);
+        this.cull();
+        this.emit('history');
+        this.commit();
+    }
+    clearHistory() {
+        this.undoStack = [];
+        this.redoStack = [];
+        this.emit('history');
+    }
+    // ── raw graph ops (no history) ────────────────────────────────────────
+    _insertNode(node) {
+        this.nodes.set(node.id, node);
+        this.nodeOrder.push(node.id);
+        if (node.parentId) {
+            let set = this.children.get(node.parentId);
+            if (!set) {
+                set = new Set();
+                this.children.set(node.parentId, set);
+            }
+            set.add(node.id);
+        }
+        if (node.selected)
+            this.selectedNodes.add(node.id);
+        this.spatial.set(node.id, this.nodeRect(node.id));
+        this.bumpNodes();
+        this.emit(`node:${node.id}`);
+        this.scheduleCull();
+    }
+    _removeNode(id) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return;
+        this.nodes.delete(id);
+        const i = this.nodeOrder.indexOf(id);
+        if (i >= 0)
+            this.nodeOrder.splice(i, 1);
+        if (node.parentId)
+            this.children.get(node.parentId)?.delete(id);
+        this.children.delete(id);
+        this.handles.delete(id);
+        this.measured.delete(id);
+        this.selectedNodes.delete(id);
+        this.spatial.delete(id);
+        this.bumpNodes();
+        this.emit(`node:${id}`);
+        this.scheduleCull();
+    }
+    _replaceNode(node) {
+        const prev = this.nodes.get(node.id);
+        this.nodes.set(node.id, node);
+        if (prev?.parentId !== node.parentId) {
+            if (prev?.parentId)
+                this.children.get(prev.parentId)?.delete(node.id);
+            if (node.parentId) {
+                let set = this.children.get(node.parentId);
+                if (!set) {
+                    set = new Set();
+                    this.children.set(node.parentId, set);
+                }
+                set.add(node.id);
+            }
+            this.bumpNodes();
+        }
+        if (node.selected)
+            this.selectedNodes.add(node.id);
+        else
+            this.selectedNodes.delete(node.id);
+        this.touchNode(node.id);
+    }
+    _insertEdge(edge) {
+        this.edges.set(edge.id, edge);
+        this.edgeOrder.push(edge.id);
+        for (const nid of [edge.source, edge.target]) {
+            let set = this.nodeEdges.get(nid);
+            if (!set) {
+                set = new Set();
+                this.nodeEdges.set(nid, set);
+            }
+            set.add(edge.id);
+        }
+        if (edge.selected)
+            this.selectedEdges.add(edge.id);
+        this.bumpEdges();
+        this.bumpEdge(edge.id);
+        this.scheduleCull();
+    }
+    _removeEdge(id) {
+        const edge = this.edges.get(id);
+        if (!edge)
+            return;
+        this.edges.delete(id);
+        const i = this.edgeOrder.indexOf(id);
+        if (i >= 0)
+            this.edgeOrder.splice(i, 1);
+        this.nodeEdges.get(edge.source)?.delete(id);
+        this.nodeEdges.get(edge.target)?.delete(id);
+        this.selectedEdges.delete(id);
+        this.bumpEdges();
+        this.bumpEdge(id);
+        this.edgeVer.delete(id);
+    }
+    _replaceEdge(edge) {
+        const prev = this.edges.get(edge.id);
+        if (prev && (prev.source !== edge.source || prev.target !== edge.target)) {
+            this.nodeEdges.get(prev.source)?.delete(edge.id);
+            this.nodeEdges.get(prev.target)?.delete(edge.id);
+            for (const nid of [edge.source, edge.target]) {
+                let set = this.nodeEdges.get(nid);
+                if (!set) {
+                    set = new Set();
+                    this.nodeEdges.set(nid, set);
+                }
+                set.add(edge.id);
+            }
+        }
+        this.edges.set(edge.id, edge);
+        if (edge.selected)
+            this.selectedEdges.add(edge.id);
+        else
+            this.selectedEdges.delete(edge.id);
+        this.bumpEdge(edge.id);
+    }
+    /** Re-index a node and notify it plus every edge touching it. */
+    touchNode(id) {
+        this.spatial.set(id, this.nodeRect(id));
+        this.emit(`node:${id}`);
+        this.emit('graph');
+        const edges = this.nodeEdges.get(id);
+        if (edges)
+            for (const eid of edges)
+                this.bumpEdge(eid);
+        const kids = this.children.get(id);
+        if (kids)
+            for (const kid of kids)
+                this.touchNode(kid);
+        this.scheduleCull();
+    }
+    // ── public graph API (history-aware) ──────────────────────────────────
+    getNode(id) {
+        return this.nodes.get(id);
+    }
+    getEdge(id) {
+        return this.edges.get(id);
+    }
+    getNodes() {
+        return this.nodeOrder.map((id) => this.nodes.get(id));
+    }
+    /** All edges connected to a node. */
+    edgesOf(id) {
+        const set = this.nodeEdges.get(id);
+        if (!set)
+            return [];
+        const out = [];
+        for (const eid of set)
+            out.push(this.edges.get(eid));
+        return out;
+    }
+    /** Direct children ids of a node (subflow members). */
+    childrenOf(id) {
+        const set = this.children.get(id);
+        return set ? [...set] : [];
+    }
+    getEdges() {
+        return this.edgeOrder.map((id) => this.edges.get(id));
+    }
+    addNodes(nodes) {
+        if (nodes.length === 0)
+            return;
+        const copies = nodes.map((n) => ({ ...n }));
+        this.batch(() => {
+            for (const n of copies)
+                this._insertNode(n);
+        });
+        this.cull();
+        this.record('add nodes', {
+            undo: () => this.batch(() => {
+                for (const n of copies)
+                    this._removeNode(n.id);
+            }),
+            redo: () => this.batch(() => {
+                for (const n of copies)
+                    this._insertNode(n);
+            }),
+        });
+        this.commit();
+    }
+    addNode(node) {
+        this.addNodes([node]);
+    }
+    /**
+     * Remove nodes plus their connected edges. Children of removed nodes are
+     * re-parented to the flow root (keeping their absolute position) instead
+     * of being orphaned.
+     */
+    removeNodes(ids) {
+        const doomed = ids.filter((id) => this.nodes.has(id) && this.nodes.get(id).deletable !== false);
+        if (doomed.length === 0)
+            return;
+        const doomedSet = new Set(doomed);
+        const removedNodes = doomed.map((id) => this.nodes.get(id));
+        const removedEdges = [];
+        for (const id of doomed) {
+            const set = this.nodeEdges.get(id);
+            if (set) {
+                for (const eid of set) {
+                    const e = this.edges.get(eid);
+                    if (e && !removedEdges.includes(e))
+                        removedEdges.push(e);
+                }
+            }
+        }
+        // Children that survive get re-parented to root at absolute position.
+        const reparented = [];
+        for (const id of doomed) {
+            const kids = this.children.get(id);
+            if (!kids)
+                continue;
+            for (const kid of kids) {
+                if (doomedSet.has(kid))
+                    continue;
+                const child = this.nodes.get(kid);
+                const abs = this.absolutePosition(kid);
+                reparented.push({
+                    before: child,
+                    after: { ...child, parentId: undefined, position: abs },
+                });
+            }
+        }
+        this.batch(() => {
+            for (const e of removedEdges)
+                this._removeEdge(e.id);
+            for (const r of reparented)
+                this._replaceNode(r.after);
+            for (const id of doomed)
+                this._removeNode(id);
+        });
+        this.cull();
+        this.record('remove nodes', {
+            undo: () => this.batch(() => {
+                for (const n of removedNodes)
+                    this._insertNode(n);
+                for (const r of reparented)
+                    this._replaceNode(r.before);
+                for (const e of removedEdges)
+                    this._insertEdge(e);
+            }),
+            redo: () => this.batch(() => {
+                for (const e of removedEdges)
+                    this._removeEdge(e.id);
+                for (const r of reparented)
+                    this._replaceNode(r.after);
+                for (const id of doomed)
+                    this._removeNode(id);
+            }),
+        });
+        this.emit('selection');
+        this.commit();
+    }
+    updateNode(id, patch) {
+        const prev = this.nodes.get(id);
+        if (!prev)
+            return;
+        const next = { ...prev, ...patch, id };
+        this._replaceNode(next);
+        this.record('update node', {
+            undo: () => this._replaceNode(prev),
+            redo: () => this._replaceNode(next),
+        });
+        this.commit();
+    }
+    updateNodeData(id, dataPatch) {
+        const prev = this.nodes.get(id);
+        if (!prev)
+            return;
+        this.updateNode(id, { data: { ...prev.data, ...dataPatch } });
+    }
+    setNodePosition(id, position) {
+        const prev = this.nodes.get(id);
+        if (!prev)
+            return;
+        const snapped = snapToGrid(position, this.options.snapGrid ?? 0);
+        const next = { ...prev, position: snapped };
+        this._replaceNode(next);
+        this.record('move node', {
+            undo: () => this._replaceNode(prev),
+            redo: () => this._replaceNode(next),
+        });
+        this.commit();
+    }
+    /** Measured size update from the renderer — not recorded in history. */
+    setNodeSize(id, width, height) {
+        if (!this.nodes.has(id))
+            return;
+        const prev = this.measured.get(id);
+        if (prev && prev.width === width && prev.height === height)
+            return;
+        this.measured.set(id, { width, height });
+        this.touchNode(id);
+    }
+    addEdges(edges) {
+        const fresh = edges.filter((e) => !this.edges.has(e.id)).map((e) => ({ ...e }));
+        if (fresh.length === 0)
+            return;
+        this.batch(() => {
+            for (const e of fresh)
+                this._insertEdge(e);
+        });
+        this.cull();
+        this.record('add edges', {
+            undo: () => this.batch(() => {
+                for (const e of fresh)
+                    this._removeEdge(e.id);
+            }),
+            redo: () => this.batch(() => {
+                for (const e of fresh)
+                    this._insertEdge(e);
+            }),
+        });
+        this.commit();
+    }
+    addEdge(edge) {
+        this.addEdges([edge]);
+    }
+    removeEdges(ids) {
+        const removed = ids
+            .map((id) => this.edges.get(id))
+            .filter((e) => !!e && e.deletable !== false);
+        if (removed.length === 0)
+            return;
+        this.batch(() => {
+            for (const e of removed)
+                this._removeEdge(e.id);
+        });
+        this.cull();
+        this.record('remove edges', {
+            undo: () => this.batch(() => {
+                for (const e of removed)
+                    this._insertEdge(e);
+            }),
+            redo: () => this.batch(() => {
+                for (const e of removed)
+                    this._removeEdge(e.id);
+            }),
+        });
+        this.emit('selection');
+        this.commit();
+    }
+    updateEdge(id, patch) {
+        const prev = this.edges.get(id);
+        if (!prev)
+            return;
+        const next = { ...prev, ...patch, id };
+        this._replaceEdge(next);
+        this.record('update edge', {
+            undo: () => this._replaceEdge(prev),
+            redo: () => this._replaceEdge(next),
+        });
+        this.commit();
+    }
+    /**
+     * Diff-sync the whole graph (used by controlled mode and loadSnapshot).
+     * Unchanged elements are left untouched, so selection, measured sizes and
+     * fine-grained subscriptions survive a controlled-props round trip.
+     */
+    setGraph(nodes, edges) {
+        this.recording = false;
+        this.batch(() => {
+            const nextNodeIds = new Set(nodes.map((n) => n.id));
+            const nextEdgeIds = new Set(edges.map((e) => e.id));
+            for (const id of [...this.edgeOrder]) {
+                if (!nextEdgeIds.has(id))
+                    this._removeEdge(id);
+            }
+            for (const id of [...this.nodeOrder]) {
+                if (!nextNodeIds.has(id))
+                    this._removeNode(id);
+            }
+            for (const n of nodes) {
+                const prev = this.nodes.get(n.id);
+                if (!prev)
+                    this._insertNode({ ...n });
+                else if (prev !== n)
+                    this._replaceNode({ ...n });
+            }
+            for (const e of edges) {
+                const prev = this.edges.get(e.id);
+                if (!prev)
+                    this._insertEdge({ ...e });
+                else if (prev !== e)
+                    this._replaceEdge({ ...e });
+            }
+            this.emit('selection');
+        });
+        this.cull();
+        this.recording = true;
+    }
+    /**
+     * Apply a remote collaborative change: upsert/remove specific nodes and
+     * edges WITHOUT recording history and WITHOUT emitting 'commit' (so it
+     * never echoes back through the local broadcast diff). Remote edits aren't
+     * part of your local undo stack — you don't undo a teammate's change.
+     */
+    applyRemotePatch(patch) {
+        this.recording = false;
+        this.batch(() => {
+            for (const id of patch.edges?.remove ?? [])
+                this._removeEdge(id);
+            for (const id of patch.nodes?.remove ?? [])
+                this._removeNode(id);
+            for (const n of patch.nodes?.upsert ?? []) {
+                if (this.nodes.has(n.id))
+                    this._replaceNode({ ...n });
+                else
+                    this._insertNode({ ...n });
+            }
+            for (const e of patch.edges?.upsert ?? []) {
+                if (this.edges.has(e.id))
+                    this._replaceEdge({ ...e });
+                else
+                    this._insertEdge({ ...e });
+            }
+        });
+        this.recording = true;
+        this.cull();
+    }
+    // ── geometry helpers ──────────────────────────────────────────────────
+    absolutePosition(id) {
+        let node = this.nodes.get(id);
+        if (!node)
+            return { x: 0, y: 0 };
+        let x = node.position.x;
+        let y = node.position.y;
+        let guard = 0;
+        while (node?.parentId && guard++ < 100) {
+            node = this.nodes.get(node.parentId);
+            if (!node)
+                break;
+            x += node.position.x;
+            y += node.position.y;
+        }
+        return { x, y };
+    }
+    nodeSize(id) {
+        const n = this.nodes.get(id);
+        const m = this.measured.get(id);
+        return {
+            width: n?.width ?? m?.width ?? DEFAULT_NODE_WIDTH,
+            height: n?.height ?? m?.height ?? DEFAULT_NODE_HEIGHT,
+        };
+    }
+    /** Absolute rect of a node in flow coordinates. */
+    nodeRect(id) {
+        const pos = this.absolutePosition(id);
+        const size = this.nodeSize(id);
+        return { x: pos.x, y: pos.y, width: size.width, height: size.height };
+    }
+    /** Union of all node rects (or the given subset). */
+    nodesBounds(ids) {
+        let acc = null;
+        for (const id of ids ?? this.nodeOrder) {
+            if (!this.nodes.has(id) || this.nodes.get(id).hidden)
+                continue;
+            acc = rectUnion(acc, this.nodeRect(id));
+        }
+        return acc ?? { x: 0, y: 0, width: 0, height: 0 };
+    }
+    /**
+     * The nearest visible node to `fromId` in a cardinal direction — for
+     * keyboard/screen-reader spatial navigation. Uses a cone test so
+     * "right" prefers nodes actually to the right, breaking ties by distance.
+     */
+    nearestNodeInDirection(fromId, dir) {
+        const from = this.nodes.get(fromId);
+        if (!from)
+            return null;
+        const a = rectCenter(this.nodeRect(fromId));
+        let best = null;
+        for (const id of this.nodeOrder) {
+            if (id === fromId)
+                continue;
+            const node = this.nodes.get(id);
+            if (node.hidden || node.selectable === false)
+                continue;
+            const b = rectCenter(this.nodeRect(id));
+            const dx = b.x - a.x;
+            const dy = b.y - a.y;
+            let along = 0;
+            let across = 0;
+            if (dir === 'left') {
+                along = -dx;
+                across = Math.abs(dy);
+            }
+            else if (dir === 'right') {
+                along = dx;
+                across = Math.abs(dy);
+            }
+            else if (dir === 'up') {
+                along = -dy;
+                across = Math.abs(dx);
+            }
+            else {
+                along = dy;
+                across = Math.abs(dx);
+            }
+            if (along <= 0)
+                continue; // wrong direction
+            // Prefer aligned + close: penalize perpendicular offset.
+            const score = along + across * 2;
+            if (!best || score < best.score)
+                best = { id, score };
+        }
+        return best?.id ?? null;
+    }
+    /** Nodes whose rects intersect (or are fully inside) the given rect. */
+    nodesInRect(rect, partially = true) {
+        const hits = this.spatial.query(rect);
+        const out = [];
+        for (const id of hits) {
+            const n = this.nodes.get(id);
+            if (!n || n.hidden || n.selectable === false)
+                continue;
+            if (partially) {
+                out.push(id);
+            }
+            else {
+                const r = this.nodeRect(id);
+                if (r.x >= rect.x &&
+                    r.y >= rect.y &&
+                    r.x + r.width <= rect.x + rect.width &&
+                    r.y + r.height <= rect.y + rect.height) {
+                    out.push(id);
+                }
+            }
+        }
+        return out;
+    }
+    // ── handles & edge geometry ───────────────────────────────────────────
+    registerHandle(info) {
+        let map = this.handles.get(info.nodeId);
+        if (!map) {
+            map = new Map();
+            this.handles.set(info.nodeId, map);
+        }
+        const prev = map.get(info.id);
+        if (prev &&
+            prev.x === info.x &&
+            prev.y === info.y &&
+            prev.side === info.side &&
+            prev.kind === info.kind) {
+            return;
+        }
+        map.set(info.id, info);
+        const edges = this.nodeEdges.get(info.nodeId);
+        if (edges)
+            for (const eid of edges)
+                this.bumpEdge(eid);
+        this.emit('connection');
+    }
+    unregisterHandle(nodeId, handleId) {
+        this.handles.get(nodeId)?.delete(handleId);
+    }
+    getHandles(nodeId) {
+        const map = this.handles.get(nodeId);
+        return map ? [...map.values()] : [];
+    }
+    /**
+     * Resolve the handle an edge endpoint attaches to. Falls back to a
+     * synthetic border-midpoint handle when nothing is registered (headless
+     * usage, or nodes without <Handle> children).
+     */
+    resolveHandle(nodeId, kind, handleId) {
+        const map = this.handles.get(nodeId);
+        if (map) {
+            if (handleId != null) {
+                const h = map.get(handleId);
+                if (h)
+                    return h;
+            }
+            for (const h of map.values())
+                if (h.kind === kind)
+                    return h;
+        }
+        const size = this.nodeSize(nodeId);
+        const side = kind === 'source' ? 'right' : 'left';
+        const anchor = sideAnchor({ x: 0, y: 0, ...size }, side);
+        return { id: handleId ?? `__${kind}`, nodeId, kind, side, x: anchor.x, y: anchor.y };
+    }
+    /** Absolute anchor point of a handle. */
+    handleAnchor(h) {
+        const pos = this.absolutePosition(h.nodeId);
+        return { x: pos.x + h.x, y: pos.y + h.y };
+    }
+    /**
+     * Node rectangles an orthogonal edge should route around: nodes near the
+     * edge's bounding box, excluding the two endpoint nodes. Uses the spatial
+     * index so this stays cheap even with thousands of nodes.
+     */
+    edgeObstacles(edge, margin = 120) {
+        const geo = this.edgeGeometry(edge);
+        if (!geo)
+            return [];
+        const x0 = Math.min(geo.source.x, geo.target.x) - margin;
+        const y0 = Math.min(geo.source.y, geo.target.y) - margin;
+        const x1 = Math.max(geo.source.x, geo.target.x) + margin;
+        const y1 = Math.max(geo.source.y, geo.target.y) + margin;
+        const near = this.spatial.query({ x: x0, y: y0, width: x1 - x0, height: y1 - y0 });
+        const out = [];
+        for (const id of near) {
+            if (id === edge.source || id === edge.target)
+                continue;
+            const n = this.nodes.get(id);
+            if (!n || n.hidden || n.type === 'group')
+                continue;
+            out.push(this.nodeRect(id));
+        }
+        return out;
+    }
+    /** Endpoint geometry for rendering an edge. */
+    edgeGeometry(edge) {
+        if (!this.nodes.has(edge.source) || !this.nodes.has(edge.target))
+            return null;
+        const sh = this.resolveHandle(edge.source, 'source', edge.sourceHandle);
+        const th = this.resolveHandle(edge.target, 'target', edge.targetHandle);
+        return {
+            source: this.handleAnchor(sh),
+            sourceSide: sh.side,
+            target: this.handleAnchor(th),
+            targetSide: th.side,
+        };
+    }
+    // ── selection ─────────────────────────────────────────────────────────
+    setSelection(nodeIds, edgeIds = []) {
+        const nextNodes = new Set(nodeIds);
+        const nextEdges = new Set(edgeIds);
+        if (setsEqual(nextNodes, this.selectedNodes) && setsEqual(nextEdges, this.selectedEdges)) {
+            return;
+        }
+        this.batch(() => {
+            for (const id of [...this.selectedNodes]) {
+                if (!nextNodes.has(id)) {
+                    const n = this.nodes.get(id);
+                    if (n)
+                        this._replaceNode({ ...n, selected: false });
+                }
+            }
+            for (const id of nextNodes) {
+                const n = this.nodes.get(id);
+                if (n && !n.selected)
+                    this._replaceNode({ ...n, selected: true });
+            }
+            for (const id of [...this.selectedEdges]) {
+                if (!nextEdges.has(id)) {
+                    const e = this.edges.get(id);
+                    if (e)
+                        this._replaceEdge({ ...e, selected: false });
+                }
+            }
+            for (const id of nextEdges) {
+                const e = this.edges.get(id);
+                if (e && !e.selected)
+                    this._replaceEdge({ ...e, selected: true });
+            }
+            this.emit('selection');
+        });
+    }
+    addToSelection(nodeIds, edgeIds = []) {
+        this.setSelection([...this.selectedNodes, ...nodeIds], [...this.selectedEdges, ...edgeIds]);
+    }
+    toggleSelection(nodeId, edgeId) {
+        const nodes = new Set(this.selectedNodes);
+        const edges = new Set(this.selectedEdges);
+        if (nodeId) {
+            if (nodes.has(nodeId))
+                nodes.delete(nodeId);
+            else
+                nodes.add(nodeId);
+        }
+        if (edgeId) {
+            if (edges.has(edgeId))
+                edges.delete(edgeId);
+            else
+                edges.add(edgeId);
+        }
+        this.setSelection(nodes, edges);
+    }
+    clearSelection() {
+        this.setSelection([], []);
+    }
+    selectAll() {
+        this.setSelection(this.nodeOrder.filter((id) => this.nodes.get(id).selectable !== false), this.edgeOrder);
+    }
+    deleteSelection() {
+        const nodeIds = [...this.selectedNodes];
+        const edgeIds = [...this.selectedEdges];
+        if (nodeIds.length === 0 && edgeIds.length === 0)
+            return;
+        this.transact('delete selection', () => {
+            this.removeEdges(edgeIds);
+            this.removeNodes(nodeIds);
+        });
+        this.commit();
+    }
+    // ── clipboard: copy / paste / duplicate ───────────────────────────────
+    /**
+     * Serialize a set of nodes (default: the selection) plus the edges wholly
+     * between them. The result is JSON-serializable — stash it in app state or
+     * the system clipboard.
+     */
+    copy(nodeIds = [...this.selectedNodes]) {
+        const idSet = new Set(nodeIds);
+        // Include descendants so groups copy with their children.
+        for (const id of nodeIds) {
+            const stack = this.childrenOf(id);
+            while (stack.length) {
+                const kid = stack.pop();
+                idSet.add(kid);
+                stack.push(...this.childrenOf(kid));
+            }
+        }
+        const nodes = [...idSet].filter((id) => this.nodes.has(id)).map((id) => ({ ...this.nodes.get(id) }));
+        const seen = new Set();
+        const edges = [];
+        for (const id of idSet) {
+            for (const e of this.edgesOf(id)) {
+                if (!seen.has(e.id) && idSet.has(e.source) && idSet.has(e.target)) {
+                    seen.add(e.id);
+                    edges.push({ ...e });
+                }
+            }
+        }
+        return { nodes, edges };
+    }
+    /**
+     * Insert a copied payload with fresh ids, offset so pasted nodes don't sit
+     * exactly on the originals, and select the result. Returns the new ids.
+     * One undo entry.
+     */
+    paste(payload, offset = { x: 24, y: 24 }) {
+        const idMap = new Map();
+        for (const n of payload.nodes)
+            idMap.set(n.id, uid('n'));
+        const newNodes = payload.nodes.map((n) => ({
+            ...n,
+            id: idMap.get(n.id),
+            // Only offset roots of the pasted set (children keep relative pos).
+            parentId: n.parentId != null && idMap.has(n.parentId) ? idMap.get(n.parentId) : undefined,
+            position: n.parentId != null && idMap.has(n.parentId)
+                ? { ...n.position }
+                : { x: n.position.x + offset.x, y: n.position.y + offset.y },
+            selected: true,
+        }));
+        const newEdges = payload.edges
+            .filter((e) => idMap.has(e.source) && idMap.has(e.target))
+            .map((e) => ({
+            ...e,
+            id: uid('e'),
+            source: idMap.get(e.source),
+            target: idMap.get(e.target),
+            selected: false,
+        }));
+        this.transact('paste', () => {
+            this.addNodes(newNodes);
+            this.addEdges(newEdges);
+            this.setSelection(newNodes.map((n) => n.id), []);
+        });
+        this.commit();
+        return { nodeIds: newNodes.map((n) => n.id), edgeIds: newEdges.map((e) => e.id) };
+    }
+    /** Copy + paste the selection in one step (⌘D-style). */
+    duplicateSelection(offset = { x: 24, y: 24 }) {
+        return this.paste(this.copy(), offset);
+    }
+    // ── dragging (with grid snap + alignment guides) ──────────────────────
+    startDrag(ids) {
+        const moving = ids.filter((id) => {
+            const n = this.nodes.get(id);
+            return n && n.draggable !== false;
+        });
+        if (moving.length === 0)
+            return;
+        const movingSet = new Set(moving);
+        const start = new Map();
+        for (const id of moving)
+            start.set(id, { ...this.nodes.get(id).position });
+        const guideRects = [];
+        if (this.options.alignmentGuides !== false) {
+            const view = this.cullingActive
+                ? this.visibleNodes
+                : new Set(this.nodeOrder);
+            for (const id of view) {
+                if (movingSet.has(id))
+                    continue;
+                // Skip nodes inside the moving subtree.
+                let p = this.nodes.get(id)?.parentId;
+                let inside = false;
+                while (p) {
+                    if (movingSet.has(p)) {
+                        inside = true;
+                        break;
+                    }
+                    p = this.nodes.get(p)?.parentId;
+                }
+                if (!inside && !this.nodes.get(id)?.hidden)
+                    guideRects.push(this.nodeRect(id));
+            }
+        }
+        this.drag = { ids: moving, start, guideRects, moved: false };
+    }
+    /** Move the dragged nodes by a flow-space delta from the drag origin. */
+    dragBy(delta) {
+        const drag = this.drag;
+        if (!drag)
+            return;
+        let dx = delta.x;
+        let dy = delta.y;
+        const grid = this.options.snapGrid ?? 0;
+        let guides = [];
+        // Alignment guides: snap the union bounds of the moving nodes.
+        if (this.options.alignmentGuides !== false && drag.guideRects.length > 0) {
+            let bounds = null;
+            for (const id of drag.ids) {
+                const startPos = drag.start.get(id);
+                const node = this.nodes.get(id);
+                const abs = this.absolutePosition(id);
+                const size = this.nodeSize(id);
+                // Absolute rect at the tentative position.
+                const rect = {
+                    x: abs.x - node.position.x + startPos.x + dx,
+                    y: abs.y - node.position.y + startPos.y + dy,
+                    width: size.width,
+                    height: size.height,
+                };
+                bounds = rectUnion(bounds, rect);
+            }
+            if (bounds) {
+                const res = computeGuides(bounds, drag.guideRects, this.options.guideThreshold ?? 6);
+                dx += res.dx;
+                dy += res.dy;
+                guides = res.guides;
+            }
+        }
+        this.batch(() => {
+            for (const id of drag.ids) {
+                const node = this.nodes.get(id);
+                const startPos = drag.start.get(id);
+                if (!node || !startPos)
+                    continue;
+                let pos = { x: startPos.x + dx, y: startPos.y + dy };
+                if (grid > 0)
+                    pos = snapToGrid(pos, grid);
+                if (node.extent === 'parent' && node.parentId) {
+                    const parentSize = this.nodeSize(node.parentId);
+                    const size = this.nodeSize(id);
+                    pos = {
+                        x: clamp(pos.x, 0, Math.max(0, parentSize.width - size.width)),
+                        y: clamp(pos.y, 0, Math.max(0, parentSize.height - size.height)),
+                    };
+                }
+                if (pos.x !== node.position.x || pos.y !== node.position.y) {
+                    this.nodes.set(id, { ...node, position: pos });
+                    this.touchNode(id);
+                    drag.moved = true;
+                }
+            }
+            this.setGuides(guides);
+        });
+    }
+    endDrag() {
+        const drag = this.drag;
+        this.drag = null;
+        this.setGuides([]);
+        if (!drag || !drag.moved)
+            return;
+        const before = drag.start;
+        const after = new Map();
+        for (const id of drag.ids) {
+            const n = this.nodes.get(id);
+            if (n)
+                after.set(id, { ...n.position });
+        }
+        this.record('move', {
+            undo: () => this.batch(() => {
+                for (const [id, pos] of before) {
+                    const n = this.nodes.get(id);
+                    if (n) {
+                        this.nodes.set(id, { ...n, position: pos });
+                        this.touchNode(id);
+                    }
+                }
+            }),
+            redo: () => this.batch(() => {
+                for (const [id, pos] of after) {
+                    const n = this.nodes.get(id);
+                    if (n) {
+                        this.nodes.set(id, { ...n, position: pos });
+                        this.touchNode(id);
+                    }
+                }
+            }),
+        });
+        this.commit();
+    }
+    get dragging() {
+        return this.drag !== null;
+    }
+    setGuides(guides) {
+        if (guides.length === 0 && this.guides.length === 0)
+            return;
+        this.guides = guides;
+        this.emit('guides');
+    }
+    // ── connections ───────────────────────────────────────────────────────
+    startConnection(nodeId, handleId, kind = 'source') {
+        const node = this.nodes.get(nodeId);
+        if (!node || node.connectable === false)
+            return;
+        const handle = this.resolveHandle(nodeId, kind, handleId);
+        this.reconnecting = null;
+        this.connection = {
+            fromNode: nodeId,
+            fromHandle: handle,
+            to: this.handleAnchor(handle),
+            toHandle: null,
+            valid: null,
+        };
+        this.emit('connection');
+    }
+    /**
+     * Begin reconnecting one end of an existing edge. The opposite (anchored)
+     * end becomes the connection origin; dropping on a new handle moves this
+     * edge's endpoint. Dropping on nothing deletes the edge (React Flow's
+     * default reconnect-to-void behavior).
+     */
+    startReconnect(edgeId, end) {
+        const edge = this.edges.get(edgeId);
+        if (!edge)
+            return;
+        // The anchored end is the OPPOSITE of the one being dragged.
+        const anchorEnd = end === 'source' ? 'target' : 'source';
+        const anchorNode = anchorEnd === 'source' ? edge.source : edge.target;
+        const anchorHandleId = anchorEnd === 'source' ? edge.sourceHandle : edge.targetHandle;
+        const handle = this.resolveHandle(anchorNode, anchorEnd, anchorHandleId);
+        this.reconnecting = { edgeId, end };
+        this.connection = {
+            fromNode: anchorNode,
+            fromHandle: handle,
+            to: this.handleAnchor(handle),
+            toHandle: null,
+            valid: null,
+        };
+        this.emit('connection');
+    }
+    get isReconnecting() {
+        return this.reconnecting !== null;
+    }
+    moveConnection(to) {
+        if (!this.connection)
+            return;
+        const snap = this.findCompatibleHandle(to, 28);
+        this.connection = {
+            ...this.connection,
+            to: snap ? this.handleAnchor(snap.handle) : to,
+            toHandle: snap?.handle ?? null,
+            valid: snap ? snap.valid : null,
+        };
+        this.emit('connection');
+    }
+    /** Complete the pending connection; returns the new/updated edge. */
+    endConnection() {
+        const conn = this.connection;
+        const reconnect = this.reconnecting;
+        this.connection = null;
+        this.reconnecting = null;
+        this.emit('connection');
+        if (!conn)
+            return null;
+        // Reconnection: move the dragged end, or delete the edge on drop-to-void.
+        if (reconnect) {
+            const edge = this.edges.get(reconnect.edgeId);
+            if (!edge)
+                return null;
+            // Dropped on empty space (no handle): delete the edge (drop-to-void).
+            if (!conn.toHandle) {
+                this.removeEdges([reconnect.edgeId]);
+                return null;
+            }
+            // Dropped on an incompatible handle (duplicate/cycle/type): revert,
+            // leaving the edge untouched.
+            if (!conn.valid)
+                return null;
+            const patch = reconnect.end === 'source'
+                ? { source: conn.toHandle.nodeId, sourceHandle: normalizeHandleId(conn.toHandle.id) }
+                : { target: conn.toHandle.nodeId, targetHandle: normalizeHandleId(conn.toHandle.id) };
+            // Guard against creating an invalid edge (self-loop, dup, cycle).
+            const candidate = {
+                source: reconnect.end === 'source' ? conn.toHandle.nodeId : edge.source,
+                target: reconnect.end === 'target' ? conn.toHandle.nodeId : edge.target,
+                sourceHandle: reconnect.end === 'source' ? conn.toHandle.id : edge.sourceHandle,
+                targetHandle: reconnect.end === 'target' ? conn.toHandle.id : edge.targetHandle,
+            };
+            if (this.validateCandidate(candidate) !== true)
+                return null;
+            this.updateEdge(reconnect.edgeId, patch);
+            return this.edges.get(reconnect.edgeId) ?? null;
+        }
+        if (!conn.toHandle || !conn.valid)
+            return null;
+        const from = conn.fromHandle;
+        const to = conn.toHandle;
+        const candidate = from.kind === 'source'
+            ? {
+                source: from.nodeId,
+                sourceHandle: from.id,
+                target: to.nodeId,
+                targetHandle: to.id,
+            }
+            : {
+                source: to.nodeId,
+                sourceHandle: to.id,
+                target: from.nodeId,
+                targetHandle: from.id,
+            };
+        return this.connect(candidate);
+    }
+    cancelConnection() {
+        if (!this.connection)
+            return;
+        this.connection = null;
+        this.reconnecting = null;
+        this.emit('connection');
+    }
+    /** Validate and create an edge (respecting defaultEdgeOptions). */
+    connect(candidate, props = {}) {
+        const verdict = this.validateCandidate(candidate);
+        if (verdict !== true)
+            return null;
+        const edge = {
+            id: uid('e'),
+            type: 'bezier',
+            ...this.options.defaultEdgeOptions,
+            ...props,
+            source: candidate.source,
+            target: candidate.target,
+            sourceHandle: normalizeHandleId(candidate.sourceHandle),
+            targetHandle: normalizeHandleId(candidate.targetHandle),
+        };
+        this.addEdges([edge]);
+        return this.edges.get(edge.id) ?? null;
+    }
+    /** Returns true, or a string describing why the connection is invalid. */
+    validateCandidate(c) {
+        if (!this.nodes.has(c.source) || !this.nodes.has(c.target))
+            return 'missing node';
+        if (c.source === c.target)
+            return 'self loop';
+        if (!this.options.allowDuplicateEdges) {
+            // Synthetic default-handle ids ("__source"/"__target") are equivalent
+            // to an unset handle, so normalize before comparing.
+            const norm = (h) => h == null || h === '__source' || h === '__target' ? null : h;
+            const set = this.nodeEdges.get(c.source);
+            if (set) {
+                for (const eid of set) {
+                    const e = this.edges.get(eid);
+                    if (e.source === c.source &&
+                        e.target === c.target &&
+                        norm(e.sourceHandle) === norm(c.sourceHandle) &&
+                        norm(e.targetHandle) === norm(c.targetHandle)) {
+                        return 'duplicate edge';
+                    }
+                }
+            }
+        }
+        const sh = this.resolveHandle(c.source, 'source', c.sourceHandle);
+        const th = this.resolveHandle(c.target, 'target', c.targetHandle);
+        if (sh.dataType && th.dataType && sh.dataType !== th.dataType)
+            return 'incompatible types';
+        for (const h of [sh, th]) {
+            if (h.maxConnections != null && this.handleConnectionCount(h) >= h.maxConnections) {
+                return 'handle full';
+            }
+        }
+        if (this.options.preventCycles && this.wouldCreateCycle(c.source, c.target)) {
+            return 'cycle';
+        }
+        const custom = this.options.validateConnection;
+        if (custom) {
+            const res = custom(c, { sourceHandle: sh, targetHandle: th });
+            if (res !== true)
+                return typeof res === 'string' ? res : 'rejected';
+        }
+        return true;
+    }
+    handleConnectionCount(h) {
+        const set = this.nodeEdges.get(h.nodeId);
+        if (!set)
+            return 0;
+        let count = 0;
+        for (const eid of set) {
+            const e = this.edges.get(eid);
+            if (h.kind === 'source' && e.source === h.nodeId && (e.sourceHandle ?? `__source`) === h.id)
+                count++;
+            if (h.kind === 'target' && e.target === h.nodeId && (e.targetHandle ?? `__target`) === h.id)
+                count++;
+        }
+        return count;
+    }
+    /** Would adding source→target create a directed cycle? */
+    wouldCreateCycle(source, target) {
+        if (source === target)
+            return true;
+        const stack = [target];
+        const seen = new Set();
+        while (stack.length > 0) {
+            const id = stack.pop();
+            if (id === source)
+                return true;
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            const set = this.nodeEdges.get(id);
+            if (set) {
+                for (const eid of set) {
+                    const e = this.edges.get(eid);
+                    if (e.source === id)
+                        stack.push(e.target);
+                }
+            }
+        }
+        return false;
+    }
+    /** Nearest compatible opposite-kind handle within `radius` flow px. */
+    findCompatibleHandle(p, radius) {
+        const conn = this.connection;
+        if (!conn)
+            return null;
+        const wantKind = conn.fromHandle.kind === 'source' ? 'target' : 'source';
+        const searchRect = {
+            x: p.x - radius,
+            y: p.y - radius,
+            width: radius * 2,
+            height: radius * 2,
+        };
+        // Handles sit on node borders, so search nodes near the pointer
+        // (expanded to catch handles that poke outside the node rect).
+        const near = this.spatial.query(expandRect(searchRect, 16));
+        let best = null;
+        for (const nodeId of near) {
+            if (nodeId === conn.fromNode)
+                continue;
+            const node = this.nodes.get(nodeId);
+            if (!node || node.hidden || node.connectable === false)
+                continue;
+            const registered = this.handles.get(nodeId);
+            const candidates = registered
+                ? [...registered.values()].filter((h) => h.kind === wantKind)
+                : [this.resolveHandle(nodeId, wantKind)];
+            for (const h of candidates) {
+                const anchor = this.handleAnchor(h);
+                const d = Math.hypot(anchor.x - p.x, anchor.y - p.y);
+                if (d <= radius && (!best || d < best.d))
+                    best = { handle: h, d };
+            }
+        }
+        if (!best)
+            return null;
+        const from = conn.fromHandle;
+        const candidate = from.kind === 'source'
+            ? {
+                source: from.nodeId,
+                sourceHandle: from.id,
+                target: best.handle.nodeId,
+                targetHandle: best.handle.id,
+            }
+            : {
+                source: best.handle.nodeId,
+                sourceHandle: best.handle.id,
+                target: from.nodeId,
+                targetHandle: from.id,
+            };
+        return { handle: best.handle, valid: this.validateCandidate(candidate) === true };
+    }
+    // ── viewport ──────────────────────────────────────────────────────────
+    setScreenSize(width, height) {
+        if (this.screen.width === width && this.screen.height === height)
+            return;
+        this.screen = { width, height };
+        this.scheduleCull();
+    }
+    setViewport(v) {
+        const minZoom = this.options.minZoom ?? 0.1;
+        const maxZoom = this.options.maxZoom ?? 2.5;
+        const next = { x: v.x, y: v.y, zoom: clamp(v.zoom, minZoom, maxZoom) };
+        if (next.x === this.viewport.x &&
+            next.y === this.viewport.y &&
+            next.zoom === this.viewport.zoom) {
+            return;
+        }
+        this.viewport = next;
+        this.emit('viewport');
+        this.scheduleCull(false);
+    }
+    panBy(dx, dy) {
+        this.setViewport({ x: this.viewport.x + dx, y: this.viewport.y + dy, zoom: this.viewport.zoom });
+    }
+    /** Zoom by factor around a screen-space pivot (defaults to center). */
+    zoomBy(factor, pivot) {
+        const p = pivot ?? { x: this.screen.width / 2, y: this.screen.height / 2 };
+        this.setViewport(zoomAt(this.viewport, factor, p, this.options.minZoom ?? 0.1, this.options.maxZoom ?? 2.5));
+    }
+    zoomTo(zoom, duration = 0) {
+        const c = { x: this.screen.width / 2, y: this.screen.height / 2 };
+        const target = zoomAt(this.viewport, zoom / this.viewport.zoom, c, this.options.minZoom ?? 0.1, this.options.maxZoom ?? 2.5);
+        this.animateViewport(target, duration);
+    }
+    fitView(opts = {}) {
+        if (this.screen.width === 0 || this.screen.height === 0)
+            return;
+        const bounds = this.nodesBounds(opts.nodes);
+        if (bounds.width === 0 && bounds.height === 0)
+            return;
+        const target = fitRect(bounds, this.screen.width, this.screen.height, opts.padding ?? 0.1, opts.minZoom ?? this.options.minZoom ?? 0.05, opts.maxZoom ?? this.options.maxZoom ?? 2.5);
+        this.animateViewport(target, opts.duration ?? 0);
+    }
+    /** Center the view on a node (nice for search/jump UX). */
+    centerNode(id, duration = 300) {
+        const r = this.spatial.getBounds(id);
+        if (!r || this.screen.width === 0)
+            return;
+        const zoom = this.viewport.zoom;
+        this.animateViewport({
+            x: this.screen.width / 2 - (r.x + r.width / 2) * zoom,
+            y: this.screen.height / 2 - (r.y + r.height / 2) * zoom,
+            zoom,
+        }, duration);
+    }
+    animateViewport(target, duration = 300) {
+        if (this.vpAnim != null && typeof cancelAnimationFrame !== 'undefined') {
+            cancelAnimationFrame(this.vpAnim);
+            this.vpAnim = null;
+        }
+        if (duration <= 0 || typeof requestAnimationFrame === 'undefined') {
+            this.setViewport(target);
+            return;
+        }
+        const from = { ...this.viewport };
+        const start = performance.now();
+        const ease = (t) => (t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2);
+        const tick = (now) => {
+            const t = clamp((now - start) / duration, 0, 1);
+            const k = ease(t);
+            this.setViewport({
+                x: from.x + (target.x - from.x) * k,
+                y: from.y + (target.y - from.y) * k,
+                zoom: from.zoom + (target.zoom - from.zoom) * k,
+            });
+            this.vpAnim = t < 1 ? requestAnimationFrame(tick) : null;
+        };
+        this.vpAnim = requestAnimationFrame(tick);
+    }
+    // ── culling ───────────────────────────────────────────────────────────
+    scheduleCull(force = true) {
+        this.cullForced = this.cullForced || force;
+        if (this.cullScheduled)
+            return;
+        this.cullScheduled = true;
+        rafSchedule(() => {
+            this.cullScheduled = false;
+            const forced = this.cullForced;
+            this.cullForced = false;
+            this.cull(forced);
+        });
+    }
+    /** Recompute the visible node/edge sets; emits 'visible' on change. */
+    cull(force = true) {
+        const total = this.nodes.size;
+        const threshold = 200;
+        const active = this.screen.width > 0 && total > threshold;
+        let nextNodes;
+        if (active) {
+            const margin = this.options.cullingMargin ?? 300;
+            const raw = visibleRect(this.viewport, this.screen.width, this.screen.height);
+            // Skip only on a pure pan (same zoom) still inside the overscan buffer.
+            if (!force &&
+                this.lastCullRect &&
+                this.viewport.zoom === this.lastCullZoom &&
+                rectContainsRect(this.lastCullRect, raw)) {
+                return; // still covered by the last cull's overscan
+            }
+            const view = expandRect(raw, margin);
+            this.lastCullRect = expandRect(raw, margin / 2);
+            this.lastCullZoom = this.viewport.zoom;
+            nextNodes = this.spatial.query(view);
+            // Selected + dragged nodes always render.
+            for (const id of this.selectedNodes)
+                nextNodes.add(id);
+            if (this.drag)
+                for (const id of this.drag.ids)
+                    nextNodes.add(id);
+        }
+        else {
+            nextNodes = new Set(this.nodeOrder);
+        }
+        const nextRoots = new Set();
+        for (const id of nextNodes) {
+            let node = this.nodes.get(id);
+            let cur = id;
+            let guard = 0;
+            while (node?.parentId && guard++ < 100) {
+                cur = node.parentId;
+                node = this.nodes.get(cur);
+            }
+            if (node)
+                nextRoots.add(cur);
+        }
+        // Children of visible roots render with their parent.
+        const stack = [...nextRoots];
+        while (stack.length > 0) {
+            const id = stack.pop();
+            const kids = this.children.get(id);
+            if (kids) {
+                for (const kid of kids) {
+                    if (!nextNodes.has(kid))
+                        nextNodes.add(kid);
+                    stack.push(kid);
+                }
+            }
+        }
+        const nextEdges = new Set();
+        if (active) {
+            for (const eid of this.edgeOrder) {
+                const e = this.edges.get(eid);
+                if (e.hidden)
+                    continue;
+                if (nextNodes.has(e.source) || nextNodes.has(e.target))
+                    nextEdges.add(eid);
+            }
+        }
+        else {
+            for (const eid of this.edgeOrder)
+                nextEdges.add(eid);
+        }
+        // Only swap the exposed sets when membership changed, so renderers can
+        // use them as useSyncExternalStore snapshots (stable identity).
+        const changed = this.cullingActive !== active ||
+            !setsEqual(nextRoots, this.visibleRoots) ||
+            !setsEqual(nextEdges, this.visibleEdges);
+        this.visibleNodes = nextNodes;
+        this.cullingActive = active;
+        if (changed) {
+            this.visibleRoots = nextRoots;
+            this.visibleEdges = nextEdges;
+            this.emit('visible');
+        }
+    }
+    // ── serialization ─────────────────────────────────────────────────────
+    toSnapshot() {
+        return {
+            version: 1,
+            nodes: this.getNodes().map((n) => ({ ...n })),
+            edges: this.getEdges().map((e) => ({ ...e })),
+            viewport: { ...this.viewport },
+        };
+    }
+    loadSnapshot(snap) {
+        this.batch(() => {
+            this.setGraph(snap.nodes, snap.edges);
+            if (snap.viewport)
+                this.setViewport(snap.viewport);
+        });
+        this.clearHistory();
+        this.commit();
+    }
+}
+//# sourceMappingURL=store.js.map