feat(map): satellite and hybrid imagery — open sources, per-cell archives in R2, the style hook (nothing published)

[NateIsern]

Satellite and hybrid maps for GoWay, built only from imagery whose licence allows hosting, re-serving and displaying publicly and commercially. Each source is credited while it is on screen. Nothing is published: the Worker route is off until MAP_SATELLITE_MANIFEST is set, and no R2 object or Cloudflare token was created. Full write-up: docs/MAP_SATELLITE.md.

Phase 1: sources (licences quoted with URLs in the doc)

• Global base (chosen):
  • z8–13: ESA WorldCover 2021, the Sentinel-2 yearly median at 10 m, CC BY 4.0. It sits on AWS Open Data (9.18 TB, public).
  • z0–7: NASA Blue Marble NG, August 2004, public domain.
• Rejected for the base:
  • EOX cloudless 2018–2025 is CC BY-NC-SA. The 2016 edition is CC BY but has no bulk download.
  • Landsat is 30 m.
  • The upgrade path is CDSE quarterly mosaics or our own Sentinel-2 composite built in us-west-2, at about $300–600 a year.
• National and regional, usable:
  • Spain PNOA (COG per sheet), Catalonia ICGC (yearly), France BD ORTHO (Etalab).
  • Netherlands, Switzerland, Austria, 15 German states, Czechia, Poland, Denmark, Wallonia, Brussels, Luxembourg.
  • US NAIP (public domain), New Zealand LINZ (S3), Massachusetts, North Carolina, NYC, DC, Québec, Hong Kong, São Paulo.
• Ask the publisher first: Japan GSI (no bulk download), Flanders, Portugal OrtoSat, Ontario, Uruguay.
• No: Italy (AGEA), Ireland, Norway, UK national, Mecklenburg-Vorpommern, most Australian states, Google, Apple, Bing, Esri, Mapbox, Maxar, Planet.

Phase 2: pipeline and serving, proven on Catalonia

• Tiers: base z0–13, detail z12–18, fine z19–20. Each tier is one raster layer, and tiles are 512 px WebP with alpha.
• Cells: each set is cut into cells, one dated PMTiles archive per cell plus a receipt. The manifest lists each set's cells as a coverage tree, so the Worker computes the archive for a tile instead of looking it up.
• Worker /map/satellite/*:
  • Per tile, the first set in priority order that has the tile answers. A 404 means the tier below shows through.
  • It reads through tiles.js, the shared directory memo from Worker: send tiles gzipped as stored, one storage read per tile #192.
  • WebP goes out exactly as stored, with no Content-Encoding. check:worker-wire now proves this in workerd: four clients, cache miss and hit.
  • The parsed manifest has its own 1 MiB line in budget.js, and the parse refuses a manifest larger than that.
• Encoding, measured: WebP q80 gives 63 KB a tile at 36.0 dB. AVIF is 9–17% smaller but 64% slower to encode, and it doesn't decode on Android before 12 or iOS before 16. WebP chosen.
• Styles, in feat(map): one style engine — Standard, Streets, Light and Dark, in day, dawn, dusk and night, with a layers picker #197's one style engine: satellite and hybrid are catalogue entries with one fixed day light and their own themes.ts recipes. buildGowayMapStyle applies applyImageryStyle, and the imagery rasters join the published layer ids.
  • Hybrid keeps roads (thinned), boundaries and labels with dark halos.
  • No 3D buildings over imagery: the orthophotos are not true orthophotos. 3D terrain drapes the imagery, with no hillshade.
  • Picker thumbnails are rendered from the Catalonia proof. The two styles are labelled in all 12 languages.
  • Both carry offer: 'development': the picker and /frame?style= offer them only in development builds until the imagery is published. Publishing is then a one-line removal.
  • There is no parallel prop, registry or URL. Light, dark and every other document are unchanged except the id list in their metadata.
• Water: WorldCover's water is made transparent with a VRT mask band (NDWI > 0 and NIR < 0.08). Coasts then meet the style's ocean without the stepped edge the composite's own water mask drew. A NIR-only threshold left speckles at sea, and NDWI alone punched holes in blue and white port roofs; the combined rule avoids both.
• Credit: useImageryCredits reads /map/satellite/coverage.json. The compact ⓘ credit names every source on screen, and /attribution#imagery quotes each notice in full. A pitched view whose bounds can't be read over-credits rather than under-credits.
• Workflow: build-satellite-tiles.yml dry-runs by default. With publish, it uploads dated keys through city-r2.sh, which is now prefix-generic.

Local proof:

Set	Result
Blue Marble z0–7	104 MB
WorldCover z8–13 over Catalonia	9 cells, 176 MB
ICGC 2025 z13–18 over central Barcelona	13 cells, 15,253 tiles, 774 MB

Each cell is verified byte for byte. It was served by serve-map-build.ts --satellite running the Worker's own module. Screenshots satellite-01…09 are in goway-videos/.

Costs

• Base for the whole planet: about 0.86 TB, about $13 a month on R2. Builds run on free runners, about 1,300 runner-hours.
• ICGC for all of Catalonia: about 106–257 GB, $1.6–3.9 a month, about 54 runner-hours.
• Base + Spain + France: about 4.6–10 TB, $69–150 a month.
• All 16 ranked sources: about 18–42 TB, $260–630 a month.
• R2 egress is free. Publish commands are in the doc.

Decisions for the owner

1. Approve publishing the base set.
2. Pick the upload path: wrangler's 300 MiB per object, or an R2 access key for multipart. I created no key.
3. Pick Catalonia's source. ICGC's server stopped answering this machine after a parallel read burst. Recommended: PNOA's per-sheet COGs for Spain now, and ICGC's yearly set from a whole-file download later.
4. Decide on z19 for the 5–12 cm sources (4× the bytes).
5. Licences to ask the publishers about: GSI, Flanders, OrtoSat, Ontario, Uruguay.
6. 3D buildings over imagery: off for now; decide whether to add them.
7. After publishing, remove offer: 'development' from the two catalogue entries.

Checks

Check	Result
Frontend tests	1,748 pass
check:worker-wire	pass
tsc / bun check	pass
Biome / ESLint	pass
map:style:check	pass
validate:agents-md	pass

frameBudget's terrain case is flaky under machine load. It has also failed on clean main.

🤖 Generated with Claude Code