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

[critchha]

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).

[critchha]

Reproduced on v324.24.2 / 11.24.2 / 3.24.2 (2026-05-22 device-clean build).

Mapbox cut v324.24.2 binaries on 2026-05-20 and shipped mapbox-navigation-ios v3.24.2 on 2026-05-21 pinning MapboxMaps
11.24.2 + MapboxNavigationNative 324.24.2. Clean SPM resolve + clean DerivedData rebuild against those pins
reproduces the same umbrella-header defect originally reported here, with identical diagnostics:

MapboxNavigationNative.framework/PrivateHeaders/MapboxNavigationNative_Internal.h:44:1:
error: umbrella header for module 'MapboxNavigationNative_Private'
does not include header 'MapboxDirectionsRoute_Internal.h'
does not include header 'MBDRouteDirectionsRouteResponse_Internal.h'
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 43-line umbrella header in the v324.24.2 framework is byte-identical to the v324.24.1 version — same three omitted
#import lines, same three header files physically present in PrivateHeaders/. The 2026-05-20 binary re-cut did not
re-run umbrella generation against the actual PrivateHeaders/ directory contents. The packaging defect is
forward-carried unchanged.

A second, distinct packaging defect is also present in this release line: nav-ios v3.24.2's Package.swift declares the
_MapboxNavigationTestKit target with path: "Sources/.empty/_MapboxNavigationTestKit", a directory that does not exist
in the source tree. SwiftPM rejects this with invalid custom path … and resolution fails before xcframeworks can be
extracted. Filed separately as mapbox/mapbox-maps-ios#2422.

The net effect: the warm-start CarPlay blank-map fix introduced by commit 5478f158a4 in 11.24.0-rc.1 (the actual fix
many of us are waiting for — see https://github.com/mapbox/mapbox-maps-ios/blob/v11.24.2/CHANGELOG.md, "Fix MapView
rendering blank when attached to an already-active CarPlay scene") remains unreachable by any consumer running Xcode
16+ with strict explicit modules. The fix exists in the binary; it's the framework packaging that's blocking adoption.

Asking for explicit acknowledgement that this is a known regression in the release-prep tooling, plus an ETA for an
11.24.x (or 11.25.x) release where both this issue and the TestKit path issue are addressed. Happy to test pre-release
binaries if a private cut would help validate.