feat(geo-layers): coverage LOD tile prefetching

[charlieforward9]

lod_strategy_comparison.mov

Summary

Adds opt-in coverage LOD prefetching for TileLayer/TerrainLayer so animated transitions can keep coarse coverage available while high-resolution target tiles load.

Why

During fast camera transitions, high-resolution requests can saturate the queue and leave temporary blank coverage. Prefetching ancestor tiles gives the viewport useful lower-resolution coverage, then lets sharper selected tiles replace it as they arrive.

Change

• Adds lodStrategy: 'coverage' with existing behavior preserved by default as lodStrategy: 'none'.
• Marks lower-resolution ancestor tiles as prefetch tiles and protects useful prefetch requests from premature abort/eviction.
• Keeps internal request tiers simple for this PR: selected tiles, visible placeholders, then prefetch tiles.
• Stabilizes coverage + best-available refinement so pending tiles use immediate child placeholders over coarse ancestors, while stale deeper placeholders are capped during zoom-out.
• Forwards the strategy through TileLayer and TerrainLayer.
• Adds API docs, focused unit coverage, and a before/after LOD comparison app at test/apps/lod-strategy-demo.

Validation

• yarn: passed; no yarn.lock change
• yarn test-headless test/modules/geo-layers/tileset-2d/tile-2d-header.spec.ts test/modules/geo-layers/tileset-2d/tileset-2d.spec.ts: passed (27 tests)
• yarn lint: passed with existing repo-wide warnings
• yarn build: failed in modules/react with existing/base @deck.gl/widgets module resolution errors
• Demo smoke: test/apps/lod-strategy-demo served successfully at http://127.0.0.1:5174/ and returned HTTP 200 when run with the repo root node_modules/.bin on PATH

Split Notes

The center-priority/default request ordering and public getPriority accessor were moved to the independent PR #10364. This PR is now scoped to lodStrategy coverage prefetching only.

[coveralls]

coverage: 83.437% (+0.05%) from 83.386% — codex/tile-priority-on-master-demo into master

[chrisgervang]

There are a couple of interesting things in the demo that I'm not really sure how to improve:

1. As the low-resolution tiles are loading in and the high-resolution tiles are loading on top, I can see almost like a parallax or perspective shift between the low-res and high-res tiles. I'm curious what the root cause of that is.
2. I see a lot of z-fighting as we zoom into the final destination in New York between the low-res and high-res tiles. There's a lot of z-fighting in the before as well, so this isn't a regression and more a limitation with our renderer

I wrote a draft of docs for this that I'll push up for you to review.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 4be9e53. Configure here.}

[cursor]

Unprojectable tiles break priority tier boundaries

Medium Severity

_getTileDistanceSquared returns Number.MAX_SAFE_INTEGER (~9e15) when a tile's bounding box can't be fully projected (fewer than 4 finite screen corners or a caught exception). This value, when added to SELECTED_TILE_PRIORITY (0), produces a priority of ~9e15, far exceeding PREFETCH_TILE_PRIORITY (~4.2e9 max). Since lower priority values load first, an unprojectable selected tile loads after all prefetch and visible tiles, violating the intended tier system. This is particularly likely in pitched globe views—exactly the target use case—where horizon tiles may not project cleanly.

Additional Locations (1)

• modules/geo-layers/src/tileset-2d/tileset-2d.ts#L458-L474

 

^{Reviewed by Cursor Bugbot for commit 4be9e53. Configure here.}

[charlieforward9]

@chrisgervang

I can see almost like a parallax or perspective shift ... what the root cause of that is.

Almost certain this is a GlobeView or globe-projection issue - due to the way the TileLayer are projected at different resolutions. This is something that I want to address asap. But feels like this could land before polishing the projection?

I see a lot of z-fighting as we zoom into the final destination

Yeah it resolves ever-so-slightly faster in the new strategy due to the center priority, but its nowhere near as bad when testing with the TerrainLayer.