···11+# Map Layers
22+33+This document describes the different map layers used in the app and how they are ordered.
44+55+## Layer Stack (bottom to top)
66+77+### 1. World Basemap Layers (`world_layers.ts`)
88+99+Low-resolution global basemap for zoom levels 0-5. Loaded from PMTiles.
1010+1111+| Layer ID | Type | Source Layer | Description |
1212+| ------------------- | ------ | ------------ | ------------------------------------------- |
1313+| `water` | fill | water | Ocean and inland water polygons |
1414+| `landcover-grass` | fill | landcover | Grass areas |
1515+| `landcover-wood` | fill | landcover | Forest/woodland |
1616+| `landcover-wetland` | fill | landcover | Wetland |
1717+| `landcover-sand` | fill | landcover | Sand/desert |
1818+| `landcover-rock` | fill | landcover | Rocky areas |
1919+| `landcover-ice` | fill | landcover | Ice caps/glaciers |
2020+| `park` | fill | park | National parks/nature reserves |
2121+| `waterway` | line | waterway | Named rivers |
2222+| `boundary-state` | line | boundary | State/province boundaries (admin_level 3-6) |
2323+| `boundary-country` | line | boundary | Country boundaries (admin_level 2) |
2424+| `place-continent` | symbol | place | Continent labels |
2525+| `place-country` | symbol | place | Country labels |
2626+| `place-state` | symbol | place | State/province labels |
2727+| `place-city` | symbol | place | City labels |
2828+| `place-town` | symbol | place | Town labels |
2929+| `place-village` | symbol | place | Village labels |
3030+3131+### 2. Regional/Detail Layers (`layers.ts`)
3232+3333+Higher resolution tiles loaded on demand (PMTiles). These are prefixed with the source ID (e.g., `europe-water`, `us-landuse`).
3434+3535+| Layer ID | Type | Source Layer | Description |
3636+| --------------------------------- | ------ | ------------------- | -------------------------- |
3737+| `*-landuse-residential` | fill | landuse | Residential areas |
3838+| `*-landcover_grass` | fill | landcover | Grass |
3939+| `*-landcover_wood` | fill | landcover | Forest |
4040+| `*-water` | fill | water | Water polygons |
4141+| `*-water_intermittent` | fill | water | Intermittent water |
4242+| `*-landcover-ice-shelf` | fill | landcover | Ice shelves |
4343+| `*-landcover-glacier` | fill | landcover | Glaciers |
4444+| `*-landcover_sand` | fill | landcover | Sand |
4545+| `*-landuse` | fill | landuse | Agriculture |
4646+| `*-landuse_overlay_national_park` | fill | landcover | National parks |
4747+| `*-waterway-tunnel` | line | waterway | Tunnels |
4848+| `*-waterway` | line | waterway | Rivers |
4949+| `*-waterway_intermittent` | line | waterway | Intermittent rivers |
5050+| `*-tunnel_railway_transit` | line | transportation | Railway tunnels |
5151+| `*-building` | fill | building | Buildings |
5252+| `*-housenumber` | symbol | housenumber | House numbers |
5353+| `*-road_area_pier` | fill | transportation | Piers |
5454+| `*-road_pier` | line | transportation | Pier lines |
5555+| `*-road_bridge_area` | fill | transportation | Bridge areas |
5656+| `*-road_path` | line | transportation | Paths/tracks |
5757+| `*-road_minor` | line | transportation | Minor roads |
5858+| `*-tunnel_minor` | line | transportation | Minor road tunnels |
5959+| `*-tunnel_major` | line | transportation | Major road tunnels |
6060+| `*-aeroway-area` | fill | aeroway | Runway/taxiway areas |
6161+| `*-aeroway-taxiway` | line | aeroway | Taxiways |
6262+| `*-aeroway-runway` | line | aeroway | Runways |
6363+| `*-road_trunk_primary` | line | transportation | Trunk/primary roads |
6464+| `*-road_secondary_tertiary` | line | transportation | Secondary/tertiary roads |
6565+| `*-road_major_motorway` | line | transportation | Motorways |
6666+| `*-railway-transit` | line | transportation | Transit lines |
6767+| `*-railway` | line | transportation | Railways |
6868+| `*-waterway-bridge-case` | line | waterway | River bridge outlines |
6969+| `*-waterway-bridge` | line | waterway | River bridges |
7070+| `*-bridge_minor case` | line | transportation | Minor road bridge outlines |
7171+| `*-bridge_major case` | line | transportation | Major road bridge outlines |
7272+| `*-bridge_minor` | line | transportation | Minor road bridges |
7373+| `*-bridge_major` | line | transportation | Major road bridges |
7474+| `*-admin_sub` | line | boundary | Sub-national boundaries |
7575+| `*-admin_country_z0-4` | line | boundary | Country boundaries (z0-4) |
7676+| `*-admin_country_z5-` | line | boundary | Country boundaries (z5+) |
7777+| `*-poi_label` | symbol | poi | POI labels |
7878+| `*-airport-label` | symbol | aerodrome_label | Airport labels |
7979+| `*-road_major_label` | symbol | transportation_name | Road names |
8080+| `*-place_label_town` | symbol | place | Town labels |
8181+| `*-place_label_suburb` | symbol | place | Suburb labels |
8282+| `*-place_label_city` | symbol | place | City labels |
8383+| `*-country_label` | symbol | place | Country labels |
8484+8585+### 3. Bookmark Layers
8686+8787+User-created bookmarks rendered on top of all map layers.
8888+8989+| Layer ID | Type | Description |
9090+| ------------------------------- | ------ | --------------------------------------- |
9191+| `bookmarks-clusters` | circle | Clustered bookmarks (5+ points) |
9292+| `bookmarks-cluster-count` | circle | Invisible hit area for clusters |
9393+| `bookmarks-cluster-count-label` | symbol | Cluster count labels |
9494+| `bookmarks` | circle | Individual bookmark pins |
9595+| `bookmarks-hit` | circle | Invisible larger hit area for bookmarks |
9696+9797+The bookmark layers are explicitly moved to the top of the layer stack in `#ensureBookmarkLayersOnTop()` to ensure they render above map tiles and labels.
9898+9999+## Layer Loading Order
100100+101101+1. **World tiles** load first via `#loadWorldTiles()` - provides low-res global coverage
102102+2. **Detail tiles** load on demand via `#loadCachedDetailTiles()` - higher resolution for downloaded regions
103103+3. **Bookmark layers** are added last and moved to top
104104+105105+## Z-Index in DOM
106106+107107+The CSS establishes the following z-index stacking:
108108+109109+- `m-map` container: `z-index: 1`
110110+- Map canvas: `z-index: 1`
111111+- MapLibre controls: `z-index: 10`
112112+- Download button: `z-index: 10`
113113+114114+This ensures controls and buttons appear above the map canvas while maintaining the correct DOM order.