Google Maps — Interactive Map Application

Zoom 0:  1 tile (whole world)
Zoom 1:  4 tiles (2×2)
Zoom 2:  16 tiles (4×4)
...
Zoom N:  4^N tiles

Zoom 15: 4^15 = 1,073,741,824 tiles (~1 billion)
Zoom 22: 4^22 = 17,592,186,044,416 tiles (~17.6 trillion)

URL Structure:
/@{lat},{lng},{zoom}z/{tilt}t,{heading}h

Examples:
/@37.7749,-122.4194,15z           — San Francisco, zoom 15
/@37.7749,-122.4194,15z/45t,90h   — Tilted 45°, heading East
/directions/@37.77,-122.42/to/@34.05,-118.24  — Route view
/place/ChIJN1t_tDeuEmsRUsoyG83frY4  — Place detail

┌─────────────────────────────────────────────────────────────┐
│ <MapApplication>                                             │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌─────────────────────────────────────────────────────┐     │
│  │ <MapCanvas>                                          │     │
│  │  ├── <TileRenderer>          — WebGL tile compositing│     │
│  │  ├── <VectorRenderer>        — Geometry/label render │     │
│  │  ├── <MarkerLayer>           — Clustered markers     │     │
│  │  ├── <RouteOverlay>          — Polyline rendering    │     │
│  │  ├── <GeolocationIndicator>  — User position dot     │     │
│  │  └── <GestureHandler>        — Touch/mouse events    │     │
│  └─────────────────────────────────────────────────────┘     │
│                                                               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐   │
│  │ <SearchBar>  │  │ <LayerPanel> │  │ <DirectionsPanel>│   │
│  │  ├── Input   │  │  ├── Toggle  │  │  ├── WaypointList│   │
│  │  └── Results │  │  └── Legend  │  │  ├── RouteOptions│   │
│  └──────────────┘  └──────────────┘  │  └── TurnList    │   │
│                                        └──────────────────┘   │
│  ┌──────────────┐  ┌──────────────┐                          │
│  │ <ZoomControl>│  │ <InfoWindow> │                          │
│  │  ├── ZoomIn  │  │  ├── Header  │                          │
│  │  ├── ZoomOut │  │  ├── Content │                          │
│  │  └── Compass │  │  └── Actions │                          │
│  └──────────────┘  └──────────────┘                          │
└─────────────────────────────────────────────────────────────┘

// Viewport state — updates at 60fps during interaction
interface ViewportState {
  center: { lat: number; lng: number };
  zoom: number; // 0–22, supports fractional (e.g., 14.5)
  bearing: number; // 0–360 degrees
  pitch: number; // 0–60 degrees
  bounds: LngLatBounds; // Derived from center + zoom + viewport size
}

// Application state — updates on user actions (Hz range)
interface AppState {
  searchQuery: string;
  selectedPlace: Place | null;
  activeRoute: Route | null;
  activeLayers: Set<LayerType>;
  isNavigating: boolean;
}

// Data state — updates on network responses (seconds range)
interface DataState {
  visibleMarkers: MarkerCluster[];
  tileCache: Map<string, TileEntry>;
  searchResults: Place[];
  routeGeometry: RouteGeometry | null;
}

/** Geographic coordinate in WGS84 */
interface LatLng {
  lat: number; // -90 to 90
  lng: number; // -180 to 180
}

/** Bounding box for viewport queries */
interface LngLatBounds {
  sw: LatLng; // Southwest corner
  ne: LatLng; // Northeast corner
}

/** Tile coordinate in the Slippy Map system */
interface TileCoord {
  x: number; // Column: 0 to 2^zoom - 1
  y: number; // Row: 0 to 2^zoom - 1
  z: number; // Zoom level: 0 to 22
}

/** Tile metadata and content */
interface TileEntry {
  coord: TileCoord;
  format: "raster-png" | "raster-jpeg" | "vector-mvt";
  data: ArrayBuffer;
  size: number; // bytes
  fetchedAt: number; // timestamp
  expiresAt: number; // Cache-Control derived
  etag: string | null;
  priority: TilePriority;
}

type TilePriority = "critical" | "visible" | "buffer" | "prefetch";

/** Vector tile layer structure (MVT decoded) */
interface VectorTileLayer {
  name: string; // 'roads', 'buildings', 'labels', 'water'
  features: VectorFeature[];
  extent: number; // Tile coordinate space (typically 4096)
}

interface VectorFeature {
  id: number;
  type: "Point" | "LineString" | "Polygon";
  geometry: number[][]; // Coordinate rings
  properties: Record<string, string | number | boolean>;
  tags: number[]; // Encoded key-value indices
}

/** Marker with clustering support */
interface MapMarker {
  id: string;
  position: LatLng;
  icon: MarkerIcon;
  category: string;
  priority: number; // Higher = shown at lower zoom levels
  clusterGroup: string; // Grouping key for clustering algorithm
  metadata: Record<string, unknown>;
}

interface MarkerIcon {
  url: string;
  size: [number, number]; // [width, height] in pixels
  anchor: [number, number]; // Anchor point offset
  spriteOffset?: [number, number]; // For sprite sheet icons
}

/** Cluster node produced by spatial indexing */
interface MarkerCluster {
  id: string;
  center: LatLng;
  count: number;
  expansion_zoom: number; // Zoom level where cluster breaks apart
  children: string[]; // Marker IDs or child cluster IDs
  bounds: LngLatBounds;
}

/** Route geometry and metadata */
interface Route {
  id: string;
  origin: LatLng;
  destination: LatLng;
  waypoints: LatLng[];
  legs: RouteLeg[];
  overview_polyline: string; // Encoded polyline
  bounds: LngLatBounds;
  duration: number; // seconds
  distance: number; // meters
  traffic_model: "best_guess" | "pessimistic" | "optimistic";
}

interface RouteLeg {
  start: LatLng;
  end: LatLng;
  steps: RouteStep[];
  duration: number;
  distance: number;
  traffic_segments: TrafficSegment[];
}

interface RouteStep {
  instruction: string;
  maneuver: ManeuverType;
  polyline: string; // Encoded polyline for this step
  duration: number;
  distance: number;
  start_location: LatLng;
  end_location: LatLng;
}

type ManeuverType =
  | "turn-left"
  | "turn-right"
  | "turn-slight-left"
  | "turn-slight-right"
  | "uturn-left"
  | "uturn-right"
  | "merge"
  | "fork-left"
  | "fork-right"
  | "ramp-left"
  | "ramp-right"
  | "roundabout"
  | "straight"
  | "depart"
  | "arrive";

interface TrafficSegment {
  start_index: number;
  end_index: number;
  speed: "fast" | "moderate" | "slow" | "traffic_jam";
  color: string; // Hex color for rendering
}

/** Place / POI entity */
interface Place {
  place_id: string;
  name: string;
  position: LatLng;
  category: PlaceCategory;
  rating: number | null;
  price_level: 1 | 2 | 3 | 4 | null;
  opening_hours: OpeningHours | null;
  address: string;
  viewport: LngLatBounds;
  icon_mask_url: string;
}

type PlaceCategory =
  | "restaurant"
  | "hotel"
  | "gas_station"
  | "hospital"
  | "school"
  | "park"
  | "shopping"
  | "transit"
  | "parking"
  | "airport"
  | "museum"
  | "bank"
  | "pharmacy";

interface OpeningHours {
  is_open_now: boolean;
  periods: { open: TimeOfDay; close: TimeOfDay }[];
}

interface TimeOfDay {
  day: 0 | 1 | 2 | 3 | 4 | 5 | 6;
  hours: number;
  minutes: number;
}

/** Geolocation state */
interface UserLocation {
  position: LatLng;
  accuracy: number; // meters
  heading: number | null; // degrees from north
  speed: number | null; // m/s
  timestamp: number;
  source: "gps" | "network" | "ip";
}

/** Offline region definition */
interface OfflineRegion {
  id: string;
  name: string;
  bounds: LngLatBounds;
  minZoom: number;
  maxZoom: number;
  tileCount: number;
  sizeEstimate: number; // bytes
  downloadedAt: number | null;
  progress: number; // 0–1
  format: "raster" | "vector";
}

/**
 * Tile URL template following Slippy Map convention.
 * CDN serves pre-rendered raster or on-demand vector tiles.
 */
// Raster: GET /tiles/{z}/{x}/{y}.png
// Vector: GET /tiles/{z}/{x}/{y}.mvt
// Satellite: GET /satellite/{z}/{x}/{y}.jpeg

interface TileRequestParams {
  z: number;
  x: number;
  y: number;
  format: "png" | "mvt" | "jpeg";
  scale?: 1 | 2; // @2x for Retina
  lang?: string; // Label language
  style?: string; // Map style ID
}

// Response headers:
// Cache-Control: public, max-age=86400
// ETag: "abc123"
// Content-Encoding: gzip (for MVT)
// Content-Type: image/png | application/x-protobuf | image/jpeg

/** Viewport-based POI search */
// GET /api/places/viewport
interface ViewportPlacesRequest {
  bounds: string; // "sw_lat,sw_lng,ne_lat,ne_lng"
  zoom: number;
  categories?: string[];
  limit?: number; // default 200
}

interface ViewportPlacesResponse {
  places: Place[];
  clusters: PlaceCluster[];
  total_count: number;
  next_cursor: string | null;
}

/** Geocoding API */
// GET /api/geocode?query=...&location=lat,lng&radius=50000
interface GeocodeRequest {
  query: string;
  location?: string; // Bias center "lat,lng"
  radius?: number; // Bias radius in meters
  language?: string;
  components?: string; // Country restriction
}

interface GeocodeResponse {
  results: GeocodeResult[];
  status: "OK" | "ZERO_RESULTS" | "OVER_QUERY_LIMIT";
}

interface GeocodeResult {
  place_id: string;
  formatted_address: string;
  geometry: {
    location: LatLng;
    viewport: LngLatBounds;
  };
  types: string[];
}

// POST /api/directions
interface DirectionsRequest {
  origin: LatLng | string; // Coordinates or place_id
  destination: LatLng | string;
  waypoints?: (LatLng | string)[];
  mode: "driving" | "walking" | "cycling" | "transit";
  departure_time?: number; // Unix timestamp
  avoid?: ("tolls" | "highways" | "ferries")[];
  alternatives?: boolean;
}

interface DirectionsResponse {
  routes: Route[];
  status: "OK" | "NOT_FOUND" | "ZERO_RESULTS";
  geocoded_waypoints: GeocodeResult[];
}

// GET /api/autocomplete?input=...&sessiontoken=...
interface AutocompleteRequest {
  input: string;
  sessiontoken: string; // Groups requests for billing
  location?: string;
  radius?: number;
  types?: string[]; // 'establishment' | 'geocode' | 'address'
  language?: string;
}

interface AutocompleteResponse {
  predictions: Prediction[];
  status: "OK" | "ZERO_RESULTS";
}

interface Prediction {
  place_id: string;
  description: string;
  structured_formatting: {
    main_text: string;
    secondary_text: string;
    main_text_matched_substrings: { offset: number; length: number }[];
  };
  types: string[];
  distance_meters: number | null;
}

/**
 * Three-tier client cache: Memory → IndexedDB → Network
 *
 * Memory (LRU): ~200 tiles, immediate access (<1ms)
 * IndexedDB: configurable budget (default 100MB), ~5ms access
 * Network: 200ms–2s depending on CDN proximity
 */

interface TileCacheConfig {
  memoryMaxTiles: number; // Default: 256
  memoryMaxBytes: number; // Default: 64MB
  diskMaxBytes: number; // Default: 100MB
  diskEvictionPolicy: "lru" | "lru-with-priority";
  prefetchRadius: number; // Tiles beyond viewport: 1–2
  offlineBudgetBytes: number; // Default: 200MB
}

class TileCache {
  private memoryCache: LRUCache<string, TileEntry>;
  private db: IDBDatabase;

  async get(coord: TileCoord): Promise<TileEntry | null> {
    const key = `${coord.z}/${coord.x}/${coord.y}`;

    // L1: Memory
    const memHit = this.memoryCache.get(key);
    if (memHit) return memHit;

    // L2: IndexedDB
    const diskHit = await this.readFromDisk(key);
    if (diskHit && !this.isExpired(diskHit)) {
      this.memoryCache.set(key, diskHit); // Promote to L1
      return diskHit;
    }

    // L3: Network (caller handles)
    return null;
  }

  async put(
    coord: TileCoord,
    data: ArrayBuffer,
    headers: Headers,
  ): Promise<void> {
    const entry: TileEntry = {
      coord,
      format: this.detectFormat(headers),
      data,
      size: data.byteLength,
      fetchedAt: Date.now(),
      expiresAt: this.parseExpiry(headers),
      etag: headers.get("etag"),
      priority: this.computePriority(coord),
    };

    this.memoryCache.set(this.toKey(coord), entry);
    await this.writeToDisk(entry);
    await this.enforceQuota();
  }

  private async enforceQuota(): Promise<void> {
    const usage = await this.getDiskUsage();
    if (usage > this.config.diskMaxBytes) {
      // Evict lowest-priority, oldest tiles first
      await this.evictLRU(usage - this.config.diskMaxBytes * 0.8);
    }
  }
}

Key format: "{style}/{z}/{x}/{y}@{scale}x.{format}"
Examples:
  "default/15/5242/[email protected]"
  "satellite/18/41943/[email protected]"

// sw.ts — Stale-while-revalidate for tiles, network-first for API
self.addEventListener("fetch", (event: FetchEvent) => {
  const url = new URL(event.request.url);

  if (url.pathname.startsWith("/tiles/")) {
    event.respondWith(staleWhileRevalidate(event.request, "tile-cache-v1"));
  } else if (url.pathname.startsWith("/api/")) {
    event.respondWith(networkFirst(event.request, "api-cache-v1", 3000));
  }
});

async function staleWhileRevalidate(
  request: Request,
  cacheName: string,
): Promise<Response> {
  const cache = await caches.open(cacheName);
  const cached = await cache.match(request);

  const networkPromise = fetch(request).then((response) => {
    if (response.ok) cache.put(request, response.clone());
    return response;
  });

  return cached ?? networkPromise;
}

Timeline (target: interactive in 1.5s):

0ms     — HTML received, parser starts
50ms    — Critical CSS inlined, map container rendered (skeleton)
100ms   — Map SDK JS begins loading (async, 120KB gzipped)
300ms   — SDK initialized, WebGL context created
400ms   — Viewport determined, first tile requests dispatched (9 center tiles)
600ms   — First tiles received from CDN (warm cache: 200ms, cold: 400ms)
700ms   — First tiles decoded and uploaded to GPU textures
800ms   — First frame rendered — user sees map ← FMP
1000ms  — Remaining buffer tiles loaded, markers fetched
1200ms  — Gesture handlers attached, search bar interactive
1500ms  — Full interactivity ← TTI

class TileRenderer {
  private gl: WebGL2RenderingContext;
  private tileProgram: WebGLProgram;
  private tileTextures: Map<string, WebGLTexture>;

  renderFrame(viewport: ViewportState, tiles: TileEntry[]): void {
    this.gl.clear(this.gl.COLOR_BUFFER_BIT);

    // Compute view-projection matrix from viewport
    const vpMatrix = this.computeViewProjection(viewport);

    // Sort tiles: lower zoom (background) first, then current zoom
    const sorted = this.sortByZoomThenDistance(tiles, viewport.center);

    for (const tile of sorted) {
      const texture = this.getOrUploadTexture(tile);
      const tileMatrix = this.computeTileMatrix(tile.coord, vpMatrix);

      this.gl.useProgram(this.tileProgram);
      this.gl.uniformMatrix4fv(this.mvpLocation, false, tileMatrix);
      this.gl.bindTexture(this.gl.TEXTURE_2D, texture);
      this.gl.drawArrays(this.gl.TRIANGLE_STRIP, 0, 4);
    }
  }

  /**
   * Convert tile coordinate to pixel position.
   * Slippy Map: pixel_x = (x * 256) - (viewport_x * 256)
   */
  private computeTileMatrix(
    coord: TileCoord,
    vpMatrix: Float32Array,
  ): Float32Array {
    const scale = Math.pow(2, coord.z);
    const tileSize = 256;
    const worldX = coord.x * tileSize;
    const worldY = coord.y * tileSize;
    // Apply world position offset then view-projection
    return mat4.translate(vpMatrix, [worldX, worldY, 0]);
  }
}

class VectorTileRenderer {
  /**
   * Vector tiles require tessellation (converting polygons to triangles)
   * and text shaping (placing labels along roads, deconflicting overlaps).
   *
   * Pipeline: MVT decode → Feature filter → Tessellate → Upload → Render
   *
   * Tessellation runs in a Web Worker to avoid blocking the main thread.
   */

  private workers: Worker[];
  private bucketCache: Map<string, RenderBucket>;

  async prepareTile(tile: VectorTileLayer[]): Promise<RenderBucket[]> {
    // Offload to worker pool
    const worker = this.getNextWorker();
    return new Promise((resolve) => {
      worker.postMessage({ type: "tessellate", layers: tile });
      worker.onmessage = (e) => resolve(e.data.buckets);
    });
  }
}

interface RenderBucket {
  layerName: string;
  vertexBuffer: Float32Array; // Tessellated geometry
  indexBuffer: Uint16Array;
  labelAnchors: LabelAnchor[]; // For text placement
  lineVertices: Float32Array; // For road/path rendering
}

/**
 * Supercluster builds a tree of clusters at each zoom level.
 * Time complexity: O(n) for initial build, O(log n) for viewport query.
 * Used by Mapbox GL, deck.gl, and most production map libraries.
 */
interface SuperclusterOptions {
  minZoom: number; // Default: 0
  maxZoom: number; // Default: 16 (beyond this, no clustering)
  radius: number; // Cluster radius in pixels: 40–80
  extent: number; // Tile extent: 512
  nodeSize: number; // KD-tree node size: 64
  minPoints: number; // Min points to form cluster: 2
}

class MarkerClusterEngine {
  private trees: KDBush[]; // One spatial index per zoom level

  /**
   * Build hierarchical cluster tree.
   * For 10K markers: ~15ms on modern hardware.
   */
  load(markers: MapMarker[]): void {
    // Zoom maxZoom+1: individual points
    let points = markers.map((m) => this.lngLatToPoint(m.position));

    for (let z = this.options.maxZoom; z >= this.options.minZoom; z--) {
      this.trees[z] = new KDBush(points);
      points = this.clusterAtZoom(points, z);
    }
  }

  /**
   * Query clusters visible in viewport.
   * Returns mix of individual markers and cluster nodes.
   */
  getClusters(
    bounds: LngLatBounds,
    zoom: number,
  ): (MapMarker | MarkerCluster)[] {
    const tree = this.trees[Math.floor(zoom)];
    const [minX, minY, maxX, maxY] = this.boundsToRange(bounds, zoom);
    const ids = tree.range(minX, minY, maxX, maxY);
    return ids.map((id) => this.points[id]);
  }

  private clusterAtZoom(points: ClusterPoint[], zoom: number): ClusterPoint[] {
    const radius =
      this.options.radius / (this.options.extent * Math.pow(2, zoom));
    const clustered: ClusterPoint[] = [];

    for (const point of points) {
      if (point.visited) continue;
      point.visited = true;

      const neighbors = this.trees[zoom + 1].within(point.x, point.y, radius);
      const cluster = this.mergePoints(point, neighbors);
      clustered.push(cluster);
    }
    return clustered;
  }
}

Map SDK bundle breakdown (target: < 150KB gzipped):

Core (always loaded):
  ├── Viewport math + projections:     8KB
  ├── Tile scheduler + cache:         12KB
  ├── WebGL renderer (shaders):       25KB
  ├── Gesture engine:                 10KB
  ├── Style spec parser:              15KB
  └── Base total:                     70KB gzipped

Lazy-loaded on demand:
  ├── Directions renderer:            15KB
  ├── Search/Geocoding UI:            12KB
  ├── Offline sync engine:            20KB
  ├── Vector tile decoder (PBF):      8KB
  ├── Marker clustering:              10KB
  ├── Street View bridge:             25KB
  └── Total lazy:                     90KB gzipped

Web Workers (loaded in worker context):
  ├── Vector tessellation worker:     30KB
  └── Label collision worker:         15KB

// Content-Security-Policy for map application
const cspDirectives = {
  "default-src": ["'self'"],
  "script-src": ["'self'", "'wasm-unsafe-eval'"], // WebAssembly for vector tile decoding
  "style-src": ["'self'", "'unsafe-inline'"], // Map styles require inline (canvas doesn't use DOM)
  "img-src": [
    "'self'",
    "https://*.tile.openstreetmap.org",
    "https://maps.googleapis.com",
    "data:",
    "blob:",
  ],
  "connect-src": [
    "'self'",
    "https://*.googleapis.com",
    "https://*.mapbox.com",
    "https://api.maptiler.com",
  ],
  "worker-src": ["'self'", "blob:"], // Web Workers for tessellation
  "child-src": ["'none'"],
  "frame-ancestors": ["'self'"], // Prevent clickjacking
};

/**
 * API keys are inherently exposed in client-side applications.
 * Defense-in-depth approach:
 */

// 1. HTTP Referrer restriction (server-side enforcement)
// Key only works from: *.yourdomain.com, localhost:*

// 2. Proxy through BFF to hide raw key
// Client calls: /api/tiles/{z}/{x}/{y}
// Server appends: ?key=ACTUAL_KEY and forwards to tile provider

// 3. Short-lived signed URLs for tile requests
interface SignedTileConfig {
  baseUrl: string;
  token: string; // Rotates every 60 minutes
  signature: string; // HMAC of baseUrl + timestamp
  expiresAt: number;
}

async function getSignedTileUrl(coord: TileCoord): Promise<string> {
  // Fetch fresh config every 55 minutes (5min buffer before expiry)
  const config = await this.getOrRefreshConfig();
  return `${config.baseUrl}/${coord.z}/${coord.x}/${coord.y}.mvt?token=${config.token}&sig=${config.signature}`;
}

// 4. Usage quotas with alerts
// Per-key daily limits: 100K tile loads, 10K geocode requests
// Alert at 80% threshold, block at 100%

/**
 * Geolocation data handling principles:
 * 1. Never persist precise location beyond session
 * 2. Coarsen location for analytics (round to 3 decimal places = ~100m)
 * 3. Allow user to override/spoof for privacy
 * 4. Clear location data on page unload
 */

function coarsenForAnalytics(position: LatLng): LatLng {
  return {
    lat: Math.round(position.lat * 1000) / 1000, // ~111m precision
    lng: Math.round(position.lng * 1000) / 1000,
  };
}

// Permission request is user-initiated only — never on page load
function requestLocation(): Promise<UserLocation> {
  // Only request after explicit user action (clicking "My Location" button)
  // navigator.geolocation.getCurrentPosition with:
  // - enableHighAccuracy: false initially (faster, less battery)
  // - timeout: 10000ms
  // - maximumAge: 60000ms (allow 1-min cached position)
}

/**
 * Priority queue prevents tile request flooding during rapid pan/zoom.
 * Maximum 6 concurrent tile requests (HTTP/2 connection limit per origin).
 * Cancellation of out-of-viewport requests on viewport change.
 */
class TileScheduler {
  private queue: PriorityQueue<TileRequest>;
  private active: Map<string, AbortController>;
  private maxConcurrent = 6;

  scheduleViewport(viewport: ViewportState): void {
    // Cancel all active requests for tiles no longer needed
    for (const [key, controller] of this.active) {
      if (!this.isTileInViewport(key, viewport)) {
        controller.abort();
        this.active.delete(key);
      }
    }

    // Compute needed tiles and enqueue by priority
    const needed = this.computeNeededTiles(viewport);
    for (const tile of needed) {
      if (!this.cache.has(tile) && !this.active.has(this.toKey(tile))) {
        this.queue.enqueue({
          coord: tile,
          priority: this.computePriority(tile, viewport),
        });
      }
    }

    this.drainQueue();
  }

  private computePriority(coord: TileCoord, viewport: ViewportState): number {
    // Priority: center tiles > edge tiles > buffer tiles
    // Priority: current zoom > parent zoom (placeholder) > child zoom
    const distFromCenter = this.distanceFromCenter(coord, viewport);
    const zoomDelta = Math.abs(coord.z - Math.round(viewport.zoom));
    return 100 - distFromCenter * 10 - zoomDelta * 20;
  }
}

/**
 * POI and geocoding requests are viewport-debounced.
 * Don't fire on every frame during pan — wait for gesture end.
 */
function createViewportObserver(
  callback: (bounds: LngLatBounds) => void,
  options: { debounceMs: number; minMovement: number },
) {
  let timeout: ReturnType<typeof setTimeout>;
  let lastBounds: LngLatBounds | null = null;

  return (bounds: LngLatBounds) => {
    if (
      lastBounds &&
      !hasMovedSignificantly(lastBounds, bounds, options.minMovement)
    ) {
      return;
    }
    clearTimeout(timeout);
    timeout = setTimeout(() => {
      lastBounds = bounds;
      callback(bounds);
    }, options.debounceMs);
  };
}

// Usage: fire POI fetch 300ms after pan ends, only if viewport moved > 20%
const poiFetcher = createViewportObserver(fetchPOIs, {
  debounceMs: 300,
  minMovement: 0.2, // 20% viewport change threshold
});

/**
 * Graceful degradation cascade:
 * WebGL → Canvas 2D → Static tile image
 * Vector tiles → Raster tiles → Cached tiles → Placeholder
 */

class RenderingFallback {
  private renderer: MapRenderer;

  initialize(): MapRenderer {
    if (this.supportsWebGL2()) {
      return new WebGL2Renderer();
    }
    if (this.supportsWebGL1()) {
      return new WebGL1Renderer();
    }
    if (this.supportsCanvas2D()) {
      console.warn("Map: Falling back to Canvas 2D — reduced performance");
      return new Canvas2DRenderer();
    }
    // Final fallback: server-side rendered static image
    return new StaticImageRenderer();
  }

  private supportsWebGL2(): boolean {
    const canvas = document.createElement("canvas");
    return canvas.getContext("webgl2") !== null;
  }
}

/**
 * Placeholder tile from parent zoom while loading:
 * If zoom 15 tile is loading, render zoom 14 parent tile scaled 2x.
 * Provides visual continuity during loading.
 */
function getPlaceholderTile(
  coord: TileCoord,
  cache: TileCache,
): TileEntry | null {
  for (let z = coord.z - 1; z >= Math.max(0, coord.z - 3); z--) {
    const parentCoord = {
      x: Math.floor(coord.x / Math.pow(2, coord.z - z)),
      y: Math.floor(coord.y / Math.pow(2, coord.z - z)),
      z,
    };
    const parent = cache.getSync(parentCoord);
    if (parent) return parent;
  }
  return null;
}

<div role="application" aria-label="Interactive map">
  <div role="region" aria-label="Map canvas" aria-roledescription="map">
    <canvas aria-hidden="true" /> {/* WebGL canvas is not accessible */}
    {/* Accessible map description — screen reader only */}
    <div className="sr-only" aria-live="polite" aria-atomic="true">
      Map showing {areaDescription}. Center: {centerAddress}. Zoom level {zoom}.{" "}
      {markerCount} points of interest visible.
    </div>
    {/* Keyboard-navigable marker list */}
    <ul role="listbox" aria-label="Map markers" className="sr-only">
      {visibleMarkers.map((marker) => (
        <li
          key={marker.id}
          role="option"
          aria-selected={marker.id === selectedId}
          tabIndex={0}
        >
          {marker.name}, {marker.category}, {distanceFromCenter(marker)}
        </li>
      ))}
    </ul>
  </div>
</div>

class MapAnnouncer {
  private liveRegion: HTMLElement;
  private debounceTimer: ReturnType<typeof setTimeout> | null = null;

  announceViewportChange(viewport: ViewportState): void {
    // Debounce: only announce after 500ms of no movement
    if (this.debounceTimer) clearTimeout(this.debounceTimer);
    this.debounceTimer = setTimeout(() => {
      const address = this.reverseGeocode(viewport.center);
      const markerCount = this.getVisibleMarkerCount(viewport);
      this.announce(
        `Map moved to ${address}. Zoom level ${Math.round(viewport.zoom)}. ` +
          `${markerCount} places visible.`,
      );
    }, 500);
  }

  announceRouteLoaded(route: Route): void {
    this.announce(
      `Route found. ${route.legs.length} legs. ` +
        `Total distance: ${formatDistance(route.distance)}. ` +
        `Estimated time: ${formatDuration(route.duration)}.`,
    );
  }

  private announce(message: string): void {
    this.liveRegion.textContent = message;
  }
}

const prefersReducedMotion = window.matchMedia(
  "(prefers-reduced-motion: reduce)",
).matches;

const animationConfig = prefersReducedMotion
  ? { inertia: false, zoomAnimation: false, panDuration: 0 }
  : { inertia: true, zoomAnimation: true, panDuration: 300 };

interface MapErrorEvent {
  type:
    | "tile_load_failure"
    | "webgl_context_lost"
    | "worker_crash"
    | "geolocation_error"
    | "api_error"
    | "oom_warning";
  timestamp: number;
  viewport: ViewportState;
  tileCoord?: TileCoord;
  httpStatus?: number;
  errorMessage: string;
  deviceMemory: number;
  connectionType: string;
  userAgent: string;
  sessionId: string;
}

class MapErrorReporter {
  private buffer: MapErrorEvent[] = [];
  private flushInterval = 10_000; // Batch every 10s

  report(event: Omit<MapErrorEvent, "timestamp" | "sessionId">): void {
    this.buffer.push({
      ...event,
      timestamp: Date.now(),
      sessionId: this.sessionId,
    });

    // Flush immediately for critical errors
    if (event.type === "webgl_context_lost" || event.type === "oom_warning") {
      this.flush();
    }
  }

  private async flush(): Promise<void> {
    if (this.buffer.length === 0) return;
    const batch = this.buffer.splice(0);

    // Use sendBeacon for reliability (survives page unload)
    navigator.sendBeacon("/api/telemetry/map-errors", JSON.stringify(batch));
  }
}