# Earth High Resolution Basemap Tiles Plan

## Summary

High-precision borders now expose a separate visual problem: the vector coastline and border data are more accurate than the current raster Earth texture. The next step is a high-resolution basemap tile layer that aligns visually with the high-precision coastline instead of replacing the globe with one huge static image.

Do not solve this by committing a larger single world texture. A single 16K/32K raster still wastes memory, loads slowly, and becomes blurry or misaligned when zooming into coastal detail. The target architecture is viewport-based raster tiles with cache control, similar to terrain tiles.

## Goals

- Render a high-resolution Earth imagery basemap that visually matches the high-precision coastline and country boundary layer.
- Load imagery by visible bbox / tile key instead of loading a whole-world giant texture.
- Keep the current global texture only as a low-zoom background, not as the source of truth for coastlines at inspection zoom.
- Let imagery failures degrade only the imagery layer; high-precision borders and hover must continue working.
- Keep generated imagery cache out of Git.

## Data Sources

Candidate sources, in recommended order:

- NASA GIBS / Blue Marble / VIIRS style imagery for permissive global coverage and stable tile service behavior.
- Sentinel-2 cloudless style public imagery if licensing and tile access are acceptable.
- A self-hosted raster pyramid generated offline from audited global imagery if third-party online tile terms are unsuitable.

The selected source must document:

- license / attribution
- max zoom and native resolution
- tile matrix / projection
- cache policy
- whether commercial or public deployment is allowed

## Architecture

```text
global low-zoom texture
→ visible Earth bbox from camera raycast
→ Web Mercator tile keys by zoom
→ raster tile fetch/cache
→ project tile image patches onto Earth surface
→ high-precision coastline / border layer remains above imagery
```

Implementation should mirror the existing terrain tile discipline:

- dedupe in-flight requests
- LRU cache for decoded images / textures
- debounce camera movement
- cancel or ignore stale viewport requests
- cap max tiles per frame / per view
- expose loading/error diagnostics

## Rendering Rules

- The high-resolution imagery layer is visual only. It must not define country hover, coastline, or border geometry.
- The high-precision coastline remains the visual alignment reference.
- The border layer render order stays above the basemap imagery.
- Low zoom may use the current global texture for speed.
- Mid/high zoom overlays imagery tiles only for the visible region plus a small prefetch ring.
- Do not draw decorative gradients or fake coastlines to hide mismatch.

## Frontend Work

- Add a new `basemap-imagery.js` module instead of expanding `country-boundaries.js`.
- Add config in `constants.js`:
  - source URL template
  - attribution
  - min/max zoom
  - tile cache limit
  - debounce interval
  - opacity
  - enable/disable setting
- Add Earth settings control:
  - `高清底图`: off / auto / on
  - default `auto`
- Add debug counters for:
  - active tile count
  - cached tile count
  - failed tile count
  - current imagery zoom

## Backend / Ops Work

- If using a third-party tile service directly, document attribution and rate-limit behavior.
- If proxying tiles, add backend cache with request coalescing and timeout limits.
- If self-hosting, add an offline builder that writes ignored tile artifacts under a dedicated data directory.
- Update Nginx static serving if self-hosted raster tiles are used.

## Performance Budget

- Desktop target: keep visible imagery tiles under a configurable cap, initially 64.
- Mobile target: lower max zoom and tile cap by default.
- Decode and upload textures incrementally; avoid blocking Earth startup on high-resolution imagery.
- First Earth paint must still use the existing lightweight global texture.

## Verification

- Compare high-precision coastline against imagery in coastal areas such as southeast China, Taiwan, Hainan, the Korean peninsula, Japan, and island chains in the South China Sea.
- Verify zooming / panning does not create visible tile thrash or long blank periods.
- Verify failed imagery requests do not hide borders or break hover.
- Verify memory stabilizes after repeated pan/zoom due to LRU eviction.
- Run `/home/ray/.bun/bin/bun run build`.

## User Operation Steps

After implementation, the user should be able to:

1. Open Earth settings.
2. Set `高清底图` to `auto` or `on`.
3. Open Earth and zoom into a coastline.
4. See imagery tiles refine under the high-precision boundary/coastline layer.
5. Use diagnostics to confirm which imagery zoom and tile source are active.

## Assumptions

- The existing high-precision vector coastline is the alignment reference.
- This plan improves visual texture fidelity; it does not replace the boundary data pipeline.
- A single larger static Earth texture is rejected as the primary solution.