trails-cool/trails
1
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
trails/openspec/changes/multi-day-routes/proposal.md
Ullrich Schäfer 0a330e4466
Break up route-features into focused specs, add new changes 
Archive the monolithic route-features spec and replace with 9 focused
OpenSpec changes: multi-day-routes, waypoint-notes (with POI snapping),
undo-redo, local-dev-stack, route-sharing, route-discovery,
activity-photos, osm-overlays, plus the existing changelog and
komoot-import.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-29 09:53:41 +02:00

3.6 KiB
Raw Blame History

Why

Long routes -- multi-day bike tours, thru-hikes, extended backpacking trips -- are flat lists of waypoints with no structure. Users planning a 5-day ride from Berlin to Prague have no way to mark where each day ends, see per-day distance and climbing, or reason about daily effort. They resort to external spreadsheets or mental arithmetic to divide the route into manageable stages.

The Planner already computes total distance and elevation across the full route. Adding day structure is a matter of marking overnight stops on existing waypoints and deriving per-day stats from the segment data we already have.

What Changes

  • Day-break waypoints: Any waypoint can be toggled as an overnight stop. This adds an overnight: true flag to the waypoint's Y.Map in the existing Yjs waypoints array. First and last waypoints are implicit day boundaries.
  • Per-day stats: Distance, total ascent, and estimated duration computed per day by splitting the route at overnight waypoints. Derived from the existing segmentBoundaries and coordinates in the enriched route data.
  • Sidebar day breakdown: Waypoints grouped by day with collapsible sections, per-day stats, and overnight toggle. Day 1 expanded by default.
  • Elevation chart day dividers: Dashed vertical lines at day boundaries with "Day N" labels.
  • Map day labels: White pill markers on the route at day boundaries showing "Day 1 . 120 km".
  • GPX export: Day-break waypoints exported with a <type>overnight</type> element so the structure survives round-trips.

All state lives in Yjs. No database changes are needed -- the Planner remains stateless. The visual design is already specified in the visual-redesign change (D4 sidebar, D5 map markers, D6 elevation chart); this spec covers the data model, computation logic, and integration wiring.

Capabilities

New Capabilities

  • multi-day-routes: Overnight waypoint markers, per-day stats computation, day-aware sidebar/chart/map display, multi-day GPX export

Modified Capabilities

  • planner-session: Waypoints gain an overnight property in Yjs state
  • map-display: Day boundary labels on route, overnight marker styling
  • gpx-export: Day-break metadata in exported GPX waypoints

Non-Goals

  • Automatic day splitting: No algorithm to suggest where to stop. Users decide manually. This avoids opinionated defaults and keeps the logic simple.
  • Accommodation search: No POI lookup for campsites or hotels. Out of scope.
  • Per-day routing profiles: All days use the same BRouter profile. Supporting different profiles per day would require rearchitecting the routing pipeline.
  • Journal integration: Saving multi-day routes to the Journal is a separate concern (route-features change). This spec is Planner-only.

Impact

  • Yjs state: overnight boolean added to waypoint Y.Map entries (additive, backwards-compatible -- existing sessions without it behave as single-day)
  • Shared types: Waypoint.isDayBreak already exists in @trails-cool/types but is unused. This change activates it.
  • New utility: compute-days.ts -- pure function that splits route data at overnight waypoints and returns per-day stats
  • Sidebar: WaypointSidebar.tsx gains day-grouped view with collapsible sections and overnight toggle buttons
  • ElevationChart: Canvas drawing extended with vertical day dividers
  • Map: New day-label layer and overnight marker variant
  • GPX: generateGpx extended to emit <type>overnight</type> on day-break waypoints
  • i18n: New keys for day labels, overnight toggle, per-day stats (en + de)