@craft-native/ios 0.0.490 → 0.0.492

package/package.json

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

package/templates/CraftApp.swift

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

package/templates/CraftHybrid.swift

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

package/templates/CraftNativeActions.swift

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

package/templates/CraftNativeFiles.swift

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

package/templates/CraftNativeScreen.swift

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

package/templates/CraftNativeServices.swift

@@ -324,11 +324,19 @@ final class CraftNativeSounds {
         object: nil,
         queue: .main,
     ) { note in CraftNativeSounds.handleInterruption(note) }
+    /// There is no interruption for the media server restarting, and it is
+    /// not recoverable the way an interruption is: see `handleMediaReset`.
+    private static let mediaResetObserver = NotificationCenter.default.addObserver(
+        forName: AVAudioSession.mediaServicesWereResetNotification,
+        object: nil,
+        queue: .main,
+    ) { _ in CraftNativeSounds.handleMediaReset() }
     /// `{ id, event: "ended" | "error", message? }` to the screen's script.
     var emit: (([String: Any]) -> Void)?
 
     init() {
         _ = Self.interruptionObserver
+        _ = Self.mediaResetObserver
         Self.services.add(self)
     }
 
@@ -362,6 +370,33 @@ final class CraftNativeSounds {
         }
     }
 
+    /// The media server restarted, which orphans every audio object the
+    /// process holds. Apple's requirement is to discard them and make new
+    /// ones; an orphaned `AVQueuePlayer` never plays again, never reaches the
+    /// end of its item and so never reports anything. Without this, a sound
+    /// playing across a reset left the script a handle that was silent
+    /// forever, `pause`/`resume` answering `true` about nothing, and the
+    /// session claim never released — while Android reports the equivalent
+    /// permanent loss of audio focus as an `error` event and drops the sound.
+    ///
+    /// A file player's playhead does not survive the reset, so the handle is
+    /// released and the loss reported rather than guessed at. Web Audio is
+    /// recovered instead (CraftWebAudio.swift): its graph is pure synthesis
+    /// the script is still driving, so a new engine continues it.
+    static let mediaResetMessage = "Audio stopped because the media services were reset"
+
+    /// Sound services and their playback controls are used on main.
+    private static func handleMediaReset() {
+        // The pre-reset interruption, if any, is gone with the server.
+        sessionInterrupted = false
+        for service in services.allObjects {
+            for id in Array(service.sounds.keys) {
+                service.remove(id, result: .failure(CraftNativeActionError(code: "AUDIO_ERROR", message: mediaResetMessage)))
+                service.emit?(["id": id, "event": "error", "message": mediaResetMessage])
+            }
+        }
+    }
+
     /// Starts `url`. `answer` hears once it plays (or could not be loaded).
     func play(id: String, url: URL, options: [String: Any], answer: @escaping (Result<Any, CraftNativeActionError>) -> Void) {
         stop(id: id, fadeOut: 0)

package/templates/CraftVoiceRecording.swift

@@ -15,7 +15,12 @@ extension AVAudioRecorder: CraftVoiceRecorder {}
 /// is starting, so a late permission/encoder answer cannot resurrect it.
 final class CraftVoiceRecording {
     static let shared = CraftVoiceRecording()
-    private static let fileQueue = DispatchQueue(label: "craft.voice-recording-files", qos: .utility)
+    /// Deleting a recording somebody just cancelled is work they are waiting
+    /// on: until it is gone, what they decided not to send still exists. At
+    /// `.utility` a busy device could leave the removal queued for seconds
+    /// behind everything else (it missed a two-second bound on a loaded CI
+    /// simulator while every other step of the cancellation was on time).
+    private static let fileQueue = DispatchQueue(label: "craft.voice-recording-files", qos: .userInitiated)
     private static let launchCleanup: Void = discardAbandonedRecordings(includeLegacy: false)
     private static let legacyCleanup: Void = discardAbandonedRecordings()
     private static let folderName = "voice-recordings"
@@ -106,7 +111,16 @@ final class CraftVoiceRecording {
     private let startupTimeout: TimeInterval
     private let stopTimeout: TimeInterval
     struct FileRemovalReceipt: Encodable {
+        /// From deciding to delete to the block actually running: the trace,
+        /// the submission, and the wait for a thread.
         let queueMilliseconds: Double
+        /// The first of those three alone. A run where `queueMilliseconds` is
+        /// seconds and this is near zero spent them waiting for GCD to admit
+        /// the block; one where this carries most of them spent them in
+        /// `trace`, which takes a process-wide lock and then logs
+        /// synchronously. Without it the two are indistinguishable, which is
+        /// where #490 ran out of evidence at 7638ms of queue for 3ms of work.
+        let submitMilliseconds: Double
         let removalMilliseconds: Double
         let ownedBefore: Bool
         let removed: Bool
@@ -178,12 +192,14 @@ final class CraftVoiceRecording {
             let queued = ProcessInfo.processInfo.systemUptime
             let observed = fileRemovalObserved
             Self.trace("cancel \(session.key.prefix(8)): file removal queued")
+            let submitted = ProcessInfo.processInfo.systemUptime
             Self.fileQueue.async {
                 let began = ProcessInfo.processInfo.systemUptime
                 let owned = CraftNativeFiles.owned(file.path) != nil
                 let removed = CraftNativeFiles.remove(file.path)
                 let receipt = FileRemovalReceipt(
                     queueMilliseconds: (began - queued) * 1000,
+                    submitMilliseconds: (submitted - queued) * 1000,
                     removalMilliseconds: (ProcessInfo.processInfo.systemUptime - began) * 1000,
                     ownedBefore: owned, removed: removed,
                     existsAfter: FileManager.default.fileExists(atPath: file.path))

package/templates/CraftWebAudio.swift

@@ -1361,7 +1361,12 @@ final class CraftWebAudio {
     private var engine: AVAudioEngine?
     private var claimedSession = false
     private var pump: Timer?
+    /// Notifications about the audio session and the app, registered once and
+    /// outliving any one engine.
     private var observers: [NSObjectProtocol] = []
+    /// And the one about this engine's configuration, which does not: a
+    /// rebuilt engine is a different object (`rebuildEngine`).
+    private var engineObserver: NSObjectProtocol?
     private weak var script: JSContext?
 
     init(live: Bool = true) {
@@ -1434,15 +1439,7 @@ final class CraftWebAudio {
                 contexts[id] = nil
                 return nil
             }
-            let engine = self.engine ?? makeEngine()
-            let source = AVAudioSourceNode(format: format) { silence, _, frameCount, bufferList in
-                let buffers = UnsafeMutableAudioBufferListPointer(bufferList)
-                silence.pointee = ObjCBool(graph.render(Int(frameCount), into: buffers))
-                return noErr
-            }
-            engine.attach(source)
-            engine.connect(source, to: engine.mainMixerNode, format: format)
-            context.source = source
+            attachSource(context, format: format, to: self.engine ?? makeEngine())
             refreshEngine()
         }
         startPump()
@@ -1482,25 +1479,84 @@ final class CraftWebAudio {
 
     // MARK: Engine and session
 
+    /// A context's graph reaches the engine through a source node. Attached
+    /// when the context opens, and again on a fresh engine for every live
+    /// context after the media server restarts.
+    private func attachSource(_ context: Context, format: AVAudioFormat, to engine: AVAudioEngine) {
+        let graph = context.graph
+        let source = AVAudioSourceNode(format: format) { silence, _, frameCount, bufferList in
+            let buffers = UnsafeMutableAudioBufferListPointer(bufferList)
+            silence.pointee = ObjCBool(graph.render(Int(frameCount), into: buffers))
+            return noErr
+        }
+        engine.attach(source)
+        engine.connect(source, to: engine.mainMixerNode, format: format)
+        context.source = source
+    }
+
     private func makeEngine() -> AVAudioEngine {
         let engine = AVAudioEngine()
         self.engine = engine
         let center = NotificationCenter.default
         // A route change (headphones) or an interruption (a call) stops the
-        // engine; it starts again when the context still plays.
-        observers.append(center.addObserver(forName: .AVAudioEngineConfigurationChange, object: engine, queue: .main) { [weak self] _ in
+        // engine; it starts again when the context still plays. This one is
+        // scoped to the engine, so a rebuilt engine replaces it.
+        if let engineObserver { center.removeObserver(engineObserver) }
+        engineObserver = center.addObserver(forName: .AVAudioEngineConfigurationChange, object: engine, queue: .main) { [weak self] _ in
             self?.refreshEngine()
-        })
+        }
+        // The rest are about the session and the app, not this engine.
+        guard observers.isEmpty else { return engine }
         observers.append(center.addObserver(forName: AVAudioSession.interruptionNotification, object: nil, queue: .main) { [weak self] note in
             let type = (note.userInfo?[AVAudioSessionInterruptionTypeKey] as? NSNumber)?.uintValue
             if type == AVAudioSession.InterruptionType.ended.rawValue { self?.refreshEngine() }
         })
+        observers.append(center.addObserver(forName: AVAudioSession.mediaServicesWereResetNotification, object: nil, queue: .main) { [weak self] _ in
+            self?.rebuildEngine()
+        })
         observers.append(center.addObserver(forName: UIApplication.willEnterForegroundNotification, object: nil, queue: .main) { [weak self] _ in
             self?.refreshEngine()
         })
         return engine
     }
 
+    /// The media server restarted, which orphans every audio object the
+    /// process holds — this engine and the source nodes attached to it. An
+    /// orphaned engine can be told to start and still produce no sound, and
+    /// no configuration-change notification is posted for it, so
+    /// `refreshEngine` cannot recover from this. Apple's requirement is to
+    /// discard the orphans and make new ones.
+    ///
+    /// A context does survive, because `CraftAudioGraph` is pure synthesis
+    /// holding no AVFoundation object: it is given a fresh source node on a
+    /// fresh engine and keeps playing from where its own clock is. That is
+    /// why this recovers where a file-backed sound reports the loss instead
+    /// (`CraftNativeSounds.handleMediaReset`) — a player's playhead does not
+    /// survive the reset, a synthesised graph does. Starting the new engine
+    /// reactivates the session, so the claim this screen already holds does
+    /// not need to be taken again.
+    private func rebuildEngine() {
+        guard live, let orphaned = engine else { return }
+        for context in contexts.values {
+            if let source = context.source {
+                orphaned.disconnectNodeOutput(source)
+                orphaned.detach(source)
+            }
+            context.source = nil
+        }
+        orphaned.stop()
+        if let engineObserver { NotificationCenter.default.removeObserver(engineObserver) }
+        engineObserver = nil
+        engine = nil
+        guard !contexts.isEmpty else { return }
+        let engine = makeEngine()
+        for context in contexts.values {
+            guard let format = AVAudioFormat(standardFormatWithSampleRate: context.graph.sampleRate, channels: 2) else { continue }
+            attachSource(context, format: format, to: engine)
+        }
+        refreshEngine()
+    }
+
     private func refreshEngine() {
         guard live, let engine else { return }
         let playing = contexts.values.contains { $0.running }
@@ -1522,6 +1578,8 @@ final class CraftWebAudio {
     }
 
     private func stopEngine() {
+        if let engineObserver { NotificationCenter.default.removeObserver(engineObserver) }
+        engineObserver = nil
         observers.forEach(NotificationCenter.default.removeObserver)
         observers.removeAll()
         engine?.stop()
@@ -1714,6 +1772,13 @@ final class CraftWebAudio {
     }
 
     var contextIdsForTesting: [Int] { Array(contexts.keys).sorted() }
+    /// The engine and a context's source node, so a test can see that a
+    /// media-services reset replaced them rather than restarting orphans
+    /// (`rebuildEngine`). Posting the notification cannot really orphan them,
+    /// so identity is the only observable; the clock moving afterwards is
+    /// what shows the replacements actually render.
+    var engineForTesting: AVAudioEngine? { engine }
+    func sourceForTesting(_ contextId: Int) -> AVAudioSourceNode? { contexts[contextId]?.source }
 
     // MARK: Helpers
 

package/templates/testing/DriverTests.swift.template

@@ -342,7 +342,19 @@ final class DriverTests: XCTestCase {
     }
 
     /// Deliver one gesture; the command's observation determines success.
-    func press(_ element: XCUIElement) {
+    ///
+    /// Waits for the target to come to rest first (`settledFrame`) and returns
+    /// the frame it settled on. Every tap command goes through here, so a
+    /// control touched straight after a flick cannot be hit while the scroll
+    /// view is still decelerating — whichever command did the tapping. #449
+    /// settled only the boolean `tapid` branch, which left `tap`, `tapif`,
+    /// `tapexact` and non-boolean `tapid` with the same exposure.
+    ///
+    /// Waiting before the one gesture is not a second gesture, and for a
+    /// control already at rest this costs one 0.1s read.
+    @discardableResult
+    func press(_ element: XCUIElement) -> CGRect {
+        let settled = settledFrame(element)
         // Resolve this before activation: a menu item can disappear as soon
         // as its gesture completes (for example Select All).
         let input = [.textField, .secureTextField, .textView, .searchField].contains(element.elementType)
@@ -352,6 +364,31 @@ final class DriverTests: XCTestCase {
         // A tap on a read-only text view need not open the keyboard. Only a
         // following type command observes whether this target took focus.
         lastTappedInput = input
+        return settled
+    }
+
+    /// `target`'s frame once it has stopped moving, or its last reading at
+    /// the deadline. This only ever waits — it never taps.
+    ///
+    /// A journey that flicks the page before touching a control leaves the
+    /// scroll view decelerating, and a touch that lands on a decelerating
+    /// scroll view stops the scroll instead of reaching the control. HQ's
+    /// agreement journey does exactly that: `swipe up`, then `tapid` the
+    /// first switch, which stayed off while the second one — tapped seconds
+    /// later — turned on (#449). `scrollto` and `drag` both end with a hold
+    /// that leaves the content at rest; `swipe` is a flick and does not.
+    ///
+    /// Waiting before the one gesture is not a second gesture.
+    func settledFrame(_ target: XCUIElement, within seconds: TimeInterval = 1.0) -> CGRect {
+        var frame = target.frame
+        let deadline = Date().addingTimeInterval(seconds)
+        while Date() < deadline {
+            Thread.sleep(forTimeInterval: 0.1)
+            let next = target.frame
+            if next.equalTo(frame) { return frame }
+            frame = next
+        }
+        return frame
     }
 
     func answerOpenPrompt() {
@@ -517,19 +554,26 @@ final class DriverTests: XCTestCase {
                 // renderer or hit-testing failure (HQ agreement job 7570).
                 let before = target.value as? String
                 let enabledBefore = target.isEnabled
-                let frameBefore = target.frame
-                press(target)
+                // press settles before it taps and hands back the frame it
+                // settled on, so this is one read rather than two.
+                let frameBefore = press(target)
                 let settle = Date().addingTimeInterval(1.5)
                 var flipped = false
                 repeat {
                     flipped = switchFlipped(from: before, to: target.value as? String)
                     if !flipped { Thread.sleep(forTimeInterval: 0.25) }
                 } while !flipped && Date() < settle
+                let frameAfter = target.frame
                 let observation: [String: Any] = [
                     "id": arg, "gestures": 1, "flipped": flipped,
                     "enabledBefore": enabledBefore, "enabledAfter": target.isEnabled,
                     "valueBefore": before ?? "unknown", "valueAfter": target.value as? String ?? "unknown",
                     "frameBefore": [frameBefore.origin.x, frameBefore.origin.y, frameBefore.width, frameBefore.height],
+                    // Without this a control that was still moving when it
+                    // was tapped looks exactly like one that sat still and
+                    // ignored the tap, which is where #449 ran out of
+                    // evidence.
+                    "frameAfter": [frameAfter.origin.x, frameAfter.origin.y, frameAfter.width, frameAfter.height],
                 ]
                 lastBooleanTap = observation
                 if let data = try? JSONSerialization.data(withJSONObject: observation, options: [.sortedKeys]),