perf: add node culling spatial index

Adds a position query for "which nodes intersect this rect", backed by a
QuadTree that is rebuilt only when layoutVersion changes. Panning over a
static graph then costs a tree query rather than a scan of every node.

Deliberately does not reuse the shared SpatialIndexManager. That index is
built on QUADTREE_CONFIG.DEFAULT_BOUNDS, a fixed +/-10000 box, and
QuadTree.insert silently drops anything not fully contained (its return
value is discarded, and update() cannot recover an item that was never
inserted). Real workflows outgrow that box - a graph built by stamping
the default workflow across empty space spans tens of thousands of units
on each axis - so most nodes would be missing from query results. This
index sizes its root to the graph's own extent instead.

Nodes with no layout yet cannot be indexed, so they are reported by every
query; callers must mount them in order for them to measure themselves.

Unused until the next commit wires it up, so the two can be reverted
independently.

Author: benjcooley

src/renderer/core/spatial/nodeCullingIndex.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from 'vitest'
+
+import type { Bounds, NodeId } from '@/renderer/core/layout/types'
+import type { CullingIndexEntry } from '@/renderer/core/spatial/nodeCullingIndex'
+import { createNodeCullingIndex } from '@/renderer/core/spatial/nodeCullingIndex'
+
+const id = (value: string) => value as NodeId
+
+function box(x: number, y: number, size = 100): Bounds {
+  return { x, y, width: size, height: size }
+}
+
+/** Index over a mutable entry list with an explicitly controlled version. */
+function setup(entries: CullingIndexEntry[]) {
+  const state = { entries, version: 1, builds: 0 }
+
+  const index = createNodeCullingIndex({
+    getVersion: () => state.version,
+    getEntries: () => {
+      state.builds++
+      return state.entries
+    }
+  })
+
+  return { index, state }
+}
+
+describe('createNodeCullingIndex', () => {
+  it('returns only nodes intersecting the query rect', () => {
+    const { index } = setup([
+      { id: id('near'), bounds: box(0, 0) },
+      { id: id('far'), bounds: box(50_000, 50_000) }
+    ])
+
+    expect(index.query(box(-10, -10, 500))).toEqual([id('near')])
+  })
+
+  it('indexes nodes far outside the shared quadtree bounds', () => {
+    // The shared QUADTREE_CONFIG root is a fixed +/-10000 box and silently
+    // drops anything outside it, so the index must size its own root.
+    const { index } = setup([
+      { id: id('distant'), bounds: box(250_000, -80_000) }
+    ])
+
+    expect(index.query(box(249_900, -80_100, 500))).toEqual([id('distant')])
+    expect(index.size).toBe(1)
+  })
+
+  it('always reports nodes that have no bounds yet', () => {
+    const { index } = setup([
+      { id: id('unmeasured'), bounds: null },
+      { id: id('far'), bounds: box(50_000, 50_000) }
+    ])
+
+    expect(index.query(box(0, 0, 10))).toEqual([id('unmeasured')])
+  })
+
+  it('reuses the tree while the version is unchanged', () => {
+    const { index, state } = setup([{ id: id('a'), bounds: box(0, 0) }])
+
+    index.query(box(0, 0, 10))
+    index.query(box(0, 0, 10))
+    index.query(box(0, 0, 10))
+
+    expect(state.builds).toBe(1)
+  })
+
+  it('rebuilds when the version changes', () => {
+    const { index, state } = setup([{ id: id('a'), bounds: box(0, 0) }])
+
+    expect(index.query(box(0, 0, 10))).toEqual([id('a')])
+
+    state.entries = [{ id: id('a'), bounds: box(40_000, 40_000) }]
+    state.version++
+
+    expect(index.query(box(0, 0, 10))).toEqual([])
+    expect(index.query(box(39_950, 39_950, 200))).toEqual([id('a')])
+    expect(state.builds).toBe(2)
+  })
+
+  it('rebuilds when explicitly invalidated', () => {
+    const { index, state } = setup([{ id: id('a'), bounds: box(0, 0) }])
+
+    index.query(box(0, 0, 10))
+
+    // Entry list changed without a version bump.
+    state.entries = [
+      { id: id('a'), bounds: box(0, 0) },
+      { id: id('b'), bounds: box(10, 10) }
+    ]
+    index.invalidate()
+
+    expect(index.query(box(0, 0, 200)).sort()).toEqual([id('a'), id('b')])
+  })
+
+  it('handles an empty graph', () => {
+    const { index } = setup([])
+
+    expect(index.query(box(0, 0, 100))).toEqual([])
+    expect(index.size).toBe(0)
+  })
+})

src/renderer/core/spatial/nodeCullingIndex.ts

@@ -0,0 +1,117 @@
+/**
+ * Spatial index for viewport culling.
+ *
+ * Holds a QuadTree of node bounds that is rebuilt only when the supplied
+ * version changes, so panning over a static graph costs a tree query rather
+ * than a full rescan of every node.
+ */
+import type { Bounds, NodeId } from '@/renderer/core/layout/types'
+
+import { QuadTree } from './QuadTree'
+
+/** Slack around the graph extent so nodes on the edge insert cleanly. */
+const ROOT_PADDING = 1000
+
+const QUAD_TREE_OPTIONS = {
+  maxDepth: 8,
+  maxItemsPerNode: 8
+} as const
+
+export interface CullingIndexEntry {
+  id: NodeId
+  /** Null while a node has no layout yet. */
+  bounds: Bounds | null
+}
+
+interface NodeCullingIndexOptions {
+  /**
+   * Changes whenever any node's position or size changes. Entries must be
+   * derived from the same source as this version, or the index can cache
+   * stale bounds indefinitely.
+   */
+  getVersion: () => number
+  getEntries: () => Iterable<CullingIndexEntry>
+}
+
+export function createNodeCullingIndex({
+  getVersion,
+  getEntries
+}: NodeCullingIndexOptions) {
+  let tree: QuadTree<NodeId> | null = null
+  let builtVersion: number | null = null
+  let built = false
+
+  /** Nodes with no bounds yet; they cannot be indexed, so always report them. */
+  let unpositioned: NodeId[] = []
+
+  function rebuild(): void {
+    const positioned: CullingIndexEntry[] = []
+    const pending: NodeId[] = []
+
+    let minX = Infinity
+    let minY = Infinity
+    let maxX = -Infinity
+    let maxY = -Infinity
+
+    for (const entry of getEntries()) {
+      const { bounds } = entry
+      if (!bounds) {
+        pending.push(entry.id)
+        continue
+      }
+      positioned.push(entry)
+      if (bounds.x < minX) minX = bounds.x
+      if (bounds.y < minY) minY = bounds.y
+      if (bounds.x + bounds.width > maxX) maxX = bounds.x + bounds.width
+      if (bounds.y + bounds.height > maxY) maxY = bounds.y + bounds.height
+    }
+
+    unpositioned = pending
+
+    if (positioned.length === 0) {
+      tree = null
+      return
+    }
+
+    // Size the root to the graph's own extent. QuadTree.insert drops anything
+    // not fully contained, and the shared QUADTREE_CONFIG bounds are a fixed
+    // +/-10000 box that real graphs outgrow.
+    const root: Bounds = {
+      x: minX - ROOT_PADDING,
+      y: minY - ROOT_PADDING,
+      width: maxX - minX + ROOT_PADDING * 2,
+      height: maxY - minY + ROOT_PADDING * 2
+    }
+
+    tree = new QuadTree<NodeId>(root, QUAD_TREE_OPTIONS)
+    for (const { id, bounds } of positioned) {
+      tree.insert(String(id), bounds!, id)
+    }
+  }
+
+  function ensureFresh(): void {
+    const version = getVersion()
+    if (built && builtVersion === version) return
+    rebuild()
+    builtVersion = version
+    built = true
+  }
+
+  return {
+    query(bounds: Bounds): NodeId[] {
+      ensureFresh()
+      const matches = tree ? tree.query(bounds) : []
+      return unpositioned.length ? matches.concat(unpositioned) : matches
+    },
+
+    /** Forces a rebuild on next query, for changes the version does not cover. */
+    invalidate(): void {
+      built = false
+    },
+
+    get size(): number {
+      ensureFresh()
+      return (tree?.size ?? 0) + unpositioned.length
+    }
+  }
+}