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

package/ios/Source/DeviceManager.swift

@@ -1,6 +1,5 @@
 //
 //  DeviceManager.swift
-//  Glassly_Manager
 //
 //  Created by Matthew Fosse on 3/5/25.
 //
@@ -254,7 +253,6 @@ struct ViewState {
         set { DeviceStore.shared.apply("bluetooth", "systemMicUnavailable", newValue) }
     }
 
-
     private var micEnabled: Bool {
         get { DeviceStore.shared.get("bluetooth", "micEnabled") as? Bool ?? false }
         set { DeviceStore.shared.apply("bluetooth", "micEnabled", newValue) }
@@ -305,7 +303,7 @@ struct ViewState {
     private var micReinitTimer: Timer?
 
     // STT:
-    #if !SWIFT_PACKAGE || GLASSLY_FEATURE_LOCAL_STT
+    #if !SWIFT_PACKAGE || FEATURE_LOCAL_STT
         private var transcriber: SherpaOnnxTranscriber?
     #endif
 
@@ -320,6 +318,28 @@ 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.
+    /// CFW scene drivers coalesce off the link themselves, so they bypass it too.
+    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)
+    }
+
+    /// CFW identity can land after device-ready, so this is re-read per update;
+    /// the flush variants fold any frame already held into the immediate send.
+    private var pacerBypassed: Bool {
+        sgc?.supportsCfwSceneRendering == true
+    }
+
+    /// 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()
@@ -327,23 +347,7 @@ struct ViewState {
         // Start memory monitoring (logs every 30s to help detect leaks)
         // MemoryMonitor.start()
 
-        // Initialize SherpaOnnx Transcriber
-        #if !SWIFT_PACKAGE || GLASSLY_FEATURE_LOCAL_STT
-            if let windowScene = UIApplication.shared.connectedScenes.first as? UIWindowScene,
-               let window = windowScene.windows.first,
-               let rootViewController = window.rootViewController
-            {
-                transcriber = SherpaOnnxTranscriber(context: rootViewController)
-            } else {
-                Bridge.log("Failed to create SherpaOnnxTranscriber - no root view controller found")
-            }
-
-            // Initialize the transcriber
-            if let transcriber = transcriber {
-                transcriber.initialize()
-                Bridge.log("SherpaOnnxTranscriber fully initialized")
-            }
-        #endif
+        // Local STT is created on demand after the model is available.
 
         // Initialize persistent LC3 converter for unified audio encoding
         lc3Converter = PcmConverter()
@@ -483,7 +487,7 @@ struct ViewState {
         SpeakerIdEngine.shared.acceptAudio(pcm16le: pcmData)
 
         // Send PCM to local transcriber.
-        #if !SWIFT_PACKAGE || GLASSLY_FEATURE_LOCAL_STT
+        #if !SWIFT_PACKAGE || FEATURE_LOCAL_STT
             if shouldSendTranscript || localSttFallbackActive {
                 transcriber?.acceptAudio(pcm16le: pcmData)
             }
@@ -669,6 +673,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()
@@ -693,12 +698,12 @@ struct ViewState {
         } else if wearable.contains(DeviceTypes.FRAME) {
             // sgc = FrameManager()
         }
-        #if !SWIFT_PACKAGE || GLASSLY_FEATURE_NEX
+        #if !SWIFT_PACKAGE || FEATURE_NEX
             if sgc == nil && wearable.contains(DeviceTypes.NEX) {
                 sgc = MentraNexSGC.getInstance()
             }
         #endif
-        #if !SWIFT_PACKAGE || GLASSLY_FEATURE_VUZIX
+        #if !SWIFT_PACKAGE || FEATURE_VUZIX
             if sgc == nil {
                 if wearable.contains(DeviceTypes.MACH1) {
                     sgc = Mach1()
@@ -811,6 +816,11 @@ struct ViewState {
 
     // MARK: - Native navigation (glasses-rendered nav UI, e.g. G2 service 0x08)
 
+    func glassesSensorControl(sensor: String, operation: String, options: [String: Double]) async -> Bool {
+        guard let g2 = sgc as? G2 else { return false }
+        return await g2.glassesSensorControl(sensor: sensor, operation: operation, options: options)
+    }
+
     func navigationModeStart() {
         sgc?.enterNavigationMode()
     }
@@ -1027,12 +1037,16 @@ struct ViewState {
         updateMicState()
     }
 
-    func restartTranscriber() {
-        #if !SWIFT_PACKAGE || GLASSLY_FEATURE_LOCAL_STT
+    func restartTranscriber() throws {
+        #if !SWIFT_PACKAGE || FEATURE_LOCAL_STT
             Bridge.log("MAN: Restarting SherpaOnnxTranscriber via command")
-            transcriber?.restart()
+            let nextTranscriber = transcriber ?? SherpaOnnxTranscriber()
+            try nextTranscriber.restart()
+            transcriber = nextTranscriber
         #else
-            Bridge.log("MAN: Local STT is not included in this SwiftPM build")
+            throw NSError(domain: "LocalSTT", code: 1, userInfo: [
+                NSLocalizedDescriptionKey: "Local STT is not included in this build",
+            ])
         #endif
     }
 
@@ -1310,7 +1324,11 @@ struct ViewState {
         }
 
         viewState = newViewState
-        sendCurrentState()
+        if layoutType == "clear_view" || pacerBypassed {
+            pacer.flushLegacy()
+        } else {
+            pacer.submitLegacy()
+        }
     }
 
     /// Parse + store a scene frame, then dispatch it.
@@ -1349,24 +1367,34 @@ struct ViewState {
             text: " ", data: nil, animationData: nil
         )
 
-        dispatchSceneFrame(frame)
+        if frame.elements.isEmpty || pacerBypassed {
+            pacer.flushScene(frame)
+        } else {
+            pacer.submitScene(frame)
+        }
     }
 
     /// Guarded scene dispatch - mirrors sendCurrentState's send conditions.
     private func dispatchSceneFrame(_ frame: SceneFrame) {
+        // Each early-out tells the host the frame won't show now; the SGC
+        // reports the rest once the device has it.
         if screenDisabled {
+            frame.reportPresented(false, reason: "screen off")
             return
         }
         // Native nav UI owns the display; the retained scene state (stored as
         // a replay frame above) repaints when navigation mode exits.
         if sgc?.navigationModeActive == true {
+            frame.reportPresented(false, reason: "navigation UI active")
             return
         }
         if sgc?.type.contains(DeviceTypes.SIMULATED) ?? true {
+            frame.reportPresented(false, reason: sgc == nil ? "no glasses" : "simulated glasses")
             return
         }
         guard sgc?.fullyBooted == true else {
             Bridge.log("MAN: dispatchSceneFrame(): sgc not ready")
+            frame.reportPresented(false, reason: "glasses not ready")
             return
         }
         Task { [weak self] in
@@ -1382,6 +1410,13 @@ struct ViewState {
                   let box = el["box"] as? [String: Any]
             else { return nil }
             let style = el["style"] as? [String: Any]
+            let transition = el["transition"] as? [String: Any]
+            let points = ((el["points"] as? [[String: Any]]) ?? []).flatMap { p -> [Int32] in
+                [(p["x"] as? NSNumber)?.int32Value ?? 0, (p["y"] as? NSNumber)?.int32Value ?? 0]
+            }
+            // Open strokes carry their width as `width`; closed shapes and boxes as `border`.
+            let border = ((style?["border"]) as? NSNumber)?.int32Value
+                ?? ((style?["width"]) as? NSNumber)?.int32Value ?? 0
             return SceneElement(
                 id: id,
                 type: type,
@@ -1391,13 +1426,28 @@ struct ViewState {
                 h: (box["h"] as? NSNumber)?.int32Value ?? 0,
                 text: (el["text"] as? String).map { parsePlaceholders($0) },
                 data: el["data"] as? String,
-                border: ((style?["border"]) as? NSNumber)?.int32Value ?? 0,
+                border: border,
                 radius: ((style?["radius"]) as? NSNumber)?.int32Value ?? 0,
                 change: el["change"] as? String ?? "created",
                 contentHash: el["contentHash"] as? String ?? "",
                 font: (style?["font"] as? String) ?? "default",
-                fontSize: ((style?["fontSize"]) as? NSNumber)?.int32Value ?? 0
+                fontSize: ((style?["fontSize"]) as? NSNumber)?.int32Value ?? 0,
+                fill: (style?["fill"] as? Bool) ?? false,
+                color: ((style?["color"]) as? NSNumber)?.int32Value ?? -1,
+                points: points,
+                startDeg: (el["startDeg"] as? NSNumber)?.int32Value ?? 0,
+                endDeg: (el["endDeg"] as? NSNumber)?.int32Value ?? 0,
+                transitionMs: (transition?["durationMs"] as? NSNumber)?.int32Value ?? 0,
+                easing: (transition?["easing"] as? String) ?? "ease",
+                path: ((el["path"] as? [NSNumber]) ?? []).map { UInt8(clamping: $0.intValue) },
+                pathScale: (el["pathScale"] as? NSNumber)?.int32Value ?? 256,
+                fillRule: (el["fillRule"] as? String) == "evenodd" ? 1 : 0,
+                rotationQ8: Int32(max(-9_216_000, min(9_216_000, ((el["rotation"] as? NSNumber)?.doubleValue ?? 0) * 256))),
+                pivotX: ((el["pivot"] as? [String: Any])?["x"] as? NSNumber)?.int32Value,
+                pivotY: ((el["pivot"] as? [String: Any])?["y"] as? NSNumber)?.int32Value,
+                depth: (el["depth"] as? NSNumber)?.int32Value ?? 0
             )
+
         }
         let canvas = sceneMap["canvas"] as? [String: Any]
         return SceneFrame(
@@ -1407,7 +1457,8 @@ struct ViewState {
             elements: elements,
             removed: (sceneMap["removed"] as? [String]) ?? [],
             canvasWidth: (canvas?["width"] as? NSNumber)?.int32Value ?? 0,
-            canvasHeight: (canvas?["height"] as? NSNumber)?.int32Value ?? 0
+            canvasHeight: (canvas?["height"] as? NSNumber)?.int32Value ?? 0,
+            seq: (sceneMap["seq"] as? NSNumber)?.intValue ?? 0
         )
     }
 
@@ -1644,6 +1695,58 @@ struct ViewState {
         return try await g2.startFirmwareFlash(target: target)
     }
 
+    // MARK: - BLE keyboard bridge (G2 Glassly CFW revision 39+)
+
+    private func requireG2ForKeyboard() throws -> G2 {
+        guard let g2 = sgc as? G2 else {
+            throw G2KeyboardBridge.BridgeError(description: "The keyboard bridge needs connected G2 glasses.")
+        }
+        return g2
+    }
+
+    func g2KeyboardScan() async throws -> [[String: Any]] {
+        try await requireG2ForKeyboard().keyboardScan()
+    }
+
+    func g2KeyboardConnect(address: String, addressType: Int, name: String) async throws {
+        try await requireG2ForKeyboard().keyboardConnect(address: address, addressType: addressType, name: name)
+    }
+
+    func g2KeyboardReconnect() async throws {
+        try await requireG2ForKeyboard().keyboardReconnect()
+    }
+
+    func g2KeyboardDisconnect() async throws {
+        guard let g2 = sgc as? G2 else { return }
+        try await g2.keyboardDisconnect()
+    }
+
+    func g2KeyboardForget() async {
+        if let g2 = sgc as? G2 {
+            await g2.keyboardForget()
+        } else {
+            // No live G2 driver: drop the remembered identity directly.
+            UserDefaults.standard.removeObject(forKey: "g2_keyboard")
+            DeviceStore.shared.apply("glasses", "keyboardSaved", false)
+            DeviceStore.shared.apply("glasses", "keyboardName", "")
+        }
+    }
+
+    func g2KeyboardPasskey(_ pin: Int) async throws {
+        try await requireG2ForKeyboard().keyboardPasskey(pin)
+    }
+
+    func g2KeyboardCompare(_ accept: Bool) async throws {
+        try await requireG2ForKeyboard().keyboardCompare(accept)
+    }
+
+    func g2KeyboardStatus() async -> [String: Any] {
+        guard let g2 = sgc as? G2 else {
+            return ["keyboardBridge": false, "keyboardConnected": false, "keyboardState": "idle"]
+        }
+        return await g2.keyboardStatus()
+    }
+
     /// Send shutdown command to glasses.
     /// This will initiate a graceful shutdown of the device.
     func sendShutdown() {
@@ -1686,6 +1789,16 @@ struct ViewState {
     func setMicState() {
         let willSendPcm = shouldSendPcm || shouldSendLc3
         let willSendTranscript = shouldSendTranscript || localSttFallbackActive
+        #if !SWIFT_PACKAGE || FEATURE_LOCAL_STT
+            // Direct SDK users can request transcripts without the JS coordinator.
+            if willSendTranscript, transcriber == nil {
+                do {
+                    try restartTranscriber()
+                } catch {
+                    Bridge.log("MAN: Local STT startup failed: \(error.localizedDescription)")
+                }
+            }
+        #endif
         // Speaker enrollment records through whichever mic is currently
         // ranked active, so it holds the mic open like any other consumer.
         micEnabled = willSendPcm || willSendTranscript || speakerEnrollmentActive
@@ -1933,6 +2046,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
@@ -1952,6 +2066,10 @@ struct ViewState {
         DeviceStore.shared.apply("glasses", "leftMacAddress", "")
         DeviceStore.shared.apply("glasses", "rightMacAddress", "")
         DeviceStore.shared.apply("glasses", "macAddress", "")
+        // The CFW scene canvas is published per classification; a G1/Nex paired
+        // next must not inherit the G2's 576x288 canvas and lifted element caps.
+        DeviceStore.shared.apply("glasses", "sceneCanvasWidth", 0)
+        DeviceStore.shared.apply("glasses", "sceneCanvasHeight", 0)
         DeviceStore.shared.apply("glasses", "fullyBooted", false)
         DeviceStore.shared.apply("glasses", "connected", false)
         DeviceStore.shared.apply("glasses", "connectionState", ConnTypes.DISCONNECTED)
@@ -2041,7 +2159,7 @@ struct ViewState {
 
     func cleanup() {
         // Clean up transcriber resources
-        #if !SWIFT_PACKAGE || GLASSLY_FEATURE_LOCAL_STT
+        #if !SWIFT_PACKAGE || FEATURE_LOCAL_STT
             transcriber?.shutdown()
             transcriber = nil
         #endif

package/ios/Source/DeviceStore.swift

@@ -34,6 +34,9 @@ class DeviceStore {
         store.set("glasses", "caseRemoved", true)
         store.set("glasses", "caseOpen", true)
         store.set("glasses", "caseCharging", false)
+        store.set("glasses", "ringConnected", false)
+        store.set("glasses", "ringBatteryLevel", -1)
+        store.set("glasses", "ringCharging", false)
         store.set("glasses", "caseBatteryLevel", -1)
         store.set("glasses", "headUp", false)
         store.set("glasses", "bluetoothMacAddress", "")
@@ -62,6 +65,14 @@ class DeviceStore {
         // iOS: whether a connected lens is authorized to read the phone's ANCS
         // notification stream (G2 consumes notifications on-firmware).
         store.set("glasses", "ancsAuthorized", false)
+        // G2 Glassly CFW keyboard bridge (revision 39+): availability on the
+        // connected firmware, the live keyboard link, and the remembered keyboard.
+        store.set("glasses", "keyboardBridge", false)
+        store.set("glasses", "keyboardConnected", false)
+        store.set("glasses", "keyboardName", "")
+        store.set("glasses", "keyboardSaved", false)
+        store.set("glasses", "keyboardState", "idle")
+        store.set("glasses", "keyboardError", "")
 
         // CORE STATE:
         store.set("bluetooth", "systemMicUnavailable", false)
@@ -112,15 +123,11 @@ class DeviceStore {
         store.set("bluetooth", "should_send_pcm", false)
         store.set("bluetooth", "should_send_lc3", false)
         store.set("bluetooth", "should_send_transcript", false)
-        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)
-        // G2 on-glass ANCS notification behavior + app filter (iOS).
-        store.set(
-            "bluetooth", "notification_ctrl",
-            ["enabled": true, "auto_display": true, "disp_time": 5, "avoid_disturb": true]
-        )
-        store.set("bluetooth", "notification_filter", ["enabled": false, "apps": [[String: Any]]()])
+        // Debug: G2 CFW fast BLE link profile (off = stock connection behaviour).
+        store.set("bluetooth", "cfw_fast_ble", false)
+        store.set("bluetooth", "display_max_fps", DisplayPacer.defaultFps)
     }
 
     func get(_ category: String, _ key: String) -> Any? {
@@ -202,7 +209,9 @@ class DeviceStore {
         // BLUETOOTH:
 
         case ("bluetooth", "brightness"):
-            let b = value as? Int ?? 50
+            // Read the stored (number-normalized) value: the bridge hands a
+            // Double, which `as? Int` rejects, and every level came out as 50.
+            let b = store.get("bluetooth", "brightness") as? Int ?? 50
             let auto = store.get("bluetooth", "auto_brightness") as? Bool ?? true
             Task {
                 DeviceManager.shared.sgc?.setBrightness(b, autoMode: auto)
@@ -231,6 +240,16 @@ class DeviceStore {
                 Task { await DeviceManager.shared.sgc?.cfwSceneRendererToggled(enabled) }
             }
 
+        case ("bluetooth", "cfw_fast_ble"):
+            if let enabled = value as? Bool, (oldValue as? Bool) != enabled {
+                Task { await DeviceManager.shared.sgc?.cfwFastBleToggled(enabled) }
+            }
+
+        case ("bluetooth", "display_max_fps"):
+            if let fps = value as? NSNumber {
+                DeviceManager.shared.setDisplayMaxFps(fps.intValue)
+            }
+
         case ("bluetooth", "dashboard_height"):
             scheduleDashboardHeightToGlasses()
 
@@ -257,12 +276,6 @@ class DeviceStore {
                 DeviceManager.shared.sgc?.sendCalendarEvents(items)
             }
 
-        case ("bluetooth", "notification_ctrl"):
-            DeviceManager.shared.sgc?.sendNotificationCtrl()
-
-        case ("bluetooth", "notification_filter"):
-            DeviceManager.shared.sgc?.sendNotificationFilter()
-
         case ("bluetooth", "metric_system"), ("bluetooth", "twelve_hour_time"):
             DeviceManager.shared.sgc?.sendDashboardDisplaySettings()
 
@@ -278,6 +291,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,180 @@
+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, seq: next.seq
+        )
+    }
+
+    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(reason: String = "cancelled") {
+        stopTimer()
+        pendingScene?.reportPresented(false, reason: reason)
+        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/GeneratedChangelogCatalog.swift

@@ -3,6 +3,15 @@ import Foundation
 /// Generated from /changelogs. Do not edit directly.
 let generatedReleaseChangelogs: [ReleaseChangelog] = [
     ReleaseChangelog(version: "3.2.0", markdown: "This release is under active development. User-facing changes will be documented as they land."),
-    ReleaseChangelog(version: "3.1.0", markdown: "Software updates are more reliable, with clearer progress and recovery when the glasses restart.\n\n- GlasslyOS, Glassly Engine, the Bluetooth SDK, and the glasses client now share one coordinated release version.\n- Mentra Live updates can continue across APK, system, and firmware restarts without asking the user to start the same update again.\n- Bluetooth photo capture and transfer diagnostics are more precise and less disruptive to normal glasses traffic."),
+    ReleaseChangelog(version: "3.1.0", markdown: "Software updates are more reliable, with clearer progress and recovery when the glasses restart.\n\n- Glassly, Glassly Engine, the Bluetooth SDK, and the glasses client now share one coordinated release version.\n- Mentra Live updates can continue across APK, system, and firmware restarts without asking the user to start the same update again.\n- Bluetooth photo capture and transfer diagnostics are more precise and less disruptive to normal glasses traffic."),
+    ReleaseChangelog(version: "0.2.8", markdown: "This release is under active development. User-facing changes will be documented as they land."),
+    ReleaseChangelog(version: "0.2.7", markdown: "This release is under active development. User-facing changes will be documented as they land."),
+    ReleaseChangelog(version: "0.2.6", markdown: "- Terminal follows light and dark mode, removes the on-glasses status badge, and uses font-scaled line spacing in the glasses session picker.\n- Notifications uses the explicit 5-second popup default and prevents text selection on iOS.\n- The session.display example removes the SVG and rotation demo."),
+    ReleaseChangelog(version: "0.2.5", markdown: "This release is under active development. User-facing changes will be documented as they land."),
+    ReleaseChangelog(version: "0.2.4", markdown: "This release is under active development. User-facing changes will be documented as they land."),
+    ReleaseChangelog(version: "0.2.3", markdown: "This release is under active development. User-facing changes will be documented as they land."),
+    ReleaseChangelog(version: "0.2.2", markdown: "This release is under active development. User-facing changes will be documented as they land."),
+    ReleaseChangelog(version: "0.2.1", markdown: "This release is under active development. User-facing changes will be documented as they land."),
+    ReleaseChangelog(version: "0.2.0", markdown: "The glasses UI on Glassly CFW is now a set of pages over one overlay: the dashboard, side menu, calendar, notification viewer and debug menu each stand on their own.\n\n- A phone notification shows the viewer on its own and closes back to whatever was on the glasses; it no longer opens the dashboard first, and the ignore-while-active hold is honoured everywhere on custom firmware.\n- Double tap on any page returns to the main content; head-down closes only the dashboard.\n- A debug menu on the dashboard (Debug Settings toggle) queries phone-side state such as isPhoneActive().\n- The metric toggle moved to Appearance, and miniapps can read the host's preferences.\n- Messenger group threads show on the notification title row."),
     ReleaseChangelog(version: "0.1.0", markdown: "First coordinated Glassly release: the app, Glassly Engine, and the Bluetooth SDK now ship one shared release version.\n\n- The Glassly App, Glassly Engine, and the Bluetooth SDK are versioned and published together.\n- Mentra Live updates can continue across APK, system, and firmware restarts without asking the user to start the same update again.\n- Bluetooth photo capture and transfer diagnostics are more precise and less disruptive to normal glasses traffic."),
 ]

package/ios/Source/GeneratedReleaseMetadata.swift

@@ -2,10 +2,10 @@ 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.99"
-    static let releaseSetId = "glassly-0.1.0-dev.99"
-    static let sourceCommit = "2aeea5db8ad4e84303faf84a92d025f0d1930ebf"
+    static let familyBaseVersion = "0.2.8"
+    static let releaseIdentity = "0.2.8-dev.445"
+    static let releaseSetId = "glassly-0.2.8-dev.445"
+    static let sourceCommit = "7e82d274d259dc795d05a3aef988d261d871106a"
     static let otaManifestUrl = ""
     static let otaManifestSha256 = ""
 }