CarPlay prototypes¶
CarPlay prototypes are not supported (#14934, epic #14924). The iOS
prototype agent draws only on the phone screen: it adds a SwiftUI window
inside the target app’s process, which CarPlay never shows, and it refuses a display selector. No
CarPlay-specific nodes exist in the spec.
A CarPlay app mostly cannot draw custom UI. The system renders Apple’s templates (CPListTemplate,
CPGridTemplate, CPTabBarTemplate, now playing and so on) out of process; only some categories,
such as the navigation map base view, get a custom window. Any CarPlay prototype needs a different
rendering path.
CarPlay screen power helper¶
ios/carplay-power (carplay-power-helper <udid> status|power-on) reports a booted simulator’s
screens, or makes its TVOut screen the CarPlay car display. It checks private CoreSimulator
selectors, waits for callbacks, and re-enumerates to verify power state; unavailable APIs produce
actionable errors.
power-onwrites a StarkConfig to<device data>/Library/Application Support/Simulator/extended_display.plist(800x480 @2x,starkandhasTouchScreentrue, the otherhas*keys false), then sets TVOut’s mode with theHasTouchScreenandStarkCarPlay properties. That powers TVOut on; backboardd makes it the car display and CarPlay’s home screen renders within about 2 s.- Both steps are required. CoreSimulator resets the plist to
{"stark":0}on every boot, so runpower-onafter each boot. Running it again on a projecting screen is harmless. power-onrefuses iOS 27 and later runtimes withunsupported-runtime: Apple does not support CarPlay on that simulator.statusworks on any runtime.- The TypeScript bridge is injectable and uses
AUTOMOBILE_CARPLAY_POWER_HELPER_PATH. Its JSON lists every screen and acarPlayobject for TVOut:found, nullablescreenIDandpowerState. - Capture the car display with
xcrun simctl io <udid> screenshot --display=TVOut. Touch input on it is not supported (#18730).
Projection readiness contract¶
ios/carplay-projection-probe is an arm64 iOS 26.0+ simulator executable, run inside the selected
simulator with xcrun simctl spawn <udid> <absolute-probe-path>. Build and ad-hoc sign it with
bash ios/carplay-projection-probe/build.sh [output-path]; set
AUTOMOBILE_CARPLAY_PROJECTION_PROBE_PATH to the result.
- It enumerates
+[CADisplay displays]and reports one display, preferred in this order: Car tag, CarInstruments tag, AirPlay tag, the display namedTVOut, the display whosedeviceNameiswireless0. On iOS 26.x the car display is TVOut (deviceNamePurpleTVOut) and the Wireless display’sdeviceNameis a UUID. - It reads
tag,displayTypeanddisplayIdthrough typedobjc_msgSendcasts, andnameanddeviceNameas strings. It never constructsFBSDisplayConfiguration: initializing one for a powered-off, tag-zero display can segfault. - Unavailable selectors fail on stderr with a nonzero exit; no matching display is a successful
found: false. - It arms
alarm(10)on start. The host’s 15 s timeout killsxcrun, which does not necessarily end the process spawned inside the simulator; the alarm bounds it either way. scripts/ios/swift-build.shbuilds it in the macOS Swift CI job when the iphonesimulator SDK is 26 or later. A unit test checks that both JSON branches inprobe.mcarry exactly the schema’s keys. Running it needs a booted simulator, so CI does not execute it.
Output is one JSON line: found, nullable tag, displayId, displayType, identity, name and
deviceName, and boolean isCarDisplay / isCarInstrumentsDisplay. Missing displays have null
metadata and false flags. Car is bit 0x20; instruments is bit 0x40; both flags are computed
independently. Identity is seed-free, chosen in priority order: Car[id], CarInstruments[id],
AirPlay[id] (bit 0x4), Untagged[id] (tag zero), then Tag0x<hex>[id]. name is the value
simctl io --display accepts.
carPlayProjection.ts validates the strict JSON over the injectable exec seam with a 15 s timeout.
requireCarPlayProjection probes and refuses capture unless either Car flag is true. Its error
names the screen and identity, explains the black frame and gives the recovery step. Attachment and power-on alone are not
enough: TVOut stays untagged without the StarkConfig. A positive tag is a readiness signal, not
verification of a captured image. No observe display selector uses this module yet.