craft-native 0.0.436 → 0.0.443

package/dist/installer-background.d.ts

@@ -0,0 +1,2 @@
+/** Shared drag-to-Applications artwork, embedded so packaged SDKs need no external files. */
+export declare const installerBackground: Buffer;

package/dist/installer-layout.d.ts

@@ -0,0 +1 @@
+export declare function writeInstallerLayout(mount: string, volume: string, appName: string): void;

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

@@ -84,12 +84,20 @@ export interface CraftConfig {
     enableAudioRecording?: boolean;
     enableVideoRecording?: boolean;
     enableMotionSensors?: boolean;
+    /** Core Motion relative altitude and pressure; includes the motion usage description. */
+    enableBarometer?: boolean;
+    /** Core Motion interval steps, cadence and seven-day device history. */
+    enablePedometer?: boolean;
     /** Shaking the phone raises a `shake` event. Arms the accelerometer while the app is in front. */
     enableShakeGesture?: boolean;
     enableLocalDatabase?: boolean;
     enableBluetooth?: boolean;
     enableNFC?: boolean;
     enableHealthKit?: boolean;
+    /** Observe declared HealthKit types on background wakes; requires enableHealthKit. */
+    enableHealthKitBackground?: boolean;
+    healthKitBackgroundTypes?: Array<'steps' | 'heartRate' | 'restingHeartRate' | 'heartRateVariability' | 'activeEnergy' | 'distance' | 'bodyMass' | 'sleep' | 'workouts'>;
+    healthKitBackgroundFrequency?: 'immediate' | 'hourly' | 'daily' | 'weekly';
     /** Native Apple Wallet pass presentation and lookup for native screens. */
     enableWallet?: boolean;
     enableLiveActivities?: boolean;
@@ -200,7 +208,9 @@ export interface CraftConfig {
      * screen until the page says it is ready (`splash.hide()`), so the app goes
      * from launch to content without a blank web view in between. PNG, PDF or
      * SVG, drawn at its own size in points: give an SVG the width and height it
-     * should have on screen.
+     * should have on screen. A PNG with `@2x` and `@3x` files beside it
+     * (`LaunchLogo.png`, `LaunchLogo@2x.png`, `LaunchLogo@3x.png`, as ts-images'
+     * `generateSplashScreens` writes them) is sharp on every screen.
      */
     splashImagePath?: string;
     /** The splash logo in Dark Mode, on `backgroundColorDark`. The light one if unset. */
@@ -361,6 +371,8 @@ export declare function hybridConfigProblems(config: Pick<CraftConfig, 'renderer
  * well as the one-file bundle, and the app runs each screen from its own
  * route's file. Stacks asks for route bundles only when this is true.
  */
+/** Build-time proof for Stacks capability mappings, including unreleased source builds. */
+export declare const nativeSensorCapabilities: readonly ['barometer', 'pedometer', 'healthKitBackground'];
 export declare const nativeRouteBundles = true;
 /**
  * The app evaluates stx's shared runtime (`__runtime.js`, stx's
@@ -522,6 +534,16 @@ export declare function renderPrivacyManifest(config: CraftConfig): string;
 export declare function pngHasAlpha(bytes: Uint8Array): boolean;
 /** The asset the launch screen and the splash both draw, so one hands over to the other unseen. */
 export declare const LAUNCH_LOGO = "LaunchLogo";
+/**
+ * A bitmap splash's `@2x` and `@3x` files beside it (`LaunchLogo.png`,
+ * `LaunchLogo@2x.png`, `LaunchLogo@3x.png`, as ts-images'
+ * `generateSplashScreens` writes them), by scale. A bitmap without them is
+ * one image, drawn at its pixel size in points.
+ */
+export declare function splashScales(source: string): Array<{
+    scale: 1 | 2 | 3;
+    path: string;
+}>;
 /** The launch screen: the background colour, and the splash logo on it when there is one. */
 export declare function renderLaunchScreen(config: Pick<CraftConfig, 'splashImagePath'>): string;
 /** Near-black or near-white, whichever reads on `background` (WCAG relative luminance). */

package/dist/ios/src/index.js

@@ -18,7 +18,7 @@ function iosPermissions(config) {
     contacts: config.enableContacts,
     calendar: config.enableCalendar,
     bluetooth: config.enableBluetooth || config.enableHeartRate,
-    motion: config.enableMotionSensors || config.enableShakeGesture,
+    motion: config.enableMotionSensors || config.enableShakeGesture || config.enableBarometer || config.enablePedometer,
     biometric: config.enableBiometric,
     music: config.enableAppleMusic,
     health: config.enableHealthKit,
@@ -618,6 +618,7 @@ function hybridConfigProblems(config) {
     problems.push(`nativeScriptThread "${String(config.nativeScriptThread)}" must be "main" or "background".`);
   return problems;
 }
+var nativeSensorCapabilities = ["barometer", "pedometer", "healthKitBackground"];
 var nativeRouteBundles = true;
 var nativeRouteRuntime = true;
 var nativeMessages = true;
@@ -701,11 +702,16 @@ var DEFAULT_CONFIG = {
   enableAudioRecording: false,
   enableVideoRecording: false,
   enableMotionSensors: false,
+  enableBarometer: false,
+  enablePedometer: false,
   enableShakeGesture: false,
   enableLocalDatabase: false,
   enableBluetooth: false,
   enableNFC: false,
   enableHealthKit: false,
+  enableHealthKitBackground: false,
+  healthKitBackgroundTypes: [],
+  healthKitBackgroundFrequency: "hourly",
   enableWallet: false,
   enableLiveActivities: false,
   enableWatchApp: false,
@@ -762,7 +768,7 @@ function renderUsageDescriptions(config) {
     [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 || 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.enableMotionSensors || config.enableBarometer || config.enablePedometer, "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.`],
     [config.enableHealthKit, "NSHealthShareUsageDescription", `${config.appName} reads health data you choose to share.`],
@@ -871,8 +877,24 @@ ${plistArray([identifier])}
 function associatedDomainEntries(domains) {
   return [...new Set((domains ?? []).map((value) => value.trim()).filter(Boolean).map((value) => /^[a-z]+:/i.test(value) ? value : `applinks:${value}`))];
 }
+function validateHealthKitBackground(config) {
+  if (!config.enableHealthKitBackground)
+    return;
+  if (!config.enableHealthKit)
+    throw new Error("enableHealthKitBackground requires enableHealthKit");
+  const types = config.healthKitBackgroundTypes;
+  const supported = ["steps", "heartRate", "restingHeartRate", "heartRateVariability", "activeEnergy", "distance", "bodyMass", "sleep", "workouts"];
+  if (!Array.isArray(types) || !types.length || types.some((type) => !supported.includes(type)))
+    throw new Error("healthKitBackgroundTypes must declare supported HealthKit sample types");
+  if (!["immediate", "hourly", "daily", "weekly"].includes(config.healthKitBackgroundFrequency ?? "hourly"))
+    throw new Error("healthKitBackgroundFrequency must be immediate, hourly, daily or weekly");
+}
 function renderEntitlements(config) {
+  validateHealthKitBackground(config);
   const entries = [];
+  if (config.enableHealthKitBackground)
+    entries.push(`    <key>com.apple.developer.healthkit.background-delivery</key>
+    <true/>`);
   const associatedDomains = associatedDomainEntries(config.associatedDomains);
   if (associatedDomains.length) {
     entries.push(`    <key>com.apple.developer.associated-domains</key>
@@ -1085,6 +1107,14 @@ function renderAssetCatalog(output, config) {
   renderLaunchLogo(catalog, config);
 }
 var LAUNCH_LOGO = "LaunchLogo";
+function splashScales(source) {
+  const extension = extname(source);
+  if (!/^\.(?:png|jpe?g)$/i.test(extension))
+    return [{ scale: 1, path: source }];
+  const stem = source.slice(0, -extension.length);
+  const scales = [2, 3].map((scale) => ({ scale, path: `${stem}@${scale}x${extension}` })).filter((item) => existsSync2(item.path));
+  return scales.length ? [{ scale: 1, path: source }, ...scales] : [{ scale: 1, path: source }];
+}
 function renderLaunchLogo(catalog, config) {
   const imageset = join4(catalog, `${LAUNCH_LOGO}.imageset`);
   rmSync3(imageset, { recursive: true, force: true });
@@ -1101,13 +1131,18 @@ function renderLaunchLogo(catalog, config) {
     const extension = source.split(".").pop().toLowerCase();
     if (extension === "svg" || extension === "pdf")
       vector = true;
-    const filename = `${LAUNCH_LOGO}${dark ? "-dark" : ""}.${extension}`;
-    cpSync(source, join4(imageset, filename));
-    images.push({
-      ...dark ? { appearances: [{ appearance: "luminosity", value: "dark" }] } : {},
-      filename,
-      idiom: "universal"
-    });
+    const files = splashScales(source);
+    const scaled = files.length > 1;
+    for (const { scale, path } of files) {
+      const filename = `${LAUNCH_LOGO}${dark ? "-dark" : ""}${scale === 1 ? "" : `@${scale}x`}.${extension}`;
+      cpSync(path, join4(imageset, filename));
+      images.push({
+        ...dark ? { appearances: [{ appearance: "luminosity", value: "dark" }] } : {},
+        filename,
+        idiom: "universal",
+        ...scaled ? { scale: `${scale}x` } : {}
+      });
+    }
   }
   writeFileSync3(join4(imageset, "Contents.json"), `${JSON.stringify({
     images,
@@ -1358,6 +1393,8 @@ function writeShell(output, config) {
   writeSource(join4(output, "Sources", "CraftNativeScreen.swift"), readFileSync3(join4(TEMPLATES_DIR, "CraftNativeScreen.swift"), "utf8"));
   writeSource(join4(output, "Sources", "CraftNativeFlatList.swift"), readFileSync3(join4(TEMPLATES_DIR, "CraftNativeFlatList.swift"), "utf8"));
   writeSource(join4(output, "Sources", "CraftNativeActions.swift"), readFileSync3(join4(TEMPLATES_DIR, "CraftNativeActions.swift"), "utf8"));
+  writeSource(join4(output, "Sources", "CraftNativePedometer.swift"), readFileSync3(join4(TEMPLATES_DIR, "CraftNativePedometer.swift"), "utf8"));
+  writeSource(join4(output, "Sources", "CraftHealthBackground.swift"), readFileSync3(join4(TEMPLATES_DIR, "CraftHealthBackground.swift"), "utf8"));
   writeSource(join4(output, "Sources", "CraftHealth.swift"), readFileSync3(join4(TEMPLATES_DIR, "CraftHealth.swift"), "utf8"));
   writeSource(join4(output, "Sources", "CraftMusic.swift"), readFileSync3(join4(TEMPLATES_DIR, "CraftMusic.swift"), "utf8"));
   writeSource(join4(output, "Sources", "CraftBluetooth.swift"), readFileSync3(join4(TEMPLATES_DIR, "CraftBluetooth.swift"), "utf8"));
@@ -1424,6 +1461,7 @@ async function init(options) {
     teamId: teamId || "",
     ...given
   };
+  validateHealthKitBackground(config);
   if (config.renderer !== "web" && config.renderer !== "native") {
     throw new Error(`Unknown iOS renderer: ${config.renderer}. Expected web or native.`);
   }
@@ -1784,6 +1822,7 @@ export {
   nativeMessages,
   nativeRouteBundles,
   nativeRouteRuntime,
+  nativeSensorCapabilities,
   nativeStartPath,
   normalizeNativePath,
   open,
@@ -1815,6 +1854,7 @@ export {
   runPostGenerateHook,
   serializeSimulatorSteps,
   showSimulator,
+  splashScales,
   syncNativeFonts,
   syncWebAssets,
   usesNativeBundle

package/dist/ios/templates/CraftApp.swift

@@ -299,6 +299,15 @@ final class CraftAppDelegate: NSObject, UIApplicationDelegate, UNUserNotificatio
         // push, a refresh, a route recording's location) draws nothing, and
         // its events still need someone to hear them.
         CraftHybrid.shared.configure(config)
+        CraftHealthBackground.shared.emit = { type in
+            let detail: [String: Any] = ["type": type]
+            CraftEventManager.shared.sendToWeb("craftHealthBackground", data: detail)
+            NotificationCenter.default.post(name: CraftWebServices.event, object: nil,
+                userInfo: ["event": "craftHealthBackground", "detail": detail])
+        }
+        CraftHealthBackground.shared.configure(types: config.enableHealthKit && config.enableHealthKitBackground ? config.healthKitBackgroundTypes : [],
+            frequency: config.healthKitBackgroundFrequency)
+
         if let shortcuts = config.appShortcuts {
             application.shortcutItems = shortcuts.prefix(4).map { shortcut in
                 UIApplicationShortcutItem(type: shortcut.id, localizedTitle: shortcut.title, localizedSubtitle: shortcut.subtitle,
@@ -1830,6 +1839,8 @@ struct CraftConfig: Codable {
     var enableAudioRecording: Bool = false
     var enableVideoRecording: Bool = false
     var enableMotionSensors: Bool = false
+    var enableBarometer: Bool = false
+    var enablePedometer: Bool = false
     /// Shaking the phone raises a `shake` event, for a report-a-problem
     /// gesture. Its own flag rather than a corner of `enableMotionSensors`,
     /// because it arms the accelerometer for as long as the app is in front:
@@ -1839,6 +1850,9 @@ struct CraftConfig: Codable {
     var enableBluetooth: Bool = false
     var enableNFC: Bool = false
     var enableHealthKit: Bool = false
+    var enableHealthKitBackground: Bool = false
+    var healthKitBackgroundTypes: [String] = []
+    var healthKitBackgroundFrequency: String = "hourly"
     /// Apple Wallet pass presentation and lookup for native screens.
     var enableWallet: Bool = false
     var enableLiveActivities: Bool = false

package/dist/ios/templates/CraftHealth.swift

@@ -227,6 +227,7 @@ final class CraftHealth {
         if readOnly { shareTypes.removeAll() }
         healthStore.requestAuthorization(toShare: shareTypes, read: readTypes) { [weak self] success, error in
             if success {
+                DispatchQueue.main.async { CraftHealthBackground.shared.refresh() }
                 completion(.success(true))
             } else {
                 completion(.failure(CraftHealthError(message: error?.localizedDescription ?? "Authorization failed")))
@@ -401,7 +402,7 @@ final class CraftHealth {
 
     /// The quantity behind each health data type, its unit, and the one
     /// statistic that type supports.
-    private static func healthQuantity(_ type: String) -> (type: HKQuantityType?, unit: HKUnit, options: HKStatisticsOptions)? {
+    static func healthQuantity(_ type: String) -> (type: HKQuantityType?, unit: HKUnit, options: HKStatisticsOptions)? {
         let bpm = HKUnit.count().unitDivided(by: .minute())
         switch type {
         case "steps": return (HKQuantityType.quantityType(forIdentifier: .stepCount), .count(), .cumulativeSum)

package/dist/ios/templates/CraftHealthBackground.swift

@@ -0,0 +1,308 @@
+import Foundation
+#if CRAFT_PERMISSION_HEALTH
+import HealthKit
+#endif
+
+struct CraftHealthBackgroundSample: Codable {
+    let id: String
+    let startDate: Double
+    let endDate: Double
+    var value: Double?
+    var unit: String?
+    var category: Int?
+    var workoutActivity: UInt?
+    var durationSeconds: Double?
+}
+
+struct CraftHealthBackgroundPage {
+    let anchor: Data
+    let samples: [CraftHealthBackgroundSample]
+    let deleted: [String]
+    let more: Bool
+}
+
+struct CraftHealthBackgroundBatch: Codable {
+    let id: String
+    let type: String
+    let samples: [CraftHealthBackgroundSample]
+    let deleted: [String]
+}
+
+struct CraftHealthBackgroundState: Codable {
+    var anchors: [String: Data] = [:]
+    var observedTypes: [String]? = nil
+    var batches: [CraftHealthBackgroundBatch] = []
+}
+
+/// An atomic snapshot keeps a new anchor inseparable from its unconsumed delta.
+protocol CraftHealthBackgroundPersistence {
+    func load() throws -> CraftHealthBackgroundState
+    func save(_ state: CraftHealthBackgroundState) throws
+}
+
+final class CraftHealthBackgroundFile: CraftHealthBackgroundPersistence {
+    private let url: URL
+    init(url: URL) { self.url = url }
+    func load() throws -> CraftHealthBackgroundState {
+        guard FileManager.default.fileExists(atPath: url.path) else { return CraftHealthBackgroundState() }
+        return try JSONDecoder().decode(CraftHealthBackgroundState.self, from: Data(contentsOf: url))
+    }
+    func save(_ state: CraftHealthBackgroundState) throws {
+        let data = try JSONEncoder().encode(state)
+        guard data.count <= 8 * 1024 * 1024 else { throw CraftHealthBackgroundError.outboxFull }
+        try FileManager.default.createDirectory(at: url.deletingLastPathComponent(), withIntermediateDirectories: true,
+            attributes: [.protectionKey: FileProtectionType.completeUntilFirstUserAuthentication])
+        try data.write(to: url, options: [.atomic, .completeFileProtectionUntilFirstUserAuthentication])
+        var excluded = url
+        var values = URLResourceValues()
+        values.isExcludedFromBackup = true
+        try excluded.setResourceValues(values)
+    }
+}
+
+enum CraftHealthBackgroundError: Error { case unavailable, outboxFull, invalidAnchor, missingAnchor }
+
+/// All callbacks and ownership transitions are serialized on the main queue.
+protocol CraftHealthBackgroundSource {
+    func observe(type: String, update: @escaping (Error?, @escaping () -> Void) -> Void) -> () -> Void
+    func enable(type: String, frequency: String, completion: @escaping (Error?) -> Void)
+    func disable(type: String)
+    func read(type: String, anchor: Data?, completion: @escaping (Result<CraftHealthBackgroundPage, Error>) -> Void) -> () -> Void
+}
+
+final class CraftHealthBackground {
+    static let shared: CraftHealthBackground = {
+        let base = FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask).first!
+        #if CRAFT_PERMISSION_HEALTH
+        let source: CraftHealthBackgroundSource = CraftHealthKitBackgroundSource()
+        #else
+        let source: CraftHealthBackgroundSource = CraftUnavailableHealthBackgroundSource()
+        #endif
+        return CraftHealthBackground(source: source, persistence: CraftHealthBackgroundFile(url: base.appendingPathComponent("craft-health/delivery.json")))
+    }()
+
+    private final class Read {
+        var completions: [() -> Void] = []
+        var cancel: (() -> Void)?
+        var deadline: DispatchWorkItem?
+        var dirty = false
+    }
+    private let readTimeout: TimeInterval
+    private let source: CraftHealthBackgroundSource
+    private let persistence: CraftHealthBackgroundPersistence
+    private var state = CraftHealthBackgroundState()
+    private var loaded = false
+    private var observers: [String: () -> Void] = [:]
+    private var reads: [String: Read] = [:]
+    private var types: [String] = []
+    private var frequency = "hourly"
+    private var generation = UUID()
+    private(set) var errors: [String: String] = [:]
+    var emit: (String) -> Void = { _ in }
+
+    init(source: CraftHealthBackgroundSource, persistence: CraftHealthBackgroundPersistence, readTimeout: TimeInterval = 20) {
+        self.source = source
+        self.persistence = persistence
+        self.readTimeout = readTimeout
+    }
+
+    func configure(types: [String], frequency: String) {
+        stop()
+        self.types = Array(Set(types)).sorted()
+        self.frequency = frequency
+        refresh()
+    }
+
+    func refresh() {
+        if !loaded {
+            do { state = try persistence.load(); loaded = true }
+            catch { errors["storage"] = "Health delivery state could not be read"; return }
+        }
+        errors.removeValue(forKey: "storage")
+        let current = generation
+        let observed = Set(state.observedTypes ?? []).union(state.anchors.keys).union(types)
+        if Set(state.observedTypes ?? []) != observed {
+            do {
+                var next = state
+                next.observedTypes = observed.sorted()
+                try persistence.save(next)
+                state = next
+            } catch { errors["storage"] = "Health registration intent could not be persisted"; return }
+        }
+        // Keep retired declarations so a temporarily unavailable store can
+        // retry disabling them on a later launch, even before its first delta.
+        for old in observed where !types.contains(old) { source.disable(type: old) }
+        for type in types {
+            if observers[type] == nil {
+                observers[type] = source.observe(type: type) { [weak self] error, acknowledge in
+                    guard let self, self.generation == current else { acknowledge(); return }
+                    if error != nil { self.errors[type] = "HealthKit observer failed"; acknowledge(); return }
+                    self.changed(type, acknowledge: acknowledge)
+                }
+            }
+            source.enable(type: type, frequency: frequency) { [weak self] error in
+                guard let self, self.generation == current else { return }
+                if error != nil { self.errors["\(type).registration"] = "Background delivery registration failed" }
+                else { self.errors.removeValue(forKey: "\(type).registration"); self.changed(type, acknowledge: {}) }
+            }
+        }
+    }
+
+    private func changed(_ type: String, acknowledge: @escaping () -> Void) {
+        if let read = reads[type] { read.completions.append(acknowledge); read.dirty = true; return }
+        let read = Read()
+        read.completions.append(acknowledge)
+        reads[type] = read
+        // Never strand HealthKit's completion waiting for an unavailable store,
+        // a locked device, an unresponsive query or JavaScript consumption.
+        let deadline = DispatchWorkItem { [weak self, weak read] in
+            guard let self, let read, self.reads[type] === read else { return }
+            self.errors[type] = "HealthKit read timed out; anchor retained for retry"
+            self.finish(type, read)
+        }
+        read.deadline = deadline
+        DispatchQueue.main.asyncAfter(deadline: .now() + readTimeout, execute: deadline)
+        next(type, read)
+    }
+
+    private func next(_ type: String, _ read: Read) {
+        read.dirty = false
+        read.cancel = source.read(type: type, anchor: state.anchors[type]) { [weak self, weak read] answer in
+            guard let self, let read, self.reads[type] === read else { return }
+            read.cancel = nil
+            switch answer {
+            case .failure:
+                self.errors[type] = "HealthKit read failed; anchor retained for retry"
+                self.finish(type, read)
+            case .success(let page):
+                do {
+                    var next = self.state
+                    if !page.samples.isEmpty || !page.deleted.isEmpty {
+                        next.batches.append(CraftHealthBackgroundBatch(id: UUID().uuidString, type: type, samples: page.samples, deleted: page.deleted))
+                    }
+                    next.anchors[type] = page.anchor
+                    try self.persistence.save(next)
+                    self.state = next
+                    self.errors.removeValue(forKey: type)
+                    if !page.samples.isEmpty || !page.deleted.isEmpty { self.emit(type) }
+                    if page.more || read.dirty { self.next(type, read) }
+                    else { self.finish(type, read) }
+                } catch {
+                    self.errors[type] = "Health delivery could not be persisted; anchor retained for retry"
+                    self.finish(type, read)
+                }
+            }
+        }
+    }
+
+    private func finish(_ type: String, _ read: Read) {
+        guard reads[type] === read else { return }
+        reads.removeValue(forKey: type)
+        read.deadline?.cancel()
+        read.cancel?()
+        let completions = read.completions
+        read.completions.removeAll()
+        completions.forEach { $0() }
+    }
+
+    func stop() {
+        generation = UUID()
+        observers.values.forEach { $0() }
+        observers.removeAll()
+        for (type, read) in reads { finish(type, read) }
+    }
+
+    func perform(method: String, args: [Any], completion: @escaping (Result<Any, CraftNativeActionError>) -> Void) {
+        if !loaded { refresh() }
+        guard loaded else { completion(.failure(CraftNativeActionError(code: "STORAGE_ERROR", message: "Health delivery state is unavailable"))); return }
+        do {
+            switch method {
+            case "status": completion(.success(["types": types, "frequency": frequency, "pendingBatches": state.batches.count, "errors": errors]))
+            case "refresh": refresh(); completion(.success(true))
+            case "pending":
+                let data = try JSONEncoder().encode(Array(state.batches.prefix(20)))
+                completion(.success(try JSONSerialization.jsonObject(with: data)))
+            case "acknowledge":
+                guard let ids = args.first as? [String], ids.count <= 20 else {
+                    completion(.failure(CraftNativeActionError(code: "INVALID_ARGUMENT", message: "acknowledge needs up to 20 batch ids"))); return
+                }
+                var next = state
+                let acknowledged = Set(ids)
+                next.batches.removeAll { acknowledged.contains($0.id) }
+                try persistence.save(next)
+                state = next
+                refresh()
+                completion(.success(true))
+            default: completion(.failure(CraftNativeActionError(code: "UNKNOWN_ACTION", message: "Unknown HealthBackground action")))
+            }
+        } catch { completion(.failure(CraftNativeActionError(code: "STORAGE_ERROR", message: "Health delivery state could not be saved"))) }
+    }
+}
+
+private final class CraftUnavailableHealthBackgroundSource: CraftHealthBackgroundSource {
+    func disable(type: String) {}
+    func observe(type: String, update: @escaping (Error?, @escaping () -> Void) -> Void) -> () -> Void { {} }
+    func enable(type: String, frequency: String, completion: @escaping (Error?) -> Void) { completion(CraftHealthBackgroundError.unavailable) }
+    func read(type: String, anchor: Data?, completion: @escaping (Result<CraftHealthBackgroundPage, Error>) -> Void) -> () -> Void { completion(.failure(CraftHealthBackgroundError.unavailable)); return {} }
+}
+
+#if CRAFT_PERMISSION_HEALTH
+private final class CraftHealthKitBackgroundSource: CraftHealthBackgroundSource {
+    private var store: HKHealthStore? { CraftHealth.shared.healthStore }
+    private func sampleType(_ name: String) -> HKSampleType? {
+        if name == "sleep" { return HKCategoryType.categoryType(forIdentifier: .sleepAnalysis) }
+        if name == "workouts" { return HKObjectType.workoutType() }
+        return CraftHealth.healthQuantity(name)?.type
+    }
+    func disable(type: String) {
+        guard let store, let sample = sampleType(type) else { return }
+        store.disableBackgroundDelivery(for: sample) { _, _ in }
+    }
+    func observe(type: String, update: @escaping (Error?, @escaping () -> Void) -> Void) -> () -> Void {
+        guard let store, let sample = sampleType(type) else { return {} }
+        let query = HKObserverQuery(sampleType: sample, predicate: nil) { _, completion, error in
+            DispatchQueue.main.async { update(error, completion) }
+        }
+        store.execute(query)
+        return { store.stop(query) }
+    }
+    func enable(type: String, frequency: String, completion: @escaping (Error?) -> Void) {
+        guard let store, let sample = sampleType(type) else { completion(CraftHealthBackgroundError.unavailable); return }
+        let value: HKUpdateFrequency = ["immediate": .immediate, "hourly": .hourly, "daily": .daily, "weekly": .weekly][frequency] ?? .hourly
+        store.enableBackgroundDelivery(for: sample, frequency: value) { success, error in
+            DispatchQueue.main.async { completion(success ? nil : error ?? CraftHealthBackgroundError.unavailable) }
+        }
+    }
+    func read(type: String, anchor: Data?, completion: @escaping (Result<CraftHealthBackgroundPage, Error>) -> Void) -> () -> Void {
+        guard let store, let sample = sampleType(type) else { completion(.failure(CraftHealthBackgroundError.unavailable)); return {} }
+        let saved: HKQueryAnchor?
+        do {
+            saved = try anchor.map { data in
+                guard let value = try NSKeyedUnarchiver.unarchivedObject(ofClass: HKQueryAnchor.self, from: data) else { throw CraftHealthBackgroundError.invalidAnchor }
+                return value
+            }
+        } catch { completion(.failure(error)); return {} }
+        let query = HKAnchoredObjectQuery(type: sample, predicate: nil, anchor: saved, limit: 250) { _, samples, deleted, anchor, error in
+            let answer: Result<CraftHealthBackgroundPage, Error>
+            do {
+                if let error { throw error }
+                guard let anchor else { throw CraftHealthBackgroundError.missingAnchor }
+                let data = try NSKeyedArchiver.archivedData(withRootObject: anchor, requiringSecureCoding: true)
+                let records = (samples ?? []).map { sample -> CraftHealthBackgroundSample in
+                    var record = CraftHealthBackgroundSample(id: sample.uuid.uuidString, startDate: sample.startDate.timeIntervalSince1970 * 1000, endDate: sample.endDate.timeIntervalSince1970 * 1000)
+                    if let quantity = sample as? HKQuantitySample, let spec = CraftHealth.healthQuantity(type) {
+                        record.value = quantity.quantity.doubleValue(for: spec.unit)
+                        record.unit = spec.unit.unitString
+                    } else if let category = sample as? HKCategorySample { record.category = category.value }
+                    else if let workout = sample as? HKWorkout { record.workoutActivity = workout.workoutActivityType.rawValue; record.durationSeconds = workout.duration }
+                    return record
+                }
+                answer = .success(CraftHealthBackgroundPage(anchor: data, samples: records, deleted: (deleted ?? []).map { $0.uuid.uuidString }, more: records.count + (deleted?.count ?? 0) >= 250))
+            } catch { answer = .failure(error) }
+            DispatchQueue.main.async { completion(answer) }
+        }
+        store.execute(query)
+        return { store.stop(query) }
+    }
+}
+#endif