craft-native 0.0.490 → 0.0.491

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

@@ -425,6 +425,13 @@ internal class CraftNativeStores private constructor(
             main.post { done(false) }
             return
         }
+        // UIKit refuses a payload that is not JSON before it touches the
+        // disk, and a checkpoint kept on one host and refused on the other is
+        // the divergence this contract exists to prevent (#396).
+        if (json != null && !craftNativeIsJsonText(json)) {
+            main.post { done(false) }
+            return
+        }
         writer.execute {
             val file = snapshotFile(name)
             val previous = snapshotCache[name]
@@ -2140,3 +2147,182 @@ internal object CraftNativeIcons {
         override fun getOpacity(): Int = android.graphics.PixelFormat.TRANSLUCENT
     }
 }
+
+/**
+ * Whether `text` is JSON that UIKit's own writer would also accept.
+ *
+ * UIKit refuses a snapshot whose payload is not JSON, before it touches the
+ * disk: `JSONSerialization.jsonObject(with:options: [.fragmentsAllowed])`
+ * returning nil fails the write. Android had no such check, so a payload iOS
+ * rejected was written here and the two hosts disagreed about whether a
+ * checkpoint had been kept (#396).
+ *
+ * The grammar is Foundation's, measured rather than assumed, because it is
+ * not RFC 8259 and a strict parser would have diverged in the other
+ * direction:
+ *
+ *  - top-level fragments are allowed (`42`, `"text"`, `null`);
+ *  - **one** trailing comma is allowed in an object or array — `{"a":1,}`
+ *    and `[1,]` are accepted, `{"a":1,,}` and `[,1]` are not;
+ *  - a lone surrogate escape is rejected, a matched pair accepted;
+ *  - a raw control character inside a string is rejected, its escape is not;
+ *  - `00`, `+1`, `.5`, `1.`, `1.0e`, `NaN` and `Infinity` are all rejected;
+ *  - trailing content after the value is rejected, surrounding space is not.
+ *
+ * `org.json` cannot stand in for this: `JSONTokener` accepts unquoted keys,
+ * single quotes and more, so it would admit payloads UIKit refuses.
+ * `android.util.JsonReader` in strict mode refuses top-level fragments that
+ * UIKit accepts. Both are wrong in a direction that matters, which is why
+ * this is scanned here and pinned against Foundation itself by
+ * `packages/android/src/snapshot-json-contract.test.ts`.
+ */
+private class CraftNativeJsonScanner(private val text: String) {
+    private var at = 0
+
+    fun validate(): Boolean {
+        skipWhitespace()
+        if (!value()) return false
+        skipWhitespace()
+        return at == text.length
+    }
+
+    private fun skipWhitespace() {
+        while (at < text.length && (text[at] == ' ' || text[at] == '\t' || text[at] == '\n' || text[at] == '\r')) at++
+    }
+
+    private fun value(): Boolean {
+        if (at >= text.length) return false
+        return when (text[at]) {
+            '{' -> obj()
+            '[' -> arr()
+            '"' -> string()
+            't' -> literal("true")
+            'f' -> literal("false")
+            'n' -> literal("null")
+            else -> number()
+        }
+    }
+
+    private fun literal(word: String): Boolean {
+        if (!text.startsWith(word, at)) return false
+        at += word.length
+        return true
+    }
+
+    /** After a member, consume the separator. Returns null when malformed. */
+    private fun afterMember(closing: Char): Boolean? {
+        skipWhitespace()
+        if (at >= text.length) return null
+        return when (text[at]) {
+            ',' -> {
+                at++
+                skipWhitespace()
+                // Foundation allows exactly one trailing comma before the
+                // close. A second comma, or a close that never comes, is not.
+                if (at < text.length && text[at] == closing) { at++; true } else false
+            }
+            closing -> { at++; true }
+            else -> null
+        }
+    }
+
+    private fun obj(): Boolean {
+        at++
+        skipWhitespace()
+        if (at < text.length && text[at] == '}') { at++; return true }
+        while (true) {
+            skipWhitespace()
+            if (at >= text.length || text[at] != '"') return false
+            if (!string()) return false
+            skipWhitespace()
+            if (at >= text.length || text[at] != ':') return false
+            at++
+            skipWhitespace()
+            if (!value()) return false
+            val done = afterMember('}') ?: return false
+            if (done) return true
+        }
+    }
+
+    private fun arr(): Boolean {
+        at++
+        skipWhitespace()
+        if (at < text.length && text[at] == ']') { at++; return true }
+        while (true) {
+            skipWhitespace()
+            if (!value()) return false
+            val done = afterMember(']') ?: return false
+            if (done) return true
+        }
+    }
+
+    private fun string(): Boolean {
+        at++
+        var pendingHighSurrogate = false
+        while (at < text.length) {
+            val character = text[at]
+            when {
+                character == '"' -> { at++; return !pendingHighSurrogate }
+                character == '\\' -> {
+                    at++
+                    if (at >= text.length) return false
+                    val escape = text[at]
+                    if (escape == 'u') {
+                        if (at + 4 >= text.length) return false
+                        var code = 0
+                        for (offset in 1..4) {
+                            val digit = Character.digit(text[at + offset], 16)
+                            if (digit < 0) return false
+                            code = code * 16 + digit
+                        }
+                        at += 5
+                        val high = code in 0xD800..0xDBFF
+                        val low = code in 0xDC00..0xDFFF
+                        // A low surrogate is only legal directly after a high
+                        // one, and a high one must be followed by a low one.
+                        if (pendingHighSurrogate != low) return false
+                        pendingHighSurrogate = high
+                        continue
+                    }
+                    if (pendingHighSurrogate) return false
+                    if (escape !in listOf('"', '\\', '/', 'b', 'f', 'n', 'r', 't')) return false
+                    at++
+                }
+                character.code < 0x20 -> return false
+                else -> {
+                    if (pendingHighSurrogate) return false
+                    at++
+                }
+            }
+        }
+        return false
+    }
+
+    private fun number(): Boolean {
+        val start = at
+        if (at < text.length && text[at] == '-') at++
+        val integerStart = at
+        while (at < text.length && text[at] in '0'..'9') at++
+        if (at == integerStart) return false
+        // A leading zero may not be followed by another digit.
+        if (text[integerStart] == '0' && at - integerStart > 1) return false
+        if (at < text.length && text[at] == '.') {
+            at++
+            val fractionStart = at
+            while (at < text.length && text[at] in '0'..'9') at++
+            if (at == fractionStart) return false
+        }
+        if (at < text.length && (text[at] == 'e' || text[at] == 'E')) {
+            at++
+            if (at < text.length && (text[at] == '+' || text[at] == '-')) at++
+            val exponentStart = at
+            while (at < text.length && text[at] in '0'..'9') at++
+            if (at == exponentStart) return false
+        }
+        return at > start
+    }
+}
+
+/** Whether a snapshot payload is JSON both hosts accept. */
+private fun craftNativeIsJsonText(text: String): Boolean = CraftNativeJsonScanner(text).validate()
+

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

@@ -149,6 +149,27 @@ private fun craftNativeBoolean(value: Any?, fallback: Boolean = false): Boolean
 
 private fun craftNativeInt(value: Any?, fallback: Int): Int = (value as? Number)?.toInt() ?: fallback
 
+/**
+ * Where a field's text and hint begin, vertically.
+ *
+ * The platform's `Widget.EditText` carries `gravity = center_vertical`, and
+ * nothing between it and this app overrides it: `Theme.CraftApp` inherits
+ * `Theme.Material3.DayNight.NoActionBar`, no Material3 theme binds
+ * `android:editTextStyle`, and AppCompat binds it to
+ * `Widget.AppCompat.EditText`, whose chain reaches `android:Widget.EditText`
+ * without touching gravity. A single-line field is never taller than its
+ * text, so the centring cannot show; a field given a `minHeight` drew its
+ * first line — and its hint — halfway down the box, where iOS and the web
+ * both start at the top (#502).
+ *
+ * Only the vertical bits are replaced. The horizontal ones are left exactly
+ * as they were, because `textAlign` resolves through `textAlignment`, whose
+ * default of `TEXT_ALIGNMENT_INHERIT` can still fall back to this gravity.
+ */
+private fun craftNativeVerticalGravity(current: Int, multiline: Boolean): Int =
+    (current and Gravity.VERTICAL_GRAVITY_MASK.inv()) or (if (multiline) Gravity.TOP else Gravity.CENTER_VERTICAL)
+
+
 /**
  * A scroll event's geometry in density-independent units.
  *
@@ -6689,6 +6710,8 @@ class MainActivity : AppCompatActivity() {
                 if (isSingleLine == multiline) isSingleLine = !multiline
                 val wantedLines = if (multiline) craftNativeInt(props.opt("numberOfLines"), Int.MAX_VALUE).coerceAtLeast(1) else 1
                 if (maxLines != wantedLines) maxLines = wantedLines
+                val wantedGravity = craftNativeVerticalGravity(gravity, multiline)
+                if (gravity != wantedGravity) gravity = wantedGravity
                 isEnabled = craftNativeBoolean(props.opt("editable"), true)
                 configureTextStyle(this, style)
                 // The style's padding is where the text starts, as on iOS and

package/dist/cli.js

@@ -1025,6 +1025,9 @@ async function detachDiskImage(mount, options = {}) {
     await wait(attempt * 2000);
   }
 }
+function attachedDevice(attachOutput) {
+  return attachOutput.match(/^(\/dev\/disk\d+)(?=\s)/m)?.[1] ?? null;
+}
 async function createDiskImage(opts) {
   if (!/^[^/:\n]{1,27}$/.test(opts.volumeName))
     return { success: false, error: `Invalid DMG volume name "${opts.volumeName}"; must be 1..27 chars without /, :, or newline` };
@@ -1068,7 +1071,7 @@ async function createDiskImage(opts) {
     phase = "layout";
     writeInstallerLayout(mount, opts.volumeName, bundleName);
     phase = "detach";
-    const detached = await detachDiskImage(mount);
+    const detached = await detachDiskImage(attachedDevice(attachment) ?? mount);
     if (!detached.success) {
       detachAttempts = detached.attempts;
       throw new Error(detached.error);
@@ -1083,7 +1086,7 @@ async function createDiskImage(opts) {
 Disk image lifecycle: ${JSON.stringify({ phase, image: writable, mount, attachment, detachAttempts })}` };
   } finally {
     if (mounted)
-      await runTool("hdiutil", ["detach", mount, "-force"]);
+      await runTool("hdiutil", ["detach", attachedDevice(attachment) ?? mount, "-force"]);
     removeTempDir(scratch);
   }
 }
@@ -3243,7 +3246,7 @@ function pinCraftNativeDependency(packagePath, craftVersion) {
 `);
 }
 // package.json
-var version = "0.0.490";
+var version = "0.0.491";
 
 // bin/cli.ts
 var spawnedFrom = process6.env[CRAFT_CLI_SPAWN_MARKER];

package/dist/index.cjs

@@ -376,7 +376,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.490";
+var version = "0.0.491";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;
@@ -1393,6 +1393,9 @@ async function detachDiskImage(mount, options = {}) {
     await wait(attempt * 2000);
   }
 }
+function attachedDevice(attachOutput) {
+  return attachOutput.match(/^(\/dev\/disk\d+)(?=\s)/m)?.[1] ?? null;
+}
 async function createDiskImage(opts) {
   if (!/^[^/:\n]{1,27}$/.test(opts.volumeName))
     return { success: false, error: `Invalid DMG volume name "${opts.volumeName}"; must be 1..27 chars without /, :, or newline` };
@@ -1436,7 +1439,7 @@ async function createDiskImage(opts) {
     phase = "layout";
     writeInstallerLayout(mount, opts.volumeName, bundleName);
     phase = "detach";
-    const detached = await detachDiskImage(mount);
+    const detached = await detachDiskImage(attachedDevice(attachment) ?? mount);
     if (!detached.success) {
       detachAttempts = detached.attempts;
       throw new Error(detached.error);
@@ -1451,7 +1454,7 @@ async function createDiskImage(opts) {
 Disk image lifecycle: ${JSON.stringify({ phase, image: writable, mount, attachment, detachAttempts })}` };
   } finally {
     if (mounted)
-      await runTool("hdiutil", ["detach", mount, "-force"]);
+      await runTool("hdiutil", ["detach", attachedDevice(attachment) ?? mount, "-force"]);
     removeTempDir(scratch);
   }
 }

package/dist/index.js

@@ -117,7 +117,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.490";
+var version = "0.0.491";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;
@@ -1149,6 +1149,9 @@ async function detachDiskImage(mount, options = {}) {
     await wait(attempt * 2000);
   }
 }
+function attachedDevice(attachOutput) {
+  return attachOutput.match(/^(\/dev\/disk\d+)(?=\s)/m)?.[1] ?? null;
+}
 async function createDiskImage(opts) {
   if (!/^[^/:\n]{1,27}$/.test(opts.volumeName))
     return { success: false, error: `Invalid DMG volume name "${opts.volumeName}"; must be 1..27 chars without /, :, or newline` };
@@ -1192,7 +1195,7 @@ async function createDiskImage(opts) {
     phase = "layout";
     writeInstallerLayout(mount, opts.volumeName, bundleName);
     phase = "detach";
-    const detached = await detachDiskImage(mount);
+    const detached = await detachDiskImage(attachedDevice(attachment) ?? mount);
     if (!detached.success) {
       detachAttempts = detached.attempts;
       throw new Error(detached.error);
@@ -1207,7 +1210,7 @@ async function createDiskImage(opts) {
 Disk image lifecycle: ${JSON.stringify({ phase, image: writable, mount, attachment, detachAttempts })}` };
   } finally {
     if (mounted)
-      await runTool("hdiutil", ["detach", mount, "-force"]);
+      await runTool("hdiutil", ["detach", attachedDevice(attachment) ?? mount, "-force"]);
     removeTempDir(scratch);
   }
 }

package/dist/ios/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/dist/ios/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/dist/ios/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/dist/ios/templates/testing/DriverTests.swift.template

@@ -354,6 +354,30 @@ final class DriverTests: XCTestCase {
         lastTappedInput = input
     }
 
+    /// `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() {
         // A direct app link has already arrived. Querying an invisible
         // SpringBoard here can stall its accessibility snapshot on iOS 27.
@@ -517,7 +541,7 @@ 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
+                let frameBefore = settledFrame(target)
                 press(target)
                 let settle = Date().addingTimeInterval(1.5)
                 var flipped = false
@@ -525,11 +549,17 @@ final class DriverTests: XCTestCase {
                     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]),

package/dist/package.d.ts

@@ -298,6 +298,11 @@ export declare function detachDiskImage(mount: string, options?: {
     error: string;
     attempts: DiskImageDetachAttempt[];
 }>;
+/**
+ * The whole-disk device `hdiutil attach` reports for the image it mounted
+ * ("/dev/disk4" from its first line), or null when the output names none.
+ */
+export declare function attachedDevice(attachOutput: string): string | null;
 /**
  * Helper: Create DMG from app bundle
  */

package/package.json

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