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

package/ios/Source/sgcs/G2CfwScene.swift

@@ -0,0 +1,394 @@
+import Foundation
+
+/// 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.
+final class G2CfwScene {
+    static let maxSlots = 128
+    static let recordBytes = 20
+    static let framePeriodMs = 33.0
+    static let textLineHeight = 27
+    static let maxTextBytes = 64
+    static let maxTileSize = 255
+    /// Mode-13/15 options: identity ramp, transparent source color 0.
+    static let textOptions: UInt8 = 0x1F
+    static let imageOptions: UInt8 = 0x0F
+
+    enum ShapeType: UInt8 {
+        case line = 1, rect, rectFill, circle, circleFill, tri, triFill, quad, quadFill
+        case bezier2, bezier3, arc, pie, image, text, textCached
+    }
+
+    struct Slot: Equatable {
+        var type: UInt8
+        var color: UInt8
+        var width: UInt8
+        var params: [Int16]
+
+        init(_ type: ShapeType, color: UInt8, width: UInt8 = 0, _ params: [Int16]) {
+            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))
+        }
+    }
+
+    struct ElementState {
+        let id: String
+        let contentHash: String
+        var slots: [Slot]
+        var indices: [Int]
+    }
+
+    struct Encoded {
+        let payload: Data
+        let uploads: [Data]
+    }
+
+    private(set) var generation = -1
+    private(set) var elements: [ElementState] = []
+    private var needsRepack = true
+
+    func reset(generation: Int) {
+        self.generation = generation
+        elements.removeAll()
+        needsRepack = true
+    }
+
+    /// The on-glass slot table is unknown (a send failed, the window moved): the next frame re-SETs everything.
+    func invalidate() {
+        needsRepack = true
+    }
+
+    // MARK: - Element → slots
+
+    /// Geometry parameters a TWEEN may interpolate, per type. Texture offsets and lengths never tween.
+    static func tweenableMask(_ type: UInt8) -> UInt16 {
+        switch ShapeType(rawValue: type) {
+        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 .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"
+        }
+    }
+
+    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)))
+    }
+
+    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 (Self.clampCoord(Int(element.points[2 * i]) + ox), Self.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 texture cache cannot hold its content.
+    func slots(
+        for element: SceneElement, originX ox: Int, originY oy: Int,
+        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 "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 == "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 offset = 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), Int16(bitPattern: UInt16(offset)), Int16(bytes.count)]))
+        }
+        return out
+    }
+
+    /// UTF-8 bytes of a line without firmware control bytes (1..31), cut at a codepoint boundary.
+    static func textBytes(_ line: String) -> [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 > maxTextBytes { break }
+            bytes.append(contentsOf: encoded)
+        }
+        return bytes
+    }
+
+    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 [] }
+        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 = "\(element.contentHash)@\(w)x\(h):\(tx),\(ty)"
+                guard let offset = cache.ensureImage(hash: key, gray: tile, width: tw, height: th) else { return nil }
+                out.append(Slot(.image, color: Self.imageOptions,
+                                [Self.clampCoord(Int(x) + tx), Self.clampCoord(Int(y) + ty),
+                                 Int16(bitPattern: UInt16(offset))]))
+                tx += tw
+            }
+            ty += th
+        }
+        return out
+    }
+
+    // MARK: - Frame encoding
+
+    /// One mode-17 patch (COMMIT, plus CLEAR on a repack) and the mode-12 uploads
+    /// that must precede it. Nil when the frame does not fit the slot table or
+    /// the texture cache; the caller then falls back to the raster path.
+    func encode(
+        _ frame: SceneFrame, originX: Int, originY: Int, cache: G2CfwTextureCache,
+        rasterize: (SceneElement, Int, Int) -> Data?
+    ) -> Encoded? {
+        struct Desired {
+            let id: String
+            let contentHash: String
+            let slots: [Slot]
+            let frames: UInt8
+            let curve: [UInt8]
+        }
+        var desired: [Desired] = []
+        for element in frame.elements {
+            guard let slots = slots(for: element, originX: originX, originY: originY, cache: cache, rasterize: rasterize)
+            else { return nil }
+            desired.append(Desired(
+                id: element.id, contentHash: element.contentHash, slots: slots,
+                frames: Self.transitionFrames(ms: element.transitionMs),
+                curve: Self.easingCurve(element.easing)
+            ))
+        }
+        let total = desired.reduce(0) { $0 + $1.slots.count }
+        guard total <= Self.maxSlots else { return nil }
+
+        var previous: [String: ElementState] = [:]
+        for state in elements { previous[state.id] = state }
+
+        var repack = needsRepack || frame.replay
+        var assigned: [[Int]] = []
+        if !repack {
+            var used = Set<Int>()
+            for item in desired {
+                if let prev = previous[item.id], prev.slots.count == item.slots.count { used.formUnion(prev.indices) }
+            }
+            var next = (used.max() ?? -1) + 1
+            var lastIndex = -1
+            for item in desired {
+                let indices: [Int]
+                if let prev = previous[item.id], prev.slots.count == item.slots.count {
+                    indices = prev.indices
+                } else {
+                    indices = (0 ..< item.slots.count).map { next + $0 }
+                    next += item.slots.count
+                }
+                if let first = indices.first, first <= lastIndex { repack = true; break }
+                lastIndex = indices.last ?? lastIndex
+                assigned.append(indices)
+            }
+            if next > Self.maxSlots { repack = true }
+        }
+        if repack {
+            assigned.removeAll()
+            var next = 0
+            for item in desired {
+                assigned.append((0 ..< item.slots.count).map { next + $0 })
+                next += item.slots.count
+            }
+        }
+
+        var ops = Data()
+        if !repack {
+            let kept = Set(desired.map(\.id))
+            for state in elements where !kept.contains(state.id) {
+                for index in state.indices { ops.append(contentsOf: [1, UInt8(index)]) }
+            }
+        }
+        var committed: [ElementState] = []
+        for (item, indices) in zip(desired, assigned) {
+            let prev = repack ? nil : previous[item.id]
+            for (k, slot) in item.slots.enumerated() {
+                let index = UInt8(indices[k])
+                if let prev, prev.slots.count == item.slots.count {
+                    let old = prev.slots[k]
+                    if old == slot { continue }
+                    if item.frames >= 2, let tween = Self.tweenRecord(from: old, to: slot, index: index,
+                                                                    frames: item.frames, curve: item.curve) {
+                        ops.append(tween)
+                        continue
+                    }
+                }
+                ops.append(Self.setRecord(slot, index: index))
+            }
+            committed.append(ElementState(id: item.id, contentHash: item.contentHash, slots: item.slots, indices: indices))
+        }
+
+        var payload = Data([17, repack ? 0x03 : 0x01, 0])
+        payload.append(ops)
+        elements = committed
+        needsRepack = false
+        return Encoded(payload: payload, uploads: cache.takeUploadPayloads())
+    }
+
+    /// `[0][slot][type][flags=visible][color][width][p0..p7 LE]`
+    static func setRecord(_ slot: Slot, index: UInt8) -> Data {
+        var out = Data([0, index, slot.type, 1, slot.color, slot.width])
+        for value in slot.params {
+            let bits = UInt16(bitPattern: value)
+            out.append(UInt8(bits & 0xFF))
+            out.append(UInt8(bits >> 8))
+        }
+        return out
+    }
+
+    /// `[5][slot][mask:u16][frames][curve x4][value:i16 per set bit]`, or nil when the
+    /// change is not a pure geometry/stroke change of the same shape type.
+    static func tweenRecord(from old: Slot, to new: Slot, index: UInt8, frames: UInt8, curve: [UInt8]) -> Data? {
+        guard old.type == new.type else { return nil }
+        let tweenable = tweenableMask(new.type)
+        var mask: UInt16 = 0
+        var values: [Int16] = []
+        for k in 0 ..< 8 where old.params[k] != new.params[k] {
+            guard tweenable & (1 << k) != 0 else { return nil }
+            mask |= 1 << k
+            values.append(new.params[k])
+        }
+        let isTexture = new.type >= ShapeType.image.rawValue
+        if old.color != new.color {
+            guard !isTexture else { return nil }
+            mask |= 0x100
+            values.append(Int16(new.color))
+        }
+        if old.width != new.width {
+            guard !isTexture else { return nil }
+            mask |= 0x200
+            values.append(Int16(new.width))
+        }
+        guard mask != 0 else { return nil }
+        var out = Data([5, index, UInt8(mask & 0xFF), UInt8(mask >> 8), frames])
+        out.append(contentsOf: curve.prefix(4))
+        for value in values {
+            let bits = UInt16(bitPattern: value)
+            out.append(UInt8(bits & 0xFF))
+            out.append(UInt8(bits >> 8))
+        }
+        return out
+    }
+}

package/ios/Source/sgcs/G2CfwTextureCache.swift

@@ -133,6 +133,16 @@ final class G2CfwTextureCache {
         return offset
     }
 
+    /// The cache offset of a raw byte string (builtin-font text for scene TEXT
+    /// slots), uploading it on first use.
+    func ensureBytes(key: String, bytes: [UInt8]) -> Int? {
+        if let offset = images[key] { return offset }
+        guard !bytes.isEmpty, let offset = allocate(bytes.count) else { return nil }
+        images[key] = offset
+        pendingUploads.append((offset: offset, data: Data(bytes)))
+        return offset
+    }
+
     /// Drain the pending mode-12 entries into `[12][offset16][len16][data]...`
     /// payloads, each at most `maxUploadPayloadBytes`. An entry larger than
     /// the budget gets a payload of its own (the BLE fragmenter splits it).

package/ios/Source/sgcs/G2Flasher.swift

@@ -37,8 +37,8 @@ enum 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
         ),
     ]
 

package/ios/Source/sgcs/SGCManager.swift

@@ -5,7 +5,7 @@ import Foundation
 /// against the previous frame sent to this device.
 struct SceneElement: Sendable {
     let id: String
-    let type: String // "text" | "rect" | "image"
+    let type: String // "text" | "rect" | "image" | "circle" | "arc" | "pie" | "line" | "triangle" | "quad" | "bezier"
     let x: Int32
     let y: Int32
     let w: Int32
@@ -20,11 +20,24 @@ struct SceneElement: Sendable {
     /// height (grid text); anything else is the default proportional face.
     let font: String
     let fontSize: Int32
+    /// Shapes: solid fill instead of an outline.
+    let fill: Bool
+    /// Gray level 0..15, or -1 for the default (brightest).
+    let color: Int32
+    /// Point shapes: x0, y0, x1, y1, … in canvas pixels.
+    let points: [Int32]
+    let startDeg: Int32
+    let endDeg: Int32
+    /// Transition duration in ms (0 = none) and easing name.
+    let transitionMs: Int32
+    let easing: String
 
     init(
         id: String, type: String, x: Int32, y: Int32, w: Int32, h: Int32, text: String?, data: String?,
         border: Int32, radius: Int32, change: String, contentHash: String,
-        font: String = "default", fontSize: Int32 = 0
+        font: String = "default", fontSize: Int32 = 0,
+        fill: Bool = false, color: Int32 = -1, points: [Int32] = [], startDeg: Int32 = 0, endDeg: Int32 = 0,
+        transitionMs: Int32 = 0, easing: String = "ease"
     ) {
         self.id = id
         self.type = type
@@ -40,13 +53,31 @@ struct SceneElement: Sendable {
         self.contentHash = contentHash
         self.font = font
         self.fontSize = fontSize
+        self.fill = fill
+        self.color = color
+        self.points = points
+        self.startDeg = startDeg
+        self.endDeg = endDeg
+        self.transitionMs = transitionMs
+        self.easing = easing
     }
 
     func with(change: String) -> SceneElement {
         SceneElement(
             id: id, type: type, x: x, y: y, w: w, h: h, text: text, data: data,
             border: border, radius: radius, change: change, contentHash: contentHash,
-            font: font, fontSize: fontSize
+            font: font, fontSize: fontSize, fill: fill, color: color, points: points,
+            startDeg: startDeg, endDeg: endDeg, transitionMs: transitionMs, easing: easing
+        )
+    }
+
+    /// The same element placed at the canvas origin (for standalone rasterization).
+    func atOrigin() -> SceneElement {
+        SceneElement(
+            id: id, type: type, x: 0, y: 0, w: w, h: h, text: text, data: data,
+            border: border, radius: radius, change: change, contentHash: contentHash,
+            font: font, fontSize: fontSize, fill: fill, color: color, points: points,
+            startDeg: startDeg, endDeg: endDeg, transitionMs: transitionMs, easing: easing
         )
     }
 }

package/ios/Tests/BluetoothSDKTests/G2CfwSceneTests.swift

@@ -0,0 +1,187 @@
+@testable import BluetoothSDK
+import Foundation
+import XCTest
+
+final class G2CfwSceneTests: XCTestCase {
+    private func element(
+        _ id: String, type: String, x: Int32 = 0, y: Int32 = 0, w: Int32 = 0, h: Int32 = 0,
+        text: String? = nil, border: Int32 = 0, radius: Int32 = 0, font: String = "default",
+        fill: Bool = false, color: Int32 = -1, points: [Int32] = [], startDeg: Int32 = 0, endDeg: Int32 = 0,
+        transitionMs: Int32 = 0, easing: String = "ease", hash: String = "h"
+    ) -> SceneElement {
+        SceneElement(
+            id: id, type: type, x: x, y: y, w: w, h: h, text: text, data: nil, border: border, radius: radius,
+            change: "created", contentHash: hash, font: font, fill: fill, color: color, points: points,
+            startDeg: startDeg, endDeg: endDeg, transitionMs: transitionMs, easing: easing
+        )
+    }
+
+    private func frame(_ elements: [SceneElement], replay: Bool = false) -> SceneFrame {
+        SceneFrame(appId: "app", epoch: 1, replay: replay, elements: elements, removed: [])
+    }
+
+    private func encode(_ scene: G2CfwScene, _ cache: G2CfwTextureCache, _ elements: [SceneElement],
+                        replay: Bool = false) -> G2CfwScene.Encoded? {
+        scene.encode(frame(elements, replay: replay), originX: 32, originY: 96, cache: cache) { el, w, h in
+            Data(repeating: 0xFF, count: w * h)
+        }
+    }
+
+    /// Little-endian int16 bytes of each value, concatenated.
+    private func le(_ values: Int...) -> [UInt8] {
+        var out: [UInt8] = []
+        for v in values {
+            let bits = UInt16(bitPattern: Int16(v))
+            out.append(UInt8(bits & 0xFF))
+            out.append(UInt8(bits >> 8))
+        }
+        return out
+    }
+
+    func testShapesBecomeSetRecordsWithOffsetGeometry() throws {
+        let scene = G2CfwScene()
+        let cache = G2CfwTextureCache()
+        cache.reset(generation: 1)
+        scene.reset(generation: 1)
+        let encoded = try XCTUnwrap(encode(scene, cache, [
+            element("l", type: "line", border: 3, color: 12, points: [10, 20, 30, 40]),
+            element("c", type: "circle", x: 100, y: 100, w: 41, h: 41, fill: true),
+            element("a", type: "arc", x: 0, y: 0, w: 101, h: 101, border: 4, startDeg: -90, endDeg: 180),
+            element("r", type: "rect", x: 1, y: 2, w: 30, h: 20, border: 2, radius: 6, fill: true),
+        ]))
+        XCTAssertTrue(encoded.uploads.isEmpty)
+        let bytes = [UInt8](encoded.payload)
+        // header: mode 17, COMMIT|CLEAR on the first (repack) frame, black background
+        XCTAssertEqual(Array(bytes[0 ..< 3]), [17, 0x03, 0])
+        // line at slot 0: type 1, visible, color 12, width 3, points shifted by the origin
+        XCTAssertEqual(Array(bytes[3 ..< 9]), [0, 0, 1, 1, 12, 3])
+        XCTAssertEqual(Array(bytes[9 ..< 17]), le(42, 116, 62, 136))
+        // filled circle at slot 1: center + radius from the box
+        let circle = 3 + 22
+        XCTAssertEqual(Array(bytes[circle ..< circle + 6]), [0, 1, 5, 1, 15, 0])
+        XCTAssertEqual(Array(bytes[circle + 6 ..< circle + 12]), le(152, 216, 20))
+        // arc at slot 2 keeps its angles
+        let arc = circle + 22
+        XCTAssertEqual(Array(bytes[arc ..< arc + 6]), [0, 2, 12, 1, 15, 4])
+        XCTAssertEqual(Array(bytes[arc + 12 ..< arc + 16]), le(-90, 180))
+        // filled rect with a border is two slots: fill then stroke
+        let rect = arc + 22
+        XCTAssertEqual(Array(bytes[rect ..< rect + 6]), [0, 3, 3, 1, 15, 0])
+        XCTAssertEqual(Array(bytes[rect + 22 ..< rect + 28]), [0, 4, 2, 1, 15, 2])
+        XCTAssertEqual(bytes.count, rect + 44)
+        XCTAssertEqual(scene.elements.map(\.indices), [[0], [1], [2], [3, 4]])
+    }
+
+    func testMovedElementWithTransitionBecomesTween() throws {
+        let scene = G2CfwScene()
+        let cache = G2CfwTextureCache()
+        cache.reset(generation: 1)
+        scene.reset(generation: 1)
+        _ = try XCTUnwrap(encode(scene, cache, [
+            element("ball", type: "circle", x: 0, y: 0, w: 21, h: 21, fill: true),
+        ]))
+        let next = try XCTUnwrap(encode(scene, cache, [
+            element("ball", type: "circle", x: 200, y: 0, w: 21, h: 21, fill: true, transitionMs: 330, easing: "linear"),
+        ]))
+        let bytes = [UInt8](next.payload)
+        XCTAssertEqual(Array(bytes[0 ..< 3]), [17, 0x01, 0])
+        // TWEEN slot 0, mask p0 only, 10 frames, linear curve, target x
+        XCTAssertEqual(Array(bytes[3 ..< 12]), [5, 0, 0x01, 0x00, 10, 0, 0, 255, 255])
+        XCTAssertEqual(Array(bytes[12 ..< 14]), le(242))
+        XCTAssertEqual(bytes.count, 14)
+    }
+
+    func testGeometryChangeWithoutTransitionAndTypeChangeReSet() throws {
+        let scene = G2CfwScene()
+        let cache = G2CfwTextureCache()
+        cache.reset(generation: 1)
+        scene.reset(generation: 1)
+        _ = try XCTUnwrap(encode(scene, cache, [element("s", type: "circle", w: 11, h: 11)]))
+        let moved = try XCTUnwrap(encode(scene, cache, [element("s", type: "circle", x: 5, w: 11, h: 11)]))
+        XCTAssertEqual([UInt8](moved.payload)[3 ..< 5], [0, 0])
+        let retyped = try XCTUnwrap(encode(scene, cache, [
+            element("s", type: "circle", x: 5, w: 11, h: 11, fill: true, transitionMs: 500),
+        ]))
+        XCTAssertEqual([UInt8](retyped.payload)[3 ..< 6], [0, 0, 5])
+    }
+
+    func testRemovalDeletesSlotsAndReorderRepacks() throws {
+        let scene = G2CfwScene()
+        let cache = G2CfwTextureCache()
+        cache.reset(generation: 1)
+        scene.reset(generation: 1)
+        _ = try XCTUnwrap(encode(scene, cache, [
+            element("a", type: "circle", w: 11, h: 11),
+            element("b", type: "circle", w: 11, h: 11),
+        ]))
+        let dropped = try XCTUnwrap(encode(scene, cache, [element("b", type: "circle", w: 11, h: 11)]))
+        XCTAssertEqual([UInt8](dropped.payload), [17, 0x01, 0, 1, 0])
+        XCTAssertEqual(scene.elements.map(\.indices), [[1]])
+        // "a" returns in front of "b": slot order would break paint order, so the frame repacks
+        let reordered = try XCTUnwrap(encode(scene, cache, [
+            element("a", type: "circle", w: 11, h: 11),
+            element("b", type: "circle", w: 11, h: 11),
+        ]))
+        XCTAssertEqual([UInt8](reordered.payload)[1], 0x03)
+        XCTAssertEqual(scene.elements.map(\.indices), [[0], [1]])
+    }
+
+    func testBuiltinTextAndRasterTilesUseTheTextureCache() throws {
+        let scene = G2CfwScene()
+        let cache = G2CfwTextureCache()
+        cache.reset(generation: 1)
+        scene.reset(generation: 1)
+        let encoded = try XCTUnwrap(encode(scene, cache, [
+            element("t", type: "text", x: 10, y: 10, w: 200, h: 60, text: "hi\nthere", font: "builtin"),
+            element("i", type: "image", x: 0, y: 0, w: 300, h: 10, hash: "img"),
+        ]))
+        XCTAssertEqual(encoded.uploads.count, 1)
+        // "hi" then "there" in the cache right after the zero guard
+        let expectedUpload: [UInt8] = [12, 2, 0, 2, 0, 0x68, 0x69, 4, 0, 5, 0]
+        XCTAssertEqual(Array(encoded.uploads[0].prefix(11)), expectedUpload)
+        let bytes = [UInt8](encoded.payload)
+        // two TEXT slots (27 px line pitch) + two IMAGE tiles (255 + 45 px)
+        XCTAssertEqual(scene.elements.map(\.indices), [[0, 1], [2, 3]])
+        XCTAssertEqual(Array(bytes[3 ..< 6]), [0, 0, 15])
+        XCTAssertEqual(Array(bytes[9 ..< 17]), le(42, 106, 2, 2))
+        let second = 3 + 22
+        XCTAssertEqual(Array(bytes[second + 6 ..< second + 14]), le(42, 133, 4, 5))
+        let tile2 = 3 + 3 * 22
+        XCTAssertEqual(Array(bytes[tile2 ..< tile2 + 3]), [0, 3, 14])
+        XCTAssertEqual(Array(bytes[tile2 + 6 ..< tile2 + 10]), le(32 + 255, 96))
+        // identical content re-renders without new uploads or ops
+        let again = try XCTUnwrap(encode(scene, cache, [
+            element("t", type: "text", x: 10, y: 10, w: 200, h: 60, text: "hi\nthere", font: "builtin"),
+            element("i", type: "image", x: 0, y: 0, w: 300, h: 10, hash: "img"),
+        ]))
+        XCTAssertTrue(again.uploads.isEmpty)
+        XCTAssertEqual([UInt8](again.payload), [17, 0x01, 0])
+    }
+
+    func testTooManySlotsOrFullCacheReturnsNil() {
+        let scene = G2CfwScene()
+        let cache = G2CfwTextureCache()
+        cache.reset(generation: 1)
+        scene.reset(generation: 1)
+        let many = (0 ..< 129).map { element("s\($0)", type: "circle", w: 11, h: 11) }
+        XCTAssertNil(encode(scene, cache, many))
+        let huge = element("big", type: "image", w: 2000, h: 2000, hash: "big")
+        let full = scene.encode(frame([huge]), originX: 0, originY: 0, cache: cache) { _, w, h in
+            var noise = Data(count: w * h)
+            for i in 0 ..< noise.count { noise[i] = UInt8(truncatingIfNeeded: i * 37) }
+            return noise
+        }
+        XCTAssertNil(full)
+    }
+
+    func testTextBytesStripControlsAndCutAtCodepoints() {
+        XCTAssertEqual(G2CfwScene.textBytes("a\u{01}b"), Array("ab".utf8))
+        let long = String(repeating: "é", count: 40) // 80 UTF-8 bytes
+        XCTAssertEqual(G2CfwScene.textBytes(long).count, 64)
+        XCTAssertEqual(G2CfwScene.transitionFrames(ms: 0), 0)
+        XCTAssertEqual(G2CfwScene.transitionFrames(ms: 10), 2)
+        XCTAssertEqual(G2CfwScene.transitionFrames(ms: 990), 30)
+        XCTAssertEqual(G2CfwScene.transitionFrames(ms: 60000), 255)
+        XCTAssertEqual(G2CfwScene.easingCurve("ease-in-out"), [107, 0, 148, 255])
+    }
+}