docs planning NATIVE_NAVIGATION_PLAN

Native navigation like CoMaps (route from my position, follow camera, voice)

Status: PLANNED (2026-10-28). Owner track: MC-C7 in MAP_COMPLETION_PLAN.md. Engine: pinned CoMaps 4587b8ad SDK (maps/engine/vendor/sdk-release.aar). Delivery: one planning stage = one PR (codex/phase-native-navigation).

1. Goal

Inside the Abastevo map, a driver gets the same routing experience as the CoMaps app: tap a station (or any point) → route from the current location → preview → Start → animated follow/perspective camera with the my-position arrow, turn panel, voice, automatic rerouting and arrival, in the foreground and with the screen off, offline once the region is installed.

"Online" and "offline" use the same engine: CoMaps routes only from the local .mwm routing sections, with no server routing or live traffic. Online only adds downloading a missing region, which goes through the Abastevo signed distribution, not CoMaps servers.

2. Baseline (what exists, verified 2026-10-28)

Already in place:

Area	State
Route build	ComapsRoutePlanner (maps/engine/.../ComapsRoutePlanner.kt): car/avoid options, preview distance/time/geometry/steps. It owns the native routing listener, so the SDK RoutingController is bypassed.
Follow route	ComapsMapEngine.startGuidance calls nativeFollowRoute. The native camera (DrapeEngine::FollowRoute, navigation scale, 3D, rotation) runs once fixes arrive and a surface is rendered. Not yet verified visually.
Fix feed	GuidanceService (location foreground service, GPS at 1 Hz) → NavigationFixPolicy → NavigationFixBridge → LocationState.nativeLocationUpdated.
Reroute	Native reroute plus a 60 s "not recoverable" timeout (GuidancePolicy).
Voice	LocalGuidanceVoice (Android TTS, local voices only, audio focus).
Recovery	GuidanceRecoveryStore with explicit resume, and a map-generation lease.
Tests	Domain/application/engine JVM tests, plus device tests GuidanceEngineInstrumentedTest, GuidanceInstrumentedTest, NativeRoutePlannerInstrumentedTest and NativeRouteCrossRegionInstrumentedTest.

Gaps against CoMaps:

1. Start point. Every point is added with isMyPosition=false. The start is a one-shot "Current" coordinate, and the station "Route" action fills only the destination.
2. My position. The SDK LocationHelper is never started. There is no LocationState mode machine, no my-position arrow outside guidance and no compass. recenter() reads locationHelper.myPosition, which is null, so it likely always reports "no-fix".
3. Guidance UI. Guidance controls live inside the dismissible route sheet (MapScreen.kt:119). There is no on-map turn panel or bottom navigation bar.
4. Dropped turn data. toNavigationProgress drops lanes, exit number, then-turn, speed limit, current street, road shields and distToNextStop.
5. Voice.
   • Only notifications.firstOrNull() is spoken.
   • LocalGuidanceVoice.start() waits up to 8 s on the main thread for TTS onInit, which is also delivered on main. This is a suspected stall followed by "voice unavailable". Confirm it first.
6. No arrival handling. nativeIsRouteFinished is never called.
7. Notification. It is static: no turn, distance or street.
8. Permissions. The guidance UI never requests FINE location or (API 33+) POST_NOTIFICATIONS, so GuidanceService refuses to start silently.
9. No camera tuning. There is no 3D/auto-zoom setting and no updateMyPositionRoutingOffset for the bottom panel.
10. Contract conflict. docs/product/MAP_21_23_CONTRACT.md says "browsing never starts continuous GPS". CoMaps tracks location whenever the map is visible and the user enabled it.

All SDK classes and natives needed are present in the shipped jar and in both liborganicmaps.so ABIs:

• Classes: RoutingController, LocationHelper, LocationState, TtsPlayer, CarDirection, RoutingInfo, LaneInfo, RoadShieldUtils, RouteSimulationProvider, MapController.updateMyPositionRoutingOffset, SensorHelper.
• Framework natives: nativeFollowRoute, nativeIsRouteFinished, nativeSetAutoReroute, nativeSet3dMode, nativeSetAutoZoomEnabled, nativeGetIntermediateStopsProgress.

The UI layer is app-only in CoMaps and must be ported:

• Navigation views: NavigationController, NavMenu, LanesView, SpeedLimitView.
• Location and service: MyPositionButton, NavigationService.
• Routing plan fragments.

3. Phases

Each task follows B-BR/BUC → RED → GREEN → REFACTOR, runs its targeted tests, and is verified on the POCO with the release build (test key) before the phase closes.

NAV-0 Decisions and contract (blocking, no code)

• NAV-0.1 Product decision. Continuous location while the Map tab is visible, only after the user taps my-position or starts a route. The default stays "no GPS while browsing". Stop on background unless navigating. Update MAP_21_23_CONTRACT.md and the scripts/check-mobile.sh location allowlist in the same task.

• NAV-0.2 Licence record. Porting CoMaps android/app code (Apache-2.0) to Kotlin is allowed if we:

  • keep the Apache header and NOTICE on ported files;
  • mark the files as modified (§4(b));
  • use no CoMaps/Organic Maps branding;
  • copy only drawables whose provenance in data/copyright.html allows it. The turn icons already ship in the AAR.

  Record this in maps/engine/vendor/NOTICE and in an evidence note.

• NAV-0.3 Engine ownership. Keep the Abastevo planner as the single owner of the native routing listener. It is stricter on NEED_MORE_MAPS than the SDK RoutingController. Do not mix in RoutingController; document why.

NAV-1 My position and recenter (CoMaps parity)

• NAV-1.1 Single location feed.
  • Start the SDK LocationHelper (start/restartWithNewMode/addListener, 500 ms) while the map is foreground and location is enabled. Stop it on ON_STOP unless navigating.
  • GuidanceService reuses the same feed instead of its own GPS_PROVIDER subscription. One feed means one arrow.
  • Keep NavigationFixPolicy as a filter, but relax the 50 m accuracy cap to CoMaps behaviour: accept GPS-provider fixes and let the core weight accuracy. Add an urban-canyon test.
• NAV-1.2 Mode machine.
  • Register LocationState.nativeSetListener. Expose MyPositionMode (PENDING, NOT_FOLLOW_NO_POSITION, NOT_FOLLOW, FOLLOW, FOLLOW_AND_ROTATE) in MapUiState.
  • Report denial and GPS off through nativeOnLocationError.
  • Never call getMode() before the drape engine exists.
• NAV-1.3 My-position button. Port MyPositionButton to Compose, with a per-mode icon and a nativeSwitchToNextMode click. It replaces today's one-shot recenter. A permission request on first tap; the pending spinner state.
• NAV-1.4 Compass. SensorHelper → Map.onCompassUpdated for FOLLOW_AND_ROTATE.
• Tests:
  • JVM: mode reducer and permission states.
  • Device: the arrow appears, a pan leaves FOLLOW and a tap returns to it. Use simulated locations (RouteSimulationProvider) and no real-user GPS in fixtures.

NAV-2 Route from my position

• NAV-2.1 Add a "Minha localização" start point with isMyPosition=true (nativeAddRoutePoint type START). This is the default origin.
  • The core then routes and reroutes from the live MyPositionMark.
  • Map NO_POSITION (2) to a pending state that waits for the first fix (nativeStartPendingPositionMode), then builds.
• NAV-2.2 The station sheet "Rota" sets origin = my position and destination = station, then opens the preview directly, as CoMaps startLocationToPoint does.
• NAV-2.3 Missing region (NEED_MORE_MAPS) → the Abastevo regional download card or screen for the named regions, then rebuild.
• Tests: planner JVM tests for the start type and the NO_POSITION path; device test station → preview offline in Mato Grosso.

NAV-3 Route preview on the map

• NAV-3.1 Replace the modal sheet with an on-map preview. A bottom card shows time, distance, ETA (local clock), avoid chips and Start. A steps sheet shows CarDirection.getTurnRes() icons and street names. The route line is drawn by the core.
• NAV-3.2 Before Start, request FINE location and POST_NOTIFICATIONS (API 33+) in context. On refusal, explain once and keep the preview usable. Mirror CoMaps requestPostNotificationsPermission.
• NAV-3.3 Visible rect: nativeSetVisibleRect so the route fits above the card.

NAV-4 Navigation mode (the "Google/CoMaps feel")

• NAV-4.1 Data. Extend NavigationProgress with:

  • nextCarDirection, exitNum, lanes, currentStreet, nextStreet (with road shields via RoadShieldUtils);
  • speedLimitMps, distToNextStop, isLeftHandTraffic, shouldPlayWarningSignal;
  • nativeGetIntermediateStopsProgress.

  Pure domain value objects; mapping tests.

• NAV-4.2 Turn panel (top, Compose port of NavigationController and LanesView): turn icon, distance to the turn (nativeFormatSpeed/distance formatting), then-turn, roundabout exit, lanes, street with shields.

• NAV-4.3 Bottom bar (port of NavMenu and RouteProgressBar): ETA clock, time left, distance left, progress, mute, stop. Current speed vs speed limit (SpeedLimitView).

• NAV-4.4 Camera.

  • nativeSet3dMode(true, buildings) and nativeSetAutoZoomEnabled(true) as the defaults, both editable in settings.
  • updateMyPositionRoutingOffset(bottomBarHeight) through a new same-package accessor in MapViewHelper.
  • Feed fixes at 2 Hz.
  • The native follow camera returns to FOLLOW 20 s after a pan (kMaxNotFollowRoutingTimeSec). Show a "Recentralizar" chip meanwhile.

• NAV-4.5 Surface rules. Navigation keeps a live MapView while foreground. nativeFollowRoute without a rendered surface crashed (MAP-23 defect 1). Background continues through the service with the surface released safely; add a regression test.

• NAV-4.6 Screen. FLAG_KEEP_SCREEN_ON while navigating. Prompt once about battery optimisation, as CoMaps does.

NAV-5 Voice

• NAV-5.1 Initialise TTS asynchronously, never blocking main. Fix the suspected 8 s stall with a device test that starts the service from the main thread.
• NAV-5.2 Speak every string from nativeGenerateNotifications(announceStreets), in order, as TtsPlayer.playTurnNotifications does. Turn texts come from the native sound-strings (pt-BR ships in the AAR).
• NAV-5.3 Voice settings: on/off, language (supported list from TtsPlayer natives), street names, and a test voice. The mute toggle sits in the bottom bar.

NAV-6 Background, rerouting and arrival

• NAV-6.1 Live notification: turn bitmap, distance and street; CATEGORY_NAVIGATION, low importance; a tap opens the map in navigation mode.
• NAV-6.2 nativeSetAutoReroute(true) at init.
  • Show "Recalculando…" on OffRoute/RouteRebuilding.
  • Native rebuild errors are silent (no NEED_MORE_MAPS callback), so keep the 60 s recoverable timeout and offer the download when the position leaves the installed regions.
• NAV-6.3 Arrival. After each fix, if nativeIsRouteFinished():
  • speak the last notification;
  • stop guidance and the service;
  • show an arrival card with the station's profile and price contribution.
• NAV-6.4 Speed cameras. nativeSetSpeedCamManagerMode, plus a beep through MediaPlayerWrapper and our own raw asset (none ships in the AAR).

NAV-7 Offline and cross-region

• NAV-7.1 Airplane-mode journey (MC-C8 leg): MT installed, airplane on, station → route → navigation → arrival.
• NAV-7.2 Cross-region route with the generated packages, for example Sorriso (MT) → Goiânia (GO). The routers match border twins by OSM way and segment, so the generated cross_mwm sections must agree.
  • If routes fail or detour, regenerate the neighbouring regions from the same PBF date with cross-MWM transitions intact (and --world-roads if long leaps need it).
  • Add a per-region minimum-transitions check to generate-regional-map.sh.
• NAV-7.3 Missing-map detection relies on SDK countries.txt/packed_polygons.bin ids matching the generated file names (Brazil_Mato Grosso). Lock this in with a test over all 23 regions.

NAV-8 Acceptance

• Instrumented journeys with LocationHelper.startNavigationSimulation(nativeGetRouteJunctionPoints): preview → start → turn panel updates → off-route → reroute → arrival. Offline and online, light and dark.
• Field drive in Sorriso with screen recording: follow camera, rotation, voice, a wrong turn and its reroute, arrival, screen off and on. Record timings in docs/backend/evidence/maps/NAV.md.
• Gates:
  • Android: :domain:test :data:testDebugUnitTest :application:test :maps:engine:testDebugUnitTest :app:testDebugUnitTest :app:lintDebug :app:assembleRelease (APK ≤ 80 MiB).
  • Mobile guard: scripts/check-mobile.sh with the updated allowlist.

4. Order, size and risks

Order: NAV-0 → NAV-1 → NAV-2 → NAV-3 → NAV-4 → NAV-5 → NAV-6 → NAV-7 → NAV-8. NAV-5.1 can start in parallel at any time, because it is a likely defect today.

Rough size, one engineer with the device:

Phases	Days
NAV-0	0.5
NAV-1	2
NAV-2	1
NAV-3	2
NAV-4	4
NAV-5	1
NAV-6	2
NAV-7	1–3 (depends on regeneration)
NAV-8	1.5
Total	≈ 15–17 working days

Risks:

• Product contract. The NAV-0.1 location decision is blocking.
• Native crashes without a surface. Covered by NAV-4.5.
• Cross-region routing on generated packages. Covered by NAV-7.2.
• TTS stall. Covered by NAV-5.1.
• Guard updates. The check-mobile.sh location allowlist must change in the same commits as the location code.