craft-native 0.0.164 → 0.0.167

package/dist/ios/templates/CraftApp.swift

@@ -614,12 +614,16 @@ final class CraftChrome: ObservableObject {
     @Published var tabBarVisible = false
     @Published var splashVisible = true
     @Published var tint: UIColor?
+    /// Whether a hybrid page lets the shell claim horizontal swipes for tabs.
+    /// Native screens use their own per-screen `tabSwipeEnabled` option.
+    private(set) var tabSwipeEnabled = true
 
     weak var webView: WKWebView?
     /// What the tab bar covers at the bottom of the screen, in points.
     private var occupied: CGFloat = 0
     private var pendingHide: DispatchWorkItem?
     private var splashDeadline: DispatchWorkItem?
+    private var tabSwipePrevious: String?
     /// The keyboard is up and covers the tab bar, so the page need not leave
     /// room for it: the web view ends at the keyboard (CraftHybrid's webHost).
     private var keyboardUp = false
@@ -645,6 +649,7 @@ final class CraftChrome: ObservableObject {
     /// false when the first screen is native and draws itself.
     func configure(tabs configured: [CraftConfig.Tab], selected: String?, splash: Bool) {
         splashVisible = splash
+        tabSwipeEnabled = true
         guard !configured.isEmpty else { return }
         tabs = configured.map { Tab(id: $0.id, title: $0.title, symbol: $0.symbol ?? "circle", badge: nil) }
         self.selected = selected ?? configured.first?.id
@@ -692,6 +697,7 @@ final class CraftChrome: ObservableObject {
                 let dark = (body["tintDark"] as? String).flatMap { UIColor(hex: $0) }
                 tint = light.map { light in dark.map { dark in UIColor { $0.userInterfaceStyle == .dark ? dark : light } } ?? light }
             }
+            if let swipeEnabled = body["swipeEnabled"] as? Bool { tabSwipeEnabled = swipeEnabled }
             withAnimation(Self.motion(.easeOut(duration: 0.2))) { tabBarVisible = !tabs.isEmpty && !hiddenByScreen }
             publishLayout()
         case "selectTab":
@@ -750,6 +756,29 @@ final class CraftChrome: ObservableObject {
         emit("craftTabSelect", ["id": id])
     }
 
+    /// Move the tab indicator with an in-flight native-stack swipe. The
+    /// controller commits or restores this preview when the finger lifts.
+    func beginTabSwipe(to id: String) {
+        guard id != selected, tabs.contains(where: { $0.id == id }) else { return }
+        tabSwipePrevious = selected
+        withAnimation(nil) { selected = id }
+    }
+
+    func cancelTabSwipe() {
+        guard let previous = tabSwipePrevious else { return }
+        tabSwipePrevious = nil
+        withAnimation(nil) { selected = previous }
+    }
+
+    func commitTabSwipe(to id: String) {
+        tabSwipePrevious = nil
+        guard tabs.contains(where: { $0.id == id }) else { return }
+        withAnimation(nil) { selected = id }
+        UISelectionFeedbackGenerator().selectionChanged()
+        guard CraftHybrid.shared.tabTapped(id, reselect: false) else { return }
+        emit("craftTabSelect", ["id": id])
+    }
+
     /// The animation, or none with Reduce Motion on: the selection jumps to
     /// its tab rather than springing there, as UIKit's own controls do.
     static func motion(_ animation: Animation) -> Animation? {
@@ -1683,14 +1712,22 @@ struct CraftWebView: UIViewRepresentable {
         // Keep awake
         private var isKeepingAwake = false
 
-        // Speech synthesis. One synthesizer for the life of the web view, so a
-        // cue can interrupt the one before it; each utterance it has not
-        // finished yet is held beside the call waiting on it.
+        // Speech synthesis. Each utterance not finished yet is held beside the
+        // call waiting on it. A cue that interrupts one still sounding speaks
+        // on a fresh synthesizer: AVSpeechSynthesizer can drop an utterance
+        // handed to it straight after `stopSpeaking(at: .immediate)`, which
+        // lost the "2" of a "3, 2, 1" countdown. The stopped one is kept in
+        // `retiredSpeechSynthesizers` until it reports the cancel.
         private lazy var speechSynthesizer: AVSpeechSynthesizer = {
             let synthesizer = AVSpeechSynthesizer()
             synthesizer.delegate = self
             return synthesizer
         }()
+        private var retiredSpeechSynthesizers: [AVSpeechSynthesizer] = []
+        /// The session is handed back this long after the last word, so a
+        /// countdown ducks the music once rather than between every number.
+        private static let speechReleaseAfterSilence: TimeInterval = 1.5
+        private var pendingSpeechRelease: DispatchWorkItem?
         private var pendingUtterances: [(utterance: AVSpeechUtterance, callbackId: String?)] = []
         /// What the session was before speech claimed it; nil while speech
         /// does not hold it.
@@ -1752,6 +1789,17 @@ struct CraftWebView: UIViewRepresentable {
             if config.enableMotionSensors {
                 motionManager = CMMotionManager()
             }
+            if config.enableHealthKit {
+                // Apple Health's heart rate as it arrives
+                // (craft.health.startHeartRateUpdates) reaches the page, and
+                // through sendToWeb every native screen too. False once this
+                // coordinator is gone: native screens still hear it.
+                CraftHealth.shared.pageSink = { [weak self] detail in
+                    guard let self else { return false }
+                    self.sendToWeb("craftHealthHeartRate", data: detail)
+                    return true
+                }
+            }
             if config.enableHeartRate {
                 // The strap's readings and connection changes reach the page,
                 // and through sendToWeb every native screen too. False once
@@ -2610,6 +2658,20 @@ struct CraftWebView: UIViewRepresentable {
                 } else {
                     rejectCallback(callbackId, error: "HealthKit is disabled", code: "CAPABILITY_DISABLED")
                 }
+            // Heart rate as Apple Health receives it: craftHealthHeartRate
+            // events until stopped (CraftHealth.swift).
+            case "startHealthHeartRateUpdates":
+                if config.enableHealthKit {
+                    CraftHealth.shared.startHeartRateUpdates(since: body["since"] as? Double) { [weak self] in self?.answer(callbackId, $0) }
+                } else {
+                    rejectCallback(callbackId, error: "HealthKit is disabled", code: "CAPABILITY_DISABLED")
+                }
+            case "stopHealthHeartRateUpdates":
+                if config.enableHealthKit {
+                    CraftHealth.shared.stopHeartRateUpdates { [weak self] in self?.answer(callbackId, $0) }
+                } else {
+                    rejectCallback(callbackId, error: "HealthKit is disabled", code: "CAPABILITY_DISABLED")
+                }
 
             // MARK: - Live Activities
             case "startLiveActivity":
@@ -5132,7 +5194,14 @@ struct CraftWebView: UIViewRepresentable {
                     getMindfulSessions: function(options) {
                         options = options || {};
                         return craft._invoke('getHealthMindfulSessions', {startDate: options.startDate, endDate: options.endDate, limit: options.limit});
-                    }
+                    },
+                    // Heart rate as Apple Health receives it, as
+                    // craftHealthHeartRate events ({samples}) until stopped.
+                    startHeartRateUpdates: function(options) {
+                        var since = options && typeof options.since === 'number' ? options.since : null;
+                        return craft._invoke('startHealthHeartRateUpdates', {since: since});
+                    },
+                    stopHeartRateUpdates: function() { return craft._invoke('stopHealthHeartRateUpdates'); }
                 };
                 // The Music app's song and transport. Nothing is read until
                 // requestAuthorization() has been allowed; observe(true) makes
@@ -6654,8 +6723,13 @@ struct CraftWebView: UIViewRepresentable {
 
         private func speak(_ text: String, body: [String: Any], callbackId: String?) {
             DispatchQueue.main.async {
-                if body["interrupt"] as? Bool ?? true {
-                    self.cancelPendingSpeech()
+                self.pendingSpeechRelease?.cancel()
+                self.pendingSpeechRelease = nil
+                if body["interrupt"] as? Bool ?? true, self.cancelPendingSpeech() {
+                    self.retiredSpeechSynthesizers.append(self.speechSynthesizer)
+                    let fresh = AVSpeechSynthesizer()
+                    fresh.delegate = self
+                    self.speechSynthesizer = fresh
                 }
 
                 let utterance = AVSpeechUtterance(string: text)
@@ -6757,8 +6831,20 @@ struct CraftWebView: UIViewRepresentable {
         /// Checked on the main thread, where the queue of utterances lives, and
         /// done on the speech queue after any setup already asked for, so a
         /// cue that arrives meanwhile reclaims the session after this.
-        private func releaseAudioSessionIfSilent(retry: Bool = true) {
+        private func releaseAudioSessionIfSilent(retry: Bool = true, after delay: TimeInterval = Coordinator.speechReleaseAfterSilence) {
             guard pendingUtterances.isEmpty else { return }
+            pendingSpeechRelease?.cancel()
+            let work = DispatchWorkItem { [weak self] in
+                guard let self else { return }
+                self.pendingSpeechRelease = nil
+                guard self.pendingUtterances.isEmpty, !self.speechSynthesizer.isSpeaking else { return }
+                self.deactivateSpeechAudioSession(retry: retry)
+            }
+            pendingSpeechRelease = work
+            DispatchQueue.main.asyncAfter(deadline: .now() + delay, execute: work)
+        }
+
+        private func deactivateSpeechAudioSession(retry: Bool) {
             speechAudioQueue.async {
                 guard let previous = self.speechAudioSessionToRestore else { return }
                 let session = AVAudioSession.sharedInstance()
@@ -6771,8 +6857,8 @@ struct CraftWebView: UIViewRepresentable {
                     // right, and the ducking still ends when the music app
                     // hears nothing more.
                     if retry {
-                        DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) {
-                            self.releaseAudioSessionIfSilent(retry: false)
+                        DispatchQueue.main.async {
+                            self.releaseAudioSessionIfSilent(retry: false, after: 0.5)
                         }
                         return
                     }
@@ -6783,11 +6869,14 @@ struct CraftWebView: UIViewRepresentable {
             }
         }
 
-        fileprivate func speechDidEnd(_ utterance: AVSpeechUtterance, spoken: Bool) {
+        fileprivate func speechDidEnd(_ synthesizer: AVSpeechSynthesizer, _ utterance: AVSpeechUtterance, spoken: Bool) {
             if let index = pendingUtterances.firstIndex(where: { $0.utterance === utterance }) {
                 let entry = pendingUtterances.remove(at: index)
                 resolveCallback(entry.callbackId, result: spoken)
             }
+            if synthesizer !== speechSynthesizer, !synthesizer.isSpeaking {
+                retiredSpeechSynthesizers.removeAll { $0 === synthesizer }
+            }
             releaseAudioSessionIfSilent()
         }
 
@@ -8419,11 +8508,11 @@ extension CraftWebView.Coordinator: WKUIDelegate {
 
 extension CraftWebView.Coordinator: AVSpeechSynthesizerDelegate {
     func speechSynthesizer(_ synthesizer: AVSpeechSynthesizer, didFinish utterance: AVSpeechUtterance) {
-        DispatchQueue.main.async { self.speechDidEnd(utterance, spoken: true) }
+        DispatchQueue.main.async { self.speechDidEnd(synthesizer, utterance, spoken: true) }
     }
 
     func speechSynthesizer(_ synthesizer: AVSpeechSynthesizer, didCancel utterance: AVSpeechUtterance) {
-        DispatchQueue.main.async { self.speechDidEnd(utterance, spoken: false) }
+        DispatchQueue.main.async { self.speechDidEnd(synthesizer, utterance, spoken: false) }
     }
 }
 
@@ -8692,7 +8781,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", "craftMusicChange", "craftHeartRate"]
+    static let forwardedEvents: Set<String> = ["craftLocationUpdate", "craftLocationError", "craftHealthHeartRate", "craftMusicChange", "craftHeartRate"]
     static let event = Notification.Name("craftWebServicesEvent")
 
     static var isAvailable: Bool { CraftSwiftShim.coordinator != nil }

package/dist/ios/templates/CraftHealth.swift

@@ -13,18 +13,29 @@ struct CraftHealthError: Error {
 /// the hybrid's web view, CraftApp.swift) and native screens alike
 /// (`Health` through CraftNativeActions), so a screen drawn natively reads
 /// and writes Apple Health exactly as a page does. One HKHealthStore for the
-/// process, as Apple asks. Every answer arrives through `completion`, on
-/// whatever queue HealthKit answered on; each caller hops to its own.
+/// process, as Apple asks. Every answer is delivered on the main queue so the
+/// native-screen JavaScript bridge can safely resume its pending call.
 final class CraftHealth {
     typealias Completion = (Result<Any, CraftHealthError>) -> Void
 
     static let shared = CraftHealth()
 
+    private func completeOnMain(_ completion: @escaping Completion) -> Completion {
+        { result in
+            if Thread.isMainThread {
+                completion(result)
+            } else {
+                DispatchQueue.main.async { completion(result) }
+            }
+        }
+    }
+
     /// Nil where Apple Health is not on this device (an iPad without it).
     let healthStore: HKHealthStore? = HKHealthStore.isHealthDataAvailable() ? HKHealthStore() : nil
 
     /// A native screen's call (`Health` in CraftNativeActions), by method and arguments as the bridge sends them.
-    func perform(method: String, args: [Any], completion: @escaping Completion) {
+    func perform(method: String, args: [Any], completion rawCompletion: @escaping Completion) {
+        let completion = completeOnMain(rawCompletion)
         let options = { (index: Int) in args.count > index ? args[index] as? [String: Any] ?? [:] : [:] }
         switch method {
         case "requestAuthorization":
@@ -54,12 +65,17 @@ final class CraftHealth {
             saveMindfulSession(body: options(0), completion: completion)
         case "getMindfulSessions":
             getMindfulSessions(startDate: options(0)["startDate"] as? Double, endDate: options(0)["endDate"] as? Double, limit: options(0)["limit"] as? Int, completion: completion)
+        case "startHeartRateUpdates":
+            startHeartRateUpdates(since: options(0)["since"] as? Double, completion: completion)
+        case "stopHeartRateUpdates":
+            stopHeartRateUpdates(completion: completion)
         default:
             completion(.failure(CraftHealthError(message: "Unsupported Health method", code: "UNKNOWN_ACTION")))
         }
     }
 
-    func requestAuthorization(types: [String], readOnly: Bool = false, completion: @escaping Completion) {
+    func requestAuthorization(types: [String], readOnly: Bool = false, completion rawCompletion: @escaping Completion) {
+        let completion = completeOnMain(rawCompletion)
         guard let healthStore = healthStore else {
             completion(.failure(CraftHealthError(message: "HealthKit not available")))
             return
@@ -151,7 +167,8 @@ final class CraftHealth {
         }
     }
 
-    func getData(type: String, startDate: Double?, endDate: Double?, completion: @escaping Completion) {
+    func getData(type: String, startDate: Double?, endDate: Double?, completion rawCompletion: @escaping Completion) {
+        let completion = completeOnMain(rawCompletion)
         guard let healthStore = healthStore else {
             completion(.failure(CraftHealthError(message: "HealthKit not available")))
             return
@@ -191,7 +208,8 @@ final class CraftHealth {
 
     /// Save one quantity sample, primarily a food-log entry. Dates are epoch
     /// milliseconds; an omitted range records an instantaneous sample now.
-    func saveData(type: String, value: Double, options: [String: Any], completion: @escaping Completion) {
+    func saveData(type: String, value: Double, options: [String: Any], completion rawCompletion: @escaping Completion) {
+        let completion = completeOnMain(rawCompletion)
         guard let healthStore = healthStore else {
             completion(.failure(CraftHealthError(message: "HealthKit not available")))
             return
@@ -225,7 +243,8 @@ final class CraftHealth {
         }
     }
 
-    func saveWorkout(body: [String: Any], completion: @escaping Completion) {
+    func saveWorkout(body: [String: Any], completion rawCompletion: @escaping Completion) {
+        let completion = completeOnMain(rawCompletion)
         guard let healthStore = healthStore else {
             completion(.failure(CraftHealthError(message: "HealthKit not available")))
             return
@@ -378,7 +397,8 @@ final class CraftHealth {
 
     /// Workouts in Apple Health — the watch's, and every app's that
     /// writes there — newest first, with the numbers a training log needs.
-    func getWorkouts(startDate: Double?, endDate: Double?, limit: Int?, completion: @escaping Completion) {
+    func getWorkouts(startDate: Double?, endDate: Double?, limit: Int?, completion rawCompletion: @escaping Completion) {
+        let completion = completeOnMain(rawCompletion)
         guard let healthStore = healthStore else {
             completion(.failure(CraftHealthError(message: "HealthKit not available")))
             return
@@ -436,7 +456,8 @@ final class CraftHealth {
     /// One value per local day: a sum for steps, energy and distance, an
     /// average for heart rate, resting heart rate and HRV, the latest
     /// weight, and hours asleep for sleep (counted on the day you woke).
-    func getDailyStatistics(type: String, startDate: Double?, endDate: Double?, completion: @escaping Completion) {
+    func getDailyStatistics(type: String, startDate: Double?, endDate: Double?, completion rawCompletion: @escaping Completion) {
+        let completion = completeOnMain(rawCompletion)
         guard let healthStore = healthStore else {
             completion(.failure(CraftHealthError(message: "HealthKit not available")))
             return
@@ -510,7 +531,8 @@ final class CraftHealth {
     /// beats per minute, when it was taken, and the app and device that
     /// wrote it. A watch's workout readings can arrive as one series
     /// sample; those also carry their count, lowest and highest.
-    func getHeartRateSamples(startDate: Double?, endDate: Double?, limit: Int?, completion: @escaping Completion) {
+    func getHeartRateSamples(startDate: Double?, endDate: Double?, limit: Int?, completion rawCompletion: @escaping Completion) {
+        let completion = completeOnMain(rawCompletion)
         guard let healthStore = healthStore else {
             completion(.failure(CraftHealthError(message: "HealthKit not available")))
             return
@@ -526,39 +548,42 @@ final class CraftHealth {
         let oldestFirst = NSSortDescriptor(key: HKSampleSortIdentifierStartDate, ascending: true)
         let cap = max(1, min(limit ?? 10_000, 50_000))
 
-        let query = HKSampleQuery(sampleType: heartType, predicate: predicate, limit: cap, sortDescriptors: [oldestFirst]) { [weak self] _, samples, error in
+        let query = HKSampleQuery(sampleType: heartType, predicate: predicate, limit: cap, sortDescriptors: [oldestFirst]) { _, samples, error in
             if let error = error, (error as? HKError)?.code != .errorNoData {
                 completion(.failure(CraftHealthError(message: error.localizedDescription)))
                 return
             }
+            completion(.success((samples as? [HKQuantitySample] ?? []).map(Self.heartRateRow)))
+        }
+        healthStore.execute(query)
+    }
 
-            let bpm = HKUnit.count().unitDivided(by: .minute())
-            let rows: [[String: Any]] = (samples as? [HKQuantitySample] ?? []).map { sample in
-                var item: [String: Any] = [
-                    "bpm": sample.quantity.doubleValue(for: bpm),
-                    "startDate": sample.startDate.timeIntervalSince1970 * 1000,
-                    "endDate": sample.endDate.timeIntervalSince1970 * 1000,
-                    "sourceName": sample.sourceRevision.source.name,
-                ]
-                if let device = sample.device?.name { item["deviceName"] = device }
-                if let model = sample.device?.model { item["deviceModel"] = model }
-                if let series = sample as? HKDiscreteQuantitySample, series.count > 1 {
-                    item["count"] = series.count
-                    item["min"] = series.minimumQuantity.doubleValue(for: bpm)
-                    item["max"] = series.maximumQuantity.doubleValue(for: bpm)
-                }
-                if let raw = sample.metadata?[HKMetadataKeyHeartRateMotionContext] as? NSNumber {
-                    switch HKHeartRateMotionContext(rawValue: raw.intValue) {
-                    case .sedentary: item["motionContext"] = "sedentary"
-                    case .active: item["motionContext"] = "active"
-                    default: break
-                    }
-                }
-                return item
+    /// One heart-rate sample as a page sees it, from a read or the stream
+    /// alike: bpm, when, the app and device that wrote it, a series' count,
+    /// lowest and highest, and what the wearer was doing when the watch says.
+    private static func heartRateRow(_ sample: HKQuantitySample) -> [String: Any] {
+        let bpm = HKUnit.count().unitDivided(by: .minute())
+        var item: [String: Any] = [
+            "bpm": sample.quantity.doubleValue(for: bpm),
+            "startDate": sample.startDate.timeIntervalSince1970 * 1000,
+            "endDate": sample.endDate.timeIntervalSince1970 * 1000,
+            "sourceName": sample.sourceRevision.source.name,
+        ]
+        if let device = sample.device?.name { item["deviceName"] = device }
+        if let model = sample.device?.model { item["deviceModel"] = model }
+        if let series = sample as? HKDiscreteQuantitySample, series.count > 1 {
+            item["count"] = series.count
+            item["min"] = series.minimumQuantity.doubleValue(for: bpm)
+            item["max"] = series.maximumQuantity.doubleValue(for: bpm)
+        }
+        if let raw = sample.metadata?[HKMetadataKeyHeartRateMotionContext] as? NSNumber {
+            switch HKHeartRateMotionContext(rawValue: raw.intValue) {
+            case .sedentary: item["motionContext"] = "sedentary"
+            case .active: item["motionContext"] = "active"
+            default: break
             }
-            completion(.success(rows))
         }
-        healthStore.execute(query)
+        return item
     }
 
     /// A stable name for each sleep analysis value: in bed, awake, or one
@@ -577,7 +602,8 @@ final class CraftHealth {
     /// Sleep between two instants, oldest first, as the sources wrote it:
     /// time in bed and every asleep or awake stretch, each with its stage
     /// and whether it counts as asleep, so a page can mark the night.
-    func getSleepIntervals(startDate: Double?, endDate: Double?, completion: @escaping Completion) {
+    func getSleepIntervals(startDate: Double?, endDate: Double?, completion rawCompletion: @escaping Completion) {
+        let completion = completeOnMain(rawCompletion)
         guard let healthStore = healthStore else {
             completion(.failure(CraftHealthError(message: "HealthKit not available")))
             return
@@ -623,7 +649,8 @@ final class CraftHealth {
     /// as the sample's external UUID, so saving the same session twice (a
     /// retry, a second device) keeps the first sample instead of adding
     /// another: the answer then says `existing: true`.
-    func saveMindfulSession(body: [String: Any], completion: @escaping Completion) {
+    func saveMindfulSession(body: [String: Any], completion rawCompletion: @escaping Completion) {
+        let completion = completeOnMain(rawCompletion)
         guard let healthStore = healthStore else {
             completion(.failure(CraftHealthError(message: "HealthKit not available")))
             return
@@ -675,7 +702,8 @@ final class CraftHealth {
     /// that writes them (the Mindfulness app, Calm, this one). Each says
     /// whether this app wrote it (`ownApp`) and carries the external id it
     /// was saved with, so a page can tell its own sessions from the rest.
-    func getMindfulSessions(startDate: Double?, endDate: Double?, limit: Int?, completion: @escaping Completion) {
+    func getMindfulSessions(startDate: Double?, endDate: Double?, limit: Int?, completion rawCompletion: @escaping Completion) {
+        let completion = completeOnMain(rawCompletion)
         guard let healthStore = healthStore else {
             completion(.failure(CraftHealthError(message: "HealthKit not available")))
             return
@@ -717,4 +745,151 @@ final class CraftHealth {
         healthStore.execute(query)
     }
 
+    // MARK: Heart rate as it arrives
+
+    /// The web view's coordinator, which sends `craftHealthHeartRate` to the
+    /// page and every native screen. False (or unset, in an app without a web
+    /// view) and the event goes to the native screens alone.
+    var pageSink: (([String: Any]) -> Bool)?
+
+    /// The one running stream: an anchored query that hears every heart-rate
+    /// sample HealthKit receives after it starts.
+    private var heartRateQuery: HKAnchoredObjectQuery?
+    /// Samples already sent, so a batch HealthKit repeats is not sent twice.
+    private var heartRateSent: Set<UUID> = []
+    /// Bumped by every start and stop, so a stopped stream's late batch is dropped.
+    private var heartRateStream = 0
+    #if targetEnvironment(simulator)
+    private var simulatedHeartRateTimer: Timer?
+    #endif
+
+    private func onMain(_ work: @escaping () -> Void) {
+        if Thread.isMainThread { work() } else { DispatchQueue.main.async(execute: work) }
+    }
+
+    /// Heart rate as Apple Health receives it, for as long as it runs: every
+    /// sample that starts at or after `since` (epoch ms; two minutes ago by
+    /// default), first what is there already, then each batch as the watch
+    /// syncs it, as `craftHealthHeartRate` events (`{samples}`, oldest first,
+    /// each sample once, in getHeartRateSamples' shape). One stream at a
+    /// time: starting again replaces the running one. Reads under the
+    /// `heartRate` grant. Answers true once the samples already there are
+    /// sent.
+    ///
+    /// Simulator builds with the `CraftFakeHealthHeartRate` default
+    /// (`xcrun simctl spawn booted defaults write <bundle id>
+    /// CraftFakeHealthHeartRate -bool YES`) skip HealthKit and send a made-up
+    /// watch reading every five seconds instead.
+    func startHeartRateUpdates(since: Double?, completion rawCompletion: @escaping Completion) {
+        let completion = completeOnMain(rawCompletion)
+        let start = Date(timeIntervalSince1970: (since ?? Date().timeIntervalSince1970 * 1000 - 120_000) / 1000)
+        onMain { [self] in
+            stopHeartRateStream()
+            let stream = heartRateStream
+
+            #if targetEnvironment(simulator)
+            if UserDefaults.standard.bool(forKey: "CraftFakeHealthHeartRate") {
+                startSimulatedHeartRate(stream: stream)
+                completion(.success(true))
+                return
+            }
+            #endif
+
+            guard let healthStore = healthStore else {
+                completion(.failure(CraftHealthError(message: "HealthKit not available")))
+                return
+            }
+            guard let heartType = HKQuantityType.quantityType(forIdentifier: .heartRate) else {
+                completion(.failure(CraftHealthError(message: "Heart rate is unavailable")))
+                return
+            }
+
+            let predicate = HKQuery.predicateForSamples(withStart: start, end: nil, options: .strictStartDate)
+            let query = HKAnchoredObjectQuery(type: heartType, predicate: predicate, anchor: nil, limit: HKObjectQueryNoLimit) { [weak self] _, samples, _, _, error in
+                let rows = (samples as? [HKQuantitySample] ?? []).map { ($0.uuid, Self.heartRateRow($0)) }
+                DispatchQueue.main.async {
+                    // Stopped or replaced before its first batch: it did start.
+                    guard let self, self.heartRateStream == stream else { return completion(.success(true)) }
+                    if let error = error, (error as? HKError)?.code != .errorNoData {
+                        self.stopHeartRateStream()
+                        return completion(.failure(CraftHealthError(message: error.localizedDescription)))
+                    }
+                    self.sendHeartRate(rows)
+                    completion(.success(true))
+                }
+            }
+            query.updateHandler = { [weak self] _, samples, _, _, error in
+                if let error = error {
+                    NSLog("[craft] Apple Health heart rate: %@", error.localizedDescription)
+                    return
+                }
+                let rows = (samples as? [HKQuantitySample] ?? []).map { ($0.uuid, Self.heartRateRow($0)) }
+                DispatchQueue.main.async {
+                    guard let self, self.heartRateStream == stream else { return }
+                    self.sendHeartRate(rows)
+                }
+            }
+            heartRateQuery = query
+            healthStore.execute(query)
+        }
+    }
+
+    /// Stops the stream; true whether or not one was running.
+    func stopHeartRateUpdates(completion rawCompletion: @escaping Completion) {
+        let completion = completeOnMain(rawCompletion)
+        onMain { [self] in
+            stopHeartRateStream()
+            completion(.success(true))
+        }
+    }
+
+    /// Main only.
+    private func stopHeartRateStream() {
+        heartRateStream += 1
+        if let query = heartRateQuery { healthStore?.stop(query) }
+        heartRateQuery = nil
+        heartRateSent.removeAll()
+        #if targetEnvironment(simulator)
+        simulatedHeartRateTimer?.invalidate()
+        simulatedHeartRateTimer = nil
+        #endif
+    }
+
+    /// Sends the samples not sent before, oldest first; nothing when none are new. Main only.
+    private func sendHeartRate(_ rows: [(UUID, [String: Any])]) {
+        let fresh = rows
+            .filter { heartRateSent.insert($0.0).inserted }
+            .map { $0.1 }
+            .sorted { ($0["startDate"] as? Double ?? 0) < ($1["startDate"] as? Double ?? 0) }
+        guard !fresh.isEmpty else { return }
+        let detail: [String: Any] = ["samples": fresh]
+        if pageSink?(detail) != true { CraftWebServices.forward("craftHealthHeartRate", data: detail) }
+    }
+
+    /// The simulator's watch: someone settling into slow breathing, about 72
+    /// at first and easing toward 60 over a few minutes, with a small wobble.
+    static func simulatedHeartRate(elapsed: TimeInterval) -> Double {
+        (60 + 12 * exp(-elapsed / 150) + 1.5 * sin(elapsed / 9)).rounded()
+    }
+
+    #if targetEnvironment(simulator)
+    /// One made-up watch reading now and every five seconds after. Main only.
+    private func startSimulatedHeartRate(stream: Int) {
+        let began = Date()
+        let send: () -> Void = { [weak self] in
+            guard let self, self.heartRateStream == stream else { return }
+            let now = Date().timeIntervalSince1970 * 1000
+            self.sendHeartRate([(UUID(), [
+                "bpm": Self.simulatedHeartRate(elapsed: Date().timeIntervalSince(began)),
+                "startDate": now,
+                "endDate": now,
+                "sourceName": "Apple Watch (simulated)",
+                "deviceName": "Apple Watch",
+                "motionContext": "sedentary",
+            ])])
+        }
+        send()
+        simulatedHeartRateTimer = Timer.scheduledTimer(withTimeInterval: 5, repeats: true) { _ in send() }
+    }
+    #endif
 }

package/dist/ios/templates/CraftHeartRate.swift

@@ -115,7 +115,8 @@ struct CraftHeartRateMeasurement: Equatable {
 /// Simulator builds have no Bluetooth; with the `CraftFakeHeartRateMonitor`
 /// default set (`xcrun simctl spawn booted defaults write <bundle id>
 /// CraftFakeHeartRateMonitor -bool YES`) a made-up strap stands in, whose
-/// readings are encoded as 0x2A37 payloads and decoded like a real one's.
+/// readings are encoded as 0x2A37 payloads and decoded like a real one's. Its
+/// RR intervals vary beat to beat with the breath, as a heart's do.
 ///
 /// Everything runs on main: the central manager delivers there, and every
 /// caller hops there first.
@@ -176,6 +177,9 @@ final class CraftHeartRate: NSObject, CBCentralManagerDelegate, CBPeripheralDele
     private static let simulatedId = UUID(uuidString: "00000000-0000-4000-8000-00000000180D")!
     private var simulatedTimer: Timer?
     private var simulatedBeat = 0
+    /// Milliseconds since the stand-in connected, and how far its beats reach.
+    private var simulatedElapsed: Double = 0
+    private var simulatedBeatsUntil: Double = 0
 
     // MARK: Entry
 
@@ -566,16 +570,42 @@ final class CraftHeartRate: NSObject, CBCentralManagerDelegate, CBPeripheralDele
         emitState()
         settleConnect(.success(state()))
         simulatedTimer?.invalidate()
+        simulatedElapsed = 0
+        simulatedBeatsUntil = 0
         simulatedTimer = Timer.scheduledTimer(withTimeInterval: 1, repeats: true) { [weak self] _ in
             guard let self else { return }
             self.simulatedBeat += 1
+            self.simulatedElapsed += 1000
             // A steady run with a slow swell, the way a real one drifts.
-            let bpm = 142 + Int((sin(Double(self.simulatedBeat) / 20) * 12).rounded())
-            let interval = 60_000 / Double(bpm)
-            self.received(CraftHeartRateMeasurement.encode(bpm: bpm, sensorContact: true, rrIntervals: [interval]))
+            let rate = 142 + sin(Double(self.simulatedBeat) / 20) * 12
+            var beatsUntil = self.simulatedBeatsUntil
+            let intervals = Self.simulatedIntervals(rate: rate, from: &beatsUntil, until: self.simulatedElapsed)
+            self.simulatedBeatsUntil = beatsUntil
+            guard !intervals.isEmpty else { return }
+            // The rate a strap reports is the one its intervals give.
+            let bpm = Int((60_000 / (intervals.reduce(0, +) / Double(intervals.count))).rounded())
+            self.received(CraftHeartRateMeasurement.encode(bpm: bpm, sensorContact: true, rrIntervals: intervals))
         }
     }
 
+    /// The beats from `start` (ms) until `end`, each interval in ms: the
+    /// rate's own interval, plus respiratory sinus arrhythmia (beats come
+    /// closer on the in-breath and spread on the out-breath over a ten-second
+    /// breath, ±4% of the interval: ±40 ms at 60 bpm) and a few ms of noise,
+    /// so a heart-rate variability worked out from them means something.
+    /// `start` moves to the last beat.
+    static func simulatedIntervals(rate: Double, from start: inout Double, until end: Double, noise: () -> Double = { Double.random(in: -4...4) }) -> [Double] {
+        let base = 60_000 / rate
+        var intervals: [Double] = []
+        while start < end {
+            let breath = sin(2 * Double.pi * start / 10_000)
+            let interval = base * (1 - 0.04 * breath) + noise()
+            start += interval
+            intervals.append(interval)
+        }
+        return intervals
+    }
+
     // MARK: Recording
 
     private var directory: URL {