trails/openspec/changes/archive/2026-03-26-planner-route-interactions/design.md

Context

The Planner currently renders routes as a single-color L.Polyline with no interactivity — users can't click on the route or drag it. Waypoints can only be appended (click on map) or reordered in the sidebar. BRouter returns per-point elevation in coordinates ([lon, lat, ele]) and can return surface tags, but mergeGeoJsonSegments currently discards all per-point data and only keeps track-level totals.

bikerouter.de and komoot both support click-to-split and drag-to-reshape as primary editing interactions. These are the most natural way to refine a route after the initial waypoints are placed.

Goals / Non-Goals

Goals:

• Hover over the route to see a transient ghost marker at the nearest route point
• Click or drag the ghost marker to insert a waypoint (split / reshape)
• Color the route by elevation gradient (green→yellow→red) or surface type
• Sync elevation chart colors with route coloring in elevation mode
• Preserve per-point data from BRouter through the merge pipeline
• All interactions synced via Yjs (collaborative)

Non-Goals:

• Undo/redo system (future change)
• Route alternatives (show multiple options)
• Custom color gradient configuration
• Surface type legend or detailed surface info panel
• Offline route coloring (requires BRouter data)

Decisions

D1: Ghost marker interaction (inspired by brouter-web)

Following brouter-web's L.Routing.Edit pattern: a single persistent draggable Marker (RouteInteraction component) that appears when the cursor is near the route and can be clicked or dragged to insert a waypoint.

Key techniques from brouter-web:

• Distance-based snap: Listen on map.mousemove, compute pixel distance to nearest route coordinate (15px tolerance). No reliance on SVG polyline mouseout events (which cause flickering).
• Single reusable marker: Created once via L.marker({ draggable: true }), shown/hidden with addTo(map)/remove(). Not destroyed/recreated on each hover.
• Dragging guard: draggingRef flag freezes snap updates during drag and prevents hide-on-mouseout.
• Leaflet's built-in drag: draggable: true on the Marker uses Leaflet's L.Draggable which automatically calls L.DomUtil.disableTextSelection() during drag and re-enables on dragend.
• Trailer lines: Two persistent dashed L.Polyline instances shown during drag, connecting the ghost to adjacent waypoints for visual feedback.

Alternative considered and rejected: Fixed midpoint CircleMarkers between waypoints. Caused flickering (render loop between marker and polyline events), required zoom threshold to avoid clutter, and CircleMarker SVG rendering was unreliable in react-leaflet after programmatic zoom.

Alternative considered and rejected: Invisible wide polyline for click detection. Playwright couldn't trigger mousemove events on SVG paths with opacity 0. The map-level listener with distance-based snap is more reliable.

D2: Per-point data preservation in BRouter response

BRouter GeoJSON coordinates are [lon, lat, ele]. For surface data, BRouter's tiledesc=true parameter includes per-point WayTags in the properties.messages array (e.g., surface=asphalt highway=primary).

mergeGeoJsonSegments now:

1. Preserves full 3D coordinates [lon, lat, ele]
2. Tracks segment boundary indices (where each waypoint segment starts)
3. Extracts surface type per point from WayTags via regex

The EnrichedRoute interface:

interface EnrichedRoute {
  coordinates: [number, number, number][]; // [lon, lat, ele]
  segmentBoundaries: number[];             // coordinate index where each segment starts
  surfaces: string[];                      // surface type per point (from WayTags)
  totalLength: number;
  totalAscend: number;
  totalTime: number;
  geojson: GeoJsonCollection;              // backwards compat
}

All enriched data is stored in routeData Y.Map (as JSON strings) so all participants receive it.

D3: Colored route rendering with segmented polylines

ColoredRoute component renders multiple L.Polyline segments colored by per-point data. Three modes toggled via a <select> in the session header, synced via Yjs routeData.colorMode:

1. Plain: Single-color blue polyline (default)
2. Elevation: green→yellow→red gradient normalized to route elevation range
3. Surface: Fixed color palette per surface type (asphalt=gray, gravel=brown, path=green, track=orange, etc.). Falls back to plain if surface data unavailable.

D4: Elevation chart color sync

ElevationChart reads colorMode from Yjs and uses the same elevationColor() function as ColoredRoute when in elevation mode. Each chart segment is drawn with the corresponding elevation color for both the fill and line.

D5: Map click suppression

When the ghost marker click or drag inserts a waypoint, a suppressMapClickRef flag prevents the subsequent MapClickHandler from also appending a waypoint. This solves the Leaflet event model issue where map click fires independently from layer click.

Risks / Trade-offs

• Performance with many segments → Hundreds of small L.Polyline instances for colored rendering could be slow. Can switch to canvas if needed later.
• BRouter surface data availability → Not all BRouter profiles return surface tags. Surface coloring falls back to plain when data is missing.
• Snap precision → Distance-based snap at 15px works well at typical zoom levels. On very dense routes, the nearest coordinate might be slightly off from the visual route line.
• Playwright E2E limitations → Ghost marker hover can't be reliably tested via Playwright's mouse simulation on Leaflet SVG. Verified visually via cmux browser instead.