craft-native 0.0.491 → 0.0.496

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

@@ -1,2 +1,9 @@
 /** Uses the Android builder's Kotlin version, including its transitive compiler dependencies. */
 export declare function runKotlinFixture(source: string, libraries?: readonly string[]): Promise<void>;
+/**
+ * One member of a Kotlin class in a template, as shipped, so a fixture can run
+ * the real text rather than a copy of it: a function, or a property with its
+ * initialiser. Members sit at four spaces; the member is everything deeper,
+ * to its closing brace when it has a block body.
+ */
+export declare function liftKotlinMember(template: string, name: string): string;

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

@@ -34,10 +34,12 @@ import org.json.JSONTokener
 import java.io.ByteArrayOutputStream
 import java.io.File
 import java.io.FileOutputStream
+import java.io.IOException
 import java.net.HttpURLConnection
 import java.net.SocketTimeoutException
 import java.net.URL
 import java.net.URLConnection
+import java.net.URLDecoder
 import java.util.UUID
 import java.util.concurrent.ConcurrentHashMap
 import java.util.concurrent.Executors
@@ -540,8 +542,7 @@ internal class CraftNativeCapabilities(
             val options = args.optJSONObject(2) ?: JSONObject()
             val bytes = when (options.optString("encoding", "utf8")) {
                 "utf8" -> data.toByteArray(Charsets.UTF_8)
-                "base64" -> runCatching { Base64.decode(data, Base64.DEFAULT) }
-                    .getOrElse { return failure("INVALID_ARGUMENT", "files.write base64 is invalid") }
+                "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" })
@@ -555,6 +556,30 @@ internal class CraftNativeCapabilities(
         }
     }
 
+    /**
+     * 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
+     * optional but right when it is there, and nothing else. Android's own
+     * decoder skips any character it does not know, so the `-` and `_` of a
+     * URL-safe encoding would vanish and a wrong file be written with no
+     * error. It is handed only what has already been read as valid.
+     */
+    private fun decodeBase64(text: String): ByteArray? {
+        val data = StringBuilder(text.length)
+        var padding = 0
+        for (letter in text) {
+            when {
+                letter == ' ' || letter == '\t' || letter == '\n' || letter == '\u000C' || letter == '\r' -> Unit
+                letter == '=' -> padding += 1
+                padding > 0 -> return null
+                letter in 'A'..'Z' || letter in 'a'..'z' || letter in '0'..'9' || letter == '+' || letter == '/' -> data.append(letter)
+                else -> return null
+            }
+        }
+        if (padding > 2 || data.length % 4 == 1 || (padding > 0 && (data.length + padding) % 4 != 0)) return null
+        return runCatching { Base64.decode(data.toString(), Base64.DEFAULT) }.getOrNull()
+    }
+
     private fun download(requestToken: String, args: JSONArray): CraftNativeCapabilityResult {
         val address = args.optString(0).trim()
         val url = validURL(address) ?: return failure("INVALID_ARGUMENT", "files.download needs an absolute http or https URL")
@@ -585,18 +610,47 @@ internal class CraftNativeCapabilities(
         return try {
             val status = connection.responseCode
             if (status !in 200..299) return refusedDownload(connection, status, requestToken)
-            val name = options.optString("name").ifBlank { connection.url.path.substringAfterLast('/').ifBlank { "download" } }
+            // The name the screen asked for, else the server's, else the
+            // address's: the order UIKit's download keeps a file under.
+            val name = options.optString("name").ifBlank { downloadName(connection.getHeaderField("Content-Disposition"), connection.url.path) }
             val file = File(fileRoot, UUID.randomUUID().toString()).apply { mkdirs() }.resolve(safeFileName(name))
-            connection.inputStream.use { input -> FileOutputStream(file).use { output ->
-                val buffer = ByteArray(8192)
-                while (true) {
-                    if (cancelled.contains(requestToken)) return failure("CANCELLED", "File download was cancelled")
-                    val count = input.read(buffer)
-                    if (count < 0) break
-                    output.write(buffer, 0, count)
+            var kept = false
+            try {
+                val output = try { FileOutputStream(file) } catch (error: IOException) {
+                    return failure("WRITE_ERROR", error.message ?: "File could not be written")
                 }
-            } }
-            success(descriptor(file, connection.contentType ?: "application/octet-stream"))
+                var written = 0L
+                output.use { connection.inputStream.use { input ->
+                    val buffer = ByteArray(8192)
+                    while (true) {
+                        if (cancelled.contains(requestToken)) return failure("CANCELLED", "File download was cancelled")
+                        val count = input.read(buffer)
+                        if (count < 0) break
+                        // A full disk is not the network's failure.
+                        try { output.write(buffer, 0, count) } catch (error: IOException) {
+                            return failure("WRITE_ERROR", error.message ?: "File could not be written")
+                        }
+                        written += count
+                    }
+                } }
+                // A body shorter than the server said it would be is not the
+                // file. Android's connection fails such a read itself, and
+                // other implementations simply stop, so the length is checked
+                // here and the answer is this function's own. (When the
+                // connection decompressed the body it reports no length.)
+                val declared = connection.getHeaderField("Content-Length")?.trim()?.toLongOrNull()
+                if (declared != null && written != declared) {
+                    // A cancel can end the read early rather than fail it.
+                    return if (cancelled.contains(requestToken)) failure("CANCELLED", "File download was cancelled")
+                    else failure("NETWORK_ERROR", "File download ended after $written of $declared bytes")
+                }
+                kept = true
+                // `ok` is how a screen tells this from a refusal, which
+                // resolves `{ ok: false, status, body }` rather than rejecting.
+                success(descriptor(file, connection.contentType ?: "application/octet-stream").put("ok", true).put("status", status))
+            } finally {
+                if (!kept) removePartial(file)
+            }
         } catch (error: SocketTimeoutException) {
             failure("TIMEOUT", error.message ?: "File download timed out")
         } catch (error: Exception) {
@@ -608,6 +662,38 @@ internal class CraftNativeCapabilities(
         }
     }
 
+    /**
+     * A download that stopped part-way is not a file. Nothing was told its
+     * path, so nothing would remove it before the daily sweep.
+     */
+    private fun removePartial(file: File) {
+        runCatching { file.delete() }
+        // Its folder was made for it alone; delete refuses one that is not empty.
+        runCatching { file.parentFile?.takeIf { it != fileRoot }?.delete() }
+    }
+
+    /**
+     * The server's name for a download (`Content-Disposition`, the encoded
+     * `filename*` before the plain one), else the address's last segment as a
+     * person reads it rather than as it is percent-encoded.
+     */
+    private fun downloadName(disposition: String?, path: String): String {
+        val header = disposition.orEmpty()
+        Regex("filename\\*\\s*=\\s*UTF-8''([^;\\s]+)", RegexOption.IGNORE_CASE).find(header)?.let { match ->
+            percentDecoded(match.groupValues[1])?.takeIf { it.isNotBlank() }?.let { return it }
+        }
+        Regex("filename\\s*=\\s*(?:\"((?:[^\"\\\\]|\\\\.)*)\"|([^;]+))", RegexOption.IGNORE_CASE).find(header)?.let { match ->
+            val quoted = match.groups[1]?.value?.replace(Regex("\\\\(.)")) { it.groupValues[1] }
+            (quoted ?: match.groupValues[2]).trim().takeIf { it.isNotBlank() }?.let { return it }
+        }
+        val segment = path.substringAfterLast('/')
+        return (percentDecoded(segment) ?: segment).ifBlank { "download" }
+    }
+
+    /** Percent-decoded as UTF-8, or null when it is not validly encoded. A `+` is a plus, not a space. */
+    private fun percentDecoded(value: String): String? =
+        runCatching { URLDecoder.decode(value.replace("+", "%2B"), "UTF-8") }.getOrNull()
+
     private fun refusedDownload(
         connection: HttpURLConnection,
         status: Int,
@@ -997,9 +1083,24 @@ internal class CraftNativeCapabilities(
         return true
     }
 
+    /**
+     * A file name with no path in it that the disk will take, as UIKit's
+     * `safeName` makes one: no leading dots (so never `..`, the folder
+     * itself), and cut to fit. 255 bytes is what a name may be on disk and
+     * 120 characters is where UIKit cuts; the extension stays, since it is
+     * how a share sheet and an upload know what the file is.
+     */
     private fun safeFileName(raw: String): String {
-        val name = raw.substringAfterLast('/').substringAfterLast('\\').trim()
-        return name.ifBlank { "file" }.replace(Regex("[\\\\/:*?\"<>|\\r\\n]"), "_")
+        val name = raw.substringAfterLast('/').substringAfterLast('\\').trim().trimStart('.')
+        val safe = name.replace(Regex("[\\\\/:*?\"<>|\\r\\n\\u0000]"), "_").ifBlank { "file" }
+        fun fits(value: String) = value.codePointCount(0, value.length) <= 120 && value.toByteArray(Charsets.UTF_8).size <= 255
+        if (fits(safe)) return safe
+        val dot = safe.lastIndexOf('.')
+        val extension = if (dot > 0 && safe.length - dot <= 16) safe.substring(dot) else ""
+        var stem = safe.dropLast(extension.length)
+        stem = stem.substring(0, stem.offsetByCodePoints(0, minOf(120, stem.codePointCount(0, stem.length))))
+        while (stem.isNotEmpty() && !fits(stem + extension)) stem = stem.substring(0, stem.offsetByCodePoints(stem.length, -1))
+        return stem + extension
     }
 
     private fun jpegName(raw: String): String {
@@ -1093,10 +1194,18 @@ internal class CraftNativeCapabilities(
         }
     }
 
-    private fun secureStorage(method: String, args: JSONArray): CraftNativeCapabilityResult {
+    private fun secureStorage(method: String, args: JSONArray): CraftNativeCapabilityResult = synchronized(CraftNativeStorage.secureLock) {
+        // A write that did not reach the disk is a failure, and nothing is told
+        // it happened: the store's own memory is put back (a failed commit
+        // has already changed it), no isolate hears of it, and the caller is
+        // refused, as UIKit refuses a Keychain delete that failed. Answering
+        // `false` and telling every isolate the token was gone made a failed
+        // sign-out look like a sign-out until the next launch read the disk.
         if (method == "clear") {
             return try {
-                success(encryptedSecureStorage.edit().clear().commit().also { storeObserver?.invoke("secure", null, null) })
+                if (!CraftNativeStorage.commit(encryptedSecureStorage) { it.clear() }) return failure("SECURE_STORAGE_ERROR", "Secure storage could not be cleared")
+                storeObserver?.invoke("secure", null, null)
+                success(true)
             } catch (error: Exception) {
                 failure("SECURE_STORAGE_ERROR", error.message ?: "Secure storage could not be cleared")
             }
@@ -1106,14 +1215,18 @@ internal class CraftNativeCapabilities(
             when (method) {
                 "set" -> {
                     if (args.length() != 2 || args.opt(1) !is String) return failure("INVALID_ARGUMENT", "SecureStorage.set needs a key and string value")
-                    if (encryptedSecureStorage.edit().putString(key, args.getString(1)).commit()) {
-                        storeObserver?.invoke("secure", key, args.getString(1))
+                    val value = args.getString(1)
+                    if (CraftNativeStorage.commit(encryptedSecureStorage) { it.putString(key, value) }) {
+                        storeObserver?.invoke("secure", key, value)
                         success(true)
                     }
                     else failure("SECURE_STORAGE_ERROR", "Secure storage could not be written")
                 }
                 "get" -> success(encryptedSecureStorage.getString(key, null) ?: JSONObject.NULL)
-                "remove" -> success(encryptedSecureStorage.edit().remove(key).commit().also { storeObserver?.invoke("secure", key, null) })
+                "remove" -> if (CraftNativeStorage.commit(encryptedSecureStorage) { it.remove(key) }) {
+                    storeObserver?.invoke("secure", key, null)
+                    success(true)
+                } else failure("SECURE_STORAGE_ERROR", "Secure storage could not be removed")
                 else -> failure("UNKNOWN_ACTION", "Unsupported SecureStorage method")
             }
         } catch (error: Exception) {

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

@@ -294,6 +294,8 @@ internal class CraftNativeRoutes(config: JSONObject) {
 /** One process-wide boundary for committed storage reads and mutations. */
 internal object CraftNativeStorage {
     val lock = Any()
+    /** The secure store's writes, one at a time across every host in the process: a rollback restores what it read. */
+    val secureLock = Any()
     fun jsonEqual(left: Any?, right: Any?): Boolean {
         if (left == null || left === JSONObject.NULL) return right == null || right === JSONObject.NULL
         if (left is Boolean || right is Boolean) return left is Boolean && right is Boolean && left == right
@@ -365,6 +367,30 @@ internal class CraftNativeStores private constructor(
         cache
     }
 
+    /**
+     * Checkpoints that have been asked for and are not on disk yet, the
+     * newest per name; a null is one being deleted. A read finds these first,
+     * as UIKit's `CraftSnapshots.read` finds its `pending`, so a screen opened
+     * right after a checkpoint is seeded with it, and one opened right after
+     * a sign-out is not seeded with the account that just left (#507). The
+     * number is which request put the entry there. Guarded by itself.
+     */
+    private val pendingSnapshots = HashMap<String, Pair<Long, String?>>()
+    private var snapshotRevision = 0L
+
+    /** What a read gives now: the snapshots on disk with those on their way laid over them. */
+    private fun currentSnapshots(): Map<String, String> {
+        synchronized(pendingSnapshots) {
+            if (pendingSnapshots.isEmpty()) return snapshotCache
+            val current = HashMap(snapshotCache)
+            for ((name, waiting) in pendingSnapshots) {
+                val json = waiting.second
+                if (json == null) current.remove(name) else current[name] = json
+            }
+            return current
+        }
+    }
+
     /**
      * Everything an isolate needs before its first line runs, as JSON text:
      * `{ storage: { key: json }, secure: { key: value }, snapshots: { name: json } }`.
@@ -388,7 +414,7 @@ internal class CraftNativeStores private constructor(
         out.append(',')
         section("secure", runCatching { secure?.all?.mapNotNull { (key, value) -> (value as? String)?.let { key to it } }?.toMap() }.getOrNull() ?: emptyMap())
         out.append(',')
-        section("snapshots", snapshotCache)
+        section("snapshots", currentSnapshots())
         out.append('}')
         return out.toString()
     }
@@ -396,7 +422,12 @@ internal class CraftNativeStores private constructor(
     /** The same, parsed (tests and small hosts). */
     fun preload(): JSONObject = JSONObject(preloadText())
 
-    fun snapshot(name: String): String? = snapshotCache[name]
+    fun snapshot(name: String): String? {
+        synchronized(pendingSnapshots) {
+            val waiting = pendingSnapshots[name]
+            return if (waiting != null) waiting.second else snapshotCache[name]
+        }
+    }
 
     /**
      * One secure value, read directly rather than through the preload.
@@ -432,44 +463,72 @@ internal class CraftNativeStores private constructor(
             main.post { done(false) }
             return
         }
-        writer.execute {
-            val file = snapshotFile(name)
-            val previous = snapshotCache[name]
-            val ok = runCatching {
-                if (json == null) {
-                    !file.exists() || file.delete()
-                } else {
-                    snapshotFiles.set(file, json)
-                    true
+        // Admitting the write and queueing it are one step, as on UIKit:
+        // apart, an older request could reach the disk after a newer one
+        // while readers were already being given the newer value.
+        synchronized(pendingSnapshots) {
+            snapshotRevision += 1
+            val mine = snapshotRevision
+            pendingSnapshots[name] = mine to json
+            writer.execute {
+                val file = snapshotFile(name)
+                val ok = runCatching {
+                    if (json == null) {
+                        !file.exists() || file.delete()
+                    } else {
+                        snapshotFiles.set(file, json)
+                        true
+                    }
+                }.getOrDefault(false)
+                if (ok) {
+                    if (json == null) snapshotCache.remove(name) else snapshotCache[name] = json
+                }
+                val current = synchronized(pendingSnapshots) {
+                    if (pendingSnapshots[name]?.first == mine) pendingSnapshots.remove(name)
+                    snapshot(name)
+                }
+                main.post {
+                    // Isolates optimistically display their write. Each is
+                    // told what a read gives now: the checkpoint when it was
+                    // kept, the confirmed value when it was not, and a newer
+                    // one still on its way in either case, so an older write
+                    // settling cannot set a screen back behind it.
+                    changed("snapshots", name, current, null)
+                    done(ok)
                 }
-            }.getOrDefault(false)
-            if (ok) {
-                if (json == null) snapshotCache.remove(name) else snapshotCache[name] = json
-            }
-            main.post {
-                // Isolates optimistically display their write. Restore the
-                // confirmed value before rejecting an unsuccessful checkpoint.
-                changed("snapshots", name, if (ok) json else previous, null)
-                done(ok)
             }
         }
     }
 
     /** `craft.snapshots.clear(keep)`: every snapshot but those named, as a sign-out does. */
     fun clearSnapshots(keep: Set<String>, done: (Boolean) -> Unit) {
-        writer.execute {
-            val removed = mutableListOf<String>()
-            var ok = true
-            snapshotsDir.listFiles()?.forEach { file ->
-                if (!file.name.endsWith(".json")) return@forEach
-                val name = snapshotName(file) ?: return@forEach
-                if (name in keep) return@forEach
-                if (file.delete()) removed.add(name) else ok = false
-            }
-            removed.forEach(snapshotCache::remove)
-            main.post {
-                removed.forEach { changed("snapshots", it, null, null) }
-                done(ok)
+        synchronized(pendingSnapshots) {
+            // Gone for a reader from this moment, as on UIKit, where a clear
+            // is a delete of every name.
+            snapshotRevision += 1
+            val mine = snapshotRevision
+            val doomed = currentSnapshots().keys.filter { it !in keep }
+            doomed.forEach { pendingSnapshots[it] = mine to null }
+            writer.execute {
+                val removed = mutableListOf<String>()
+                var ok = true
+                snapshotsDir.listFiles()?.forEach { file ->
+                    if (!file.name.endsWith(".json")) return@forEach
+                    val name = snapshotName(file) ?: return@forEach
+                    if (name in keep) return@forEach
+                    if (file.delete()) removed.add(name) else ok = false
+                }
+                removed.forEach(snapshotCache::remove)
+                val current = synchronized(pendingSnapshots) {
+                    doomed.forEach { if (pendingSnapshots[it]?.first == mine) pendingSnapshots.remove(it) }
+                    // One that could not be deleted is still there, and one
+                    // written since the clear was asked for is on its way.
+                    (removed + doomed).distinct().associateWith { snapshot(it) }
+                }
+                main.post {
+                    current.forEach { (name, json) -> changed("snapshots", name, json, null) }
+                    done(ok)
+                }
             }
         }
     }
@@ -912,6 +971,7 @@ internal class CraftNativeChrome(
     private val fonts: CraftNativeChromeFonts = CraftNativeChromeFonts(),
 ) : LinearLayout(context) {
     val content = FrameLayout(context)
+    private val body = FrameLayout(context)
     private val bar = LinearLayout(context)
     private val backButton = ImageView(context)
     private val leadingButtons = LinearLayout(context)
@@ -922,6 +982,7 @@ internal class CraftNativeChrome(
     private val tabRow = LinearLayout(context)
     private val accessory = FrameLayout(context)
     private val companionRow = LinearLayout(context)
+    private val accessoryGroup = LinearLayout(context)
     private val companionViews = mutableListOf<Pair<FrameLayout, JSONObject>>()
     private var renderedCompanionSpecs = ""
     private val accessoryIcon = ImageView(context)
@@ -1002,7 +1063,8 @@ internal class CraftNativeChrome(
         largeTitleView.ellipsize = TextUtils.TruncateAt.END
         largeTitleView.setPadding(dp(16), 0, dp(16), dp(8))
         addView(largeTitleView, LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.WRAP_CONTENT))
-        addView(content, LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, 0, 1f))
+        body.addView(content, FrameLayout.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT))
+        addView(body, LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, 0, 1f))
         tabBar.orientation = HORIZONTAL
         tabBar.gravity = Gravity.CENTER
         tabs.forEachIndexed { index, tab ->
@@ -1052,7 +1114,9 @@ internal class CraftNativeChrome(
         tabRow.addView(tabBar, LayoutParams(0, dp(64), 1f))
         companionRow.orientation = HORIZONTAL
         companionRow.gravity = Gravity.CENTER_VERTICAL
-        tabRow.addView(companionRow, LayoutParams(ViewGroup.LayoutParams.WRAP_CONTENT, dp(64)))
+        accessoryGroup.orientation = HORIZONTAL
+        accessoryGroup.gravity = Gravity.CENTER
+        accessoryGroup.addView(companionRow, LayoutParams(ViewGroup.LayoutParams.WRAP_CONTENT, ViewGroup.LayoutParams.WRAP_CONTENT))
         accessory.addView(accessoryIcon, FrameLayout.LayoutParams(dp(26), dp(26), Gravity.CENTER))
         accessoryBadge.textSize = 10f
         accessoryBadge.gravity = Gravity.CENTER
@@ -1062,7 +1126,8 @@ internal class CraftNativeChrome(
         accessory.addView(accessoryBadge, FrameLayout.LayoutParams(ViewGroup.LayoutParams.WRAP_CONTENT, dp(18), Gravity.TOP or Gravity.END))
         accessory.setOnClickListener { accessorySpec?.optString("path")?.let { onAccessory?.invoke(it) } }
         accessory.visibility = View.GONE
-        tabRow.addView(accessory, LayoutParams(dp(64), dp(64)).apply { marginStart = dp(8) })
+        accessoryGroup.addView(accessory, LayoutParams(dp(64), dp(64)).apply { marginStart = dp(8) })
+        tabRow.addView(accessoryGroup, LayoutParams(ViewGroup.LayoutParams.WRAP_CONTENT, ViewGroup.LayoutParams.WRAP_CONTENT))
         addView(tabRow, LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, dp(72)))
         tabRow.visibility = if (tabs.isEmpty()) View.GONE else View.VISIBLE
         refreshColors()
@@ -1074,7 +1139,8 @@ internal class CraftNativeChrome(
                 val overHorizontalScroll = onTabSwipeShouldDefer?.invoke(event.x, event.y) == true
                 horizontalScrollDeferred = overHorizontalScroll
                 if (overHorizontalScroll) parent?.requestDisallowInterceptTouchEvent(true)
-                swipeTracking = tabs.size > 1 && tabSwipeEnabled && !overHorizontalScroll && tabRow.visibility == View.VISIBLE && event.y < tabRow.top
+                val overActions = android.graphics.Rect().let { accessoryGroup.getGlobalVisibleRect(it) && it.contains(event.rawX.toInt(), event.rawY.toInt()) }
+                swipeTracking = tabs.size > 1 && tabSwipeEnabled && !overActions && !overHorizontalScroll && tabRow.visibility == View.VISIBLE && event.y < tabRow.top
                 swipeIntercepted = false
                 swipeDownX = event.x
                 swipeDownY = event.y
@@ -1218,10 +1284,45 @@ internal class CraftNativeChrome(
             accessoryBadge.text = it.optString("badge").takeUnless { badge -> badge == "null" }.orEmpty().take(8)
             accessoryBadge.visibility = if (accessoryBadge.text.isEmpty()) View.GONE else View.VISIBLE
         }
+        layoutAccessoryGroup(tabBarHidden)
         tabSwipeEnabled = options.optBoolean("tabSwipeEnabled", true)
         refreshColors()
     }
 
+    /** The same actions and popup anchors survive switching between grouped and separate chrome. */
+    private fun layoutAccessoryGroup(hidden: Boolean) {
+        val layout = accessorySpec?.optString("layout").orEmpty()
+        val grouped = layout == "vertical" || layout == "horizontal"
+        val parent = if (grouped) body else tabRow
+        if (accessoryGroup.parent !== parent) {
+            (accessoryGroup.parent as? ViewGroup)?.removeView(accessoryGroup)
+            if (grouped) body.addView(accessoryGroup, FrameLayout.LayoutParams(ViewGroup.LayoutParams.WRAP_CONTENT, ViewGroup.LayoutParams.WRAP_CONTENT, Gravity.BOTTOM or Gravity.END).apply {
+                marginEnd = dp(20)
+                bottomMargin = dp(8)
+            }) else tabRow.addView(accessoryGroup, LayoutParams(ViewGroup.LayoutParams.WRAP_CONTENT, ViewGroup.LayoutParams.WRAP_CONTENT))
+        }
+        val vertical = layout == "vertical"
+        accessoryGroup.orientation = if (vertical) VERTICAL else HORIZONTAL
+        companionRow.orientation = accessoryGroup.orientation
+        accessoryGroup.setPadding(if (grouped) dp(2) else 0, if (grouped) dp(2) else 0, if (grouped) dp(2) else 0, if (grouped) dp(2) else 0)
+        accessoryGroup.visibility = if (accessorySpec == null || hidden || tabs.isEmpty()) View.GONE else View.VISIBLE
+        accessoryGroup.tag = if (grouped) "craft-tab-accessory-group" else null
+        accessoryGroup.elevation = if (grouped) dp(6).toFloat() else 0f
+        accessoryGroup.clipToOutline = grouped
+        companionViews.forEach { (action, _) ->
+            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.
+        companionRow.visibility = if (companionViews.isEmpty()) View.GONE else View.VISIBLE
+    }
+
     fun selectTab(index: Int) {
         selectedTab = index
         refreshColors()
@@ -1316,16 +1417,18 @@ internal class CraftNativeChrome(
         largeTitleView.setTextColor(navigationTitleColor ?: text)
         backButton.imageTintList = ColorStateList.valueOf(accent)
         val surface = if (dark) Color.parseColor("#1C1C1E") else Color.parseColor("#F9F9F9")
+        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
         accessory.isSelected = primarySelected
         companionViews.forEach { (action, item) ->
             val selected = isAccessorySelected(item)
             action.isSelected = selected
-            action.background = GradientDrawable().apply { setColor(if (selected) Color.argb(36, Color.red(accent), Color.green(accent), Color.blue(accent)) else surface); cornerRadius = dp(32).toFloat() }
+            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))
         }
-        accessory.background = GradientDrawable().apply { setColor(if (primarySelected) Color.argb(36, Color.red(accent), Color.green(accent), Color.blue(accent)) else surface); cornerRadius = dp(32).toFloat() }
+        accessory.background = if (grouped) rippleBackground() else GradientDrawable().apply { setColor(if (primarySelected) Color.argb(36, Color.red(accent), Color.green(accent), Color.blue(accent)) else surface); cornerRadius = dp(32).toFloat() }
         accessorySpec?.let { accessoryIcon.setImageDrawable(CraftNativeIcons.drawable(context, null, it.optString("symbol"), if (primarySelected) accent else text)) }
         tabViews.forEachIndexed { index, (icon, label) ->
             tabBar.getChildAt(index).isSelected = index == selectedTab && !accessorySelected

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

@@ -26,7 +26,17 @@ internal class CraftNativeSounds(
 ) {
     private data class Sound(
         val player: MediaPlayer,
+        /** Where the player is right now, part-way through a fade included. */
         var volume: Float,
+        /**
+         * The volume that was asked for. A fade moves `volume` toward or away
+         * from this and must not overwrite it: with one number for both, a
+         * pause during a fade left the sound at whatever fraction the fade had
+         * reached, and `resume` played it there for the rest of its life —
+         * `play({ volume: 1, fadeIn: 2000 })` paused at 500 ms came back at
+         * 0.25. UIKit keeps the two apart and resumes at the asked-for volume.
+         */
+        var asked: Float,
         var paused: Boolean = false,
         var interrupted: Boolean = false,
         var prepared: Boolean = false,
@@ -66,7 +76,7 @@ internal class CraftNativeSounds(
         // Its player, pending load and cancellation handle still belong to it.
         stop(id, 0.0)
         val player = MediaPlayer()
-        val sound = Sound(player, if (fadeIn > 0) 0f else volume, pending = done)
+        val sound = Sound(player, if (fadeIn > 0) 0f else volume, asked = volume, pending = done)
         sounds[id] = sound
         fun settle(result: CraftNativeCapabilityResult) {
             val answer = sound.pending ?: return
@@ -144,7 +154,19 @@ internal class CraftNativeSounds(
     fun resume(id: String): Boolean {
         val sound = sounds[id] ?: return false
         if (focusSuspended) return false
-        if (sound.prepared) runCatching { sound.player.start() }.onFailure { return false }
+        // UIKit answers false for a sound that is not paused, and a caller
+        // reading the answer to learn whether anything was resumed should not
+        // get a different one here.
+        if (!sound.paused) return false
+        if (sound.prepared) {
+            // A pause cancels a fade where it stands. Land on the volume that
+            // was asked for rather than on the fraction the fade had reached.
+            // Left alone until the player is prepared: a fade-in that has not
+            // begun yet still starts from silence when it does.
+            sound.volume = sound.asked
+            applyVolume(sound)
+            runCatching { sound.player.start() }.onFailure { return false }
+        }
         sound.paused = false
         sound.interrupted = false
         return true
@@ -154,6 +176,7 @@ internal class CraftNativeSounds(
         val sound = sounds[id] ?: return false
         if (!volume.isFinite() || !fade.isFinite() || fade < 0) return false
         val target = volume.coerceIn(0.0, 1.0).toFloat()
+        sound.asked = target
         sound.fade?.let(main::removeCallbacks)
         sound.fade = null
         if (fade > 0 && !sound.paused) ramp(sound, target, fade / 1000.0)

package/dist/cli.js

@@ -3246,7 +3246,7 @@ function pinCraftNativeDependency(packagePath, craftVersion) {
 `);
 }
 // package.json
-var version = "0.0.491";
+var version = "0.0.496";
 
 // 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.491";
+var version = "0.0.496";
 
 // 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.491";
+var version = "0.0.496";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;

package/dist/ios/templates/CraftApp.swift

@@ -819,6 +819,8 @@ final class CraftChrome: ObservableObject {
         var image: String? = nil
         /// A compact floating icon, instead of the system full-width accessory shelf.
         var iconOnly = false
+        /// A shared material capsule; nil keeps separate floating buttons.
+        var accessoryLayout: String? = nil
         var companions: [Tab] = []
         /// A tap opens these destinations in a compact menu instead of navigating.
         var menu: [TabMenuItem] = []
@@ -964,10 +966,11 @@ final class CraftChrome: ObservableObject {
         if let item, let path = item["path"] as? String,
            path.hasPrefix("/"), !path.hasPrefix("//"),
            let title = item["title"] as? String {
-            next = Tab(id: path, title: title, symbol: item["symbol"] as? String ?? "message",
+            next = Tab(id: path, title: title, symbol: item["symbol"] as? String ?? "bubble.left",
                 badge: (item["badge"] as? String).flatMap { $0.isEmpty ? nil : String($0.prefix(8)) },
                 accessibilityLabel: item["accessibilityLabel"] as? String,
-                iconOnly: item["iconOnly"] as? Bool ?? false,
+                iconOnly: (item["iconOnly"] as? Bool ?? false) || ["vertical", "horizontal"].contains(item["layout"] as? String ?? ""),
+                accessoryLayout: (item["layout"] as? String).flatMap { ["vertical", "horizontal"].contains($0) ? $0 : nil },
                 companions: ((item["companions"] as? [[String: Any]]) ?? []).prefix(2).compactMap { action in
                     guard let companionPath = action["path"] as? String,
                           companionPath.hasPrefix("/"), !companionPath.hasPrefix("//"), companionPath != path,

package/dist/ios/templates/CraftHybrid.swift

@@ -1241,9 +1241,14 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
     private var synchronizingTabs = false
     private var accessoryModel: CraftChrome.Tab?
     private let accessoryButton = UIButton(type: .system)
+    // UIKit retains its shelf's content view across removal animations. Never
+    // reparent that same button into floating chrome: the shelf can take it
+    // back after our layout, leaving a perfectly sized but empty capsule.
+    private let shelfAccessoryButton = UIButton(type: .system)
     private var companionButtons: [UIButton] = []
     private var companionModels: [CraftChrome.Tab] = []
     private var companionGlasses: [UIVisualEffectView] = []
+    private var accessorySeparators: [UIView] = []
     private let accessoryBadge = UILabel()
     private let accessoryGlass = UIVisualEffectView(effect: UIBlurEffect(style: .systemMaterial))
     private static let tabPictures = NSCache<NSURL, UIImage>()
@@ -1309,6 +1314,8 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
         CraftChromeFonts.apply(to: tabBar)
         accessoryButton.accessibilityIdentifier = "craft-tab-accessory"
         accessoryButton.addTarget(self, action: #selector(openTabAccessory), for: .touchUpInside)
+        shelfAccessoryButton.accessibilityIdentifier = "craft-tab-accessory"
+        shelfAccessoryButton.addTarget(self, action: #selector(openTabAccessory), for: .touchUpInside)
         chromeSubscription = CraftChrome.shared.objectWillChange.sink { [weak self] in
             guard let self, !self.chromeUpdatePending else { return }
             self.chromeUpdatePending = true
@@ -1474,6 +1481,7 @@ 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
@@ -1506,16 +1514,32 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
         for (index, action) in companionModels.enumerated() {
             companionButtons[index].accessibilityTraits = chrome.accessorySelected(action) ? [.button, .selected] : [.button]
         }
+        let grouped = model?.accessoryLayout != nil
+        for glass in companionGlasses { glass.isHidden = grouped }
+        for button in companionButtons { button.tintColor = grouped ? .label : nil }
+        accessoryButton.tintColor = grouped ? .label : nil
+        for separator in accessorySeparators { separator.removeFromSuperview() }
+        accessorySeparators = grouped ? companionButtons.map { _ in
+            let separator = UIView()
+            separator.backgroundColor = .separator
+            separator.isUserInteractionEnabled = false
+            separator.isAccessibilityElement = false
+            view.addSubview(separator)
+            return separator
+        } : []
         if let model {
             var configuration = UIButton.Configuration.plain()
             configuration.image = UIImage(systemName: model.symbol)
+            configuration.preferredSymbolConfigurationForImage = UIImage.SymbolConfiguration(pointSize: 22, weight: .regular)
             configuration.title = model.iconOnly ? nil : model.displayTitle
             configuration.subtitle = model.iconOnly ? nil : model.badge
             configuration.imagePadding = model.iconOnly ? 0 : 8
-            accessoryButton.configuration = configuration
-            accessoryButton.accessibilityLabel = model.accessibilityLabel ?? model.displayTitle
-            accessoryButton.accessibilityValue = model.badge
-            accessoryButton.accessibilityTraits = chrome.accessorySelected(model) ? [.button, .selected] : [.button]
+            for button in [accessoryButton, shelfAccessoryButton] {
+                button.configuration = configuration
+                button.accessibilityLabel = model.accessibilityLabel ?? model.displayTitle
+                button.accessibilityValue = model.badge
+                button.accessibilityTraits = chrome.accessorySelected(model) ? [.button, .selected] : [.button]
+            }
         }
 #if compiler(>=6.2)
         if #available(iOS 26.0, *), model?.iconOnly != true {
@@ -1525,7 +1549,7 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
                 accessoryButton.removeFromSuperview()
             }
             if (model == nil) != (bottomAccessory == nil) {
-                bottomAccessory = model.map { _ in UITabAccessory(contentView: accessoryButton) }
+                bottomAccessory = model.map { _ in UITabAccessory(contentView: shelfAccessoryButton) }
             }
             accessoryModel = model
             for nav in stacks.values { nav.additionalSafeAreaInsets.bottom = 0 }
@@ -1549,7 +1573,7 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
         accessoryButton.isHidden = model == nil
         accessoryGlass.isHidden = model == nil
         accessoryGlass.isUserInteractionEnabled = false
-        accessoryGlass.layer.cornerRadius = 24
+        accessoryGlass.layer.cornerRadius = grouped ? 26 : 24
         accessoryGlass.clipsToBounds = true
         accessoryButton.backgroundColor = .clear
         accessoryButton.layer.cornerRadius = 24
@@ -1563,6 +1587,15 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
         accessoryBadge.clipsToBounds = true
         accessoryBadge.isAccessibilityElement = false
         accessoryModel = model
+        // The shared material must stay behind every button, even after a
+        // companion-only update creates new controls or a shelf changes mode.
+        if accessoryGlass.superview === view {
+            view.bringSubviewToFront(accessoryGlass)
+            for button in companionButtons { view.bringSubviewToFront(button) }
+            view.bringSubviewToFront(accessoryButton)
+            for separator in accessorySeparators { view.bringSubviewToFront(separator) }
+            view.bringSubviewToFront(accessoryBadge)
+        }
         for nav in stacks.values { nav.additionalSafeAreaInsets.bottom = safeAreaForTabBar() }
         view.setNeedsLayout()
     }
@@ -1586,14 +1619,30 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
         let iconOnly = accessoryModel?.iconOnly == true
         let height: CGFloat = iconOnly ? 48 : 44
         let width: CGFloat = iconOnly ? 48 : max(0, view.bounds.width - 32)
-        let x = iconOnly ? view.bounds.maxX - view.safeAreaInsets.right - width - 20 : 16
+        let trailingX = view.effectiveUserInterfaceLayoutDirection == .rightToLeft
+            ? view.safeAreaInsets.left + 20 : view.bounds.maxX - view.safeAreaInsets.right - width - 20
+        let x = iconOnly ? trailingX : 16
         accessoryButton.frame = CGRect(x: x, y: tabBar.frame.minY - height - (iconOnly ? 8 : 0), width: width, height: height)
         accessoryGlass.frame = accessoryButton.frame
+        let layout = accessoryModel?.accessoryLayout
         for (index, button) in companionButtons.enumerated() {
-            // Array order reads left to right, ending at the primary action.
-            button.frame = accessoryButton.frame.offsetBy(dx: -CGFloat(companionButtons.count - index) * (width + 12), dy: 0)
+            let offset = CGFloat(companionButtons.count - index)
+            if layout == "vertical" {
+                button.frame = accessoryButton.frame.offsetBy(dx: 0, dy: -offset * height)
+            } else {
+                let direction: CGFloat = view.effectiveUserInterfaceLayoutDirection == .rightToLeft ? 1 : -1
+                button.frame = accessoryButton.frame.offsetBy(dx: direction * offset * (width + (layout == nil ? 12 : 0)), dy: 0)
+            }
             companionGlasses[index].frame = button.frame
+            if layout != nil {
+                accessoryGlass.frame = accessoryGlass.frame.union(button.frame)
+                let line = 1 / (view.window?.screen.scale ?? 2)
+                accessorySeparators[index].frame = layout == "vertical"
+                    ? CGRect(x: button.frame.minX + 12, y: button.frame.maxY - line / 2, width: width - 24, height: line)
+                    : CGRect(x: view.effectiveUserInterfaceLayoutDirection == .rightToLeft ? button.frame.minX : button.frame.maxX - line / 2, y: button.frame.minY + 12, width: line, height: height - 24)
+            }
         }
+        if layout != nil { accessoryGlass.frame = accessoryGlass.frame.insetBy(dx: -2, dy: -2) }
         let badgeWidth = max(18, accessoryBadge.intrinsicContentSize.width + 8)
         accessoryBadge.frame = CGRect(x: accessoryButton.frame.maxX - badgeWidth + 4, y: accessoryButton.frame.minY - 3, width: badgeWidth, height: 18)
         // A compact action floats over the page, not across its whole width.
@@ -2595,8 +2644,8 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
             // Craft's content swipe must not steal their drag/hold gestures.
             let point = gestureRecognizer.location(in: view)
             if !tabBar.isHidden, tabBar.frame.contains(point) { return false }
-            if !accessoryButton.isHidden, accessoryButton.window != nil,
-               accessoryButton.convert(accessoryButton.bounds, to: view).contains(point) { return false }
+            if [accessoryButton, shelfAccessoryButton].contains(where: { !$0.isHidden && $0.window != nil && $0.convert($0.bounds, to: view).contains(point) }) { return false }
+            if companionButtons.contains(where: { !$0.isHidden && $0.window != nil && $0.convert($0.bounds, to: view).contains(point) }) { return false }
             // A swipe may begin while the last one settles: it catches it.
             guard activeTabSwipeTarget == nil || tabSwipeSettling,
                   hybrid.tabIds.count > 1, let nav = visibleStack, let top = nav.topViewController else { return false }

package/dist/ios/templates/CraftNativeActions.swift

@@ -2007,8 +2007,9 @@ enum CraftSnapshots {
                 // after a failure finds the previous value, because `pending`
                 // was cleared above and the cache was only refilled on success.
                 // Posting only on success left a failed checkpoint on screen as
-                // though it had been kept; Android already restores it
-                // (`changed("snapshots", name, if (ok) json else previous, null)`).
+                // though it had been kept; Android restores it by sending what
+                // a read gives once the write settles
+                // (`changed("snapshots", name, current, null)`).
                 NotificationCenter.default.post(name: changed, object: nil, userInfo: ["name": name])
                 completion?(ok)
             }

package/dist/ios/templates/CraftNativeFiles.swift

@@ -126,12 +126,21 @@ enum CraftNativeFiles {
         return url
     }
 
-    /// A file name with no path in it.
+    /// A file name with no path in it that the disk will take. A long name
+    /// is cut to fit and keeps its extension, which is how a share sheet and
+    /// an upload know what the file is.
     static func safeName(_ name: String) -> String {
         let parts = name.components(separatedBy: CharacterSet(charactersIn: "/\\:\u{0}\r\n"))
         var cleaned = parts.joined(separator: "-").trimmingCharacters(in: .whitespacesAndNewlines)
         while cleaned.hasPrefix(".") { cleaned.removeFirst() }
-        return cleaned.isEmpty ? "file" : String(cleaned.prefix(120))
+        // 255 UTF-16 units is what the file system takes, and 120 characters
+        // of flags or family emoji is more than that.
+        guard cleaned.count > 120 || cleaned.utf16.count > 255 else { return cleaned.isEmpty ? "file" : cleaned }
+        let ending = (cleaned as NSString).pathExtension
+        let suffix = ending.isEmpty || ending.count > 15 ? "" : "." + ending
+        var stem = String(cleaned.dropLast(suffix.count).prefix(120 - suffix.count))
+        while (stem + suffix).utf16.count > 255, !stem.isEmpty { stem.removeLast() }
+        return stem + suffix
     }
 
     static func describe(_ url: URL, type: String, extra: [String: Any] = [:]) -> [String: Any] {
@@ -857,6 +866,30 @@ enum CraftNativeFiles {
         }
     }
 
+    /// Base64 as `atob` reads it, which is what the browser host runs and
+    /// what Android is held to: the alphabet, ASCII white space anywhere,
+    /// padding optional but right when it is there, and nothing else.
+    /// Foundation alone wants the padding present and lets a third `=` by.
+    static func decodeBase64(_ text: String) -> Data? {
+        var data = [UInt8]()
+        data.reserveCapacity(text.utf8.count + 2)
+        var padding = 0
+        for byte in text.utf8 {
+            switch byte {
+            case 0x20, 0x09, 0x0A, 0x0C, 0x0D: continue
+            case UInt8(ascii: "="): padding += 1
+            case _ where padding > 0: return nil
+            case UInt8(ascii: "A")...UInt8(ascii: "Z"), UInt8(ascii: "a")...UInt8(ascii: "z"),
+                 UInt8(ascii: "0")...UInt8(ascii: "9"), UInt8(ascii: "+"), UInt8(ascii: "/"):
+                data.append(byte)
+            default: return nil
+            }
+        }
+        guard padding <= 2, data.count % 4 != 1, padding == 0 || (data.count + padding) % 4 == 0 else { return nil }
+        data.append(contentsOf: repeatElement(UInt8(ascii: "="), count: (4 - data.count % 4) % 4))
+        return Data(base64Encoded: Data(data))
+    }
+
     /// What a screen made itself (a CSV export, a route it built) written as
     /// a file for the share sheet: `data` is text (`encoding: 'utf8'`, the
     /// default, so a CSV crosses the bridge once and no larger) or base64
@@ -874,7 +907,7 @@ enum CraftNativeFiles {
         case "utf8":
             bytes = Data(text.utf8)
         case "base64":
-            guard let decoded = Data(base64Encoded: text.filter { !$0.isWhitespace }) else {
+            guard let decoded = decodeBase64(text) else {
                 return .failure(CraftNativeActionError(code: "INVALID_ARGUMENT", message: "files.write was given base64 it could not read"))
             }
             bytes = decoded

package/dist/ios/templates/CraftNativeScreen.swift

@@ -9423,7 +9423,18 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         case ("Audio", "resume"):
             reply(.success(sounds.resume(id: id)))
         case ("Audio", "setVolume"):
-            reply(.success(sounds.setVolume(id: id, volume: number(1), fade: number(2, "fade") / 1000)))
+            // A missing or non-numeric volume used to arrive here as 0 — the
+            // `number` helper's fallback — which silenced the sound and
+            // answered true. Android refuses it and leaves the sound as it
+            // was (`!volume.isFinite() || !fade.isFinite() || fade < 0`), so a
+            // malformed call muted on one host and did nothing on the other.
+            let fade = number(2, "fade")
+            guard args.count > 1, let volume = craftNativeNumber(args[1])?.doubleValue,
+                  volume.isFinite, fade.isFinite, fade >= 0 else {
+                reply(.success(false))
+                return true
+            }
+            reply(.success(sounds.setVolume(id: id, volume: volume, fade: fade / 1000)))
         case ("Audio", "stop"):
             reply(.success(sounds.stop(id: id, fadeOut: number(1, "fadeOut") / 1000)))
         case ("Audio", "stopAll"):

package/dist/ios/templates/testing/DriverTests.swift.template

@@ -342,7 +342,19 @@ final class DriverTests: XCTestCase {
     }
 
     /// Deliver one gesture; the command's observation determines success.
-    func press(_ element: XCUIElement) {
+    ///
+    /// Waits for the target to come to rest first (`settledFrame`) and returns
+    /// the frame it settled on. Every tap command goes through here, so a
+    /// control touched straight after a flick cannot be hit while the scroll
+    /// view is still decelerating — whichever command did the tapping. #449
+    /// settled only the boolean `tapid` branch, which left `tap`, `tapif`,
+    /// `tapexact` and non-boolean `tapid` with the same exposure.
+    ///
+    /// Waiting before the one gesture is not a second gesture, and for a
+    /// control already at rest this costs one 0.1s read.
+    @discardableResult
+    func press(_ element: XCUIElement) -> CGRect {
+        let settled = settledFrame(element)
         // Resolve this before activation: a menu item can disappear as soon
         // as its gesture completes (for example Select All).
         let input = [.textField, .secureTextField, .textView, .searchField].contains(element.elementType)
@@ -352,6 +364,7 @@ final class DriverTests: XCTestCase {
         // A tap on a read-only text view need not open the keyboard. Only a
         // following type command observes whether this target took focus.
         lastTappedInput = input
+        return settled
     }
 
     /// `target`'s frame once it has stopped moving, or its last reading at
@@ -541,8 +554,9 @@ final class DriverTests: XCTestCase {
                 // renderer or hit-testing failure (HQ agreement job 7570).
                 let before = target.value as? String
                 let enabledBefore = target.isEnabled
-                let frameBefore = settledFrame(target)
-                press(target)
+                // press settles before it taps and hands back the frame it
+                // settled on, so this is one read rather than two.
+                let frameBefore = press(target)
                 let settle = Date().addingTimeInterval(1.5)
                 var flipped = false
                 repeat {

package/package.json

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