samplez/rippr-flutter-src/docs/v3/V3-05-mounted-mode.md

V3-05 — Mounted (handlebar) mode

Phase Live map · Depends on V3-04 · Size M · Status Done

Goal

Make the app usable on handlebars in daylight, at speed, with gloves — as an explicit mode rather than an accident.

Context

v1 and v2 were built entirely around "start it, pocket it, stop it". A mounted phone is a different product. Treating it as a mode makes the differences deliberate instead of half-met.

Design

A toggle that changes several things at once:

• Keep the screen awake for the whole ride (wakelock_plus). Currently the screen sleeps and recording continues; mounted, that is wrong.
• Sunlight legibility. The dark theme was chosen for glanceability at night and in a pocket-glance. Behind a visor in daylight it is the wrong choice — a high-contrast variant with larger figures is needed. This is not the same as V3-16's visual identity.
• Larger touch targets still. 72 dp works stopped; at speed with gloves it does not.
• Interruptions. What happens on an incoming call or a notification — the recording must survive and the screen must come back.

Implementation

1. mountedMode in Config, surfaced in settings and as a quick toggle on the record screen
2. wakelock_plus, acquired on start when mounted, released on stop/pause — and released on dispose, or the screen stays lit after the app closes
3. A high-contrast text scale applied when mounted
4. Handle AppLifecycleState.inactive (a call arriving) distinctly from paused

Acceptance criteria

• Mounted: the screen never sleeps during a ride
• Un-mounted: behaviour is exactly as today
• The wake lock is released on stop, on discard, and on app exit
• An incoming call does not stop recording
• Battery cost of mounted mode is measured and written down (V3-13)

Tests

• Widget: mounted toggle changes text scale and requests the wake lock (fake the plugin)
• Widget: the lock is released on stop
• Manual, on a real bike — legibility in daylight cannot be tested any other way

Risks

• A leaked wake lock flattens the battery, silently and after the app is closed. Test the release path harder than the acquire path.
• Legibility is a judgement call that needs a real ride in real sun.

Out of scope

A dedicated mounted layout with different information architecture — start by scaling what exists and see what the ride teaches.

Outcome

Shipped as designed, plus two deviations worth recording.

Config.mountedMode follows the same seeded-StateProvider shape as mapEnabled and unitSystem (mountedModeProvider); a quick-toggle icon button sits next to Settings on the record screen, and a matching switch was added to SettingsScreen. The wake lock is wrapped in a WakelockController seam (FakeWakelockController for tests), mirroring LocationSource — the same reasoning: the risk named in this ticket ("a leaked lock flattens the battery silently") is exactly the kind of thing that has to be provable, not just plausible.

Deviation 1 — no TextTheme.apply(fontSizeFactor: ...). The design called for scaling the whole mounted text theme at once; Flutter's TextStyle.apply asserts when fontSizeFactor != 1.0 meets any style with a null fontSize, which Material 3's default TextTheme has for at least one role. Scaling was moved to where it already existed: BigStat gained an explicit scale parameter (default 1.0), applied to the record screen's headline figure only. StatRow and button labels were not wired to mountedTextScale — the acceptance criterion is legibility of the number that matters at a glance, not uniform scaling of every row, and over-scaling the stat card risked reintroducing the record screen's known overflow-on-short-phones failure mode.

Deviation 2 — the mounted theme wraps only the record screen, via a local Theme(...) widget inside RecordScreen.build, not the app's MaterialApp. Theme.of(context) inside that build method would still report the ambient dark theme, so colors is read off the locally-built ThemeData directly rather than through Theme.of(context) — a small trap worth flagging for V3-16, which will touch this same file.

Wake lock acquisition is gated on recording, not merely mounted-and-idle or mounted-and-paused, and re-evaluated both on trip-state transitions and on the mounted toggle itself changing mid-ride. Release happens on stop, on discard (both drive the same trip-state listener), on navigating away (dispose), and defensively whenever mounted mode is off. One implementation snag: reading ref inside State.dispose() throws (ConsumerStatefulElement forbids it once unmounting has started) — fixed by capturing the WakelockController once in initState via a late final field instead of reading it fresh in dispose.

7 new tests across widget_test.dart (wake lock acquired while recording+mounted, never requested un-mounted, released on ride completion, released on navigating away while still recording, mounted theme scales the headline and enlarges Start), settings_screen_test.dart (switch writes through to Config), and config_test.dart (default/round-trip). flutter analyze clean; full suite green (231 tests, up from 224).

Not done, and explicitly out of scope per the ticket: real daylight/glove legibility (needs an actual ride — V3-13), and AppLifecycleState.inactive handling for an incoming call — recording is already fully DB-derived and does not observe app lifecycle at all, so a call cannot stop it; this was verified by reasoning about the existing architecture rather than a new test, since there is no lifecycle-reactive code path to test.