@glassly/bluetooth-sdk 0.1.0-dev.112 → 0.1.0-dev.114

package/android/src/test/java/com/glassly/bluetoothsdk/DisplayPacerTest.kt

@@ -0,0 +1,277 @@
+package com.glassly.bluetoothsdk
+
+import com.glassly.bluetoothsdk.sgcs.SceneElement
+import com.glassly.bluetoothsdk.sgcs.SceneFrame
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class DisplayPacerTest {
+    private class FakeScheduler : DisplayPacer.Scheduler {
+        var delay: Long? = null
+        var block: (() -> Unit)? = null
+        var scheduled = 0
+
+        override fun schedule(delayMs: Long, block: () -> Unit): () -> Unit {
+            scheduled++
+            delay = delayMs
+            this.block = block
+            return {
+                if (this.block === block) {
+                    this.block = null
+                    delay = null
+                }
+            }
+        }
+
+        fun fire() {
+            val b = block ?: error("no timer armed")
+            block = null
+            delay = null
+            b()
+        }
+    }
+
+    private class Harness(fps: Int = 8) {
+        var now = 1_000L
+        val scheduler = FakeScheduler()
+        val scenes = mutableListOf<SceneFrame>()
+        var legacySends = 0
+        val pacer =
+            DisplayPacer(
+                dispatchScene = { scenes.add(it) },
+                sendLegacy = { legacySends++ },
+                clock = { now },
+                scheduler = scheduler,
+            ).also { it.setMaxFps(fps) }
+    }
+
+    private fun element(id: String, change: String = "created", x: Int = 0) =
+        SceneElement(
+            id = id, type = "text", x = x, y = 0, w = 10, h = 10, text = id, data = null,
+            border = 0, radius = 0, change = change, contentHash = "h-$id",
+        )
+
+    private fun frame(
+        vararg elements: SceneElement,
+        removed: List<String> = emptyList(),
+        appId: String = "app",
+        replay: Boolean = false,
+        epoch: Int = 1,
+    ) = SceneFrame(appId = appId, epoch = epoch, replay = replay, elements = elements.toList(), removed = removed)
+
+    private fun SceneFrame.change(id: String) = elements.first { it.id == id }.change
+
+    @Test
+    fun firstSubmitSendsImmediately() {
+        val h = Harness()
+        h.pacer.submitScene(frame(element("a")))
+        assertEquals(1, h.scenes.size)
+        assertNull(h.scheduler.block)
+    }
+
+    @Test
+    fun secondSubmitInsideWindowIsHeldUntilTheSlot() {
+        val h = Harness(fps = 10) // 100 ms slots
+        h.pacer.submitScene(frame(element("a"), epoch = 1))
+        h.now += 30
+        h.pacer.submitScene(frame(element("a", change = "updated"), epoch = 2))
+        assertEquals(1, h.scenes.size)
+        assertEquals(70L, h.scheduler.delay)
+        h.now += 70
+        h.scheduler.fire()
+        assertEquals(2, h.scenes.size)
+        assertEquals(2, h.scenes[1].epoch)
+    }
+
+    @Test
+    fun rapidFramesCoalesceIntoOneMergedSend() {
+        val h = Harness(fps = 10)
+        h.pacer.submitScene(frame(element("a"), epoch = 1))
+        h.now += 10
+        h.pacer.submitScene(frame(element("a", change = "updated"), element("b", change = "created"), epoch = 2))
+        h.now += 10
+        h.pacer.submitScene(frame(element("a", change = "unchanged"), element("b", change = "moved", x = 5), epoch = 3))
+        h.now += 10
+        h.pacer.submitScene(
+            frame(element("a", change = "unchanged"), element("b", change = "unchanged", x = 5), epoch = 4),
+        )
+        assertEquals(1, h.scheduler.scheduled)
+        h.now += 70
+        h.scheduler.fire()
+        assertEquals(2, h.scenes.size)
+        val sent = h.scenes[1]
+        assertEquals(4, sent.epoch)
+        assertEquals("updated", sent.change("a"))
+        assertEquals("created", sent.change("b"))
+        assertEquals(5, sent.elements.first { it.id == "b" }.x)
+    }
+
+    @Test
+    fun updatedThenUnchangedBecomesUpdated() {
+        val h = Harness()
+        h.pacer.submitScene(frame(element("a")))
+        h.now += 1
+        h.pacer.submitScene(frame(element("a", change = "moved", x = 3)))
+        h.now += 1
+        h.pacer.submitScene(frame(element("a", change = "unchanged", x = 3)))
+        h.now += 200
+        h.scheduler.fire()
+        assertEquals("updated", h.scenes[1].change("a"))
+    }
+
+    @Test
+    fun removedThenRecreatedIdIsNotRemoved() {
+        val h = Harness()
+        h.pacer.submitScene(frame(element("a"), element("b")))
+        h.now += 1
+        h.pacer.submitScene(frame(element("a", change = "unchanged"), removed = listOf("b")))
+        h.now += 1
+        h.pacer.submitScene(frame(element("a", change = "unchanged"), element("b", change = "created")))
+        h.now += 200
+        h.scheduler.fire()
+        val sent = h.scenes[1]
+        assertTrue(sent.removed.isEmpty())
+        assertEquals("created", sent.change("b"))
+    }
+
+    @Test
+    fun pendingRemovesSurviveIntoTheMergedFrame() {
+        val h = Harness()
+        h.pacer.submitScene(frame(element("a"), element("b"), element("c")))
+        h.now += 1
+        h.pacer.submitScene(frame(element("a", change = "unchanged"), removed = listOf("b", "c")))
+        h.now += 1
+        h.pacer.submitScene(frame(element("a", change = "unchanged"), removed = listOf("c")))
+        h.now += 200
+        h.scheduler.fire()
+        assertEquals(listOf("b", "c"), h.scenes[1].removed)
+    }
+
+    @Test
+    fun appSwitchDiscardsPending() {
+        val h = Harness()
+        h.pacer.submitScene(frame(element("a"), appId = "one"))
+        h.now += 1
+        h.pacer.submitScene(frame(element("a", change = "updated"), removed = listOf("z"), appId = "one"))
+        h.now += 1
+        h.pacer.submitScene(frame(element("b", change = "created"), appId = "two", replay = true))
+        h.now += 200
+        h.scheduler.fire()
+        val sent = h.scenes[1]
+        assertEquals("two", sent.appId)
+        assertTrue(sent.removed.isEmpty())
+        assertEquals(listOf("b"), sent.elements.map { it.id })
+    }
+
+    @Test
+    fun emptyFrameFlushesImmediatelyWithPendingRemoves() {
+        val h = Harness()
+        h.pacer.submitScene(frame(element("a"), element("b")))
+        h.now += 1
+        h.pacer.submitScene(frame(element("a", change = "unchanged"), removed = listOf("b")))
+        h.now += 1
+        h.pacer.flushScene(frame(removed = listOf("a")))
+        assertEquals(2, h.scenes.size)
+        assertEquals(setOf("a", "b"), h.scenes[1].removed.toSet())
+        assertTrue(h.scenes[1].elements.isEmpty())
+        assertNull(h.scheduler.block)
+        // Nothing left pending: a later timer must not resend.
+        h.now += 200
+        h.pacer.setMaxFps(8)
+        assertEquals(2, h.scenes.size)
+    }
+
+    @Test
+    fun clearViewFlushesImmediatelyAndDropsPendingScene() {
+        val h = Harness()
+        h.pacer.submitScene(frame(element("a")))
+        h.now += 1
+        h.pacer.submitScene(frame(element("a", change = "updated")))
+        assertNotNull(h.scheduler.block)
+        h.pacer.flushLegacy()
+        assertEquals(1, h.legacySends)
+        assertEquals(1, h.scenes.size)
+        assertNull(h.scheduler.block)
+    }
+
+    @Test
+    fun legacyAfterSceneDropsThePendingScene() {
+        val h = Harness()
+        h.pacer.submitScene(frame(element("a")))
+        h.now += 1
+        h.pacer.submitScene(frame(element("a", change = "updated")))
+        h.now += 1
+        h.pacer.submitLegacy()
+        h.now += 200
+        h.scheduler.fire()
+        assertEquals(1, h.scenes.size)
+        assertEquals(1, h.legacySends)
+    }
+
+    @Test
+    fun sceneAfterLegacyDropsThePendingLegacy() {
+        val h = Harness()
+        h.pacer.submitLegacy()
+        assertEquals(1, h.legacySends)
+        h.now += 1
+        h.pacer.submitLegacy()
+        h.now += 1
+        h.pacer.submitScene(frame(element("a")))
+        h.now += 200
+        h.scheduler.fire()
+        assertEquals(1, h.legacySends)
+        assertEquals(1, h.scenes.size)
+    }
+
+    @Test
+    fun setMaxFpsRearmsAPendingTimer() {
+        val h = Harness(fps = 2) // 500 ms slots
+        h.pacer.submitScene(frame(element("a")))
+        h.now += 50
+        h.pacer.submitScene(frame(element("a", change = "updated")))
+        assertEquals(450L, h.scheduler.delay)
+        h.pacer.setMaxFps(20) // 50 ms slots: the slot is already due
+        assertEquals(2, h.scenes.size)
+        assertNull(h.scheduler.block)
+
+        h.now += 10
+        h.pacer.submitScene(frame(element("a", change = "updated")))
+        assertEquals(40L, h.scheduler.delay)
+        h.pacer.setMaxFps(10)
+        assertEquals(90L, h.scheduler.delay)
+        assertEquals(2, h.scenes.size)
+    }
+
+    @Test
+    fun cancelDropsPendingWithoutSending() {
+        val h = Harness()
+        h.pacer.submitScene(frame(element("a")))
+        h.now += 1
+        h.pacer.submitScene(frame(element("a", change = "updated")))
+        h.pacer.cancel()
+        assertNull(h.scheduler.block)
+        h.now += 200
+        h.pacer.setMaxFps(8)
+        assertEquals(1, h.scenes.size)
+        assertFalse(h.scheduler.block != null)
+    }
+
+    @Test
+    fun lateSubmitAfterTheSlotSendsMergedImmediately() {
+        val h = Harness(fps = 10)
+        h.pacer.submitScene(frame(element("a")))
+        h.now += 10
+        h.pacer.submitScene(frame(element("a", change = "updated"), element("b", change = "created")))
+        // The timer is late; a submit past the slot sends now with the pending fold.
+        h.now += 200
+        h.pacer.submitScene(frame(element("a", change = "unchanged"), element("b", change = "unchanged")))
+        assertEquals(2, h.scenes.size)
+        assertEquals("updated", h.scenes[1].change("a"))
+        assertEquals("created", h.scenes[1].change("b"))
+        assertNull(h.scheduler.block)
+    }
+}

package/android/src/test/java/com/glassly/bluetoothsdk/sgcs/G2CfwSceneTest.kt

@@ -35,8 +35,8 @@ class G2CfwSceneTest {
     private fun frame(elements: List<SceneElement>, replay: Boolean = false) =
         SceneFrame("app", 1, replay, elements, emptyList())
 
-    private fun encode(scene: G2CfwScene, cache: G2CfwTextureCache, elements: List<SceneElement>) =
-        scene.encode(frame(elements), 32, 96, cache) { _, w, h -> ByteArray(w * h) { 0xFF.toByte() } }
+    private fun encode(scene: G2CfwScene, cache: G2CfwTextureCache, elements: List<SceneElement>, inlineText: Boolean = false) =
+        scene.encode(frame(elements), 32, 96, cache, { _, w, h -> ByteArray(w * h) { 0xFF.toByte() } }, inlineText)
 
     private fun le(v: Int): List<Byte> = listOf((v and 0xFF).toByte(), ((v ushr 8) and 0xFF).toByte())
 
@@ -158,7 +158,7 @@ class G2CfwSceneTest {
         val (scene, cache) = fresh()
         assertNull(encode(scene, cache, (0 until 129).map { element("s$it", "circle", w = 11, h = 11) }))
         val huge = element("big", "image", w = 2000, h = 2000, hash = "big")
-        val full = scene.encode(frame(listOf(huge)), 0, 0, cache) { _, w, h -> ByteArray(w * h) { (it * 37).toByte() } }
+        val full = scene.encode(frame(listOf(huge)), 0, 0, cache, { _, w, h -> ByteArray(w * h) { (it * 37).toByte() } })
         assertNull(full)
     }
 
@@ -172,4 +172,38 @@ class G2CfwSceneTest {
         assertEquals(255, G2CfwScene.transitionFrames(60000))
         assertArrayEquals(intArrayOf(107, 0, 148, 255), G2CfwScene.easingCurve("ease-in-out"))
     }
+
+    @Test
+    fun inlineTextRecordsCarryTheirBytesAndAnimate() {
+        val (scene, cache) = fresh()
+        val mono = element("m", "text", y = 200, w = 100, h = 30, text = "grid", font = "mono", hash = "mono")
+        val first = requireNotNull(
+            encode(scene, cache, listOf(element("t", "text", x = 10, y = 10, w = 200, h = 60, text = "hi\nthere", color = 9), mono), true),
+        )
+        assertEquals(1, first.uploads.size)
+        assertEquals(listOf(listOf(0, 1), listOf(2)), scene.elements.map { it.indices })
+        val p = first.payload
+        assertEquals(listOf<Byte>(0, 0, 17, 1, 0x19, 0), bytes(p, 3, 9))
+        assertEquals(le(44) + le(108) + le(198) + le(58), bytes(p, 9, 17))
+        assertEquals(listOf<Byte>(2, 0x68, 0x69), bytes(p, 17, 20))
+        assertEquals(listOf<Byte>(0, 1, 17), bytes(p, 20, 23))
+        assertEquals(le(44) + le(135) + le(198) + le(31), bytes(p, 26, 34))
+        assertEquals("there".toByteArray().toList(), bytes(p, 35, 40))
+        assertEquals(0.toByte(), p[40])
+        assertEquals(14.toByte(), p[42])
+
+        val moved = requireNotNull(
+            encode(scene, cache, listOf(element("t", "text", x = 10, y = 40, w = 200, h = 60, text = "hi\nthere", color = 9, transitionMs = 330), mono), true),
+        )
+        assertEquals(listOf<Byte>(5, 0, 0x02, 0x00, 10), bytes(moved.payload, 3, 8))
+        val retexted = requireNotNull(
+            encode(scene, cache, listOf(element("t", "text", x = 10, y = 40, w = 200, h = 60, text = "ho\nthere", color = 9, transitionMs = 330), mono), true),
+        )
+        assertEquals(listOf<Byte>(0, 0, 17), bytes(retexted.payload, 3, 6))
+        val faded = requireNotNull(
+            encode(scene, cache, listOf(element("t", "text", x = 10, y = 40, w = 200, h = 60, text = "ho\nthere", color = 3, transitionMs = 330), mono), true),
+        )
+        assertEquals(listOf<Byte>(5, 0, 0x00, 0x01, 10), bytes(faded.payload, 3, 8))
+        assertEquals(le(0x13), bytes(faded.payload, 12, 14))
+    }
 }

package/build/generated/releaseMetadata.js

@@ -1,9 +1,9 @@
 export const BLUETOOTH_SDK_RELEASE_METADATA = Object.freeze({
     "schemaVersion": 1,
     "familyBaseVersion": "0.1.0",
-    "releaseIdentity": "0.1.0-dev.112",
-    "releaseSetId": "glassly-0.1.0-dev.112",
-    "sourceCommit": "385c3de9054122bf005790a6b1faf04d3117d512",
+    "releaseIdentity": "0.1.0-dev.114",
+    "releaseSetId": "glassly-0.1.0-dev.114",
+    "sourceCommit": "17263133b35c04f044ba0d3acd9f80efc81999d4",
     "otaManifestUrl": null,
     "otaManifestSha256": null
 });

package/build/generated/releaseMetadata.js.map

@@ -1 +1 @@
-{"version":3,"file":"releaseMetadata.js","sourceRoot":"","sources":["../../src/generated/releaseMetadata.ts"],"names":[],"mappings":"AAWA,MAAM,CAAC,MAAM,8BAA8B,GAA0C,MAAM,CAAC,MAAM,CAAC;IACjG,eAAe,EAAE,CAAC;IAClB,mBAAmB,EAAE,OAAO;IAC5B,iBAAiB,EAAE,eAAe;IAClC,cAAc,EAAE,uBAAuB;IACvC,cAAc,EAAE,0CAA0C;IAC1D,gBAAgB,EAAE,IAAI;IACtB,mBAAmB,EAAE,IAAI;CAC1B,CAAC,CAAA","sourcesContent":["/** Generated by release CI. Do not edit in a release checkout. */\nexport interface BluetoothSdkReleaseMetadata {\n  schemaVersion: 1\n  familyBaseVersion: string | null\n  releaseIdentity: string | null\n  releaseSetId: string | null\n  sourceCommit: string | null\n  otaManifestUrl: string | null\n  otaManifestSha256: string | null\n}\n\nexport const BLUETOOTH_SDK_RELEASE_METADATA: Readonly<BluetoothSdkReleaseMetadata> = Object.freeze({\n  \"schemaVersion\": 1,\n  \"familyBaseVersion\": \"0.1.0\",\n  \"releaseIdentity\": \"0.1.0-dev.112\",\n  \"releaseSetId\": \"glassly-0.1.0-dev.112\",\n  \"sourceCommit\": \"385c3de9054122bf005790a6b1faf04d3117d512\",\n  \"otaManifestUrl\": null,\n  \"otaManifestSha256\": null\n})\n"]}
+{"version":3,"file":"releaseMetadata.js","sourceRoot":"","sources":["../../src/generated/releaseMetadata.ts"],"names":[],"mappings":"AAWA,MAAM,CAAC,MAAM,8BAA8B,GAA0C,MAAM,CAAC,MAAM,CAAC;IACjG,eAAe,EAAE,CAAC;IAClB,mBAAmB,EAAE,OAAO;IAC5B,iBAAiB,EAAE,eAAe;IAClC,cAAc,EAAE,uBAAuB;IACvC,cAAc,EAAE,0CAA0C;IAC1D,gBAAgB,EAAE,IAAI;IACtB,mBAAmB,EAAE,IAAI;CAC1B,CAAC,CAAA","sourcesContent":["/** Generated by release CI. Do not edit in a release checkout. */\nexport interface BluetoothSdkReleaseMetadata {\n  schemaVersion: 1\n  familyBaseVersion: string | null\n  releaseIdentity: string | null\n  releaseSetId: string | null\n  sourceCommit: string | null\n  otaManifestUrl: string | null\n  otaManifestSha256: string | null\n}\n\nexport const BLUETOOTH_SDK_RELEASE_METADATA: Readonly<BluetoothSdkReleaseMetadata> = Object.freeze({\n  \"schemaVersion\": 1,\n  \"familyBaseVersion\": \"0.1.0\",\n  \"releaseIdentity\": \"0.1.0-dev.114\",\n  \"releaseSetId\": \"glassly-0.1.0-dev.114\",\n  \"sourceCommit\": \"17263133b35c04f044ba0d3acd9f80efc81999d4\",\n  \"otaManifestUrl\": null,\n  \"otaManifestSha256\": null\n})\n"]}

package/ios/Source/BluetoothSDK.swift

@@ -491,6 +491,7 @@ public final class BluetoothSDK {
     }
 
     public func clearDisplay() async throws {
+        DeviceManager.shared.cancelPendingDisplay()
         DeviceManager.shared.sgc?.clearDisplay()
     }
 

package/ios/Source/BluetoothSdkDefaults.swift

@@ -11,7 +11,7 @@ enum BluetoothSdkDefaults {
     static let voiceActivityDetectionEnabled = false
     static let loudnessGateEnabled = true
     private static let infoSdkVersionKey = "BluetoothSdkVersion"
-    private static let swiftPackageSdkVersion = "0.1.0-dev.112"
+    private static let swiftPackageSdkVersion = "0.1.0-dev.114"
     private static let swiftPackageSdkVersionPlaceholder = "__GLASSLY" + "_BLUETOOTH_SDK_VERSION__"
 
     private static func normalizedSdkVersion(_ value: String?) -> String? {

package/ios/Source/DeviceManager.swift

@@ -320,6 +320,21 @@ struct ViewState {
     /// native re-dispatch coherent (nav exit re-applies a complete scene).
     var sceneState: SceneFrame?
 
+    /// Paces scene frames and legacy layouts to display_max_fps; clears bypass it.
+    private lazy var pacer = DisplayPacer(
+        dispatchScene: { [weak self] frame in self?.dispatchSceneFrame(frame) },
+        sendLegacy: { [weak self] in self?.sendCurrentState() }
+    )
+
+    func setDisplayMaxFps(_ fps: Int) {
+        pacer.setMaxFps(fps)
+    }
+
+    /// Drop paced display work (screen off): the retained state repaints on re-enable.
+    func cancelPendingDisplay() {
+        pacer.cancel()
+    }
+
     override init() {
         Bridge.log("MAN: init()")
         super.init()
@@ -669,6 +684,7 @@ struct ViewState {
         Bridge.log("Initializing manager for wearable: \(wearable)")
         if sgc != nil && sgc?.type != wearable {
             Bridge.log("MAN: Manager already initialized, cleaning up previous sgc")
+            pacer.cancel()
             sgc?.cleanup()
             sgc = nil
             resetSystemTimeSync()
@@ -1310,7 +1326,11 @@ struct ViewState {
         }
 
         viewState = newViewState
-        sendCurrentState()
+        if layoutType == "clear_view" {
+            pacer.flushLegacy()
+        } else {
+            pacer.submitLegacy()
+        }
     }
 
     /// Parse + store a scene frame, then dispatch it.
@@ -1349,7 +1369,11 @@ struct ViewState {
             text: " ", data: nil, animationData: nil
         )
 
-        dispatchSceneFrame(frame)
+        if frame.elements.isEmpty {
+            pacer.flushScene(frame)
+        } else {
+            pacer.submitScene(frame)
+        }
     }
 
     /// Guarded scene dispatch - mirrors sendCurrentState's send conditions.
@@ -1947,6 +1971,7 @@ struct ViewState {
     }
 
     func disconnect(clearPendingConnection: Bool = true) {
+        pacer.cancel()
         sgc?.clearDisplay() // clear the screen
         sgc?.disconnect()
         sgc = nil // Clear the SGC reference after disconnect

package/ios/Source/DeviceStore.swift

@@ -115,6 +115,7 @@ class DeviceStore {
         store.set("bluetooth", "use_native_dashboard", false)
         // Debug escape hatch: G2 CFW direct-framebuffer rendering (off = stock containers).
         store.set("bluetooth", "cfw_scene_renderer", true)
+        store.set("bluetooth", "display_max_fps", DisplayPacer.defaultFps)
         // G2 on-glass ANCS notification behavior + app filter (iOS).
         store.set(
             "bluetooth", "notification_ctrl",
@@ -231,6 +232,11 @@ class DeviceStore {
                 Task { await DeviceManager.shared.sgc?.cfwSceneRendererToggled(enabled) }
             }
 
+        case ("bluetooth", "display_max_fps"):
+            if let fps = value as? NSNumber {
+                DeviceManager.shared.setDisplayMaxFps(fps.intValue)
+            }
+
         case ("bluetooth", "dashboard_height"):
             scheduleDashboardHeightToGlasses()
 
@@ -278,6 +284,7 @@ class DeviceStore {
         case ("bluetooth", "screen_disabled"):
             if let disabled = value as? Bool {
                 if disabled {
+                    DeviceManager.shared.cancelPendingDisplay()
                     DeviceManager.shared.sgc?.exit()
                 } else {
                     DeviceManager.shared.sgc?.clearDisplay()

package/ios/Source/DisplayPacer.swift

@@ -0,0 +1,179 @@
+import Foundation
+
+/// Paces display updates leaving the phone to at most `setMaxFps` per second.
+///
+/// Updates that arrive inside the current slot are held and sent at the next
+/// one, last-wins: a newer scene frame replaces a pending one (with the pending
+/// frame's per-element annotations folded in so per-element devices never miss
+/// a change), a legacy layout replaces a pending scene and vice versa. Clears
+/// (`flushScene` with an empty frame, `flushLegacy`) bypass the pacer and drop
+/// pending work.
+@MainActor
+final class DisplayPacer {
+    /// Runs `block` after `delayMs`; the returned closure cancels it.
+    typealias Scheduler = (_ delayMs: Int64, _ block: @escaping @MainActor () -> Void) -> () -> Void
+
+    static let minFps = 2
+    static let maxFps = 20
+    static let defaultFps = 8
+
+    static func interval(forFps fps: Int) -> Int64 {
+        Int64(1000 / min(max(fps, minFps), maxFps))
+    }
+
+    static func monotonicMs() -> Int64 {
+        Int64(DispatchTime.now().uptimeNanoseconds / 1_000_000)
+    }
+
+    static func taskScheduler(_ delayMs: Int64, _ block: @escaping @MainActor () -> Void) -> () -> Void {
+        let task = Task { @MainActor in
+            try? await Task.sleep(nanoseconds: UInt64(max(0, delayMs)) * 1_000_000)
+            if Task.isCancelled { return }
+            block()
+        }
+        return { task.cancel() }
+    }
+
+    /// Fold pending frame `previous` into `next` (both unsent). The device only
+    /// ever sees the merged frame, so an element the pending frame changed must
+    /// not read as "unchanged" in the merged one, and ids the pending frame
+    /// removed must still be removed unless `next` re-creates them. A different
+    /// app is already a from-scratch replay.
+    static func merge(_ previous: SceneFrame?, into next: SceneFrame) -> SceneFrame {
+        guard let previous, previous.appId == next.appId else { return next }
+        var pending: [String: SceneElement] = [:]
+        for el in previous.elements { pending[el.id] = el }
+        let elements = next.elements.map { el -> SceneElement in
+            guard let prior = pending[el.id] else { return el }
+            if prior.change == "created" { return el.with(change: "created") }
+            if prior.change != "unchanged", el.change == "unchanged" { return el.with(change: "updated") }
+            return el
+        }
+        let painted = Set(next.elements.map(\.id))
+        var seen = Set<String>()
+        var removed: [String] = []
+        for id in previous.removed + next.removed where !painted.contains(id) && seen.insert(id).inserted {
+            removed.append(id)
+        }
+        return SceneFrame(
+            appId: next.appId, epoch: next.epoch, replay: previous.replay || next.replay,
+            elements: elements, removed: removed,
+            canvasWidth: next.canvasWidth, canvasHeight: next.canvasHeight
+        )
+    }
+
+    private let dispatchScene: (SceneFrame) -> Void
+    private let sendLegacy: () -> Void
+    private let clock: () -> Int64
+    private let scheduler: Scheduler
+
+    private var intervalMs: Int64 = DisplayPacer.interval(forFps: DisplayPacer.defaultFps)
+    private var lastSendAt: Int64 = Int64.min / 2
+    private var pendingScene: SceneFrame?
+    private var pendingLegacy = false
+    private var cancelTimer: (() -> Void)?
+
+    init(
+        dispatchScene: @escaping (SceneFrame) -> Void,
+        sendLegacy: @escaping () -> Void,
+        clock: @escaping () -> Int64 = DisplayPacer.monotonicMs,
+        scheduler: @escaping Scheduler = DisplayPacer.taskScheduler
+    ) {
+        self.dispatchScene = dispatchScene
+        self.sendLegacy = sendLegacy
+        self.clock = clock
+        self.scheduler = scheduler
+    }
+
+    func setMaxFps(_ fps: Int) {
+        intervalMs = Self.interval(forFps: fps)
+        guard hasPending else { return }
+        stopTimer()
+        let now = clock()
+        if now - lastSendAt >= intervalMs {
+            take(now)?()
+        } else {
+            armTimer(now)
+        }
+    }
+
+    /// Send `frame` at the next slot; replaces any pending update.
+    func submitScene(_ frame: SceneFrame) {
+        let now = clock()
+        pendingScene = Self.merge(pendingScene, into: frame)
+        pendingLegacy = false
+        submitPending(now)
+    }
+
+    /// Send the current legacy view state at the next slot; replaces any pending update.
+    func submitLegacy() {
+        let now = clock()
+        pendingScene = nil
+        pendingLegacy = true
+        submitPending(now)
+    }
+
+    /// Immediate send for an empty (clearing) frame; pending removes ride along.
+    func flushScene(_ frame: SceneFrame) {
+        stopTimer()
+        let merged = Self.merge(pendingScene, into: frame)
+        pendingScene = nil
+        pendingLegacy = false
+        lastSendAt = clock()
+        dispatchScene(merged)
+    }
+
+    /// Immediate legacy send (clear_view); drops any pending scene.
+    func flushLegacy() {
+        stopTimer()
+        pendingScene = nil
+        pendingLegacy = false
+        lastSendAt = clock()
+        sendLegacy()
+    }
+
+    /// Drop pending work without sending (disconnect, screen off, clearDisplay).
+    func cancel() {
+        stopTimer()
+        pendingScene = nil
+        pendingLegacy = false
+    }
+
+    private var hasPending: Bool { pendingScene != nil || pendingLegacy }
+
+    private func submitPending(_ now: Int64) {
+        if now - lastSendAt >= intervalMs {
+            stopTimer()
+            take(now)?()
+        } else if cancelTimer == nil {
+            armTimer(now)
+        }
+    }
+
+    private func stopTimer() {
+        cancelTimer?()
+        cancelTimer = nil
+    }
+
+    /// Consume pending work into a send closure and stamp the slot.
+    private func take(_ now: Int64) -> (() -> Void)? {
+        let scene = pendingScene
+        let legacy = pendingLegacy
+        pendingScene = nil
+        pendingLegacy = false
+        if scene == nil, !legacy { return nil }
+        lastSendAt = now
+        if let scene { return { self.dispatchScene(scene) } }
+        return { self.sendLegacy() }
+    }
+
+    /// Arm the single trailing timer for the next slot.
+    private func armTimer(_ now: Int64) {
+        let delay = max(0, lastSendAt + intervalMs - now)
+        cancelTimer = scheduler(delay) { [weak self] in
+            guard let self else { return }
+            self.cancelTimer = nil
+            self.take(self.clock())?()
+        }
+    }
+}

package/ios/Source/GeneratedReleaseMetadata.swift

@@ -3,9 +3,9 @@ import Foundation
 /// Generated by release CI. Do not edit in a release checkout.
 enum GeneratedReleaseMetadata {
     static let familyBaseVersion = "0.1.0"
-    static let releaseIdentity = "0.1.0-dev.112"
-    static let releaseSetId = "glassly-0.1.0-dev.112"
-    static let sourceCommit = "385c3de9054122bf005790a6b1faf04d3117d512"
+    static let releaseIdentity = "0.1.0-dev.114"
+    static let releaseSetId = "glassly-0.1.0-dev.114"
+    static let sourceCommit = "17263133b35c04f044ba0d3acd9f80efc81999d4"
     static let otaManifestUrl = ""
     static let otaManifestSha256 = ""
 }