Add web worker support for layout calculations

- Add `webWorkers` prop to GraphCanvas for offloading layout computations
- Implement ForceAtlas2 worker using graphology's native FA2Layout
- Add custom d3-force worker for forceDirected2d/3d layouts
- Create layout adapters (createGraphPositionAdapter, createPositionMapAdapter)
  that implement LayoutStrategy for unified graph transformation
- Use inline worker imports (?worker&inline) for npm distribution compatibility
- Add WorkerLayout stories for testing worker vs main thread performance

The webWorkers prop moves heavy layout calculations off the main thread,
improving UI responsiveness especially for large graphs (500+ nodes).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: amcdnl

src/GraphCanvas/GraphCanvas.tsx

@@ -87,6 +87,14 @@ export interface GraphCanvasProps extends Omit<GraphSceneProps, 'theme'> {
    * Whether to aggregate edges with the same source and target.
    */
   aggregateEdges?: boolean;
+
+  /**
+   * Enable web workers for layout calculations.
+   * This moves heavy layout computations off the main thread,
+   * improving UI responsiveness especially for large graphs.
+   * Default: false
+   */
+  webWorkers?: boolean;
 }
 
 export type GraphCanvasRef = Omit<GraphSceneRef, 'graph' | 'renderScene'> &

src/GraphScene.tsx

@@ -182,6 +182,14 @@ export interface GraphSceneProps {
    */
   aggregateEdges?: boolean;
 
+  /**
+   * Enable web workers for layout calculations.
+   * This moves heavy layout computations off the main thread,
+   * improving UI responsiveness especially for large graphs.
+   * Default: false
+   */
+  webWorkers?: boolean;
+
   /**
    * When a node was clicked.
    */

src/layout/graphPositionAdapter.ts

@@ -0,0 +1,92 @@
+/**
+ * Layout adapter that reads positions directly from graphology node attributes.
+ * Used when a worker (like FA2Layout) has already computed positions
+ * and stored them as x/y attributes on the graph nodes.
+ */
+
+import type Graph from 'graphology';
+import type { DragReferences } from '../store';
+import type { InternalGraphPosition, InternalVector3 } from '../types';
+import type { LayoutStrategy } from './types';
+
+export interface GraphPositionAdapterOptions {
+  graph: Graph;
+  drags?: DragReferences;
+  /** Whether the layout is 3D (reads z attribute) */
+  is3d?: boolean;
+}
+
+/**
+ * Creates a LayoutStrategy adapter that reads positions from graph node attributes.
+ * This allows using `transformGraph` instead of `transformGraphWithPositions`
+ * when positions are stored directly on the graph (e.g., from FA2 worker).
+ */
+export function createGraphPositionAdapter({
+  graph,
+  drags,
+  is3d = false
+}: GraphPositionAdapterOptions): LayoutStrategy {
+  return {
+    getNodePosition(id: string): InternalGraphPosition {
+      // Check for drag position first
+      if (drags?.[id]?.position) {
+        const dragPos = drags[id].position;
+        return {
+          x: dragPos.x,
+          y: dragPos.y,
+          z: dragPos.z ?? (is3d ? 0 : 1)
+        } as InternalGraphPosition;
+      }
+
+      // Read position from graph node attributes
+      const attrs = graph.getNodeAttributes(id);
+      return {
+        x: (attrs as any).x ?? 0,
+        y: (attrs as any).y ?? 0,
+        z: is3d ? ((attrs as any).z ?? 0) : 1
+      } as InternalGraphPosition;
+    },
+
+    // No-op step since the worker already ran the layout
+    step(): boolean {
+      return false;
+    }
+  };
+}
+
+/**
+ * Creates a LayoutStrategy adapter from a pre-computed positions Map.
+ * Used when positions come from a custom worker that returns a Map.
+ */
+export function createPositionMapAdapter(
+  positions: Map<string, InternalVector3>,
+  drags?: DragReferences,
+  is3d = false
+): LayoutStrategy {
+  return {
+    getNodePosition(id: string): InternalGraphPosition {
+      // Check for drag position first
+      if (drags?.[id]?.position) {
+        const dragPos = drags[id].position;
+        return {
+          x: dragPos.x,
+          y: dragPos.y,
+          z: dragPos.z ?? (is3d ? 0 : 1)
+        } as InternalGraphPosition;
+      }
+
+      // Read position from positions map
+      const pos = positions.get(id);
+      return {
+        x: pos?.x ?? 0,
+        y: pos?.y ?? 0,
+        z: is3d ? (pos?.z ?? 0) : 1
+      } as InternalGraphPosition;
+    },
+
+    // No-op step since the worker already ran the layout
+    step(): boolean {
+      return false;
+    }
+  };
+}

src/layout/index.ts

@@ -12,3 +12,5 @@ export * from './layoutUtils';
 export * from './nooverlap';
 export * from './recommender';
 export * from './types';
+export * from './useForceAtlas2Worker';
+export * from './graphPositionAdapter';

src/layout/useForceAtlas2Worker.ts

@@ -0,0 +1,129 @@
+/**
+ * Hook for using graphology's built-in ForceAtlas2 web worker.
+ * This uses the production-ready worker implementation from graphology-layout-forceatlas2.
+ */
+
+import { useCallback, useEffect, useRef } from 'react';
+import type Graph from 'graphology';
+import random from 'graphology-layout/random.js';
+import FA2Layout from 'graphology-layout-forceatlas2/worker';
+import type { ForceAtlas2LayoutInputs } from './forceatlas2';
+
+export interface FA2WorkerResult {
+  /** Whether the layout completed successfully */
+  success: boolean;
+}
+
+/**
+ * Hook that provides access to graphology's ForceAtlas2 web worker.
+ * The FA2Layout worker runs the layout algorithm off the main thread,
+ * updating node positions directly on the graph object.
+ */
+export function useForceAtlas2Worker() {
+  const layoutRef = useRef<any | null>(null);
+  const isRunningRef = useRef(false);
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (layoutRef.current) {
+        layoutRef.current.kill();
+        layoutRef.current = null;
+      }
+    };
+  }, []);
+
+  /**
+   * Run ForceAtlas2 layout using web worker.
+   * Returns a promise that resolves when layout runs for sufficient time.
+   */
+  const runLayout = useCallback(
+    async (
+      graph: Graph,
+      options: Omit<ForceAtlas2LayoutInputs, 'graph' | 'drags'>
+    ): Promise<FA2WorkerResult> => {
+      // Kill any existing layout
+      if (layoutRef.current) {
+        layoutRef.current.kill();
+        layoutRef.current = null;
+      }
+
+      return new Promise((resolve) => {
+        const { iterations = 50, ...settings } = options;
+
+        // FA2 requires nodes to have initial x,y positions
+        // Assign random positions if not present
+        random.assign(graph);
+
+        // Create the FA2Layout worker
+        const layout = new FA2Layout(graph, {
+          settings
+        });
+
+        layoutRef.current = layout;
+        isRunningRef.current = true;
+
+        // FA2Layout worker runs continuously, we need to stop it after sufficient iterations
+        // Each requestAnimationFrame is roughly one "tick" - we'll run for iterations * 16ms
+        const runTimeMs = Math.max(500, iterations * 10); // At least 500ms, or 10ms per iteration
+
+        // Start the layout
+        layout.start();
+
+        // Stop after the calculated run time
+        setTimeout(() => {
+          if (layoutRef.current && isRunningRef.current) {
+            layout.stop();
+            isRunningRef.current = false;
+            resolve({ success: true });
+          } else {
+            resolve({ success: false });
+          }
+        }, runTimeMs);
+      });
+    },
+    []
+  );
+
+  /**
+   * Stop the current layout calculation
+   */
+  const stopLayout = useCallback(() => {
+    if (layoutRef.current) {
+      layoutRef.current.stop();
+      isRunningRef.current = false;
+    }
+  }, []);
+
+  /**
+   * Kill the layout and release resources
+   */
+  const killLayout = useCallback(() => {
+    if (layoutRef.current) {
+      layoutRef.current.kill();
+      layoutRef.current = null;
+      isRunningRef.current = false;
+    }
+  }, []);
+
+  /**
+   * Check if layout is currently running
+   */
+  const isRunning = useCallback(() => {
+    return isRunningRef.current && layoutRef.current?.isRunning();
+  }, []);
+
+  return {
+    runLayout,
+    stopLayout,
+    killLayout,
+    isRunning
+  };
+}
+
+/**
+ * Check if ForceAtlas2 worker is supported
+ */
+export function supportsFA2Worker(): boolean {
+  return typeof Worker !== 'undefined';
+}

src/typings.d.ts

@@ -2,3 +2,42 @@ declare module '*.json';
 declare module '*.css';
 declare module '*.md';
 declare module '*.svg';
+
+// Vite inline worker imports - creates worker from blob URL
+declare module '*?worker&inline' {
+  const WorkerConstructor: {
+    new (): Worker;
+  };
+  export default WorkerConstructor;
+}
+
+declare module 'graphology-layout-forceatlas2/worker' {
+  import type Graph from 'graphology';
+
+  interface FA2LayoutSettings {
+    adjustSizes?: boolean;
+    barnesHutOptimize?: boolean;
+    barnesHutTheta?: number;
+    edgeWeightInfluence?: number;
+    gravity?: number;
+    linLogMode?: boolean;
+    outboundAttractionDistribution?: boolean;
+    scalingRatio?: number;
+    slowDown?: number;
+    strongGravityMode?: boolean;
+  }
+
+  interface FA2LayoutOptions {
+    settings?: FA2LayoutSettings;
+  }
+
+  class FA2Layout {
+    constructor(graph: Graph, options?: FA2LayoutOptions);
+    start(): void;
+    stop(): void;
+    kill(): void;
+    isRunning(): boolean;
+  }
+
+  export default FA2Layout;
+}