craft-native 0.0.396 → 0.0.408

package/README.md

@@ -598,6 +598,13 @@ precommitted ID without adopting an unknown recording. The asynchronous Crypto
 service uses the platform's secure UUID generator; an unsupported native host
 rejects with `CRYPTO_UNSUPPORTED` without falling back to JavaScript entropy.
 
+To save battery on a long effort, start with `powerMode: 'saver'`, or `'auto'` to
+save only while iOS Low Power Mode or Android Battery Saver is on or the battery
+is low. Change a running recording with
+`location.setRecordingPowerMode({ expectedId: id, powerMode })` after checking
+`location.supportsRecordingPowerMode()`; recording states report `powerMode` and
+`effectivePowerMode` (see `docs/api/mobile/location.md`).
+
 Pass `{ expectedId: id }` to pause, resume, stop, read and get-state calls. Heart-rate reads also accept
 `since`. A supplied empty, whitespace or non-string ID rejects with
 `INVALID_ARGUMENT`. Starting while another session is active rejects with

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

@@ -323,6 +323,7 @@ class CraftBridge(
                     crypto: true,
                     locationRecordingOwnership: {{ENABLE_GEOLOCATION}} && ${CraftNative.supportsRecordingOwnership()},
                     locationRecordingIntentIdentity: {{ENABLE_GEOLOCATION}} && ${CraftNative.supportsRecordingIntentIdentity()},
+                    locationRecordingPowerMode: {{ENABLE_GEOLOCATION}} && ${CraftNative.supportsRecordingPowerMode()},
                     backgroundLocation: {{ENABLE_BACKGROUND_LOCATION}},
                     clipboard: false,
                     deviceInfo: true,
@@ -1714,6 +1715,7 @@ class CraftBridge(
                     watchPosition: craft.watchPosition,
                     clearWatch: craft.clearWatch,
                     startRecording: function(options) { return recordingCall('startRecording', options); },
+                    setRecordingPowerMode: function(options) { return recordingCall('setRecordingPowerMode', options); },
                     pauseRecording: function(options) { return recordingCall('pauseRecording', options); },
                     resumeRecording: function(options) { return recordingCall('resumeRecording', options); },
                     stopRecording: function(options) { return recordingCall('stopRecording', options); },

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

@@ -1954,6 +1954,13 @@ object CraftNative {
         return try { nativeRecordingOwnershipVersion() >= 1 } catch (_: UnsatisfiedLinkError) { false }
     }
 
+    /**
+     * `setRecordingPowerMode` and `powerMode: 'auto'`. The Kotlin store serves
+     * any method it is handed, so a linked runtime that passes recorder calls
+     * through (version 1 and up) supports it exactly as it supports ownership.
+     */
+    fun supportsRecordingPowerMode(): Boolean = supportsRecordingOwnership()
+
     fun supportsRecordingIntentIdentity(): Boolean {
         if (!isAvailable) return true
         return try { nativeRecordingOwnershipVersion() >= 2 } catch (_: UnsatisfiedLinkError) { false }

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

@@ -135,6 +135,7 @@ internal class CraftNativeServices(
             add("geolocation")
             if (CraftNative.supportsRecordingOwnership()) add("locationRecordingOwnership")
             if (CraftNative.supportsRecordingIntentIdentity()) add("locationRecordingIntentIdentity")
+            if (CraftNative.supportsRecordingPowerMode()) add("locationRecordingPowerMode")
         }
         if (config.optJSONObject("backgroundRefresh")?.optBoolean("enabled") == true || config.optBoolean("enablePushNotifications")) add("background")
         // A Bluetooth heart-rate strap (CraftHeartRate.kt), the app's own
@@ -513,7 +514,7 @@ internal class CraftNativeServices(
                 watchCallback = null
                 done(success(true))
             }
-            "startRecording", "pauseRecording", "resumeRecording", "stopRecording", "getRecordingState", "readRecording", "acknowledgeRecording" -> {
+            "startRecording", "setRecordingPowerMode", "pauseRecording", "resumeRecording", "stopRecording", "getRecordingState", "readRecording", "acknowledgeRecording" -> {
                 val invoke = {
                     val answer = JSONObject(store.perform(context, method, (args.optJSONObject(0) ?: JSONObject()).toString()))
                     if (answer.optBoolean("ok")) {

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

@@ -93,6 +93,9 @@ internal data class CraftNativeTabBarAppearance(
 
 internal data class CraftTabIconAppearance(val symbol: String, val tint: Int?, val pulse: Boolean)
 
+/** The app's faces for the chrome (`fontFamily`, `headingFontFamily`); null keeps the system face. */
+internal data class CraftNativeChromeFonts(val body: Typeface? = null, val heading: Typeface? = null)
+
 /** The app's paths (`nativeScreens`), its tabs and its site. */
 internal class CraftNativeRoutes(config: JSONObject) {
     private data class Route(val segments: List<String>, val screen: String)
@@ -137,6 +140,10 @@ internal class CraftNativeRoutes(config: JSONObject) {
         }
         ?: CraftNativeTabBarAppearance()
 
+    /** CSS stacks for the chrome's labels and titles, as the app configured them. */
+    val fontFamily: String? = config.optString("fontFamily").takeUnless { config.isNull("fontFamily") || it.isBlank() }
+    val headingFontFamily: String? = config.optString("headingFontFamily").takeUnless { config.isNull("headingFontFamily") || it.isBlank() }
+
     /** The app's site (`devServerURL`): its origin answers paths no screen draws. */
     val site: Uri? = config.optString("devServerURL").takeIf { it.isNotBlank() }?.let(Uri::parse)
     val siteOrigin: String? = site?.let { uri ->
@@ -789,6 +796,7 @@ internal class CraftNativeChrome(
     context: Context,
     private val tabs: List<CraftNativeTab>,
     private val tabBarAppearance: CraftNativeTabBarAppearance = CraftNativeTabBarAppearance(),
+    private val fonts: CraftNativeChromeFonts = CraftNativeChromeFonts(),
 ) : LinearLayout(context) {
     val content = FrameLayout(context)
     private val bar = LinearLayout(context)
@@ -858,7 +866,7 @@ internal class CraftNativeChrome(
         leadingButtons.gravity = Gravity.CENTER_VERTICAL
         bar.addView(leadingButtons, LayoutParams(ViewGroup.LayoutParams.WRAP_CONTENT, dp(56)))
         titleView.textSize = 20f
-        titleView.typeface = Typeface.create("sans-serif-medium", Typeface.NORMAL)
+        titleView.typeface = fonts.heading?.let { Typeface.create(it, Typeface.BOLD) } ?: Typeface.create("sans-serif-medium", Typeface.NORMAL)
         titleView.isSingleLine = true
         titleView.ellipsize = TextUtils.TruncateAt.END
         titleView.setPadding(dp(12), 0, dp(8), 0)
@@ -868,7 +876,7 @@ internal class CraftNativeChrome(
         bar.addView(buttons, LayoutParams(ViewGroup.LayoutParams.WRAP_CONTENT, dp(56)))
         addView(bar, LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, dp(56)))
         largeTitleView.textSize = 32f
-        largeTitleView.typeface = Typeface.create("sans-serif", Typeface.BOLD)
+        largeTitleView.typeface = Typeface.create(fonts.heading ?: Typeface.create("sans-serif", Typeface.NORMAL), Typeface.BOLD)
         largeTitleView.isSingleLine = true
         largeTitleView.ellipsize = TextUtils.TruncateAt.END
         largeTitleView.setPadding(dp(16), 0, dp(16), dp(8))
@@ -907,6 +915,7 @@ internal class CraftNativeChrome(
             label.importantForAccessibility = View.IMPORTANT_FOR_ACCESSIBILITY_NO
             label.text = tab.title
             label.textSize = 12f
+            fonts.body?.let { label.typeface = it }
             label.fontFeatureSettings = "tnum"
             label.gravity = Gravity.CENTER
             label.isSingleLine = true
@@ -1199,6 +1208,7 @@ internal class CraftNativeChrome(
         val vector = if (symbol.isNotBlank()) CraftNativeIcons.drawable(context, null, symbol, tint) else null
         view.text = if (vector != null) "" else if (symbol.isNotBlank()) CraftNativeSymbols.glyph(symbol) else title
         view.textSize = if (symbol.isNotBlank()) 22f else 16f
+        if (symbol.isBlank()) fonts.body?.let { view.typeface = it }
         if (vector != null) {
             view.foreground = android.graphics.drawable.InsetDrawable(vector, dp(10), dp(15), dp(10), dp(15))
             view.minWidth = dp(46)

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

@@ -4,12 +4,16 @@ import android.Manifest
 import android.app.NotificationChannel
 import android.app.NotificationManager
 import android.app.Service
+import android.content.BroadcastReceiver
 import android.content.Context
 import android.content.Intent
+import android.content.IntentFilter
 import android.content.pm.PackageManager
+import android.os.BatteryManager
 import android.os.Build
 import android.os.IBinder
 import android.os.Looper
+import android.os.PowerManager
 import androidx.core.app.NotificationCompat
 import androidx.core.content.ContextCompat
 import {{PACKAGE_NAME}}.R
@@ -112,14 +116,71 @@ object CraftLocationRecordingStore {
     }
 
     @Synchronized
-    fun start(context: Context, id: String, startedAt: Long) {
+    fun start(context: Context, id: String, startedAt: Long, powerMode: String = "default") {
         recover(context)
         if (isActive(context)) throw CraftRecordingException("RECORDING_ALREADY_ACTIVE", "A location recording is already active")
         if (id == recordingId(context) || archive(context, id).exists() || acknowledged(context, id))
             throw CraftRecordingException("RECORDING_CONFLICT", "Recording IDs cannot be reused")
         archiveCompleted(context)
         file(context).writeText("")
-        edit(context) { it.putString("id", id).putBoolean("active", true).putBoolean("paused", false).putLong("startedAt", startedAt) }
+        edit(context) { it.putString("id", id).putBoolean("active", true).putBoolean("paused", false).putLong("startedAt", startedAt).putString("powerMode", powerMode).remove("powerSaver") }
+    }
+
+    private val POWER_MODES = setOf("default", "saver", "auto")
+
+    /** A mode the page may ask for; `fallback` when the option is absent or null. */
+    private fun requestedPowerMode(options: JSONObject?, fallback: String?): String {
+        if (options == null || !options.has("powerMode") || options.isNull("powerMode"))
+            return fallback ?: throw CraftRecordingException("INVALID_ARGUMENT", "powerMode must be 'default', 'saver' or 'auto'")
+        val mode = options.opt("powerMode")
+        if (mode !is String || mode !in POWER_MODES) throw CraftRecordingException("INVALID_ARGUMENT", "powerMode must be 'default', 'saver' or 'auto'")
+        return mode
+    }
+
+    /**
+     * The mode the recording was asked for (`default`, `saver` or `auto`):
+     * `startRecording({ powerMode })`, changed by `setRecordingPowerMode`.
+     * A recording stored by an older build kept a `powerSaver` flag instead.
+     */
+    @Synchronized
+    fun powerMode(context: Context): String {
+        val values = prefs(context)
+        return values.getString("powerMode", null)?.takeIf { it in POWER_MODES }
+            ?: if (values.getBoolean("powerSaver", false)) "saver" else "default"
+    }
+
+    /**
+     * What the recorder uses right now: `saver` spaces fixes out and batches
+     * them, and `auto` is a saver while the device is saving power (Battery
+     * Saver on, or under 20% charge and not plugged in). Never outside a recording.
+     */
+    @Synchronized
+    fun isPowerSaver(context: Context): Boolean {
+        if (!isActive(context)) return false
+        return when (powerMode(context)) {
+            "saver" -> true
+            "auto" -> deviceIsSavingPower(context)
+            else -> false
+        }
+    }
+
+    fun deviceIsSavingPower(context: Context): Boolean {
+        if (context.getSystemService(PowerManager::class.java)?.isPowerSaveMode == true) return true
+        // ACTION_BATTERY_CHANGED is sticky: a null receiver reads it right now.
+        val battery = context.registerReceiver(null, IntentFilter(Intent.ACTION_BATTERY_CHANGED)) ?: return false
+        val level = battery.getIntExtra(BatteryManager.EXTRA_LEVEL, -1)
+        val scale = battery.getIntExtra(BatteryManager.EXTRA_SCALE, -1)
+        val pluggedIn = battery.getIntExtra(BatteryManager.EXTRA_PLUGGED, 0) != 0
+        return level >= 0 && scale > 0 && !pluggedIn && level * 100 < scale * 20
+    }
+
+    @Synchronized
+    fun updatePowerMode(context: Context, options: JSONObject?): JSONObject {
+        requireOwner(context, options)
+        val mode = requestedPowerMode(options, null)
+        if (!isActive(context)) throw CraftRecordingException("NO_ACTIVE_RECORDING", "No active location recording")
+        edit(context) { it.putString("powerMode", mode).remove("powerSaver") }
+        return state(context)
     }
 
     @Synchronized
@@ -138,7 +199,7 @@ object CraftLocationRecordingStore {
         val stopped = state(context, includeLocations = true)
         commit(context, false, false)
         listener = null
-        return stopped.put("active", false).put("paused", false)
+        return stopped.put("active", false).put("paused", false).put("effectivePowerMode", "default")
     }
     @Synchronized fun stop(context: Context) { finish(context, null) }
     @Synchronized
@@ -175,11 +236,21 @@ object CraftLocationRecordingStore {
                         if (requested !is String || requested.isBlank()) throw CraftRecordingException("INVALID_ARGUMENT", "recordingId must be a nonempty recording ID")
                         requested
                     } else java.util.UUID.randomUUID().toString()
-                    start(context, id, System.currentTimeMillis())
+                    start(context, id, System.currentTimeMillis(), requestedPowerMode(options, "default"))
                     try { ContextCompat.startForegroundService(context, Intent(context, LocationRecordingService::class.java).setAction(LocationRecordingService.ACTION_START).putExtra("recordingId", id)) }
                     catch (error: Exception) { finish(context, JSONObject().put("expectedId", id)); throw error }
                     state(context)
                 }
+                "setRecordingPowerMode" -> {
+                    val previous = powerMode(context)
+                    val updated = updatePowerMode(context, options)
+                    // The running service re-requests its updates for the new spacing.
+                    // If Android refuses to start it from the background, the stored
+                    // mode is still what the service takes up on its next start.
+                    runCatching { ContextCompat.startForegroundService(context, Intent(context, LocationRecordingService::class.java).setAction(LocationRecordingService.ACTION_START).putExtra("recordingId", recordingId(context))) }
+                        .onFailure { android.util.Log.w("CraftLocation", "Power mode $previous -> ${powerMode(context)} waits for the service", it) }
+                    updated
+                }
                 "pauseRecording" -> updatePause(context, true, options)
                 "resumeRecording" -> {
                     val permitted = ContextCompat.checkSelfPermission(context, Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED || ContextCompat.checkSelfPermission(context, Manifest.permission.ACCESS_COARSE_LOCATION) == PackageManager.PERMISSION_GRANTED
@@ -270,6 +341,8 @@ object CraftLocationRecordingStore {
             put("paused", values.getBoolean("paused", false))
             put("startedAt", values.getLong("startedAt", 0).takeIf { it > 0 } ?: JSONObject.NULL)
             put("sampleCount", locations.length())
+            put("powerMode", powerMode(context))
+            put("effectivePowerMode", if (isPowerSaver(context)) "saver" else "default")
             if (includeLocations) put("locations", locations)
         }
     }
@@ -279,7 +352,9 @@ class LocationRecordingService : Service() {
     private val client by lazy { LocationServices.getFusedLocationProviderClient(this) }
     private var callback: LocationCallback? = null
     private var callbackRecordingId: String? = null
+    private var callbackSaver = false
     private var serviceStartId = 0
+    private var powerReceiver: BroadcastReceiver? = null
 
     override fun onCreate() {
         super.onCreate()
@@ -337,7 +412,13 @@ class LocationRecordingService : Service() {
 
     private fun startUpdates(): Boolean {
         val id = CraftLocationRecordingStore.recordingId(this) ?: return false
-        if (callback != null && callbackRecordingId == id) return true
+        // `auto` can change what the recorder should do without a call: the
+        // request is only rebuilt when the mode in use is not the one it was made for.
+        val saver = CraftLocationRecordingStore.isPowerSaver(this)
+        if (callback != null && callbackRecordingId == id && callbackSaver == saver) {
+            syncPowerReceiver()
+            return true
+        }
         stopUpdates()
         if (!CraftLocationRecordingStore.isActive(this)) return false
         val hasForegroundLocation =
@@ -347,9 +428,14 @@ class LocationRecordingService : Service() {
             runCatching { CraftLocationRecordingStore.finish(this, JSONObject().put("expectedId", id)) }
             return false
         }
+        // Saving power (an ultra): fixes at least 5 m apart and delivered in
+        // batches of up to 20 s, each keeping its own time. 5 m stays under
+        // the route's 30 s pause gap at any speed that counts as moving
+        // (0.2 m/s), so distance and moving time come out as at full rate.
         val request = LocationRequest.Builder(Priority.PRIORITY_HIGH_ACCURACY, 5_000)
             .setMinUpdateIntervalMillis(2_000)
-            .setMaxUpdateDelayMillis(10_000)
+            .setMaxUpdateDelayMillis(if (saver) 20_000 else 10_000)
+            .apply { if (saver) setMinUpdateDistanceMeters(5f) }
             .build()
         val nextCallback = object : LocationCallback() {
             override fun onLocationResult(result: LocationResult) {
@@ -358,6 +444,8 @@ class LocationRecordingService : Service() {
         }
         callback = nextCallback
         callbackRecordingId = id
+        callbackSaver = saver
+        syncPowerReceiver()
         return try {
             client.requestLocationUpdates(request, nextCallback, Looper.getMainLooper())
                 .addOnFailureListener {
@@ -382,6 +470,37 @@ class LocationRecordingService : Service() {
         callback?.let { client.removeLocationUpdates(it) }
         callback = null
         callbackRecordingId = null
+        callbackSaver = false
+        powerReceiver?.let { runCatching { unregisterReceiver(it) } }
+        powerReceiver = null
+    }
+
+    /**
+     * `powerMode: 'auto'` follows Battery Saver and the charge, so the service
+     * listens for the platform's changes while a recording runs in that mode,
+     * and for no other recording.
+     */
+    private fun syncPowerReceiver() {
+        val wanted = CraftLocationRecordingStore.powerMode(this) == "auto"
+        if (!wanted) {
+            powerReceiver?.let { runCatching { unregisterReceiver(it) } }
+            powerReceiver = null
+            return
+        }
+        if (powerReceiver != null) return
+        val receiver = object : BroadcastReceiver() {
+            override fun onReceive(context: Context?, intent: Intent?) {
+                synchronized(CraftLocationRecordingStore) {
+                    if (callback != null && CraftLocationRecordingStore.isPowerSaver(this@LocationRecordingService) != callbackSaver) startUpdates()
+                }
+            }
+        }
+        powerReceiver = receiver
+        val filter = IntentFilter().apply {
+            addAction(PowerManager.ACTION_POWER_SAVE_MODE_CHANGED)
+            addAction(Intent.ACTION_BATTERY_CHANGED)
+        }
+        ContextCompat.registerReceiver(this, receiver, filter, ContextCompat.RECEIVER_NOT_EXPORTED)
     }
 
     override fun onDestroy() {

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

@@ -2677,6 +2677,24 @@ internal fun craftNativeInheritFontFamily(style: JSONObject, inherited: String?)
 }
 
 /** CSS family fallback order, using bundled app fonts before platform families. */
+/**
+ * The face a CSS stack gives the app's own chrome (title, tab and button
+ * labels): the first family packaged with the app, or null for the system
+ * face when a generic family (`system-ui`, `sans-serif`) comes first or none is
+ * packaged. Screens resolve the same stacks with `craftNativeFontFamily`.
+ */
+internal fun craftNativeChromeTypeface(stack: String?, bundledFonts: Map<String, Typeface>): Typeface? {
+    for (part in stack.orEmpty().split(',')) {
+        val name = part.trim().trim('"', '\'')
+        when (name.lowercase()) {
+            "" -> continue
+            "sans-serif", "ui-sans-serif", "system-ui", "-apple-system", "serif", "ui-serif", "monospace", "ui-monospace" -> return null
+            else -> bundledFonts[name]?.let { return it }
+        }
+    }
+    return null
+}
+
 internal fun craftNativeFontFamily(family: String?, bundledFonts: Map<String, Typeface> = emptyMap()): Typeface =
     family?.split(',')?.asSequence()?.map { it.trim().trim('"', '\'') }?.mapNotNull { name ->
         bundledFonts[name] ?: when (name.lowercase()) {
@@ -4841,7 +4859,9 @@ class MainActivity : AppCompatActivity() {
     }
 
     private fun installChrome() {
-        val bars = CraftNativeChrome(this, routes.tabs, routes.tabBarAppearance)
+        val bodyFont = craftNativeChromeTypeface(routes.fontFamily, bundledFonts)
+        val bars = CraftNativeChrome(this, routes.tabs, routes.tabBarAppearance,
+            CraftNativeChromeFonts(bodyFont, craftNativeChromeTypeface(routes.headingFontFamily, bundledFonts) ?: bodyFont))
         bars.layoutParams = FrameLayout.LayoutParams(-1, -1)
         bars.onBack = { onBackPressedDispatcherCompat() }
         bars.onAccessory = { path -> navigateOpen(path) }

package/dist/api/mobile.d.ts

@@ -558,10 +558,42 @@ export interface LocationOptions {
 export interface RecordingStartOptions {
     recordingId?: string;
 }
+/**
+ * How hard a route recording works the GPS. `'saver'` is for a long effort (an
+ * ultra): fixes come at least 5 m apart rather than every second, and while
+ * the pace holds steady iOS asks for ten-metre accuracy instead of the best it
+ * can do, going back to the best at once when the pace or the signal changes.
+ * Fixes stay under 30 s apart at any speed that counts as moving, so distance
+ * and moving time come out as they would at full rate. Android asks for the
+ * same spacing and batches delivery.
+ *
+ * `'auto'` saves power only while the device wants it: iOS Low Power Mode or
+ * Android Battery Saver is on, or the battery is under 20% and not charging.
+ * The host re-checks whenever the platform reports a change, so a recording
+ * moves between `'saver'` and `'default'` by itself. Read which one it is using
+ * from `effectivePowerMode` on the recording's state.
+ */
+export type LocationRecordingPowerMode = 'default' | 'saver' | 'auto';
+/** What a recording is actually using right now: `'auto'` resolves to one of these. */
+export type LocationRecordingEffectivePowerMode = 'default' | 'saver';
+export interface LocationRecordingPowerOptions {
+    powerMode?: LocationRecordingPowerMode;
+}
+/**
+ * Change the power mode of the recording that is running, fenced to its ID
+ * like pause, resume and stop.
+ */
+export interface LocationRecordingPowerModeOptions extends RecordingOwnershipOptions {
+    powerMode: LocationRecordingPowerMode;
+}
 /** Fence a recording operation to the ID returned by start or explicit recovery. */
 export interface RecordingOwnershipOptions {
     expectedId: string;
 }
+/** Reading a route back: `since` (epoch ms) asks only for the fixes recorded after it. */
+export interface LocationRecordingReadOptions extends RecordingOwnershipOptions {
+    since?: number;
+}
 /** Secure IDs supplied by the platform, including WebView-free mobile hosts. */
 export declare const crypto: {
     randomUUID(): Promise<string>;
@@ -584,6 +616,10 @@ export interface LocationRecordingState {
     paused: boolean;
     startedAt: number | null;
     sampleCount?: number;
+    /** The mode asked for (`'default'` on a host that predates power modes). */
+    powerMode?: LocationRecordingPowerMode;
+    /** The mode in use now. `'default'` once the recording has stopped. */
+    effectivePowerMode?: LocationRecordingEffectivePowerMode;
 }
 export interface LocationRecordingResult extends LocationRecordingState {
     locations: Location[];
@@ -609,6 +645,8 @@ export interface LocationRecordingResult extends LocationRecordingState {
 export declare const location: {
     supportsRecordingOwnership: () => boolean;
     supportsRecordingIntentIdentity: () => boolean;
+    /** `setRecordingPowerMode()` and `powerMode: 'auto'` work on this host. */
+    supportsRecordingPowerMode: () => boolean;
     /**
      * Get current position.
      *
@@ -630,13 +668,32 @@ export declare const location: {
      * @param watchId - Watch ID returned from watchPosition
      */
     clearWatch(watchId: number): void;
-    startRecording(options?: LocationOptions & RecordingStartOptions): Promise<LocationRecordingState>;
+    startRecording(options?: LocationOptions & RecordingStartOptions & LocationRecordingPowerOptions): Promise<LocationRecordingState>;
+    /**
+     * Change how hard the running recording works the GPS, for example to
+     * `'saver'` while the screen shows nothing but a countdown and back to
+     * `'default'` afterwards, or to `'auto'` to follow the device's own power
+     * saving. Resolves with the recording's state, which reports the mode asked
+     * for (`powerMode`) and the one in use (`effectivePowerMode`).
+     *
+     * Rejects with `NO_ACTIVE_RECORDING` when nothing is recording,
+     * `RECORDING_CONFLICT` when `expectedId` is not the recording that is
+     * running, `INVALID_ARGUMENT` for an unknown mode, and
+     * `RECORDING_POWER_MODE_UNSUPPORTED` on a host built before this existed
+     * (check `supportsRecordingPowerMode()`).
+     */
+    setRecordingPowerMode(options: LocationRecordingPowerModeOptions): Promise<LocationRecordingState>;
     pauseRecording(options?: RecordingOwnershipOptions): Promise<LocationRecordingState>;
     resumeRecording(options?: RecordingOwnershipOptions): Promise<LocationRecordingState>;
     stopRecording(options?: RecordingOwnershipOptions): Promise<LocationRecordingResult>;
     getRecordingState(options?: RecordingOwnershipOptions): Promise<LocationRecordingState>;
     acknowledgeRecording(options: RecordingOwnershipOptions): Promise<boolean>;
-    readRecording(options?: RecordingOwnershipOptions): Promise<Location[]>;
+    /**
+     * The recording's fixes. With `since`, iOS reads only the fixes after it
+     * from the end of the track; a host that does not know `since` answers with
+     * every fix, so a caller skips those it already has.
+     */
+    readRecording(options?: LocationRecordingReadOptions): Promise<Location[]>;
 };
 /**
  * Share options.

package/dist/cli.js

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

package/dist/index.cjs

@@ -375,7 +375,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.396";
+var version = "0.0.408";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;
@@ -5491,6 +5491,7 @@ var secureStorage = {
     Object.keys(localStorage).filter((k) => k.startsWith("secure_")).forEach((k) => localStorage.removeItem(k));
   }
 };
+var RECORDING_POWER_MODES = ["default", "saver", "auto"];
 function storageHost(method) {
   const host = getCraftRoot()?.storage;
   if (typeof host?.[method] !== "function")
@@ -5554,6 +5555,23 @@ function recordingIntentSupported(namespace) {
   const advertised = Array.isArray(caps) ? caps.includes(flag) : caps?.[flag] === true;
   return advertised && recordingOwnershipSupported(namespace) && typeof root?.[namespace]?.startRecording === "function";
 }
+function recordingPowerModeSupported() {
+  const root = getCraftRoot();
+  const caps = root?.capabilities;
+  const advertised = Array.isArray(caps) ? caps.includes("locationRecordingPowerMode") : caps?.locationRecordingPowerMode === true;
+  return advertised && recordingOwnershipSupported("location") && typeof root?.location?.setRecordingPowerMode === "function";
+}
+function validatePowerMode(value) {
+  if (typeof value !== "string" || !RECORDING_POWER_MODES.includes(value))
+    throw Object.assign(new Error("powerMode must be 'default', 'saver' or 'auto'"), { code: "INVALID_ARGUMENT" });
+  return value;
+}
+function validateRecordingPowerStart(options) {
+  if (!Object.prototype.hasOwnProperty.call(options, "powerMode") || options.powerMode === undefined)
+    return;
+  if (validatePowerMode(options.powerMode) === "auto" && getCraftRoot() && !recordingPowerModeSupported())
+    throw Object.assign(new Error("This app build cannot start a recording in powerMode 'auto'"), { code: "RECORDING_POWER_MODE_UNSUPPORTED" });
+}
 function validateRecordingStart(namespace, options) {
   if (!Object.prototype.hasOwnProperty.call(options, "recordingId"))
     return;
@@ -5584,10 +5602,20 @@ var webLocationRecording = {
   startedAt: null,
   locations: []
 };
+var webLocationPowerMode = "default";
+function webLocationRecordingState() {
+  return {
+    ...webLocationRecording,
+    sampleCount: webLocationRecording.locations.length,
+    powerMode: webLocationPowerMode,
+    effectivePowerMode: webLocationRecording.active && webLocationPowerMode === "saver" ? "saver" : "default"
+  };
+}
 var webLocationRecordingWatchId = null;
 var location = {
   supportsRecordingOwnership: () => recordingOwnershipSupported("location"),
   supportsRecordingIntentIdentity: () => recordingIntentSupported("location"),
+  supportsRecordingPowerMode: () => recordingPowerModeSupported(),
   async getCurrentPosition(options = {}) {
     const craft = getCraftMobile();
     if (typeof window !== "undefined" && craft?.location) {
@@ -5637,6 +5665,7 @@ var location = {
   },
   async startRecording(options = {}) {
     validateRecordingStart("location", options);
+    validateRecordingPowerStart(options);
     const craft = getCraftMobile();
     if (typeof window !== "undefined" && craft?.location?.startRecording)
       return verifyRecordingStart(options, await craft.location.startRecording(options));
@@ -5651,11 +5680,27 @@ var location = {
       startedAt: Date.now(),
       locations: []
     };
+    webLocationPowerMode = options.powerMode ?? "default";
     webLocationRecordingWatchId = location.watchPosition((position) => {
       if (!webLocationRecording.paused)
         webLocationRecording.locations.push(position);
     }, options);
-    return { ...webLocationRecording, sampleCount: 0 };
+    return webLocationRecordingState();
+  },
+  async setRecordingPowerMode(options) {
+    if (!options || !Object.prototype.hasOwnProperty.call(options, "expectedId"))
+      throw Object.assign(new Error("setRecordingPowerMode needs expectedId"), { code: "INVALID_ARGUMENT" });
+    validateRecordingOwnership("location", options);
+    const powerMode = validatePowerMode(options.powerMode);
+    if (getCraftRoot() && !recordingPowerModeSupported())
+      throw Object.assign(new Error("This app build cannot change the recording power mode"), { code: "RECORDING_POWER_MODE_UNSUPPORTED" });
+    const craft = getCraftMobile();
+    if (typeof window !== "undefined" && craft?.location?.setRecordingPowerMode)
+      return craft.location.setRecordingPowerMode({ expectedId: options.expectedId, powerMode });
+    if (!webLocationRecording.active)
+      throw Object.assign(new Error("No active location recording"), { code: "NO_ACTIVE_RECORDING" });
+    webLocationPowerMode = powerMode;
+    return webLocationRecordingState();
   },
   async pauseRecording(options) {
     validateRecordingOwnership("location", options);
@@ -5663,7 +5708,7 @@ var location = {
     if (typeof window !== "undefined" && craft?.location?.pauseRecording)
       return craft.location.pauseRecording(options);
     webLocationRecording.paused = true;
-    return { ...webLocationRecording, sampleCount: webLocationRecording.locations.length };
+    return webLocationRecordingState();
   },
   async resumeRecording(options) {
     validateRecordingOwnership("location", options);
@@ -5671,7 +5716,7 @@ var location = {
     if (typeof window !== "undefined" && craft?.location?.resumeRecording)
       return craft.location.resumeRecording(options);
     webLocationRecording.paused = false;
-    return { ...webLocationRecording, sampleCount: webLocationRecording.locations.length };
+    return webLocationRecordingState();
   },
   async stopRecording(options) {
     validateRecordingOwnership("location", options);
@@ -5684,14 +5729,14 @@ var location = {
     }
     webLocationRecording.active = false;
     webLocationRecording.paused = false;
-    return { ...webLocationRecording, locations: [...webLocationRecording.locations] };
+    return { ...webLocationRecordingState(), locations: [...webLocationRecording.locations] };
   },
   async getRecordingState(options) {
     validateRecordingOwnership("location", options);
     const craft = getCraftMobile();
     if (typeof window !== "undefined" && craft?.location?.getRecordingState)
       return craft.location.getRecordingState(options);
-    return { ...webLocationRecording, sampleCount: webLocationRecording.locations.length };
+    return webLocationRecordingState();
   },
   async acknowledgeRecording(options) {
     if (!options || !Object.prototype.hasOwnProperty.call(options, "expectedId"))
@@ -5703,6 +5748,7 @@ var location = {
     if (webLocationRecording.active)
       throw Object.assign(new Error("The recording is still active"), { code: "RECORDING_ALREADY_ACTIVE" });
     webLocationRecording = { id: null, active: false, paused: false, startedAt: null, locations: [] };
+    webLocationPowerMode = "default";
     return true;
   },
   async readRecording(options) {
@@ -5710,7 +5756,8 @@ var location = {
     const craft = getCraftMobile();
     if (typeof window !== "undefined" && craft?.location?.readRecording)
       return craft.location.readRecording(options);
-    return [...webLocationRecording.locations];
+    const since = options?.since;
+    return typeof since === "number" && Number.isFinite(since) ? webLocationRecording.locations.filter((location) => location.timestamp > since) : [...webLocationRecording.locations];
   }
 };
 var share = {