[draedful]

Experiment. An alternative implementation of tree-native viewport culling, built on top of #428 to compare the two on the preview stand. It is not meant to be merged as is.

Only the difference from #428: experiment/tile-visibility-culling...claude/culling-redesign (two commits: 75455305 makes #428's visibility incremental, d25cb4ec is the redesign). The branch is not merged with the two newest v2 commits (#424, #425), so that this comparison stays clean.

Why

#428 is fast when zoomed in but slower than v2 when zoomed out (scales 0.01–0.03), most of all on connection-heavy scenes such as Nirvana Max Graph, and on the first frames after mounting. The costs that grew with the number of visible nodes:

• a separate prepare pass for every visible clean node;
• an O(N) selection and publication every frame;
• a binary switch between sparse and dense traversal;
• a Map and sort based painter;
• updatePoints running three times per connection on mount.

Behavior and architecture

Each culled layer root has one TreeCulling coordinator that runs a frame in three steps:

1. Prepare. The owner, new nodes and nodes that requested an update call prepareUpdate(), ancestors first. Clean nodes are not touched.
2. Publish visibility. It is kept between frames. A camera move rechecks only nodes in the strips between the old and new viewports, plus nodes with changed bounds. A full selection runs only after a structural change; when the viewport covers the whole index, every eligible node is visible without a query. Bounds reach the TileIndex once per frame, right before publication.
3. Paint. One flat pass over the cached local paint order calls iterate(prepared, visible) only for visible and already prepared nodes. A clean visible node applies its own pending work inside iterate(). Clean offscreen nodes get no call; their visible descendants are still reached through them.

A frame therefore costs the visible nodes plus the work that changed.

• Contract. The tree decides spatial visibility and passes it to iterate(). A component can only veto painting through isRenderAllowed() (hidden blocks, connections without geometry). isVisible() combines that veto with isInViewport() for queries.
• Bookkeeping. The coordinator's node sets are arrays indexed by slots stored on the nodes, with no hashing. The paint order also marks the eligible nodes, so publication does not call isEligible() per node. Tree.setChildren() with unchanged children no longer invalidates the scope. Before this, Block.updateChildren() returned a new anchor array on every update and rebuilt the whole scope's structure, including on every drag frame.
• Connections. Batches keep v2's chunks: up to 100 items in registration order, so overlap blending is identical to v2. A chunk whose bounds lie outside the viewport is skipped. Camera moves never rebuild chunk paths. Connections cache their line and arrow paths, and labels skip themselves through isInViewport() in afterRender.

Internal API changes

Compatibility of Tree and Component internals was intentionally not preserved. What to restore, and how, is to be discussed separately.

• ITree.iterate(prepared, visible); the tree and scheduler iterator is (node, prepared, visible).
• Removed: onViewportChange, isSkippedByCulling, the getWalkToken option, preparesOnIterate, invalidateVisibility, getChildrenArray, activeInViewport, Tree.setVisible.
• Components override isRenderAllowed() instead of isVisible() to veto painting.
• Batch items return cached geometry from getPath(). New: BlockConnection.getArrowPath(), batch.markBoundsDirty(item). A chunk containing an item without getPathBounds() is never culled.

Results

GraphLayer scheduler.update time, ms, measured with scripts/bench/culling (headless Chromium, ANGLE Metal, Apple Silicon, DPR 2). Both versions run the same zoom history before measuring, and screenshots are compared after the camera moves.

Panning, near view (1600×1000):

Scale	Nirvana v2	Nirvana this PR	Playground v2	Playground this PR
0.01	13.3	11.4	22.8	21.5
0.02	12.9	10.6	19.4	16.1
0.05	10.4	5.0	13.2	7.1
0.1	8.6	2.3	10.3	2.3
0.2	8.5	1.9	9.6	1.5

Zooming and the full view (1600×1600) follow the same pattern.

First two frames after mounting, scale 0.01:

• Nirvana: on par with v2 (±2–3% between runs).
• Playground: still +5…+11% (for example 416 vs 374 ms); 0–5% at scales 0.1–0.2. The remaining cost is a few extra passes over ~38k nodes while the code is not yet optimized by the JIT: indexing, publication, paint-order build and registration.

Screenshots match v2 at every measured point. At scale 0.01, GPU rasterization varies by a few grey levels between page loads, even for the same version; the benchmark reports the largest per-channel difference to tell this noise from culling errors.

Benchmark

node scripts/bench/culling/run.mjs --variants base=origin/v2,current=. --scales 0.01,0.02,0.05,0.1
node scripts/bench/culling/run.mjs --variants pr428=origin/experiment/tile-visibility-culling,current=. --first --repeats 12

Scenes, options and caveats are described in scripts/bench/culling/README.md.

Not verified

• Tests and typecheck of the other packages (graph-react, devtools and so on), and e2e. packages/graph typecheck, lint and all 569 tests pass.
• Scenes with connection labels turned on.
• Browsers and hardware other than Chromium with Metal on Apple Silicon.
• Manual checks in Storybook.

🤖 Generated with Claude Code

[gravity-ui-bot]

Preview is ready.