craft-native 0.0.151 → 0.0.152

package/dist/api/mobile.d.ts

@@ -825,6 +825,118 @@ export declare const music: {
      */
     onChange(callback: (nowPlaying: NowPlaying) => void): () => void;
 };
+export type HeartRateAuthorization = 'authorized' | 'denied' | 'restricted' | 'notDetermined' | 'unavailable';
+export type BluetoothState = 'poweredOn' | 'poweredOff' | 'unauthorized' | 'unsupported' | 'resetting' | 'unknown';
+export type HeartRateConnection = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+export interface HeartRateDevice {
+    id: string;
+    name: string;
+    /** Signal strength, dBm; 0 for a strap the phone is already connected to. */
+    rssi: number | null;
+}
+export interface HeartRateRecordingState {
+    id: string | null;
+    active: boolean;
+    paused: boolean;
+    /** ms since the epoch. */
+    startedAt: number | null;
+    sampleCount: number | null;
+}
+export interface HeartRateState {
+    /** False off a phone, in a build without `enableHeartRate`, or on a phone without Bluetooth. */
+    available: boolean;
+    bluetooth: BluetoothState;
+    authorization: HeartRateAuthorization;
+    scanning: boolean;
+    connection: HeartRateConnection;
+    /** The strap connected, or being connected to. */
+    device: HeartRateDevice | null;
+    /** The strap `reconnect()` asks for. */
+    lastDevice: HeartRateDevice | null;
+    /** The latest reading while it is fresh (ten seconds), else null. */
+    bpm: number | null;
+    lastReadingAt: number | null;
+    recording: HeartRateRecordingState;
+}
+export interface HeartRateReading {
+    bpm: number;
+    /** Milliseconds between beats, oldest first; empty when the strap sends none. */
+    rrIntervals: number[];
+    /** Whether the strap touches skin; null when it cannot tell. */
+    contact: boolean | null;
+    energyExpended: number | null;
+    /** ms since the epoch. */
+    timestamp: number;
+    deviceId: string | null;
+}
+/** A reading as a recording keeps it. */
+export interface HeartRateSample {
+    /** ms since the epoch. */
+    timestamp: number;
+    bpm: number;
+    /** Milliseconds between beats, when the strap sent them. */
+    rr?: number[];
+}
+export type HeartRateMethod = 'getState' | 'requestAuthorization' | 'scan' | 'stopScan' | 'getDevices' | 'connect' | 'reconnect' | 'disconnect' | 'startRecording' | 'pauseRecording' | 'resumeRecording' | 'stopRecording' | 'getRecordingState' | 'readRecording';
+export declare function normalizeHeartRateDevice(value: unknown): HeartRateDevice | null;
+/** A state from native, made safe to render whatever an older or newer build sent. */
+export declare function normalizeHeartRateState(value: unknown): HeartRateState;
+/** A reading event's detail, or null for one that is not a usable reading. */
+export declare function normalizeHeartRateReading(value: unknown): HeartRateReading | null;
+/** A recording's samples, oldest first, one per timestamp, implausible ones left out. */
+export declare function normalizeHeartRateSamples(value: unknown): HeartRateSample[];
+export declare const heartRate: {
+    /** Whether this app can read a heart-rate strap. */
+    isAvailable(): boolean;
+    /** Whether this app build answers `method`; an older build may lack one. */
+    supports(method: HeartRateMethod): boolean;
+    /** Bluetooth, the connection, the strap and its latest reading, without asking anything. */
+    getState: () => Promise<HeartRateState>;
+    /**
+     * Ask for Bluetooth: iOS's prompt the first time, its remembered answer
+     * after that. Scanning and connecting ask too; call this from the person's
+     * tap to ask first.
+     */
+    requestAuthorization: () => Promise<HeartRateAuthorization>;
+    /** Look for straps for `timeout` seconds (15 by default); `onDevice` hears each one. */
+    scan: (options?: {
+        timeout?: number;
+    }) => Promise<HeartRateState>;
+    stopScan: () => Promise<HeartRateState>;
+    /** What the last scan found, strongest signal first. */
+    getDevices: () => Promise<HeartRateDevice[]>;
+    /**
+     * Connect to a strap from `scan` and subscribe to its readings; it is
+     * remembered for `reconnect()`. Rejects with code TIMEOUT when it does not
+     * answer within 15 s, while still asking for it: a strap wakes up when worn.
+     */
+    connect: (id: string) => Promise<HeartRateState>;
+    /** Ask for the remembered strap again, without waiting for it. */
+    reconnect: () => Promise<HeartRateState>;
+    /** Stop asking for the strap; `forget` also drops it from memory. */
+    disconnect: (options?: {
+        forget?: boolean;
+    }) => Promise<HeartRateState>;
+    /** Keep every reading natively from now on: screen locked, page suspended or app closed. */
+    startRecording: () => Promise<HeartRateRecordingState>;
+    pauseRecording: () => Promise<HeartRateRecordingState>;
+    resumeRecording: () => Promise<HeartRateRecordingState>;
+    /** Ends the recording and hands back every reading it kept. */
+    stopRecording: () => Promise<HeartRateRecordingState & {
+        samples: HeartRateSample[];
+    }>;
+    getRecordingState: () => Promise<HeartRateRecordingState>;
+    /** The recording so far; only what came after `since` (ms) when given. */
+    readRecording: (options?: {
+        since?: number;
+    }) => Promise<HeartRateSample[]>;
+    /** Every reading from the connected strap, about once a second. */
+    onReading: (callback: (reading: HeartRateReading) => void) => (() => void);
+    /** Each strap a scan finds. */
+    onDevice: (callback: (device: HeartRateDevice) => void) => (() => void);
+    /** Bluetooth, scanning or the connection changed. */
+    onState: (callback: (state: HeartRateState) => void) => (() => void);
+};
 export declare const deepLinks: {
     getInitialURL(): Promise<string | null>;
     /**
@@ -1308,6 +1420,7 @@ declare const mobile: {
     brightness: typeof brightness;
     speech: typeof speech;
     music: typeof music;
+    heartRate: typeof heartRate;
     deepLinks: typeof deepLinks;
     network: typeof network;
     appReview: typeof appReview;

package/dist/cli.js

@@ -3303,7 +3303,7 @@ function pinCraftNativeDependency(packagePath, craftVersion) {
 `);
 }
 // package.json
-var version = "0.0.151";
+var version = "0.0.152";
 
 // bin/cli.ts
 var spawnedFrom = process6.env[CRAFT_CLI_SPAWN_MARKER];

package/dist/index.cjs

@@ -310,7 +310,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.151";
+var version = "0.0.152";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;
@@ -5325,6 +5325,7 @@ var notifications = {
 };
 var speakingOnTheWeb = new Set;
 var musicWatch = { listeners: new Set, stop: null };
+var heartRateWatch = { readings: new Set, devices: new Set, states: new Set, stop: null };
 function onCraftEvent(eventName, callback) {
   if (typeof globalThis === "undefined")
     return () => {};

package/dist/index.js

@@ -58,7 +58,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.151";
+var version = "0.0.152";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;
@@ -5085,6 +5085,7 @@ var notifications = {
 };
 var speakingOnTheWeb = new Set;
 var musicWatch = { listeners: new Set, stop: null };
+var heartRateWatch = { readings: new Set, devices: new Set, states: new Set, stop: null };
 function onCraftEvent(eventName, callback) {
   if (typeof globalThis === "undefined")
     return () => {};

package/dist/ios/src/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/ios/src/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/dist/ios/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/dist/ios/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/dist/ios/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

package/dist/mobile.js

@@ -823,6 +823,164 @@ var music = {
     };
   }
 };
+var HR_AUTHORIZATIONS = ["authorized", "denied", "restricted", "notDetermined", "unavailable"];
+var HR_BLUETOOTH = ["poweredOn", "poweredOff", "unauthorized", "unsupported", "resetting", "unknown"];
+var HR_CONNECTIONS = ["disconnected", "connecting", "connected", "reconnecting"];
+function hrRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function hrNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function hrBpm(value) {
+  const bpm = hrNumber(value);
+  return bpm !== null && bpm >= 20 && bpm <= 250 ? Math.round(bpm) : null;
+}
+function hrIntervals(value) {
+  return Array.isArray(value) ? value.filter((ms) => typeof ms === "number" && Number.isFinite(ms) && ms > 0 && ms < 5000) : [];
+}
+function normalizeHeartRateDevice(value) {
+  const raw = hrRecord(value);
+  if (typeof raw.id !== "string" || !raw.id)
+    return null;
+  return { id: raw.id, name: typeof raw.name === "string" && raw.name.trim() ? raw.name : "Heart rate monitor", rssi: hrNumber(raw.rssi) };
+}
+function normalizeHeartRateRecording(value) {
+  const raw = hrRecord(value);
+  return {
+    id: typeof raw.id === "string" ? raw.id : null,
+    active: raw.active === true,
+    paused: raw.paused === true,
+    startedAt: hrNumber(raw.startedAt),
+    sampleCount: hrNumber(raw.sampleCount)
+  };
+}
+function normalizeHeartRateState(value) {
+  const raw = hrRecord(value);
+  return {
+    available: raw.available !== false && Object.keys(raw).length > 0,
+    bluetooth: HR_BLUETOOTH.includes(raw.bluetooth) ? raw.bluetooth : "unknown",
+    authorization: HR_AUTHORIZATIONS.includes(raw.authorization) ? raw.authorization : "unavailable",
+    scanning: raw.scanning === true,
+    connection: HR_CONNECTIONS.includes(raw.connection) ? raw.connection : "disconnected",
+    device: normalizeHeartRateDevice(raw.device),
+    lastDevice: normalizeHeartRateDevice(raw.lastDevice),
+    bpm: hrBpm(raw.bpm),
+    lastReadingAt: hrNumber(raw.lastReadingAt),
+    recording: normalizeHeartRateRecording(raw.recording)
+  };
+}
+function normalizeHeartRateReading(value) {
+  const raw = hrRecord(value);
+  const bpm = hrBpm(raw.bpm);
+  if (bpm === null)
+    return null;
+  return {
+    bpm,
+    rrIntervals: hrIntervals(raw.rrIntervals),
+    contact: typeof raw.contact === "boolean" ? raw.contact : null,
+    energyExpended: hrNumber(raw.energyExpended),
+    timestamp: hrNumber(raw.timestamp) ?? Date.now(),
+    deviceId: typeof raw.deviceId === "string" ? raw.deviceId : null
+  };
+}
+function normalizeHeartRateSamples(value) {
+  if (!Array.isArray(value))
+    return [];
+  const seen = new Set;
+  const samples = [];
+  for (const item of value) {
+    const raw = hrRecord(item);
+    const timestamp = hrNumber(raw.timestamp);
+    const bpm = hrBpm(raw.bpm);
+    if (timestamp === null || bpm === null || seen.has(timestamp))
+      continue;
+    seen.add(timestamp);
+    const rr = hrIntervals(raw.rr);
+    samples.push(rr.length ? { timestamp, bpm, rr } : { timestamp, bpm });
+  }
+  return samples.sort((a, b) => a.timestamp - b.timestamp);
+}
+function noHeartRate() {
+  return normalizeHeartRateState({ available: false });
+}
+function nativeHeartRate() {
+  const craft = getCraftRoot();
+  if (!craft?.heartRate || craft.capabilities?.heartRate === false)
+    return;
+  return craft.heartRate;
+}
+var heartRateWatch = { readings: new Set, devices: new Set, states: new Set, stop: null };
+function hrNotify(listeners, value) {
+  for (const listener of [...listeners]) {
+    try {
+      listener(value);
+    } catch {}
+  }
+}
+function hrSubscribe(set, callback) {
+  if (!nativeHeartRate() || typeof window === "undefined")
+    return () => {};
+  set.add(callback);
+  if (!heartRateWatch.stop) {
+    const onEvent = (event) => {
+      const detail = hrRecord(event.detail);
+      if (detail.type === "reading") {
+        const reading = normalizeHeartRateReading(detail);
+        if (reading)
+          hrNotify(heartRateWatch.readings, reading);
+      } else if (detail.type === "device") {
+        const device2 = normalizeHeartRateDevice(detail.device);
+        if (device2)
+          hrNotify(heartRateWatch.devices, device2);
+      } else if (detail.type === "state") {
+        hrNotify(heartRateWatch.states, normalizeHeartRateState(detail));
+      }
+    };
+    window.addEventListener("craftHeartRate", onEvent);
+    heartRateWatch.stop = () => window.removeEventListener("craftHeartRate", onEvent);
+  }
+  return () => {
+    if (!set.delete(callback))
+      return;
+    if (heartRateWatch.readings.size + heartRateWatch.devices.size + heartRateWatch.states.size > 0)
+      return;
+    heartRateWatch.stop?.();
+    heartRateWatch.stop = null;
+  };
+}
+async function heartRateCall(method, fallback, normalize, ...args) {
+  const native = nativeHeartRate();
+  if (typeof native?.[method] !== "function")
+    return fallback();
+  return normalize(await native[method](...args));
+}
+var noRecording = () => normalizeHeartRateRecording({});
+var heartRate = {
+  isAvailable() {
+    return typeof nativeHeartRate()?.getState === "function";
+  },
+  supports(method) {
+    return typeof nativeHeartRate()?.[method] === "function";
+  },
+  getState: () => heartRateCall("getState", noHeartRate, normalizeHeartRateState),
+  requestAuthorization: () => heartRateCall("requestAuthorization", () => "unavailable", (value) => HR_AUTHORIZATIONS.includes(value) ? value : "unavailable"),
+  scan: (options = {}) => heartRateCall("scan", noHeartRate, normalizeHeartRateState, options),
+  stopScan: () => heartRateCall("stopScan", noHeartRate, normalizeHeartRateState),
+  getDevices: () => heartRateCall("getDevices", () => [], (value) => Array.isArray(value) ? value.map(normalizeHeartRateDevice).filter((device2) => device2 !== null) : []),
+  connect: (id) => heartRateCall("connect", noHeartRate, normalizeHeartRateState, id),
+  reconnect: () => heartRateCall("reconnect", noHeartRate, normalizeHeartRateState),
+  disconnect: (options = {}) => heartRateCall("disconnect", noHeartRate, normalizeHeartRateState, options),
+  startRecording: () => heartRateCall("startRecording", noRecording, normalizeHeartRateRecording),
+  pauseRecording: () => heartRateCall("pauseRecording", noRecording, normalizeHeartRateRecording),
+  resumeRecording: () => heartRateCall("resumeRecording", noRecording, normalizeHeartRateRecording),
+  stopRecording: () => heartRateCall("stopRecording", () => ({ ...noRecording(), samples: [] }), (value) => ({ ...normalizeHeartRateRecording(value), samples: normalizeHeartRateSamples(hrRecord(value).samples) })),
+  getRecordingState: () => heartRateCall("getRecordingState", noRecording, normalizeHeartRateRecording),
+  readRecording: (options = {}) => heartRateCall("readRecording", () => [], normalizeHeartRateSamples, options),
+  onReading: (callback) => hrSubscribe(heartRateWatch.readings, callback),
+  onDevice: (callback) => hrSubscribe(heartRateWatch.devices, callback),
+  onState: (callback) => hrSubscribe(heartRateWatch.states, callback)
+};
 var deepLinks = {
   async getInitialURL() {
     return normalizeDeepLinkURL(await getCraftRoot()?.deepLinks?.getInitialURL?.());
@@ -1314,6 +1472,10 @@ export {
   permissions,
   notifications,
   normalizeNowPlaying,
+  normalizeHeartRateState,
+  normalizeHeartRateSamples,
+  normalizeHeartRateReading,
+  normalizeHeartRateDevice,
   normalizeDeepLinkURL,
   network,
   music,
@@ -1323,6 +1485,7 @@ export {
   keepAwake,
   isSnapshotName,
   hybrid,
+  heartRate,
   health,
   haptics,
   dialog,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "craft-native",
-  "version": "0.0.151",
+  "version": "0.0.152",
   "type": "module",
   "description": "Build desktop apps with web languages - TypeScript SDK for Craft",
   "author": "Chris Breuer <chris@stacksjs.org>",