@glassly/engine 0.1.0-dev.0

package/src/services/NavigationService.ts

@@ -0,0 +1,926 @@
+/**
+ * NavigationService
+ *
+ * Thin singleton wrapper around the native Mapbox Navigation SDK exposed
+ * by the `crust` Expo module.
+ *
+ * Mini apps will eventually subscribe through the mini app SDK, which
+ * routes via LocalMiniappRuntime and ultimately calls into here. For now,
+ * this is also called directly by the developer-settings test button.
+ *
+ * Works on both Android and iOS via the native Mapbox Navigation SDK.
+ */
+
+import CrustModule from "@glassly/crust"
+
+import {resolveMapboxAccessToken, resolveMapboxRenderToken, userMapboxApiKey} from "./MapboxTokenService"
+import {decodePolyline, parseDurationSeconds} from "./navigation/routesApiCodec"
+import {resolveStepRoads} from "./navigation/roadNameResolver"
+
+const LOG_TAG = "NAV_SERVICE"
+
+export type NavManeuver = {
+  kind: "maneuver"
+  /**
+   * Categorical type of the upcoming maneuver. One of: STRAIGHT,
+   * SLIGHT_LEFT, SLIGHT_RIGHT, TURN_LEFT, TURN_RIGHT, SHARP_LEFT,
+   * SHARP_RIGHT, U_TURN, ARRIVE.
+   */
+  maneuverType: string
+  distanceMeters: number
+  /** Road the user is currently on. Null if the SDK didn't supply one. */
+  fromRoad?: string | null
+  /** Road the user will be on after the maneuver. Null if the SDK didn't supply one. */
+  toRoad?: string | null
+  distanceToDestinationMeters?: number
+  timeToDestinationSeconds?: number
+  currentSpeedMps?: number | null
+  speedLimitMps?: number | null
+  routeHeadingDeg?: number | null
+}
+
+export type NavOffRoute = {
+  kind: "off_route"
+  offRouteDistanceMeters: number
+}
+
+export type NavRerouting = {kind: "rerouting"}
+export type NavArrived = {kind: "arrived"}
+export type NavError = {kind: "error"; message: string}
+
+export type NavUpdate = NavManeuver | NavOffRoute | NavRerouting | NavArrived | NavError
+
+export type NavListener = (update: NavUpdate) => void
+
+export type NavLocation = {
+  lat: number
+  lng: number
+  accuracy: number | null
+  timestamp: number
+}
+export type NavLocationListener = (loc: NavLocation) => void
+
+export type NavRouteStep = {
+  lat: number
+  lng: number
+  routeIndex: number
+  road: string | null
+  maneuver: string
+  distanceMeters: number
+}
+export type NavRoute = {
+  points: Array<{lat: number; lng: number}>
+  steps?: NavRouteStep[]
+}
+export type NavRouteListener = (route: NavRoute) => void
+
+export type NavState = "idle" | "navigating" | "rerouting" | "arrived"
+
+/**
+ * Snapshot of the active trip — fed to miniapps that open mid-trip via
+ * `navigation.getState()`. Mirrors the SDK's NavState shape closely; the
+ * runtime keeps it strictly in sync as nav events arrive.
+ */
+export type NavTripSnapshot = {
+  active: boolean
+  mode?: string
+  stops?: Array<{lat: number; lng: number}>
+  currentStopIndex?: number
+  route?: NavRoute
+  maneuver?: NavManeuver
+  distanceToDestinationMeters?: number
+  timeToDestinationSeconds?: number
+  currentSpeedMps?: number | null
+  speedLimitMps?: number | null
+}
+
+class NavigationService {
+  private static instance: NavigationService | null = null
+  private listeners = new Set<NavListener>()
+  private locationListeners = new Set<NavLocationListener>()
+  private routeListeners = new Set<NavRouteListener>()
+  private subs: Array<{remove: () => void}> = []
+  private state: NavState = "idle"
+  /** Last emitted route — replayed to late subscribers so they get the
+   *  current geometry immediately. */
+  private lastRoute: NavRoute | null = null
+  /** Last maneuver event observed — used to hydrate getState() on mid-trip mount. */
+  private lastManeuver: NavManeuver | null = null
+  /** Trip configuration captured at start(), surfaced via getState(). */
+  private tripStops: Array<{lat: number; lng: number}> = []
+  private tripMode: string = "driving"
+
+  private constructor() {}
+
+  public static getInstance(): NavigationService {
+    if (!NavigationService.instance) {
+      NavigationService.instance = new NavigationService()
+    }
+    return NavigationService.instance
+  }
+
+  public getState(): NavState {
+    return this.state
+  }
+
+  public addListener(listener: NavListener): () => void {
+    this.listeners.add(listener)
+    if (this.subs.length === 0) {
+      this.attachNativeSubs()
+    }
+    return () => {
+      this.listeners.delete(listener)
+      if (this.noListeners()) {
+        this.detachNativeSubs()
+      }
+    }
+  }
+
+  /**
+   * Subscribe to the Mapbox Nav SDK's road-snapped location stream. Only
+   * fires while a nav session is active. Returns an unsubscribe fn.
+   */
+  public addLocationListener(listener: NavLocationListener): () => void {
+    this.locationListeners.add(listener)
+    if (this.subs.length === 0) {
+      this.attachNativeSubs()
+    }
+    return () => {
+      this.locationListeners.delete(listener)
+      if (this.noListeners()) {
+        this.detachNativeSubs()
+      }
+    }
+  }
+
+  /**
+   * Subscribe to the active route's polyline. Fires once per route build
+   * (initial + after every reroute). Late subscribers get the current
+   * route replayed on subscribe so the UI can render immediately.
+   */
+  public addRouteListener(listener: NavRouteListener): () => void {
+    this.routeListeners.add(listener)
+    if (this.subs.length === 0) {
+      this.attachNativeSubs()
+    }
+    if (this.lastRoute) {
+      try {
+        listener(this.lastRoute)
+      } catch (err) {
+        console.error(`${LOG_TAG}: route listener threw on replay`, err)
+      }
+    }
+    return () => {
+      this.routeListeners.delete(listener)
+      if (this.noListeners()) {
+        this.detachNativeSubs()
+      }
+    }
+  }
+
+  private noListeners(): boolean {
+    return this.listeners.size === 0 && this.locationListeners.size === 0 && this.routeListeners.size === 0
+  }
+
+  public async start(
+    coords: {lat: number; lng: number},
+    options?: {
+      simulate?: boolean
+      speedMultiplier?: number
+      stops?: Array<{lat: number; lng: number}>
+      mode?: string
+      avoid?: {highways?: boolean; tolls?: boolean; ferries?: boolean}
+      missedTurnRerouteMeters?: number
+    },
+  ): Promise<{ok: boolean; error?: string}> {
+    console.log(
+      `${LOG_TAG}: start ${coords.lat},${coords.lng} sim=${options?.simulate ?? false} speed=${options?.speedMultiplier ?? 5}`,
+    )
+    if (this.subs.length === 0) {
+      // Listeners may attach after start(); make sure native subs exist
+      // so we don't drop early events.
+      this.attachNativeSubs()
+    }
+    // Resolve the token for the native SDK: user key first, else the public
+    // render token served by Glassly Cloud. The binary bakes no key, so with
+    // no resolvable token the trip must NOT start — the native SDK would
+    // otherwise fail opaquely mid-boot. Cloud disabled + no user key lands
+    // here by design. Pushed per-start rather than on settings change so it
+    // can't race native boot.
+    const mapboxRenderToken = await resolveMapboxRenderToken()
+    if (!mapboxRenderToken) {
+      const error =
+        "No Mapbox token available — add your key in Settings > API Keys" +
+        " (required while Glassly Cloud is disabled or unreachable)"
+      console.warn(`${LOG_TAG}: start blocked — ${error}`)
+      return {ok: false, error}
+    }
+    try {
+      await CrustModule.setMapboxAccessToken(mapboxRenderToken)
+    } catch (err) {
+      // Native build predating setMapboxAccessToken — no token reaches the
+      // SDK (nothing is baked), so fail the start rather than limp into an
+      // opaque native error.
+      console.warn(`${LOG_TAG}: setMapboxAccessToken unavailable`, err)
+      return {ok: false, error: "This build cannot receive a Mapbox token (update the app)"}
+    }
+    const result = await CrustModule.startNavigation(coords.lat, coords.lng, {
+      simulate: options?.simulate ?? false,
+      speedMultiplier: options?.speedMultiplier ?? 5,
+      stops: options?.stops,
+      mode: options?.mode ?? "driving",
+      avoid: options?.avoid,
+      missedTurnRerouteMeters: options?.missedTurnRerouteMeters,
+    })
+    if (!result.ok) {
+      console.warn(`${LOG_TAG}: start failed — ${result.error}`)
+      this.state = "idle"
+      this.tripStops = []
+      this.tripMode = "driving"
+    } else {
+      this.state = "navigating"
+      this.tripStops = options?.stops ?? [{lat: coords.lat, lng: coords.lng}]
+      this.tripMode = options?.mode ?? "driving"
+    }
+    return result
+  }
+
+  /**
+   * Snapshot of the active trip for `navigation.getState()`. Returns null
+   * when no trip is running. The snapshot is built from in-memory state
+   * fed by the existing native event stream — no extra IPC.
+   */
+  public getSnapshot(): NavTripSnapshot | null {
+    if (this.state === "idle") return null
+    const m = this.lastManeuver
+    return {
+      active: this.state !== "arrived",
+      mode: this.tripMode,
+      stops: this.tripStops.length > 0 ? this.tripStops : undefined,
+      // Single-destination trips: index is always 0 (final stop). The Nav
+      // SDK manages waypoint progression internally, so for now we report 0.
+      currentStopIndex: 0,
+      route: this.lastRoute ?? undefined,
+      maneuver: m ?? undefined,
+      distanceToDestinationMeters: m?.distanceToDestinationMeters,
+      timeToDestinationSeconds: m?.timeToDestinationSeconds,
+      currentSpeedMps: m?.currentSpeedMps,
+      speedLimitMps: m?.speedLimitMps,
+    }
+  }
+
+  public async stop(): Promise<{ok: boolean; error?: string}> {
+    console.log(`${LOG_TAG}: stop`)
+    const result = await CrustModule.stopNavigation()
+    this.state = "idle"
+    this.lastRoute = null
+    this.lastManeuver = null
+    this.tripStops = []
+    this.tripMode = "driving"
+    return result
+  }
+
+  /**
+   * Request navigation permission. Under Mapbox there is no T&C dialog —
+   * this resolves immediately with `accepted: true` — but it's still safe
+   * (and intended) to call eagerly on mount.
+   */
+  public async requestPermission(): Promise<{ok: boolean; accepted: boolean; error?: string}> {
+    console.log(`${LOG_TAG}: requestPermission`)
+    return await CrustModule.requestNavigationPermission()
+  }
+
+  /**
+   * Dev-only: nudge the simulator off-route to trigger an actual reroute
+   * from the Nav SDK. Useful for verifying the rerouting pipeline (UI
+   * flips to "Rebuilding route…", route polyline updates, glasses display
+   * mirrors the new path). No-op on iOS or with real GPS fixes.
+   */
+  public async simulateDeviation(offsetMeters: number = 20): Promise<{ok: boolean; error?: string}> {
+    console.log(`${LOG_TAG}: simulateDeviation(${offsetMeters}m)`)
+    return await CrustModule.simulateDeviation(offsetMeters)
+  }
+
+  /**
+   * Dev toggle: lock simulated locations onto the wrong sidewalk
+   * (perpendicular-right of the route bearing by ~8m). Used to verify
+   * the SDK's along-path pivot trigger fires even when the user never
+   * comes within the 7m radius of a pivot point. Android-only today; iOS
+   * is a no-op stub.
+   */
+  public async setWrongSidewalkOffset(enabled: boolean): Promise<{ok: boolean; error?: string}> {
+    console.log(`${LOG_TAG}: setWrongSidewalkOffset(${enabled})`)
+    return await CrustModule.setWrongSidewalkOffset(enabled)
+  }
+
+  /**
+   * Dev toggle: take over from the Google simulator and walk the user
+   * along a modified polyline that skips crossing micro-steps. Lets us
+   * reproduce the wrong-sidewalk-then-missed-the-turn scenario for
+   * pivot trigger testing. Android-only today; iOS is a no-op stub.
+   */
+  public async setSkipCrossings(enabled: boolean): Promise<{ok: boolean; error?: string}> {
+    console.log(`${LOG_TAG}: setSkipCrossings(${enabled})`)
+    return await CrustModule.setSkipCrossings(enabled)
+  }
+
+  /**
+   * Compute one or more routes without starting a trip.
+   *
+   * Reached from the miniapp bridge (NavigationHandlers.handleComputeRoute)
+   * when the user has saved their own Mapbox key in Settings > API Keys —
+   * that key exists so navigation works without the cloud. Without a user
+   * key the bridge uses the v2 cloud maps service, which holds a provider
+   * token server-side and caches results. Implemented by
+   * calling Mapbox's Directions API (REST) so we don't disturb the active
+   * Navigator. Returns `{ok: false}` plus an error string when the engine
+   * can't produce a route — mirrors the SDK's ComputeRouteResult shape so
+   * the host can pass it back to miniapps unchanged.
+   */
+  public async computeRoute(payload: Record<string, unknown>): Promise<{
+    ok: boolean
+    error?: string
+    routes?: Array<{
+      points: Array<{lat: number; lng: number}>
+      totalDistanceMeters: number
+      totalDurationSeconds: number
+      summary?: string
+    }>
+  }> {
+    return computeRouteViaRoutesApi(payload)
+  }
+
+  /**
+   * Reverse-geocode a coordinate into a short road/route name (plus the full
+   * formatted `address` for dropped-pin / POI labels).
+   *
+   * Reached from the miniapp bridge when the user has saved their own Mapbox
+   * key; otherwise the bridge uses the v2 cloud maps service. See
+   * {@link computeRoute} for the same local-first branch.
+   *
+   * Implemented via Mapbox's Geocoding REST API. Backs the SDK pivot engine's
+   * last-resort fallback when a Routes-API instruction didn't carry a parseable
+   * road. Returns `{ok: true, road: null}` when the coordinate is genuinely
+   * off-grid (mid-park, water) — that's a successful query with no road
+   * component, distinct from a failure.
+   */
+  public async reverseGeocodeRoad(coord: {lat: number; lng: number}): Promise<{
+    ok: boolean
+    road?: string | null
+    address?: string | null
+    error?: string
+  }> {
+    return reverseGeocodeRoadViaGeocodingApi(coord)
+  }
+
+  /** True when a phone-side DIRECT Mapbox call can be made (user key saved). */
+  public hasMapboxToken(): boolean {
+    return !!resolveMapboxAccessToken()
+  }
+
+  /** True when the user saved their own Mapbox key in Settings > API Keys. */
+  public hasUserMapboxKey(): boolean {
+    return !!userMapboxApiKey()
+  }
+
+  /**
+   * Type-ahead place search on-device with the user's own Mapbox key.
+   * Preferred over the cloud maps service whenever that key is set — see
+   * {@link placeAutocompleteViaSearchBox}.
+   */
+  public async placeAutocomplete(
+    query: string,
+    near: {lat: number; lng: number} | undefined,
+    sessionToken: string,
+  ): Promise<{
+    ok: boolean
+    suggestions?: Array<{placeId: string; mainText: string; secondaryText: string}>
+    error?: string
+  }> {
+    return placeAutocompleteViaSearchBox(query, near, sessionToken)
+  }
+
+  /** Resolve a suggestion to coordinates on-device. Pairs with {@link placeAutocomplete}. */
+  public async placeDetails(
+    placeId: string,
+    sessionToken: string,
+  ): Promise<{
+    ok: boolean
+    place?: {placeId: string; name: string; address: string; lat: number; lng: number}
+    error?: string
+  }> {
+    return placeDetailsViaSearchBox(placeId, sessionToken)
+  }
+
+  private attachNativeSubs(): void {
+    console.log(`${LOG_TAG}: attachNativeSubs() — listeners=${this.listeners.size}`)
+    this.subs.push(
+      CrustModule.addListener("onNavManeuver", (data) => {
+        this.state = "navigating"
+        const event: NavManeuver = {kind: "maneuver", ...data}
+        this.lastManeuver = event
+        this.fanout(event)
+      }),
+      CrustModule.addListener("onNavRerouting", () => {
+        console.log(`${LOG_TAG}: ← onNavRerouting`)
+        this.state = "rerouting"
+        this.fanout({kind: "rerouting"})
+      }),
+      CrustModule.addListener("onNavArrived", () => {
+        console.log(`${LOG_TAG}: ← onNavArrived`)
+        this.state = "arrived"
+        this.lastManeuver = null
+        this.fanout({kind: "arrived"})
+      }),
+      CrustModule.addListener("onNavError", (data) => {
+        console.log(`${LOG_TAG}: ← onNavError`, data?.message)
+        this.fanout({kind: "error", message: data.message})
+      }),
+      CrustModule.addListener("onNavLocation", (data) => {
+        const loc: NavLocation = {
+          lat: data.lat,
+          lng: data.lng,
+          accuracy: data.accuracy ?? null,
+          timestamp: data.timestamp,
+        }
+        this.locationListeners.forEach((l) => {
+          try {
+            l(loc)
+          } catch (err) {
+            console.error(`${LOG_TAG}: location listener threw`, err)
+          }
+        })
+      }),
+      CrustModule.addListener("onNavRoute", (data) => {
+        const route: NavRoute = {
+          points: data.points ?? [],
+          steps: data.steps?.map((step) => ({
+            ...step,
+            road: step.road ?? null,
+          })),
+        }
+        this.lastRoute = route
+        console.log(`${LOG_TAG}: ← onNavRoute (${route.points.length} points, steps=${route.steps?.length ?? "null"})`)
+        this.routeListeners.forEach((l) => {
+          try {
+            l(route)
+          } catch (err) {
+            console.error(`${LOG_TAG}: route listener threw`, err)
+          }
+        })
+      }),
+      CrustModule.addListener("onNavOffRoute", (data) => {
+        console.log(`${LOG_TAG}: ← onNavOffRoute`, data?.offRouteDistanceMeters)
+        this.fanout({kind: "off_route", offRouteDistanceMeters: data?.offRouteDistanceMeters ?? 0})
+      }),
+    )
+  }
+
+  private detachNativeSubs(): void {
+    this.subs.forEach((s) => s.remove())
+    this.subs = []
+  }
+
+  private fanout(update: NavUpdate): void {
+    this.listeners.forEach((l) => {
+      try {
+        l(update)
+      } catch (err) {
+        console.error(`${LOG_TAG}: listener threw`, err)
+      }
+    })
+  }
+}
+
+const navigationService = NavigationService.getInstance()
+export default navigationService
+
+// ---------------------------------------------------------------------------
+// Routes API (REST)
+// ---------------------------------------------------------------------------
+
+// Routes + Geocoding go DIRECT to Mapbox from the phone process ONLY when the
+// user saved their own key (Settings > API Keys) — "use my account". Without
+// one, callers (NavigationHandlers) route these operations through the v2
+// cloud maps proxy instead; the binary ships no baked Mapbox key.
+const MAPBOX_DIRECTIONS_BASE = "https://api.mapbox.com/directions/v5/mapbox"
+const MAPBOX_GEOCODE_REVERSE = "https://api.mapbox.com/search/geocode/v6/reverse"
+const MAPBOX_SEARCHBOX_SUGGEST = "https://api.mapbox.com/search/searchbox/v1/suggest"
+const MAPBOX_SEARCHBOX_RETRIEVE = "https://api.mapbox.com/search/searchbox/v1/retrieve"
+
+/**
+ * The Mapbox token for phone-side REST calls: the user's key
+ * (Settings > Keys) or nothing — empty means "use the cloud maps proxy".
+ */
+function mapboxToken(): string {
+  return resolveMapboxAccessToken()
+}
+
+/**
+ * Phone-side helper: hit the Mapbox Directions API directly with the user's own
+ * key (Settings > API Keys). Preferred over the v2 cloud maps service whenever
+ * that key is set, so routing works without the cloud. Lives here
+ * (not in Kotlin) so it's platform-independent across the JS bridge.
+ * Returns the SDK-shaped result with primary + alternates.
+ *
+ * Mapbox Directions differs from Google Routes in shape: numeric
+ * `distance`/`duration`, `polyline6` geometry per-route AND per-step, and
+ * `maneuver = {location:[lng,lat], type, modifier, instruction}`. We
+ * synthesize the SDK's `ComputedRouteStep` (lat/lng start, endLat/endLng
+ * = next step's start) from the ordered step list.
+ */
+async function computeRouteViaRoutesApi(payload: Record<string, unknown>): Promise<{
+  ok: boolean
+  error?: string
+  routes?: Array<{
+    points: Array<{lat: number; lng: number}>
+    totalDistanceMeters: number
+    totalDurationSeconds: number
+    summary?: string
+    steps?: Array<{
+      lat: number
+      lng: number
+      endLat: number
+      endLng: number
+      distanceMeters: number
+      maneuver?: string
+      instruction?: string
+      road?: string | null
+    }>
+  }>
+}> {
+  const origin = payload.origin as {lat?: unknown; lng?: unknown} | undefined
+  const stopsRaw = payload.stops as Array<{lat?: unknown; lng?: unknown}> | undefined
+  const mode = (typeof payload.mode === "string" ? payload.mode : "driving").toLowerCase()
+  const alt = Number(payload.alternatives)
+  const alternatives = Number.isFinite(alt) && alt > 0 ? alt : 1
+  const avoid = (payload.avoid as Record<string, unknown> | undefined) ?? {}
+
+  const oLat = Number(origin?.lat)
+  const oLng = Number(origin?.lng)
+  if (!Number.isFinite(oLat) || !Number.isFinite(oLng)) {
+    return {ok: false, error: "computeRoute: origin.lat/lng required"}
+  }
+  const stops = (Array.isArray(stopsRaw) ? stopsRaw : [])
+    .map((s) => ({lat: Number(s?.lat), lng: Number(s?.lng)}))
+    .filter((s) => Number.isFinite(s.lat) && Number.isFinite(s.lng))
+  if (stops.length === 0) {
+    return {ok: false, error: "computeRoute: at least one stop required"}
+  }
+
+  const token = mapboxToken()
+  if (!token) return {ok: false, error: "computeRoute: no Mapbox key saved (add yours in Settings > API Keys)"}
+
+  // Mapbox path is a semicolon-joined `lng,lat` list: origin then each stop.
+  const coords = [`${oLng},${oLat}`, ...stops.map((s) => `${s.lng},${s.lat}`)].join(";")
+  const exclude = mapboxExclude(avoid)
+  const params = new URLSearchParams({
+    alternatives: String(alternatives > 1),
+    geometries: "polyline6",
+    overview: "full",
+    steps: "true",
+    banner_instructions: "true",
+    voice_instructions: "false",
+    access_token: token,
+  })
+  if (exclude) params.set("exclude", exclude)
+  const url = `${MAPBOX_DIRECTIONS_BASE}/${mapboxProfile(mode)}/${coords}?${params.toString()}`
+
+  try {
+    const res = await fetch(url, {method: "GET"})
+    if (!res.ok) {
+      return {ok: false, error: `Directions API ${res.status}`}
+    }
+    const json = (await res.json()) as {
+      code?: string
+      message?: string
+      routes?: Array<{
+        geometry?: string
+        distance?: number
+        duration?: string | number
+        weight_name?: string
+        legs?: Array<{
+          summary?: string
+          steps?: Array<{
+            geometry?: string
+            name?: string
+            distance?: number
+            maneuver?: {location?: [number, number]; type?: string; modifier?: string; instruction?: string}
+          }>
+        }>
+      }>
+    }
+    if (json.code && json.code !== "Ok") {
+      return {ok: false, error: json.message ?? `Directions code ${json.code}`}
+    }
+    // Resolve `road` for every step whose Mapbox `name` was blank (slip
+    // lanes, unnamed paths, arrival legs) via reverse-geocode. Per-route
+    // and per-alternate resolution fire concurrently.
+    const routes = await Promise.all(
+      (json.routes ?? []).slice(0, alternatives).map(async (r) => {
+        const legs = r.legs ?? []
+        const flatSteps = legs.flatMap((leg) => leg.steps ?? [])
+        const rawSteps = flatSteps.map((s, i) => {
+          const here = s.maneuver?.location // [lng, lat]
+          const next = flatSteps[i + 1]?.maneuver?.location
+          const lat = here?.[1] ?? Number.NaN
+          const lng = here?.[0] ?? Number.NaN
+          return {
+            lat,
+            lng,
+            // End of step i == start of step i+1; final step ends at itself.
+            endLat: next?.[1] ?? lat,
+            endLng: next?.[0] ?? lng,
+            distanceMeters: Math.round(s.distance ?? 0),
+            maneuver: mapboxManeuverToKind(s.maneuver?.type, s.maneuver?.modifier),
+            instruction: s.maneuver?.instruction,
+            // Mapbox gives the road name inline as `step.name`; prefer it
+            // over geocoding. Blank names fall through to resolveStepRoads.
+            road: s.name && s.name.trim().length > 0 ? s.name.trim() : undefined,
+          }
+        })
+        const steps = await resolveStepRoads(rawSteps, reverseGeocodeRoadViaGeocodingApi)
+        return {
+          points: decodePolyline(r.geometry ?? "", 6),
+          totalDistanceMeters: Math.round(r.distance ?? 0),
+          totalDurationSeconds: parseDurationSeconds(r.duration ?? 0),
+          summary: legs[0]?.summary,
+          steps: steps.length > 0 ? steps : undefined,
+        }
+      }),
+    )
+    if (routes.length === 0) return {ok: false, error: "no routes returned"}
+    return {ok: true, routes}
+  } catch (err) {
+    return {ok: false, error: err instanceof Error ? err.message : "computeRoute failed"}
+  }
+}
+
+/** SDK-agnostic mode → Mapbox Directions profile. two_wheeler → driving. */
+function mapboxProfile(mode: string): string {
+  switch (mode) {
+    case "walking":
+      return "walking"
+    case "cycling":
+      return "cycling"
+    case "two_wheeler":
+      return "driving"
+    default:
+      return "driving-traffic"
+  }
+}
+
+/** Avoid flags → Mapbox `exclude` param. Null when nothing to exclude. */
+function mapboxExclude(avoid: Record<string, unknown>): string | null {
+  const ex: string[] = []
+  if (avoid.tolls === true) ex.push("toll")
+  if (avoid.ferries === true) ex.push("ferry")
+  if (avoid.highways === true) ex.push("motorway")
+  return ex.length > 0 ? ex.join(",") : null
+}
+
+/**
+ * Map Mapbox `maneuver.type` + `modifier` to the SDK's ManeuverKind
+ * vocabulary — the JS-side mirror of NavigationManager.kt's mapManeuver
+ * (issues/mapbox-navigation-migration.md §7). Kept here so the
+ * computeRoute preview path labels turns the same way the live trip does.
+ */
+function mapboxManeuverToKind(type?: string, modifier?: string): string | undefined {
+  switch (type) {
+    case "depart":
+      return "DEPART"
+    case "arrive":
+      return "ARRIVE"
+    case "new name":
+      return "NAME_CHANGE"
+    case "continue":
+    case "merge":
+      return "CONTINUE"
+    case "notification":
+      return "STRAIGHT"
+    default:
+      break
+  }
+  switch (modifier) {
+    case "uturn":
+      return "U_TURN"
+    case "sharp left":
+      return "SHARP_LEFT"
+    case "left":
+      return "TURN_LEFT"
+    case "slight left":
+      return "SLIGHT_LEFT"
+    case "straight":
+      return "STRAIGHT"
+    case "slight right":
+      return "SLIGHT_RIGHT"
+    case "right":
+      return "TURN_RIGHT"
+    case "sharp right":
+      return "SHARP_RIGHT"
+    default:
+      return type ? "STRAIGHT" : undefined
+  }
+}
+
+/**
+ * Reverse-geocode a coordinate via the Mapbox Geocoding v6 API directly, using
+ * the user's own key (Settings > API Keys). Preferred over the v2 cloud maps
+ * service whenever that key is set, so pin labels work without the cloud.
+ *
+ * Returns the road/street name (e.g. "Octavia Blvd") plus the full formatted
+ * `address` for dropped-pin / POI labels. When no street is
+ * present — the coordinate is genuinely off-grid (water, park interior) —
+ * resolves with `{ok: true, road: null}`. Network failures and missing
+ * token resolve with `{ok: false, error}`.
+ *
+ * Mapbox v6 returns a GeoJSON FeatureCollection; the street name lives at
+ * `features[0].properties.context.street.name`. We also accept a feature
+ * whose own `feature_type` is `street` (its `name` is the road). We prefer
+ * the most-specific feature (the first), matching how the Google-era code
+ * took the first `route` component.
+ */
+async function reverseGeocodeRoadViaGeocodingApi(coord: {lat: number; lng: number}): Promise<{
+  ok: boolean
+  road?: string | null
+  address?: string | null
+  error?: string
+}> {
+  if (!Number.isFinite(coord.lat) || !Number.isFinite(coord.lng)) {
+    return {ok: false, error: "reverseGeocode: invalid coord"}
+  }
+  const token = mapboxToken()
+  if (!token)
+    return {
+      ok: false,
+      error: "reverseGeocode: no Mapbox key saved (add yours in Settings > API Keys)",
+    }
+  const params = new URLSearchParams({
+    longitude: String(coord.lng),
+    latitude: String(coord.lat),
+    // Bias toward address/street features so the street context is present.
+    types: "address,street",
+    limit: "1",
+    access_token: token,
+  })
+  try {
+    const res = await fetch(`${MAPBOX_GEOCODE_REVERSE}?${params.toString()}`, {method: "GET"})
+    if (!res.ok) return {ok: false, error: `Geocoding API ${res.status}`}
+    const json = (await res.json()) as {
+      features?: Array<{
+        properties?: {
+          feature_type?: string
+          name?: string
+          full_address?: string
+          place_formatted?: string
+          context?: {street?: {name?: string}}
+        }
+      }>
+    }
+    // The full formatted address for dropped-pin / POI labels, taken from the
+    // most-specific feature. Same precedence as the cloud provider so both
+    // paths label a pin identically.
+    const first = json.features?.[0]?.properties
+    const address = (first?.full_address ?? first?.name ?? first?.place_formatted ?? "").trim() || null
+
+    for (const feature of json.features ?? []) {
+      const props = feature.properties
+      // A street-type feature's own name is the road; otherwise read the
+      // street from context.
+      const fromStreetType = props?.feature_type === "street" ? props?.name : undefined
+      const name = (fromStreetType ?? props?.context?.street?.name ?? "").trim()
+      if (name) return {ok: true, road: name, address}
+    }
+    return {ok: true, road: null, address}
+  } catch (err) {
+    return {ok: false, error: err instanceof Error ? err.message : "reverseGeocode failed"}
+  }
+}
+
+/**
+ * Type-ahead place search straight from the device via Mapbox Search Box,
+ * using the user's own key (Settings > API Keys). This is the offline-from-
+ * the-cloud path: with a key saved, place search works with no runtime
+ * involvement at all.
+ *
+ * Field extraction mirrors the cloud provider so both paths return identical
+ * suggestions: only entries carrying a `mapbox_id` survive (without one there
+ * is nothing to retrieve later), and the secondary line prefers
+ * `place_formatted` over `full_address`.
+ *
+ * An empty query short-circuits to no suggestions — Search Box answers 422 for
+ * a blank `q`. A missing token resolves `{ok: false}` so the caller can fall
+ * back to the cloud.
+ */
+async function placeAutocompleteViaSearchBox(
+  query: string,
+  near: {lat: number; lng: number} | undefined,
+  sessionToken: string,
+): Promise<{
+  ok: boolean
+  suggestions?: Array<{placeId: string; mainText: string; secondaryText: string}>
+  error?: string
+}> {
+  if (!query.trim()) return {ok: true, suggestions: []}
+  const token = mapboxToken()
+  if (!token) {
+    return {
+      ok: false,
+      error: "placeAutocomplete: no Mapbox key saved (add yours in Settings > API Keys)",
+    }
+  }
+  const params = new URLSearchParams({
+    q: query,
+    access_token: token,
+    session_token: sessionToken,
+    // POIs + addresses + places — the things a user navigates to.
+    types: "poi,address,place,street",
+    limit: "10",
+  })
+  // Mapbox wants lng,lat for proximity bias.
+  if (near) params.set("proximity", `${near.lng},${near.lat}`)
+
+  try {
+    const res = await fetch(`${MAPBOX_SEARCHBOX_SUGGEST}?${params.toString()}`, {method: "GET"})
+    if (!res.ok) return {ok: false, error: `Search Box suggest ${res.status}`}
+    const json = (await res.json()) as {
+      suggestions?: Array<{
+        mapbox_id?: string
+        name?: string
+        place_formatted?: string
+        full_address?: string
+      }>
+    }
+    const suggestions = (json.suggestions ?? [])
+      .filter((s): s is {mapbox_id: string} & typeof s => !!s.mapbox_id)
+      .map((s) => ({
+        placeId: s.mapbox_id,
+        mainText: s.name ?? "",
+        secondaryText: s.place_formatted ?? s.full_address ?? "",
+      }))
+    return {ok: true, suggestions}
+  } catch (err) {
+    return {ok: false, error: err instanceof Error ? err.message : "placeAutocomplete failed"}
+  }
+}
+
+/**
+ * Resolve a Search Box suggestion to a full place with coordinates, using the
+ * user's own key. Pairs with {@link placeAutocompleteViaSearchBox} — the same
+ * `sessionToken` must thread both calls so Mapbox bills the keystrokes plus
+ * this retrieve as one search session.
+ *
+ * Retrieve answers a GeoJSON FeatureCollection; coordinates live at
+ * `features[0].geometry.coordinates` as [lng, lat].
+ */
+async function placeDetailsViaSearchBox(
+  placeId: string,
+  sessionToken: string,
+): Promise<{
+  ok: boolean
+  place?: {placeId: string; name: string; address: string; lat: number; lng: number}
+  error?: string
+}> {
+  const token = mapboxToken()
+  if (!token) {
+    return {
+      ok: false,
+      error: "placeDetails: no Mapbox key saved (add yours in Settings > API Keys)",
+    }
+  }
+  const params = new URLSearchParams({access_token: token, session_token: sessionToken})
+  try {
+    const res = await fetch(`${MAPBOX_SEARCHBOX_RETRIEVE}/${encodeURIComponent(placeId)}?${params.toString()}`, {
+      method: "GET",
+    })
+    if (!res.ok) return {ok: false, error: `Search Box retrieve ${res.status}`}
+    const json = (await res.json()) as {
+      features?: Array<{
+        geometry?: {coordinates?: [number, number]}
+        properties?: {
+          name?: string
+          full_address?: string
+          place_formatted?: string
+        }
+      }>
+    }
+    const feature = json.features?.[0]
+    const coords = feature?.geometry?.coordinates
+    if (!coords || coords.length < 2 || !Number.isFinite(coords[0]) || !Number.isFinite(coords[1])) {
+      return {ok: false, error: "placeDetails: no coordinates for place"}
+    }
+    const props = feature?.properties
+    return {
+      ok: true,
+      place: {
+        placeId,
+        name: props?.name ?? "",
+        address: props?.full_address ?? props?.place_formatted ?? "",
+        lng: coords[0],
+        lat: coords[1],
+      },
+    }
+  } catch (err) {
+    return {ok: false, error: err instanceof Error ? err.message : "placeDetails failed"}
+  }
+}