@glassly/bluetooth-sdk 0.1.0-dev.100

package/ios/Source/sgcs/G2CfwRenderer.swift

@@ -0,0 +1,1295 @@
+import Foundation
+import UIKit
+
+/// Serial background encoder for Glassly CFW's direct-framebuffer mode.
+/// Actor isolation keeps frames ordered without blocking G2's MainActor BLE/UI work.
+///
+/// Placement mirrors the stock compositor, which blits its 576×288 canvas into
+/// the 640×480 panel 1:1 at a per-lens offset: `y` from the user's height level
+/// and `x` from the depth level, in OPPOSITE directions per eye (that is the
+/// convergence control). The outer margin is never drawn on — it exists so the
+/// window can move, and the optics are only clean where the window sits.
+actor G2CfwRenderer {
+    static let frameWidth = 640
+    static let frameHeight = 480
+
+    /// Level → pixel tables from firmware 2.2.6.10 (`DAT_0046c738`, `DAT_0046c730/34`).
+    static let heightOffsets: [Int32] = [192, 176, 160, 144, 128, 112, 96, 80, 64, 48, 32, 16, 0]
+    static let depthOffsetsLeft: [Int32] = [40, 32, 24]
+    static let depthOffsetsRight: [Int32] = [24, 32, 40]
+
+    /// Where each lens draws the canvas. Mode 3's box header quantizes x/w to
+    /// multiples of 4 and y/h to multiples of 2.
+    struct LensBoxes: Equatable {
+        let left: CGPoint
+        let right: CGPoint
+        let width: Int32
+        let height: Int32
+    }
+
+    static func lensBoxes(
+        canvasWidth: Int32, canvasHeight: Int32, heightLevel: Int, depthLevel: Int
+    ) -> LensBoxes {
+        let h = min(max(heightLevel, 0), heightOffsets.count - 1)
+        let d = min(max(depthLevel, 0), depthOffsetsLeft.count - 1)
+        let width = min(max(canvasWidth, 4), Int32(frameWidth)) & ~3
+        let height = min(max(canvasHeight, 2), Int32(frameHeight)) & ~1
+        func place(_ x: Int32, _ y: Int32) -> CGPoint {
+            CGPoint(
+                x: CGFloat(min(max(x, 0), Int32(frameWidth) - width) & ~3),
+                y: CGFloat(min(max(y, 0), Int32(frameHeight) - height) & ~1)
+            )
+        }
+        return LensBoxes(
+            left: place(depthOffsetsLeft[d], heightOffsets[h]),
+            right: place(depthOffsetsRight[d], heightOffsets[h]),
+            width: width, height: height
+        )
+    }
+
+    /// Line pitch for `font: "mono"` text — the contract apps size their grids by.
+    static func monoLineHeight(fontSize: CGFloat) -> CGFloat {
+        (fontSize * 1.2).rounded()
+    }
+
+    // MARK: - 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 let textureCache = G2CfwTextureCache()
+    private var glyphRasterMemo: [String: Data] = [:]
+
+    /// Fixed cell metrics of the phone's monospaced face at `fontSize`.
+    static func monoCellMetrics(fontSize: Int32) -> (cellWidth: Int, lineHeight: Int) {
+        let size = CGFloat(fontSize > 0 ? fontSize : 20)
+        let font = UIFont.monospacedSystemFont(ofSize: size, weight: .regular)
+        let advance = ("0" as NSString).size(withAttributes: [.font: font]).width
+        return (max(1, Int(advance.rounded())), max(1, Int(monoLineHeight(fontSize: size))))
+    }
+
+    /// 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.
+    static func monoGlyphRaster(
+        _ scalar: Unicode.Scalar, fontSize: Int32, cellWidth: Int, lineHeight: Int
+    ) -> Data? {
+        let size = CGFloat(fontSize > 0 ? fontSize : 20)
+        let font = UIFont.monospacedSystemFont(ofSize: size, weight: .regular)
+        var gray = Data(count: cellWidth * lineHeight)
+        let ok = gray.withUnsafeMutableBytes { buffer -> Bool in
+            guard let context = CGContext(
+                data: buffer.baseAddress, width: cellWidth, height: lineHeight,
+                bitsPerComponent: 8, bytesPerRow: cellWidth,
+                space: CGColorSpaceCreateDeviceGray(),
+                bitmapInfo: CGImageAlphaInfo.none.rawValue
+            ) else { return false }
+            context.setFillColor(gray: 0, alpha: 1)
+            context.fill(CGRect(x: 0, y: 0, width: CGFloat(cellWidth), height: CGFloat(lineHeight)))
+            // Flip to UIKit's top-left origin so NSString.draw lands top-down
+            // like the frame raster.
+            context.translateBy(x: 0, y: CGFloat(lineHeight))
+            context.scaleBy(x: 1, y: -1)
+            UIGraphicsPushContext(context)
+            let yOffset = max(0, (CGFloat(lineHeight) - font.lineHeight) / 2)
+            (String(scalar) as NSString).draw(
+                at: CGPoint(x: 0, y: yOffset),
+                withAttributes: [.font: font, .foregroundColor: UIColor.white]
+            )
+            UIGraphicsPopContext()
+            return true
+        }
+        return ok ? gray : nil
+    }
+
+    private func memoizedGlyphRaster(
+        _ scalar: Unicode.Scalar, fontSize: Int32, cellWidth: Int, lineHeight: Int
+    ) -> Data? {
+        let key = "\(fontSize)|\(scalar.value)"
+        if let cached = glyphRasterMemo[key] { return cached }
+        guard let raster = Self.monoGlyphRaster(
+            scalar, fontSize: fontSize, cellWidth: cellWidth, lineHeight: lineHeight
+        ) else { return nil }
+        glyphRasterMemo[key] = raster
+        return raster
+    }
+
+    /// Rasterize + encode a scene as a stereo mode-3 frame at `boxes`.
+    func encode(_ frame: SceneFrame, boxes: LensBoxes, fid: UInt16) -> Data? {
+        guard let pixels = Self.rasterize(frame, width: Int(boxes.width), height: Int(boxes.height))
+        else { return nil }
+        return Self.stereoFrame(pixels: pixels, boxes: boxes, fid: fid)
+    }
+
+    // MARK: - Incremental updates (dirty rects / rect copy / builtin text)
+
+    /// A canvas-space rectangle aligned to mode 3's box quantization
+    /// (x/w multiples of 4, y/h multiples of 2).
+    struct CanvasRect: Equatable {
+        let x: Int
+        let y: Int
+        let w: Int
+        let h: Int
+    }
+
+    /// Full-width vertical band copy inside the canvas: rows
+    /// [srcY, srcY+height) become rows [dstY, dstY+height).
+    struct RowCopy: Equatable {
+        let srcY: Int
+        let dstY: Int
+        let 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.
+    struct DeltaPlan: Equatable {
+        let full: Bool
+        let copy: RowCopy?
+        let rects: [CanvasRect]
+
+        static let noop = DeltaPlan(full: false, copy: nil, rects: [])
+        static let fullFrame = DeltaPlan(full: true, copy: nil, rects: [])
+        var isNoop: Bool { !full && copy == nil && rects.isEmpty }
+    }
+
+    /// One firmware-drawn (mode 15) text line at absolute panel coordinates.
+    /// `boxWidth` is the source element's canvas-space box width — the erase
+    /// bounds floor, since the phone ellipsized the line against it.
+    struct TextDraw: Equatable {
+        let x: Int
+        let y: Int
+        let text: String
+        let boxWidth: Int
+    }
+
+    /// The result of one incremental encode: the wire payload (nil when the
+    /// frame is visually identical to the previous one), 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.
+    struct SceneUpdate {
+        let payload: Data?
+        let uploads: [Data]
+        let raster: Data
+        let usedFullFrame: Bool
+    }
+
+    /// 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.
+    struct MonoGrid {
+        let z: Int
+        let fontSize: Int32
+        let originX: Int
+        let originY: Int
+        let cellWidth: Int
+        let lineHeight: Int
+        let fullCols: Int
+        let fullRows: Int
+        /// Unicode scalar per cell; rows/cols beyond the text are spaces.
+        let rows: [[Unicode.Scalar]]
+
+        func scalar(row: Int, col: Int) -> Unicode.Scalar {
+            guard row < rows.count else { return " " }
+            let line = rows[row]
+            return col < line.count ? line[col] : " "
+        }
+
+        /// The canvas region whose every pixel belongs to a full cell.
+        var expressibleRegion: CanvasRect {
+            CanvasRect(x: originX, y: originY, w: fullCols * cellWidth, h: fullRows * lineHeight)
+        }
+
+        func covers(_ rect: CanvasRect) -> Bool {
+            let 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
+        }
+    }
+
+    /// Caps for the delta planner. maxDirtyRects bounds fids the caller must
+    /// pre-allocate (one per rect, plus full frame, a move blank, and a
+    /// right-margin blank).
+    static let maxDirtyRects = 6
+    static let requiredFidCount = maxDirtyRects + 3
+    /// Cap on mode-14 runs per update (mode-8's count byte is the hard bound).
+    static let maxGlyphRuns = 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).
+    static let builtinLineHeight = 27
+    static let builtinTextOptions: UInt8 = 0x1F
+    private static let dirtyRowMergeGap = 8
+    private static let fullFrameCoveragePercent = 60
+    private static let minScrollBandRows = 16
+    private static let scrollSavingsPercent = 30
+
+    /// Rasterize + plan + encode one incremental scene update.
+    ///
+    /// `previousRaster` is the canvas raster matching the on-glass shadow; nil
+    /// forces a full frame. `forcedRects` are treated as changed even when the
+    /// rasters agree (used to erase firmware-drawn text the raster never
+    /// contained). `textDraws` are appended after the pixel segments so glyphs
+    /// land on top of freshly pushed background. `blankBoxes` prepends a solid
+    /// black frame at a previous window position (window move) in the same
+    /// atomic bundle. `marginBlankBoxes` prepends a solid black frame OUTSIDE
+    /// the window — mode-15 draws at absolute panel coordinates without
+    /// clipping to the window, so stale glyph tails past the window's right
+    /// edge can only be erased by a frame aimed at the margin itself.
+    /// `omitBuiltinText` skips `font == "builtin"` text during rasterization —
+    /// the firmware draws those lines itself.
+    func encodeUpdate(
+        _ frame: SceneFrame, boxes: LensBoxes, previousRaster: Data?,
+        forcedRects: [CanvasRect], fids: [UInt16], textDraws: [TextDraw],
+        allowRectCopy: Bool, blankBoxes: LensBoxes?, marginBlankBoxes: LensBoxes? = nil,
+        omitBuiltinText: Bool,
+        textureGlyphsEnabled: Bool = false, textureImagesEnabled: Bool = false,
+        cacheGeneration: Int = 0
+    ) -> SceneUpdate? {
+        guard fids.count >= Self.requiredFidCount else { return nil }
+        let width = Int(boxes.width)
+        let height = Int(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.
+        let lensEqual = boxes.left == boxes.right
+        let useTexGlyphs = textureGlyphsEnabled && lensEqual
+        let 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(generation: cacheGeneration)
+        }
+
+        var grids: [MonoGrid] = []
+        let raster: Data
+        if useTexGlyphs {
+            guard let result = rasterizeGridExact(
+                frame, width: width, height: height, omitBuiltinText: omitBuiltinText
+            ) else { return nil }
+            raster = Self.quantizeToPanelLevels(result.raster)
+            grids = result.grids
+        } else {
+            guard let flat = Self.rasterize(
+                frame, width: width, height: height, omitBuiltinText: omitBuiltinText
+            ) else { return nil }
+            raster = Self.quantizeToPanelLevels(flat)
+        }
+
+        var nextFid = 0
+        func takeFid() -> UInt16 {
+            defer { nextFid += 1 }
+            return fids[nextFid]
+        }
+
+        var segments: [Data] = []
+        if let blankBoxes, let blank = Self.solidStereoFrame(color: 0, boxes: blankBoxes, fid: takeFid()) {
+            segments.append(blank)
+        }
+        if let marginBlankBoxes,
+           let blank = Self.solidStereoFrame(color: 0, boxes: marginBlankBoxes, fid: takeFid())
+        {
+            segments.append(blank)
+        }
+
+        let plan: DeltaPlan
+        if let previousRaster, previousRaster.count == raster.count, blankBoxes == nil {
+            plan = Self.diffPlan(
+                previous: previousRaster, next: raster, width: width, height: height,
+                forced: forcedRects, allowCopy: allowRectCopy
+            )
+        } else {
+            plan = .fullFrame
+        }
+
+        if plan.isNoop {
+            let uploads = textureCache.takeUploadPayloads()
+            return SceneUpdate(payload: nil, uploads: uploads, raster: raster, usedFullFrame: false)
+        }
+
+        if plan.full {
+            guard let full = Self.stereoFrame(pixels: raster, boxes: boxes, fid: takeFid())
+            else { return nil }
+            segments.append(full)
+        } else {
+            if let copy = plan.copy {
+                segments.append(Self.rectCopyPayload(copy: copy, width: width, boxes: boxes))
+            }
+            var deltaRects = plan.rects
+            var drawSegments: [Data] = []
+            if useTexGlyphs || useTexImages {
+                // Reserve one fid for the bundle-overflow fallback below.
+                let fidBudget = Self.requiredFidCount - nextFid - 1
+                let expressed = expressTextureRects(
+                    plan.rects, grids: useTexGlyphs ? grids : [], frame: frame,
+                    boxes: boxes, raster: raster, width: width, height: height,
+                    allowImages: useTexImages, fidBudget: fidBudget
+                )
+                deltaRects = expressed.deltas
+                drawSegments = expressed.draws
+            }
+            for rect in deltaRects {
+                guard let delta = Self.boxDeltaFrame(
+                    raster: raster, canvasWidth: width, rect: rect, boxes: boxes, fid: takeFid()
+                ) else { return nil }
+                segments.append(delta)
+            }
+            segments.append(contentsOf: drawSegments)
+        }
+
+        for draw in textDraws {
+            if let text = Self.builtinStringPayload(
+                x: draw.x, y: draw.y, options: Self.builtinTextOptions, text: draw.text
+            ) {
+                segments.append(text)
+            }
+        }
+
+        let uploads = textureCache.takeUploadPayloads()
+        if segments.count == 1 {
+            return SceneUpdate(payload: segments[0], uploads: uploads, raster: raster, usedFullFrame: plan.full)
+        }
+        if let bundled = Self.bundle(segments) {
+            return SceneUpdate(payload: bundled, uploads: uploads, raster: raster, usedFullFrame: 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.
+        guard let flat = Self.rasterize(frame, width: width, height: height, omitBuiltinText: false),
+              let full = Self.stereoFrame(pixels: flat, boxes: boxes, fid: takeFid())
+        else { return nil }
+        return SceneUpdate(payload: full, uploads: uploads, raster: 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 func rasterizeGridExact(
+        _ frame: SceneFrame, width: Int, height: Int, omitBuiltinText: Bool
+    ) -> (raster: Data, grids: [MonoGrid])? {
+        guard var raster = Self.rasterize(
+            frame, width: width, height: height, omitBuiltinText: omitBuiltinText, omitMonoText: true
+        ) else { return nil }
+
+        var grids: [MonoGrid] = []
+        for (z, element) in frame.elements.enumerated()
+            where element.type == "text" && element.font == "mono"
+        {
+            let bx = Int(element.x)
+            let by = Int(element.y)
+            let clipX0 = max(0, bx)
+            let clipY0 = max(0, by)
+            let clipX1 = min(width, bx + Int(element.w))
+            let clipY1 = min(height, by + Int(element.h))
+            guard clipX0 < clipX1, clipY0 < clipY1 else { continue }
+            let metrics = Self.monoCellMetrics(fontSize: element.fontSize)
+            let originX = bx + 2
+            let originY = by + 2
+            raster.withUnsafeMutableBytes { buf in
+                let base = buf.bindMemory(to: UInt8.self).baseAddress!
+                for y in clipY0 ..< clipY1 {
+                    memset(base + y * width + clipX0, 0, clipX1 - clipX0)
+                }
+            }
+            let lines: [[Unicode.Scalar]] = (element.text ?? "")
+                .split(separator: "\n", omittingEmptySubsequences: false)
+                .map { Array($0.unicodeScalars) }
+            let blitCols = max(0, (clipX1 - originX + metrics.cellWidth - 1) / metrics.cellWidth)
+            let blitRows = max(0, (clipY1 - originY + metrics.lineHeight - 1) / metrics.lineHeight)
+            for row in 0 ..< min(blitRows, lines.count) {
+                let line = lines[row]
+                for col in 0 ..< min(blitCols, line.count) where line[col].value != 32 {
+                    guard let glyph = memoizedGlyphRaster(
+                        line[col], fontSize: element.fontSize,
+                        cellWidth: metrics.cellWidth, lineHeight: metrics.lineHeight
+                    ) else { continue }
+                    Self.blitCell(
+                        glyph, into: &raster, rasterWidth: width,
+                        atX: originX + col * metrics.cellWidth, atY: originY + row * metrics.lineHeight,
+                        cellWidth: metrics.cellWidth, cellHeight: metrics.lineHeight,
+                        clipX0: clipX0, clipY0: clipY0, clipX1: clipX1, clipY1: clipY1
+                    )
+                }
+            }
+            grids.append(MonoGrid(
+                z: z, fontSize: element.fontSize, originX: originX, originY: originY,
+                cellWidth: metrics.cellWidth, lineHeight: metrics.lineHeight,
+                fullCols: max(0, (clipX1 - originX) / metrics.cellWidth),
+                fullRows: max(0, (clipY1 - originY) / metrics.lineHeight),
+                rows: lines
+            ))
+        }
+        return (raster, grids)
+    }
+
+    private static func blitCell(
+        _ glyph: Data, into raster: inout Data, rasterWidth: Int,
+        atX: Int, atY: Int, cellWidth: Int, cellHeight: Int,
+        clipX0: Int, clipY0: Int, clipX1: Int, clipY1: Int
+    ) {
+        let x0 = max(atX, clipX0)
+        let y0 = max(atY, clipY0)
+        let x1 = min(atX + cellWidth, clipX1)
+        let y1 = min(atY + cellHeight, clipY1)
+        guard x0 < x1, y0 < y1 else { return }
+        raster.withUnsafeMutableBytes { dstRaw in
+            glyph.withUnsafeBytes { srcRaw in
+                let dst = dstRaw.bindMemory(to: UInt8.self).baseAddress!
+                let src = srcRaw.bindMemory(to: UInt8.self).baseAddress!
+                for y in y0 ..< y1 {
+                    memcpy(
+                        dst + y * rasterWidth + x0,
+                        src + (y - atY) * cellWidth + (x0 - atX),
+                        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 func expressTextureRects(
+        _ rects: [CanvasRect], grids: [MonoGrid], frame: SceneFrame,
+        boxes: LensBoxes, raster: Data, width: Int, height: Int,
+        allowImages: Bool, fidBudget: Int
+    ) -> (deltas: [CanvasRect], draws: [Data]) {
+        struct ElementBox {
+            let z: Int
+            let x0: Int
+            let y0: Int
+            let x1: Int
+            let y1: Int
+            func intersects(_ r: CanvasRect) -> Bool {
+                r.x < x1 && r.x + r.w > x0 && r.y < y1 && r.y + r.h > y0
+            }
+        }
+        let elementBoxes: [ElementBox] = frame.elements.enumerated().map { z, el in
+            ElementBox(
+                z: z, x0: max(0, Int(el.x)), y0: max(0, Int(el.y)),
+                x1: min(width, Int(el.x) + Int(el.w)), y1: min(height, Int(el.y) + Int(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).
+        struct ImageCandidate {
+            let box: ElementBox
+            let key: String
+            let seen: Bool
+        }
+        var imageCandidates: [Int: ImageCandidate] = [:]
+        if allowImages {
+            for (z, el) in frame.elements.enumerated() where el.type == "image" {
+                let box = elementBoxes[z]
+                let w = box.x1 - box.x0
+                let h = box.y1 - box.y0
+                guard w > 0, h > 0, w <= 255, h <= 255, !el.contentHash.isEmpty else { continue }
+                let isolated = !elementBoxes.contains { other in
+                    other.z != z && other.x0 < box.x1 && other.x1 > box.x0
+                        && other.y0 < box.y1 && other.y1 > box.y0
+                }
+                guard isolated else { continue }
+                let key = "\(el.contentHash)@\(w)x\(h)"
+                imageCandidates[z] = ImageCandidate(
+                    box: box, key: key, seen: textureCache.noteImageSighting(key)
+                )
+            }
+        }
+
+        var deltas: [CanvasRect] = []
+        var imageDraws: [Int: Data] = [:]
+        var runPayloads: [Data] = []
+        var runCount = 0
+
+        rectLoop: for (index, rect) in rects.enumerated() {
+            let remaining = rects.count - index - 1
+
+            // Glyph express: topmost mono grid fully covering the rect, with
+            // nothing stacked above it in that region.
+            if let grid = grids.filter({ $0.covers(rect) }).max(by: { $0.z < $1.z }),
+               !elementBoxes.contains(where: { $0.z > grid.z && $0.intersects(rect) }),
+               let font = textureCache.font(
+                   fontSize: grid.fontSize, cellWidth: grid.cellWidth, lineHeight: grid.lineHeight
+               )
+            {
+                let r0 = (rect.y - grid.originY) / grid.lineHeight
+                let r1 = (rect.y + rect.h - 1 - grid.originY) / grid.lineHeight
+                let c0 = (rect.x - grid.originX) / grid.cellWidth
+                let c1 = (rect.x + rect.w - 1 - grid.originX) / grid.cellWidth
+                var newRuns: [(x: Int, y: Int, chars: [UInt8])] = []
+                var residuals: [CanvasRect] = []
+                var expressible = true
+                for row in r0 ... r1 {
+                    let rowY = grid.originY + row * grid.lineHeight
+                    var runChars: [UInt8] = []
+                    var runStartCol = c0
+                    var residualStart: Int?
+                    func flushRun(endCol: Int) {
+                        guard !runChars.isEmpty else { return }
+                        newRuns.append((
+                            x: grid.originX + runStartCol * grid.cellWidth, y: rowY, chars: runChars
+                        ))
+                        runChars = []
+                        _ = endCol
+                    }
+                    func flushResidual(endCol: Int) {
+                        guard let start = residualStart else { return }
+                        let x0 = max(0, (grid.originX + start * grid.cellWidth) & ~3)
+                        let x1 = min(width, (grid.originX + endCol * grid.cellWidth + 3) & ~3)
+                        let y0 = max(0, rowY & ~1)
+                        let y1 = min(height, (rowY + grid.lineHeight + 1) & ~1)
+                        residuals.append(CanvasRect(x: x0, y: y0, w: x1 - x0, h: y1 - y0))
+                        residualStart = nil
+                    }
+                    for col in c0 ... c1 {
+                        let scalar = grid.scalar(row: row, col: col)
+                        if scalar.value >= 32, scalar.value <= 126,
+                           textureCache.ensureGlyph(font: font, char: UInt8(scalar.value), rasterize: {
+                               self.memoizedGlyphRaster(
+                                   scalar, fontSize: grid.fontSize,
+                                   cellWidth: grid.cellWidth, lineHeight: grid.lineHeight
+                               )
+                           })
+                        {
+                            flushResidual(endCol: col)
+                            if runChars.isEmpty { runStartCol = col }
+                            runChars.append(UInt8(scalar.value))
+                            if runChars.count == 255 { flushRun(endCol: col + 1) }
+                        } else {
+                            flushRun(endCol: col)
+                            if residualStart == nil { residualStart = col }
+                        }
+                    }
+                    flushRun(endCol: c1 + 1)
+                    flushResidual(endCol: c1 + 1)
+                    if runCount + newRuns.count > Self.maxGlyphRuns { expressible = false; break }
+                }
+                // Residual deltas + every remaining rect must still fit the
+                // fid budget; otherwise keep this rect as one plain delta.
+                if expressible, deltas.count + residuals.count + remaining + 1 <= fidBudget,
+                   residuals.count <= 3
+                {
+                    var payloads: [Data] = []
+                    for run in newRuns {
+                        guard let payload = G2CfwTextureCache.stringRunPayload(
+                            fontTableOffset: font.tableOffset,
+                            x: Int(boxes.left.x) + run.x, y: Int(boxes.left.y) + run.y,
+                            options: G2CfwTextureCache.opaqueDrawOptions, chars: run.chars
+                        ) else { payloads = []; break }
+                        payloads.append(payload)
+                    }
+                    if !payloads.isEmpty || newRuns.isEmpty {
+                        runPayloads.append(contentsOf: payloads)
+                        runCount += payloads.count
+                        deltas.append(contentsOf: 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,
+               let (z, candidate) = imageCandidates.first(where: { _, c in
+                   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 imageDraws[z] != nil { continue rectLoop }
+                let w = candidate.box.x1 - candidate.box.x0
+                let h = candidate.box.y1 - candidate.box.y0
+                var gray = Data(capacity: w * h)
+                raster.withUnsafeBytes { raw in
+                    let src = raw.bindMemory(to: UInt8.self)
+                    for y in candidate.box.y0 ..< candidate.box.y1 {
+                        gray.append(contentsOf: UnsafeBufferPointer(
+                            start: src.baseAddress! + y * width + candidate.box.x0, count: w
+                        ))
+                    }
+                }
+                if let offset = textureCache.ensureImage(hash: candidate.key, gray: gray, width: w, height: h),
+                   let draw = G2CfwTextureCache.imageDrawPayload(
+                       offset: offset,
+                       x: Int(boxes.left.x) + candidate.box.x0, y: Int(boxes.left.y) + candidate.box.y0,
+                       options: G2CfwTextureCache.opaqueDrawOptions
+                   )
+                {
+                    imageDraws[z] = draw
+                    continue rectLoop
+                }
+            }
+
+            deltas.append(rect)
+        }
+
+        let draws = imageDraws.sorted { $0.key < $1.key }.map(\.value) + runPayloads
+        return (deltas, draws)
+    }
+
+    /// Diff two same-size canvas rasters into a scroll copy + aligned dirty
+    /// rects, or a full-frame decision when the change is too large to be
+    /// worth splitting.
+    static func diffPlan(
+        previous: Data, next: Data, width: Int, height: Int,
+        forced: [CanvasRect], allowCopy: Bool
+    ) -> DeltaPlan {
+        guard previous.count == width * height, next.count == width * height,
+              width > 0, height > 0
+        else { return .fullFrame }
+
+        return previous.withUnsafeBytes { prevRaw in
+            next.withUnsafeBytes { nextRaw in
+                let prev = prevRaw.bindMemory(to: UInt8.self)
+                let new = nextRaw.bindMemory(to: UInt8.self)
+
+                var changed = [Bool](repeating: false, count: height)
+                var anyChanged = false
+                for y in 0 ..< height {
+                    let row = y * width
+                    if memcmp(prev.baseAddress! + row, new.baseAddress! + row, width) != 0 {
+                        changed[y] = true
+                        anyChanged = true
+                    }
+                }
+                if !anyChanged, forced.isEmpty { return .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?
+                var predicted: [UInt8]?
+                if allowCopy, anyChanged {
+                    var prevHash = [UInt64](repeating: 0, count: height)
+                    var newHash = [UInt64](repeating: 0, count: height)
+                    for y in 0 ..< height {
+                        prevHash[y] = rowHash(prev, offset: y * width, count: width)
+                        newHash[y] = rowHash(new, offset: y * width, count: width)
+                    }
+                    let changedCount = changed.lazy.filter { $0 }.count
+                    var bestDy = 0
+                    var bestScore = 0
+                    let maxShift = height - minScrollBandRows
+                    if maxShift > 0 {
+                        for dy in -maxShift ... maxShift where dy != 0 {
+                            var score = 0
+                            let lo = max(0, -dy)
+                            let hi = min(height, height - dy)
+                            for y in lo ..< hi where changed[y] && newHash[y] == prevHash[y + dy] {
+                                score += 1
+                            }
+                            if score > bestScore {
+                                bestScore = score
+                                bestDy = dy
+                            }
+                        }
+                    }
+                    if bestDy != 0, bestScore >= minScrollBandRows,
+                       bestScore * 100 >= changedCount * scrollSavingsPercent
+                    {
+                        // Longest contiguous hash-matching run, then byte-verify.
+                        var runStart = -1
+                        var bandStart = 0
+                        var bandLen = 0
+                        let lo = max(0, -bestDy)
+                        let hi = min(height, height - bestDy)
+                        for y in lo ... hi {
+                            let 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 >= minScrollBandRows {
+                            var verified = true
+                            for y in bandStart ..< bandStart + bandLen where verified {
+                                verified = memcmp(
+                                    new.baseAddress! + y * width,
+                                    prev.baseAddress! + (y + bestDy) * width, width
+                                ) == 0
+                            }
+                            if verified {
+                                copy = RowCopy(srcY: bandStart + bestDy, dstY: bandStart, height: bandLen)
+                                var scratch = [UInt8](repeating: 0, count: width * height)
+                                scratch.withUnsafeMutableBufferPointer { buf in
+                                    memcpy(buf.baseAddress!, prev.baseAddress!, width * height)
+                                    memmove(
+                                        buf.baseAddress! + bandStart * width,
+                                        prev.baseAddress! + (bandStart + bestDy) * width,
+                                        bandLen * width
+                                    )
+                                }
+                                predicted = scratch
+                                for y in bandStart ..< bandStart + bandLen {
+                                    changed[y] = false
+                                }
+                                anyChanged = changed.contains(true)
+                            }
+                        }
+                    }
+                }
+
+                // Per-row dirty column ranges against the (possibly copied) base.
+                var colLo = [Int](repeating: Int.max, count: height)
+                var colHi = [Int](repeating: -1, count: height)
+                func base(_ y: Int, _ x: Int) -> UInt8 {
+                    if let predicted { return predicted[y * width + x] }
+                    return prev[y * width + x]
+                }
+                for y in 0 ..< height where changed[y] {
+                    var lo = 0
+                    while lo < width, base(y, lo) == new[y * width + lo] { lo += 1 }
+                    var hi = width - 1
+                    while hi > lo, base(y, hi) == new[y * width + hi] { hi -= 1 }
+                    colLo[y] = lo
+                    colHi[y] = hi
+                }
+                var dirtyRows = changed
+                for rect in forced {
+                    let y0 = max(0, rect.y)
+                    let y1 = min(height, rect.y + rect.h)
+                    guard y0 < y1, rect.w > 0 else { continue }
+                    for y in y0 ..< y1 {
+                        dirtyRows[y] = true
+                        colLo[y] = min(colLo[y], max(0, rect.x))
+                        colHi[y] = max(colHi[y], min(width - 1, rect.x + rect.w - 1))
+                    }
+                }
+                guard dirtyRows.contains(true) else {
+                    if let copy { return DeltaPlan(full: false, copy: copy, rects: []) }
+                    return .noop
+                }
+
+                // Group dirty rows into bands (small gaps merge), then align
+                // each band to the mode-3 quantization grid.
+                var rects: [CanvasRect] = []
+                var y = 0
+                while y < height {
+                    guard dirtyRows[y] else {
+                        y += 1
+                        continue
+                    }
+                    var end = y
+                    var gap = 0
+                    var scan = y
+                    while scan < height, gap <= dirtyRowMergeGap {
+                        if dirtyRows[scan] {
+                            end = scan
+                            gap = 0
+                        } else {
+                            gap += 1
+                        }
+                        scan += 1
+                    }
+                    var lo = Int.max
+                    var hi = -1
+                    for row in y ... end where dirtyRows[row] {
+                        lo = min(lo, colLo[row])
+                        hi = max(hi, colHi[row])
+                    }
+                    let x0 = max(0, lo & ~3)
+                    let x1 = min(width, (hi + 4) & ~3)
+                    let ry0 = max(0, y & ~1)
+                    let ry1 = min(height, (end + 2) & ~1)
+                    rects.append(CanvasRect(x: x0, y: ry0, w: x1 - x0, h: ry1 - ry0))
+                    y = end + 1
+                }
+                if rects.count > maxDirtyRects {
+                    var x0 = Int.max
+                    var y0 = Int.max
+                    var x1 = 0
+                    var y1 = 0
+                    for rect in rects {
+                        x0 = min(x0, rect.x)
+                        y0 = min(y0, rect.y)
+                        x1 = max(x1, rect.x + rect.w)
+                        y1 = max(y1, rect.y + rect.h)
+                    }
+                    rects = [CanvasRect(x: x0, y: y0, w: x1 - x0, h: y1 - y0)]
+                }
+                let coverage = rects.reduce(0) { $0 + $1.w * $1.h }
+                if copy == nil, coverage * 100 >= width * height * fullFrameCoveragePercent {
+                    return .fullFrame
+                }
+                return DeltaPlan(full: false, copy: copy, rects: rects)
+            }
+        }
+    }
+
+    private static func rowHash(_ pixels: UnsafeBufferPointer<UInt8>, offset: Int, count: Int) -> UInt64 {
+        // FNV-1a 64 — collision-safe enough for scoring; bands are byte-verified.
+        var hash: UInt64 = 0xCBF2_9CE4_8422_2325
+        for i in offset ..< offset + count {
+            hash = (hash ^ UInt64(pixels[i])) &* 0x0000_0100_0000_01B3
+        }
+        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.
+    static func boxDeltaFrame(
+        raster: Data, canvasWidth: Int, rect: CanvasRect, boxes: LensBoxes, fid: UInt16
+    ) -> Data? {
+        guard 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.count
+        else { return nil }
+        var pixels = Data(capacity: rect.w * rect.h)
+        raster.withUnsafeBytes { raw in
+            let src = raw.bindMemory(to: UInt8.self)
+            for y in rect.y ..< rect.y + rect.h {
+                pixels.append(contentsOf: UnsafeBufferPointer(
+                    start: src.baseAddress! + y * canvasWidth + rect.x, count: rect.w
+                ))
+            }
+        }
+        let rle = rleEncode(pack4Bpp(pixels))
+        return stereoRleFrame(
+            rle: rle,
+            lx: Int(boxes.left.x) + rect.x, ly: Int(boxes.left.y) + rect.y,
+            rx: Int(boxes.right.x) + rect.x, ry: Int(boxes.right.y) + rect.y,
+            w: Int32(rect.w), h: Int32(rect.h), fid: fid
+        )
+    }
+
+    /// 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.
+    static func rectCopyPayload(copy: RowCopy, width: Int, boxes: LensBoxes) -> Data {
+        var payload = Data([0x89])
+        func appendRect(_ x: Int, _ y: Int) {
+            for value in [x, y, width, copy.height] {
+                payload.append(UInt8(value & 0xFF))
+                payload.append(UInt8((value >> 8) & 0xFF))
+            }
+        }
+        appendRect(Int(boxes.left.x), Int(boxes.left.y) + copy.srcY)
+        appendRect(Int(boxes.left.x), Int(boxes.left.y) + copy.dstY)
+        appendRect(Int(boxes.right.x), Int(boxes.right.y) + copy.srcY)
+        appendRect(Int(boxes.right.x), Int(boxes.right.y) + copy.dstY)
+        return payload
+    }
+
+    /// 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.
+    static func builtinStringPayload(x: Int, y: Int, options: UInt8, text: String) -> Data? {
+        guard x >= 0, x <= 0xFFFF, y >= 0, y <= 0xFFFF else { return nil }
+        let sanitized = String(text.unicodeScalars.filter { $0.value >= 32 })
+        var bytes = Array(sanitized.utf8)
+        if bytes.count > 255 {
+            var cut = 255
+            while cut > 0, bytes[cut] & 0xC0 == 0x80 { cut -= 1 }
+            bytes = Array(bytes[..<cut])
+        }
+        guard !bytes.isEmpty else { return nil }
+        var payload = Data([15])
+        payload.append(UInt8(x & 0xFF))
+        payload.append(UInt8((x >> 8) & 0xFF))
+        payload.append(UInt8(y & 0xFF))
+        payload.append(UInt8((y >> 8) & 0xFF))
+        payload.append(options)
+        payload.append(UInt8(bytes.count))
+        payload.append(contentsOf: bytes)
+        return payload
+    }
+
+    /// 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.
+    static func builtinTextDraws(_ frame: SceneFrame, boxes: LensBoxes) -> [TextDraw] {
+        var draws: [TextDraw] = []
+        for element in frame.elements where element.type == "text" && element.font == "builtin" {
+            guard let text = element.text, !text.isEmpty else { continue }
+            let baseX = Int(boxes.left.x) + Int(element.x) + 2
+            let baseY = Int(boxes.left.y) + Int(element.y) + 2
+            for (index, line) in text.split(separator: "\n", omittingEmptySubsequences: false).enumerated() {
+                let y = baseY + index * builtinLineHeight
+                guard y >= 0, y + builtinLineHeight <= frameHeight, !line.isEmpty else { continue }
+                draws.append(TextDraw(x: baseX, y: y, text: String(line), boxWidth: Int(element.w)))
+            }
+        }
+        return draws
+    }
+
+    /// Conservative canvas-space bounds of firmware-drawn text, used to force
+    /// background re-pushes that erase glyphs the phone raster never
+    /// contained. The phone has no advance tables, so width is the char-count
+    /// estimate floored at the element's box width — wide glyphs overshoot
+    /// 13px/char, and an undershot erase leaves glyph tails on the panel.
+    static func builtinTextBounds(
+        _ draws: [TextDraw], boxes: LensBoxes, canvasWidth: Int, canvasHeight: Int
+    ) -> [CanvasRect] {
+        draws.compactMap { draw in
+            let x = max(0, draw.x - Int(boxes.left.x) - 4)
+            let y = max(0, draw.y - Int(boxes.left.y) - 2)
+            guard x < canvasWidth, y < canvasHeight else { return nil }
+            let width = min(canvasWidth - x, max(draw.text.count * 13 + 30, draw.boxWidth + 8))
+            let height = min(canvasHeight - y, builtinLineHeight + 4)
+            return CanvasRect(x: x, y: y, w: width, h: height)
+        }
+    }
+
+    /// Rasterize a scene into a width×height 8-bit grayscale buffer (row-major,
+    /// one byte per pixel), or nil when an image element fails to decode.
+    /// `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.
+    static func rasterize(
+        _ frame: SceneFrame, width: Int, height: Int, omitBuiltinText: Bool = false,
+        omitMonoText: Bool = false
+    ) -> Data? {
+        var decodedImages: [Int: UIImage] = [:]
+        for (index, element) in frame.elements.enumerated() where element.type == "image" {
+            guard let encoded = element.data,
+                  let data = Data(base64Encoded: encoded),
+                  let image = UIImage(data: data)
+            else { return nil }
+            decodedImages[index] = image
+        }
+
+        let format = UIGraphicsImageRendererFormat()
+        format.scale = 1
+        format.opaque = true
+        let renderer = UIGraphicsImageRenderer(
+            size: CGSize(width: CGFloat(width), height: CGFloat(height)),
+            format: format
+        )
+        let image = renderer.image { rendererContext in
+            let context = rendererContext.cgContext
+            context.setFillColor(UIColor.black.cgColor)
+            context.fill(CGRect(x: 0, y: 0, width: CGFloat(width), height: CGFloat(height)))
+
+            context.saveGState()
+            for (index, element) in frame.elements.enumerated() {
+                // Mode 15 draws only the glyphs, so an omitted builtin-text
+                // element's border must still come from the raster.
+                let skipBuiltinInk = omitBuiltinText && element.type == "text"
+                    && element.font == "builtin"
+                if skipBuiltinInk, element.border <= 0 {
+                    continue
+                }
+                if omitMonoText, element.type == "text", element.font == "mono" {
+                    continue
+                }
+                let rect = CGRect(
+                    x: CGFloat(element.x), y: CGFloat(element.y),
+                    width: CGFloat(element.w), height: CGFloat(element.h)
+                )
+                context.saveGState()
+                context.clip(to: rect)
+
+                switch element.type {
+                case "text" where skipBuiltinInk:
+                    break
+
+                case "text":
+                    let paragraph = NSMutableParagraphStyle()
+                    let font: UIFont
+                    if element.font == "mono" {
+                        // Grid text: fixed pitch, fixed line height, no re-wrap —
+                        // the app laid out cols × rows against these metrics.
+                        let size = CGFloat(element.fontSize > 0 ? element.fontSize : 20)
+                        font = UIFont.monospacedSystemFont(ofSize: size, weight: .regular)
+                        paragraph.lineBreakMode = .byClipping
+                        paragraph.minimumLineHeight = Self.monoLineHeight(fontSize: size)
+                        paragraph.maximumLineHeight = paragraph.minimumLineHeight
+                    } else {
+                        font = UIFont.systemFont(ofSize: 20)
+                        paragraph.lineBreakMode = .byWordWrapping
+                    }
+                    let attributes: [NSAttributedString.Key: Any] = [
+                        .font: font,
+                        .foregroundColor: UIColor.white,
+                        .paragraphStyle: paragraph,
+                    ]
+                    ((element.text ?? "") as NSString).draw(
+                        in: rect.insetBy(dx: 2, dy: 2), withAttributes: attributes
+                    )
+
+                case "image":
+                    if let source = decodedImages[index] {
+                        let sourceSize = source.size
+                        let imageScale = min(
+                            rect.width / max(sourceSize.width, 1),
+                            rect.height / max(sourceSize.height, 1)
+                        )
+                        let target = CGSize(
+                            width: sourceSize.width * imageScale,
+                            height: sourceSize.height * imageScale
+                        )
+                        source.draw(
+                            in: CGRect(
+                                x: rect.midX - target.width / 2,
+                                y: rect.midY - target.height / 2,
+                                width: target.width, height: target.height
+                            )
+                        )
+                    }
+
+                case "rect":
+                    break
+
+                default:
+                    break
+                }
+
+                let logicalBorder = max(element.type == "rect" ? Int32(1) : 0, element.border)
+                if logicalBorder > 0 {
+                    context.setStrokeColor(UIColor.white.cgColor)
+                    context.setLineWidth(CGFloat(logicalBorder))
+                    let inset = CGFloat(logicalBorder) / 2
+                    let borderRect = rect.insetBy(dx: inset, dy: inset)
+                    let radius = min(
+                        CGFloat(max(0, element.radius)),
+                        min(borderRect.width, borderRect.height) / 2
+                    )
+                    context.addPath(
+                        UIBezierPath(roundedRect: borderRect, cornerRadius: radius).cgPath
+                    )
+                    context.strokePath()
+                }
+                context.restoreGState()
+            }
+            context.restoreGState()
+        }
+
+        guard let cgImage = image.cgImage else { return nil }
+        var grayscale = Data(count: width * height)
+        let rendered = grayscale.withUnsafeMutableBytes { buffer -> Bool in
+            guard let context = CGContext(
+                data: buffer.baseAddress,
+                width: width,
+                height: height,
+                bitsPerComponent: 8,
+                bytesPerRow: width,
+                space: CGColorSpaceCreateDeviceGray(),
+                bitmapInfo: CGImageAlphaInfo.none.rawValue
+            ) else { return false }
+            context.setFillColor(gray: 0, alpha: 1)
+            context.fill(CGRect(x: 0, y: 0, width: CGFloat(width), height: CGFloat(height)))
+            context.draw(cgImage, in: CGRect(x: 0, y: 0, width: CGFloat(width), height: CGFloat(height)))
+            return true
+        }
+        return rendered ? grayscale : nil
+    }
+
+    /// Mode 3 with the lenses-differ bit: one zlib(RLE(4bpp)) payload of the
+    /// box pixels, drawn by each lens at its own box.
+    /// `[0x83][lx/4][ly/2][w/4][h/2][rx/4][ry/2][w/4][h/2][fid lo][fid hi][zlib]`
+    static func stereoFrame(pixels: Data, boxes: LensBoxes, fid: UInt16) -> Data? {
+        guard pixels.count == Int(boxes.width) * Int(boxes.height) else { return nil }
+        let rle = rleEncode(pack4Bpp(pixels))
+        return stereoFrame(rle: rle, boxes: boxes, fid: fid)
+    }
+
+    /// Solid-color mode-3 frame at `boxes` — blanks a previous window position.
+    static func solidStereoFrame(color: UInt8, boxes: LensBoxes, fid: UInt16) -> Data? {
+        let rle = rleEncodeSolid(color: color, pixelCount: Int(boxes.width) * Int(boxes.height))
+        return stereoFrame(rle: rle, boxes: boxes, fid: fid)
+    }
+
+    private static func stereoFrame(rle: Data, boxes: LensBoxes, fid: UInt16) -> Data? {
+        stereoRleFrame(
+            rle: rle,
+            lx: Int(boxes.left.x), ly: Int(boxes.left.y),
+            rx: Int(boxes.right.x), ry: Int(boxes.right.y),
+            w: boxes.width, h: boxes.height, fid: fid
+        )
+    }
+
+    private static func stereoRleFrame(
+        rle: Data, lx: Int, ly: Int, rx: Int, ry: Int, w: Int32, h: Int32, fid: UInt16
+    ) -> Data? {
+        guard let compressed = BinaryCodec.zlibRFC1950(rle) else { return nil }
+        var payload = Data([0x83])
+        for (x, y) in [(lx, ly), (rx, ry)] {
+            payload.append(UInt8(x / 4))
+            payload.append(UInt8(y / 2))
+            payload.append(UInt8(w / 4))
+            payload.append(UInt8(h / 2))
+        }
+        payload.append(UInt8(fid & 0xFF))
+        payload.append(UInt8(fid >> 8))
+        payload.append(compressed)
+        return payload
+    }
+
+    /// Mode 8: apply every segment to the shadow, then present once.
+    /// `[8][count][len lo][len hi][segment]...`
+    static func bundle(_ segments: [Data]) -> Data? {
+        guard !segments.isEmpty, segments.count <= 255 else { return nil }
+        for segment in segments where segment.isEmpty || segment.count > 0xFFFF {
+            return nil
+        }
+        var payload = Data([8, UInt8(segments.count)])
+        for segment in segments {
+            payload.append(UInt8(segment.count & 0xFF))
+            payload.append(UInt8(segment.count >> 8))
+            payload.append(segment)
+        }
+        return payload
+    }
+
+    /// 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 nil unless the window is lens-equal — callers fall back to the
+    /// black seed there.
+    static func seededFramePayload(pixels: Data, boxes: LensBoxes) -> Data? {
+        guard boxes.left == boxes.right,
+              pixels.count == Int(boxes.width) * Int(boxes.height)
+        else { return nil }
+        var panel = Data(count: frameWidth * frameHeight)
+        let x0 = Int(boxes.left.x)
+        let y0 = Int(boxes.left.y)
+        let w = Int(boxes.width)
+        let h = Int(boxes.height)
+        panel.withUnsafeMutableBytes { dstRaw in
+            pixels.withUnsafeBytes { srcRaw in
+                let dst = dstRaw.bindMemory(to: UInt8.self).baseAddress!
+                let src = srcRaw.bindMemory(to: UInt8.self).baseAddress!
+                for row in 0 ..< h {
+                    memcpy(dst + (y0 + row) * frameWidth + x0, src + row * w, w)
+                }
+            }
+        }
+        return encodePixels(panel)
+    }
+
+    /// Mode 6 full-panel black: seeds the shadow mode-3 frames composite onto.
+    static func blackPayload() -> Data? {
+        let pixelCount = frameWidth * frameHeight
+        let rle = rleEncodeSolid(color: 0, pixelCount: pixelCount)
+        guard let compressed = BinaryCodec.zlibRFC1950(rle) else { return nil }
+        var payload = Data([6])
+        payload.append(compressed)
+        return payload
+    }
+
+    static func encodePixels(_ grayscale: Data) -> Data? {
+        guard grayscale.count == frameWidth * frameHeight else { return nil }
+        let packed = pack4Bpp(grayscale)
+        let rle = rleEncode(packed)
+        guard let compressed = BinaryCodec.zlibRFC1950(rle) else { return nil }
+        var payload = Data([6])
+        payload.append(compressed)
+        return payload
+    }
+
+    /// 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.
+    static func grayNibble(_ value: UInt8) -> UInt8 {
+        value == 0 ? 0 : UInt8(min(15, (Int(value) + 8) >> 4))
+    }
+
+    /// 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.
+    static func quantizeToPanelLevels(_ raster: Data) -> Data {
+        var out = raster
+        out.withUnsafeMutableBytes { buffer in
+            guard let base = buffer.bindMemory(to: UInt8.self).baseAddress else { return }
+            for index in 0 ..< buffer.count {
+                base[index] = grayNibble(base[index]) &* 16
+            }
+        }
+        return out
+    }
+
+    static func pack4Bpp(_ grayscale: Data) -> Data {
+        let source = [UInt8](grayscale)
+        var packed = Data(count: (source.count + 1) / 2)
+        for index in packed.indices {
+            let left = grayNibble(source[index * 2])
+            let rightIndex = index * 2 + 1
+            let right = rightIndex < source.count ? grayNibble(source[rightIndex]) : 0
+            packed[index] = (left << 4) | right
+        }
+        return packed
+    }
+
+    static func rleEncode(_ packed: Data) -> Data {
+        let bytes = [UInt8](packed)
+        let pixelCount = bytes.count * 2
+        var output = Data()
+        output.reserveCapacity(pixelCount / 4)
+
+        func nibble(_ index: Int) -> UInt8 {
+            index.isMultiple(of: 2) ? bytes[index / 2] >> 4 : bytes[index / 2] & 0x0F
+        }
+
+        var index = 0
+        while index < pixelCount {
+            let value = nibble(index)
+            var end = index + 1
+            while end < pixelCount, nibble(end) == value {
+                end += 1
+            }
+            appendRun(color: value, count: end - index, to: &output)
+            index = end
+        }
+        return output
+    }
+
+    private static func rleEncodeSolid(color: UInt8, pixelCount: Int) -> Data {
+        var output = Data()
+        appendRun(color: color & 0x0F, count: pixelCount, to: &output)
+        return output
+    }
+
+    private static func appendRun(color: UInt8, count: Int, to output: inout Data) {
+        var remaining = count
+        while remaining > 0 {
+            let chunk = min(remaining, 0xFFFF)
+            if chunk <= 15 {
+                output.append(UInt8(chunk << 4) | color)
+            } else if chunk <= 255 {
+                output.append(color)
+                output.append(UInt8(chunk))
+            } else {
+                output.append(color)
+                output.append(0)
+                output.append(UInt8(chunk & 0xFF))
+                output.append(UInt8((chunk >> 8) & 0xFF))
+            }
+            remaining -= chunk
+        }
+    }
+}