From 744bbb37c3bc8b6c5f0f2773544789a15c2ee977 Mon Sep 17 00:00:00 2001 From: Ricardo Ezequiel <106978749+ricaezejo@users.noreply.github.com> Date: Fri, 6 Nov 2026 11:38:03 +0100 Subject: [PATCH 01/13] docs: spec and plan for the full-screen route map and GPX export Co-Authored-By: Claude Sonnet 5.5 --- .../2026-11-05-outdoor-run-map-and-gpx.md | 247 ++++++++++++++++++ ...26-11-05-outdoor-run-map-and-gpx-design.md | 62 +++++ 2 files changed, 309 insertions(+) create mode 100644 docs/superpowers/plans/2026-11-05-outdoor-run-map-and-gpx.md create mode 100644 docs/superpowers/specs/2026-11-05-outdoor-run-map-and-gpx-design.md diff --git a/docs/superpowers/plans/2026-11-05-outdoor-run-map-and-gpx.md b/docs/superpowers/plans/2026-11-05-outdoor-run-map-and-gpx.md new file mode 100644 index 00000000..42efcd8c --- /dev/null +++ b/docs/superpowers/plans/2026-11-05-outdoor-run-map-and-gpx.md @@ -0,0 +1,247 @@ +# Outdoor Run: Full-Screen Map, Km Markers, Split Highlight and GPX Export Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** From a finished GPS workout's Route card, open the map full screen with a numbered marker at each kilometre and a split picker that highlights one kilometre on the map, and export the run as a GPX file. + +**Architecture:** All of it hangs off the existing `RouteCard` (`ui/glow/SummarySections.kt`), which the just-finished summary and a past workout's page both render. The full-screen map is a `Dialog` hosting the existing `WorkoutMap`, so no navigation changes. Km markers are bitmaps drawn with `android.graphics` and added to the map style as images, so they need no font download and work in route-only mode with no network. Split highlight reuses the existing split rows (`SummaryCopy.splitRows`) and a new `Route.legs` that returns each kilometre's points. GPX is a pure-Kotlin writer over the already cleaned `Route.track`, handed to the system share sheet through the existing `share/` FileProvider path. Two stacked branches, made with git-spice. + +**Tech Stack:** Kotlin, Jetpack Compose, MapLibre (`WorkoutMap`), Room entities already in place, JUnit4 + Robolectric (`ComposeRules`). + +**Spec:** `docs/superpowers/specs/2026-11-05-outdoor-run-map-and-gpx-design.md`. Strava upload and a Health Connect `ExerciseRoute` are out of scope for now (see the end). + +## Global Constraints + +- User-facing text goes in `app/src/main/res/values/strings_glow_summary.xml`, never in Kotlin literals (`i18n/HardcodedEnglishTest`). Each string has an XML comment saying where it shows. +- `i18n/StringsParityTest` must stay green; CI also runs `./gradlew :app:testDebugUnitTest -PtestLocale=de-DE`. +- No new network use: export is a local file handed to the share sheet; `docs/privacy.md` says routes never leave the phone. +- No new permissions and no new FileProvider paths: `res/xml/share_paths.xml` already exposes `cache/share/`. +- Commit messages are `type: summary` with no ticket key. End each with the Co-Authored-By line from the session. +- Branches: git-spice only (`gs branch create`, `gs stack submit` as drafts). No worktrees, no plain `git checkout -b`. +- Verification commands: `./gradlew :app:testDebugUnitTest --tests ''`; before submitting also `./gradlew :app:lintDebug detektMain ktlintCheck`. + +## Review Focus + +- A run under 1 km has no km markers, and its "Last N m" chip is still selectable and highlights the whole route (Task 2). +- A run with pauses or a tunnel gap exports as separate ``s, not one line across the gap (Task 3). +- A device in a decimal-comma locale (de-DE) still writes `51.5000000`, not `51,5000000` (Task 3). +- Rotating the phone or process death with the full-screen map open keeps it open, with the same route-only choice and the same selected split (Tasks 1 and 2). +- Switching Route only on and off with a split selected keeps the km markers and the highlight, since the new style drops the images added to the old one (Task 2). +- A workout name with `&`, `<`, `"` produces well-formed XML, and no heart rate or altitude still gives a valid GPX (Task 3, tested there). + +--- + +## Branch 1: `feat/fullscreen-route-map` + +Start with `gs branch create feat/fullscreen-route-map` from `main`. + +### Task 1: Full-screen route map + +**Files:** +- Create: `app/src/main/kotlin/org/openstrap/app/ui/glow/FullScreenRouteMap.kt` +- Modify: `app/src/main/kotlin/org/openstrap/app/ui/glow/GlowWorkoutSummary.kt:328-339` (`RouteMap`) +- Modify: `app/src/main/kotlin/org/openstrap/app/ui/glow/SummarySections.kt:268-277` (`RouteCard`) +- Modify: `app/src/main/res/values/strings_glow_summary.xml` (after `glow_summary_climb`) +- Test: `app/src/test/kotlin/org/openstrap/app/ui/glow/FullScreenRouteMapTest.kt` + +**Interfaces:** +- Consumes: `WorkoutMap(stretches, routeOnly, modifier, here, fitPadding, creditBottom, hereColor, follow, onPanned)` (`ui/glow/WorkoutMap.kt`); `Route.byZone(points, hr, maxHr, zones)`; `LocalHeartZones`; `IconPill(label, onClick, modifier, icon, ...)` (`PageParts.kt:690`); `PhoneSummary`. +- Produces: + - `@Composable internal fun rememberZoneStretches(summary: PhoneSummary): List, Int>>`, extracted from `RouteMap` so both maps colour the line the same way. + - `@Composable internal fun FullScreenRouteMap(summary: PhoneSummary, onClose: () -> Unit)`: a `Dialog` (`usePlatformDefaultWidth = false`, `decorFitsSystemWindows = false`, `onDismissRequest = onClose`) around the content below. + - `@Composable internal fun FullScreenRouteMapContent(summary: PhoneSummary, onClose: () -> Unit)`: the map and its pills, without the `Dialog`, so tests need no window. + - `RouteMap(summary, modifier, onOpen: (() -> Unit)? = null)`: the card's map becomes tappable when `onOpen` is given. + +- [ ] **Step 1: Write the failing test** in `FullScreenRouteMapTest` (Robolectric, `ComposeRules`, content wrapped in `CompositionLocalProvider(LocalInspectionMode provides true)` so `WorkoutMap` draws its black stand-in; see `LiveLandscapeLayoutTest` for the rule and `@Config`). Build a `PhoneSummary` with a mappable route (the `appWorkout` helper in `org.openstrap.app.testing`; a run east of 40 points as in `RouteTest.run`). Tests, with strings read from `R.string`: + - `closing calls onClose`: click the node with text `R.string.glow_summary_map_close`; assert a counter is 1. + - `route only can be switched on and back`: click `glow_summary_map_route_only`, assert the node with text `glow_summary_map_show_map` exists, click it, assert the first label is back. + - `fit route shows only after the map was panned`: assert `glow_summary_map_fit` does not exist initially. (Panning cannot be driven in inspection mode; this pins the initial state only.) + - `the summary's route card map opens it`: render `RouteMap(summary, onOpen = { opened++ })`, click the node with content description `glow_summary_map_open`, assert `opened == 1`. + +- [ ] **Step 2: Run to verify it fails** + +Run: `./gradlew :app:testDebugUnitTest --tests 'org.openstrap.app.ui.glow.FullScreenRouteMapTest'` +Expected: FAIL, compilation error (`FullScreenRouteMapContent` and the strings undefined). + +- [ ] **Step 3: Add the strings** to `strings_glow_summary.xml`, each with a comment: `glow_summary_map_open` ("Open map full screen", content description of the card's map), `glow_summary_map_close` ("Close"), `glow_summary_map_route_only` ("Route only", same wording as `workout_live_map_route_only`), `glow_summary_map_show_map` ("Show map"), `glow_summary_map_fit` ("Fit route"). + +- [ ] **Step 4: Implement `rememberZoneStretches`, `FullScreenRouteMapContent` and `FullScreenRouteMap`** in `FullScreenRouteMap.kt`. Content is a black `Box(fillMaxSize)` with `WorkoutMap(stretches, routeOnly, Modifier.fillMaxSize(), follow = follow, fitPadding = PaddingValues(horizontal = 24.dp, vertical = 96.dp), onPanned = { follow = false })`. `routeOnly` is `rememberSaveable` (default false, matching the card). `follow` is `remember` (true). Pills, inside `WindowInsets.safeDrawing` padding: Close top-end, Route only / Show map top-start, and Fit route top-centre only while `!follow` (tap sets `follow = true`). The bottom edge is left free for Task 2's split picker. Reuse `IconPill`; no new styling. + +- [ ] **Step 5: Wire the card.** `RouteMap` takes `onOpen`; when non-null its `Box` gets `Modifier.clickable(onClickLabel = open label, onClick = onOpen)` and a content description from `glow_summary_map_open`. `RouteCard` holds `var full by rememberSaveable { mutableStateOf(false) }`, passes `onOpen = { full = true }`, and shows `FullScreenRouteMap(summary) { full = false }` while `full`. `RouteMap`'s other caller keeps passing no `onOpen`. + +- [ ] **Step 6: Run the tests** + +Run: `./gradlew :app:testDebugUnitTest --tests 'org.openstrap.app.ui.glow.FullScreenRouteMapTest' --tests 'org.openstrap.app.i18n.*'` +Expected: PASS. + +- [ ] **Step 7: Check on a device.** Per `CLAUDE.md`, check no workout is recording first. Install the debug build, open a past GPS run, tap the route card map. Expect: full screen with the route fitted, drag to pan makes Fit route appear and tapping it refits, Route only shows a plain black map, system Back closes, rotating keeps it open. + +- [ ] **Step 8: Commit** + +```bash +git add -A +git commit -m "feat: open the route map full screen from a workout's summary" +``` + +### Task 2: Km markers and split highlight + +Still on `feat/fullscreen-route-map`. Splits are per kilometre everywhere in the app (`Km 3`), not per mile, so markers and the picker are too. + +**Files:** +- Modify: `app/src/main/kotlin/org/openstrap/app/data/Route.kt` (`splits`, around line 305) +- Modify: `app/src/main/kotlin/org/openstrap/app/ui/glow/WorkoutMap.kt` +- Modify: `app/src/main/kotlin/org/openstrap/app/ui/glow/GlowWorkoutSummary.kt:398-410` (`SplitsList`) +- Modify: `app/src/main/kotlin/org/openstrap/app/ui/glow/FullScreenRouteMap.kt` (from Task 1) +- Create: `app/src/main/kotlin/org/openstrap/app/ui/glow/KmMarkers.kt` +- Create: `app/src/main/kotlin/org/openstrap/app/ui/glow/SplitPicker.kt` +- Test: `app/src/test/kotlin/org/openstrap/app/data/RouteTest.kt` (add), `app/src/test/kotlin/org/openstrap/app/ui/glow/KmMarkersTest.kt`, `app/src/test/kotlin/org/openstrap/app/ui/glow/FullScreenRouteMapTest.kt` (add) + +**Interfaces:** +- Consumes: `Route.splits`, `Route.Split(index, endT, seconds, meters)`, `SummaryCopy.splitRows(splits, readings, firstT, totalMeters): List` (`SplitRow(name, time, averageBpm, seconds, kind)`), `workout_summary_split_km` and `workout_summary_split_last` strings, Task 1's `FullScreenRouteMapContent`. +- Produces: + - `Route.Leg(val split: Split, val points: List)` and `Route.legs(points: List, pauses: List = emptyList(), km: Double = 1000.0): List`: the same kilometres as `splits`, each with the smoothed track points it covers, a leg's first point being the previous leg's last. `splits` becomes `legs(...).map { it.split }`, so the two cannot disagree. + - `internal fun splitRowsFor(summary: PhoneSummary, route: List): List` in `GlowWorkoutSummary.kt`, extracted from `SplitsList` (the `SummaryCopy.splitRows(Route.splits(route, summary.pauses), summary.history, route.firstOrNull()?.t, summary.distanceMeters?.takeIf { !summary.distanceFromSteps })` call) so the list and the picker build identical rows. Row `i` is leg `i`. + - `internal fun kmMarkerFeatures(markers: List>): String`: GeoJSON FeatureCollection, one Point feature per marker (lon, lat order), property `icon` = `"km-"`. + - `internal fun kmMarkerBitmap(km: Int, density: Float): Bitmap`: a 22 dp circle, dark fill (`0xFF121316`, as the start dot), white 2 dp ring, the number centred in bold white, text scaled down so 3 digits fit. + - `internal fun highlightGeoJson(points: List): String`: an empty FeatureCollection under 2 points, else one LineString feature. + - `WorkoutMap(..., kmMarkers: List> = emptyList(), highlight: List = emptyList())`: both default to nothing, so the live map is unchanged. + - `@Composable internal fun SplitPicker(rows: List, selected: Int?, onSelect: (Int?) -> Unit, modifier: Modifier = Modifier)`: a `LazyRow` of chips, name over time, the selected one lit white; each chip has `Modifier.semantics { selected = ... }` and `selectable`-style click (tap an unselected chip selects it, tap the selected one clears it). + +- [ ] **Step 1: Write the failing tests.** + - In `RouteTest` (helpers `east`, `run` already there): `legs cut the track at each kilometre` with `run(1200)` (about 3.6 km at 3 m/s): 4 legs; legs 0 to 2 each measure 1000 m ± 15 m summed with `Route.meters`; `legs[i].points.last() == legs[i + 1].points.first()`. `legs and splits agree`: `Route.legs(run(1200)).map { it.split } == Route.splits(run(1200))`. `a run under a kilometre is one part leg`: `Route.legs(run(100))` has one leg with `split.meters < 1000.0`. `a pause stays out of a leg's metres`: pauses `500L..600L` on `run(1200)`: the leg containing it measures 1000 m ± 15 m of unpaused track and the whole-run total is about 100 s × 3 m/s shorter than the unpaused run's. + - `KmMarkersTest` (Robolectric, `@GraphicsMode(NATIVE)`): `features carry the km as an icon name` (markers `1 to p1, 2 to p2` parse with `org.json.JSONObject`: 2 features, `properties.icon` is `km-1` and `km-2`, `coordinates[0]` is the lon); `a marker bitmap is square, sized by density, and drawn` (`kmMarkerBitmap(7, 2f)`: width equals height equals 44, and the centre pixel is not fully transparent); `three digits still fit` (`kmMarkerBitmap(123, 2f)` does not throw and is the same size); `highlight needs two points` (`highlightGeoJson(emptyList())` has no features, a two-point list has one feature of type `LineString`). + - In `FullScreenRouteMapTest`: `the picker lists each kilometre and the last part` (route of 3.5 km: nodes with text `getString(R.string.workout_summary_split_km, 1)` to `3` exist, so does a node starting with the `workout_summary_split_last` text prefix); `tapping a split selects it and tapping it again clears it` (`assertIsSelected()` after the first click on the "Km 2" chip's node, `assertIsNotSelected()` after the second); `a run under a kilometre has no km chips` (route of 400 m: no node with the `workout_summary_split_km` text for 1). + +- [ ] **Step 2: Run to verify they fail** + +Run: `./gradlew :app:testDebugUnitTest --tests 'org.openstrap.app.data.RouteTest' --tests 'org.openstrap.app.ui.glow.KmMarkersTest' --tests 'org.openstrap.app.ui.glow.FullScreenRouteMapTest'` +Expected: FAIL, compilation errors (`Route.legs`, `kmMarkerFeatures` and friends undefined). + +- [ ] **Step 3: Implement `Route.Leg` and `Route.legs`**, moving the body of `splits` into it (the loop over `track(points).zipWithNext()`, skipping paused pairs, closing a leg at `meters >= km`); keep a `current` list of points, seed it with the leg's start point, add each unpaused `b`, and start the next leg's list from the closing point. Make `splits` delegate. Run `RouteTest` alone: the existing splits tests must still pass unchanged. + +- [ ] **Step 4: Implement `splitRowsFor`** and use it in `SplitsList` (behaviour unchanged; `SplitsListTest` or the summary tests that exist must stay green). + +- [ ] **Step 5: Implement `KmMarkers.kt`** (`kmMarkerFeatures`, `kmMarkerBitmap` with `Canvas`, `Paint(ANTI_ALIAS_FLAG)`, `Paint.Align.CENTER`) and `highlightGeoJson` (next to the existing private `geoJson` in `WorkoutMap.kt`, reusing `coord`). + +- [ ] **Step 6: Extend `WorkoutMap`.** In the style-ready callback add a `GeoJsonSource` `KM_SRC` with a `SymbolLayer` `KM_LAYER` (`iconImage(Expression.get("icon"))`, `iconAllowOverlap(true)`, `iconIgnorePlacement(true)`), and a `GeoJsonSource` `HIGHLIGHT_SRC` with a white `LineLayer` (width 10, round caps) added with `addLayerBelow(..., LINE)` so the zone-coloured line sits on top of a white casing. A `LaunchedEffect(style, kmMarkers)` does `style.addImage("km-$n", kmMarkerBitmap(n, density))` for each marker then `setGeoJson(kmMarkerFeatures(kmMarkers))`; it must run again whenever `style` changes, because switching Route only calls `setStyle` and the new style has none of the old images. A `LaunchedEffect(style, highlight)` sets `highlightGeoJson(highlight)`. In the existing camera effect: when `follow` and `highlight.size >= 2`, fit the highlight's bounds (same padding) instead of the whole route. + +- [ ] **Step 7: Implement `SplitPicker`** (`SplitPicker.kt`). Chip label is `row.name`, second line `row.time`; reuse `GlowType` text styles and the pill colours of `IconPill`; no new theme values. + +- [ ] **Step 8: Wire `FullScreenRouteMapContent`.** `val legs = remember(summary) { Route.legs(summary.route, summary.pauses) }`, `val rows = remember(summary) { splitRowsFor(summary, summary.route) }`, `var selected by rememberSaveable { mutableStateOf(null) }`. Pass `kmMarkers = legs.filter { it.split.meters >= 1000.0 }.map { it.split.index + 1 to it.points.last() }` and `highlight = selected?.let { legs.getOrNull(it)?.points }.orEmpty()` to `WorkoutMap`. Place `SplitPicker(rows, selected, onSelect = { selected = it; follow = true })` along the bottom inside `WindowInsets.safeDrawing`; show it only when `rows` is not empty; pass `creditBottom` equal to the picker's height so the OpenStreetMap credit stays visible above it. + +- [ ] **Step 9: Run the tests** + +Run: `./gradlew :app:testDebugUnitTest --tests 'org.openstrap.app.data.*' --tests 'org.openstrap.app.ui.glow.*' --tests 'org.openstrap.app.i18n.*'` +Expected: PASS. + +- [ ] **Step 10: Check on a device.** Open a past run longer than 3 km. Expect: numbered circles at each km along the line; tapping "Km 2" in the picker draws it with a white casing and zooms to it, tapping it again returns to the whole route; Route only keeps markers and highlight and makes no tile requests; a run under 1 km has no markers and only a "Last N m" chip; rotating keeps the selection; the OpenStreetMap credit is visible above the picker. + +- [ ] **Step 11: Commit** + +```bash +git add -A +git commit -m "feat: km markers and split highlight on the full-screen route map" +``` + +--- + +## Branch 2: `feat/gpx-export` + +Start with `gs branch create feat/gpx-export` (stacked on branch 1; the Export pill sits in the same `RouteCard`). + +### Task 3: GPX writer + +**Files:** +- Create: `app/src/main/kotlin/org/openstrap/app/export/GpxWriter.kt` +- Modify: `app/src/main/kotlin/org/openstrap/app/data/Route.kt:411` (`private const val MAX_HR_GAP_S` becomes `const val`, so the writer matches heart rate the same way `byZone` does) +- Test: `app/src/test/kotlin/org/openstrap/app/export/GpxWriterTest.kt` + +**Interfaces:** +- Consumes: `Route.track(points): List`, `Route.MAX_HR_GAP_S` (30 s), `Route.Point`. +- Produces: `object GpxWriter { fun write(name: String, points: List, heartRate: List>, pauses: List = emptyList()): String }`. `heartRate` is (epoch seconds, bpm) ascending, as `PhoneSummary.history`. `pauses` is `PhoneSummary.pauses`. + +Output format (the only decisions the tests do not pin): GPX 1.1, `creator="OpenStrap"`, namespaces `http://www.topografix.com/GPX/1/1` and `gpxtpx` = `http://www.garmin.com/xmlschemas/TrackPointExtension/v1`; one `` with ``; `