@glassly/bluetooth-sdk 0.1.0-dev.26

package/android/src/main/java/com/glassly/bluetoothsdk/sgcs/G2CfwRenderer.kt

@@ -0,0 +1,1241 @@
+package com.glassly.bluetoothsdk.sgcs
+
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import android.graphics.Canvas
+import android.graphics.Color
+import android.graphics.Paint
+import android.graphics.Rect
+import android.graphics.RectF
+import android.graphics.Typeface
+import android.text.Layout
+import android.text.StaticLayout
+import android.text.TextPaint
+import android.util.Base64
+import java.io.ByteArrayOutputStream
+import java.util.zip.DeflaterOutputStream
+import kotlin.math.roundToInt
+
+/** Phone-side full-scene rasterizer for Glassly CFW's direct-framebuffer protocol. */
+internal object G2CfwRenderer {
+    const val FRAME_WIDTH = 640
+    const val FRAME_HEIGHT = 480
+
+    private val heightOffsets = intArrayOf(192, 176, 160, 144, 128, 112, 96, 80, 64, 48, 32, 16, 0)
+    private val depthOffsetsLeft = intArrayOf(40, 32, 24)
+    private val depthOffsetsRight = intArrayOf(24, 32, 40)
+
+    data class LensBoxes(
+        val leftX: Int,
+        val leftY: Int,
+        val rightX: Int,
+        val rightY: Int,
+        val width: Int,
+        val height: Int,
+    )
+
+    fun lensBoxes(
+        canvasWidth: Int,
+        canvasHeight: Int,
+        heightLevel: Int,
+        depthLevel: Int,
+    ): LensBoxes {
+        val heightIndex = heightLevel.coerceIn(heightOffsets.indices)
+        val depthIndex = depthLevel.coerceIn(depthOffsetsLeft.indices)
+        val width = canvasWidth.coerceIn(4, FRAME_WIDTH) and 3.inv()
+        val height = canvasHeight.coerceIn(2, FRAME_HEIGHT) and 1.inv()
+
+        fun x(value: Int) = value.coerceIn(0, FRAME_WIDTH - width) and 3.inv()
+        fun y(value: Int) = value.coerceIn(0, FRAME_HEIGHT - height) and 1.inv()
+        return LensBoxes(
+            leftX = x(depthOffsetsLeft[depthIndex]),
+            leftY = y(heightOffsets[heightIndex]),
+            rightX = x(depthOffsetsRight[depthIndex]),
+            rightY = y(heightOffsets[heightIndex]),
+            width = width,
+            height = height,
+        )
+    }
+
+    fun monoLineHeight(fontSize: Float): Float = (fontSize * 1.2f).roundToInt().toFloat()
+
+    fun encode(frame: SceneFrame, boxes: LensBoxes, frameId: Int): ByteArray? {
+        val pixels = rasterize(frame, boxes.width, boxes.height) ?: return null
+        return stereoFrame(pixels, boxes, frameId)
+    }
+
+    // ── Grid-exact mono glyphs (texture-cache path) ─────────────────────────
+
+    /**
+     * Texture-cache state. Modes 12/13/14 draw at absolute panel coordinates
+     * (no per-lens variant), so the caller only enables this path on frames
+     * whose window is placed lens-equal. The cache model resets whenever the
+     * caller's generation changes (lease cycled / residency unknown); the
+     * glyph raster memo survives resets — rasters don't change.
+     */
+    private val textureCache = G2CfwTextureCache()
+    private val glyphRasterMemo = mutableMapOf<String, ByteArray>()
+
+    private fun monoPaint(fontSize: Float): Paint =
+        Paint(Paint.ANTI_ALIAS_FLAG).apply {
+            color = Color.WHITE
+            textSize = fontSize
+            typeface = Typeface.MONOSPACE
+        }
+
+    /** Fixed cell metrics of the phone's monospaced face at `fontSize`: (cellWidth, lineHeight). */
+    fun monoCellMetrics(fontSize: Int): Pair<Int, Int> {
+        val size = (if (fontSize > 0) fontSize else 20).toFloat()
+        val advance = monoPaint(size).measureText("0")
+        return maxOf(1, advance.roundToInt()) to maxOf(1, monoLineHeight(size).toInt())
+    }
+
+    /**
+     * One full-cell glyph raster (cellWidth × lineHeight, 8-bit gray, white
+     * ink on black). This single function feeds BOTH the frame raster (grid
+     * blits) and the mode-12 uploads, so an on-glasses cached draw reproduces
+     * the phone raster byte-for-byte. Baseline placement matches the flat
+     * rasterizer's mono path (-ascent from the cell top).
+     */
+    fun monoGlyphRaster(codePoint: Int, fontSize: Int, cellWidth: Int, lineHeight: Int): ByteArray? {
+        val size = (if (fontSize > 0) fontSize else 20).toFloat()
+        val paint = monoPaint(size)
+        val bitmap = Bitmap.createBitmap(cellWidth, lineHeight, Bitmap.Config.ARGB_8888)
+        try {
+            val canvas = Canvas(bitmap)
+            canvas.drawColor(Color.BLACK)
+            canvas.drawText(String(Character.toChars(codePoint)), 0f, -paint.fontMetrics.ascent, paint)
+            val colors = IntArray(cellWidth * lineHeight)
+            bitmap.getPixels(colors, 0, cellWidth, 0, 0, cellWidth, lineHeight)
+            return ByteArray(colors.size) { index ->
+                val color = colors[index]
+                ((Color.red(color) * 299 + Color.green(color) * 587 + Color.blue(color) * 114) / 1000).toByte()
+            }
+        } finally {
+            bitmap.recycle()
+        }
+    }
+
+    private fun memoizedGlyphRaster(codePoint: Int, fontSize: Int, cellWidth: Int, lineHeight: Int): ByteArray? {
+        val key = "$fontSize|$codePoint"
+        glyphRasterMemo[key]?.let { return it }
+        val raster = monoGlyphRaster(codePoint, fontSize, cellWidth, lineHeight) ?: return null
+        glyphRasterMemo[key] = raster
+        return raster
+    }
+
+    /** A line's Unicode code points (mode 14 addresses cells per code point). */
+    private fun codePoints(line: String): IntArray {
+        val out = mutableListOf<Int>()
+        var i = 0
+        while (i < line.length) {
+            val cp = line.codePointAt(i)
+            out.add(cp)
+            i += Character.charCount(cp)
+        }
+        return out.toIntArray()
+    }
+
+    /**
+     * One mono text element's glyph grid, produced by the grid-exact
+     * rasterizer: cell (0,0) sits at (originX, originY) in canvas coords, and
+     * only the `fullCols`×`fullRows` cells wholly inside the element box (and
+     * canvas) are expressible as cached draws — clipped edge cells stay baked.
+     */
+    data class MonoGrid(
+        val z: Int,
+        val fontSize: Int,
+        val originX: Int,
+        val originY: Int,
+        val cellWidth: Int,
+        val lineHeight: Int,
+        val fullCols: Int,
+        val fullRows: Int,
+        /** Code point per cell; rows/cols beyond the text are spaces. */
+        val rows: List<IntArray>,
+    ) {
+        fun scalar(row: Int, col: Int): Int {
+            if (row >= rows.size) return 32
+            val line = rows[row]
+            return if (col < line.size) line[col] else 32
+        }
+
+        /** The canvas region whose every pixel belongs to a full cell. */
+        val expressibleRegion: CanvasRect
+            get() = CanvasRect(originX, originY, fullCols * cellWidth, fullRows * lineHeight)
+
+        fun covers(rect: CanvasRect): Boolean {
+            val region = expressibleRegion
+            return rect.x >= region.x && rect.y >= region.y &&
+                rect.x + rect.w <= region.x + region.w &&
+                rect.y + rect.h <= region.y + region.h
+        }
+    }
+
+    // ── Incremental updates (dirty rects / rect copy / builtin text) ────────
+
+    /** Canvas-space rect aligned to mode 3's quantization (x/w %4, y/h %2). */
+    data class CanvasRect(val x: Int, val y: Int, val w: Int, val h: Int)
+
+    /** Full-width vertical band copy: rows [srcY, srcY+height) → [dstY, ...). */
+    data class RowCopy(val srcY: Int, val dstY: Int, val height: Int)
+
+    /**
+     * What an incremental frame needs: a full re-send, or a scroll copy plus
+     * the aligned rects whose pixels still differ after it.
+     */
+    data class DeltaPlan(val full: Boolean, val copy: RowCopy?, val rects: List<CanvasRect>) {
+        val isNoop: Boolean get() = !full && copy == null && rects.isEmpty()
+
+        companion object {
+            val NOOP = DeltaPlan(full = false, copy = null, rects = emptyList())
+            val FULL_FRAME = DeltaPlan(full = true, copy = null, rects = emptyList())
+        }
+    }
+
+    /** One firmware-drawn (mode 15) text line at absolute panel coordinates. */
+    data class TextDraw(val x: Int, val y: Int, val text: String)
+
+    /**
+     * One incremental encode: the wire payload (null when the frame is
+     * visually identical), mode-12 texture uploads that must be queued AHEAD
+     * of it, the raster backing the on-glass shadow after this payload
+     * applies, and whether the payload re-sends the whole canvas.
+     */
+    class SceneUpdate(
+        val payload: ByteArray?,
+        val uploads: List<ByteArray>,
+        val raster: ByteArray,
+        val usedFullFrame: Boolean,
+    )
+
+    const val MAX_DIRTY_RECTS = 6
+    const val REQUIRED_FID_COUNT = MAX_DIRTY_RECTS + 2
+
+    /** Cap on mode-14 runs per update (mode-8's count byte is the hard bound). */
+    const val MAX_GLYPH_RUNS = 180
+
+    /**
+     * Line pitch and default draw options of the glasses' builtin 20 px font
+     * chain (mode 15): lineHeight 27 / baseline 22 in firmware 2.2.6.10.
+     * 0x1F = top color 15 (white) + bit 4 (source color 0 transparent).
+     */
+    const val BUILTIN_LINE_HEIGHT = 27
+    const val BUILTIN_TEXT_OPTIONS = 0x1F
+    private const val DIRTY_ROW_MERGE_GAP = 8
+    private const val FULL_FRAME_COVERAGE_PERCENT = 60
+    private const val MIN_SCROLL_BAND_ROWS = 16
+    private const val SCROLL_SAVINGS_PERCENT = 30
+
+    /**
+     * Rasterize + plan + encode one incremental scene update. Mirrors the iOS
+     * renderer: see G2CfwRenderer.swift `encodeUpdate` for the contract.
+     */
+    fun encodeUpdate(
+        frame: SceneFrame,
+        boxes: LensBoxes,
+        previousRaster: ByteArray?,
+        forcedRects: List<CanvasRect>,
+        fids: List<Int>,
+        textDraws: List<TextDraw>,
+        allowRectCopy: Boolean,
+        blankBoxes: LensBoxes?,
+        omitBuiltinText: Boolean,
+        textureGlyphsEnabled: Boolean = false,
+        textureImagesEnabled: Boolean = false,
+        cacheGeneration: Int = 0,
+    ): SceneUpdate? {
+        if (fids.size < REQUIRED_FID_COUNT) return null
+        val width = boxes.width
+        val height = boxes.height
+        // Texture draws (modes 13/14) land at absolute panel coordinates with
+        // no per-lens variant — only a lens-equal window may use them.
+        val lensEqual = boxes.leftX == boxes.rightX && boxes.leftY == boxes.rightY
+        val useTexGlyphs = textureGlyphsEnabled && lensEqual
+        val useTexImages = textureImagesEnabled && lensEqual
+        // A full cache resets between frames (never mid-frame: draws already
+        // planned this frame reference the old offsets). Bumping past the
+        // caller's generation keeps the caller's own bumps monotonic.
+        if ((useTexGlyphs || useTexImages) && (textureCache.generation != cacheGeneration || textureCache.exhausted)) {
+            textureCache.reset(cacheGeneration)
+        }
+
+        var grids: List<MonoGrid> = emptyList()
+        val raster: ByteArray
+        if (useTexGlyphs) {
+            val result = rasterizeGridExact(frame, width, height, omitBuiltinText) ?: return null
+            raster = quantizeToPanelLevels(result.first)
+            grids = result.second
+        } else {
+            raster = quantizeToPanelLevels(rasterize(frame, width, height, omitBuiltinText) ?: return null)
+        }
+
+        var nextFid = 0
+        fun takeFid(): Int = fids[nextFid++]
+
+        val segments = mutableListOf<ByteArray>()
+        if (blankBoxes != null) {
+            solidStereoFrame(0, blankBoxes, takeFid())?.let { segments.add(it) }
+        }
+
+        val plan =
+            if (previousRaster != null && previousRaster.size == raster.size && blankBoxes == null) {
+                diffPlan(previousRaster, raster, width, height, forcedRects, allowRectCopy)
+            } else {
+                DeltaPlan.FULL_FRAME
+            }
+
+        if (plan.isNoop) {
+            return SceneUpdate(
+                payload = null, uploads = textureCache.takeUploadPayloads(),
+                raster = raster, usedFullFrame = false,
+            )
+        }
+
+        if (plan.full) {
+            val full = stereoFrame(raster, boxes, takeFid()) ?: return null
+            segments.add(full)
+        } else {
+            plan.copy?.let { segments.add(rectCopyPayload(it, width, boxes)) }
+            var deltaRects = plan.rects
+            var drawSegments: List<ByteArray> = emptyList()
+            if (useTexGlyphs || useTexImages) {
+                // Reserve one fid for the bundle-overflow fallback below.
+                val fidBudget = REQUIRED_FID_COUNT - nextFid - 1
+                val expressed =
+                    expressTextureRects(
+                        plan.rects,
+                        grids = if (useTexGlyphs) grids else emptyList(),
+                        frame = frame, boxes = boxes, raster = raster,
+                        width = width, height = height,
+                        allowImages = useTexImages, fidBudget = fidBudget,
+                    )
+                deltaRects = expressed.first
+                drawSegments = expressed.second
+            }
+            for (rect in deltaRects) {
+                val delta = boxDeltaFrame(raster, width, rect, boxes, takeFid()) ?: return null
+                segments.add(delta)
+            }
+            segments.addAll(drawSegments)
+        }
+
+        for (draw in textDraws) {
+            builtinStringPayload(draw.x, draw.y, BUILTIN_TEXT_OPTIONS, draw.text)?.let { segments.add(it) }
+        }
+
+        val uploads = textureCache.takeUploadPayloads()
+        if (segments.size == 1) return SceneUpdate(segments[0], uploads, raster, plan.full)
+        bundle(segments)?.let { return SceneUpdate(it, uploads, raster, plan.full) }
+        // A segment overflowed the bundle's 64 KiB cap (a near-incompressible
+        // full canvas). Fall back to one bare full frame with any builtin text
+        // baked into the bitmap so nothing is lost. The uploads still go out —
+        // residency was already recorded in the model.
+        val flat = rasterize(frame, width, height, omitBuiltinText = false) ?: return null
+        val full = stereoFrame(flat, boxes, takeFid()) ?: return null
+        return SceneUpdate(full, uploads, flat, usedFullFrame = true)
+    }
+
+    /**
+     * Blit `font: "mono"` elements as opaque glyph grids: the element's box
+     * is cleared to black and every non-space cell blits the SAME full-cell
+     * raster mode-14 draws replay, so an on-glasses cached draw reproduces
+     * the raster exactly. (Opaque cells are also what makes cached draws
+     * self-erasing.) Mono grids paint after all other elements — an exotic
+     * frame stacking a non-mono element ON TOP of a mono grid would z-order
+     * differently here, which no current miniapp does.
+     */
+    private fun rasterizeGridExact(
+        frame: SceneFrame,
+        width: Int,
+        height: Int,
+        omitBuiltinText: Boolean,
+    ): Pair<ByteArray, List<MonoGrid>>? {
+        val raster =
+            rasterize(frame, width, height, omitBuiltinText, omitMonoText = true) ?: return null
+
+        val grids = mutableListOf<MonoGrid>()
+        for ((z, element) in frame.elements.withIndex()) {
+            if (element.type != "text" || element.font != "mono") continue
+            val bx = element.x
+            val by = element.y
+            val clipX0 = maxOf(0, bx)
+            val clipY0 = maxOf(0, by)
+            val clipX1 = minOf(width, bx + element.w)
+            val clipY1 = minOf(height, by + element.h)
+            if (clipX0 >= clipX1 || clipY0 >= clipY1) continue
+            val (cellWidth, lineHeight) = monoCellMetrics(element.fontSize)
+            val originX = bx + 2
+            val originY = by + 2
+            for (y in clipY0 until clipY1) {
+                raster.fill(0, y * width + clipX0, y * width + clipX1)
+            }
+            val lines = (element.text ?: "").split('\n').map { codePoints(it) }
+            val blitCols = maxOf(0, (clipX1 - originX + cellWidth - 1) / cellWidth)
+            val blitRows = maxOf(0, (clipY1 - originY + lineHeight - 1) / lineHeight)
+            for (row in 0 until minOf(blitRows, lines.size)) {
+                val line = lines[row]
+                for (col in 0 until minOf(blitCols, line.size)) {
+                    if (line[col] == 32) continue
+                    val glyph =
+                        memoizedGlyphRaster(line[col], element.fontSize, cellWidth, lineHeight)
+                            ?: continue
+                    blitCell(
+                        glyph, raster, width,
+                        atX = originX + col * cellWidth, atY = originY + row * lineHeight,
+                        cellWidth = cellWidth, cellHeight = lineHeight,
+                        clipX0 = clipX0, clipY0 = clipY0, clipX1 = clipX1, clipY1 = clipY1,
+                    )
+                }
+            }
+            grids.add(
+                MonoGrid(
+                    z = z, fontSize = element.fontSize, originX = originX, originY = originY,
+                    cellWidth = cellWidth, lineHeight = lineHeight,
+                    fullCols = maxOf(0, (clipX1 - originX) / cellWidth),
+                    fullRows = maxOf(0, (clipY1 - originY) / lineHeight),
+                    rows = lines,
+                )
+            )
+        }
+        return raster to grids
+    }
+
+    private fun blitCell(
+        glyph: ByteArray,
+        raster: ByteArray,
+        rasterWidth: Int,
+        atX: Int,
+        atY: Int,
+        cellWidth: Int,
+        cellHeight: Int,
+        clipX0: Int,
+        clipY0: Int,
+        clipX1: Int,
+        clipY1: Int,
+    ) {
+        val x0 = maxOf(atX, clipX0)
+        val y0 = maxOf(atY, clipY0)
+        val x1 = minOf(atX + cellWidth, clipX1)
+        val y1 = minOf(atY + cellHeight, clipY1)
+        if (x0 >= x1 || y0 >= y1) return
+        for (y in y0 until y1) {
+            System.arraycopy(
+                glyph, (y - atY) * cellWidth + (x0 - atX),
+                raster, y * rasterWidth + x0,
+                x1 - x0,
+            )
+        }
+    }
+
+    /**
+     * Express-or-bake: each dirty rect either becomes cached draws (mode-14
+     * glyph runs from the topmost covering mono grid, or one mode-13 draw of
+     * an isolated repeated image) and drops its bitmap delta, or stays a
+     * plain delta untouched. All-or-nothing per rect keeps the shadow model
+     * trivially exact — no partial punch-out. Non-ASCII cells (mode 14 is
+     * 32..126 only) become small residual bitmap deltas within an otherwise
+     * expressed rect.
+     */
+    private fun expressTextureRects(
+        rects: List<CanvasRect>,
+        grids: List<MonoGrid>,
+        frame: SceneFrame,
+        boxes: LensBoxes,
+        raster: ByteArray,
+        width: Int,
+        height: Int,
+        allowImages: Boolean,
+        fidBudget: Int,
+    ): Pair<List<CanvasRect>, List<ByteArray>> {
+        class ElementBox(val z: Int, val x0: Int, val y0: Int, val x1: Int, val y1: Int) {
+            fun intersects(r: CanvasRect): Boolean =
+                r.x < x1 && r.x + r.w > x0 && r.y < y1 && r.y + r.h > y0
+        }
+        val elementBoxes =
+            frame.elements.mapIndexed { z, el ->
+                ElementBox(
+                    z = z, x0 = maxOf(0, el.x), y0 = maxOf(0, el.y),
+                    x1 = minOf(width, el.x + el.w), y1 = minOf(height, el.y + el.h),
+                )
+            }
+
+        // Isolated image candidates: nothing else overlaps their box, so the
+        // frame raster inside the box IS the standalone render and an opaque
+        // full-box cached draw reproduces it. Sightings are recorded every
+        // frame; only content seen before enters the cache (streaming content
+        // like a live minimap never repeats a hash).
+        class ImageCandidate(val box: ElementBox, val key: String, val seen: Boolean)
+        val imageCandidates = mutableMapOf<Int, ImageCandidate>()
+        if (allowImages) {
+            for ((z, el) in frame.elements.withIndex()) {
+                if (el.type != "image") continue
+                val box = elementBoxes[z]
+                val w = box.x1 - box.x0
+                val h = box.y1 - box.y0
+                if (w <= 0 || h <= 0 || w > 255 || h > 255 || el.contentHash.isEmpty()) continue
+                val isolated =
+                    elementBoxes.none { other ->
+                        other.z != z && other.x0 < box.x1 && other.x1 > box.x0 &&
+                            other.y0 < box.y1 && other.y1 > box.y0
+                    }
+                if (!isolated) continue
+                val key = "${el.contentHash}@${w}x$h"
+                imageCandidates[z] = ImageCandidate(box, key, textureCache.noteImageSighting(key))
+            }
+        }
+
+        val deltas = mutableListOf<CanvasRect>()
+        val imageDraws = sortedMapOf<Int, ByteArray>()
+        val runPayloads = mutableListOf<ByteArray>()
+        var runCount = 0
+
+        rectLoop@ for ((index, rect) in rects.withIndex()) {
+            val remaining = rects.size - index - 1
+
+            // Glyph express: topmost mono grid fully covering the rect, with
+            // nothing stacked above it in that region.
+            val grid = grids.filter { it.covers(rect) }.maxByOrNull { it.z }
+            if (grid != null &&
+                elementBoxes.none { it.z > grid.z && it.intersects(rect) }
+            ) {
+                val font = textureCache.font(grid.fontSize, grid.cellWidth, grid.lineHeight)
+                if (font != null) {
+                    val r0 = (rect.y - grid.originY) / grid.lineHeight
+                    val r1 = (rect.y + rect.h - 1 - grid.originY) / grid.lineHeight
+                    val c0 = (rect.x - grid.originX) / grid.cellWidth
+                    val c1 = (rect.x + rect.w - 1 - grid.originX) / grid.cellWidth
+                    val newRuns = mutableListOf<Triple<Int, Int, ByteArray>>() // x, y, chars
+                    val residuals = mutableListOf<CanvasRect>()
+                    var expressible = true
+                    rowLoop@ for (row in r0..r1) {
+                        val rowY = grid.originY + row * grid.lineHeight
+                        var runChars = mutableListOf<Byte>()
+                        var runStartCol = c0
+                        var residualStart: Int? = null
+                        fun flushRun() {
+                            if (runChars.isEmpty()) return
+                            newRuns.add(
+                                Triple(
+                                    grid.originX + runStartCol * grid.cellWidth, rowY,
+                                    runChars.toByteArray(),
+                                )
+                            )
+                            runChars = mutableListOf()
+                        }
+                        fun flushResidual(endCol: Int) {
+                            val start = residualStart ?: return
+                            val x0 = maxOf(0, (grid.originX + start * grid.cellWidth) and 3.inv())
+                            val x1 = minOf(width, (grid.originX + endCol * grid.cellWidth + 3) and 3.inv())
+                            val y0 = maxOf(0, rowY and 1.inv())
+                            val y1 = minOf(height, (rowY + grid.lineHeight + 1) and 1.inv())
+                            residuals.add(CanvasRect(x0, y0, x1 - x0, y1 - y0))
+                            residualStart = null
+                        }
+                        for (col in c0..c1) {
+                            val scalar = grid.scalar(row, col)
+                            val resident =
+                                scalar in 32..126 &&
+                                    textureCache.ensureGlyph(font, scalar) {
+                                        memoizedGlyphRaster(
+                                            scalar, grid.fontSize, grid.cellWidth, grid.lineHeight
+                                        )
+                                    }
+                            if (resident) {
+                                flushResidual(col)
+                                if (runChars.isEmpty()) runStartCol = col
+                                runChars.add(scalar.toByte())
+                                if (runChars.size == 255) flushRun()
+                            } else {
+                                flushRun()
+                                if (residualStart == null) residualStart = col
+                            }
+                        }
+                        flushRun()
+                        flushResidual(c1 + 1)
+                        if (runCount + newRuns.size > MAX_GLYPH_RUNS) {
+                            expressible = false
+                            break@rowLoop
+                        }
+                    }
+                    // Residual deltas + every remaining rect must still fit the
+                    // fid budget; otherwise keep this rect as one plain delta.
+                    if (expressible &&
+                        deltas.size + residuals.size + remaining + 1 <= fidBudget &&
+                        residuals.size <= 3
+                    ) {
+                        var payloads = mutableListOf<ByteArray>()
+                        for ((runX, runY, chars) in newRuns) {
+                            val payload =
+                                G2CfwTextureCache.stringRunPayload(
+                                    fontTableOffset = font.tableOffset,
+                                    x = boxes.leftX + runX, y = boxes.leftY + runY,
+                                    options = G2CfwTextureCache.OPAQUE_DRAW_OPTIONS, chars = chars,
+                                )
+                            if (payload == null) {
+                                payloads = mutableListOf()
+                                break
+                            }
+                            payloads.add(payload)
+                        }
+                        if (payloads.isNotEmpty() || newRuns.isEmpty()) {
+                            runPayloads.addAll(payloads)
+                            runCount += payloads.size
+                            deltas.addAll(residuals)
+                            continue@rectLoop
+                        }
+                    }
+                }
+            }
+
+            // Image express: the rect sits wholly inside an isolated, repeated
+            // image's box — one opaque full-box draw covers it (and any other
+            // rect in the same box).
+            if (allowImages) {
+                val entry =
+                    imageCandidates.entries.firstOrNull { (_, c) ->
+                        c.seen && rect.x >= c.box.x0 && rect.y >= c.box.y0 &&
+                            rect.x + rect.w <= c.box.x1 && rect.y + rect.h <= c.box.y1
+                    }
+                if (entry != null) {
+                    val (z, candidate) = entry
+                    if (imageDraws.containsKey(z)) continue@rectLoop
+                    val w = candidate.box.x1 - candidate.box.x0
+                    val h = candidate.box.y1 - candidate.box.y0
+                    val gray = ByteArray(w * h)
+                    for (y in candidate.box.y0 until candidate.box.y1) {
+                        System.arraycopy(
+                            raster, y * width + candidate.box.x0,
+                            gray, (y - candidate.box.y0) * w, w,
+                        )
+                    }
+                    val offset = textureCache.ensureImage(candidate.key, gray, w, h)
+                    val draw =
+                        offset?.let {
+                            G2CfwTextureCache.imageDrawPayload(
+                                offset = it,
+                                x = boxes.leftX + candidate.box.x0,
+                                y = boxes.leftY + candidate.box.y0,
+                                options = G2CfwTextureCache.OPAQUE_DRAW_OPTIONS,
+                            )
+                        }
+                    if (draw != null) {
+                        imageDraws[z] = draw
+                        continue@rectLoop
+                    }
+                }
+            }
+
+            deltas.add(rect)
+        }
+
+        return deltas to (imageDraws.values.toList() + runPayloads)
+    }
+
+    /**
+     * Diff two same-size canvas rasters into a scroll copy + aligned dirty
+     * rects, or a full-frame decision when the change is too large.
+     */
+    fun diffPlan(
+        previous: ByteArray,
+        next: ByteArray,
+        width: Int,
+        height: Int,
+        forced: List<CanvasRect>,
+        allowCopy: Boolean,
+    ): DeltaPlan {
+        if (previous.size != width * height || next.size != width * height || width <= 0 || height <= 0) {
+            return DeltaPlan.FULL_FRAME
+        }
+
+        fun rowsEqual(a: ByteArray, aRow: Int, b: ByteArray, bRow: Int): Boolean {
+            val aOff = aRow * width
+            val bOff = bRow * width
+            for (x in 0 until width) {
+                if (a[aOff + x] != b[bOff + x]) return false
+            }
+            return true
+        }
+
+        val changed = BooleanArray(height) { y -> !rowsEqual(previous, y, next, y) }
+        var anyChanged = changed.any { it }
+        if (!anyChanged && forced.isEmpty()) return DeltaPlan.NOOP
+
+        // Scroll detection: a vertical band of new rows that byte-match
+        // previous rows shifted by dy. Row hashes score candidate shifts;
+        // the winning band is byte-verified before use.
+        var copy: RowCopy? = null
+        var predicted: ByteArray? = null
+        if (allowCopy && anyChanged) {
+            val prevHash = LongArray(height) { y -> rowHash(previous, y * width, width) }
+            val newHash = LongArray(height) { y -> rowHash(next, y * width, width) }
+            val changedCount = changed.count { it }
+            var bestDy = 0
+            var bestScore = 0
+            val maxShift = height - MIN_SCROLL_BAND_ROWS
+            if (maxShift > 0) {
+                for (dy in -maxShift..maxShift) {
+                    if (dy == 0) continue
+                    var score = 0
+                    for (y in maxOf(0, -dy) until minOf(height, height - dy)) {
+                        if (changed[y] && newHash[y] == prevHash[y + dy]) score += 1
+                    }
+                    if (score > bestScore) {
+                        bestScore = score
+                        bestDy = dy
+                    }
+                }
+            }
+            if (bestDy != 0 && bestScore >= MIN_SCROLL_BAND_ROWS &&
+                bestScore * 100 >= changedCount * SCROLL_SAVINGS_PERCENT
+            ) {
+                var runStart = -1
+                var bandStart = 0
+                var bandLen = 0
+                val lo = maxOf(0, -bestDy)
+                val hi = minOf(height, height - bestDy)
+                for (y in lo..hi) {
+                    val matches = y < hi && newHash[y] == prevHash[y + bestDy]
+                    if (matches) {
+                        if (runStart < 0) runStart = y
+                    } else if (runStart >= 0) {
+                        if (y - runStart > bandLen) {
+                            bandStart = runStart
+                            bandLen = y - runStart
+                        }
+                        runStart = -1
+                    }
+                }
+                if (bandLen >= MIN_SCROLL_BAND_ROWS) {
+                    var verified = true
+                    for (y in bandStart until bandStart + bandLen) {
+                        if (!rowsEqual(next, y, previous, y + bestDy)) {
+                            verified = false
+                            break
+                        }
+                    }
+                    if (verified) {
+                        copy = RowCopy(srcY = bandStart + bestDy, dstY = bandStart, height = bandLen)
+                        predicted = previous.copyOf().also {
+                            System.arraycopy(
+                                previous, (bandStart + bestDy) * width, it, bandStart * width, bandLen * width
+                            )
+                        }
+                        for (y in bandStart until bandStart + bandLen) changed[y] = false
+                        anyChanged = changed.any { it }
+                    }
+                }
+            }
+        }
+
+        // Per-row dirty column ranges against the (possibly copied) base.
+        val base = predicted ?: previous
+        val colLo = IntArray(height) { Int.MAX_VALUE }
+        val colHi = IntArray(height) { -1 }
+        for (y in 0 until height) {
+            if (!changed[y]) continue
+            var lo = 0
+            while (lo < width && base[y * width + lo] == next[y * width + lo]) lo += 1
+            var hi = width - 1
+            while (hi > lo && base[y * width + hi] == next[y * width + hi]) hi -= 1
+            colLo[y] = lo
+            colHi[y] = hi
+        }
+        val dirtyRows = changed.copyOf()
+        for (rect in forced) {
+            val y0 = maxOf(0, rect.y)
+            val y1 = minOf(height, rect.y + rect.h)
+            if (y0 >= y1 || rect.w <= 0) continue
+            for (y in y0 until y1) {
+                dirtyRows[y] = true
+                colLo[y] = minOf(colLo[y], maxOf(0, rect.x))
+                colHi[y] = maxOf(colHi[y], minOf(width - 1, rect.x + rect.w - 1))
+            }
+        }
+        if (!dirtyRows.any { it }) {
+            return if (copy != null) DeltaPlan(full = false, copy = copy, rects = emptyList()) else DeltaPlan.NOOP
+        }
+
+        // Group dirty rows into bands (small gaps merge), aligned to the grid.
+        var rects = mutableListOf<CanvasRect>()
+        var y = 0
+        while (y < height) {
+            if (!dirtyRows[y]) {
+                y += 1
+                continue
+            }
+            var end = y
+            var gap = 0
+            var scan = y
+            while (scan < height && gap <= DIRTY_ROW_MERGE_GAP) {
+                if (dirtyRows[scan]) {
+                    end = scan
+                    gap = 0
+                } else {
+                    gap += 1
+                }
+                scan += 1
+            }
+            var lo = Int.MAX_VALUE
+            var hi = -1
+            for (row in y..end) {
+                if (!dirtyRows[row]) continue
+                lo = minOf(lo, colLo[row])
+                hi = maxOf(hi, colHi[row])
+            }
+            val x0 = maxOf(0, lo and 3.inv())
+            val x1 = minOf(width, (hi + 4) and 3.inv())
+            val ry0 = maxOf(0, y and 1.inv())
+            val ry1 = minOf(height, (end + 2) and 1.inv())
+            rects.add(CanvasRect(x0, ry0, x1 - x0, ry1 - ry0))
+            y = end + 1
+        }
+        if (rects.size > MAX_DIRTY_RECTS) {
+            val x0 = rects.minOf { it.x }
+            val y0 = rects.minOf { it.y }
+            val x1 = rects.maxOf { it.x + it.w }
+            val y1 = rects.maxOf { it.y + it.h }
+            rects = mutableListOf(CanvasRect(x0, y0, x1 - x0, y1 - y0))
+        }
+        val coverage = rects.sumOf { it.w * it.h }
+        if (copy == null && coverage * 100 >= width * height * FULL_FRAME_COVERAGE_PERCENT) {
+            return DeltaPlan.FULL_FRAME
+        }
+        return DeltaPlan(full = false, copy = copy, rects = rects)
+    }
+
+    private fun rowHash(pixels: ByteArray, offset: Int, count: Int): Long {
+        // FNV-1a 64 — collision-safe enough for scoring; bands are byte-verified.
+        var hash = -0x340d631b7bdddcdbL
+        for (i in offset until offset + count) {
+            hash = (hash xor (pixels[i].toLong() and 0xFF)) * 0x100000001b3L
+        }
+        return hash
+    }
+
+    /**
+     * Stereo mode-3 delta of one canvas sub-rect, drawn at each lens's window
+     * origin plus the rect offset. Rect must be grid-aligned and in bounds.
+     */
+    fun boxDeltaFrame(
+        raster: ByteArray,
+        canvasWidth: Int,
+        rect: CanvasRect,
+        boxes: LensBoxes,
+        frameId: Int,
+    ): ByteArray? {
+        if (rect.w <= 0 || rect.h <= 0 || rect.x % 4 != 0 || rect.w % 4 != 0 ||
+            rect.y % 2 != 0 || rect.h % 2 != 0 || rect.x + rect.w > canvasWidth ||
+            (rect.y + rect.h) * canvasWidth > raster.size
+        ) {
+            return null
+        }
+        val pixels = ByteArray(rect.w * rect.h)
+        for (y in 0 until rect.h) {
+            System.arraycopy(raster, (rect.y + y) * canvasWidth + rect.x, pixels, y * rect.w, rect.w)
+        }
+        return stereoRleFrame(
+            rleEncode(pack4Bpp(pixels)),
+            lx = boxes.leftX + rect.x, ly = boxes.leftY + rect.y,
+            rx = boxes.rightX + rect.x, ry = boxes.rightY + rect.y,
+            w = rect.w, h = rect.h, frameId = frameId,
+        )
+    }
+
+    /**
+     * Mode-9 rect copy with the lenses-differ flag: a full-width canvas band
+     * moves srcY→dstY inside each lens's window.
+     * `[0x89][L src LTWH dst LTWH][R src LTWH dst LTWH]`, u16 LE each.
+     */
+    fun rectCopyPayload(copy: RowCopy, width: Int, boxes: LensBoxes): ByteArray {
+        val output = ByteArrayOutputStream()
+        output.write(0x89)
+        fun writeRect(x: Int, y: Int) {
+            for (value in intArrayOf(x, y, width, copy.height)) {
+                output.write(value and 0xFF)
+                output.write((value ushr 8) and 0xFF)
+            }
+        }
+        writeRect(boxes.leftX, boxes.leftY + copy.srcY)
+        writeRect(boxes.leftX, boxes.leftY + copy.dstY)
+        writeRect(boxes.rightX, boxes.rightY + copy.srcY)
+        writeRect(boxes.rightX, boxes.rightY + copy.dstY)
+        return output.toByteArray()
+    }
+
+    /**
+     * Mode-15 builtin-font string draw:
+     * `[15][x:u16][y:u16][options:u8][strlen:u8][UTF-8]`. Bytes 1–31 are
+     * firmware x-adjust controls, so control characters are stripped here;
+     * the text is truncated to 255 UTF-8 bytes at a codepoint boundary.
+     */
+    fun builtinStringPayload(x: Int, y: Int, options: Int, text: String): ByteArray? {
+        if (x !in 0..0xFFFF || y !in 0..0xFFFF) return null
+        val sanitized = text.filter { it.code >= 32 }
+        var bytes = sanitized.toByteArray(Charsets.UTF_8)
+        if (bytes.size > 255) {
+            var cut = 255
+            while (cut > 0 && (bytes[cut].toInt() and 0xC0) == 0x80) cut -= 1
+            bytes = bytes.copyOfRange(0, cut)
+        }
+        if (bytes.isEmpty()) return null
+        val output = ByteArrayOutputStream()
+        output.write(15)
+        output.write(x and 0xFF)
+        output.write((x ushr 8) and 0xFF)
+        output.write(y and 0xFF)
+        output.write((y ushr 8) and 0xFF)
+        output.write(options and 0xFF)
+        output.write(bytes.size)
+        output.write(bytes)
+        return output.toByteArray()
+    }
+
+    /**
+     * The firmware-drawn text lines of a frame, at absolute panel
+     * coordinates. Mode 15 has no per-lens variant, so callers must place the
+     * window at lens-equal offsets (depth level 1) whenever these are used.
+     * The +2 inset matches the rasterizer's text padding.
+     */
+    fun builtinTextDraws(frame: SceneFrame, boxes: LensBoxes): List<TextDraw> {
+        val draws = mutableListOf<TextDraw>()
+        for (element in frame.elements) {
+            if (element.type != "text" || element.font != "builtin") continue
+            val text = element.text ?: continue
+            if (text.isEmpty()) continue
+            val baseX = boxes.leftX + element.x + 2
+            val baseY = boxes.leftY + element.y + 2
+            text.split('\n').forEachIndexed { index, line ->
+                val y = baseY + index * BUILTIN_LINE_HEIGHT
+                if (y >= 0 && y + BUILTIN_LINE_HEIGHT <= FRAME_HEIGHT && line.isNotEmpty()) {
+                    draws.add(TextDraw(baseX, y, line))
+                }
+            }
+        }
+        return draws
+    }
+
+    /**
+     * Conservative canvas-space bounds of firmware-drawn text, used to force
+     * background re-pushes that erase glyphs the phone raster never
+     * contained. Width is overestimated (the phone has no advance tables).
+     */
+    fun builtinTextBounds(
+        draws: List<TextDraw>,
+        boxes: LensBoxes,
+        canvasWidth: Int,
+        canvasHeight: Int,
+    ): List<CanvasRect> =
+        draws.mapNotNull { draw ->
+            val x = maxOf(0, draw.x - boxes.leftX - 4)
+            val y = maxOf(0, draw.y - boxes.leftY - 2)
+            if (x >= canvasWidth || y >= canvasHeight) return@mapNotNull null
+            CanvasRect(
+                x = x,
+                y = y,
+                w = minOf(canvasWidth - x, draw.text.length * 13 + 30),
+                h = minOf(canvasHeight - y, BUILTIN_LINE_HEIGHT + 4),
+            )
+        }
+
+    /**
+     * `omitBuiltinText` skips `font == "builtin"` text elements — the CFW
+     * draws those with mode 15, so the bitmap must not also contain them.
+     * `omitMonoText` skips `font == "mono"` text elements — the grid-exact
+     * texture path blits those from the same glyph rasters it uploads.
+     */
+    fun rasterize(
+        frame: SceneFrame,
+        width: Int,
+        height: Int,
+        omitBuiltinText: Boolean = false,
+        omitMonoText: Boolean = false,
+    ): ByteArray? {
+        if (width <= 0 || height <= 0) return null
+        val decodedImages = mutableMapOf<Int, Bitmap>()
+        try {
+            for ((index, element) in frame.elements.withIndex()) {
+                if (element.type != "image") continue
+                val encoded = element.data ?: return null
+                val data =
+                    try {
+                        Base64.decode(encoded, Base64.DEFAULT)
+                    } catch (_: IllegalArgumentException) {
+                        return null
+                    }
+                decodedImages[index] = BitmapFactory.decodeByteArray(data, 0, data.size) ?: return null
+            }
+
+            val bitmap = Bitmap.createBitmap(width, height, Bitmap.Config.ARGB_8888)
+            val canvas = Canvas(bitmap)
+            canvas.drawColor(Color.BLACK)
+            for ((index, element) in frame.elements.withIndex()) {
+                // Mode 15 draws only the glyphs, so an omitted builtin-text
+                // element's border must still come from the raster.
+                val skipBuiltinInk = omitBuiltinText && element.type == "text" && element.font == "builtin"
+                if (skipBuiltinInk && element.border <= 0) continue
+                if (omitMonoText && element.type == "text" && element.font == "mono") continue
+                val left = element.x.toFloat()
+                val top = element.y.toFloat()
+                val rect = RectF(left, top, left + element.w, top + element.h)
+                val save = canvas.save()
+                canvas.clipRect(rect)
+                when (element.type) {
+                    "text" -> if (!skipBuiltinInk) drawText(canvas, element, rect)
+                    "image" -> decodedImages[index]?.let { drawImage(canvas, it, rect) }
+                }
+
+                val border = maxOf(if (element.type == "rect") 1 else 0, element.border)
+                if (border > 0) {
+                    val paint =
+                        Paint(Paint.ANTI_ALIAS_FLAG).apply {
+                            color = Color.WHITE
+                            style = Paint.Style.STROKE
+                            strokeWidth = border.toFloat()
+                        }
+                    val inset = border / 2f
+                    val borderRect = RectF(rect).apply { inset(inset, inset) }
+                    val radius =
+                        element.radius
+                            .coerceAtLeast(0)
+                            .toFloat()
+                            .coerceAtMost(minOf(borderRect.width(), borderRect.height()) / 2f)
+                    canvas.drawRoundRect(borderRect, radius, radius, paint)
+                }
+                canvas.restoreToCount(save)
+            }
+
+            val colors = IntArray(width * height)
+            bitmap.getPixels(colors, 0, width, 0, 0, width, height)
+            bitmap.recycle()
+            return ByteArray(colors.size) { index ->
+                val color = colors[index]
+                ((Color.red(color) * 299 + Color.green(color) * 587 + Color.blue(color) * 114) / 1000).toByte()
+            }
+        } finally {
+            decodedImages.values.forEach { it.recycle() }
+        }
+    }
+
+    private fun drawText(canvas: Canvas, element: SceneElement, rect: RectF) {
+        val text = element.text.orEmpty()
+        if (text.isEmpty()) return
+        val availableWidth = (rect.width() - 4f).toInt().coerceAtLeast(1)
+        val save = canvas.save()
+        canvas.translate(rect.left + 2f, rect.top + 2f)
+        if (element.font == "mono") {
+            val size = (if (element.fontSize > 0) element.fontSize else 20).toFloat()
+            val paint =
+                Paint(Paint.ANTI_ALIAS_FLAG).apply {
+                    color = Color.WHITE
+                    textSize = size
+                    typeface = Typeface.MONOSPACE
+                }
+            val baseline = -paint.fontMetrics.ascent
+            val pitch = monoLineHeight(size)
+            text.split('\n').forEachIndexed { index, line ->
+                canvas.drawText(line, 0f, baseline + index * pitch, paint)
+            }
+        } else {
+            val paint =
+                TextPaint(Paint.ANTI_ALIAS_FLAG).apply {
+                    color = Color.WHITE
+                    textSize = 20f
+                    typeface = Typeface.DEFAULT
+                }
+            StaticLayout.Builder.obtain(text, 0, text.length, paint, availableWidth)
+                .setAlignment(Layout.Alignment.ALIGN_NORMAL)
+                .setIncludePad(false)
+                .build()
+                .draw(canvas)
+        }
+        canvas.restoreToCount(save)
+    }
+
+    private fun drawImage(canvas: Canvas, bitmap: Bitmap, rect: RectF) {
+        val scale = minOf(rect.width() / bitmap.width.coerceAtLeast(1), rect.height() / bitmap.height.coerceAtLeast(1))
+        val targetWidth = bitmap.width * scale
+        val targetHeight = bitmap.height * scale
+        canvas.drawBitmap(
+            bitmap,
+            Rect(0, 0, bitmap.width, bitmap.height),
+            RectF(
+                rect.centerX() - targetWidth / 2f,
+                rect.centerY() - targetHeight / 2f,
+                rect.centerX() + targetWidth / 2f,
+                rect.centerY() + targetHeight / 2f,
+            ),
+            Paint(Paint.ANTI_ALIAS_FLAG or Paint.FILTER_BITMAP_FLAG),
+        )
+    }
+
+    fun stereoFrame(pixels: ByteArray, boxes: LensBoxes, frameId: Int): ByteArray? {
+        if (pixels.size != boxes.width * boxes.height) return null
+        return stereoRleFrame(rleEncode(pack4Bpp(pixels)), boxes, frameId)
+    }
+
+    fun solidStereoFrame(color: Int, boxes: LensBoxes, frameId: Int): ByteArray? =
+        stereoRleFrame(rleEncodeSolid(color and 0x0F, boxes.width * boxes.height), boxes, frameId)
+
+    private fun stereoRleFrame(rle: ByteArray, boxes: LensBoxes, frameId: Int): ByteArray? =
+        stereoRleFrame(rle, boxes.leftX, boxes.leftY, boxes.rightX, boxes.rightY, boxes.width, boxes.height, frameId)
+
+    private fun stereoRleFrame(
+        rle: ByteArray,
+        lx: Int,
+        ly: Int,
+        rx: Int,
+        ry: Int,
+        w: Int,
+        h: Int,
+        frameId: Int,
+    ): ByteArray? {
+        val compressed = zlib(rle) ?: return null
+        return byteArrayOf(
+            0x83.toByte(),
+            (lx / 4).toByte(),
+            (ly / 2).toByte(),
+            (w / 4).toByte(),
+            (h / 2).toByte(),
+            (rx / 4).toByte(),
+            (ry / 2).toByte(),
+            (w / 4).toByte(),
+            (h / 2).toByte(),
+            (frameId and 0xFF).toByte(),
+            ((frameId ushr 8) and 0xFF).toByte(),
+        ) + compressed
+    }
+
+    fun bundle(segments: List<ByteArray>): ByteArray? {
+        if (segments.isEmpty() || segments.size > 255 || segments.any { it.isEmpty() || it.size > 0xFFFF }) {
+            return null
+        }
+        val output = ByteArrayOutputStream()
+        output.write(8)
+        output.write(segments.size)
+        for (segment in segments) {
+            output.write(segment.size and 0xFF)
+            output.write((segment.size ushr 8) and 0xFF)
+            output.write(segment)
+        }
+        return output.toByteArray()
+    }
+
+    /**
+     * Mode-6 full-panel seed with the frame's own pixels composited at the
+     * window position on black — seeds the shadow AND paints the frame in ONE
+     * payload, so a resync shows content immediately instead of flashing a
+     * black panel (the faceclaw reference client's resyncs are mode-6 content
+     * frames and never flash). Mode 6 has no per-lens variant, so this
+     * returns null unless the window is lens-equal — callers fall back to the
+     * black seed there.
+     */
+    fun seededFramePayload(pixels: ByteArray, boxes: LensBoxes): ByteArray? {
+        if (boxes.leftX != boxes.rightX || boxes.leftY != boxes.rightY) return null
+        if (pixels.size != boxes.width * boxes.height) return null
+        val panel = ByteArray(FRAME_WIDTH * FRAME_HEIGHT)
+        for (row in 0 until boxes.height) {
+            System.arraycopy(
+                pixels,
+                row * boxes.width,
+                panel,
+                (boxes.leftY + row) * FRAME_WIDTH + boxes.leftX,
+                boxes.width,
+            )
+        }
+        return encodePixels(panel)
+    }
+
+    fun blackPayload(): ByteArray? {
+        val compressed = zlib(rleEncodeSolid(0, FRAME_WIDTH * FRAME_HEIGHT)) ?: return null
+        return byteArrayOf(6) + compressed
+    }
+
+    fun encodePixels(grayscale: ByteArray): ByteArray? {
+        if (grayscale.size != FRAME_WIDTH * FRAME_HEIGHT) return null
+        val compressed = zlib(rleEncode(pack4Bpp(grayscale))) ?: return null
+        return byteArrayOf(6) + compressed
+    }
+
+    /**
+     * Snap an 8bpp raster to the 16 panel levels (`grayNibble(v) * 16`) before
+     * it enters the diff/shadow pipeline. The reference client diffs packed
+     * 4bpp bytes — exactly what the panel shows; diffing raw 8bpp instead
+     * marked rows dirty for sub-quantization AA noise the panel can never
+     * display (spurious rects, inflated coverage, and a scroll-copy detector
+     * that almost never matched). `grayNibble` round-trips `level * 16`
+     * exactly, so packing a quantized raster is lossless.
+     */
+    fun quantizeToPanelLevels(raster: ByteArray): ByteArray =
+        ByteArray(raster.size) { index -> (grayNibble(raster[index].toInt()) * 16).toByte() }
+
+    /**
+     * 8-bit gray → 4-bit panel level, round-to-nearest (matches the reference
+     * client's GRAY_TO_NIBBLE). 0 stays 0 so the shell's transparent color key
+     * survives; plain truncation instead darkened the upper half of every
+     * 16-value bucket by a full visible step on the 16-level panel.
+     */
+    fun grayNibble(value: Int): Int {
+        val v = value and 0xFF
+        return if (v == 0) 0 else minOf(15, (v + 8) ushr 4)
+    }
+
+    fun pack4Bpp(grayscale: ByteArray): ByteArray =
+        ByteArray((grayscale.size + 1) / 2) { index ->
+            val left = grayNibble(grayscale[index * 2].toInt())
+            val rightIndex = index * 2 + 1
+            val right = if (rightIndex < grayscale.size) grayNibble(grayscale[rightIndex].toInt()) else 0
+            ((left shl 4) or right).toByte()
+        }
+
+    fun rleEncode(packed: ByteArray): ByteArray {
+        val pixelCount = packed.size * 2
+        fun nibble(index: Int): Int =
+            if (index % 2 == 0) (packed[index / 2].toInt() ushr 4) and 0x0F
+            else packed[index / 2].toInt() and 0x0F
+
+        val output = ByteArrayOutputStream()
+        var index = 0
+        while (index < pixelCount) {
+            val color = nibble(index)
+            var end = index + 1
+            while (end < pixelCount && nibble(end) == color) end += 1
+            appendRun(output, color, end - index)
+            index = end
+        }
+        return output.toByteArray()
+    }
+
+    private fun rleEncodeSolid(color: Int, pixelCount: Int): ByteArray =
+        ByteArrayOutputStream().also { appendRun(it, color, pixelCount) }.toByteArray()
+
+    private fun appendRun(output: ByteArrayOutputStream, color: Int, count: Int) {
+        var remaining = count
+        while (remaining > 0) {
+            val chunk = minOf(remaining, 0xFFFF)
+            when {
+                chunk <= 15 -> output.write((chunk shl 4) or color)
+                chunk <= 255 -> {
+                    output.write(color)
+                    output.write(chunk)
+                }
+                else -> {
+                    output.write(color)
+                    output.write(0)
+                    output.write(chunk and 0xFF)
+                    output.write((chunk ushr 8) and 0xFF)
+                }
+            }
+            remaining -= chunk
+        }
+    }
+
+    private fun zlib(data: ByteArray): ByteArray? =
+        try {
+            ByteArrayOutputStream().also { output ->
+                DeflaterOutputStream(output).use { it.write(data) }
+            }.toByteArray()
+        } catch (_: Exception) {
+            null
+        }
+}