Add coverage LOD tile prefetching

[charlieforward9]

lod+priority.mov

Summary

This PR improves TileLayer/TerrainLayer transition behavior by giving Tileset2D an opt-in coverage LOD strategy and making request priority focus on the viewport center.

• Adds lodStrategy: 'coverage' to prefetch lower-resolution ancestor tiles while the selected high-resolution tiles load.
• Keeps selected/visible tiles ahead of LOD prefetch, with priority based on projected tile footprint coverage of the viewport center instead of tile-center distance alone.
• Preserves existing behavior by default with lodStrategy: 'none'.
• Forwards the strategy through TileLayer and TerrainLayer so terrain can use the lower-level tile loading behavior.
• Adds a side-by-side website demo for screen recording and visual validation.

Why

During animated transitions, especially on pitched/globe terrain views, high-resolution target tiles can leave black gaps while requests are saturated. The new strategy keeps coarse coverage available and then prioritizes the tiles nearest the focal point so the visible transition resolves more cleanly.

Validation

• npx vitest run --project headless test/modules/geo-layers/tileset-2d/tileset-2d.spec.ts test/modules/geo-layers/tileset-2d/tile-2d-header.spec.ts
• Pre-commit lint/prettier/test hook
• Local visual demo: examples/website/tile-priority-demo at http://127.0.0.1:8094/

---

Note

Medium Risk
Touches core Tileset2D loading/prioritization and cache eviction logic, which can affect performance and tile loading order across all TileLayer/TerrainLayer users; behavior is opt-in via lodStrategy with default preserved.

Overview
Adds an opt-in lodStrategy to TileLayer/TerrainLayer that enables coverage LOD prefetching: when set to 'coverage', Tileset2D now prefetches lower-zoom ancestor tiles (tracked via new tile.isPrefetch) to provide quick fallback coverage during viewport transitions.

Updates the internal request scheduler integration to accept a per-tile priority function and implements viewport-center weighted request prioritization (selected/visible tiles first, then prefetch tiles), plus adjusts request pruning and cache eviction to avoid aborting/evicting prefetch tiles prematurely.

Adds docs for lodStrategy, new unit tests covering prefetch + priority ordering, and a side-by-side website demo (examples/website/tile-priority-demo) to visually compare legacy vs new behavior.

^{Reviewed by Cursor Bugbot for commit 4be9e53. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coveralls]

coverage: 83.402% (-0.03%) from 83.434% — 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.

[chrisgervang]

before/after comparison demos may be better suited as a test app rather than a website example, since website examples are typically reserved for large new features. Would you be open to moving this to test/apps/?

[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.}