[Watch] 1 - Set up watch app

[KacperKozak]

What to build

Build a reproducibly generated native watchOS target and a minimal live Board telemetry readout fed directly by the existing native iOS session. Resolve the runtime mechanism through measured Series 6 behavior before the remaining port assumes wrist-down parity.

Source: docs/watchos.md and the approved watchOS parity plan. Execution: HITL for physical-device verification; implementation is agent-owned.

Project setup included

• Create a native SwiftUI watch app under watch/watchos/, with its own entry point, assets, bundle identifier and watchOS deployment target supporting Series 6.
• Add a reproducible Expo config plugin, registered in app.config.ts, to generate the watch target inside the existing iOS Xcode project. Configure target dependencies, build schemes and embedding in the iPhone app. Repeated prebuilds must not duplicate targets.
• Wire development/release app variants, companion identifiers, version/build numbers, signing team and required capabilities. Keep credentials and machine configuration outside source.
• Configure the phone and watch WatchConnectivity endpoints, then prove the complete native telemetry path in the minimal watch UI.
• Document simulator build/run and physical paired-watch installation. Verify a release archive includes the watch app for eventual TestFlight/App Store delivery; publishing is not part of this ticket.

Likely files

• app.config.ts — existing Expo plugin registration, iOS identifiers, version and signing configuration.

• src/config/appVariant.ts — development/release application identity.

• plugins/withWearMirror.ts — existing settings or native-target integration reference.

• modules/vescape-core/ios/connection/BoardSessionController.swift — existing native iOS integration or test starting point.

• modules/vescape-core/ios/location/GpsMonitor.swift — existing native iOS integration or test starting point.

• modules/vescape-core/android/src/main/java/expo/modules/vescapecore/watch/WatchFrame.kt — existing Android phone-side parity peer.

• modules/vescape-core/android/src/main/java/expo/modules/vescapecore/watch/WatchTick.kt — existing Android phone-side parity peer.

Implementation hints

Read current Android code, not historical alert-forwarding docs. Keep native phone truth and actions in vescape-core; do not make live wrist behavior depend on JS. Add bidirectional @parity links for equivalent contracts/logic and document verified platform differences in docs/watchos.md. New durable watch source belongs under watch/watchos/, not generated ios/. The local planning document will be included in the draft watchOS feature PR; this issue includes its relevant requirements independently.

Acceptance criteria

• Clean and repeated prebuilds recreate exactly one correctly configured watch target from durable source and plugin inputs.
• Both app variants have correct companion/bundle identifiers, signing configuration and versions; simulator build succeeds and the app installs on the paired Series 6.
• An iPhone release archive contains the watch app; document the build and installation steps and any external signing blockers without claiming unperformed verification.
• Real changing frame timestamps reach the wrist with the iPhone locked; test raised/lowered wrist, active/no route, moving/stationary, loss and restoration of connectivity.
• Record lifecycle state, frame age, received/rendered cadence and permission-denied behavior in docs/watchos.md. Simulator rendering is not evidence of background execution.
• Use supported execution for actual app behavior. If no mechanism meets the requirement, document evidence and leave this slice blocked rather than accepting wrist-up-only behavior.

Blocked by

None — can start immediately

Related

• [Watch] 2 - Adapt gauges and navigation #485
• [Watch] 3 - Mirror watch settings #486
• [Watch] 4 - Mirror route navigation #487
• [Watch] 5 - Mirror weather and radar #488
• [Watch] 6 - Control Board lights #489
• [Watch] 7 - Control Board Move #490
• [Watch] 8 - Complete diagnostics and ride validation #491
• [Watch] 9 - Prepare App Store shipping #493

[KacperKozak]

Implemented in 6cfe484 + 6a1816f on watchos. Left open: the device-measured criteria below have not been performed.

Done and verified on this machine (unsigned builds):

• Watch target generated from watch/watchos/ by @bacons/apple-targets (type: watch), one registration in app.config.ts covering both targets/* and watch/watchos. Repeated prebuilds update the one target — verified, no duplication.
• Both variants: app.vescape.dev.watchkitapp / app.vescape.watchkitapp, companion id and version inherited from the phone target.
• VescapeWatch builds against watchsimulator26.5; the iPhone app builds Debug (simulator) and Release (generic device), both embedding Watch/VescapeWatch.app. Watch binary is arm64_32+arm64, so Series 6 is covered.
• Native frame path in vescape-core: WatchFrame / WatchTick / WatchTelemetryPusher (WCSession.sendMessageData), started at process launch. 13 new Swift tests.
• Wrist readout shows the lifecycle instrumentation: activation state, reachability, frame age, rx Hz, drawn Hz.

Not performed — needs the paired Series 6:

• Install on the watch; changing frame timestamps with the iPhone locked.
• Raised/lowered wrist, active/no route, moving/stationary, connectivity loss and restoration.
• Measured cadence and permission-denied behavior recorded in docs/watchos.md.
• The last criterion's decision (supported execution vs. leaving the slice blocked) turns on those readings.

Also not performed: an actual release archive/export — no signing credentials here. The Release device product does embed the watch app, which is as far as that goes without them.

Machine setup note: xcodebuild -downloadPlatform watchOS is now required. Without the simulator runtime Xcode refuses the iPhone scheme entirely, so bun run ios fails on a machine that has never done watchOS work.