craft-native 0.0.496 → 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
@@ -1313,13 +1359,7 @@ internal class CraftNativeChrome(
             action.layoutParams = LayoutParams(dp(48), dp(48)).apply { marginStart = if (grouped) 0 else dp(8) }
         }
         accessory.layoutParams = LayoutParams(dp(if (grouped) 48 else 64), dp(if (grouped) 48 else 64)).apply { marginStart = if (grouped) 0 else dp(8) }
-        val divider = GradientDrawable().apply { setColor(Color.argb(48, 128, 128, 128)); setSize(dp(1), dp(1)) }
-        for (row in listOf(accessoryGroup, companionRow)) {
-            row.showDividers = if (grouped) SHOW_DIVIDER_MIDDLE else SHOW_DIVIDER_NONE
-            row.dividerDrawable = if (grouped) divider.constantState?.newDrawable() else null
-            row.dividerPadding = dp(12)
-        }
-        // An empty companion row must not leave a divider above a single icon.
+        // A group is one control: no divider between its actions, as on iOS.
         companionRow.visibility = if (companionViews.isEmpty()) View.GONE else View.VISIBLE
     }
 
@@ -1420,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()
         }
     }