@mentra/bluetooth-sdk 3.3.0-dev.316 → 3.3.0-dev.320

package/ios/Source/sgcs/SGCManager.swift

@@ -96,6 +96,10 @@ protocol SGCManager {
 
     // MARK: - Display Control
 
+    /// Full-frame adapters preserve the active scene instead of showing temporary overlays.
+    var showBrightnessConfirmation: Bool { get }
+    var showConnectionConfirmation: Bool { get }
+    var sceneHandoffRequiresClear: Bool { get }
     func setBrightness(_ level: Int, autoMode: Bool)
     func clearDisplay()
     func sendText(_ text: String) async
@@ -254,6 +258,18 @@ protocol SGCManager {
 /// doesn't seem to work for concurrency reasons :(
 /// we can make read-only getters for convienence though:
 extension SGCManager {
+    var showBrightnessConfirmation: Bool {
+        true
+    }
+
+    var showConnectionConfirmation: Bool {
+        true
+    }
+
+    var sceneHandoffRequiresClear: Bool {
+        true
+    }
+
     var isMicSuspendedForAudio: Bool {
         false
     }

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/Tests/DashboardRenderingTests.swift

@@ -15,6 +15,36 @@ final class DashboardRenderingTests: XCTestCase {
         return (manager, display)
     }
 
+    func testFullFrameDashboardHandoffDoesNotClearActiveScene() async {
+        let (manager, display) = setupDashboard()
+        display.sceneHandoffRequiresClear = false
+        await manager.setDashboardContent("new dashboard")
+        XCTAssertEqual(display.cleanupCount, 0)
+        XCTAssertEqual(display.clearDisplayCount, 0)
+        XCTAssertEqual(display.texts.count, 1)
+        XCTAssertTrue(display.texts[0].hasSuffix("new dashboard"))
+    }
+
+    func testHiddenSceneHandoffCannotClearMainView() async {
+        let (manager, display) = setupDashboard()
+        DeviceStore.shared.apply("glasses", "headUp", false)
+        manager.displayEvent([
+            "view": "dashboard",
+            "scene": ["appId": "replacement", "sceneEpoch": 2, "elements": [[String: Any]]()],
+        ])
+        await Task.yield()
+        XCTAssertEqual(display.cleanupCount, 0)
+        XCTAssertEqual(display.clearDisplayCount, 0)
+        XCTAssertTrue(display.scenes.isEmpty)
+    }
+
+    func testNimoOptsOutOfDestructiveTransientOverlays() {
+        let device: SGCManager = Nimo()
+        XCTAssertFalse(device.sceneHandoffRequiresClear)
+        XCTAssertFalse(device.showBrightnessConfirmation)
+        XCTAssertFalse(device.showConnectionConfirmation)
+    }
+
     func testSetterWaitsForCleanupAndLatestContentWins() async {
         let (manager, display) = setupDashboard()
         var firstReturned = false
@@ -74,6 +104,7 @@ final class DashboardRenderingTests: XCTestCase {
 private final class PausedDisplay: SGCManager {
     var type = "Test display"
     let hasMic = false
+    var sceneHandoffRequiresClear = true
     let cleanupStarted = XCTestExpectation(description: "cleanup suspended")
     var cleanupCount = 0
     var clearDisplayCount = 0

package/ios/Tests/G2TextTests.swift

@@ -0,0 +1,10 @@
+@testable import MentraBluetoothSDK
+import XCTest
+
+final class G2TextTests: XCTestCase {
+    func testBlankRowsAreEncodedOnlyAtTheDeviceBoundary() {
+        XCTAssertEqual(G2Text.containerContent("hello\n\nworld\n"), "hello\n\u{200B}\nworld\n\u{200B}")
+        XCTAssertEqual(G2Text.containerContent(""), " ")
+        XCTAssertEqual(G2Text.containerContent("hello\nworld"), "hello\nworld")
+    }
+}

package/ios/Tests/NimoCanvasCodecTests.swift

@@ -0,0 +1,204 @@
+import CoreGraphics
+import ImageIO
+@testable import MentraBluetoothSDK
+import XCTest
+import zlib
+
+final class NimoCanvasCodecTests: XCTestCase {
+    private func hex(_ data: Data) -> String {
+        data.map { String(format: "%02X", $0) }.joined()
+    }
+
+    private func packet(_ hex: String) -> Data {
+        let chars = Array(hex)
+        return Data(stride(from: 0, to: chars.count, by: 2).map { UInt8(String(chars[$0 ... $0 + 1]), radix: 16)! })
+    }
+
+    func testVendorGoldenPacketsMatchAndroid() throws {
+        let frame = try NimoCanvasCodec.replace([
+            NimoCanvasCodec.rectangle(20, 20, 120, 50, stroke: 2, radius: 8),
+            NimoCanvasCodec.label("Hello Glass", 160, 30, 300, 40, font: 2),
+        ])
+        XCTAssertEqual(try hex(NimoCanvasCodec.frames(key: 4, content: frame, writeCapacity: 512)[0]),
+                       "BF003600F72D000007043200FD000000020001010C0014001400780032000208FF00031900A0001E002C012800000002FF0B0048656C6C6F20476C617373")
+        XCTAssertEqual(try hex(NimoCanvasCodec.frames(key: 1, writeCapacity: 512)[0]), "BF000600F5E4000007010200FD00")
+        XCTAssertEqual(try hex(NimoCanvasCodec.frames(key: 3, writeCapacity: 512)[0]), "BF00050086E4000007030100FD")
+    }
+
+    func testPolarityOddPaddingAndImageHeader() throws {
+        let gray = Data([0, 85, 170, 255, 255])
+        XCTAssertEqual(try NimoCanvasCodec.pack2(gray), Data([0xE4, 0x3F]))
+        let bitmap = try NimoCanvasCodec.bitmap(0, 0, 5, 1, gray: gray)
+        XCTAssertEqual(bitmap.payload[10], 1)
+        XCTAssertEqual(bitmap.payload[19], 2)
+        XCTAssertEqual(bitmap.payload[20], 3)
+        XCTAssertEqual(bitmap.payload[21], 2)
+        XCTAssertEqual(bitmap.payload.dropFirst(29), Data([0x82, 0xE4, 0x3F]))
+    }
+
+    func testRleRunAndLiteralBoundariesRoundTrip() throws {
+        for size in [1, 2, 3, 126, 127, 128, 254, 27500] {
+            for source in [Data(repeating: 33, count: size), Data((0 ..< size).map { UInt8($0 % 251) })] {
+                let encoded = try [UInt8](NimoCanvasCodec.rle(source))
+                var decoded = Data(), i = 0
+                while i < encoded.count {
+                    let tag = encoded[i]; i += 1
+                    let count = Int(tag & 127)
+                    XCTAssertGreaterThan(count, 0)
+                    if tag & 128 != 0 { decoded.append(contentsOf: encoded[i ..< i + count]); i += count }
+                    else { decoded.append(Data(repeating: encoded[i], count: count)); i += 1 }
+                }
+                XCTAssertEqual(decoded, source)
+            }
+        }
+    }
+
+    func testZlibImageInflatesToPackedPixels() throws {
+        let pixels: [UInt8] = (0 ..< 32768).map { index in
+            let tone = ((index / 17) ^ (index / 43)) % 4
+            return UInt8(tone * 85)
+        }
+        let gray = Data(pixels)
+        let bitmap = try NimoCanvasCodec.bitmap(0, 0, 256, 128, gray: gray)
+        XCTAssertEqual(bitmap.payload[20], 7)
+        let compressed = Data(bitmap.payload.dropFirst(29))
+        var count: uLong = 8192
+        var output = Data(count: Int(count))
+        let status = output.withUnsafeMutableBytes { dst in
+            compressed.withUnsafeBytes { src in
+                uncompress(dst.bindMemory(to: UInt8.self).baseAddress!, &count,
+                           src.bindMemory(to: UInt8.self).baseAddress!, uLong(compressed.count))
+            }
+        }
+        XCTAssertEqual(status, Z_OK)
+        XCTAssertEqual(output, try NimoCanvasCodec.pack2(gray))
+    }
+
+    func testFragmentationRespectsCoreBluetoothCapacityAndCrc() throws {
+        let content = try NimoCanvasCodec.replace([NimoCanvasCodec.label(String(repeating: "X", count: 2048), 0, 0, 500, 220)])
+        var baseline: Data?
+        for capacity in [20, 64, 185, 244, 512] {
+            let frames = try NimoCanvasCodec.frames(key: 4, content: content, writeCapacity: capacity)
+            var stream = Data()
+            for (index, frame) in frames.enumerated() {
+                XCTAssertLessThanOrEqual(frame.count, capacity)
+                XCTAssertEqual(frame[1], 0)
+                XCTAssertEqual(Int(frame[6]) | Int(frame[7]) << 8, index == frames.count - 1 ? 0 : index + 1)
+                XCTAssertEqual(UInt16(frame[4]) | UInt16(frame[5]) << 8, nimoCrc16(Data(frame.dropFirst(8))))
+                stream += frame.dropFirst(8)
+            }
+            if let baseline { XCTAssertEqual(stream, baseline) } else { baseline = stream }
+        }
+        XCTAssertThrowsError(try NimoCanvasCodec.frames(key: 4, content: content, writeCapacity: 19))
+        XCTAssertThrowsError(try NimoCanvasCodec.frames(key: 4, content: Data(count: 12281), writeCapacity: 512))
+    }
+
+    func testStrictCanvasResponseParsing() {
+        let good = packet("BF000900D87900000704050000FD000000")
+        XCTAssertEqual(NimoCanvasCodec.response(good)?.payload, Data([0, 0xFD, 0, 0, 0]))
+        XCTAssertNil(NimoCanvasCodec.response(good + Data([0])))
+        for index in [0, 1, 2, 4, 6, 8, 10] {
+            var bad = good; bad[index] ^= 1
+            XCTAssertNil(NimoCanvasCodec.response(bad))
+        }
+        let body = Data([7, 4, 1, 0, 7])
+        let statusOnly = NimoFrameCodec.transportHeader(body, needsAck: false) + body
+        XCTAssertEqual(NimoCanvasCodec.response(statusOnly)?.payload, Data([7]))
+    }
+
+    func testUtf8RowsAndGeometryValidation() throws {
+        XCTAssertEqual(try NimoCanvasCodec.label("😀é", 0, 0, 100, 20).textBytes, 6)
+        XCTAssertThrowsError(try NimoCanvasCodec.label("a\0b", 0, 0, 100, 20))
+        XCTAssertThrowsError(try NimoCanvasCodec.label(String(repeating: "é", count: 1025), 0, 0, 100, 20))
+        let rows = try NimoCanvasCodec.textRows("first\n\nthird", 12, 15, 400, 100)
+        XCTAssertEqual(rows.count, 2)
+        XCTAssertEqual(rows.map { $0.payload[2] }, [15, 55])
+        XCTAssertEqual(rows[1].payload[6], 20)
+        XCTAssertThrowsError(try NimoCanvasCodec.rectangle(Int.max, 0, 10, 1))
+        XCTAssertThrowsError(try NimoCanvasCodec.line(0, 0, 500, 219))
+        XCTAssertThrowsError(try NimoCanvasCodec.circle(0, 10, radius: 10))
+        XCTAssertEqual(try NimoCanvasCodec.circle(10, 10, radius: 10).payload.count, 9)
+    }
+
+    func testFrameBudgetsBeforeRasterDecode() throws {
+        XCTAssertEqual(try NimoCanvasCodec.replace([]), Data([0, 0, 1]))
+        let line = try NimoCanvasCodec.line(0, 0, 1, 1)
+        XCTAssertThrowsError(try NimoCanvasCodec.replace(Array(repeating: line, count: 65)))
+        let text = try NimoCanvasCodec.label(String(repeating: "a", count: 2048), 0, 0, 500, 220)
+        XCTAssertThrowsError(try NimoCanvasCodec.replace(Array(repeating: text, count: 5)))
+        let image = SceneElement(id: "image", type: "image", x: 0, y: 0, w: 500, h: 220, text: nil,
+                                 data: "unused", border: 0, radius: 0, change: "unchanged", contentHash: "")
+        var decoded = 0
+        XCTAssertThrowsError(try NimoCanvasCodec.scene([image, image]) { _, _, _ in decoded += 1; return Data() })
+        XCTAssertEqual(decoded, 0)
+        XCTAssertThrowsError(try NimoCanvasCodec.replace([.init(type: 4, payload: Data(count: 12278))]))
+    }
+
+    func testHostFrameReservationBoundsNativeEncoding() throws {
+        var seed: UInt32 = 42
+        func noise(_ count: Int) -> Data {
+            Data((0 ..< count).map { _ in
+                seed = seed &* 1_664_525 &+ 1_013_904_223
+                return UInt8(truncatingIfNeeded: seed >> 24)
+            })
+        }
+        for size in [1, 5, 80, 160, 200] {
+            let image = try NimoCanvasCodec.bitmap(0, 0, size, size, gray: noise(size * size))
+            let packed = (size * size + 3) / 4
+            let reserved = 32 + packed + (packed + 126) / 127
+            XCTAssertLessThanOrEqual(3 + image.payload.count, reserved)
+        }
+        // Retained prefixes of the host's over-budget regression scenes.
+        let rows = try NimoCanvasCodec.textRows(Array(repeating: "row", count: 11).joined(separator: "\n"), 0, 0, 500, 220)
+        XCTAssertLessThanOrEqual(try NimoCanvasCodec.replace(Array(repeating: rows, count: 5).flatMap { $0 }).count, 12280)
+        let images = try [200, 80].map { try NimoCanvasCodec.bitmap(0, 0, $0, $0, gray: noise($0 * $0)) }
+        XCTAssertLessThanOrEqual(try NimoCanvasCodec.replace(images).count, 12280)
+    }
+
+    func testWholeScenePreservesOrderAndIgnoresDiffAnnotations() throws {
+        let text = SceneElement(id: "caption", type: "text", x: 10, y: 20, w: 100, h: 40, text: "hello",
+                                data: nil, border: 2, radius: 3, change: "unchanged", contentHash: "")
+        let expected = try NimoCanvasCodec.replace([
+            NimoCanvasCodec.rectangle(10, 20, 100, 40, stroke: 2, radius: 3),
+            NimoCanvasCodec.label("hello", 10, 20, 100, 20),
+        ])
+        XCTAssertEqual(try NimoCanvasCodec.scene([text]) { _, _, _ in XCTFail("Not an image"); return Data() }, expected)
+    }
+
+    func testImageKindAndDimensionsAreValidatedBeforeDecode() throws {
+        let png = Data([0x89, 0x50, 0x4E, 0x47, 13, 10, 26, 10]) + Data(count: 24)
+        XCTAssertEqual(try NimoCanvasCodec.imageBytes(png.base64EncodedString()), png)
+        XCTAssertThrowsError(try NimoCanvasCodec.imageBytes("data:image/bmp;base64," + png.base64EncodedString()))
+        XCTAssertThrowsError(try NimoCanvasCodec.imageBytes("data:image/jpeg;base64,AAAA"))
+        XCTAssertThrowsError(try NimoCanvasCodec.imageBytes("Qk0"))
+        XCTAssertThrowsError(try NimoCanvasImage.source(png.base64EncodedString()))
+        XCTAssertThrowsError(try NimoCanvasCodec.imageBytes(String(repeating: "a", count: 2_800_001)))
+    }
+
+    func testJpegPixelsAreDecodedForRawAndDataUriInputs() throws {
+        let rgba = Data(repeating: 255, count: 16)
+        let provider = CGDataProvider(data: rgba as CFData)!
+        let image = try XCTUnwrap(CGImage(width: 2, height: 2, bitsPerComponent: 8, bitsPerPixel: 32, bytesPerRow: 8,
+                                          space: CGColorSpaceCreateDeviceRGB(), bitmapInfo: CGBitmapInfo(rawValue: CGImageAlphaInfo.noneSkipLast.rawValue),
+                                          provider: provider, decode: nil, shouldInterpolate: false, intent: .defaultIntent))
+        let bytes = NSMutableData()
+        let destination = try XCTUnwrap(CGImageDestinationCreateWithData(bytes, "public.jpeg" as CFString, 1, nil))
+        CGImageDestinationAddImage(destination, image, nil)
+        XCTAssertTrue(CGImageDestinationFinalize(destination))
+        let raw = (bytes as Data).base64EncodedString()
+        for input in [raw, "data:image/jpeg;base64," + raw] {
+            XCTAssertEqual(try NimoCanvasImage.decode(input, width: 2, height: 2), Data(repeating: 255, count: 4))
+        }
+        XCTAssertThrowsError(try NimoCanvasImage.source("data:image/png;base64," + raw))
+    }
+
+    func testRasterKeepsTopRowAndLuminanceWithoutInversion() throws {
+        // Top row red/green; bottom row blue/white. Match the Android integer luminance formula.
+        let rgba = Data([255, 0, 0, 255, 0, 255, 0, 255, 0, 0, 255, 255, 255, 255, 255, 255])
+        let provider = CGDataProvider(data: rgba as CFData)!
+        let image = try XCTUnwrap(CGImage(width: 2, height: 2, bitsPerComponent: 8, bitsPerPixel: 32, bytesPerRow: 8,
+                                          space: CGColorSpaceCreateDeviceRGB(), bitmapInfo: CGBitmapInfo(rawValue: CGImageAlphaInfo.last.rawValue),
+                                          provider: provider, decode: nil, shouldInterpolate: false, intent: .defaultIntent))
+        XCTAssertEqual(try NimoCanvasImage.grayscale(image, width: 2, height: 2), Data([77, 149, 29, 255]))
+    }
+}

package/ios/Tests/NimoCanvasSessionTests.swift

@@ -0,0 +1,112 @@
+@testable import MentraBluetoothSDK
+import XCTest
+
+final class NimoCanvasSessionTests: XCTestCase {
+    private let a = Data([0, 0, 1])
+    private let b = Data([1, 0, 1])
+    private func ack(_ session: NimoCanvasSession, _ key: Int, status: UInt8 = 0) -> [NimoCanvasSession.Action] {
+        session.response(key: key, payload: status == 0 ? (key == 4 ? Data([0, 0xFD, 0, 0, 0]) : Data([0, 0xFD])) : Data([status]))
+    }
+
+    private func sentKey(_ actions: [NimoCanvasSession.Action]) -> Int? {
+        guard case let .send(key, _, _) = actions.first else { return nil }
+        return key
+    }
+
+    private func connected(_ session: NimoCanvasSession) {
+        XCTAssertTrue(session.offer(a, scope: "app:1").isEmpty)
+        XCTAssertEqual(sentKey(session.readiness(true)), 1)
+        XCTAssertEqual(sentKey(ack(session, 1)), 4)
+        XCTAssertTrue(ack(session, 4).isEmpty)
+    }
+
+    func testReadinessLaunchAndLatestSceneWins() {
+        let session = NimoCanvasSession()
+        XCTAssertTrue(session.offer(a, scope: "app:1").isEmpty)
+        XCTAssertEqual(sentKey(session.readiness(true)), 1)
+        XCTAssertTrue(session.offer(b, scope: "app:1").isEmpty)
+        guard case let .send(key, frame, _) = ack(session, 1).first else { return XCTFail("Missing update") }
+        XCTAssertEqual(key, 4); XCTAssertEqual(frame, b)
+        XCTAssertTrue(ack(session, 4).isEmpty)
+        XCTAssertTrue(session.offer(b, scope: "app:1").isEmpty)
+        XCTAssertEqual(sentKey(session.offer(b, scope: "app:2")), 4)
+    }
+
+    func testForcedReplayAndReconnectDiscardAcceptedState() {
+        let session = NimoCanvasSession(); connected(session)
+        XCTAssertEqual(sentKey(session.offer(a, scope: "app:1", force: true)), 4)
+        _ = ack(session, 4)
+        session.disconnected()
+        XCTAssertEqual(sentKey(session.readiness(true)), 1)
+        XCTAssertEqual(sentKey(ack(session, 1)), 4)
+    }
+
+    func testStatusSevenRequiresFreshReadinessAndBoundsRetries() {
+        let session = NimoCanvasSession()
+        _ = session.offer(a, scope: "app:1"); _ = session.readiness(true)
+        for _ in 0 ..< 3 {
+            XCTAssertEqual(ack(session, 1, status: 7), [.rejected(7)])
+            XCTAssertTrue(session.readiness(true).isEmpty)
+            XCTAssertEqual(sentKey(session.readiness(true, confirmed: true)), 1)
+        }
+        _ = ack(session, 1, status: 7)
+        XCTAssertTrue(session.readiness(true, confirmed: true).isEmpty)
+        XCTAssertTrue(session.readiness(false).isEmpty)
+        XCTAssertEqual(sentKey(session.readiness(true)), 1)
+    }
+
+    func testWrongEchoAndWrongKeyDoNotAdvance() {
+        let session = NimoCanvasSession()
+        _ = session.offer(a, scope: "app:1"); _ = session.readiness(true)
+        XCTAssertTrue(session.response(key: 1, payload: Data([0])).isEmpty)
+        XCTAssertTrue(session.response(key: 1, payload: Data([0, 1])).isEmpty)
+        XCTAssertTrue(ack(session, 4).isEmpty)
+        XCTAssertEqual(sentKey(ack(session, 1)), 4)
+    }
+
+    func testLockedAndRejectedFramesDoNotSpin() {
+        let session = NimoCanvasSession(); connected(session)
+        _ = session.offer(b, scope: "app:1")
+        XCTAssertEqual(ack(session, 4, status: 5), [.rejected(5)])
+        XCTAssertTrue(session.offer(b, scope: "app:1", force: true).isEmpty)
+        XCTAssertEqual(sentKey(session.offer(a, scope: "app:2")), 4)
+        XCTAssertEqual(ack(session, 4, status: 8), [.rejected(8)])
+        XCTAssertTrue(session.readiness(true, confirmed: true).isEmpty)
+        XCTAssertTrue(session.offer(b, scope: "new").isEmpty)
+    }
+
+    func testTimeoutRequiresNewConnectionAndStaleTicketCannotResetIt() {
+        let session = NimoCanvasSession()
+        _ = session.offer(a, scope: "app")
+        guard case let .send(_, _, ticket) = session.readiness(true).first else { return XCTFail() }
+        XCTAssertEqual(session.timeout(ticket), [.reconnect("Canvas ACK timeout; reconnect before reusing a command key")])
+        XCTAssertTrue(ack(session, 1).isEmpty)
+        session.disconnected()
+        XCTAssertEqual(sentKey(session.readiness(true)), 1)
+        XCTAssertTrue(session.timeout(ticket).isEmpty)
+    }
+
+    func testReadinessLossDuringFlightRetiresTransport() {
+        let session = NimoCanvasSession(); connected(session)
+        _ = session.offer(b, scope: "app")
+        XCTAssertEqual(session.readiness(false), [.reconnect("Readiness lost during canvas command")])
+    }
+
+    func testExitReportPreservesNewHostScene() {
+        let session = NimoCanvasSession(); connected(session)
+        XCTAssertEqual(sentKey(session.exit()), 3)
+        _ = session.offer(b, scope: "new")
+        XCTAssertTrue(session.nativeApp(0xFD, entered: false).isEmpty)
+        XCTAssertEqual(sentKey(ack(session, 3)), 1)
+        guard case let .send(_, frame, _) = ack(session, 1).first else { return XCTFail() }
+        XCTAssertEqual(frame, b)
+    }
+
+    func testNativeTakeoverSuppressesReplayUntilHostOffersAgain() {
+        let session = NimoCanvasSession(); connected(session)
+        XCTAssertTrue(session.nativeApp(1, entered: true).isEmpty)
+        XCTAssertTrue(session.readiness(true, confirmed: true).isEmpty)
+        XCTAssertEqual(sentKey(session.offer(b, scope: "new")), 1)
+        XCTAssertEqual(session.nativeApp(1, entered: true), [.reconnect("Native app transition interrupted canvas command")])
+    }
+}

package/ios/Tests/NimoCanvasTransportTests.swift

@@ -0,0 +1,161 @@
+@testable import MentraBluetoothSDK
+import XCTest
+
+private final class NimoTestClock {
+    private final class Job {
+        let time: TimeInterval
+        let task: () -> Void
+        var cancelled = false
+        init(_ time: TimeInterval, _ task: @escaping () -> Void) {
+            self.time = time; self.task = task
+        }
+    }
+
+    private var now: TimeInterval = 0
+    private var jobs: [Job] = []
+    lazy var schedule: NimoScheduler = { [unowned self] delay, task in
+        let job = Job(self.now + delay, task)
+        self.jobs.append(job)
+        return { job.cancelled = true }
+    }
+
+    func advance(_ seconds: TimeInterval = 0) {
+        let end = now + seconds
+        while let job = jobs.filter({ !$0.cancelled && $0.time <= end }).min(by: { $0.time < $1.time }) {
+            jobs.removeAll { $0 === job }
+            now = job.time
+            job.task()
+        }
+        now = end
+    }
+}
+
+final class NimoCanvasTransportTests: XCTestCase {
+    private let frame = Data([0, 0, 1])
+
+    func testEarlyAckOnlyAdvancesAfterFinalWriteCompletes() {
+        let clock = NimoTestClock()
+        var chains: [[Data]] = [], starts: [() -> Void] = [], completes: [() -> Void] = []
+        let canvas = NimoCanvasCoordinator(schedule: clock.schedule, writeCapacity: { 20 }, enqueue: { frames, start, complete in
+            chains.append(frames); starts.append(start); completes.append(complete); return true
+        }, reconnect: { XCTFail($0) }, rejected: { XCTFail("Unexpected rejection \($0)") })
+        canvas.offer(frame, scope: "app")
+        canvas.readiness(true)
+        canvas.response(key: 1, payload: Data([0, 0xFD])) // Before final fragment: ignore.
+        starts[0]()
+        XCTAssertEqual(chains.count, 1)
+        canvas.response(key: 1, payload: Data([0, 0xFD])) // Before GATT callback: buffer.
+        XCTAssertEqual(chains.count, 1)
+        completes[0]()
+        XCTAssertEqual(chains.count, 2)
+        XCTAssertEqual(chains[1][0][9], 4)
+        starts[1](); completes[1]()
+        canvas.response(key: 4, payload: Data([0, 0xFD, 0, 0, 0]))
+        clock.advance(60)
+    }
+
+    func testTimeoutAndOldCompletionCannotAdvanceNewGeneration() {
+        let clock = NimoTestClock()
+        var completions: [() -> Void] = [], reasons: [String] = [], count = 0
+        let canvas = NimoCanvasCoordinator(schedule: clock.schedule, writeCapacity: { 512 }, enqueue: { _, start, complete in
+            count += 1; start(); completions.append(complete); return true
+        }, reconnect: { reasons.append($0) }, rejected: { _ in })
+        canvas.offer(frame, scope: "app"); canvas.readiness(true)
+        clock.advance(45)
+        XCTAssertEqual(reasons.count, 1)
+        canvas.readiness(true)
+        completions[0]()
+        canvas.response(key: 1, payload: Data([0, 0xFD]))
+        XCTAssertEqual(count, 2) // ACK buffered for the new flight until its own write completes.
+        completions[1]()
+        XCTAssertEqual(count, 3)
+        canvas.disconnected()
+    }
+
+    func testQueueWatchdogRetiresRatherThanSkippingFragment() {
+        let clock = NimoTestClock(), connection = NSObject(), characteristic = NSObject()
+        var bytes: [Data] = [], failures: [String] = []
+        let queue = NimoWriteQueue<NSObject>(schedule: clock.schedule, write: { _, data in bytes.append(data); return true }, failure: { failures.append($0) })
+        queue.connected(connection)
+        queue.enqueue(connection, characteristic: characteristic, frames: [Data([1]), Data([2])])
+        clock.advance(3)
+        XCTAssertEqual(bytes, [Data([1])]); XCTAssertEqual(failures, ["GATT write timed out"])
+        queue.written(connection, characteristic: characteristic, success: true)
+        clock.advance(1)
+        XCTAssertEqual(bytes.count, 1)
+    }
+
+    func testQueueRejectsOldPeripheralAndCharacteristicAndPacesWrites() {
+        let clock = NimoTestClock(), old = NSObject(), current = NSObject(), characteristic = NSObject()
+        var count = 0, completed = 0
+        let queue = NimoWriteQueue<NSObject>(schedule: clock.schedule, write: { _, _ in count += 1; return true }, failure: { XCTFail($0) })
+        queue.connected(old)
+        queue.enqueue(old, characteristic: characteristic, frames: [Data([0])])
+        queue.connected(current)
+        queue.enqueue(current, characteristic: characteristic, frames: [Data([1]), Data([2])], completed: { completed += 1 })
+        queue.written(old, characteristic: characteristic, success: true)
+        queue.written(current, characteristic: NSObject(), success: true)
+        clock.advance(0.01)
+        XCTAssertEqual(count, 2)
+        queue.written(current, characteristic: characteristic, success: true)
+        clock.advance(0.004)
+        XCTAssertEqual(count, 2)
+        clock.advance(0.001)
+        XCTAssertEqual(count, 3)
+        queue.written(current, characteristic: characteristic, success: true)
+        clock.advance(0.005)
+        XCTAssertEqual(completed, 1)
+        clock.advance(10)
+    }
+
+    func testGattErrorAbortsRemainingChain() {
+        let clock = NimoTestClock(), connection = NSObject(), characteristic = NSObject()
+        var count = 0, failures = 0
+        let queue = NimoWriteQueue<NSObject>(schedule: clock.schedule, write: { _, _ in count += 1; return true }, failure: { _ in failures += 1 })
+        queue.connected(connection)
+        queue.enqueue(connection, characteristic: characteristic, frames: [Data([1]), Data([2])])
+        queue.written(connection, characteristic: characteristic, success: false)
+        clock.advance(4)
+        XCTAssertEqual(count, 1); XCTAssertEqual(failures, 1)
+    }
+
+    func testLatestOnlyEncoderAndExitFenceRunningResults() {
+        let main = NimoTestClock(), worker = NimoTestClock()
+        var delivered: [Data] = [], encoded = 0
+        let encoder = NimoCanvasEncoder(main: main.schedule, worker: worker.schedule, failure: { XCTFail("\($0)") })
+        encoder.submit(encode: { encoded += 1; return Data([1]) }, deliver: { delivered.append($0) })
+        encoder.submit(encode: { encoded += 1; return Data([2]) }, deliver: { delivered.append($0) })
+        worker.advance()
+        XCTAssertEqual(encoded, 1)
+        encoder.invalidate() // Exit/disconnect while the finished encode awaits Main.
+        main.advance()
+        XCTAssertTrue(delivered.isEmpty)
+        encoder.submit(encode: { Data([3]) }, deliver: { delivered.append($0) })
+        worker.advance(); main.advance()
+        XCTAssertEqual(delivered, [Data([3])])
+    }
+
+    func testCompleteSceneThroughWriteQueueAndBusinessAcks() throws {
+        let clock = NimoTestClock(), connection = NSObject(), characteristic = NSObject()
+        var written: [Data] = []
+        let queue = NimoWriteQueue<NSObject>(schedule: clock.schedule, write: { _, data in written.append(data); return true }, failure: { XCTFail($0) })
+        queue.connected(connection)
+        let canvas = NimoCanvasCoordinator(schedule: clock.schedule, writeCapacity: { 20 }, enqueue: { frames, started, completed in
+            queue.enqueue(connection, characteristic: characteristic, frames: frames, finalStarted: started, completed: completed)
+        }, reconnect: { XCTFail($0) }, rejected: { XCTFail("Rejected \($0)") })
+        let content = try NimoCanvasCodec.replace([NimoCanvasCodec.label("Captions", 0, 0, 500, 20)])
+        canvas.offer(content, scope: "captions:1"); canvas.readiness(true)
+        queue.written(connection, characteristic: characteristic, success: true); clock.advance(0.005)
+        let launchAck = Data([0, 0xFD])
+        canvas.response(key: 1, payload: launchAck)
+        let expected = try NimoCanvasCodec.frames(key: 4, content: content, writeCapacity: 20)
+        for _ in expected {
+            queue.written(connection, characteristic: characteristic, success: true); clock.advance(0.005)
+        }
+        XCTAssertEqual(Array(written.dropFirst()), expected)
+        canvas.response(key: 4, payload: Data([0, 0xFD, 0, 0, 0]))
+        canvas.offer(content, scope: "captions:1")
+        XCTAssertEqual(written.count, expected.count + 1)
+        canvas.disconnected(); queue.reset()
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/bluetooth-sdk",
-  "version": "3.3.0-dev.316",
+  "version": "3.3.0-dev.320",
   "description": "SDK for communicating with smart glasses",
   "main": "build/index.js",
   "react-native": "src/index.ts",
@@ -114,7 +114,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@mentra/cloud-protocol": "3.3.0-dev.316"
+    "@mentra/cloud-protocol": "3.3.0-dev.320"
   },
   "devDependencies": {
     "@types/node": "^25.9.3",

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.3.0",
-  "releaseIdentity": "3.3.0-dev.316",
-  "releaseSetId": "mentra-3.3.0-dev.316",
-  "sourceCommit": "63243ae4b5f55788c3d2a6befedd577f847b53bf",
-  "otaManifestUrl": "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.3.0/mentra-live-ota-3.3.0-dev.316.json",
-  "otaManifestSha256": "9bc74604efb9461b2185ec56e27ab5596b8471dfef76b4932459834d638acb81"
+  "releaseIdentity": "3.3.0-dev.320",
+  "releaseSetId": "mentra-3.3.0-dev.320",
+  "sourceCommit": "09b74eac29a0f25515856bc31ca48fee514537e5",
+  "otaManifestUrl": "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.3.0/mentra-live-ota-3.3.0-dev.320.json",
+  "otaManifestSha256": "217126614245f133053a9c340003bb4d75dc7812271f723d56ed90a855cc3464"
 })