@glassly/bluetooth-sdk 0.1.0-dev.26

package/ios/Tests/BluetoothSDKTests/G2CfwRendererTests.swift

@@ -0,0 +1,372 @@
+@testable import BluetoothSDK
+import Foundation
+import XCTest
+
+final class G2CfwRendererTests: XCTestCase {
+    private static let white: UInt8 = 200
+
+    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: ""
+        )
+    }
+
+    private func frame(_ elements: [SceneElement]) -> SceneFrame {
+        SceneFrame(appId: "test", epoch: 1, replay: false, elements: elements, removed: [])
+    }
+
+    private func boxes(height: Int, depth: Int) -> G2CfwRenderer.LensBoxes {
+        G2CfwRenderer.lensBoxes(canvasWidth: 576, canvasHeight: 288, heightLevel: height, depthLevel: depth)
+    }
+
+    // MARK: - Placement (stock window tables)
+
+    func testDefaultLevelsMatchStockPlacement() {
+        let b = boxes(height: 4, depth: 2)
+        XCTAssertEqual(b.left, CGPoint(x: 24, y: 128))
+        XCTAssertEqual(b.right, CGPoint(x: 40, y: 128))
+        XCTAssertEqual(b.width, 576)
+        XCTAssertEqual(b.height, 288)
+    }
+
+    func testDepthShiftsLensesInOppositeDirections() {
+        XCTAssertEqual(boxes(height: 6, depth: 1).left.x, 32)
+        XCTAssertEqual(boxes(height: 6, depth: 1).right.x, 32)
+        XCTAssertEqual(boxes(height: 6, depth: 0).left.x, 40)
+        XCTAssertEqual(boxes(height: 6, depth: 0).right.x, 24)
+    }
+
+    func testHeightLevelSpansThePanel() {
+        XCTAssertEqual(boxes(height: 0, depth: 1).left.y, 192)
+        XCTAssertEqual(boxes(height: 12, depth: 1).left.y, 0)
+        XCTAssertEqual(boxes(height: 99, depth: 7).left.y, 0)
+        XCTAssertEqual(boxes(height: -3, depth: -1).right, CGPoint(x: 24, y: 192))
+    }
+
+    func testOversizedCanvasIsClampedToThePanel() {
+        let b = G2CfwRenderer.lensBoxes(canvasWidth: 900, canvasHeight: 700, heightLevel: 4, depthLevel: 2)
+        XCTAssertEqual(b.width, 640)
+        XCTAssertEqual(b.height, 480)
+        XCTAssertEqual(b.left, .zero)
+        XCTAssertEqual(b.right, .zero)
+    }
+
+    // MARK: - Rasterization
+
+    func testCanvasIsRasterizedUnscaled() throws {
+        let pixels = try XCTUnwrap(G2CfwRenderer.rasterize(
+            frame([rect(x: 0, y: 0, w: 576, h: 288, border: 4)]), width: 576, height: 288
+        ))
+        XCTAssertEqual(pixels.count, 576 * 288)
+        func px(_ x: Int, _ y: Int) -> UInt8 {
+            pixels[y * 576 + x]
+        }
+        XCTAssertGreaterThan(px(100, 1), Self.white)
+        XCTAssertGreaterThan(px(1, 100), Self.white)
+        XCTAssertGreaterThan(px(574, 100), Self.white)
+        XCTAssertGreaterThan(px(100, 286), Self.white)
+        XCTAssertEqual(px(288, 144), 0)
+    }
+
+    func testOmittedBuiltinTextStillRasterizesItsBorder() throws {
+        let element = SceneElement(
+            id: "apps-button", type: "text", x: 16, y: 100, w: 200, h: 34,
+            text: "Apps", data: nil, border: 2, radius: 8, change: "created",
+            contentHash: "", font: "builtin"
+        )
+        let pixels = try XCTUnwrap(G2CfwRenderer.rasterize(
+            frame([element]), width: 576, height: 288, omitBuiltinText: true
+        ))
+        func px(_ x: Int, _ y: Int) -> UInt8 {
+            pixels[y * 576 + x]
+        }
+        // Border edges (past the corner radius) are stroked white.
+        XCTAssertGreaterThan(px(116, 101), 100) // top edge
+        XCTAssertGreaterThan(px(116, 132), 100) // bottom edge
+        XCTAssertGreaterThan(px(17, 117), 100) // left edge
+        XCTAssertGreaterThan(px(214, 117), 100) // right edge
+        // Interior stays black: the glyphs are firmware-drawn (mode 15).
+        XCTAssertEqual(px(116, 117), 0)
+
+        // A border-less builtin element is skipped entirely.
+        let plainElement = SceneElement(
+            id: "apps-button", type: "text", x: 16, y: 100, w: 200, h: 34,
+            text: "Apps", data: nil, border: 0, radius: 8, change: "created",
+            contentHash: "", font: "builtin"
+        )
+        let plain = try XCTUnwrap(G2CfwRenderer.rasterize(
+            frame([plainElement]), width: 576, height: 288, omitBuiltinText: true
+        ))
+        XCTAssertTrue(plain.allSatisfy { $0 == 0 })
+    }
+
+    // MARK: - Wire format
+
+    func testStereoFrameHeaderCarriesBothBoxesAndFrameId() throws {
+        let b = boxes(height: 4, depth: 2)
+        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
+    }
+
+    func testSolidStereoFrameMatchesPixelFrameHeader() throws {
+        let b = boxes(height: 0, depth: 1)
+        let solid = try XCTUnwrap(G2CfwRenderer.solidStereoFrame(color: 0, boxes: b, fid: 7))
+        XCTAssertEqual(Array(solid.prefix(11)), [0x83, 8, 96, 144, 144, 8, 96, 144, 144, 7, 0])
+    }
+
+    func testStereoFrameRejectsMismatchedPixelCount() {
+        XCTAssertNil(G2CfwRenderer.stereoFrame(pixels: Data(count: 10), boxes: boxes(height: 4, depth: 2), fid: 1))
+    }
+
+    func testBundleFramesSegmentsWithLittleEndianLengths() throws {
+        let a = Data([0x83, 1, 2, 3])
+        let b = Data(repeating: 6, count: 300)
+        let bundle = try XCTUnwrap(G2CfwRenderer.bundle([a, b]))
+        XCTAssertEqual(Array(bundle.prefix(4)), [8, 2, 4, 0])
+        XCTAssertEqual(Array(bundle[4 ..< 8]), [0x83, 1, 2, 3])
+        XCTAssertEqual(Array(bundle[8 ..< 10]), [0x2C, 0x01])
+        XCTAssertEqual(bundle.count, 2 + 2 + 4 + 2 + 300)
+        XCTAssertNil(G2CfwRenderer.bundle([]))
+    }
+
+    func testRleTokensMatchFirmwareDecoder() {
+        // 20 white pixels then 2 black: long run escapes to [color][count8]; short runs pack count<<4|color.
+        let pixels = Data(repeating: 0xFF, count: 20) + Data(repeating: 0, count: 2)
+        XCTAssertEqual(Array(G2CfwRenderer.rleEncode(G2CfwRenderer.pack4Bpp(pixels))), [0x0F, 20, 0x20])
+        let big = Data(repeating: 0xFF, count: 300)
+        XCTAssertEqual(Array(G2CfwRenderer.rleEncode(G2CfwRenderer.pack4Bpp(big))), [0x0F, 0, 0x2C, 0x01])
+    }
+
+    func testBlackKeyframeIsMode6() throws {
+        let payload = try XCTUnwrap(G2CfwRenderer.blackPayload())
+        XCTAssertEqual(payload.first, 6)
+        XCTAssertEqual(payload[1], 0x78)
+    }
+
+    func testSeededFramePayloadCompositesContentAtLensEqualWindow() throws {
+        let b = boxes(height: 4, depth: 1) // depth 1: both lenses share an x offset
+        let pixels = Data(repeating: 0xFF, count: Int(b.width) * Int(b.height))
+        let payload = try XCTUnwrap(G2CfwRenderer.seededFramePayload(pixels: pixels, boxes: b))
+        XCTAssertEqual(payload.first, 6)
+
+        // Byte-identical to a mode-6 encode of the hand-composed panel.
+        var expected = [UInt8](repeating: 0, count: 640 * 480)
+        for row in 0 ..< Int(b.height) {
+            let base = (Int(b.left.y) + row) * 640 + Int(b.left.x)
+            for col in 0 ..< Int(b.width) {
+                expected[base + col] = 0xFF
+            }
+        }
+        XCTAssertEqual(payload, G2CfwRenderer.encodePixels(Data(expected)))
+
+        // Mode 6 has no per-lens variant: differing windows and mismatched
+        // pixel counts must refuse rather than mis-place one lens.
+        XCTAssertNil(G2CfwRenderer.seededFramePayload(pixels: pixels, boxes: boxes(height: 4, depth: 2)))
+        XCTAssertNil(G2CfwRenderer.seededFramePayload(pixels: Data(count: 10), boxes: b))
+    }
+
+    // MARK: - Dirty-rect planning
+
+    private func raster(width: Int, height: Int, _ paint: (inout [UInt8]) -> Void = { _ in }) -> Data {
+        var pixels = [UInt8](repeating: 0, count: width * height)
+        paint(&pixels)
+        return Data(pixels)
+    }
+
+    func testIdenticalRastersPlanNothing() {
+        let base = raster(width: 64, height: 32)
+        let plan = G2CfwRenderer.diffPlan(
+            previous: base, next: base, width: 64, height: 32, forced: [], allowCopy: true
+        )
+        XCTAssertTrue(plan.isNoop)
+    }
+
+    func testSmallChangeBecomesOneAlignedRect() {
+        let width = 64
+        let height = 32
+        let prev = raster(width: width, height: height)
+        let next = raster(width: width, height: height) { px in
+            px[9 * width + 13] = 0xFF
+            px[10 * width + 17] = 0xFF
+        }
+        let plan = G2CfwRenderer.diffPlan(
+            previous: prev, next: next, width: width, height: height, forced: [], allowCopy: true
+        )
+        XCTAssertFalse(plan.full)
+        XCTAssertNil(plan.copy)
+        XCTAssertEqual(plan.rects, [G2CfwRenderer.CanvasRect(x: 12, y: 8, w: 8, h: 4)])
+    }
+
+    func testDistantChangesBecomeSeparateRects() {
+        let width = 64
+        let height = 64
+        let prev = raster(width: width, height: height)
+        let next = raster(width: width, height: height) { px in
+            px[2 * width + 4] = 0xFF
+            px[60 * width + 40] = 0xFF
+        }
+        let plan = G2CfwRenderer.diffPlan(
+            previous: prev, next: next, width: width, height: height, forced: [], allowCopy: true
+        )
+        XCTAssertEqual(plan.rects.count, 2)
+    }
+
+    func testLargeChangeFallsBackToFullFrame() {
+        let width = 64
+        let height = 32
+        let prev = raster(width: width, height: height)
+        let next = raster(width: width, height: height) { px in
+            for i in px.indices where i % 2 == 0 {
+                px[i] = 0xFF
+            }
+        }
+        let plan = G2CfwRenderer.diffPlan(
+            previous: prev, next: next, width: width, height: height, forced: [], allowCopy: true
+        )
+        XCTAssertTrue(plan.full)
+    }
+
+    func testForcedRectsDirtyUnchangedPixels() {
+        let base = raster(width: 64, height: 32)
+        let plan = G2CfwRenderer.diffPlan(
+            previous: base, next: base, width: 64, height: 32,
+            forced: [G2CfwRenderer.CanvasRect(x: 5, y: 3, w: 10, h: 6)], allowCopy: true
+        )
+        XCTAssertFalse(plan.full)
+        XCTAssertEqual(plan.rects, [G2CfwRenderer.CanvasRect(x: 4, y: 2, w: 12, h: 8)])
+    }
+
+    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) }
+        let prev = raster(width: width, height: height) { px in
+            for y in 0 ..< height {
+                for x in 0 ..< width {
+                    px[y * width + x] = content(y) &+ UInt8(x % 3)
+                }
+            }
+        }
+        let next = raster(width: width, height: height) { px in
+            for y in 0 ..< height {
+                let source = y + 8
+                for x in 0 ..< width {
+                    px[y * width + x] = source < height ? content(source) &+ UInt8(x % 3) : 0xEE
+                }
+            }
+        }
+        let plan = G2CfwRenderer.diffPlan(
+            previous: prev, next: next, width: width, height: height, forced: [], allowCopy: true
+        )
+        XCTAssertFalse(plan.full)
+        XCTAssertEqual(plan.copy, G2CfwRenderer.RowCopy(srcY: 8, dstY: 0, height: 88))
+        // Residue: only the fresh rows at the bottom still need pixels.
+        XCTAssertEqual(plan.rects.count, 1)
+        XCTAssertEqual(plan.rects[0].y, 88)
+        XCTAssertEqual(plan.rects[0].h, 8)
+    }
+
+    func testScrollIsSkippedWhenCopyingIsDisallowed() {
+        let width = 64
+        let height = 96
+        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 { px[y * width + x] = content(y) &+ UInt8(x % 3) } }
+        }
+        let next = raster(width: width, height: height) { px in
+            for y in 0 ..< height {
+                let source = y + 8
+                for x in 0 ..< width {
+                    px[y * width + x] = source < height ? content(source) &+ UInt8(x % 3) : 0xEE
+                }
+            }
+        }
+        let plan = G2CfwRenderer.diffPlan(
+            previous: prev, next: next, width: width, height: height, forced: [], allowCopy: false
+        )
+        XCTAssertNil(plan.copy)
+    }
+
+    // MARK: - Delta / copy / builtin-text wire formats
+
+    func testBoxDeltaFrameOffsetsBothLensWindows() throws {
+        let b = boxes(height: 4, depth: 2) // left (24,128), right (40,128)
+        let canvas = raster(width: 576, height: 288)
+        let rect = G2CfwRenderer.CanvasRect(x: 100, y: 50, w: 32, h: 16)
+        let payload = try XCTUnwrap(
+            G2CfwRenderer.boxDeltaFrame(raster: canvas, canvasWidth: 576, rect: rect, boxes: b, fid: 5)
+        )
+        XCTAssertEqual(
+            Array(payload.prefix(11)),
+            [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)
+    }
+
+    func testBoxDeltaFrameRejectsUnalignedRects() {
+        let canvas = raster(width: 576, height: 288)
+        XCTAssertNil(G2CfwRenderer.boxDeltaFrame(
+            raster: canvas, canvasWidth: 576,
+            rect: G2CfwRenderer.CanvasRect(x: 3, y: 0, w: 32, h: 16),
+            boxes: boxes(height: 4, depth: 2), fid: 1
+        ))
+    }
+
+    func testRectCopyPayloadCarriesPerLensRectSets() {
+        let b = boxes(height: 4, depth: 2) // left (24,128), right (40,128)
+        let copy = G2CfwRenderer.RowCopy(srcY: 20, dstY: 8, height: 100)
+        let payload = G2CfwRenderer.rectCopyPayload(copy: copy, width: 576, boxes: b)
+        XCTAssertEqual(payload.count, 33)
+        XCTAssertEqual(payload[0], 0x89)
+        func u16(_ offset: Int) -> Int { Int(payload[offset]) | Int(payload[offset + 1]) << 8 }
+        // Left lens: src (24, 148, 576, 100) → dst (24, 136, 576, 100)
+        XCTAssertEqual([u16(1), u16(3), u16(5), u16(7)], [24, 148, 576, 100])
+        XCTAssertEqual([u16(9), u16(11), u16(13), u16(15)], [24, 136, 576, 100])
+        // Right lens: same band at its own window origin.
+        XCTAssertEqual([u16(17), u16(19), u16(21), u16(23)], [40, 148, 576, 100])
+        XCTAssertEqual([u16(25), u16(27), u16(29), u16(31)], [40, 136, 576, 100])
+    }
+
+    func testBuiltinStringPayloadMatchesMode15Wire() throws {
+        let payload = try XCTUnwrap(
+            G2CfwRenderer.builtinStringPayload(x: 300, y: 130, options: 0x1F, text: "Hi ✓")
+        )
+        let bytes = Array("Hi ✓".utf8)
+        XCTAssertEqual(Array(payload.prefix(7)), [15, 0x2C, 0x01, 130, 0, 0x1F, UInt8(bytes.count)])
+        XCTAssertEqual(Array(payload.dropFirst(7)), bytes)
+    }
+
+    func testBuiltinStringPayloadStripsControlBytesAndTruncates() throws {
+        // Bytes 1–31 are firmware x-adjust controls; raw control chars must not leak.
+        let payload = try XCTUnwrap(
+            G2CfwRenderer.builtinStringPayload(x: 0, y: 0, options: 0, text: "a\tb\u{07}c")
+        )
+        XCTAssertEqual(Array(payload.dropFirst(7)), Array("abc".utf8))
+        let long = String(repeating: "é", count: 200) // 400 UTF-8 bytes
+        let truncated = try XCTUnwrap(G2CfwRenderer.builtinStringPayload(x: 0, y: 0, options: 0, text: long))
+        XCTAssertEqual(truncated[6], 254) // even byte count — no split codepoint
+        XCTAssertNil(G2CfwRenderer.builtinStringPayload(x: 0, y: 0, options: 0, text: "\u{01}\u{02}"))
+    }
+
+    func testBuiltinTextDrawsSplitLinesAtTheLineHeight() {
+        let b = boxes(height: 4, depth: 1) // equal lens x = 32
+        let element = SceneElement(
+            id: "t", type: "text", x: 10, y: 20, w: 200, h: 80, text: "one\ntwo", data: nil,
+            border: 0, radius: 0, change: "created", contentHash: "", font: "builtin"
+        )
+        let draws = G2CfwRenderer.builtinTextDraws(frame([element]), boxes: b)
+        XCTAssertEqual(draws, [
+            G2CfwRenderer.TextDraw(x: 32 + 10 + 2, y: 128 + 20 + 2, text: "one"),
+            G2CfwRenderer.TextDraw(x: 32 + 10 + 2, y: 128 + 20 + 2 + 27, text: "two"),
+        ])
+        let bounds = G2CfwRenderer.builtinTextBounds(draws, boxes: b, canvasWidth: 576, canvasHeight: 288)
+        XCTAssertEqual(bounds.count, 2)
+        XCTAssertEqual(bounds[0].x, 8)
+        XCTAssertEqual(bounds[0].y, 20)
+    }
+}

package/ios/Tests/BluetoothSDKTests/G2CfwTextureCacheTests.swift

@@ -0,0 +1,162 @@
+@testable import BluetoothSDK
+import Foundation
+import XCTest
+
+final class G2CfwTextureCacheTests: XCTestCase {
+    // MARK: - Flat RLE (cached-image contract: exact pixel count, no row pad)
+
+    func testRleEncodePixelsCoversExactPixelCount() {
+        // 3 white pixels — the odd count must NOT gain a pad nibble.
+        XCTAssertEqual(
+            Array(G2CfwTextureCache.rleEncodePixels(Data([0xFF, 0xFF, 0xF0]))), [0x3F]
+        )
+        XCTAssertEqual(
+            Array(G2CfwTextureCache.rleEncodePixels(Data(repeating: 0xFF, count: 300))),
+            [0x0F, 0, 0x2C, 0x01]
+        )
+        XCTAssertEqual(
+            Array(G2CfwTextureCache.rleEncodePixels(Data([0x00, 0xFF]))), [0x10, 0x1F]
+        )
+    }
+
+    // MARK: - Cache model
+
+    func testAllocationsSkipTheZeroGuardAndPatchTheFontTable() 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 })
+
+        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),
+        ])
+
+        XCTAssertTrue(cache.takeUploadPayloads().isEmpty)
+        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 })
+        XCTAssertEqual(cache.takeUploadPayloads().count, 1)
+    }
+
+    func testImagePromotionRequiresASecondSighting() {
+        let cache = G2CfwTextureCache()
+        cache.reset(generation: 1)
+        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)
+        XCTAssertNil(cache.ensureImage(hash: "big", gray: Data(count: 300 * 10), width: 300, height: 10))
+    }
+
+    // MARK: - Draw payload wire formats
+
+    func testImageDrawPayloadMatchesMode13Wire() throws {
+        let payload = try XCTUnwrap(
+            G2CfwTextureCache.imageDrawPayload(offset: 0x1234, x: 300, y: 130, options: 0x0F)
+        )
+        XCTAssertEqual(Array(payload), [13, 0x34, 0x12, 0x2C, 0x01, 130, 0, 0x0F])
+    }
+
+    func testStringRunPayloadMatchesMode14Wire() throws {
+        let chars = Array("Hi".utf8)
+        let payload = try XCTUnwrap(G2CfwTextureCache.stringRunPayload(
+            fontTableOffset: 2, x: 40, y: 150, options: 0x0F, chars: chars
+        ))
+        XCTAssertEqual(Array(payload), [14, 2, 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]
+        ))
+    }
+
+    // MARK: - End-to-end mono fast path (actor)
+
+    private func monoFrame(_ text: String) -> SceneFrame {
+        SceneFrame(appId: "t", epoch: 1, replay: false, elements: [
+            SceneElement(
+                id: "screen", type: "text", x: 0, y: 0, w: 576, h: 288, text: text, data: nil,
+                border: 0, radius: 0, change: "updated", contentHash: "", font: "mono", fontSize: 12
+            ),
+        ], removed: [])
+    }
+
+    func testMonoTextChangeBecomesCachedGlyphRunsNotBitmapDeltas() async throws {
+        let renderer = G2CfwRenderer()
+        // Depth level 1 = lens-equal window, the texture-path requirement.
+        let boxes = G2CfwRenderer.lensBoxes(canvasWidth: 576, canvasHeight: 288, heightLevel: 4, depthLevel: 1)
+        let fids: [UInt16] = (1 ... UInt16(G2CfwRenderer.requiredFidCount)).map { $0 }
+
+        let firstResult = await renderer.encodeUpdate(
+            monoFrame("hello world\nrow two"), boxes: boxes, previousRaster: nil,
+            forcedRects: [], fids: fids, textDraws: [], allowRectCopy: true,
+            blankBoxes: nil, omitBuiltinText: false,
+            textureGlyphsEnabled: true, textureImagesEnabled: true, cacheGeneration: 7
+        )
+        let first = try XCTUnwrap(firstResult)
+        XCTAssertTrue(first.usedFullFrame)
+
+        let secondResult = await renderer.encodeUpdate(
+            monoFrame("hello there\nrow two"), boxes: boxes, previousRaster: first.raster,
+            forcedRects: [], fids: fids, textDraws: [], allowRectCopy: true,
+            blankBoxes: nil, omitBuiltinText: false,
+            textureGlyphsEnabled: true, textureImagesEnabled: true, cacheGeneration: 7
+        )
+        let second = try XCTUnwrap(secondResult)
+        XCTAssertFalse(second.usedFullFrame)
+        // The changed cells travel as mode-12 uploads + mode-14 runs; no
+        // bitmap delta (0x83) should remain for a pure-ASCII grid change.
+        XCTAssertFalse(second.uploads.isEmpty)
+        XCTAssertTrue(second.uploads.allSatisfy { $0.first == 12 })
+        let payload = try XCTUnwrap(second.payload)
+        if payload.first == 8 {
+            var segments: [UInt8] = []
+            var pos = 2
+            let bytes = [UInt8](payload)
+            while pos + 2 <= bytes.count {
+                let len = Int(bytes[pos]) | Int(bytes[pos + 1]) << 8
+                pos += 2
+                if pos < bytes.count { segments.append(bytes[pos]) }
+                pos += len
+            }
+            XCTAssertTrue(segments.contains(14))
+            XCTAssertFalse(segments.contains(0x83))
+        } else {
+            XCTAssertEqual(payload.first, 14)
+        }
+
+        // A lens-unequal window must fall back to plain bitmap deltas.
+        let stereo = G2CfwRenderer.lensBoxes(canvasWidth: 576, canvasHeight: 288, heightLevel: 4, depthLevel: 2)
+        let plainResult = await renderer.encodeUpdate(
+            monoFrame("hello"), boxes: stereo, previousRaster: nil,
+            forcedRects: [], fids: fids, textDraws: [], allowRectCopy: true,
+            blankBoxes: nil, omitBuiltinText: false,
+            textureGlyphsEnabled: true, textureImagesEnabled: true, cacheGeneration: 7
+        )
+        let plain = try XCTUnwrap(plainResult)
+        XCTAssertTrue(plain.uploads.isEmpty)
+        XCTAssertEqual(plain.payload?.first, 0x83)
+    }
+}