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

package/ios/Source/sgcs/G2CfwScene.swift

@@ -0,0 +1,779 @@
+import Foundation
+
+/// 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(objectIds:)`).
+///
+/// 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`).
+final class G2CfwScene {
+    static let maxObjects = 256
+    static let framePeriodMs = 33.0
+    static let textLineHeight = 27
+    static let textInset = 2
+    static let maxTextBytes = 64
+    static let maxInlineBytes = 128
+    static let maxTileSize = 255
+    /// Mode-15/20 options: identity ramp, transparent source color 0.
+    static let textOptions: UInt8 = 0x1F
+    static let imageOptions: UInt8 = 0x0F
+    static let allObjects: UInt32 = 0xFFFF_FFFF
+
+    enum ShapeType: UInt8 {
+        case line = 1, rect, rectFill, circle, circleFill, tri, triFill, quad, quadFill
+        case bezier2, bezier3, arc, pie, image, text, textCached, textInline, path
+    }
+
+    /// The id of the warm-up dot and its SHOW: a hidden two-frame tween on a
+    /// black 1 px dot, sent once per cache generation right after the RESET so
+    /// the first visible transition of a session is not also the first
+    /// animation the firmware ever runs (it creates its timer lazily).
+    static let warmUpId = G2CfwTextureCache.hash31("warm-up")
+    static let warmUpShow: Data = {
+        let dot = Slot(.circleFill, color: 0, [0, 0, 1])
+        return showPayload(
+            puts: [putObject(id: warmUpId, version: 1, record: objectRecord(dot))],
+            refs: [(warmUpId, 1)],
+            ops: [tweenOp(id: warmUpId, mask: 0x01, frames: 2, curve: [0, 0, 255, 255], values: [1])],
+            request: 0
+        )
+    }()
+    /// Mode 39: freeze, blank and keep everything cached.
+    static let hidePayload = Data([39, 0, 0, 0, 0, 0x01, 0])
+    /// Mode 41 sub 0: empty both caches and adopt the epoch the link stamps in.
+    static let resetPayload = Data([41, 0, 0, 0, 0, 0])
+
+    struct Slot: Equatable {
+        var type: UInt8
+        var color: UInt8
+        var width: UInt8
+        var params: [Int16]
+        /// TEXT_INLINE bytes carried in the record.
+        var text: [UInt8]
+        var path: [UInt8]
+        var fillRule: UInt8
+        /// Asset ids for IMAGE (image), TEXT (string), TEXT_CACHED (string + font).
+        var asset: UInt32 = 0
+        var font: UInt32 = 0
+        var angle: Int32 = 0
+        var pivotX: Int16 = 0
+        var pivotY: Int16 = 0
+
+        func sameGeometry(as other: Slot) -> Bool {
+            type == other.type && color == other.color && width == other.width && params == other.params
+                && text == other.text && path == other.path && fillRule == other.fillRule
+                && asset == other.asset && font == other.font
+        }
+
+        var rotatable: Bool {
+            type <= 13 || type == 18
+        }
+
+        init(_ type: ShapeType, color: UInt8, width: UInt8 = 0, _ params: [Int16], text: [UInt8] = [], path: [UInt8] = [],
+             fillRule: UInt8 = 0, asset: UInt32 = 0, font: UInt32 = 0) {
+            self.type = type.rawValue
+            self.color = color
+            self.width = width
+            var padded = params
+            while padded.count < 8 {
+                padded.append(0)
+            }
+            self.params = Array(padded.prefix(8))
+            self.text = text
+            self.path = path
+            self.fillRule = fillRule
+            self.asset = asset
+            self.font = font
+        }
+    }
+
+    /// What this mirror knows the glasses hold for one object.
+    struct Known {
+        /// Version of the definition resident on the glasses and what it defines.
+        var version: UInt32
+        var definition: Slot
+        /// The geometry the glasses currently show (ops move it without a new
+        /// version); nil after a hide mid-flight, when it must be re-snapped.
+        var state: Slot?
+        var animEndsAt: TimeInterval
+    }
+
+    struct Encoded {
+        /// The SHOW.
+        let payload: Data
+        /// Standalone PUT messages (asset uploads) that must precede it.
+        let uploads: [Data]
+        /// False when the frame is the one already on screen (nothing to send).
+        let changed: Bool
+        /// Objects the frame redefined / referenced from the cache / tweened.
+        let puts: Int
+        let hits: Int
+        let tweens: Int
+    }
+
+    /// Changing bitmaps benefit from compressed dirty rectangles, without
+    /// allocating new retained textures every frame. Transitions still need objects.
+    static func prefersRaster(_ frame: SceneFrame) -> Bool {
+        !frame.elements.isEmpty && frame.elements.allSatisfy { $0.type == "image" && $0.transitionMs == 0 && $0.depth == 0 }
+    }
+
+    /// The phone's monospaced face for TEXT_CACHED runs: fixed cell metrics per
+    /// font size, and the full-cell glyph raster (cellWidth × lineHeight, 8-bit
+    /// gray, white ink) for one char — the same raster the frame blits use.
+    struct MonoFace {
+        let metrics: (Int32) -> (cellWidth: Int, lineHeight: Int)
+        let glyph: (Unicode.Scalar, Int32, Int, Int) -> Data?
+    }
+
+    private(set) var generation = -1
+    private(set) var known: [UInt32: Known] = [:]
+    /// Object ids of the frame on screen, in paint order; empty after a hide.
+    private(set) var active: [UInt32] = []
+    /// Element id → its object ids, for the last encoded frame.
+    private(set) var objectIds: [[UInt32]] = []
+
+    /// Forget everything: the on-glass cache is empty or unknown.
+    func reset(generation: Int) {
+        self.generation = generation
+        known.removeAll()
+        active.removeAll()
+        objectIds.removeAll()
+    }
+
+    /// The residency of every object is unknown (a send failed): the next frame redefines everything it shows.
+    func invalidate() {
+        known.removeAll()
+        active.removeAll()
+    }
+
+    /// The panel went blank (HIDE or a raster takeover): objects animating right
+    /// now froze mid-flight on the glasses, so they are re-snapped when shown again.
+    func hidden() {
+        let now = Date().timeIntervalSince1970
+        for id in active {
+            if let k = known[id], k.animEndsAt > now {
+                known[id]?.state = nil
+            }
+        }
+        active.removeAll()
+    }
+
+    /// The glasses reported these object ids absent (or at another version).
+    func forget(objectIds ids: [UInt32]) {
+        for id in ids {
+            known.removeValue(forKey: id)
+        }
+    }
+
+    /// Become a copy of `other`: the second lens mirror starts from the shared
+    /// state the moment the lenses diverge (the first frame with depth).
+    func adopt(_ other: G2CfwScene) {
+        generation = other.generation
+        known = other.known
+        active = other.active
+        objectIds = other.objectIds
+    }
+
+    // MARK: - Element → slots
+
+    /// Geometry parameters a TWEEN may interpolate, per type. Asset ids never tween.
+    static func tweenableMask(_ type: UInt8) -> UInt16 {
+        switch ShapeType(rawValue: type) {
+        case .path: return 0x07
+        case .line: return 0x0F
+        case .rect, .rectFill, .arc, .pie: return 0x1F
+        case .circle, .circleFill: return 0x07
+        case .tri, .triFill, .bezier2: return 0x3F
+        case .quad, .quadFill, .bezier3: return 0xFF
+        case .image, .text, .textCached: return 0x03
+        case .textInline: return 0x0F
+        case .none: return 0
+        }
+    }
+
+    static func easingCurve(_ easing: String) -> [UInt8] {
+        switch easing {
+        case "linear": return [0, 0, 255, 255]
+        case "ease-in": return [107, 0, 255, 255]
+        case "ease-out": return [0, 0, 148, 255]
+        case "ease-in-out": return [107, 0, 148, 255]
+        default: return [64, 26, 64, 255] // CSS "ease"
+        }
+    }
+
+    /// FNV-1a 64 of a tile's pixels: the asset key, so elements with the same
+    /// pixels (one icon on several cards, at any ink) share one upload.
+    static func pixelHash(_ pixels: Data) -> String {
+        var hash: UInt64 = 0xCBF2_9CE4_8422_2325
+        for byte in pixels {
+            hash ^= UInt64(byte)
+            hash = hash &* 0x0000_0100_0000_01B3
+        }
+        return String(hash, radix: 36)
+    }
+
+    static func transitionFrames(ms: Int32) -> UInt8 {
+        guard ms > 0 else { return 0 }
+        let frames = Int((Double(ms) / framePeriodMs).rounded())
+        return UInt8(max(2, min(255, frames)))
+    }
+
+    /// Object id of the k-th slot of an element: stable across frames and reopenings.
+    static func objectId(_ elementId: String, _ k: Int) -> UInt32 {
+        G2CfwTextureCache.hash31("\(elementId)#\(k)")
+    }
+
+    /// Content version of a slot: a hash of the record the glasses store.
+    static func version(of slot: Slot) -> UInt32 {
+        G2CfwTextureCache.hash31(objectRecord(slot))
+    }
+
+    private static func gray(_ element: SceneElement) -> UInt8 {
+        element.color < 0 ? 15 : UInt8(max(0, min(15, element.color)))
+    }
+
+    private static func stroke(_ element: SceneElement) -> UInt8 {
+        UInt8(max(1, min(255, element.border)))
+    }
+
+    private static func point(_ element: SceneElement, _ i: Int, ox: Int, oy: Int) -> (Int16, Int16) {
+        guard element.points.count >= 2 * i + 2 else { return (0, 0) }
+        return (clampCoord(Int(element.points[2 * i]) + ox), clampCoord(Int(element.points[2 * i + 1]) + oy))
+    }
+
+    private static func clampCoord(_ v: Int) -> Int16 {
+        Int16(max(-1024, min(1023, v)))
+    }
+
+    private static func circleGeometry(_ element: SceneElement, ox: Int, oy: Int) -> (Int16, Int16, Int16) {
+        let w = Int(element.w), h = Int(element.h)
+        let r = max(0, (min(w, h) - 1) / 2)
+        return (clampCoord(Int(element.x) + w / 2 + ox), clampCoord(Int(element.y) + h / 2 + oy), Int16(r))
+    }
+
+    /// Slots for one element, or nil when the asset store cannot hold its content.
+    /// `inlineText` selects TEXT_INLINE records for default/builtin text; without
+    /// `mono`, mono text falls back to image tiles.
+    func slots(
+        for element: SceneElement, originX ox: Int, originY oy: Int, inlineText: Bool,
+        mono: MonoFace? = nil, cache: G2CfwTextureCache, rasterize: (SceneElement, Int, Int) -> Data?
+    ) -> [Slot]? {
+        let x = Self.clampCoord(Int(element.x) + ox)
+        let y = Self.clampCoord(Int(element.y) + oy)
+        let w = Int16(max(0, min(2047, Int(element.w))))
+        let h = Int16(max(0, min(2047, Int(element.h))))
+        let color = Self.gray(element)
+        let radius = Int16(max(0, min(2047, Int(element.radius))))
+        switch element.type {
+        case "svg":
+            guard !element.path.isEmpty, element.path.count <= 8192, (0 ... 2048).contains(element.pathScale) else { return nil }
+            return [Slot(.path, color: color, [x, y, Int16(element.pathScale)], path: element.path, fillRule: UInt8(clamping: element.fillRule))]
+        case "rect":
+            var out: [Slot] = []
+            if element.fill {
+                out.append(Slot(.rectFill, color: color, [x, y, w, h, radius]))
+                if element.border > 0 {
+                    out.append(Slot(.rect, color: color, width: Self.stroke(element), [x, y, w, h, radius]))
+                }
+            } else {
+                out.append(Slot(.rect, color: color, width: Self.stroke(element), [x, y, w, h, radius]))
+            }
+            return out
+        case "circle":
+            let (cx, cy, r) = Self.circleGeometry(element, ox: ox, oy: oy)
+            if element.fill {
+                return [Slot(.circleFill, color: color, [cx, cy, r])]
+            }
+            return [Slot(.circle, color: color, width: Self.stroke(element), [cx, cy, r])]
+        case "arc", "pie":
+            let (cx, cy, r) = Self.circleGeometry(element, ox: ox, oy: oy)
+            let a0 = Self.clampCoord(Int(element.startDeg)), a1 = Self.clampCoord(Int(element.endDeg))
+            if element.type == "pie" {
+                return [Slot(.pie, color: color, [cx, cy, r, a0, a1])]
+            }
+            return [Slot(.arc, color: color, width: Self.stroke(element), [cx, cy, r, a0, a1])]
+        case "line":
+            let (x1, y1) = Self.point(element, 0, ox: ox, oy: oy)
+            let (x2, y2) = Self.point(element, 1, ox: ox, oy: oy)
+            return [Slot(.line, color: color, width: Self.stroke(element), [x1, y1, x2, y2])]
+        case "triangle", "quad":
+            let n = element.type == "triangle" ? 3 : 4
+            var params: [Int16] = []
+            for i in 0 ..< n {
+                let (px, py) = Self.point(element, i, ox: ox, oy: oy)
+                params.append(contentsOf: [px, py])
+            }
+            let filled: ShapeType = n == 3 ? .triFill : .quadFill
+            let stroked: ShapeType = n == 3 ? .tri : .quad
+            if element.fill {
+                return [Slot(filled, color: color, params)]
+            }
+            return [Slot(stroked, color: color, width: Self.stroke(element), params)]
+        case "bezier":
+            let n = element.points.count / 2
+            guard n == 3 || n == 4 else { return [] }
+            var params: [Int16] = []
+            for i in 0 ..< n {
+                let (px, py) = Self.point(element, i, ox: ox, oy: oy)
+                params.append(contentsOf: [px, py])
+            }
+            return [Slot(n == 3 ? .bezier2 : .bezier3, color: color, width: Self.stroke(element), params)]
+        case "text" where element.font == "mono":
+            guard let mono = mono else { return rasterSlots(element, x: x, y: y, cache: cache, rasterize: rasterize) }
+            return monoTextSlots(element, x: x, y: y, cache: cache, mono: mono, rasterize: rasterize)
+        case "text" where inlineText:
+            return inlineTextSlots(element, x: x, y: y)
+        case "text" where element.font == "builtin":
+            return builtinTextSlots(element, x: x, y: y, cache: cache)
+        case "text", "image":
+            return rasterSlots(element, x: x, y: y, cache: cache, rasterize: rasterize)
+        default:
+            return []
+        }
+    }
+
+    private func builtinTextSlots(_ element: SceneElement, x: Int16, y: Int16, cache: G2CfwTextureCache) -> [Slot]? {
+        var out: [Slot] = []
+        if element.border > 0 {
+            out.append(Slot(.rect, color: 15, width: Self.stroke(element),
+                            [x, y, Int16(min(2047, Int(element.w))), Int16(min(2047, Int(element.h))),
+                             Int16(max(0, min(2047, Int(element.radius))))]))
+        }
+        let maxLines = max(1, Int(element.h) / Self.textLineHeight)
+        let lines = (element.text ?? "").split(separator: "\n", omittingEmptySubsequences: false).prefix(maxLines)
+        for (index, line) in lines.enumerated() {
+            let bytes = Self.textBytes(String(line))
+            if bytes.isEmpty {
+                continue
+            }
+            guard let asset = cache.ensureBytes(key: "t:" + String(line), bytes: bytes) else { return nil }
+            let lineY = Int(y) + index * Self.textLineHeight
+            out.append(Slot(.text, color: Self.textOptions, [x, Self.clampCoord(lineY)], asset: asset))
+        }
+        return out
+    }
+
+    /// One TEXT_INLINE object per line, drawn by the glasses' font at the same 2 px
+    /// inset as phone-rasterized text, clipped to the box.
+    private func inlineTextSlots(_ element: SceneElement, x: Int16, y: Int16) -> [Slot] {
+        var out: [Slot] = []
+        let w = Int16(max(0, min(2047, Int(element.w))))
+        let h = Int16(max(0, min(2047, Int(element.h))))
+        if element.border > 0 {
+            out.append(Slot(.rect, color: Self.gray(element), width: Self.stroke(element),
+                            [x, y, w, h, Int16(max(0, min(2047, Int(element.radius))))]))
+        }
+        let options = UInt8(0x10) | Self.gray(element)
+        let maxLines = max(1, Int(element.h) / Self.textLineHeight)
+        let lines = (element.text ?? "").split(separator: "\n", omittingEmptySubsequences: false).prefix(maxLines)
+        for (index, line) in lines.enumerated() {
+            let bytes = Self.textBytes(String(line), max: Self.maxInlineBytes)
+            if bytes.isEmpty {
+                continue
+            }
+            let lineY = Int(y) + Self.textInset + index * Self.textLineHeight
+            let clipW = max(0, Int(element.w) - Self.textInset)
+            let clipH = max(0, Int(element.h) - Self.textInset - index * Self.textLineHeight)
+            out.append(Slot(.textInline, color: options,
+                            [Self.clampCoord(Int(x) + Self.textInset), Self.clampCoord(lineY),
+                             Int16(min(2047, clipW)), Int16(min(2047, clipH)), Int16(bytes.count)],
+                            text: bytes))
+        }
+        return out
+    }
+
+    /// UTF-8 bytes of a line without firmware control bytes (1..31), cut at a codepoint boundary.
+    static func textBytes(_ line: String, max limit: Int = maxTextBytes) -> [UInt8] {
+        let cleaned = line.unicodeScalars.filter { $0.value >= 32 }
+        var bytes: [UInt8] = []
+        for scalar in cleaned {
+            let encoded = Array(String(scalar).utf8)
+            if bytes.count + encoded.count > limit {
+                break
+            }
+            bytes.append(contentsOf: encoded)
+        }
+        return bytes
+    }
+
+    /// Wire codes of the half-block grid font: mode 20 indexes a font by
+    /// ASCII byte, so its glyphs need not be ASCII. Kept apart from the real ASCII font.
+    static let blockCodes: [UInt32: UInt8] = [32: 32, 0x2580: 65, 0x2584: 66, 0x2588: 67]
+
+    /// 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 func monoTextSlots(
+        _ element: SceneElement, x: Int16, y: Int16, cache: G2CfwTextureCache, mono: MonoFace,
+        rasterize: (SceneElement, Int, Int) -> Data?
+    ) -> [Slot]? {
+        let metrics = mono.metrics(element.fontSize)
+        let cellW = metrics.cellWidth, lineH = metrics.lineHeight
+        guard cellW > 0, lineH > 0 else { return [] }
+        let cols = max(0, (Int(element.w) - Self.textInset + cellW - 1) / cellW)
+        let rows = max(0, (Int(element.h) - Self.textInset + lineH - 1) / lineH)
+        let lines: [[Unicode.Scalar]] = (element.text ?? "")
+            .split(separator: "\n", omittingEmptySubsequences: false).prefix(rows)
+            .map { Array($0.unicodeScalars.prefix(cols)) }
+        let blockGrid = lines.contains { $0.contains { $0.value > 126 } }
+            && lines.allSatisfy { $0.allSatisfy { Self.blockCodes[$0.value] != nil } }
+        guard blockGrid || lines.allSatisfy({ $0.allSatisfy { $0.value >= 32 && $0.value <= 126 } }) else {
+            return rasterSlots(element, x: x, y: y, cache: cache, rasterize: rasterize)
+        }
+        let variant = blockGrid ? "blocks" : "ascii"
+        let codes: [UInt8] = blockGrid ? [32, 65, 66, 67] : Array(32 ... 126)
+        let scalarFor: (UInt8) -> Unicode.Scalar? = { code in
+            if blockGrid {
+                return Self.blockCodes.first { $0.value == code }.flatMap { Unicode.Scalar($0.key) }
+            }
+            return Unicode.Scalar(UInt32(code))
+        }
+        guard let font = cache.font(fontSize: element.fontSize, cellWidth: cellW, lineHeight: lineH, variant: variant, codes: codes, rasterize: { code in
+            scalarFor(code).flatMap { mono.glyph($0, element.fontSize, cellW, lineH) }
+        }) else { return nil }
+        // Opaque cells (options bit 4 clear): the grid owns its cells, as the raster path's blits do.
+        let options = Self.gray(element)
+        var out: [Slot] = []
+        for (row, line) in lines.enumerated() where !line.isEmpty {
+            let lineY = Self.clampCoord(Int(y) + Self.textInset + row * lineH)
+            var start = 0
+            while start < line.count {
+                let run = Array(line[start ..< min(line.count, start + Self.maxTextBytes)])
+                let bytes = run.map { blockGrid ? Self.blockCodes[$0.value]! : UInt8($0.value) }
+                // A glyph the font could not raster keeps the tile path for the element.
+                guard bytes.allSatisfy({ $0 == 32 || font.glyphs.contains($0) }) else {
+                    return rasterSlots(element, x: x, y: y, cache: cache, rasterize: rasterize)
+                }
+                guard let asset = cache.ensureBytes(key: "t:\(variant):" + String(run.map { Character($0) }), bytes: bytes)
+                else { return nil }
+                out.append(Slot(.textCached, color: options,
+                                [Self.clampCoord(Int(x) + Self.textInset + start * cellW), lineY],
+                                asset: asset, font: font.id))
+                start += run.count
+            }
+        }
+        return out
+    }
+
+    private func rasterSlots(
+        _ element: SceneElement, x: Int16, y: Int16, cache: G2CfwTextureCache,
+        rasterize: (SceneElement, Int, Int) -> Data?
+    ) -> [Slot]? {
+        let w = Int(element.w), h = Int(element.h)
+        guard w > 0, h > 0, let gray = rasterize(element, w, h), gray.count == w * h else { return [] }
+        // An image's ink is the ramp's top color; rasterized text keeps its ink in the pixels.
+        let options = element.type == "image" ? Self.gray(element) : Self.imageOptions
+        var out: [Slot] = []
+        var ty = 0
+        while ty < h {
+            let th = min(Self.maxTileSize, h - ty)
+            var tx = 0
+            while tx < w {
+                let tw = min(Self.maxTileSize, w - tx)
+                var tile = Data(capacity: tw * th)
+                for row in 0 ..< th {
+                    let start = (ty + row) * w + tx
+                    tile.append(gray.subdata(in: start ..< start + tw))
+                }
+                let key = "px:\(Self.pixelHash(tile))@\(tw)x\(th)"
+                guard let asset = cache.ensureImage(hash: key, gray: tile, width: tw, height: th) else { return nil }
+                out.append(Slot(.image, color: options,
+                                [Self.clampCoord(Int(x) + tx), Self.clampCoord(Int(y) + ty)], asset: asset))
+                tx += tw
+            }
+            ty += th
+        }
+        return out
+    }
+
+    // MARK: - Frame encoding
+
+    /// One SHOW (embedded object PUTs, references in paint order, ops) and the
+    /// asset PUT messages that must precede it. Nil 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.
+    /// `parallax` is +1 for the left lens mirror and -1 for the right: each
+    /// element shifts by `depth × parallax` px; 0 draws every element flat.
+    func encode(
+        _ frame: SceneFrame, originX: Int, originY: Int, inlineText: Bool = false, mono: MonoFace? = nil,
+        tag: Int? = nil, parallax: Int = 0, cache: G2CfwTextureCache, rasterize: (SceneElement, Int, Int) -> Data?
+    ) -> Encoded? {
+        struct Desired {
+            let id: String
+            let slots: [Slot]
+            let frames: UInt8
+            let duration: Int32
+            let curve: [UInt8]
+        }
+        var desired: [Desired] = []
+        for element in frame.elements {
+            let ox = originX + Int(element.depth) * parallax
+            guard var slots = slots(for: element, originX: ox, originY: originY, inlineText: inlineText,
+                                    mono: mono, cache: cache, rasterize: rasterize)
+            else { return nil }
+            for i in slots.indices where slots[i].rotatable {
+                slots[i].angle = element.rotationQ8
+                slots[i].pivotX = Int16(clamping: Int(element.pivotX ?? (element.x + element.w / 2)) + ox)
+                slots[i].pivotY = Int16(clamping: Int(element.pivotY ?? (element.y + element.h / 2)) + originY)
+            }
+
+            desired.append(Desired(
+                id: element.id, slots: slots,
+                frames: Self.transitionFrames(ms: element.transitionMs), duration: element.transitionMs,
+                curve: Self.easingCurve(element.easing)
+            ))
+        }
+        guard desired.reduce(0, { $0 + $1.slots.count }) <= Self.maxObjects else { return nil }
+
+        let now = Date().timeIntervalSince1970
+        var puts: [Data] = []
+        var refs: [(UInt32, UInt32)] = []
+        var ops = Data()
+        var putCount = 0, hits = 0, tweens = 0
+        var ids: [[UInt32]] = []
+        var seen = Set<UInt32>()
+        // 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.
+        let onScreen = Set(active)
+        for item in desired {
+            var mine: [UInt32] = []
+            for (k, slot) in item.slots.enumerated() {
+                let id = Self.objectId(item.id, k)
+                guard !seen.contains(id) else { continue }
+                seen.insert(id)
+                mine.append(id)
+                let version = Self.version(of: slot)
+                func put() {
+                    puts.append(Self.putObject(id: id, version: version, record: Self.objectRecord(slot)))
+                    if slot.angle != 0 {
+                        ops.append(Self.rotationOp(slot, id: id, duration: 0, curve: item.curve))
+                    }
+                    putCount += 1
+                    known[id] = Known(version: version, definition: slot, state: slot, animEndsAt: 0)
+                    refs.append((id, version))
+                }
+                guard var k0 = known[id] else { put(); continue }
+                let animate = onScreen.contains(id)
+                if let current = k0.state {
+                    if current == slot {
+                        hits += 1
+                        refs.append((id, k0.version))
+                        continue
+                    }
+                    let rotationChanged = current.angle != slot.angle
+                        || ((current.angle != 0 || slot.angle != 0) && (current.pivotX != slot.pivotX || current.pivotY != slot.pivotY))
+                    if current.sameGeometry(as: slot) {
+                        if rotationChanged {
+                            let duration = animate ? item.duration : 0
+                            ops.append(Self.rotationOp(slot, id: id, duration: duration, curve: item.curve))
+                            k0.animEndsAt = now + Double(duration) / 1000
+                        }
+                        k0.state = slot
+                        known[id] = k0
+                        hits += 1
+                        refs.append((id, k0.version))
+                        continue
+                    }
+                    if animate, item.frames >= 2, let tween = Self.tweenOp(from: current, to: slot, id: id, frames: item.frames, curve: item.curve) {
+                        ops.append(tween)
+                        if rotationChanged {
+                            ops.append(Self.rotationOp(slot, id: id, duration: item.duration, curve: item.curve))
+                        }
+                        tweens += 1
+                        k0.state = slot
+                        k0.animEndsAt = now + Double(Int(item.frames)) * Self.framePeriodMs / 1000
+                        known[id] = k0
+                        refs.append((id, 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, let snap = Self.tweenOp(from: current, to: slot, id: id, frames: 0, curve: item.curve) {
+                        ops.append(snap)
+                        if rotationChanged {
+                            ops.append(Self.rotationOp(slot, id: id, duration: 0, curve: item.curve))
+                        }
+                        k0.state = slot
+                        k0.animEndsAt = 0
+                        known[id] = k0
+                        hits += 1
+                        refs.append((id, k0.version))
+                        continue
+                    }
+                    put()
+                    continue
+                }
+
+                // Frozen mid-flight by a hide: snap it back to the geometry it should show.
+                if let snap = Self.tweenOp(from: k0.definition, to: slot, id: id, frames: 0, curve: item.curve) {
+                    ops.append(snap)
+                    if slot.angle != 0 || k0.definition.angle != 0 {
+                        ops.append(Self.rotationOp(slot, id: id, duration: 0, curve: item.curve))
+                    }
+                    k0.state = slot
+                    known[id] = k0
+                    hits += 1
+                    refs.append((id, k0.version))
+                    continue
+                }
+                put()
+            }
+            ids.append(mine)
+        }
+        let listChanged = refs.map { $0.0 } != active
+        active = refs.map { $0.0 }
+        objectIds = ids
+        let payload = Self.showPayload(puts: puts, refs: refs, ops: [ops], request: tag.map { UInt16(truncatingIfNeeded: $0) } ?? 0,
+                                       tag: (tag ?? 0) > 0)
+        return Encoded(payload: payload, uploads: cache.takeUploadPayloads(),
+                       changed: listChanged || !puts.isEmpty || !ops.isEmpty, puts: putCount, hits: hits, tweens: tweens)
+    }
+
+    // MARK: - Wire records
+
+    private static func appendI16(_ value: Int16, to out: inout Data) {
+        let bits = UInt16(bitPattern: value)
+        out.append(UInt8(bits & 0xFF))
+        out.append(UInt8(bits >> 8))
+    }
+
+    /// The shape record the object cache stores for a slot (shapes.h layouts).
+    static func objectRecord(_ slot: Slot) -> Data {
+        switch ShapeType(rawValue: slot.type) {
+        case .path:
+            var out = Data([slot.type, 1, slot.color, slot.fillRule])
+            for value in slot.params.prefix(3) { appendI16(value, to: &out) }
+            out.append(UInt8(slot.path.count & 255)); out.append(UInt8(slot.path.count >> 8))
+            out.append(contentsOf: slot.path)
+            return out
+        case .textInline:
+            var out = Data([slot.type, 1, slot.color, 0])
+            for value in slot.params.prefix(4) { appendI16(value, to: &out) }
+            out.append(UInt8(min(slot.text.count, maxInlineBytes)))
+            out.append(contentsOf: slot.text.prefix(maxInlineBytes))
+            return out
+        case .image, .text, .textCached:
+            var out = Data([slot.type, 1, slot.color, 0])
+            for value in slot.params.prefix(2) { appendI16(value, to: &out) }
+            G2CfwTextureCache.appendU32(Int(slot.asset), to: &out)
+            if slot.type == ShapeType.textCached.rawValue { G2CfwTextureCache.appendU32(Int(slot.font), to: &out) }
+            return out
+        default:
+            var out = Data([slot.type, 1, slot.color, slot.width])
+            for value in slot.params { appendI16(value, to: &out) }
+            return out
+        }
+    }
+
+    /// `[1][id:u32][version:u32][record]`
+    static func putObject(id: UInt32, version: UInt32, record: Data) -> Data {
+        var out = Data([1])
+        G2CfwTextureCache.appendU32(Int(id), to: &out)
+        G2CfwTextureCache.appendU32(Int(version), to: &out)
+        out.append(record)
+        return out
+    }
+
+    /// `[38][epoch 0][request][flags][bg][puts][put entries][count:u16][(id, version) x count][ops]`
+    static func showPayload(puts: [Data], refs: [(UInt32, UInt32)], ops: [Data], request: UInt16, tag: Bool = false, bg: UInt8 = 0) -> Data {
+        var out = Data([38, 0, 0, UInt8(request & 0xFF), UInt8(request >> 8), tag ? 0x05 : 0x01, bg & 0x0F, UInt8(min(255, puts.count))])
+        for put in puts { out.append(put) }
+        out.append(UInt8(refs.count & 0xFF)); out.append(UInt8(refs.count >> 8))
+        for (id, version) in refs {
+            G2CfwTextureCache.appendU32(Int(id), to: &out)
+            G2CfwTextureCache.appendU32(Int(version), to: &out)
+        }
+        for op in ops { out.append(op) }
+        return out
+    }
+
+    /// `[9][id:u32][angle:i32][pivotX:i16][pivotY:i16][durationMs:u16][curve x4]`
+    static func rotationOp(_ slot: Slot, id: UInt32, duration: Int32, curve: [UInt8]) -> Data {
+        guard slot.rotatable else { return Data() }
+        var out = Data([9])
+        G2CfwTextureCache.appendU32(Int(id), to: &out)
+        let bits = UInt32(bitPattern: slot.angle)
+        for shift in stride(from: 0, through: 24, by: 8) {
+            out.append(UInt8((bits >> shift) & 255))
+        }
+        for value in [UInt16(bitPattern: slot.pivotX), UInt16(bitPattern: slot.pivotY), UInt16(clamping: duration)] {
+            out.append(UInt8(value & 255)); out.append(UInt8(value >> 8))
+        }
+        out.append(contentsOf: curve.prefix(4))
+        return out
+    }
+
+    /// `[5][id:u32][mask:u16][frames][curve x4][value:i16 per set bit]`
+    static func tweenOp(id: UInt32, mask: UInt16, frames: UInt8, curve: [UInt8], values: [Int16]) -> Data {
+        var out = Data([5])
+        G2CfwTextureCache.appendU32(Int(id), to: &out)
+        out.append(UInt8(mask & 0xFF)); out.append(UInt8(mask >> 8)); out.append(frames)
+        out.append(contentsOf: curve.prefix(4))
+        for value in values { appendI16(value, to: &out) }
+        return out
+    }
+
+    /// A TWEEN from `old` (what the glasses show) to `new`, or nil 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, so a changed-only mask would freeze
+    /// that axis wherever the earlier tween had got to when a second move lands.
+    static func tweenOp(from old: Slot, to new: Slot, id: UInt32, frames: UInt8, curve: [UInt8]) -> Data? {
+        guard old.type == new.type, old.text == new.text, old.path == new.path, old.fillRule == new.fillRule,
+              old.asset == new.asset, old.font == new.font else { return nil }
+        let tweenable = tweenableMask(new.type)
+        for k in 0 ..< 8 where old.params[k] != new.params[k] {
+            guard tweenable & (1 << k) != 0 else { return nil }
+        }
+        let isTexture = new.type >= ShapeType.image.rawValue && new.type != ShapeType.path.rawValue
+        // Textures fade through the options byte's low nibble (the ramp's top
+        // color) as long as the option bits stay put; the firmware lerps the
+        // whole byte, so a changed option bit would pass through wrong states.
+        let textureFade = isTexture && (old.color & 0xF0) == (new.color & 0xF0)
+        if old.color != new.color {
+            guard !isTexture || textureFade else { return nil }
+        }
+        if old.width != new.width {
+            guard !isTexture else { return nil }
+        }
+        var mask: UInt16 = tweenable
+        var values: [Int16] = []
+        for k in 0 ..< 8 where tweenable & (1 << k) != 0 {
+            values.append(new.params[k])
+        }
+        if !isTexture || textureFade {
+            mask |= 0x100
+            values.append(Int16(new.color))
+        }
+        if !isTexture && new.type != ShapeType.path.rawValue {
+            mask |= 0x200
+            values.append(Int16(new.width))
+        }
+        guard mask != 0 else { return nil }
+        return tweenOp(id: id, mask: mask, frames: frames, curve: curve, values: values)
+    }
+}