@pixerate/editor-svelte 0.3.11 → 0.4.0

package/src/canvas/README.md

@@ -0,0 +1,167 @@
+# @pixerate/editor-svelte/canvas
+
+A headless, unstyled Svelte 5 runes architecture for building interactive graph, flow, and diagramming canvas experiences on top of SvelteFlow (`@xyflow/svelte`).
+
+---
+
+## Philosophy & Core Principles
+
+1. **Headless & UI-Agnostic**: Contains zero assumptions about styles, colors, DOM presentation, or application-specific AI pipelines. Pure business logic, coordinate mathematics, and interaction controllers.
+2. **Svelte 5 Runes First**: Implemented using `$state.raw`, `$derived`, and modern functional runes instead of `.svelte` component-as-controller wrappers.
+3. **High Performance**: Eliminates expensive per-frame array clones during animations and node dragging, avoiding requestAnimationFrame memory churn.
+4. **Decoupled Architecture**: Independent modules for graph state, clipboard serialization, Dagre auto-layout, docking/intersections, and hotkeys that can be used together or individually.
+
+---
+
+## Module Overview
+
+| Module | Purpose |
+| :--- | :--- |
+| [`createCanvasGraph.svelte.ts`](./createCanvasGraph.svelte.ts) | Reactive graph state management, node deduplication, edge-preserving replacement, and diff calculation. |
+| [`createCanvasClipboard.svelte.ts`](./createCanvasClipboard.svelte.ts) | Serialized JSON clipboard management, UUID remapping, position offset, URL and text pasting. |
+| [`createCanvasDocking.svelte.ts`](./createCanvasDocking.svelte.ts) | Drag-to-dock intersection tracking, dock target hover/leave/drop lifecycle, and connection state. |
+| [`createCanvasLayout.ts`](./createCanvasLayout.ts) | Dagre hierarchical auto-layout, viewport centering, and bounding box math. |
+| [`createCanvasShortcuts.ts`](./createCanvasShortcuts.ts) | Global keyboard shortcut binding with automatic suppression during active text editing. |
+| [`createCanvasInteractions.svelte.ts`](./createCanvasInteractions.svelte.ts) | Spacebar panning toggle, trackpad pinch detection, and SvelteFlow interaction presets. |
+| [`types.ts`](./types.ts) | Shared generic types (`CanvasNode`, `CanvasEdge`, `GraphDifferences`, `CanvasLayoutOptions`, etc.). |
+
+---
+
+## Quickstart & Usage
+
+### 1. Basic Setup
+
+```svelte
+<script lang="ts">
+  import { SvelteFlow, useSvelteFlow } from '@xyflow/svelte';
+  import '@xyflow/svelte/dist/style.css';
+  import {
+    createCanvasGraph,
+    createCanvasClipboard,
+    createCanvasShortcuts,
+    createCanvasInteractions,
+    defaultSvelteFlowPreset
+  } from '@pixerate/editor-svelte/canvas';
+
+  // 1. Initialize reactive graph controller
+  const graph = createCanvasGraph({
+    initialNodes: [
+      { id: '1', position: { x: 100, y: 100 }, data: { label: 'Start' } }
+    ],
+    initialEdges: [],
+    onSave: () => console.log('Graph changed, autosaving...')
+  });
+
+  // 2. Setup clipboard handler
+  const clipboard = createCanvasClipboard({
+    onPasteNodes: (nodes, edges) => {
+      graph.addNodeOrNodes(nodes);
+      if (edges) graph.addEdges(edges);
+    },
+    onPasteUrl: (url) => {
+      console.log('Pasted URL:', url);
+    }
+  });
+
+  // 3. Attach keyboard shortcuts
+  $effect(() => {
+    return createCanvasShortcuts({
+      getSelectedNodes: () => graph.nodes.filter((n) => n.selected),
+      onDelete: (selected) => graph.removeNodes(selected),
+      onDuplicate: (selected) => {
+        const clones = selected.map((n) => ({
+          ...n,
+          id: crypto.randomUUID(),
+          position: { x: n.position.x + 40, y: n.position.y + 40 }
+        }));
+        graph.addNodeOrNodes(clones);
+      }
+    });
+  });
+</script>
+
+<div class="w-full h-screen" onpaste={(e) => clipboard.handlePasteEvent(e)}>
+  <SvelteFlow
+    bind:nodes={graph.nodes}
+    bind:edges={graph.edges}
+    {...defaultSvelteFlowPreset}
+  />
+</div>
+```
+
+---
+
+## API Reference
+
+### `createCanvasGraph<TNode, TEdge>(options?)`
+
+Creates a reactive graph controller managing nodes and edges.
+
+#### Parameters (`options`):
+- `initialNodes?: TNode[]`: Initial node list.
+- `initialEdges?: TEdge[]`: Initial edge list.
+- `onNodesChange?: (nodes: TNode[]) => void`: Callback fired when nodes change.
+- `onEdgesChange?: (edges: TEdge[]) => void`: Callback fired when edges change.
+- `onSave?: () => void`: Optional persistence trigger.
+- `createEdge?: (sourceId, targetId, options?) => TEdge`: Edge factory function.
+
+#### Returns:
+- `nodes`: Getter/setter for active nodes array.
+- `edges`: Getter/setter for active edges array.
+- `addNodeOrNodes(nodeOrNodes, animateFromPosition?, options?)`: Adds nodes with deduplication and optional positioning animation.
+- `addEdge(edge, options?)` / `addEdges(edges, options?)`: Adds edges.
+- `removeNodes(nodesToRemove, options?)` / `removeEdges(edgesToRemove, options?)`: Removes entities by ID.
+- `replaceNode(oldNode, newNode, save?, keepEdges?)`: Replaces a node, optionally updating connected edge endpoints.
+- `addConnectedNodes(params)`: Connects incoming and outgoing nodes to a batch of added nodes.
+- `getDifferences(baseline)`: Returns `{ changedNodes, changedEdges, removedNodes, removedEdges }`.
+
+---
+
+### `createCanvasLayout`
+
+Pure geometry and Dagre layout calculations:
+
+- `getLayoutedNodes(nodes, edges, getNodesBounds, options?)`: Automatically lays out graph nodes hierarchically (`'LR'`, `'TB'`, `'RL'`, or `'BT'`).
+- `getCenteredNodePosition(width, height, screenToFlowPosition, screenDimensions?)`: Computes top-left coordinate to center an element in view.
+- `centerNodes(nodes, screenToFlowPosition, getNodesBounds, screenDimensions?)`: Translates a collection of nodes so their bounding box is centered in the current viewport.
+
+---
+
+### `createCanvasClipboard(options?)`
+
+Headless clipboard interaction:
+
+- `copySelectedNodes(nodes, edges?, event?)`: Serializes nodes to clipboard as JSON.
+- `cutSelectedNodes(nodes, edges?, onRemove?, event?)`: Copies and calls deletion callback.
+- `handlePasteEvent(event)`: Intelligently handles paste events, disambiguating images, serialized nodes, URLs, and plain text.
+
+---
+
+### `createCanvasDocking(options?)`
+
+Drag-and-dock interaction tracking:
+
+- `handleNodeDragStart({ targetNode, event })`: Starts drag tracking.
+- `handleNodeDrag({ targetNode, event }, getIntersectingNodes)`: Computes intersections, firing `onDockHover` and `onDockLeave`.
+- `handleNodeDragStop({ targetNode, event }, getIntersectingNodes, updatePosition?)`: Fires `onDockDrop` and cleans up state.
+- `handleConnectStart` / `handleConnectEnd`: Tracks connection handle dragging.
+
+---
+
+### `createCanvasShortcuts(options)`
+
+Attaches standard canvas hotkeys (`Meta/Ctrl+C`, `Meta/Ctrl+X`, `Meta/Ctrl+V`, `Delete`, `Meta/Ctrl+D`, `Meta/Ctrl+A`, `Meta/Ctrl+G`, zoom controls):
+
+- Automatically respects active text inputs (`input`, `textarea`, `select`, `contenteditable`, and `.ProseMirror`).
+- Returns a cleanup function `() => void`.
+
+---
+
+### `createCanvasInteractions(options?)`
+
+Manages viewport interaction modes:
+
+- `isSpacebarPanning`: Reactive flag active while Spacebar is held down.
+- `trackpadDetected`: Reactive flag set when trackpad pinch-to-zoom is detected.
+- Presets: `defaultSvelteFlowPreset`, `miroCompatiblePreset`.
+- Helper: `restorePanelPointerEvents()` restores panel clickability after drag-selection.

package/src/canvas/__tests__/canvas-clipboard.test.ts

@@ -0,0 +1,154 @@
+import { describe, it, expect, vi } from 'vitest';
+import {
+	createCanvasClipboard,
+	isValidCanvasNode,
+	isValidUrl,
+	isEventFromTextInput
+} from '../createCanvasClipboard.svelte.js';
+import type { CanvasNode, CanvasEdge } from '../types.js';
+
+describe('createCanvasClipboard & Clipboard Utilities', () => {
+	it('validates canvas nodes with isValidCanvasNode', () => {
+		expect(isValidCanvasNode({ id: '1', position: { x: 10, y: 20 } })).toBe(true);
+		expect(isValidCanvasNode({ id: 123, position: { x: 10, y: 20 } })).toBe(false);
+		expect(isValidCanvasNode({ id: '1' })).toBe(false);
+		expect(isValidCanvasNode(null)).toBe(false);
+		expect(isValidCanvasNode('not a node')).toBe(false);
+	});
+
+	it('validates URLs with isValidUrl', () => {
+		expect(isValidUrl('https://example.com')).toBe(true);
+		expect(isValidUrl('http://localhost:5173/canvas')).toBe(true);
+		expect(isValidUrl('not a url')).toBe(false);
+		expect(isValidUrl('ftp://example.com')).toBe(false);
+	});
+
+	it('detects text input targets with isEventFromTextInput', () => {
+		const inputEl = { tagName: 'INPUT' } as unknown as HTMLElement;
+		const textareaEl = { tagName: 'TEXTAREA' } as unknown as HTMLElement;
+		const contentEditableEl = { isContentEditable: true, tagName: 'DIV' } as unknown as HTMLElement;
+		const canvasEl = { tagName: 'DIV', isContentEditable: false } as unknown as HTMLElement;
+
+		expect(isEventFromTextInput({ target: inputEl })).toBe(true);
+		expect(isEventFromTextInput({ target: textareaEl })).toBe(true);
+		expect(isEventFromTextInput({ target: contentEditableEl })).toBe(true);
+		expect(isEventFromTextInput({ target: canvasEl })).toBe(false);
+		expect(isEventFromTextInput({ target: null })).toBe(false);
+	});
+
+	it('copies selected nodes into clipboardData JSON payload', () => {
+		const clipboard = createCanvasClipboard();
+		const mockClipboardData = {
+			setData: vi.fn()
+		};
+		const mockEvent = {
+			target: { tagName: 'DIV' },
+			clipboardData: mockClipboardData,
+			preventDefault: vi.fn()
+		} as unknown as ClipboardEvent;
+
+		const selectedNodes: CanvasNode[] = [{ id: 'n1', position: { x: 10, y: 20 }, data: {} }];
+		const connectedEdges: CanvasEdge[] = [{ id: 'e1', source: 'n1', target: 'n2' }];
+
+		const copied = clipboard.copySelectedNodes(selectedNodes, connectedEdges, mockEvent);
+		expect(copied).toBe(true);
+		expect(mockClipboardData.setData).toHaveBeenCalledWith(
+			'application/json',
+			expect.stringContaining('"id":"n1"')
+		);
+		expect(mockEvent.preventDefault).toHaveBeenCalled();
+	});
+
+	it('cuts selected nodes by calling onRemove callback', () => {
+		const clipboard = createCanvasClipboard();
+		const onRemove = vi.fn();
+		const mockEvent = {
+			target: { tagName: 'DIV' },
+			clipboardData: { setData: vi.fn() },
+			preventDefault: vi.fn()
+		} as unknown as ClipboardEvent;
+
+		const selectedNodes: CanvasNode[] = [{ id: 'n1', position: { x: 0, y: 0 }, data: {} }];
+
+		const cut = clipboard.cutSelectedNodes(selectedNodes, undefined, onRemove, mockEvent);
+		expect(cut).toBe(true);
+		expect(onRemove).toHaveBeenCalledWith(selectedNodes);
+	});
+
+	it('handles paste of serialized node JSON with UUID remapping and offset', async () => {
+		const onPasteNodes = vi.fn();
+		const clipboard = createCanvasClipboard({ onPasteNodes });
+
+		const originalNodes: CanvasNode[] = [
+			{ id: 'orig-1', position: { x: 100, y: 100 }, data: { label: 'Node 1' } },
+			{ id: 'orig-2', position: { x: 200, y: 200 }, data: { label: 'Node 2' } }
+		];
+		const originalEdges: CanvasEdge[] = [{ id: 'e-orig', source: 'orig-1', target: 'orig-2' }];
+
+		const serializedPayload = JSON.stringify({
+			version: 1,
+			nodes: originalNodes,
+			edges: originalEdges
+		});
+
+		const mockEvent = {
+			target: { tagName: 'DIV' },
+			clipboardData: {
+				getData: (format: string) => (format === 'application/json' ? serializedPayload : ''),
+				files: []
+			},
+			preventDefault: vi.fn()
+		} as unknown as ClipboardEvent;
+
+		const handled = await clipboard.handlePasteEvent(mockEvent);
+		expect(handled).toBe(true);
+		expect(onPasteNodes).toHaveBeenCalledTimes(1);
+
+		const [pastedNodes, pastedEdges] = onPasteNodes.mock.calls[0];
+		expect(pastedNodes).toHaveLength(2);
+		expect(pastedNodes[0].id).not.toBe('orig-1');
+		expect(pastedNodes[0].position.x).toBe(140); // 100 + 40
+		expect(pastedNodes[0].position.y).toBe(140); // 100 + 40
+
+		// Check edge remapping
+		expect(pastedEdges).toHaveLength(1);
+		expect(pastedEdges[0].source).toBe(pastedNodes[0].id);
+		expect(pastedEdges[0].target).toBe(pastedNodes[1].id);
+	});
+
+	it('handles paste of plain text URLs', async () => {
+		const onPasteUrl = vi.fn();
+		const clipboard = createCanvasClipboard({ onPasteUrl });
+
+		const mockEvent = {
+			target: { tagName: 'DIV' },
+			clipboardData: {
+				getData: (format: string) => (format === 'text/plain' ? 'https://example.com/asset' : ''),
+				files: []
+			},
+			preventDefault: vi.fn()
+		} as unknown as ClipboardEvent;
+
+		const handled = await clipboard.handlePasteEvent(mockEvent);
+		expect(handled).toBe(true);
+		expect(onPasteUrl).toHaveBeenCalledWith('https://example.com/asset');
+	});
+
+	it('handles paste of plain text', async () => {
+		const onPasteText = vi.fn();
+		const clipboard = createCanvasClipboard({ onPasteText });
+
+		const mockEvent = {
+			target: { tagName: 'DIV' },
+			clipboardData: {
+				getData: (format: string) => (format === 'text/plain' ? 'Sample text content' : ''),
+				files: []
+			},
+			preventDefault: vi.fn()
+		} as unknown as ClipboardEvent;
+
+		const handled = await clipboard.handlePasteEvent(mockEvent);
+		expect(handled).toBe(true);
+		expect(onPasteText).toHaveBeenCalledWith('Sample text content');
+	});
+});

package/src/canvas/__tests__/canvas-docking.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createCanvasDocking } from '../createCanvasDocking.svelte.js';
+import type { CanvasNode } from '../types.js';
+
+describe('createCanvasDocking', () => {
+  const createSampleNode = (id: string, type = 'default', x = 0, y = 0): CanvasNode => ({
+    id,
+    type,
+    position: { x, y },
+    data: {}
+  });
+
+  it('initializes with null drag and connect states', () => {
+    const docking = createCanvasDocking();
+
+    expect(docking.isDragging).toBe(false);
+    expect(docking.draggedNode).toBeNull();
+    expect(docking.draggedInitialPosition).toBeNull();
+    expect(docking.connectingHandle).toBe('');
+    expect(docking.connectingNode).toBeNull();
+  });
+
+  it('tracks drag start, records initial position, and sets isDragging', () => {
+    const docking = createCanvasDocking();
+    const node = createSampleNode('n1', 'default', 100, 200);
+
+    docking.handleNodeDragStart({ targetNode: node });
+
+    expect(docking.isDragging).toBe(true);
+    expect(docking.draggedNode).toBe(node);
+    expect(docking.draggedInitialPosition).toEqual({ x: 100, y: 200 });
+  });
+
+  it('fires onDockHover and onDockLeave as intersecting dock targets change', () => {
+    const onDockHover = vi.fn();
+    const onDockLeave = vi.fn();
+    const docking = createCanvasDocking({
+      isDockTarget: (n) => n.type === 'dockArea',
+      onDockHover,
+      onDockLeave
+    });
+
+    const draggedNode = createSampleNode('dragged', 'item', 50, 50);
+    const dockNode1 = createSampleNode('dock-1', 'dockArea', 0, 0);
+    const dockNode2 = createSampleNode('dock-2', 'dockArea', 200, 200);
+    const normalNode = createSampleNode('normal', 'item', 50, 50);
+
+    docking.handleNodeDragStart({ targetNode: draggedNode });
+
+    // Drag intersecting with dockNode1 and a non-dock normalNode
+    docking.handleNodeDrag(
+      { targetNode: draggedNode },
+      () => [dockNode1, normalNode]
+    );
+
+    expect(onDockHover).toHaveBeenCalledTimes(1);
+    expect(onDockHover).toHaveBeenCalledWith(dockNode1, draggedNode);
+    expect(onDockLeave).not.toHaveBeenCalled();
+
+    // Drag moves over dockNode2, leaving dockNode1
+    docking.handleNodeDrag(
+      { targetNode: draggedNode },
+      () => [dockNode2]
+    );
+
+    expect(onDockLeave).toHaveBeenCalledTimes(1);
+    expect(onDockLeave).toHaveBeenCalledWith(expect.objectContaining({ id: 'dock-1' }), draggedNode);
+    expect(onDockHover).toHaveBeenCalledTimes(2);
+    expect(onDockHover).toHaveBeenLastCalledWith(dockNode2, draggedNode);
+  });
+
+  it('fires onDockDrop and restores position on dock stop', () => {
+    const onDockDrop = vi.fn();
+    const onSave = vi.fn();
+    const updateNodePosition = vi.fn();
+
+    const docking = createCanvasDocking({
+      isDockTarget: (n) => n.type === 'dockArea',
+      restorePositionOnDock: true,
+      onDockDrop,
+      onSave
+    });
+
+    const draggedNode = createSampleNode('dragged', 'item', 100, 100);
+    const dockNode = createSampleNode('dock', 'dockArea', 0, 0);
+
+    docking.handleNodeDragStart({ targetNode: draggedNode });
+
+    // Node was dragged to new position
+    draggedNode.position = { x: 300, y: 300 };
+
+    docking.handleNodeDragStop(
+      { targetNode: draggedNode },
+      () => [dockNode],
+      updateNodePosition
+    );
+
+    expect(onDockDrop).toHaveBeenCalledWith(dockNode, draggedNode);
+    expect(updateNodePosition).toHaveBeenCalledWith('dragged', { x: 100, y: 100 });
+    expect(onSave).toHaveBeenCalled();
+    expect(docking.isDragging).toBe(false);
+    expect(docking.draggedNode).toBeNull();
+  });
+
+  it('tracks handle connect start and end', () => {
+    const docking = createCanvasDocking();
+    const node = createSampleNode('source-node');
+    const getNode = (id: string) => (id === 'source-node' ? node : undefined);
+
+    docking.handleConnectStart(
+      { nodeId: 'source-node', handleId: 'h1', handleType: 'source' },
+      getNode
+    );
+
+    expect(docking.connectingHandle).toBe('source');
+    expect(docking.connectingNode).toBe(node);
+
+    docking.handleConnectEnd();
+
+    expect(docking.connectingHandle).toBe('');
+    expect(docking.connectingNode).toBeNull();
+  });
+
+  it('resets all state cleanly', () => {
+    const docking = createCanvasDocking();
+    const node = createSampleNode('test');
+
+    docking.handleNodeDragStart({ targetNode: node });
+    expect(docking.isDragging).toBe(true);
+
+    docking.reset();
+    expect(docking.isDragging).toBe(false);
+    expect(docking.draggedNode).toBeNull();
+    expect(docking.draggedInitialPosition).toBeNull();
+  });
+});

package/src/canvas/__tests__/canvas-graph.test.ts

@@ -0,0 +1,159 @@
+import { describe, it, expect, vi } from 'vitest';
+import {
+	createCanvasGraph,
+	calculateGraphDifferences,
+	replaceNodeInGraph
+} from '../createCanvasGraph.svelte.js';
+import type { CanvasNode, CanvasEdge } from '../types.js';
+
+describe('createCanvasGraph & Graph Operations', () => {
+	const createSampleNode = (id: string, x = 0, y = 0): CanvasNode => ({
+		id,
+		position: { x, y },
+		data: { label: `Node ${id}` }
+	});
+
+	const createSampleEdge = (id: string, source: string, target: string): CanvasEdge => ({
+		id,
+		source,
+		target
+	});
+
+	it('initializes with default empty or provided nodes and edges', () => {
+		const graph = createCanvasGraph({
+			initialNodes: [createSampleNode('1')],
+			initialEdges: [createSampleEdge('e1', '1', '2')]
+		});
+
+		expect(graph.nodes).toHaveLength(1);
+		expect(graph.edges).toHaveLength(1);
+		expect(graph.nodes[0].id).toBe('1');
+	});
+
+	it('adds nodes and ignores duplicates', () => {
+		const onNodesChange = vi.fn();
+		const graph = createCanvasGraph({ onNodesChange });
+
+		graph.addNodeOrNodes(createSampleNode('1'));
+		expect(graph.nodes).toHaveLength(1);
+		expect(onNodesChange).toHaveBeenCalledTimes(1);
+
+		// Adding existing node does not duplicate
+		graph.addNodeOrNodes(createSampleNode('1'));
+		expect(graph.nodes).toHaveLength(1);
+
+		// Adding multiple nodes
+		graph.addNodeOrNodes([createSampleNode('2'), createSampleNode('3')]);
+		expect(graph.nodes).toHaveLength(3);
+	});
+
+	it('adds and removes edges cleanly', () => {
+		const onEdgesChange = vi.fn();
+		const graph = createCanvasGraph({ onEdgesChange });
+
+		const e1 = createSampleEdge('e1', '1', '2');
+		const e2 = createSampleEdge('e2', '2', '3');
+
+		graph.addEdge(e1);
+		expect(graph.edges).toHaveLength(1);
+
+		graph.addEdges([e2]);
+		expect(graph.edges).toHaveLength(2);
+
+		graph.removeEdges([e1]);
+		expect(graph.edges).toHaveLength(1);
+		expect(graph.edges[0].id).toBe('e2');
+	});
+
+	it('removes nodes by reference or ID matching', () => {
+		const n1 = createSampleNode('1');
+		const n2 = createSampleNode('2');
+		const graph = createCanvasGraph({ initialNodes: [n1, n2] });
+
+		graph.removeNodes([n1]);
+		expect(graph.nodes).toHaveLength(1);
+		expect(graph.nodes[0].id).toBe('2');
+	});
+
+	it('replaces a node and preserves connected edges when keepEdges is true', () => {
+		const n1 = createSampleNode('1');
+		const n2 = createSampleNode('2');
+		const e1 = createSampleEdge('e1', '1', '2');
+		const n1Replacement = createSampleNode('new-1', 10, 10);
+
+		const result = replaceNodeInGraph([n1, n2], [e1], n1, n1Replacement, true);
+		expect(result.nodes.some((n) => n.id === 'new-1')).toBe(true);
+		expect(result.nodes.some((n) => n.id === '1')).toBe(false);
+
+		// Edge should have updated source to new-1
+		expect(result.edges).toHaveLength(1);
+		expect(result.edges[0].source).toBe('new-1');
+		expect(result.edges[0].target).toBe('2');
+	});
+
+	it('replaces a node without preserving edges when keepEdges is false', () => {
+		const n1 = createSampleNode('1');
+		const n2 = createSampleNode('2');
+		const e1 = createSampleEdge('e1', '1', '2');
+		const n1Replacement = createSampleNode('new-1', 10, 10);
+
+		const result = replaceNodeInGraph([n1, n2], [e1], n1, n1Replacement, false);
+		expect(result.nodes.some((n) => n.id === 'new-1')).toBe(true);
+		expect(result.edges).toHaveLength(1);
+		expect(result.edges[0].source).toBe('1'); // Unchanged
+	});
+
+	it('adds connected nodes connecting inbound and outbound targets', () => {
+		const graph = createCanvasGraph();
+		const inNode = createSampleNode('in');
+		const outNode = createSampleNode('out');
+		const midNode = createSampleNode('mid');
+
+		graph.addNodeOrNodes([inNode, outNode]);
+
+		graph.addConnectedNodes({
+			nodesToAdd: [midNode],
+			inboundNodes: [inNode],
+			outboundNodes: [outNode],
+			getEdgeLabel: (src, tgt) => `${src.id}->${tgt.id}`
+		});
+
+		expect(graph.nodes).toHaveLength(3);
+		expect(graph.edges).toHaveLength(2);
+		expect(graph.edges.find((e) => e.source === 'in' && e.target === 'mid')?.label).toBe('in->mid');
+		expect(graph.edges.find((e) => e.source === 'mid' && e.target === 'out')?.label).toBe('mid->out');
+	});
+
+	it('accurately calculates graph differences against a baseline', () => {
+		const n1 = createSampleNode('1', 0, 0);
+		const n2 = createSampleNode('2', 50, 50);
+		const e1 = createSampleEdge('e1', '1', '2');
+
+		const baseline = {
+			nodes: [n1, n2],
+			edges: [e1]
+		};
+
+		// Node 2 position changed, node 3 added, edge 1 removed, edge 2 added
+		const n2Changed = createSampleNode('2', 100, 100);
+		const n3Added = createSampleNode('3', 200, 200);
+		const e2Added = createSampleEdge('e2', '2', '3');
+
+		const current = {
+			nodes: [n1, n2Changed, n3Added],
+			edges: [e2Added]
+		};
+
+		const diff = calculateGraphDifferences(current, baseline);
+
+		expect(diff.changedNodes).toHaveLength(2); // n2 changed + n3 newly added
+		expect(diff.changedNodes.map((n) => n.id)).toContain('2');
+		expect(diff.changedNodes.map((n) => n.id)).toContain('3');
+		expect(diff.removedNodes).toHaveLength(0);
+
+		expect(diff.removedEdges).toHaveLength(1);
+		expect(diff.removedEdges[0].id).toBe('e1');
+		expect(diff.changedEdges).toHaveLength(1);
+		expect(diff.changedEdges[0].id).toBe('e2');
+	});
+});