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: 82.284% (+0.03%) from 82.25% — 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.}

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

[charlieforward9]

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

Willing to put this into the 9.4 release as a means of moving this forward without the risk of regression?

@chrisgervang

[charlieforward9]

@copilot resolver los conflictos de combinación en esta rama.

[Copilot]

@copilot resolver los conflictos de combinación en esta rama.

Merge conflicts resolved in 4f61a0b (initial merge) and fixed in the follow-up commit. The resolution:

• terrain-layer.ts: included both lodStrategy and zoomOffset in props destructuring
• tile-2d-header.ts: adopted getRequestPriority (master's rename)
• tileset-2d.ts: combined coverage LOD prefetch tiers with master's center-distance priority — selected/visible tiles now use viewport-center distance ordering within their tiers, and prefetch tiles remain in the third tier by zoom proximity
• Test files: kept both coverage LOD tests and the new center-priority tests from master

All 29 tests pass.

[greptile-apps]

Greptile Summary

Adds opt-in ancestor-tile prefetching to TileLayer and TerrainLayer to preserve coarse visual coverage while selected high-resolution tiles load.

• Introduces the coverage LOD strategy, prefetch request tiers, cache protection, and coverage-aware refinement.
• Forwards the strategy through public layer APIs and documents its intended use.
• Adds focused tileset tests and a side-by-side globe transition demo.

Confidence Score: 4/5

The implementation appears safe to merge, with a non-blocking reproducibility issue in the new demo package manifest.

The coverage-prefetch lifecycle, priority, and refinement paths have no accepted functional failure, but the new demo dependencies are not captured in the committed lockfile as required by repository guidance.

Files Needing Attention: test/apps/lod-strategy-demo/package.json

Important Files Changed

Filename	Overview
modules/geo-layers/src/tileset-2d/tileset-2d.ts	Implements coverage ancestor selection, request prioritization, eviction handling, and coverage-aware best-available refinement without an accepted behavioral defect.
modules/geo-layers/src/tile-layer/tile-layer.ts	Adds and forwards the public lodStrategy option with the existing behavior retained as the default.
modules/geo-layers/src/terrain-layer/terrain-layer.ts	Forwards TerrainLayer's lodStrategy into its internal tileset options.
test/modules/geo-layers/tileset-2d/tileset-2d.spec.ts	Adds focused tests for coverage selection, priority tiers, resolution floors, and placeholder refinement.
test/apps/lod-strategy-demo/package.json	Defines the new demo dependencies, but their resolutions are not represented by a corresponding lockfile update.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Viewport update] --> B[Select target tiles]
  B --> C{lodStrategy = coverage?}
  C -- No --> D[Request selected tiles]
  C -- Yes --> E[Find ancestor coverage tiles]
  E --> F[Request selected tiles first]
  F --> G[Request visible placeholders]
  G --> H[Request prefetch ancestors]
  H --> I{Selected tile loaded?}
  I -- No --> J[Render immediate children and nearest allowed ancestor]
  I -- Yes --> K[Render selected high-resolution tile]

Loading

_{Reviews (1): Last reviewed commit: "Merge remote-tracking branch 'upstream/m..." | Re-trigger Greptile}