Refine iOS Navigation: SwiftUI + drop-in NVC default

[ArtemStepuk]

Summary

Stacked on #12 (add-navigation-patterns-skill). Updates iOS Navigation only, aligned with current official Mapbox getting-started guidance and review feedback on this PR.

• Default: SwiftUI app shell + wrap drop-in NavigationViewController via UIViewControllerRepresentable
• UIKit apps: present NavigationViewController directly
• Opt-in: fully custom Core UI (CoreSDKExample) only when the user wants to replace the drop-in nav chrome
• Single reference: references/ios-navigation-sdk.md
• Sample host ≠ API stack: AdditionalExamples are UIKit demo hosts. A UIViewController sample does not mean the API is UIKit-only.
  • NavigationMapView APIs are stack-independent — wrap NavigationMapView in UIViewRepresentable and configure the same entities (custom waypoint / final-waypoint image, waypoint styling, route line, camera, callouts)
  • MapboxMap APIs (road cameras) attach to any map — SwiftUI MapReader (proxy.map) or navigationMapView.mapView.mapboxMap
  • True drop-in / UIKit chrome: NVC top/bottom bars, styled NVC UI elements, embedding NVC
• Example patterns catalog: self-contained topic index with the stack tags above; fetch upstream sample source only if the user asks
• Updates SKILL.md, AGENTS.md, README blurb, and evals (including Add spell check entries for new skills #17 road cameras + Add Pattern 6: Delivery/Logistics Map #18 NMV/waypoints) accordingly

Android/Web navigation content from #12 is unchanged. Maps and Search skills are untouched. Does not inline all AdditionalExamples implementations.

Test plan

• npm run validate:skills (and format/spell/lint as usual)
• Confirm default path is SwiftUI + wrapped NavigationViewController
• Confirm CoreSDKExample is documented as opt-in only
• Confirm catalog distinguishes NMV API / MapboxMap (stack-independent) vs NVC chrome
• Confirm Road Cameras section uses RoadCamerasManager + RoadCamerasMapController + MapReader
• Spot-check evals 1, 16, 17, 18
• After merge into Add mapbox-navigation-patterns skill #12, confirm Android/Web sections still read correctly

[mattpodwysocki]

Thanks for this, and nice work on the verification, I checked the actual upstream repo against most of the specific claims here (CoreSDKExample's Navigation.swift, the tripSession methods, Constants.swift's listOfExamples, the Road Cameras example) and it all holds up. Ran the full check suite on the actual branch in an isolated worktree too, that's clean.

Two things I want addressed before this merges:

1. ios-navigation-sdk.md doesn't get touched by this PR, but SKILL.md now describes it as "UIKit / drop-in NavigationViewController only." The file itself still has the full "Custom Navigation UI" section (Combine-based, not UIKit at all) and the "Anti-pattern: recomputing progress manually" section, both of which now duplicate content in the new ios-navigation-swiftui.md and contradict the file's new stated scope. Can you prune ios-navigation-sdk.md down to just Basic Turn-by-Turn Navigation and Voice Guidance Configuration so it actually matches what SKILL.md says it's for? Otherwise we've got two copies of the same guidance that'll drift apart over time.

2. The bigger one: requiring a live fetch of the upstream Examples tree before answering any iOS navigation question is a real shift for how skills work in this repo. Everything else here is built to be self-contained so an agent can act without a follow-up network call, this makes an external GitHub fetch a prerequisite for answering at all, even for stuff the inline content already covers correctly. I don't think that's a call to make inside one iOS-specific PR. What happens when an agent doesn't have live network/tool access? Also worth knowing unauthenticated GitHub API calls are rate limited at 60/hr per IP, so this could start silently failing in some environments with nothing to catch it, unlike a dead link our CI link checker would flag. I'd want an explicit yes from whoever owns the overall skill conventions here before this pattern lands, since it changes what "self-contained skill" means for the whole repo, not just this one.

Small thing, not blocking: eval #16 checks for the literal method signature tripSession().startActiveGuidance(with:startLegIndex:), which is more brittle than the project's own eval guidance calls for (testing behavior over exact API recall). Wouldn't hold up the PR for it, just flagging.

[mattpodwysocki]

Re-reviewed after the latest push, both things I flagged last time are fixed. ios-navigation-swiftui.md is gone and everything's consolidated into one file, and the live-fetch requirement is now an inline catalog with fetch as opt-in only. I cross-checked all 22 rows in the Example patterns catalog against the real Constants.swift listOfExamples on mapbox-navigation-ios, all match exactly. Ran the full eval suite on the actual branch too: 98% (194/198).

One small gap from that eval run worth a quick fix: eval #17 (Road Cameras) scored 83% because the response never mentioned that AdditionalExamples samples are typically UIKit-based even though Core/SwiftUI is the default elsewhere in the skill. Could you add a line to the catalog's intro along those lines, something like "note: most AdditionalExamples samples are UIKit, adapt the pattern to Core/SwiftUI unless the user wants UIKit directly"? Not blocking, just tightens up that one case.

Also, we talked through whether to inline more of the 22 examples the way Android inlined route line/camera/voice, and decided against it. The current shape (two inlined defaults plus a catalog pointer for the long tail) is the right scope, pulling in all 22 would add maintenance surface without much real benefit given most of them are pretty niche.

Good to merge from my side once the catalog intro line is in.

[mattpodwysocki]

Need to walk back my "good to merge" from before. I verified the code in this PR was accurate, but I didn't check whether defaulting to Core+SwiftUI custom UI over UIKit is actually the right call, and it isn't, at least not based on what Mapbox's own current official docs recommend.

I pulled the mapbox-navigation-ios README and the docs.mapbox.com tutorial "Add turn-by-turn navigation to an iOS app" (the current, official getting-started guide). Both use SwiftUI for the app's own screens, sure, but for the actual navigation experience they wrap the UIKit NavigationViewController via UIViewControllerRepresentable, not a fully custom Core+Combine UI. Neither the README nor the tutorial mentions CoreSDKExample or a Core-only custom UI at all. The README's getting started and customization sections are UIKit end to end (NavigationViewController, NavigationOptions, StandardDayStyle).

I think this PR conflates two separate things: what UI framework the app is built in (SwiftUI vs UIKit) and whether the user wants the drop-in navigation experience or a fully custom one. Those are independent. The official answer for "I'm building a SwiftUI app, add navigation" is: keep SwiftUI for your own screens, wrap the drop-in NavigationViewController for the nav surface itself via UIViewControllerRepresentable. That's a lot simpler than the full custom Core+Combine build CoreSDKExample shows, and it's what Mapbox is actually telling people to do right now.

CoreSDKExample is a real, legitimate pattern, for people who explicitly want full UI customization, but I don't think it should be the default over drop-in-wrapped-in-SwiftUI. Given you two mentioned this is a work in progress toward more SwiftUI support, that also tracks, if Core-first isn't fully where the SDK's guidance is yet, defaulting to it in the skill is ahead of where Mapbox's own docs currently are.

Would want to see the default flipped to: SwiftUI app shell + UIViewControllerRepresentable-wrapped NavigationViewController as the default path, with the Core+Combine fully-custom UI (CoreSDKExample) as the opt-in for people who explicitly want to build their own nav UI instead of using the drop-in one.

[mattpodwysocki]

Re-reviewed after the latest push. The default fix is right and I verified it, not just read the description. New default is exactly the official pattern, SwiftUI app shell + NavigationViewController wrapped in UIViewControllerRepresentable, with CoreSDKExample's fully custom Core UI now clearly opt-in.

Went through the new content carefully since there's a lot of it now (multi-stop, route line styling, navigation camera, road cameras, route alerts). Checked all of it against real SDK source, NavigationOptions.swift, RouteProgress.swift, NavigationMapView.swift, and the actual upstream examples. It all holds up. The Road Cameras section's @_spi(MapboxInternal) import MapboxNavigationCore looked alarming at first glance since that's normally an internal-only marker, but I pulled the real Road-Cameras.swift and it's a verbatim match, that's genuinely how that example works today, not something invented for this PR. Also checked both new doc URLs (get-started, install), both resolve fine.

Ran the full eval suite on the actual branch: 95.5% (189/198). One real gap worth fixing before merge:

Eval #17 dropped to 67% (was around 83% before). Asked specifically about Road Cameras, the model said the example is "stack independent" and works the same for SwiftUI drop-in or custom Core UI, which actually contradicts the nuance we wanted. The catalog table's general note about AdditionalExamples being UIKit based isn't strong enough on its own, the model didn't connect it to this specific inline section. Can you add that caveat directly in the Road Cameras section itself, not just the catalog intro?

Smaller thing: eval #1 dipped to 80%, missed the MAU vs pay-per-request pricing point entirely. Pre-existing eval, not iOS specific, probably just crowded out by how much more implementation detail is in the response now. Worth a glance but not blocking.

One structural note, not blocking either: the file's at 455 lines now, up from 270 last round, well past the under-200-lines guideline in CONTRIBUTING.md for reference files. Not enforced by validate:skills and it covers a lot of genuinely distinct ground now (setup, three UI approaches, five specialized patterns, voice, antipattern). Might be worth splitting the specialized topics (multi-stop, route line, camera, road cameras, alerts) into a second reference file the way Android already separates android-navigation-sdk.md from android-performance-antipatterns.md, before it grows further.

[mattpodwysocki]

Re-reviewed after the latest push. Both things from last round are handled well.

The file split worked out nicely. ios-navigation-sdk.md is down to 310 lines, and the new ios-navigation-specialized.md (multi-stop, route line, camera, road cameras, alerts) is 165, under the guideline. Good separation, matches how Android splits basic patterns from antipatterns.

The sample host vs API stack framing is a better fix than what I suggested, not just a caveat, it draws a real distinction between the demo app's UI framework and whether the specific API is UIKit-only. Checked it, NavigationMapView really is open class NavigationMapView: UIView in the actual source, so wrapping it in UIViewRepresentable is architecturally sound, not just plausible sounding.

Ran the full eval suite on the actual branch: 99.1% (211/213). Both regressions from last round are gone, pricing point's back to 100%, eval #17 recovered to 93%, and the new eval #18 (the "do I have to switch to UIKit" scenario) scores 100%.

One real issue I found while checking the Road Cameras rewrite, evals won't catch this since it's a compile time thing not a fact check. This won't compile:

guard let mapboxMap = navigationMapView.mapView.mapboxMap else { return }

.mapboxMap on MapView isn't optional, I confirmed against the real CoreSDKExample, which calls navigationMapView.mapView.mapboxMap.loadStyle(...) directly with no ? and no guard anywhere. The original upstream Road-Cameras.swift only got away with a guard let here because it was chained off navigationViewController.navigationMapView?, which is optional, not because mapboxMap itself is. Since this rewrite takes a non-optional NavigationMapView param directly, the whole chain is non-optional now, so that guard let won't compile. Should just be let mapboxMap = navigationMapView.mapView.mapboxMap.

Good to merge once that one line's fixed.

[ArtemStepuk]

Re-reviewed after the latest push. Both things from last round are handled well.

The file split worked out nicely. ios-navigation-sdk.md is down to 310 lines, and the new ios-navigation-specialized.md (multi-stop, route line, camera, road cameras, alerts) is 165, under the guideline. Good separation, matches how Android splits basic patterns from antipatterns.

The sample host vs API stack framing is a better fix than what I suggested, not just a caveat, it draws a real distinction between the demo app's UI framework and whether the specific API is UIKit-only. Checked it, NavigationMapView really is open class NavigationMapView: UIView in the actual source, so wrapping it in UIViewRepresentable is architecturally sound, not just plausible sounding.

Ran the full eval suite on the actual branch: 99.1% (211/213). Both regressions from last round are gone, pricing point's back to 100%, eval #17 recovered to 93%, and the new eval #18 (the "do I have to switch to UIKit" scenario) scores 100%.

One real issue I found while checking the Road Cameras rewrite, evals won't catch this since it's a compile time thing not a fact check. This won't compile:

guard let mapboxMap = navigationMapView.mapView.mapboxMap else { return }

.mapboxMap on MapView isn't optional, I confirmed against the real CoreSDKExample, which calls navigationMapView.mapView.mapboxMap.loadStyle(...) directly with no ? and no guard anywhere. The original upstream Road-Cameras.swift only got away with a guard let here because it was chained off navigationViewController.navigationMapView?, which is optional, not because mapboxMap itself is. Since this rewrite takes a non-optional NavigationMapView param directly, the whole chain is non-optional now, so that guard let won't compile. Should just be let mapboxMap = navigationMapView.mapView.mapboxMap.

Good to merge once that one line's fixed.

thank you! great call, ready.