@mentra/bluetooth-sdk 3.4.0-dev.993 → 3.4.0-dev.998

package/ios/Tests/MentraLiveSessionReadinessTests.swift

@@ -1,3 +1,4 @@
+import CoreBluetooth
 @testable import MentraBluetoothSDK
 import XCTest
 
@@ -93,10 +94,19 @@ final class MentraLiveSessionReadinessTests: XCTestCase {
                        BluetoothSdkDefaults.voiceActivityDetectionEnabled)
     }
 
-    func testPairingYieldDuringPendingReadinessCleansUpAndReclaimsAfterItsWindow() async throws {
+    /// The pairing state is process-wide and persisted; every test starts and ends clean.
+    private func resetPairingState() {
+        UserDefaults.standard.removeObject(forKey: MentraLivePairingStateStore.defaultsKey)
+        MentraLivePairingStateStore.shared.resetForTest()
+    }
+
+    private func withPairingTransport(
+        _ body: (SessionReadinessTransport, MentraBluetoothSDK, ObservableStore) throws -> Void
+    ) rethrows {
         let store = DeviceStore.shared.store
         let saved = ["bluetooth", "glasses"].map { ($0, store.getCategory($0)) }
         let previous = DeviceManager.shared.sgc
+        resetPairingState()
         let transport = SessionReadinessTransport()
         let sdk = MentraBluetoothSDK()
         DeviceManager.shared.sgc = transport
@@ -104,6 +114,7 @@ final class MentraLiveSessionReadinessTests: XCTestCase {
             sdk.invalidate()
             transport.cleanup()
             DeviceManager.shared.sgc = previous
+            resetPairingState()
             for (category, values) in saved {
                 for key in store.getCategory(category).keys where values[key] == nil {
                     store.remove(category, key)
@@ -111,36 +122,327 @@ final class MentraLiveSessionReadinessTests: XCTestCase {
                 for (key, value) in values { store.set(category, key, value) }
             }
         }
+        try body(transport, sdk, store)
+    }
 
-        func receive(_ value: [String: Any]) throws {
-            try transport.processReceivedData(JSONSerialization.data(withJSONObject: value))
+    private func receive(_ transport: MentraLive, _ value: [String: Any]) throws {
+        try transport.processReceivedData(JSONSerialization.data(withJSONObject: value))
+    }
+
+    func testPairingPauseDuringPendingReadinessCleansUpAndLastsTheWindowPlusMargin() throws {
+        try withPairingTransport { transport, sdk, store in
+            try receive(transport, ["type": "glasses_ready", "sid": "original"])
+            try receive(transport, ["type": "version_info_1", "sid": "replacement", "build_number": "302010070"])
+            XCTAssertTrue(sdk.glassesStatus.connected)
+            XCTAssertFalse(sdk.glassesStatus.fullyBooted)
+            store.set("glasses", "headUp", true)
+
+            var enteringBodies: [[String: Any]] = []
+            var stateEvents: [[String: Any]] = []
+            let sink = Bridge.addEventSink { event, body in
+                if event == "entering_pairing_mode" { enteringBodies.append(body) }
+                if event == "pairing_state_changed", let state = body["state"] as? [String: Any] {
+                    stateEvents.append(state)
+                }
+            }
+            defer { Bridge.removeEventSink(sink) }
+
+            let before = MentraLivePairingStateStore.nowMs()
+            try receive(transport, [
+                "type": "entering_pairing_mode", "window_ms": 5000, "window_id": 7,
+                "owner_retained": true, "protocol_version": 4,
+            ])
+            let after = MentraLivePairingStateStore.nowMs()
+            let pairingStore = MentraLivePairingStateStore.shared
+            XCTAssertTrue(pairingStore.isPaused)
+            XCTAssertFalse(transport.isManagerKilled)
+            guard case let .pairingMode(windowId, endsAtMs) = pairingStore.state else {
+                return XCTFail("expected pairing_mode, got \(pairingStore.describe())")
+            }
+            XCTAssertEqual(windowId, 7)
+            // window_ms + 30 s, with no 300 s floor.
+            XCTAssertGreaterThanOrEqual(endsAtMs, before + 35_000)
+            XCTAssertLessThanOrEqual(endsAtMs, after + 35_000)
+
+            XCTAssertEqual(enteringBodies.count, 1)
+            XCTAssertEqual(enteringBodies.first?["window_id"] as? Int, 7)
+            XCTAssertEqual(enteringBodies.first?["owner_retained"] as? Bool, true)
+            XCTAssertEqual(stateEvents.last?["state"] as? String, "pairing_mode")
+            XCTAssertEqual(stateEvents.last?["windowId"] as? Int, 7)
+            let published = store.get("glasses", "pairingState") as? [String: Any]
+            XCTAssertEqual(published?["state"] as? String, "pairing_mode")
+            XCTAssertEqual(sdk.glassesStatus.pairingState?["windowId"] as? Int, 7)
+            XCTAssertFalse(sdk.glassesStatus.connected)
+            XCTAssertEqual(store.get("glasses", "headUp") as? Bool, false)
+
+            // Readiness queued on the relinquished GATT must not end the pause.
+            try receive(transport, ["type": "glasses_ready", "sid": "replacement"])
+            XCTAssertTrue(pairingStore.isPaused)
+            XCTAssertFalse(sdk.glassesStatus.fullyBooted)
+
+            // The pause is persisted with its window id.
+            let record = UserDefaults.standard.dictionary(forKey: MentraLivePairingStateStore.defaultsKey)
+            XCTAssertEqual(record?[MentraLivePairingStateMachine.keyWindowId] as? Int, 7)
+            XCTAssertEqual(record?[MentraLivePairingStateMachine.keyState] as? String, "pairing_mode")
+
+            // pairing_mode_ended for another window is ignored; the matching one resumes early.
+            var endedBodies: [[String: Any]] = []
+            let endedSink = Bridge.addEventSink { event, body in
+                if event == "pairing_mode_ended" { endedBodies.append(body) }
+            }
+            defer { Bridge.removeEventSink(endedSink) }
+            try receive(transport, ["type": "pairing_mode_ended", "reason": "timeout", "window_id": 8])
+            XCTAssertTrue(pairingStore.isPaused)
+            try receive(transport, ["type": "pairing_mode_ended", "reason": "timeout", "window_id": 7])
+            XCTAssertEqual(pairingStore.state, .normal)
+            XCTAssertEqual(endedBodies.count, 2)
+            XCTAssertEqual(endedBodies.last?["reason"] as? String, "timeout")
+            XCTAssertEqual(endedBodies.last?["window_id"] as? Int, 7)
+            XCTAssertEqual(stateEvents.last?["state"] as? String, "normal")
         }
-        try receive(["type": "glasses_ready", "sid": "original"])
-        try receive(["type": "version_info_1", "sid": "replacement", "build_number": "302010070"])
-        XCTAssertTrue(sdk.glassesStatus.connected)
-        XCTAssertFalse(sdk.glassesStatus.fullyBooted)
-        store.set("glasses", "headUp", true)
-        store.set("glasses", "voiceActivityDetectionEnabled", !BluetoothSdkDefaults.voiceActivityDetectionEnabled)
+    }
 
-        try receive(["type": "entering_pairing_mode", "window_ms": 5000])
-        XCTAssertTrue(transport.isPairingYieldActive())
-        XCTAssertFalse(sdk.glassesStatus.connected)
-        XCTAssertFalse(sdk.glassesStatus.fullyBooted)
-        XCTAssertEqual(store.get("glasses", "headUp") as? Bool, false)
-        XCTAssertEqual(store.get("glasses", "voiceActivityDetectionEnabled") as? Bool,
-                       BluetoothSdkDefaults.voiceActivityDetectionEnabled)
+    func testFlagOffFirmwareEnteringPairingModeIsAPersistentRejection() throws {
+        try withPairingTransport { transport, _, store in
+            var enteringEvents = 0
+            let sink = Bridge.addEventSink { event, _ in
+                if event == "entering_pairing_mode" { enteringEvents += 1 }
+            }
+            defer { Bridge.removeEventSink(sink) }
 
-        // Readiness queued on the relinquished GATT must not close the yield.
-        try receive(["type": "glasses_ready", "sid": "replacement"])
-        XCTAssertTrue(transport.isPairingYieldActive())
-        XCTAssertFalse(sdk.glassesStatus.fullyBooted)
+            try receive(transport, ["type": "entering_pairing_mode", "window_ms": 5000])
+            let pairingStore = MentraLivePairingStateStore.shared
+            XCTAssertTrue(pairingStore.isRejected)
+            // The manager stays alive; the pairing state gates every automatic connect.
+            XCTAssertFalse(transport.isManagerKilled)
+            XCTAssertEqual(enteringEvents, 1)
+            XCTAssertEqual((store.get("glasses", "pairingState") as? [String: Any])?["state"] as? String, "pairing_rejected")
+            // Native code never writes the retired settings flag.
+            XCTAssertNotEqual(store.get("bluetooth", "mentra_live_owner_lost") as? Bool, true)
 
-        // Let the existing minimum yield expire, then accept a fresh readiness.
-        try await Task.sleep(nanoseconds: 5_100_000_000)
-        XCTAssertFalse(transport.isPairingYieldActive())
-        try receive(["type": "glasses_ready", "sid": "reclaimed"])
-        XCTAssertTrue(sdk.glassesStatus.connected)
-        XCTAssertTrue(sdk.glassesStatus.fullyBooted)
+            // A later pairing mode does not lift it, and the settings replay cannot either.
+            try receive(transport, ["type": "entering_pairing_mode", "window_ms": 5000])
+            store.set("bluetooth", "mentra_live_owner_lost", false)
+            XCTAssertTrue(pairingStore.isRejected)
+
+            // A restart keeps it.
+            pairingStore.resetForTest()
+            pairingStore.ensureRestored(savedDeviceId: "")
+            XCTAssertTrue(pairingStore.isRejected)
+
+            // A successful automatic session does not clear it; an explicit pair does. The
+            // selected row lists this flag-off unit as legacy firmware.
+            try receive(transport, ["type": "glasses_ready", "sid": "automatic"])
+            XCTAssertTrue(pairingStore.isRejected)
+            store.set("bluetooth", "pending_device_name", "MENTRA_LIVE_BLE_ABCD")
+            store.set("bluetooth", "pending_device_secure_pairing_capable", false)
+            try receive(transport, ["type": "glasses_ready", "sid": "explicit"])
+            XCTAssertEqual(pairingStore.state, .normal)
+        }
+    }
+
+    func testPhoneHelloOnEverySecureSessionAndPairSelectOnlyOnAnExplicitAttempt() throws {
+        try withPairingTransport { transport, _, store in
+            let securePairingInfo: [String: Any] = [
+                "type": "pairing_info", "secure_pairing_capable": true, "protocol_version": 4,
+                "had_previous_bond": true, "owner_committed": true, "auto_audio": true,
+            ]
+            var pairingInfoBodies: [[String: Any]] = []
+            let sink = Bridge.addEventSink { event, body in
+                if event == "pairing_info" { pairingInfoBodies.append(body) }
+            }
+            defer { Bridge.removeEventSink(sink) }
+
+            // Automatic reconnect: hello only.
+            try receive(transport, securePairingInfo)
+            try receive(transport, securePairingInfo)
+            let types = transport.commands.compactMap { $0["type"] as? String }
+            XCTAssertEqual(types.filter { $0 == "phone_hello" }.count, 1)
+            XCTAssertFalse(types.contains("pair_select"))
+            let hello = transport.commands.first { $0["type"] as? String == "phone_hello" }
+            XCTAssertEqual(hello?["pairing_protocol"] as? Int, 4)
+            XCTAssertEqual(pairingInfoBodies.last?["auto_audio"] as? Bool, true)
+            XCTAssertNil(pairingInfoBodies.last?["awaiting_confirm"])
+            XCTAssertNil(pairingInfoBodies.last?["retained_owner_link"])
+
+            // An explicit attempt on a new session also selects this phone.
+            transport.cleanup()
+            let explicitTransport = SessionReadinessTransport()
+            defer { explicitTransport.cleanup() }
+            store.set("bluetooth", "pending_device_name", "MENTRA_LIVE_BLE_ABCD")
+            store.set("bluetooth", "pending_device_secure_pairing_capable", true)
+            try receive(explicitTransport, securePairingInfo)
+            try receive(explicitTransport, securePairingInfo)
+            let explicitTypes = explicitTransport.commands.compactMap { $0["type"] as? String }
+            XCTAssertEqual(explicitTypes.filter { $0 == "phone_hello" }.count, 1)
+            XCTAssertEqual(explicitTypes.filter { $0 == "pair_select" }.count, 1)
+        }
+    }
+
+    func testLegacyFirmwareGetsNoPairingProtocolMessages() throws {
+        try withPairingTransport { transport, _, store in
+            store.set("bluetooth", "mentra_live_secure_firmware", false)
+            store.set("bluetooth", "pending_device_name", "MENTRA_LIVE_BLE_ABCD")
+            try receive(transport, ["type": "pairing_info", "had_previous_bond": false])
+            let types = transport.commands.compactMap { $0["type"] as? String }
+            XCTAssertFalse(types.contains("phone_hello"))
+            XCTAssertFalse(types.contains("pair_select"))
+        }
+    }
+
+    func testError14OnAnExplicitAttemptAsksToForgetThePairingWithItsCode() throws {
+        try withPairingTransport { transport, _, store in
+            var failures: [[String: Any]] = []
+            let sink = Bridge.addEventSink { event, body in
+                if event == "pair_failure" { failures.append(body) }
+            }
+            defer { Bridge.removeEventSink(sink) }
+            MentraLive.clearStaleIosBondPrompt()
+            defer { MentraLive.clearStaleIosBondPrompt() }
+
+            let error14 = NSError(domain: CBErrorDomain, code: CBError.peerRemovedPairingInformation.rawValue)
+            store.set("bluetooth", "pending_device_name", "MENTRA_LIVE_BLE_ABCD")
+            XCTAssertTrue(transport.stopAfterConnectFailure(error14))
+            XCTAssertEqual(failures.count, 1)
+            XCTAssertEqual(failures.first?["code"] as? String, "ios_forget_pairing")
+            XCTAssertEqual(failures.first?["error"] as? String, "errors:pairingCouldNotStart")
+            // An explicit attempt never counts toward a rejection.
+            XCTAssertEqual(MentraLivePairingStateStore.shared.state, .normal)
+
+            // On an automatic reconnect error 14 is one strike, not a prompt.
+            store.set("bluetooth", "pending_device_name", "")
+            store.set("bluetooth", "mentra_live_secure_firmware", true)
+            _ = transport.stopAfterConnectFailure(error14)
+            XCTAssertEqual(failures.count, 1)
+            XCTAssertEqual(MentraLivePairingStateStore.shared.state, .normal)
+        }
+    }
+
+    // MARK: - Pairing readiness by target capability
+
+    private func runMainLoop(until condition: () -> Bool, timeout: TimeInterval = 3) {
+        let deadline = Date().addingTimeInterval(timeout)
+        while !condition(), Date() < deadline {
+            RunLoop.main.run(until: Date().addingTimeInterval(0.01))
+        }
+    }
+
+    private func ready(_ store: ObservableStore) -> Bool {
+        store.get("glasses", "fullyBooted") as? Bool == true
+    }
+
+    /// An explicit pair to the row `capability` (nil when the row did not know it).
+    private func startExplicitPair(_ store: ObservableStore, capability: Bool?) {
+        store.set("glasses", "fullyBooted", false)
+        store.set("bluetooth", "pending_device_name", "MENTRA_LIVE_BLE_ABCD")
+        store.set("bluetooth", "pending_device_secure_pairing_capable", capability.map { $0 as Any } ?? "")
+    }
+
+    func testUnknownCapabilityWithoutPairingInfoIsReportedReadyAfterTheWait() throws {
+        try withPairingTransport { transport, _, store in
+            transport.unknownCapabilityPairingInfoWaitMs = 50
+            startExplicitPair(store, capability: nil)
+            try receive(transport, ["type": "glasses_ready", "sid": "legacy"])
+            XCTAssertFalse(ready(store), "readiness waits, bounded, for pairing_info")
+
+            runMainLoop { self.ready(store) }
+            XCTAssertTrue(ready(store), "no pairing_info: legacy firmware, reported ready")
+            let types = transport.commands.compactMap { $0["type"] as? String }
+            XCTAssertFalse(types.contains("pair_select"))
+        }
+    }
+
+    func testUnknownCapabilityWithASecurePairingInfoFollowsTheSecureRule() throws {
+        try withPairingTransport { transport, _, store in
+            var failures = 0
+            let sink = Bridge.addEventSink { event, _ in
+                if event == "pair_failure" { failures += 1 }
+            }
+            defer { Bridge.removeEventSink(sink) }
+            startExplicitPair(store, capability: nil)
+            try receive(transport, ["type": "glasses_ready", "sid": "secure"])
+            XCTAssertFalse(ready(store))
+
+            try receive(transport, [
+                "type": "pairing_info", "secure_pairing_capable": true, "owner_committed": false,
+                "protocol_version": 4,
+            ])
+            XCTAssertFalse(ready(store), "secure firmware: ready only after the owner commit")
+            let types = transport.commands.compactMap { $0["type"] as? String }
+            XCTAssertEqual(types.filter { $0 == "pair_select" }.count, 1)
+
+            // The unknown-capability wait no longer applies.
+            RunLoop.main.run(until: Date().addingTimeInterval(0.1))
+            XCTAssertFalse(ready(store))
+
+            try receive(transport, [
+                "type": "pairing_info", "secure_pairing_capable": true, "owner_committed": true,
+                "protocol_version": 4,
+            ])
+            XCTAssertTrue(ready(store))
+            XCTAssertEqual(failures, 0)
+        }
+    }
+
+    func testUnknownCapabilityWithALegacyPairingInfoIsReadyAtOnce() throws {
+        try withPairingTransport { transport, _, store in
+            startExplicitPair(store, capability: nil)
+            try receive(transport, ["type": "glasses_ready", "sid": "legacy"])
+            XCTAssertFalse(ready(store))
+            try receive(transport, ["type": "pairing_info", "had_previous_bond": false])
+            XCTAssertTrue(ready(store))
+        }
+    }
+
+    func testTheSelectedRowDecidesTheSecureRuleNotTheSession() throws {
+        try withPairingTransport { transport, _, store in
+            // The row listed legacy firmware: no owner-commit wait and no pair_select, even if
+            // the glasses then report secure firmware.
+            startExplicitPair(store, capability: false)
+            try receive(transport, ["type": "pairing_info", "secure_pairing_capable": true, "protocol_version": 4])
+            try receive(transport, ["type": "glasses_ready", "sid": "row_legacy"])
+            XCTAssertTrue(ready(store))
+            XCTAssertFalse(transport.commands.contains { $0["type"] as? String == "pair_select" })
+
+            // A secure row waits for the owner commit.
+            transport.cleanup()
+            let secureTransport = SessionReadinessTransport()
+            DeviceManager.shared.sgc = secureTransport
+            defer { secureTransport.cleanup() }
+            startExplicitPair(store, capability: true)
+            try receive(secureTransport, ["type": "glasses_ready", "sid": "row_secure"])
+            XCTAssertFalse(ready(store))
+            try receive(secureTransport, [
+                "type": "pairing_info", "secure_pairing_capable": true, "owner_committed": true,
+                "protocol_version": 4,
+            ])
+            XCTAssertTrue(ready(store))
+        }
+    }
+
+    func testAReadySessionWithoutPairingInfoClearsTheSecureFirmwareFlag() throws {
+        try withPairingTransport { transport, _, store in
+            transport.secureFirmwareRefreshMs = 50
+            store.set("bluetooth", "mentra_live_secure_firmware", true)
+            store.set("glasses", "fullyBooted", false)
+            try receive(transport, ["type": "glasses_ready", "sid": "rolled_back"])
+            XCTAssertTrue(ready(store))
+            runMainLoop { store.get("bluetooth", "mentra_live_secure_firmware") as? Bool == false }
+            XCTAssertEqual(store.get("bluetooth", "mentra_live_secure_firmware") as? Bool, false)
+        }
+    }
+
+    func testASecurePairingInfoKeepsTheSecureFirmwareFlag() throws {
+        try withPairingTransport { transport, _, store in
+            transport.secureFirmwareRefreshMs = 50
+            store.set("bluetooth", "mentra_live_secure_firmware", false)
+            store.set("glasses", "fullyBooted", false)
+            try receive(transport, ["type": "glasses_ready", "sid": "secure"])
+            try receive(transport, ["type": "pairing_info", "secure_pairing_capable": true, "protocol_version": 4])
+            runMainLoop { store.get("bluetooth", "mentra_live_secure_firmware") as? Bool == true }
+            RunLoop.main.run(until: Date().addingTimeInterval(0.15))
+            XCTAssertEqual(store.get("bluetooth", "mentra_live_secure_firmware") as? Bool, true)
+        }
     }
 
     func testInitialVersionChunkDoesNotStartAnExtraReadinessExchange() throws {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/bluetooth-sdk",
-  "version": "3.4.0-dev.993",
+  "version": "3.4.0-dev.998",
   "description": "SDK for communicating with smart glasses",
   "main": "build/index.js",
   "react-native": "src/index.ts",
@@ -68,6 +68,7 @@
     "!ios/Pods",
     "!ios/Pods/**",
     "plugin/build",
+    "MIGRATION.md",
     "README.md",
     "scripts",
     "src",
@@ -114,7 +115,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@mentra/cloud-protocol": "3.4.0-dev.993"
+    "@mentra/cloud-protocol": "3.4.0-dev.998"
   },
   "devDependencies": {
     "@types/node": "^25.9.3",

package/src/BluetoothSdk.types.ts

@@ -876,9 +876,68 @@ export type StreamKeepAliveRequest = {
   ackId: string
 }
 
+/**
+ * Stable machine-readable `pair_failure` causes. Unknown native codes still typecheck.
+ * `ios_forget_pairing`: iOS holds a stale Bluetooth pairing for these glasses during an
+ * explicit attempt; the user must remove it in Settings > Bluetooth before pairing again.
+ */
+export type PairFailureCode = "ios_forget_pairing" | string
+
 export type PairFailureEvent = {
   type: "pair_failure"
   error: string
+  /** Stable cause, when the SDK can classify the failure. */
+  code?: PairFailureCode
+}
+
+/**
+ * Mentra Live pairing state, owned by the SDK.
+ * - `normal`: no pairing mode in effect; automatic reconnect is allowed.
+ * - `pairing_mode`: the glasses opened a pairing window. Automatic reconnect is paused until
+ *   `endsAtMs` or until the glasses report the window ended. `windowId` identifies the
+ *   window and survives a cold restart.
+ * - `pairing_rejected`: the glasses no longer accept this phone (another phone paired, or repeated
+ *   authentication rejections on secure-pairing firmware). Reconnect has stopped. Render Pair Again.
+ */
+export type MentraLivePairingState =
+  | {state: "normal"}
+  | {state: "pairing_mode"; windowId: number; endsAtMs: number}
+  | {state: "pairing_rejected"}
+
+export type PairingStateChangedEvent = {
+  state: MentraLivePairingState
+}
+
+/**
+ * Whether the user has to do anything to get glasses audio working, decided by the SDK for
+ * every glasses model. Render it; do not add your own audio timers or platform checks.
+ *
+ * - `idle`: no glasses session.
+ * - `not_applicable`: no user step for audio. Android attaches Classic audio from the BLE bond,
+ *   and glasses without Classic audio have nothing to set up.
+ * - `connecting`: the glasses are connected, audio is not, and the SDK still expects audio to
+ *   come up on its own (for example iPhone audio derived from the BLE pair).
+ * - `connected`: Classic audio (A2DP or HFP) to the glasses is up.
+ * - `needs_user`: audio did not come up on its own. Ask the user to connect the glasses in the
+ *   system Bluetooth settings (iPhone: Settings > Bluetooth). The state moves to `connected`
+ *   as soon as audio comes up.
+ */
+export type GlassesAudioSetupState =
+  | {state: "idle"}
+  | {state: "not_applicable"}
+  | {state: "connecting"}
+  | {state: "connected"}
+  | {state: "needs_user"; action: "connect_in_settings"}
+
+export type AudioSetupChangedEvent = {
+  state: GlassesAudioSetupState
+}
+
+export type PairingModeEndedReason = "paired" | "cancelled" | "timeout" | string
+
+export type PairingModeEndedEvent = {
+  reason: PairingModeEndedReason
+  window_id?: number
 }
 
 export type PairingInfoEvent = {
@@ -887,13 +946,27 @@ export type PairingInfoEvent = {
   classic_bond_ready?: boolean
   secure_pairing_capable?: boolean
   protocol_version?: number
+  /** Present when the glasses build includes ownership transfer. */
+  ownership_transfer?: boolean
+  /** True when the glasses derive Classic audio from the LE pair (CTKD), so audio should connect on its own. */
+  auto_audio?: boolean
+  /** True only after a BLE bond committed the owner and the window closed. */
+  owner_committed?: boolean
 }
 
 export type EnteringPairingModeEvent = {
   window_ms: number
+  /** Identifies this pairing window. Also carried in `pairing_mode_ended` and the advertisement. */
+  window_id?: number
   reason?: string
+  /** The glasses kept their bonds when the window opened; they change only if another phone pairs. */
+  owner_retained?: boolean
 }
 
+/**
+ * @deprecated No longer emitted. Observe `pairing_state_changed` (or `GlassesStatus.pairingState`)
+ * and render Pair Again for `pairing_rejected`.
+ */
 export type OwnerReplacedEvent = {
   reason: string
 }
@@ -1182,6 +1255,10 @@ export type BluetoothSdkModuleEvents = {
   pair_failure: (event: PairFailureEvent) => void
   pairing_info: (event: PairingInfoEvent) => void
   entering_pairing_mode: (event: EnteringPairingModeEvent) => void
+  pairing_mode_ended: (event: PairingModeEndedEvent) => void
+  pairing_state_changed: (event: PairingStateChangedEvent) => void
+  audio_setup_changed: (event: AudioSetupChangedEvent) => void
+  /** @deprecated No longer emitted. Use `pairing_state_changed`. */
   owner_replaced: (event: OwnerReplacedEvent) => void
   audio_pairing_needed: (event: AudioPairingNeededEvent) => void
   audio_connected: (event: AudioConnectedEvent) => void
@@ -1346,6 +1423,10 @@ export type BluetoothSdkEventMap = {
   pair_failure: PairFailureEvent
   pairing_info: PairingInfoEvent
   entering_pairing_mode: EnteringPairingModeEvent
+  pairing_mode_ended: PairingModeEndedEvent
+  pairing_state_changed: PairingStateChangedEvent
+  audio_setup_changed: AudioSetupChangedEvent
+  /** @deprecated No longer emitted. Use `pairing_state_changed`. */
   owner_replaced: OwnerReplacedEvent
   audio_pairing_needed: AudioPairingNeededEvent
   audio_connected: AudioConnectedEvent
@@ -1639,6 +1720,10 @@ export interface GlassesStatus {
   micEnabled: boolean
   voiceActivityDetectionEnabled: boolean
   bluetoothClassicConnected: boolean
+  /** iOS: an HFP input is available or a matching Bluetooth output is active. Android: same as `bluetoothClassicConnected`. */
+  bluetoothClassicProfilesConnected: boolean
+  /** iOS: a matching Bluetooth output is the active audio route. Android: same as `bluetoothClassicConnected`. */
+  bluetoothAudioRouted: boolean
   signalStrength: number
   /** Milliseconds since epoch when signalStrength was last refreshed by the phone BLE stack. */
   signalStrengthUpdatedAt: number
@@ -1653,6 +1738,10 @@ export interface GlassesStatus {
   leftMacAddress: string
   rightMacAddress: string
   buildNumber: string
+  /** Mentra Live pairing state owned by the SDK. Absent on other models. */
+  pairingState?: MentraLivePairingState
+  /** Audio setup state owned by the SDK, on every model. See `GlassesAudioSetupState`. */
+  audioSetup?: GlassesAudioSetupState
   /** Glasses System.currentTimeMillis() from last version_info (clock skew detection). */
   systemTimeMs?: number
   otaVersionUrl: string
@@ -1747,6 +1836,14 @@ export interface ConnectOptions {
    * Android accepts this option as a no-op.
    */
   requiresAncs?: boolean
+  /**
+   * iOS Mentra Live only. When true, CoreBluetooth is asked to bring up the
+   * Classic profiles (A2DP/HFP) after the BLE connection
+   * (CBConnectPeripheralOptionEnableTransportBridgingKey). Defaults to true:
+   * without it the pairing screen waits for an audio route that never appears.
+   * Android accepts this option as a no-op.
+   */
+  enableTransportBridging?: boolean
 }
 
 export type ScanResultsCallback = (devices: Device[]) => void

package/src/_private/BluetoothSdkModule.ts

@@ -361,6 +361,7 @@ const DEFAULT_CONNECT_OPTIONS: Required<ConnectOptions> = {
   saveAsDefault: true,
   cancelExistingConnectionAttempt: true,
   requiresAncs: true,
+  enableTransportBridging: true,
 }
 
 const DEFAULT_SCAN_TIMEOUT_MS = 15_000

package/src/generated/releaseMetadata.ts

@@ -12,9 +12,9 @@ export interface BluetoothSdkReleaseMetadata {
 export const BLUETOOTH_SDK_RELEASE_METADATA: Readonly<BluetoothSdkReleaseMetadata> = Object.freeze({
   "schemaVersion": 1,
   "familyBaseVersion": "3.4.0",
-  "releaseIdentity": "3.4.0-dev.993",
-  "releaseSetId": "mentra-3.4.0-dev.993",
-  "sourceCommit": "7fd0a5cfd9fb3db878f18f3975121c613a4b8fcc",
-  "otaManifestUrl": "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.4.0/mentra-live-ota-3.4.0-dev.993.json",
-  "otaManifestSha256": "fb9e951467dcb09ceca5e7b3c244f6e7c21f0fd61efadbf3c06d59134e272345"
+  "releaseIdentity": "3.4.0-dev.998",
+  "releaseSetId": "mentra-3.4.0-dev.998",
+  "sourceCommit": "c77108af50fcaabe3f2c1464b2a5d649a30e337b",
+  "otaManifestUrl": "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.4.0/mentra-live-ota-3.4.0-dev.998.json",
+  "otaManifestSha256": "8c797478019499beb9a637bf418ff6586fd974115f712dfb51c7a96f6e08151c"
 })

package/src/index.ts

@@ -47,6 +47,9 @@ const PUBLIC_EVENT_NAMES = new Set<BluetoothSdkEventName>([
   "pair_failure",
   "pairing_info",
   "entering_pairing_mode",
+  "pairing_mode_ended",
+  "pairing_state_changed",
+  "audio_setup_changed",
   "owner_replaced",
   "audio_pairing_needed",
   "audio_connected",
@@ -266,9 +269,16 @@ export type {
   OtaUpdateInfo,
   ReleaseChangelog,
   MtkUpdateCompleteEvent,
+  PairFailureCode,
   PairFailureEvent,
   PairingInfoEvent,
   EnteringPairingModeEvent,
+  MentraLivePairingState,
+  PairingModeEndedEvent,
+  PairingModeEndedReason,
+  PairingStateChangedEvent,
+  GlassesAudioSetupState,
+  AudioSetupChangedEvent,
   OwnerReplacedEvent,
   PhotoCaptureMetadata,
   PhotoResolvedConfig,