craft-native 0.0.497 → 0.0.499

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

@@ -17,6 +17,34 @@ internal fun craftAppLinkPathMatches(pattern: String, path: String): Boolean {
 
 /** Ordered website path rules, also publishable as Android 15 dynamic App Links. */
 internal object CraftAppLinks {
+    /**
+     * A link as a screen or a page hears it.
+     *
+     * A link is whatever its sender wrote. One written without `//`
+     * (`myapp:open?x=1`) is what Android calls opaque: it has no path or
+     * query of its own, and asking for its parameters throws. Both hosts
+     * asked on every link, on the main thread, so the app closed on being
+     * handed one. Its path and query are read from what follows the scheme,
+     * which is how UIKit reads the same link. A parameter named twice gives
+     * its first value.
+     */
+    fun describe(uri: Uri): JSONObject {
+        val rest = if (uri.isOpaque) uri.encodedSchemeSpecificPart.orEmpty() else null
+        val asked = if (rest == null) uri else Uri.parse("craft://link/?" + rest.substringAfter('?', ""))
+        // A link with nothing after its `?`, or no `?`, has no parameters;
+        // asked anyway, Android answers one with an empty name.
+        val named = if (asked.encodedQuery.isNullOrEmpty()) emptySet() else asked.queryParameterNames
+        return JSONObject()
+            .put("url", uri.toString())
+            .put("scheme", uri.scheme ?: "")
+            .put("host", uri.host ?: "")
+            .put("path", if (rest == null) uri.path ?: "" else Uri.decode(rest.substringBefore('?')))
+            .put("query", asked.query ?: "")
+            .put("queryParams", JSONObject().apply {
+                named.forEach { name -> put(name, asked.getQueryParameter(name) ?: "") }
+            })
+    }
+
     fun opensInBrowser(config: JSONObject?, uri: Uri): Boolean {
         if (uri.scheme != "https") return false
         val hosts = config?.optJSONArray("appLinks") ?: return false

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

@@ -5351,20 +5351,8 @@ class CraftBridge(
 
         activity.runOnUiThread {
             if (initialURL != null) {
-                val uri = Uri.parse(initialURL)
-                val json = JSONObject().apply {
-                    put("url", initialURL)
-                    put("scheme", uri.scheme ?: "")
-                    put("host", uri.host ?: "")
-                    put("path", uri.path ?: "")
-                    put("query", uri.query ?: "")
-                    // Parse query parameters
-                    val queryParams = JSONObject()
-                    uri.queryParameterNames.forEach { name ->
-                        queryParams.put(name, uri.getQueryParameter(name) ?: "")
-                    }
-                    put("queryParams", queryParams)
-                }
+                // Described where every link is: a link without `//` threw here.
+                val json = CraftAppLinks.describe(Uri.parse(initialURL)).put("url", initialURL)
                 evaluatePromiseJavascript(
                     "window._craftDeepLinkResolve && window._craftDeepLinkResolve($json)"
                 )
@@ -5415,21 +5403,7 @@ class CraftBridge(
     private fun dispatchDeepLink(url: String, initial: Boolean) {
         if (nativeDeepLinks && CraftNative.dispatchDeepLink(url, initial)) return
 
-        val uri = Uri.parse(url)
-        val json = JSONObject().apply {
-            put("url", url)
-            put("scheme", uri.scheme ?: "")
-            put("host", uri.host ?: "")
-            put("path", uri.path ?: "")
-            put("query", uri.query ?: "")
-            // Parse query parameters
-            val queryParams = JSONObject()
-            uri.queryParameterNames.forEach { name ->
-                queryParams.put(name, uri.getQueryParameter(name) ?: "")
-            }
-            put("queryParams", queryParams)
-            put("initial", initial)
-        }
+        val json = CraftAppLinks.describe(Uri.parse(url)).put("url", url).put("initial", initial)
 
         evaluateJavascriptUnlessClosed(
             "window.dispatchEvent(new CustomEvent('craftDeepLink', {detail: $json}));"

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

@@ -251,6 +251,23 @@ internal class CraftNativeHeadlessApp(
     private val timers = mutableMapOf<Int, Runnable>()
     private val chunks = CraftNativeChunks()
 
+    /**
+     * The clock's reading at this script's first frame, as a screen keeps
+     * (`Screen.frameTimeOrigin` in the activity).
+     *
+     * `requestAnimationFrame` hands its callback milliseconds from the
+     * script's own origin. This host handed it milliseconds from boot, so
+     * code shared with a screen read a first frame near zero there and one
+     * in the billions here, on the same device.
+     */
+    private var frameTimeOrigin: Long? = null
+
+    /** Milliseconds from this script's first frame, for a reading of the monotonic clock in nanoseconds. */
+    private fun frameTime(now: Long): Double {
+        val origin = frameTimeOrigin ?: now.also { frameTimeOrigin = it }
+        return (now - origin) / 1_000_000.0
+    }
+
     init {
         capabilities.storeObserver = { store, key, value -> stores.changed(store, key, value, scope) }
         services.onBackgroundComplete = { ok, answered -> if (answered == null || answered == id) finish(ok) }
@@ -273,7 +290,8 @@ internal class CraftNativeHeadlessApp(
                 if (entry.message.startsWith(prefix)) chunks.accept(entry.message.removePrefix(prefix))?.let(::receive)
                 else Log.i(TAG, "[background] ${entry.message}")
             })
-            CraftNativeHub.register(scope) { type, payload -> send(type, payload) }
+            // Not able to hear yet: its prelude is built and run below.
+            CraftNativeHub.registerWaiting(scope) { type, payload -> send(type, payload) }
             val names = capabilities.names().apply { services.names().forEach { put(it) } }
             val bridgeFields = """
                 platform: 'android',
@@ -300,6 +318,7 @@ internal class CraftNativeHeadlessApp(
                 if (closed) return@addListener
                 try {
                     setup.get()
+                    CraftNativeHub.ready(scope)
                     val load = created.evaluateJavaScriptAsync(bundle)
                     load.addListener({
                         try {
@@ -349,7 +368,7 @@ internal class CraftNativeHeadlessApp(
             }
             "TIMER_CLEAR" -> timers.remove(payload.optInt("id"))?.let(main::removeCallbacks)
             // Nothing is drawn in the background: frames come at a calm pace.
-            "FRAME" -> main.postDelayed({ send("FRAME_FIRE", JSONObject().put("time", android.os.SystemClock.uptimeMillis().toDouble())) }, 100)
+            "FRAME" -> main.postDelayed({ send("FRAME_FIRE", JSONObject().put("time", frameTime(System.nanoTime()))) }, 100)
             // A background refresh shows nothing: navigation waits for the app.
         }
     }

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

@@ -276,7 +276,10 @@ internal class CraftNativeCapabilities(
                     complete(requestToken, failure("CAPABILITY_DISABLED", "Local database is disabled"), completion)
                 }
                 else databaseExecutor.execute {
-                    complete(requestToken, database(method, args), completion)
+                    // Asked before the host closed and reached after: it
+                    // must not reopen what closing is about to give back.
+                    if (closed.get()) return@execute
+                    complete(requestToken, database(requestToken, method, args), completion)
                 }
             }
             "Lifecycle" -> complete(requestToken, if (method == "getState") success(activity?.nativeAppState ?: "background")
@@ -324,17 +327,42 @@ internal class CraftNativeCapabilities(
         runCatching { connectivity.unregisterNetworkCallback(networkWatch) }
         cancelled.clear()
         if (config.optBoolean("enableBluetooth")) bluetooth.disconnect()
-        databaseExecutor.shutdownNow()
+        closeDatabase()
         networkExecutor.shutdownNow()
         fetchConnections.values.forEach(HttpURLConnection::disconnect)
         fetchConnections.clear()
         onMain { dismissFilePick(); pendingPedometerPermission = null; pedometerPermissionInFlight = false }
-        database?.close()
-        database = null
         biometricPrompts.values.forEach { it.cancelAuthentication() }
         biometricPrompts.clear()
     }
 
+    /**
+     * The database is closed on its own thread, and a transaction this host
+     * left open is rolled back there first.
+     *
+     * A transaction belongs to the thread that began it. Closing from the
+     * caller's thread could not end it, so its connection stayed open where
+     * nothing could reach it again, holding the write lock on the file. Each
+     * host has its own connection to that one file: the next activity, or
+     * the script started for a background refresh, answered every call with
+     * "database is locked" until the lost connection happened to be
+     * collected. Calls still queued behind this one are answering a closed
+     * host and do nothing.
+     */
+    private fun closeDatabase() {
+        runCatching {
+            databaseExecutor.execute {
+                val db = database ?: return@execute
+                database = null
+                transactionScope = null
+                runCatching { if (db.inTransaction()) db.endTransaction() }
+                    .onFailure { android.util.Log.w("CraftNativeAndroid", "A closed host's transaction could not be rolled back", it) }
+                runCatching { db.close() }
+            }
+        }
+        databaseExecutor.shutdown()
+    }
+
     fun pedometerPermissionGranted(): Boolean = checkPedometerPermission?.invoke() ?: (Build.VERSION.SDK_INT < 29 ||
         ContextCompat.checkSelfPermission(context, Manifest.permission.ACTIVITY_RECOGNITION) == PackageManager.PERMISSION_GRANTED)
 
@@ -535,18 +563,7 @@ internal class CraftNativeCapabilities(
 
     private fun files(requestToken: String, method: String, args: JSONArray): CraftNativeCapabilityResult {
         return when (method) {
-        "write" -> {
-            val name = args.optString(0).trim()
-            if (name.isBlank()) return failure("INVALID_ARGUMENT", "files.write needs a file name")
-            val data = args.optString(1, "")
-            val options = args.optJSONObject(2) ?: JSONObject()
-            val bytes = when (options.optString("encoding", "utf8")) {
-                "utf8" -> data.toByteArray(Charsets.UTF_8)
-                "base64" -> decodeBase64(data) ?: return failure("INVALID_ARGUMENT", "files.write base64 is invalid")
-                else -> return failure("INVALID_ARGUMENT", "files.write encoding is 'utf8' or 'base64'")
-            }
-            store(bytes, name, options.optString("type").ifBlank { URLConnection.guessContentTypeFromName(name) ?: "application/octet-stream" })
-        }
+        "write" -> write(args)
         "remove" -> {
             val file = ownedFile(args.optString(0)) ?: return failure("INVALID_ARGUMENT", "files.remove needs a file made by craft.files")
             success(removeOwnedFile(file))
@@ -556,6 +573,30 @@ internal class CraftNativeCapabilities(
         }
     }
 
+    /**
+     * What a screen made itself, written as a file: text, or bytes as base64.
+     *
+     * The name and the contents are strings, and nothing else is read as
+     * one. `optString` reads anything: a number became its digits, `null`
+     * the four letters "null", and bytes handed over as they were (a
+     * `Uint8Array` crosses the bridge as `{"0":1,"1":2}`) became that JSON
+     * text, written to a file and answered as a success. UIKit refuses each
+     * of those, and so does this. An absent or `null` encoding is `utf8`.
+     */
+    private fun write(args: JSONArray): CraftNativeCapabilityResult {
+        val name = (args.opt(0) as? String)?.trim().orEmpty()
+        if (name.isBlank()) return failure("INVALID_ARGUMENT", "files.write needs a file name")
+        val data = args.opt(1) as? String ?: return failure("INVALID_ARGUMENT", "files.write needs its contents as a string")
+        val options = args.optJSONObject(2) ?: JSONObject()
+        val encoding = if (options.isNull("encoding")) "utf8" else options.opt("encoding") as? String
+        val bytes = when (encoding) {
+            "utf8" -> data.toByteArray(Charsets.UTF_8)
+            "base64" -> decodeBase64(data) ?: return failure("INVALID_ARGUMENT", "files.write base64 is invalid")
+            else -> return failure("INVALID_ARGUMENT", "files.write encoding is 'utf8' or 'base64'")
+        }
+        return store(bytes, name, options.optString("type").ifBlank { URLConnection.guessContentTypeFromName(name) ?: "application/octet-stream" })
+    }
+
     /**
      * Base64 as `atob` reads it, which is what the browser host runs and what
      * UIKit is held to: the alphabet, ASCII white space anywhere, padding
@@ -1172,7 +1213,12 @@ internal class CraftNativeCapabilities(
             "compareAndSet" -> {
                 if (args.length() != 3) return failure("INVALID_ARGUMENT", "Storage.compareAndSet needs a key, expected value and next value")
                 val current = storage.getString(key, null) ?: return success(false)
-                if (!CraftNativeStorage.jsonEqual(JSONTokener(current).nextValue(), args.opt(1))) return success(false)
+                // What `get` answers for a value it cannot read. Unparsed, it
+                // threw from here and reached the screen as STORAGE_ERROR,
+                // the code for a disk that failed.
+                val held = runCatching { JSONTokener(current).nextValue() }
+                    .getOrElse { return failure("STORAGE_CORRUPT", "Stored value is not valid JSON") }
+                if (!CraftNativeStorage.jsonEqual(held, args.opt(1))) return success(false)
                 val next = jsonString(args.opt(2)) ?: return failure("INVALID_ARGUMENT", "Storage values must be JSON serializable")
                 if (!CraftNativeStorage.commit(storage) { it.putString(key, next) }) return failure("STORAGE_ERROR", "Storage could not persist the checkpoint")
                 storeObserver?.invoke("storage", key, next)
@@ -1292,7 +1338,50 @@ internal class CraftNativeCapabilities(
         }
     }
 
-    private fun database(method: String, args: JSONArray): CraftNativeCapabilityResult {
+    /**
+     * A screen has closed. A transaction it began and never finished is
+     * rolled back.
+     *
+     * The database is one connection shared by every screen, and a
+     * transaction left open on it does not end with the screen that began
+     * it: every later write joins it, reads back as written, and is gone
+     * when the process exits, since nobody is left to commit. Rolling back
+     * loses what the closed screen had not committed, which is what closing
+     * mid-transaction means, and gives every later write its own fate back.
+     * Queued behind whatever that screen had already asked for.
+     */
+    fun endScope(scope: String) {
+        if (closed.get()) return
+        runCatching {
+            databaseExecutor.execute {
+                if (transactionScope != scope) return@execute
+                transactionScope = null
+                val db = database ?: return@execute
+                runCatching { if (db.inTransaction()) db.endTransaction() }
+                    .onFailure { android.util.Log.w("CraftNativeAndroid", "A closed screen's transaction could not be rolled back", it) }
+            }
+        }
+    }
+
+    /**
+     * Which screen's transaction is open, read off the database around each
+     * call rather than off the method's name: a call that leaves a
+     * transaction open where there was none began it, and one that leaves
+     * none ended it. The scope is the part of a request token before its
+     * last `/`. Only touched on the database thread.
+     */
+    private var transactionScope: String? = null
+
+    private fun database(requestToken: String, method: String, args: JSONArray): CraftNativeCapabilityResult {
+        val before = runCatching { database?.inTransaction() == true }.getOrDefault(false)
+        val answer = databaseCall(method, args)
+        val after = runCatching { database?.inTransaction() == true }.getOrDefault(false)
+        if (after && !before) transactionScope = requestToken.substringBeforeLast('/', "")
+        else if (!after) transactionScope = null
+        return answer
+    }
+
+    private fun databaseCall(method: String, args: JSONArray): CraftNativeCapabilityResult {
         val db = database ?: runCatching {
             context.openOrCreateDatabase("craft-native.sqlite", Context.MODE_PRIVATE, null)
         }.getOrElse { return failure("DATABASE_ERROR", it.message ?: "Could not open the local database") }
@@ -1309,7 +1398,12 @@ internal class CraftNativeCapabilities(
                     if (sql.isEmpty()) return failure("INVALID_ARGUMENT", "Database.query needs a SQL statement")
                     query(db, sql, args.optJSONArray(1) ?: JSONArray())
                 }
-                "beginTransaction" -> { db.beginTransaction(); success(true) }
+                // SQLite refuses a transaction inside a transaction, and that
+                // is UIKit's answer. Android would nest it instead: the inner
+                // `commit` then makes nothing durable and reports that it did,
+                // and the outer one is some other caller's to finish.
+                "beginTransaction" -> if (db.inTransaction()) failure("DATABASE_ERROR", "cannot start a transaction within a transaction")
+                    else { db.beginTransaction(); success(true) }
                 "commit" -> {
                     if (!db.inTransaction()) failure("DATABASE_ERROR", "No transaction is active")
                     else { db.setTransactionSuccessful(); db.endTransaction(); success(true) }
@@ -1435,13 +1529,10 @@ internal class CraftNativeCapabilities(
             "cancel" -> {
                 val id = validKey(args.opt(0))
                 complete(requestToken, if (id == null) failure("INVALID_ARGUMENT", "Notifications.cancel needs an id")
-                    else { cancelNotification(id); success(true) }, completion)
-            }
-            "cancelAll" -> {
-                notificationStorage.all.keys.forEach(::cancelNotification)
-                CraftNativeNotifications.cancelAll(context)
-                complete(requestToken, success(true), completion)
+                    else if (cancelNotification(id)) success(true)
+                    else failure("NOTIFICATION_ERROR", "The notification could not be cancelled"), completion)
             }
+            "cancelAll" -> complete(requestToken, cancelEveryNotification(), completion)
             "pending" -> complete(requestToken, success(JSONArray(notificationStorage.all.values.mapNotNull {
                 runCatching { JSONObject(it as String) }.getOrNull()
             })), completion)
@@ -1467,7 +1558,13 @@ internal class CraftNativeCapabilities(
         val id = validKey(value?.opt("id")) ?: UUID.randomUUID().toString()
         val fireAt = System.currentTimeMillis() + value!!.optLong("delay", 0).coerceAtLeast(0)
         val stored = JSONObject(value.toString()).put("id", id).put("fireAt", fireAt)
-        notificationStorage.edit().putString(id, stored.toString()).commit()
+        // What is stored under the id is what the receiver shows when the
+        // alarm fires, usually in a process started for it. Scheduled without
+        // being saved, the alarm fired, found nothing and showed nothing,
+        // after this had answered with the id.
+        if (!CraftNativeStorage.commit(notificationStorage) { it.putString(id, stored.toString()) }) {
+            return failure("NOTIFICATION_ERROR", "The notification could not be saved")
+        }
         scheduleStored(stored)
         return success(id)
     }
@@ -1489,14 +1586,34 @@ internal class CraftNativeCapabilities(
         )
     }
 
-    private fun cancelNotification(id: String) {
+    /**
+     * Cancels a scheduled notification. False when its removal did not reach
+     * the disk, and then nothing is cancelled.
+     *
+     * Every start schedules whatever is stored (`restoreNotifications`). The
+     * alarm used to be cancelled first and the failed removal ignored, so a
+     * reminder looked cancelled for the life of the process and was
+     * scheduled again by the next one. It is removed from storage first, and
+     * one that cannot be removed stays as it was, alarm included, and the
+     * call says so.
+     */
+    private fun cancelNotification(id: String): Boolean {
+        if (!CraftNativeStorage.commit(notificationStorage) { it.remove(id) }) return false
         CraftNativeNotifications.cancel(context, id)
         val alarm = context.getSystemService(Context.ALARM_SERVICE) as AlarmManager
         val intent = notificationIntent(id)
         alarm.cancel(intent)
         intent.cancel()
-        notificationStorage.edit().remove(id).commit()
         (context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager).cancel(id, 0)
+        return true
+    }
+
+    /** `cancelAll`: every scheduled notification, and an error naming how many could not be. */
+    private fun cancelEveryNotification(): CraftNativeCapabilityResult {
+        val left = notificationStorage.all.keys.toList().filterNot(::cancelNotification)
+        CraftNativeNotifications.cancelAll(context)
+        return if (left.isEmpty()) success(true)
+            else failure("NOTIFICATION_ERROR", "${left.size} scheduled notifications could not be cancelled")
     }
 
     private fun notificationIntent(id: String): PendingIntent = PendingIntent.getBroadcast(

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

@@ -58,12 +58,56 @@ internal object CraftNativeHub {
     private val receivers = ConcurrentHashMap<String, (String, JSONObject) -> Unit>()
     private val main = Handler(Looper.getMainLooper())
 
+    /** What was broadcast to an isolate that could not hear yet, in order. Guarded by itself. */
+    private val waiting = HashMap<String, ArrayList<Pair<String, JSONObject>>>()
+
     fun register(id: String, receiver: (String, JSONObject) -> Unit) {
         receivers[id] = receiver
     }
 
+    /**
+     * Registers an isolate whose prelude has not run yet.
+     *
+     * Such an isolate is registered before it is given its copy of the
+     * stores, and the copy is taken some time later, off the main thread. A
+     * change broadcast in between has nowhere to land: the prelude defines
+     * what receives it, so a message sent before the prelude runs is
+     * discarded, and the isolate goes on to start from a copy that may
+     * predate the change (#507). What is broadcast meanwhile is kept instead
+     * and handed over, in order, by [ready]. Changes are broadcast in the
+     * order they are made, so replaying them over a copy taken part-way
+     * through ends on the latest value.
+     */
+    fun registerWaiting(id: String, receiver: (String, JSONObject) -> Unit) {
+        synchronized(waiting) { waiting[id] = ArrayList() }
+        receivers[id] = { type, payload ->
+            val kept = synchronized(waiting) { waiting[id]?.also { it.add(type to payload) } }
+            if (kept == null) receiver(type, payload)
+        }
+    }
+
+    /**
+     * The isolate's prelude has run: it is given what was kept for it, then
+     * hears each broadcast as it is made. On the main thread, where
+     * broadcasts are delivered, so nothing can arrive between the two.
+     */
+    fun ready(id: String) {
+        val deliver = {
+            val kept = synchronized(waiting) { waiting.remove(id) }
+            val receiver = receivers[id]
+            if (kept != null && receiver != null) {
+                for ((type, payload) in kept) {
+                    runCatching { receiver(type, payload) }
+                        .onFailure { Log.w("CraftNativeAndroid", "Kept $type to $id failed", it) }
+                }
+            }
+        }
+        if (Looper.myLooper() == Looper.getMainLooper()) deliver() else main.post(deliver)
+    }
+
     fun unregister(id: String) {
         receivers.remove(id)
+        synchronized(waiting) { waiting.remove(id) }
     }
 
     /** Sends to every registered isolate but `except`, on the main thread. */
@@ -1015,6 +1059,8 @@ internal class CraftNativeChrome(
         val path = item.optString("path")
         return visiblePath == path || visiblePath?.startsWith(path + "/") == true
     }
+    /** Drawn in the accent: its destination is showing, or the app says it is on. */
+    private fun isAccessoryActive(item: JSONObject): Boolean = item.optBoolean("selected") || isAccessorySelected(item)
     private var swipeTracking = false
     private var swipeIntercepted = false
     private var horizontalScrollDeferred = false
@@ -1414,10 +1460,10 @@ internal class CraftNativeChrome(
         val grouped = accessoryGroup.parent === body
         accessoryGroup.background = if (grouped) GradientDrawable().apply { setColor(surface); cornerRadius = dp(26).toFloat() } else null
         tabBar.background = GradientDrawable().apply { setColor(surface); cornerRadius = dp(32).toFloat() }
-        val primarySelected = accessorySpec?.let { isAccessorySelected(it) } == true
+        val primarySelected = accessorySpec?.let { isAccessoryActive(it) } == true
         accessory.isSelected = primarySelected
         companionViews.forEach { (action, item) ->
-            val selected = isAccessorySelected(item)
+            val selected = isAccessoryActive(item)
             action.isSelected = selected
             action.background = if (grouped) rippleBackground() else GradientDrawable().apply { setColor(if (selected) Color.argb(36, Color.red(accent), Color.green(accent), Color.blue(accent)) else surface); cornerRadius = dp(32).toFloat() }
             (action.getChildAt(0) as ImageView).setImageDrawable(CraftNativeIcons.drawable(context, null, item.optString("symbol"), if (selected) accent else text))

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

@@ -187,17 +187,36 @@ internal class CraftNativeSounds(
         return true
     }
 
+    /**
+     * The fade a `stop` asked for, in milliseconds: a JSON number that is
+     * finite and above zero, and otherwise none.
+     *
+     * `optDouble` also read "500" as a number, where UIKit reads only a
+     * number as one.
+     */
+    fun fadeOut(options: JSONObject?): Double {
+        val asked = (options?.opt("fadeOut") as? Number)?.toDouble() ?: return 0.0
+        return if (asked.isFinite() && asked > 0) asked else 0.0
+    }
+
+    /**
+     * Stops the sound, fading it out over `fadeOut` milliseconds first.
+     *
+     * Stopping is what was asked, and the fade is how. A `fadeOut` that is
+     * not a duration, a negative one say, used to be refused: the call
+     * answered `false`, which is the answer for a sound that does not exist,
+     * and the sound went on playing. UIKit and the browser host stop it at
+     * once, and so does this.
+     */
     fun stop(id: String, fadeOut: Double): Boolean {
         val sound = sounds[id] ?: return false
-        if (!fadeOut.isFinite() || fadeOut < 0) return false
-        if (fadeOut > 0 && !sound.paused) {
+        if (fadeOut.isFinite() && fadeOut > 0 && !sound.paused) {
             ramp(sound, 0f, fadeOut / 1000.0) { if (sounds[id] === sound) remove(id) }
         } else remove(id)
         return true
     }
 
     fun stopAll(fadeOut: Double): Boolean {
-        if (!fadeOut.isFinite() || fadeOut < 0) return false
         sounds.keys.toList().forEach { stop(it, fadeOut) }
         return true
     }

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

@@ -5635,7 +5635,8 @@ class MainActivity : AppCompatActivity() {
             if (activeScreen.active) send(activeScreen, "SOUND_EVENT", payload)
         }
         screen = activeScreen
-        CraftNativeHub.register(activeScreen.capabilityScope) { type, payload ->
+        // Not able to hear yet: its prelude is built and run below.
+        CraftNativeHub.registerWaiting(activeScreen.capabilityScope) { type, payload ->
             if (activeScreen.active) send(activeScreen, type, payload)
         }
         if (!headless) {
@@ -5845,6 +5846,9 @@ class MainActivity : AppCompatActivity() {
             if (!activeScreen.active) return@addListener
             try {
                 setup.get()
+                // The prelude has run, so the isolate can hear: what changed
+                // while it was being built, before the bundle reads any of it.
+                CraftNativeHub.ready(activeScreen.capabilityScope)
                 val source = CraftNativeBundle.source(this, route)
                 if (source == null) {
                     if (activeScreen.active) showError("Missing native-screen.js. Build with --native-bundle after compiling STX.")
@@ -5891,6 +5895,8 @@ class MainActivity : AppCompatActivity() {
                     }
                 }, executor)
             } catch (error: Exception) {
+                // Nothing will run in this isolate, so nothing is kept for it.
+                CraftNativeHub.ready(activeScreen.capabilityScope)
                 Log.e(TAG, "Native STX bridge failed", error)
                 showError("Native STX bridge failed: ${error.message}")
             }
@@ -8723,9 +8729,13 @@ class MainActivity : AppCompatActivity() {
             }
             "pause" -> completion(CraftNativeCapabilityResult(data = screen.sounds.pause(id)))
             "resume" -> completion(CraftNativeCapabilityResult(data = screen.sounds.resume(id)))
-            "setVolume" -> completion(CraftNativeCapabilityResult(data = screen.sounds.setVolume(id, args.optDouble(1, Double.NaN), args.optJSONObject(2)?.optDouble("fade", 0.0) ?: 0.0)))
-            "stop" -> completion(CraftNativeCapabilityResult(data = screen.sounds.stop(id, args.optJSONObject(1)?.optDouble("fadeOut", 0.0) ?: 0.0)))
-            "stopAll" -> completion(CraftNativeCapabilityResult(data = screen.sounds.stopAll(args.optJSONObject(0)?.optDouble("fadeOut", 0.0) ?: 0.0)))
+            // A number is a JSON number: `optDouble` also read "0.5" as one,
+            // where UIKit answers false for a volume given as text.
+            "setVolume" -> completion(CraftNativeCapabilityResult(data = screen.sounds.setVolume(id,
+                (args.opt(1) as? Number)?.toDouble() ?: Double.NaN,
+                (args.optJSONObject(2)?.opt("fade") as? Number)?.toDouble() ?: 0.0)))
+            "stop" -> completion(CraftNativeCapabilityResult(data = screen.sounds.stop(id, screen.sounds.fadeOut(args.optJSONObject(1)))))
+            "stopAll" -> completion(CraftNativeCapabilityResult(data = screen.sounds.stopAll(screen.sounds.fadeOut(args.optJSONObject(0)))))
             else -> completion(CraftNativeCapabilityResult(code = "UNKNOWN_ACTION", message = "Unsupported Audio method"))
         }
     }
@@ -8865,15 +8875,8 @@ class MainActivity : AppCompatActivity() {
             else -> CraftNativeCapabilityResult(code = "UNKNOWN_ACTION", message = "Unsupported native API")
         }
 
-    internal fun deepLinkData(uri: android.net.Uri): JSONObject = JSONObject()
-        .put("url", uri.toString())
-        .put("scheme", uri.scheme ?: "")
-        .put("host", uri.host ?: "")
-        .put("path", uri.path ?: "")
-        .put("query", uri.query ?: "")
-        .put("queryParams", JSONObject().apply {
-            uri.queryParameterNames.forEach { name -> put(name, uri.getQueryParameter(name) ?: "") }
-        })
+    /** A link as the screens hear it: `CraftAppLinks.describe`, which the page bridge uses too. */
+    internal fun deepLinkData(uri: android.net.Uri): JSONObject = CraftAppLinks.describe(uri)
 
     /** App-wide news (the app's state, a link): every screen and the app script hear it. */
     private fun publish(type: String, payload: JSONObject) {
@@ -9423,6 +9426,7 @@ class MainActivity : AppCompatActivity() {
         screen.capabilityTimeouts.clear()
         screen.pendingCapabilities.forEach(capabilities::cancel)
         screen.pendingCapabilities.clear()
+        capabilities.endScope(screen.capabilityScope)
         releaseViewState(screen, retainedViews(screen).toList())
         screen.inputWatchers.forEach { (input, watcher) -> input.removeTextChangedListener(watcher) }
         screen.inputWatchers.clear()
@@ -9463,6 +9467,8 @@ class MainActivity : AppCompatActivity() {
             screen.capabilityTimeouts.clear()
             screen.pendingCapabilities.forEach(capabilities::cancel)
             screen.pendingCapabilities.clear()
+            // Again: a transaction can be begun while the isolate is closing.
+            capabilities.endScope(screen.capabilityScope)
             done()
         }
     }

package/dist/browser.js

@@ -909,8 +909,24 @@ async function createBrowserPlatform(options = {}) {
         }
         if (method === "write") {
           const settings = object(args[2]);
-          const contents = settings.encoding === "base64" ? Uint8Array.from(atob(String(args[1])), (letter) => letter.charCodeAt(0)) : String(args[1]);
-          return file([contents], String(args[0]), String(settings.type ?? "application/octet-stream"));
+          const [name, data] = args;
+          const refuse = (message) => Object.assign(new Error(message), { code: "INVALID_ARGUMENT" });
+          if (typeof name !== "string" || !name.trim())
+            throw refuse("files.write needs a file name");
+          if (typeof data !== "string")
+            throw refuse("files.write needs its contents as a string");
+          const encoding = settings.encoding ?? "utf8";
+          if (encoding !== "utf8" && encoding !== "base64")
+            throw refuse("files.write encoding is 'utf8' or 'base64'");
+          let contents = data;
+          if (encoding === "base64") {
+            try {
+              contents = Uint8Array.from(atob(data), (letter) => letter.charCodeAt(0));
+            } catch {
+              throw refuse("files.write base64 is invalid");
+            }
+          }
+          return file([contents], name, String(settings.type ?? "application/octet-stream"));
         }
         if (method === "remove") {
           const path = String(args[0]);
@@ -1071,14 +1087,15 @@ async function createBrowserPlatform(options = {}) {
             throw error;
           }
         }
+        const fadeOut = (options) => typeof options.fadeOut === "number" ? options.fadeOut : 0;
         if (method === "stopAll") {
           soundRequests.clear();
-          await Promise.all([...sounds.keys()].map((key) => stopSound(key, Number(first.fadeOut ?? 0))));
+          await Promise.all([...sounds.keys()].map((key) => stopSound(key, fadeOut(first))));
           return true;
         }
         if (method === "stop") {
           soundRequests.delete(id);
-          await stopSound(id, Number(object(args[1]).fadeOut ?? 0));
+          await stopSound(id, fadeOut(object(args[1])));
           return Boolean(sound);
         }
         if (!sound)
@@ -1092,7 +1109,12 @@ async function createBrowserPlatform(options = {}) {
           return true;
         }
         if (method === "setVolume") {
-          await fade(sound, Number(args[1]), Number(object(args[2]).fade ?? 0));
+          const volume = args[1];
+          const asked = object(args[2]).fade;
+          const milliseconds = typeof asked === "number" ? asked : 0;
+          if (typeof volume !== "number" || !Number.isFinite(volume) || !Number.isFinite(milliseconds) || milliseconds < 0)
+            return false;
+          await fade(sound, volume, milliseconds);
           return true;
         }
       }

package/dist/cli.js

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

package/dist/index.cjs

@@ -376,7 +376,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.497";
+var version = "0.0.499";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;

package/dist/index.js

@@ -117,7 +117,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.497";
+var version = "0.0.499";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;

package/dist/ios/templates/CraftApp.swift

@@ -822,6 +822,9 @@ final class CraftChrome: ObservableObject {
         /// A shared material capsule; nil keeps separate floating buttons.
         var accessoryLayout: String? = nil
         var companions: [Tab] = []
+        /// A floating action that is on: a mode it switched (tracking in
+        /// Maps), drawn in the tint whatever screen is showing.
+        var active = false
         /// A tap opens these destinations in a compact menu instead of navigating.
         var menu: [TabMenuItem] = []
     }
@@ -846,6 +849,8 @@ final class CraftChrome: ObservableObject {
         guard let path = visiblePath else { return false }
         return path == accessory.id || path.hasPrefix(accessory.id + "/")
     }
+    /// Drawn in the tint: its destination is showing, or the app says it is on.
+    func accessoryActive(_ accessory: Tab) -> Bool { accessory.active || accessorySelected(accessory) }
     var highlightedTab: String? { accessorySelected ? nil : selected }
     let tabSwipeProgress = CraftTabSwipeProgress()
     private(set) var tabSwipePosition: CGFloat? {
@@ -977,13 +982,15 @@ final class CraftChrome: ObservableObject {
                           let companionTitle = action["title"] as? String else { return nil }
                     return Tab(id: companionPath, title: companionTitle, symbol: action["symbol"] as? String ?? "circle",
                         accessibilityLabel: action["accessibilityLabel"] as? String, iconOnly: true,
+                        active: action["selected"] as? Bool ?? false,
                         menu: ((action["menu"] as? [[String: Any]]) ?? []).prefix(12).compactMap { choice in
                             guard let destination = choice["path"] as? String,
                                   destination.hasPrefix("/"), !destination.hasPrefix("//"),
                                   let label = choice["title"] as? String, !label.isEmpty else { return nil }
                             return TabMenuItem(id: destination, title: label, symbol: choice["symbol"] as? String ?? "circle")
                         })
-                })
+                },
+                active: item["selected"] as? Bool ?? false)
         } else {
             next = nil
         }

package/dist/ios/templates/CraftHybrid.swift

@@ -1483,12 +1483,10 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
                 let button = UIButton(type: .system)
                 var configuration = UIButton.Configuration.plain()
                 configuration.image = UIImage(systemName: action.symbol)
-                configuration.preferredSymbolConfigurationForImage = UIImage.SymbolConfiguration(pointSize: 22, weight: .regular)
                 button.configuration = configuration
                 button.accessibilityIdentifier = "craft-tab-companion:" + action.id
                 button.accessibilityLabel = action.accessibilityLabel ?? action.title
                 button.accessibilityValue = action.badge
-                button.accessibilityTraits = chrome.accessorySelected(action) ? [.button, .selected] : [.button]
                 if action.menu.isEmpty {
                     button.addAction(UIAction { [weak self] _ in self?.hybrid.open(action.id) }, for: .touchUpInside)
                 } else {
@@ -1512,9 +1510,6 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
                 companionButtons.append(button)
             }
         }
-        for (index, action) in companionModels.enumerated() {
-            companionButtons[index].accessibilityTraits = chrome.accessorySelected(action) ? [.button, .selected] : [.button]
-        }
         let grouped = model?.accessoryLayout != nil
         // A group is one control, as the map controls in Maps are: its
         // actions live inside the shared surface, so the glass lights the
@@ -1522,16 +1517,12 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
         // Separate actions stay in the shell, each on its own surface.
         let actionHost: UIView = grouped ? accessoryGlass.contentView : view
         for glass in companionGlasses { glass.isHidden = grouped }
-        for button in companionButtons {
+        for (index, button) in companionButtons.enumerated() {
             if button.superview !== actionHost { actionHost.addSubview(button) }
-            button.tintColor = grouped ? .label : nil
-            button.configuration?.preferredSymbolConfigurationForImage = Self.accessorySymbol(grouped: grouped)
+            styleAccessory(button, for: companionModels[index], grouped: grouped)
         }
-        accessoryButton.tintColor = grouped ? .label : nil
         if let model {
             var configuration = UIButton.Configuration.plain()
-            configuration.image = UIImage(systemName: model.symbol)
-            configuration.preferredSymbolConfigurationForImage = Self.accessorySymbol(grouped: grouped)
             configuration.title = model.iconOnly ? nil : model.displayTitle
             configuration.subtitle = model.iconOnly ? nil : model.badge
             configuration.imagePadding = model.iconOnly ? 0 : 8
@@ -1539,7 +1530,7 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
                 button.configuration = configuration
                 button.accessibilityLabel = model.accessibilityLabel ?? model.displayTitle
                 button.accessibilityValue = model.badge
-                button.accessibilityTraits = chrome.accessorySelected(model) ? [.button, .selected] : [.button]
+                styleAccessory(button, for: model, grouped: grouped)
             }
         }
 #if compiler(>=6.2)
@@ -1597,10 +1588,32 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
         view.setNeedsLayout()
     }
 
-    /// Symbols in a group carry the weight of the system's own map controls;
-    /// a separate action keeps the lighter bar-button weight.
+    /// Symbols in a group carry the weight of the system's own map controls,
+    /// and their size: at 20 points a symbol filled its 48-point action
+    /// where the ones in Maps leave half of theirs clear. The control and
+    /// its touch targets keep their size; only the symbol is smaller. A
+    /// separate action keeps the lighter bar-button weight.
     private static func accessorySymbol(grouped: Bool) -> UIImage.SymbolConfiguration {
-        UIImage.SymbolConfiguration(pointSize: grouped ? 20 : 22, weight: grouped ? .medium : .regular)
+        UIImage.SymbolConfiguration(pointSize: grouped ? 15 : 22, weight: grouped ? .medium : .regular)
+    }
+
+    /// One action's symbol, tint and state. An action that is on (its
+    /// destination is showing, or the app says so) is drawn in the tint and,
+    /// where the symbol has one, filled: Maps' location arrow while tracking.
+    /// Off, a grouped action is the label colour, as the map controls are.
+    private func styleAccessory(_ button: UIButton, for action: CraftChrome.Tab, grouped: Bool) {
+        let active = CraftChrome.shared.accessoryActive(action)
+        let filled = active && !action.symbol.hasSuffix(".fill") ? UIImage(systemName: action.symbol + ".fill") : nil
+        let tint: UIColor = CraftChrome.shared.tint ?? config.tintColor.flatMap { UIColor(hex: $0) } ?? view.tintColor
+        button.configuration?.image = filled ?? UIImage(systemName: action.symbol)
+        button.configuration?.preferredSymbolConfigurationForImage = Self.accessorySymbol(grouped: grouped)
+        // Said to the configuration as well as the view: glass draws its
+        // content in the label colour unless the content names its own.
+        button.configuration?.baseForegroundColor = active ? tint : grouped ? .label : nil
+        // A group places each symbol itself, when it lays out.
+        if !grouped { button.configuration?.contentInsets = .zero }
+        button.tintColor = active ? tint : grouped ? .label : nil
+        button.accessibilityTraits = active ? [.button, .selected] : [.button]
     }
 
     /// The surface under the floating actions. A group is a capsule of
@@ -1639,10 +1652,11 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
         }
     }
 
-    /// A group's breadth, and each action's length along it: the system map
-    /// controls' proportions, every target at least 48 points.
+    /// A group's breadth, and the distance from one symbol to the next. As
+    /// in Maps, the first and last symbols sit at the centres of the
+    /// capsule's round ends, so two actions make a 48 by 103 point control.
     static let accessoryGroupBreadth: CGFloat = 48
-    static let accessoryGroupStep: CGFloat = 52
+    static let accessoryGroupStep: CGFloat = 55
 
     @objc private func openTabAccessory() {
         if let accessoryModel { hybrid.open(accessoryModel.id) }
@@ -1694,7 +1708,7 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
         let breadth = Self.accessoryGroupBreadth
         let step = Self.accessoryGroupStep
         let buttons = companionButtons + [accessoryButton]
-        let length = step * CGFloat(buttons.count)
+        let length = breadth + step * CGFloat(buttons.count - 1)
         let size = vertical ? CGSize(width: breadth, height: length) : CGSize(width: length, height: breadth)
         let rightToLeft = view.effectiveUserInterfaceLayoutDirection == .rightToLeft
         // The tab bar's own platter sits this far in from the screen's edge.
@@ -1702,10 +1716,21 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
         let x = rightToLeft ? view.safeAreaInsets.left + margin : view.bounds.maxX - view.safeAreaInsets.right - size.width - margin
         accessoryGlass.frame = CGRect(x: x, y: tabBar.frame.minY - size.height - 10, width: size.width, height: size.height)
         for (index, button) in buttons.enumerated() {
-            let place = CGFloat(rightToLeft && !vertical ? buttons.count - 1 - index : index) * step
+            // Every point of the capsule belongs to the nearest action; its
+            // symbol stays where Maps puts it, at the centre of a round end
+            // for the first and the last.
+            let place = rightToLeft && !vertical ? buttons.count - 1 - index : index
+            let centre = breadth / 2 + CGFloat(place) * step
+            let from = place == 0 ? 0 : centre - step / 2
+            let to = place == buttons.count - 1 ? length : centre + step / 2
             button.frame = vertical
-                ? CGRect(x: 0, y: place, width: breadth, height: step)
-                : CGRect(x: place, y: 0, width: step, height: breadth)
+                ? CGRect(x: 0, y: from, width: breadth, height: to - from)
+                : CGRect(x: from, y: 0, width: to - from, height: breadth)
+            let shift = 2 * (centre - from) - (to - from)
+            let before = max(0, shift), after = max(0, -shift)
+            button.configuration?.contentInsets = vertical
+                ? NSDirectionalEdgeInsets(top: before, leading: 0, bottom: after, trailing: 0)
+                : NSDirectionalEdgeInsets(top: 0, leading: rightToLeft ? after : before, bottom: 0, trailing: rightToLeft ? before : after)
         }
         let badgeWidth = max(18, accessoryBadge.intrinsicContentSize.width + 8)
         let primary = accessoryButton.convert(accessoryButton.bounds, to: view)

package/dist/ios/templates/CraftNativeActions.swift

@@ -391,7 +391,7 @@ enum CraftNativeActions {
                 complete(requestToken, failure("CAPABILITY_DISABLED", "Local database is disabled"), completion)
                 return
             }
-            databaseQueue.async { complete(requestToken, database(method: method, args: args), completion) }
+            databaseQueue.async { complete(requestToken, database(requestToken: requestToken, method: method, args: args), completion) }
             return
         case ("Browser", "open"):
             // SFSafariViewController, or for `mode: 'auth'` the system's web
@@ -1275,7 +1275,47 @@ enum CraftNativeActions {
         #endif
     }
 
-    private static func database(method: String, args: [Any]) -> Result<Any, CraftNativeActionError> {
+    /// A screen has gone. A transaction it began and never finished is rolled
+    /// back.
+    ///
+    /// The database is one connection shared by every screen, and a
+    /// transaction left open on it does not end with the screen that began
+    /// it: every later write joins it, reads back as written, and is gone
+    /// when the process exits, since nobody is left to commit; every later
+    /// `beginTransaction` is refused. Rolling back loses what the closed
+    /// screen had not committed, which is what closing mid-transaction means,
+    /// and gives every later write its own fate back. Queued behind whatever
+    /// that screen had already asked for.
+    static func endScope(_ scope: String) {
+        databaseQueue.async {
+            guard transactionScope == scope else { return }
+            transactionScope = nil
+            guard let database, sqlite3_get_autocommit(database) == 0 else { return }
+            _ = execute(sql: "ROLLBACK", params: [])
+        }
+    }
+
+    /// Which screen's transaction is open, read off the database around each
+    /// call rather than off the method's name, so a `BEGIN` sent through
+    /// `execute` is owned like one sent through `beginTransaction`: a call
+    /// that leaves a transaction open where there was none began it, and one
+    /// that leaves none ended it. The scope is the part of a request token
+    /// before its last `/`. Only touched on `databaseQueue`.
+    private static var transactionScope: String?
+
+    private static func database(requestToken: String, method: String, args: [Any]) -> Result<Any, CraftNativeActionError> {
+        let before = database.map { sqlite3_get_autocommit($0) == 0 } ?? false
+        let answer = databaseCall(method: method, args: args)
+        let after = database.map { sqlite3_get_autocommit($0) == 0 } ?? false
+        if after && !before {
+            transactionScope = requestToken.range(of: "/", options: .backwards).map { String(requestToken[..<$0.lowerBound]) } ?? ""
+        } else if !after {
+            transactionScope = nil
+        }
+        return answer
+    }
+
+    private static func databaseCall(method: String, args: [Any]) -> Result<Any, CraftNativeActionError> {
         guard openDatabase() else { return failure("DATABASE_ERROR", "Could not open the local database") }
         switch method {
         case "execute":
@@ -1497,7 +1537,11 @@ enum CraftNativeActions {
             "host": url.host ?? "",
             "path": url.path,
             "query": url.query ?? "",
-            "queryParams": Dictionary(uniqueKeysWithValues: (components?.queryItems ?? []).map { ($0.name, $0.value ?? "") }),
+            // A link is whatever its sender wrote, and may name a parameter
+            // twice. Built with unique keys this trapped, and the app closed
+            // on being opened by such a link. The first value is kept, which
+            // is the one Android gives.
+            "queryParams": Dictionary((components?.queryItems ?? []).map { ($0.name, $0.value ?? "") }, uniquingKeysWith: { first, _ in first }),
         ]
     }
 

package/dist/ios/templates/CraftNativeFiles.swift

@@ -902,8 +902,15 @@ enum CraftNativeFiles {
         guard let text = data as? String else {
             return .failure(CraftNativeActionError(code: "INVALID_ARGUMENT", message: "files.write needs its contents as a string"))
         }
+        // Absent or null is utf8. Anything else that is not one of the two
+        // names is refused, a number included, rather than read as utf8.
+        let encoding: String?
+        switch options["encoding"] {
+        case nil, is NSNull: encoding = "utf8"
+        case let named: encoding = named as? String
+        }
         let bytes: Data
-        switch options["encoding"] as? String ?? "utf8" {
+        switch encoding {
         case "utf8":
             bytes = Data(text.utf8)
         case "base64":

package/dist/ios/templates/CraftNativeScreen.swift

@@ -4798,14 +4798,23 @@ final class CraftPressFeedbackDelegate: NSObject, UIGestureRecognizerDelegate {
 
 /// Whether a scrolling view's gesture runs together with `other`. A scroll
 /// view is the delegate of its own pan as well as of its keyboard tap, so this
-/// answers for both. Everything runs together (the keyboard tap watches
+/// answers for both. Most things run together (the keyboard tap watches
 /// alongside a control's own gestures; the back-swipe and the tab swipe decide
-/// for themselves) except two scroll views' pans: run together, a drag on a
-/// nested scroll view scrolled its parent at the same time.
+/// for themselves), with two exceptions for a scroll view's pan.
+///
+/// Another scroll view's pan: run together, a drag on a nested scroll view
+/// scrolled its parent at the same time.
+///
+/// A press. A row or a card that can be pressed is a view with a tap
+/// recognizer, and UIKit fails a tap the moment a drag begins on the scroll
+/// view around it. That is what keeps a flick, or the touch that stops a
+/// moving list, from also pressing whatever is under the finger. Told to run
+/// together, both happened: a short scroll pressed the thing it began on.
 func craftScrollGesture(_ gesture: UIGestureRecognizer, runsWith other: UIGestureRecognizer) -> Bool {
-    guard let scroll = gesture.view as? UIScrollView, gesture === scroll.panGestureRecognizer,
-          let otherScroll = other.view as? UIScrollView, other === otherScroll.panGestureRecognizer else { return true }
-    return false
+    guard let scroll = gesture.view as? UIScrollView, gesture === scroll.panGestureRecognizer else { return true }
+    if let otherScroll = other.view as? UIScrollView, other === otherScroll.panGestureRecognizer { return false }
+    if other is UITapGestureRecognizer, other.delegate is CraftPressGestureDelegate { return false }
+    return true
 }
 
 /// Scroll containers observe taps without cancelling native input focus or
@@ -6930,6 +6939,17 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     private var runningAnimation: CraftNativeRunningAnimation?
     private var renderedRoot: RenderedNode?
     private weak var lastFocusedInput: UIView?
+    /// On its way off screen, or off it: from `viewWillDisappear` until the
+    /// screen is next about to appear.
+    ///
+    /// A screen ends editing as it starts to leave (#497), and its view stays
+    /// in the window for the length of the transition. Whatever put focus
+    /// back in that time brought the keyboard up for a screen that was then
+    /// removed, where nothing could put it away: a render, and a sign-in
+    /// screen makes one as it navigates; the acknowledgement an input had
+    /// scheduled a tenth of a second before; a modal closing; `autoFocus`.
+    /// Each of them asks this first.
+    private var isLeavingScreen = false
 
     /// The person put the keyboard away (Return, or a tap on nothing in a
     /// scroll view): the last input is let go. Kept, the next render or
@@ -7035,6 +7055,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         let timers = self.timers
         CraftNativeScriptThread.run { timers.pending.values.forEach { $0.cancel() } }
         pendingCapabilityRequests.forEach { CraftNativeActions.cancel(requestToken: $0) }
+        CraftNativeActions.endScope(capabilityScope)
         lifecycleObservers.forEach(NotificationCenter.default.removeObserver)
         if let deepLinkListener = deepLinkListener { DeepLinkManager.shared.removeNativeListener(deepLinkListener) }
     }
@@ -7091,6 +7112,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
 
     override func viewWillAppear(_ animated: Bool) {
         super.viewWillAppear(animated)
+        isLeavingScreen = false
         if let navigationBarHidden, navigationController?.isNavigationBarHidden != navigationBarHidden {
             navigationController?.setNavigationBarHidden(navigationBarHidden, animated: animated)
         } else if navigationBarHidden == nil, navigationController?.isNavigationBarHidden == true,
@@ -7133,7 +7155,10 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         //
         // `lastFocusedInput` is deliberately left alone. A screen merely
         // covered by a push comes back, and restoreFocus putting the person
-        // back where they were is the behaviour that was already there.
+        // back where they were is the behaviour that was already there. It
+        // is not consulted again until the screen is coming back, or what
+        // is ended here would be started again a moment later.
+        isLeavingScreen = true
         view.endEditing(true)
         screenVisibilityChanged(false)
         stopCelebrations(in: view)
@@ -7298,6 +7323,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         pendingCapabilityDeadlines.values.forEach { $0.cancel() }
         pendingCapabilityDeadlines.removeAll()
         pendingCapabilityRequests.forEach { CraftNativeActions.cancel(requestToken: $0) }
+        CraftNativeActions.endScope(capabilityScope)
         pendingCapabilityRequests.removeAll()
         if let owner = voiceRecordingOwner {
             voiceRecordingOwner = nil
@@ -9307,7 +9333,9 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
                     reply(.failure(CraftNativeActionError(code: "UNSUPPORTED_TARGET", message: "Keyboard focus is supported only for text inputs")))
                     return true
                 }
-                guard node.view.becomeFirstResponder() else {
+                // A screen that is leaving does not open a keyboard it will
+                // not be there to close.
+                guard !isLeavingScreen, node.view.becomeFirstResponder() else {
                     reply(.failure(CraftNativeActionError(code: "FOCUS_FAILED", message: "The mounted view refused keyboard focus")))
                     return true
                 }
@@ -9652,6 +9680,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     }
 
     private func restoreFocus(_ focused: UIView?) {
+        guard !isLeavingScreen else { return }
         guard let focused, focused.window != nil, !focused.isFirstResponder,
               lastFocusedInput === focused, firstResponder(in: rootStack) == nil else { return }
         var ancestor: UIView? = focused
@@ -9862,7 +9891,10 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             updateAuxiliaryHandler(events["onEndEditing"], in: &endEditingHandlers, for: field)
             updateAuxiliaryHandler(events["onSubmitEditing"], in: &submitHandlers, for: field)
             if props["autoFocus"] as? Bool == true, !field.isFirstResponder {
-                DispatchQueue.main.async { _ = field.becomeFirstResponder() }
+                DispatchQueue.main.async { [weak self] in
+                    guard self?.isLeavingScreen == false else { return }
+                    _ = field.becomeFirstResponder()
+                }
             }
         case "SegmentedControl":
             let control = result as! CraftNativeSegmentedControl
@@ -9982,7 +10014,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             if !visible, wasVisible == true {
                 let restore = modalFocusRestore.removeValue(forKey: modalID)
                 DispatchQueue.main.async { [weak self, weak restore] in
-                    guard let self, let restore, restore.window != nil, restore.isDescendant(of: self.view) else { return }
+                    guard let self, !self.isLeavingScreen, let restore, restore.window != nil, restore.isDescendant(of: self.view) else { return }
                     self.lastFocusedInput = restore
                     _ = restore.becomeFirstResponder()
                 }
@@ -11185,7 +11217,10 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         updateAuxiliaryHandler(events["onEndEditing"], in: &endEditingHandlers, for: textView)
         updateAuxiliaryHandler(events["onSubmitEditing"], in: &submitHandlers, for: textView)
         if props["autoFocus"] as? Bool == true, !textView.isFirstResponder {
-            DispatchQueue.main.async { _ = textView.becomeFirstResponder() }
+            DispatchQueue.main.async { [weak self] in
+                guard self?.isLeavingScreen == false else { return }
+                _ = textView.becomeFirstResponder()
+            }
         }
     }
 

package/dist/ios/templates/CraftPersistentStorage.swift

@@ -13,11 +13,22 @@ enum CraftPersistentStorage {
         let digest = SHA256.hash(data: Data(key.utf8)).map { String(format: "%02x", $0) }.joined()
         return directory.appendingPathComponent(digest + ".json")
     }
+    /// What an entry file holds, or nil when it is there and is not an entry.
+    ///
+    /// A file that cannot be parsed is a corrupt value, as one that parses to
+    /// the wrong thing is, and an app starts that value again. Only a file
+    /// that cannot be read at all is the disk failing, which an app retries;
+    /// that still throws. The two used to share the disk's answer.
+    private static func entry(at source: URL) throws -> [String: Any]? {
+        let contents = try Data(contentsOf: source)
+        return (try? JSONSerialization.jsonObject(with: contents)) as? [String: Any]
+    }
+
     static func get(_ key: String, prefix: String, storageDirectory: URL? = nil) throws -> Data? {
         lock.lock(); defer { lock.unlock() }
         let source = path(key, directory: storageDirectory ?? directory)
         if FileManager.default.fileExists(atPath: source.path) {
-            guard let saved = try JSONSerialization.jsonObject(with: Data(contentsOf: source)) as? [String: Any], saved["key"] as? String == key else {
+            guard let saved = try entry(at: source), saved["key"] as? String == key else {
                 throw CraftNativeActionError(code: "STORAGE_CORRUPT", message: "Invalid stored value")
             }
             if saved["deleted"] as? Bool == true { return nil }
@@ -26,7 +37,9 @@ enum CraftPersistentStorage {
         }
         guard let legacy = UserDefaults.standard.data(forKey: prefix + key) else { return nil }
         // Only valid legacy JSON qualifies for deferred migration on I/O failure.
-        _ = try JSONSerialization.jsonObject(with: legacy, options: .fragmentsAllowed)
+        guard (try? JSONSerialization.jsonObject(with: legacy, options: .fragmentsAllowed)) != nil else {
+            throw CraftNativeActionError(code: "STORAGE_CORRUPT", message: "Stored value is not valid JSON")
+        }
         // Reading a valid legacy checkpoint must survive a full disk. Migration
         // can be retried on a later read; only a successful set promises a new
         // durable checkpoint and permits the application to acknowledge it.
@@ -84,9 +97,11 @@ enum CraftPersistentStorage {
         var result = Set(UserDefaults.standard.dictionaryRepresentation().keys.filter { $0.hasPrefix(prefix) }.map { String($0.dropFirst(prefix.count)) })
         if FileManager.default.fileExists(atPath: directory.path) {
             for source in try FileManager.default.contentsOfDirectory(at: directory, includingPropertiesForKeys: nil) where source.pathExtension == "json" {
-                guard let entry = try JSONSerialization.jsonObject(with: Data(contentsOf: source)) as? [String: Any], let key = entry["key"] as? String else {
-                    throw CraftNativeActionError(code: "STORAGE_CORRUPT", message: "Invalid stored value")
-                }
+                // A file that is not an entry names no key. It used to fail
+                // the whole listing, and `clear` with it, over a value
+                // neither call had been asked about. `get` of its key still
+                // answers STORAGE_CORRUPT.
+                guard let entry = try entry(at: source), let key = entry["key"] as? String else { continue }
                 if entry["deleted"] as? Bool == true { result.remove(key) } else { result.insert(key) }
             }
         }
@@ -95,5 +110,13 @@ enum CraftPersistentStorage {
     static func clear(prefix: String) throws {
         lock.lock(); defer { lock.unlock() }
         for key in try keys(prefix: prefix) { try set(key, data: nil, prefix: prefix) }
+        // Clearing a key writes over its file, so what is still not an entry
+        // belongs to no key this store knows, and cannot be marked removed.
+        // It is deleted. No earlier value can come back in its place: every
+        // one this store mirrors was removed just above.
+        guard FileManager.default.fileExists(atPath: directory.path) else { return }
+        for source in try FileManager.default.contentsOfDirectory(at: directory, includingPropertiesForKeys: nil) where source.pathExtension == "json" {
+            if try entry(at: source)?["key"] as? String == nil { try FileManager.default.removeItem(at: source) }
+        }
     }
 }

package/package.json

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