perf: virtualize vue nodes outside the viewport

GraphCanvas rendered every node in the graph, so a large workflow paid
full DOM cost for nodes nobody could see. Filter the v-for down to nodes
intersecting an expanded viewport rect.

Measured on a graph built by stamping the default workflow across empty
space, panning at a working zoom:

  8000 nodes: 1790ms -> 133ms median frame, 606k -> 5.3k DOM elements
  3000 nodes:  272ms ->  49ms median frame

Design notes:

- The mounted set is derived from a throttled sample of the camera, not a
  reactive dependency on it. TransformPane deliberately writes its
  transform via direct DOM mutation to avoid re-diffing every node each
  frame; binding the node list to the camera would reintroduce exactly
  that cost.
- Nodes mount as soon as they enter and unmount after a delay, so nodes
  oscillating on the viewport edge do not thrash. Because that delay only
  elapses once panning stops, a long continuous pan would otherwise
  accumulate everything swept over; an eager prune bounds the set once it
  outgrows what is visible.
- Selected nodes are never culled, so unmounting cannot interrupt a drag
  or resize in progress.
- Culls by unmounting, never by `display: none`. The shared ResizeObserver
  has no zero-size guard, so a hidden node would write 0x0 bounds back
  through layoutStore into `liteNode.size` and corrupt the saved workflow.

Note this does not help when the whole graph is on screen. `min_scale` is
0.1, but loadGraphData's fit-view bypasses that clamp, so a freshly
loaded large workflow starts fully visible with nothing to cull.

Author: benjcooley

src/components/graph/GraphCanvas.vue

@@ -158,6 +158,7 @@ import { useChainCallback } from '@/composables/functional/useChainCallback'
 import { useGroupContextMenu } from '@/composables/graph/useGroupContextMenu'
 import { installErrorClearingHooks } from '@/composables/graph/useErrorClearingHooks'
 import type { VueNodeData } from '@/composables/graph/useGraphNodeManager'
+import { useViewportCulling } from '@/composables/graph/useViewportCulling'
 import { useVueNodeLifecycle } from '@/composables/graph/useVueNodeLifecycle'
 import { useNodeBadge } from '@/composables/node/useNodeBadge'
 import { useCanvasDrop } from '@/composables/useCanvasDrop'
@@ -178,6 +179,7 @@ import { useWorkflowPersistenceV2 as useWorkflowPersistence } from '@/platform/w
 import { useCanvasStore } from '@/renderer/core/canvas/canvasStore'
 import { useCanvasInteractions } from '@/renderer/core/canvas/useCanvasInteractions'
 import { layoutStore } from '@/renderer/core/layout/store/layoutStore'
+import { createNodeCullingIndex } from '@/renderer/core/spatial/nodeCullingIndex'
 import TransformPane from '@/renderer/core/layout/transform/TransformPane.vue'
 import type { StartupOutcome } from '@/platform/workflow/persistence/base/draftTypes'
 import { useFirstRunEntry } from '@/renderer/extensions/firstRunTour/gettingStarted/firstRunEntry'
@@ -292,9 +294,53 @@ watch(
   }
 )
 
-const allNodes = computed((): VueNodeData[] =>
+const rawNodes = computed((): VueNodeData[] =>
   Array.from(vueNodeLifecycle.nodeManager.value?.vueNodeData?.values() ?? [])
 )
+
+// Bounds come from layoutStore rather than the litegraph nodes so they share a
+// source with layoutVersion; keying the cache on one and reading the other
+// would let it hold stale bounds indefinitely.
+const cullingIndex = createNodeCullingIndex({
+  getVersion: () => layoutStore.layoutVersion,
+  getEntries: () => {
+    const layouts = layoutStore.getAllNodes().value
+    return rawNodes.value.map((node) => {
+      const layout = layouts.get(node.id)
+      if (!layout) return { id: node.id, bounds: null }
+
+      // Vue nodes render their title above the stored position.
+      return {
+        id: node.id,
+        bounds: {
+          x: layout.position.x,
+          y: layout.position.y - LiteGraph.NODE_TITLE_HEIGHT,
+          width: layout.size.width,
+          height: layout.size.height + LiteGraph.NODE_TITLE_HEIGHT
+        }
+      }
+    })
+  }
+})
+
+watch(rawNodes, () => cullingIndex.invalidate())
+
+const { mountedNodeIds } = useViewportCulling({
+  nodes: rawNodes,
+  queryNodesInBounds: (bounds) => cullingIndex.query(bounds),
+  getViewportSize: () => {
+    const element = comfyApp.canvas?.canvas
+    return {
+      width: element?.clientWidth ?? 0,
+      height: element?.clientHeight ?? 0
+    }
+  },
+  isPinned: (id) => canvasStore.selectedNodeIds.has(id)
+})
+
+const allNodes = computed((): VueNodeData[] =>
+  rawNodes.value.filter((node) => mountedNodeIds.value.has(node.id))
+)
 watch(
   () => linearMode.value,
   (isLinearMode) => {

src/composables/graph/useViewportCulling.test.ts

@@ -0,0 +1,172 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { computed, effectScope, nextTick, reactive, ref } from 'vue'
+
+import type { VueNodeData } from '@/composables/graph/useGraphNodeManager'
+import {
+  getCullingBounds,
+  useViewportCulling
+} from '@/composables/graph/useViewportCulling'
+import type { Bounds, NodeId } from '@/renderer/core/layout/types'
+import { boundsIntersect } from '@/renderer/core/layout/utils/layoutMath'
+
+const camera = reactive({ x: 0, y: 0, z: 1 })
+
+vi.mock('@/renderer/core/layout/transform/useTransformState', () => ({
+  useTransformState: () => ({ camera })
+}))
+
+function nodeData(id: string): VueNodeData {
+  return {
+    id: id as NodeId,
+    title: id,
+    type: 'test',
+    mode: 0,
+    selected: false,
+    executing: false
+  }
+}
+
+const VIEWPORT = { width: 1000, height: 1000 }
+
+/** Runs the culling composable inside a scope and exposes its reactive result. */
+function setup(
+  bounds: Record<string, Bounds | null>,
+  pinned: Set<string> = new Set()
+) {
+  const nodes = ref(Object.keys(bounds).map(nodeData))
+  const scope = effectScope()
+
+  // Plain scan stands in for the spatial index; the index has its own tests.
+  const queryNodesInBounds = (rect: Bounds) =>
+    nodes.value
+      .map((node) => node.id)
+      .filter((id) => {
+        const nodeBounds = bounds[id]
+        return !nodeBounds || boundsIntersect(nodeBounds, rect)
+      })
+
+  const mountedNodeIds = scope.run(
+    () =>
+      useViewportCulling({
+        nodes: computed(() => nodes.value),
+        queryNodesInBounds,
+        getViewportSize: () => VIEWPORT,
+        isPinned: (id) => pinned.has(id)
+      }).mountedNodeIds
+  )!
+
+  return { nodes, mountedNodeIds, scope }
+}
+
+beforeEach(() => {
+  vi.useFakeTimers()
+  Object.assign(camera, { x: 0, y: 0, z: 1 })
+})
+
+describe('getCullingBounds', () => {
+  it('expands the viewport by the margin ratio in graph space', () => {
+    expect(getCullingBounds({ x: 0, y: 0, z: 1 }, VIEWPORT, 0.5)).toEqual({
+      x: -500,
+      y: -500,
+      width: 2000,
+      height: 2000
+    })
+  })
+
+  it('accounts for pan offset and zoom', () => {
+    // At z=2 the viewport covers half as much graph space.
+    expect(getCullingBounds({ x: -100, y: -50, z: 2 }, VIEWPORT, 0)).toEqual({
+      x: 100,
+      y: 50,
+      width: 500,
+      height: 500
+    })
+  })
+})
+
+describe('useViewportCulling', () => {
+  it('mounts only nodes intersecting the expanded viewport', () => {
+    const { mountedNodeIds } = setup({
+      onscreen: { x: 0, y: 0, width: 100, height: 100 },
+      // Inside the 0.5 margin band, so still mounted.
+      margin: { x: 1200, y: 0, width: 100, height: 100 },
+      offscreen: { x: 50_000, y: 0, width: 100, height: 100 }
+    })
+
+    expect(mountedNodeIds.value).toEqual(
+      new Set(['onscreen', 'margin'] as NodeId[])
+    )
+  })
+
+  it('keeps pinned nodes mounted even when far off screen', () => {
+    const { mountedNodeIds } = setup(
+      { dragged: { x: 50_000, y: 0, width: 100, height: 100 } },
+      new Set(['dragged'])
+    )
+
+    expect(mountedNodeIds.value.has('dragged' as NodeId)).toBe(true)
+  })
+
+  it('mounts nodes that have no layout yet so they can measure themselves', () => {
+    const { mountedNodeIds } = setup({ unmeasured: null })
+
+    expect(mountedNodeIds.value.has('unmeasured' as NodeId)).toBe(true)
+  })
+
+  it('mounts entering nodes immediately but delays unmounting departing ones', async () => {
+    const { mountedNodeIds } = setup({
+      left: { x: -3000, y: 0, width: 100, height: 100 },
+      right: { x: 1000, y: 0, width: 100, height: 100 }
+    })
+
+    expect(mountedNodeIds.value).toEqual(new Set(['right'] as NodeId[]))
+
+    // Pan left so `left` enters and `right` leaves.
+    camera.x = 3000
+    await nextTick()
+
+    // Entering node is mounted right away; departing node lingers.
+    expect(mountedNodeIds.value).toEqual(new Set(['left', 'right'] as NodeId[]))
+
+    await vi.advanceTimersByTimeAsync(300)
+    expect(mountedNodeIds.value).toEqual(new Set(['left'] as NodeId[]))
+  })
+
+  it('does not accumulate nodes during a long continuous pan', async () => {
+    // A row of nodes the viewport sweeps across without ever pausing.
+    const NODE_COUNT = 60
+    const bounds = Object.fromEntries(
+      Array.from({ length: NODE_COUNT }, (_, i) => [
+        `n${i}`,
+        { x: i * 4000, y: 0, width: 100, height: 100 }
+      ])
+    )
+    const { mountedNodeIds } = setup(bounds)
+
+    for (let step = 0; step < NODE_COUNT; step++) {
+      camera.x = -step * 4000
+      await nextTick()
+      // Stay under the unmount delay so the debounced prune never runs.
+      await vi.advanceTimersByTimeAsync(120)
+    }
+
+    // Without eager pruning the mounted set would cover every node the
+    // viewport swept over.
+    expect(mountedNodeIds.value.size).toBeLessThan(NODE_COUNT / 3)
+  })
+
+  it('drops nodes removed from the graph', async () => {
+    const { nodes, mountedNodeIds } = setup({
+      a: { x: 0, y: 0, width: 100, height: 100 },
+      b: { x: 0, y: 0, width: 100, height: 100 }
+    })
+
+    expect(mountedNodeIds.value.size).toBe(2)
+
+    nodes.value = [nodeData('a')]
+    await nextTick()
+    await vi.advanceTimersByTimeAsync(300)
+
+    expect(mountedNodeIds.value).toEqual(new Set(['a'] as NodeId[]))
+  })
+})