feat(map): toggle the trip map between default and satellite tiles

Add a corner button on the Leaflet trip map that switches the base layer
between the default street tiles and a tokenless satellite view (ESRI
World Imagery). The choice is a per-user setting (map_base_layer) that
persists and applies instantly, including offline. GL-renderer satellite
styles are unchanged.

Closes #993

client/src/components/Map/MapLayerSwitcher.test.tsx

@@ -0,0 +1,44 @@
+// FE-COMP-MAPLAYER-001 to FE-COMP-MAPLAYER-005
+import React from 'react'
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '../../../tests/helpers/render'
+import { MapLayerSwitcher } from './MapLayerSwitcher'
+
+describe('MapLayerSwitcher', () => {
+  it('FE-COMP-MAPLAYER-001: on the default layer, offers the switch to satellite', () => {
+    render(<MapLayerSwitcher active="default" onToggle={() => {}} />)
+    const button = screen.getByRole('button', { name: 'Switch to satellite view' })
+    expect(button.getAttribute('aria-pressed')).toBe('false')
+  })
+
+  it('FE-COMP-MAPLAYER-002: on the satellite layer, offers the switch back to the map', () => {
+    render(<MapLayerSwitcher active="satellite" onToggle={() => {}} />)
+    const button = screen.getByRole('button', { name: 'Switch to map view' })
+    expect(button.getAttribute('aria-pressed')).toBe('true')
+  })
+
+  it('FE-COMP-MAPLAYER-003: clicking fires the toggle', () => {
+    const onToggle = vi.fn()
+    render(<MapLayerSwitcher active="default" onToggle={onToggle} />)
+    fireEvent.click(screen.getByRole('button', { name: 'Switch to satellite view' }))
+    expect(onToggle).toHaveBeenCalledTimes(1)
+  })
+
+  it('FE-COMP-MAPLAYER-004: swaps the icon with the active layer', () => {
+    const { rerender } = render(<MapLayerSwitcher active="default" onToggle={() => {}} />)
+    // Destination icon: on the map you can reach satellite, and vice-versa.
+    const iconOnDefault = screen.getByRole('button').querySelector('svg')?.getAttribute('class')
+    rerender(<MapLayerSwitcher active="satellite" onToggle={() => {}} />)
+    const iconOnSatellite = screen.getByRole('button').querySelector('svg')?.getAttribute('class')
+    expect(iconOnDefault).not.toBe(iconOnSatellite)
+  })
+
+  it('FE-COMP-MAPLAYER-005: highlights the button on hover and clears it again', () => {
+    render(<MapLayerSwitcher active="default" onToggle={() => {}} />)
+    const button = screen.getByRole('button')
+    fireEvent.mouseEnter(button)
+    expect(button.style.background).toBe('var(--bg-hover)')
+    fireEvent.mouseLeave(button)
+    expect(button.style.background).toBe('transparent')
+  })
+})

client/src/components/Map/MapLayerSwitcher.tsx

@@ -0,0 +1,43 @@
+import { Map as MapIcon, Satellite } from 'lucide-react'
+import { useTranslation } from '../../i18n'
+
+export type BaseLayer = 'default' | 'satellite'
+
+// Round base-layer switcher for the Leaflet planner map (default street tiles ↔
+// satellite). Same frosted shell as MapCompassPill so it lines up with the other
+// map controls; the icon shows the layer it switches to.
+export function MapLayerSwitcher({ active, onToggle }: { active: BaseLayer; onToggle: () => void }) {
+  const { t } = useTranslation()
+  const isSatellite = active === 'satellite'
+  const Icon = isSatellite ? MapIcon : Satellite
+  const label = isSatellite ? t('map.baseLayer.switchToDefault') : t('map.baseLayer.switchToSatellite')
+
+  return (
+    <div style={{
+      display: 'inline-flex', alignItems: 'center', padding: 4, borderRadius: 999, pointerEvents: 'auto',
+      background: 'var(--sidebar-bg)',
+      backdropFilter: 'blur(20px) saturate(180%)',
+      WebkitBackdropFilter: 'blur(20px) saturate(180%)',
+      boxShadow: 'var(--sidebar-shadow, 0 4px 16px rgba(0,0,0,0.14))',
+    }}>
+      <button
+        type="button"
+        onClick={onToggle}
+        aria-label={label}
+        title={label}
+        aria-pressed={isSatellite}
+        className="text-content-muted"
+        style={{
+          display: 'inline-flex', alignItems: 'center', justifyContent: 'center',
+          width: 34, height: 34, borderRadius: 999, border: 'none', cursor: 'pointer',
+          background: 'transparent', padding: 0,
+          transition: 'background 0.14s, color 0.14s',
+        }}
+        onMouseEnter={e => { e.currentTarget.style.background = 'var(--bg-hover)' }}
+        onMouseLeave={e => { e.currentTarget.style.background = 'transparent' }}
+      >
+        <Icon size={17} strokeWidth={2} />
+      </button>
+    </div>
+  )
+}

client/src/components/Map/MapView.tsx

@@ -16,7 +16,9 @@ import { visibleRouteReservations } from '../../utils/reservationRoutes'
 import type { Reservation, RouteVia } from '../../types'
 import { POI_CATEGORY_BY_KEY, type Poi } from './poiCategories'
 import { resolveTrackColor, hasManualTrackColor } from './trackColors'
-import { DEFAULT_MAP_CENTER, DEFAULT_MAP_ZOOM } from '../../constants/mapDefaults'
+import { DEFAULT_MAP_CENTER, DEFAULT_MAP_ZOOM, SATELLITE_TILE_URL, SATELLITE_TILE_ATTRIBUTION, SATELLITE_TILE_MAXZOOM } from '../../constants/mapDefaults'
+import { useSettingsStore } from '../../store/settingsStore'
+import { MapLayerSwitcher } from './MapLayerSwitcher'
 import { computeMapViewport, TILE_SIZE_RASTER, type ViewportPadding } from '../../utils/mapViewport'
 
 function categoryIconSvg(iconName: string | null | undefined, size: number): string {
@@ -771,6 +773,17 @@ export const MapView = memo(function MapView({
     ? 'calc(var(--bottom-nav-h, 84px) + 20px + var(--day-panel-h, 0px) + 12px)'
     : 'calc(var(--bottom-nav-h, 84px) + 12px)'
 
+  const baseLayer = useSettingsStore(s => s.settings.map_base_layer) || 'default'
+  const updateSetting = useSettingsStore(s => s.updateSetting)
+  const isSatellite = baseLayer === 'satellite'
+  const toggleBaseLayer = useCallback(() => {
+    // Store flips state synchronously (instant, works offline); a failed save is logged there.
+    updateSetting('map_base_layer', isSatellite ? 'default' : 'satellite').catch(() => {})
+  }, [isSatellite, updateSetting])
+  const switcherBottom = hasDayDetail
+    ? 'calc(var(--bottom-nav-h, 0px) + 20px + var(--day-panel-h, 0px) + 12px)'
+    : 'calc(var(--bottom-nav-h, 0px) + 12px)'
+
   return (
     <>
     <div className="w-full h-full relative">
@@ -781,10 +794,12 @@ export const MapView = memo(function MapView({
       zoomControl={false}
       className="w-full h-full bg-[#e5e7eb]"
     >
+      {/* key remounts the layer on switch, else attribution/maxZoom stick at mount-time values. */}
       <TileLayer
-        url={tileUrl}
-        attribution='&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a>'
-        maxZoom={19}
+        key={isSatellite ? 'satellite' : 'default'}
+        url={isSatellite ? SATELLITE_TILE_URL : tileUrl}
+        attribution={isSatellite ? SATELLITE_TILE_ATTRIBUTION : '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a>'}
+        maxZoom={isSatellite ? SATELLITE_TILE_MAXZOOM : 19}
         keepBuffer={8}
         updateWhenZooming={false}
         updateWhenIdle={true}
@@ -864,6 +879,9 @@ export const MapView = memo(function MapView({
       onClick={cycleTrackingMode}
       bottomOffset={locationButtonBottom as unknown as number}
     />}
+    <div style={{ position: 'absolute', left: leftWidth + 12, bottom: switcherBottom, zIndex: 1000, pointerEvents: 'none' }}>
+      <MapLayerSwitcher active={baseLayer} onToggle={toggleBaseLayer} />
+    </div>
     </div>
 
     {TooltipOverlay && (

client/src/constants/mapDefaults.ts

@@ -2,3 +2,10 @@ export const DEFAULT_MAP_LAT = 0
 export const DEFAULT_MAP_LNG = 0
 export const DEFAULT_MAP_ZOOM = 2
 export const DEFAULT_MAP_CENTER: [number, number] = [DEFAULT_MAP_LAT, DEFAULT_MAP_LNG]
+
+// Tokenless satellite base layer (ESRI World Imagery) — works without an API key.
+export const SATELLITE_TILE_URL =
+  'https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}'
+export const SATELLITE_TILE_ATTRIBUTION =
+  'Imagery &copy; <a href="https://www.esri.com">Esri</a>, Maxar, Earthstar Geographics'
+export const SATELLITE_TILE_MAXZOOM = 19

client/src/store/settingsStore.ts

@@ -40,6 +40,7 @@ export const DEFAULT_SETTINGS: Settings = {
   show_place_description: false,
   optimize_from_accommodation: true,
   map_provider: 'leaflet',
+  map_base_layer: 'default',
   map_poi_pill_enabled: true,
   mapbox_access_token: '',
   mapbox_style: 'mapbox://styles/mapbox/standard',

client/src/types.ts

@@ -122,6 +122,8 @@ export interface Settings {
   map_always_show_routes?: boolean
   optimize_from_accommodation?: boolean
   map_provider?: 'leaflet' | 'mapbox-gl' | 'maplibre-gl'
+  /** Leaflet base layer: default street tiles or a satellite/aerial view. */
+  map_base_layer?: 'default' | 'satellite'
   mapbox_access_token?: string
   mapbox_style?: string
   maplibre_style?: string

shared/src/i18n/ar/map.ts

@@ -15,5 +15,9 @@ const map: TranslationStrings = {
   'poi.cat.activities': 'أنشطة',
   'map.showAllConnections': 'إظهار جميع مسارات الحجوزات',
   'map.hideAllConnections': 'إخفاء جميع مسارات الحجوزات',
+  'map.baseLayer.default': 'خريطة',
+  'map.baseLayer.satellite': 'قمر صناعي',
+  'map.baseLayer.switchToSatellite': 'التبديل إلى عرض القمر الصناعي',
+  'map.baseLayer.switchToDefault': 'التبديل إلى عرض الخريطة',
 };
 export default map;

shared/src/i18n/br/map.ts

@@ -15,5 +15,9 @@ const map: TranslationStrings = {
   'poi.cat.activities': 'Atividades',
   'map.showAllConnections': 'Mostrar todas as rotas de reservas',
   'map.hideAllConnections': 'Ocultar todas as rotas de reservas',
+  'map.baseLayer.default': 'Mapa',
+  'map.baseLayer.satellite': 'Satélite',
+  'map.baseLayer.switchToSatellite': 'Mudar para vista de satélite',
+  'map.baseLayer.switchToDefault': 'Mudar para vista de mapa',
 };
 export default map;

shared/src/i18n/ca/map.ts

@@ -15,5 +15,9 @@ const map: TranslationStrings = {
   'poi.cat.activities': 'Activitats',
   'map.showAllConnections': 'Mostra totes les rutes de reserva',
   'map.hideAllConnections': 'Amaga totes les rutes de reserva',
+  'map.baseLayer.default': 'Mapa',
+  'map.baseLayer.satellite': 'Satèl·lit',
+  'map.baseLayer.switchToSatellite': 'Canvia a vista de satèl·lit',
+  'map.baseLayer.switchToDefault': 'Canvia a vista de mapa',
 };
 export default map;

shared/src/i18n/cs/map.ts

@@ -15,5 +15,9 @@ const map: TranslationStrings = {
   'poi.cat.activities': 'Aktivity',
   'map.showAllConnections': 'Zobrazit všechny trasy rezervací',
   'map.hideAllConnections': 'Skrýt všechny trasy rezervací',
+  'map.baseLayer.default': 'Mapa',
+  'map.baseLayer.satellite': 'Satelit',
+  'map.baseLayer.switchToSatellite': 'Přepnout na satelitní zobrazení',
+  'map.baseLayer.switchToDefault': 'Přepnout na mapové zobrazení',
 };
 export default map;

shared/src/i18n/de/map.ts

@@ -15,5 +15,9 @@ const map: TranslationStrings = {
   'poi.cat.activities': 'Aktivitäten',
   'map.showAllConnections': 'Alle Buchungsrouten anzeigen',
   'map.hideAllConnections': 'Alle Buchungsrouten ausblenden',
+  'map.baseLayer.default': 'Karte',
+  'map.baseLayer.satellite': 'Satellit',
+  'map.baseLayer.switchToSatellite': 'Zur Satellitenansicht wechseln',
+  'map.baseLayer.switchToDefault': 'Zur Kartenansicht wechseln',
 };
 export default map;

shared/src/i18n/en/map.ts

@@ -15,5 +15,9 @@ const map: TranslationStrings = {
   'poi.cat.activities': 'Activities',
   'map.showAllConnections': 'Show all booking routes',
   'map.hideAllConnections': 'Hide all booking routes',
+  'map.baseLayer.default': 'Map',
+  'map.baseLayer.satellite': 'Satellite',
+  'map.baseLayer.switchToSatellite': 'Switch to satellite view',
+  'map.baseLayer.switchToDefault': 'Switch to map view',
 };
 export default map;

shared/src/i18n/es/map.ts

@@ -15,5 +15,9 @@ const map: TranslationStrings = {
   'poi.cat.activities': 'Actividades',
   'map.showAllConnections': 'Mostrar todas las rutas de reservas',
   'map.hideAllConnections': 'Ocultar todas las rutas de reservas',
+  'map.baseLayer.default': 'Mapa',
+  'map.baseLayer.satellite': 'Satélite',
+  'map.baseLayer.switchToSatellite': 'Cambiar a vista de satélite',
+  'map.baseLayer.switchToDefault': 'Cambiar a vista de mapa',
 };
 export default map;

shared/src/i18n/fr/map.ts

@@ -15,5 +15,9 @@ const map: TranslationStrings = {
   'poi.cat.activities': 'Activités',
   'map.showAllConnections': 'Afficher tous les itinéraires',
   'map.hideAllConnections': 'Masquer tous les itinéraires',
+  'map.baseLayer.default': 'Carte',
+  'map.baseLayer.satellite': 'Satellite',
+  'map.baseLayer.switchToSatellite': 'Passer à la vue satellite',
+  'map.baseLayer.switchToDefault': 'Passer à la vue carte',
 };
 export default map;

shared/src/i18n/gr/map.ts

@@ -15,5 +15,9 @@ const map: TranslationStrings = {
   'poi.cat.activities': 'Δραστηριότητες',
   'map.showAllConnections': 'Εμφάνιση όλων των διαδρομών κρατήσεων',
   'map.hideAllConnections': 'Απόκρυψη όλων των διαδρομών κρατήσεων',
+  'map.baseLayer.default': 'Χάρτης',
+  'map.baseLayer.satellite': 'Δορυφόρος',
+  'map.baseLayer.switchToSatellite': 'Εναλλαγή σε δορυφορική προβολή',
+  'map.baseLayer.switchToDefault': 'Εναλλαγή σε προβολή χάρτη',
 };
 export default map;

shared/src/i18n/hu/map.ts

@@ -15,5 +15,9 @@ const map: TranslationStrings = {
   'poi.cat.activities': 'Programok',
   'map.showAllConnections': 'Összes foglalási útvonal megjelenítése',
   'map.hideAllConnections': 'Összes foglalási útvonal elrejtése',
+  'map.baseLayer.default': 'Térkép',
+  'map.baseLayer.satellite': 'Műhold',
+  'map.baseLayer.switchToSatellite': 'Váltás műholdas nézetre',
+  'map.baseLayer.switchToDefault': 'Váltás térkép nézetre',
 };
 export default map;

shared/src/i18n/id/map.ts

@@ -15,5 +15,9 @@ const map: TranslationStrings = {
   'poi.cat.activities': 'Aktivitas',
   'map.showAllConnections': 'Tampilkan semua rute pemesanan',
   'map.hideAllConnections': 'Sembunyikan semua rute pemesanan',
+  'map.baseLayer.default': 'Peta',
+  'map.baseLayer.satellite': 'Satelit',
+  'map.baseLayer.switchToSatellite': 'Beralih ke tampilan satelit',
+  'map.baseLayer.switchToDefault': 'Beralih ke tampilan peta',
 };
 export default map;

shared/src/i18n/it/map.ts

@@ -15,5 +15,9 @@ const map: TranslationStrings = {
   'poi.cat.activities': 'Attività',
   'map.showAllConnections': 'Mostra tutti i percorsi prenotati',
   'map.hideAllConnections': 'Nascondi tutti i percorsi prenotati',
+  'map.baseLayer.default': 'Mappa',
+  'map.baseLayer.satellite': 'Satellite',
+  'map.baseLayer.switchToSatellite': 'Passa alla vista satellitare',
+  'map.baseLayer.switchToDefault': 'Passa alla vista mappa',
 };
 export default map;

shared/src/i18n/ja/map.ts

@@ -15,5 +15,9 @@ const map: TranslationStrings = {
   'poi.cat.activities': 'アクティビティ',
   'map.showAllConnections': 'すべての予約ルートを表示',
   'map.hideAllConnections': 'すべての予約ルートを非表示',
+  'map.baseLayer.default': '地図',
+  'map.baseLayer.satellite': '衛星',
+  'map.baseLayer.switchToSatellite': '衛星表示に切り替える',
+  'map.baseLayer.switchToDefault': '地図表示に切り替える',
 };
 export default map;

shared/src/i18n/ko/map.ts

@@ -15,5 +15,9 @@ const map: TranslationStrings = {
   'poi.cat.activities': '액티비티',
   'map.showAllConnections': '모든 예약 경로 표시',
   'map.hideAllConnections': '모든 예약 경로 숨기기',
+  'map.baseLayer.default': '지도',
+  'map.baseLayer.satellite': '위성',
+  'map.baseLayer.switchToSatellite': '위성 보기로 전환',
+  'map.baseLayer.switchToDefault': '지도 보기로 전환',
 };
 export default map;

shared/src/i18n/nl/map.ts

@@ -15,5 +15,9 @@ const map: TranslationStrings = {
   'poi.cat.activities': 'Activiteiten',
   'map.showAllConnections': 'Alle boekingsroutes tonen',
   'map.hideAllConnections': 'Alle boekingsroutes verbergen',
+  'map.baseLayer.default': 'Kaart',
+  'map.baseLayer.satellite': 'Satelliet',
+  'map.baseLayer.switchToSatellite': 'Overschakelen naar satellietweergave',
+  'map.baseLayer.switchToDefault': 'Overschakelen naar kaartweergave',
 };
 export default map;

shared/src/i18n/pl/map.ts

@@ -15,5 +15,9 @@ const map: TranslationStrings = {
   'poi.cat.activities': 'Aktywności',
   'map.showAllConnections': 'Pokaż wszystkie trasy rezerwacji',
   'map.hideAllConnections': 'Ukryj wszystkie trasy rezerwacji',
+  'map.baseLayer.default': 'Mapa',
+  'map.baseLayer.satellite': 'Satelita',
+  'map.baseLayer.switchToSatellite': 'Przełącz na widok satelitarny',
+  'map.baseLayer.switchToDefault': 'Przełącz na widok mapy',
 };
 export default map;

shared/src/i18n/ru/map.ts

@@ -15,5 +15,9 @@ const map: TranslationStrings = {
   'poi.cat.activities': 'Развлечения',
   'map.showAllConnections': 'Показать все маршруты бронирований',
   'map.hideAllConnections': 'Скрыть все маршруты бронирований',
+  'map.baseLayer.default': 'Карта',
+  'map.baseLayer.satellite': 'Спутник',
+  'map.baseLayer.switchToSatellite': 'Переключить на спутниковый вид',
+  'map.baseLayer.switchToDefault': 'Переключить на вид карты',
 };
 export default map;

shared/src/i18n/sv/map.ts

@@ -15,5 +15,9 @@ const map: TranslationStrings = {
   'poi.cat.activities': 'Aktiviteter',
   'map.showAllConnections': 'Visa alla bokningsvägar',
   'map.hideAllConnections': 'Dölj alla bokningsvägar',
+  'map.baseLayer.default': 'Karta',
+  'map.baseLayer.satellite': 'Satellit',
+  'map.baseLayer.switchToSatellite': 'Byt till satellitvy',
+  'map.baseLayer.switchToDefault': 'Byt till kartvy',
 };
 export default map;

shared/src/i18n/tr/map.ts

@@ -15,5 +15,9 @@ const map: TranslationStrings = {
   'poi.cat.activities': 'Aktiviteler',
   'map.showAllConnections': 'Tüm rezervasyon rotalarını göster',
   'map.hideAllConnections': 'Tüm rezervasyon rotalarını gizle',
+  'map.baseLayer.default': 'Harita',
+  'map.baseLayer.satellite': 'Uydu',
+  'map.baseLayer.switchToSatellite': 'Uydu görünümüne geç',
+  'map.baseLayer.switchToDefault': 'Harita görünümüne geç',
 };
 export default map;

shared/src/i18n/uk/map.ts

@@ -15,5 +15,9 @@ const map: TranslationStrings = {
   'poi.cat.activities': 'Активності',
   'map.showAllConnections': 'Показати всі маршрути бронювань',
   'map.hideAllConnections': 'Приховати всі маршрути бронювань',
+  'map.baseLayer.default': 'Карта',
+  'map.baseLayer.satellite': 'Супутник',
+  'map.baseLayer.switchToSatellite': 'Перемкнути на супутниковий вигляд',
+  'map.baseLayer.switchToDefault': 'Перемкнути на вигляд карти',
 };
 export default map;

shared/src/i18n/vi/map.ts

@@ -15,5 +15,9 @@ const map: TranslationStrings = {
   'poi.cat.activities': 'Các hoạt động',
   'map.showAllConnections': 'Hiển thị tất cả lộ trình đặt chỗ',
   'map.hideAllConnections': 'Ẩn tất cả lộ trình đặt chỗ',
+  'map.baseLayer.default': 'Bản đồ',
+  'map.baseLayer.satellite': 'Vệ tinh',
+  'map.baseLayer.switchToSatellite': 'Chuyển sang chế độ xem vệ tinh',
+  'map.baseLayer.switchToDefault': 'Chuyển sang chế độ xem bản đồ',
 };
 export default map;

shared/src/i18n/zh-TW/map.ts

@@ -15,5 +15,9 @@ const map: TranslationStrings = {
   'poi.cat.activities': '活動',
   'map.showAllConnections': '顯示所有預訂路線',
   'map.hideAllConnections': '隱藏所有預訂路線',
+  'map.baseLayer.default': '地圖',
+  'map.baseLayer.satellite': '衛星',
+  'map.baseLayer.switchToSatellite': '切換到衛星檢視',
+  'map.baseLayer.switchToDefault': '切換到地圖檢視',
 };
 export default map;

shared/src/i18n/zh/map.ts

@@ -15,5 +15,9 @@ const map: TranslationStrings = {
   'poi.cat.activities': '活动',
   'map.showAllConnections': '显示所有预订路线',
   'map.hideAllConnections': '隐藏所有预订路线',
+  'map.baseLayer.default': '地图',
+  'map.baseLayer.satellite': '卫星',
+  'map.baseLayer.switchToSatellite': '切换到卫星视图',
+  'map.baseLayer.switchToDefault': '切换到地图视图',
 };
 export default map;