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

package/ios/Tests/BluetoothSDKTests/G2AncsRelayTests.swift

@@ -0,0 +1,186 @@
+@testable import BluetoothSDK
+import Foundation
+import XCTest
+
+/// Pins the ANCS relay wire format shared with g2flash's patches/ancs_relay.c.
+final class G2AncsRelayTests: XCTestCase {
+    private var relay = G2AncsRelay()
+
+    override func setUp() {
+        super.setUp()
+        relay = G2AncsRelay()
+    }
+
+    // MARK: - helpers
+
+    private func le16(_ v: Int) -> [UInt8] { [UInt8(v & 0xFF), UInt8(v >> 8)] }
+    private func le32(_ v: UInt32) -> [UInt8] {
+        [UInt8(v & 0xFF), UInt8((v >> 8) & 0xFF), UInt8((v >> 16) & 0xFF), UInt8(v >> 24)]
+    }
+
+    private func source(uid: UInt32, event: UInt8 = 0, flags: UInt8 = 0, category: UInt8 = 4, count: UInt8 = 1) -> Data {
+        Data([0x41, 0x4E, 1, 1, event, flags, category, count] + le32(uid))
+    }
+
+    private func attr(uid: UInt32, id: UInt8, _ value: String, total: Int? = nil, offset: Int = 0) -> Data {
+        let bytes = [UInt8](value.utf8)
+        return Data([0x41, 0x4E, 1, 2] + le32(uid) + [id] + le16(total ?? bytes.count) + le16(offset) + bytes)
+    }
+
+    private func app(_ id: String, name: String, total: Int? = nil, offset: Int = 0) -> Data {
+        let idBytes = [UInt8](id.utf8), nameBytes = [UInt8](name.utf8)
+        return Data([0x41, 0x4E, 1, 3] + le16(total ?? nameBytes.count) + le16(offset) + [UInt8(idBytes.count)] + idBytes + nameBytes)
+    }
+
+    /// Feed a whole notification; returns the event produced by the last attribute.
+    private func feedNotification(
+        uid: UInt32, flags: UInt8 = 0, app: String = "com.apple.MobileSMS",
+        title: String = "Alice", subtitle: String = "", message: String = "hi",
+        date: String = "20260902T183000"
+    ) -> G2AncsRelay.Event? {
+        XCTAssertNil(relay.ingest(source(uid: uid, flags: flags)))
+        let values: [(UInt8, String)] = [
+            (0, app), (1, title), (2, subtitle), (3, message), (4, "\(message.utf8.count)"),
+            (5, date), (6, "Open"), (7, "Clear"),
+        ]
+        var last: G2AncsRelay.Event?
+        for (id, value) in values {
+            last = relay.ingest(attr(uid: uid, id: id, value))
+            if id != 7 { XCTAssertNil(last, "attribute \(id) completed the notification early") }
+        }
+        return last
+    }
+
+    // MARK: - encoding
+
+    func testControlPacketFramesFieldOneHundredSix() {
+        XCTAssertEqual(
+            [UInt8](G2AncsRelay.controlPacket(op: .enable)),
+            [0x08, 0x01, 0x10, 0x00, 0xF2, 0x07, 0x04, 0x41, 0x4E, 0x01, 0x01]
+        )
+        XCTAssertEqual(
+            [UInt8](G2AncsRelay.actionPacket(uid: 0x1234_5678, positive: false)),
+            [0x08, 0x01, 0x10, 0x00, 0xF2, 0x07, 0x09, 0x41, 0x4E, 0x01, 0x04, 0x78, 0x56, 0x34, 0x12, 0x01]
+        )
+        XCTAssertEqual([UInt8](G2AncsRelay.actionPacket(uid: 1, positive: true)).last, 0)
+    }
+
+    // MARK: - reassembly
+
+    func testNotificationCompletesAfterAllEightAttributes() throws {
+        let event = try XCTUnwrap(feedNotification(uid: 42, flags: 0x02, subtitle: "Re: lunch"))
+        guard case let .notification(n) = event else { return XCTFail("expected a notification, got \(event)") }
+        XCTAssertEqual(n.uid, 42)
+        XCTAssertEqual(n.notificationId, "ancs-42")
+        XCTAssertEqual(n.event, .added)
+        XCTAssertTrue(n.flags.contains(.important))
+        XCTAssertFalse(n.flags.contains(.preExisting))
+        XCTAssertEqual(n.category, 4)
+        XCTAssertEqual(n.appIdentifier, "com.apple.MobileSMS")
+        XCTAssertEqual(n.title, "Alice")
+        XCTAssertEqual(n.subtitle, "Re: lunch")
+        XCTAssertEqual(n.message, "hi")
+        XCTAssertEqual(n.date, "20260902T183000")
+        XCTAssertEqual(n.positiveActionLabel, "Open")
+        XCTAssertEqual(n.negativeActionLabel, "Clear")
+    }
+
+    func testChunkedMessageReassemblesInAnyOrder() throws {
+        let message = String(repeating: "abcdefghij", count: 30) // 300 bytes, three firmware chunks
+        let bytes = [UInt8](message.utf8)
+        XCTAssertNil(relay.ingest(source(uid: 7)))
+        for (id, value) in [(0, "com.example"), (1, "t"), (2, ""), (4, "300"), (5, ""), (6, ""), (7, "")] as [(UInt8, String)] {
+            XCTAssertNil(relay.ingest(attr(uid: 7, id: id, value)))
+        }
+        let chunks = [(274, bytes[274...]), (0, bytes[0 ..< 137]), (137, bytes[137 ..< 274])]
+        var event: G2AncsRelay.Event?
+        for (offset, chunk) in chunks {
+            let record = Data([0x41, 0x4E, 1, 2] + le32(7) + [3] + le16(300) + le16(offset) + chunk)
+            event = relay.ingest(record)
+        }
+        guard case let .notification(n) = try XCTUnwrap(event) else { return XCTFail("expected a notification") }
+        XCTAssertEqual(n.message, message)
+    }
+
+    func testAttributesWithoutASourceAreIgnored() {
+        XCTAssertNil(relay.ingest(attr(uid: 9, id: 1, "orphan")))
+        XCTAssertNotNil(feedNotification(uid: 9))
+    }
+
+    func testRemovedReportsTheAppLearnedFromTheNotification() throws {
+        _ = feedNotification(uid: 5, app: "com.apple.mobilemail")
+        XCTAssertEqual(
+            relay.ingest(source(uid: 5, event: 2)),
+            .removed(uid: 5, appIdentifier: "com.apple.mobilemail")
+        )
+        // A second removal (or one for an unknown uid) carries no app.
+        XCTAssertEqual(relay.ingest(source(uid: 5, event: 2)), .removed(uid: 5, appIdentifier: nil))
+    }
+
+    func testRemovalDiscardsAPartialReassembly() {
+        XCTAssertNil(relay.ingest(source(uid: 3)))
+        XCTAssertNil(relay.ingest(attr(uid: 3, id: 0, "com.example")))
+        XCTAssertEqual(relay.ingest(source(uid: 3, event: 2)), .removed(uid: 3, appIdentifier: nil))
+        XCTAssertNil(relay.ingest(attr(uid: 3, id: 1, "late")))
+    }
+
+    func testAppNameRecordUpdatesTheDirectory() {
+        XCTAssertEqual(
+            relay.ingest(app("com.apple.MobileSMS", name: "Messages")),
+            .appName(appIdentifier: "com.apple.MobileSMS", displayName: "Messages")
+        )
+        XCTAssertEqual(relay.appNames["com.apple.MobileSMS"], "Messages")
+    }
+
+    func testAppNameChunksReassemble() {
+        let name = String(repeating: "N", count: 200)
+        let bytes = [UInt8](name.utf8)
+        XCTAssertNil(relay.ingest(app("com.example", name: String(decoding: bytes[0 ..< 120], as: UTF8.self), total: 200)))
+        XCTAssertEqual(
+            relay.ingest(app("com.example", name: String(decoding: bytes[120...], as: UTF8.self), total: 200, offset: 120)),
+            .appName(appIdentifier: "com.example", displayName: name)
+        )
+    }
+
+    func testStatusDecodes() {
+        let record = Data([0x41, 0x4E, 1, 4, 1, 1] + le16(3) + le16(70) + [2])
+        XCTAssertEqual(
+            relay.ingest(record),
+            .status(G2AncsRelay.Status(enabled: true, side: 1, drops: 3, sent: 70, sendErrors: 2))
+        )
+    }
+
+    func testUnknownVersionKindAndShortRecordsAreIgnored() {
+        XCTAssertNil(relay.ingest(Data([0x41, 0x4E, 2, 1, 0, 0, 0, 0, 1, 0, 0, 0])))
+        XCTAssertNil(relay.ingest(Data([0x41, 0x4E, 1, 9])))
+        XCTAssertNil(relay.ingest(Data([0x41, 0x4E, 1, 1, 0])))
+        XCTAssertNil(relay.ingest(Data([0x41, 0x4E, 1, 4, 1])))
+    }
+
+    func testPruneDropsStaleReassemblies() {
+        let start = Date(timeIntervalSince1970: 1000)
+        XCTAssertNil(relay.ingest(source(uid: 11), now: start))
+        relay.prune(olderThan: 30, now: start.addingTimeInterval(31))
+        XCTAssertNil(relay.ingest(attr(uid: 11, id: 0, "com.example")))
+        XCTAssertNil(relay.ingest(source(uid: 12), now: start))
+        relay.prune(olderThan: 30, now: start.addingTimeInterval(5))
+        // Still pending: attributes are accepted and the notification completes.
+        for id in UInt8(0) ... 6 { XCTAssertNil(relay.ingest(attr(uid: 12, id: id, "x"))) }
+        XCTAssertNotNil(relay.ingest(attr(uid: 12, id: 7, "x")))
+    }
+
+    // MARK: - timestamps
+
+    func testTimestampParsesLocalAncsDateAndFallsBackToNow() {
+        let now = Date(timeIntervalSince1970: 1_700_000_000)
+        XCTAssertEqual(G2AncsRelay.timestampMs(date: "", now: now), 1_700_000_000_000)
+        XCTAssertEqual(G2AncsRelay.timestampMs(date: "garbage", now: now), 1_700_000_000_000)
+        var components = DateComponents()
+        components.calendar = Calendar(identifier: .gregorian)
+        components.timeZone = .current
+        components.year = 2026; components.month = 9; components.day = 2
+        components.hour = 18; components.minute = 30; components.second = 0
+        let expected = Int64(components.date!.timeIntervalSince1970 * 1000)
+        XCTAssertEqual(G2AncsRelay.timestampMs(date: "20260902T183000", now: now), expected)
+    }
+}

package/ios/Tests/BluetoothSDKTests/G2BleLinkTests.swift

@@ -0,0 +1,52 @@
+@testable import BluetoothSDK
+import Foundation
+import XCTest
+
+/// Pins the BLE link control wire format shared with g2flash's patches/ble_link.c.
+final class G2BleLinkTests: XCTestCase {
+    private func le16(_ v: Int) -> [UInt8] {
+        [UInt8(v & 0xFF), UInt8(v >> 8)]
+    }
+
+    func testControlPacketFramesField127OnDeviceReceiveInfo() {
+        XCTAssertEqual(
+            [UInt8](G2BleLink.controlPacket(op: .fast)),
+            [0x08, 0x01, 0x10, 0x00, 0xFA, 0x07, 4, 0x42, 0x4C, 1, 1]
+        )
+        XCTAssertEqual([UInt8](G2BleLink.controlPacket(op: .stock)).suffix(1), [0])
+        XCTAssertEqual([UInt8](G2BleLink.controlPacket(op: .query)).suffix(1), [2])
+    }
+
+    func testDecodesFullStatusWithLivePair() {
+        let body = Data([0x42, 0x4C, 1, 1, 1, 0xA3, 0xA3] + le16(6) + le16(6) + le16(0) + le16(12) + le16(0))
+        let status = G2BleLink.decodeStatus(body)
+        XCTAssertEqual(status, G2BleLink.Status(
+            fast: true, side: 1, wanted: .fast, applied: .fast,
+            requestedMinMs: 7.5, requestedMaxMs: 7.5, requestedLatency: 0,
+            liveIntervalMs: 15, liveLatency: 0
+        ))
+        XCTAssertEqual(status?.summary, "FAST wanted=fast applied=fast requested 7.50-7.50 ms / latency 0 live 15.00 ms / latency 0")
+    }
+
+    func testDecodesThirteenByteStatusWithoutLivePair() {
+        let body = Data([0x42, 0x4C, 1, 0, 2, 0xA4, 0] + le16(36) + le16(72) + le16(4))
+        let status = G2BleLink.decodeStatus(body)
+        XCTAssertEqual(status?.fast, false)
+        XCTAssertEqual(status?.side, 2)
+        XCTAssertEqual(status?.wanted, .slow)
+        XCTAssertEqual(status?.applied, .pending)
+        XCTAssertEqual(status?.requestedMinMs, 45)
+        XCTAssertEqual(status?.requestedMaxMs, 90)
+        XCTAssertEqual(status?.requestedLatency, 4)
+        XCTAssertNil(status?.liveIntervalMs)
+        XCTAssertNil(status?.liveLatency)
+        XCTAssertEqual(status?.summary, "stock wanted=slow applied=pending requested 45.00-90.00 ms / latency 4")
+    }
+
+    func testRejectsForeignShortOrVersionedBodies() {
+        XCTAssertNil(G2BleLink.decodeStatus(Data([0x41, 0x4E, 1, 1, 1, 0xA3, 0xA3] + le16(6) + le16(6) + le16(0))))
+        XCTAssertNil(G2BleLink.decodeStatus(Data([0x42, 0x4C, 2, 1, 1, 0xA3, 0xA3] + le16(6) + le16(6) + le16(0))))
+        XCTAssertNil(G2BleLink.decodeStatus(Data([0x42, 0x4C, 1, 1, 1, 0xA3, 0xA3] + le16(6) + le16(6))))
+        XCTAssertEqual(G2BleLink.decodeStatus(Data([0x42, 0x4C, 1, 0, 1, 0x99, 0] + le16(0) + le16(0) + le16(0)))?.wanted, .other(0x99))
+    }
+}

package/ios/Tests/BluetoothSDKTests/G2CfwClassificationTests.swift

@@ -2,10 +2,6 @@
 import Foundation
 import XCTest
 
-/// Pins the stock-vs-CFW identity rules that gate the connect banner. A
-/// regression here re-opens the stuck "// Glassly connected" bug: text drawn
-/// down the stock path before classification, cleared down the CFW path
-/// after it, never leaves the glass.
 final class G2CfwClassificationTests: XCTestCase {
     private func classify(
         _ capability: String?, definitive: Bool = false, current: String? = nil
@@ -17,62 +13,61 @@ final class G2CfwClassificationTests: XCTestCase {
         )
     }
 
-    // MARK: - CFW detection
-
-    func testCfwBannerClassifiesWithFeaturesAndRevision() throws {
-        let result = try XCTUnwrap(classify("EVENCFW/15 img640 imgz rle directfb font15"))
-        XCTAssertTrue(result.isCfw)
-        XCTAssertEqual(result.capabilityString, "EVENCFW/15 img640 imgz rle directfb font15")
-        XCTAssertEqual(result.features, ["img640", "imgz", "rle", "directfb", "font15"])
-        XCTAssertEqual(result.protocolVersion, 15)
-    }
-
-    func testCfwDetectionDoesNotWaitForADefinitiveResponse() throws {
-        // The banner may ride any settings packet; requiring `definitive`
-        // would delay classification past the connect banner and re-split
-        // the draw/clear paths.
-        let result = try XCTUnwrap(classify("EVENCFW/12 img640", definitive: false))
-        XCTAssertTrue(result.isCfw)
+    func testGlasslyUsesOneContractWithoutRevisionOrTokenNegotiation() throws {
+        for banner in ["GLASSLYCFW/24", "GLASSLYCFW/24 shapes36 scene37 anim38", "GLASSLYCFW/25"] {
+            let result = try XCTUnwrap(classify(banner))
+            XCTAssertEqual(result.family, .glassly)
+            XCTAssertTrue(result.isCfw)
+            XCTAssertTrue(result.isGlassly)
+            XCTAssertEqual(result.displayName, banner == "GLASSLYCFW/25" ? "Glassly CFW v25" : "Glassly CFW v24")
+            XCTAssertEqual(result.capabilityString, banner)
+        }
     }
 
-    func testCfwBannerTrimsNulTermination() throws {
-        let result = try XCTUnwrap(classify("EVENCFW/12 img640\0\0"))
-        XCTAssertEqual(result.capabilityString, "EVENCFW/12 img640")
-        XCTAssertEqual(result.features, ["img640"])
+    func testRevisionIsRetainedIndependentlyOfTheFirmwareFamily() throws {
+        XCTAssertEqual(classify("GLASSLYCFW/24 shapes36 scene37 anim38")?.revision, 24)
+        XCTAssertEqual(classify("GLASSLYCFW/25")?.revision, 25)
+        XCTAssertEqual(classify("EVENCFW/22 img640")?.revision, 22)
+        XCTAssertEqual(classify("GLASSLYCFW/24\0\0")?.revision, 24)
+        XCTAssertNil(G2CfwClassification.stock.revision)
+        for banner in ["GLASSLYCFW/", "GLASSLYCFW/beta", "GLASSLYCFW/0", "GLASSLYCFW/-1"] {
+            let result = try XCTUnwrap(classify(banner))
+            XCTAssertNil(result.revision)
+            XCTAssertTrue(result.isGlassly)
+        }
     }
 
-    func testMalformedRevisionFallsBackToZero() throws {
-        let result = try XCTUnwrap(classify("EVENCFW/beta img640"))
-        XCTAssertTrue(result.isCfw)
-        XCTAssertEqual(result.protocolVersion, 0)
+    func testEvenCfwIsUpstreamAndNeverGlassly() throws {
+        for banner in ["EVENCFW/22 img640 imgz rle font15 ringbat17", "EVENCFW/24 shapes36 scene37 anim38"] {
+            let result = try XCTUnwrap(classify(banner))
+            XCTAssertEqual(result.family, .upstream)
+            XCTAssertTrue(result.isCfw)
+            XCTAssertFalse(result.isGlassly)
+            XCTAssertEqual(result.displayName, "g2flash CFW")
+        }
     }
 
-    // MARK: - Stock classification
-
-    func testDefinitiveAbsenceClassifiesStock() throws {
-        let result = try XCTUnwrap(classify(nil, definitive: true))
-        XCTAssertFalse(result.isCfw)
-        XCTAssertEqual(result, .stock)
+    func testBannerTrimsNulTermination() throws {
+        let result = try XCTUnwrap(classify("GLASSLYCFW/24\0\0"))
+        XCTAssertEqual(result.capabilityString, "GLASSLYCFW/24")
     }
 
-    func testDefinitiveNonCfwPayloadClassifiesStock() throws {
-        let result = try XCTUnwrap(classify("something-else", definitive: true))
-        XCTAssertEqual(result, .stock)
-    }
-
-    // MARK: - Packets that prove nothing
-
-    func testNonDefinitiveAbsenceLeavesConnectionUnclassified() {
-        // Individual settings packets can legitimately omit field 100 or
-        // arrive truncated — only a deviceReceiveRequest response is proof.
-        XCTAssertNil(classify(nil, definitive: false))
-        XCTAssertNil(classify("garbage", definitive: false))
+    func testDefinitiveAbsenceOrUnrecognizedPrefixClassifiesStock() throws {
+        for banner: String? in [nil, "something-else", "GLASSLYCFW-invalid", "EVENCFW-invalid"] {
+            let result = try XCTUnwrap(classify(banner, definitive: true))
+            XCTAssertEqual(result, .stock)
+            XCTAssertFalse(result.isCfw)
+            XCTAssertFalse(result.isGlassly)
+            XCTAssertNil(result.displayName)
+        }
     }
 
-    func testDefinitiveAbsenceNeverDowngradesDetectedCfw() {
-        // Firmware identity is connection-sticky: downgrading would
-        // reinterpret an installed mode-6 carrier as a stock BMP.
-        XCTAssertNil(classify(nil, definitive: true, current: "EVENCFW/15 img640"))
-        XCTAssertNil(classify("garbage", definitive: true, current: "EVENCFW/15 img640"))
+    func testPartialSettingsPacketsPreserveTheKnownRenderPath() {
+        XCTAssertNil(classify(nil))
+        XCTAssertNil(classify("garbage"))
+        for banner in ["GLASSLYCFW/24", "EVENCFW/22"] {
+            XCTAssertNil(classify(nil, definitive: true, current: banner))
+            XCTAssertNil(classify("garbage", definitive: true, current: banner))
+        }
     }
 }

package/ios/Tests/BluetoothSDKTests/G2CfwRendererTests.swift

@@ -5,7 +5,161 @@ import XCTest
 final class G2CfwRendererTests: XCTestCase {
     private static let white: UInt8 = 200
 
+    func testGlobalDepthMovesFlatScenesWithoutMiniappDepth() async throws {
+        let renderer = G2CfwRenderer()
+        let content = frame([rect(x: 100, y: 40, w: 100, h: 50, border: 1)])
+        // Start flat, split the retained mirror, change sides, then converge again.
+        for (index, setting) in [2, 1, 3, 2].enumerated() {
+            let b = boxes(height: 4, depth: G2CfwRenderer.depthLevel(forSetting: setting))
+            let result = await renderer.encodeVector(
+                content, boxes: b, cacheGeneration: 1, invalidate: index == 0, inlineText: true
+            )
+            let encoded = try XCTUnwrap(result)
+            if setting == 2 {
+                XCTAssertEqual(encoded.shows.map(\.lenses), [G2CfwTransport.lensBoth])
+                XCTAssertEqual(firstRectX(encoded.shows[0].payload), 132)
+            } else {
+                XCTAssertEqual(encoded.shows.map(\.lenses), [G2CfwTransport.lensLeft, G2CfwTransport.lensRight])
+                XCTAssertEqual(firstRectX(encoded.shows[0].payload), setting == 1 ? 140 : 124)
+                XCTAssertEqual(firstRectX(encoded.shows[1].payload), setting == 1 ? 124 : 140)
+            }
+        }
+    }
+
+    func testElementDepthIsRelativeToEachGlobalLensOrigin() async throws {
+        let renderer = G2CfwRenderer()
+        let content = SceneElement(
+            id: "card", type: "rect", x: 100, y: 40, w: 100, h: 50,
+            text: nil, data: nil, border: 1, radius: 0, change: "created", contentHash: "card", depth: 5
+        )
+        let result = await renderer.encodeVector(
+            frame([content]), boxes: boxes(height: 4, depth: G2CfwRenderer.depthLevel(forSetting: 3)),
+            cacheGeneration: 1, invalidate: true, inlineText: true
+        )
+        let encoded = try XCTUnwrap(result)
+        XCTAssertEqual(encoded.shows.map(\.lenses), [G2CfwTransport.lensLeft, G2CfwTransport.lensRight])
+        XCTAssertEqual(firstRectX(encoded.shows[0].payload), 24 + 100 + 5)
+        XCTAssertEqual(firstRectX(encoded.shows[1].payload), 40 + 100 - 5)
+    }
+
+    private func firstRectX(_ payload: Data) -> Int {
+        let bytes = [UInt8](payload)
+        XCTAssertEqual(bytes[0], 38) // SHOW
+        XCTAssertEqual(bytes[7], 1) // one object PUT
+        // SHOW header (8), PUT opcode/id/version (9), type/flags/color/width (4).
+        return Int(Int16(bitPattern: UInt16(bytes[21]) | UInt16(bytes[22]) << 8))
+    }
+
+    func testGlobalDepthSettingsMapToAllThreeFirmwareLevels() {
+        XCTAssertEqual([1, 2, 3].map { G2CfwRenderer.depthLevel(forSetting: $0) }, [0, 1, 2])
+        XCTAssertEqual(G2CfwRenderer.depthLevel(forSetting: Int.min), 0)
+        XCTAssertEqual(G2CfwRenderer.depthLevel(forSetting: Int.max), 2)
+    }
+
+    func testRasterFallbackBakesTextIntoStereoWindows() async throws {
+        let renderer = G2CfwRenderer()
+        for font in ["builtin", "mono"] {
+            let text = SceneElement(
+                id: "text", type: "text", x: 10, y: 10, w: 200, h: 60,
+                text: "Depth", data: nil, border: 0, radius: 0,
+                change: "created", contentHash: font, font: font, fontSize: 20
+            )
+            for setting in [1, 3] {
+                let b = boxes(height: 4, depth: G2CfwRenderer.depthLevel(forSetting: setting))
+                let result = await renderer.encodeUpdate(
+                    frame([text]), boxes: b, previousRaster: nil, forcedRects: [],
+                    fids: (1 ... G2CfwRenderer.requiredFidCount).map { UInt16($0) },
+                    textDraws: [], allowRectCopy: true, blankBoxes: nil, omitBuiltinText: false,
+                    textureGlyphsEnabled: true, textureImagesEnabled: true
+                )
+                let update = try XCTUnwrap(result)
+                XCTAssertTrue(update.raster.contains { $0 > 0 }, "\(font) text must remain visible")
+                let payload = try XCTUnwrap(update.payload)
+                XCTAssertEqual(payload[0], 0x83, "a stereo bitmap, without lens-equal text/cache commands")
+                XCTAssertEqual(Int(payload[1]) * 4, Int(b.left.x))
+                XCTAssertEqual(Int(payload[5]) * 4, Int(b.right.x))
+            }
+        }
+    }
+
+    func testSustainedHalfBlockFramesStaySmallOnTheObjectCache() async throws {
+        let renderer = G2CfwRenderer()
+        let b = boxes(height: 4, depth: 1)
+        let glyphs: [Character] = [" ", "▀", "▄", "█"]
+        var rng: UInt32 = 42
+        var uploads = 0
+        var largest = 0
+        for index in 0 ..< 120 {
+            var lines: [String] = []
+            for _ in 0 ..< 20 {
+                var line = ""
+                for _ in 0 ..< 78 {
+                    rng = rng &* 1_664_525 &+ 1_013_904_223
+                    line.append(glyphs[Int(rng >> 30)])
+                }
+                lines.append(line)
+            }
+            let element = SceneElement(
+                id: "badapple", type: "text", x: 0, y: 0, w: 576, h: 288,
+                text: lines.joined(separator: "\n"), data: nil, border: 0, radius: 0,
+                change: "updated", contentHash: "frame-\(index)", font: "mono", fontSize: 12
+            )
+            let result = await renderer.encodeVector(
+                frame([element]), boxes: b, cacheGeneration: 1, invalidate: index == 0, inlineText: true
+            )
+            let encoded = try XCTUnwrap(result)
+            uploads += encoded.uploads.count
+            XCTAssertEqual(encoded.shows.map(\.lenses), [G2CfwTransport.lensBoth], "flat frames are one SHOW for both lenses")
+            let payload = try XCTUnwrap(encoded.shows.first?.payload)
+            let bytes = payload.count + (index == 0 ? 0 : encoded.uploads.reduce(0) { $0 + $1.count })
+            largest = max(largest, bytes)
+            XCTAssertLessThan(bytes, 4500, "frame \(index) fell back to image tiles")
+            XCTAssertEqual(payload.first, 38)
+
+        }
+        XCTAssertGreaterThan(uploads, 1, "the font goes once, then the changed strings")
+        print("120 half-block frames: largest encoded frame = \(largest) bytes, uploads = \(uploads)")
+    }
+
+    func testElementDepthSplitsTheSceneIntoLensSpecificShows() async throws {
+        let renderer = G2CfwRenderer()
+        let b = boxes(height: 4, depth: 1)
+        let content = rect(x: 10, y: 10, w: 100, h: 50, border: 1)
+        let card = SceneElement(
+            id: "card", type: "rect", x: 200, y: 40, w: 200, h: 120, text: nil, data: nil, border: 2, radius: 8,
+            change: "created", contentHash: "card", fill: true, color: 3, depth: 8
+        )
+        let flatResult = await renderer.encodeVector(frame([content]), boxes: b, cacheGeneration: 1, invalidate: true, inlineText: true)
+        let flat = try XCTUnwrap(flatResult)
+        XCTAssertEqual(flat.shows.map(\.lenses), [G2CfwTransport.lensBoth], "flat frames are one SHOW for both lenses")
+        XCTAssertTrue(flat.changed)
+
+        let stereoResult = await renderer.encodeVector(frame([content, card]), boxes: b, cacheGeneration: 1, invalidate: false, inlineText: true)
+        let stereo = try XCTUnwrap(stereoResult)
+        XCTAssertEqual(stereo.shows.map(\.lenses), [G2CfwTransport.lensLeft, G2CfwTransport.lensRight])
+        XCTAssertNotEqual(stereo.shows[0].payload, stereo.shows[1].payload)
+        XCTAssertEqual(stereo.puts, 4, "the card's fill and frame are defined once per lens; the content is a hit on both")
+        XCTAssertEqual(stereo.hits, 2)
+
+
+        let sameResult = await renderer.encodeVector(frame([content, card]), boxes: b, cacheGeneration: 1, invalidate: false, inlineText: true)
+        let same = try XCTUnwrap(sameResult)
+        XCTAssertFalse(same.changed, "an identical frame changes nothing on either lens")
+        XCTAssertEqual(same.shows.count, 2, "but a caller that always sends still gets one SHOW per lens")
+
+        let backResult = await renderer.encodeVector(frame([content]), boxes: b, cacheGeneration: 1, invalidate: false, inlineText: true)
+        let back = try XCTUnwrap(backResult)
+        XCTAssertEqual(back.shows.map(\.lenses), [G2CfwTransport.lensBoth], "with the card gone the lenses agree again")
+        XCTAssertTrue(back.changed)
+
+        let resetResult = await renderer.encodeVector(frame([content]), boxes: b, cacheGeneration: 2, invalidate: false, inlineText: true)
+        let reset = try XCTUnwrap(resetResult)
+        XCTAssertEqual(reset.shows.map(\.lenses), [G2CfwTransport.lensBoth])
+        XCTAssertEqual(reset.puts, 1, "a new generation redefines from the shared mirror")
+    }
+
     private func rect(x: Int32, y: Int32, w: Int32, h: Int32, border: Int32) -> SceneElement {
+
         SceneElement(
             id: "r", type: "rect", x: x, y: y, w: w, h: h, text: nil, data: nil,
             border: border, radius: 0, change: "created", contentHash: ""
@@ -108,7 +262,8 @@ final class G2CfwRendererTests: XCTestCase {
         let pixels = Data(count: 576 * 288)
         let payload = try XCTUnwrap(G2CfwRenderer.stereoFrame(pixels: pixels, boxes: b, fid: 0x1234))
         XCTAssertEqual(Array(payload.prefix(11)), [0x83, 6, 64, 144, 144, 10, 64, 144, 144, 0x34, 0x12])
-        XCTAssertEqual(payload[11], 0x78) // zlib (RFC 1950) header
+        // Plain RLE follows the header (the transport compresses): 576*288 black pixels.
+        XCTAssertEqual(Array(payload[11 ..< 15]), [0x00, 0x00, 0xFF, 0xFF])
     }
 
     func testSolidStereoFrameMatchesPixelFrameHeader() throws {
@@ -143,7 +298,8 @@ final class G2CfwRendererTests: XCTestCase {
     func testBlackKeyframeIsMode6() throws {
         let payload = try XCTUnwrap(G2CfwRenderer.blackPayload())
         XCTAssertEqual(payload.first, 6)
-        XCTAssertEqual(payload[1], 0x78)
+        // 307,200 black pixels as RLE: four 65,535 runs and a 45,060 remainder.
+        XCTAssertEqual(Array(payload.dropFirst()), [0x00, 0x00, 0xFF, 0xFF, 0x00, 0x00, 0xFF, 0xFF, 0x00, 0x00, 0xFF, 0xFF, 0x00, 0x00, 0xFF, 0xFF, 0x00, 0x00, 0x04, 0xB0])
     }
 
     func testSeededFramePayloadCompositesContentAtLensEqualWindow() throws {
@@ -242,8 +398,10 @@ final class G2CfwRendererTests: XCTestCase {
     func testVerticalScrollBecomesRectCopyPlusResidue() {
         let width = 64
         let height = 96
-        // Distinct rows of "content" scrolled up by 8, with a fresh bottom row band.
-        func content(_ row: Int) -> UInt8 { UInt8((row * 7) % 251) }
+        /// Distinct rows of "content" scrolled up by 8, with a fresh bottom row band.
+        func content(_ row: Int) -> UInt8 {
+            UInt8((row * 7) % 251)
+        }
         let prev = raster(width: width, height: height) { px in
             for y in 0 ..< height {
                 for x in 0 ..< width {
@@ -305,7 +463,8 @@ final class G2CfwRendererTests: XCTestCase {
             [0x83, UInt8((24 + 100) / 4), UInt8((128 + 50) / 2), 8, 8,
              UInt8((40 + 100) / 4), UInt8((128 + 50) / 2), 8, 8, 5, 0]
         )
-        XCTAssertEqual(payload[11], 0x78)
+        // Plain RLE of the 32x16 box follows (the transport compresses).
+        XCTAssertEqual(Array(payload[11...]), Array(G2CfwRenderer.rleEncode(G2CfwRenderer.pack4Bpp(Data(count: 32 * 16)))))
     }
 
     func testBoxDeltaFrameRejectsUnalignedRects() {