craft-native 0.0.424 → 0.0.435

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

@@ -478,7 +478,7 @@ internal class CraftNativeCapabilities(
         }
         "remove" -> {
             val file = ownedFile(args.optString(0)) ?: return failure("INVALID_ARGUMENT", "files.remove needs a file made by craft.files")
-            success(file.delete())
+            success(removeOwnedFile(file))
         }
         "download" -> download(requestToken, args)
             else -> failure("UNKNOWN_ACTION", "Unsupported Files method")
@@ -802,7 +802,7 @@ internal class CraftNativeCapabilities(
             success(copied)
         } catch (error: Exception) {
             for (index in 0 until copied.length()) {
-                copied.optJSONObject(index)?.optString("path")?.let { ownedFile(it)?.parentFile?.deleteRecursively() }
+                copied.optJSONObject(index)?.optString("path")?.let { ownedFile(it)?.let(::removeOwnedFile) }
             }
             val message = error.message ?: "The selected document could not be read"
             if (message.startsWith("CANCELLED:")) failure("CANCELLED", message.removePrefix("CANCELLED:").trim())
@@ -915,6 +915,18 @@ internal class CraftNativeCapabilities(
         return file.takeIf { it.path.startsWith(root.path + File.separator) }
     }
 
+    /** Delete only a validated owned file; never sweep siblings or the shared root. */
+    private fun removeOwnedFile(file: File): Boolean {
+        // File.delete is non-recursive and reports permission failures. Reject
+        // directories before removal; parent pruning must remain best effort.
+        if (!runCatching { file.isFile && file.delete() }.getOrDefault(false)) return false
+        runCatching {
+            val parent = file.parentFile
+            if (parent != null && parent != fileRoot.canonicalFile && parent.isDirectory) parent.delete()
+        }
+        return true
+    }
+
     private fun safeFileName(raw: String): String {
         val name = raw.substringAfterLast('/').substringAfterLast('\\').trim()
         return name.ifBlank { "file" }.replace(Regex("[\\\\/:*?\"<>|\\r\\n]"), "_")
@@ -939,7 +951,7 @@ internal class CraftNativeCapabilities(
         val files = if (data is JSONArray) (0 until data.length()).mapNotNull { data.optJSONObject(it) }
             else listOfNotNull(data as? JSONObject)
         files.forEach { file ->
-            ownedFile(file.optString("path"))?.parentFile?.deleteRecursively()
+            ownedFile(file.optString("path"))?.let(::removeOwnedFile)
         }
     }
 

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

@@ -57,13 +57,14 @@ internal class CraftNativeSounds(
         if (id.isBlank()) return done(failure("INVALID_ARGUMENT", "audio.play needs an id"))
         val uri = source(address)
             ?: return done(failure("INVALID_ARGUMENT", "audio.play needs an absolute http, https, file or content URL"))
-        stop(id, 0.0)
-
         val requestedVolume = options.optDouble("volume", 1.0)
         val volume = requestedVolume.takeIf { it.isFinite() }?.coerceIn(0.0, 1.0)?.toFloat()
             ?: return done(failure("INVALID_ARGUMENT", "audio.play volume must be a finite number between 0 and 1"))
         val fadeIn = options.optDouble("fadeIn", 0.0)
         if (!fadeIn.isFinite() || fadeIn < 0) return done(failure("INVALID_ARGUMENT", "audio.play fadeIn must be a non-negative finite number"))
+        // Reject malformed options before cancelling a sound with the same id.
+        // 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)
         sounds[id] = sound

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

@@ -9,6 +9,10 @@ import android.content.pm.PackageManager
 import android.content.res.ColorStateList
 import android.content.res.Configuration
 import android.content.res.Resources
+import android.hardware.Sensor
+import android.hardware.SensorEvent
+import android.hardware.SensorEventListener
+import android.hardware.SensorManager
 import android.database.ContentObserver
 import android.content.Intent
 import android.app.PictureInPictureParams
@@ -4683,6 +4687,7 @@ class MainActivity : AppCompatActivity() {
     private val capabilityHandler = Handler(Looper.getMainLooper())
     private var hapticsEnabled = false
     private var clipboardEnabled = false
+    private var shakeEnabled = false
     internal var nativeAppState = "inactive"
         private set
     private var deliveredInitialDeepLink = false
@@ -4755,6 +4760,7 @@ class MainActivity : AppCompatActivity() {
         }.getOrDefault(JSONObject())
         hapticsEnabled = config.optBoolean("enableHaptics", false)
         clipboardEnabled = config.optBoolean("enableClipboard", false)
+        shakeEnabled = config.optBoolean("enableShakeGesture", false)
         // Normally started already by its content provider; this covers a
         // process that skipped providers (instrumentation).
         CraftCrashReporter.start(this)
@@ -6101,9 +6107,7 @@ class MainActivity : AppCompatActivity() {
                 val handler = craftNativeEventName(events, "onPress", "onClick")
                 if (handler.isNotBlank()) screen.handlers[this] = handler else screen.handlers.remove(this)
                 setOnClickListener {
-                    screen.linkTargets[it]?.let { target -> navigateOpen(target); return@setOnClickListener }
-                    val current = screen.handlers[this] ?: return@setOnClickListener
-                    send(screen, "EVENT", JSONObject().put("handlerName", current).put("nativeEvent", JSONObject()))
+                    dispatchNativePress(screen, it)
                 }
             }
             "Button" -> (previous as? Button ?: CraftNativePointerButton(this).apply {
@@ -6877,9 +6881,7 @@ class MainActivity : AppCompatActivity() {
                 control.isClickable = true
                 if (type in setOf("TouchableOpacity", "TouchableHighlight", "Pressable")) {
                     control.setOnClickListener {
-                        screen.linkTargets[it]?.let { target -> navigateOpen(target); return@setOnClickListener }
-                        val current = screen.handlers[it] ?: return@setOnClickListener
-                        send(screen, "EVENT", JSONObject().put("handlerName", current).put("nativeEvent", JSONObject()))
+                        dispatchNativePress(screen, it)
                     }
                     control.setOnTouchListener { view, event ->
                         if (!CraftNativePointers.ownsTouch(view) && event.actionMasked != MotionEvent.ACTION_CANCEL) return@setOnTouchListener false
@@ -6907,9 +6909,7 @@ class MainActivity : AppCompatActivity() {
                                     send(screen, "EVENT", JSONObject().put("handlerName", current).put("nativeEvent", JSONObject()))
                                 }
                                 if (event.actionMasked == android.view.MotionEvent.ACTION_UP) {
-                                    screen.linkTargets[view]?.let { target -> navigateOpen(target); return@setOnTouchListener true }
-                                    val current = screen.handlers[view] ?: return@setOnTouchListener true
-                                    send(screen, "EVENT", JSONObject().put("handlerName", current).put("nativeEvent", JSONObject()))
+                                    dispatchNativePress(screen, view)
                                 }
                                 true
                             }
@@ -6920,9 +6920,7 @@ class MainActivity : AppCompatActivity() {
                     control.setOnTouchListener(null)
                     if (screen.pressBaseBackgrounds.containsKey(control)) control.background = screen.pressBaseBackgrounds[control]
                     control.setOnClickListener {
-                        screen.linkTargets[control]?.let { target -> navigateOpen(target); return@setOnClickListener }
-                        val current = screen.handlers[control] ?: return@setOnClickListener
-                        send(screen, "EVENT", JSONObject().put("handlerName", current).put("nativeEvent", JSONObject()))
+                        dispatchNativePress(screen, control)
                     }
                 }
             } else {
@@ -8254,7 +8252,45 @@ class MainActivity : AppCompatActivity() {
         publish("APP_STATE", JSONObject().put("state", nativeAppState))
     }
 
+    // MARK: - Shake gesture (enableShakeGesture)
+
+    /// The accelerometer, watched for a shake while the app is in front, as on
+    /// iOS. Armed on resume and disarmed on pause, because the sensor is the
+    /// whole cost of this feature and nobody can shake a phone at an app they
+    /// cannot see.
+    private var lastShakeAt = 0L
+    private val shakeSensors by lazy { getSystemService(Context.SENSOR_SERVICE) as? SensorManager }
+    private val shakeListener = object : SensorEventListener {
+        override fun onAccuracyChanged(sensor: Sensor?, accuracy: Int) {}
+        override fun onSensorChanged(event: SensorEvent?) {
+            val reading = event?.values ?: return
+            if (reading.size < 3) return
+            // Android reports m/s^2 with gravity included, so a phone at rest
+            // reads about 9.81. Converted to g to match the iOS threshold and
+            // the force the event carries.
+            val magnitude = kotlin.math.sqrt((reading[0] * reading[0] + reading[1] * reading[1] + reading[2] * reading[2]).toDouble()) / SensorManager.GRAVITY_EARTH
+            if (magnitude < 2.2) return
+            val now = System.currentTimeMillis()
+            // One event per gesture, not one per sample.
+            if (now - lastShakeAt < 2000L) return
+            lastShakeAt = now
+            CraftNativeHub.broadcast("CRAFT_EVENT", JSONObject().put("event", "shake").put("detail", JSONObject().put("force", magnitude)))
+        }
+    }
+
+    private fun armShakeGesture() {
+        if (!shakeEnabled) return
+        val sensor = shakeSensors?.getDefaultSensor(Sensor.TYPE_ACCELEROMETER) ?: return
+        shakeSensors?.registerListener(shakeListener, sensor, SensorManager.SENSOR_DELAY_UI)
+    }
+
+    private fun disarmShakeGesture() {
+        if (!shakeEnabled) return
+        shakeSensors?.unregisterListener(shakeListener)
+    }
+
     override fun onPause() {
+        disarmShakeGesture()
         if (::services.isInitialized) services.pauseVoice()
         nativeAppState = "inactive"
         publish("APP_STATE", JSONObject().put("state", nativeAppState))
@@ -8314,6 +8350,7 @@ class MainActivity : AppCompatActivity() {
 
     override fun onResume() {
         super.onResume()
+        armShakeGesture()
         if (::services.isInitialized) services.resumed()
     }
 
@@ -8371,6 +8408,18 @@ class MainActivity : AppCompatActivity() {
         }
     }
 
+    // The authored handler owns navigation. The bridge is asynchronous, so
+    // opening the link as well cannot honor a handler's preventDefault intent.
+    private fun dispatchNativePress(screen: Screen, view: View) {
+        if (!view.isEnabled) return
+        val handler = screen.handlers[view]
+        if (handler != null) {
+            send(screen, "EVENT", JSONObject().put("handlerName", handler).put("nativeEvent", JSONObject()))
+        } else {
+            screen.linkTargets[view]?.let { target -> navigateOpen(target) }
+        }
+    }
+
     private fun send(screen: Screen, type: String, payload: JSONObject, correlationId: String? = null) {
         if (!screen.active) return
         val message = JSONObject().put("type", type).put("payload", payload)

package/dist/browser.js

@@ -317,7 +317,7 @@ async function createBrowserStorage(options) {
   };
   const accountChanged = async () => {
     const next = storage.getItem(tokenKey);
-    if (next === token) {
+    if (next === token && (!transitioning || transition)) {
       await transition;
       return;
     }
@@ -351,7 +351,14 @@ async function createBrowserStorage(options) {
       if (before !== next)
         options.sessionChanged?.(next, before);
     })();
-    await transition;
+    const attempt = transition;
+    try {
+      await attempt;
+    } catch (error) {
+      if (current === revision && transition === attempt)
+        transition = null;
+      throw error;
+    }
   };
   const secureKey = (name) => name === sessionTokenKey ? tokenKey : key(`credential:${name}`);
   return {

package/dist/cli.js

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

package/dist/index.cjs

@@ -375,7 +375,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.424";
+var version = "0.0.435";
 
 // 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.424";
+var version = "0.0.435";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;

package/dist/ios/src/index.d.ts

@@ -84,6 +84,8 @@ export interface CraftConfig {
     enableAudioRecording?: boolean;
     enableVideoRecording?: boolean;
     enableMotionSensors?: boolean;
+    /** Shaking the phone raises a `shake` event. Arms the accelerometer while the app is in front. */
+    enableShakeGesture?: boolean;
     enableLocalDatabase?: boolean;
     enableBluetooth?: boolean;
     enableNFC?: boolean;

package/dist/ios/src/index.js

@@ -18,7 +18,7 @@ function iosPermissions(config) {
     contacts: config.enableContacts,
     calendar: config.enableCalendar,
     bluetooth: config.enableBluetooth || config.enableHeartRate,
-    motion: config.enableMotionSensors,
+    motion: config.enableMotionSensors || config.enableShakeGesture,
     biometric: config.enableBiometric,
     music: config.enableAppleMusic,
     health: config.enableHealthKit,
@@ -701,6 +701,7 @@ var DEFAULT_CONFIG = {
   enableAudioRecording: false,
   enableVideoRecording: false,
   enableMotionSensors: false,
+  enableShakeGesture: false,
   enableLocalDatabase: false,
   enableBluetooth: false,
   enableNFC: false,

package/dist/ios/templates/CraftApp.swift

@@ -1830,6 +1830,11 @@ struct CraftConfig: Codable {
     var enableAudioRecording: Bool = false
     var enableVideoRecording: Bool = false
     var enableMotionSensors: Bool = false
+    /// Shaking the phone raises a `shake` event, for a report-a-problem
+    /// gesture. Its own flag rather than a corner of `enableMotionSensors`,
+    /// because it arms the accelerometer for as long as the app is in front:
+    /// an app that wanted only the motion API should not pay for that.
+    var enableShakeGesture: Bool = false
     var enableLocalDatabase: Bool = false
     var enableBluetooth: Bool = false
     var enableNFC: Bool = false
@@ -2413,6 +2418,10 @@ struct CraftWebView: UIViewRepresentable {
         private var motionManager: CMMotionManager?
         private var isMotionUpdating = false
 
+        // Shake gesture (enableShakeGesture), armed only while the app is in front
+        private var shakeMotion: CMMotionManager?
+        private var lastShakeAt: Date?
+
         // Bluetooth
         private var centralManager: CBCentralManager?
         private var peripheralManager: CBPeripheralManager?
@@ -2465,6 +2474,8 @@ struct CraftWebView: UIViewRepresentable {
             if config.enableMotionSensors {
                 motionManager = CMMotionManager()
             }
+            // The app starts in front, so the gesture starts armed.
+            armShakeGesture()
             #endif
             if config.enableHealthKit {
                 // Apple Health's heart rate as it arrives
@@ -3866,6 +3877,7 @@ struct CraftWebView: UIViewRepresentable {
         @objc private func appDidEnterBackground(_ notification: Notification) {
             backgroundedAt = Date()
             saveInteractionState()
+            disarmShakeGesture()
         }
 
         @objc private func appDidReceiveMemoryWarning(_ notification: Notification) {
@@ -3997,6 +4009,7 @@ struct CraftWebView: UIViewRepresentable {
         }
 
         @objc private func appWillEnterForeground(_ notification: Notification) {
+            armShakeGesture()
             if recoverOnForeground, let webView {
                 // The page is about to be rebuilt; there is no one to resume.
                 backgroundedAt = nil
@@ -8499,6 +8512,56 @@ struct CraftWebView: UIViewRepresentable {
             #endif
         }
 
+        // MARK: - Shake Gesture
+
+        /// The accelerometer, watched for a shake while the app is in front.
+        ///
+        /// Deliberately not `startDeviceMotionUpdates`: that fuses attitude and
+        /// gravity every sample, and a shake needs neither. Raw acceleration at
+        /// 20 Hz is enough to see one and costs a fraction of the same watch.
+        ///
+        /// Armed on foreground and disarmed on background, because the sensor
+        /// is the whole cost of this feature and nobody can shake a phone at an
+        /// app they cannot see.
+        private func armShakeGesture() {
+            #if CRAFT_PERMISSION_MOTION
+            guard config.enableShakeGesture, shakeMotion == nil else { return }
+            let manager = CMMotionManager()
+            guard manager.isAccelerometerAvailable else { return }
+            manager.accelerometerUpdateInterval = 1.0 / 20.0
+            shakeMotion = manager
+            manager.startAccelerometerUpdates(to: .main) { [weak self] sample, _ in
+                guard let self, let sample else { return }
+                self.readShake(sample.acceleration)
+            }
+            #endif
+        }
+
+        private func disarmShakeGesture() {
+            #if CRAFT_PERMISSION_MOTION
+            shakeMotion?.stopAccelerometerUpdates()
+            shakeMotion = nil
+            #endif
+        }
+
+        #if CRAFT_PERMISSION_MOTION
+        private func readShake(_ force: CMAcceleration) {
+            // Total force, gravity included, so a phone at rest reads 1g and
+            // the threshold is what a deliberate shake adds on top of it. At
+            // 2.2g a pocket, a footfall and setting the phone down are all
+            // below it, which is what a fitness app has to clear.
+            let magnitude = sqrt(force.x * force.x + force.y * force.y + force.z * force.z)
+            guard magnitude >= 2.2 else { return }
+            let now = Date()
+            // One event per gesture, not one per sample. A shake is a second
+            // or two of samples over the threshold, and every one of them
+            // would otherwise be reported as its own shake.
+            if let lastShakeAt, now.timeIntervalSince(lastShakeAt) < 2.0 { return }
+            lastShakeAt = now
+            sendToWeb("shake", data: ["force": magnitude])
+        }
+        #endif
+
         // MARK: - Motion Sensors
         private func startMotionUpdates(interval: Double, callbackId: String?) {
             #if CRAFT_PERMISSION_MOTION

package/dist/ios/templates/CraftNativeScreen.swift

@@ -2716,6 +2716,8 @@ enum CraftNativeFlexLayout {
                 ? label.sizeThatFits(CGSize(width: resolvedWidth, height: unbounded)).height
                 : maxContent.height)
             return CGSize(width: resolvedWidth, height: resolvedHeight)
+        case let image as CraftNativePositionedImageView where image.image == nil:
+            return CGSize(width: width ?? 0, height: height ?? 0)
         case let image as UIImageView where image.image == nil:
             return CGSize(width: width ?? 0, height: height ?? 0)
         default:
@@ -4165,25 +4167,37 @@ private extension UIImage {
 }
 
 /// Explicit CSS-facing image geometry; the loader and semantic view stay retained.
-class CraftNativePositionedImageView: UIImageView {
+class CraftNativePositionedImageView: UIView {
     private var storedImage: UIImage?
-    private var fittedImage: UIImageView?
+    private let fittedImage = UIImageView()
     private var fit: String?
     private var position = CGPoint(x: 0.5, y: 0.5)
 
-    override var image: UIImage? {
+    override init(frame: CGRect) {
+        super.init(frame: frame)
+        isUserInteractionEnabled = false
+        fittedImage.isUserInteractionEnabled = false
+        fittedImage.isAccessibilityElement = false
+        addSubview(fittedImage)
+    }
+
+    required init?(coder: NSCoder) { fatalError("init(coder:) has not been implemented") }
+
+    // Keep source identity separate from UIKit's image renderer. A UIImageView
+    // host with this stored-image getter painted an extra copy even with
+    // super.image set to nil; only the child owns image drawing now.
+    var image: UIImage? {
         get { storedImage }
         set {
             storedImage = newValue
-            super.image = fit == nil ? newValue : nil
-            fittedImage?.image = newValue
+            fittedImage.image = newValue
             invalidateIntrinsicContentSize()
             setNeedsLayout()
         }
     }
 
     override var intrinsicContentSize: CGSize {
-        fit == nil ? super.intrinsicContentSize : storedImage?.craftIntrinsicSize ?? CGSize(width: UIView.noIntrinsicMetric, height: UIView.noIntrinsicMetric)
+        fit == nil ? fittedImage.intrinsicContentSize : storedImage?.craftIntrinsicSize ?? CGSize(width: UIView.noIntrinsicMetric, height: UIView.noIntrinsicMetric)
     }
 
     func configureObjectGeometry(props: [String: Any], style: [String: Any]) {
@@ -4197,22 +4211,28 @@ class CraftNativePositionedImageView: UIImageView {
             let requested = rawFit as? String ?? "fill"
             fit = ["fill", "contain", "cover", "none", "scale-down"].contains(requested) ? requested : "fill"
             position = Self.objectPosition(rawPosition)
-            if fittedImage == nil {
-                let child = UIImageView()
-                child.isUserInteractionEnabled = false
-                child.isAccessibilityElement = false
-                child.contentMode = .scaleToFill
-                insertSubview(child, at: 0)
-                fittedImage = child
-            }
         } else { fit = nil }
-        fittedImage?.isHidden = fit == nil
-        super.image = fit == nil ? storedImage : nil
-        fittedImage?.image = storedImage
+        fittedImage.contentMode = fit == nil ? contentMode : .scaleToFill
         invalidateIntrinsicContentSize()
         setNeedsLayout()
     }
 
+    override var contentMode: UIView.ContentMode {
+        didSet {
+            fittedImage.contentMode = fit == nil ? contentMode : .scaleToFill
+            setNeedsLayout()
+        }
+    }
+
+    override func sizeThatFits(_ size: CGSize) -> CGSize {
+        fit == nil ? fittedImage.sizeThatFits(size) : intrinsicContentSize
+    }
+
+    override func tintColorDidChange() {
+        super.tintColorDidChange()
+        fittedImage.tintColor = tintColor
+    }
+
     var usesObjectGeometry: Bool { fit != nil }
     var objectCovers: Bool { fit == "cover" }
 
@@ -4234,7 +4254,8 @@ class CraftNativePositionedImageView: UIImageView {
 
     override func layoutSubviews() {
         super.layoutSubviews()
-        guard let fit, let child = fittedImage else { return }
+        let child = fittedImage
+        guard let fit else { child.frame = bounds; return }
         let source = storedImage?.craftIntrinsicSize ?? .zero
         guard source.width > 0, source.height > 0 else { child.frame = .zero; return }
         let contain = min(bounds.width / source.width, bounds.height / source.height)
@@ -9203,7 +9224,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         case "Icon":
             configureIcon(result as! UIImageView, props: props, style: style)
         case "Image":
-            let image = result as! UIImageView
+            let image = result as! CraftNativePositionedImageView
             let imageID = ObjectIdentifier(image)
             if let tint = color(style["tintColor"]) {
                 tintedImages.insert(imageID)
@@ -9215,7 +9236,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             if let current = image.image { image.image = imageForDisplay(current, view: image) }
             let requestedResizeMode = style["resizeMode"] as? String ?? props["resizeMode"] as? String
             image.contentMode = imageContentMode(requestedResizeMode)
-            (image as? CraftNativePositionedImageView)?.configureObjectGeometry(props: props, style: style)
+            image.configureObjectGeometry(props: props, style: style)
             applyImageClipping(image, contentMode: image.contentMode, style: style)
             updateAuxiliaryHandler(events["onLoadStart"], in: &imageLoadStartHandlers, for: image)
             updateAuxiliaryHandler(events["onLoad"], in: &imageLoadHandlers, for: image)
@@ -10347,7 +10368,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         view.clipsToBounds = overflow == "hidden"
             || (view is UIScrollView && overflow != "visible")
             || (view is UILabel && (view.craftRequestedCornerRadius ?? 0) > 0)
-            || (view is UIImageView && (borderRadius > 0 || hasCornerRadii))
+            || ((view is UIImageView || view is CraftNativePositionedImageView) && (borderRadius > 0 || hasCornerRadii))
             // Per-corner rounding clips its content, as its mask did.
             || hasCornerRadii
         view.layer.masksToBounds = view.clipsToBounds
@@ -10659,7 +10680,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     /// The pixels a picture is drawn at, when its style fixes its size (a
     /// 40-point avatar, a card's photo): nil otherwise, for a picture whose
     /// own size lays it out, which must keep its full size.
-    static func displayPixels(of view: UIImageView) -> (size: CGSize, scale: CGFloat)? {
+    static func displayPixels(of view: UIView) -> (size: CGSize, scale: CGFloat)? {
         let style = view.craftLayoutStyle
         let points: CGSize
         switch (style.width, style.height, style.aspectRatio) {
@@ -10742,16 +10763,16 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         return candidate
     }
 
-    private func applyImageClipping(_ view: UIImageView, contentMode: UIView.ContentMode, style: [String: Any]) {
+    private func applyImageClipping(_ view: CraftNativePositionedImageView, contentMode: UIView.ContentMode, style: [String: Any]) {
         let authored = (style["overflow"] as? String) == "hidden"
             || (view.craftRequestedCornerRadius ?? 0) > 0
             || view.craftRequestedCornerRadii != nil
-        let clips = authored || contentMode == .scaleAspectFill || (view as? CraftNativePositionedImageView)?.usesObjectGeometry == true
+        let clips = authored || contentMode == .scaleAspectFill || view.usesObjectGeometry
         view.clipsToBounds = clips
         view.layer.masksToBounds = clips
     }
 
-    private func updateImage(_ view: UIImageView, source: Any?, defaultSource: Any? = nil) {
+    private func updateImage(_ view: CraftNativePositionedImageView, source: Any?, defaultSource: Any? = nil) {
         let sourceObject = source as? [String: Any]
         let uri = (source as? String) ?? sourceObject?["uri"] as? String
         let headers = (sourceObject?["headers"] as? [String: Any])?.reduce(into: [String: String]()) { result, entry in
@@ -10793,7 +10814,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         if let url = imageURL(for: uri) {
             // Decoded at the size it is drawn, when the style fixes that size.
             let pixels = Self.displayPixels(of: view)
-            let fill = (view as? CraftNativePositionedImageView)?.objectCovers == true || view.contentMode == .scaleAspectFill
+            let fill = view.objectCovers || view.contentMode == .scaleAspectFill
             // media.keep owns private/offline copies keyed by the authored URL.
             // Read before the decoded/network cache, without retaining private
             // pixels there after the app clears its media on sign-out.
@@ -10884,7 +10905,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         return !uri.contains(":") ? UIImage(named: uri) : nil
     }
 
-    private func imageFailure(_ view: UIImageView, uri: String?, message: String) {
+    private func imageFailure(_ view: CraftNativePositionedImageView, uri: String?, message: String) {
         imageErrors[ObjectIdentifier(view)] = message
         view.image = nil
         imageDidChange(view)
@@ -10895,19 +10916,19 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         NSLog("[craft native] %@: %@", message, uri ?? "<missing>")
     }
 
-    private func imageDidChange(_ view: UIImageView) {
+    private func imageDidChange(_ view: CraftNativePositionedImageView) {
         view.invalidateIntrinsicContentSize()
         CraftNativeFlexLayout.invalidateAncestors(of: view)
     }
 
-    private func imageForDisplay(_ image: UIImage, view: UIImageView) -> UIImage {
+    private func imageForDisplay(_ image: UIImage, view: CraftNativePositionedImageView) -> UIImage {
         let displayed = image.withRenderingMode(tintedImages.contains(ObjectIdentifier(view)) ? .alwaysTemplate : .alwaysOriginal)
         displayed.craftIntrinsicSize = image.craftIntrinsicSize
         return displayed
     }
 
     private func emitImageEvent(
-        _ view: UIImageView,
+        _ view: CraftNativePositionedImageView,
         handler: String?,
         nativeEvent: [String: Any] = [:]
     ) {
@@ -10961,7 +10982,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         switch role ?? type.lowercased() {
         case "tablist": traits.insert(.tabBar)
         case "button", "checkbox": traits.insert(.button)
-        case "image": traits.insert(.image)
+        case "image", "imagebackground": traits.insert(.image)
         case "header": traits.insert(.header)
         case "link": traits.insert(.link)
         case "search": traits.insert(.searchField)
@@ -11023,11 +11044,13 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
 
     @objc private func buttonPressed(_ sender: UIButton) {
         let focused = firstResponder(in: rootStack) ?? lastFocusedInput
-        if let target = linkTargets[ObjectIdentifier(sender)] {
-        hybridEvents?.nativeScreen(self, open: target, props: [:])
+        let id = ObjectIdentifier(sender)
+        // An authored handler owns navigation; the asynchronous bridge cannot
+        // wait for preventDefault before opening the link.
+        guard let handler = handlers[id] else {
+            if let target = linkTargets[id] { hybridEvents?.nativeScreen(self, open: target, props: [:]) }
             return
         }
-        guard let handler = handlers[ObjectIdentifier(sender)] else { return }
         send(type: "EVENT", payload: ["handlerName": handler, "nativeEvent": [:]])
         restoreFocus(focused)
         DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) { [weak self, weak focused] in
@@ -11191,7 +11214,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
 
     @objc private func solidSwitchChanged(_ sender: CraftNativeSolidSwitch) {
         guard sender.isEnabled, let handler = handlers[ObjectIdentifier(sender)] else { return }
-        send(type: "EVENT", payload: ["handlerName": handler, "nativeEvent": ["value": sender.isOn]])
+        sendAfterThumb(handler: handler, value: sender.isOn)
     }
 
     @objc private func switchChanged(_ sender: UISwitch) {
@@ -11202,7 +11225,28 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             self.switchUserValues.removeValue(forKey: id)
         }
         guard let handler = handlers[id] else { return }
-        send(type: "EVENT", payload: ["handlerName": handler, "nativeEvent": ["value": sender.isOn]])
+        sendAfterThumb(handler: handler, value: sender.isOn)
+    }
+
+    /// A switch's value, told to the script after UIKit has been left to draw
+    /// the thumb.
+    ///
+    /// On the default main-thread script a handler runs inline, inside the
+    /// control's own action, so the touch's CATransaction stays open until the
+    /// script has finished its work and whatever render it causes. UIKit has
+    /// already set the new value by then, so the thumb does not travel: the
+    /// switch sits still for as long as the script takes and then appears in
+    /// its new state. Yielding the runloop turn first lets that transaction
+    /// commit, the animation is handed to the render server, and the script's
+    /// work no longer holds the thumb. A background script never blocks the
+    /// main thread, so it is told at once.
+    private func sendAfterThumb(handler: String, value: Bool) {
+        let payload: [String: Any] = ["handlerName": handler, "nativeEvent": ["value": value]]
+        guard !CraftNativeScriptThread.isBackground else {
+            send(type: "EVENT", payload: payload)
+            return
+        }
+        DispatchQueue.main.async { [weak self] in self?.send(type: "EVENT", payload: payload) }
     }
 
     @objc private func sliderChanged(_ sender: UISlider) {
@@ -11385,11 +11429,10 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     @objc private func viewPressed(_ sender: UITapGestureRecognizer) {
         guard let view = sender.view else { return }
         let id = ObjectIdentifier(view)
-        if let target = linkTargets[id] {
-        hybridEvents?.nativeScreen(self, open: target, props: [:])
+        guard let handler = handlers[id] else {
+            if let target = linkTargets[id] { hybridEvents?.nativeScreen(self, open: target, props: [:]) }
             return
         }
-        guard let handler = handlers[id] else { return }
         if pressInHandlers[id] == nil, pressOutHandlers[id] == nil,
            let pressable = view as? CraftNativeFlowView, let activeOpacity = pressable.pressActiveOpacity {
             UIView.animate(withDuration: 0.1, animations: { pressable.alpha = pressable.pressBaseOpacity * activeOpacity }) { _ in

package/dist/ios/templates/CraftVoiceRecording.swift

@@ -69,6 +69,7 @@ final class CraftVoiceRecording {
         var recorder: CraftVoiceRecorder? // audio queue only
         var completion: ((Result<Any, CraftNativeActionError>) -> Void)? // main only
         var deadline: DispatchWorkItem?
+        var stopping = false // main only
         private let lock = NSLock()
         private var cancelled = false
         init(key: String, completion: @escaping (Result<Any, CraftNativeActionError>) -> Void) {
@@ -86,15 +87,29 @@ final class CraftVoiceRecording {
         }
     }
     private var current: Session?
+    /// Each microphone step in the unified log (`subsystem == "craft.native"`,
+    /// category `voice-recording`), so a recording that never finished says
+    /// whether its stop arrived, and where AVFoundation held it.
+    private static func trace(_ message: String) {
+        CraftNativeConsole.write("info", category: "voice-recording", message: message)
+    }
     private let audioQueue: DispatchQueue
     private let permission: (@escaping (Bool) -> Void) -> Void
     private let makeRecorder: (URL) throws -> CraftVoiceRecorder
     private let deactivate: () -> Void
+    /// Releasing the audio session runs here, never on `audioQueue`: a
+    /// deactivation that stalls (seen on simulators with a virtual input)
+    /// must not hold the next recording's start or stop behind it.
+    private let releaseQueue = DispatchQueue(label: "craft.voice-recording-release", qos: .utility)
+    private let generationLock = NSLock()
+    private var generation = 0
     private let startupTimeout: TimeInterval
+    private let stopTimeout: TimeInterval
     private var backgroundObserver: NSObjectProtocol?
 
     init(audioQueue: DispatchQueue = DispatchQueue(label: "craft.voice-recording", qos: .userInitiated),
          startupTimeout: TimeInterval = 15,
+         stopTimeout: TimeInterval = 10,
          permission: @escaping (@escaping (Bool) -> Void) -> Void = { answer in
              #if CRAFT_PERMISSION_MICROPHONE
              AVAudioSession.sharedInstance().requestRecordPermission(answer)
@@ -116,6 +131,7 @@ final class CraftVoiceRecording {
         Self.prepareForLaunch()
         self.audioQueue = audioQueue
         self.startupTimeout = startupTimeout
+        self.stopTimeout = stopTimeout
         self.permission = permission
         self.makeRecorder = makeRecorder
         self.deactivate = deactivate
@@ -128,7 +144,17 @@ final class CraftVoiceRecording {
         session.recorder?.stop()
         session.recorder = nil
         if let file = session.file { CraftNativeFiles.remove(file.path) }
-        deactivate()
+        releaseAudioSession()
+    }
+
+    /// Deactivate off the recording queue, and not at all once a newer
+    /// recording has started: it would only take the microphone from it.
+    private func releaseAudioSession() {
+        let mine = generationLock.withLock { generation }
+        releaseQueue.async { [weak self] in
+            guard let self, self.generationLock.withLock({ self.generation }) == mine else { return }
+            self.deactivate()
+        }
     }
 
     private func clear(_ error: CraftNativeActionError = CraftNativeActionError(code: "RECORDING_CANCELLED", message: "Recording was cancelled")) {
@@ -150,6 +176,7 @@ final class CraftVoiceRecording {
     private func performOnMain(method: String, args: [Any], isActive: @escaping () -> Bool, completion: @escaping (Result<Any, CraftNativeActionError>) -> Void) {
         func fail(_ code: String, _ message: String) { completion(.failure(CraftNativeActionError(code: code, message: message))) }
         guard let key = args.first as? String, UUID(uuidString: key) != nil else { fail("INVALID_ARGUMENT", "A recording owner UUID is required"); return }
+        Self.trace("\(method) \(key.prefix(8)) (current \(current.map { String($0.key.prefix(8)) } ?? "none"))")
         if method == "cancel" {
             if current?.key == key { clear() }
             completion(.success(true))
@@ -157,11 +184,36 @@ final class CraftVoiceRecording {
         }
         if method == "stop" {
             guard let session = current, session.key == key, let file = session.file else { fail("RECORDING_NOT_FOUND", "This recording is no longer available"); return }
+            guard !session.stopping else { fail("RECORDING_BUSY", "This recording is already finishing"); return }
+            session.stopping = true
+            // Answered exactly once: by the encoder's result, or by the
+            // deadline when AVFoundation never returns (a stalled encoder or
+            // audio route), which then erases the recording like a cancel.
+            var settled = false
+            var timeout: DispatchWorkItem?
+            func settle(_ result: Result<Any, CraftNativeActionError>) {
+                timeout?.cancel()
+                guard !settled else { return }
+                settled = true
+                completion(result)
+            }
+            let late = CraftNativeActionError(code: "RECORDING_TIMEOUT", message: "The recording took too long to finish. Please try again.")
+            timeout = DispatchWorkItem { [weak self] in
+                guard !settled else { return }
+                Self.trace("stop \(key.prefix(8)) timed out waiting for the encoder")
+                if let self, self.current === session { self.clear(late) }
+                settle(.failure(late))
+            }
+            DispatchQueue.main.asyncAfter(deadline: .now() + stopTimeout, execute: timeout!)
             audioQueue.async {
-                guard !session.isCancelled else { return DispatchQueue.main.async { fail("RECORDING_CANCELLED", "Recording was cancelled") } }
+                guard !session.isCancelled else {
+                    return DispatchQueue.main.async { settle(.failure(CraftNativeActionError(code: "RECORDING_CANCELLED", message: "Recording was cancelled"))) }
+                }
                 session.recorder?.stop()
                 session.recorder = nil
-                self.deactivate()
+                Self.trace("stop \(key.prefix(8)): encoder stopped")
+                // Read the finished file before releasing the audio session:
+                // the answer must not wait on a deactivation that can stall.
                 let result: Result<Any, CraftNativeActionError>
                 if let audio = try? AVAudioFile(forReading: file), audio.length > 0 {
                     let duration = Double(audio.length) / audio.processingFormat.sampleRate
@@ -170,14 +222,17 @@ final class CraftVoiceRecording {
                     result = .failure(CraftNativeActionError(code: "EMPTY_RECORDING", message: "The recording was empty"))
                 }
                 DispatchQueue.main.async {
+                    guard !settled else { return }
                     guard self.current === session, isActive(), !session.isCancelled else {
                         if self.current === session { self.clear() }
-                        fail("RECORDING_CANCELLED", "Recording was cancelled")
+                        settle(.failure(CraftNativeActionError(code: "RECORDING_CANCELLED", message: "Recording was cancelled")))
                         return
                     }
                     if case .failure = result { self.clear() }
-                    completion(result)
+                    Self.trace("stop \(key.prefix(8)) answered")
+                    settle(result)
                 }
+                self.releaseAudioSession()
             }
             return
         }
@@ -209,6 +264,7 @@ final class CraftVoiceRecording {
                 self.audioQueue.async {
                     do {
                         guard !session.isCancelled else { return }
+                        self.generationLock.withLock { self.generation += 1 }
                         session.recorder = try self.makeRecorder(file)
                         guard !session.isCancelled else { self.erase(session); return }
                         guard session.recorder?.record(forDuration: max(0.5, seconds - 0.25)) == true else {
@@ -220,6 +276,7 @@ final class CraftVoiceRecording {
                                 if self.current === session { self.clear() }
                                 return
                             }
+                            Self.trace("start \(key.prefix(8)): recording")
                             session.finish(.success(true))
                         }
                     }

package/dist/ios/templates/testing/CraftTimedInput.m

@@ -1,6 +1,8 @@
 #import "CraftTimedInput.h"
 #import <UIKit/UIKit.h>
 #import <math.h>
+#import <dlfcn.h>
+#import <XCTest/XCTest.h>
 
 // XCTest's own touch-record API is private. Look up classes and check every
 // selector at runtime; unsupported Xcode versions fail rather than skipping or
@@ -12,6 +14,16 @@
 - (id)initWithName:(NSString *)name interfaceOrientation:(NSInteger)orientation;
 - (void)addPointerEventPath:(id)path;
 - (BOOL)synthesizeWithError:(NSError **)error;
++ (id)eventStreamWithEventActions:(void (^)(id))actions;
+- (void)advanceTime:(double)seconds;
+- (void)touchDown:(CGPoint)point;
+- (void)liftUp:(CGPoint)point;
+- (id)underlyingPlayer;
+- (BOOL)prewarmForEventStream:(id)stream withError:(NSError **)error;
+- (void)setNeedsInitialDelay:(BOOL)value;
+- (void)setIgnoresCompletionDelay:(BOOL)value;
+- (void)playEventStream:(id)stream options:(id)options completion:(void (^)(void))completion;
+- (void)tearDown;
 @end
 
 @implementation CraftTimedInput
@@ -21,6 +33,68 @@
     return NO;
 }
 
+// The simulator's XCTest touch-path translator omits idle intervals between
+// fingers and rounds stationary moves to its sample interval. Submit stationary,
+// non-overlapping taps as one native HID stream with explicit clock advances.
+// Moving/overlapping paths retain the existing XCTest gesture implementation.
++ (BOOL)synthesizeStationaryPaths:(NSArray *)paths frame:(CGRect)frame error:(NSError **)error {
+    static dispatch_once_t once;
+    static void *recap;
+    dispatch_once(&once, ^{
+        recap = dlopen("/System/Library/PrivateFrameworks/Recap.framework/Recap", RTLD_NOW | RTLD_LOCAL);
+    });
+    Class streamClass = NSClassFromString(@"RCPSyntheticEventStream");
+    Class playerClass = NSClassFromString(@"RCPInlinePlayer");
+    if (!recap || ![streamClass respondsToSelector:@selector(eventStreamWithEventActions:)])
+        return [self fail:@"Native timed tap streams are unavailable on this runtime" error:error];
+    for (NSString *name in @[@"advanceTime:", @"touchDown:", @"liftUp:"])
+        if (![streamClass instancesRespondToSelector:NSSelectorFromString(name)])
+            return [self fail:@"Native timed tap stream cannot preserve the schedule" error:error];
+    for (NSString *name in @[@"underlyingPlayer", @"setNeedsInitialDelay:", @"setIgnoresCompletionDelay:",
+                             @"playEventStream:options:completion:", @"tearDown"])
+        if (![playerClass instancesRespondToSelector:NSSelectorFromString(name)])
+            return [self fail:@"Native timed tap playback is unavailable" error:error];
+
+    id stream = [streamClass eventStreamWithEventActions:^(id builder) {
+        double previous = 0;
+        for (NSArray *points in paths) {
+            NSDictionary *first = points.firstObject, *last = points.lastObject;
+            double start = [first[@"at"] doubleValue], end = [last[@"at"] doubleValue];
+            CGPoint point = CGPointMake(frame.origin.x + [first[@"x"] doubleValue] * frame.size.width,
+                                         frame.origin.y + [first[@"y"] doubleValue] * frame.size.height);
+            [builder advanceTime:start - previous];
+            [builder touchDown:point];
+            [builder advanceTime:end - start];
+            [builder liftUp:point];
+            previous = end;
+        }
+    }];
+    if (!stream) return [self fail:@"Native timed tap stream could not be constructed" error:error];
+    id player = [playerClass new];
+    id underlying = [player underlyingPlayer];
+    if (![underlying respondsToSelector:@selector(prewarmForEventStream:withError:)]) {
+        [player tearDown];
+        return [self fail:@"Native timed tap delivery cannot be prepared" error:error];
+    }
+    // Preparing the HID delivery service emits no touches. Do not add a warm-up
+    // touch or an initial/completion sleep to make the receiver appear reliable.
+    if (![underlying prewarmForEventStream:stream withError:error]) {
+        [player tearDown];
+        return NO;
+    }
+    [player setNeedsInitialDelay:NO];
+    [player setIgnoresCompletionDelay:YES];
+    XCTestExpectation *done = [[XCTestExpectation alloc] initWithDescription:@"Native timed tap completion"];
+    [player playEventStream:stream options:nil completion:^{
+        [player tearDown];
+        [done fulfill];
+    }];
+    // Validated streams end within 12s. A timeout is a failure, never a retry.
+    if ([XCTWaiter waitForExpectations:@[done] timeout:20] != XCTWaiterResultCompleted)
+        return [self fail:@"Native timed tap playback did not complete" error:error];
+    return YES;
+}
+
 + (BOOL)synthesizePaths:(NSArray *)paths frame:(CGRect)frame error:(NSError **)error {
     if (![paths isKindOfClass:NSArray.class] || paths.count == 0 || paths.count > 64
         || CGRectIsEmpty(frame) || !isfinite(frame.size.width) || !isfinite(frame.size.height))
@@ -43,6 +117,21 @@
             previous = at;
         }
     }
+    NSArray *ordered = [paths sortedArrayUsingComparator:^NSComparisonResult(NSArray *left, NSArray *right) {
+        return [left.firstObject[@"at"] compare:right.firstObject[@"at"]];
+    }];
+    BOOL stationary = [ordered.firstObject[0][@"at"] doubleValue] == 0;
+    double previousEnd = 0;
+    for (NSArray *points in ordered) {
+        NSDictionary *first = points.firstObject;
+        if ([first[@"at"] doubleValue] < previousEnd) stationary = NO;
+        for (NSDictionary *point in points)
+            if ([point[@"x"] doubleValue] != [first[@"x"] doubleValue]
+                || [point[@"y"] doubleValue] != [first[@"y"] doubleValue]) stationary = NO;
+        previousEnd = [points.lastObject[@"at"] doubleValue];
+    }
+    if (stationary) return [self synthesizeStationaryPaths:ordered frame:frame error:error];
+
     Class recordClass = NSClassFromString(@"XCSynthesizedEventRecord");
     Class pathClass = NSClassFromString(@"XCPointerEventPath");
     for (NSString *name in @[@"initWithName:interfaceOrientation:", @"addPointerEventPath:", @"synthesizeWithError:"])
@@ -68,7 +157,7 @@
         [path liftUpAtOffset:[points.lastObject[@"at"] doubleValue]];
         [record addPointerEventPath:path];
     }
-    // One dispatch retains the native offsets between different fingers/taps.
+    // One dispatch preserves the existing moving/overlapping gesture path.
     // Individual XCUICoordinate.tap() calls would wait for app quiescence.
     return [record synthesizeWithError:error];
 }

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

@@ -42,7 +42,7 @@ import Darwin
 ///   tabbar shown|hidden   the native tab bar (Today, Calendar, …) can be tapped, or not
 ///   selected <tab>        the tab bar's selected button is this one
 ///   tab <name>            tap a tab bar button
-///   scrollto <text>       swipes up (at most 8 times) until text is hittable
+///   scrollto <text>       at most 12 drags until the target is hittable and visible
 ///   swipe up|down|left|right
 ///   drag x1 y1 x2 y2     slow app-relative drag, held 0.3s before release
 ///   audit <name>          accessibility audit (element descriptions, Dynamic Type, contrast); logs each issue
@@ -143,13 +143,29 @@ final class DriverTests: XCTestCase {
         return any.exists ? any : nil
     }
 
+    /// Where a label is looked for, in order: the topmost presented alert,
+    /// then the topmost sheet, then the whole app. A sheet's "Sign out" and
+    /// the row that opened it share a label, and the row behind the sheet
+    /// is still reported hittable, so the presented one has to win.
+    func searchScopes<Scope>(alerts: [Scope], sheets: [Scope], app: Scope) -> [Scope] {
+        [alerts.last, sheets.last].compactMap { $0 } + [app]
+    }
+
+    func presentedScopes() -> [XCUIElement] {
+        let alerts = app.alerts.allElementsBoundByIndex.filter { $0.exists }
+        let sheets = app.sheets.allElementsBoundByIndex.filter { $0.exists }
+        return searchScopes(alerts: alerts, sheets: sheets, app: app as XCUIElement)
+    }
+
     func exact(_ label: String) -> XCUIElement? {
         let predicate = NSPredicate(format: "label == %@", label)
-        for query in [app.buttons, app.links, app.staticTexts] {
-            let matches = query.matching(predicate)
-            for index in 0..<min(matches.count, 25) {
-                let candidate = matches.element(boundBy: index)
-                if candidate.exists && candidate.isHittable { return candidate }
+        for scope in presentedScopes() {
+            for query in [scope.buttons, scope.links, scope.staticTexts] {
+                let matches = query.matching(predicate)
+                for index in 0..<min(matches.count, 25) {
+                    let candidate = matches.element(boundBy: index)
+                    if candidate.exists && candidate.isHittable { return candidate }
+                }
             }
         }
         return nil
@@ -164,6 +180,27 @@ final class DriverTests: XCTestCase {
         return nil
     }
 
+    /// A short target fits entirely; an oversized target fills the viewport.
+    func visibleScrollFrame(_ target: CGRect, in viewport: CGRect) -> Bool {
+        let visible = target.intersection(viewport)
+        return !target.isEmpty && !viewport.isEmpty && !visible.isNull
+            && visible.width >= min(target.width, viewport.width)
+            && visible.height >= min(target.height, viewport.height)
+    }
+
+    func scrollTargetVisible(_ target: XCUIElement?) -> Bool {
+        guard let target, target.exists, target.isHittable,
+              visibleScrollFrame(target.frame, in: app.frame) else { return false }
+        // Hittable alone accepts controls clipped by the scroll view's edge.
+        // Only an ancestor scroll view clips this target, not its siblings.
+        let identity = NSPredicate(format: "identifier == %@ AND label == %@", target.identifier, target.label)
+        for scroll in app.scrollViews.allElementsBoundByIndex {
+            if scroll.descendants(matching: .any).matching(identity).firstMatch.exists,
+               !visibleScrollFrame(target.frame, in: scroll.frame.intersection(app.frame)) { return false }
+        }
+        return true
+    }
+
     /// About a third of a screen of scrolling, as a held drag.
     ///
     /// `app.swipeUp()` is a flick, and how far a flick throws a scroll view
@@ -590,13 +627,13 @@ final class DriverTests: XCTestCase {
         case "scrollto":
             var found = element(containing: arg)
             var drags = 0
-            while (found == nil || !(found!.isHittable)) && drags < 12 {
+            while !scrollTargetVisible(found) && drags < 12 {
                 let towardTop = found.map { !$0.frame.isEmpty && $0.frame.midY < app.frame.midY } ?? false
                 scrollPage(towardTop: towardTop)
                 drags += 1
                 found = element(containing: arg)
             }
-            check(found != nil && found!.isHittable, "scrollto \(arg)")
+            check(scrollTargetVisible(found), "scrollto \(arg)")
         case "swipe":
             switch arg {
             case "up": app.swipeUp()
@@ -644,7 +681,9 @@ final class DriverTests: XCTestCase {
             // A system prompt over the app ("Save Password?" → Not Now), wherever iOS shows it.
             let label = arg.isEmpty ? "Not Now" : arg
             let springboard = XCUIApplication(bundleIdentifier: "com.apple.springboard")
-            let candidates = [app.buttons[label], springboard.buttons[label]]
+            // The app's own alert or sheet first (its button can share a
+            // label with the control behind it), then the app, then iOS.
+            let candidates = { self.presentedScopes().map { $0.buttons[label] } + [springboard.buttons[label]] }
             let end = Date().addingTimeInterval(6)
             // A tap is not a dismissal. iOS 26 draws "Save Password?" as a
             // sheet that is in the tree, and hittable, while it still slides
@@ -655,7 +694,7 @@ final class DriverTests: XCTestCase {
             var tapped = false
             var gone = false
             while !gone && Date() < end {
-                guard let button = candidates.first(where: { $0.exists && $0.isHittable }) else {
+                guard let button = candidates().first(where: { $0.exists && $0.isHittable }) else {
                     if tapped { gone = true } else { Thread.sleep(forTimeInterval: 0.5) }
                     continue
                 }

package/dist/macos/src/index.js

@@ -43,9 +43,9 @@ import process from "process";
 var macosToolchain = {
   zig: "0.18.0-dev.252+86dc5ce25",
   sources: {
-    "zig-js": { repository: "zig-utils/zig-js", revision: "a6739721273ae0f13d36fb3422052a588c5079a8", paths: ["src", "include", "tests", "tools", "docs", "bench", "conformance"] },
+    "zig-js": { repository: "zig-utils/zig-js", revision: "59497a090677aeb317e52ac55329e6a680457727", paths: ["src", "include", "tests", "tools", "docs", "bench", "conformance"] },
     "zig-regex": { repository: "zig-utils/zig-regex", revision: "fdd9c2e333ea6ac2fd06d080d939ef7f11d61b1b", paths: ["src"] },
-    "zig-gc": { repository: "zig-utils/zig-gc", revision: "0285ef801dd221a4ae8e88b31a09ae31627657a3", paths: ["src"] }
+    "zig-gc": { repository: "zig-utils/zig-gc", revision: "73c802e05768a729614e9c4296abb118aa06faf9", paths: ["src"] }
   }
 };
 var defaultRun = async (args, cwd) => {

package/dist/macos/src/toolchain.d.ts

@@ -9,7 +9,7 @@ export declare const macosToolchain: {
     readonly sources: {
         readonly 'zig-js': {
             readonly repository: 'zig-utils/zig-js';
-            readonly revision: 'a6739721273ae0f13d36fb3422052a588c5079a8';
+            readonly revision: '59497a090677aeb317e52ac55329e6a680457727';
             readonly paths: readonly ['src', 'include', 'tests', 'tools', 'docs', 'bench', 'conformance'];
         };
         readonly 'zig-regex': {
@@ -19,7 +19,7 @@ export declare const macosToolchain: {
         };
         readonly 'zig-gc': {
             readonly repository: 'zig-utils/zig-gc';
-            readonly revision: '0285ef801dd221a4ae8e88b31a09ae31627657a3';
+            readonly revision: '73c802e05768a729614e9c4296abb118aa06faf9';
             readonly paths: readonly ['src'];
         };
     };

package/dist/macos/templates/CraftMacApplication.swift

@@ -21,6 +21,8 @@ final class CraftMacScene: NSObject, NSWindowDelegate {
     let trafficLights: CGPoint?
     /// The screen has work to finish before the app quits (`craft.desktop.onQuit`).
     var holdsQuit = false
+    /// The content width the screen last heard, so a resize that changes nothing sends nothing.
+    var reportedViewportWidth: CGFloat = -1
     init(name: String, route: String, options: [String: Any], application: CraftMacApplication) {
         self.name = name
         runtime = CraftMacRuntime(route: route, params: options["params"] as? [String: Any] ?? [:], network: application.network)
@@ -49,9 +51,22 @@ final class CraftMacScene: NSObject, NSWindowDelegate {
         if name == "main" && application.testDirectory == nil { window.setFrameAutosaveName("\(application.appName)NativeMain") }
         window.makeKeyAndOrderFront(nil)
         placeTrafficLights()
+        // The screen starts knowing its width, so `md:`/`lg:` classes and `matchMedia` are right on the first frame.
+        let size = window.contentLayoutRect.size
+        reportedViewportWidth = size.width
+        runtime.context.evaluateScript("__stxNativeBridge.viewportWidth = \(Double(size.width)); __stxNativeBridge.viewportHeight = \(Double(size.height));")
         runtime.load(application.bundle)
     }
 
+    /// Tells the screen its new width (VIEWPORT, as a phone does on rotation): only when the width changed,
+    /// since a live resize lays out every frame.
+    func reportViewport() {
+        let size = window.contentLayoutRect.size
+        guard size.width > 0, abs(size.width - reportedViewportWidth) >= 0.5 else { return }
+        reportedViewportWidth = size.width
+        runtime.send("VIEWPORT", ["width": Double(size.width), "height": Double(size.height)])
+    }
+
     /// AppKit lays the title bar out again on resize, full screen and appearance changes, so this runs after each.
     func placeTrafficLights() {
         guard let inset = trafficLights, let close = window.standardWindowButton(.closeButton), let titlebar = close.superview?.superview else { return }
@@ -64,8 +79,8 @@ final class CraftMacScene: NSObject, NSWindowDelegate {
             window.standardWindowButton(type)?.setFrameOrigin(CGPoint(x: inset.x + CGFloat(index) * (size.width + 6), y: (height - size.height) / 2))
         }
     }
-    func windowDidResize(_ notification: Notification) { placeTrafficLights() }
-    func windowDidExitFullScreen(_ notification: Notification) { placeTrafficLights() }
+    func windowDidResize(_ notification: Notification) { placeTrafficLights(); reportViewport() }
+    func windowDidExitFullScreen(_ notification: Notification) { placeTrafficLights(); reportViewport() }
     func windowShouldClose(_ sender: NSWindow) -> Bool {
         if name == "main" { sender.orderOut(nil); return false }
         return true
@@ -213,6 +228,9 @@ final class CraftMacApplication: NSObject, NSApplicationDelegate, UNUserNotifica
         defer { CATransaction.commit() }
         let scheme = CraftMacColor.isDark ? "dark" : "light"
         for scene in scenes.values {
+            // AppKit lays the title bar out again for the new appearance, after this returns.
+            scene.placeTrafficLights()
+            DispatchQueue.main.async { [weak scene] in scene?.placeTrafficLights() }
             scene.runtime.context.evaluateScript("__stxNativeBridge.colorScheme = '\(scheme)';")
             // The protocol's own message: the screen restyles its `dark:` classes and tells `craft.appearance.onChange`.
             scene.runtime.send("APPEARANCE", ["colorScheme": scheme])
@@ -455,7 +473,7 @@ final class CraftMacApplication: NSObject, NSApplicationDelegate, UNUserNotifica
                   let box = scene.renderer.boxes.values.first(where: { ($0.props["testID"] as? String ?? $0.props["testId"] as? String ?? $0.id) == target }) else { return ["ok": false, "error": "No control \(action["target"] ?? "")"] }
             let text = action["text"] as? String ?? ""
             switch kind {
-            case "press": if let button = box.control as? NSButton { button.performClick(nil) } else { box.fire("onPress") }
+            case "press": if let button = box.control as? NSButton { button.performClick(nil) } else if let toggle = box.control as? NSSwitch { toggle.performClick(nil) } else { box.fire("onPress") }
             case "type":
                 if let field = box.control as? NSTextField { field.stringValue = text }
                 else if let view = (box.control as? NSScrollView)?.documentView as? NSTextView { view.string = text }
@@ -500,7 +518,7 @@ final class CraftMacApplication: NSObject, NSApplicationDelegate, UNUserNotifica
             let editor = (target as? NSTextField)?.currentEditor() as? NSTextView ?? target as? NSTextView
             guard let editor else { return ["ok": false, "error": "Not a text input"] }
             editor.doCommand(by: command)
-        case "click": if let button = box.control as? NSButton { button.performClick(nil) } else { box.pressed() }
+        case "click": if let button = box.control as? NSButton { button.performClick(nil) } else if let toggle = box.control as? NSSwitch { toggle.performClick(nil) } else { box.pressed() }
         case "fill":
             let value = action["value"] as? String ?? ""
             if let field = box.control as? NSTextField { field.stringValue = value; box.input(value) }
@@ -536,7 +554,7 @@ final class CraftMacApplication: NSObject, NSApplicationDelegate, UNUserNotifica
                 return node
             }
             func classes(_ view: NSView) -> [String] { [String(describing: type(of: view))] + view.subviews.flatMap(classes) }
-            return ["name": scene.name, "title": scene.window.title, "route": scene.runtime.route, "contextClass": String(describing: type(of: scene.runtime.context)), "nodes": nodes, "viewClasses": classes(scene.renderer.root), "errors": scene.runtime.errors]
+            return ["name": scene.name, "title": scene.window.title, "route": scene.runtime.route, "contextClass": String(describing: type(of: scene.runtime.context)), "nodes": nodes, "viewClasses": classes(scene.renderer.root), "viewportWidth": Double(scene.reportedViewportWidth), "errors": scene.runtime.errors]
         }
         let webViews = windows.reduce(0) { count, window in count + ((window["viewClasses"] as? [String] ?? []).filter { $0.contains("WKWebView") || $0 == "WebView" }.count) }
         return ["renderer": "appkit", "scriptEngine": "zig-js", "appearance": CraftMacColor.isDark ? "dark" : "light", "windows": windows, "webViews": webViews, "menu": testMenu]

package/dist/macos/templates/CraftMacRenderer.swift

@@ -318,7 +318,10 @@ final class CraftMacBox: NSView, NSTextFieldDelegate, NSTextViewDelegate, NSDrag
         case "Picker":
             let picker = NSPopUpButton(frame: .zero, pullsDown: false)
             picker.target = self; picker.action = #selector(changed); control = picker
-        case "Switch", "Checkbox":
+        case "Switch":
+            // A toggle, as System Settings draws one; a checkbox is the Checkbox primitive's.
+            let toggle = NSSwitch(); toggle.target = self; toggle.action = #selector(changed); control = toggle
+        case "Checkbox":
             let button = NSButton(checkboxWithTitle: "", target: self, action: #selector(changed)); control = button
         case "Icon", "Image":
             let image = NSImageView(); image.imageScaling = .scaleProportionallyUpOrDown; control = image
@@ -407,6 +410,11 @@ final class CraftMacBox: NSView, NSTextFieldDelegate, NSTextViewDelegate, NSDrag
             text.maximumNumberOfLines = (props["numberOfLines"] as? NSNumber)?.intValue ?? 0
             text.lineBreakMode = text.maximumNumberOfLines == 1 ? .byTruncatingTail : .byWordWrapping
         }
+        if let toggle = control as? NSSwitch {
+            toggle.state = (props["value"] as? Bool ?? props["checked"] as? Bool ?? false) ? .on : .off
+            toggle.isEnabled = props["disabled"] as? Bool != true
+            if let label { toggle.setAccessibilityLabel(label) }
+        }
         if let button = control as? NSButton {
             let title = props["title"] as? String ?? nativeText(node)
             button.title = props["iconOnly"] as? Bool == true ? "" : title
@@ -811,7 +819,8 @@ final class CraftMacBox: NSView, NSTextFieldDelegate, NSTextViewDelegate, NSDrag
     func fire(_ name: String, _ payload: [String: Any] = [:]) { renderer?.runtime.event(events[name], payload: payload) }
     @objc func pressed() { fire("onPress") }
     @objc func changed() {
-        let value: Any = (control as? NSPopUpButton)?.selectedItem?.representedObject ?? ((control as? NSButton)?.state == .on)
+        let state: NSControl.StateValue? = (control as? NSSwitch)?.state ?? (control as? NSButton)?.state
+        let value: Any = (control as? NSPopUpButton)?.selectedItem?.representedObject ?? (state == .on)
         fire("onValueChange", ["value": value, "nativeEvent": ["value": value]])
     }
     func controlTextDidChange(_ notification: Notification) { if let field = notification.object as? NSTextField { input(field.stringValue) } }

package/package.json

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