iOS - Track distance - Route line not drawn after backgrounding app during GPS tracking

[melvin-bot]

Problem
When tracking distance via GPS, if the app is backgrounded for an extended period during the trip and then reopened after the trip finishes, the route line is not drawn on the map. The map view is missing the route until the app is fully closed and reopened.

Platform: iOS

Steps to reproduce

1. Start GPS distance tracking.
2. Background the app and go on a trip (extended time backgrounded).
3. Finish the trip and reopen the app.
4. Observe the map — the route line is not drawn.

Expected result
The route line should be drawn on the map when returning to the app after the trip.

Actual result
The route line is missing. Fully closing and reopening the app draws the route line correctly.

Notes
Suspected to be related to map layer ordering on iOS, specific to the GPS map view variant (the route line draws correctly on the confirmation screen). A fix is already in progress and this issue is being created to link that PR.

Reported in Slack.

Issue Owner

Current Issue Owner: @dukenv0307

[MelvinBot]

Issue Analysis

Root Cause: The GPS live-tracking map anchors its route line and waypoint layers using Mapbox belowLayerID, gated on a fragile isLocationPuckLayerReady flag that is only ever set true by the one-shot onDidFinishRenderingFrameFully callback. After an extended background on iOS, the JS context stays alive (so isLocationPuckLayerReady remains true) while the native Mapbox layers get torn down and recreated. On the return-from-background render, the route LineLayer mounts with belowLayerID="waypoints" before that layer exists natively, so @rnmapbox/maps silently drops the insertion and the route never draws. A full close/reopen resets the flag to false, so the route mounts with belowLayerID=undefined (drawn on top, insertion always succeeds) — which is why the workaround fixes it. The confirmation-screen map is unaffected because it renders the route with no belowLayerID at all.

Fix status: A fix is already in progress — Expensify/App#98891 "Fix layers ordering in GPSMapView" (OPEN) links this issue. It drops the onDidFinishRenderingFrameFully + key-remount logic in favor of a LayerOrderAnchors component that renders stable empty anchor layers, so route/waypoint layers always anchor to layers that exist. The fix is entirely in Expensify/App (JS/TS) — no native/Mobile-Expensify change needed.

Investigation details

All references at SHA 07a4f68bb5b0d9160721b98c59925584a5728c3e.

1. Gated layer anchoring (the bug): GPSMapView.tsx:292-311 — waypoint SymbolLayer uses belowLayerID={isLocationPuckLayerReady ? LOCATION_PUCK_LAYER_ID : undefined} and the route uses belowLayerID={isLocationPuckLayerReady ? CONST.MAP_VIEW_LAYERS.WAYPOINTS : undefined}.
2. Readiness never re-sequenced after foreground: GPSMapView.tsx:177-194 — the guard if (hasSetLocationPuckLayerReady.current && foregroundLocationPermissionsGranted) return; means the flag stays true on background-restore, so the route mounts referencing a not-yet-created waypoints layer.
3. Route LineLayer that silently fails when its anchor is missing: Direction.tsx:70-79.
4. Working confirmation map (no belowLayerID): Directions.tsx:46.

Reproduction flow: fresh launch → isLocationPuckLayerReady=false → route drawn on top (works) → callback flips flag true → re-anchored correctly. Extended background → iOS tears down native layers, JS flag stays true → foreground re-render mounts route with belowLayerID="waypoints" before that layer exists → insertion dropped → route missing until full app restart.

Alternatives considered: Onyx state loss / breadcrumb data being cleared on background was ruled out — the route data is still present (it renders after a full restart, and waypoints/confirmation map are unaffected), so this is a layer-insertion ordering problem, not a data problem.

Note: iOS-native testing was out of scope for this run (the configured platform was web), so this analysis is code-based; the confirmation is corroborated by the linked PR's description and test plan, which independently describe the same belowLayerID mechanism.

---

Since Expensify/App#98891 already implements this fix, no new implementation is needed — this analysis is for confirmation/linking. Reply with @MelvinBot <your feedback> to refine it.