# LiveView Map

## Overview

**Module:** `AprsmeWeb.MapLive.Index` (~2050 lines, the largest LiveView)
**Routes:** `/` (main map), `/:callsign` (tracked station)

The map is the primary user interface — a real-time Leaflet-based map displaying live APRS station positions, trails, weather data, and station information.

## MapLive Architecture

`MapLive.Index` is supported by 12 submodules under `lib/aprsme_web/live/map_live/`:

```
MapLive.Index
├── Components       — Reusable UI (map container, slideover panel, packet list)
├── PopupComponent   — Marker popup rendering (callsign, weather, timestamp)
├── DataBuilder      — Constructs map data payloads for JS hooks
├── DisplayManager   — Manages what's shown on map (stations, trails, clusters)
├── HistoricalLoader — Loads historical packet data for selected station
├── Navigation       — Determines map center/zoom from URL params
├── PacketBatcher    — Batches incoming real-time packets for rendering
├── PacketProcessor  — Processes raw packets into display-ready data
├── RfPath           — RF path visualization (digipeater hops)
├── UrlParams        — URL parameter sync with map state
└── (Plus shared modules in live/shared/)
```

## Real-Time Updates

MapLive subscribes to:
- `StreamingPacketsPubSub` — viewport-filtered new packets
- `SpatialPubSub` — grid-indexed spatial delivery
- Phoenix PubSub topics for callsign-specific updates

Updates are batched via `PacketBatcher` to reduce DOM operations, then pushed to the Leaflet client via `push_event` (e.g., `"update_markers"`, `"update_clusters"`).

## Client-Side

The `APRSMap` JavaScript hook (`assets/js/map.ts`) handles:
- Leaflet map initialization with multiple tile layers
- Marker management (add, update, remove)
- Marker clustering at lower zoom levels
- Trail line rendering (`trail_manager.ts`)
- Viewport change tracking (pushed back to server for subscription bounds)
- URL parameter sync (center, zoom)

## Lazy Loading

The map bundle (Leaflet + plugins, ~300KB) is loaded only when a map page is visited, via `VendorLoader.loadMap()` in `assets/js/app.ts`. Non-map pages never download it.

## Key Features

### Station Tracking
When visiting `/:callsign`, the map centers on that station and subscribes to its specific PubSub topic. A slideover panel shows station details.

### Trail Lines
Historical path of a station rendered as a polyline on the map. See [trail-line-visualization.md](../features/trail-line-visualization.md).

### RF Path
Digipeater hop visualization showing the path an APRS packet took through the network.

### Heatmap Clustering
At low zoom levels (≤8), individual markers are replaced by grid-based heatmap clusters via `Packets.Clustering` for performance.

### Weather Overlay
Weather station markers with temperature/wind indicators. Clicking opens a popup with current conditions, linking to the full weather page.

## Slideover Panel

When a station is selected, a slideover panel displays:
- Latest position and timestamp
- Course, speed, altitude
- Device/manufacturer info
- Link to full info page (`/info/:callsign`)
- Link to packet history (`/packets/:callsign`)
- Weather data (if weather station)

## URL State

Map state (center, zoom, selected callsign) is synced to URL query parameters via `UrlParams`, enabling shareable map views and browser back/forward navigation.