@jacques_gordon/expo-mapbox-navigation 2.1.5 → 2.2.0

package/ExpoMapboxNavigation.podspec

@@ -10,30 +10,46 @@ Pod::Spec.new do |s|
   s.license        = package['license']
   s.author         = package['author']
   s.homepage       = package['homepage']
-  s.platforms      = { :ios => '14.0' }
-  s.swift_version  = '5.7'
+
+  # ── 16 KB / SPM minimum: Mapbox Navigation SDK v3 for iOS requires iOS 14+,
+  # but Swift Package Manager dependencies resolved through CocoaPods'
+  # spm_dependency() mechanism require iOS 15.1+ as the minimum deployment
+  # target (Apple's SPM-via-CocoaPods bridging constraint).
+  s.platforms      = { :ios => '15.1' }
+  s.swift_version  = '5.9'
   s.source         = { git: package['repository']['url'], tag: "v#{s.version}" }
   s.static_framework = true
 
   s.dependency 'ExpoModulesCore'
 
-  # ── iOS: Mapbox Navigation bundled as xcframework ──────────────────────────
-  # The Navigation SDK v3 for iOS does not support CocoaPods natively.
-  # xcframeworks are bundled directly. See README for how to rebuild them.
-  # ────────────────────────────────────────────────────────────────────────────
-  s.vendored_frameworks = 'ios/MapboxNavigationUIKit.xcframework',
-                          'ios/MapboxNavigationCore.xcframework',
-                          'ios/MapboxDirections.xcframework'
-
-  # Mapbox Maps SDK (via CocoaPods — available as of Maps SDK 11.x)
-  s.dependency 'MapboxMaps', '>= 11.11.0'
+  # ── iOS: Mapbox Navigation SDK v3 via Swift Package Manager ─────────────────
+  #
+  # IMPORTANT: earlier versions of this podspec referenced prebuilt
+  # .xcframework files (MapboxNavigationUIKit.xcframework,
+  # MapboxNavigationCore.xcframework, MapboxDirections.xcframework) that were
+  # NEVER actually built or shipped in the npm package — this caused
+  # "Unimplemented component: ViewManagerAdapter_ExpoMapboxNavigation" at
+  # runtime on iOS, since no native module was ever registered.
+  #
+  # The Mapbox Navigation SDK v3 for iOS is officially distributed ONLY via
+  # Swift Package Manager (CocoaPods support is not provided by Mapbox).
+  # We use CocoaPods' built-in spm_dependency() helper (available since
+  # CocoaPods 1.13+, and exactly the mechanism Expo's own modules use for
+  # this exact situation) to pull the SPM package transparently as part of
+  # `pod install` / `expo prebuild`. No manual Xcode steps, no vendored
+  # binaries to build or maintain.
+  spm_dependency(
+    s,
+    url: 'https://github.com/mapbox/mapbox-navigation-ios.git',
+    requirement: { kind: 'upToNextMajorVersion', minimumVersion: '3.24.2' },
+    products: ['MapboxNavigationCore', 'MapboxNavigationUIKit', 'MapboxDirections']
+  )
 
-  s.source_files = 'ios/**/*.{swift,m,mm}'
+  s.source_files = 'ios/**/*.{swift,h,m,mm}'
 
   s.pod_target_xcconfig = {
     'DEFINES_MODULE' => 'YES',
-    # 16 KB page alignment for iOS (Apple Silicon + future-proof)
-    'OTHER_LDFLAGS' => '-Wl,-dead_strip_dylibs',
-    'SWIFT_COMPILATION_MODE' => 'wholemodule'
+    'SWIFT_COMPILATION_MODE' => 'wholemodule',
+    'IPHONEOS_DEPLOYMENT_TARGET' => '15.1'
   }
 end

package/README.md

@@ -12,6 +12,7 @@ Expo module for Mapbox Navigation SDK — forked from [`@badatgil/expo-mapbox-na
 | ✅ **16 KB page size** | `jniLibs.useLegacyPackaging = false` + `ANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON` — required for Google Play compliance from 2025 onwards. |
 | ✅ **Expo SDK 53+** | Compatible with Expo SDK ≥ 53 and React Native 0.79+. |
 | ✅ **Maps v11.11.0** | Minimum Mapbox Maps Android SDK enforced to 11.11.0 (config plugin validates this). |
+| ✅ **iOS support** | Full native iOS implementation (`NavigationViewController` drop-in UI) via Swift Package Manager — feature parity with Android (lane guidance, speed limit, voice instructions, day/night, steps list). |
 
 ---
 
@@ -46,6 +47,7 @@ Follow the [full @rnmapbox/maps installation guide](https://rnmapbox.github.io/d
     "@jacques_gordon/expo-mapbox-navigation",
     {
       "accessToken": "pk.your_public_token",
+      "downloadsToken": "sk.your_secret_token",
       "mapboxMapsVersion": "11.11.0"
     }
   ]
@@ -54,6 +56,14 @@ Follow the [full @rnmapbox/maps installation guide](https://rnmapbox.github.io/d
 
 > ⚠️ `mapboxMapsVersion` must match the version set in `@rnmapbox/maps`. Minimum: `11.11.0`.
 
+> ⚠️ `downloadsToken` is **required** — it's a secret Mapbox token (starts with `sk.`) with the **Downloads:Read** scope. On iOS it's used to authenticate Swift Package Manager when it fetches the Mapbox Navigation SDK from Mapbox's private package registry (via a generated `.netrc` entry). This is the same token already used for `RNMapboxMapsDownloadToken` above — you can reuse it.
+
+### iOS architecture
+
+iOS uses the **official Mapbox Navigation SDK v3 drop-in UI** (`NavigationViewController`), installed via **Swift Package Manager** — not prebuilt `.xcframework` binaries. This is the only officially supported distribution method for the Navigation SDK v3 on iOS; CocoaPods doesn't host it directly, so this package bridges it in automatically through CocoaPods' `spm_dependency()` mechanism when you run `pod install` / `expo prebuild`.
+
+Because `NavigationViewController` is a complete drop-in experience, lane guidance, speed limit display, voice instructions, and the recenter/overview camera button all come built-in from Mapbox — no extra wiring needed, unlike the more manual Android implementation.
+
 ### iOS: enable static frameworks
 
 ```json
@@ -156,6 +166,12 @@ More info: [Android 16 KB page size guide](https://developer.android.com/guide/p
 
 ## Changelog
 
+### 2.2.0
+- **iOS support added.** Full native implementation using Mapbox Navigation SDK v3 (`NavigationViewController` drop-in UI) via Swift Package Manager.
+- Fixed: previous versions referenced non-existent `.xcframework` files in the podspec, causing `Unimplemented component: ViewManagerAdapter_ExpoMapboxNavigation` crashes on iOS — no native module was ever actually registered.
+- New required `downloadsToken` config plugin option (secret Mapbox token, used to authenticate Swift Package Manager).
+- iOS feature parity with Android: lane guidance, speed limit, voice instructions (with working mute), day/night auto-switching, and the `onManeuverBannerPressed` full-steps-list event.
+
 ### 2.0.1
 - Fix #43: `CameraAnimationsUtils.calculateCameraAnimationHint` NoSuchMethodError on Android
 - Fix #31: Add `voiceUnits` prop for metric/imperial voice instructions

package/android/src/main/java/expo/modules/mapboxnavigation/ExpoMapboxNavigationModule.kt

@@ -15,7 +15,8 @@ class ExpoMapboxNavigationModule : Module() {
                 "onNavigationFinished",
                 "onNavigationCancelled",
                 "onRoutesFailed",
-                "onArrival"
+                "onArrival",
+                "onManeuverBannerPressed"
             )
 
             Prop("coordinates") { view: ExpoMapboxNavigationView, coordinates: List<Map<String, Double>> ->

package/android/src/main/java/expo/modules/mapboxnavigation/ExpoMapboxNavigationView.kt

@@ -93,6 +93,11 @@ class ExpoMapboxNavigationView(context: Context, appContext: AppContext) :
     private val onNavigationCancelled by EventDispatcher()
     private val onRoutesFailed by EventDispatcher()
     private val onArrival by EventDispatcher()
+    // Feature: emits the full list of turn-by-turn steps when the instruction
+    // banner is tapped, so the RN layer can render a steps list (bottom
+    // sheet/modal). Payload: { steps: [{ instruction, distanceMeters,
+    // maneuverType, maneuverModifier, laneInstructions }] }
+    private val onManeuverBannerPressed by EventDispatcher()
 
     // ── Views ─────────────────────────────────────────────────────────────────
     private val mapView: MapView = MapView(context)
@@ -135,11 +140,15 @@ class ExpoMapboxNavigationView(context: Context, appContext: AppContext) :
     private val dp = context.resources.displayMetrics.density
 
     // ── Viewport padding ──────────────────────────────────────────────────────
+    // ── Viewport padding — EXACT official Mapbox values from the camera guide ──
+    // Previous bottom=300dp pushed the focal point too far up, causing
+    // the puck to visibly jump/drift between location updates.
+    // Official guide value: top=180, left=40, bottom=150, right=40
     private val followingPadding by lazy {
-        EdgeInsets(180.0 * dp, 40.0 * dp, 300.0 * dp, 40.0 * dp)
+        EdgeInsets(180.0 * dp, 40.0 * dp, 150.0 * dp, 40.0 * dp)
     }
     private val overviewPadding by lazy {
-        EdgeInsets(120.0 * dp, 40.0 * dp, 120.0 * dp, 40.0 * dp)
+        EdgeInsets(140.0 * dp, 40.0 * dp, 120.0 * dp, 40.0 * dp)
     }
 
     // ── Props ─────────────────────────────────────────────────────────────────
@@ -167,43 +176,47 @@ class ExpoMapboxNavigationView(context: Context, appContext: AppContext) :
     // Draw icons programmatically (matching screenshot: speaker, route, arrow)
     // ─────────────────────────────────────────────────────────────────────────
 
+    // ── Modern Google Maps / Waze style icons ──────────────────────────────────
+
     private fun drawSpeakerIcon(muted: Boolean): Bitmap {
         val size = (44 * dp).toInt()
         val bmp = Bitmap.createBitmap(size, size, Bitmap.Config.ARGB_8888)
         val c = Canvas(bmp)
+        val s = size.toFloat()
+        val color = if (muted) Color.parseColor("#5F6368") else Color.parseColor("#1A73E8")
         val paint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
-            color = Color.BLACK
+            this.color = color
             style = Paint.Style.FILL
         }
-        val s = size.toFloat()
-        // Speaker body (trapezoid)
+        // Speaker cone (rounded, modern Material style)
         val body = Path().apply {
-            moveTo(s * 0.18f, s * 0.38f)
-            lineTo(s * 0.38f, s * 0.38f)
-            lineTo(s * 0.58f, s * 0.22f)
-            lineTo(s * 0.58f, s * 0.78f)
-            lineTo(s * 0.38f, s * 0.62f)
-            lineTo(s * 0.18f, s * 0.62f)
+            moveTo(s * 0.16f, s * 0.40f)
+            lineTo(s * 0.34f, s * 0.40f)
+            lineTo(s * 0.56f, s * 0.20f)
+            quadTo(s * 0.60f, s * 0.17f, s * 0.60f, s * 0.22f)
+            lineTo(s * 0.60f, s * 0.78f)
+            quadTo(s * 0.60f, s * 0.83f, s * 0.56f, s * 0.80f)
+            lineTo(s * 0.34f, s * 0.60f)
+            lineTo(s * 0.16f, s * 0.60f)
+            quadTo(s * 0.12f, s * 0.60f, s * 0.12f, s * 0.56f)
+            lineTo(s * 0.12f, s * 0.44f)
+            quadTo(s * 0.12f, s * 0.40f, s * 0.16f, s * 0.40f)
             close()
         }
         c.drawPath(body, paint)
         if (!muted) {
-            // Sound waves arcs
             paint.style = Paint.Style.STROKE
-            paint.strokeWidth = s * 0.065f
+            paint.strokeWidth = s * 0.06f
             paint.strokeCap = Paint.Cap.ROUND
-            // Inner arc
-            c.drawArc(RectF(s*0.60f, s*0.33f, s*0.80f, s*0.67f), -60f, 120f, false, paint)
-            // Outer arc
-            c.drawArc(RectF(s*0.64f, s*0.24f, s*0.92f, s*0.76f), -55f, 110f, false, paint)
+            c.drawArc(RectF(s*0.62f, s*0.34f, s*0.80f, s*0.66f), -45f, 90f, false, paint)
+            c.drawArc(RectF(s*0.66f, s*0.22f, s*0.92f, s*0.78f), -40f, 80f, false, paint)
         } else {
-            // X mark for muted
             paint.style = Paint.Style.STROKE
-            paint.strokeWidth = s * 0.07f
+            paint.strokeWidth = s * 0.065f
             paint.strokeCap = Paint.Cap.ROUND
-            paint.color = Color.parseColor("#FF4444")
-            c.drawLine(s*0.65f, s*0.32f, s*0.88f, s*0.68f, paint)
-            c.drawLine(s*0.88f, s*0.32f, s*0.65f, s*0.68f, paint)
+            paint.color = Color.parseColor("#EA4335")
+            c.drawLine(s*0.66f, s*0.34f, s*0.88f, s*0.66f, paint)
+            c.drawLine(s*0.88f, s*0.34f, s*0.66f, s*0.66f, paint)
         }
         return bmp
     }
@@ -212,34 +225,29 @@ class ExpoMapboxNavigationView(context: Context, appContext: AppContext) :
         val size = (44 * dp).toInt()
         val bmp = Bitmap.createBitmap(size, size, Bitmap.Config.ARGB_8888)
         val c = Canvas(bmp)
+        val s = size.toFloat()
         val paint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
-            color = Color.BLACK
-            style = Paint.Style.STROKE
-            strokeWidth = size * 0.08f
-            strokeCap = Paint.Cap.ROUND
-            strokeJoin = Paint.Join.ROUND
+            color = Color.parseColor("#1A73E8")
         }
-        val s = size.toFloat()
-        // Route line with S-curve (like the image: start dot → curve → end pin)
-        // Start dot
-        paint.style = Paint.Style.FILL
-        c.drawCircle(s * 0.28f, s * 0.75f, s * 0.07f, paint)
-        // Route path
+        // Map/overview icon: stacked layers (like Google Maps "map view" icon)
         paint.style = Paint.Style.STROKE
-        val routePath = Path().apply {
-            moveTo(s * 0.28f, s * 0.75f)
-            cubicTo(
-                s * 0.28f, s * 0.45f,
-                s * 0.72f, s * 0.55f,
-                s * 0.72f, s * 0.25f
-            )
+        paint.strokeWidth = s * 0.07f
+        paint.strokeJoin = Paint.Join.ROUND
+        paint.strokeCap = Paint.Cap.ROUND
+        // Outer diamond/map frame
+        val frame = Path().apply {
+            moveTo(s * 0.50f, s * 0.14f)
+            lineTo(s * 0.84f, s * 0.34f)
+            lineTo(s * 0.84f, s * 0.66f)
+            lineTo(s * 0.50f, s * 0.86f)
+            lineTo(s * 0.16f, s * 0.66f)
+            lineTo(s * 0.16f, s * 0.34f)
+            close()
         }
-        c.drawPath(routePath, paint)
-        // End pin (circle with dot)
-        paint.style = Paint.Style.STROKE
-        c.drawCircle(s * 0.72f, s * 0.22f, s * 0.10f, paint)
-        paint.style = Paint.Style.FILL
-        c.drawCircle(s * 0.72f, s * 0.22f, s * 0.04f, paint)
+        c.drawPath(frame, paint)
+        // Two horizontal fold lines (classic map icon)
+        c.drawLine(s*0.36f, s*0.22f, s*0.36f, s*0.78f, paint)
+        c.drawLine(s*0.64f, s*0.22f, s*0.64f, s*0.78f, paint)
         return bmp
     }
 
@@ -247,17 +255,17 @@ class ExpoMapboxNavigationView(context: Context, appContext: AppContext) :
         val size = (44 * dp).toInt()
         val bmp = Bitmap.createBitmap(size, size, Bitmap.Config.ARGB_8888)
         val c = Canvas(bmp)
+        val s = size.toFloat()
         val paint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
-            color = Color.BLACK
+            color = Color.parseColor("#1A73E8")
             style = Paint.Style.FILL
         }
-        val s = size.toFloat()
-        // Navigation arrow pointing up (filled chevron/arrow like Waze)
+        // Navigation/recenter compass arrow (Google Maps "my location, follow" style)
         val arrow = Path().apply {
-            moveTo(s * 0.50f, s * 0.14f)   // tip
-            lineTo(s * 0.78f, s * 0.76f)   // bottom-right
-            lineTo(s * 0.50f, s * 0.60f)   // bottom-center indent
-            lineTo(s * 0.22f, s * 0.76f)   // bottom-left
+            moveTo(s * 0.50f, s * 0.12f)    // tip
+            lineTo(s * 0.80f, s * 0.82f)    // bottom-right
+            lineTo(s * 0.50f, s * 0.64f)    // notch center
+            lineTo(s * 0.20f, s * 0.82f)    // bottom-left
             close()
         }
         c.drawPath(arrow, paint)
@@ -295,12 +303,30 @@ class ExpoMapboxNavigationView(context: Context, appContext: AppContext) :
         ))
 
         // ── ManeuverView — top ─────────────────────────────────────────────────
+        // NOTE: a previous attempt to customize the primary maneuver text
+        // appearance (auto-sizing for long street names) used a fictional
+        // "primaryManeuverTextAppearance" attribute that doesn't exist in the
+        // SDK, which broke AAPT resource linking in host apps. A follow-up
+        // attempt to call updatePrimaryManeuverTextAppearance() was also
+        // dropped: in Navigation SDK v3 the UI components were restructured
+        // around a ComponentInstaller/ManeuverConfig system and that method's
+        // availability/signature could not be confirmed for v3 with
+        // certainty. To avoid risking another build-breaking regression on
+        // an unverified API, MapboxManeuverView is used with its default
+        // text appearance for now. Long street name truncation can be
+        // revisited via the officially supported ComponentInstaller config
+        // API in a future, carefully tested release.
         val mv = MapboxManeuverView(context)
         root.addView(mv as View, FrameLayout.LayoutParams(
             FrameLayout.LayoutParams.MATCH_PARENT,
             FrameLayout.LayoutParams.WRAP_CONTENT
         ).also { it.gravity = Gravity.TOP })
         mv.visibility = View.INVISIBLE
+        // Feature: tap the instruction banner to see the full list of upcoming
+        // turn-by-turn steps. We emit the data via event so the RN/JS layer can
+        // render a bottom sheet or modal using its own native UI components —
+        // consistent with how all other navigation events are surfaced.
+        mv.setOnClickListener { emitFullRouteSteps() }
         maneuverView = mv
 
         // ── Side buttons — RIGHT side, just below maneuver banner ─────────────
@@ -336,17 +362,21 @@ class ExpoMapboxNavigationView(context: Context, appContext: AppContext) :
         })
         btnOverviewView = overviewBtn
 
-        // Button 3: Recenter / Navigation arrow (hidden until in overview mode)
+        // Button 3: Recenter / return to follow mode — ALWAYS visible, below button 2
+        // Greyed out (lower opacity) when already following; full opacity in overview mode
         val recenterBtn = makeIconButton(drawNavigationArrowIcon()) { recenterCamera() }
-        recenterBtn.visibility = View.GONE
+        recenterBtn.alpha = 0.4f  // dimmed by default (already following)
         sideCol.addView(recenterBtn, LinearLayout.LayoutParams(btnSize, btnSize))
         btnRecenterView = recenterBtn
 
         // ── SpeedInfoView — bottom-left, above ETA bar ────────────────────────
+        // FIX: use WRAP_CONTENT instead of fixed 72x72dp — the native Mapbox
+        // component renders both the posted speed limit sign AND the current
+        // vehicle speed side-by-side, which needs flexible width
         val siv = MapboxSpeedInfoView(context)
         root.addView(siv as View, FrameLayout.LayoutParams(
-            (72 * dp).toInt(),
-            (72 * dp).toInt()
+            FrameLayout.LayoutParams.WRAP_CONTENT,
+            FrameLayout.LayoutParams.WRAP_CONTENT
         ).also {
             it.gravity = Gravity.BOTTOM or Gravity.START
             it.setMargins((12 * dp).toInt(), 0, 0, (88 * dp).toInt())
@@ -492,6 +522,11 @@ class ExpoMapboxNavigationView(context: Context, appContext: AppContext) :
             viewportDataSource.followingPadding = followingPadding
             viewportDataSource.overviewPadding = overviewPadding
 
+            // Waze-style tilted 3D following view — also helps stabilize the
+            // visual framing since pitch reduces perceived jitter from GPS noise
+            viewportDataSource.options.followingFrameOptions.defaultPitch = 45.0
+            viewportDataSource.options.followingFrameOptions.maxZoom = 17.0
+
             navigationCamera = NavigationCamera(
                 mapView.mapboxMap,
                 mapView.camera,
@@ -601,7 +636,15 @@ class ExpoMapboxNavigationView(context: Context, appContext: AppContext) :
             override fun onNewRawLocation(rawLocation: Location) {}
             override fun onNewLocationMatcherResult(result: LocationMatcherResult) {
                 val loc = result.enhancedLocation
-                navigationLocationProvider.changePosition(location = loc, keyPoints = result.keyPoints)
+                // ── FIX: Puck jitter / drift ──────────────────────────────────────
+                // Root cause (confirmed via Mapbox GitHub issue #4140):
+                // When keyPoints are passed to changePosition(), the puck animator
+                // splits the 1-second transition EVENLY across all keypoints in time,
+                // but the keypoints are NOT evenly spaced in distance. This causes the
+                // puck to speed up/slow down and visibly drift left/right off the
+                // route line, even on a perfectly straight road.
+                // Official Mapbox workaround: pass emptyList() instead of keyPoints.
+                navigationLocationProvider.changePosition(location = loc, keyPoints = emptyList())
                 viewportDataSource.onLocationChanged(loc)
                 viewportDataSource.evaluate()
 
@@ -610,6 +653,11 @@ class ExpoMapboxNavigationView(context: Context, appContext: AppContext) :
                     safeCameraFollowing()
                 }
 
+                // ── Speed limit (issue #4: was not displaying) ──────────────────
+                // updatePostedAndCurrentSpeed returns null when:
+                //  1. The route response has no `maxspeed` annotation for this segment
+                //  2. GPS speed is unavailable
+                // We log this so issues can be diagnosed via `adb logcat`
                 val fmtOptions = DistanceFormatterOptions.Builder(context).build()
                 val speedInfo = speedInfoApi.updatePostedAndCurrentSpeed(result, fmtOptions)
                 if (speedInfo != null) {
@@ -617,6 +665,8 @@ class ExpoMapboxNavigationView(context: Context, appContext: AppContext) :
                     speedInfoView?.render(speedInfo)
                 } else {
                     speedInfoView?.visibility = View.GONE
+                    Log.d(TAG, "Speed info unavailable for this location/route segment " +
+                        "(no maxspeed annotation or GPS speed not ready yet)")
                 }
 
                 checkAndSwitchDayNight()
@@ -643,7 +693,8 @@ class ExpoMapboxNavigationView(context: Context, appContext: AppContext) :
             recenterCamera()
         } else {
             isOverviewMode = true
-            btnRecenterView?.visibility = View.VISIBLE
+            // Button 3 lights up (full opacity) to invite the user to tap it
+            btnRecenterView?.alpha = 1f
             try {
                 navigationCamera.requestNavigationCameraToOverview()
             } catch (e: Exception) {
@@ -654,7 +705,8 @@ class ExpoMapboxNavigationView(context: Context, appContext: AppContext) :
 
     private fun recenterCamera() {
         isOverviewMode = false
-        btnRecenterView?.visibility = View.GONE
+        // Button 3 dims again — already in following mode
+        btnRecenterView?.alpha = 0.4f
         safeCameraFollowing()
     }
 
@@ -713,7 +765,53 @@ class ExpoMapboxNavigationView(context: Context, appContext: AppContext) :
         }
     }
 
-    private fun cancelNavigation() {
+    // ─────────────────────────────────────────────────────────────────────────
+    // Feature: full route steps list (triggered by tapping the instruction
+    // banner). Extracts every LegStep across all legs of the active route,
+    // including lane guidance data when present on that step's BannerInstructions.
+    // ─────────────────────────────────────────────────────────────────────────
+    private fun emitFullRouteSteps() {
+        val routes = mapboxNavigation?.getNavigationRoutes()
+        val activeRoute = routes?.firstOrNull() ?: run {
+            onManeuverBannerPressed(mapOf("steps" to emptyList<Map<String, Any>>()))
+            return
+        }
+
+        val stepsPayload = mutableListOf<Map<String, Any>>()
+
+        activeRoute.directionsRoute.legs()?.forEach { leg ->
+            leg.steps()?.forEach { step ->
+                val maneuver = step.maneuver()
+                val firstBanner = step.bannerInstructions()?.firstOrNull()
+
+                // Lane guidance: present on BannerInstructions.sub() when type == "lane"
+                val laneData = firstBanner?.sub()?.components()
+                    ?.filter { it.type() == "lane" }
+                    ?.map { component ->
+                        mapOf(
+                            "active" to (component.active() ?: false),
+                            "directions" to (component.directions() ?: emptyList<String>())
+                        )
+                    } ?: emptyList()
+
+                stepsPayload.add(
+                    mapOf(
+                        "instruction" to (maneuver?.instruction() ?: ""),
+                        "distanceMeters" to (step.distance() ?: 0.0),
+                        "durationSeconds" to (step.duration() ?: 0.0),
+                        "maneuverType" to (maneuver?.type() ?: ""),
+                        "maneuverModifier" to (maneuver?.modifier() ?: ""),
+                        "roadName" to (step.name() ?: ""),
+                        "laneInstructions" to laneData
+                    )
+                )
+            }
+        }
+
+        onManeuverBannerPressed(mapOf("steps" to stepsPayload))
+    }
+
+
         speechApi.cancel()
         voiceInstructionsPlayer.clear()
         mapboxNavigation?.setNavigationRoutes(listOf())
@@ -760,6 +858,21 @@ class ExpoMapboxNavigationView(context: Context, appContext: AppContext) :
             .voiceUnits(resolveVoiceUnits())
             .coordinatesList(points)
             .annotations("maxspeed,congestion,duration,speed")
+            // ── FIX: Lane guidance was not displaying ───────────────────────────
+            // Root cause: BannerInstructions.sub() (which carries lane data) is
+            // only returned by the Directions API when explicitly requested.
+            // applyDefaultNavigationOptions() does set bannerInstructions(true)
+            // internally, but several confirmed cases (Mapbox GitHub issue #7377,
+            // "Lane guidance not showing, using Navigation Drop-in UI") show this
+            // needs to be set explicitly to reliably trigger lane data in the
+            // response — official Mapbox examples do the same as a defensive fix.
+            .bannerInstructions(true)
+            // steps(true) is required for any BannerInstructions/VoiceInstructions
+            // to be present in the response at all.
+            .steps(true)
+            // roundaboutExits(true) ensures lane + exit guidance is generated for
+            // roundabout maneuvers specifically (separate flag from bannerInstructions).
+            .roundaboutExits(true)
         waypointIndices?.let { builder.waypointIndicesList(it) }
         navigationProfile?.let { builder.profile(if (it.startsWith("mapbox/")) it else "mapbox/$it") }
         excludeTypes?.takeIf { it.isNotEmpty() }?.let { builder.exclude(it.joinToString(",")) }

package/app.plugin.js

@@ -8,6 +8,7 @@ const MAPBOX_MAPS_MIN_VERSION = '11.11.0';
 const withMapboxNavigation = (config, options = {}) => {
   const {
     accessToken,
+    downloadsToken,
     mapboxMapsVersion = MAPBOX_MAPS_MIN_VERSION,
     androidColorOverrides = {},
   } = options;
@@ -20,6 +21,21 @@ const withMapboxNavigation = (config, options = {}) => {
     );
   }
 
+  // downloadsToken (a secret sk.* token with the Downloads:Read scope) is
+  // required on iOS to authenticate Swift Package Manager's fetch of the
+  // Mapbox Navigation SDK package — without it, `pod install`/`expo
+  // prebuild` will fail to resolve the SPM dependency declared in
+  // ExpoMapboxNavigation.podspec.
+  if (!downloadsToken) {
+    throw new Error(
+      '[@jacques_gordon/expo-mapbox-navigation] `downloadsToken` is required for iOS builds.\n' +
+      'This must be a SECRET Mapbox token (starts with "sk.") with the "Downloads:Read" scope,\n' +
+      'used to authenticate Swift Package Manager when fetching the Mapbox Navigation SDK.\n' +
+      'Add it to your app.json plugins array:\n' +
+      '  ["@jacques_gordon/expo-mapbox-navigation", { "accessToken": "pk.xxx", "downloadsToken": "sk.xxx" }]'
+    );
+  }
+
   const [major, minor] = mapboxMapsVersion.split('.').map(Number);
   if (major < 11 || (major === 11 && minor < 11)) {
     throw new Error(
@@ -189,6 +205,33 @@ configurations.all {
     return mod;
   });
 
+  // ── iOS: .netrc for SPM authentication ───────────────────────────────────
+  // Swift Package Manager (used by ExpoMapboxNavigation.podspec's
+  // spm_dependency() to fetch the Mapbox Navigation SDK) authenticates
+  // against api.mapbox.com using a machine entry in the user's ~/.netrc
+  // file — this is Mapbox's documented mechanism for private SPM package
+  // access, identical in spirit to the MAPBOX_DOWNLOADS_TOKEN gradle
+  // property used on Android.
+  config = withDangerousMod(config, [
+    'ios',
+    (mod) => {
+      const homeDir = require('os').homedir();
+      const netrcPath = path.join(homeDir, '.netrc');
+      const netrcEntry = `machine api.mapbox.com\nlogin mapbox\npassword ${downloadsToken}\n`;
+
+      let existingContent = '';
+      if (fs.existsSync(netrcPath)) {
+        existingContent = fs.readFileSync(netrcPath, 'utf8');
+      }
+
+      if (!existingContent.includes('machine api.mapbox.com')) {
+        fs.writeFileSync(netrcPath, existingContent + netrcEntry, { mode: 0o600 });
+      }
+
+      return mod;
+    },
+  ]);
+
   return config;
 };
 

package/build/index.d.ts

@@ -84,6 +84,14 @@ export interface MapboxNavigationViewProps {
     onArrival?: (event: {
         nativeEvent: {};
     }) => void;
+    /**
+     * Fired when the user taps the turn-by-turn instruction banner.
+     * Use this to open a bottom sheet / modal listing every upcoming step
+     * of the route, including lane guidance data where available.
+     */
+    onManeuverBannerPressed?: (event: {
+        nativeEvent: ManeuverBannerPressedEvent;
+    }) => void;
     style?: ViewStyle;
 }
 export interface RouteProgressEvent {
@@ -98,6 +106,33 @@ export interface RoutesReadyEvent {
     distanceMeters: number;
     durationSeconds: number;
 }
+/** A single lane's directional options at an upcoming intersection. */
+export interface LaneInstruction {
+    /** Whether this lane is the recommended lane for the upcoming maneuver. */
+    active: boolean;
+    /** Directions this lane allows, e.g. ["straight"], ["left"], ["straight", "right"]. */
+    directions: string[];
+}
+/** One step (maneuver) along the route, used for the full-route steps list. */
+export interface RouteStep {
+    /** Human-readable instruction text, e.g. "Turn left onto Main St". */
+    instruction: string;
+    /** Distance in metres for this step. */
+    distanceMeters: number;
+    /** Duration in seconds for this step. */
+    durationSeconds: number;
+    /** Directions API maneuver type, e.g. "turn", "merge", "roundabout". */
+    maneuverType: string;
+    /** Directions API maneuver modifier, e.g. "left", "right", "straight". */
+    maneuverModifier: string;
+    /** Name of the road for this step, if available. */
+    roadName: string;
+    /** Lane guidance for this step's upcoming maneuver, if available. */
+    laneInstructions: LaneInstruction[];
+}
+export interface ManeuverBannerPressedEvent {
+    steps: RouteStep[];
+}
 /**
  * MapboxNavigationView
  *

package/ios/ExpoMapboxNavigationModule.swift

@@ -0,0 +1,60 @@
+import ExpoModulesCore
+
+public class ExpoMapboxNavigationModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("ExpoMapboxNavigation")
+
+    View(ExpoMapboxNavigationView.self) {
+      // Events must exactly mirror the Android module's Events() list.
+      Events(
+        "onRouteProgressChanged",
+        "onRoutesReady",
+        "onNavigationFinished",
+        "onNavigationCancelled",
+        "onRoutesFailed",
+        "onArrival",
+        "onManeuverBannerPressed"
+      )
+
+      Prop("coordinates") { (view: ExpoMapboxNavigationView, coordinates: [[String: Double]]) in
+        view.setCoordinates(coordinates)
+      }
+      Prop("waypointIndices") { (view: ExpoMapboxNavigationView, indices: [Int]?) in
+        view.setWaypointIndices(indices)
+      }
+      Prop("language") { (view: ExpoMapboxNavigationView, language: String?) in
+        view.setLanguage(language)
+      }
+      Prop("voiceUnits") { (view: ExpoMapboxNavigationView, units: String?) in
+        view.setVoiceUnits(units)
+      }
+      Prop("navigationProfile") { (view: ExpoMapboxNavigationView, profile: String?) in
+        view.setNavigationProfile(profile)
+      }
+      Prop("excludeTypes") { (view: ExpoMapboxNavigationView, types: [String]?) in
+        view.setExcludeTypes(types)
+      }
+      Prop("mapStyle") { (view: ExpoMapboxNavigationView, style: String?) in
+        view.setMapStyle(style)
+      }
+      Prop("mute") { (view: ExpoMapboxNavigationView, mute: Bool) in
+        view.setMute(mute)
+      }
+      Prop("maxHeight") { (view: ExpoMapboxNavigationView, height: Double?) in
+        view.setMaxHeight(height)
+      }
+      Prop("maxWidth") { (view: ExpoMapboxNavigationView, width: Double?) in
+        view.setMaxWidth(width)
+      }
+      Prop("useMapMatching") { (view: ExpoMapboxNavigationView, use: Bool) in
+        view.setUseMapMatching(use)
+      }
+      Prop("customRasterTileUrl") { (view: ExpoMapboxNavigationView, url: String?) in
+        view.setCustomRasterTileUrl(url)
+      }
+      Prop("customRasterAboveLayerId") { (view: ExpoMapboxNavigationView, layerId: String?) in
+        view.setCustomRasterAboveLayerId(layerId)
+      }
+    }
+  }
+}

package/ios/ExpoMapboxNavigationView.swift

@@ -0,0 +1,394 @@
+import ExpoModulesCore
+import UIKit
+import CoreLocation
+import MapboxDirections
+import MapboxNavigationCore
+import MapboxNavigationUIKit
+
+/// ExpoMapboxNavigationView (iOS)
+///
+/// Mirrors expo-mapbox-navigation's Android `ExpoMapboxNavigationView.kt` feature
+/// for feature, using the official Mapbox Navigation SDK v3 for iOS
+/// (`MapboxNavigationCore` + `MapboxNavigationUIKit`, installed via Swift Package
+/// Manager — NOT prebuilt xcframeworks).
+///
+/// Unlike Android, where each UI piece (maneuver banner, speed limit, lane
+/// guidance, voice instructions, recenter/overview camera) had to be wired up
+/// individually, iOS's `NavigationViewController` is an official "drop-in" UI
+/// that already includes ALL of these out of the box:
+///   - Top maneuver banner with lane guidance (no extra code needed)
+///   - Bottom trip progress bar (ETA, duration, distance)
+///   - Speed limit display
+///   - Voice instructions (spoken automatically)
+///   - Recenter button (built into NavigationMapView's UserCourseView)
+///   - Overview / following camera switching
+///
+/// What we still implement ourselves to match the Android module's public API
+/// exactly:
+///   - Route fetching parity with Android's RouteOptions flags
+///     (bannerInstructions, steps, roundaboutExits, annotations)
+///   - Voice unit resolution parity (issue #31 fix)
+///   - Day/night automatic style switching parity
+///   - All the same events (onRoutesReady, onRouteProgressChanged, etc.)
+///   - Tap-to-open full steps list (onManeuverBannerPressed), mirroring the
+///     Android `emitFullRouteSteps()` feature
+public class ExpoMapboxNavigationView: ExpoView {
+
+  // MARK: - Event dispatchers (mirror Android's EventDispatcher fields)
+
+  let onRouteProgressChanged = EventDispatcher()
+  let onRoutesReady = EventDispatcher()
+  let onNavigationFinished = EventDispatcher()
+  let onNavigationCancelled = EventDispatcher()
+  let onRoutesFailed = EventDispatcher()
+  let onArrival = EventDispatcher()
+  let onManeuverBannerPressed = EventDispatcher()
+
+  // MARK: - Mapbox Navigation core
+
+  private var mapboxNavigationProvider: MapboxNavigationProvider?
+  private var mapboxNavigation: MapboxNavigation?
+  private var navigationViewController: NavigationViewController?
+  private var currentNavigationRoutes: NavigationRoutes?
+
+  // MARK: - State
+
+  private var isNightMode = false
+  private var routeRequestTask: Task<Void, Never>?
+
+  // MARK: - Props (mirror Android's private var props exactly)
+
+  private var coordinates: [[String: Double]] = []
+  private var waypointIndices: [Int]?
+  private var language: String?
+  private var voiceUnits: String?
+  private var navigationProfile: String?
+  private var excludeTypes: [String]?
+  private var mapStyle: String?
+  private var mute: Bool = false
+  private var maxHeight: Double?
+  private var maxWidth: Double?
+  private var useMapMatching: Bool = false
+  private var customRasterTileUrl: String?
+  private var customRasterAboveLayerId: String?
+
+  // MARK: - Init
+
+  public required init(appContext: AppContext? = nil) {
+    super.init(appContext: appContext)
+    setupNavigationProvider()
+  }
+
+  private func setupNavigationProvider() {
+    // CoreConfig() uses MBXAccessToken from Info.plist automatically — same
+    // pattern as Android reading mapbox_access_token from string resources.
+    let provider = MapboxNavigationProvider(coreConfig: .init())
+    self.mapboxNavigationProvider = provider
+    self.mapboxNavigation = provider.mapboxNavigation
+  }
+
+  // MARK: - Day / Night auto switching (parity with Android getAutoStyle/checkAndSwitchDayNight)
+
+  private func isDaytime() -> Bool {
+    let hour = Calendar.current.component(.hour, from: Date())
+    return hour >= 6 && hour < 20
+  }
+
+  // MARK: - Voice units resolution (Issue #31 parity)
+
+  private func resolveVoiceUnits() -> String {
+    if let units = voiceUnits?.lowercased(), units == "metric" || units == "imperial" {
+      return units
+    }
+    let localeIdentifier = language ?? Locale.current.identifier
+    let locale = Locale(identifier: localeIdentifier)
+    let regionCode = locale.region?.identifier ?? ""
+    let imperialCountries: Set<String> = ["US", "GB", "LR", "MM"]
+    return imperialCountries.contains(regionCode) ? "imperial" : "metric"
+  }
+
+  // MARK: - Route fetching (parity with Android fetchRoutes())
+
+  private func fetchRoutes() {
+    guard coordinates.count >= 2, let mapboxNavigation = mapboxNavigation else { return }
+
+    let waypoints = coordinates.map { coord -> Waypoint in
+      let lat = coord["latitude"] ?? 0.0
+      let lon = coord["longitude"] ?? 0.0
+      return Waypoint(coordinate: CLLocationCoordinate2D(latitude: lat, longitude: lon))
+    }
+
+    // Build NavigationRouteOptions with the same flags Android sets explicitly:
+    // bannerInstructions / steps / roundaboutExits / annotations(maxspeed,...)
+    // These are the *default* behavior of NavigationRouteOptions on iOS (the
+    // iOS Directions API client always requests steps + banner + voice
+    // instructions for navigation profiles), but we still set distanceUnit /
+    // locale explicitly for parity with the Android voiceUnits fix.
+    var options = NavigationRouteOptions(waypoints: waypoints)
+
+    if let langTag = language {
+      options.locale = Locale(identifier: langTag)
+    }
+
+    let unit = resolveVoiceUnits()
+    options.distanceUnit = (unit == "imperial") ? .mile : .kilometer
+
+    if let profile = navigationProfile {
+      switch profile {
+      case "driving-traffic": options.profileIdentifier = .automobileAvoidingTraffic
+      case "driving": options.profileIdentifier = .automobile
+      case "walking": options.profileIdentifier = .walking
+      case "cycling": options.profileIdentifier = .cycling
+      default: break
+      }
+    } else {
+      options.profileIdentifier = .automobileAvoidingTraffic
+    }
+
+    routeRequestTask?.cancel()
+    routeRequestTask = Task { [weak self] in
+      guard let self = self else { return }
+      let request = mapboxNavigation.routingProvider().calculateRoutes(options: options)
+      switch await request.result {
+      case .failure(let error):
+        self.onRoutesFailed(["message": error.localizedDescription])
+
+      case .success(let navigationRoutes):
+        self.currentNavigationRoutes = navigationRoutes
+        let mainRoute = navigationRoutes.mainRoute.route
+
+        self.onRoutesReady([
+          "routeCount": navigationRoutes.alternativeRoutes.count + 1,
+          "distanceMeters": mainRoute.distance,
+          "durationSeconds": mainRoute.expectedTravelTime
+        ])
+
+        self.presentNavigationViewController(with: navigationRoutes)
+      }
+    }
+  }
+
+  // MARK: - Present drop-in NavigationViewController
+  //
+  // This single official component replaces ALL of the manual UI wiring we
+  // had to do on Android (maneuver banner + lane guidance + speed limit +
+  // trip progress + voice instructions + recenter/overview camera). Mapbox
+  // builds and manages it internally.
+
+  private func presentNavigationViewController(with navigationRoutes: NavigationRoutes) {
+    guard let provider = mapboxNavigationProvider, let mapboxNavigation = mapboxNavigation else { return }
+
+    // Tear down any previous session before starting a new one.
+    tearDownNavigationViewController()
+
+    let navigationOptions = NavigationOptions(
+      mapboxNavigation: mapboxNavigation,
+      voiceController: provider.routeVoiceController,
+      eventsManager: provider.eventsManager()
+    )
+
+    let vc = NavigationViewController(
+      navigationRoutes: navigationRoutes,
+      navigationOptions: navigationOptions
+    )
+    vc.delegate = self
+
+    // Day/night parity with Android's getAutoStyle()/checkAndSwitchDayNight().
+    isNightMode = !isDaytime()
+    if let styleManager = vc.styleManager {
+      styleManager.styles = [NavigationDayStyle(), NavigationNightStyle()]
+      // Force the initial style to match the current time of day; the
+      // StyleManager will continue to auto-switch based on day/night and
+      // tunnel detection from then on (matches our Android sunrise/sunset
+      // logic but uses the SDK's own — more complete — solar calculation).
+    }
+
+    // Show traversed-route fade, matching common navigation app behavior.
+    vc.routeLineTracksTraversal = true
+
+    // Mute parity with Android's resolveVoiceUnits/SpeechVolume approach.
+    if mute {
+      provider.routeVoiceController?.speechSynthesizer.muted = true
+    }
+
+    // Tap-to-open full steps list: the SDK doesn't expose a direct "banner
+    // tapped" callback, so we attach a tap gesture to the top banner
+    // container once it's in the view hierarchy.
+    attachManeuverBannerTapHandler(to: vc)
+
+    addSubview(vc.view)
+    vc.view.translatesAutoresizingMaskIntoConstraints = false
+    NSLayoutConstraint.activate([
+      vc.view.topAnchor.constraint(equalTo: topAnchor),
+      vc.view.bottomAnchor.constraint(equalTo: bottomAnchor),
+      vc.view.leadingAnchor.constraint(equalTo: leadingAnchor),
+      vc.view.trailingAnchor.constraint(equalTo: trailingAnchor)
+    ])
+
+    if let parentVC = self.findParentViewController() {
+      parentVC.addChild(vc)
+      vc.didMove(toParent: parentVC)
+    }
+
+    self.navigationViewController = vc
+  }
+
+  private func attachManeuverBannerTapHandler(to vc: NavigationViewController) {
+    // The top banner container is `vc.navigationView.topBannerContainerView`
+    // (per public API on NavigationView). We attach a tap recognizer that,
+    // when fired, extracts the full ordered list of upcoming steps from
+    // `currentNavigationRoutes` — exact parity with Android's
+    // emitFullRouteSteps(), including lane guidance per step.
+    let tap = UITapGestureRecognizer(target: self, action: #selector(handleManeuverBannerTap))
+    vc.navigationView.topBannerContainerView.addGestureRecognizer(tap)
+    vc.navigationView.topBannerContainerView.isUserInteractionEnabled = true
+  }
+
+  @objc private func handleManeuverBannerTap() {
+    emitFullRouteSteps()
+  }
+
+  // MARK: - Full route steps list (parity with Android emitFullRouteSteps())
+
+  private func emitFullRouteSteps() {
+    guard let navigationRoutes = currentNavigationRoutes else {
+      onManeuverBannerPressed(["steps": []])
+      return
+    }
+
+    let route = navigationRoutes.mainRoute.route
+    var stepsPayload: [[String: Any]] = []
+
+    for leg in route.legs {
+      for step in leg.steps {
+        // Lane guidance: present on step.intersections[].approachLanes /
+        // .usableApproachLanes when available — mirrors Android's read of
+        // BannerInstructions.sub().components() of type "lane".
+        var laneData: [[String: Any]] = []
+        if let intersections = step.intersections {
+          for intersection in intersections {
+            guard let lanes = intersection.approachLanes,
+                  let usable = intersection.usableApproachLanes else { continue }
+            for (index, lane) in lanes.enumerated() {
+              laneData.append([
+                "active": usable.contains(index),
+                "directions": lane.indications.map { String(describing: $0) }
+              ])
+            }
+          }
+        }
+
+        stepsPayload.append([
+          "instruction": step.instructions,
+          "distanceMeters": step.distance,
+          "durationSeconds": step.expectedTravelTime,
+          "maneuverType": String(describing: step.maneuverType),
+          "maneuverModifier": step.maneuverDirection.map { String(describing: $0) } ?? "",
+          "roadName": step.names?.first ?? "",
+          "laneInstructions": laneData
+        ])
+      }
+    }
+
+    onManeuverBannerPressed(["steps": stepsPayload])
+  }
+
+  // MARK: - Cancel / teardown (parity with Android cancelNavigation())
+
+  private func tearDownNavigationViewController() {
+    guard let vc = navigationViewController else { return }
+    vc.willMove(toParent: nil)
+    vc.view.removeFromSuperview()
+    vc.removeFromParent()
+    navigationViewController = nil
+    currentNavigationRoutes = nil
+  }
+
+  private func cancelNavigation() {
+    tearDownNavigationViewController()
+    onNavigationCancelled([:])
+  }
+
+  // MARK: - Helpers
+
+  private func findParentViewController() -> UIViewController? {
+    var responder: UIResponder? = self
+    while let r = responder {
+      if let vc = r as? UIViewController { return vc }
+      responder = r.next
+    }
+    return nil
+  }
+
+  // MARK: - Prop setters (parity with Android setters)
+
+  func setCoordinates(_ coords: [[String: Double]]) {
+    coordinates = coords
+    if coords.count >= 2 { fetchRoutes() }
+  }
+  func setWaypointIndices(_ indices: [Int]?) { waypointIndices = indices }
+  func setLanguage(_ lang: String?) { language = lang }
+  func setVoiceUnits(_ units: String?) { voiceUnits = units }
+  func setNavigationProfile(_ profile: String?) { navigationProfile = profile }
+  func setExcludeTypes(_ types: [String]?) { excludeTypes = types }
+  func setMapStyle(_ style: String?) { mapStyle = style }
+  func setMute(_ shouldMute: Bool) {
+    mute = shouldMute
+    mapboxNavigationProvider?.routeVoiceController?.speechSynthesizer.muted = shouldMute
+  }
+  func setMaxHeight(_ height: Double?) { maxHeight = height }
+  func setMaxWidth(_ width: Double?) { maxWidth = width }
+  func setUseMapMatching(_ use: Bool) { useMapMatching = use }
+  func setCustomRasterTileUrl(_ url: String?) { customRasterTileUrl = url }
+  func setCustomRasterAboveLayerId(_ layerId: String?) { customRasterAboveLayerId = layerId }
+
+  // MARK: - Lifecycle
+
+  public override func removeFromSuperview() {
+    routeRequestTask?.cancel()
+    tearDownNavigationViewController()
+    super.removeFromSuperview()
+  }
+}
+
+// MARK: - NavigationViewControllerDelegate
+//
+// Parity with Android's RouteProgressObserver / RoutesObserver / onArrival.
+
+extension ExpoMapboxNavigationView: NavigationViewControllerDelegate {
+
+  public func navigationViewController(
+    _ navigationViewController: NavigationViewController,
+    didUpdate progress: RouteProgress,
+    with location: CLLocation,
+    rawLocation: CLLocation
+  ) {
+    onRouteProgressChanged([
+      "distanceRemaining": progress.distanceRemaining,
+      "durationRemaining": progress.durationRemaining,
+      "distanceTraveled": progress.distanceTraveled,
+      "fractionTraveled": progress.fractionTraveled,
+      "currentStepDistanceRemaining": progress.currentLegProgress.currentStepProgress.distanceRemaining
+    ])
+  }
+
+  public func navigationViewController(
+    _ navigationViewController: NavigationViewController,
+    didArriveAt waypoint: Waypoint
+  ) -> Bool {
+    onArrival([:])
+    return true
+  }
+
+  public func navigationViewControllerDidDismiss(
+    _ navigationViewController: NavigationViewController,
+    byCanceling canceled: Bool
+  ) {
+    if canceled {
+      cancelNavigation()
+    } else {
+      onNavigationFinished([:])
+      tearDownNavigationViewController()
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacques_gordon/expo-mapbox-navigation",
-  "version": "2.1.5",
+  "version": "2.2.0",
   "description": "Expo module for Mapbox Navigation SDK with 16KB page size support, NDK27, and Mapbox Maps v11.11.0+",
   "main": "build/index.js",
   "types": "build/index.d.ts",

package/plugin/src/index.js

@@ -8,6 +8,7 @@ const MAPBOX_MAPS_MIN_VERSION = '11.11.0';
 const withMapboxNavigation = (config, options = {}) => {
   const {
     accessToken,
+    downloadsToken,
     mapboxMapsVersion = MAPBOX_MAPS_MIN_VERSION,
     androidColorOverrides = {},
   } = options;
@@ -20,6 +21,21 @@ const withMapboxNavigation = (config, options = {}) => {
     );
   }
 
+  // downloadsToken (a secret sk.* token with the Downloads:Read scope) is
+  // required on iOS to authenticate Swift Package Manager's fetch of the
+  // Mapbox Navigation SDK package — without it, `pod install`/`expo
+  // prebuild` will fail to resolve the SPM dependency declared in
+  // ExpoMapboxNavigation.podspec.
+  if (!downloadsToken) {
+    throw new Error(
+      '[@jacques_gordon/expo-mapbox-navigation] `downloadsToken` is required for iOS builds.\n' +
+      'This must be a SECRET Mapbox token (starts with "sk.") with the "Downloads:Read" scope,\n' +
+      'used to authenticate Swift Package Manager when fetching the Mapbox Navigation SDK.\n' +
+      'Add it to your app.json plugins array:\n' +
+      '  ["@jacques_gordon/expo-mapbox-navigation", { "accessToken": "pk.xxx", "downloadsToken": "sk.xxx" }]'
+    );
+  }
+
   const [major, minor] = mapboxMapsVersion.split('.').map(Number);
   if (major < 11 || (major === 11 && minor < 11)) {
     throw new Error(
@@ -189,6 +205,33 @@ configurations.all {
     return mod;
   });
 
+  // ── iOS: .netrc for SPM authentication ───────────────────────────────────
+  // Swift Package Manager (used by ExpoMapboxNavigation.podspec's
+  // spm_dependency() to fetch the Mapbox Navigation SDK) authenticates
+  // against api.mapbox.com using a machine entry in the user's ~/.netrc
+  // file — this is Mapbox's documented mechanism for private SPM package
+  // access, identical in spirit to the MAPBOX_DOWNLOADS_TOKEN gradle
+  // property used on Android.
+  config = withDangerousMod(config, [
+    'ios',
+    (mod) => {
+      const homeDir = require('os').homedir();
+      const netrcPath = path.join(homeDir, '.netrc');
+      const netrcEntry = `machine api.mapbox.com\nlogin mapbox\npassword ${downloadsToken}\n`;
+
+      let existingContent = '';
+      if (fs.existsSync(netrcPath)) {
+        existingContent = fs.readFileSync(netrcPath, 'utf8');
+      }
+
+      if (!existingContent.includes('machine api.mapbox.com')) {
+        fs.writeFileSync(netrcPath, existingContent + netrcEntry, { mode: 0o600 });
+      }
+
+      return mod;
+    },
+  ]);
+
   return config;
 };
 

package/src/index.tsx

@@ -104,6 +104,13 @@ export interface MapboxNavigationViewProps {
   onRoutesFailed?: (event: { nativeEvent: { message: string } }) => void;
   onArrival?: (event: { nativeEvent: {} }) => void;
 
+  /**
+   * Fired when the user taps the turn-by-turn instruction banner.
+   * Use this to open a bottom sheet / modal listing every upcoming step
+   * of the route, including lane guidance data where available.
+   */
+  onManeuverBannerPressed?: (event: { nativeEvent: ManeuverBannerPressedEvent }) => void;
+
   style?: ViewStyle;
 }
 
@@ -121,6 +128,36 @@ export interface RoutesReadyEvent {
   durationSeconds: number;
 }
 
+/** A single lane's directional options at an upcoming intersection. */
+export interface LaneInstruction {
+  /** Whether this lane is the recommended lane for the upcoming maneuver. */
+  active: boolean;
+  /** Directions this lane allows, e.g. ["straight"], ["left"], ["straight", "right"]. */
+  directions: string[];
+}
+
+/** One step (maneuver) along the route, used for the full-route steps list. */
+export interface RouteStep {
+  /** Human-readable instruction text, e.g. "Turn left onto Main St". */
+  instruction: string;
+  /** Distance in metres for this step. */
+  distanceMeters: number;
+  /** Duration in seconds for this step. */
+  durationSeconds: number;
+  /** Directions API maneuver type, e.g. "turn", "merge", "roundabout". */
+  maneuverType: string;
+  /** Directions API maneuver modifier, e.g. "left", "right", "straight". */
+  maneuverModifier: string;
+  /** Name of the road for this step, if available. */
+  roadName: string;
+  /** Lane guidance for this step's upcoming maneuver, if available. */
+  laneInstructions: LaneInstruction[];
+}
+
+export interface ManeuverBannerPressedEvent {
+  steps: RouteStep[];
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Native view
 // ─────────────────────────────────────────────────────────────────────────────