@mentra/bluetooth-sdk 3.2.1-dev.311 → 3.2.1

package/ios/Tests/G2ConnectionSessionTests.swift

@@ -0,0 +1,172 @@
+@testable import MentraBluetoothSDK
+import XCTest
+
+final class G2ConnectionSessionTests: XCTestCase {
+    func testEitherArmAloneCannotStartAuthenticationOrBecomeReady() {
+        for side in G2ConnectionSession.Side.allCases {
+            var session = G2ConnectionSession()
+            session.initialize(side)
+            XCTAssertNil(session.beginAuthentication())
+            session.authenticated(side, success: true)
+            session.completeSetup(generation: session.generation)
+            XCTAssertFalse(session.isReady)
+        }
+    }
+
+    func testReadinessWaitsForBothAuthenticationResponsesAndCompletedSetup() throws {
+        for completeSetupFirst in [false, true] {
+            var session = G2ConnectionSession()
+            session.initialize(.right)
+            session.initialize(.left)
+            let generation = try XCTUnwrap(session.beginAuthentication())
+            XCTAssertNil(session.beginAuthentication(), "Duplicate service callbacks must not restart setup")
+            if completeSetupFirst { session.completeSetup(generation: generation) }
+            session.authenticated(.left, success: true)
+            session.authenticated(.right, success: false)
+            XCTAssertFalse(session.isReady)
+            session.authenticated(.right, success: true)
+            XCTAssertEqual(session.isReady, completeSetupFirst)
+            session.completeSetup(generation: generation)
+            XCTAssertTrue(session.isReady)
+        }
+    }
+
+    func testDisconnectRetiresAuthenticationAndSuspendedSetup() throws {
+        var session = G2ConnectionSession()
+        session.initialize(.left)
+        session.initialize(.right)
+        let oldGeneration = try XCTUnwrap(session.beginAuthentication())
+        session.authenticated(.left, success: true)
+        session.reset()
+        session.authenticated(.right, success: true)
+        session.completeSetup(generation: oldGeneration)
+        XCTAssertFalse(session.isReady)
+
+        session.initialize(.left)
+        session.initialize(.right)
+        let newGeneration = try XCTUnwrap(session.beginAuthentication())
+        session.authenticated(.left, success: true)
+        session.authenticated(.right, success: true)
+        session.completeSetup(generation: oldGeneration)
+        XCTAssertFalse(session.isReady, "Old setup cannot complete the replacement attempt")
+        session.completeSetup(generation: newGeneration)
+        XCTAssertTrue(session.isReady)
+    }
+
+    func testAttemptDeadlineCoversBothPartialPairsAndIncompleteAuthentication() throws {
+        for sides: [G2ConnectionSession.Side] in [[], [.left], [.right], [.left, .right]] {
+            var session = G2ConnectionSession()
+            for side in sides {
+                session.initialize(side)
+            }
+            _ = session.beginAuthentication()
+            let attempt = session.generation
+            XCTAssertTrue(session.needsRecovery(attempt: attempt))
+            session.reset()
+            XCTAssertFalse(session.needsRecovery(attempt: attempt), "A retired deadline cannot reset a new attempt")
+        }
+        var ready = G2ConnectionSession()
+        ready.initialize(.left)
+        ready.initialize(.right)
+        let attempt = try XCTUnwrap(ready.beginAuthentication())
+        ready.authenticated(.left, success: true)
+        ready.authenticated(.right, success: true)
+        ready.completeSetup(generation: attempt)
+        XCTAssertFalse(ready.needsRecovery(attempt: attempt))
+    }
+
+    func testCachedArmsCanReconnectIndependentlyWithoutAdvertisements() {
+        let left = UUID(), right = UUID()
+        XCTAssertEqual(target(left, left: left), .left)
+        XCTAssertEqual(target(right, right: right), .right)
+        XCTAssertNil(target(UUID(), left: left, right: right))
+        XCTAssertNil(target(right, left: right, right: right), "Ambiguous cache must not bind one arm twice")
+    }
+
+    func testOnlySelectedSerialCanFillTheMissingArm() {
+        let id = UUID()
+        XCTAssertEqual(target(id, name: "Even G2_32_L_123456", serial: "S211SELECTED"), .left)
+        XCTAssertNil(target(id, name: "Even G2_32_L_123456", serial: "S211OTHER"))
+        XCTAssertNil(target(id, name: "Even G2_32_R_123456"))
+        XCTAssertNil(target(id, right: id, searchID: "NOT_SET"))
+        XCTAssertNil(target(id, right: id, searchID: ""))
+    }
+
+    private func target(
+        _ id: UUID, name: String? = nil, serial: String? = nil,
+        left: UUID? = nil, right: UUID? = nil, searchID: String = "S211SELECTED"
+    ) -> G2ConnectionSession.Side? {
+        G2ConnectionTarget.side(identifier: id, name: name, advertisedSerial: serial,
+                                searchID: searchID, leftUUID: left, rightUUID: right)
+    }
+}
+
+@MainActor
+final class G2PrematureReadinessTests: XCTestCase {
+    func testSystemExitAndTouchBeforePairInitializationDoNotPublishReady() {
+        let store = DeviceStore.shared.store
+        let connected = store.get("glasses", "connected")
+        let booted = store.get("glasses", "fullyBooted")
+        defer {
+            if let connected { store.set("glasses", "connected", connected) }
+            if let booted { store.set("glasses", "fullyBooted", booted) }
+        }
+        store.set("glasses", "connected", false)
+        store.set("glasses", "fullyBooted", false)
+        let g2 = G2()
+        // SendDeviceEvent.SysEvent { eventType: systemExit }, as observed on the right arm.
+        g2.handleTouchEvent(Data([0x1A, 0x02, 0x08, 0x07]))
+        XCTAssertEqual(store.get("glasses", "connected") as? Bool, false)
+        XCTAssertEqual(store.get("glasses", "fullyBooted") as? Bool, false)
+        g2.handleTouchEvent(Data([0x1A, 0x02, 0x08, 0x00]))
+        XCTAssertEqual(store.get("glasses", "connected") as? Bool, false)
+        XCTAssertEqual(store.get("glasses", "fullyBooted") as? Bool, false)
+    }
+}
+
+final class G2PartialConnectionTests: XCTestCase {
+    func testEitherPartialLinkStaysQuietForThreeSeconds() {
+        for leftConnected in [false, true] {
+            var progress = G2PartialConnection()
+            progress.update(leftConnected: leftConnected, rightConnected: !leftConnected, now: 10)
+            XCTAssertNil(progress.visibleMissingSide(now: 10))
+            XCTAssertNil(progress.visibleMissingSide(now: 12.999))
+            // Duplicate observations must not restart the grace period.
+            progress.update(leftConnected: leftConnected, rightConnected: !leftConnected, now: 12)
+            XCTAssertEqual(progress.visibleMissingSide(now: 13), leftConnected ? .right : .left)
+            XCTAssertEqual(progress.timeoutError, leftConnected ? "errors:g2RightArmUnavailable" : "errors:g2LeftArmUnavailable")
+        }
+    }
+
+    func testNormalSequentialPairingAndDisconnectedStateNeverShowMissingArm() {
+        var progress = G2PartialConnection()
+        progress.update(leftConnected: false, rightConnected: true, now: 10)
+        progress.update(leftConnected: true, rightConnected: true, now: 12)
+        XCTAssertNil(progress.visibleMissingSide(now: 15))
+        progress.update(leftConnected: false, rightConnected: false, now: 16)
+        XCTAssertNil(progress.visibleMissingSide(now: 20))
+        XCTAssertEqual(progress.timeoutError, "errors:g2ConnectionTimedOut")
+    }
+
+    func testPeerArrivalClearsVisibleNoticeAndNewPartialLinkGetsOwnGracePeriod() {
+        var progress = G2PartialConnection()
+        progress.update(leftConnected: true, rightConnected: false, now: 10)
+        XCTAssertEqual(progress.visibleMissingSide(now: 13), .right)
+        progress.update(leftConnected: true, rightConnected: true, now: 14)
+        XCTAssertNil(progress.visibleMissingSide(now: 14))
+        progress.update(leftConnected: false, rightConnected: true, now: 15)
+        XCTAssertNil(progress.visibleMissingSide(now: 17))
+        XCTAssertEqual(progress.visibleMissingSide(now: 18), .left)
+        progress = G2PartialConnection()
+        XCTAssertNil(progress.visibleMissingSide(now: 100))
+    }
+
+    func testStatusSnapshotAndUpdateCarryNoticeAndDisconnectClearsIt() throws {
+        let status = GlassesStatus(values: ["g2MissingArm": "left"])
+        XCTAssertEqual(status.dictionary["g2MissingArm"] as? String, "left")
+        XCTAssertEqual(GlassesStatusUpdate(values: ["g2MissingArm": "right"]).dictionary["g2MissingArm"] as? String, "right")
+        let disconnected = status.disconnected().dictionary
+        XCTAssertTrue(disconnected["g2MissingArm"] is NSNull)
+        XCTAssertNoThrow(try JSONSerialization.data(withJSONObject: disconnected))
+    }
+}

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/MentraLiveFileTransferSessionTests.swift

@@ -0,0 +1,47 @@
+import Foundation
+@testable import MentraBluetoothSDK
+import XCTest
+
+final class MentraLiveFileTransferSessionTests: XCTestCase {
+    func testDynamicPayloadUsesTrueSizeEvenWhenDivisibleBy400() {
+        for pack in [244, 474, 800] {
+            var session = MentraLiveFileTransferSession(fileName: "photo", fileSize: 80000, flags: 2)
+            session.recalculateTotalPackets(actualPackSize: pack)
+            XCTAssertEqual(session.totalPackets, (80000 + pack - 1) / pack)
+            for index in 0 ..< session.totalPackets {
+                XCTAssertTrue(session.addPacket(index, data: Data(repeating: 7, count: min(pack, 80000 - index * pack))))
+            }
+            XCTAssertTrue(session.isComplete)
+            XCTAssertEqual(session.assembleFile()?.count, 80000)
+        }
+    }
+
+    func testLegacyInflatedSizeAndLargeUnflaggedPayloads() {
+        // Old senders inflate the header length for small packs, including
+        // the short final pack. Flag 1 only enables batched ACKs.
+        for (pack, headerSize, actualSize, packets) in [(221, 80000, 43982, 200), (400, 80000, 79777, 200), (800, 80000, 80000, 100)] {
+            var session = MentraLiveFileTransferSession(fileName: "photo", fileSize: headerSize, flags: 1)
+            session.recalculateTotalPackets(actualPackSize: pack)
+            XCTAssertEqual(session.totalPackets, packets)
+            let source = Data((0 ..< actualSize).map { UInt8($0 % 251) })
+            for index in (0 ..< packets).reversed() {
+                let start = index * pack
+                XCTAssertTrue(session.addPacket(index, data: source.subdata(in: start ..< min(start + pack, actualSize))))
+            }
+            XCTAssertTrue(session.isComplete)
+            XCTAssertEqual(session.assembleFile(), source)
+        }
+    }
+
+    func testMalformedOrDuplicatePacketsCannotCompleteFile() {
+        var session = MentraLiveFileTransferSession(fileName: "photo", fileSize: 1000, flags: 2)
+        session.recalculateTotalPackets(actualPackSize: 800)
+        XCTAssertFalse(session.addPacket(0, data: Data(count: 799)))
+        XCTAssertFalse(session.addPacket(2, data: Data(count: 200)))
+        XCTAssertTrue(session.addPacket(1, data: Data(count: 200)))
+        XCTAssertFalse(session.isComplete)
+        XCTAssertFalse(session.addPacket(1, data: Data(count: 200)))
+        XCTAssertTrue(session.addPacket(0, data: Data(count: 800)))
+        XCTAssertEqual(session.assembleFile()?.count, 1000)
+    }
+}

package/ios/Tests/MentraLiveReconnectPolicyTests.swift

@@ -0,0 +1,58 @@
+@testable import MentraBluetoothSDK
+import XCTest
+
+final class MentraLiveReconnectPolicyTests: XCTestCase {
+    private func decide(
+        isKilled: Bool = false,
+        pairingYieldActive: Bool = false,
+        bluetoothPoweredOn: Bool = true,
+        peripheralName: String? = "Mentra_Live_D910",
+        savedDeviceName: String? = "Mentra_Live_D910"
+    ) -> Bool {
+        MentraLiveConnectionAttemptPolicy.shouldReconnectDirectly(
+            isKilled: isKilled,
+            pairingYieldActive: pairingYieldActive,
+            bluetoothPoweredOn: bluetoothPoweredOn,
+            peripheralName: peripheralName,
+            savedDeviceName: savedDeviceName
+        )
+    }
+
+    func testRemembersLostGlassesWithPendingConnect() {
+        XCTAssertTrue(decide())
+    }
+
+    func testDoesNotReconnectAfterUserDisconnectOrKill() {
+        XCTAssertFalse(decide(isKilled: true))
+    }
+
+    func testYieldsToAnotherPhonePairing() {
+        XCTAssertFalse(decide(pairingYieldActive: true))
+    }
+
+    func testFallsBackWhenBluetoothIsOff() {
+        XCTAssertFalse(decide(bluetoothPoweredOn: false))
+    }
+
+    func testDoesNotReconnectForgottenOrDifferentGlasses() {
+        XCTAssertFalse(decide(savedDeviceName: nil))
+        XCTAssertFalse(decide(savedDeviceName: "Mentra_Live_023B"))
+        XCTAssertFalse(decide(peripheralName: nil))
+        XCTAssertFalse(decide(peripheralName: "", savedDeviceName: ""))
+    }
+
+    func testFailureThenFallbackLeavesTheStaleSettleTimerPowerless() {
+        var pending = MentraLivePendingReconnect()
+        let first = pending.arm()
+        XCTAssertTrue(pending.owns(first))
+
+        // didFailToConnect or a fallback connectToDevice clears tracking.
+        pending.clear()
+        XCTAssertFalse(pending.owns(first))
+
+        // A later re-arm does not revive the earlier attempt's timer.
+        let second = pending.arm()
+        XCTAssertFalse(pending.owns(first))
+        XCTAssertTrue(pending.owns(second))
+    }
+}

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,181 @@
+@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 testNativeTakeoverReplaysWithoutNewHostFrame() {
+        let session = NimoCanvasSession(); connected(session)
+        XCTAssertEqual(sentKey(session.nativeApp(0, entered: true)), 1)
+        XCTAssertTrue(session.nativeApp(0, entered: true).isEmpty)
+        guard case let .send(_, frame, _) = ack(session, 1).first else { return XCTFail() }
+        XCTAssertEqual(frame, a)
+        XCTAssertTrue(session.nativeApp(0xFD, entered: false).isEmpty)
+        XCTAssertEqual(sentKey(ack(session, 4)), 1)
+    }
+
+    func testTakeoverDuringUpdateReplaysIdenticalFrameAfterRelaunch() {
+        let session = NimoCanvasSession()
+        _ = session.offer(a, scope: "app:1"); _ = session.readiness(true)
+        XCTAssertEqual(sentKey(ack(session, 1)), 4)
+        XCTAssertTrue(session.nativeApp(0, entered: true).isEmpty)
+        XCTAssertEqual(sentKey(ack(session, 4)), 1)
+        guard case let .send(_, frame, _) = ack(session, 1).first else { return XCTFail("Missing replay Update") }
+        XCTAssertEqual(frame, a)
+        XCTAssertTrue(ack(session, 4).isEmpty)
+        XCTAssertTrue(session.offer(a, scope: "app:1").isEmpty)
+    }
+
+    func testStartupStockUiPreservesReconnectScene() {
+        let session = NimoCanvasSession(); connected(session)
+        session.disconnected()
+        XCTAssertTrue(session.nativeApp(0, entered: true).isEmpty)
+        XCTAssertTrue(session.activate().isEmpty)
+        XCTAssertEqual(sentKey(session.readiness(true)), 1)
+        guard case let .send(_, frame, _) = ack(session, 1).first else { return XCTFail() }
+        XCTAssertEqual(frame, a)
+    }
+
+    func testActivationEntersBlankCanvasBeforeAnyMiniapp() {
+        let session = NimoCanvasSession()
+        XCTAssertTrue(session.activate().isEmpty)
+        XCTAssertEqual(sentKey(session.readiness(true)), 1)
+        guard case let .send(_, frame, _) = ack(session, 1).first else { return XCTFail() }
+        XCTAssertEqual(frame, Data([0, 0, 1]))
+    }
+
+    func testExplicitExitStopsRestorationUntilAnotherConnection() {
+        let session = NimoCanvasSession(); connected(session)
+        XCTAssertEqual(sentKey(session.exit()), 3)
+        XCTAssertTrue(session.nativeApp(0, entered: true).isEmpty)
+        XCTAssertTrue(ack(session, 3).isEmpty)
+        XCTAssertTrue(session.nativeApp(0xFD, entered: false).isEmpty)
+        session.disconnected()
+        _ = session.activate()
+        XCTAssertEqual(sentKey(session.readiness(true)), 1)
+    }
+
+    func testSuccessfulUpdateRestoresProbeBudgetForNextRecovery() {
+        let session = NimoCanvasSession()
+        _ = session.activate(); _ = session.readiness(true)
+        for episode in 0 ..< 2 {
+            if episode > 0 { XCTAssertEqual(sentKey(session.nativeApp(0, entered: true)), 1) }
+            for _ in 0 ..< 3 {
+                _ = ack(session, 1, status: 7)
+                XCTAssertEqual(sentKey(session.retryNotReady()), 1)
+            }
+            XCTAssertEqual(sentKey(ack(session, 1)), 4)
+            XCTAssertTrue(ack(session, 4).isEmpty)
+        }
+    }
+
+    func testProbesAreBoundedAndHeartbeatCanStillRecover() {
+        let session = NimoCanvasSession()
+        _ = session.activate(); _ = session.readiness(true)
+        for _ in 0 ..< 3 {
+            _ = ack(session, 1, status: 7)
+            XCTAssertEqual(sentKey(session.retryNotReady()), 1)
+        }
+        _ = ack(session, 1, status: 7)
+        XCTAssertTrue(session.retryNotReady().isEmpty)
+        XCTAssertEqual(sentKey(session.readiness(true, confirmed: true)), 1)
+    }
+}