@mentra/bluetooth-sdk 3.2.1-dev.314 → 3.3.0-beta.942

package/ios/Source/utils/AudioSessionMonitor.swift

@@ -10,9 +10,11 @@ import Foundation
 
 #if !os(macOS)
 import AVFoundation
+import OSLog
 import UIKit
 
 class AudioSessionMonitor {
+    private static let readinessLog = Logger(subsystem: "com.mentra.bluetooth-sdk", category: "AudioReadiness")
     /// Singleton instance
     private static var instance: AudioSessionMonitor?
 
@@ -96,15 +98,31 @@ class AudioSessionMonitor {
     /// This avoids switching A2DP music playback to HFP microphone mode
     static func isDevicePaired(devicePattern: String) -> Bool {
         let session = AVAudioSession.sharedInstance()
+        let outputs = session.currentRoute.outputs
+        let route = BluetoothAudioRoute.observe(
+            outputs: outputs.map { (name: $0.portName, portType: $0.portType.rawValue) },
+            target: devicePattern, isIOSAppOnMac: ProcessInfo.processInfo.isiOSAppOnMac
+        )
+        let activeTarget = route.matchingOutputCount > 0
+        let availableInputs = session.availableInputs
+        let bluetoothInput = availableInputs?.first { input in
+            input.portType == .bluetoothHFP
+                && input.portName.localizedCaseInsensitiveContains(devicePattern)
+        }
+
+        // NSLog messages redact the native route checks in retained Mac logs.
+        // Keep categorical evidence at notice level without exposing names or
+        // selecting an input, activating the session, or changing audio routing.
+        readinessLog.notice("Pair audio: iosOnMac=\(ProcessInfo.processInfo.isiOSAppOnMac, privacy: .public) targetPresent=\(!devicePattern.isEmpty, privacy: .public) category=\(session.category.rawValue, privacy: .public) outputs=\(outputs.count, privacy: .public) bluetoothOutputs=\(route.bluetoothOutputCount, privacy: .public) targetNameOutputs=\(route.targetNameOutputCount, privacy: .public) inputs=\(availableInputs?.count ?? -1, privacy: .public) activeTarget=\(activeTarget, privacy: .public) hfpTarget=\(bluetoothInput != nil, privacy: .public)")
 
         // Check if already active (using A2DP for music or HFP for calls)
-        if isAudioDeviceConnected(devicePattern: devicePattern) {
+        if activeTarget {
             Bridge.log("AudioMonitor: Device '\(devicePattern)' already active")
             return true
         }
 
         // Try to find in availableInputs (includes paired devices)
-        guard let availableInputs = session.availableInputs else {
+        guard let availableInputs else {
             Bridge.log("AudioMonitor: ❌ availableInputs is nil")
             return false
         }
@@ -114,11 +132,6 @@ class AudioSessionMonitor {
             Bridge.log("AudioMonitor:   - \(input.portName) (type: \(input.portType.rawValue))")
         }
 
-        let bluetoothInput = availableInputs.first { input in
-            input.portType == .bluetoothHFP
-                && input.portName.localizedCaseInsensitiveContains(devicePattern)
-        }
-
         if let btInput = bluetoothInput {
             Bridge.log(
                 "AudioMonitor: ✅ Found paired device '\(btInput.portName)' (not activating to preserve A2DP)"
@@ -291,8 +304,31 @@ class AudioSessionMonitor {
 /// AVAudioSession preserves the route name on iOS-on-Mac but reports the
 /// CoreAudio transport "Bluetooth" instead of iPhone's profile-specific port.
 enum BluetoothAudioRoute {
+    struct Observation: Equatable {
+        let bluetoothOutputCount: Int
+        let targetNameOutputCount: Int
+        let matchingOutputCount: Int
+    }
+
+    static func observe(outputs: [(name: String, portType: String)], target: String, isIOSAppOnMac: Bool) -> Observation {
+        Observation(
+            bluetoothOutputCount: outputs.filter { isBluetoothTransport($0.portType, isIOSAppOnMac: isIOSAppOnMac) }.count,
+            targetNameOutputCount: outputs.filter { matchesName($0.name, target: target) }.count,
+            matchingOutputCount: outputs.filter {
+                matches(name: $0.name, portType: $0.portType, target: target, isIOSAppOnMac: isIOSAppOnMac)
+            }.count
+        )
+    }
+
     static func matches(name: String, portType: String, target: String, isIOSAppOnMac: Bool) -> Bool {
-        guard !target.isEmpty, name.localizedCaseInsensitiveContains(target) else { return false }
+        matchesName(name, target: target) && isBluetoothTransport(portType, isIOSAppOnMac: isIOSAppOnMac)
+    }
+
+    private static func matchesName(_ name: String, target: String) -> Bool {
+        !target.isEmpty && name.localizedCaseInsensitiveContains(target)
+    }
+
+    private static func isBluetoothTransport(_ portType: String, isIOSAppOnMac: Bool) -> Bool {
         return portType == "BluetoothHFP" || portType == "BluetoothA2DPOutput"
             || (isIOSAppOnMac && portType == "Bluetooth")
     }

package/ios/Source/utils/DemandDrivenAudioWorker.swift

@@ -0,0 +1,150 @@
+import Foundation
+
+/// Owns a processor on one serial queue. Empty queues schedule no recurring work.
+/// Demand changes invalidate queued audio/results immediately; creation, processing,
+/// and destruction finish in order without blocking the caller (including the UI).
+final class DemandDrivenAudioWorker<Processor> {
+    struct Snapshot {
+        let active: Bool
+        let initialized: Bool
+        let processing: Bool
+        let queuedBuffers: Int
+        let processedBuffers: UInt64
+        let droppedBuffers: UInt64
+    }
+
+    private let lock = NSLock()
+    private let queue: DispatchQueue
+    private let capacity: Int
+    private let makeProcessor: () -> Processor?
+    private let process: (Processor, Data, UInt64) -> Void
+    private var active = false
+    private var generation: UInt64 = 0
+    private var buffers = [Data]()
+    private var scheduled = false
+    private var initialized = false
+    private var processing = false
+    private var processedBuffers: UInt64 = 0
+    private var droppedBuffers: UInt64 = 0
+
+    // Accessed only on queue, including release of the previous processor.
+    private var processor: Processor?
+    private var processorGeneration: UInt64?
+    private var attemptedInitialization = false
+
+    init(capacity: Int = 100,
+         queue: DispatchQueue = DispatchQueue(label: "com.mentra.speech.processor", qos: .userInitiated),
+         makeProcessor: @escaping () -> Processor?,
+         process: @escaping (Processor, Data, UInt64) -> Void)
+    {
+        precondition(capacity > 0)
+        self.capacity = capacity
+        self.queue = queue
+        self.makeProcessor = makeProcessor
+        self.process = process
+    }
+
+    func setActive(_ value: Bool) {
+        lock.lock()
+        defer { lock.unlock() }
+        guard active != value else { return }
+        active = value
+        invalidateLocked()
+    }
+
+    /// Reload a changed model only if there is still local-transcription demand.
+    func restart() {
+        lock.lock()
+        defer { lock.unlock() }
+        invalidateLocked()
+    }
+
+    private func invalidateLocked() {
+        generation &+= 1
+        buffers.removeAll(keepingCapacity: true)
+        initialized = false
+        scheduleLocked()
+    }
+
+    func accept(_ data: Data) {
+        guard !data.isEmpty else { return }
+        lock.lock()
+        defer { lock.unlock() }
+        guard active else { return }
+        // Bound even audio arriving while model loading or decoding is blocked.
+        if buffers.count == capacity {
+            buffers.removeFirst()
+            droppedBuffers &+= 1
+        }
+        buffers.append(data)
+        scheduleLocked()
+    }
+
+    func isCurrent(_ token: UInt64) -> Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        return active && generation == token
+    }
+
+    func snapshot() -> Snapshot {
+        lock.lock()
+        defer { lock.unlock() }
+        return Snapshot(active: active, initialized: initialized, processing: processing,
+                        queuedBuffers: buffers.count, processedBuffers: processedBuffers,
+                        droppedBuffers: droppedBuffers)
+    }
+
+    private func scheduleLocked() {
+        guard !scheduled else { return }
+        scheduled = true
+        queue.async { self.drain() }
+    }
+
+    private func drain() {
+        while true {
+            lock.lock()
+            let token = generation
+            if processorGeneration != token {
+                lock.unlock()
+                // ARC destruction stays serialized with inference and model loading.
+                processor = nil
+                processorGeneration = token
+                attemptedInitialization = false
+                continue
+            }
+            guard active else {
+                scheduled = false
+                lock.unlock()
+                return
+            }
+            if !attemptedInitialization {
+                attemptedInitialization = true
+                lock.unlock()
+                processor = makeProcessor()
+                lock.lock()
+                if generation == token { initialized = processor != nil }
+                lock.unlock()
+                continue
+            }
+            guard let processor else {
+                buffers.removeAll(keepingCapacity: true)
+                scheduled = false
+                lock.unlock()
+                return // Missing model: retry on a demand transition or model restart.
+            }
+            guard !buffers.isEmpty else {
+                scheduled = false
+                lock.unlock()
+                return
+            }
+            let data = buffers.removeFirst()
+            processing = true
+            lock.unlock()
+            process(processor, data, token)
+            lock.lock()
+            processedBuffers &+= 1
+            processing = false
+            lock.unlock()
+        }
+    }
+}

package/ios/Source/utils/G1Text.swift

@@ -24,31 +24,9 @@ class G1Text {
 
     init() {}
 
-    /// Converts text to the base Latin glyphs available in G1 firmware.
-    /// Newer glasses bypass this G1-only transport and keep the original text.
+    /// Preserve supported G1 Latin glyphs before BLE encoding.
     static func sanitizeForDisplay(_ text: String) -> String {
-        let expanded = text.reduce(into: "") { result, character in
-            switch character {
-            case "Đ", "Ð": result.append("D")
-            case "đ", "ð": result.append("d")
-            case "Ł": result.append("L")
-            case "ł": result.append("l")
-            case "Ø": result.append("O")
-            case "ø": result.append("o")
-            case "Æ": result.append("AE")
-            case "æ": result.append("ae")
-            case "Œ": result.append("OE")
-            case "œ": result.append("oe")
-            case "ẞ": result.append("SS")
-            case "ß": result.append("ss")
-            case "Þ": result.append("TH")
-            case "þ": result.append("th")
-            default: result.append(character)
-            }
-        }
-
-        return expanded
-            .folding(options: .diacriticInsensitive, locale: Locale(identifier: "en_US_POSIX"))
+        G1TextSanitizer.sanitizeForDisplay(text)
     }
 
     // MARK: - Text Wall Methods

package/ios/Source/utils/G1TextSanitizer.swift

@@ -0,0 +1,27 @@
+import Foundation
+
+/// Preserves the embedded G1 1.5.6 Latin glyphs; see notes/g1-character-support.md.
+enum G1TextSanitizer {
+    private static let supportedLatin = Set("ÀÂÇÈÉÊËÎÏÔÙÛÜàçèéêëîïôùûüÿŸÄäÖößẞâÁáÍíÑñúÓóÚⁱIJijŠšŽžÃÅÆÌÐÒÕØÝÞãåæìðòõøýþĄąĆćČčĎďĘęĚěĞğŁłŃńŇňŘřŚśŞşŤťŮůŹźŻżĂăıȘșȚțǖǘǚǜǎǐǒǔŐőŰű".unicodeScalars)
+    private static let latinClusters = try! NSRegularExpression(pattern: #"\p{Latin}\p{M}*"#)
+
+    static func sanitizeForDisplay(_ text: String) -> String {
+        let output = NSMutableString(string: text)
+        let range = NSRange(text.startIndex ..< text.endIndex, in: text)
+        for match in latinClusters.matches(in: text, range: range).reversed() {
+            let cluster = output.substring(with: match.range)
+            let composed = cluster.precomposedStringWithCanonicalMapping
+            let scalars = composed.unicodeScalars
+            let replacement: String
+            if scalars.count == 1, let scalar = scalars.first,
+               (0x20 ... 0x7E).contains(scalar.value) || supportedLatin.contains(scalar)
+            {
+                replacement = composed
+            } else {
+                replacement = LatinTextSanitizer.sanitizeForDisplay(cluster, preserveOtherScripts: true)
+            }
+            output.replaceCharacters(in: match.range, with: replacement)
+        }
+        return output as String
+    }
+}

package/ios/Source/utils/G2Text.swift

@@ -0,0 +1,11 @@
+import Foundation
+
+/// Empty interior rows shut down some EvenHub firmware pages. Keep the row
+/// without exposing this protocol workaround to miniapps or other devices.
+enum G2Text {
+    static func containerContent(_ text: String) -> String {
+        if text.isEmpty { return " " }
+        return text.components(separatedBy: "\n")
+            .map { $0.isEmpty ? "\u{200B}" : $0 }.joined(separator: "\n")
+    }
+}

package/ios/Source/utils/LatinTextSanitizer.swift

@@ -0,0 +1,48 @@
+import Foundation
+
+/// Converts accented and extended Latin letters to base glyphs at the device boundary.
+enum LatinTextSanitizer {
+    private static let latinLettersWithMarks = try! NSRegularExpression(pattern: #"\p{Latin}\p{M}*"#)
+
+    static func sanitizeForDisplay(_ text: String, preserveOtherScripts: Bool = false) -> String {
+        if preserveOtherScripts {
+            let output = NSMutableString(string: text)
+            let range = NSRange(text.startIndex ..< text.endIndex, in: text)
+            for match in latinLettersWithMarks.matches(in: text, range: range).reversed() {
+                let cluster = output.substring(with: match.range)
+                let expanded = cluster.unicodeScalars.map { expandLatinLetter(Character($0)) }.joined()
+                output.replaceCharacters(in: match.range, with: stripDiacritics(expanded))
+            }
+            return output as String
+        }
+        // Preserve the established G1 folding behavior.
+        let expanded = text.reduce(into: "") { result, character in
+            result.append(expandLatinLetter(character))
+        }
+        return stripDiacritics(expanded)
+    }
+
+    private static func stripDiacritics(_ text: String) -> String {
+        text.folding(options: .diacriticInsensitive, locale: Locale(identifier: "en_US_POSIX"))
+    }
+
+    private static func expandLatinLetter(_ character: Character) -> String {
+        switch character {
+        case "Đ", "Ð": return "D"
+        case "đ", "ð": return "d"
+        case "Ł": return "L"
+        case "ł": return "l"
+        case "Ø": return "O"
+        case "ø": return "o"
+        case "Æ": return "AE"
+        case "æ": return "ae"
+        case "Œ": return "OE"
+        case "œ": return "oe"
+        case "ẞ": return "SS"
+        case "ß": return "ss"
+        case "Þ": return "TH"
+        case "þ": return "th"
+        default: return String(character)
+        }
+    }
+}

package/ios/Tests/BluetoothAudioRouteTests.swift

@@ -2,6 +2,32 @@
 import XCTest
 
 final class BluetoothAudioRouteTests: XCTestCase {
+    func testObservationSeparatesAbsentBluetoothFromWrongTarget() {
+        let builtIn = BluetoothAudioRoute.observe(
+            outputs: [(name: "MacBook Speakers", portType: "Speaker")], target: "03BE", isIOSAppOnMac: true
+        )
+        let wrongTarget = BluetoothAudioRoute.observe(
+            outputs: [(name: "Mentra_Live_023B", portType: "Bluetooth")], target: "03BE", isIOSAppOnMac: true
+        )
+        XCTAssertEqual(builtIn, .init(bluetoothOutputCount: 0, targetNameOutputCount: 0, matchingOutputCount: 0))
+        XCTAssertEqual(wrongTarget, .init(bluetoothOutputCount: 1, targetNameOutputCount: 0, matchingOutputCount: 0))
+    }
+
+    func testObservationKeepsIdentityAndTransportSeparate() {
+        let matching = BluetoothAudioRoute.observe(
+            outputs: [(name: "Mentra_Live_03BE", portType: "Bluetooth")], target: "03BE", isIOSAppOnMac: true
+        )
+        let usb = BluetoothAudioRoute.observe(
+            outputs: [(name: "Mentra_Live_03BE", portType: "USBAudio")], target: "03BE", isIOSAppOnMac: true
+        )
+        let missingTarget = BluetoothAudioRoute.observe(
+            outputs: [(name: "Mentra_Live_03BE", portType: "Bluetooth")], target: "", isIOSAppOnMac: true
+        )
+        XCTAssertEqual(matching, .init(bluetoothOutputCount: 1, targetNameOutputCount: 1, matchingOutputCount: 1))
+        XCTAssertEqual(usb, .init(bluetoothOutputCount: 0, targetNameOutputCount: 1, matchingOutputCount: 0))
+        XCTAssertEqual(missingTarget, .init(bluetoothOutputCount: 1, targetNameOutputCount: 0, matchingOutputCount: 0))
+    }
+
     func testRecognizesIPhoneProfiles() {
         for port in ["BluetoothHFP", "BluetoothA2DPOutput"] {
             XCTAssertTrue(BluetoothAudioRoute.matches(

package/ios/Tests/BluetoothBackgroundModeTests.swift

@@ -0,0 +1,32 @@
+@testable import MentraBluetoothSDK
+import XCTest
+
+final class BluetoothBackgroundModeTests: XCTestCase {
+    func testDetectsDeclaredBluetoothCentral() {
+        XCTAssertTrue(
+            BluetoothBackgroundMode.declaresBluetoothCentral(
+                ["UIBackgroundModes": ["audio", "bluetooth-central"]]
+            )
+        )
+    }
+
+    func testReportsMissingOrMalformedBackgroundModes() {
+        XCTAssertFalse(BluetoothBackgroundMode.declaresBluetoothCentral(nil))
+        XCTAssertFalse(BluetoothBackgroundMode.declaresBluetoothCentral([:]))
+        XCTAssertFalse(BluetoothBackgroundMode.declaresBluetoothCentral(["UIBackgroundModes": ["audio"]]))
+        XCTAssertFalse(
+            BluetoothBackgroundMode.declaresBluetoothCentral(["UIBackgroundModes": "bluetooth-central"])
+        )
+    }
+
+    func testMacOSHasNoBackgroundModeRequirement() {
+        #if os(macOS)
+            XCTAssertTrue(BluetoothBackgroundMode.isDeclared(in: nil))
+        #endif
+    }
+
+    func testWarningPointsToTheDocs() {
+        XCTAssertTrue(BluetoothBackgroundMode.missingWarning.contains("bluetooth-central"))
+        XCTAssertTrue(BluetoothBackgroundMode.missingWarning.contains("#background-operation"))
+    }
+}

package/ios/Tests/BluetoothSdkAnalyticsTrackerTests.swift

@@ -4,8 +4,59 @@ import XCTest
 final class BluetoothSdkAnalyticsTrackerTests: XCTestCase {
     private var tracker = BluetoothSdkAnalyticsTracker(simulatedModel: "Simulated Glasses")
 
-    private func snapshot(connected: Bool, model: String = "Mentra Live", serial: String = "") -> AnalyticsGlassesSnapshot {
-        AnalyticsGlassesSnapshot(connected: connected, fullyBooted: connected, model: model, serialNumber: serial)
+    private func snapshot(
+        connected: Bool,
+        model: String = "Mentra Live",
+        serial: String = "",
+        battery: Int = -1,
+        charging: Bool = false
+    ) -> AnalyticsGlassesSnapshot {
+        var snapshot = AnalyticsGlassesSnapshot(connected: connected, fullyBooted: connected, model: model, serialNumber: serial)
+        snapshot.batteryLevel = battery
+        snapshot.charging = charging
+        return snapshot
+    }
+
+    func testCountedConnectionReportsItsLengthReasonAndBatteryWhenItEnds() throws {
+        tracker.initialize(snapshot(connected: false), reportingDay: 100)
+        _ = tracker.observe(snapshot(connected: true), reportingDay: 100, nowMs: 1000)
+        _ = tracker.observe(snapshot(connected: true, battery: 80), reportingDay: 100, nowMs: 2000)
+        _ = tracker.observe(snapshot(connected: true, battery: 71, charging: true), reportingDay: 100, nowMs: 3000)
+
+        let ended = tracker.observe(snapshot(connected: false), reportingDay: 100, nowMs: 61000) {
+            BluetoothSdkAnalyticsTracker.disconnectUser
+        }
+        XCTAssertEqual(ended.count, 1)
+        let disconnected = try XCTUnwrap(ended.first)
+        XCTAssertEqual(disconnected.name, "bluetooth_sdk_glasses_disconnected")
+        XCTAssertEqual(disconnected.properties["session_duration_ms"] as? Int64, 60000)
+        XCTAssertEqual(disconnected.properties["disconnect_reason"] as? String, "user_disconnect")
+        XCTAssertEqual(disconnected.properties["battery_level_at_connect"] as? Int, 80)
+        XCTAssertEqual(disconnected.properties["battery_level_at_disconnect"] as? Int, 71)
+        XCTAssertEqual(disconnected.properties["charging"] as? Bool, true)
+        XCTAssertEqual(disconnected.properties["glasses_model"] as? String, "Mentra Live")
+
+        // Further disconnected updates do not report the connection again.
+        XCTAssertTrue(tracker.observe(snapshot(connected: false), reportingDay: 100, nowMs: 62000).isEmpty)
+    }
+
+    func testConnectionAlreadyUpWhenTheSdkStartedIsNotReportedAsEnding() {
+        tracker.initialize(snapshot(connected: true, serial: "MLAB0001"), reportingDay: 100)
+        XCTAssertTrue(tracker.observe(snapshot(connected: false), reportingDay: 100, nowMs: 5000).isEmpty)
+    }
+
+    func testBatteryFromAPreviousConnectionDoesNotLeakIntoTheNextOne() throws {
+        tracker.initialize(snapshot(connected: false), reportingDay: 100)
+        _ = tracker.observe(snapshot(connected: true, battery: 90), reportingDay: 100, nowMs: 0)
+        _ = tracker.observe(snapshot(connected: false), reportingDay: 100, nowMs: 1000)
+        _ = tracker.observe(snapshot(connected: true), reportingDay: 100, nowMs: 2000)
+        let ended = tracker.observe(snapshot(connected: false), reportingDay: 100, nowMs: 3000)
+        XCTAssertEqual(ended.count, 1)
+        let second = try XCTUnwrap(ended.first)
+        XCTAssertNil(second.properties["battery_level_at_connect"])
+        XCTAssertNil(second.properties["battery_level_at_disconnect"])
+        XCTAssertNil(second.properties["charging"])
+        XCTAssertEqual(second.properties["disconnect_reason"] as? String, "unknown")
     }
 
     func testConnectThenSerialEmitsEachOncePerConnection() {
@@ -40,7 +91,7 @@ final class BluetoothSdkAnalyticsTrackerTests: XCTestCase {
         tracker.initialize(snapshot(connected: false), reportingDay: 100)
         _ = tracker.observe(snapshot(connected: true, model: ""), reportingDay: 100)
         let ended = tracker.observe(snapshot(connected: false, model: ""), reportingDay: 100)
-        XCTAssertEqual(ended.map(\.name), ["bluetooth_sdk_glasses_connected"])
+        XCTAssertEqual(ended.map(\.name), ["bluetooth_sdk_glasses_connected", "bluetooth_sdk_glasses_disconnected"])
         XCTAssertEqual(ended[0].properties["glasses_model_unresolved"] as? Bool, true)
         XCTAssertNil(ended[0].properties["glasses_model"])
     }

package/ios/Tests/BluetoothSdkUpdateCheckTests.swift

@@ -0,0 +1,153 @@
+@testable import MentraBluetoothSDK
+import XCTest
+
+final class BluetoothSdkUpdateCheckTests: XCTestCase {
+    /// Collects values handed to `@Sendable` callbacks from the check's queue.
+    private final class Recorder<Value>: @unchecked Sendable {
+        private let lock = NSLock()
+        private var stored: [Value] = []
+
+        var values: [Value] {
+            lock.lock()
+            defer { lock.unlock() }
+            return stored
+        }
+
+        func append(_ value: Value) {
+            lock.lock()
+            stored.append(value)
+            lock.unlock()
+        }
+    }
+
+    private final class CheckBox: @unchecked Sendable {
+        var check: BluetoothSdkUpdateCheck?
+    }
+
+    private func result(
+        _ status: String,
+        latest: String? = "3.2.1",
+        minimum: String? = nil
+    ) -> BluetoothSdkUpdateCheckResult {
+        BluetoothSdkUpdateCheckResult(status: status, channel: "latest", latestVersion: latest, minimumSupportedVersion: minimum)
+    }
+
+    func testParsesTheCoreResponseTreatingNullAndBlankVersionsAsUnknown() {
+        let parsed = BluetoothSdkUpdateCheckResult.parse(
+            #"{"status":"update_available","channel":"dev","latestVersion":"3.3.0-dev.821","minimumSupportedVersion":null}"#
+        )
+        XCTAssertEqual(
+            parsed,
+            BluetoothSdkUpdateCheckResult(status: "update_available", channel: "dev", latestVersion: "3.3.0-dev.821", minimumSupportedVersion: nil)
+        )
+        XCTAssertNil(BluetoothSdkUpdateCheckResult.parse(#"{"status":"current","latestVersion":""}"#)?.latestVersion)
+        XCTAssertNotNil(BluetoothSdkUpdateCheckResult.parse(#"{"status":"current","latestVersion":""}"#))
+        XCTAssertNil(BluetoothSdkUpdateCheckResult.parse("<html>502</html>"))
+    }
+
+    func testBannerNamesInstalledAndLatestVersionsAndTheSurfaceUpdateCommand() throws {
+        let reactNative = try XCTUnwrap(BluetoothSdkUpdateNotice.banner(installedVersion: "3.1.0", result: result("update_available"), surface: "react_native"))
+        XCTAssertTrue(reactNative.contains("MENTRA BLUETOOTH SDK UPDATE AVAILABLE"))
+        XCTAssertTrue(reactNative.contains("Installed: 3.1.0"))
+        XCTAssertTrue(reactNative.contains("Latest: 3.2.1"))
+        XCTAssertTrue(reactNative.contains("bun add @mentra/bluetooth-sdk@3.2.1"))
+        XCTAssertFalse(reactNative.contains("NO LONGER SUPPORTED"))
+        XCTAssertTrue(reactNative.hasPrefix("=================================================================="))
+        XCTAssertTrue(reactNative.hasSuffix("=================================================================="))
+
+        let ios = try XCTUnwrap(BluetoothSdkUpdateNotice.banner(installedVersion: "3.1.0", result: result("update_available"), surface: "ios"))
+        XCTAssertTrue(ios.contains("MentraBluetoothSDK Swift package at 3.2.1"))
+        let android = try XCTUnwrap(BluetoothSdkUpdateNotice.banner(installedVersion: "3.1.0", result: result("update_available"), surface: "android"))
+        XCTAssertTrue(android.contains("com.mentraglass:bluetooth-sdk:3.2.1"))
+    }
+
+    func testUnsupportedVersionGetsTheStrongerBanner() throws {
+        let banner = try XCTUnwrap(BluetoothSdkUpdateNotice.banner(
+            installedVersion: "3.0.5",
+            result: result("unsupported", minimum: "3.1.0"),
+            surface: "ios"
+        ))
+        XCTAssertTrue(banner.contains("MENTRA BLUETOOTH SDK 3.0.5 IS NO LONGER SUPPORTED"))
+        XCTAssertTrue(banner.contains("known issues"))
+    }
+
+    func testNoBannerWhenCurrentUnknownOrNoLatestVersionToPointAt() {
+        XCTAssertNil(BluetoothSdkUpdateNotice.banner(installedVersion: "3.2.1", result: result("current"), surface: "ios"))
+        XCTAssertNil(BluetoothSdkUpdateNotice.banner(installedVersion: "3.2.1", result: result("unknown", latest: nil), surface: "ios"))
+        XCTAssertNil(BluetoothSdkUpdateNotice.banner(installedVersion: "3.2.1", result: result("update_available", latest: nil), surface: "ios"))
+    }
+
+    func testSurfaceFollowsTheIntegration() {
+        XCTAssertEqual(BluetoothSdkUpdateCheck.surface(forAnalyticsSurface: "react_native"), "react_native")
+        XCTAssertEqual(BluetoothSdkUpdateCheck.surface(forAnalyticsSurface: "ios"), "ios")
+        XCTAssertEqual(BluetoothSdkUpdateCheck.surface(forAnalyticsSurface: "macos"), "ios")
+    }
+
+    func testRequestIdentifiesTheInstallAppAndSdk() throws {
+        let check = BluetoothSdkUpdateCheck(surface: "react_native", sdkVersion: "3.1.0", transport: { _, completion in completion(nil) }) { _, _ in }
+        let body = check.requestBody()
+        let installId = try XCTUnwrap(body["install_id"] as? String)
+        XCTAssertEqual(installId, BluetoothSdkInstallId.get())
+        XCTAssertTrue(installId.hasPrefix("mentra-bt-sdk-"))
+        XCTAssertEqual(body["app_identifier"] as? String, Bundle.main.bundleIdentifier ?? "")
+        XCTAssertEqual(body["sdk_version"] as? String, "3.1.0")
+        XCTAssertEqual(body["sdk_platform"] as? String, "ios")
+        XCTAssertEqual(body["sdk_surface"] as? String, "react_native")
+        XCTAssertNotNil(body["app_build_type"])
+        XCTAssertNotNil(body["app_install_source"])
+        XCTAssertTrue(JSONSerialization.isValidJSONObject(body))
+    }
+
+    func testOutOfDateSdkPrintsTheBannerOnceAtStartAndStopsOnClose() throws {
+        let notices = Recorder<String>()
+        let sentBodies = Recorder<Data>()
+        let check = BluetoothSdkUpdateCheck(
+            surface: "ios",
+            sdkVersion: "3.1.0",
+            transport: { body, completion in
+                sentBodies.append(body)
+                completion(Data(#"{"status":"update_available","channel":"latest","latestVersion":"3.2.1","minimumSupportedVersion":null}"#.utf8))
+            }
+        ) { banner, _ in notices.append(banner) }
+        check.start()
+        BluetoothSdkUpdateCheck.awaitIdle()
+        XCTAssertEqual(notices.values.count, 1)
+        XCTAssertTrue(notices.values.first?.contains("Latest: 3.2.1") == true)
+        let sentBody = try XCTUnwrap(sentBodies.values.first)
+        let sent = try XCTUnwrap(JSONSerialization.jsonObject(with: sentBody) as? [String: Any])
+        XCTAssertEqual(sent["sdk_version"] as? String, "3.1.0")
+        check.stop()
+    }
+
+    func testFailuresAndUnknownVersionsAreSilent() {
+        let notices = Recorder<String>()
+        let calls = Recorder<Bool>()
+        let checks = [
+            BluetoothSdkUpdateCheck(surface: "ios", sdkVersion: "3.1.0", transport: { _, completion in completion(nil) }) { banner, _ in notices.append(banner) },
+            BluetoothSdkUpdateCheck(surface: "ios", sdkVersion: "3.1.0", transport: { _, completion in completion(Data("<html>502</html>".utf8)) }) { banner, _ in notices.append(banner) },
+            BluetoothSdkUpdateCheck(surface: "ios", sdkVersion: "unknown", transport: { _, completion in calls.append(true); completion(nil) }) { banner, _ in notices.append(banner) },
+            BluetoothSdkUpdateCheck(surface: "ios", sdkVersion: nil, transport: { _, completion in calls.append(true); completion(nil) }) { banner, _ in notices.append(banner) },
+        ]
+        checks.forEach { $0.start() }
+        BluetoothSdkUpdateCheck.awaitIdle()
+        XCTAssertTrue(notices.values.isEmpty)
+        XCTAssertTrue(calls.values.isEmpty)
+    }
+
+    func testCheckStoppedBeforeTheResponseArrivesPrintsNothing() {
+        let notices = Recorder<String>()
+        let box = CheckBox()
+        let check = BluetoothSdkUpdateCheck(
+            surface: "ios",
+            sdkVersion: "3.1.0",
+            transport: { _, completion in
+                box.check?.stop()
+                completion(Data(#"{"status":"update_available","latestVersion":"3.2.1"}"#.utf8))
+            }
+        ) { banner, _ in notices.append(banner) }
+        box.check = check
+        check.start()
+        BluetoothSdkUpdateCheck.awaitIdle()
+        XCTAssertTrue(notices.values.isEmpty)
+    }
+}