@glassly/bluetooth-sdk 0.1.0-dev.26

package/android/src/test/java/com/glassly/bluetoothsdk/sgcs/G2CfwRendererTest.kt

@@ -0,0 +1,344 @@
+package com.glassly.bluetoothsdk.sgcs
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+import org.robolectric.annotation.GraphicsMode
+
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [33])
+@GraphicsMode(GraphicsMode.Mode.NATIVE)
+class G2CfwRendererTest {
+    @Test
+    fun placementMatchesStockWindowTablesAndClamps() {
+        val defaults = boxes(height = 4, depth = 2)
+        assertEquals(G2CfwRenderer.LensBoxes(24, 128, 40, 128, 576, 288), defaults)
+
+        assertEquals(32, boxes(height = 6, depth = 1).leftX)
+        assertEquals(32, boxes(height = 6, depth = 1).rightX)
+        assertEquals(40, boxes(height = 6, depth = 0).leftX)
+        assertEquals(24, boxes(height = 6, depth = 0).rightX)
+        assertEquals(192, boxes(height = 0, depth = 1).leftY)
+        assertEquals(0, boxes(height = 99, depth = 7).leftY)
+
+        val oversized = G2CfwRenderer.lensBoxes(900, 700, 4, 2)
+        assertEquals(G2CfwRenderer.LensBoxes(0, 0, 0, 0, 640, 480), oversized)
+    }
+
+    @Test
+    fun canvasIsRasterizedOneToOne() {
+        val pixels = G2CfwRenderer.rasterize(frame(rect(border = 4)), 576, 288)
+        assertNotNull(pixels)
+        pixels!!
+        assertEquals(576 * 288, pixels.size)
+        fun pixel(x: Int, y: Int) = pixels[y * 576 + x].toInt() and 0xFF
+        assertTrue(pixel(100, 1) > 200)
+        assertTrue(pixel(1, 100) > 200)
+        assertTrue(pixel(574, 100) > 200)
+        assertTrue(pixel(100, 286) > 200)
+        assertEquals(0, pixel(288, 144))
+    }
+
+    @Test
+    fun wireHeaderCarriesBothLensBoxesAndFrameId() {
+        val payload = G2CfwRenderer.stereoFrame(ByteArray(576 * 288), boxes(4, 2), 0x1234)
+        assertNotNull(payload)
+        assertEquals(
+            listOf(0x83, 6, 64, 144, 144, 10, 64, 144, 144, 0x34, 0x12),
+            payload!!.take(11).map { it.toInt() and 0xFF },
+        )
+        assertEquals(0x78, payload[11].toInt() and 0xFF)
+        assertNull(G2CfwRenderer.stereoFrame(ByteArray(10), boxes(4, 2), 1))
+    }
+
+    @Test
+    fun bundleAndRleMatchFirmwareDecoder() {
+        val first = byteArrayOf(0x83.toByte(), 1, 2, 3)
+        val second = ByteArray(300) { 6 }
+        val bundle = G2CfwRenderer.bundle(listOf(first, second))
+        assertNotNull(bundle)
+        assertEquals(listOf(8, 2, 4, 0), bundle!!.take(4).map { it.toInt() and 0xFF })
+        assertEquals(listOf(0x2C, 0x01), bundle.copyOfRange(8, 10).map { it.toInt() and 0xFF })
+        assertEquals(310, bundle.size)
+        assertNull(G2CfwRenderer.bundle(emptyList()))
+
+        // Round-to-nearest quantization (reference GRAY_TO_NIBBLE): [8,15]
+        // promotes to level 1, 7 stays 0, and 0 is pinned for the transparent
+        // color key.
+        assertEquals(0, G2CfwRenderer.grayNibble(0))
+        assertEquals(0, G2CfwRenderer.grayNibble(7))
+        assertEquals(1, G2CfwRenderer.grayNibble(8))
+        assertEquals(9, G2CfwRenderer.grayNibble(0x88))
+        assertEquals(15, G2CfwRenderer.grayNibble(234))
+        assertEquals(15, G2CfwRenderer.grayNibble(255))
+
+        val pixels = ByteArray(22) { if (it < 20) 0xFF.toByte() else 0 }
+        assertEquals(
+            listOf(0x0F, 20, 0x20),
+            G2CfwRenderer.rleEncode(G2CfwRenderer.pack4Bpp(pixels)).map { it.toInt() and 0xFF },
+        )
+        assertEquals(
+            listOf(0x0F, 0, 0x2C, 0x01),
+            G2CfwRenderer.rleEncode(G2CfwRenderer.pack4Bpp(ByteArray(300) { 0xFF.toByte() }))
+                .map { it.toInt() and 0xFF },
+        )
+    }
+
+    @Test
+    fun blackKeyframeUsesModeSixZlibEnvelope() {
+        val payload = G2CfwRenderer.blackPayload()
+        assertNotNull(payload)
+        assertEquals(6, payload!![0].toInt() and 0xFF)
+        assertEquals(0x78, payload[1].toInt() and 0xFF)
+    }
+
+    @Test
+    fun seededFramePayloadCompositesContentAtLensEqualWindow() {
+        val lensEqual = boxes(height = 4, depth = 1) // depth 1: both lenses share an x offset
+        val pixels = ByteArray(lensEqual.width * lensEqual.height) { 0xFF.toByte() }
+        val payload = G2CfwRenderer.seededFramePayload(pixels, lensEqual)
+        assertNotNull(payload)
+        assertEquals(6, payload!![0].toInt() and 0xFF)
+
+        // Byte-identical to a mode-6 encode of the hand-composed panel.
+        val expected = ByteArray(G2CfwRenderer.FRAME_WIDTH * G2CfwRenderer.FRAME_HEIGHT)
+        for (row in 0 until lensEqual.height) {
+            val base = (lensEqual.leftY + row) * G2CfwRenderer.FRAME_WIDTH + lensEqual.leftX
+            expected.fill(0xFF.toByte(), base, base + lensEqual.width)
+        }
+        assertTrue(payload.contentEquals(G2CfwRenderer.encodePixels(expected)))
+
+        // Mode 6 has no per-lens variant: differing windows and mismatched
+        // pixel counts must refuse rather than mis-place one lens.
+        assertNull(G2CfwRenderer.seededFramePayload(pixels, boxes(height = 4, depth = 2)))
+        assertNull(G2CfwRenderer.seededFramePayload(ByteArray(10), lensEqual))
+    }
+
+    // ── Dirty-rect planning ──────────────────────────────────────────────
+
+    private fun raster(width: Int, height: Int, paint: (ByteArray) -> Unit = {}): ByteArray =
+        ByteArray(width * height).also(paint)
+
+    @Test
+    fun identicalRastersPlanNothing() {
+        val base = raster(64, 32)
+        val plan = G2CfwRenderer.diffPlan(base, base, 64, 32, emptyList(), allowCopy = true)
+        assertTrue(plan.isNoop)
+    }
+
+    @Test
+    fun smallChangeBecomesOneAlignedRect() {
+        val width = 64
+        val prev = raster(width, 32)
+        val next = raster(width, 32) {
+            it[9 * width + 13] = 0xFF.toByte()
+            it[10 * width + 17] = 0xFF.toByte()
+        }
+        val plan = G2CfwRenderer.diffPlan(prev, next, width, 32, emptyList(), allowCopy = true)
+        assertTrue(!plan.full)
+        assertNull(plan.copy)
+        assertEquals(listOf(G2CfwRenderer.CanvasRect(12, 8, 8, 4)), plan.rects)
+    }
+
+    @Test
+    fun distantChangesBecomeSeparateRectsAndLargeChangesGoFull() {
+        val width = 64
+        val prev = raster(width, 64)
+        val next = raster(width, 64) {
+            it[2 * width + 4] = 0xFF.toByte()
+            it[60 * width + 40] = 0xFF.toByte()
+        }
+        assertEquals(2, G2CfwRenderer.diffPlan(prev, next, width, 64, emptyList(), true).rects.size)
+
+        val noisy = raster(width, 32) {
+            for (i in it.indices step 2) it[i] = 0xFF.toByte()
+        }
+        assertTrue(G2CfwRenderer.diffPlan(raster(width, 32), noisy, width, 32, emptyList(), true).full)
+    }
+
+    @Test
+    fun forcedRectsDirtyUnchangedPixels() {
+        val base = raster(64, 32)
+        val plan =
+            G2CfwRenderer.diffPlan(
+                base, base, 64, 32,
+                listOf(G2CfwRenderer.CanvasRect(5, 3, 10, 6)), allowCopy = true,
+            )
+        assertTrue(!plan.full)
+        assertEquals(listOf(G2CfwRenderer.CanvasRect(4, 2, 12, 8)), plan.rects)
+    }
+
+    @Test
+    fun verticalScrollBecomesRectCopyPlusResidue() {
+        val width = 64
+        val height = 96
+        fun content(row: Int) = ((row * 7) % 251).toByte()
+        val prev = raster(width, height) {
+            for (y in 0 until height) for (x in 0 until width) {
+                it[y * width + x] = (content(y) + (x % 3)).toByte()
+            }
+        }
+        val next = raster(width, height) {
+            for (y in 0 until height) for (x in 0 until width) {
+                val source = y + 8
+                it[y * width + x] =
+                    if (source < height) (content(source) + (x % 3)).toByte() else 0xEE.toByte()
+            }
+        }
+        val plan = G2CfwRenderer.diffPlan(prev, next, width, height, emptyList(), allowCopy = true)
+        assertTrue(!plan.full)
+        assertEquals(G2CfwRenderer.RowCopy(srcY = 8, dstY = 0, height = 88), plan.copy)
+        assertEquals(1, plan.rects.size)
+        assertEquals(88, plan.rects[0].y)
+        assertEquals(8, plan.rects[0].h)
+
+        assertNull(G2CfwRenderer.diffPlan(prev, next, width, height, emptyList(), allowCopy = false).copy)
+    }
+
+    // ── Delta / copy / builtin-text wire formats ─────────────────────────
+
+    @Test
+    fun boxDeltaFrameOffsetsBothLensWindows() {
+        val b = boxes(height = 4, depth = 2) // left (24,128), right (40,128)
+        val rect = G2CfwRenderer.CanvasRect(100, 50, 32, 16)
+        val payload = G2CfwRenderer.boxDeltaFrame(raster(576, 288), 576, rect, b, 5)
+        assertNotNull(payload)
+        assertEquals(
+            listOf(0x83, (24 + 100) / 4, (128 + 50) / 2, 8, 8, (40 + 100) / 4, (128 + 50) / 2, 8, 8, 5, 0),
+            payload!!.take(11).map { it.toInt() and 0xFF },
+        )
+        assertEquals(0x78, payload[11].toInt() and 0xFF)
+        assertNull(
+            G2CfwRenderer.boxDeltaFrame(raster(576, 288), 576, G2CfwRenderer.CanvasRect(3, 0, 32, 16), b, 1)
+        )
+    }
+
+    @Test
+    fun rectCopyPayloadCarriesPerLensRectSets() {
+        val b = boxes(height = 4, depth = 2) // left (24,128), right (40,128)
+        val payload = G2CfwRenderer.rectCopyPayload(G2CfwRenderer.RowCopy(20, 8, 100), 576, b)
+        assertEquals(33, payload.size)
+        assertEquals(0x89, payload[0].toInt() and 0xFF)
+        fun u16(offset: Int) = (payload[offset].toInt() and 0xFF) or ((payload[offset + 1].toInt() and 0xFF) shl 8)
+        assertEquals(listOf(24, 148, 576, 100), listOf(u16(1), u16(3), u16(5), u16(7)))
+        assertEquals(listOf(24, 136, 576, 100), listOf(u16(9), u16(11), u16(13), u16(15)))
+        assertEquals(listOf(40, 148, 576, 100), listOf(u16(17), u16(19), u16(21), u16(23)))
+        assertEquals(listOf(40, 136, 576, 100), listOf(u16(25), u16(27), u16(29), u16(31)))
+    }
+
+    @Test
+    fun builtinStringPayloadMatchesMode15Wire() {
+        val payload = G2CfwRenderer.builtinStringPayload(300, 130, 0x1F, "Hi ✓")
+        assertNotNull(payload)
+        val bytes = "Hi ✓".toByteArray(Charsets.UTF_8)
+        assertEquals(
+            listOf(15, 0x2C, 0x01, 130, 0, 0x1F, bytes.size),
+            payload!!.take(7).map { it.toInt() and 0xFF },
+        )
+        assertEquals(bytes.toList(), payload.drop(7))
+
+        // Bytes 1–31 are firmware x-adjust controls; raw control chars must not leak.
+        val cleaned = G2CfwRenderer.builtinStringPayload(0, 0, 0, "a\tbc")
+        assertEquals("abc".toByteArray(Charsets.UTF_8).toList(), cleaned!!.drop(7))
+        val truncated = G2CfwRenderer.builtinStringPayload(0, 0, 0, "é".repeat(200))
+        assertEquals(254, truncated!![6].toInt() and 0xFF) // no split codepoint
+        assertNull(G2CfwRenderer.builtinStringPayload(0, 0, 0, "
"))
+    }
+
+    @Test
+    fun builtinTextDrawsSplitLinesAtTheLineHeight() {
+        val b = boxes(height = 4, depth = 1) // equal lens x = 32
+        val element =
+            SceneElement(
+                id = "t",
+                type = "text",
+                x = 10,
+                y = 20,
+                w = 200,
+                h = 80,
+                text = "one\ntwo",
+                data = null,
+                border = 0,
+                radius = 0,
+                change = "created",
+                contentHash = "",
+                font = "builtin",
+            )
+        val draws = G2CfwRenderer.builtinTextDraws(frame(element), b)
+        assertEquals(
+            listOf(
+                G2CfwRenderer.TextDraw(32 + 10 + 2, 128 + 20 + 2, "one"),
+                G2CfwRenderer.TextDraw(32 + 10 + 2, 128 + 20 + 2 + 27, "two"),
+            ),
+            draws,
+        )
+        val bounds = G2CfwRenderer.builtinTextBounds(draws, b, 576, 288)
+        assertEquals(2, bounds.size)
+        assertEquals(8, bounds[0].x)
+        assertEquals(20, bounds[0].y)
+    }
+
+    @Test
+    fun omittedBuiltinTextStillRasterizesItsBorder() {
+        val element =
+            SceneElement(
+                id = "apps-button",
+                type = "text",
+                x = 16,
+                y = 100,
+                w = 200,
+                h = 34,
+                text = "Apps",
+                data = null,
+                border = 2,
+                radius = 8,
+                change = "created",
+                contentHash = "",
+                font = "builtin",
+            )
+        val pixels = G2CfwRenderer.rasterize(frame(element), 576, 288, omitBuiltinText = true)
+        assertNotNull(pixels)
+        pixels!!
+        fun pixel(x: Int, y: Int) = pixels[y * 576 + x].toInt() and 0xFF
+        // Border edges (past the corner radius) are stroked white.
+        assertTrue(pixel(116, 101) > 100) // top edge
+        assertTrue(pixel(116, 132) > 100) // bottom edge
+        assertTrue(pixel(17, 117) > 100) // left edge
+        assertTrue(pixel(214, 117) > 100) // right edge
+        // Interior stays black: the glyphs are firmware-drawn (mode 15).
+        assertEquals(0, pixel(116, 117))
+        // A border-less builtin element is skipped entirely.
+        val plain = G2CfwRenderer.rasterize(
+            frame(element.copy(border = 0)), 576, 288, omitBuiltinText = true
+        )
+        assertNotNull(plain)
+        assertTrue(plain!!.all { it.toInt() == 0 })
+    }
+
+    private fun boxes(height: Int, depth: Int) =
+        G2CfwRenderer.lensBoxes(576, 288, height, depth)
+
+    private fun rect(border: Int) =
+        SceneElement(
+            id = "r",
+            type = "rect",
+            x = 0,
+            y = 0,
+            w = 576,
+            h = 288,
+            text = null,
+            data = null,
+            border = border,
+            radius = 0,
+            change = "created",
+            contentHash = "",
+        )
+
+    private fun frame(element: SceneElement) =
+        SceneFrame(appId = "test", epoch = 1, replay = false, elements = listOf(element), removed = emptyList())
+}

package/android/src/test/java/com/glassly/bluetoothsdk/sgcs/G2CfwTextureCacheTest.kt

@@ -0,0 +1,200 @@
+package com.glassly.bluetoothsdk.sgcs
+
+import org.junit.Assert.assertArrayEquals
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+import org.robolectric.annotation.GraphicsMode
+
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [33])
+@GraphicsMode(GraphicsMode.Mode.NATIVE)
+class G2CfwTextureCacheTest {
+    // ── Flat RLE (cached-image contract: exact pixel count, no row pad) ─────
+
+    @Test
+    fun rleEncodePixelsCoversExactPixelCount() {
+        // 3 white pixels — the odd count must NOT gain a pad nibble.
+        assertArrayEquals(
+            byteArrayOf(0x3F),
+            G2CfwTextureCache.rleEncodePixels(byteArrayOf(0xFF.toByte(), 0xFF.toByte(), 0xF0.toByte())),
+        )
+        assertArrayEquals(
+            byteArrayOf(0x0F, 0, 0x2C, 0x01),
+            G2CfwTextureCache.rleEncodePixels(ByteArray(300) { 0xFF.toByte() }),
+        )
+        assertArrayEquals(
+            byteArrayOf(0x10, 0x1F),
+            G2CfwTextureCache.rleEncodePixels(byteArrayOf(0x00, 0xFF.toByte())),
+        )
+    }
+
+    // ── Cache model ─────────────────────────────────────────────────────────
+
+    @Test
+    fun allocationsSkipTheZeroGuardAndPatchTheFontTable() {
+        val cache = G2CfwTextureCache()
+        cache.reset(1)
+        val font = cache.font(fontSize = 12, cellWidth = 4, lineHeight = 2)
+        assertNotNull(font)
+        font!!
+        // Bytes 0..1 stay zero (invalid-image guard); the table lands at 2.
+        assertEquals(2, font.tableOffset)
+
+        val raster = ByteArray(8) { 0xFF.toByte() } // 4×2 white cell
+        assertTrue(cache.ensureGlyph(font, 'A'.code) { raster })
+        // Second ensure is a no-op (no duplicate uploads).
+        assertTrue(cache.ensureGlyph(font, 'A'.code) { raster })
+
+        val payloads = cache.takeUploadPayloads()
+        assertEquals(1, payloads.size)
+        // [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.
+        val glyphOffset = 2 + 96 * 2 // 194
+        val patchOffset = 2 + ('A'.code - 32) * 2
+        assertArrayEquals(
+            byteArrayOf(
+                12,
+                (glyphOffset and 0xFF).toByte(), (glyphOffset ushr 8).toByte(), 3, 0, 4, 2, 0x8F.toByte(),
+                (patchOffset and 0xFF).toByte(), (patchOffset ushr 8).toByte(), 2, 0,
+                (glyphOffset and 0xFF).toByte(), (glyphOffset ushr 8).toByte(),
+            ),
+            payloads[0],
+        )
+
+        assertTrue(cache.takeUploadPayloads().isEmpty())
+        cache.reset(2)
+        // After a reset the same glyph re-uploads.
+        val font2 = cache.font(fontSize = 12, cellWidth = 4, lineHeight = 2)
+        assertNotNull(font2)
+        assertTrue(cache.ensureGlyph(font2!!, 'A'.code) { raster })
+        assertEquals(1, cache.takeUploadPayloads().size)
+    }
+
+    @Test
+    fun imagePromotionRequiresASecondSighting() {
+        val cache = G2CfwTextureCache()
+        cache.reset(1)
+        assertFalse(cache.noteImageSighting("icon@10x10"))
+        assertTrue(cache.noteImageSighting("icon@10x10"))
+        val gray = ByteArray(100) { 0x80.toByte() }
+        val offset = cache.ensureImage("icon@10x10", gray, width = 10, height = 10)
+        assertNotNull(offset)
+        assertEquals(offset, cache.ensureImage("icon@10x10", gray, width = 10, height = 10))
+        assertNull(cache.ensureImage("big", ByteArray(300 * 10), width = 300, height = 10))
+    }
+
+    // ── Draw payload wire formats ───────────────────────────────────────────
+
+    @Test
+    fun imageDrawPayloadMatchesMode13Wire() {
+        val payload = G2CfwTextureCache.imageDrawPayload(offset = 0x1234, x = 300, y = 130, options = 0x0F)
+        assertNotNull(payload)
+        assertArrayEquals(
+            byteArrayOf(13, 0x34, 0x12, 0x2C, 0x01, 130.toByte(), 0, 0x0F),
+            payload,
+        )
+    }
+
+    @Test
+    fun stringRunPayloadMatchesMode14Wire() {
+        val chars = "Hi".toByteArray(Charsets.US_ASCII)
+        val payload =
+            G2CfwTextureCache.stringRunPayload(fontTableOffset = 2, x = 40, y = 150, options = 0x0F, chars = chars)
+        assertNotNull(payload)
+        assertArrayEquals(
+            byteArrayOf(14, 2, 0, 40, 0, 150.toByte(), 0, 0x0F, 2) + chars,
+            payload,
+        )
+        // Control/non-ASCII bytes are x-adjust commands on the wire — rejected.
+        assertNull(G2CfwTextureCache.stringRunPayload(2, 0, 0, 0, byteArrayOf(10)))
+        assertNull(G2CfwTextureCache.stringRunPayload(2, 0, 0, 0, byteArrayOf(200.toByte())))
+    }
+
+    // ── End-to-end mono fast path ───────────────────────────────────────────
+
+    private fun monoFrame(text: String): SceneFrame =
+        SceneFrame(
+            appId = "t",
+            epoch = 1,
+            replay = false,
+            elements =
+                listOf(
+                    SceneElement(
+                        id = "screen", type = "text", x = 0, y = 0, w = 576, h = 288,
+                        text = text, data = null, border = 0, radius = 0,
+                        change = "updated", contentHash = "", font = "mono", fontSize = 12,
+                    )
+                ),
+            removed = emptyList(),
+        )
+
+    @Test
+    fun monoTextChangeBecomesCachedGlyphRunsNotBitmapDeltas() {
+        // Depth level 1 = lens-equal window, the texture-path requirement.
+        val boxes = G2CfwRenderer.lensBoxes(576, 288, heightLevel = 4, depthLevel = 1)
+        val fids = List(G2CfwRenderer.REQUIRED_FID_COUNT) { it + 1 }
+
+        val first =
+            G2CfwRenderer.encodeUpdate(
+                monoFrame("hello world\nrow two"), boxes, previousRaster = null,
+                forcedRects = emptyList(), fids = fids, textDraws = emptyList(),
+                allowRectCopy = true, blankBoxes = null, omitBuiltinText = false,
+                textureGlyphsEnabled = true, textureImagesEnabled = true, cacheGeneration = 7,
+            )
+        assertNotNull(first)
+        assertTrue(first!!.usedFullFrame)
+
+        val second =
+            G2CfwRenderer.encodeUpdate(
+                monoFrame("hello there\nrow two"), boxes, previousRaster = first.raster,
+                forcedRects = emptyList(), fids = fids, textDraws = emptyList(),
+                allowRectCopy = true, blankBoxes = null, omitBuiltinText = false,
+                textureGlyphsEnabled = true, textureImagesEnabled = true, cacheGeneration = 7,
+            )
+        assertNotNull(second)
+        second!!
+        assertFalse(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.
+        assertTrue(second.uploads.isNotEmpty())
+        assertTrue(second.uploads.all { it.first() == 12.toByte() })
+        val payload = second.payload
+        assertNotNull(payload)
+        payload!!
+        if (payload.first() == 8.toByte()) {
+            val segments = mutableListOf<Byte>()
+            var pos = 2
+            while (pos + 2 <= payload.size) {
+                val len = (payload[pos].toInt() and 0xFF) or ((payload[pos + 1].toInt() and 0xFF) shl 8)
+                pos += 2
+                if (pos < payload.size) segments.add(payload[pos])
+                pos += len
+            }
+            assertTrue(segments.contains(14.toByte()))
+            assertFalse(segments.contains(0x83.toByte()))
+        } else {
+            assertEquals(14.toByte(), payload.first())
+        }
+
+        // A lens-unequal window must fall back to plain bitmap deltas.
+        val stereo = G2CfwRenderer.lensBoxes(576, 288, heightLevel = 4, depthLevel = 2)
+        val plain =
+            G2CfwRenderer.encodeUpdate(
+                monoFrame("hello"), stereo, previousRaster = null,
+                forcedRects = emptyList(), fids = fids, textDraws = emptyList(),
+                allowRectCopy = true, blankBoxes = null, omitBuiltinText = false,
+                textureGlyphsEnabled = true, textureImagesEnabled = true, cacheGeneration = 7,
+            )
+        assertNotNull(plain)
+        assertTrue(plain!!.uploads.isEmpty())
+        assertEquals(0x83.toByte(), plain.payload?.first())
+    }
+}

package/android/src/test/java/com/glassly/bluetoothsdk/sgcs/G2FlashProtocolTest.kt

@@ -0,0 +1,131 @@
+package com.glassly.bluetoothsdk.sgcs
+
+import androidx.test.core.app.ApplicationProvider
+import java.io.FileNotFoundException
+import org.junit.Assert.assertArrayEquals
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Assume.assumeTrue
+import org.junit.Test
+import org.robolectric.RobolectricTestRunner
+import org.junit.runner.RunWith
+import org.robolectric.annotation.Config
+
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [33])
+class G2FlashProtocolTest {
+    @Test
+    fun crcGoldenVectorsMatchFirmwareTools() {
+        assertArrayEquals(byteArrayOf(0xB1.toByte(), 0x29), G2FlashProtocol.crc16("123456789".toByteArray()))
+        assertEquals(0xC052_A8C8L, G2FlashProtocol.crc32c("123456789".toByteArray()))
+    }
+
+    @Test
+    fun framesCarrySharedSequenceAndCrc() {
+        val payload = byteArrayOf(1, 2, 3)
+        val frames = G2FlashProtocol.frames(sid = 0xC1, pb = payload, seq = 0x44)
+        assertEquals(1, frames.size)
+        assertEquals(listOf(0xAA, 0x21, 0x44, 5, 1, 1, 0xC1, 0), frames[0].take(8).unsigned())
+        assertArrayEquals(payload, frames[0].copyOfRange(8, 11))
+        assertArrayEquals(G2FlashProtocol.crc16(payload), frames[0].takeLast(2).toByteArray())
+    }
+
+    @Test
+    fun replyParserMatchesOpcodeWithoutSequenceOrSidEcho() {
+        assertNull(G2FlashProtocol.parseRx(bytes(0xAA, 0x21, 0, 0, 0, 0, 0, 0, 0, 0)))
+        val parsed = G2FlashProtocol.parseRx(bytes(0xAA, 0x12, 7, 4, 1, 1, 0xC0, 0, 3, 8))
+        assertNotNull(parsed)
+        assertEquals(7, parsed?.sequence)
+        assertEquals(0xC0, parsed?.sid)
+        assertArrayEquals(byteArrayOf(3, 8), parsed?.pb)
+
+        val unrelated = bytes(0xAA, 0x12, 3, 4, 1, 1, 0xC0, 0, 1, 0)
+        val blockAck = bytes(0xAA, 0x12, 99, 4, 1, 1, 0xC1, 0, 2, 0)
+        assertEquals(0, G2FlashProtocol.otaAckStatus(listOf(unrelated, blockAck), opcode = 0x02))
+    }
+
+    @Test
+    fun preflightAcceptsConsistentImageAndRejectsPayloadCorruption() {
+        val image = makeFirmware()
+        val validated = G2Flasher.preflight(image)
+        assertEquals(5, validated.segments.size)
+        assertTrue(validated.guardResult.pass)
+
+        val first = G2FlashProtocol.parseSegments(image).first()
+        val corrupt = image.copyOf()
+        corrupt[first.off.toInt() + 128] = (corrupt[first.off.toInt() + 128].toInt() xor 1).toByte()
+        val error = runCatching { G2Flasher.preflight(corrupt) }.exceptionOrNull()
+        assertTrue(error?.message.orEmpty().contains("CRC32C mismatch"))
+    }
+
+    @Test
+    fun preflightRejectsStaleSubheaderCrc() {
+        val image = makeFirmware()
+        val first = G2FlashProtocol.parseSegments(image).first()
+        image[first.off.toInt() + 12] = (image[first.off.toInt() + 12].toInt() xor 1).toByte()
+        val error = runCatching { G2Flasher.preflight(image) }.exceptionOrNull()
+        assertTrue(error?.message.orEmpty().contains("CRC32C mismatch"))
+    }
+
+    @Test
+    fun locallyBundledFirmwarePassesFullValidationWhenAvailable() {
+        val context = ApplicationProvider.getApplicationContext<android.content.Context>()
+        val available =
+            try {
+                context.assets.list("G2Firmware").orEmpty().filter { it.endsWith(".bin") }.toSet()
+            } catch (_: FileNotFoundException) {
+                emptySet()
+            }
+        assumeTrue("Firmware binaries are intentionally absent from fresh clones", available.isNotEmpty())
+        assertEquals(G2FirmwareCatalog.artifacts.map { it.fileName }.toSet(), available)
+        for (artifact in G2FirmwareCatalog.artifacts) {
+            G2Flasher.preflight(G2FirmwareCatalog.load(context, artifact))
+        }
+    }
+
+    private fun makeFirmware(): ByteArray {
+        val names =
+            listOf(
+                "firmware/codec.bin",
+                "firmware/ble.bin",
+                "firmware/touch.bin",
+                "ota/s200_bootloader.bin",
+                G2FlashProtocol.REQUIRED_SEGMENT,
+            )
+        var image = ByteArray(0x100)
+        writeU32(names.size.toLong(), 8, image)
+        var offset = 0x100
+        for ((index, name) in names.withIndex()) {
+            val payload = ByteArray(32) { (index + 1).toByte() }
+            if (name == G2FlashProtocol.REQUIRED_SEGMENT) {
+                writeU32(payload.size.toLong(), 0, payload)
+                writeU32(G2FlashProtocol.APP_LOAD_ADDR, 0x14, payload)
+            }
+            val crc = G2FlashProtocol.crc32c(payload)
+            val end = offset + 128 + payload.size
+            if (image.size < end) image = image.copyOf(end)
+
+            val toc = 0x40 + index * 16
+            writeU32((index + 1).toLong(), toc, image)
+            writeU32(offset.toLong(), toc + 4, image)
+            writeU32((payload.size + 128).toLong(), toc + 8, image)
+            writeU32(crc, toc + 12, image)
+            writeU32(payload.size.toLong(), offset + 8, image)
+            writeU32(crc, offset + 12, image)
+            name.toByteArray(Charsets.ISO_8859_1).copyInto(image, offset + 48)
+            payload.copyInto(image, offset + 128)
+            offset = end
+        }
+        return image
+    }
+
+    private fun writeU32(value: Long, offset: Int, bytes: ByteArray) {
+        repeat(4) { index -> bytes[offset + index] = ((value ushr (index * 8)) and 0xFF).toByte() }
+    }
+
+    private fun bytes(vararg values: Int): ByteArray = ByteArray(values.size) { values[it].toByte() }
+
+    private fun List<Byte>.unsigned(): List<Int> = map { it.toInt() and 0xFF }
+}