MapboxNavigationNative 324.24.1: private umbrella header omits three shipped PrivateHeaders/ files, breaks Xcode 16 explicit-module precompile

Environment

• Xcode version: 26.5 (Build 17F42), iOS Simulator SDK 26.5 (Build 23F73)
• iOS version: N/A — fails at compile time, never reaches a runtime. App deployment target is iOS 18.0.
• Devices affected: Build-time failure on all targets. Reproduced on iOS Simulator (arm64 and x86_64); identical PCM
  emit pattern means device builds (arm64) will fail the same way.
• Maps SDK Version:
  • mapbox-maps-ios 11.24.1
  • mapbox-navigation-ios 3.24.1
  • mapbox-navigation-native-ios 324.24.1 ← failing framework
  • MapboxCommon 24.24.1
  • MapboxCoreMaps 11.24.1

Observed behavior and steps to reproduce

MapboxNavigationNative.framework (v324.24.1, distributed via SPM as a binary .xcframework) ships a private module map
(module.private.modulemap) whose umbrella header (MapboxNavigationNative_Internal.h) does not #import three private
headers it ships in PrivateHeaders/. Under Xcode 16+ Swift Explicit Modules (the default), Clang fails the
precompiled-module emit.

Reproduce:

1. Pin SPM dependencies to:
   MapboxMaps: exactVersion: 11.24.1
   MapboxNavigation: exactVersion: 3.24.1
   MapboxSearch: exactVersion: 2.24.1
2. Clean DerivedData, resolve SPM (yields MapboxNavigationNative @ 324.24.1).
3. xcodebuild -scheme … -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' build

Resulting errors (verbatim):

MapboxNavigationNative.framework/PrivateHeaders/MapboxNavigationNative_Internal.h:44:1:
error: umbrella header for module 'MapboxNavigationNative_Private'
does not include header 'MapboxDirectionsRoute_Internal.h'

MapboxNavigationNative.framework/PrivateHeaders/MapboxNavigationNative_Internal.h:44:1:
error: umbrella header for module 'MapboxNavigationNative_Private'
does not include header 'MBDRouteDirectionsRouteResponse_Internal.h'

MapboxNavigationNative.framework/PrivateHeaders/MapboxNavigationNative_Internal.h:44:1:
error: umbrella header for module 'MapboxNavigationNative_Private'
does not include header 'MBDRouteDirectionsRouteContext_Internal.h'

:0: error: failed to emit precompiled module
'…/SwiftExplicitPrecompiledModules/MapboxNavigationNative_Private-.pcm'
for module map '…/MapboxNavigationNative.framework/Modules/module.private.modulemap'

The build emits this for both arm64 and x86_64 slices, then aborts (** BUILD FAILED ** with 2 failed dependency-PCM
tasks).

I verified that MapboxDirectionsRoute_Internal.h does exist on disk at
MapboxNavigationNative.framework/PrivateHeaders/MapboxDirectionsRoute_Internal.h — the diagnostic is "umbrella doesn't
include," not "file not found." The other two are implied to exist on the same basis (Clang's "does not include
header" diagnostic only fires when the header is on disk but absent from the umbrella).

Expected behavior

Either (a) the umbrella header MapboxNavigationNative_Internal.h #imports every header shipped under PrivateHeaders/
(which is the standard Clang modules convention and was the case in 324.23.0 — the previous version builds cleanly),
or (b) the three orphan headers are removed from the framework if they're not part of the private module.

Notes / preliminary analysis

• The previous release mapbox-navigation-native-ios 324.23.0 (paired with mapbox-maps-ios 11.23.0 /
  mapbox-navigation-ios 3.23.0) does not have this problem — same project, same Xcode, same explicit-modules setting,
  builds clean.
• Inspecting the shipped umbrella in 324.24.1 (PrivateHeaders/MapboxNavigationNative_Internal.h) shows ~40 #import
  "…_Internal.h" lines but no entry for any of the three flagged headers. The omitted set appears to be specifically the
  route-directions private interfaces:
  • MapboxDirectionsRoute_Internal.h
  • MBDRouteDirectionsRouteResponse_Internal.h
  • MBDRouteDirectionsRouteContext_Internal.h
• This looks like a packaging/codegen step that fell out of sync between the framework's exported private headers and
  the regenerated umbrella for this release. Almost certainly fixable by re-running whatever generates
  MapboxNavigationNative_Internal.h against the actual PrivateHeaders/ directory contents.
• Workaround consumers could apply: post-resolve patch the umbrella to add the three #import lines — but it doesn't
  survive SPM cache eviction, so most apps will just pin back to 324.23.0 (which is what we did).

Additional links and references

• Failing release: https://github.com/mapbox/mapbox-navigation-native-ios/releases/tag/v324.24.1
• Pulled in by: https://github.com/mapbox/mapbox-maps-ios/releases/tag/v11.24.1 and
  https://github.com/mapbox/mapbox-navigation-ios/releases/tag/v3.24.1
• Related broken release one cycle earlier: mapbox-maps-ios 11.24.0-rc.1 / native 324.24.0-rc.1 failed differently
  (Image(uiImage:) source-vs-binary mismatch in core-maps).

Compare MapboxNavigationNative_Internal.h and module.private.modulemap in the 324.24.1 framework with the 324.23.0 release, focusing on the three omitted PrivateHeaders files. Reproduce with the provided xcodebuild and pinned SPM versions; done means the explicit-module precompile succeeds for both simulator architectures without umbrella-header diagnostics.