@pixerate/editor-svelte 0.15.3 → 0.16.1

package/dist/canvas/createCanvasDocking.svelte.d.ts

@@ -0,0 +1,56 @@
+import type { XYPosition } from '@xyflow/svelte';
+import type { CanvasNode, CanvasDockingCallbacks, DockStrategy } from './types.js';
+export type { DockStrategy };
+export interface CreateCanvasDockingOptions<TNode extends CanvasNode = CanvasNode> extends CanvasDockingCallbacks<TNode> {
+    isDockTarget?: (target: TNode) => boolean;
+    restorePositionOnDock?: boolean;
+    onSave?: () => void;
+    /**
+     * Disambiguation strategy when multiple candidate dock targets intersect the dragged node.
+     * - 'center-point': (Default) Resolves the target enclosing or closest to the dragged node's center.
+     * - 'max-overlap': Resolves the target with the greatest overlapping area.
+     * - 'pointer': Resolves the target enclosing or closest to the mouse/touch cursor.
+     * - 'first': Resolves the first intersecting target (legacy behavior).
+     */
+    dockStrategy?: DockStrategy;
+    /**
+     * Custom primary dock target resolution callback. If provided and returns a node, takes precedence.
+     */
+    resolvePrimaryDockTarget?: (targets: TNode[], draggedNode: TNode, event?: MouseEvent | TouchEvent) => TNode | null;
+    /**
+     * When true (default), ensures only a single primary dock target is considered hovered at any time.
+     * Transitioning across adjacent dock targets automatically fires onDockLeave on the previous target
+     * and onDockHover on the new target. Set to false to allow concurrent multi-target hover.
+     */
+    exclusiveHover?: boolean;
+}
+/**
+ * Headless Svelte 5 rune managing canvas node dragging, docking intersection, and connection tracking.
+ */
+export declare function createCanvasDocking<TNode extends CanvasNode = CanvasNode>(options?: CreateCanvasDockingOptions<TNode>): {
+    readonly draggedNode: TNode | null;
+    readonly draggedInitialPosition: XYPosition | null;
+    readonly connectingHandle: string;
+    readonly connectingNode: TNode | null;
+    readonly isDragging: boolean;
+    handleNodeDragStart: (params: {
+        targetNode: TNode | null;
+        event?: MouseEvent | TouchEvent;
+    }) => void;
+    handleNodeDrag: (params: {
+        targetNode: TNode | null;
+        event?: MouseEvent | TouchEvent;
+    }, getIntersectingNodes: (node: TNode) => TNode[]) => void;
+    handleNodeDragStop: (params: {
+        targetNode: TNode | null;
+        event?: MouseEvent | TouchEvent;
+    }, getIntersectingNodes: (node: TNode) => TNode[], updateNodePosition?: (nodeId: string, position: XYPosition) => void) => void;
+    handleConnectStart: (params: {
+        nodeId: string | null;
+        handleId?: string | null;
+        handleType: "source" | "target" | null;
+    }, getNode: (id: string) => TNode | undefined) => void;
+    handleConnectEnd: () => void;
+    reset: () => void;
+};
+//# sourceMappingURL=createCanvasDocking.svelte.d.ts.map

package/dist/canvas/createCanvasDocking.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createCanvasDocking.svelte.d.ts","sourceRoot":"","sources":["../../src/canvas/createCanvasDocking.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEnF,YAAY,EAAE,YAAY,EAAE,CAAC;AAE7B,MAAM,WAAW,0BAA0B,CAAC,KAAK,SAAS,UAAU,GAAG,UAAU,CAChF,SAAQ,sBAAsB,CAAC,KAAK,CAAC;IACrC,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,KAAK,KAAK,OAAO,CAAC;IAC1C,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B;;OAEG;IACH,wBAAwB,CAAC,EAAE,CAC1B,OAAO,EAAE,KAAK,EAAE,EAChB,WAAW,EAAE,KAAK,EAClB,KAAK,CAAC,EAAE,UAAU,GAAG,UAAU,KAC3B,KAAK,GAAG,IAAI,CAAC;IAClB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB;AAkJD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,SAAS,UAAU,GAAG,UAAU,EACxE,OAAO,GAAE,0BAA0B,CAAC,KAAK,CAAM;;;;;;kCAYV;QACpC,UAAU,EAAE,KAAK,GAAG,IAAI,CAAC;QACzB,KAAK,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;KAChC,KAAG,IAAI;6BAOC;QACP,UAAU,EAAE,KAAK,GAAG,IAAI,CAAC;QACzB,KAAK,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;KAChC,wBACqB,CAAC,IAAI,EAAE,KAAK,KAAK,KAAK,EAAE,KAC5C,IAAI;iCAyDE;QACP,UAAU,EAAE,KAAK,GAAG,IAAI,CAAC;QACzB,KAAK,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;KAChC,wBACqB,CAAC,IAAI,EAAE,KAAK,KAAK,KAAK,EAAE,uBACzB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,KAAK,IAAI,KACjE,IAAI;iCAmCE;QACP,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,UAAU,EAAE,QAAQ,GAAG,QAAQ,GAAG,IAAI,CAAC;KACvC,WACQ,CAAC,EAAE,EAAE,MAAM,KAAK,KAAK,GAAG,SAAS,KACxC,IAAI;4BAKsB,IAAI;iBAKf,IAAI;EA+BtB"}

package/dist/canvas/createCanvasDocking.svelte.js

@@ -0,0 +1,227 @@
+function getNodeRect(node) {
+    const x = node.position?.x ?? 0;
+    const y = node.position?.y ?? 0;
+    const width = node.measured?.width ??
+        node.width ??
+        node.initialWidth ??
+        0;
+    const height = node.measured?.height ??
+        node.height ??
+        node.initialHeight ??
+        0;
+    return { x, y, width, height };
+}
+function getNodeCenter(node) {
+    const rect = getNodeRect(node);
+    return {
+        x: rect.x + rect.width / 2,
+        y: rect.y + rect.height / 2
+    };
+}
+function getDistanceSq(p1, p2) {
+    const dx = p1.x - p2.x;
+    const dy = p1.y - p2.y;
+    return dx * dx + dy * dy;
+}
+function getOverlapArea(rectA, rectB) {
+    const xOverlap = Math.max(0, Math.min(rectA.x + rectA.width, rectB.x + rectB.width) - Math.max(rectA.x, rectB.x));
+    const yOverlap = Math.max(0, Math.min(rectA.y + rectA.height, rectB.y + rectB.height) - Math.max(rectA.y, rectB.y));
+    return xOverlap * yOverlap;
+}
+function resolvePrimaryTarget(targets, draggedNode, strategy, customResolver, event) {
+    if (targets.length === 0)
+        return null;
+    if (targets.length === 1)
+        return targets[0];
+    if (customResolver) {
+        const resolved = customResolver(targets, draggedNode, event);
+        if (resolved !== undefined)
+            return resolved;
+    }
+    if (strategy === 'first') {
+        return targets[0];
+    }
+    if (strategy === 'pointer' && event) {
+        const clientX = 'clientX' in event ? event.clientX : event.touches?.[0]?.clientX;
+        const clientY = 'clientY' in event ? event.clientY : event.touches?.[0]?.clientY;
+        if (typeof clientX === 'number' && typeof clientY === 'number') {
+            const pointerInside = targets.filter((target) => {
+                const r = getNodeRect(target);
+                return (r.width > 0 &&
+                    r.height > 0 &&
+                    clientX >= r.x &&
+                    clientX <= r.x + r.width &&
+                    clientY >= r.y &&
+                    clientY <= r.y + r.height);
+            });
+            if (pointerInside.length === 1)
+                return pointerInside[0];
+            if (pointerInside.length > 1) {
+                return pointerInside.reduce((best, cur) => {
+                    const bestDist = getDistanceSq(getNodeCenter(best), { x: clientX, y: clientY });
+                    const curDist = getDistanceSq(getNodeCenter(cur), { x: clientX, y: clientY });
+                    return curDist < bestDist ? cur : best;
+                });
+            }
+        }
+    }
+    if (strategy === 'max-overlap') {
+        const draggedRect = getNodeRect(draggedNode);
+        let maxArea = -1;
+        let bestTarget = targets[0];
+        for (const target of targets) {
+            const targetRect = getNodeRect(target);
+            const area = getOverlapArea(draggedRect, targetRect);
+            if (area > maxArea) {
+                maxArea = area;
+                bestTarget = target;
+            }
+        }
+        return bestTarget;
+    }
+    // Strategy: 'center-point' (default)
+    const draggedCenter = getNodeCenter(draggedNode);
+    const containing = targets.filter((target) => {
+        const r = getNodeRect(target);
+        if (r.width > 0 && r.height > 0) {
+            return (draggedCenter.x >= r.x &&
+                draggedCenter.x <= r.x + r.width &&
+                draggedCenter.y >= r.y &&
+                draggedCenter.y <= r.y + r.height);
+        }
+        return false;
+    });
+    if (containing.length === 1)
+        return containing[0];
+    if (containing.length > 1) {
+        return containing.reduce((best, cur) => {
+            const bestDist = getDistanceSq(getNodeCenter(best), draggedCenter);
+            const curDist = getDistanceSq(getNodeCenter(cur), draggedCenter);
+            return curDist < bestDist ? cur : best;
+        });
+    }
+    return targets.reduce((best, cur) => {
+        const bestDist = getDistanceSq(getNodeCenter(best), draggedCenter);
+        const curDist = getDistanceSq(getNodeCenter(cur), draggedCenter);
+        return curDist < bestDist ? cur : best;
+    });
+}
+/**
+ * Headless Svelte 5 rune managing canvas node dragging, docking intersection, and connection tracking.
+ */
+export function createCanvasDocking(options = {}) {
+    let draggedNode = $state.raw(null);
+    let draggedInitialPosition = $state.raw(null);
+    let connectingHandle = $state.raw('');
+    let connectingNode = $state.raw(null);
+    let currentHoverTargets = $state.raw(new Set());
+    const isDockTarget = options.isDockTarget ?? ((target) => target.type === 'boardNode');
+    const dockStrategy = options.dockStrategy ?? 'center-point';
+    const exclusiveHover = options.exclusiveHover ?? true;
+    function handleNodeDragStart(params) {
+        draggedNode = params.targetNode;
+        draggedInitialPosition = params.targetNode?.position ? { ...params.targetNode.position } : null;
+        currentHoverTargets = new Set();
+    }
+    function handleNodeDrag(params, getIntersectingNodes) {
+        draggedNode = params.targetNode;
+        if (!draggedNode)
+            return;
+        const intersecting = getIntersectingNodes(draggedNode);
+        const currentDockTargets = intersecting.filter(isDockTarget);
+        if (exclusiveHover) {
+            const primaryTarget = currentDockTargets.length > 0
+                ? resolvePrimaryTarget(currentDockTargets, draggedNode, dockStrategy, options.resolvePrimaryDockTarget, params.event)
+                : null;
+            const primaryTargetId = primaryTarget ? primaryTarget.id : null;
+            // Fire onDockLeave for previous targets no longer considered primary
+            currentHoverTargets.forEach((targetId) => {
+                if (targetId !== primaryTargetId) {
+                    const leftNode = intersecting.find((n) => n.id === targetId) ?? { id: targetId };
+                    options.onDockLeave?.(leftNode, draggedNode);
+                }
+            });
+            // Fire onDockHover if entering a new primary target
+            if (primaryTarget && !currentHoverTargets.has(primaryTarget.id)) {
+                options.onDockHover?.(primaryTarget, draggedNode);
+            }
+            currentHoverTargets = primaryTargetId ? new Set([primaryTargetId]) : new Set();
+        }
+        else {
+            const newHoverSet = new Set(currentDockTargets.map((t) => t.id));
+            // Check for left targets
+            currentHoverTargets.forEach((targetId) => {
+                if (!newHoverSet.has(targetId)) {
+                    const leftNode = intersecting.find((n) => n.id === targetId) ?? { id: targetId };
+                    options.onDockLeave?.(leftNode, draggedNode);
+                }
+            });
+            // Check for newly entered targets
+            currentDockTargets.forEach((target) => {
+                if (!currentHoverTargets.has(target.id)) {
+                    options.onDockHover?.(target, draggedNode);
+                }
+            });
+            currentHoverTargets = newHoverSet;
+        }
+    }
+    function handleNodeDragStop(params, getIntersectingNodes, updateNodePosition) {
+        draggedNode = params.targetNode;
+        if (draggedNode) {
+            const intersecting = getIntersectingNodes(draggedNode);
+            const dockTargets = intersecting.filter(isDockTarget);
+            const dockTarget = dockTargets.length > 0
+                ? resolvePrimaryTarget(dockTargets, draggedNode, dockStrategy, options.resolvePrimaryDockTarget, params.event)
+                : null;
+            if (dockTarget) {
+                options.onDockDrop?.(dockTarget, draggedNode);
+                if (options.restorePositionOnDock !== false && draggedInitialPosition && updateNodePosition) {
+                    updateNodePosition(draggedNode.id, draggedInitialPosition);
+                }
+            }
+        }
+        // Reset state
+        draggedNode = null;
+        draggedInitialPosition = null;
+        currentHoverTargets = new Set();
+        options.onSave?.();
+    }
+    function handleConnectStart(params, getNode) {
+        connectingHandle = params.handleType ?? '';
+        connectingNode = params.nodeId ? (getNode(params.nodeId) ?? null) : null;
+    }
+    function handleConnectEnd() {
+        connectingHandle = '';
+        connectingNode = null;
+    }
+    function reset() {
+        draggedNode = null;
+        draggedInitialPosition = null;
+        connectingHandle = '';
+        connectingNode = null;
+        currentHoverTargets = new Set();
+    }
+    return {
+        get draggedNode() {
+            return draggedNode;
+        },
+        get draggedInitialPosition() {
+            return draggedInitialPosition;
+        },
+        get connectingHandle() {
+            return connectingHandle;
+        },
+        get connectingNode() {
+            return connectingNode;
+        },
+        get isDragging() {
+            return draggedNode !== null;
+        },
+        handleNodeDragStart,
+        handleNodeDrag,
+        handleNodeDragStop,
+        handleConnectStart,
+        handleConnectEnd,
+        reset
+    };
+}

package/dist/canvas/createCanvasExplosion.svelte.d.ts

@@ -0,0 +1,31 @@
+import type { Rect, XYPosition } from '@xyflow/svelte';
+import type { CanvasEdge, CanvasNode, CollapseNodeOptions, ExplodeNodeOptions, ExplosionSnapshot } from './types.js';
+export interface CanvasGraphTarget<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge> {
+    nodes: TNode[];
+    edges: TEdge[];
+    setNodes: (nodes: TNode[], triggerCallback?: boolean) => void;
+    setEdges: (edges: TEdge[], triggerCallback?: boolean) => void;
+    addNodeOrNodes: (nodes: TNode | TNode[], animateFrom?: XYPosition, save?: boolean) => void;
+    addEdges: (edges: TEdge[], save?: boolean) => void;
+    removeNodes: (nodes: TNode[], save?: boolean) => void;
+    removeEdges: (edges: TEdge[], save?: boolean) => void;
+    createEdge?: (sourceId: string, targetId: string, options?: any) => TEdge;
+    onSave?: () => void;
+}
+export interface CreateCanvasExplosionOptions<TNode extends CanvasNode = CanvasNode> {
+    getNodesBounds?: (nodes: TNode[]) => Rect;
+    onSave?: () => void;
+}
+/**
+ * Headless Svelte 5 rune managing canvas node explosion, spatial layout displacement,
+ * coordinated multi-node animation paths, and reversible collapsing.
+ */
+export declare function createCanvasExplosion<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge>(graph: CanvasGraphTarget<TNode, TEdge>, options?: CreateCanvasExplosionOptions<TNode>): {
+    readonly explodedNodeIds: string[];
+    isExploded: (nodeId: string) => boolean;
+    explodeNode: (parentId: string, explodeOptions: ExplodeNodeOptions<TNode, TEdge>) => boolean;
+    collapseNode: (parentId: string, collapseOptions?: CollapseNodeOptions) => boolean;
+    toggleExplode: (parentId: string, explodeOptions: ExplodeNodeOptions<TNode, TEdge>, collapseOptions?: CollapseNodeOptions) => boolean;
+    getSnapshot: (parentId: string) => ExplosionSnapshot<TNode, TEdge> | undefined;
+};
+//# sourceMappingURL=createCanvasExplosion.svelte.d.ts.map

package/dist/canvas/createCanvasExplosion.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createCanvasExplosion.svelte.d.ts","sourceRoot":"","sources":["../../src/canvas/createCanvasExplosion.svelte.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EACX,UAAU,EACV,UAAU,EACV,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EAEjB,MAAM,YAAY,CAAC;AAYpB,MAAM,WAAW,iBAAiB,CACjC,KAAK,SAAS,UAAU,GAAG,UAAU,EACrC,KAAK,SAAS,UAAU,GAAG,UAAU;IAErC,KAAK,EAAE,KAAK,EAAE,CAAC;IACf,KAAK,EAAE,KAAK,EAAE,CAAC;IACf,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,eAAe,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC9D,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,eAAe,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC9D,cAAc,EAAE,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,EAAE,EAAE,WAAW,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC3F,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACnD,WAAW,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACtD,WAAW,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACtD,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,KAAK,KAAK,CAAC;IAC1E,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,4BAA4B,CAAC,KAAK,SAAS,UAAU,GAAG,UAAU;IAClF,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,IAAI,CAAC;IAC1C,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACpC,KAAK,SAAS,UAAU,GAAG,UAAU,EACrC,KAAK,SAAS,UAAU,GAAG,UAAU,EAErC,KAAK,EAAE,iBAAiB,CAAC,KAAK,EAAE,KAAK,CAAC,EACtC,OAAO,GAAE,4BAA4B,CAAC,KAAK,CAAM;;yBAMrB,MAAM,KAAG,OAAO;4BAKjC,MAAM,kBACA,kBAAkB,CAAC,KAAK,EAAE,KAAK,CAAC,KAC9C,OAAO;6BA2OC,MAAM,oBACC,mBAAmB,KAClC,OAAO;8BAmIC,MAAM,kBACA,kBAAkB,CAAC,KAAK,EAAE,KAAK,CAAC,oBAC9B,mBAAmB,KACnC,OAAO;4BAOqB,MAAM;EAcrC"}

package/dist/canvas/createCanvasExplosion.svelte.js

@@ -0,0 +1,346 @@
+import { cubicOut } from 'svelte/easing';
+import { calculateDirectionalDisplacement, calculateReflowDisplacement } from './createCanvasDisplacement.js';
+import { createFanOutTrajectory, linearPositionTrajectory, runMultiNodeTransition } from './createCanvasTrajectory.js';
+/**
+ * Headless Svelte 5 rune managing canvas node explosion, spatial layout displacement,
+ * coordinated multi-node animation paths, and reversible collapsing.
+ */
+export function createCanvasExplosion(graph, options = {}) {
+    let explodedNodeIds = $state([]);
+    const snapshots = new Map();
+    let activeAnimationCancel = null;
+    function isExploded(nodeId) {
+        return explodedNodeIds.includes(nodeId);
+    }
+    function explodeNode(parentId, explodeOptions) {
+        if (isExploded(parentId)) {
+            return false;
+        }
+        const parentNode = graph.nodes.find((n) => n.id === parentId);
+        if (!parentNode) {
+            return false;
+        }
+        const { childNodes, childEdges = [], connectParentToChildren = 'all', displacementStrategy = 'directional', directionalOptions = {}, reflowOptions = {}, trajectory, duration = 500, staggerDelay = 20, easing = cubicOut, onComplete } = explodeOptions;
+        if (childNodes.length === 0) {
+            return false;
+        }
+        // 1. Calculate displacement for existing nodes
+        let displacementMap;
+        if (displacementStrategy === 'dagre') {
+            displacementMap = calculateReflowDisplacement({
+                existingNodes: graph.nodes,
+                existingEdges: graph.edges,
+                originNode: parentNode,
+                childNodes,
+                childEdges,
+                getNodesBounds: options.getNodesBounds,
+                options: {
+                    ...reflowOptions,
+                    direction: reflowOptions.direction ?? 'LR'
+                }
+            });
+        }
+        else if (displacementStrategy === 'none') {
+            displacementMap = new Map();
+        }
+        else {
+            displacementMap = calculateDirectionalDisplacement({
+                existingNodes: graph.nodes,
+                originNode: parentNode,
+                childNodes,
+                getNodesBounds: options.getNodesBounds,
+                options: directionalOptions
+            });
+        }
+        // 2. Build snapshot of displaced nodes before mutating positions
+        const displacedNodesSnapshot = Array.from(displacementMap.entries()).map(([id]) => {
+            const node = graph.nodes.find((n) => n.id === id);
+            return {
+                id,
+                originalPosition: { ...(node?.position ?? { x: 0, y: 0 }) }
+            };
+        });
+        // 3. Prepare child edges & parent connection edges
+        const edgesToAdd = [...childEdges];
+        const defaultCreateEdge = (sourceId, targetId) => {
+            if (graph.createEdge) {
+                return graph.createEdge(sourceId, targetId);
+            }
+            return {
+                id: crypto.randomUUID(),
+                type: 'default',
+                source: sourceId,
+                target: targetId
+            };
+        };
+        if (connectParentToChildren === 'all' || connectParentToChildren === true) {
+            childNodes.forEach((child) => {
+                const exists = edgesToAdd.some((e) => e.source === parentId && e.target === child.id);
+                if (!exists) {
+                    edgesToAdd.push(defaultCreateEdge(parentId, child.id));
+                }
+            });
+        }
+        else if (connectParentToChildren === 'first' && childNodes.length > 0) {
+            const firstChild = childNodes[0];
+            const exists = edgesToAdd.some((e) => e.source === parentId && e.target === firstChild.id);
+            if (!exists) {
+                edgesToAdd.push(defaultCreateEdge(parentId, firstChild.id));
+            }
+        }
+        const snapshot = {
+            parentId,
+            childNodeIds: childNodes.map((n) => n.id),
+            childEdgeIds: edgesToAdd.map((e) => e.id),
+            displacedNodes: displacedNodesSnapshot,
+            timestamp: Date.now()
+        };
+        snapshots.set(parentId, snapshot);
+        // 4. Position child nodes initially at origin node coordinate
+        const originPos = { ...parentNode.position };
+        const targetPositions = childNodes.map((child) => ({ ...child.position }));
+        childNodes.forEach((child) => {
+            child.position = { ...originPos };
+            if (!child.data)
+                child.data = {};
+            child.data.scale = 0;
+            child.data.opacity = 0;
+            const currentStyle = (child.style || '').replace(/opacity:\s*[^;]+;?/g, '').trim();
+            child.style = `${currentStyle ? currentStyle + '; ' : ''}opacity: 0;`;
+        });
+        edgesToAdd.forEach((edge) => {
+            const currentStyle = (edge.style || '').replace(/opacity:\s*[^;]+;?/g, '').trim();
+            edge.style = `${currentStyle ? currentStyle + '; ' : ''}opacity: 0;`;
+        });
+        // Add nodes and edges to graph without saving yet
+        graph.addNodeOrNodes(childNodes, undefined, false);
+        if (edgesToAdd.length > 0) {
+            graph.addEdges(edgesToAdd, false);
+        }
+        // 5. Build transition list
+        const chosenTrajectory = trajectory ?? createFanOutTrajectory({ curvature: 0.35 });
+        const transitions = [];
+        const effectiveStagger = duration === 0 ? 0 : staggerDelay;
+        // Expanding child transitions
+        childNodes.forEach((child, i) => {
+            transitions.push({
+                node: child,
+                from: originPos,
+                to: targetPositions[i],
+                trajectory: chosenTrajectory,
+                delay: i * effectiveStagger,
+                duration,
+                easing,
+                index: i,
+                total: childNodes.length
+            });
+        });
+        // Displaced node transitions
+        displacementMap.forEach((targetPos, nodeId) => {
+            const node = graph.nodes.find((n) => n.id === nodeId);
+            if (node) {
+                transitions.push({
+                    node,
+                    from: { ...node.position },
+                    to: targetPos,
+                    trajectory: linearPositionTrajectory,
+                    duration,
+                    easing
+                });
+            }
+        });
+        // 6. Run coordinated animation
+        if (activeAnimationCancel) {
+            activeAnimationCancel();
+        }
+        activeAnimationCancel = runMultiNodeTransition(transitions, {
+            defaultDuration: duration,
+            defaultEasing: easing,
+            onUpdate: () => {
+                if (edgesToAdd.length > 0) {
+                    const childIdSet = new Set(childNodes.map((c) => c.id));
+                    const childEdgesInGraph = graph.edges.filter((e) => childIdSet.has(e.target));
+                    if (childEdgesInGraph.length > 0) {
+                        childEdgesInGraph.forEach((edge) => {
+                            const child = childNodes.find((c) => c.id === edge.target);
+                            const childOpacity = child?.data?.opacity ?? 1;
+                            const currentStyle = (edge.style || '').replace(/opacity:\s*[^;]+;?/g, '').trim();
+                            edge.style = `${currentStyle ? currentStyle + '; ' : ''}opacity: ${childOpacity};`;
+                        });
+                        graph.setEdges([...graph.edges]);
+                    }
+                }
+                // Sync any mismatched node references in graph.nodes from transitions
+                transitions.forEach((t) => {
+                    const graphNode = graph.nodes.find((n) => n.id === t.node.id);
+                    if (graphNode && graphNode !== t.node) {
+                        graphNode.position = { ...t.node.position };
+                        graphNode.style = t.node.style;
+                        if (t.node.data) {
+                            graphNode.data = { ...graphNode.data, ...t.node.data };
+                        }
+                    }
+                });
+                graph.setNodes([...graph.nodes]);
+            },
+            onComplete: () => {
+                childNodes.forEach((child, i) => {
+                    const node = graph.nodes.find((n) => n.id === child.id);
+                    if (node) {
+                        node.position = { ...targetPositions[i] };
+                        node.style = (node.style || '').replace(/opacity:\s*[^;]+;?/g, '').trim() || undefined;
+                        if (node.data) {
+                            node.data.opacity = 1;
+                        }
+                    }
+                });
+                displacementMap.forEach((targetPos, nodeId) => {
+                    const graphNode = graph.nodes.find((n) => n.id === nodeId);
+                    if (graphNode) {
+                        graphNode.position = { ...targetPos };
+                    }
+                });
+                edgesToAdd.forEach((edge) => {
+                    const graphEdge = graph.edges.find((e) => e.id === edge.id);
+                    if (graphEdge) {
+                        graphEdge.style = (graphEdge.style || '').replace(/opacity:\s*[^;]+;?/g, '').trim() || undefined;
+                    }
+                });
+                graph.setNodes([...graph.nodes]);
+                graph.setEdges([...graph.edges]);
+                explodedNodeIds = [...explodedNodeIds, parentId];
+                activeAnimationCancel = null;
+                options.onSave?.();
+                graph.onSave?.();
+                onComplete?.();
+            }
+        });
+        return true;
+    }
+    function collapseNode(parentId, collapseOptions = {}) {
+        const snapshot = snapshots.get(parentId);
+        if (!snapshot) {
+            return false;
+        }
+        const parentNode = graph.nodes.find((n) => n.id === parentId);
+        if (!parentNode) {
+            return false;
+        }
+        const { duration = 400, staggerDelay = 15, easing = cubicOut, trajectory, onComplete } = collapseOptions;
+        const childIdSet = new Set(snapshot.childNodeIds);
+        const activeChildNodes = graph.nodes.filter((n) => childIdSet.has(n.id));
+        const originPos = { ...parentNode.position };
+        // Reverse trajectory pulls nodes back toward parent while collapsing scale
+        const reverseTrajectory = trajectory ?? createFanOutTrajectory({
+            curvature: 0.2,
+            startScale: 1,
+            endScale: 0,
+            startOpacity: 1,
+            endOpacity: 0
+        });
+        const transitions = [];
+        const effectiveStagger = duration === 0 ? 0 : staggerDelay;
+        // Collapsing child transitions back into origin
+        activeChildNodes.forEach((child, i) => {
+            transitions.push({
+                node: child,
+                from: { ...child.position },
+                to: originPos,
+                trajectory: reverseTrajectory,
+                delay: (activeChildNodes.length - 1 - i) * effectiveStagger,
+                duration,
+                easing,
+                index: i,
+                total: activeChildNodes.length
+            });
+        });
+        // Displaced node restore transitions
+        snapshot.displacedNodes.forEach(({ id, originalPosition }) => {
+            const node = graph.nodes.find((n) => n.id === id);
+            if (node) {
+                transitions.push({
+                    node,
+                    from: { ...node.position },
+                    to: originalPosition,
+                    trajectory: linearPositionTrajectory,
+                    duration,
+                    easing
+                });
+            }
+        });
+        if (activeAnimationCancel) {
+            activeAnimationCancel();
+        }
+        activeAnimationCancel = runMultiNodeTransition(transitions, {
+            defaultDuration: duration,
+            defaultEasing: easing,
+            onUpdate: () => {
+                const edgeIdSet = new Set(snapshot.childEdgeIds);
+                const childEdgesInGraph = graph.edges.filter((e) => edgeIdSet.has(e.id));
+                if (childEdgesInGraph.length > 0) {
+                    childEdgesInGraph.forEach((edge) => {
+                        const child = activeChildNodes.find((c) => c.id === edge.target);
+                        const childOpacity = child?.data?.opacity ?? 0;
+                        const currentStyle = (edge.style || '').replace(/opacity:\s*[^;]+;?/g, '').trim();
+                        edge.style = `${currentStyle ? currentStyle + '; ' : ''}opacity: ${childOpacity};`;
+                    });
+                    graph.setEdges([...graph.edges]);
+                }
+                // Sync any mismatched node references in graph.nodes from transitions
+                transitions.forEach((t) => {
+                    const graphNode = graph.nodes.find((n) => n.id === t.node.id);
+                    if (graphNode && graphNode !== t.node) {
+                        graphNode.position = { ...t.node.position };
+                        graphNode.style = t.node.style;
+                        if (t.node.data) {
+                            graphNode.data = { ...graphNode.data, ...t.node.data };
+                        }
+                    }
+                });
+                graph.setNodes([...graph.nodes]);
+            },
+            onComplete: () => {
+                // Animation completed: prune child nodes and edges
+                graph.removeNodes(activeChildNodes, false);
+                const edgeIdSet = new Set(snapshot.childEdgeIds);
+                const edgesToRemove = graph.edges.filter((e) => edgeIdSet.has(e.id));
+                if (edgesToRemove.length > 0) {
+                    graph.removeEdges(edgesToRemove, false);
+                }
+                snapshot.displacedNodes.forEach(({ id, originalPosition }) => {
+                    const graphNode = graph.nodes.find((n) => n.id === id);
+                    if (graphNode) {
+                        graphNode.position = { ...originalPosition };
+                    }
+                });
+                graph.setNodes([...graph.nodes]);
+                snapshots.delete(parentId);
+                explodedNodeIds = explodedNodeIds.filter((id) => id !== parentId);
+                activeAnimationCancel = null;
+                options.onSave?.();
+                graph.onSave?.();
+                onComplete?.();
+            }
+        });
+        return true;
+    }
+    function toggleExplode(parentId, explodeOptions, collapseOptions) {
+        if (isExploded(parentId)) {
+            return collapseNode(parentId, collapseOptions);
+        }
+        return explodeNode(parentId, explodeOptions);
+    }
+    function getSnapshot(parentId) {
+        return snapshots.get(parentId);
+    }
+    return {
+        get explodedNodeIds() {
+            return explodedNodeIds;
+        },
+        isExploded,
+        explodeNode,
+        collapseNode,
+        toggleExplode,
+        getSnapshot
+    };
+}