Performance Refactors #396

amcdnl · 2026-01-02T16:27:27Z

Improve edges
Improve nodes
Add web workers
Add edge sub labels

- 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]>

- Add Nodes.tsx batched container using Three.js InstancedMesh - Add useNodeInstancing.ts for managing instanced sphere rendering - Add useNodeAnimations.ts with centralized lerp animation loop - Add useNodeEvents.ts for raycasting and event handling - Add classifyNodes.ts for node type classification - Update GraphScene.tsx to use batched Nodes component - Add hoveredNodeIds and nodeContextMenus state to store Replaces O(n) individual Node components with single InstancedMesh, achieving 136 FPS with 1000 nodes (target was 60 FPS). Maintains backward compatibility with custom renderNode prop. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

cloudflare-workers-and-pages · 2026-01-02T16:27:58Z

Deploying reagraph-storybook with Cloudflare Pages

Latest commit:	`b8347aa`
Status:	✅ Deploy successful!
Preview URL:	https://a7e0162e.reagraph-storybook.pages.dev
Branch Preview URL:	https://edge-refactor-2.reagraph-storybook.pages.dev

View logs

Copilot

Pull request overview

This PR implements significant performance improvements for graph rendering by introducing web workers for layout calculations, instanced rendering for nodes, batched edge rendering, edge sub-labels, and LOD (Level of Detail) optimizations. The changes enable the library to handle 1000+ nodes/edges efficiently while maintaining smooth animations and interactions.

Key changes:

Web worker support for layout calculations (ForceAtlas2 and custom layouts)
InstancedMesh-based node rendering for massive performance gains
Unified edge rendering system with geometry batching
LOD system for labels to improve zoom-out performance

Reviewed changes

Copilot reviewed 31 out of 33 changed files in this pull request and generated 16 comments.

Show a summary per file

File	Description
stories/demos/WorkerLayout.story.tsx	New story demonstrating web worker layout performance across different graph sizes and layout types
stories/demos/EdgePerformance.story.tsx	Comprehensive edge rendering performance test suite with multiple test configurations
stories/demos/BackwardsCompatibilityTest.story.tsx	Test stories validating backwards compatibility with legacy edge system
src/workers/useLayoutWorker.ts	Hook managing layout web worker lifecycle and async layout calculations
src/workers/layout.worker.ts	Web worker implementation for force-directed and circular layouts
src/workers/index.ts	Worker module exports
src/utils/visibility.ts	Import path fix for Edge types
src/utils/graph.ts	New transformGraphWithPositions function for worker-computed positions
src/utils/geometry.ts	Reduced geometry complexity for better edge performance
src/useGraph.ts	Integrated web worker support for layout calculations
src/typings.d.ts	Type definitions for Vite worker imports and ForceAtlas2 worker
src/symbols/nodes/*	New instanced node rendering system with animation, events, and classification
src/symbols/edges/*	Improved edge rendering with animation, LOD, and sub-label support
src/symbols/Node.tsx	Added LOD for individual node labels
src/symbols/Edge.tsx	Deprecated in favor of batched Edges component, added sub-label support
src/store.ts	Added hoveredNodeIds and nodeContextMenus for batched rendering
src/layout/*	Worker integration for ForceAtlas2 and position adapters
src/GraphScene.tsx	Switched to batched Nodes and Edges components
src/GraphCanvas/GraphCanvas.tsx	Increased animation threshold to 2000 nodes/edges
.gitignore	Added IDE and tool-specific ignore patterns

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-02T16:31:26Z

stories/demos/EdgePerformance.story.tsx

+    // Avoid duplicate edges
+    if (!edges.find(e => e.id === edgeId)) {


The edge generation logic checks if an edge with the same ID exists, but self-loops are intentionally allowed 10% of the time. However, the duplicate check on line 44 only checks ID equality, not source-target pairs. This could lead to different edges with duplicate IDs being incorrectly filtered. Consider checking both the edge ID and the source-target pair to handle self-loops correctly.

Copilot · 2026-01-02T16:31:27Z

src/workers/layout.worker.ts

+// Note: We can't import forceRadial and forceInABox here as they have complex dependencies
+// that don't work in the worker context. For now, we use a simplified force layout.


The comment mentions 'forceRadial and forceInABox' having complex dependencies that don't work in worker context, but doesn't specify what the limitation is. Consider documenting why these dependencies fail in workers (e.g., DOM access, module imports) to help future maintainers.

Suggested change

// Note: We can't import forceRadial and forceInABox here as they have complex dependencies

// that don't work in the worker context. For now, we use a simplified force layout.

// Note: We can't import forceRadial and forceInABox here as they pull in dependencies that

// rely on main-thread-only features (e.g., DOM/window access and side-effectful module imports),

// which are not available in the Web Worker context. For now, we use a simplified force layout.

Copilot · 2026-01-02T16:31:27Z

src/layout/useForceAtlas2Worker.ts

+        setTimeout(() => {
+          if (layoutRef.current && isRunningRef.current) {
+            layout.stop();
+            isRunningRef.current = false;
+            resolve({ success: true });
+          } else {
+            resolve({ success: false });
+          }
+        }, runTimeMs);


The FA2Layout worker is killed on unmount but there's no cleanup for the timeout started on line 74. If the component unmounts before the timeout fires, the callback will attempt to access a killed layout. Store the timeout ID and clear it in the cleanup function.

Copilot · 2026-01-02T16:31:27Z

stories/demos/WorkerLayout.story.tsx

+const fa2SmallGraph = generateLargeGraph(50);
+const fa2MediumGraph = generateLargeGraph(200);
+const fa2LargeGraph = generateLargeGraph(500);


The variable name 'fa2SmallGraph' uses the abbreviation 'fa2' which may not be clear to all developers. Consider using more descriptive names like 'forceAtlas2SmallGraph' or adding a comment explaining that FA2 refers to ForceAtlas2 layout algorithm.

Copilot · 2026-01-02T16:31:28Z

src/workers/useLayoutWorker.ts

+      // Reject all pending requests
+      pendingRequestsRef.current.forEach((pending) => {
+        pending.reject(new Error('Worker error: ' + error.message));


The error message concatenation on line 108 uses string concatenation which could potentially expose sensitive error details. Consider using a structured error logging approach or sanitizing the error message before logging.

Suggested change

// Reject all pending requests

pendingRequestsRef.current.forEach((pending) => {

pending.reject(new Error('Worker error: ' + error.message));

// Reject all pending requests with a sanitized error

pendingRequestsRef.current.forEach((pending) => {

const sanitizedError = new Error('Worker error');

(sanitizedError as any).cause = error;

pending.reject(sanitizedError);

Copilot · 2026-01-02T16:31:30Z

src/workers/layout.worker.ts

+/**
+ * Run force-directed layout calculation
+ * Note: This is a simplified version that doesn't support clustering or DAG modes
+ * since those have complex dependencies. For full features, use main-thread layout.
+ */
+function calculateForceDirectedLayout(
+  nodes: WorkerNode[],
+  edges: WorkerEdge[],
+  options: LayoutWorkerOptions
+): Map<string, WorkerPosition> {


The comment states this is a 'simplified version that doesn't support clustering or DAG modes' but the function signature accepts options for clusterAttribute, clusterStrength, clusterType, mode, etc. These parameters should either be removed from the interface or the function should handle them gracefully with a warning when they're provided but not supported.

Copilot · 2026-01-02T16:31:30Z

src/utils/visibility.ts

 import type { PerspectiveCamera } from 'three';

-import type { EdgeLabelPosition } from '../symbols';
+import type { EdgeLabelPosition } from '../symbols/Edge';


The import path '../symbols/Edge' is changed to '../symbols/Edge.tsx' which includes the file extension. TypeScript/JavaScript imports typically omit the .tsx extension. Verify this doesn't cause module resolution issues.

Copilot · 2026-01-02T16:31:30Z

src/layout/layoutUtils.ts

+    async function run() {
      if (!stable) {
-        stable = layout.step();
-        run();
+        stable = await layout.step();
+        if (!stable) {
+          // Use requestAnimationFrame for better performance in async scenarios
+          requestAnimationFrame(run);
+        } else {
+          resolve(stable);
+        }
      } else {


The async function 'run' is defined but uses recursion which could cause stack overflow with deep recursion. Although requestAnimationFrame is used in the updated code, ensure the recursion depth is bounded for very slow layout convergence scenarios.

Copilot · 2026-01-02T16:31:31Z

src/symbols/nodes/useNodeInstancing.ts

+    /**
+     * Returns the current nodeIdToIndex map reference.
+     * Note: This returns the ref's current value. The map is mutated
+     * in-place by updateTransforms, so consumers should re-read this
+     * property after calling updateTransforms if they need fresh data.
+     */
+    get nodeIdToIndex() {
+      return nodeIdToIndexRef.current;
+    },


The nodeIdToIndex getter always returns the current value of the ref, but the comment on lines 224-228 mentions that consumers should 're-read this property after calling updateTransforms'. This is misleading since the getter always returns the current ref value. Consider clarifying the documentation or restructuring the API.

Copilot · 2026-01-02T16:31:31Z

stories/demos/WorkerLayout.story.tsx

@@ -0,0 +1,227 @@
+import React from 'react';
+import { GraphCanvas, LayoutTypes } from '../../src';


Unused import LayoutTypes.

ebassity · 2026-01-02T22:51:51Z

src/symbols/nodes/useNodeInstancing.ts

+    (nodes: InternalGraphNode[], defaultSize: number) => {
+      const idToIndex = new Map<string, number>();
+
+      for (let i = 0; i < nodes.length && i < maxCount; i++) {


i think we have a blocker here with silent data loss when node count exceeds maxCount - with the hardcoded 5000 limit in Nodes.tsx. so users with 6000+ node graphs will see incomplete visualizations with no indication why. unless it's super rare to ever have more than 5000?

below in line 139: mesh.count = Math.min(nodes.length, maxCount) - caps visible instance count.

ebassity · 2026-01-02T23:13:09Z

src/symbols/nodes/useNodeEvents.ts

+
+      // Update hovered state
+      hoveredNodeIdRef.current = currentHoveredId;
+      setHoveredNodeIds?.(currentHoveredId ? [currentHoveredId] : []);


cluster dragging seems to be broken for instanced sphere nodes here: this only sets hoveredNodeIds (plural) but never sets hoveredNodeId (singular). Cluster.tsx line 173 checks hoveredNodeId to disable cluster dragging while hovering nodes: draggable: draggable && !hoveredNodeId

since instanced sphere nodes never set hoveredNodeId, it stays null/undefined, so cluster dragging is not disabled when hovering sphere nodes. this looks correct for icon/custom/dragging nodes (which use the individual Node component that sets hoveredNodeId), but fails for the instanced/sphere node type.

also: may want to call setHoveredNodeId(currentHoveredId) alongside setHoveredNodeIds to maintain compatibility with existing cluster behavior.

@claude please address

ebassity

left a couple comments! also, i know it's not introduced in this PR, but in Edges.tsx line 260: previousDraggingId !== null is always true, causing dynamic geometry to rebuild every frame, and the intersecting.join() comparison (same file, line 284) collapses objects to [object Object],... making different edge sets with same counts indistinguishable - maybe should be fixed in a diff PR since the changeset here is already pretty large.

ebassity · 2026-01-02T23:18:53Z

src/symbols/edges/useEdgeAnimations.ts

+    // Update mesh geometry
+    const meshGeometry = meshRef.current?.geometry;
+    if (meshGeometry) {
+      const newPosition = new BufferAttribute(new Float32Array(current), 3);


this may cause memory churn for large graphs, but i don't really know how common it is to have very large graphs. we may want to reuse a single BufferAttribute and update its data in place.

@claude - please address

ebassity · 2026-01-03T02:09:27Z

src/useGraph.ts


+  // Worker layout support
+  const workerEnabled = webWorkers && supportsWebWorkers();
+  const { calculateLayout: workerCalculateLayout } = useLayoutWorker();


do we want to always create a worker even if webWorkers is false? maybe pass that as a flag to useLayoutWorker and create when true only?

ebassity · 2026-01-03T02:39:03Z

src/layout/layoutUtils.ts

 */
 export function tick(layout: LayoutStrategy) {
-  return new Promise((resolve, _reject) => {
+  return new Promise(async (resolve, _reject) => {


antipattern here, should be synchronous ... if layout.step() below throws, errors may no be caught properly and unhandled promise rejections can crash node (or show console errors/warnings at the very least)

- Fix cluster dragging bug: use setHoveredNodeId (singular) instead of setHoveredNodeIds for compatibility with Cluster.tsx drag-disable logic - Fix silent data loss: add maxNodeCount prop (default: 10000) with console.warn when node count exceeds limit - Expose maxNodeCount prop through GraphScene.tsx - Remove unused hoveredNodeIds state from store 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

SerhiiTsybulskyi · 2026-01-05T07:53:22Z

I made a quick check of functionality and noticed several issues:

Selection by click doesn't work (single, multi, lasso)
Context menu doesn't work
Node dragging doesn't work
Edges display over the node (story)
Nodes in the heap if workers are used (story)
Nodes disappear when zooming in (story)
Edges are animated, but nodes aren't

Screen.Recording.2026-01-05.at.09.34.27.mov

amcdnl and others added 6 commits December 30, 2025 11:55

update ignore

cff759d

improve layout

e639cdb

good baseline

c44a82d

ignore nul

f9f8264

Copilot AI review requested due to automatic review settings January 2, 2026 16:27

Copilot started reviewing on behalf of amcdnl January 2, 2026 16:27 View session

Copilot AI reviewed Jan 2, 2026

View reviewed changes

ebassity reviewed Jan 2, 2026

View reviewed changes

ebassity requested changes Jan 2, 2026

View reviewed changes

ebassity reviewed Jan 2, 2026

View reviewed changes

ebassity reviewed Jan 3, 2026

View reviewed changes

		// Avoid duplicate edges
		if (!edges.find(e => e.id === edgeId)) {

		// Note: We can't import forceRadial and forceInABox here as they have complex dependencies
		// that don't work in the worker context. For now, we use a simplified force layout.

-// Note: We can't import forceRadial and forceInABox here as they have complex dependencies
-// that don't work in the worker context. For now, we use a simplified force layout.
+// Note: We can't import forceRadial and forceInABox here as they pull in dependencies that
+// rely on main-thread-only features (e.g., DOM/window access and side-effectful module imports),
+// which are not available in the Web Worker context. For now, we use a simplified force layout.

		@@ -0,0 +1,227 @@
		import React from 'react';
		import { GraphCanvas, LayoutTypes } from '../../src';

Uh oh!

Performance Refactors #396

Are you sure you want to change the base?

Performance Refactors #396

Uh oh!

Conversation

amcdnl commented Jan 2, 2026

Uh oh!

cloudflare-workers-and-pages bot commented Jan 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying reagraph-storybook with Cloudflare Pages

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 2, 2026

Choose a reason for hiding this comment

Uh oh!

ebassity Jan 2, 2026

Choose a reason for hiding this comment

Uh oh!

ebassity Jan 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amcdnl Jan 3, 2026

Choose a reason for hiding this comment

Uh oh!

ebassity left a comment

Choose a reason for hiding this comment

Uh oh!

ebassity Jan 2, 2026

Choose a reason for hiding this comment

Uh oh!

amcdnl Jan 3, 2026

Choose a reason for hiding this comment

Uh oh!

ebassity Jan 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ebassity Jan 3, 2026

Choose a reason for hiding this comment

Uh oh!

SerhiiTsybulskyi commented Jan 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

cloudflare-workers-and-pages bot commented Jan 2, 2026 •

edited

Loading

ebassity Jan 2, 2026 •

edited

Loading

ebassity Jan 3, 2026 •

edited

Loading