Handle tile availaibility at zoom levels #44

New issue

Closed

opened 2026-03-29 06:58:13 +00:00 by maxtkc · 0 comments

maxtkc commented

2026-03-29 06:58:13 +00:00

Owner

Summary

When the user zooms in past the max tile zoom for a basemap (most visibly with Esri satellite imagery, which tops out around zoom 19 in most areas), MapLibre requests tiles that don't exist and the map goes blank or shows grey tiles. The fix is to add maxzoom to each raster source definition so MapLibre knows to overzoom-scale the highest available tile rather than requesting nonexistent ones. This is a one-line change per source with well-known values for each provider.

We also change the satellite button icon from a globe to a tree, since the globe SVG is already used by the projection toggle button and having two globe icons in the basemap control is confusing.

Relevant context

src/modules/basemap-styles.ts — defines all six BasemapStyle entries with their MapLibre style specs. Each has a single raster source. The maxzoom property on a raster source tells MapLibre "use overzoom past this level" — it will render higher zooms using scaled-up tiles from maxzoom, not blank tiles.
src/modules/map-controller.ts lines 218–237 — the initial OSM style defined inline during map construction also lacks maxzoom. This is what renders on first load before any basemap switch.
src/modules/basemap-control.ts line 42 — the satellite entry's icon field is the globe SVG, which conflicts with the projection toggle's globe icon (line 196).
No other files need changes.

maxzoom values by provider:

Source	Max zoom
OSM Standard (`tile.openstreetmap.org`)	19
Esri World Imagery (satellite)	19
Stadia/Stamen Toner Lite	20
Stadia/Stamen Toner (dark)	20
Stadia/Stamen Watercolor	16
Esri World Topo	19

Phase 1: Add maxzoom to all raster sources + change satellite icon

Goal: Fix the blank-tile problem for all basemaps and fix the icon ambiguity in one pass, since both changes touch basemap-styles.ts.

In src/modules/basemap-styles.ts, add maxzoom to each raster source:
- standard OSM source: maxzoom: 19
- satellite Esri source: maxzoom: 19
- stamen-light Stadia source: maxzoom: 20
- stamen-dark Stadia source: maxzoom: 20
- stamen-watercolor Stadia source: maxzoom: 16
- topo Esri source: maxzoom: 19

In src/modules/basemap-styles.ts, replace the satellite entry's icon globe SVG with a tree SVG (Heroicons outline style, class="w-6 h-6", stroke-width="1.5"):

<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" class="w-6 h-6">
  <path stroke-linecap="round" stroke-linejoin="round" d="M12 3 7 10h3.5L6 17h5v4h2v-4h5l-4.5-7H17L12 3z" />
</svg>

In src/modules/map-controller.ts (the inline initial style, lines ~221–226), add maxzoom: 19 to the OSM source.

Gotcha: maxzoom on a raster source is distinct from maxzoom on a layer. Set it on the source object (sources.osm, sources.satellite, etc.), not on the layer entry.

Original Issue

Tiles are not available when you zoom in too tight with satellite. We should handle the problem better.

## Summary When the user zooms in past the max tile zoom for a basemap (most visibly with Esri satellite imagery, which tops out around zoom 19 in most areas), MapLibre requests tiles that don't exist and the map goes blank or shows grey tiles. The fix is to add `maxzoom` to each raster source definition so MapLibre knows to overzoom-scale the highest available tile rather than requesting nonexistent ones. This is a one-line change per source with well-known values for each provider. We also change the satellite button icon from a globe to a tree, since the globe SVG is already used by the projection toggle button and having two globe icons in the basemap control is confusing. ## Relevant context - **`src/modules/basemap-styles.ts`** — defines all six `BasemapStyle` entries with their MapLibre style specs. Each has a single raster source. The `maxzoom` property on a raster source tells MapLibre "use overzoom past this level" — it will render higher zooms using scaled-up tiles from `maxzoom`, not blank tiles. - **`src/modules/map-controller.ts`** lines 218–237 — the initial OSM style defined inline during map construction also lacks `maxzoom`. This is what renders on first load before any basemap switch. - **`src/modules/basemap-control.ts`** line 42 — the satellite entry's `icon` field is the globe SVG, which conflicts with the projection toggle's globe icon (line 196). - No other files need changes. **`maxzoom` values by provider:** | Source | Max zoom | |--------|----------| | OSM Standard (`tile.openstreetmap.org`) | 19 | | Esri World Imagery (satellite) | 19 | | Stadia/Stamen Toner Lite | 20 | | Stadia/Stamen Toner (dark) | 20 | | Stadia/Stamen Watercolor | 16 | | Esri World Topo | 19 | --- ## Phase 1: Add maxzoom to all raster sources + change satellite icon **Goal**: Fix the blank-tile problem for all basemaps and fix the icon ambiguity in one pass, since both changes touch `basemap-styles.ts`. - [x] In `src/modules/basemap-styles.ts`, add `maxzoom` to each raster source: - `standard` OSM source: `maxzoom: 19` - `satellite` Esri source: `maxzoom: 19` - `stamen-light` Stadia source: `maxzoom: 20` - `stamen-dark` Stadia source: `maxzoom: 20` - `stamen-watercolor` Stadia source: `maxzoom: 16` - `topo` Esri source: `maxzoom: 19` - [x] In `src/modules/basemap-styles.ts`, replace the satellite entry's `icon` globe SVG with a tree SVG (Heroicons outline style, `class="w-6 h-6"`, `stroke-width="1.5"`): ```html <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" class="w-6 h-6"> <path stroke-linecap="round" stroke-linejoin="round" d="M12 3 7 10h3.5L6 17h5v4h2v-4h5l-4.5-7H17L12 3z" /> </svg> ``` - [x] In `src/modules/map-controller.ts` (the inline initial style, lines ~221–226), add `maxzoom: 19` to the OSM source. **Gotcha**: `maxzoom` on a raster source is distinct from `maxzoom` on a layer. Set it on the source object (`sources.osm`, `sources.satellite`, etc.), not on the layer entry. --- ## Original Issue Tiles are not available when you zoom in too tight with satellite. We should handle the problem better.