@craft-native/ios 0.0.151 → 0.0.152

package/README.md

@@ -179,6 +179,7 @@ Edit `craft.config.json` in your iOS project:
   "enableNFC": true,
   "enableHealthKit": false,
   "enableAppleMusic": false,
+  "enableHeartRate": false,
   "enableScreenCapture": true,
   "iosVersion": "15.0",
   "teamId": ""
@@ -558,6 +559,35 @@ window.addEventListener('craftMusicChange', (event) => render(event.detail));
 // CraftFakeMusicPlayer -bool YES`) for three made-up songs that play (counting as other audio) and skip.
 // Simulator builds only; a device always talks to the Music app.
 
+// Heart rate (enableHeartRate): a Bluetooth strap, or a watch broadcasting
+// its heart rate, through the standard Heart Rate Service (0x180D) and its
+// Heart Rate Measurement (0x2A37): bpm, sensor contact, energy and RR
+// intervals. The app gets the `bluetooth-central` background mode, so
+// readings keep coming during a workout with the screen locked. iOS asks
+// for Bluetooth on the first scan or connect (or requestAuthorization()); word
+// it with usageDescriptions.NSBluetoothAlwaysUsageDescription.
+window.addEventListener('craftHeartRate', (event) => {
+  // { type: 'device', device: { id, name, rssi } }      a scan found a strap
+  // { type: 'reading', bpm, rrIntervals, contact, energyExpended, timestamp, deviceId }
+  // { type: 'state', connection, bluetooth, device, lastDevice, bpm, ... }
+});
+await window.craft.heartRate.scan({ timeout: 15 });     // straps nearby, and one already connected
+const strap = (await window.craft.heartRate.getDevices())[0]; // strongest signal first
+await window.craft.heartRate.connect(strap.id);  // remembered; rejects TIMEOUT after 15 s while still asking
+await window.craft.heartRate.reconnect();        // next time: the remembered strap, no scan
+// A strap that drops out is asked for again (connection 'reconnecting')
+// until disconnect({ forget }) lets it go.
+await window.craft.heartRate.startRecording();   // every reading kept natively, app closed or not
+await window.craft.heartRate.pauseRecording();   // resumeRecording() / getRecordingState()
+const { samples } = await window.craft.heartRate.stopRecording(); // [{ timestamp, bpm, rr? }]
+// Native screens call the same service as the HeartRate module (capability
+// `heartRate`), and hear the same craftHeartRate events. Or use `heartRate`
+// from 'craft-native/mobile' (onReading, onDevice, onState); off a phone it
+// answers { available: false }.
+// The simulator has no Bluetooth: `simctl spawn <device> defaults write
+// <bundle id> CraftFakeHeartRateMonitor -bool YES` stands in a strap ("Simulated
+// HRM") whose readings are encoded and decoded as 0x2A37 payloads. Simulator builds only.
+
 // Speech: short spoken cues that duck the person's music instead of stopping
 // it, and play with the silent switch on. Always available (no config flag).
 // Resolves when the utterance ends: true if spoken, false if stopped or

package/dist/cli.js

@@ -115,6 +115,7 @@ var DEFAULT_CONFIG = {
   enableAR: false,
   enableMLKit: false,
   enableAppleMusic: false,
+  enableHeartRate: false,
   iosVersion: "16.0",
   watchosVersion: "9.0",
   teamId: "",
@@ -171,7 +172,7 @@ function renderUsageDescriptions(config) {
     [config.enableBackgroundLocation, "NSLocationAlwaysAndWhenInUseUsageDescription", `${config.appName} continues recording your route when the screen is locked or the app is in the background.`],
     [config.enableContacts, "NSContactsUsageDescription", `${config.appName} accesses contacts only when you choose a contact feature.`],
     [config.enableCalendar, "NSCalendarsUsageDescription", `${config.appName} accesses your calendar only when you choose a calendar feature.`],
-    [config.enableBluetooth, "NSBluetoothAlwaysUsageDescription", `${config.appName} uses Bluetooth to connect to nearby devices.`],
+    [config.enableBluetooth || config.enableHeartRate, "NSBluetoothAlwaysUsageDescription", config.enableHeartRate ? `${config.appName} connects to your heart-rate monitor over Bluetooth to show and record your heart rate during a workout.` : `${config.appName} uses Bluetooth to connect to nearby devices.`],
     [config.enableMotionSensors, "NSMotionUsageDescription", `${config.appName} uses motion data for activity features.`],
     [config.enableNFC, "NFCReaderUsageDescription", `${config.appName} reads NFC tags when you start a scan.`],
     [config.enableLocalNetwork, "NSLocalNetworkUsageDescription", `${config.appName} connects to your own devices on this network.`],
@@ -254,6 +255,8 @@ function renderBackgroundModes(config) {
     modes.add("processing");
   if (config.enablePushNotifications)
     modes.add("remote-notification");
+  if (config.enableHeartRate)
+    modes.add("bluetooth-central");
   if (!modes.size)
     return "";
   return `    <key>UIBackgroundModes</key>
@@ -732,6 +735,7 @@ async function init(options) {
   cpSync(join(TEMPLATES_DIR, "CraftNativeActions.swift"), join(output, "Sources", "CraftNativeActions.swift"));
   cpSync(join(TEMPLATES_DIR, "CraftHealth.swift"), join(output, "Sources", "CraftHealth.swift"));
   cpSync(join(TEMPLATES_DIR, "CraftMusic.swift"), join(output, "Sources", "CraftMusic.swift"));
+  cpSync(join(TEMPLATES_DIR, "CraftHeartRate.swift"), join(output, "Sources", "CraftHeartRate.swift"));
   cpSync(join(TEMPLATES_DIR, "CraftNativeMutation.swift"), join(output, "Sources", "CraftNativeMutation.swift"));
   cpSync(join(TEMPLATES_DIR, "CraftNativeUI.swift"), join(output, "Sources", "CraftNativeUI.swift"));
   cpSync(join(TEMPLATES_DIR, "CraftNativeServices.swift"), join(output, "Sources", "CraftNativeServices.swift"));

package/dist/index.d.ts

@@ -68,6 +68,15 @@ export interface CraftConfig {
      * `craft.music.requestAuthorization()`, never at launch.
      */
     enableAppleMusic?: boolean;
+    /**
+     * Read a Bluetooth heart-rate strap, or a watch broadcasting its heart rate
+     * (the standard Heart Rate Service), through `craft.heartRate`: scan,
+     * connect, live readings with RR intervals, and a recording kept natively.
+     * Adds the `bluetooth-central` background mode, so readings keep coming
+     * during a workout with the screen locked. iOS asks for Bluetooth the first
+     * time the page scans or connects.
+     */
+    enableHeartRate?: boolean;
     /**
      * Purpose strings in the app's own words, by Info.plist key
      * (`{ NSAppleMusicUsageDescription: 'Shows the song playing during a workout.' }`).

package/dist/index.js

@@ -170,6 +170,7 @@ var DEFAULT_CONFIG = {
   enableAR: false,
   enableMLKit: false,
   enableAppleMusic: false,
+  enableHeartRate: false,
   iosVersion: "16.0",
   watchosVersion: "9.0",
   teamId: "",
@@ -226,7 +227,7 @@ function renderUsageDescriptions(config) {
     [config.enableBackgroundLocation, "NSLocationAlwaysAndWhenInUseUsageDescription", `${config.appName} continues recording your route when the screen is locked or the app is in the background.`],
     [config.enableContacts, "NSContactsUsageDescription", `${config.appName} accesses contacts only when you choose a contact feature.`],
     [config.enableCalendar, "NSCalendarsUsageDescription", `${config.appName} accesses your calendar only when you choose a calendar feature.`],
-    [config.enableBluetooth, "NSBluetoothAlwaysUsageDescription", `${config.appName} uses Bluetooth to connect to nearby devices.`],
+    [config.enableBluetooth || config.enableHeartRate, "NSBluetoothAlwaysUsageDescription", config.enableHeartRate ? `${config.appName} connects to your heart-rate monitor over Bluetooth to show and record your heart rate during a workout.` : `${config.appName} uses Bluetooth to connect to nearby devices.`],
     [config.enableMotionSensors, "NSMotionUsageDescription", `${config.appName} uses motion data for activity features.`],
     [config.enableNFC, "NFCReaderUsageDescription", `${config.appName} reads NFC tags when you start a scan.`],
     [config.enableLocalNetwork, "NSLocalNetworkUsageDescription", `${config.appName} connects to your own devices on this network.`],
@@ -309,6 +310,8 @@ function renderBackgroundModes(config) {
     modes.add("processing");
   if (config.enablePushNotifications)
     modes.add("remote-notification");
+  if (config.enableHeartRate)
+    modes.add("bluetooth-central");
   if (!modes.size)
     return "";
   return `    <key>UIBackgroundModes</key>
@@ -787,6 +790,7 @@ async function init(options) {
   cpSync(join(TEMPLATES_DIR, "CraftNativeActions.swift"), join(output, "Sources", "CraftNativeActions.swift"));
   cpSync(join(TEMPLATES_DIR, "CraftHealth.swift"), join(output, "Sources", "CraftHealth.swift"));
   cpSync(join(TEMPLATES_DIR, "CraftMusic.swift"), join(output, "Sources", "CraftMusic.swift"));
+  cpSync(join(TEMPLATES_DIR, "CraftHeartRate.swift"), join(output, "Sources", "CraftHeartRate.swift"));
   cpSync(join(TEMPLATES_DIR, "CraftNativeMutation.swift"), join(output, "Sources", "CraftNativeMutation.swift"));
   cpSync(join(TEMPLATES_DIR, "CraftNativeUI.swift"), join(output, "Sources", "CraftNativeUI.swift"));
   cpSync(join(TEMPLATES_DIR, "CraftNativeServices.swift"), join(output, "Sources", "CraftNativeServices.swift"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craft-native/ios",
-  "version": "0.0.151",
+  "version": "0.0.152",
   "homepage": "https://github.com/craft-native/craft/tree/main/packages/ios#readme",
   "repository": {
     "type": "git",

package/templates/CraftApp.swift

@@ -1119,6 +1119,9 @@ struct CraftConfig: Codable {
     var enableMLKit: Bool = false
     /// The Music app's song and transport through `craft.music` (CraftMusic.swift).
     var enableAppleMusic: Bool = false
+    /// A Bluetooth heart-rate strap (or a watch broadcasting its heart rate)
+    /// through `craft.heartRate` (CraftHeartRate.swift).
+    var enableHeartRate: Bool = false
     var devServerURL: String? = nil
     var trustedOrigins: [String] = []
     /// The longest the launch splash stays up when the page neither says it is
@@ -1641,6 +1644,16 @@ struct CraftWebView: UIViewRepresentable {
             if config.enableMotionSensors {
                 motionManager = CMMotionManager()
             }
+            if config.enableHeartRate {
+                // The strap's readings and connection changes reach the page,
+                // and through sendToWeb every native screen too. False once
+                // this coordinator is gone: native screens still hear them.
+                CraftHeartRate.shared.pageSink = { [weak self] detail in
+                    guard let self else { return false }
+                    self.sendToWeb("craftHeartRate", data: detail)
+                    return true
+                }
+            }
             if config.enableWatchApp {
                 setupWatchConnectivity()
             }
@@ -2213,6 +2226,22 @@ struct CraftWebView: UIViewRepresentable {
                 } else {
                     rejectCallback(callbackId, error: "Apple Music is disabled", code: "CAPABILITY_DISABLED")
                 }
+            // MARK: - Heart rate (CraftHeartRate.swift)
+            // Gated on enableHeartRate. One action for every method, as a
+            // native screen's HeartRate module calls them; asking for
+            // Bluetooth has its own, which waits on the person.
+            case "heartRate", "heartRateRequestAuthorization":
+                if !config.enableHeartRate {
+                    rejectCallback(callbackId, error: "Heart rate is disabled", code: "CAPABILITY_DISABLED")
+                } else {
+                    let method = action == "heartRate" ? body["method"] as? String ?? "" : "requestAuthorization"
+                    CraftHeartRate.shared.perform(method: method, args: [body["options"] as? [String: Any] ?? [:]]) { [weak self] result in
+                        switch result {
+                        case .success(let value): self?.resolveCallback(callbackId, result: value)
+                        case .failure(let failure): self?.rejectCallback(callbackId, error: failure.message, code: failure.code)
+                        }
+                    }
+                }
             // MARK: - Orientation Lock
             case "lockOrientation":
                 if config.enableOrientationLock {
@@ -3198,6 +3227,7 @@ struct CraftWebView: UIViewRepresentable {
                     flashlight: true,
                     brightness: true,
                     music: \(config.enableAppleMusic),
+                    heartRate: \(config.enableHeartRate),
                     speech: true,
                     network: true,
                     deviceInfo: true,
@@ -4737,6 +4767,7 @@ struct CraftWebView: UIViewRepresentable {
                 var personFacing = {
                     requestHealthAuthorization: true,
                     musicRequestAuthorization: true,
+                    heartRateRequestAuthorization: true,
                     requestPermission: true,
                     signInWithApple: true,
                     dialogAlert: true,
@@ -4951,6 +4982,30 @@ struct CraftWebView: UIViewRepresentable {
                     },
                     observe: function(enabled) { return craft._invoke('musicObserve', {enabled: enabled !== false}); }
                 };
+                // A Bluetooth heart-rate strap, or a watch broadcasting its
+                // heart rate. Readings, devices found by scan() and connection
+                // changes arrive as craftHeartRate events ({type: 'reading' |
+                // 'device' | 'state'}); startRecording() keeps every reading
+                // natively, screen locked or app closed, until stopRecording().
+                (function() {
+                    function heartRate(method, options) { return craft._invoke('heartRate', {method: method, options: options || {}}); }
+                    craft.heartRate = {
+                        getState: function() { return heartRate('getState'); },
+                        requestAuthorization: function() { return craft._invoke('heartRateRequestAuthorization'); },
+                        scan: function(options) { return heartRate('scan', {timeout: options && typeof options.timeout === 'number' ? options.timeout : null}); },
+                        stopScan: function() { return heartRate('stopScan'); },
+                        getDevices: function() { return heartRate('getDevices'); },
+                        connect: function(id) { return heartRate('connect', {id: typeof id === 'string' ? id : id && id.id}); },
+                        reconnect: function() { return heartRate('reconnect'); },
+                        disconnect: function(options) { return heartRate('disconnect', {forget: !!(options && options.forget)}); },
+                        startRecording: function() { return heartRate('startRecording'); },
+                        pauseRecording: function() { return heartRate('pauseRecording'); },
+                        resumeRecording: function() { return heartRate('resumeRecording'); },
+                        stopRecording: function() { return heartRate('stopRecording'); },
+                        getRecordingState: function() { return heartRate('getRecordingState'); },
+                        readRecording: function(options) { return heartRate('readRecording', {since: options && typeof options.since === 'number' ? options.since : null}); }
+                    };
+                })();
                 craft.liveActivity = {
                     start: function(options) { return craft._invoke('startLiveActivity', options || {}); },
                     update: function(idOrState, state) {
@@ -8450,7 +8505,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"]
+    static let forwardedEvents: Set<String> = ["craftLocationUpdate", "craftLocationError", "craftMusicChange", "craftHeartRate"]
     static let event = Notification.Name("craftWebServicesEvent")
 
     static var isAvailable: Bool { CraftSwiftShim.coordinator != nil }

package/templates/CraftHeartRate.swift

@@ -0,0 +1,699 @@
+import CoreBluetooth
+import Foundation
+import UIKit
+
+/// A heart-rate call that did not happen: the message a page sees, and the
+/// bridge's error code.
+struct CraftHeartRateError: Error {
+    let message: String
+    var code: String = "CRAFT_ERROR"
+}
+
+/// One Heart Rate Measurement (characteristic 0x2A37 of the Bluetooth SIG's
+/// Heart Rate Service, 0x180D), decoded.
+///
+/// The payload is a flags byte and then the fields the flags announce, all
+/// little-endian:
+///
+///   bit 0     the heart rate is a uint16 (else a uint8)
+///   bits 1-2  sensor contact: bit 2 says the strap reports it at all,
+///             bit 1 that the skin is touching (a strap worn loose reads 0)
+///   bit 3     a uint16 of energy expended, kilojoules, follows the rate
+///   bit 4     uint16 RR intervals follow, as many as fit, in 1/1024 s
+///
+/// Every strap and every watch that broadcasts its heart rate (Polar, Garmin,
+/// Wahoo, an Apple Watch with a broadcasting app) sends this one shape.
+struct CraftHeartRateMeasurement: Equatable {
+    /// Beats per minute.
+    let bpm: Int
+    /// Whether the strap is touching skin; nil when it cannot tell.
+    let sensorContact: Bool?
+    /// Kilojoules since the strap was last reset; nil when it does not count them.
+    let energyExpended: Int?
+    /// The time between beats, in milliseconds, oldest first.
+    let rrIntervals: [Double]
+
+    /// Nil for a payload too short for what its flags announce.
+    static func parse(_ bytes: [UInt8]) -> CraftHeartRateMeasurement? {
+        guard let flags = bytes.first else { return nil }
+        var offset = 1
+        func uint8() -> Int? {
+            guard offset < bytes.count else { return nil }
+            defer { offset += 1 }
+            return Int(bytes[offset])
+        }
+        func uint16() -> Int? {
+            guard offset + 1 < bytes.count else { return nil }
+            defer { offset += 2 }
+            return Int(bytes[offset]) | Int(bytes[offset + 1]) << 8
+        }
+        guard let bpm = flags & 0x01 != 0 ? uint16() : uint8() else { return nil }
+        let contact: Bool? = flags & 0x04 != 0 ? flags & 0x02 != 0 : nil
+        var energy: Int?
+        if flags & 0x08 != 0 {
+            guard let value = uint16() else { return nil }
+            energy = value
+        }
+        var intervals: [Double] = []
+        if flags & 0x10 != 0 {
+            while let value = uint16() { intervals.append(Double(value) * 1000 / 1024) }
+        }
+        return CraftHeartRateMeasurement(bpm: bpm, sensorContact: contact, energyExpended: energy, rrIntervals: intervals)
+    }
+
+    static func parse(_ data: Data) -> CraftHeartRateMeasurement? { parse([UInt8](data)) }
+
+    /// The payload a strap would send for these values: the simulator's
+    /// stand-in speaks it, so its readings take the same path as a strap's.
+    static func encode(bpm: Int, sensorContact: Bool? = true, energyExpended: Int? = nil, rrIntervals: [Double] = []) -> [UInt8] {
+        var flags: UInt8 = 0
+        var body: [UInt8] = []
+        func append16(_ value: Int) { body.append(UInt8(value & 0xFF)); body.append(UInt8((value >> 8) & 0xFF)) }
+        if bpm > 255 {
+            flags |= 0x01
+            append16(bpm)
+        } else {
+            body.append(UInt8(max(0, bpm)))
+        }
+        if let contact = sensorContact { flags |= 0x04 | (contact ? 0x02 : 0) }
+        if let energy = energyExpended {
+            flags |= 0x08
+            append16(energy)
+        }
+        if !rrIntervals.isEmpty {
+            flags |= 0x10
+            for interval in rrIntervals { append16(Int((interval * 1024 / 1000).rounded())) }
+        }
+        return [flags] + body
+    }
+}
+
+/// A heart-rate strap, or a watch broadcasting its heart rate, read during a
+/// workout: the page's `craft.heartRate` (CraftApp.swift) and a native
+/// screen's `HeartRate` module (CraftNativeActions.swift), one service for
+/// both.
+///
+/// CoreBluetooth central for the standard Heart Rate Service (0x180D):
+/// - `scan` finds what advertises the service nearby (and a strap the phone
+///   is already connected to, which does not advertise), each one a
+///   `{type: 'device'}` event with its name and signal strength.
+/// - `connect` subscribes to Heart Rate Measurement (0x2A37); every reading
+///   is a `{type: 'reading'}` event with bpm and, when the strap sends them,
+///   RR intervals. The device is remembered, and `reconnect` finds it again
+///   next time without a scan.
+/// - A strap that drops out (out of range, the battery, a sweaty contact) is
+///   asked for again until `disconnect`: CoreBluetooth's pending connect
+///   never times out, so it comes back by itself when the strap does.
+/// - `startRecording` keeps every reading on disk until `stopRecording`, as
+///   the location recording keeps fixes: the readings survive the web view
+///   being suspended with the screen locked (the `bluetooth-central`
+///   background mode keeps them coming) and the app being closed.
+///
+/// Connection changes are `{type: 'state'}` events. All of them reach the
+/// page as `craftHeartRate` and every native screen the same way.
+///
+/// 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.
+///
+/// Everything runs on main: the central manager delivers there, and every
+/// caller hops there first.
+final class CraftHeartRate: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate {
+    typealias Completion = (Result<Any, CraftHeartRateError>) -> Void
+
+    static let shared = CraftHeartRate()
+
+    static let serviceUUID = CBUUID(string: "180D")
+    static let measurementUUID = CBUUID(string: "2A37")
+    /// How long `connect` waits before answering TIMEOUT. The connection is
+    /// still asked for after that: a strap only wakes when it is worn.
+    static let connectTimeout: TimeInterval = 15
+    /// A reading older than this is no longer "now".
+    static let staleAfter: TimeInterval = 10
+    /// Fourteen hours of one reading a second: more is not one workout.
+    static let maxRecordedSamples = 50_000
+
+    /// The web view's coordinator, which sends an event 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)?
+
+    private var central: CBCentralManager?
+    private var stateWaiters: [() -> Void] = []
+    private var discovered: [UUID: (peripheral: CBPeripheral?, name: String, rssi: Int)] = [:]
+    private var scanning = false
+    private var scanStop: DispatchWorkItem?
+    private var peripheral: CBPeripheral?
+    private var deviceId: UUID?
+    private var deviceName: String?
+    private var connection = "disconnected"
+    /// Between connect and disconnect: a lost strap is asked for again.
+    private var wantsConnection = false
+    private var connectWaiters: [Completion] = []
+    private var connectDeadline: DispatchWorkItem?
+    private var latest: CraftHeartRateMeasurement?
+    private var latestAt: Date?
+
+    private var recordingId: String?
+    private var recordingStartedAt: Double?
+    private var recordingPaused = false
+    private var recordedCount = 0
+    private var restored = false
+
+    private static let rememberedKey = "CraftHeartRate.lastDevice"
+
+    // MARK: The simulator's stand-in
+
+    /// A strap that is not there: one device, readings once a second.
+    private var simulated: Bool = {
+        #if targetEnvironment(simulator)
+        return UserDefaults.standard.bool(forKey: "CraftFakeHeartRateMonitor")
+        #else
+        return false
+        #endif
+    }()
+    private static let simulatedId = UUID(uuidString: "00000000-0000-4000-8000-00000000180D")!
+    private var simulatedTimer: Timer?
+    private var simulatedBeat = 0
+
+    // MARK: Entry
+
+    /// One call from a page or a native screen, by method name.
+    func perform(method: String, args: [Any], completion: @escaping Completion) {
+        let options = args.first as? [String: Any] ?? [:]
+        DispatchQueue.main.async {
+            self.restoreRecording()
+            switch method {
+            case "getState": completion(.success(self.state()))
+            case "requestAuthorization": self.requestAuthorization(completion: completion)
+            case "scan": self.scan(seconds: (options["timeout"] as? NSNumber)?.doubleValue, completion: completion)
+            case "stopScan":
+                self.stopScan()
+                completion(.success(self.state()))
+            case "getDevices": completion(.success(self.devices()))
+            case "connect": self.connect(id: options["id"] as? String, wait: true, completion: completion)
+            case "reconnect": self.connect(id: nil, wait: false, completion: completion)
+            case "disconnect": self.disconnect(forget: options["forget"] as? Bool ?? false, completion: completion)
+            case "startRecording": self.startRecording(completion: completion)
+            case "pauseRecording": self.setRecordingPaused(true, completion: completion)
+            case "resumeRecording": self.setRecordingPaused(false, completion: completion)
+            case "stopRecording": self.stopRecording(completion: completion)
+            case "getRecordingState": completion(.success(self.recordingSummary(count: true)))
+            case "readRecording": completion(.success(self.loadSamples(since: (options["since"] as? NSNumber)?.doubleValue)))
+            default: completion(.failure(CraftHeartRateError(message: "Unsupported HeartRate method", code: "UNKNOWN_ACTION")))
+            }
+        }
+    }
+
+    // MARK: State
+
+    static func authorizationName(_ value: CBManagerAuthorization) -> String {
+        switch value {
+        case .allowedAlways: return "authorized"
+        case .denied: return "denied"
+        case .restricted: return "restricted"
+        case .notDetermined: return "notDetermined"
+        @unknown default: return "denied"
+        }
+    }
+
+    static func bluetoothName(_ value: CBManagerState) -> String {
+        switch value {
+        case .poweredOn: return "poweredOn"
+        case .poweredOff: return "poweredOff"
+        case .unauthorized: return "unauthorized"
+        case .unsupported: return "unsupported"
+        case .resetting: return "resetting"
+        case .unknown: return "unknown"
+        @unknown default: return "unknown"
+        }
+    }
+
+    private var authorization: String { simulated ? "authorized" : Self.authorizationName(CBManager.authorization) }
+
+    /// "unknown" until something has asked for Bluetooth: reading it would
+    /// make the central manager, and that is what shows iOS's prompt.
+    private var bluetooth: String {
+        if simulated { return "poweredOn" }
+        guard let central else { return "unknown" }
+        return Self.bluetoothName(central.state)
+    }
+
+    private func remembered() -> [String: Any]? {
+        guard let device = UserDefaults.standard.dictionary(forKey: Self.rememberedKey),
+              device["id"] is String else { return nil }
+        return device
+    }
+
+    private func remember(id: UUID, name: String) {
+        UserDefaults.standard.set(["id": id.uuidString, "name": name], forKey: Self.rememberedKey)
+    }
+
+    func state() -> [String: Any] {
+        let fresh = latestAt.map { Date().timeIntervalSince($0) <= Self.staleAfter } ?? false
+        let device: Any = deviceId.map { ["id": $0.uuidString, "name": deviceName ?? "Heart rate monitor"] as [String: Any] } ?? NSNull()
+        return [
+            "available": bluetooth != "unsupported",
+            "bluetooth": bluetooth,
+            "authorization": authorization,
+            "scanning": scanning,
+            "connection": connection,
+            "device": device,
+            "lastDevice": remembered() ?? NSNull(),
+            "bpm": (fresh ? latest?.bpm : nil) ?? NSNull(),
+            "lastReadingAt": latestAt.map { $0.timeIntervalSince1970 * 1000 } ?? NSNull(),
+            "recording": recordingSummary(count: false),
+        ]
+    }
+
+    private func emit(_ detail: [String: Any]) {
+        if pageSink?(detail) != true { CraftWebServices.forward("craftHeartRate", data: detail) }
+    }
+
+    private func emitState() {
+        var detail = state()
+        detail["type"] = "state"
+        emit(detail)
+    }
+
+    // MARK: Bluetooth
+
+    /// The central manager, made on first use: that is when iOS asks.
+    private func whenReady(_ run: @escaping () -> Void) {
+        if simulated { return run() }
+        if central == nil {
+            central = CBCentralManager(delegate: self, queue: nil, options: [CBCentralManagerOptionShowPowerAlertKey: false])
+        }
+        if central!.state == .unknown || central!.state == .resetting {
+            stateWaiters.append(run)
+        } else {
+            run()
+        }
+    }
+
+    /// A reason the radio cannot be used now, or nil when it can.
+    private func unusable() -> CraftHeartRateError? {
+        switch bluetooth {
+        case "poweredOn": return nil
+        case "poweredOff": return CraftHeartRateError(message: "Bluetooth is off", code: "BLUETOOTH_OFF")
+        case "unauthorized": return CraftHeartRateError(message: "Bluetooth access was not allowed", code: "NOT_AUTHORIZED")
+        case "unsupported": return CraftHeartRateError(message: "This device has no Bluetooth", code: "UNSUPPORTED")
+        default: return CraftHeartRateError(message: "Bluetooth is not ready", code: "BLUETOOTH_UNAVAILABLE")
+        }
+    }
+
+    private func requestAuthorization(completion: @escaping Completion) {
+        whenReady { completion(.success(self.authorization)) }
+    }
+
+    func centralManagerDidUpdateState(_ central: CBCentralManager) {
+        let waiting = stateWaiters
+        if central.state != .unknown && central.state != .resetting {
+            stateWaiters.removeAll()
+            waiting.forEach { $0() }
+        }
+        if central.state == .poweredOn {
+            // Bluetooth back on (or on at last): ask for the strap again.
+            if wantsConnection, let peripheral, peripheral.state == .disconnected {
+                connection = "reconnecting"
+                central.connect(peripheral)
+            }
+        } else if central.state != .unknown {
+            scanning = false
+            if wantsConnection && connection != "disconnected" { connection = "reconnecting" }
+        }
+        emitState()
+    }
+
+    // MARK: Scanning
+
+    private func devices() -> [[String: Any]] {
+        discovered
+            .map { id, device in ["id": id.uuidString, "name": device.name, "rssi": device.rssi] as [String: Any] }
+            .sorted { ($0["rssi"] as? Int ?? -200) > ($1["rssi"] as? Int ?? -200) }
+    }
+
+    private func found(id: UUID, peripheral: CBPeripheral?, name: String, rssi: Int) {
+        let known = discovered[id] != nil
+        discovered[id] = (peripheral, name, rssi)
+        if !known { emit(["type": "device", "device": ["id": id.uuidString, "name": name, "rssi": rssi]]) }
+    }
+
+    private func scan(seconds: Double?, completion: @escaping Completion) {
+        whenReady {
+            if let reason = self.unusable() { return completion(.failure(reason)) }
+            self.discovered.removeAll()
+            self.scanning = true
+            if self.simulated {
+                self.found(id: Self.simulatedId, peripheral: nil, name: "Simulated HRM", rssi: -48)
+            } else if let central = self.central {
+                // A strap already connected to this phone (by Settings or
+                // another app) no longer advertises; it is still a choice.
+                for peripheral in central.retrieveConnectedPeripherals(withServices: [Self.serviceUUID]) {
+                    self.found(id: peripheral.identifier, peripheral: peripheral, name: peripheral.name ?? "Heart rate monitor", rssi: 0)
+                }
+                central.scanForPeripherals(withServices: [Self.serviceUUID], options: [CBCentralManagerScanOptionAllowDuplicatesKey: false])
+            }
+            self.scanStop?.cancel()
+            let stop = DispatchWorkItem { [weak self] in self?.stopScan() }
+            self.scanStop = stop
+            DispatchQueue.main.asyncAfter(deadline: .now() + min(max(seconds ?? 15, 1), 60), execute: stop)
+            self.emitState()
+            completion(.success(self.state()))
+        }
+    }
+
+    private func stopScan() {
+        scanStop?.cancel()
+        scanStop = nil
+        guard scanning else { return }
+        scanning = false
+        if central?.state == .poweredOn { central?.stopScan() }
+        emitState()
+    }
+
+    func centralManager(_ central: CBCentralManager, didDiscover peripheral: CBPeripheral, advertisementData: [String: Any], rssi RSSI: NSNumber) {
+        let name = (advertisementData[CBAdvertisementDataLocalNameKey] as? String) ?? peripheral.name ?? "Heart rate monitor"
+        // 127 is CoreBluetooth's "no reading".
+        found(id: peripheral.identifier, peripheral: peripheral, name: name, rssi: RSSI.intValue == 127 ? -100 : RSSI.intValue)
+    }
+
+    // MARK: Connecting
+
+    private func connect(id: String?, wait: Bool, completion: @escaping Completion) {
+        let target = id ?? remembered()?["id"] as? String
+        guard let target, let uuid = UUID(uuidString: target) else {
+            if wait { return completion(.failure(CraftHeartRateError(message: "connect needs the id of a device from scan", code: "INVALID_ARGUMENT"))) }
+            return completion(.success(state()))
+        }
+        whenReady {
+            if let reason = self.unusable() { return completion(.failure(reason)) }
+            // Already there, or on the way: nothing to start again.
+            if self.deviceId == uuid && self.wantsConnection {
+                if self.connection == "connected" || !wait { return completion(.success(self.state())) }
+                self.connectWaiters.append(completion)
+                self.armConnectDeadline()
+                return
+            }
+            self.release()
+            let saved = self.remembered()
+            let savedName = (saved?["id"] as? String) == target ? saved?["name"] as? String : nil
+            let name = self.discovered[uuid]?.name ?? savedName ?? "Heart rate monitor"
+            if self.simulated {
+                guard uuid == Self.simulatedId else { return completion(.failure(CraftHeartRateError(message: "No heart-rate monitor with that id is nearby", code: "NOT_FOUND"))) }
+            } else {
+                let peripheral = self.discovered[uuid]?.peripheral ?? self.central?.retrievePeripherals(withIdentifiers: [uuid]).first
+                guard let peripheral else { return completion(.failure(CraftHeartRateError(message: "No heart-rate monitor with that id is nearby", code: "NOT_FOUND"))) }
+                peripheral.delegate = self
+                self.peripheral = peripheral
+            }
+            self.deviceId = uuid
+            self.deviceName = name
+            self.wantsConnection = true
+            self.connection = "connecting"
+            self.remember(id: uuid, name: name)
+            if wait {
+                self.connectWaiters.append(completion)
+                self.armConnectDeadline()
+            }
+            if self.simulated {
+                DispatchQueue.main.asyncAfter(deadline: .now() + 0.3) { [weak self] in self?.simulatedConnected() }
+            } else if let peripheral = self.peripheral {
+                self.central?.connect(peripheral)
+            }
+            self.emitState()
+            if !wait { completion(.success(self.state())) }
+        }
+    }
+
+    /// `connect` answers TIMEOUT after a while; the strap is still asked
+    /// for, since it may wake up once it is worn.
+    private func armConnectDeadline() {
+        guard connectDeadline == nil else { return }
+        let deadline = DispatchWorkItem { [weak self] in
+            guard let self, self.connection != "connected" else { return }
+            self.settleConnect(.failure(CraftHeartRateError(message: "The heart-rate monitor did not answer. Wear it to wake it up.", code: "TIMEOUT")))
+        }
+        connectDeadline = deadline
+        DispatchQueue.main.asyncAfter(deadline: .now() + Self.connectTimeout, execute: deadline)
+    }
+
+    private func settleConnect(_ result: Result<Any, CraftHeartRateError>) {
+        connectDeadline?.cancel()
+        connectDeadline = nil
+        let waiting = connectWaiters
+        connectWaiters.removeAll()
+        waiting.forEach { $0(result) }
+    }
+
+    /// Lets go of the current strap without telling anyone.
+    private func release() {
+        wantsConnection = false
+        simulatedTimer?.invalidate()
+        simulatedTimer = nil
+        if let peripheral, let central, peripheral.state != .disconnected { central.cancelPeripheralConnection(peripheral) }
+        peripheral = nil
+        deviceId = nil
+        deviceName = nil
+        latest = nil
+        latestAt = nil
+        connection = "disconnected"
+        settleConnect(.failure(CraftHeartRateError(message: "Another heart-rate monitor was chosen", code: "CANCELLED")))
+    }
+
+    private func disconnect(forget: Bool, completion: @escaping Completion) {
+        release()
+        if forget { UserDefaults.standard.removeObject(forKey: Self.rememberedKey) }
+        emitState()
+        completion(.success(state()))
+    }
+
+    func centralManager(_ central: CBCentralManager, didConnect peripheral: CBPeripheral) {
+        guard peripheral.identifier == deviceId else { return }
+        peripheral.delegate = self
+        peripheral.discoverServices([Self.serviceUUID])
+    }
+
+    func centralManager(_ central: CBCentralManager, didFailToConnect peripheral: CBPeripheral, error: Error?) {
+        guard peripheral.identifier == deviceId, wantsConnection else { return }
+        // Asked for again: a failed attempt is usually a strap going to sleep.
+        connection = "reconnecting"
+        central.connect(peripheral)
+        emitState()
+    }
+
+    func centralManager(_ central: CBCentralManager, didDisconnectPeripheral peripheral: CBPeripheral, error: Error?) {
+        guard peripheral.identifier == deviceId else { return }
+        latest = nil
+        latestAt = nil
+        if wantsConnection {
+            connection = "reconnecting"
+            central.connect(peripheral)
+        } else {
+            connection = "disconnected"
+        }
+        emitState()
+    }
+
+    func peripheral(_ peripheral: CBPeripheral, didDiscoverServices error: Error?) {
+        guard let service = peripheral.services?.first(where: { $0.uuid == Self.serviceUUID }) else {
+            notAHeartRateMonitor(peripheral)
+            return
+        }
+        peripheral.discoverCharacteristics([Self.measurementUUID], for: service)
+    }
+
+    func peripheral(_ peripheral: CBPeripheral, didDiscoverCharacteristicsFor service: CBService, error: Error?) {
+        guard let measurement = service.characteristics?.first(where: { $0.uuid == Self.measurementUUID }) else {
+            notAHeartRateMonitor(peripheral)
+            return
+        }
+        peripheral.setNotifyValue(true, for: measurement)
+    }
+
+    func peripheral(_ peripheral: CBPeripheral, didUpdateNotificationStateFor characteristic: CBCharacteristic, error: Error?) {
+        guard characteristic.uuid == Self.measurementUUID, peripheral.identifier == deviceId else { return }
+        if characteristic.isNotifying {
+            connection = "connected"
+            emitState()
+            settleConnect(.success(state()))
+        } else if let error {
+            settleConnect(.failure(CraftHeartRateError(message: error.localizedDescription, code: "CONNECT_FAILED")))
+        }
+    }
+
+    func peripheral(_ peripheral: CBPeripheral, didUpdateValueFor characteristic: CBCharacteristic, error: Error?) {
+        guard characteristic.uuid == Self.measurementUUID, peripheral.identifier == deviceId, let value = characteristic.value else { return }
+        received([UInt8](value))
+    }
+
+    private func notAHeartRateMonitor(_ peripheral: CBPeripheral) {
+        wantsConnection = false
+        central?.cancelPeripheralConnection(peripheral)
+        connection = "disconnected"
+        settleConnect(.failure(CraftHeartRateError(message: "That device does not send a heart rate", code: "NOT_HEART_RATE_MONITOR")))
+        emitState()
+    }
+
+    // MARK: Readings
+
+    private func received(_ bytes: [UInt8]) {
+        // A strap reads 0 between losing the skin and giving up; that is no
+        // heart rate, and neither is anything a heart could not do.
+        guard let reading = CraftHeartRateMeasurement.parse(bytes), reading.bpm >= 20, reading.bpm <= 250 else { return }
+        let now = Date()
+        latest = reading
+        latestAt = now
+        let timestamp = (now.timeIntervalSince1970 * 1000).rounded()
+        let intervals = reading.rrIntervals.map { ($0 * 10).rounded() / 10 }
+        var detail: [String: Any] = [
+            "type": "reading",
+            "bpm": reading.bpm,
+            "rrIntervals": intervals,
+            "contact": reading.sensorContact ?? NSNull(),
+            "energyExpended": reading.energyExpended ?? NSNull(),
+            "timestamp": timestamp,
+        ]
+        if let deviceId { detail["deviceId"] = deviceId.uuidString }
+        appendSample(["timestamp": timestamp, "bpm": reading.bpm, "rr": intervals])
+        emit(detail)
+    }
+
+    private func simulatedConnected() {
+        guard simulated, wantsConnection, deviceId == Self.simulatedId else { return }
+        connection = "connected"
+        emitState()
+        settleConnect(.success(state()))
+        simulatedTimer?.invalidate()
+        simulatedTimer = Timer.scheduledTimer(withTimeInterval: 1, repeats: true) { [weak self] _ in
+            guard let self else { return }
+            self.simulatedBeat += 1
+            // 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]))
+        }
+    }
+
+    // MARK: Recording
+
+    private var directory: URL {
+        FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
+    }
+    private var stateURL: URL { directory.appendingPathComponent("craft-heart-rate-recording-state.json") }
+    private var samplesURL: URL { directory.appendingPathComponent("craft-heart-rate-recording.jsonl") }
+
+    /// A recording that was running when the app last closed carries on.
+    private func restoreRecording() {
+        guard !restored else { return }
+        restored = true
+        guard let data = try? Data(contentsOf: stateURL),
+              let saved = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+              saved["active"] as? Bool == true else { return }
+        recordingId = saved["id"] as? String
+        recordingStartedAt = saved["startedAt"] as? Double
+        recordingPaused = saved["paused"] as? Bool ?? false
+        recordedCount = loadSamples(since: nil).count
+    }
+
+    private func persistRecording() {
+        let saved: [String: Any] = [
+            "active": recordingId != nil,
+            "paused": recordingPaused,
+            "id": recordingId ?? NSNull(),
+            "startedAt": recordingStartedAt ?? NSNull(),
+        ]
+        do {
+            try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+            try JSONSerialization.data(withJSONObject: saved).write(to: stateURL, options: .atomic)
+            protect(stateURL)
+        } catch {
+            print("Unable to persist the heart-rate recording state: \(error)")
+        }
+    }
+
+    private func protect(_ url: URL) {
+        try? FileManager.default.setAttributes([.protectionKey: FileProtectionType.completeUntilFirstUserAuthentication], ofItemAtPath: url.path)
+        var values = URLResourceValues()
+        values.isExcludedFromBackup = true
+        var protectedURL = url
+        try? protectedURL.setResourceValues(values)
+    }
+
+    private func recordingSummary(count: Bool) -> [String: Any] {
+        var summary: [String: Any] = [
+            "id": recordingId ?? NSNull(),
+            "active": recordingId != nil,
+            "paused": recordingPaused,
+            "startedAt": recordingStartedAt ?? NSNull(),
+        ]
+        if count { summary["sampleCount"] = recordedCount }
+        return summary
+    }
+
+    private func startRecording(completion: @escaping Completion) {
+        do {
+            try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+            try Data().write(to: samplesURL, options: .atomic)
+            protect(samplesURL)
+        } catch {
+            return completion(.failure(CraftHeartRateError(message: "Unable to create the heart-rate recording", code: "RECORDING_STORAGE_ERROR")))
+        }
+        recordingId = UUID().uuidString
+        recordingStartedAt = (Date().timeIntervalSince1970 * 1000).rounded()
+        recordingPaused = false
+        recordedCount = 0
+        persistRecording()
+        completion(.success(recordingSummary(count: true)))
+    }
+
+    private func setRecordingPaused(_ paused: Bool, completion: @escaping Completion) {
+        guard recordingId != nil else {
+            return completion(.failure(CraftHeartRateError(message: "No active heart-rate recording", code: "NO_ACTIVE_RECORDING")))
+        }
+        recordingPaused = paused
+        persistRecording()
+        completion(.success(recordingSummary(count: true)))
+    }
+
+    private func stopRecording(completion: @escaping Completion) {
+        var summary = recordingSummary(count: true)
+        summary["active"] = false
+        summary["samples"] = loadSamples(since: nil)
+        recordingId = nil
+        recordingStartedAt = nil
+        recordingPaused = false
+        recordedCount = 0
+        persistRecording()
+        try? FileManager.default.removeItem(at: samplesURL)
+        completion(.success(summary))
+    }
+
+    private func appendSample(_ sample: [String: Any]) {
+        guard recordingId != nil, !recordingPaused, recordedCount < Self.maxRecordedSamples,
+              let json = try? JSONSerialization.data(withJSONObject: sample) else { return }
+        var line = json
+        line.append(0x0A)
+        do {
+            let handle = try FileHandle(forWritingTo: samplesURL)
+            try handle.seekToEnd()
+            try handle.write(contentsOf: line)
+            try handle.close()
+            recordedCount += 1
+        } catch {
+            print("Unable to append a heart-rate sample: \(error)")
+        }
+    }
+
+    /// The recording's samples, oldest first; only those after `since` (ms) when given.
+    private func loadSamples(since: Double?) -> [[String: Any]] {
+        guard let text = try? String(contentsOf: samplesURL, encoding: .utf8) else { return [] }
+        return text.split(separator: "\n").compactMap { line in
+            guard let data = line.data(using: .utf8),
+                  let sample = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else { return nil }
+            if let since, ((sample["timestamp"] as? NSNumber)?.doubleValue ?? 0) <= since { return nil }
+            return sample
+        }
+    }
+}

package/templates/CraftNativeActions.swift

@@ -61,6 +61,9 @@ enum CraftNativeActions {
         if config.enableGeolocation && config.renderer != "native" { values.append("geolocation") }
         // The Music app's song and transport are the coordinator's too.
         if config.enableAppleMusic && config.renderer != "native" { values.append("music") }
+        // A heart-rate strap is the app's own service (CraftHeartRate.swift),
+        // so it needs no web view.
+        if config.enableHeartRate { values.append("heartRate") }
         return values
     }
 
@@ -290,6 +293,19 @@ enum CraftNativeActions {
             }
             CraftWebServices.perform(action: action, body: args.first as? [String: Any] ?? [:]) { complete(requestToken, $0, completion) }
             return
+        case ("HeartRate", _):
+            // A Bluetooth heart-rate strap, the same service as a page's
+            // `craft.heartRate`: one connection and one recording, whichever
+            // side started them. Its events reach every screen as
+            // `craftHeartRate`.
+            guard config.enableHeartRate else {
+                complete(requestToken, failure("CAPABILITY_DISABLED", "Heart rate is disabled"), completion)
+                return
+            }
+            CraftHeartRate.shared.perform(method: method, args: args) { result in
+                complete(requestToken, result.mapError { CraftNativeActionError(code: $0.code, message: $0.message) }, completion)
+            }
+            return
         case ("Linking", "openURL"), ("Linking", "canOpenURL"):
             // Another app or the system: `webcal:` subscriptions, `mailto:`,
             // `tel:`, the App Store, this app's page in Settings