craft-native 0.0.254 → 0.0.272

package/README.md

@@ -646,3 +646,25 @@ An explicit discard may ACK the captured old ID only after a fresh committed
 native read proves that its previously registered intent was deleted or
 replaced. A cached missing draft or an unsuccessful initial registration is
 not evidence of deletion.
+
+### Browser lifecycle
+
+`createBrowserPlatform()` from `craft-native/browser` supplies
+`craft.lifecycle.getState()` and `onStateChange(callback)` (also `onChange`).
+States are `active` and `background`. The host emits the native-compatible
+`APP_STATE { state }` event on visibility changes and page cache navigation,
+coalesces duplicate transitions, and releases listeners in `dispose()`.
+This lets browser simulations checkpoint on backgrounding with the same contract
+as a native shell. Storage failures must still be handled by the caller.
+
+Await `platform.call('Storage', 'set', [key, value], signal)` before reporting
+a saved checkpoint. `craft.storage.setSync` updates the immediate UI cache and
+queues its write when Web Locks are available; it cannot acknowledge durability
+or propagate a later quota failure. Background events are an opportunity to
+checkpoint, but browsers can terminate a page before queued work finishes, so
+also save periodically during play.
+
+Browser audio assigns one owner per sound ID. A newer play or stop invalidates
+pending media resolution for that ID; stopping all sounds, changing accounts,
+aborting a call or disposing the host also releases active audio. Superseded
+play calls reject with `AbortError`.

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

@@ -70,7 +70,9 @@ export interface CraftAndroidConfig {
      */
     enableHeartRate?: boolean;
     enableHealthConnect?: boolean;
-    /** Google Wallet save-link handoff for native screens. */
+    /** Android Health Services live exercise tracking for native screens. Requires minSdk 30. */
+    enableHealthServices?: boolean;
+    /** Google Wallet save-link or native SDK handoff for native screens. */
     enableWallet?: boolean;
     /**
      * The Health Connect data the app reads and writes, by the shared type
@@ -123,7 +125,7 @@ export interface CraftAndroidConfig {
     mapsApiKey?: string;
     devServerURL?: string;
     hasBundledFallback?: boolean;
-    /** Android API level, at least ANDROID_MIN_SDK (26). */
+    /** Android API level, at least ANDROID_MIN_SDK (26), or 30 with Health Services. */
     minSdk?: number;
     compileSdk?: number;
     targetSdk?: number;

package/dist/android/src/index.js

@@ -454,6 +454,7 @@ var KOTLIN_KEYWORDS = new Set([
   "while"
 ]);
 var ANDROID_MIN_SDK = 26;
+var ANDROID_HEALTH_SERVICES_MIN_SDK = 30;
 var HEALTH_CONNECT_PERMISSIONS = {
   steps: { read: ["READ_STEPS"], write: [] },
   heartRate: { read: ["READ_HEART_RATE"], write: [] },
@@ -514,6 +515,7 @@ var DEFAULT_CONFIG = {
   enableBluetooth: false,
   enableHeartRate: false,
   enableHealthConnect: false,
+  enableHealthServices: false,
   enableWallet: false,
   enableKeepAwake: false,
   enableDeepLinks: false,
@@ -648,6 +650,9 @@ function validateAndroidConfig(config) {
   if (Number(config.minSdk) < ANDROID_MIN_SDK) {
     throw new Error(`Android minSdk must be at least ${ANDROID_MIN_SDK} (Android 8.0) for the Craft runtime`);
   }
+  if (config.enableHealthServices && Number(config.minSdk) < ANDROID_HEALTH_SERVICES_MIN_SDK) {
+    throw new Error(`Android Health Services requires minSdk at least ${ANDROID_HEALTH_SERVICES_MIN_SDK} (Android 11)`);
+  }
   if (Number(config.minSdk) > Number(config.targetSdk)) {
     throw new Error("Android minSdk must not exceed targetSdk");
   }
@@ -810,12 +815,23 @@ function renderAndroidPermissions(config) {
     permissions.add("android.permission.FOREGROUND_SERVICE");
     permissions.add("android.permission.FOREGROUND_SERVICE_CONNECTED_DEVICE");
   }
+  if (config.enableHealthServices) {
+    permissions.add("android.permission.BODY_SENSORS");
+    permissions.add("android.permission.BODY_SENSORS_BACKGROUND");
+    permissions.add("android.permission.health.READ_HEART_RATE");
+    permissions.add("android.permission.health.READ_HEALTH_DATA_IN_BACKGROUND");
+    permissions.add("android.permission.ACTIVITY_RECOGNITION");
+    permissions.add("android.permission.ACCESS_FINE_LOCATION");
+    permissions.add("android.permission.ACCESS_COARSE_LOCATION");
+    permissions.add("android.permission.FOREGROUND_SERVICE");
+    permissions.add("android.permission.FOREGROUND_SERVICE_HEALTH");
+  }
   const bluetooth = config.enableBluetooth || config.enableHeartRate ? [
     '    <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />',
     '    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />',
     '    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation" />',
     '    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />',
-    ...config.enableGeolocation ? [] : ['    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30" />']
+    ...permissions.has("android.permission.ACCESS_FINE_LOCATION") ? [] : ['    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30" />']
   ].join(`
 `) : "";
   return [bluetooth, ...[...permissions].map((permission) => `    <uses-permission android:name="${permission}" />`)].filter(Boolean).join(`
@@ -833,7 +849,49 @@ function writeNativeShellSources(output, packagePath, packageName, config) {
   write("CraftNativeHaptics.kt.template", "CraftNativeHaptics.kt");
   write("CraftNativeBackground.kt.template", "CraftNativeBackground.kt");
   write(config.enableHealthConnect ? "CraftNativeHealth.kt.template" : "CraftNativeHealthStub.kt.template", "CraftNativeHealth.kt");
-  write("CraftNativeServices.kt.template", "CraftNativeServices.kt", (source) => source.replace("{{NATIVE_PUSH_IMPORTS}}", config.enablePushNotifications ? "import com.google.firebase.messaging.FirebaseMessaging" : "").replace("{{NATIVE_PUSH_REGISTER}}", config.enablePushNotifications ? `        try {
+  write(config.enableHealthServices ? "CraftHealthServices.kt.template" : "CraftHealthServicesStub.kt.template", "CraftHealthServices.kt");
+  if (config.enableHealthServices) {
+    write("CraftHealthServicesService.kt.template", "CraftHealthServicesService.kt");
+  } else {
+    rmSync2(join3(javaDir, "CraftHealthServicesService.kt"), { force: true });
+  }
+  write("CraftNativeServices.kt.template", "CraftNativeServices.kt", (source) => source.replace("{{NATIVE_PUSH_IMPORTS}}", config.enablePushNotifications ? "import com.google.firebase.messaging.FirebaseMessaging" : "").replace("{{NATIVE_WALLET_IMPORTS}}", config.enableWallet ? `import com.google.android.gms.pay.Pay
+import com.google.android.gms.pay.PayApiAvailabilityStatus
+import com.google.android.gms.pay.PayClient` : "").replace("{{NATIVE_WALLET_FIELDS}}", config.enableWallet ? `    private var pendingWallet: ((CraftNativeCapabilityResult) -> Unit)? = null
+    private val walletRequestCode = 9517` : "").replace("{{NATIVE_WALLET_AVAILABILITY}}", config.enableWallet ? `                val host = activity()
+                if (host == null) {
+                    done(success(false))
+                } else {
+                    Pay.getClient(host).getPayApiAvailabilityStatus(PayClient.RequestType.SAVE_PASSES_JWT)
+                        .addOnSuccessListener { status -> done(success(status == PayApiAvailabilityStatus.AVAILABLE)) }
+                        .addOnFailureListener { done(success(false)) }
+                }` : `                done(success(runCatching {
+                    context.packageManager.getLaunchIntentForPackage("com.google.android.apps.walletnfcrel") != null
+                }.getOrDefault(false)))`).replace("{{NATIVE_WALLET_JWT_ADD}}", config.enableWallet ? "                    saveWalletJwt(jwt, host, done)" : '                    done(failure("UNSUPPORTED", "Android Wallet JWT saves are not enabled"))').replace("{{NATIVE_WALLET_HELPER}}", config.enableWallet ? `    private fun saveWalletJwt(jwt: String, host: Activity, done: (CraftNativeCapabilityResult) -> Unit) {
+        if (pendingWallet != null) return done(failure("BUSY", "A Google Wallet save is already in progress"))
+        pendingWallet = done
+        try {
+            Pay.getClient(host).savePassesJwt(jwt, host, walletRequestCode)
+        } catch (error: Exception) {
+            pendingWallet = null
+            done(failure("PRESENTATION_FAILED", error.message ?: "Google Wallet could not open"))
+        }
+    }
+` : "").replace("{{NATIVE_WALLET_RESULT}}", config.enableWallet ? `        if (requestCode == walletRequestCode) {
+            val completion = pendingWallet
+            pendingWallet = null
+            if (completion == null) return true
+            when (resultCode) {
+                Activity.RESULT_OK -> completion(success(true))
+                Activity.RESULT_CANCELED -> completion(success(false))
+                PayClient.SavePassesResult.API_UNAVAILABLE -> completion(failure("UNAVAILABLE", "Google Wallet save is unavailable"))
+                PayClient.SavePassesResult.INTERNAL_ERROR -> completion(failure("WALLET_ERROR", "Google Wallet returned an internal error"))
+                PayClient.SavePassesResult.SAVE_ERROR -> completion(failure("SAVE_ERROR", data?.getStringExtra(PayClient.EXTRA_API_ERROR_MESSAGE) ?: "Google Wallet could not save the pass"))
+                else -> completion(failure("WALLET_ERROR", "Google Wallet returned an unknown result"))
+            }
+            return true
+        }
+` : "").replace("{{NATIVE_PUSH_REGISTER}}", config.enablePushNotifications ? `        try {
             FirebaseMessaging.getInstance().token.addOnCompleteListener { task ->
                 val token = if (task.isSuccessful) task.result else null
                 if (token.isNullOrBlank()) done(failure("PUSH_UNAVAILABLE", task.exception?.message ?: "Firebase Cloud Messaging gave no token"))
@@ -963,6 +1021,8 @@ async function init(options) {
     appName: name,
     packageName: finalPackageName
   };
+  if (config.enableHealthServices && given.minSdk === undefined)
+    config.minSdk = ANDROID_HEALTH_SERVICES_MIN_SDK;
   if (config.enableBackgroundLocation)
     config.enableGeolocation = true;
   if (config.enableHealthConnect) {
@@ -1071,7 +1131,7 @@ async function init(options) {
     writeFileSync(join3(output, "app/src/main/java", packagePath, file), readFileSync2(join3(TEMPLATES_DIR, template), "utf8").replace(/\{\{PACKAGE_NAME\}\}/g, finalPackageName));
   }
   const manifestTemplate = readFileSync2(join3(TEMPLATES_DIR, "AndroidManifest.xml.template"), "utf-8");
-  const manifest = manifestTemplate.replace(/\{\{PACKAGE_NAME\}\}/g, finalPackageName).replace(/\{\{APP_NAME\}\}/g, name).replace(/\{\{PERMISSIONS\}\}/g, renderAndroidPermissions(config)).replace(/\{\{USES_CLEARTEXT\}\}/g, config.devServerURL?.startsWith("http://") || config.enableLocalNetwork ? "true" : "false").replace(/\{\{DEEP_LINK_INTENT_FILTERS\}\}/g, renderAndroidDeepLinks(config)).replace(/\{\{BACKGROUND_SERVICE\}\}/g, config.enableBackgroundLocation ? '        <service android:name="com.craft.runtime.LocationRecordingService" android:exported="false" android:foregroundServiceType="location" android:stopWithTask="false" />' : "").replace(/\{\{HEART_RATE_SERVICE\}\}/g, config.enableHeartRate ? '        <service android:name=".CraftHeartRateService" android:exported="false" android:foregroundServiceType="connectedDevice" />' : "").replace(/\{\{NATIVE_NOTIFICATION_RECEIVER\}\}/g, config.renderer === "native" ? renderNativeShellManifest(config) : "").replace(/\{\{CRASH_REPORTER_PROVIDER\}\}/g, `        <provider android:name=".CraftCrashReporterInit" android:authorities="\${applicationId}.craft-crash" android:exported="false" android:initOrder="1000" />`).replace(/\{\{GOOGLE_MAPS_API_KEY\}\}/g, config.mapProvider !== "maplibre" && config.mapsApiKey ? `        <meta-data android:name="com.google.android.geo.API_KEY" android:value="${escapeXml(config.mapsApiKey)}" />` : "").replace(/\{\{HEALTH_CONNECT_QUERIES\}\}/g, config.enableHealthConnect ? `    <queries>
+  const manifest = manifestTemplate.replace(/\{\{PACKAGE_NAME\}\}/g, finalPackageName).replace(/\{\{APP_NAME\}\}/g, name).replace(/\{\{PERMISSIONS\}\}/g, renderAndroidPermissions(config)).replace(/\{\{USES_CLEARTEXT\}\}/g, config.devServerURL?.startsWith("http://") || config.enableLocalNetwork ? "true" : "false").replace(/\{\{DEEP_LINK_INTENT_FILTERS\}\}/g, renderAndroidDeepLinks(config)).replace(/\{\{BACKGROUND_SERVICE\}\}/g, config.enableBackgroundLocation ? '        <service android:name="com.craft.runtime.LocationRecordingService" android:exported="false" android:foregroundServiceType="location" android:stopWithTask="false" />' : "").replace(/\{\{HEART_RATE_SERVICE\}\}/g, config.enableHeartRate ? '        <service android:name=".CraftHeartRateService" android:exported="false" android:foregroundServiceType="connectedDevice" />' : "").replace(/\{\{HEALTH_SERVICES_SERVICE\}\}/g, config.enableHealthServices ? '        <service android:name=".CraftHealthServicesService" android:exported="false" android:foregroundServiceType="health" android:stopWithTask="false" />' : "").replace(/\{\{NATIVE_NOTIFICATION_RECEIVER\}\}/g, config.renderer === "native" ? renderNativeShellManifest(config) : "").replace(/\{\{CRASH_REPORTER_PROVIDER\}\}/g, `        <provider android:name=".CraftCrashReporterInit" android:authorities="\${applicationId}.craft-crash" android:exported="false" android:initOrder="1000" />`).replace(/\{\{GOOGLE_MAPS_API_KEY\}\}/g, config.mapProvider !== "maplibre" && config.mapsApiKey ? `        <meta-data android:name="com.google.android.geo.API_KEY" android:value="${escapeXml(config.mapsApiKey)}" />` : "").replace(/\{\{HEALTH_CONNECT_QUERIES\}\}/g, config.enableHealthConnect ? `    <queries>
         <package android:name="com.google.android.apps.healthdata" />
     </queries>` : "").replace(/\{\{HEALTH_CONNECT_RATIONALE\}\}/g, config.enableHealthConnect ? `            <intent-filter>
                 <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
@@ -1086,7 +1146,8 @@ async function init(options) {
   const appGradleTemplate = readFileSync2(join3(TEMPLATES_DIR, "build.gradle.kts.app.template"), "utf-8");
   const appGradle = appGradleTemplate.replace(/\{\{PACKAGE_NAME\}\}/g, finalPackageName).replace(/\{\{VERSION_NAME\}\}/g, escapeKotlinString(config.version || "1.0.0")).replace(/\{\{VERSION_CODE\}\}/g, String(config.versionCode || 1)).replace(/\{\{MIN_SDK\}\}/g, String(config.minSdk ?? ANDROID_MIN_SDK)).replace(/\{\{COMPILE_SDK\}\}/g, String(config.compileSdk || 36)).replace(/\{\{TARGET_SDK\}\}/g, String(config.targetSdk || 35)).replace(/\{\{GOOGLE_SERVICES_PLUGIN\}\}/g, hasGoogleServices ? '    id("com.google.gms.google-services")' : "").replace(/\{\{FIREBASE_MESSAGING_DEPENDENCY\}\}/g, config.enablePushNotifications ? '    implementation("com.google.firebase:firebase-messaging:24.1.0")' : "").replace(/\{\{REFRESH_LAYOUT_DEPENDENCY\}\}/g, config.renderer === "native" ? '    implementation("androidx.swiperefreshlayout:swiperefreshlayout:1.1.0")' : "").replace(/\{\{NATIVE_MAP_DEPENDENCY\}\}/g, config.renderer === "native" ? `    // Native STX Map overlays and trail routes
     implementation("${androidMapHost(config.mapProvider).dependency}")` : "").replace(/\{\{HEALTH_CONNECT_DEPENDENCIES\}\}/g, config.enableHealthConnect ? `    implementation("androidx.health.connect:connect-client:1.1.0")
-    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1")` : "").replace(/\{\{JAVASCRIPT_ENGINE_DEPENDENCY\}\}/g, config.renderer === "native" ? `    implementation("androidx.javascriptengine:javascriptengine:1.1.0")
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1")` : "").replace(/\{\{HEALTH_SERVICES_DEPENDENCIES\}\}/g, config.enableHealthServices ? '    implementation("androidx.health:health-services-client:1.1.0")' : "").replace(/\{\{WALLET_DEPENDENCY\}\}/g, config.enableWallet ? `    // Native Google Wallet save flow for signed pass JWTs
+    implementation("com.google.android.gms:play-services-pay:16.5.0")` : "").replace(/\{\{JAVASCRIPT_ENGINE_DEPENDENCY\}\}/g, config.renderer === "native" ? `    implementation("androidx.javascriptengine:javascriptengine:1.1.0")
     // Native background refresh (WorkManager).
     implementation("androidx.work:work-runtime-ktx:2.9.1")` : "");
   writeFileSync(join3(output, "app/build.gradle.kts"), appGradle);

package/dist/android/templates/AndroidManifest.xml.template

@@ -56,6 +56,7 @@
 
 {{BACKGROUND_SERVICE}}
 {{HEART_RATE_SERVICE}}
+{{HEALTH_SERVICES_SERVICE}}
 {{NATIVE_NOTIFICATION_RECEIVER}}
 {{CRASH_REPORTER_PROVIDER}}
 

package/dist/android/templates/CraftHealthServices.kt.template

@@ -0,0 +1,132 @@
+package {{PACKAGE_NAME}}
+
+import android.app.Activity
+import android.content.Context
+import android.content.Intent
+import android.os.Build
+import androidx.core.content.ContextCompat
+import androidx.health.services.client.HealthServices
+import androidx.health.services.client.data.DataType
+import androidx.health.services.client.data.ExerciseType
+import org.json.JSONArray
+import org.json.JSONObject
+import java.util.UUID
+import java.util.concurrent.atomic.AtomicReference
+import java.util.concurrent.ConcurrentHashMap
+
+/** Native Health Services entry point; the ExerciseClient lives in the retained service. */
+internal class CraftHealthServices(
+    private val context: Context,
+    private val activityProvider: () -> Activity?,
+    private val fallback: ((String, JSONArray, (CraftNativeCapabilityResult) -> Unit) -> Unit)? = null,
+) {
+    private fun failure(code: String, message: String) = CraftNativeCapabilityResult(code = code, message = message)
+
+    fun perform(method: String, args: JSONArray, done: (CraftNativeCapabilityResult) -> Unit) {
+        when (method) {
+            "startWorkout" -> start(args.optJSONObject(0) ?: JSONObject(), done)
+            "pauseWorkout" -> command(CraftHealthServicesService.ACTION_PAUSE, done)
+            "resumeWorkout" -> command(CraftHealthServicesService.ACTION_RESUME, done)
+            "endWorkout" -> command(CraftHealthServicesService.ACTION_END, done)
+            else -> done(failure("UNKNOWN_ACTION", "Unsupported Health Services method"))
+        }
+    }
+
+    private fun start(options: JSONObject, done: (CraftNativeCapabilityResult) -> Unit) {
+        if (activityProvider() == null) return done(failure("NEEDS_ACTIVITY", "Live workouts require a foreground activity"))
+        val type = options.optString("type").takeIf { it.isNotBlank() }
+            ?: return done(failure("INVALID_ARGUMENT", "startWorkout needs a workout type"))
+        if (type !in SUPPORTED_TYPES) return done(failure("INVALID_ARGUMENT", "Unsupported workout type: $type"))
+        if (!activeId.compareAndSet(null, "pending")) return done(failure("BUSY", "A live workout is already running"))
+        val id = "live-${UUID.randomUUID()}"
+        val exerciseType = when (type) {
+            "running" -> ExerciseType.RUNNING
+            "walking" -> ExerciseType.WALKING
+            "hiking" -> ExerciseType.HIKING
+            "cycling" -> ExerciseType.BIKING
+            else -> null
+        } ?: return unsupported(options, done, "Unsupported workout type: $type")
+        val future = HealthServices.getClient(context).exerciseClient.getCapabilitiesAsync()
+        future.addListener({
+            runCatching {
+                val capabilities = future.get()
+                val requested = setOf(DataType.HEART_RATE_BPM, DataType.CALORIES_TOTAL, DataType.DISTANCE_TOTAL)
+                if (exerciseType !in capabilities.supportedExerciseTypes) {
+                    return@runCatching unsupported(options, done, "Health Services does not support this workout on this device")
+                }
+                val typeCapabilities = capabilities.getExerciseTypeCapabilities(exerciseType)
+                if (requested.none { it in typeCapabilities.supportedDataTypes }) {
+                    return@runCatching unsupported(options, done, "Health Services exposes none of the requested workout metrics")
+                }
+                startService(id, type, done)
+            }.onFailure { unsupported(options, done, it.message ?: "Health Services is unavailable") }
+        }, ContextCompat.getMainExecutor(context))
+    }
+
+    private fun startService(id: String, type: String, done: (CraftNativeCapabilityResult) -> Unit) {
+        activeId.set(id)
+        val intent = Intent(context, CraftHealthServicesService::class.java)
+            .setAction(CraftHealthServicesService.ACTION_START)
+            .putExtra(CraftHealthServicesService.EXTRA_ID, id)
+            .putExtra(CraftHealthServicesService.EXTRA_TYPE, type)
+        try {
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) context.startForegroundService(intent) else context.startService(intent)
+            done(CraftNativeCapabilityResult(data = JSONObject().put("id", id).put("type", type).put("startDate", System.currentTimeMillis())))
+        } catch (error: Exception) {
+            activeId.compareAndSet(id, null)
+            done(failure("UNAVAILABLE", error.message ?: "Health Services could not start"))
+        }
+    }
+
+    private fun unsupported(options: JSONObject, done: (CraftNativeCapabilityResult) -> Unit, message: String) {
+        activeId.set(null)
+        fallback?.invoke("startWorkout", JSONArray().put(options), done)
+            ?: done(failure("UNAVAILABLE", message))
+    }
+
+    private fun command(action: String, done: (CraftNativeCapabilityResult) -> Unit) {
+        val id = activeId.get()?.takeIf { it != "pending" }
+            ?: return done(failure("NO_WORKOUT", "No live workout is running"))
+        try {
+            context.startService(Intent(context, CraftHealthServicesService::class.java).setAction(action).putExtra(CraftHealthServicesService.EXTRA_ID, id))
+            if (action == CraftHealthServicesService.ACTION_END) endCompletions[id] = { result -> finishEnd(result, done) }
+            else done(CraftNativeCapabilityResult(data = true))
+        } catch (error: Exception) {
+            if (action == CraftHealthServicesService.ACTION_END) endCompletions.remove(id)
+            done(failure("UNAVAILABLE", error.message ?: "Health Services command failed"))
+        }
+    }
+
+    private fun finishEnd(result: CraftNativeCapabilityResult, done: (CraftNativeCapabilityResult) -> Unit) {
+        val payload = result.data as? JSONObject
+        if (result.code != null || payload == null || fallback == null) return done(result)
+        fallback.invoke("saveWorkout", JSONArray().put(payload)) { saved ->
+            if (saved.code != null) return@invoke done(saved)
+            val workoutId = (saved.data as? JSONObject)?.optString("id")?.takeIf { it.isNotBlank() }
+                ?: payload.optString("id")
+            done(CraftNativeCapabilityResult(data = JSONObject()
+                .put("id", payload.optString("id"))
+                .put("workoutId", workoutId)
+                .put("endDate", payload.optLong("endDate"))
+                .put("durationSeconds", payload.optDouble("durationSeconds"))))
+        }
+    }
+
+    companion object {
+        private val activeId = AtomicReference<String?>(null)
+        private val endCompletions = ConcurrentHashMap<String, (CraftNativeCapabilityResult) -> Unit>()
+        private val SUPPORTED_TYPES = setOf("running", "walking", "hiking", "cycling")
+
+        internal fun completeEnd(id: String, result: CraftNativeCapabilityResult) {
+            endCompletions.remove(id)?.invoke(result)
+        }
+
+        internal fun failEnd(id: String, message: String) {
+            completeEnd(id, CraftNativeCapabilityResult(code = "UNAVAILABLE", message = message))
+        }
+
+        internal fun clearActive() {
+            activeId.set(null)
+        }
+    }
+}

package/dist/android/templates/CraftHealthServicesService.kt.template

@@ -0,0 +1,217 @@
+package {{PACKAGE_NAME}}
+
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.Service
+import android.content.Intent
+import android.os.Build
+import android.os.IBinder
+import androidx.core.app.NotificationCompat
+import androidx.health.services.client.ExerciseClient
+import androidx.health.services.client.ExerciseUpdateCallback
+import androidx.health.services.client.HealthServices
+import androidx.health.services.client.data.Availability
+import androidx.health.services.client.data.DataType
+import androidx.health.services.client.data.ExerciseConfig
+import androidx.health.services.client.data.ExerciseLapSummary
+import androidx.health.services.client.data.ExerciseState
+import androidx.health.services.client.data.ExerciseType
+import androidx.health.services.client.data.ExerciseUpdate
+import org.json.JSONObject
+import java.util.concurrent.Executor
+
+/** Retained foreground owner for one Android Health Services exercise. */
+internal class CraftHealthServicesService : Service() {
+    private lateinit var exerciseClient: ExerciseClient
+    private lateinit var callback: ExerciseUpdateCallback
+    private val executor: Executor by lazy { mainExecutor }
+    private var workoutId = ""
+    private var workoutType = ""
+    private var workoutStartedAt = 0L
+    private var pausedAt = 0L
+    private var pausedMillis = 0L
+    private var lastDurationSeconds = 0.0
+    private var lastEnergyCalories: Double? = null
+    private var lastDistanceMeters: Double? = null
+
+    override fun onCreate() {
+        super.onCreate()
+        createNotificationChannel()
+        exerciseClient = HealthServices.getClient(this).exerciseClient
+        callback = object : ExerciseUpdateCallback {
+            override fun onRegistered() = Unit
+            override fun onRegistrationFailed(throwable: Throwable) {
+                emitError(throwable.message ?: "Health Services callback registration failed")
+            }
+            override fun onExerciseUpdateReceived(update: ExerciseUpdate) = emit(update)
+            override fun onAvailabilityChanged(dataType: DataType<*, *>, availability: Availability) {
+                emitError("${dataType.name} is unavailable ($availability)")
+            }
+            override fun onLapSummaryReceived(lapSummary: ExerciseLapSummary) = Unit
+        }
+        exerciseClient.setUpdateCallback(executor, callback)
+    }
+
+    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+        when (intent?.action) {
+            ACTION_START -> start(intent)
+            ACTION_PAUSE -> {
+                if (pausedAt == 0L) pausedAt = System.currentTimeMillis()
+                exerciseClient.pauseExerciseAsync()
+            }
+            ACTION_RESUME -> {
+                if (pausedAt != 0L) {
+                    pausedMillis += (System.currentTimeMillis() - pausedAt).coerceAtLeast(0)
+                    pausedAt = 0L
+                }
+                exerciseClient.resumeExerciseAsync()
+            }
+            ACTION_END -> end()
+        }
+        return START_STICKY
+    }
+
+    private fun start(intent: Intent) {
+        workoutId = intent.getStringExtra(EXTRA_ID).orEmpty()
+        workoutType = intent.getStringExtra(EXTRA_TYPE).orEmpty()
+        workoutStartedAt = System.currentTimeMillis()
+        pausedAt = 0L
+        pausedMillis = 0L
+        lastDurationSeconds = 0.0
+        lastEnergyCalories = null
+        lastDistanceMeters = null
+        startForeground(NOTIFICATION_ID, notification())
+        val type = exerciseType(workoutType) ?: return emitError("Unsupported Health Services workout type: $workoutType")
+        val capabilitiesFuture = exerciseClient.getCapabilitiesAsync()
+        capabilitiesFuture.addListener({
+            runCatching {
+                val capabilities = capabilitiesFuture.get()
+                if (type !in capabilities.supportedExerciseTypes) return@runCatching emitError("Health Services does not support $workoutType on this device")
+                val typeCapabilities = capabilities.getExerciseTypeCapabilities(type)
+                val requested = setOf(DataType.HEART_RATE_BPM, DataType.CALORIES_TOTAL, DataType.DISTANCE_TOTAL)
+                    .filter { it in typeCapabilities.supportedDataTypes }.toSet()
+                if (requested.isEmpty()) return@runCatching emitError("Health Services exposes none of the requested workout metrics")
+                val config = ExerciseConfig.builder(type).setDataTypes(requested).setIsGpsEnabled(DataType.DISTANCE_TOTAL in requested).build()
+                exerciseClient.startExerciseAsync(config)
+            }.onFailure { emitError(it.message ?: "Health Services could not start") }
+        }, executor)
+    }
+
+    private fun end() {
+        val id = workoutId
+        if (pausedAt != 0L) {
+            pausedMillis += (System.currentTimeMillis() - pausedAt).coerceAtLeast(0)
+            pausedAt = 0L
+        }
+        try {
+            val future = exerciseClient.endExerciseAsync()
+            future.addListener({
+                runCatching {
+                    future.get()
+                    val duration = if (lastDurationSeconds > 0) lastDurationSeconds
+                    else ((System.currentTimeMillis() - workoutStartedAt - pausedMillis).coerceAtLeast(0) / 1000.0)
+                    val result = JSONObject()
+                        .put("id", id)
+                        .put("activityId", id)
+                        .put("type", workoutType)
+                        .put("startDate", workoutStartedAt)
+                        .put("workoutId", id)
+                        .put("endDate", System.currentTimeMillis())
+                        .put("durationSeconds", duration)
+                    lastEnergyCalories?.let { result.put("activeEnergyCalories", it) }
+                    lastDistanceMeters?.let { result.put("distanceMeters", it) }
+                    CraftHealthServices.completeEnd(id, CraftNativeCapabilityResult(data = result))
+                    CraftHealthServices.clearActive()
+                    stopSelf()
+                }.onFailure {
+                    CraftHealthServices.failEnd(id, it.message ?: "Health Services workout could not end")
+                    CraftHealthServices.clearActive()
+                    emitError(it.message ?: "Health Services workout could not end")
+                }
+            }, executor)
+        } catch (error: Exception) {
+            CraftHealthServices.failEnd(id, error.message ?: "Health Services workout could not end")
+            CraftHealthServices.clearActive()
+            emitError(error.message ?: "Health Services workout could not end")
+        }
+    }
+
+    private fun emit(update: ExerciseUpdate) {
+        val state = update.exerciseStateInfo.state
+        val detail = JSONObject().put("id", workoutId).put("event", if (state.isEnded) "state" else "metrics")
+            .put("state", stateName(state)).put("date", System.currentTimeMillis())
+        update.latestMetrics.getData(DataType.HEART_RATE_BPM).lastOrNull()?.value?.let { detail.put("heartRateBpm", it) }
+        update.latestMetrics.getData(DataType.CALORIES_TOTAL)?.total?.let {
+            lastEnergyCalories = it
+            detail.put("activeEnergyCalories", it)
+        }
+        update.latestMetrics.getData(DataType.DISTANCE_TOTAL)?.total?.let {
+            lastDistanceMeters = it
+            detail.put("distanceMeters", it)
+        }
+        update.activeDurationCheckpoint?.let { detail.put("durationSeconds", it.activeDuration.toMillis() / 1000.0) }
+        detail.optDouble("durationSeconds", -1.0).takeIf { it >= 0 }?.let { lastDurationSeconds = it }
+        CraftNativeHub.broadcast("CRAFT_EVENT", JSONObject().put("event", "craftHealthWorkout").put("detail", detail))
+        if (state.isEnded) {
+            CraftHealthServices.clearActive()
+            stopSelf()
+        }
+    }
+
+    private fun emitError(message: String) {
+        CraftHealthServices.clearActive()
+        CraftHealthServices.failEnd(workoutId, message)
+        CraftNativeHub.broadcast("CRAFT_EVENT", JSONObject().put("event", "craftHealthWorkout").put("detail", JSONObject()
+            .put("id", workoutId).put("event", "error").put("message", message)))
+        stopSelf()
+    }
+
+    private fun exerciseType(value: String): ExerciseType? = when (value) {
+        "running" -> ExerciseType.RUNNING
+        "walking" -> ExerciseType.WALKING
+        "hiking" -> ExerciseType.HIKING
+        "cycling" -> ExerciseType.BIKING
+        else -> null
+    }
+
+    private fun stateName(state: ExerciseState): String = when {
+        state == ExerciseState.ACTIVE -> "running"
+        state.isPaused -> "paused"
+        state.isEnded -> "ended"
+        else -> "unknown"
+    }
+
+    private fun notification(): Notification = NotificationCompat.Builder(this, CHANNEL_ID)
+        .setSmallIcon(android.R.drawable.ic_media_play)
+        .setContentTitle("Workout in progress")
+        .setContentText("Craft is tracking your workout")
+        .setOngoing(true)
+        .build()
+
+    private fun createNotificationChannel() {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            getSystemService(NotificationManager::class.java).createNotificationChannel(
+                NotificationChannel(CHANNEL_ID, "Workouts", NotificationManager.IMPORTANCE_LOW),
+            )
+        }
+    }
+
+    override fun onDestroy() {
+        runCatching { exerciseClient.clearUpdateCallbackAsync(callback) }
+        super.onDestroy()
+    }
+
+    override fun onBind(intent: Intent?): IBinder? = null
+
+    companion object {
+        const val ACTION_START = "com.craft.health.START"
+        const val ACTION_PAUSE = "com.craft.health.PAUSE"
+        const val ACTION_RESUME = "com.craft.health.RESUME"
+        const val ACTION_END = "com.craft.health.END"
+        const val EXTRA_ID = "craft.health.id"
+        const val EXTRA_TYPE = "craft.health.type"
+        private const val CHANNEL_ID = "craft-health-workout"
+        private const val NOTIFICATION_ID = 8412
+    }
+}

package/dist/android/templates/CraftHealthServicesStub.kt.template

@@ -0,0 +1,16 @@
+package {{PACKAGE_NAME}}
+
+import android.content.Context
+import android.app.Activity
+import org.json.JSONArray
+
+/** Compile-time placeholder when Android Health Services is not enabled. */
+internal class CraftHealthServices(
+    private val context: Context,
+    private val activityProvider: () -> Activity?,
+    private val fallback: ((String, JSONArray, (CraftNativeCapabilityResult) -> Unit) -> Unit)? = null,
+) {
+    fun perform(method: String, args: JSONArray, done: (CraftNativeCapabilityResult) -> Unit) {
+        done(CraftNativeCapabilityResult(code = "CAPABILITY_DISABLED", message = "Health Services is not enabled for this app"))
+    }
+}