Add route interactions: click-to-split, drag-to-reshape, colored route rendering
- Enrich BRouter response with per-point 3D coordinates and segment boundary tracking (EnrichedRoute interface) - ColoredRoute component: plain, elevation gradient (green→yellow→red), and surface color modes with invisible wide polyline for click targeting - Click-to-split: click on route polyline inserts waypoint at nearest point, mapped to correct segment via boundary indices - MidpointHandles: draggable CircleMarkers at route segment midpoints for reshaping, hidden below zoom 12, opaque on hover - Color mode toggle (select) synced via Yjs routeData - i18n keys for color mode labels (en + de) - Unit tests for segment boundary tracking (13 tests) - E2E tests for enriched route response and color mode toggle Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ullrich Schäfer
parent
5aef99b5ce
commit
ba044610b7
43 changed files with 533 additions and 285 deletions
|
|
@ -0,0 +1,2 @@
|
|||
schema: spec-driven
|
||||
created: 2026-03-25
|
||||
|
|
@ -0,0 +1,74 @@
|
|||
## Context
|
||||
|
||||
The Planner architecture defines noGoAreas, notes, and crash recovery in the
|
||||
Yjs data model but none are implemented. The public instance also lacks rate
|
||||
limiting — anyone can create unlimited sessions or hammer BRouter.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Draw no-go polygons on the map, synced via Yjs, sent to BRouter
|
||||
- Shared notes (Y.Text) visible in sidebar for planning discussion
|
||||
- localStorage backup of Yjs state, merged on reconnect
|
||||
- Rate limits: 10 sessions/IP/hour, 60 BRouter calls/session/hour
|
||||
|
||||
**Non-Goals:**
|
||||
- Complex polygon editing (holes, multi-polygon) — just simple polygons
|
||||
- Rich text in notes (just plain text)
|
||||
- Cross-tab Yjs sync via localStorage (handled by WebSocket)
|
||||
- Rate limiting dashboard or admin UI
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1: No-go areas as Yjs Y.Array of polygon coordinates
|
||||
|
||||
```typescript
|
||||
// Yjs doc structure addition
|
||||
noGoAreas: Y.Array<Y.Map<{
|
||||
points: Array<{lat: number, lon: number}>,
|
||||
name?: string
|
||||
}>>
|
||||
```
|
||||
|
||||
Each polygon is a closed ring of lat/lon points. BRouter accepts no-go areas
|
||||
as a `nogo` parameter: `lon,lat,radius` for circles or polygon coordinates
|
||||
depending on the BRouter version. We'll convert our polygons to BRouter's
|
||||
expected format in the routing request.
|
||||
|
||||
### D2: Leaflet.draw for polygon drawing
|
||||
|
||||
Use `leaflet-draw` (or `@geoman-io/leaflet-geoman-free`) for drawing polygons
|
||||
on the map. When a polygon is completed, add it to the Y.Array. Existing
|
||||
polygons render as semi-transparent red overlays.
|
||||
|
||||
### D3: Notes as Y.Text in sidebar tab
|
||||
|
||||
Add a "Notes" tab to the sidebar (alongside waypoints). Uses Y.Text for
|
||||
collaborative editing — simple textarea bound to Y.Text. Changes sync in
|
||||
real-time. No markdown rendering — plain text only.
|
||||
|
||||
### D4: localStorage crash recovery
|
||||
|
||||
Every 10 seconds, save `Y.encodeStateAsUpdate(doc)` to
|
||||
`localStorage['trails:session:${id}']`. On page load, if localStorage has
|
||||
state for the current session, apply it as an update before connecting to
|
||||
the server. Yjs CRDTs merge automatically — no conflicts.
|
||||
|
||||
Clear localStorage entry when session is closed or after successful sync.
|
||||
|
||||
### D5: In-memory rate limiter
|
||||
|
||||
Simple Map-based rate limiter in `server.ts`:
|
||||
- Session creation: Track IP → count + window. Reject with 429 after 10/hour.
|
||||
- BRouter proxy: Track session ID → count + window. Reject after 60/hour.
|
||||
- No Redis needed — single server, in-memory is fine. Resets on restart
|
||||
(acceptable).
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **leaflet-draw adds bundle size** → ~50KB gzipped. Acceptable for polygon
|
||||
drawing functionality. Can lazy-load.
|
||||
- **localStorage size limit** → ~5MB per origin. Yjs state is typically
|
||||
10-100KB. No risk.
|
||||
- **In-memory rate limiter resets on deploy** → Acceptable for current scale.
|
||||
Redis-backed when needed.
|
||||
|
|
@ -0,0 +1,40 @@
|
|||
## Why
|
||||
|
||||
The Planner's core editing works but is missing features from the architecture
|
||||
doc: no-go areas for route avoidance, session notes for collaborative planning
|
||||
communication, localStorage crash recovery for unsaved work, and rate limiting
|
||||
to protect the BRouter API from abuse on the public instance.
|
||||
|
||||
## What Changes
|
||||
|
||||
- **No-go areas**: Draw polygons on the map that BRouter avoids when computing
|
||||
routes. Stored as Y.Array in the Yjs doc, synced across participants.
|
||||
- **Session notes**: Shared text area (Y.Text) for participants to leave notes,
|
||||
discuss the route, or plan logistics. Visible in the sidebar.
|
||||
- **Crash recovery**: Periodically save Yjs state to localStorage. On
|
||||
reconnect, merge local state with server state to recover unsaved changes.
|
||||
- **Rate limiting**: Limit session creation per IP and BRouter API calls per
|
||||
session to prevent abuse on the public instance.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `no-go-areas`: Draw avoidance polygons on the Planner map, passed to BRouter as routing constraints
|
||||
- `session-notes`: Shared collaborative text in Planner sessions via Yjs Y.Text
|
||||
- `crash-recovery`: localStorage backup of Yjs state for reconnection after browser crash
|
||||
- `rate-limiting`: IP-based limits on session creation and route computation
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `planner-session`: Session data model gains noGoAreas and notes fields
|
||||
- `brouter-integration`: Routing requests include no-go area polygons
|
||||
- `map-display`: Map gains polygon drawing tools for no-go areas
|
||||
|
||||
## Impact
|
||||
|
||||
- **Planner Yjs doc**: New fields (noGoAreas: Y.Array, notes: Y.Text)
|
||||
- **BRouter API**: No-go areas passed as `nogo` parameter
|
||||
- **Map**: Leaflet.draw or custom polygon tool for no-go areas
|
||||
- **Dependencies**: May need `leaflet-draw` for polygon editing
|
||||
- **Server**: Rate limiting middleware (in-memory store)
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: BRouter routing with constraints
|
||||
Route computation SHALL include no-go area polygons as avoidance constraints.
|
||||
|
||||
#### Scenario: Route with no-go areas
|
||||
- **WHEN** the routing host computes a route and no-go areas exist
|
||||
- **THEN** the BRouter request includes nogo parameters for each polygon
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
## ADDED Requirements
|
||||
|
||||
### Requirement: localStorage crash recovery
|
||||
The Planner SHALL periodically save Yjs state to localStorage and recover it on reconnect.
|
||||
|
||||
#### Scenario: Browser crash recovery
|
||||
- **WHEN** a user's browser crashes and they reopen the session
|
||||
- **THEN** unsaved changes from localStorage are merged with the server state
|
||||
|
||||
#### Scenario: Clean exit
|
||||
- **WHEN** a session syncs successfully
|
||||
- **THEN** the localStorage backup is cleared
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Map polygon drawing
|
||||
The Planner map SHALL support drawing and displaying no-go area polygons.
|
||||
|
||||
#### Scenario: Polygon tool
|
||||
- **WHEN** a user activates the no-go area tool
|
||||
- **THEN** they can draw a polygon by clicking points on the map
|
||||
|
||||
#### Scenario: Polygon display
|
||||
- **WHEN** no-go areas exist in the session
|
||||
- **THEN** they are rendered as semi-transparent red polygons on the map
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
## ADDED Requirements
|
||||
|
||||
### Requirement: Draw no-go areas
|
||||
Users SHALL be able to draw polygons on the map that BRouter avoids when computing routes.
|
||||
|
||||
#### Scenario: Draw polygon
|
||||
- **WHEN** a user activates the no-go area tool and draws a polygon on the map
|
||||
- **THEN** the polygon is added to the Yjs doc and visible to all participants
|
||||
|
||||
#### Scenario: Route avoids no-go area
|
||||
- **WHEN** a route is computed and a no-go area intersects the direct path
|
||||
- **THEN** BRouter routes around the no-go area
|
||||
|
||||
#### Scenario: Delete no-go area
|
||||
- **WHEN** a user deletes a no-go area polygon
|
||||
- **THEN** it is removed from the Yjs doc and the route is recomputed
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Planner session data model
|
||||
The Yjs document SHALL include noGoAreas and notes fields alongside waypoints and routeData.
|
||||
|
||||
#### Scenario: Session with all fields
|
||||
- **WHEN** a Planner session is active
|
||||
- **THEN** the Yjs doc contains: waypoints (Y.Array), routeData (Y.Map), noGoAreas (Y.Array), notes (Y.Text)
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
## ADDED Requirements
|
||||
|
||||
### Requirement: Session creation rate limit
|
||||
The Planner SHALL limit session creation to 10 per IP per hour.
|
||||
|
||||
#### Scenario: Rate limit exceeded
|
||||
- **WHEN** an IP creates more than 10 sessions in one hour
|
||||
- **THEN** the server responds with 429 Too Many Requests
|
||||
|
||||
### Requirement: BRouter call rate limit
|
||||
The Planner SHALL limit route computations to 60 per session per hour.
|
||||
|
||||
#### Scenario: Routing rate limit exceeded
|
||||
- **WHEN** a session exceeds 60 BRouter calls in one hour
|
||||
- **THEN** the server responds with 429 and the client shows a "slow down" message
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
## ADDED Requirements
|
||||
|
||||
### Requirement: Collaborative session notes
|
||||
Planner sessions SHALL have a shared text area for participants to write notes.
|
||||
|
||||
#### Scenario: Write notes
|
||||
- **WHEN** a user types in the notes area
|
||||
- **THEN** the text syncs in real-time to all other participants via Yjs
|
||||
|
||||
#### Scenario: Notes persist
|
||||
- **WHEN** a user leaves and rejoins a session
|
||||
- **THEN** the notes are still there (stored in Yjs doc)
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
## 1. No-Go Areas
|
||||
|
||||
- [x] 1.1 Add `noGoAreas` Y.Array to Yjs doc in use-yjs.ts
|
||||
- [x] 1.2 Add leaflet-draw (or geoman) dependency for polygon drawing
|
||||
- [x] 1.3 Create NoGoAreaLayer component — renders polygons as red overlays, handles draw/delete
|
||||
- [x] 1.4 Add no-go area toolbar button to PlannerMap
|
||||
- [x] 1.5 Pass no-go areas to BRouter API as `nogo` parameters in brouter.ts
|
||||
- [x] 1.6 Trigger route recomputation when no-go areas change
|
||||
|
||||
## 2. Session Notes
|
||||
|
||||
- [x] 2.1 Add `notes` Y.Text to Yjs doc in use-yjs.ts
|
||||
- [x] 2.2 Create NotesPanel component — textarea bound to Y.Text with real-time sync
|
||||
- [x] 2.3 Add "Notes" tab to sidebar (alongside waypoints)
|
||||
- [x] 2.4 Add i18n keys for notes UI (en + de)
|
||||
|
||||
## 3. Crash Recovery
|
||||
|
||||
- [x] 3.1 Add periodic localStorage save (every 10s) of Yjs state in use-yjs.ts
|
||||
- [x] 3.2 On session reconnect, check localStorage for saved state and apply as Yjs update
|
||||
- [x] 3.3 Clear localStorage entry after successful sync or session close
|
||||
- [x] 3.4 Write unit test for save/restore logic
|
||||
|
||||
## 4. Rate Limiting
|
||||
|
||||
- [x] 4.1 Create rate limiter utility in apps/planner/app/lib/rate-limit.ts (already exists — extend for IP tracking)
|
||||
- [x] 4.2 Add session creation rate limit (10/IP/hour) in the /new route or API
|
||||
- [x] 4.3 Add BRouter proxy rate limit (60/session/hour) in the route computation handler
|
||||
- [x] 4.4 Return 429 with Retry-After header and show user-friendly message on client
|
||||
|
||||
## 5. Verify
|
||||
|
||||
- [x] 5.1 Test no-go areas: draw polygon, verify route avoids it, delete polygon
|
||||
- [x] 5.2 Test notes: type in two windows, verify real-time sync
|
||||
- [x] 5.3 Test crash recovery: make changes, kill browser, reopen — verify recovery
|
||||
- [x] 5.4 Test rate limiting: exceed limits, verify 429 response
|
||||
|
|
@ -0,0 +1,2 @@
|
|||
schema: spec-driven
|
||||
created: 2026-03-26
|
||||
|
|
@ -0,0 +1,127 @@
|
|||
## 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:
|
||||
|
||||
```typescript
|
||||
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.
|
||||
|
|
@ -0,0 +1,54 @@
|
|||
## Why
|
||||
|
||||
The Planner's route editing is click-only: users place waypoints and the route
|
||||
auto-computes between them. But refining a route is tedious — you can't insert
|
||||
a waypoint on the route itself, drag a route segment to reshape it, or see what
|
||||
kind of terrain you're heading into. These are table-stakes features in modern
|
||||
route planners (bikerouter.de, komoot, Ride with GPS) and the most common
|
||||
feedback from early testers.
|
||||
|
||||
## What Changes
|
||||
|
||||
- **Route splitting**: Hover near the route to see a ghost marker at the nearest
|
||||
point. Click it to insert a new waypoint, splitting the segment. The waypoint
|
||||
snaps to the closest coordinate on the existing route.
|
||||
- **Drag-to-reshape**: Drag the ghost marker to a new position to reshape the
|
||||
route. Dashed trailer lines connect to adjacent waypoints during drag.
|
||||
Inspired by brouter-web's single-persistent-marker pattern.
|
||||
- **Colored route rendering**: Replace the single-color route polyline with
|
||||
segments colored by elevation gradient or surface type (from BRouter's
|
||||
per-point data). Users toggle between plain, elevation, and surface color
|
||||
modes. Elevation chart syncs with route colors in elevation mode.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `route-splitting`: Insert waypoints by clicking the ghost marker on the route,
|
||||
with snapping to the nearest route coordinate
|
||||
- `route-drag-reshape`: Drag the ghost marker to reshape the route interactively
|
||||
with trailer lines and text selection prevention
|
||||
- `route-coloring`: Color-code the route polyline by elevation gradient or
|
||||
surface type using BRouter tiledesc data, with elevation chart color sync
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `map-display`: Route visualization changes from a single-color polyline to
|
||||
a segmented, interactive polyline with color modes and ghost marker interaction
|
||||
- `brouter-integration`: BRouter requests include `tiledesc=true`; response data
|
||||
(elevation, surface tags, segment boundaries) preserved in EnrichedRoute
|
||||
|
||||
## Impact
|
||||
|
||||
- **PlannerMap.tsx**: Route polyline becomes interactive via RouteInteraction
|
||||
component with ghost marker, map click suppression
|
||||
- **brouter.ts**: EnrichedRoute with per-point 3D coordinates, segment
|
||||
boundaries, and surface types extracted from BRouter tiledesc WayTags
|
||||
- **use-routing.ts**: Stores enriched data (coordinates, boundaries, surfaces)
|
||||
in Yjs routeData map
|
||||
- **New components**: RouteInteraction (ghost marker + drag), ColoredRoute
|
||||
(segmented polyline renderer)
|
||||
- **ElevationChart**: Uses same `elevationColor()` gradient as route in
|
||||
elevation mode
|
||||
- **Dependencies**: No new dependencies (uses Leaflet's built-in L.Draggable)
|
||||
- **i18n**: New keys for color mode labels (en + de)
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Route computation from waypoints
|
||||
The Planner SHALL compute a route between ordered waypoints by calling the BRouter HTTP API with tiledesc enabled and returning the result as an EnrichedRoute, preserving per-point elevation, surface data, and segment boundary indices.
|
||||
|
||||
#### Scenario: Compute route with two waypoints
|
||||
- **WHEN** the routing host submits two waypoints (start, end) with profile "trekking"
|
||||
- **THEN** the BRouter API returns a route within 2 seconds
|
||||
|
||||
#### Scenario: Compute route with via points
|
||||
- **WHEN** the routing host submits three or more waypoints
|
||||
- **THEN** the BRouter API returns a route passing through all waypoints in order
|
||||
|
||||
#### Scenario: Per-point elevation preserved
|
||||
- **WHEN** BRouter returns GeoJSON with 3D coordinates [lon, lat, ele]
|
||||
- **THEN** the merged route response SHALL preserve elevation values for every coordinate point
|
||||
|
||||
#### Scenario: Segment boundaries tracked
|
||||
- **WHEN** a route with N waypoints is computed (N-1 segments)
|
||||
- **THEN** the response SHALL include an array of coordinate indices marking where each waypoint-to-waypoint segment begins
|
||||
|
||||
#### Scenario: Surface data extracted
|
||||
- **WHEN** BRouter returns tiledesc messages with WayTags containing surface information
|
||||
- **THEN** the response SHALL include a surface type string per coordinate point extracted from the WayTags (e.g., "asphalt", "gravel", "path")
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Route visualization
|
||||
The map SHALL display the computed route as an interactive, optionally color-coded polyline on the map.
|
||||
|
||||
#### Scenario: Display route
|
||||
- **WHEN** BRouter returns a route GeoJSON
|
||||
- **THEN** the route is rendered as a polyline on the map, colored according to the active color mode
|
||||
|
||||
#### Scenario: Route updates on waypoint change
|
||||
- **WHEN** a waypoint is added, moved, or deleted
|
||||
- **THEN** the route polyline updates after BRouter recomputes the route
|
||||
|
||||
#### Scenario: Ghost marker on hover
|
||||
- **WHEN** the cursor is within 15 pixels of the route polyline
|
||||
- **THEN** a transient ghost marker appears at the nearest route point, which can be clicked or dragged to insert a waypoint (see route-splitting and route-drag-reshape specs)
|
||||
|
|
@ -0,0 +1,42 @@
|
|||
## ADDED Requirements
|
||||
|
||||
### Requirement: Route color modes
|
||||
The Planner SHALL support multiple route color modes that visualize per-point data along the route.
|
||||
|
||||
#### Scenario: Default plain mode
|
||||
- **WHEN** a route is first displayed
|
||||
- **THEN** it renders as a single-color blue polyline (current behavior)
|
||||
|
||||
#### Scenario: Elevation color mode
|
||||
- **WHEN** a user selects the "Elevation" color mode
|
||||
- **THEN** the route polyline is colored with a gradient from green (low) through yellow (mid) to red (high), based on the elevation at each point
|
||||
|
||||
#### Scenario: Surface color mode
|
||||
- **WHEN** a user selects the "Surface" color mode and surface data is available from BRouter tiledesc
|
||||
- **THEN** the route polyline is colored by surface type (e.g., asphalt=gray, gravel=brown, path=green, track=orange)
|
||||
|
||||
#### Scenario: Surface data unavailable
|
||||
- **WHEN** a user selects "Surface" color mode but BRouter did not return surface data
|
||||
- **THEN** the route falls back to plain color mode
|
||||
|
||||
### Requirement: Color mode toggle
|
||||
The Planner SHALL provide a UI control to switch between route color modes.
|
||||
|
||||
#### Scenario: Toggle control location
|
||||
- **WHEN** a route is displayed
|
||||
- **THEN** a color mode select dropdown is visible in the session header
|
||||
|
||||
#### Scenario: Color mode persists in session
|
||||
- **WHEN** a user changes the color mode
|
||||
- **THEN** the selection is stored in the Yjs routeData map and synced to all participants
|
||||
|
||||
### Requirement: Elevation chart color sync
|
||||
The elevation profile chart SHALL use the same color gradient as the route when in elevation mode.
|
||||
|
||||
#### Scenario: Elevation mode chart coloring
|
||||
- **WHEN** the color mode is set to "Elevation"
|
||||
- **THEN** the elevation chart line and fill use the same green→yellow→red gradient as the route polyline
|
||||
|
||||
#### Scenario: Plain mode chart coloring
|
||||
- **WHEN** the color mode is "Plain" or "Surface"
|
||||
- **THEN** the elevation chart uses the default blue color
|
||||
|
|
@ -0,0 +1,28 @@
|
|||
## ADDED Requirements
|
||||
|
||||
### Requirement: Ghost marker on route hover
|
||||
The Planner SHALL display a transient ghost marker when the cursor is near the route polyline, allowing users to reshape the route by dragging.
|
||||
|
||||
#### Scenario: Ghost marker appears on hover
|
||||
- **WHEN** the cursor moves within 15 pixels of the route polyline
|
||||
- **THEN** a ghost marker (small blue circle) appears at the nearest route coordinate point
|
||||
|
||||
#### Scenario: Ghost marker disappears on leave
|
||||
- **WHEN** the cursor moves more than 15 pixels away from the route polyline
|
||||
- **THEN** the ghost marker disappears
|
||||
|
||||
#### Scenario: Drag ghost marker to reshape
|
||||
- **WHEN** a user drags the ghost marker to a new position
|
||||
- **THEN** a new waypoint is inserted between the two adjacent waypoints of the hovered segment, and the route recomputes through the new point
|
||||
|
||||
#### Scenario: Trailer lines during drag
|
||||
- **WHEN** a user is dragging the ghost marker
|
||||
- **THEN** dashed guide lines are shown connecting the ghost marker to the adjacent waypoints
|
||||
|
||||
#### Scenario: No text selection during drag
|
||||
- **WHEN** a user drags the ghost marker
|
||||
- **THEN** text selection is disabled on the page (via Leaflet's built-in L.Draggable)
|
||||
|
||||
#### Scenario: Reshape syncs to other participants
|
||||
- **WHEN** a user reshapes the route by dragging the ghost marker
|
||||
- **THEN** all other participants see the new waypoint and recomputed route via Yjs sync
|
||||
|
|
@ -0,0 +1,20 @@
|
|||
## ADDED Requirements
|
||||
|
||||
### Requirement: Insert waypoint by clicking on route
|
||||
The Planner SHALL allow users to insert a new waypoint by clicking the ghost marker that appears when hovering near the route.
|
||||
|
||||
#### Scenario: Click ghost marker to split
|
||||
- **WHEN** a ghost marker is visible on the route and the user clicks it
|
||||
- **THEN** a new waypoint is inserted at the ghost marker position between the appropriate adjacent waypoints, and the route recomputes
|
||||
|
||||
#### Scenario: Waypoint snaps to route
|
||||
- **WHEN** the ghost marker appears near the route
|
||||
- **THEN** it is positioned at the closest coordinate point on the existing route geometry, not at the raw cursor position
|
||||
|
||||
#### Scenario: No duplicate waypoint from map click
|
||||
- **WHEN** a user clicks the ghost marker to insert a waypoint
|
||||
- **THEN** the map click handler is suppressed so only one waypoint is inserted (not an additional one appended at the end)
|
||||
|
||||
#### Scenario: Split syncs to other participants
|
||||
- **WHEN** a user inserts a waypoint by clicking the ghost marker
|
||||
- **THEN** all other participants see the new waypoint appear in the waypoint list and on the map via Yjs sync
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
## 1. BRouter Data Pipeline
|
||||
|
||||
- [x] 1.1 Modify `mergeGeoJsonSegments` to preserve 3D coordinates (lon, lat, ele) and track segment boundary indices
|
||||
- [x] 1.2 Add `EnrichedRoute` interface with coordinates, segmentBoundaries, surfaces, and stats
|
||||
- [x] 1.3 Store enriched route data (including segment boundaries and surfaces) in Yjs routeData map
|
||||
- [x] 1.4 Add `tiledesc=true` to BRouter requests and extract surface types from WayTags messages
|
||||
- [x] 1.5 Write unit test for segment boundary tracking across multi-waypoint routes
|
||||
|
||||
## 2. Route Interaction (ghost marker)
|
||||
|
||||
- [x] 2.1 Create `RouteInteraction` component — single persistent draggable Marker following brouter-web pattern
|
||||
- [x] 2.2 Listen on `map.mousemove`, snap ghost marker to nearest route point within 15px tolerance (distance-based, not polyline events)
|
||||
- [x] 2.3 On click, insert waypoint at snapped position using segment boundary lookup
|
||||
- [x] 2.4 On drag, insert waypoint at drop position with trailer lines to adjacent waypoints
|
||||
- [x] 2.5 Suppress map click handler after ghost insert to prevent duplicate waypoints
|
||||
- [x] 2.6 Guard against flickering: `draggingRef` freezes snap updates during drag, distance-based mouseout
|
||||
- [x] 2.7 Disable route interaction when no-go area drawing mode is active
|
||||
|
||||
## 3. Route Coloring
|
||||
|
||||
- [x] 3.1 Create `ColoredRoute` component — renders segmented L.Polyline instances with per-point colors
|
||||
- [x] 3.2 Implement elevation gradient: normalize elevation to 0-1 range, map to green→yellow→red
|
||||
- [x] 3.3 Implement surface coloring: extract surface types from BRouter tiledesc, map to color palette
|
||||
- [x] 3.4 Fall back to plain mode when surface data is unavailable
|
||||
- [x] 3.5 Add color mode state (`colorMode`) to Yjs routeData map, synced across participants
|
||||
- [x] 3.6 Add color mode select dropdown to session header
|
||||
- [x] 3.7 Sync elevation chart colors with route — use same `elevationColor()` gradient in ElevationChart
|
||||
- [x] 3.8 Add i18n keys for color mode labels (en + de)
|
||||
|
||||
## 4. Verify
|
||||
|
||||
- [x] 4.1 E2E test: click near route inserts waypoint at correct position
|
||||
- [x] 4.2 E2E test: color mode toggle switches between plain/elevation/surface
|
||||
- [x] 4.3 E2E test: enriched route response includes segment boundaries and coordinates
|
||||
- [x] 4.4 Unit test: segment boundary computation with 1, 2, and 4 segments
|
||||
- [x] 4.5 Visual verification: ghost marker, drag with trailers, all color modes (cmux browser)
|
||||
|
|
@ -0,0 +1,2 @@
|
|||
schema: spec-driven
|
||||
created: 2026-03-25
|
||||
|
|
@ -0,0 +1,62 @@
|
|||
## Context
|
||||
|
||||
The Journal has passkey auth (primary) and magic link login (fallback). Magic
|
||||
links work in dev (auto-redirect) but in production the link is only logged
|
||||
to console — users never receive it. No email infrastructure exists.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Actually deliver magic link emails in production
|
||||
- Send a welcome email after registration
|
||||
- Provider-agnostic email interface (easy to swap providers)
|
||||
- HTML templates with plain-text fallback
|
||||
- Easy to add new email types in the future (just add a template + call)
|
||||
- Dev mode: still log to console / return devLink (no real emails)
|
||||
|
||||
**Non-Goals:**
|
||||
- Marketing emails or newsletters
|
||||
- Email preferences / unsubscribe (only transactional)
|
||||
- Inline CSS / complex email layouts (keep it simple text-focused)
|
||||
- Queuing or retry logic (provider handles delivery)
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1: SMTP via nodemailer
|
||||
|
||||
Use [nodemailer](https://nodemailer.com) with SMTP — standard, provider-agnostic,
|
||||
works with any SMTP server. Single dependency: `nodemailer` npm package.
|
||||
Configured via `SMTP_URL` env var (e.g., `smtp://user:pass@mail.example.com:587`).
|
||||
|
||||
**Alternative considered**: Resend API. Simpler initial setup but creates vendor
|
||||
dependency. SMTP is a standard protocol that works with any provider and aligns
|
||||
with the self-hostable philosophy.
|
||||
|
||||
### D2: Email module in apps/journal/app/lib/email.server.ts
|
||||
|
||||
Not a shared package — only the Journal sends emails. Keep it simple:
|
||||
- `sendEmail(to, subject, html, text)` — low-level sender
|
||||
- `sendMagicLink(email, link)` — template wrapper
|
||||
- `sendWelcome(email, username)` — template wrapper
|
||||
|
||||
In dev mode, `sendEmail` logs to console instead of calling Resend.
|
||||
|
||||
### D3: Inline HTML templates
|
||||
|
||||
Simple functions returning HTML strings. No template engine. Each email type
|
||||
is a function: `magicLinkTemplate(link)`, `welcomeTemplate(username)`. Plain
|
||||
text generated by stripping tags.
|
||||
|
||||
### D4: Sender domain: noreply@trails.cool
|
||||
|
||||
Requires DNS records (DKIM/SPF/DMARC) for deliverability. Add TXT records
|
||||
via Terraform or manually in Hetzner DNS.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **SMTP server required** → Must provide an SMTP server. Can use any provider
|
||||
(Mailgun, Amazon SES, Postfix, etc.) or a simple relay.
|
||||
- **DNS records required** → Must add SPF/DKIM/DMARC records for deliverability.
|
||||
- **No built-in retry** → nodemailer doesn't queue. If SMTP is down, the send
|
||||
fails. Acceptable for current scale — welcome emails are fire-and-forget,
|
||||
magic links can be re-requested.
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
## Why
|
||||
|
||||
Magic link login doesn't work in production — the link is logged to console
|
||||
but never emailed to the user. Registration works (passkey-based) but the
|
||||
fallback auth flow is broken. We need actual email delivery.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Add a reusable email sending layer (`@trails-cool/email` or in-app module)
|
||||
with a provider-agnostic interface so future emails are trivial to add
|
||||
- Send magic link emails in production
|
||||
- Send a welcome email after registration
|
||||
- Use a transactional email provider (Resend, Postmark, or SMTP)
|
||||
- HTML email templates with plain-text fallback
|
||||
- Document email sending in the privacy manifest
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `transactional-emails`: Send templated emails via a provider-agnostic interface. Current emails: magic link login, welcome on registration. Designed for easy addition of future email types.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `journal-auth`: Magic link flow now actually sends the email instead of logging to console
|
||||
|
||||
## Impact
|
||||
|
||||
- **Files**: New email module (lib or package), modified `api.auth.login.ts`, modified registration flow, email templates
|
||||
- **Dependencies**: One email provider SDK (e.g., `resend` or `nodemailer`)
|
||||
- **Infrastructure**: Email provider API key as env var, DNS records for sender domain verification
|
||||
- **Privacy**: Email addresses sent to third-party email provider — must document
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Magic link login
|
||||
The magic link login flow SHALL deliver the link via email in production instead of logging to console.
|
||||
|
||||
#### Scenario: Production email delivery
|
||||
- **WHEN** a user requests a magic link in production
|
||||
- **THEN** the link is emailed to the user (not just logged to console)
|
||||
|
||||
#### Scenario: Dev mode unchanged
|
||||
- **WHEN** a user requests a magic link in development
|
||||
- **THEN** the link is returned directly for auto-redirect (existing behavior preserved)
|
||||
|
|
@ -0,0 +1,44 @@
|
|||
## ADDED Requirements
|
||||
|
||||
### Requirement: Email sending interface
|
||||
The system SHALL provide a provider-agnostic email sending function that supports HTML and plain-text content.
|
||||
|
||||
#### Scenario: Send email in production
|
||||
- **WHEN** the system sends a transactional email in production
|
||||
- **THEN** the email is delivered via the configured provider (Resend) to the recipient
|
||||
|
||||
#### Scenario: Dev mode skips sending
|
||||
- **WHEN** the system sends a transactional email in development
|
||||
- **THEN** the email content is logged to console and no external API is called
|
||||
|
||||
### Requirement: Magic link email
|
||||
The system SHALL send an email containing the magic link when a user requests passwordless login.
|
||||
|
||||
#### Scenario: Magic link delivered
|
||||
- **WHEN** a user requests a magic link login
|
||||
- **THEN** an email is sent with a clickable link that logs them in
|
||||
|
||||
#### Scenario: Email content
|
||||
- **WHEN** a magic link email is sent
|
||||
- **THEN** it includes: the link, expiry time (15 minutes), and plain-text fallback
|
||||
|
||||
### Requirement: Welcome email
|
||||
The system SHALL send a welcome email after successful registration.
|
||||
|
||||
#### Scenario: Welcome on registration
|
||||
- **WHEN** a user completes passkey registration
|
||||
- **THEN** a welcome email is sent to their registered email address
|
||||
|
||||
### Requirement: Email templates
|
||||
Each email type SHALL have an HTML template with a plain-text fallback.
|
||||
|
||||
#### Scenario: Extensible template pattern
|
||||
- **WHEN** a new email type is needed in the future
|
||||
- **THEN** it can be added by creating a template function and calling sendEmail
|
||||
|
||||
### Requirement: Privacy disclosure
|
||||
Email sending SHALL be documented in the privacy manifest.
|
||||
|
||||
#### Scenario: Privacy manifest updated
|
||||
- **WHEN** transactional emails are enabled
|
||||
- **THEN** the /privacy page documents: what emails are sent, that email addresses are shared with the email provider, and which provider is used
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
## 1. Email Infrastructure
|
||||
|
||||
- [x] 1.1 Add `nodemailer` package to Journal dependencies
|
||||
- [x] 1.2 Create `apps/journal/app/lib/email.server.ts` with sendEmail(to, subject, html, text) — uses SMTP in production, logs to console in dev
|
||||
- [x] 1.3 Add `SMTP_URL` and `SMTP_FROM` env vars to docker-compose.yml
|
||||
- [x] 1.4 Write unit test for sendEmail (mock nodemailer, verify dev-mode logging)
|
||||
|
||||
## 2. Email Templates
|
||||
|
||||
- [x] 2.1 Create magicLinkTemplate(link: string) returning { html, text } — includes link, 15-min expiry note, trails.cool branding
|
||||
- [x] 2.2 Create welcomeTemplate(username: string) returning { html, text } — greeting, what they can do, link to routes
|
||||
- [x] 2.3 Wire sendMagicLink(email, link) and sendWelcome(email, username) helper functions
|
||||
|
||||
## 3. Integration
|
||||
|
||||
- [x] 3.1 Update api.auth.login.ts: call sendMagicLink in production instead of just logging
|
||||
- [x] 3.2 Update registration flow: call sendWelcome after successful passkey registration
|
||||
- [x] 3.3 Verify dev mode still works (devLink returned, no email sent)
|
||||
|
||||
## 4. Privacy & Config
|
||||
|
||||
- [x] 4.1 Update /privacy page: document email sending, provider (Resend), what data is shared
|
||||
- [x] 4.2 Add `SMTP_URL` to server env and deploy documentation
|
||||
- [x] 4.3 Document sender domain DNS setup (SPF/DKIM/DMARC for noreply@trails.cool)
|
||||
|
||||
## 5. Verify
|
||||
|
||||
- [x] 5.1 Test magic link email delivery locally with SMTP
|
||||
- [x] 5.2 Test welcome email on registration
|
||||
- [x] 5.3 Verify existing E2E tests still pass (dev mode unchanged)
|
||||
Loading…
Add table
Add a link
Reference in a new issue