CarPlay: implement the navigation metadata channel (mapTemplateShouldProvideNavigationMetadata / rich CPManeuver fields / CPLaneGuidance) for OEM instrument-cluster rendering

[guardianai-uae]

Feature request

The SDK's CarPlay integration (CarPlayManager / CarPlayNavigationViewController) populates CPNavigationSession maneuvers with instructionVariants, symbolSet, and travel estimates — which fully drives the main-scene guidance panel. However, it never opts into CarPlay's navigation metadata channel:

• CPMapTemplateDelegate.mapTemplateShouldProvideNavigationMetadata(_:) is not implemented (defaults to false)
• CPManeuver.maneuverType, .junctionType, .trafficSide, .state (initial → prepare → execute progression) are never set
• CPNavigationSession.add(laneGuidances:) / CPLaneGuidance are never used

Per Apple's CarPlay Developer Guide (June 2026 edition, pp. 55–58), this metadata is what vehicles with digital instrument clusters and HUDs use to natively render maneuvers, junction-aware iconography, and lane guidance — including vehicles that do not support app-window cluster scenes at all. Without it, CarPlay in metadata-capable vehicles renders a degraded or absent cluster experience for SDK-based apps, while the SDK already computes every needed input (maneuver types/modifiers, Intersection lane data, junction geometry) for its own UI.

Verified absent in 3.16.1 through 3.29.0-alpha.3 (changelog + source grep: zero matches for mapTemplateShouldProvideNavigationMetadata, CPLaneGuidance, maneuverType in the CarPlay integration).

Proposed shape

• CarPlayManager (as CPMapTemplateDelegate) returns true from mapTemplateShouldProvideNavigationMetadata (opt-in via a CarPlayManagerDelegate hook or config flag for backward compatibility)
• CarPlayNavigationViewController's maneuver construction (the same path that sets instructionVariants/symbolSet) additionally maps: MapboxDirections ManeuverType/ManeuverDirection → CPManeuver.maneuverType + .junctionType; drive-side from the route's region → .trafficSide; step progress thresholds → .state
• Intersection.approachLanes/usableApproachLanes/usableLaneIndication → CPLaneGuidance/CPLane, added via CPNavigationSession.add(laneGuidances:) and referenced from the maneuvers

Context

We (Guardian AI, UAE/Pakistan telematics + navigation) ship CarPlay on SDK 3.x and have implemented the app-window instrument-cluster scene; the metadata channel is the remaining gap for metadata-driven clusters. Happy to contribute the mapping tables as a PR if maintainers are open to it — the enum mapping (Mapbox maneuver types/modifiers → CPManeuver types/junctions) is the main review surface.

[guardianai-uae]

Follow-up with concrete findings from attempting an app-side interim implementation against v3.27.1:

There is currently no public seam for an app to perform the enrichment itself: CarPlayNavigationViewController.carSession and .mapTemplate are internal; updateManeuvers() (where CPManeuvers are constructed) is internal; startNavigationSession(for:) is public but not open. The CPMapTemplateDelegate maneuver-bearing callbacks are implemented by CarPlayManager itself, so a forwarding proxy can't add enrichment without replacing SDK behavior.

We've built the full mapping layer app-side (exhaustive ManeuverType×ManeuverDirection → CPManeuverType/CPJunctionType tables, maneuver .state thresholds, Intersection → CPLaneGuidance conversion, all unit-tested) and it sits dark behind a flag pending either this feature landing upstream or a public seam (e.g. an open maneuver-construction hook or a CarPlayManagerDelegate willAdd-maneuvers callback). Happy to adapt our tables into a PR if maintainers indicate a preferred shape.