Repository navigation
First-person navigation: course-up pitched camera, maneuver banner and compact strip - #28
Conversation
… navigation snapshot Native: keep raw OSRM maneuver facts (type, modifier, exit, name, ref, bearings, driving side) beside Ferrostar's parsed steps, index maneuvers into the immutable route geometry, and publish upcoming/following maneuvers with ids tied to the route revision, the route-relative progress offset, Ferrostar's snapped position with an alignment state, and speed/course/accuracies/monotonic fix time. Payloads stay free of null/NaN. TypeScript: snapshot types, a route measure using the native metric, and a pure first-person camera planner with deterministic fixtures (straight, turns, close turns, roundabout, U-turn, stop/start, deviation, degraded fixes, arrival, bearing wraparound, duplicate timestamps).
The guidance map is now app-controlled: one native ease per distinct accepted fix (linear over the measured fix interval, so puck and map share one clock and React renders at 1 Hz), course-up with circular filtering and a held bearing when slow, per-mode pitch/zoom, and the puck anchored low in the map between banner and bottom strip through top padding. Turn framing keeps the junction and outgoing path in view from 8/10/12 s before the maneuver and releases over 2-3 s. Cycling and driving add a bounded presentation-only lead that never crosses the upcoming maneuver and stops on degraded or late fixes. Camera intent is follow / free / overview: a gesture enters free at gesture start and blocks pending moves; overview frames the remaining route north-up once; Ricentra restores the follow pose in one 500 ms move; fixes and reroutes never take the camera back. The puck is original artwork (wedge with live centre, disc without a direction, subdued ring for a retained position), drawn at the anchor while following and as a map symbol otherwise. Development builds log MapLibre's own projection of the anchor and junction for assertions.
… route split and turn arrow Banner: original maneuver glyphs from the OSRM type/modifier (straight, slight/normal/sharp turns, U-turn, fork, merge, ramps, roundabouts with exit number and circulation, arrival; unknown maneuvers keep a neutral glyph with the supplied text), the distance in heavy Mona Sans with a smaller unit, street and action in Geist with two lines reserved, and a reserved row for 'Poi ...' (only when the following maneuver is within about ten seconds of travel) or status (rerouting, off route, reduced precision, paused with the last instruction). No state changes the banner or strip height, so the camera anchor never jumps. Strip: arrival labelled as an estimate without traffic, remaining time and distance, distinct voice states, overview and Interrompi; the summary opens details; problems and Retry float above the strip; a paused position shows 'Stima sospesa' instead of an apparently current ETA. Map: muted travelled route under the active remaining line (cut by the native progress through line-gradient), one cased arrow through the next junction from the real geometry, generic business labels hidden while driving or cycling, one-way chevrons while driving (a hidden brand basemap layer adopted under an app source so live theme switches keep it). Transit access/transfer/final walks use the walking camera when a usable fix exists and otherwise frame the current leg. Leaving guidance returns the browsing map to north-up and flat.
Ricentra, the problem row and transit confirmations float above the strip from the screen container: Android delivers no touches to views drawn outside their parent's bounds. Record the emulator replay evidence for first-person guidance in the delivery notes.
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
Warning Review limit reachedYou've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. Next included review available in 11 minutes. View limit details
|
| Layer / File(s) | Summary |
|---|---|
Native guidance data and runtime src/domain/navigation.ts, modules/avoid-navigation/android/src/main/java/quest/avoid/maps/navigation/*, modules/avoid-navigation/android/src/test/java/quest/avoid/maps/navigation/GuidanceModelTest.kt |
Adds navigation snapshot types and Android parsing and indexing for maneuver facts. Runtime updates publish maneuver details, route progress, snapped location, alignment, and fix kinematics. |
Route measurement and camera planning src/features/navigation/route-measure.ts, src/features/navigation/map-projection.ts, src/features/navigation/guidance-camera.ts, src/features/navigation/guidance-route.ts, src/features/navigation/guidance-fixtures.ts, src/features/navigation/*test.ts |
Adds route measurement, map projection, per-mode camera frames, route progress styling calculations, and maneuver arrows. Tests cover camera behavior, route geometry, and guidance calculations. |
Guidance state and camera integration src/features/navigation/useGuidanceCamera.ts, src/features/navigation/useMapCamera.ts, src/features/map/MapCanvas*, src/features/map/useGuidanceCameraDriver.ts, src/features/app/AppMap.tsx, src/features/app/AppShell.tsx |
Connects navigation state and measured panel layout to guidance camera state. Map camera controls handle follow, free, and overview intent, and MapCanvas applies guidance camera commands. |
Guidance map layers and assets src/features/map/GuidanceMapLayers.tsx, src/features/map/guidance-puck.ts, src/theme/brand-basemap.ts, src/theme/palette.ts, scripts/render-navigation-assets.mjs, src/theme/*test.ts |
Adds guidance route layers, puck symbols, and one-way arrows. The asset script generates navigation PNGs and checks them; theme definitions include a traveled-route color. |
Maneuver interface and guidance documentation src/features/navigation/maneuver-presentation.ts, src/features/navigation/ManeuverGlyphImage.tsx, src/features/navigation/NavigationPanel.tsx, src/features/navigation/TransitFollowPanel.tsx, docs/development/* |
Adds maneuver glyph and banner presentation, a compact navigation strip and overlay controls, and panel layout reporting. Development documentation describes the guidance behavior and emulator checks. |
Estimated code review effort: 4 (Complex) | ~60 minutes
Change: Feature
Sequence Diagram(s)
sequenceDiagram
participant AppShell
participant AppMap
participant useGuidanceCamera
participant MapCanvas
participant useGuidanceCameraDriver
participant MapLibre
AppShell->>AppMap: Pass measured guidance viewport
AppMap->>useGuidanceCamera: Provide navigation state and viewport
useGuidanceCamera-->>AppMap: Return guidance map state
AppMap->>MapCanvas: Pass guidance state
MapCanvas->>useGuidanceCameraDriver: Provide camera state and map commands
useGuidanceCameraDriver->>MapLibre: easeTo or fitBounds
Possibly related PRs
- avoid-quest/maps#16: Defines accepted native fixes and location states used by this PR’s camera planning.
- avoid-quest/maps#11: Establishes the navigation UI and map-camera modules that this PR extends.
- avoid-quest/maps#25: Adds the transit plan and follow-panel flow used by this PR’s transit guidance handling.
Merge Risk: 
Moderate · previous review df43e
-
After guidance stops, the browsing map can stay tilted and rotated instead of returning to north-up and flat. On phones in landscape, the guidance camera frames the puck and turns within a very small area. Fix the exit reset before merging; the remaining findings are minor.
Pre-merge checks: 
4 · 
1
-
Failed checks: 1 warning Passed checks: 4 passedFull details: Docstring Coverage
-
Explanation
Docstring coverage is 66.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 50 functions across 32 files. (3 skipped: 3 unsupported.)
Resolution
Write docstrings for the functions missing them to satisfy the coverage threshold.
-
Finishing Touches
-
Generate docstrings
-
- Commit to this branch
- Create a new PR
Generate unit tests (beta)
-
- Commit to this branch
- Create a new PR
-
- Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: df43e5e5ad
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| if (!loaded || frame || !fit || intent !== 'follow' || gestureActive.current || fitIssued.current === fit.key) return; | ||
| fitIssued.current = fit.key; |
There was a problem hiding this comment.
Honor transit recenter requests without a walking frame
During a transit ride, while waiting to board, or during a walk without a usable fix, useGuidanceCamera returns no camera frame. After the current leg has been fitted once, panning and pressing Ricentra changes the intent back to follow, but this guard rejects the unchanged leg key; the recenter counter is only consumed when a walking frame exists. Consequently, the visible Ricentra control does not move the map back. Include explicit recenter requests in the fit identity or otherwise issue a new fit when returning from free mode.
Useful? React with 👍 / 👎.
| {then ? <> | ||
| <Text className="text-sm font-semibold text-secondary">Poi</Text> | ||
| <ManeuverGlyphImage glyph={maneuverGlyph(then)} size={22} color={colors.textSecondary} /> | ||
| <Text numberOfLines={1} className="min-w-0 flex-1 text-sm text-secondary">{maneuverLines(then, then.instruction).secondary ?? then.instruction}</Text> | ||
| </> : status ? <Num testID="navigation-status" accessibilityLiveRegion="polite" numberOfLines={1} className={`min-w-0 flex-1 text-sm font-semibold ${statusTone}`}>{status}</Num> : null} |
There was a problem hiding this comment.
Keep reduced-precision warnings visible beside chained turns
When a following maneuver qualifies for the “Poi” row, this conditional suppresses status, including text.precision. Accepted reduced-precision fixes do not necessarily set snapshot.problem, so the separate problem overlay does not restore the warning; the accuracy limitation is then only available inside the details modal. The previous panel displayed precision independently of the next instruction. Preserve a visible precision warning even when showing chained maneuvers, rather than presenting those instructions without their location uncertainty.
AGENTS.md reference: AGENTS.md:L7-L7
Useful? React with 👍 / 👎.
| leftGuidance.current = false; | ||
| let current = true; | ||
| const issued = commands.current; | ||
| void map.current?.getCenter().then(center => { | ||
| if (current && issued === commands.current) camera.current?.easeTo({ center, padding: { top, right, bottom, left }, duration: 250 }); | ||
| if (current && issued === commands.current) camera.current?.easeTo({ center, ...pose, padding: { top, right, bottom, left }, duration: 250 }); |
There was a problem hiding this comment.
Preserve the orientation reset when leaving guidance
When guidance closes, this effect captures commands.current and waits asynchronously for getCenter(), but the browsing-centering effect at line 70 runs in the same effect flush because guiding and followLocation changed, incrementing that counter. The callback therefore skips the only command containing bearing: 0, pitch: 0, while leftGuidance.current has already been cleared. The browsing move supplies neither orientation field, leaving the map pitched and course-up after navigation ends. Apply the reset in the winning browsing command or retain it until a reset command actually executes.
Useful? React with 👍 / 👎.
| <View style={{ minHeight: Math.round(52 * Math.min(fontScale, 1.5)) }}> | ||
| <Text accessibilityLiveRegion="polite" numberOfLines={2} className="text-xl font-semibold leading-7 text-primary">{lines.primary}</Text> | ||
| {lines.secondary ? <Text numberOfLines={1} className="text-base leading-6 text-secondary">{lines.secondary}</Text> : null} |
There was a problem hiding this comment.
Reserve enough banner height for a wrapped street and action
When a street name wraps to two lines and has a secondary action, these children require 80 dp at the default font scale: two 28 dp primary lines plus a 24 dp action. The container reserves only 52 dp and can grow, so switching between short and wrapped street names changes the banner height by 28 dp. That height is reported through onChromeLayout, changing the guidance viewport and causing GuidanceCamera.update to issue a layout-recovery camera move even without a new fix; entering rerouting can shrink it again. Reserve a consistent height for all allowed text lines so maneuver changes and status transitions do not resize the banner and disturb the following camera.
Useful? React with 👍 / 👎.
- Derive motion honestly when the platform omits speed/course: a displacement must clear the combined horizontal accuracy (min 3 m, 10 s window), motion needs two consistent estimates, course accuracy is geometric; stationary jitter yields no speed, course or lead. - Show status in its own pill below the banner so 'Poi' never hides a reduced-precision or pause warning; both are in the spoken label. - Transit ride/wait: Ricentra re-fits the current leg (the recenter request is part of the fit identity); one pure command decision. - Keep the north-up/flat reset after guidance until a browse command that is actually issued carries it; a user gesture cancels it. - Model the visible map as a rectangle with horizontal insets (landscape side panel) for anchoring, projection and fits. - Fixed banner row heights measured per font scale (text capped at 2x); one street line when an action line is shown. - Stack the bottom strip on narrow screens or large text. - Lay the roundabout exit number beside its glyph, sized in proportion. - '1 chilometro' for 1000-1049 m. - One-way chevrons also on reverse one-way roads (oneway = -1).
Summary
First-person navigation: an app-controlled, course-up, pitched follow camera driven only by accepted native fixes, an original directional puck, a maneuver banner, a compact bottom strip, traveled/remaining route rendering and one cased arrow through the next junction.
Deferred: 3D buildings, compass heading for walking, lane guidance.
Evidence
Android 16 emulator, replayed 1 Hz traces (walk, bike, drive, day/night, transit access walk), screen recordings + screenshots:
bun run verify: typecheck, zero-warning lint, 531 tests.:avoid-navigation:testDebugUnitTest: 87 tests. Rust harness not run (no cargo).Merge Danger
Door: two-way
Blast Radius: navigation
Navigation camera, panel and native snapshot; browsing map unaffected (navigation exit restores north-up and flat).
Summary by cubic
Implements first-person road navigation: an app-controlled, course-up, pitched follow camera driven only by accepted native fixes, with a maneuver banner, compact bottom strip, traveled/remaining route rendering and an original directional puck. The native snapshot now carries structured maneuvers and kinematics, and the camera runs as follow, free, or overview without fixes or reroutes ever reclaiming it.
Native snapshot
Camera and screen
Transit access, transfer, and final walks use the walking camera; 3D buildings, walking compass heading and lane guidance remain deferred.
Written for commit 973e4d9. Summary will update on new commits.
Summary by CodeRabbit
New Features
Documentation