rippr/docs/v3/V3-07-route-drawing.md

V3-07 — Route drawing (pins and straight lines)

Phase Route planning · Depends on nothing · Size M · Status Done

Goal

Drop pins on a map to sketch a route, see the straight-line distance, and save it. The foundation for V3-08, deliberately shipped without a routing engine.

Context

Pre-ride planning is a genuinely new mode, not an extension of recording. It needs no ride in progress, no server, and nothing else in v3 — the most independent thing in the backlog.

Split from road-snapped routing (V3-08) on purpose: pins, storage, editing and the map interaction are all needed either way, and none of them require choosing a routing vendor. That decision should not block a usable feature.

Design

New entities, separate from Trip. A plan is not a recording, and conflating them would put unridden kilometres into ride totals.

Route(id, name, createdAt, activity?, distanceM, estimatedMillis?, geometry?)
Waypoint(id, routeId, ordinal, latitude, longitude, name?)

geometry is null in this ticket; V3-08 fills it with the road-snapped polyline. ordinal rather than relying on insertion id, so waypoints can be reordered.

Straight-line distance reuses haversineMeters — already ported and parity-proven.

Implementation

1. Drift tables + migration (the second one; V3-01 proves the path)
2. RouteRepository mirroring TripRepository's shape
3. RoutePlannerScreen — tap to add a pin, drag to move, tap a pin to delete, reorder
4. Straight-line polyline between pins, visibly distinct from a recorded path
5. Routes list, reachable from the record screen alongside Rides
6. Name, rename, delete

Acceptance criteria

• Pins can be added, moved, reordered and deleted
• Distance updates live as pins change
• A saved route survives an app restart
• Routes never appear in the rides list, and never contribute to ride totals
• Deleting a route cascades to its waypoints

Tests

• Repository: create, reorder, delete, cascade — in-memory, like the trip tests
• Distance matches pathLengthMeters over the same points
• Widget: tapping the map adds a pin; the distance label updates
• A test asserting routes are absent from watchCompletedTrips

Risks

The main one is scope drift into V3-08. Ship straight lines first; they are genuinely useful for a rough plan.

Out of scope

Road snapping, ETA, following a route while riding. Import of existing GPX routes.

Outcome

Shipped as designed, with one naming deviation and two real testing traps worth recording for V3-08/V3-09.

Named RoutePlan, not Route. The ticket's own design sketch used Route, but that collides with dart:ui/package:flutter's own Route<T> (the navigator's page-transition class) and with go_router's GoRoute. Renaming up front avoided constant hide/as import juggling across every file that touches both navigation and route plans.

Schema: route_plans/waypoints tables, schema version 2→3, following V3-01's migration pattern exactly (m.createTable for brand-new tables needs no backfill, unlike V3-01's addColumn). RoutePlanRepository mirrors TripRepository's shape but has no state machine — every mutating call ends by recomputing distanceM via geo.pathLengthMeters, so "distance always matches the current waypoints" holds with no exceptions to remember, including after a pure reorder that doesn't change it.

RoutePlannerScreen: tap-to-add via MapOptions.onTap, tap-a-pin-to-delete, and drag-to-move implemented by hand against MapCamera.latLngToScreenOffset/ screenOffsetToLatLng (flutter_map has no built-in draggable-marker widget). The straight line is dashed and uses the planning accent, visibly distinct from RideMap's speed-bucketed solid polyline, satisfying the acceptance criterion without a design pass.

Real bug found by testing, not review: the map's initialCenter/initialZoom are read exactly once, at FlutterMap construction. Building the map before the waypoints stream delivered its first value froze the camera on null-island permanently, even once real waypoints arrived — invisible in manual testing (a route sketched from empty always starts empty) but immediate in a test that opens a planner for a route with existing waypoints. Fixed by gating the map behind the stream's first emission, and by switching from a fixed-zoom guess to CameraFit.bounds (matching RideMap's own established pattern) so pins can't be culled off-camera either.

Real testing trap, likely to recur in V3-08/V3-09: await db.watchRoutePlans().first inside a testWidgets body hung for a genuine ten minutes (the framework's own internal timeout, not a guess) — a fresh Stream.first subscription on a Drift .watch() query depends on a Timer inside Drift's stream-query store that flutter_test's fake test zone never advances without an explicit pump. repo-level Future-returning calls (routePlanById, etc.) have no such dependency and are what every other assertion in this suite already used correctly. Documented inline in the test as a trap for the next ticket that watches a stream from inside testWidgets.

16 new tests: 8 in route_plan_repository_test.dart (create, live distance on add/move/delete, ordinal-gap closing, reordering, rename, cascade delete, and the ticket-mandated "never appears in ride totals" check), 1 migration test (v2→v3, tables created and usable, existing trip untouched), 7 in route_planner_screen_test.dart (empty state, create-and-open, delete, tap-to-add-and-distance-updates, tap-to-delete, rename, missing-route fallback), plus 1 in widget_test.dart for the Routes entry point on the record screen. flutter analyze clean; full suite green (254 tests, up from 237).