craft-native 0.0.237 → 0.0.238

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

@@ -78,7 +78,12 @@ internal object CraftNativeHub {
 /** A screen of the app found for a path. */
 internal data class CraftNativeRouteMatch(val screen: String, val params: JSONObject, val path: String)
 
-internal data class CraftNativeTab(val id: String, val title: String, val symbol: String)
+internal data class CraftNativeTab(
+    val id: String, val title: String, val symbol: String,
+    val selectedSymbol: String? = null, val selectedIconTint: String? = null, val selectedIconPulse: Boolean? = null,
+)
+
+internal data class CraftTabIconAppearance(val symbol: String, val tint: Int?, val pulse: Boolean)
 
 /** The app's paths (`nativeScreens`), its tabs and its site. */
 internal class CraftNativeRoutes(config: JSONObject) {
@@ -107,7 +112,10 @@ internal class CraftNativeRoutes(config: JSONObject) {
         for (index in 0 until list.length()) {
             val tab = list.optJSONObject(index) ?: continue
             val id = tab.optString("id").takeIf { it.isNotBlank() } ?: continue
-            add(CraftNativeTab(normalize(id), tab.optString("title", id), tab.optString("symbol")))
+            add(CraftNativeTab(normalize(id), tab.optString("title", id), tab.optString("symbol"),
+                tab.optString("selectedSymbol").trim().takeUnless { tab.isNull("selectedSymbol") || it.isBlank() },
+                tab.optString("selectedIconTint").takeUnless { tab.isNull("selectedIconTint") || it.isBlank() },
+                if (tab.opt("selectedIconPulse") is Boolean) tab.optBoolean("selectedIconPulse") else null))
         }
     }
 
@@ -226,6 +234,39 @@ internal class CraftNativeRoutes(config: JSONObject) {
  *
  * Writes happen on one background thread, in order.
  */
+/** One process-wide boundary for committed storage reads and mutations. */
+internal object CraftNativeStorage {
+    val lock = Any()
+    fun jsonEqual(left: Any?, right: Any?): Boolean {
+        if (left == null || left === JSONObject.NULL) return right == null || right === JSONObject.NULL
+        if (left is Boolean || right is Boolean) return left is Boolean && right is Boolean && left == right
+        if (left is Number && right is Number) return java.math.BigDecimal(left.toString()).compareTo(java.math.BigDecimal(right.toString())) == 0
+        if (left is JSONObject && right is JSONObject) return left.length() == right.length() && left.keys().asSequence().all { right.has(it) && jsonEqual(left.get(it), right.get(it)) }
+        if (left is JSONArray && right is JSONArray) return left.length() == right.length() && (0 until left.length()).all { jsonEqual(left.get(it), right.get(it)) }
+        return left is String && right is String && left == right
+    }
+    fun commit(storage: SharedPreferences, update: (android.content.SharedPreferences.Editor) -> Unit): Boolean {
+        val previous = storage.all
+        val editor = storage.edit()
+        update(editor)
+        if (editor.commit()) return true
+        // A failed commit has already changed SharedPreferences' memory map.
+        // Restore it before a later draft read can mistake it for a checkpoint.
+        val rollback = storage.edit().clear()
+        previous.forEach { (key, value) -> when (value) {
+            is String -> rollback.putString(key, value)
+            is Boolean -> rollback.putBoolean(key, value)
+            is Long -> rollback.putLong(key, value)
+            is Int -> rollback.putInt(key, value)
+            is Float -> rollback.putFloat(key, value)
+            else -> error("Invalid stored value")
+        } }
+        rollback.commit()
+        return false
+    }
+
+}
+
 internal class CraftNativeStores private constructor(context: Context, private val secureEnabled: Boolean) {
     private val appContext = context.applicationContext
     private val storage: SharedPreferences = appContext.getSharedPreferences("craft-native-storage", Context.MODE_PRIVATE)
@@ -281,7 +322,7 @@ internal class CraftNativeStores private constructor(context: Context, private v
             out.append('}')
         }
         out.append('{')
-        section("storage", storage.all.mapNotNull { (key, value) -> (value as? String)?.let { key to it } }.toMap())
+        section("storage", synchronized(CraftNativeStorage.lock) { storage.all.mapNotNull { (key, value) -> (value as? String)?.let { key to it } }.toMap() })
         out.append(',')
         section("secure", runCatching { secure?.all?.mapNotNull { (key, value) -> (value as? String)?.let { key to it } }?.toMap() }.getOrNull() ?: emptyMap())
         out.append(',')
@@ -297,8 +338,14 @@ internal class CraftNativeStores private constructor(context: Context, private v
 
     /** `craft.storage.setSync`: null removes the key. Tells every isolate. */
     fun setStorage(key: String, json: String?, from: String?) {
-        if (json == null) storage.edit().remove(key).apply() else storage.edit().putString(key, json).apply()
-        changed("storage", key, json, from)
+        synchronized(CraftNativeStorage.lock) {
+            val previous = storage.getString(key, null)
+            val kept = CraftNativeStorage.commit(storage) {
+                if (json == null) it.remove(key) else it.putString(key, json)
+            }
+            if (kept) changed("storage", key, json, from)
+            else changed("storage", key, previous, null)
+        }
     }
 
     /** `craft.snapshots.set`: null deletes it. `done` hears whether it was kept, on the main thread. */
@@ -647,9 +694,13 @@ internal class CraftNativeChrome(context: Context, private val tabs: List<CraftN
     private val tabAccessibilityLabels = mutableMapOf<String, String>()
     private val tabIconTints = mutableMapOf<String, Int>()
     private val tabIconPulses = mutableSetOf<String>()
+    private val selectedSymbols = mutableMapOf<String, String>()
+    private val selectedIconTints = mutableMapOf<String, Int>()
+    private val selectedIconPulses = mutableMapOf<String, Boolean>()
     private val tabImageURLs = mutableMapOf<String, String>()
     private val tabImages = mutableMapOf<String, android.graphics.drawable.Drawable>()
     private val navButtonSpecs = mutableMapOf<TextView, JSONObject>()
+    private var renderedButtonSpecs: Pair<String, String>? = null
     private val density = resources.displayMetrics.density
     private var screenBackgroundColor: Int? = null
     private var selectedTab = 0
@@ -705,6 +756,9 @@ internal class CraftNativeChrome(context: Context, private val tabs: List<CraftN
         tabBar.orientation = HORIZONTAL
         tabBar.gravity = Gravity.CENTER
         tabs.forEachIndexed { index, tab ->
+            tab.selectedSymbol?.trim()?.takeIf { it.isNotEmpty() }?.let { selectedSymbols[tab.id] = it }
+            tab.selectedIconTint?.let { runCatching { Color.parseColor(it) }.getOrNull() }?.let { selectedIconTints[tab.id] = it }
+            tab.selectedIconPulse?.let { selectedIconPulses[tab.id] = it }
             val cell = LinearLayout(context)
             cell.orientation = VERTICAL
             cell.gravity = Gravity.CENTER
@@ -812,18 +866,24 @@ internal class CraftNativeChrome(context: Context, private val tabs: List<CraftN
         titleView.text = if (large) "" else title
         largeTitleView.text = title
         largeTitleView.visibility = if (!hidden && large && title.isNotBlank()) View.VISIBLE else View.GONE
-        buttons.removeAllViews()
-        leadingButtons.removeAllViews()
-        navButtonSpecs.clear()
         val leading = options.optJSONArray("leftButtons") ?: JSONArray()
-        for (index in 0 until leading.length()) {
-            val button = leading.optJSONObject(index) ?: continue
-            leadingButtons.addView(navButton(button))
-        }
         val list = options.optJSONArray("rightButtons") ?: JSONArray()
-        for (index in 0 until list.length()) {
-            val button = list.optJSONObject(index) ?: continue
-            buttons.addView(navButton(button))
+        // The activity passes cumulative screen options, even for a live BPM
+        // patch. Keep unchanged toolbar views, images and touch targets alive.
+        val buttonSpecs = leading.toString() to list.toString()
+        if (buttonSpecs != renderedButtonSpecs) {
+            buttons.removeAllViews()
+            leadingButtons.removeAllViews()
+            navButtonSpecs.clear()
+            for (index in 0 until leading.length()) {
+                val button = leading.optJSONObject(index) ?: continue
+                leadingButtons.addView(navButton(button))
+            }
+            for (index in 0 until list.length()) {
+                val button = list.optJSONObject(index) ?: continue
+                buttons.addView(navButton(button))
+            }
+            renderedButtonSpecs = buttonSpecs
         }
         val tabBarHidden = options.optBoolean("tabBarHidden", false) || depth > 0 && options.optBoolean("tabBarHiddenWhenPushed", false)
         tabRow.visibility = if (tabs.isEmpty() || tabBarHidden) View.GONE else View.VISIBLE
@@ -869,6 +929,18 @@ internal class CraftNativeChrome(context: Context, private val tabs: List<CraftN
         if (item.has("iconPulse")) {
             if (item.optBoolean("iconPulse", false)) tabIconPulses.add(id) else tabIconPulses.remove(id)
         }
+        if (item.has("selectedSymbol")) {
+            selectedSymbols.remove(id)
+            item.optString("selectedSymbol").trim().takeUnless { item.isNull("selectedSymbol") || it.isBlank() }?.let { selectedSymbols[id] = it }
+        }
+        if (item.has("selectedIconTint")) {
+            selectedIconTints.remove(id)
+            if (!item.isNull("selectedIconTint")) runCatching { Color.parseColor(item.optString("selectedIconTint")) }.getOrNull()?.let { selectedIconTints[id] = it }
+        }
+        if (item.has("selectedIconPulse")) {
+            selectedIconPulses.remove(id)
+            if (item.opt("selectedIconPulse") is Boolean) selectedIconPulses[id] = item.optBoolean("selectedIconPulse")
+        }
         if (item.has("image")) {
             val address = item.optString("image").takeIf { !item.isNull("image") && it.startsWith("https://") }
             if (address != tabImageURLs[id]) {
@@ -892,7 +964,17 @@ internal class CraftNativeChrome(context: Context, private val tabs: List<CraftN
                 }
             }
         }
-        refreshColors()
+    }
+
+    /** Selection belongs to the native tab stack, including retained pushed screens. */
+    internal fun tabIconAppearance(index: Int, motionAllowed: Boolean): CraftTabIconAppearance {
+        val tab = tabs[index]
+        val selected = index == selectedTab
+        return CraftTabIconAppearance(
+            if (selected) selectedSymbols[tab.id] ?: tab.symbol else tab.symbol,
+            if (selected) selectedIconTints[tab.id] ?: tabIconTints[tab.id] else tabIconTints[tab.id],
+            (if (selected) selectedIconPulses[tab.id] ?: tabIconPulses.contains(tab.id) else tabIconPulses.contains(tab.id)) && motionAllowed,
+        )
     }
 
     /** Light or dark changed: the bars follow the screen's background. */
@@ -917,13 +999,14 @@ internal class CraftNativeChrome(context: Context, private val tabs: List<CraftN
             val color = if (index == selectedTab) accent else muted
             val id = tabs[index].id
             val number = tabIconText[id]
-            val iconColor = tabIconTints[id] ?: if (number != null) Color.parseColor("#FF2D55") else color
+            val appearance = tabIconAppearance(index, hasWindowFocus() && tabRow.isShown && android.animation.ValueAnimator.areAnimatorsEnabled())
+            val iconColor = appearance.tint ?: if (number != null) Color.parseColor("#FF2D55") else color
             icon.setTextColor(iconColor)
             label.text = tabTitles[id] ?: tabs[index].title
             tabBar.getChildAt(index).contentDescription = tabAccessibilityLabels[id] ?: label.text
             label.setTextColor(color)
-            val vector = tabImages[id] ?: if (number == null) CraftNativeIcons.drawable(context, null, tabs[index].symbol, iconColor) else null
-            val pulse = tabIconPulses.contains(id) && number == null && tabImages[id] == null && hasWindowFocus() && android.animation.ValueAnimator.areAnimatorsEnabled()
+            val vector = tabImages[id] ?: if (number == null) CraftNativeIcons.drawable(context, null, appearance.symbol, iconColor) else null
+            val pulse = appearance.pulse && number == null && tabImages[id] == null
             if (pulse && icon.animation == null) {
                 icon.startAnimation(android.view.animation.AlphaAnimation(1f, 0.55f).apply {
                     duration = 700
@@ -935,7 +1018,7 @@ internal class CraftNativeChrome(context: Context, private val tabs: List<CraftN
                 icon.alpha = 1f
             }
             icon.foreground = vector
-            icon.text = if (vector != null) "" else number ?: CraftNativeSymbols.glyph(tabs[index].symbol)
+            icon.text = if (vector != null) "" else number ?: CraftNativeSymbols.glyph(appearance.symbol)
         }
         navButtonSpecs.forEach { (view, spec) -> applyNavButtonTint(view, spec, dark) }
     }

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

@@ -21,71 +21,246 @@ import org.json.JSONArray
 import org.json.JSONObject
 import java.io.File
 
+class CraftRecordingException(val code: String, message: String) : IllegalStateException(message)
+
 object CraftLocationRecordingStore {
     private const val PREFS = "craft_location_recording"
     private const val FILE = "craft-location-recording.jsonl"
-
     private fun prefs(context: Context) = context.getSharedPreferences(PREFS, Context.MODE_PRIVATE)
     private fun file(context: Context) = File(context.filesDir, FILE)
+    private fun archive(context: Context, id: String): File {
+        val digest = java.security.MessageDigest.getInstance("SHA-256").digest(id.toByteArray(Charsets.UTF_8))
+        return File(context.filesDir, "craft-location-completed-${digest.joinToString("") { "%02x".format(it) }}.json")
+    }
+    private fun acknowledged(context: Context, id: String): Boolean {
+        val marker = File(archive(context, id).path.replace("-completed-", "-ack-"))
+        if (!marker.exists()) return false
+        if (marker.readText() != id) throw CraftRecordingException("RECORDING_STORAGE_ERROR", "Invalid recording acknowledgement")
+        return true
+    }
+    private fun writeAtomic(destination: File, value: String) {
+        val temporary = File.createTempFile(".craft-recording-", ".tmp", destination.parentFile)
+        try {
+            java.io.FileOutputStream(temporary).use { stream -> stream.write(value.toByteArray(Charsets.UTF_8)); stream.fd.sync() }
+            java.nio.file.Files.move(temporary.toPath(), destination.toPath(), java.nio.file.StandardCopyOption.ATOMIC_MOVE)
+        } finally { temporary.delete() }
+    }
+    private fun expected(options: JSONObject?): String? {
+        if (options == null || !options.has("expectedId")) return null
+        val id = options.opt("expectedId")
+        if (id !is String || id.isBlank()) throw CraftRecordingException("INVALID_ARGUMENT", "expectedId must be a nonempty recording ID")
+        return id
+    }
+    private fun requireOwner(context: Context, options: JSONObject?) {
+        val id = expected(options) ?: return
+        if (id != prefs(context).getString("id", null)) throw CraftRecordingException("RECORDING_CONFLICT", "The active location recording has changed")
+    }
+    private fun completed(context: Context, id: String?): JSONObject? {
+        if (id == null) return null
+        val source = archive(context, id)
+        if (acknowledged(context, id)) {
+            if (source.exists() && !source.delete()) throw CraftRecordingException("RECORDING_STORAGE_ERROR", "Unable to remove acknowledged recording")
+            throw CraftRecordingException("RECORDING_NOT_FOUND", "This recording has been acknowledged")
+        }
+        if (!source.exists()) return null
+        val saved = JSONObject(source.readText())
+        if (saved.optString("id") != id || saved.optBoolean("active") || saved.optJSONArray("locations") == null)
+            throw CraftRecordingException("RECORDING_STORAGE_ERROR", "Invalid completed recording archive")
+        return saved
+    }
+    private fun archiveCompleted(context: Context) {
+        val id = prefs(context).getString("id", null) ?: return
+        if (acknowledged(context, id) || completed(context, id) != null) return
+        val saved = state(context, includeLocations = true)
+        val destination = archive(context, id)
+        writeAtomic(destination, saved.toString())
+    }
+    private fun edit(context: Context, update: (android.content.SharedPreferences.Editor) -> Unit) {
+        val values = prefs(context)
+        val previous = values.all.toMap()
+        val editor = values.edit()
+        update(editor)
+        if (editor.commit()) return
+        // SharedPreferences publishes its memory map before reporting disk
+        // failure. Restore it too, so a rejected operation cannot change owner.
+        val rollback = values.edit().clear()
+        previous.forEach { (key, value) -> when (value) {
+            is String -> rollback.putString(key, value)
+            is Boolean -> rollback.putBoolean(key, value)
+            is Long -> rollback.putLong(key, value)
+            is Int -> rollback.putInt(key, value)
+            is Float -> rollback.putFloat(key, value)
+            else -> throw CraftRecordingException("RECORDING_STORAGE_ERROR", "Invalid recording metadata")
+        } }
+        rollback.commit()
+        throw CraftRecordingException("RECORDING_STORAGE_ERROR", "Unable to persist recording state")
+    }
+    private fun commit(context: Context, active: Boolean, paused: Boolean) {
+        edit(context) { it.putBoolean("active", active).putBoolean("paused", paused) }
+    }
+
+    @Synchronized
+    fun recover(context: Context) {
+        val id = recordingId(context) ?: return
+        if (!acknowledged(context, id)) return
+        val saved = archive(context, id)
+        if (saved.exists() && !saved.delete()) throw CraftRecordingException("RECORDING_STORAGE_ERROR", "Unable to remove acknowledged recording")
+        if (file(context).exists() && !file(context).delete()) throw CraftRecordingException("RECORDING_STORAGE_ERROR", "Unable to remove acknowledged samples")
+        edit(context) { it.remove("id").remove("startedAt").putBoolean("active", false).putBoolean("paused", false) }
+        listener = null
+    }
 
     @Synchronized
     fun start(context: Context, id: String, startedAt: Long) {
+        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("")
-        prefs(context).edit()
-            .putString("id", id)
-            .putBoolean("active", true)
-            .putBoolean("paused", false)
-            .putLong("startedAt", startedAt)
-            .apply()
+        edit(context) { it.putString("id", id).putBoolean("active", true).putBoolean("paused", false).putLong("startedAt", startedAt) }
     }
 
     @Synchronized
-    fun setPaused(context: Context, paused: Boolean) {
-        prefs(context).edit().putBoolean("paused", paused).apply()
+    fun updatePause(context: Context, paused: Boolean, options: JSONObject?): JSONObject {
+        requireOwner(context, options)
+        if (!isActive(context)) throw CraftRecordingException("NO_ACTIVE_RECORDING", "No active location recording")
+        commit(context, true, paused)
+        return state(context)
     }
+    @Synchronized fun setPaused(context: Context, paused: Boolean) { updatePause(context, paused, null) }
 
     @Synchronized
-    fun stop(context: Context) {
-        prefs(context).edit().putBoolean("active", false).putBoolean("paused", false).apply()
+    fun finish(context: Context, options: JSONObject?): JSONObject {
+        completed(context, expected(options))?.let { return it }
+        requireOwner(context, options)
+        val stopped = state(context, includeLocations = true)
+        commit(context, false, false)
+        listener = null
+        return stopped.put("active", false).put("paused", false)
+    }
+    @Synchronized fun stop(context: Context) { finish(context, null) }
+    @Synchronized
+    fun acknowledge(context: Context, options: JSONObject?): Boolean {
+        val id = expected(options) ?: throw CraftRecordingException("INVALID_ARGUMENT", "Acknowledgement needs expectedId")
+        val current = recordingId(context) == id
+        if (current && isActive(context)) throw CraftRecordingException("RECORDING_ALREADY_ACTIVE", "The recording is still active")
+        if (!current && !acknowledged(context, id) && completed(context, id) == null)
+            throw CraftRecordingException("RECORDING_CONFLICT", "Unknown recording ID")
+        val saved = archive(context, id)
+        val marker = File(saved.path.replace("-completed-", "-ack-"))
+        if (!marker.exists()) writeAtomic(marker, id)
+        if (saved.exists() && !saved.delete()) throw CraftRecordingException("RECORDING_STORAGE_ERROR", "Unable to remove completed recording")
+        if (current) {
+            if (file(context).exists() && !file(context).delete()) throw CraftRecordingException("RECORDING_STORAGE_ERROR", "Unable to remove recording samples")
+            edit(context) { it.remove("id").remove("startedAt").putBoolean("active", false).putBoolean("paused", false) }
+            listener = null
+        }
+        return true
     }
 
-    fun isActive(context: Context) = prefs(context).getBoolean("active", false)
-    fun isPaused(context: Context) = prefs(context).getBoolean("paused", false)
+    /** One native backend used by the STX host and the page's JNI entry point. */
+    @JvmStatic
+    fun perform(context: Context, method: String, optionsJson: String): String = synchronized(this) {
+        return try {
+            recover(context)
+            val options = JSONObject(optionsJson)
+            val result: Any = when (method) {
+                "startRecording" -> {
+                    val permitted = ContextCompat.checkSelfPermission(context, Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED || ContextCompat.checkSelfPermission(context, Manifest.permission.ACCESS_COARSE_LOCATION) == PackageManager.PERMISSION_GRANTED
+                    if (!permitted) throw CraftRecordingException("PERMISSION_DENIED", "Location is not allowed")
+                    val id = if (options.has("recordingId")) {
+                        val requested = options.opt("recordingId")
+                        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())
+                    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)
+                }
+                "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
+                    if (!permitted) throw CraftRecordingException("PERMISSION_DENIED", "Location is not allowed")
+                    val wasPaused = isPaused(context)
+                    val resumed = updatePause(context, false, options)
+                    try { ContextCompat.startForegroundService(context, Intent(context, LocationRecordingService::class.java).setAction(LocationRecordingService.ACTION_START).putExtra("recordingId", recordingId(context))) }
+                    catch (error: Exception) { updatePause(context, wasPaused, options); throw error }
+                    resumed
+                }
+                "stopRecording" -> {
+                    val stopped = finish(context, options)
+                    if (stopped.optString("id") == recordingId(context) && !isActive(context))
+                        context.startService(Intent(context, LocationRecordingService::class.java).setAction(LocationRecordingService.ACTION_STOP).putExtra("recordingId", stopped.optString("id")))
+                    stopped
+                }
+                "getRecordingState" -> state(context, options = options)
+                "readRecording" -> read(context, options)
+                "acknowledgeRecording" -> acknowledge(context, options)
+                else -> throw CraftRecordingException("UNKNOWN_ACTION", "Unsupported Location method")
+            }
+            JSONObject().put("ok", true).put("data", result).toString()
+        } catch (error: Exception) {
+            JSONObject().put("ok", false).put("code", (error as? CraftRecordingException)?.code ?: "RECORDING_STORAGE_ERROR").put("message", error.message ?: "Recording failed").toString()
+        }
+    }
 
-    /**
-     * Hears each fix the recording keeps, while the app is running: a native
-     * screen shows the route growing (`craftLocationUpdate`).
-     */
-    @Volatile var listener: ((android.location.Location) -> Unit)? = null
+    @Synchronized fun isActive(context: Context) = prefs(context).getBoolean("active", false)
+    @Synchronized fun isPaused(context: Context) = prefs(context).getBoolean("paused", false)
+    @Synchronized fun recordingId(context: Context): String? = prefs(context).getString("id", null)
+    @Volatile var listener: ((android.location.Location, String) -> Unit)? = null
+    @Volatile var nativeListener: ((android.location.Location, String) -> Unit)? = null
 
     @Synchronized
-    fun append(context: Context, location: android.location.Location) {
-        if (!isActive(context) || isPaused(context)) return
-        listener?.invoke(location)
-        val json = JSONObject().apply {
-            put("latitude", location.latitude)
-            put("longitude", location.longitude)
-            put("accuracy", location.accuracy)
-            put("altitude", location.altitude)
-            put("speed", location.speed)
-            put("heading", location.bearing)
-            put("timestamp", location.time)
+    fun listen(context: Context, id: String, callback: (android.location.Location, String) -> Unit) {
+        if (recordingId(context) == id && isActive(context)) listener = callback
+    }
+
+    @JvmOverloads
+    fun append(context: Context, location: android.location.Location, expectedId: String? = null) {
+        val notify = synchronized(this) {
+            val id = recordingId(context) ?: return
+            if (!isActive(context) || isPaused(context) || (expectedId != null && expectedId != id)) return
+            val json = JSONObject().apply {
+                put("latitude", location.latitude); put("longitude", location.longitude)
+                put("accuracy", location.accuracy); put("altitude", location.altitude)
+                put("speed", location.speed); put("heading", location.bearing)
+                put("timestamp", location.time); put("recordingId", recordingId(context))
+            }
+            file(context).appendText("$json\n")
+            Triple(listener, nativeListener, id)
         }
-        file(context).appendText("$json\n")
+        // The event keeps the owner captured before releasing the store lock.
+        notify.first?.invoke(location, notify.third)
+        notify.second?.invoke(location, notify.third)
     }
 
     @Synchronized
     fun locations(context: Context): JSONArray {
         val result = JSONArray()
         val source = file(context)
-        if (!source.exists()) return result
-        source.forEachLine { line ->
-            if (line.isNotBlank()) runCatching { result.put(JSONObject(line)) }
+        if (!source.exists()) {
+            val id = recordingId(context)
+            if (id != null && !acknowledged(context, id)) throw CraftRecordingException("RECORDING_STORAGE_ERROR", "Recording samples are missing")
+            return result
         }
+        source.forEachLine { line -> if (line.isNotBlank()) runCatching { result.put(JSONObject(line)) } }
         return result
     }
-
-    fun state(context: Context, includeLocations: Boolean = false): JSONObject {
+    @Synchronized
+    fun read(context: Context, options: JSONObject?): JSONArray {
+        completed(context, expected(options))?.let { return it.getJSONArray("locations") }
+        requireOwner(context, options)
+        return locations(context)
+    }
+    @Synchronized
+    fun state(context: Context, includeLocations: Boolean = false, options: JSONObject? = null): JSONObject {
+        completed(context, expected(options))?.let {
+            if (!includeLocations) it.remove("locations")
+            return it
+        }
+        requireOwner(context, options)
         val values = prefs(context)
         val locations = locations(context)
         return JSONObject().apply {
@@ -102,6 +277,8 @@ object CraftLocationRecordingStore {
 class LocationRecordingService : Service() {
     private val client by lazy { LocationServices.getFusedLocationProviderClient(this) }
     private var callback: LocationCallback? = null
+    private var callbackRecordingId: String? = null
+    private var serviceStartId = 0
 
     override fun onCreate() {
         super.onCreate()
@@ -120,28 +297,52 @@ class LocationRecordingService : Service() {
     }
 
     override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+        return synchronized(CraftLocationRecordingStore) {
+        try { CraftLocationRecordingStore.recover(this) }
+        catch (error: Exception) {
+            android.util.Log.e("CraftLocation", "Unable to restore recording", error)
+            stopUpdates()
+            stopSelfResult(startId)
+            return START_NOT_STICKY
+        }
+        val expected = intent?.getStringExtra("recordingId")
+        val current = CraftLocationRecordingStore.recordingId(this)
+        if (expected != null && expected != current) {
+            // ACK can clear A before its queued service intent arrives. Only
+            // tear down an unowned service; a newer B must keep its callback.
+            if (current == null && !CraftLocationRecordingStore.isActive(this)) {
+                stopUpdates()
+                stopSelfResult(startId)
+                return START_NOT_STICKY
+            }
+            return START_STICKY
+        }
+        serviceStartId = startId
         when (intent?.action) {
             ACTION_STOP -> {
                 stopUpdates()
-                stopSelf()
+                stopSelfResult(startId)
                 return START_NOT_STICKY
             }
             else -> if (!startUpdates()) {
-                stopSelf()
+                stopSelfResult(startId)
                 return START_NOT_STICKY
             }
         }
-        return START_STICKY
+        START_STICKY
+        }
     }
 
     private fun startUpdates(): Boolean {
-        if (callback != null) return true
+        val id = CraftLocationRecordingStore.recordingId(this) ?: return false
+        if (callback != null && callbackRecordingId == id) return true
+        stopUpdates()
         if (!CraftLocationRecordingStore.isActive(this)) return false
         val hasForegroundLocation =
             ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED ||
                 ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_COARSE_LOCATION) == PackageManager.PERMISSION_GRANTED
         if (!hasForegroundLocation) {
-            CraftLocationRecordingStore.stop(this)
+            runCatching { CraftLocationRecordingStore.finish(this, JSONObject().put("expectedId", id)) }
             return false
         }
         val request = LocationRequest.Builder(Priority.PRIORITY_HIGH_ACCURACY, 5_000)
@@ -150,23 +351,27 @@ class LocationRecordingService : Service() {
             .build()
         val nextCallback = object : LocationCallback() {
             override fun onLocationResult(result: LocationResult) {
-                for (location in result.locations) CraftLocationRecordingStore.append(this@LocationRecordingService, location)
+                for (location in result.locations) CraftLocationRecordingStore.append(this@LocationRecordingService, location, id)
             }
         }
         callback = nextCallback
+        callbackRecordingId = id
         return try {
             client.requestLocationUpdates(request, nextCallback, Looper.getMainLooper())
                 .addOnFailureListener {
-                    if (callback === nextCallback) {
-                        CraftLocationRecordingStore.stop(this)
-                        stopUpdates()
-                        stopSelf()
+                    synchronized(CraftLocationRecordingStore) {
+                        if (callback === nextCallback && CraftLocationRecordingStore.recordingId(this) == id) {
+                            runCatching { CraftLocationRecordingStore.finish(this, JSONObject().put("expectedId", id)) }
+                                .onFailure { android.util.Log.e("CraftLocation", "Unable to persist failed recording", it) }
+                            stopUpdates()
+                            stopSelfResult(serviceStartId)
+                        }
                     }
                 }
             true
         } catch (error: Exception) {
             callback = null
-            CraftLocationRecordingStore.stop(this)
+            runCatching { CraftLocationRecordingStore.finish(this, JSONObject().put("expectedId", id)) }
             false
         }
     }
@@ -174,6 +379,7 @@ class LocationRecordingService : Service() {
     private fun stopUpdates() {
         callback?.let { client.removeLocationUpdates(it) }
         callback = null
+        callbackRecordingId = null
     }
 
     override fun onDestroy() {

package/dist/android-adb.d.ts

@@ -0,0 +1,2 @@
+/** Restart adbd once and require a rooted, explicitly selected disposable emulator. */
+export declare function requireAndroidEmulatorRoot(adb: string, serial: string, timeoutMs?: number): Promise<void>;

package/dist/api/index.d.ts

@@ -17,7 +17,7 @@ export type { HttpClientOptions, RequestOptions, HttpResponse, WebSocketOptions
 export { crypto, uuid, randomString, hmac, timingSafeEqual, hashPassword, verifyPassword } from './crypto.js';
 export { env, getPlatform, isDesktop, isMobile, isCraft, getSystemInfo, exec, spawn, ChildProcess, cwd, homeDir, tempDir, exit, argv, open } from './process.js';
 export type { Platform, SystemInfo, ExecOptions, ExecResult, SpawnOptions } from './process.js';
-export { device, haptics, permissions, camera, biometrics, secureStorage, location, share, lifecycle, notifications, notifications as notification } from './mobile.js';
+export { device, haptics, permissions, camera, biometrics, secureStorage, storage, location, share, lifecycle, notifications, notifications as notification } from './mobile.js';
 export type { DeviceInfo, DeviceCapabilities, HapticStyle, HapticNotificationType, PermissionType, PermissionStatus, CameraOptions as MobileCameraOptions, PhotoResult, BiometricType, Location, LocationOptions, ShareOptions, AppState, NotificationOptions as MobileNotificationOptions } from './mobile.js';
 export { carplay, appClips, liveActivities, sharePlay, storeKit, appIntents, tipKit, focusFilters } from './ios-advanced.js';
 export type { CarPlayTemplateType, CarPlayListItem, CarPlayGridItem, CarPlayTemplate, AppClipInvocation, LiveActivityContentState, LiveActivityAttributes, LiveActivityConfig, LiveActivityHandle, SharePlaySessionState, SharePlayParticipant, SharePlayActivity, ProductType, Product, Transaction, IntentParameterType, IntentParameter, AppIntent, TipDisplayFrequency, Tip, FocusStatus, FocusFilter } from './ios-advanced.js';