@craft-native/ios 0.0.424 → 0.0.436

package/README.md

@@ -52,6 +52,14 @@ decoration. Resuming does not replay it. Available on both native renderers.
 - **Audio Recording** - AVAudioRecorder with compressed output
 - **Video Recording** - UIImagePickerController video capture
 
+### Shake gesture configuration
+
+`enableShakeGesture` is an opt-in boolean, separate from
+`enableMotionSensors`. It defaults to false and arms the host's shake gesture
+only while the app is in the foreground. Both configuration readers validate
+its type: an invalid value rejects the configuration instead of letting the
+Swift and Zig hosts disagree about which capabilities are enabled.
+
 ### Native voice capture
 
 With `enableAudioRecording`, the native renderer exposes

package/dist/cli.js

@@ -24,7 +24,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,
@@ -504,6 +504,7 @@ var DEFAULT_CONFIG = {
   enableAudioRecording: false,
   enableVideoRecording: false,
   enableMotionSensors: false,
+  enableShakeGesture: false,
   enableLocalDatabase: false,
   enableBluetooth: false,
   enableNFC: false,

package/dist/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craft-native/ios",
-  "version": "0.0.424",
+  "version": "0.0.436",
   "homepage": "https://github.com/craft-native/craft/tree/main/packages/ios#readme",
   "repository": {
     "type": "git",

package/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/templates/CraftNativeMutation.swift

@@ -18,10 +18,22 @@ struct CraftNativeMutationFailure: Error, Equatable {
 struct CraftNativeMutationResult {
     let batchId: String
     let revision: Int
-    let document: [String: Any]?
     let updatedNodeIds: [String]
     let affectedNodeIds: [String]
     let requiresFullRender: Bool
+    private let materialize: () -> [String: Any]?
+    /// The committed tree, built when asked for: a host that redraws only the
+    /// nodes a batch touched never needs the whole tree.
+    var document: [String: Any]? { materialize() }
+
+    init(batchId: String, revision: Int, document: @escaping () -> [String: Any]?, updatedNodeIds: [String], affectedNodeIds: [String], requiresFullRender: Bool) {
+        self.batchId = batchId
+        self.revision = revision
+        self.materialize = document
+        self.updatedNodeIds = updatedNodeIds
+        self.affectedNodeIds = affectedNodeIds
+        self.requiresFullRender = requiresFullRender
+    }
 }
 
 /// Validates and applies versioned native-tree mutations without touching UIKit.
@@ -91,6 +103,8 @@ final class CraftNativeMutationDocument {
         var updatedNodeIds: [String] = []
         var affectedNodeIds: [String] = []
         var requiresFullRender = false
+        // Only an operation that adds, moves or removes nodes can leave one unreachable.
+        var reshaped = false
         for (index, value) in operations.enumerated() {
             guard let operation = value as? [String: Any], let name = operation["op"] as? String else {
                 throw CraftNativeMutationFailure(
@@ -99,6 +113,7 @@ final class CraftNativeMutationDocument {
                     operationIndex: index
                 )
             }
+            if name != "updateNode" { reshaped = true }
             do {
                 switch name {
                 case "createNode":
@@ -147,7 +162,7 @@ final class CraftNativeMutationDocument {
             guard let root = candidateNodes[candidateRoot], root.parent == nil else {
                 throw CraftNativeMutationFailure("INVALID_TREE", "root node must not have a parent")
             }
-            guard descendants(of: candidateRoot, nodes: candidateNodes).count + 1 == candidateNodes.count else {
+            guard !reshaped || descendants(of: candidateRoot, nodes: candidateNodes).count + 1 == candidateNodes.count else {
                 throw CraftNativeMutationFailure("INVALID_TREE", "all nodes must be reachable from the root")
             }
         }
@@ -158,7 +173,7 @@ final class CraftNativeMutationDocument {
         return CraftNativeMutationResult(
             batchId: batchId,
             revision: nextRevision,
-            document: candidateRoot.flatMap { materialize($0, nodes: candidateNodes) },
+            document: { [candidateRoot, candidateNodes, weak self] in candidateRoot.flatMap { self?.materialize($0, nodes: candidateNodes) } },
             updatedNodeIds: updatedNodeIds,
             affectedNodeIds: affectedNodeIds,
             requiresFullRender: requiresFullRender

package/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/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/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/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
@@ -248,8 +285,15 @@ final class DriverTests: XCTestCase {
         return (parts[0], parts.count > 1 ? Double(parts[1]) ?? 10 : 10)
     }
 
-    /// A tap that never fails the run: an element covered a moment (the big
-    /// timer coming up) is tapped where it is, and the check after says.
+    /// A switch reports "0" or "1". Any other value is not a switch state to
+    /// wait on, so the tap stands as it would for any other control.
+    func switchFlipped(from before: String?, to after: String?) -> Bool {
+        let states: Set<String> = ["0", "1"]
+        guard let before, let after, states.contains(before), states.contains(after) else { return true }
+        return before != after
+    }
+
+    /// Deliver one gesture; the command's observation determines success.
     func press(_ element: XCUIElement) {
         if element.isHittable { element.tap() }
         else { element.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.5)).tap() }
@@ -401,8 +445,21 @@ final class DriverTests: XCTestCase {
             else { XCTFail("Element not found"); note("FAIL tapexact \(arg): NOT FOUND") }
         case "tapid":
             let target = identified(arg)
-            if target.waitForExistence(timeout: 10) { press(target); note("tapid \(arg): ok") }
-            else { XCTFail("Element not found"); note("FAIL tapid \(arg): NOT FOUND") }
+            if !target.waitForExistence(timeout: 10) { XCTFail("Element not found"); note("FAIL tapid \(arg): NOT FOUND") }
+            else if target.elementType == .switch {
+                // Observe one physical gesture. Retapping could conceal a
+                // renderer or hit-testing failure (HQ agreement job 7570).
+                let before = target.value as? String
+                press(target)
+                let settle = Date().addingTimeInterval(1.5)
+                var flipped = false
+                repeat {
+                    flipped = switchFlipped(from: before, to: target.value as? String)
+                    if !flipped { Thread.sleep(forTimeInterval: 0.25) }
+                } while !flipped && Date() < settle
+                check(flipped, "tapid \(arg) flips the switch")
+            }
+            else { press(target); note("tapid \(arg): ok") }
         case "longpressid":
             let target = identified(arg)
             guard target.waitForExistence(timeout: 10), target.isHittable else {
@@ -590,13 +647,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 +701,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 +714,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
                 }