@glassly/bluetooth-sdk 0.1.0-dev.105 → 0.1.0-dev.106

package/android/src/main/java/com/glassly/bluetoothsdk/DeviceManager.kt

@@ -1703,6 +1703,15 @@ class DeviceManager {
             elementsRaw.mapNotNull { el ->
                 val box = el["box"] as? Map<String, Any> ?: return@mapNotNull null
                 val style = el["style"] as? Map<String, Any>
+                val transition = el["transition"] as? Map<String, Any>
+                val points =
+                    (el["points"] as? List<*>)?.flatMap { p ->
+                        val point = p as? Map<*, *>
+                        listOf((point?.get("x") as? Number)?.toInt() ?: 0, (point?.get("y") as? Number)?.toInt() ?: 0)
+                    } ?: emptyList()
+                // Open strokes carry their width as `width`; closed shapes and boxes as `border`.
+                val border =
+                    (style?.get("border") as? Number)?.toInt() ?: (style?.get("width") as? Number)?.toInt() ?: 0
                 SceneElement(
                     id = el["id"] as? String ?: return@mapNotNull null,
                     type = el["type"] as? String ?: return@mapNotNull null,
@@ -1712,12 +1721,19 @@ class DeviceManager {
                     h = (box["h"] as? Number)?.toInt() ?: 0,
                     text = (el["text"] as? String)?.let { parsePlaceholders(it) },
                     data = el["data"] as? String,
-                    border = (style?.get("border") as? Number)?.toInt() ?: 0,
+                    border = border,
                     radius = (style?.get("radius") as? Number)?.toInt() ?: 0,
                     change = el["change"] as? String ?: "created",
                     contentHash = el["contentHash"] as? String ?: "",
                     font = style?.get("font") as? String ?: "default",
                     fontSize = (style?.get("fontSize") as? Number)?.toInt() ?: 0,
+                    fill = style?.get("fill") as? Boolean ?: false,
+                    color = (style?.get("color") as? Number)?.toInt() ?: -1,
+                    points = points,
+                    startDeg = (el["startDeg"] as? Number)?.toInt() ?: 0,
+                    endDeg = (el["endDeg"] as? Number)?.toInt() ?: 0,
+                    transitionMs = (transition?.get("durationMs") as? Number)?.toInt() ?: 0,
+                    easing = transition?.get("easing") as? String ?: "ease",
                 )
             }
         val canvas = sceneMap["canvas"] as? Map<String, Any>

package/android/src/main/java/com/glassly/bluetoothsdk/GeneratedReleaseMetadata.kt

@@ -3,9 +3,9 @@ package com.glassly.bluetoothsdk
 /** Generated by release CI. Do not edit in a release checkout. */
 internal object GeneratedReleaseMetadata {
     const val FAMILY_BASE_VERSION: String = "0.1.0"
-    const val RELEASE_IDENTITY: String = "0.1.0-dev.105"
-    const val RELEASE_SET_ID: String = "glassly-0.1.0-dev.105"
-    const val SOURCE_COMMIT: String = "efce299cebb9bd86929450ade940c2a26386ea7e"
+    const val RELEASE_IDENTITY: String = "0.1.0-dev.106"
+    const val RELEASE_SET_ID: String = "glassly-0.1.0-dev.106"
+    const val SOURCE_COMMIT: String = "a98050b8f0c6d44cef52b09ebb187f6bf49edaf4"
     const val OTA_MANIFEST_URL: String = ""
     const val OTA_MANIFEST_SHA256: String = ""
 }

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

@@ -1476,7 +1476,7 @@ class G2 : SGCManager() {
      * fulls/deltas. SEED (mode-6 black) and MOVE_BUNDLE (blank of an old
      * window position) always survive.
      */
-    private enum class CfwPayloadKind { SEED, FULL, DELTA, MOVE_BUNDLE, UPLOAD }
+    private enum class CfwPayloadKind { SEED, FULL, DELTA, MOVE_BUNDLE, UPLOAD, SCENE }
 
     private class CfwPayload(val kind: CfwPayloadKind, val data: ByteArray)
 
@@ -1572,6 +1572,15 @@ class G2 : SGCManager() {
     private val supportsCfwTextureImages: Boolean
         get() = "texcache12" in cfwFeatures && "teximg13" in cfwFeatures
 
+    /** Retained vector scene with on-glass animation (modes 16-18). */
+    private val supportsCfwVectorScene: Boolean
+        get() =
+            supportsCfwSceneRendering &&
+                listOf("scene17", "shapes16", "anim18", "texcache12", "teximg13", "font15").all { it in cfwFeatures }
+
+    /** The on-glass slot table must be re-SET on the next vector frame. */
+    private var cfwSceneInvalid = true
+
     // BLE
     private val context: Context
         get() = Bridge.getContext()
@@ -2938,6 +2947,7 @@ class G2 : SGCManager() {
 
     private fun cfwResetShadow() {
         cfwPendingPayloads.clear()
+        cfwSceneInvalid = true
         cfwShadowSeeded = false
         cfwLastBoxes = null
         cfwPrevRaster = null
@@ -3080,7 +3090,43 @@ class G2 : SGCManager() {
      * change is large, the queue backed up, or on the periodic insurance
      * keyframe. Seeds the shadow with mode-6 black when it is fresh.
      */
+    /**
+     * Queue [frame] as a retained-scene patch: the firmware keeps the slots,
+     * tweens transitions itself, and renders every frame into its own buffer.
+     * Returns false when the frame does not fit, so the raster path takes it.
+     */
+    private suspend fun enqueueCfwVectorFrame(frame: SceneFrame): Boolean {
+        val boxes = cfwBoxes(frame, pinDepth = true)
+        val backlogged = cfwPendingPayloads.count { it.kind == CfwPayloadKind.SCENE } >= CFW_MAX_QUEUED_UPDATES
+        if (backlogged) {
+            cfwPendingPayloads.removeAll { it.kind == CfwPayloadKind.SCENE }
+            cfwSceneInvalid = true
+        }
+        if (cfwLastBoxes != boxes) cfwSceneInvalid = true
+        val invalidate = cfwSceneInvalid
+        val encoded =
+            kotlinx.coroutines.withContext(Dispatchers.Default) {
+                G2CfwRenderer.encodeVector(frame, boxes, cfwCacheGeneration, invalidate)
+            }
+        if (encoded == null) {
+            Bridge.log("G2: vector scene does not fit; using the raster path for this frame")
+            cfwSceneInvalid = true
+            return false
+        }
+        cfwSceneInvalid = false
+        cfwLastBoxes = boxes
+        // A later raster frame must start from a keyframe: the panel shows the scene, not the shadow.
+        cfwDeltasSinceFull = CFW_MAX_DELTAS_BETWEEN_FULL_FRAMES
+        for (upload in encoded.uploads) {
+            cfwPendingPayloads.addLast(CfwPayload(CfwPayloadKind.UPLOAD, upload))
+        }
+        cfwPendingPayloads.addLast(CfwPayload(CfwPayloadKind.SCENE, encoded.payload))
+        cfwLastPayloadQueuedAt = System.currentTimeMillis()
+        return true
+    }
+
     private suspend fun enqueueCfwFrame(frame: SceneFrame): Boolean {
+        if (supportsCfwVectorScene && enqueueCfwVectorFrame(frame)) return true
         val useBuiltinText =
             supportsCfwBuiltinText && frame.elements.any { it.type == "text" && it.font == "builtin" }
         // Modes 13/14 have no per-lens variant, so they need the lens-equal window.
@@ -3179,7 +3225,8 @@ class G2 : SGCManager() {
                 cfwShadowSeeded = true
                 if (textDraws.isEmpty()) {
                     cfwPendingPayloads.removeAll {
-                        it.kind == CfwPayloadKind.FULL || it.kind == CfwPayloadKind.DELTA
+                        it.kind == CfwPayloadKind.FULL || it.kind == CfwPayloadKind.DELTA ||
+                            it.kind == CfwPayloadKind.SCENE
                     }
                     cfwLastPayloadQueuedAt = System.currentTimeMillis()
                     return true
@@ -3193,7 +3240,9 @@ class G2 : SGCManager() {
         }
         if (update.usedFullFrame) {
             // A full overwrites the window; seeds, uploads, and move-blanks must still survive.
-            cfwPendingPayloads.removeAll { it.kind == CfwPayloadKind.FULL || it.kind == CfwPayloadKind.DELTA }
+            cfwPendingPayloads.removeAll {
+                it.kind == CfwPayloadKind.FULL || it.kind == CfwPayloadKind.DELTA || it.kind == CfwPayloadKind.SCENE
+            }
             val kind = if (movedBoxes) CfwPayloadKind.MOVE_BUNDLE else CfwPayloadKind.FULL
             cfwPendingPayloads.addLast(CfwPayload(kind, payload))
         } else {
@@ -6368,6 +6417,20 @@ class G2 : SGCManager() {
             cfwFeatures.clear()
             cfwProtocolVersion = 0
         }
+        publishSceneCanvas()
+    }
+
+    /**
+     * Publish the CFW scene canvas and vector-scene support into the glasses
+     * status once classification lands; zeros/false on stock so a stale value
+     * cannot survive a CFW→stock swap.
+     */
+    private fun publishSceneCanvas() {
+        if (!cfwClassified) return
+        val active = supportsCfwSceneRendering
+        DeviceStore.apply("glasses", "sceneCanvasWidth", if (active) 576 else 0)
+        DeviceStore.apply("glasses", "sceneCanvasHeight", if (active) 288 else 0)
+        DeviceStore.apply("glasses", "sceneVector", active && supportsCfwVectorScene)
     }
 
     /**

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

@@ -74,6 +74,41 @@ internal object G2CfwRenderer {
      * glyph raster memo survives resets — rasters don't change.
      */
     private val textureCache = G2CfwTextureCache()
+    /** Retained vector scene (modes 16-18); shares the texture cache with the raster path. */
+    private val scene = G2CfwScene()
+
+    /**
+     * Encode [frame] as a retained-scene patch (plus its mode-12 uploads).
+     * [invalidate] forces a full re-SET (the on-glass slot table is unknown).
+     * Null when the frame does not fit the slot table or the texture cache.
+     */
+    fun encodeVector(
+        frame: SceneFrame,
+        boxes: LensBoxes,
+        cacheGeneration: Int,
+        invalidate: Boolean,
+    ): G2CfwScene.Encoded? {
+        if (textureCache.generation != cacheGeneration || textureCache.exhausted) {
+            textureCache.reset(cacheGeneration)
+        }
+        if (scene.generation != textureCache.generation) {
+            scene.reset(textureCache.generation)
+        } else if (invalidate) {
+            scene.invalidate()
+        }
+        val rasterizeOne: (SceneElement, Int, Int) -> ByteArray? = { element, w, h ->
+            rasterize(
+                SceneFrame(frame.appId, frame.epoch, false, listOf(element.atOrigin()), emptyList(), w, h),
+                w,
+                h,
+            )
+        }
+        scene.encode(frame, boxes.leftX, boxes.leftY, textureCache, rasterizeOne)?.let { return it }
+        // Out of texture cache mid-frame: start a fresh cache and repack once.
+        textureCache.reset(cacheGeneration)
+        scene.reset(cacheGeneration)
+        return scene.encode(frame, boxes.leftX, boxes.leftY, textureCache, rasterizeOne)
+    }
     private val glyphRasterMemo = mutableMapOf<String, ByteArray>()
 
     private fun monoPaint(fontSize: Float): Paint =

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

@@ -0,0 +1,415 @@
+package com.glassly.bluetoothsdk.sgcs
+
+import java.io.ByteArrayOutputStream
+
+/**
+ * Retained vector scene for the Glassly CFW (firmware modes 16-18).
+ *
+ * Every scene element becomes one or more firmware slots (paint order = slot
+ * order): vector shapes map 1:1, builtin-font text becomes one TEXT slot per
+ * line with its bytes in the texture cache, and everything else (proportional
+ * text, images) is rasterized on the phone and drawn as cached IMAGE slots
+ * tiled to the 255 px slot limit. Frames diff against the last committed
+ * layout: unchanged slots cost nothing, geometry changes on an element with a
+ * transition become firmware TWEENs, and anything else is re-SET. Slot indices
+ * stay stable per element id; a reorder or an over-budget frame repacks.
+ */
+internal class G2CfwScene {
+    companion object {
+        const val MAX_SLOTS = 128
+        const val RECORD_BYTES = 20
+        const val FRAME_PERIOD_MS = 33.0
+        const val TEXT_LINE_HEIGHT = 27
+        const val MAX_TEXT_BYTES = 64
+        const val MAX_TILE_SIZE = 255
+        /** Mode-13/15 options: identity ramp, transparent source color 0. */
+        const val TEXT_OPTIONS = 0x1F
+        const val IMAGE_OPTIONS = 0x0F
+
+        const val TYPE_LINE = 1
+        const val TYPE_RECT = 2
+        const val TYPE_RECT_FILL = 3
+        const val TYPE_CIRCLE = 4
+        const val TYPE_CIRCLE_FILL = 5
+        const val TYPE_TRI = 6
+        const val TYPE_TRI_FILL = 7
+        const val TYPE_QUAD = 8
+        const val TYPE_QUAD_FILL = 9
+        const val TYPE_BEZIER2 = 10
+        const val TYPE_BEZIER3 = 11
+        const val TYPE_ARC = 12
+        const val TYPE_PIE = 13
+        const val TYPE_IMAGE = 14
+        const val TYPE_TEXT = 15
+        const val TYPE_TEXT_CACHED = 16
+
+        /** Geometry parameters a TWEEN may interpolate, per type. Texture offsets and lengths never tween. */
+        fun tweenableMask(type: Int): Int =
+            when (type) {
+                TYPE_LINE -> 0x0F
+                TYPE_RECT, TYPE_RECT_FILL, TYPE_ARC, TYPE_PIE -> 0x1F
+                TYPE_CIRCLE, TYPE_CIRCLE_FILL -> 0x07
+                TYPE_TRI, TYPE_TRI_FILL, TYPE_BEZIER2 -> 0x3F
+                TYPE_QUAD, TYPE_QUAD_FILL, TYPE_BEZIER3 -> 0xFF
+                TYPE_IMAGE, TYPE_TEXT, TYPE_TEXT_CACHED -> 0x03
+                else -> 0
+            }
+
+        fun easingCurve(easing: String): IntArray =
+            when (easing) {
+                "linear" -> intArrayOf(0, 0, 255, 255)
+                "ease-in" -> intArrayOf(107, 0, 255, 255)
+                "ease-out" -> intArrayOf(0, 0, 148, 255)
+                "ease-in-out" -> intArrayOf(107, 0, 148, 255)
+                else -> intArrayOf(64, 26, 64, 255) // CSS "ease"
+            }
+
+        fun transitionFrames(ms: Int): Int {
+            if (ms <= 0) return 0
+            val frames = Math.round(ms / FRAME_PERIOD_MS).toInt()
+            return frames.coerceIn(2, 255)
+        }
+
+        /** UTF-8 bytes of a line without firmware control bytes (1..31), cut at a codepoint boundary. */
+        fun textBytes(line: String): ByteArray {
+            val out = ByteArrayOutputStream()
+            var i = 0
+            while (i < line.length) {
+                val cp = line.codePointAt(i)
+                i += Character.charCount(cp)
+                if (cp < 32) continue
+                val encoded = String(Character.toChars(cp)).toByteArray(Charsets.UTF_8)
+                if (out.size() + encoded.size > MAX_TEXT_BYTES) break
+                out.write(encoded)
+            }
+            return out.toByteArray()
+        }
+
+        private fun clampCoord(v: Int): Int = v.coerceIn(-1024, 1023)
+
+        private fun gray(element: SceneElement): Int = if (element.color < 0) 15 else element.color.coerceIn(0, 15)
+
+        private fun stroke(element: SceneElement): Int = element.border.coerceIn(1, 255)
+
+        private fun le(out: ByteArrayOutputStream, value: Int) {
+            out.write(value and 0xFF)
+            out.write((value ushr 8) and 0xFF)
+        }
+
+        /** `[0][slot][type][flags=visible][color][width][p0..p7 LE]` */
+        fun setRecord(slot: Slot, index: Int): ByteArray {
+            val out = ByteArrayOutputStream()
+            out.write(0)
+            out.write(index)
+            out.write(slot.type)
+            out.write(1)
+            out.write(slot.color)
+            out.write(slot.width)
+            for (value in slot.params) le(out, value)
+            return out.toByteArray()
+        }
+
+        /**
+         * `[5][slot][mask:u16][frames][curve x4][value:i16 per set bit]`, or null when the
+         * change is not a pure geometry/stroke change of the same shape type.
+         */
+        fun tweenRecord(old: Slot, new: Slot, index: Int, frames: Int, curve: IntArray): ByteArray? {
+            if (old.type != new.type) return null
+            val tweenable = tweenableMask(new.type)
+            var mask = 0
+            val values = mutableListOf<Int>()
+            for (k in 0 until 8) {
+                if (old.params[k] == new.params[k]) continue
+                if (tweenable and (1 shl k) == 0) return null
+                mask = mask or (1 shl k)
+                values.add(new.params[k])
+            }
+            val isTexture = new.type >= TYPE_IMAGE
+            if (old.color != new.color) {
+                if (isTexture) return null
+                mask = mask or 0x100
+                values.add(new.color)
+            }
+            if (old.width != new.width) {
+                if (isTexture) return null
+                mask = mask or 0x200
+                values.add(new.width)
+            }
+            if (mask == 0) return null
+            val out = ByteArrayOutputStream()
+            out.write(5)
+            out.write(index)
+            le(out, mask)
+            out.write(frames)
+            for (i in 0 until 4) out.write(curve[i])
+            for (value in values) le(out, value)
+            return out.toByteArray()
+        }
+    }
+
+    /** One firmware slot: type, 4-bit color (or options byte), stroke width, eight int16 parameters. */
+    class Slot(val type: Int, val color: Int, val width: Int, params: List<Int>) {
+        val params: IntArray = IntArray(8) { params.getOrElse(it) { 0 } }
+
+        override fun equals(other: Any?): Boolean =
+            other is Slot && other.type == type && other.color == color && other.width == width &&
+                other.params.contentEquals(params)
+
+        override fun hashCode(): Int = ((type * 31 + color) * 31 + width) * 31 + params.contentHashCode()
+    }
+
+    class ElementState(val id: String, val contentHash: String, val slots: List<Slot>, val indices: List<Int>)
+
+    class Encoded(val payload: ByteArray, val uploads: List<ByteArray>)
+
+    var generation = -1
+        private set
+    var elements: List<ElementState> = emptyList()
+        private set
+    private var needsRepack = true
+
+    fun reset(generation: Int) {
+        this.generation = generation
+        elements = emptyList()
+        needsRepack = true
+    }
+
+    /** The on-glass slot table is unknown (a send failed, the window moved): the next frame re-SETs everything. */
+    fun invalidate() {
+        needsRepack = true
+    }
+
+    private fun point(element: SceneElement, i: Int, ox: Int, oy: Int): Pair<Int, Int> {
+        if (element.points.size < 2 * i + 2) return 0 to 0
+        return clampCoord(element.points[2 * i] + ox) to clampCoord(element.points[2 * i + 1] + oy)
+    }
+
+    private fun circleGeometry(element: SceneElement, ox: Int, oy: Int): Triple<Int, Int, Int> {
+        val r = maxOf(0, (minOf(element.w, element.h) - 1) / 2)
+        return Triple(clampCoord(element.x + element.w / 2 + ox), clampCoord(element.y + element.h / 2 + oy), r)
+    }
+
+    /** Slots for one element, or null when the texture cache cannot hold its content. */
+    fun slotsFor(
+        element: SceneElement,
+        ox: Int,
+        oy: Int,
+        cache: G2CfwTextureCache,
+        rasterize: (SceneElement, Int, Int) -> ByteArray?,
+    ): List<Slot>? {
+        val x = clampCoord(element.x + ox)
+        val y = clampCoord(element.y + oy)
+        val w = element.w.coerceIn(0, 2047)
+        val h = element.h.coerceIn(0, 2047)
+        val color = gray(element)
+        val radius = element.radius.coerceIn(0, 2047)
+        return when (element.type) {
+            "rect" -> {
+                val out = mutableListOf<Slot>()
+                if (element.fill) {
+                    out.add(Slot(TYPE_RECT_FILL, color, 0, listOf(x, y, w, h, radius)))
+                    if (element.border > 0) out.add(Slot(TYPE_RECT, color, stroke(element), listOf(x, y, w, h, radius)))
+                } else {
+                    out.add(Slot(TYPE_RECT, color, stroke(element), listOf(x, y, w, h, radius)))
+                }
+                out
+            }
+            "circle" -> {
+                val (cx, cy, r) = circleGeometry(element, ox, oy)
+                if (element.fill) listOf(Slot(TYPE_CIRCLE_FILL, color, 0, listOf(cx, cy, r)))
+                else listOf(Slot(TYPE_CIRCLE, color, stroke(element), listOf(cx, cy, r)))
+            }
+            "arc", "pie" -> {
+                val (cx, cy, r) = circleGeometry(element, ox, oy)
+                val a0 = clampCoord(element.startDeg)
+                val a1 = clampCoord(element.endDeg)
+                if (element.type == "pie") listOf(Slot(TYPE_PIE, color, 0, listOf(cx, cy, r, a0, a1)))
+                else listOf(Slot(TYPE_ARC, color, stroke(element), listOf(cx, cy, r, a0, a1)))
+            }
+            "line" -> {
+                val (x1, y1) = point(element, 0, ox, oy)
+                val (x2, y2) = point(element, 1, ox, oy)
+                listOf(Slot(TYPE_LINE, color, stroke(element), listOf(x1, y1, x2, y2)))
+            }
+            "triangle", "quad" -> {
+                val n = if (element.type == "triangle") 3 else 4
+                val params = (0 until n).flatMap { point(element, it, ox, oy).toList() }
+                val filled = if (n == 3) TYPE_TRI_FILL else TYPE_QUAD_FILL
+                val stroked = if (n == 3) TYPE_TRI else TYPE_QUAD
+                if (element.fill) listOf(Slot(filled, color, 0, params))
+                else listOf(Slot(stroked, color, stroke(element), params))
+            }
+            "bezier" -> {
+                val n = element.points.size / 2
+                if (n != 3 && n != 4) return emptyList()
+                val params = (0 until n).flatMap { point(element, it, ox, oy).toList() }
+                listOf(Slot(if (n == 3) TYPE_BEZIER2 else TYPE_BEZIER3, color, stroke(element), params))
+            }
+            "text" -> if (element.font == "builtin") builtinTextSlots(element, x, y, cache)
+                      else rasterSlots(element, x, y, cache, rasterize)
+            "image" -> rasterSlots(element, x, y, cache, rasterize)
+            else -> emptyList()
+        }
+    }
+
+    private fun builtinTextSlots(element: SceneElement, x: Int, y: Int, cache: G2CfwTextureCache): List<Slot>? {
+        val out = mutableListOf<Slot>()
+        if (element.border > 0) {
+            out.add(
+                Slot(
+                    TYPE_RECT, 15, stroke(element),
+                    listOf(x, y, element.w.coerceIn(0, 2047), element.h.coerceIn(0, 2047), element.radius.coerceIn(0, 2047)),
+                ),
+            )
+        }
+        val maxLines = maxOf(1, element.h / TEXT_LINE_HEIGHT)
+        val lines = (element.text ?: "").split("\n").take(maxLines)
+        for ((index, line) in lines.withIndex()) {
+            val bytes = textBytes(line)
+            if (bytes.isEmpty()) continue
+            val offset = cache.ensureBytes("t:$line", bytes) ?: return null
+            out.add(Slot(TYPE_TEXT, TEXT_OPTIONS, 0, listOf(x, clampCoord(y + index * TEXT_LINE_HEIGHT), offset, bytes.size)))
+        }
+        return out
+    }
+
+    private fun rasterSlots(
+        element: SceneElement,
+        x: Int,
+        y: Int,
+        cache: G2CfwTextureCache,
+        rasterize: (SceneElement, Int, Int) -> ByteArray?,
+    ): List<Slot>? {
+        val w = element.w
+        val h = element.h
+        if (w <= 0 || h <= 0) return emptyList()
+        val gray = rasterize(element, w, h)?.takeIf { it.size == w * h } ?: return emptyList()
+        val out = mutableListOf<Slot>()
+        var ty = 0
+        while (ty < h) {
+            val th = minOf(MAX_TILE_SIZE, h - ty)
+            var tx = 0
+            while (tx < w) {
+                val tw = minOf(MAX_TILE_SIZE, w - tx)
+                val tile = ByteArray(tw * th)
+                for (row in 0 until th) {
+                    System.arraycopy(gray, (ty + row) * w + tx, tile, row * tw, tw)
+                }
+                val key = "${element.contentHash}@${w}x$h:$tx,$ty"
+                val offset = cache.ensureImage(key, tile, tw, th) ?: return null
+                out.add(Slot(TYPE_IMAGE, IMAGE_OPTIONS, 0, listOf(clampCoord(x + tx), clampCoord(y + ty), offset)))
+                tx += tw
+            }
+            ty += th
+        }
+        return out
+    }
+
+    private class Desired(
+        val id: String,
+        val contentHash: String,
+        val slots: List<Slot>,
+        val frames: Int,
+        val curve: IntArray,
+    )
+
+    /**
+     * One mode-17 patch (COMMIT, plus CLEAR on a repack) and the mode-12 uploads
+     * that must precede it. Null when the frame does not fit the slot table or
+     * the texture cache; the caller then falls back to the raster path.
+     */
+    fun encode(
+        frame: SceneFrame,
+        originX: Int,
+        originY: Int,
+        cache: G2CfwTextureCache,
+        rasterize: (SceneElement, Int, Int) -> ByteArray?,
+    ): Encoded? {
+        val desired = mutableListOf<Desired>()
+        for (element in frame.elements) {
+            val slots = slotsFor(element, originX, originY, cache, rasterize) ?: return null
+            desired.add(
+                Desired(element.id, element.contentHash, slots, transitionFrames(element.transitionMs), easingCurve(element.easing)),
+            )
+        }
+        if (desired.sumOf { it.slots.size } > MAX_SLOTS) return null
+
+        val previous = elements.associateBy { it.id }
+        var repack = needsRepack || frame.replay
+        val assigned = mutableListOf<List<Int>>()
+        if (!repack) {
+            val used = mutableSetOf<Int>()
+            for (item in desired) {
+                previous[item.id]?.takeIf { it.slots.size == item.slots.size }?.let { used.addAll(it.indices) }
+            }
+            var next = (used.maxOrNull() ?: -1) + 1
+            var lastIndex = -1
+            for (item in desired) {
+                val prev = previous[item.id]
+                val indices =
+                    if (prev != null && prev.slots.size == item.slots.size) {
+                        prev.indices
+                    } else {
+                        List(item.slots.size) { next + it }.also { next += item.slots.size }
+                    }
+                val first = indices.firstOrNull()
+                if (first != null && first <= lastIndex) {
+                    repack = true
+                    break
+                }
+                indices.lastOrNull()?.let { lastIndex = it }
+                assigned.add(indices)
+            }
+            if (next > MAX_SLOTS) repack = true
+        }
+        if (repack) {
+            assigned.clear()
+            var next = 0
+            for (item in desired) {
+                assigned.add(List(item.slots.size) { next + it })
+                next += item.slots.size
+            }
+        }
+
+        val ops = ByteArrayOutputStream()
+        if (!repack) {
+            val kept = desired.mapTo(HashSet()) { it.id }
+            for (state in elements) {
+                if (state.id in kept) continue
+                for (index in state.indices) {
+                    ops.write(1)
+                    ops.write(index)
+                }
+            }
+        }
+        val committed = mutableListOf<ElementState>()
+        for ((item, indices) in desired.zip(assigned)) {
+            val prev = if (repack) null else previous[item.id]
+            for ((k, slot) in item.slots.withIndex()) {
+                val index = indices[k]
+                if (prev != null && prev.slots.size == item.slots.size) {
+                    val old = prev.slots[k]
+                    if (old == slot) continue
+                    if (item.frames >= 2) {
+                        val tween = tweenRecord(old, slot, index, item.frames, item.curve)
+                        if (tween != null) {
+                            ops.write(tween)
+                            continue
+                        }
+                    }
+                }
+                ops.write(setRecord(slot, index))
+            }
+            committed.add(ElementState(item.id, item.contentHash, item.slots, indices))
+        }
+
+        val payload = ByteArrayOutputStream()
+        payload.write(17)
+        payload.write(if (repack) 0x03 else 0x01)
+        payload.write(0)
+        payload.write(ops.toByteArray())
+        elements = committed
+        needsRepack = false
+        return Encoded(payload.toByteArray(), cache.takeUploadPayloads())
+    }
+}

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

@@ -227,6 +227,16 @@ internal class G2CfwTextureCache {
      * The cache offset of an image, uploading it on first residency.
      * `gray` is the width×height 8-bit grayscale raster.
      */
+    /** The cache offset of a raw byte string (builtin-font text for scene TEXT slots), uploading it on first use. */
+    fun ensureBytes(key: String, bytes: ByteArray): Int? {
+        images[key]?.let { return it }
+        if (bytes.isEmpty()) return null
+        val offset = allocate(bytes.size) ?: return null
+        images[key] = offset
+        pendingUploads.add(offset to bytes)
+        return offset
+    }
+
     fun ensureImage(hash: String, gray: ByteArray, width: Int, height: Int): Int? {
         images[hash]?.let { return it }
         if (width !in 1..255 || height !in 1..255 || gray.size != width * height) return null

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

@@ -50,8 +50,8 @@ internal object G2FirmwareCatalog {
                 displayName = "Glassly CFW",
                 version = "2.2.9.22 CFW",
                 fileName = "g2-glassly-cfw-2.2.9.22.evenota.bin",
-                sha256 = "ceeede999529505ebc0a1369f57ab3c941273379a90b16669ccd39cc6bd99135",
-                size = 4_515_846,
+                sha256 = "fe6051085507269c8007bc1245bfe8bd10d5c566540389ae976daaf753f536f9",
+                size = 4_527_476,
             ),
         )