@glassly/bluetooth-sdk 0.1.0-dev.99 → 0.2.8-dev.444

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

@@ -0,0 +1,673 @@
+package com.glassly.bluetoothsdk.sgcs
+
+import com.glassly.bluetoothsdk.sgcs.G2CfwTextureCache.Companion.writeI16
+import com.glassly.bluetoothsdk.sgcs.G2CfwTextureCache.Companion.writeU32
+import java.io.ByteArrayOutputStream
+
+/**
+ * Retained object cache encoder for the Glassly CFW (GLASSLYCFW/38, modes 37-41).
+ *
+ * Every scene element becomes one or more OBJECTS with stable 32-bit ids
+ * (derived from the element id and the object's position within the element):
+ * vector shapes map 1:1; default and builtin text becomes one inline TEXT
+ * object per line drawn by the glasses' font; mono text becomes TEXT_CACHED
+ * runs drawn with a font asset (uploaded whole, once per cache generation);
+ * images are rasterized on the phone and drawn as IMAGE objects tiled to the
+ * 255 px limit, keyed by their pixels so identical images share one asset.
+ *
+ * A frame is one SHOW: the ordered (id, version) references of what is on
+ * screen, the embedded PUTs for objects the glasses do not hold yet (new, or
+ * changed content: a version is a hash of the record), and TWEEN/ROTATE ops for
+ * animated changes of geometry the glasses already hold. Objects that leave a
+ * frame stay cached on the glasses (and in this mirror) until the firmware
+ * evicts them least-recently-used, so a view coming back after a HIDE is pure
+ * references. The firmware validates every reference; a MISSING reply names
+ * what to redefine ([forget]).
+ *
+ * One instance mirrors one lens. Element depth is a stereo disparity: a lens
+ * mirror encoding with parallax ±1 shifts each element by depth × parallax px,
+ * so the renderer keeps a left and a right mirror once a frame uses depth and
+ * sends each lens its own SHOW ([G2CfwRenderer]).
+ */
+internal class G2CfwScene {
+
+    companion object {
+        const val MAX_OBJECTS = 256
+        const val FRAME_PERIOD_MS = 33.0
+        const val TEXT_LINE_HEIGHT = 27
+        const val TEXT_INSET = 2
+        const val MAX_TEXT_BYTES = 64
+        const val MAX_INLINE_BYTES = 128
+        const val MAX_TILE_SIZE = 255
+        /** Mode-15/20 options: identity ramp, transparent source color 0. */
+        const val TEXT_OPTIONS = 0x1F
+        const val IMAGE_OPTIONS = 0x0F
+        const val ALL_OBJECTS = -1
+
+        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
+        const val TYPE_TEXT_INLINE = 17
+        const val TYPE_PATH = 18
+
+        /** Wire codes of the half-block grid font (mode 20 indexes a font by byte, so glyphs need not be ASCII). */
+        val BLOCK_CODES: Map<Int, Int> = mapOf(32 to 32, 0x2580 to 65, 0x2584 to 66, 0x2588 to 67)
+
+        /** The warm-up dot: a hidden two-frame tween sent once per cache generation right after the RESET. */
+        val WARM_UP_ID: Int = G2CfwTextureCache.hash31("warm-up")
+        val WARM_UP_SHOW: ByteArray by lazy {
+            val dot = Slot(TYPE_CIRCLE_FILL, 0, 0, listOf(0, 0, 1))
+            showPayload(
+                puts = listOf(putObject(WARM_UP_ID, 1, objectRecord(dot))),
+                refs = listOf(WARM_UP_ID to 1),
+                ops = listOf(tweenOp(WARM_UP_ID, 0x01, 2, intArrayOf(0, 0, 255, 255), listOf(1))),
+                request = 0,
+            )
+        }
+        /** Mode 39: freeze, blank and keep everything cached. */
+        val HIDE_PAYLOAD: ByteArray = byteArrayOf(39, 0, 0, 0, 0, 0x01, 0)
+        /** Mode 41 sub 0: empty both caches and adopt the epoch the link stamps in. */
+        val RESET_PAYLOAD: ByteArray = byteArrayOf(41, 0, 0, 0, 0, 0)
+
+        /** Geometry parameters a TWEEN may interpolate, per type. Asset ids never tween. */
+        fun tweenableMask(type: Int): Int =
+            when (type) {
+                TYPE_PATH -> 0x07
+                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
+                TYPE_TEXT_INLINE -> 0x0F
+                else -> 0
+            }
+
+        /** FNV-1a 64 of a tile's pixels: the asset key, so identical pixels share one upload. */
+        fun pixelHash(pixels: ByteArray): String {
+            var hash = -0x340d631b7bdddcdbL // 0xcbf29ce484222325
+            for (byte in pixels) {
+                hash = hash xor (byte.toLong() and 0xFF)
+                hash *= 0x100000001b3L
+            }
+            return java.lang.Long.toUnsignedString(hash, 36)
+        }
+
+        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, limit: Int = MAX_TEXT_BYTES): 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 > limit) break
+                out.write(encoded)
+            }
+            return out.toByteArray()
+        }
+
+        /** Object id of the k-th slot of an element: stable across frames and reopenings. */
+        fun objectId(elementId: String, k: Int): Int = G2CfwTextureCache.hash31("$elementId#$k")
+
+        /** Content version of a slot: a hash of the record the glasses store. */
+        fun versionOf(slot: Slot): Int = G2CfwTextureCache.hash31(objectRecord(slot))
+
+        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)
+
+        /** The shape record the object cache stores for a slot (shapes.h layouts). */
+        fun objectRecord(slot: Slot): ByteArray {
+            val out = ByteArrayOutputStream()
+            when (slot.type) {
+                TYPE_PATH -> {
+                    out.write(slot.type); out.write(1); out.write(slot.color); out.write(slot.fillRule)
+                    for (k in 0..2) out.writeI16(slot.params[k])
+                    out.write(slot.path.size and 0xFF); out.write((slot.path.size ushr 8) and 0xFF)
+                    out.write(slot.path)
+                }
+                TYPE_TEXT_INLINE -> {
+                    out.write(slot.type); out.write(1); out.write(slot.color); out.write(0)
+                    for (k in 0..3) out.writeI16(slot.params[k])
+                    val bytes = slot.text.take(MAX_INLINE_BYTES).toByteArray()
+                    out.write(bytes.size); out.write(bytes)
+                }
+                TYPE_IMAGE, TYPE_TEXT, TYPE_TEXT_CACHED -> {
+                    out.write(slot.type); out.write(1); out.write(slot.color); out.write(0)
+                    for (k in 0..1) out.writeI16(slot.params[k])
+                    out.writeU32(slot.asset)
+                    if (slot.type == TYPE_TEXT_CACHED) out.writeU32(slot.font)
+                }
+                else -> {
+                    out.write(slot.type); out.write(1); out.write(slot.color); out.write(slot.width)
+                    for (k in 0 until 8) out.writeI16(slot.params[k])
+                }
+            }
+            return out.toByteArray()
+        }
+
+        /** `[1][id:u32][version:u32][record]` */
+        fun putObject(id: Int, version: Int, record: ByteArray): ByteArray {
+            val out = ByteArrayOutputStream()
+            out.write(1); out.writeU32(id); out.writeU32(version); out.write(record)
+            return out.toByteArray()
+        }
+
+        /** `[38][epoch 0][request][flags][bg][puts][put entries][count:u16][(id, version) x count][ops]` */
+        fun showPayload(puts: List<ByteArray>, refs: List<Pair<Int, Int>>, ops: List<ByteArray>, request: Int, tag: Boolean = false, bg: Int = 0): ByteArray {
+            val out = ByteArrayOutputStream()
+            out.write(38); out.write(0); out.write(0)
+            out.write(request and 0xFF); out.write((request ushr 8) and 0xFF)
+            out.write(if (tag) 0x05 else 0x01); out.write(bg and 0x0F); out.write(minOf(255, puts.size))
+            for (put in puts) out.write(put)
+            out.write(refs.size and 0xFF); out.write((refs.size ushr 8) and 0xFF)
+            for ((id, version) in refs) { out.writeU32(id); out.writeU32(version) }
+            for (op in ops) out.write(op)
+            return out.toByteArray()
+        }
+
+        /** `[9][id:u32][angle:i32][pivotX:i16][pivotY:i16][durationMs:u16][curve x4]` */
+        fun rotationOp(slot: Slot, id: Int, duration: Int, curve: IntArray): ByteArray {
+            if (!slot.rotatable) return ByteArray(0)
+            val out = ByteArrayOutputStream()
+            out.write(9); out.writeU32(id); out.writeU32(slot.angle)
+            out.writeI16(slot.pivotX); out.writeI16(slot.pivotY)
+            val ms = duration.coerceIn(0, 65535)
+            out.write(ms and 0xFF); out.write((ms ushr 8) and 0xFF)
+            for (i in 0..3) out.write(curve[i])
+            return out.toByteArray()
+        }
+
+        /** `[5][id:u32][mask:u16][frames][curve x4][value:i16 per set bit]` */
+        fun tweenOp(id: Int, mask: Int, frames: Int, curve: IntArray, values: List<Int>): ByteArray {
+            val out = ByteArrayOutputStream()
+            out.write(5); out.writeU32(id)
+            out.write(mask and 0xFF); out.write((mask ushr 8) and 0xFF); out.write(frames.coerceIn(0, 255))
+            for (i in 0..3) out.write(curve[i])
+            for (value in values) out.writeI16(value)
+            return out.toByteArray()
+        }
+
+        /**
+         * A TWEEN from `old` (what the glasses show) to `new`, or null when the change
+         * is not a pure geometry/stroke change of the same shape type. The mask covers
+         * every tweenable parameter (plus color and width where the type allows), not
+         * only the ones that changed: the firmware takes an unmasked parameter's end
+         * value from the object's CURRENT value, which is mid-flight while an earlier
+         * tween is still running.
+         */
+        fun tweenOp(old: Slot, new: Slot, id: Int, frames: Int, curve: IntArray): ByteArray? {
+            if (old.type != new.type || !old.text.contentEquals(new.text) || !old.path.contentEquals(new.path) ||
+                old.fillRule != new.fillRule || old.asset != new.asset || old.font != new.font
+            ) return null
+            val tweenable = tweenableMask(new.type)
+            for (k in 0 until 8) {
+                if (old.params[k] != new.params[k] && tweenable and (1 shl k) == 0) return null
+            }
+            val isTexture = new.type >= TYPE_IMAGE && new.type != TYPE_PATH
+            val textureFade = isTexture && (old.color and 0xF0) == (new.color and 0xF0)
+            if (old.color != new.color && isTexture && !textureFade) return null
+            if (old.width != new.width && isTexture) return null
+            var mask = tweenable
+            val values = mutableListOf<Int>()
+            for (k in 0 until 8) if (tweenable and (1 shl k) != 0) values.add(new.params[k])
+            if (!isTexture || textureFade) { mask = mask or 0x100; values.add(new.color) }
+            if (!isTexture && new.type != TYPE_PATH) { mask = mask or 0x200; values.add(new.width) }
+            if (mask == 0) return null
+            return tweenOp(id, mask, frames, curve, values)
+        }
+
+        /** Changing bitmaps benefit from compressed dirty rectangles; transitions still need objects. */
+        fun prefersRaster(frame: SceneFrame): Boolean =
+            frame.elements.isNotEmpty() && frame.elements.all { it.type == "image" && it.transitionMs == 0 && it.depth == 0 }
+    }
+
+    /**
+     * One object's record in decoded form: type, 4-bit color (or options byte), stroke width,
+     * eight int16 parameters, inline text bytes, path commands, and asset ids.
+     */
+    class Slot(
+        val type: Int, val color: Int, val width: Int, params: List<Int>,
+        val text: ByteArray = ByteArray(0), val path: ByteArray = ByteArray(0), val fillRule: Int = 0,
+        val asset: Int = 0, val font: Int = 0,
+    ) {
+        var angle: Int = 0
+        var pivotX: Int = 0
+        var pivotY: Int = 0
+        val rotatable: Boolean get() = type <= 13 || type == TYPE_PATH
+        val params: IntArray = IntArray(8) { params.getOrElse(it) { 0 } }
+
+        override fun equals(other: Any?): Boolean =
+            other is Slot && sameGeometry(other) && other.angle == angle && other.pivotX == pivotX && other.pivotY == pivotY
+
+        fun sameGeometry(other: Slot): Boolean = type == other.type && color == other.color && width == other.width &&
+            params.contentEquals(other.params) && text.contentEquals(other.text) && path.contentEquals(other.path) &&
+            fillRule == other.fillRule && asset == other.asset && font == other.font
+
+        override fun hashCode(): Int =
+            (((type * 31 + color) * 31 + width) * 31 + params.contentHashCode()) * 31 + text.contentHashCode()
+    }
+
+    /** What this mirror knows the glasses hold for one object. */
+    class Known(var version: Int, var definition: Slot, var state: Slot?, var animEndsAt: Long)
+
+    class Encoded(val payload: ByteArray, val uploads: List<ByteArray>, val changed: Boolean = true, val puts: Int = 0, val hits: Int = 0, val tweens: Int = 0)
+
+    class MonoFace(
+        val metrics: (Int) -> Pair<Int, Int>,
+        val glyph: (Int, Int, Int, Int) -> ByteArray?,
+    )
+
+    var generation = -1
+        private set
+    val known = mutableMapOf<Int, Known>()
+    var active: List<Int> = emptyList()
+        private set
+    var objectIds: List<List<Int>> = emptyList()
+        private set
+
+    fun reset(generation: Int) {
+        this.generation = generation
+        known.clear()
+        active = emptyList()
+        objectIds = emptyList()
+    }
+
+    /** Residency is unknown (a send failed): the next frame redefines everything it shows. */
+    fun invalidate() {
+        known.clear()
+        active = emptyList()
+    }
+
+    /** The panel went blank: objects animating right now froze mid-flight, so they are re-snapped when shown again. */
+    fun hidden() {
+        val now = System.currentTimeMillis()
+        for (id in active) known[id]?.let { if (it.animEndsAt > now) it.state = null }
+        active = emptyList()
+    }
+
+    /** The glasses reported these object ids absent (or at another version). */
+    fun forget(objectIds: Collection<Int>) {
+        for (id in objectIds) known.remove(id)
+    }
+
+    /**
+     * Become a copy of [other]: the second lens mirror starts from the shared
+     * state the moment the lenses diverge (the first frame with element depth).
+     */
+    fun adopt(other: G2CfwScene) {
+        generation = other.generation
+        known.clear()
+        for ((id, k) in other.known) known[id] = Known(k.version, k.definition, k.state, k.animEndsAt)
+        active = other.active
+        objectIds = other.objectIds
+    }
+
+    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 asset store cannot hold its content. */
+    fun slotsFor(
+        element: SceneElement,
+        ox: Int,
+        oy: Int,
+        inlineText: Boolean,
+        cache: G2CfwTextureCache,
+        rasterize: (SceneElement, Int, Int) -> ByteArray?,
+        mono: MonoFace? = null,
+    ): 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) {
+            "svg" -> {
+                if (element.path.isEmpty() || element.path.size > 8192 || element.pathScale !in 0..2048) return null
+                listOf(Slot(TYPE_PATH, color, 0, listOf(x, y, element.pathScale), path = element.path.map { it.toByte() }.toByteArray(), fillRule = element.fillRule))
+            }
+            "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" ->
+                when {
+                    element.font == "mono" ->
+                        if (mono == null) rasterSlots(element, x, y, cache, rasterize)
+                        else monoTextSlots(element, x, y, cache, mono, rasterize)
+                    inlineText -> inlineTextSlots(element, x, y)
+                    element.font == "builtin" -> builtinTextSlots(element, x, y, cache)
+                    else -> rasterSlots(element, x, y, cache, rasterize)
+                }
+            "image" -> rasterSlots(element, x, y, cache, rasterize)
+            else -> emptyList()
+        }
+    }
+
+    /** One TEXT_INLINE object per line, drawn by the glasses' font at the phone-raster 2 px inset, clipped to the box. */
+    private fun inlineTextSlots(element: SceneElement, x: Int, y: Int): List<Slot> {
+        val out = mutableListOf<Slot>()
+        val w = element.w.coerceIn(0, 2047)
+        val h = element.h.coerceIn(0, 2047)
+        if (element.border > 0) {
+            out.add(Slot(TYPE_RECT, gray(element), stroke(element), listOf(x, y, w, h, element.radius.coerceIn(0, 2047))))
+        }
+        val options = 0x10 or gray(element)
+        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, MAX_INLINE_BYTES)
+            if (bytes.isEmpty()) continue
+            val lineY = y + TEXT_INSET + index * TEXT_LINE_HEIGHT
+            val clipW = maxOf(0, element.w - TEXT_INSET).coerceAtMost(2047)
+            val clipH = maxOf(0, element.h - TEXT_INSET - index * TEXT_LINE_HEIGHT).coerceAtMost(2047)
+            out.add(Slot(TYPE_TEXT_INLINE, options, 0, listOf(clampCoord(x + TEXT_INSET), clampCoord(lineY), clipW, clipH, bytes.size), bytes))
+        }
+        return out
+    }
+
+    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 asset = cache.ensureBytes("t:$line", bytes) ?: return null
+            out.add(Slot(TYPE_TEXT, TEXT_OPTIONS, 0, listOf(x, clampCoord(y + index * TEXT_LINE_HEIGHT)), asset = asset))
+        }
+        return out
+    }
+
+    /**
+     * Mono text as TEXT_CACHED runs: each line is a string asset drawn with the font asset for
+     * its size, so glyphs upload once per generation and a changed string costs only its bytes.
+     * Cells sit on the raster path's grid (2 px inset, partial edge cells kept); runs split at
+     * the 64-byte limit. A separate font maps half-block grids to printable wire bytes; other
+     * non-ASCII text keeps the image-tile path.
+     */
+    private fun monoTextSlots(
+        element: SceneElement,
+        x: Int,
+        y: Int,
+        cache: G2CfwTextureCache,
+        mono: MonoFace,
+        rasterize: (SceneElement, Int, Int) -> ByteArray?,
+    ): List<Slot>? {
+        val (cellW, lineH) = mono.metrics(element.fontSize)
+        if (cellW <= 0 || lineH <= 0) return emptyList()
+        val cols = maxOf(0, (element.w - TEXT_INSET + cellW - 1) / cellW)
+        val rows = maxOf(0, (element.h - TEXT_INSET + lineH - 1) / lineH)
+        val lines = (element.text ?: "").split('\n').take(rows).map { it.codePoints().toArray().take(cols) }
+        val blockGrid = lines.any { line -> line.any { it > 126 } } && lines.all { line -> line.all { BLOCK_CODES.containsKey(it) } }
+        if (!blockGrid && lines.any { line -> line.any { it < 32 || it > 126 } }) return rasterSlots(element, x, y, cache, rasterize)
+        val variant = if (blockGrid) "blocks" else "ascii"
+        val codes = if (blockGrid) listOf(32, 65, 66, 67) else (32..126).toList()
+        val scalarFor: (Int) -> Int? = { code -> if (blockGrid) BLOCK_CODES.entries.firstOrNull { it.value == code }?.key else code }
+        val font = cache.font(element.fontSize, cellW, lineH, variant, codes) { code ->
+            scalarFor(code)?.let { mono.glyph(it, element.fontSize, cellW, lineH) }
+        } ?: return null
+        // Opaque cells (options bit 4 clear): the grid owns its cells, as the raster path's blits do.
+        val options = gray(element)
+        val out = mutableListOf<Slot>()
+        for ((row, line) in lines.withIndex()) {
+            if (line.isEmpty()) continue
+            val lineY = clampCoord(y + TEXT_INSET + row * lineH)
+            var start = 0
+            while (start < line.size) {
+                val run = line.subList(start, minOf(line.size, start + MAX_TEXT_BYTES))
+                val bytes = ByteArray(run.size) { (if (blockGrid) BLOCK_CODES[run[it]]!! else run[it]).toByte() }
+                // A glyph the font could not raster keeps the tile path for the element.
+                if (bytes.any { val c = it.toInt() and 0xFF; c != 32 && c !in font.glyphs }) return rasterSlots(element, x, y, cache, rasterize)
+                val text = String(run.toIntArray(), 0, run.size)
+                val asset = cache.ensureBytes("t:$variant:$text", bytes) ?: return null
+                out.add(Slot(TYPE_TEXT_CACHED, options, 0, listOf(clampCoord(x + TEXT_INSET + start * cellW), lineY), asset = asset, font = font.id))
+                start += run.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()
+        // An image's ink is the ramp's top color; rasterized text keeps its ink in the pixels.
+        val options = if (element.type == "image") gray(element) else IMAGE_OPTIONS
+        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 = "px:${pixelHash(tile)}@${tw}x$th"
+                val asset = cache.ensureImage(key, tile, tw, th) ?: return null
+                out.add(Slot(TYPE_IMAGE, options, 0, listOf(clampCoord(x + tx), clampCoord(y + ty)), asset = asset))
+                tx += tw
+            }
+            ty += th
+        }
+        return out
+    }
+
+    private class Desired(val id: String, val slots: List<Slot>, val frames: Int, val curve: IntArray, val duration: Int)
+
+    /**
+     * One SHOW (embedded object PUTs, references in paint order, ops) and the asset PUT
+     * messages that must precede it. Null when the frame does not fit the object table or
+     * the asset store; the caller then falls back to the raster path. `tag` (the host frame
+     * number) becomes the SHOW's request id with the TAG flag, so settings field 129 reports
+     * it once the scene settles.
+     */
+    fun encode(
+        frame: SceneFrame,
+        originX: Int,
+        originY: Int,
+        cache: G2CfwTextureCache,
+        rasterize: (SceneElement, Int, Int) -> ByteArray?,
+        inlineText: Boolean = false,
+        mono: MonoFace? = null,
+        tag: Int? = null,
+        /** +1 for the left lens mirror, -1 for the right: each element shifts by depth × parallax px; 0 draws flat. */
+        parallax: Int = 0,
+    ): Encoded? {
+        val desired = mutableListOf<Desired>()
+        for (element in frame.elements) {
+            val ox = originX + element.depth * parallax
+            val slots = slotsFor(element, ox, originY, inlineText, cache, rasterize, mono) ?: return null
+            slots.filter { it.rotatable }.forEach { slot ->
+                slot.angle = element.rotationQ8
+                slot.pivotX = ((element.pivotX ?: (element.x + element.w / 2)) + ox).coerceIn(-32768, 32767)
+
+                slot.pivotY = ((element.pivotY ?: (element.y + element.h / 2)) + originY).coerceIn(-32768, 32767)
+            }
+            desired.add(Desired(element.id, slots, transitionFrames(element.transitionMs), easingCurve(element.easing), element.transitionMs))
+        }
+        if (desired.sumOf { it.slots.size } > MAX_OBJECTS) return null
+
+        val now = System.currentTimeMillis()
+        val puts = mutableListOf<ByteArray>()
+        val refs = mutableListOf<Pair<Int, Int>>()
+        val ops = mutableListOf<ByteArray>()
+        var putCount = 0
+        var hits = 0
+        var tweens = 0
+        val ids = mutableListOf<List<Int>>()
+        val seen = mutableSetOf<Int>()
+        // Only objects the previous frame showed may animate: one coming back to
+        // the frame appears where it is asked to be, not tweened from where it left.
+        val onScreen = active.toSet()
+        for (item in desired) {
+            val mine = mutableListOf<Int>()
+            for ((k, slot) in item.slots.withIndex()) {
+                val id = objectId(item.id, k)
+                if (!seen.add(id)) continue
+                mine.add(id)
+                val version = versionOf(slot)
+                fun put() {
+                    puts.add(putObject(id, version, objectRecord(slot)))
+                    if (slot.angle != 0) ops.add(rotationOp(slot, id, 0, item.curve))
+                    putCount += 1
+                    known[id] = Known(version, slot, slot, 0)
+                    refs.add(id to version)
+                }
+                val k0 = known[id]
+                if (k0 == null) { put(); continue }
+                val animate = id in onScreen
+                val current = k0.state
+                if (current != null) {
+                    if (current == slot) { hits += 1; refs.add(id to k0.version); continue }
+                    val rotationChanged = current.angle != slot.angle ||
+                        ((current.angle != 0 || slot.angle != 0) && (current.pivotX != slot.pivotX || current.pivotY != slot.pivotY))
+                    if (current.sameGeometry(slot)) {
+                        if (rotationChanged) {
+                            val duration = if (animate) item.duration else 0
+                            ops.add(rotationOp(slot, id, duration, item.curve))
+                            k0.animEndsAt = now + duration
+                        }
+                        k0.state = slot
+                        hits += 1
+                        refs.add(id to k0.version)
+                        continue
+                    }
+                    if (animate && item.frames >= 2) {
+                        val tween = tweenOp(current, slot, id, item.frames, item.curve)
+                        if (tween != null) {
+                            ops.add(tween)
+                            if (rotationChanged) ops.add(rotationOp(slot, id, item.duration, item.curve))
+                            tweens += 1
+                            k0.state = slot
+                            k0.animEndsAt = now + (item.frames * FRAME_PERIOD_MS).toLong()
+                            refs.add(id to k0.version)
+                            continue
+                        }
+                    }
+                    // The glasses hold this exact definition and earlier ops only moved it:
+                    // a same-version PUT is a no-op there, so snap the state instead.
+                    if (k0.version == version) {
+                        val snap = tweenOp(current, slot, id, 0, item.curve)
+                        if (snap != null) {
+                            ops.add(snap)
+                            if (rotationChanged) ops.add(rotationOp(slot, id, 0, item.curve))
+                            k0.state = slot
+                            k0.animEndsAt = 0
+                            hits += 1
+                            refs.add(id to k0.version)
+                            continue
+                        }
+                    }
+                    put()
+                    continue
+                }
+
+                // Frozen mid-flight by a hide: snap it back to the geometry it should show.
+                val snap = tweenOp(k0.definition, slot, id, 0, item.curve)
+                if (snap != null) {
+                    ops.add(snap)
+                    if (slot.angle != 0 || k0.definition.angle != 0) ops.add(rotationOp(slot, id, 0, item.curve))
+                    k0.state = slot
+                    hits += 1
+                    refs.add(id to k0.version)
+                    continue
+                }
+                put()
+            }
+            ids.add(mine)
+        }
+        val listChanged = refs.map { it.first } != active
+        active = refs.map { it.first }
+        objectIds = ids
+        val payload = showPayload(puts, refs, ops, request = (tag ?: 0) and 0xFFFF, tag = (tag ?: 0) > 0)
+        return Encoded(payload, cache.takeUploadPayloads(), listChanged || puts.isNotEmpty() || ops.isNotEmpty(), putCount, hits, tweens)
+    }
+}