@glassly/bluetooth-sdk 0.1.0-dev.98 → 0.2.8-dev.444

package/ios/Tests/BluetoothSDKTests/G2CfwTextureCacheTests.swift

@@ -19,40 +19,50 @@ final class G2CfwTextureCacheTests: XCTestCase {
         )
     }
 
-    // MARK: - Cache model
+    private func u32(_ v: UInt32) -> [UInt8] {
+        [UInt8(v & 0xFF), UInt8((v >> 8) & 0xFF), UInt8((v >> 16) & 0xFF), UInt8((v >> 24) & 0xFF)]
+    }
+
+    // MARK: - Asset mirror
 
-    func testAllocationsSkipTheZeroGuardAndPatchTheFontTable() throws {
+    func testFontsUploadWholeAsOneAssetWithRelativeGlyphOffsets() throws {
         let cache = G2CfwTextureCache()
         cache.reset(generation: 1)
-        let font = try XCTUnwrap(cache.font(fontSize: 12, cellWidth: 4, lineHeight: 2))
-        // Bytes 0..1 stay zero (invalid-image guard); the table lands at 2.
-        XCTAssertEqual(font.tableOffset, 2)
-
         let raster = Data(repeating: 0xFF, count: 8) // 4×2 white cell
-        XCTAssertTrue(cache.ensureGlyph(font: font, char: UInt8(ascii: "A")) { raster })
-        // Second ensure is a no-op (no duplicate uploads).
-        XCTAssertTrue(cache.ensureGlyph(font: font, char: UInt8(ascii: "A")) { raster })
+        var rasterized = 0
+        let font = try XCTUnwrap(cache.font(fontSize: 12, cellWidth: 4, lineHeight: 2, codes: [65, 66]) { code in
+            rasterized += 1
+            return code == 65 ? raster : nil
+        })
+        XCTAssertEqual(rasterized, 2)
+        XCTAssertEqual(font.glyphs, [65])
+        XCTAssertEqual(font.id, G2CfwTextureCache.hash31("font:12:4x2:ascii"))
+        // asking again is a no-op: same entry, nothing rasterized, nothing uploaded twice
+        XCTAssertTrue(cache.font(fontSize: 12, cellWidth: 4, lineHeight: 2, codes: [65, 66]) { _ in rasterized += 1; return nil } === font)
+        XCTAssertEqual(rasterized, 2)
 
         let payloads = cache.takeUploadPayloads()
         XCTAssertEqual(payloads.count, 1)
-        let payload = payloads[0]
-        // [12] + glyph entry: image right after the 192-byte table (offset
-        // 194), [offset16][len16][w=4][h=2][RLE 8 white pixels = 0x8F] —
-        // + table-patch entry for slot ('A' - 32) pointing at that offset.
-        let glyphOffset = 2 + 96 * 2 // 194
-        let patchOffset = 2 + (Int(UInt8(ascii: "A")) - 32) * 2
-        XCTAssertEqual(Array(payload), [
-            12,
-            UInt8(glyphOffset & 0xFF), UInt8(glyphOffset >> 8), 3, 0, 4, 2, 0x8F,
-            UInt8(patchOffset & 0xFF), UInt8(patchOffset >> 8), 2, 0,
-            UInt8(glyphOffset & 0xFF), UInt8(glyphOffset >> 8),
-        ])
-
+        let p = [UInt8](payloads[0])
+        XCTAssertEqual(Array(p[0 ..< 5]), [37, 0, 0, 0, 0], "the link stamps epoch and request")
+        XCTAssertEqual(p[5], 0)
+        XCTAssertEqual(Array(p[6 ..< 10]), u32(font.id))
+        XCTAssertEqual(p[14], G2CfwTextureCache.kindFont)
+        let total = 96 * 4 + 2 + 1
+        XCTAssertEqual(Array(p[15 ..< 19]), u32(UInt32(total)))
+        XCTAssertEqual(Array(p[19 ..< 23]), u32(0))
+        XCTAssertEqual(Array(p[23 ..< 25]), [UInt8(total & 0xFF), UInt8(total >> 8)])
+        let table = Array(p[25 ..< 25 + 96 * 4])
+        XCTAssertEqual(Array(table[(65 - 32) * 4 ..< (65 - 32) * 4 + 4]), u32(UInt32(96 * 4)), "glyph A right after the table")
+        XCTAssertEqual(Array(table[(66 - 32) * 4 ..< (66 - 32) * 4 + 4]), [0, 0, 0, 0], "absent glyph")
+        XCTAssertEqual(Array(p[25 + 96 * 4 ..< 25 + total]), [4, 2, 0x8F])
         XCTAssertTrue(cache.takeUploadPayloads().isEmpty)
+        // a forgotten font re-uploads
+        cache.forget(assetIds: [font.id])
+        _ = cache.font(fontSize: 12, cellWidth: 4, lineHeight: 2, codes: [65]) { _ in raster }
+        XCTAssertEqual(cache.takeUploadPayloads().count, 1)
         cache.reset(generation: 2)
-        // After a reset the same glyph re-uploads.
-        let font2 = try XCTUnwrap(cache.font(fontSize: 12, cellWidth: 4, lineHeight: 2))
-        XCTAssertTrue(cache.ensureGlyph(font: font2, char: UInt8(ascii: "A")) { raster })
+        _ = cache.font(fontSize: 12, cellWidth: 4, lineHeight: 2, codes: [65]) { _ in raster }
         XCTAssertEqual(cache.takeUploadPayloads().count, 1)
     }
 
@@ -62,34 +72,88 @@ final class G2CfwTextureCacheTests: XCTestCase {
         XCTAssertFalse(cache.noteImageSighting("icon@10x10"))
         XCTAssertTrue(cache.noteImageSighting("icon@10x10"))
         let gray = Data(repeating: 0x80, count: 100)
-        let offset = cache.ensureImage(hash: "icon@10x10", gray: gray, width: 10, height: 10)
-        XCTAssertNotNil(offset)
-        XCTAssertEqual(cache.ensureImage(hash: "icon@10x10", gray: gray, width: 10, height: 10), offset)
+        let id = cache.ensureImage(hash: "icon@10x10", gray: gray, width: 10, height: 10)
+        XCTAssertEqual(id, G2CfwTextureCache.hash31("icon@10x10"))
+        XCTAssertEqual(cache.ensureImage(hash: "icon@10x10", gray: gray, width: 10, height: 10), id)
         XCTAssertNil(cache.ensureImage(hash: "big", gray: Data(count: 300 * 10), width: 300, height: 10))
+        XCTAssertEqual(cache.takeUploadPayloads().count, 1)
+        XCTAssertTrue(cache.holds(assetId: id!))
+    }
+
+    func testStringsAreBoundedAndLargeAssetsAreChunked() {
+        let cache = G2CfwTextureCache()
+        cache.reset(generation: 1)
+        XCTAssertNil(cache.ensureBytes(key: "empty", bytes: []))
+        XCTAssertNil(cache.ensureBytes(key: "nul", bytes: [65, 0]))
+        XCTAssertNil(cache.ensureBytes(key: "long", bytes: [UInt8](repeating: 65, count: 129)))
+        XCTAssertNotNil(cache.ensureBytes(key: "ok", bytes: [UInt8](repeating: 65, count: 128)))
+        let entries = G2CfwTextureCache.putAssetEntries(id: 7, version: 9, kind: 0, data: Data(repeating: 1, count: 20000))
+        XCTAssertEqual(entries.count, 3)
+        var offset = 0
+        for entry in entries {
+            let e = [UInt8](entry)
+            XCTAssertEqual(Array(e[10 ..< 14]), u32(20000))
+            XCTAssertEqual(Array(e[14 ..< 18]), u32(UInt32(offset)))
+            let len = Int(e[18]) | Int(e[19]) << 8
+            XCTAssertEqual(e.count, 20 + len)
+            offset += len
+        }
+        XCTAssertEqual(offset, 20000)
+    }
+
+    func testUploadPayloadsNameTheAssetsTheyPut() throws {
+        let cache = G2CfwTextureCache()
+        cache.reset(generation: 1)
+        var noise = Data(count: 255 * 255)
+        for i in 0 ..< noise.count { noise[i] = UInt8(truncatingIfNeeded: i * 37) }
+        let a = try XCTUnwrap(cache.ensureBytes(key: "a", bytes: [65, 66]))
+        let big = try XCTUnwrap(cache.ensureImage(hash: "noise", gray: noise, width: 255, height: 255))
+        let b = try XCTUnwrap(cache.ensureBytes(key: "b", bytes: [67]))
+        let payloads = cache.takeUploadPayloads()
+        XCTAssertGreaterThan(payloads.count, 1, "the image spans several payloads")
+        let ids = payloads.map(G2CfwTextureCache.assetIds(inUploadPayload:))
+        XCTAssertEqual(Set(ids.joined()), [a, big, b])
+        XCTAssertEqual(ids.first?.first, a)
+        XCTAssertEqual(ids.last?.last, b)
+        XCTAssertEqual(G2CfwTextureCache.assetIds(inUploadPayload: Data([38, 0, 0, 0, 0, 0])), [])
+    }
+
+    func testPredictedOverflowForgetsTheLeastRecentlyUsedAssets() {
+        let cache = G2CfwTextureCache()
+        cache.reset(generation: 1)
+        // 255x255 noisy tiles compress poorly: ~65 KiB each, four fill the store
+        var noise = Data(count: 255 * 255)
+        for i in 0 ..< noise.count { noise[i] = UInt8(truncatingIfNeeded: i * 37) }
+        var ids: [UInt32] = []
+        for i in 0 ..< 5 {
+            ids.append(cache.ensureImage(hash: "n\(i)", gray: noise, width: 255, height: 255)!)
+        }
+        XCTAssertTrue(cache.exhausted)
+        XCTAssertFalse(cache.holds(assetId: ids[0]), "the oldest prediction was dropped")
+        XCTAssertTrue(cache.holds(assetId: ids[4]))
+        XCTAssertLessThanOrEqual(cache.predictedBytes, G2CfwTextureCache.storeSize)
     }
 
     // MARK: - Draw payload wire formats
 
-    func testImageDrawPayloadMatchesMode13Wire() throws {
+    func testImageDrawPayloadMatchesMode19Wire() throws {
         let payload = try XCTUnwrap(
-            G2CfwTextureCache.imageDrawPayload(offset: 0x1234, x: 300, y: 130, options: 0x0F)
+            G2CfwTextureCache.imageDrawPayload(assetId: 0x1234, x: 300, y: -2, options: 0x0F)
         )
-        XCTAssertEqual(Array(payload), [13, 0x34, 0x12, 0x2C, 0x01, 130, 0, 0x0F])
+        XCTAssertEqual(Array(payload), [19, 0x34, 0x12, 0, 0, 0x2C, 0x01, 0xFE, 0xFF, 0x0F])
+        XCTAssertNil(G2CfwTextureCache.imageDrawPayload(assetId: 0, x: 0, y: 0, options: 0))
     }
 
-    func testStringRunPayloadMatchesMode14Wire() throws {
+    func testStringRunPayloadMatchesMode20Wire() throws {
         let chars = Array("Hi".utf8)
         let payload = try XCTUnwrap(G2CfwTextureCache.stringRunPayload(
-            fontTableOffset: 2, x: 40, y: 150, options: 0x0F, chars: chars
+            fontId: 2, x: 40, y: 150, options: 0x0F, chars: chars
         ))
-        XCTAssertEqual(Array(payload), [14, 2, 0, 40, 0, 150, 0, 0x0F, 2] + chars)
+        XCTAssertEqual(Array(payload), [20, 2, 0, 0, 0, 40, 0, 150, 0, 0x0F, 2] + chars)
         // Control/non-ASCII bytes are x-adjust commands on the wire — rejected.
-        XCTAssertNil(G2CfwTextureCache.stringRunPayload(
-            fontTableOffset: 2, x: 0, y: 0, options: 0, chars: [10]
-        ))
-        XCTAssertNil(G2CfwTextureCache.stringRunPayload(
-            fontTableOffset: 2, x: 0, y: 0, options: 0, chars: [200]
-        ))
+        XCTAssertNil(G2CfwTextureCache.stringRunPayload(fontId: 2, x: 0, y: 0, options: 0, chars: [10]))
+        XCTAssertNil(G2CfwTextureCache.stringRunPayload(fontId: 2, x: 0, y: 0, options: 0, chars: [200]))
+        XCTAssertNil(G2CfwTextureCache.stringRunPayload(fontId: 0, x: 0, y: 0, options: 0, chars: chars))
     }
 
     // MARK: - End-to-end mono fast path (actor)
@@ -126,10 +190,10 @@ final class G2CfwTextureCacheTests: XCTestCase {
         )
         let second = try XCTUnwrap(secondResult)
         XCTAssertFalse(second.usedFullFrame)
-        // The changed cells travel as mode-12 uploads + mode-14 runs; no
+        // The changed cells travel as a font-asset PUT + mode-20 runs; no
         // bitmap delta (0x83) should remain for a pure-ASCII grid change.
         XCTAssertFalse(second.uploads.isEmpty)
-        XCTAssertTrue(second.uploads.allSatisfy { $0.first == 12 })
+        XCTAssertTrue(second.uploads.allSatisfy { $0.first == 37 })
         let payload = try XCTUnwrap(second.payload)
         if payload.first == 8 {
             var segments: [UInt8] = []
@@ -141,10 +205,10 @@ final class G2CfwTextureCacheTests: XCTestCase {
                 if pos < bytes.count { segments.append(bytes[pos]) }
                 pos += len
             }
-            XCTAssertTrue(segments.contains(14))
+            XCTAssertTrue(segments.contains(20))
             XCTAssertFalse(segments.contains(0x83))
         } else {
-            XCTAssertEqual(payload.first, 14)
+            XCTAssertEqual(payload.first, 20)
         }
 
         // A lens-unequal window must fall back to plain bitmap deltas.

package/ios/Tests/BluetoothSDKTests/G2CfwTransportTests.swift

@@ -0,0 +1,259 @@
+@testable import BluetoothSDK
+import Foundation
+import XCTest
+import zlib
+
+/// Wire contract of the SID-0xf0 message stream (g2flash message_transport.c,
+/// GLASSLYCFW/31). The probe in g2flash (`send_message_probe.py --dry-run`)
+/// produces the same packets for the same input.
+final class G2CfwTransportTests: XCTestCase {
+    private func inflateRecords(_ records: [Data]) throws -> [Data] {
+        var stream = z_stream()
+        XCTAssertEqual(inflateInit_(&stream, ZLIB_VERSION, Int32(MemoryLayout<z_stream>.size)), Z_OK)
+        defer { inflateEnd(&stream) }
+        var out: [Data] = []
+        for record in records {
+            let flags = record[0]
+            let length = Int(record[1]) | Int(record[2]) << 8
+            XCTAssertEqual(length, record.count - 5)
+            let body = record.subdata(in: 5 ..< record.count)
+            guard flags & G2CfwTransport.flagCompressed != 0 else {
+                out.append(body)
+                continue
+            }
+            // Every compressed record ends in a complete SYNC_FLUSH marker.
+            XCTAssertEqual(Array(body.suffix(4)), [0x00, 0x00, 0xFF, 0xFF])
+            // As the firmware does: a RESET_CONTEXT record starts a fresh inflate stream.
+            if flags & G2CfwTransport.flagResetContext != 0 { XCTAssertEqual(inflateReset(&stream), Z_OK) }
+            var decoded = Data(count: 0x10000)
+
+            var input = body
+            let produced: Int = input.withUnsafeMutableBytes { inRaw in
+                decoded.withUnsafeMutableBytes { outRaw in
+                    stream.next_in = inRaw.bindMemory(to: Bytef.self).baseAddress
+                    stream.avail_in = uInt(body.count)
+                    stream.next_out = outRaw.bindMemory(to: Bytef.self).baseAddress
+                    stream.avail_out = 0x10000
+                    XCTAssertEqual(inflate(&stream, Z_NO_FLUSH), Z_OK)
+                    XCTAssertEqual(stream.avail_in, 0)
+                    return 0x10000 - Int(stream.avail_out)
+                }
+            }
+            out.append(decoded.prefix(produced))
+        }
+        return out
+    }
+
+    func testRecordsShareOneContextAndCarryThePlainCrc() throws {
+        let encoder = G2CfwTransport.Encoder()
+        let first = Data([6] + [UInt8](repeating: 0x00, count: 5000))
+        let second = Data([3, 1, 2, 3, 4, 5, 0] + [UInt8](repeating: 0x1F, count: 300))
+        let r1 = try XCTUnwrap(encoder.record(first, targets: 3))
+        let r2 = try XCTUnwrap(encoder.record(second, targets: 3))
+        // First record resets the context (flag 8); the second continues it.
+        XCTAssertEqual(r1[0], 3 | 4 | 8)
+        XCTAssertEqual(r2[0], 3 | 4)
+        XCTAssertEqual(UInt16(r1[3]) | UInt16(r1[4]) << 8, BinaryCodec.crc16CCITT(first))
+        XCTAssertEqual(UInt16(r2[3]) | UInt16(r2[4]) << 8, BinaryCodec.crc16CCITT(second))
+        XCTAssertLessThan(r1.count, 100) // 5000 zero bytes deflate to a few
+        XCTAssertEqual(try inflateRecords([r1, r2]), [first, second])
+        // After a NACK/timeout the context restarts and the next record says so.
+        encoder.resetContext()
+        let r3 = try XCTUnwrap(encoder.record(second, targets: 1))
+        XCTAssertEqual(r3[0], 1 | 4 | 8)
+        XCTAssertEqual(try inflateRecords([r3]), [second])
+        XCTAssertNil(encoder.record(Data(count: 0x10000), targets: 3))
+        XCTAssertNil(encoder.record(Data([7, 255]), targets: 4))
+    }
+
+    func testLensTargetedRecordsAreSelfContainedSoTheSkippingLensStaysInSync() throws {
+        let encoder = G2CfwTransport.Encoder()
+        let shared = Data([38, 0, 0, 0, 0, 1, 0] + [UInt8](repeating: 0x2A, count: 400))
+        let leftOnly = Data([38, 0, 0, 1, 0, 1, 0] + [UInt8](repeating: 0x2B, count: 400))
+        let rightOnly = Data([38, 0, 0, 2, 0, 1, 0] + [UInt8](repeating: 0x2C, count: 400))
+        let r1 = try XCTUnwrap(encoder.record(shared, targets: 3))
+        let r2 = try XCTUnwrap(encoder.record(leftOnly, targets: 1))
+        let r3 = try XCTUnwrap(encoder.record(rightOnly, targets: 2))
+        let r4 = try XCTUnwrap(encoder.record(shared, targets: 3))
+        let r5 = try XCTUnwrap(encoder.record(shared, targets: 3))
+        XCTAssertEqual(r2[0], 1 | 4 | 8, "a left-only record starts a fresh context")
+        XCTAssertEqual(r3[0], 2 | 4 | 8)
+        XCTAssertEqual(r4[0], 3 | 4 | 8, "and the record after it starts fresh again")
+        XCTAssertEqual(r5[0], 3 | 4, "then the shared context resumes")
+        // Each lens inflates exactly the records addressed to it.
+        XCTAssertEqual(try inflateRecords([r1, r2, r4, r5]), [shared, leftOnly, shared, shared])
+        XCTAssertEqual(try inflateRecords([r1, r3, r4, r5]), [shared, rightOnly, shared, shared])
+    }
+
+    func testPacketsMatchTheProbeFraming() {
+
+        let stream = Data((0 ..< 500).map { UInt8($0 & 0xFF) })
+        let packets = G2CfwTransport.packets(stream: stream, sequence: 254, targets: 3, chunkBytes: 200)
+        XCTAssertEqual(packets.count, 3)
+        // [aa 21 seq len+2 1 1 f0 0][options][chunk][crc lo][crc hi]
+        XCTAssertEqual(Array(packets[0].prefix(9)), [0xAA, 0x21, 254, 203, 1, 1, 0xF0, 0, 3 | 0x80])
+        XCTAssertEqual(Array(packets[1].prefix(9)), [0xAA, 0x21, 255, 203, 1, 1, 0xF0, 0, 3])
+        XCTAssertEqual(Array(packets[2].prefix(9)), [0xAA, 0x21, 0, 103, 1, 1, 0xF0, 0, 3 | 0x40])
+        XCTAssertEqual(packets[2].count, 8 + 1 + 100 + 2)
+        for packet in packets {
+            let body = packet.subdata(in: 8 ..< packet.count - 2)
+            XCTAssertEqual(Array(packet.suffix(2)), BinaryCodec.crc16CCITTLittleEndian(body))
+            XCTAssertEqual(Int(packet[3]), packet.count - 8)
+        }
+        XCTAssertEqual(Array(packets.flatMap { $0.subdata(in: 9 ..< $0.count - 2) }), Array(stream))
+        // An empty stream is one RESET|END packet; the probe rejects >252-byte chunks.
+        let empty = G2CfwTransport.packets(stream: Data(), sequence: 7, targets: 1)
+        XCTAssertEqual(Array(empty[0]), [0xAA, 0x21, 7, 3, 1, 1, 0xF0, 0, 1 | 0x80 | 0x40] + BinaryCodec.crc16CCITTLittleEndian([1 | 0x80 | 0x40]))
+        XCTAssertLessThanOrEqual(G2CfwTransport.maxChunkBytes, 252)
+    }
+
+    func testAckParsingIncludesHistoryAndRejectsMalformedReplies() throws {
+        let body = Data([1, 7, 0, 0, 2, 0x34, 0x12, 0xCD, 0xAB, 6, 1, 0, 0x10, 0, 0x22, 0x11])
+        let ack = try XCTUnwrap(G2CfwTransport.parseAck(body))
+        XCTAssertTrue(ack.success)
+        XCTAssertEqual(ack.lens, 2)
+        XCTAssertEqual(ack.current, .init(streamId: 7, ordinal: 0, size: 0x1234, crc: 0xABCD))
+        XCTAssertEqual(ack.entries.count, 2)
+        XCTAssertEqual(ack.entries[1], .init(streamId: 6, ordinal: 1, size: 0x10, crc: 0x1122))
+        let nack = try XCTUnwrap(G2CfwTransport.parseAck(Data([3, 7, 0, 0, 1, 0, 0, 0, 0])))
+        XCTAssertFalse(nack.success)
+        XCTAssertNil(G2CfwTransport.parseAck(Data([3, 7, 0, 0, 1, 0, 0, 0, 0, 6, 1, 0, 0, 0, 0, 0]))) // NACK has no history
+        XCTAssertNil(G2CfwTransport.parseAck(Data([2, 7, 0, 0, 1, 0, 0, 0, 0])))
+        XCTAssertNil(G2CfwTransport.parseAck(Data([1, 7, 0, 0, 3, 0, 0, 0, 0])))
+        XCTAssertNil(G2CfwTransport.parseAck(Data([1, 7, 0, 0])))
+
+        // Notify frame as the glasses send it: [aa 12 seq len 1 1 f0 0][body][crc].
+        var frame = Data([0xAA, 0x12, 9, UInt8(body.count + 2), 1, 1, 0xF0, 0])
+        frame.append(body)
+        frame.append(contentsOf: BinaryCodec.crc16CCITTLittleEndian(body))
+        XCTAssertEqual(G2CfwTransport.replyBody(fromNotifyFrame: frame), body)
+        var corrupt = frame
+        corrupt[10] ^= 1
+        XCTAssertNil(G2CfwTransport.replyBody(fromNotifyFrame: corrupt))
+        var otherService = frame
+        otherService[6] = 0xE0
+        XCTAssertNil(G2CfwTransport.replyBody(fromNotifyFrame: otherService))
+    }
+
+    @MainActor
+    func testAckBoxCompletesWhenBothLensesAckAndFailsOnNack() async throws {
+        let box = G2CfwAckBox()
+        let left = try XCTUnwrap(G2CfwTransport.parseAck(Data([1, 5, 0, 0, 1, 2, 0, 0, 0])))
+        let right = try XCTUnwrap(G2CfwTransport.parseAck(Data([1, 5, 0, 0, 2, 2, 0, 0, 0])))
+        let ok = await box.wait(streamId: 5, lenses: 3, timeoutNs: 1_000_000_000) { _ in
+            XCTAssertFalse(box.resolve(left)) // one lens is not enough
+            XCTAssertFalse(box.resolve(left)) // duplicate is harmless
+            XCTAssertTrue(box.resolve(right))
+        }
+        XCTAssertTrue(ok)
+        XCTAssertEqual(box.outcome()?.reason, "ack")
+        XCTAssertLessThan(box.msSinceLastSuccess(), 1000)
+
+        let nack = try XCTUnwrap(G2CfwTransport.parseAck(Data([3, 6, 0, 0, 2, 0, 0, 0, 0])))
+        let failed = await box.wait(streamId: 6, lenses: 3, timeoutNs: 1_000_000_000) { _ in
+            XCTAssertFalse(box.resolve(left)) // wrong stream
+            XCTAssertTrue(box.resolve(nack))
+        }
+        XCTAssertFalse(failed)
+        XCTAssertEqual(box.outcome()?.reason, "nack")
+
+        let timedOut = await box.wait(streamId: 7, lenses: 1, timeoutNs: 50_000_000) { _ in }
+        XCTAssertFalse(timedOut)
+        XCTAssertEqual(box.outcome()?.reason, "timeout")
+    }
+
+    @MainActor
+    func testQueuedWritesExpireBeforeCreditsReturnAndStayExpiredWhenStreamIdIsReused() async {
+        let box = G2CfwAckBox()
+        var staleWrite: (() -> Bool)?
+        let timedOut = await box.wait(streamId: 7, lenses: 1, timeoutNs: 20_000_000) { isPending in
+            staleWrite = isPending
+            XCTAssertTrue(isPending())
+            // Simulate no BLE credits: no packet is written and no ACK arrives.
+        }
+        XCTAssertFalse(timedOut)
+        XCTAssertEqual(box.outcome()?.reason, "timeout")
+        XCTAssertEqual(staleWrite?(), false)
+
+        // Recovery can reuse the wire ID after it wraps. An old queue entry
+        // must still be discarded, while the recovery's packets may be sent.
+        var recoveryWrite: (() -> Bool)?
+        let recovered = await box.wait(streamId: 7, lenses: 1, timeoutNs: 1_000_000_000) { isPending in
+            recoveryWrite = isPending
+            XCTAssertEqual(staleWrite?(), false)
+            XCTAssertTrue(isPending())
+            box.resolve(G2CfwTransport.Ack(success: true, lens: 1, entries: [.init(streamId: 7, ordinal: 0, size: 1, crc: 0)]))
+        }
+        XCTAssertTrue(recovered)
+        XCTAssertEqual(recoveryWrite?(), false)
+    }
+
+    @MainActor
+    func testAckBoxSingleLensAndCancellation() async throws {
+        let box = G2CfwAckBox()
+        let right = try XCTUnwrap(G2CfwTransport.parseAck(Data([1, 9, 0, 0, 2, 0, 0, 0, 0])))
+        let ok = await box.wait(streamId: 9, lenses: 2, timeoutNs: 1_000_000_000) { _ in
+            XCTAssertTrue(box.resolve(right))
+        }
+        XCTAssertTrue(ok)
+        var queuedWrite: (() -> Bool)?
+        let task = Task { @MainActor in
+            await box.wait(streamId: 10, lenses: 3, timeoutNs: 60_000_000_000) { isPending in
+                queuedWrite = isPending
+            }
+        }
+        try await Task.sleep(nanoseconds: 20_000_000)
+        task.cancel()
+        let cancelled = await task.value
+        XCTAssertFalse(cancelled)
+        XCTAssertEqual(box.outcome()?.reason, "cancelled")
+        XCTAssertEqual(queuedWrite?(), false)
+    }
+
+    func testCacheRepliesParseAndStampFillsEpochAndRequest() async throws {
+        let body = Data([5, 9, 0, 0, 2, 38, 7, 0, 2, 0x34, 0x12, 5, 0, 0, 0, 2, 1, 1, 0, 0, 0, 0, 1, 0, 0])
+        let reply = try XCTUnwrap(G2CfwTransport.parseCacheReply(body))
+        XCTAssertEqual(reply.streamId, 9)
+        XCTAssertEqual(reply.lens, 2)
+        XCTAssertEqual(reply.mode, 38)
+        XCTAssertEqual(reply.request, 7)
+        XCTAssertEqual(reply.status, G2CfwTransport.CacheReply.missing)
+        XCTAssertEqual(reply.epoch, 0x1234)
+        XCTAssertEqual(reply.revision, 5)
+        XCTAssertEqual(reply.missingIds, [1, 256])
+        XCTAssertTrue(reply.summary.hasPrefix("missing"))
+        XCTAssertNil(G2CfwTransport.parseCacheReply(Data([1, 9, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0])))
+        XCTAssertNil(G2CfwTransport.parseAck(body))
+
+        let show = Data([38, 0, 0, 0, 0, 1, 0, 0, 0, 0])
+        XCTAssertTrue(G2CfwTransport.isCacheMessage(show))
+        XCTAssertFalse(G2CfwTransport.isCacheMessage(Data([36, 0, 0, 0, 0])))
+        XCTAssertEqual(Array(G2CfwTransport.stamp(show, epoch: 0x1234, request: 0x0102).prefix(5)), [38, 0x34, 0x12, 2, 1])
+        let tagged = Data([38, 0, 0, 9, 0, 1, 0, 0, 0, 0])
+        XCTAssertEqual(Array(G2CfwTransport.stamp(tagged, epoch: 1, request: 7).prefix(5)), [38, 1, 0, 9, 0], "a tagged request is kept")
+        let state = Data([40, 0, 0, 0, 0, 0, 0, 0, 0])
+        XCTAssertEqual(Array(G2CfwTransport.stamp(state, epoch: 1, request: 7).prefix(5)), [40, 1, 0, 0, 0], "STATE carries a revision, not a request")
+
+        let box = G2CfwAckBox()
+        let armed = expectation(description: "armed")
+        Task { @MainActor in
+            let ok = await box.wait(streamId: 9, lenses: G2CfwTransport.lensBoth, timeoutNs: 1_000_000_000) { _ in
+                box.record(reply)
+                box.resolve(G2CfwTransport.Ack(success: true, lens: 2, entries: [.init(streamId: 9, ordinal: 0, size: 1, crc: 0)]))
+                box.resolve(G2CfwTransport.Ack(success: true, lens: 1, entries: [.init(streamId: 9, ordinal: 0, size: 1, crc: 0)]))
+            }
+            XCTAssertTrue(ok)
+            XCTAssertEqual(box.cacheReplies()[2], reply)
+            XCTAssertNil(box.cacheReplies()[1])
+            armed.fulfill()
+        }
+        await fulfillment(of: [armed], timeout: 2)
+    }
+
+    func testAckTimeoutScalesWithStreamSize() {
+        XCTAssertEqual(G2CfwTransport.ackTimeoutNs(streamBytes: 0), 3_500_000_000)
+        XCTAssertEqual(G2CfwTransport.ackTimeoutNs(streamBytes: 65_535), 3_500_000_000 + 65_535 * 1_000_000)
+        // A 4.5 KB upload chunk acked in ~4.1 s on GLASSLYCFW/39; the deadline must clear it.
+        XCTAssertGreaterThan(G2CfwTransport.ackTimeoutNs(streamBytes: 4_500), 6_000_000_000)
+    }
+}

package/ios/Tests/BluetoothSDKTests/G2DisplayDiagnosticsTests.swift

@@ -0,0 +1,89 @@
+@testable import BluetoothSDK
+import Foundation
+import XCTest
+
+final class G2DisplayDiagnosticsTests: XCTestCase {
+    private func decode(_ line: String) throws -> [String: Any] {
+        try XCTUnwrap(JSONSerialization.jsonObject(with: Data(line.dropFirst(7).utf8)) as? [String: Any])
+    }
+
+    @MainActor
+    func testSamplesAreThrottledResetAndLeaveOutEmptyValues() throws {
+        let diagnostics = G2DisplayDiagnostics(enabled: true, now: 0)
+        diagnostics.count("framesIn")
+        diagnostics.count("txBytes", 100)
+        diagnostics.timing("ackMs", 10)
+        diagnostics.timing("ackMs", 30.25)
+        diagnostics.timing("resumeMs", 0.2)
+        XCTAssertNil(diagnostics.sample(context: [:], now: 0.9))
+        let line = try XCTUnwrap(diagnostics.sample(
+            context: ["app": "com.glassly.dashboard", "qL": 0, "pendingFrame": false, "page": true, "blockedL": false],
+            now: 1
+        ))
+        let first = try decode(line)
+        XCTAssertEqual(first["txBytes"] as? Int, 100)
+        XCTAssertEqual(first["ackMsAvg"] as? Double, 20.1)
+        XCTAssertEqual(first["ackMsMax"] as? Double, 30.3)
+        XCTAssertNil(first["ackMsTotal"])
+        XCTAssertNil(first["resumeMsAvg"], "a sub-millisecond timing is left out")
+        XCTAssertTrue(line.contains("\"ackMsAvg\":20.1,"), "one decimal, no binary float noise: \(line)")
+        XCTAssertEqual(first["windowMs"] as? Int, 1000)
+        XCTAssertEqual(first["page"] as? Bool, true)
+        for key in ["qL", "pendingFrame", "blockedL", "timeouts", "errors"] {
+            XCTAssertNil(first[key], key)
+        }
+        XCTAssertEqual((first["run"] as? String)?.count, 8)
+        // Counters and timings reset with the window.
+        diagnostics.count("framesIn")
+        let second = try decode(XCTUnwrap(diagnostics.sample(context: [:], now: 2)))
+        XCTAssertNil(second["txBytes"])
+        XCTAssertNil(second["ackMsAvg"])
+        XCTAssertEqual(first["run"] as? String, second["run"] as? String)
+        XCTAssertEqual(second["id"] as? Int, 2)
+    }
+
+    @MainActor
+    func testIdleWindowsAreSkippedUnlessBusyOrLate() throws {
+        let diagnostics = G2DisplayDiagnostics(enabled: true, now: 0)
+        // IMU reports and heartbeat writes alone are idle.
+        diagnostics.count("imuReceived")
+        diagnostics.count("txPackets", 2)
+        diagnostics.timing("notifyDispatchMs", 0.1)
+        XCTAssertNil(diagnostics.sample(context: [:], now: 1))
+        // Something queued for the glasses is never idle.
+        XCTAssertNotNil(diagnostics.sample(context: ["qL": 3], busy: true, now: 2))
+        // A tick held up past the stretched window is logged even when nothing happened.
+        XCTAssertNil(diagnostics.sample(context: [:], now: 3))
+        let late = try decode(XCTUnwrap(diagnostics.sample(context: [:], now: 26.3)))
+        XCTAssertEqual(late["windowMs"] as? Int, 23300)
+    }
+
+    @MainActor
+    func testSessionFactsAreLoggedOnChangeAndOnceAMinute() throws {
+        let diagnostics = G2DisplayDiagnostics(enabled: true, now: 0)
+        let facts: [String: Any] = ["cfw": "GLASSLYCFW/39", "mtuL": 244, "mtuR": 244, "fpsLimit": 8]
+        let first = try decode(XCTUnwrap(diagnostics.session(facts, now: 1)))
+        XCTAssertEqual(first["type"] as? String, "session")
+        XCTAssertEqual(first["cfw"] as? String, "GLASSLYCFW/39")
+        XCTAssertNil(diagnostics.session(facts, now: 30))
+        var changed = facts
+        changed["mtuR"] = 180
+        XCTAssertNotNil(diagnostics.session(changed, now: 31))
+        XCTAssertNil(diagnostics.session(changed, now: 90))
+        XCTAssertNotNil(diagnostics.session(changed, now: 91))
+    }
+
+    @MainActor
+    func testStallDetailsAreBoundedButFailureCountersAreNotLost() throws {
+        let diagnostics = G2DisplayDiagnostics(enabled: true, now: 0)
+        for i in 0 ..< 100 {
+            diagnostics.count("errors")
+            let line = diagnostics.stall(fields: ["result": "timeout"], now: Double(i) / 100)
+            XCTAssertEqual(line != nil, i == 0)
+        }
+        let sample = try decode(XCTUnwrap(diagnostics.sample(context: [:], now: 2)))
+        XCTAssertEqual(sample["errors"] as? Int, 100)
+        XCTAssertEqual(sample["windowMs"] as? Int, 2000)
+        XCTAssertNotNil(diagnostics.stall(fields: [:], now: 2))
+    }
+}

package/ios/Tests/BluetoothSDKTests/G2FlashProtocolTests.swift

@@ -129,9 +129,10 @@ final class G2FlashProtocolTests: XCTestCase {
         XCTAssertEqual(Array(longRun), [0, 0, 0, 1])
     }
 
-    func testCfwBlackPayloadUsesModeSixZlibEnvelope() throws {
+    func testCfwBlackPayloadUsesModeSixRleEnvelope() throws {
+        // Plain RLE follows the mode byte: the SID-0xf0 transport compresses.
         let payload = try XCTUnwrap(G2CfwRenderer.blackPayload())
-        XCTAssertEqual(Array(payload.prefix(3)), [6, 0x78, 0x9C])
+        XCTAssertEqual(Array(payload.prefix(5)), [6, 0, 0, 0xFF, 0xFF])
     }
 
     private func makeFirmware() -> [UInt8] {