feat(ios): .onOpenURL handler for pi-remote:// deep-link pairing (sim convenience)

Adds App-level .onOpenURL that parses pi-remote:// URLs and calls
PairingService.exchange directly. Useful in the simulator where the
QR scanner isn't available.

Also documents the iPhone 12 mini simulator UUID + deep-link workflow
in BUILD.md.

Sources/App/piRemoteApp.swift

@@ -1,10 +1,12 @@
 import SwiftUI
+import UIKit
 import UserNotifications
 
 @main
 struct piRemoteApp: App {
     @StateObject private var appState = AppState.shared
     @StateObject private var notificationDelegate = NotificationDelegate.shared
+    private let pairingService = PairingService()
 
     var body: some Scene {
         WindowGroup {
@@ -14,6 +16,29 @@ struct piRemoteApp: App {
                     notificationDelegate.setup()
                     UIApplication.shared.registerForRemoteNotifications()
                 }
+                .onOpenURL { url in
+                    handlePairingURL(url)
+                }
+        }
+    }
+
+    /// Handle `pi-remote://...` deep links — dev / simulator convenience pairing.
+    private func handlePairingURL(_ url: URL) {
+        guard let parsed = try? PairingService.parseQR(url.absoluteString) else { return }
+        Task { @MainActor in
+            do {
+                let credential = try await pairingService.exchange(
+                    host: parsed.host,
+                    port: parsed.port,
+                    pairingToken: parsed.pairingToken,
+                    fingerprint: parsed.fingerprint,
+                    name: parsed.name,
+                    deviceName: UIDevice.current.name
+                )
+                appState.didPair(credential: credential)
+            } catch {
+                print("[pairing] deep-link exchange failed: \(error)")
+            }
         }
     }
 }

docs/BUILD.md

@@ -119,11 +119,33 @@ Direct CLI deploy works via `xcrun devicectl`.
 
 ## Simulator (for UI dev without device)
 
+**Preferred simulator: iPhone 12 mini (matches the physical test device).**
+Sim UUID: `062F8F0A-B3E5-4A4B-BC8A-B01E98CF27F2`
+
 ```bash
-# iPhone 16 Pro simulator
+SIM=062F8F0A-B3E5-4A4B-BC8A-B01E98CF27F2
+xcrun simctl boot $SIM
+open -a Simulator
+
 xcodebuild build \
   -project piRemote.xcodeproj \
   -scheme piRemote \
-  -destination "platform=iOS Simulator,id=C147BAB0-6644-477E-8E9E-77E7D5D5092B" \
+  -destination "platform=iOS Simulator,id=$SIM" \
   CODE_SIGNING_ALLOWED=NO
+
+APP=$(find ~/Library/Developer/Xcode/DerivedData/piRemote-*/Build/Products/Debug-iphonesimulator -name "piRemote.app" -maxdepth 1 | head -1)
+xcrun simctl install $SIM "$APP"
+xcrun simctl launch $SIM de.vpsj.pi-remote
+```
+
+### Deep-link pairing in simulator
+
+The app handles `pi-remote://` URLs via `.onOpenURL` for dev convenience:
+
+```bash
+PAIR_URL=$(curl -s "http://10.13.37.2:17373/pair-qr?token=$TOKEN&format=url" | grep -oE 'pi-remote://[^[:space:]]+' | head -1)
+xcrun simctl openurl $SIM "$PAIR_URL"
+# Tap "Open" in the iOS confirm dialog — use cliclick to script it:
+# (window content rect: pos (591,124), size (323,700))
+cliclick c:778,495   # Open button on iPhone 12 mini
 ```