craft-native 0.0.247 → 0.0.249

package/dist/ios/src/index.d.ts

@@ -65,6 +65,8 @@ export interface CraftConfig {
     enableBluetooth?: boolean;
     enableNFC?: boolean;
     enableHealthKit?: boolean;
+    /** Native Apple Wallet pass presentation and lookup for native screens. */
+    enableWallet?: boolean;
     enableLiveActivities?: boolean;
     enableWatchApp?: boolean;
     enableBackgroundLocation?: boolean;

package/dist/ios/src/index.js

@@ -134,8 +134,8 @@ function initSimulatorDriver(options) {
   if (!["http:", "https:"].includes(new URL(control).protocol))
     throw new Error("controlUrl must use HTTP or HTTPS");
   const tabIdentifiers = Object.entries(options.tabIdentifiers ?? {});
-  for (const [name2, identifier] of tabIdentifiers) {
-    if (!name2.trim() || !identifier.trim())
+  for (const [name, identifier] of tabIdentifiers) {
+    if (!name.trim() || !identifier.trim())
       throw new Error("Tab names and native identifiers must be nonempty");
   }
   const replacements = {
@@ -145,7 +145,7 @@ function initSimulatorDriver(options) {
     BUNDLE_ID: swiftString(bundleId),
     CONTROL_URL: swiftString(control),
     TABS: `[${(options.tabs ?? []).map(swiftString).join(", ")}]`,
-    TAB_IDENTIFIERS: tabIdentifiers.length ? `[${tabIdentifiers.map(([name2, identifier]) => `${swiftString(name2)}: ${swiftString(identifier)}`).join(", ")}]` : "[:]"
+    TAB_IDENTIFIERS: tabIdentifiers.length ? `[${tabIdentifiers.map(([name, identifier]) => `${swiftString(name)}: ${swiftString(identifier)}`).join(", ")}]` : "[:]"
   };
   for (const [source, destination] of [
     ["HostApp.swift", "Host/HostApp.swift"],
@@ -547,6 +547,7 @@ var DEFAULT_CONFIG = {
   enableBluetooth: false,
   enableNFC: false,
   enableHealthKit: false,
+  enableWallet: false,
   enableLiveActivities: false,
   enableWatchApp: false,
   enableBackgroundLocation: false,
@@ -1539,55 +1540,55 @@ async function run(options) {
   }
 }
 export {
-  usesNativeBundle,
-  syncWebAssets,
-  syncNativeFonts,
-  showSimulator,
-  serializeSimulatorSteps,
-  run,
-  restoreShell,
-  resolveRuntimeDir,
-  resolveCraftVersion,
-  resolveAppearance,
-  renderWatchEntitlements,
-  renderUsageDescriptions,
-  renderUrlTypes,
-  renderRuntimeSettings,
-  renderPrivacyManifest,
-  renderOrientations,
-  renderOfflinePage,
-  renderLaunchScreen,
-  renderFeatureSettings,
-  renderEntitlements,
-  renderDeviceFamilies,
-  renderBackgroundTaskIdentifiers,
-  renderBackgroundModes,
-  renderAppearance,
-  renderAppBoundDomains,
-  readableTextOn,
-  productName,
-  pngHasAlpha,
-  pickSimulator,
-  orderSimulators,
-  open,
-  normalizeNativePath,
-  nativeStartPath,
-  nativeRouteRuntime,
-  nativeRouteBundles,
-  nativeMessages,
-  matchNativePath,
-  isHybrid,
-  installRuntime,
-  initSimulatorDriver,
-  init,
-  hybridConfigProblems,
-  hasNativeRoutes,
-  findApplicationSwiftSources,
-  createNativeMutationValidator,
-  build,
-  bootSimulator,
-  backgroundRefreshIdentifier,
-  associatedDomainEntries,
+  LAUNCH_LOGO,
   assertNoApplicationSwiftSources,
-  LAUNCH_LOGO
+  associatedDomainEntries,
+  backgroundRefreshIdentifier,
+  bootSimulator,
+  build,
+  createNativeMutationValidator,
+  findApplicationSwiftSources,
+  hasNativeRoutes,
+  hybridConfigProblems,
+  init,
+  initSimulatorDriver,
+  installRuntime,
+  isHybrid,
+  matchNativePath,
+  nativeMessages,
+  nativeRouteBundles,
+  nativeRouteRuntime,
+  nativeStartPath,
+  normalizeNativePath,
+  open,
+  orderSimulators,
+  pickSimulator,
+  pngHasAlpha,
+  productName,
+  readableTextOn,
+  renderAppBoundDomains,
+  renderAppearance,
+  renderBackgroundModes,
+  renderBackgroundTaskIdentifiers,
+  renderDeviceFamilies,
+  renderEntitlements,
+  renderFeatureSettings,
+  renderLaunchScreen,
+  renderOfflinePage,
+  renderOrientations,
+  renderPrivacyManifest,
+  renderRuntimeSettings,
+  renderUrlTypes,
+  renderUsageDescriptions,
+  renderWatchEntitlements,
+  resolveAppearance,
+  resolveCraftVersion,
+  resolveRuntimeDir,
+  restoreShell,
+  run,
+  serializeSimulatorSteps,
+  showSimulator,
+  syncNativeFonts,
+  syncWebAssets,
+  usesNativeBundle
 };

package/dist/ios/templates/CraftApp.swift

@@ -648,6 +648,9 @@ final class CraftChrome: ObservableObject {
         var titleOverride: String? = nil
         var iconTint: String? = nil
         var iconPulse = false
+        /// The page's own symbol for the tab while it says so (a live
+        /// reading's filled heart), in place of the configured one.
+        var iconSymbol: String? = nil
         var selectedSymbol: String? = nil
         var selectedIconTint: String? = nil
         var selectedIconPulse: Bool? = nil
@@ -658,7 +661,7 @@ final class CraftChrome: ObservableObject {
         }
 
         func iconAppearance(selected: Bool, motionAllowed: Bool) -> (symbol: String, tint: String?, pulse: Bool) {
-            let name = selected ? selectedSymbol ?? symbol : symbol
+            let name = selected ? selectedSymbol ?? iconSymbol ?? symbol : iconSymbol ?? symbol
             let tint = selected ? selectedIconTint ?? iconTint : iconTint
             let pulse = selected ? selectedIconPulse ?? iconPulse : iconPulse
             return (name, tint, pulse && motionAllowed)
@@ -750,6 +753,9 @@ final class CraftChrome: ObservableObject {
         if item.keys.contains("iconPulse") {
             next.iconPulse = item["iconPulse"] as? Bool ?? false
         }
+        if item.keys.contains("symbol") {
+            next.iconSymbol = Tab.normalizedSelectedSymbol(item["symbol"] as? String)
+        }
         if item.keys.contains("selectedSymbol") {
             next.selectedSymbol = Tab.normalizedSelectedSymbol(item["selectedSymbol"] as? String)
         }
@@ -1574,6 +1580,8 @@ struct CraftConfig: Codable {
     var enableBluetooth: Bool = false
     var enableNFC: Bool = false
     var enableHealthKit: Bool = false
+    /// Apple Wallet pass presentation and lookup for native screens.
+    var enableWallet: Bool = false
     var enableLiveActivities: Bool = false
     var enableWatchApp: Bool = false
     var enableBackgroundLocation: Bool = false
@@ -2168,6 +2176,11 @@ struct CraftWebView: UIViewRepresentable {
                     self.sendToWeb("craftHealthHeartRate", data: detail)
                     return true
                 }
+                CraftHealth.shared.workoutSink = { [weak self] detail in
+                    guard let self else { return false }
+                    self.sendToWeb("craftHealthWorkout", data: detail)
+                    return true
+                }
             }
             if config.enableHeartRate {
                 // The strap's readings and connection changes reach the page,
@@ -3061,6 +3074,30 @@ struct CraftWebView: UIViewRepresentable {
                 } else {
                     rejectCallback(callbackId, error: "HealthKit is disabled", code: "CAPABILITY_DISABLED")
                 }
+            case "startHealthWorkout":
+                if config.enableHealthKit {
+                    CraftHealth.shared.startWorkout(body: body) { [weak self] in self?.answer(callbackId, $0) }
+                } else {
+                    rejectCallback(callbackId, error: "HealthKit is disabled", code: "CAPABILITY_DISABLED")
+                }
+            case "pauseHealthWorkout":
+                if config.enableHealthKit {
+                    CraftHealth.shared.pauseWorkout { [weak self] in self?.answer(callbackId, $0) }
+                } else {
+                    rejectCallback(callbackId, error: "HealthKit is disabled", code: "CAPABILITY_DISABLED")
+                }
+            case "resumeHealthWorkout":
+                if config.enableHealthKit {
+                    CraftHealth.shared.resumeWorkout { [weak self] in self?.answer(callbackId, $0) }
+                } else {
+                    rejectCallback(callbackId, error: "HealthKit is disabled", code: "CAPABILITY_DISABLED")
+                }
+            case "endHealthWorkout":
+                if config.enableHealthKit {
+                    CraftHealth.shared.endWorkout { [weak self] in self?.answer(callbackId, $0) }
+                } else {
+                    rejectCallback(callbackId, error: "HealthKit is disabled", code: "CAPABILITY_DISABLED")
+                }
 
             // MARK: - Live Activities
             case "isLiveActivityAvailable":
@@ -5648,7 +5685,11 @@ struct CraftWebView: UIViewRepresentable {
                         var since = options && typeof options.since === 'number' ? options.since : null;
                         return craft._invoke('startHealthHeartRateUpdates', {since: since});
                     },
-                    stopHeartRateUpdates: function() { return craft._invoke('stopHealthHeartRateUpdates'); }
+                    stopHeartRateUpdates: function() { return craft._invoke('stopHealthHeartRateUpdates'); },
+                    startWorkout: function(options) { return craft._invoke('startHealthWorkout', options || {}); },
+                    pauseWorkout: function() { return craft._invoke('pauseHealthWorkout'); },
+                    resumeWorkout: function() { return craft._invoke('resumeHealthWorkout'); },
+                    endWorkout: function() { return craft._invoke('endHealthWorkout'); }
                 };
                 // The Music app's song and transport. Nothing is read until
                 // requestAuthorization() has been allowed; observe(true) makes
@@ -9340,7 +9381,7 @@ final class CraftZigRuntime: NSObject {
 enum CraftWebServices {
     private static var waiting: [String: (Result<Any, CraftNativeActionError>) -> Void] = [:]
     /// Coordinator events a native screen hears too.
-    static let forwardedEvents: Set<String> = ["craftLocationUpdate", "craftLocationError", "craftHealthHeartRate", "craftMusicChange", "craftHeartRate"]
+    static let forwardedEvents: Set<String> = ["craftLocationUpdate", "craftLocationError", "craftHealthHeartRate", "craftHealthWorkout", "craftMusicChange", "craftHeartRate"]
     static let event = Notification.Name("craftWebServicesEvent")
 
     static var isAvailable: Bool { CraftSwiftShim.coordinator != nil }

package/dist/ios/templates/CraftHealth.swift

@@ -9,6 +9,40 @@ struct CraftHealthError: Error {
     var code: String = "CRAFT_ERROR"
 }
 
+/// A separate delegate keeps the iOS 17+ HealthKit session types out of the
+/// iOS 16-compatible CraftHealth declaration. The owning service retains it
+/// for the lifetime of the session.
+@available(iOS 17.0, *)
+private final class CraftHealthWorkoutDelegate: NSObject, HKWorkoutSessionDelegate {
+    private let id: () -> String
+    private let emit: ([String: Any]) -> Void
+
+    init(id: @escaping () -> String, emit: @escaping ([String: Any]) -> Void) {
+        self.id = id
+        self.emit = emit
+    }
+
+    func workoutSession(_ workoutSession: HKWorkoutSession, didChangeTo toState: HKWorkoutSessionState, from fromState: HKWorkoutSessionState, date: Date) {
+        emit(["id": id(), "event": "state", "state": Self.stateName(toState), "date": date.timeIntervalSince1970 * 1000])
+    }
+
+    func workoutSession(_ workoutSession: HKWorkoutSession, didFailWithError error: Error) {
+        emit(["id": id(), "event": "error", "message": error.localizedDescription])
+    }
+
+    private static func stateName(_ state: HKWorkoutSessionState) -> String {
+        switch state {
+        case .notStarted: return "notStarted"
+        case .prepared: return "prepared"
+        case .running: return "running"
+        case .paused: return "paused"
+        case .stopped: return "stopped"
+        case .ended: return "ended"
+        @unknown default: return "unknown"
+        }
+    }
+}
+
 /// Apple Health for the whole app: the web page's bridge (`craft.health` in
 /// the hybrid's web view, CraftApp.swift) and native screens alike
 /// (`Health` through CraftNativeActions), so a screen drawn natively reads
@@ -69,6 +103,14 @@ final class CraftHealth {
             startHeartRateUpdates(since: options(0)["since"] as? Double, completion: completion)
         case "stopHeartRateUpdates":
             stopHeartRateUpdates(completion: completion)
+        case "startWorkout":
+            startWorkout(body: options(0), completion: completion)
+        case "pauseWorkout":
+            pauseWorkout(completion: completion)
+        case "resumeWorkout":
+            resumeWorkout(completion: completion)
+        case "endWorkout":
+            endWorkout(completion: completion)
         default:
             completion(.failure(CraftHealthError(message: "Unsupported Health method", code: "UNKNOWN_ACTION")))
         }
@@ -745,6 +787,166 @@ final class CraftHealth {
         healthStore.execute(query)
     }
 
+    // MARK: Live workout sessions
+
+    /// Starts an OS-owned workout session. HealthKit's live builder was
+    /// introduced for iOS 26; older systems receive a clear unsupported
+    /// result instead of silently recording a post-hoc workout.
+    func startWorkout(body: [String: Any], completion rawCompletion: @escaping Completion) {
+        let completion = completeOnMain(rawCompletion)
+        guard let type = body["type"] as? String, !type.isEmpty else {
+            completion(.failure(CraftHealthError(message: "startWorkout needs a workout type", code: "INVALID_ARGUMENT")))
+            return
+        }
+        guard healthStore != nil else {
+            completion(.failure(CraftHealthError(message: "HealthKit not available")))
+            return
+        }
+        guard liveWorkoutID == nil else {
+            completion(.failure(CraftHealthError(message: "A live workout is already running", code: "WORKOUT_IN_PROGRESS")))
+            return
+        }
+        guard #available(iOS 26.0, *) else {
+            completion(.failure(CraftHealthError(message: "Live workouts require iOS 26 or later", code: "UNSUPPORTED")))
+            return
+        }
+        startWorkout26(type: type, location: body["location"] as? String, completion: completion)
+    }
+
+    @available(iOS 26.0, *)
+    private func startWorkout26(type: String, location: String?, completion: @escaping Completion) {
+        guard let healthStore else {
+            completion(.failure(CraftHealthError(message: "HealthKit not available")))
+            return
+        }
+        guard let activity = Self.workoutActivity(type) else {
+            completion(.failure(CraftHealthError(message: "Unsupported workout type", code: "INVALID_ARGUMENT")))
+            return
+        }
+        let configuration = HKWorkoutConfiguration()
+        configuration.activityType = activity
+        switch location {
+        case "indoor": configuration.locationType = .indoor
+        case "outdoor": configuration.locationType = .outdoor
+        case nil, "unknown": configuration.locationType = .unknown
+        default:
+            completion(.failure(CraftHealthError(message: "location must be indoor, outdoor, or unknown", code: "INVALID_ARGUMENT")))
+            return
+        }
+        do {
+            let session = try HKWorkoutSession(healthStore: healthStore, configuration: configuration)
+            let builder = session.associatedWorkoutBuilder()
+            let delegate = CraftHealthWorkoutDelegate(id: { [weak self] in self?.liveWorkoutID ?? "" }) { [weak self] detail in self?.sendWorkout(detail) }
+            session.delegate = delegate
+            builder.shouldCollectWorkoutEvents = true
+            builder.dataSource = HKLiveWorkoutDataSource(healthStore: healthStore, workoutConfiguration: configuration)
+            liveWorkoutSession = session
+            liveWorkoutBuilder = builder
+            liveWorkoutDelegate = delegate
+            liveWorkoutID = UUID().uuidString.lowercased()
+            liveWorkoutType = type
+            liveWorkoutStart = Date()
+            let id = liveWorkoutID!
+            let start = liveWorkoutStart!
+            session.startActivity(with: start)
+            builder.beginCollection(withStart: start) { [weak self] success, error in
+                DispatchQueue.main.async {
+                    guard let self else { return }
+                    guard success else {
+                        self.clearLiveWorkout()
+                        completion(.failure(CraftHealthError(message: error?.localizedDescription ?? "Live workout could not start")))
+                        return
+                    }
+                    completion(.success(["id": id, "type": type, "startDate": start.timeIntervalSince1970 * 1000]))
+                }
+            }
+        } catch {
+            clearLiveWorkout()
+            completion(.failure(CraftHealthError(message: error.localizedDescription, code: "INVALID_ARGUMENT")))
+        }
+    }
+
+    func pauseWorkout(completion rawCompletion: @escaping Completion) {
+        let completion = completeOnMain(rawCompletion)
+        guard #available(iOS 26.0, *), let session = liveWorkoutSession as? HKWorkoutSession else {
+            completion(.failure(CraftHealthError(message: "No live workout is running", code: "NO_WORKOUT")))
+            return
+        }
+        session.pause()
+        completion(.success(true))
+    }
+
+    func resumeWorkout(completion rawCompletion: @escaping Completion) {
+        let completion = completeOnMain(rawCompletion)
+        guard #available(iOS 26.0, *), let session = liveWorkoutSession as? HKWorkoutSession else {
+            completion(.failure(CraftHealthError(message: "No live workout is running", code: "NO_WORKOUT")))
+            return
+        }
+        session.resume()
+        completion(.success(true))
+    }
+
+    func endWorkout(completion rawCompletion: @escaping Completion) {
+        let completion = completeOnMain(rawCompletion)
+        guard #available(iOS 26.0, *), let session = liveWorkoutSession as? HKWorkoutSession, let builder = liveWorkoutBuilder as? HKLiveWorkoutBuilder, let id = liveWorkoutID else {
+            completion(.failure(CraftHealthError(message: "No live workout is running", code: "NO_WORKOUT")))
+            return
+        }
+        let end = Date()
+        session.end()
+        builder.endCollection(withEnd: end) { [weak self] success, error in
+            guard let self else { return }
+            guard success else {
+                DispatchQueue.main.async { completion(.failure(CraftHealthError(message: error?.localizedDescription ?? "Live workout could not end"))) }
+                return
+            }
+            builder.finishWorkout { [weak self] workout, finishError in
+                DispatchQueue.main.async {
+                    guard let self else { return }
+                    defer { self.clearLiveWorkout() }
+                    guard let workout else {
+                        completion(.failure(CraftHealthError(message: finishError?.localizedDescription ?? "Live workout could not be saved")))
+                        return
+                    }
+                    completion(.success([
+                        "id": id,
+                        "workoutId": workout.uuid.uuidString,
+                        "endDate": end.timeIntervalSince1970 * 1000,
+                        "durationSeconds": workout.duration,
+                    ]))
+                }
+            }
+        }
+    }
+
+    private func clearLiveWorkout() {
+        liveWorkoutSession = nil
+        liveWorkoutBuilder = nil
+        liveWorkoutDelegate = nil
+        liveWorkoutID = nil
+        liveWorkoutType = nil
+        liveWorkoutStart = nil
+    }
+
+    private static func workoutActivity(_ type: String) -> HKWorkoutActivityType? {
+        switch type {
+        case "running": return .running
+        case "walking": return .walking
+        case "hiking": return .hiking
+        case "cycling": return .cycling
+        case "swimming": return .swimming
+        case "rowing": return .rowing
+        case "elliptical": return .elliptical
+        case "strength": return .traditionalStrengthTraining
+        case "hiit": return .highIntensityIntervalTraining
+        default: return nil
+        }
+    }
+
+    private func sendWorkout(_ detail: [String: Any]) {
+        if workoutSink?(detail) != true { CraftWebServices.forward("craftHealthWorkout", data: detail) }
+    }
+
     // MARK: Heart rate as it arrives
 
     /// The web view's coordinator, which sends `craftHealthHeartRate` to the
@@ -752,6 +954,21 @@ final class CraftHealth {
     /// view) and the event goes to the native screens alone.
     var pageSink: (([String: Any]) -> Bool)?
 
+    /// Live workout lifecycle events use a separate page event so existing
+    /// heart-rate listeners remain unchanged. When no page owns the event,
+    /// CraftWebServices forwards it to native screens.
+    var workoutSink: (([String: Any]) -> Bool)?
+
+    // Stored as object references because the generated app still supports
+    // iOS 16.2; concrete HealthKit types are only touched behind the iOS 26
+    // availability checks below.
+    private var liveWorkoutSession: AnyObject?
+    private var liveWorkoutBuilder: AnyObject?
+    private var liveWorkoutDelegate: AnyObject?
+    private var liveWorkoutID: String?
+    private var liveWorkoutType: String?
+    private var liveWorkoutStart: Date?
+
     /// The one running stream: an anchored query that hears every heart-rate
     /// sample HealthKit receives after it starts.
     private var heartRateQuery: HKAnchoredObjectQuery?

package/dist/ios/templates/CraftHeartRate.swift

@@ -235,7 +235,7 @@ final class CraftHeartRate: NSObject, CBCentralManagerDelegate, CBPeripheralDele
                     }
                     if var archived = try CraftRecordingArchive.read(self.directory, "heart-rate", id) {
                         if method == "readRecording" {
-                            let since = (options["since"] as? NSNumber)?.doubleValue
+                            let since = craftNativeNumber(options["since"]).map { $0.doubleValue }.flatMap { $0.isFinite ? $0 : nil }
                             let samples = archived["samples"] as? [[String: Any]] ?? []
                             return completion(.success(samples.filter { since == nil || (($0["timestamp"] as? NSNumber)?.doubleValue ?? 0) > since! }))
                         }
@@ -256,7 +256,7 @@ final class CraftHeartRate: NSObject, CBCentralManagerDelegate, CBPeripheralDele
                 self.recoverQuietBroadcast()
                 completion(.success(self.state()))
             case "requestAuthorization": self.requestAuthorization(completion: completion)
-            case "scan": self.scan(seconds: (options["timeout"] as? NSNumber)?.doubleValue, completion: completion)
+            case "scan": self.scan(seconds: craftNativeNumber(options["timeout"]).map { $0.doubleValue }.flatMap { $0.isFinite ? $0 : nil }, completion: completion)
             case "stopScan":
                 self.stopScan()
                 completion(.success(self.state()))
@@ -270,7 +270,10 @@ final class CraftHeartRate: NSObject, CBCentralManagerDelegate, CBPeripheralDele
             case "stopRecording": self.stopRecording(completion: completion)
             case "getRecordingState": completion(.success(self.recordingSummary(count: true)))
             case "readRecording":
-                do { completion(.success(try self.persistedSamples(since: (options["since"] as? NSNumber)?.doubleValue))) }
+                do {
+                    let since = craftNativeNumber(options["since"]).map { $0.doubleValue }.flatMap { $0.isFinite ? $0 : nil }
+                    completion(.success(try self.persistedSamples(since: since)))
+                }
                 catch { completion(.failure(CraftHeartRateError(message: "Unable to read the recording", code: "RECORDING_STORAGE_ERROR"))) }
             default: completion(.failure(CraftHeartRateError(message: "Unsupported HeartRate method", code: "UNKNOWN_ACTION")))
             }

package/dist/ios/templates/CraftHybrid.swift

@@ -264,8 +264,8 @@ protocol CraftHybridScreenEvents: AnyObject {
     func nativeScreenDidRender(_ screen: CraftNativeScreenController)
     /// The screen could not draw its first frame: no bundle, or its script threw.
     func nativeScreen(_ screen: CraftNativeScreenController, didFail message: String)
-    /// `craft.navigation.open(path)`.
-    func nativeScreen(_ screen: CraftNativeScreenController, open path: String)
+    /// `craft.navigation.open(path, props)`.
+    func nativeScreen(_ screen: CraftNativeScreenController, open path: String, props: [String: Any])
     /// `craft.navigation.replace(path)`: finish the current flow atomically.
     func nativeScreen(_ screen: CraftNativeScreenController, replace path: String)
 }
@@ -446,11 +446,11 @@ final class CraftHybrid: NSObject {
     /// A path or a web address opened by the app script or a single-stack
     /// screen: the shell opens it (holding it until the shell exists); an app
     /// with no shell opens a web address in the in-app browser.
-    func open(_ path: String) {
+    func open(_ path: String, props: [String: Any] = [:]) {
         if let controller {
-            controller.open(path)
+            controller.open(path, props: props)
         } else if isEnabled {
-            untilShell.append { $0.open(path) }
+            untilShell.append { $0.open(path, props: props) }
         } else {
             openOutside(path)
         }
@@ -976,8 +976,8 @@ extension CraftHybrid: CraftHybridScreenEvents {
         DispatchQueue.main.async { self.startAppScript() }
     }
 
-    func nativeScreen(_ screen: CraftNativeScreenController, open path: String) {
-        open(path)
+    func nativeScreen(_ screen: CraftNativeScreenController, open path: String, props: [String: Any]) {
+        open(path, props: props)
     }
 
     func nativeScreen(_ screen: CraftNativeScreenController, replace path: String) {
@@ -1249,8 +1249,7 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
             // create a second web root here: the shared WebView cannot draw
             // both pages during the same gesture.
             guard hybrid.routes.match(id) != nil else { return false }
-            target = CraftFramePacing.shared.measure("tab swipe mount \(id)") { makeStack(tab: id, rootPath: id) }
-            (target.topViewController as? CraftNativeScreenController)?.screenVisibilityChanged(false)
+            target = CraftFramePacing.shared.measure("tab swipe mount \(id)") { makeStack(tab: id, rootPath: id, hidden: true) }
         }
         guard current.view !== target.view,
               !(current.topViewController is CraftHybridWebSlot && target.topViewController is CraftHybridWebSlot),
@@ -1546,6 +1545,12 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
 
     private var visibleStack: UINavigationController? { stacks[currentTab] }
 
+    /// A swipe preview can be visible without owning navigation or focus.
+    /// UIKit appearance callbacks must follow the committed native stack.
+    func isFocusedScreen(_ screen: CraftNativeScreenController) -> Bool {
+        visibleStack?.topViewController === screen
+    }
+
     var webIsVisible: Bool {
         guard let webHost, let slot = visibleStack?.topViewController as? CraftHybridWebSlot else { return false }
         return webHost.view.superview === slot.view
@@ -1557,7 +1562,11 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
     /// the view hierarchy, so its screen never takes the shell's chrome (the
     /// bar, the tab accessory) from the one on screen.
     private func makeStack(tab: String, rootPath: String, hidden: Bool = false) -> UINavigationController {
-        let nav = UINavigationController(rootViewController: entry(for: rootPath, isTabRoot: true, depth: nil))
+        let root = entry(for: rootPath, isTabRoot: true, depth: nil)
+        // Constructing the navigation controller can load the root's view and
+        // mount its script immediately. Set its initial focus before that.
+        if hidden { (root as? CraftNativeScreenController)?.screenVisibilityChanged(false) }
+        let nav = UINavigationController(rootViewController: root)
         nav.delegate = self
         nav.view.backgroundColor = config.resolvedBackgroundColor
         nav.additionalSafeAreaInsets.bottom = safeAreaForTabBar()
@@ -1585,11 +1594,10 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
     }
 
     /// The entry for a path: its native screen, or a web entry.
-    private func entry(for path: String, isTabRoot: Bool, depth: Int?, params extra: [String: Any] = [:]) -> UIViewController {
+    private func entry(for path: String, isTabRoot: Bool, depth: Int?, props: [String: Any] = [:]) -> UIViewController {
         if hybrid.isEnabled, let match = hybrid.routes.match(path) {
-            var params = self.params(for: path, match)
-            extra.forEach { params[$0.key] = $0.value }
-            let screen = CraftNativeScreenController(config: config, routeName: match.screen, routeParams: params)
+            let params = self.params(for: path, match)
+            let screen = CraftNativeScreenController(config: config, routeName: match.screen, routeParams: params, routeProps: props)
             screen.hybridEvents = self
             nativePaths[ObjectIdentifier(screen)] = match.path
             return screen
@@ -1734,7 +1742,7 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
     /// an app with no web view, a path no screen draws opens in the in-app
     /// browser on the app's site. A web address on the app's site is its
     /// path; one anywhere else opens in the in-app browser.
-    func open(_ raw: String) {
+    func open(_ raw: String, props: [String: Any] = [:]) {
         if let url = URL(string: raw), let scheme = url.scheme?.lowercased(), scheme == "http" || scheme == "https" {
             guard CraftHybridRoutes.isSite(url, site: hybrid.siteURL) else {
                 hybrid.openOutside(raw)
@@ -1749,7 +1757,7 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
             return
         }
         if hybrid.routes.match(raw) != nil {
-            showNative(path: raw, replace: false)
+            showNative(path: raw, replace: false, props: props)
             return
         }
         if hybrid.hasWeb {
@@ -1769,7 +1777,7 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
 
     /// The native screen for `raw`: the one already in the stack (popping to
     /// it), a tab's root, or a new one pushed.
-    func showNative(path raw: String, replace: Bool, fromLink: Bool = false) {
+    func showNative(path raw: String, replace: Bool, fromLink: Bool = false, props: [String: Any] = [:]) {
         guard let match = hybrid.routes.match(raw) else { return }
         interruptTabSwipe(restoringSelection: true)
         let tabs = hybrid.tabIds
@@ -1785,7 +1793,7 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
                 nav.popToRootViewController(animated: !fromLink)
             }
             // `/m/store?coach=5`: the tab's own screen, with the query.
-            (stacks[tab]?.viewControllers.first as? CraftNativeScreenController)?.receiveRouteParams(params(for: raw, match))
+            (stacks[tab]?.viewControllers.first as? CraftNativeScreenController)?.receiveRouteParams(params(for: raw, match), props: props)
             return
         }
         if fromLink, let owner = CraftHybridRoutes.tab(owning: match.path, among: tabs), owner != currentTab {
@@ -1796,10 +1804,10 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
             if existing !== nav.topViewController { nav.popToViewController(existing, animated: true) }
             // Opened again, perhaps with another query (`?person=8`): the
             // screen hears the params it was opened with this time.
-            (existing as? CraftNativeScreenController)?.receiveRouteParams(params(for: raw, match))
+            (existing as? CraftNativeScreenController)?.receiveRouteParams(params(for: raw, match), props: props)
             return
         }
-        let screen = entry(for: raw, isTabRoot: false, depth: nil)
+        let screen = entry(for: raw, isTabRoot: false, depth: nil, props: props)
         let show = { [weak nav] in
             guard let nav else { return }
             if replace, !nav.viewControllers.isEmpty {
@@ -2175,8 +2183,8 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
         }
     }
 
-    func nativeScreen(_ screen: CraftNativeScreenController, open path: String) {
-        open(path)
+    func nativeScreen(_ screen: CraftNativeScreenController, open path: String, props: [String: Any]) {
+        open(path, props: props)
     }
 
     func nativeScreen(_ screen: CraftNativeScreenController, replace path: String) {