rippr/docs/feedback/FB-10-map-pan-recenter-race.md

# FB-10 — Manual map pan loses a race against the follow-recenter timer

**Depends on** — · **Size** M · **Status** Done

## Goal
The rider must be able to pan the map and have it stay where they put it. Today a pan
gesture is silently cancelled a moment after it happens, both idle and while recording.

## Context
Direct user feedback (`docs/FEEDBACK.md`):

> Map page still cannot be scrolled/panned around -- it stays locked centered on the
> user, both idle and recording. A previous attempt at this fix (FB-06) did not
> actually resolve it on-device.

FB-06 already removed the old `hasPoints` gate that fully disabled
`InteractiveFlag.drag`/`InteractiveFlag.pinchZoom`. That part of the fix is correct and
confirmed by widget tests. The map is still stuck because of a **different** bug FB-06
did not find: a timer-driven recenter that keeps re-arming and wins a race against the
user's own drag.

`lib/src/ui/app_shell.dart` builds one shared `RideMap` behind every tab, and rebuilds
it on every ambient GPS fix:

```dart
child: RideMap(
  key: const Key('shell-background-map'),
  points: points,
  segments: segments,
  ambientPosition: ambientPosition,
  follow: isMapTab,
  ...
```

`ambientPosition` comes from `ambientPositionProvider`, fed by
`GeolocatorLocationSource` at a fixed one-second interval with no distance filter
(`lib/src/recording/geolocator_location_source.dart`):

```dart
/// Matches the native `LocationRequest`: high accuracy, 1 s nominal interval, no
/// distance filter (a stationary bike must still produce fixes so elapsed time and the
/// noise floor behave).
const Duration _interval = Duration(seconds: 1);
```

Because `distanceFilter` is `0`, almost every one-second tick delivers a fix that is at
least slightly different from the last one -- so `AppShell`, and therefore `RideMap`,
rebuilds roughly once per second, indefinitely, on the Map tab.

`lib/src/ui/components/ride_map.dart`, `didUpdateWidget` (~line 142):

```dart
void didUpdateWidget(RideMap old) {
  super.didUpdateWidget(old);
  if (!_following || _backgrounded) return;
  if (widget.points.isNotEmpty) {
    final last = widget.points.last;
    WidgetsBinding.instance.addPostFrameCallback((_) {
      if (!mounted || !_following) return;
      _controller.move(ll.LatLng(last.latitude, last.longitude), _controller.camera.zoom);
    });
  } else if (widget.ambientPosition != null &&
      widget.ambientPosition != old.ambientPosition) {
    final isFirstFix = old.ambientPosition == null;
    WidgetsBinding.instance.addPostFrameCallback((_) {
      if (!mounted || !_following) return;
      _controller.move(
        widget.ambientPosition!,
        isFirstFix ? ambientZoom : _controller.camera.zoom,
      );
    });
  }
}
```

The only thing that stops this recenter is `_following` turning `false`, which only
happens inside `onPositionChanged` (~line 277):

```dart
onPositionChanged: !widget.follow
    ? null
    : (position, hasGesture) {
        if (hasGesture && _following) {
          setState(() => _following = false);
        }
      },
```

This callback is correct on its own -- a controller-driven `.move()` reports
`hasGesture: false`, so it never cancels itself out. The problem is timing, not logic:
`didUpdateWidget` re-arms a fresh `postFrameCallback` on almost every one-second tick,
for as long as `_following` is still `true`. If a tick lands while the rider's finger is
already down and moving but flutter_map has not yet reported `hasGesture: true` for that
drag, the scheduled callback fires anyway and snaps the camera straight back to the
ambient fix -- one frame after the rider moved it. The next tick does the same thing a
second later. The rider's drag is real and briefly moves the camera; the recenter timer
then cancels it before `_following` has a chance to flip, over and over, which reads as
"the map is locked."

`test/ride_map_test.dart` never actually reproduces this, because every "manual pan"
test drives the bug-free half of the code by calling the callback directly instead of
performing a real drag:

```dart
var map = tester.widget<FlutterMap>(find.byType(FlutterMap));
map.options.onPositionChanged!(map.mapController!.camera, true);
```

A test built this way cannot observe the race: it sets `hasGesture: true` instantly,
with no competing `postFrameCallback` scheduled in between. This is why FB-06's own
tests passed while the on-device bug remained.

## Design
Track whether a real pointer gesture is currently in progress on the map, and skip the
follow-recenter entirely while one is. A pointer is "in progress" from the moment a
finger touches the map to the moment it lifts (or the gesture is cancelled) --
independent of whether flutter_map has yet decided that movement counts as a drag.

- Add a private `bool _gestureInProgress = false;` field to `_RideMapState`.
- Wrap the `FlutterMap` widget in a `Listener` that only observes raw pointer events,
  it must not consume or claim them, so flutter_map's own gesture recognizers keep
  working exactly as they do today:
  ```dart
  Listener(
    onPointerDown: (_) => _gestureInProgress = true,
    onPointerUp: (_) => _gestureInProgress = false,
    onPointerCancel: (_) => _gestureInProgress = false,
    child: FlutterMap(...),
  )
  ```
- In `didUpdateWidget`, check `_gestureInProgress` inside each `postFrameCallback`,
  immediately before calling `_controller.move(...)`, in addition to the existing
  `mounted`/`_following` checks. Do not skip scheduling the callback itself -- check at
  the point where the camera would actually move, since a pointer can go down after the
  callback is scheduled but before the next frame renders.
- Leave `onPositionChanged`'s existing `hasGesture` check exactly as it is. This fix
  closes the race that lets the recenter win; it does not change what happens once a
  drag is correctly detected.

## Implementation
1. Add the `_gestureInProgress` field to `_RideMapState` in
   `lib/src/ui/components/ride_map.dart`.
2. Wrap the existing `FlutterMap` widget in a `Listener` with `onPointerDown`,
   `onPointerUp`, and `onPointerCancel` handlers that set `_gestureInProgress`.
3. Add `if (_gestureInProgress) return;` to both `postFrameCallback` bodies in
   `didUpdateWidget`, alongside the existing `if (!mounted || !_following) return;`
   check.
4. Add a widget test to `test/ride_map_test.dart` that reproduces the race directly:
   start a real drag with `tester.startGesture(...)`, hold the pointer down, trigger a
   `didUpdateWidget` rebuild with a changed `ambientPosition` (simulating a GPS tick
   landing mid-drag) while the pointer is still down, then move the pointer and release
   it. Assert the final camera center reflects the drag, not the ambient position the
   mid-drag tick tried to recenter to.
5. Run the app on the Android emulator. Set a mock GPS fix so ambient ticks keep
   arriving. Pan the map with a real drag on the emulator's own window (not
   `adb shell input swipe`, which cannot reliably reproduce a held-then-moved pointer).
   Confirm the camera stays where it was dragged to and does not snap back.

## Acceptance criteria
- [ ] A pan gesture on the idle Map tab moves the camera and it stays moved, even while
      ambient GPS fixes keep arriving once per second.
- [ ] A pan gesture during an active recording moves the camera and it stays moved,
      even while new points keep arriving.
- [ ] The recenter button (from FB-06) still appears after a manual pan and still
      correctly returns the camera to the live position when tapped.
- [ ] The new widget test reproduces the race and fails without the fix, passes with it.
- [ ] `flutter analyze` clean, `flutter test` green, test count only goes up.

## Tests
- New test in `test/ride_map_test.dart`: a real `tester.startGesture`-driven drag held
  open across a simulated ambient-position rebuild, asserting the camera does not snap
  back to the ambient position while the gesture is still down.
- Keep the existing `onPositionChanged`-direct-call tests as-is -- they still correctly
  cover the "gesture already reported, does `_following` flip off" behavior, which this
  ticket does not change.

## Risks
`Listener`'s `onPointerDown`/`onPointerUp` fire for every pointer, including a tap that
never becomes a drag (e.g. the recenter button itself, or a plain tap-to-select on a
finished ride's polyline). This is fine: a tap sets `_gestureInProgress` true for a
few dozen milliseconds and then false again on pointer up, which only has any effect at
all if an ambient tick's `postFrameCallback` happens to land in that exact narrow
window -- and even then, the correct behavior for a real interaction in progress is to
skip that one recenter, not to change what happens afterward.

## Out of scope
Any change to how often ambient position ticks arrive (`_interval` in
`geolocator_location_source.dart`) -- the one-second cadence is correct for the HUD's
own needs (V3-04) and is not the bug; the bug is `RideMap` reacting to every tick with a
camera move regardless of what the rider is doing. FB-11's Route Planner tile issue,
tracked separately.

## Outcome
Shipped exactly as designed, with no deviation.

`lib/src/ui/components/ride_map.dart` now has a `_gestureInProgress` field on
`_RideMapState`. The `FlutterMap` is wrapped in a `Listener` that sets it `true` on
`onPointerDown` and `false` on `onPointerUp`/`onPointerCancel`. The `Listener` only
observes pointer events; it does not consume them, so `flutter_map`'s own drag and
pinch-zoom recognizers still work untouched. Both `postFrameCallback` bodies in
`didUpdateWidget` now check `if (_gestureInProgress) return;` right before the
`_controller.move(...)` call, alongside the existing `mounted`/`_following` checks.
`onPositionChanged` was left alone, as the design said.

Added one new widget test to `test/ride_map_test.dart`, in the "always-interactive
map + recenter (FB-06)" group: `a real drag beats an ambient tick that lands
mid-drag (FB-10)`. It starts a real pointer with `tester.startGesture`, holds it
down, then rebuilds the widget with a changed `ambientPosition` to simulate a GPS
tick landing mid-drag, and asserts right there — before any pointer movement — that
the camera has not snapped to the ambient fix. It then moves and lifts the pointer
and asserts the same thing again for the completed drag.

Getting this test to actually catch the bug took one extra iteration. The first
version did the pointer-down, the mid-drag ambient tick, then a real move-and-lift,
and only checked the camera position at the very end. That version passed even with
the fix removed, because the final drag always overwrites the camera regardless of
what the buggy recenter did in between — a drag is relative motion, so wherever the
camera started, the drag moves it away from there, and the end position is never
exactly equal to the ambient fix either way. The fix was to add the same assertion
right after the mid-drag tick, before any pointer movement happens. At that point,
with the pointer down but not yet moved, the old code snaps the camera to exactly
the ambient position (confirmed by temporarily removing the two
`_gestureInProgress` guards and re-running: the test failed with `Actual: <51.5>`,
the exact ambient fix latitude); the fixed code leaves the camera where it was.
Both the "old code fails, fixed code passes" checks were run and confirmed before
finishing.

One unrelated flake showed up during a full `flutter test` run:
`test/geo_test.dart`'s "douglas-peucker handles a full ride without stack overflow
and stays fast" failed once, then passed on every subsequent run in isolation and in
the full suite. It looks like a timing-sensitive performance assertion, not
something this change touches -- `ride_map.dart` and `geo.dart` share no code path.

`flutter analyze` stayed clean: the same 4 pre-existing info-level issues in
`crash_reporter.dart` and `map_connectivity.dart`, nothing new. `flutter test` went
from 434 to 435 passing (the one new test), everything else green.

No Android emulator or `adb` was available in this environment, so the on-device
check in Implementation step 5 was not attempted here. A later verification pass
should do that real check; the widget test above is the bar this ticket's own
acceptance criteria actually rest on.