@mentra/bluetooth-sdk 0.1.17 → 0.1.19

package/ios/Source/sgcs/MentraNex.swift

@@ -84,23 +84,230 @@ class MentraNexSGC: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate, SG
         await sendTextWall("\(top)\n\(bottom)")
     }
 
-    func displayBitmap(base64ImageData: String, x _: Int32? = nil, y _: Int32? = nil, width _: Int32? = nil, height _: Int32? = nil) async -> Bool {
+    func displayBitmap(base64ImageData: String, x _: Int32? = nil, y _: Int32? = nil, width: Int32? = nil, height: Int32? = nil) async -> Bool {
         guard let imageData = Data(base64Encoded: base64ImageData),
               let image = UIImage(data: imageData)
         else {
             Bridge.log("NEX: Failed to decode base64 image payload")
             return false
         }
-        guard let bmpData = convertUIImageToBmpData(image) else {
-            Bridge.log("NEX: Failed to convert UIImage to bitmap bytes")
+        // Same glasses-native pipeline as the canvas path: scale to the target
+        // size when given, invert + dither, encode a real 1-bit BMP (the old
+        // conversion emitted raw RGBA the firmware couldn't decode).
+        // Legacy callers can hand us zero/negative dims — clamp to the canvas
+        // so the scale/encode path can't divide by zero or allocate garbage.
+        let rawWidth = width ?? Int32(image.cgImage?.width ?? Int(image.size.width * image.scale))
+        let rawHeight = height ?? Int32(image.cgImage?.height ?? Int(image.size.height * image.scale))
+        let pixelWidth = min(max(rawWidth, 1), 500)
+        let pixelHeight = min(max(rawHeight, 1), 220)
+        let scaled = scaledImage(image, toWidth: pixelWidth, height: pixelHeight)
+        guard let bmpData = convertImageToNex1BitBmp(scaled) else {
+            Bridge.log("NEX: Failed to convert UIImage to 1-bit BMP")
             return false
         }
-        let pixelWidth = image.cgImage?.width ?? Int(image.size.width * image.scale)
-        let pixelHeight = image.cgImage?.height ?? Int(image.size.height * image.scale)
-        displayBitmapData(bmpData, width: pixelWidth, height: pixelHeight)
+        displayBitmapData(bmpData, width: Int(pixelWidth), height: Int(pixelHeight))
         return true
     }
 
+    // MARK: - Canvas scene verbs (display.render() pipeline)
+
+    // Retained-mode canvas registry: elementId → firmware component. Mirrors
+    // MentraNex.kt. Text ids come from the firmware pool 1–6, bitmaps from
+    // 10–13 (mos_display_canvas_view.c); insertion order drives real oldest-out
+    // eviction when a pool is exhausted.
+    private struct CanvasElement {
+        let firmwareId: UInt32
+        let isBitmap: Bool
+        var rect: String
+    }
+
+    private var canvasElements: [(key: String, value: CanvasElement)] = []
+    private var currentLayoutId: String?
+    private let canvasTextIdPool: [UInt32] = [1, 2, 3, 4, 5, 6]
+    private let canvasBitmapIdPool: [UInt32] = [10, 11, 12, 13]
+
+    private func canvasElementIndex(_ key: String) -> Int? {
+        canvasElements.firstIndex(where: { $0.key == key })
+    }
+
+    private func sendCanvasCommand(_ configure: (inout Mentraos_Ble_PhoneToGlasses) -> Void) {
+        var msg = Mentraos_Ble_PhoneToGlasses()
+        configure(&msg)
+        guard let data = try? msg.serializedData() else { return }
+        queueDataWithOptimalChunking(data, packetType: PACKET_TYPE_PROTOBUF, waitTimeMs: 10)
+    }
+
+    /**
+     Handle a scene/layout change. DeviceManager sweeps the previous app's
+     elements before a cross-app frame arrives, so the registry is usually empty
+     here and switching costs nothing. Stale components are deleted
+     individually, NOT via CanvasClear — clear also exits the canvas VIEW (the
+     first create re-activates it), which reads as a full-screen flash.
+     */
+    private func ensureLayout(_ layoutId: String?) {
+        guard let layoutId, layoutId != currentLayoutId else { return }
+        if !canvasElements.isEmpty {
+            for (_, el) in canvasElements {
+                sendCanvasCommand { $0.canvasDeleteComponent = .with { $0.id = el.firmwareId } }
+            }
+            canvasElements.removeAll()
+        }
+        currentLayoutId = layoutId
+    }
+
+    /// Replay frames repaint from scratch: forget the registry so every element
+    /// takes the CREATE path (create-on-existing-id is replace in firmware;
+    /// updates to dead component ids are dropped silently).
+    func onSceneReplay(_ appId: String) async {
+        canvasElements.removeAll()
+        currentLayoutId = appId
+    }
+
+    /// Free firmware id from the type's pool, evicting the oldest same-type
+    /// element (delete on glasses + registry) when the pool is exhausted.
+    private func allocFirmwareId(isBitmap: Bool) -> UInt32? {
+        let pool = isBitmap ? canvasBitmapIdPool : canvasTextIdPool
+        let used = Set(canvasElements.filter { $0.value.isBitmap == isBitmap }.map(\.value.firmwareId))
+        if let free = pool.first(where: { !used.contains($0) }) {
+            return free
+        }
+        guard let oldestIdx = canvasElements.firstIndex(where: { $0.value.isBitmap == isBitmap }) else {
+            return nil
+        }
+        let oldest = canvasElements.remove(at: oldestIdx)
+        Bridge.log("NEX: pool full — evicting oldest \(isBitmap ? "bitmap" : "text") element '\(oldest.key)' (fw id \(oldest.value.firmwareId))")
+        sendCanvasCommand { $0.canvasDeleteComponent = .with { $0.id = oldest.value.firmwareId } }
+        return oldest.value.firmwareId
+    }
+
+    func drawLayoutText(
+        _ text: String, x: Int32, y: Int32, width: Int32, height: Int32,
+        borderWidth: Int32, borderRadius: Int32, elementId: String, layoutId: String?
+    ) async {
+        ensureLayout(layoutId)
+        let rect = "\(x),\(y),\(width)x\(height),\(borderWidth),\(borderRadius)"
+        if let i = canvasElementIndex(elementId), !canvasElements[i].value.isBitmap {
+            let fid = canvasElements[i].value.firmwareId
+            if canvasElements[i].value.rect != rect {
+                // Geometry moved/restyled — recreate the box at the SAME
+                // firmware id (create-on-existing-id = replace), then set text.
+                sendCanvasCommand {
+                    $0.canvasCreateComponent = .with {
+                        $0.id = fid
+                        $0.type = .canvasTextbox
+                        $0.x = UInt32(max(0, x)); $0.y = UInt32(max(0, y))
+                        $0.width = UInt32(max(0, width)); $0.height = UInt32(max(0, height))
+                        $0.borderWidth = UInt32(max(0, borderWidth))
+                        $0.borderRadius = UInt32(max(0, borderRadius))
+                    }
+                }
+                canvasElements[i].value.rect = rect
+            }
+            sendCanvasCommand { $0.canvasUpdateText = .with { $0.id = fid; $0.text = self.sanitizeDisplayText(text) } }
+            return
+        }
+        guard let fid = allocFirmwareId(isBitmap: false) else {
+            Bridge.log("NEX: text pool exhausted — dropping element '\(elementId)'")
+            return
+        }
+        canvasElements.append((key: elementId, value: CanvasElement(firmwareId: fid, isBitmap: false, rect: rect)))
+        sendCanvasCommand {
+            $0.canvasCreateComponent = .with {
+                $0.id = fid
+                $0.type = .canvasTextbox
+                $0.x = UInt32(max(0, x)); $0.y = UInt32(max(0, y))
+                $0.width = UInt32(max(0, width)); $0.height = UInt32(max(0, height))
+                $0.borderWidth = UInt32(max(0, borderWidth))
+                $0.borderRadius = UInt32(max(0, borderRadius))
+            }
+        }
+        sendCanvasCommand { $0.canvasUpdateText = .with { $0.id = fid; $0.text = self.sanitizeDisplayText(text) } }
+    }
+
+    func drawLayoutBitmap(
+        base64ImageData: String, x: Int32, y: Int32, width: Int32, height: Int32,
+        elementId: String, layoutId: String?
+    ) async -> Bool {
+        ensureLayout(layoutId)
+        guard let imageData = Data(base64Encoded: base64ImageData),
+              let image = UIImage(data: imageData)
+        else {
+            Bridge.log("NEX: drawLayoutBitmap failed to decode base64 image")
+            return false
+        }
+        // Scale phone-side to the component box (never on glasses), then run
+        // the glasses-native pipeline: invert → Floyd–Steinberg dither → real
+        // 1-bit BMP encode (Android parity; the old convertUIImageToBmpData
+        // emitted raw RGBA, which the firmware BMP decoder can't read).
+        let scaled = scaledImage(image, toWidth: width, height: height)
+        guard let bmpData = convertImageToNex1BitBmp(scaled) else {
+            Bridge.log("NEX: drawLayoutBitmap failed to convert image")
+            return false
+        }
+
+        let rect = "\(x),\(y),\(width)x\(height)"
+        let fid: UInt32
+        if let i = canvasElementIndex(elementId), canvasElements[i].value.isBitmap {
+            fid = canvasElements[i].value.firmwareId
+            if canvasElements[i].value.rect != rect {
+                sendCanvasCommand {
+                    $0.canvasCreateComponent = .with {
+                        $0.id = fid
+                        $0.type = .canvasBitmap
+                        $0.x = UInt32(max(0, x)); $0.y = UInt32(max(0, y))
+                        $0.width = UInt32(max(0, width)); $0.height = UInt32(max(0, height))
+                    }
+                }
+                canvasElements[i].value.rect = rect
+            }
+        } else {
+            guard let allocated = allocFirmwareId(isBitmap: true) else {
+                Bridge.log("NEX: bitmap pool exhausted — dropping element '\(elementId)'")
+                return false
+            }
+            fid = allocated
+            canvasElements.append((key: elementId, value: CanvasElement(firmwareId: fid, isBitmap: true, rect: rect)))
+            sendCanvasCommand {
+                $0.canvasCreateComponent = .with {
+                    $0.id = fid
+                    $0.type = .canvasBitmap
+                    $0.x = UInt32(max(0, x)); $0.y = UInt32(max(0, y))
+                    $0.width = UInt32(max(0, width)); $0.height = UInt32(max(0, height))
+                }
+            }
+        }
+
+        // Stream pixels into the component: CanvasUpdateImage header, then the
+        // same 0xB0 chunk transport the legacy DisplayImage path uses.
+        let streamId = String(format: "%04X", Int.random(in: 0 ... 0xFFFF))
+        let totalChunks = Int(ceil(Double(bmpData.count) / Double(bmpChunkSize)))
+        sendCanvasCommand {
+            $0.canvasUpdateImage = .with {
+                $0.id = fid
+                $0.streamID = streamId
+                $0.totalChunks = UInt32(totalChunks)
+            }
+        }
+        sendImageChunks(streamId: streamId, imageData: bmpData)
+        return true
+    }
+
+    func removeLayoutElement(_ elementId: String, layoutId _: String?) async {
+        guard let i = canvasElementIndex(elementId) else { return }
+        let el = canvasElements.remove(at: i)
+        sendCanvasCommand { $0.canvasDeleteComponent = .with { $0.id = el.value.firmwareId } }
+    }
+
+    private func scaledImage(_ image: UIImage, toWidth width: Int32, height: Int32) -> UIImage {
+        let size = CGSize(width: CGFloat(max(1, width)), height: CGFloat(max(1, height)))
+        if image.size == size { return image }
+        UIGraphicsBeginImageContextWithOptions(size, false, 1)
+        image.draw(in: CGRect(origin: .zero, size: size))
+        let out = UIGraphicsGetImageFromCurrentImageContext() ?? image
+        UIGraphicsEndImageContext()
+        return out
+    }
+
     func showDashboard() {
         exit()
     }
@@ -247,6 +454,11 @@ class MentraNexSGC: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate, SG
     private var servicesReady = false
     private var serviceReadyWaiters: [CheckedContinuation<Void, Never>] = []
     private var pendingWriteContinuation: CheckedContinuation<Void, Never>?
+    // Separate from pendingWriteContinuation (which is flow-control for
+    // .withoutResponse): this one is resumed by didWriteValueFor, i.e. the ATT
+    // ack for a .withResponse write. Kept distinct so a peripheralIsReady
+    // flow-control callback can't spuriously resume an in-flight acked write.
+    private var pendingAckContinuation: CheckedContinuation<Void, Never>?
 
     // MARK: - Published Properties (G1-compatible)
 
@@ -360,11 +572,16 @@ class MentraNexSGC: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate, SG
         let chunks: [[UInt8]]
         let waitTimeMs: Int
         let chunkDelayMs: Int
+        // true → fragments written .withResponse (firmware ATT-acks each, worker
+        // waits for the ack before the next). false → .withoutResponse (captions):
+        // fire-and-forget for throughput, newest caption supersedes the last.
+        let ack: Bool
 
-        init(chunks: [[UInt8]], waitTimeMs: Int = 0, chunkDelayMs: Int = 8) {
+        init(chunks: [[UInt8]], waitTimeMs: Int = 0, chunkDelayMs: Int = 8, ack: Bool = true) {
             self.chunks = chunks
             self.waitTimeMs = waitTimeMs
             self.chunkDelayMs = chunkDelayMs
+            self.ack = ack
         }
     }
 
@@ -456,9 +673,9 @@ class MentraNexSGC: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate, SG
         }
     }
 
-    private func queueChunks(_ chunks: [[UInt8]], waitTimeMs: Int = 0, chunkDelayMs: Int = 10) {
+    private func queueChunks(_ chunks: [[UInt8]], waitTimeMs: Int = 0, chunkDelayMs: Int = 10, ack: Bool = true) {
         let cmd = BufferedCommand(
-            chunks: chunks, waitTimeMs: waitTimeMs, chunkDelayMs: chunkDelayMs
+            chunks: chunks, waitTimeMs: waitTimeMs, chunkDelayMs: chunkDelayMs, ack: ack
         )
         Task { [weak self] in
             await self?.commandQueue.enqueue(cmd)
@@ -500,6 +717,20 @@ class MentraNexSGC: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate, SG
         pendingWriteContinuation = nil
     }
 
+    /// Suspends until the ATT ack for a .withResponse write arrives (resumed by
+    /// didWriteValueFor, or by the disconnect handlers so an in-flight acked
+    /// write can't wedge the queue across a drop).
+    private func waitUntilAcked() async {
+        await withCheckedContinuation { continuation in
+            pendingAckContinuation = continuation
+        }
+    }
+
+    private func resumePendingAck() {
+        pendingAckContinuation?.resume()
+        pendingAckContinuation = nil
+    }
+
     private func emitBleCommandSent(_ packetData: Data) {
         guard packetData.first == PACKET_TYPE_PROTOBUF else { return }
         guard packetData.count > 1 else { return }
@@ -530,7 +761,7 @@ class MentraNexSGC: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate, SG
     /// reassemble messages larger than one MTU. Single-fragment messages set totalChunks = 1
     /// and are decoded directly by the firmware's fast path.
     private func queueDataWithOptimalChunking(
-        _ data: Data, packetType: UInt8 = 0x02, waitTimeMs: Int = 0, emitTelemetry: Bool = true
+        _ data: Data, packetType: UInt8 = 0x02, waitTimeMs: Int = 0, emitTelemetry: Bool = true, ack: Bool = true
     ) {
         // Telemetry: report the full logical command (type byte + protobuf) before fragmenting.
         // Callers on high-rate paths (caption text walls, up to 10/sec) pass
@@ -576,7 +807,7 @@ class MentraNexSGC: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate, SG
         // Bridge.log(
         //     "NEX: 📦 Fragmented protobuf into \(chunks.count) chunk(s) (seq=\(seq), max payload \(effectiveChunkSize) bytes)"
         // )
-        queueChunks(chunks, waitTimeMs: waitTimeMs)
+        queueChunks(chunks, waitTimeMs: waitTimeMs, ack: ack)
     }
 
     private func processCommand(_ command: BufferedCommand) async {
@@ -599,18 +830,22 @@ class MentraNexSGC: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate, SG
             //     "NEX: 📦 Sending chunk \(index) of \(command.chunks.count) to \(peripheral.name ?? "Unknown")"
             // )
             // Bridge.log("NEX: 📦 Chunk data: \(data.toHexString())")
-            // // Write WITHOUT response: a write-with-response is one outstanding request at a
-            // // time gated on a remote round trip, which puts the (screen-off-throttled) app
-            // // thread in the path of every fragment and makes captions crawl in the background.
-            // // .withoutResponse lets CoreBluetooth batch fragments into connection events.
-            // // CoreBluetooth does NOT call didWriteValueFor for .withoutResponse, so we use its
-            // // flow-control flag instead of an ack — gating prevents dropped fragments (which
-            // // would make the firmware discard the whole reassembled caption). See
-            // // docs/ble-disconnects-during-captions.md in the firmware repo.
-            // if !peripheral.canSendWriteWithoutResponse {
-            //     await waitUntilReadyToWrite()
-            // }
-            peripheral.writeValue(data, for: writeCharacteristic, type: .withoutResponse)
+            if command.ack {
+                // Acked path (everything except captions): write WITH response so the
+                // firmware ATT-acks each fragment, then wait for that ack
+                // (didWriteValueFor) before sending the next — reliable delivery, one
+                // outstanding write at a time.
+                peripheral.writeValue(data, for: writeCharacteristic, type: .withResponse)
+                await waitUntilAcked()
+            } else {
+                // Captions: write WITHOUT response. A write-with-response is one
+                // outstanding request gated on a remote round trip, which puts the
+                // (screen-off-throttled) app thread in the path of every fragment and
+                // makes captions crawl in the background. .withoutResponse lets
+                // CoreBluetooth batch fragments into connection events; the newest
+                // caption supersedes the last, so a dropped fragment self-heals.
+                peripheral.writeValue(data, for: writeCharacteristic, type: .withoutResponse)
+            }
 
             // // Delay between chunks except maybe after the last chunk if waitTime will handle it
             // if index < command.chunks.count - 1 {
@@ -991,10 +1226,23 @@ class MentraNexSGC: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate, SG
         }
     }
 
+    // Characters the Nex font can render: letters, digits, whitespace, and a small
+    // punctuation set. Everything else (CJK, emoji, smart quotes, …) is stripped when
+    // Chinese captions are off. Matches UNSUPPORTED_GLYPH_REGEX in NexSGCUtils.kt.
+    private static let unsupportedGlyphPattern = #"[^A-Za-z0-9 \r\n\.,!\?;:\-\[\]\(\)\{\}'"\+=/]"#
+
+    /// Sanitize text bound for the glasses. When Chinese captions are disabled (the
+    /// default) the Nex font can't render CJK/emoji/etc., so em-dashes are normalised
+    /// to hyphens and unsupported glyphs are dropped; when enabled, text passes through
+    /// untouched. Every text path to the display funnels through here so captions and
+    /// layout text filter identically. Mirrors sanitizeDisplayText in NexSGCUtils.kt.
     private func sanitizeDisplayText(_ text: String) -> String {
+        let chineseCaptionsEnabled = DeviceStore.shared.get("bluetooth", "nex_chinese_captions") as? Bool ?? false
+        if chineseCaptionsEnabled { return text }
         let normalized = text.replacingOccurrences(of: "—", with: "-")
-        let pattern = #"[^A-Za-z0-9 \r\n\.,!\?;:\-\[\]\(\)\{\}'"\+=/]"#
-        return normalized.replacingOccurrences(of: pattern, with: "", options: .regularExpression)
+        return normalized.replacingOccurrences(
+            of: MentraNexSGC.unsupportedGlyphPattern, with: "", options: .regularExpression
+        )
     }
 
     func sendTextWall(_ text: String) async {
@@ -1003,10 +1251,9 @@ class MentraNexSGC: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate, SG
             return
         }
 
-        // When Chinese captions are disabled (default), strip characters the Nex font
-        // can't render (CJK etc.). When enabled, pass the text through unmodified.
-        let chineseCaptionsEnabled = DeviceStore.shared.get("bluetooth", "nex_chinese_captions") as? Bool ?? false
-        let sanitizedText = chineseCaptionsEnabled ? text : sanitizeDisplayText(text)
+        // sanitizeDisplayText applies the Chinese-captions gate internally: off (default)
+        // strips glyphs the Nex font can't render, on passes the text through unmodified.
+        let sanitizedText = sanitizeDisplayText(text)
         // No per-call log: this runs for every interim transcript (several/sec
         // during continuous speech) and each Bridge.log costs the JS thread.
         // Bridge.log("NEX: Displaying text wall: '\(sanitizedText)'")
@@ -1067,7 +1314,9 @@ class MentraNexSGC: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate, SG
         }
         textWallLock.unlock()
         guard let toSend else { return }
-        queueDataWithOptimalChunking(toSend, packetType: PACKET_TYPE_PROTOBUF, emitTelemetry: false)
+        // Captions go out unacked (.withoutResponse) for throughput; every other
+        // command uses acked writes. Mirrors MentraNex.kt.
+        queueDataWithOptimalChunking(toSend, packetType: PACKET_TYPE_PROTOBUF, emitTelemetry: false, ack: false)
     }
 
     @objc func displayTextLine(_ text: String) {
@@ -1246,6 +1495,112 @@ class MentraNexSGC: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate, SG
         return pixelData
     }
 
+    // MARK: - Glasses-native 1-bit BMP pipeline (parity with Android's decodeBitmapForNex)
+
+    /**
+     Decode → invert → Floyd–Steinberg dither → 1-bit BMP encode, mirroring
+     Android's `decodeBitmapForNex` + `BitmapJavaUtils.convertBitmapTo1BitBmpBytes`.
+
+     The panel is 1-bpp and renders white-on-black; the firmware BMP decoder
+     normalises palette polarity, so the only way to flip the on-glass result is
+     to invert the actual pixel content. Dithering preserves gradients as dot
+     patterns instead of a hard 50% threshold. Output byte layout matches the
+     Android encoder exactly: 14-byte file header + 40-byte BITMAPINFOHEADER +
+     8-byte palette (index 0 = white, 1 = black), rows padded to 4 bytes,
+     bottom-to-top, bit set when the (post-invert, post-dither) pixel is dark.
+     */
+    private func convertImageToNex1BitBmp(_ image: UIImage) -> Data? {
+        guard let cgImage = image.cgImage else { return nil }
+        let width = cgImage.width
+        let height = cgImage.height
+        guard width > 0, height > 0 else { return nil }
+
+        // RGBA readback.
+        var rgba = [UInt8](repeating: 0, count: width * height * 4)
+        guard
+            let context = CGContext(
+                data: &rgba,
+                width: width,
+                height: height,
+                bitsPerComponent: 8,
+                bytesPerRow: width * 4,
+                space: CGColorSpaceCreateDeviceRGB(),
+                bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue
+            )
+        else { return nil }
+        context.draw(cgImage, in: CGRect(x: 0, y: 0, width: width, height: height))
+
+        // Luminance (Rec. 601), INVERTED — same order as Android (invert, then dither).
+        var lum = [Float](repeating: 0, count: width * height)
+        for i in 0 ..< (width * height) {
+            let r = Float(rgba[i * 4])
+            let g = Float(rgba[i * 4 + 1])
+            let b = Float(rgba[i * 4 + 2])
+            lum[i] = 255.0 - (0.299 * r + 0.587 * g + 0.114 * b)
+        }
+
+        // Floyd–Steinberg error diffusion (7/3/5/1 over 16, right/below neighbours).
+        var dark = [Bool](repeating: false, count: width * height)
+        for y in 0 ..< height {
+            for x in 0 ..< width {
+                let idx = y * width + x
+                let old = lum[idx]
+                let newVal: Float = old < 128 ? 0 : 255
+                let err = old - newVal
+                dark[idx] = newVal < 128
+                if x + 1 < width { lum[idx + 1] += err * 7 / 16 }
+                if y + 1 < height {
+                    if x >= 1 { lum[idx + width - 1] += err * 3 / 16 }
+                    lum[idx + width] += err * 5 / 16
+                    if x + 1 < width { lum[idx + width + 1] += err * 1 / 16 }
+                }
+            }
+        }
+
+        // 1-bpp BMP encode (Android layout, invert=false palette).
+        let rowSizeBytes = ((width + 31) / 32) * 4
+        let imageSize = rowSizeBytes * height
+        let dataOffset = 62
+        var bmp = Data(capacity: dataOffset + imageSize)
+
+        func putU16(_ v: UInt16) {
+            bmp.append(UInt8(v & 0xFF)); bmp.append(UInt8(v >> 8))
+        }
+        func putU32(_ v: UInt32) {
+            bmp.append(UInt8(v & 0xFF)); bmp.append(UInt8((v >> 8) & 0xFF))
+            bmp.append(UInt8((v >> 16) & 0xFF)); bmp.append(UInt8((v >> 24) & 0xFF))
+        }
+
+        bmp.append(UInt8(ascii: "B")); bmp.append(UInt8(ascii: "M"))
+        putU32(UInt32(dataOffset + imageSize)) // file size
+        putU16(0); putU16(0) // reserved
+        putU32(UInt32(dataOffset)) // pixel data offset
+        putU32(40) // DIB header size
+        putU32(UInt32(width))
+        putU32(UInt32(height)) // positive => bottom-to-top
+        putU16(1) // planes
+        putU16(1) // bits per pixel
+        putU32(0) // BI_RGB
+        putU32(UInt32(imageSize))
+        putU32(2835); putU32(2835) // 72 DPI
+        putU32(2) // palette colors
+        putU32(0) // important colors
+        // Palette: index 0 = white, index 1 = black (Android invert=false).
+        bmp.append(contentsOf: [0xFF, 0xFF, 0xFF, 0x00])
+        bmp.append(contentsOf: [0x00, 0x00, 0x00, 0x00])
+
+        var row = [UInt8](repeating: 0, count: rowSizeBytes)
+        for y in 0 ..< height {
+            let py = height - 1 - y // BMP rows are bottom-to-top
+            for i in 0 ..< rowSizeBytes { row[i] = 0 }
+            for x in 0 ..< width where dark[py * width + x] {
+                row[x / 8] |= UInt8(0x80 >> (x % 8))
+            }
+            bmp.append(contentsOf: row)
+        }
+        return bmp
+    }
+
     // MARK: - Display Control Commands
 
     @objc func clearDisplay() {
@@ -1256,6 +1611,14 @@ class MentraNexSGC: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate, SG
 
         Bridge.log("NEX: Clearing display")
 
+        // Tear down any canvas components and forget the registry — clear_view
+        // wipes the whole screen, canvas included.
+        if !canvasElements.isEmpty || currentLayoutId != nil {
+            canvasElements.removeAll()
+            currentLayoutId = nil
+            sendCanvasCommand { $0.canvasClear = Mentraos_Ble_CanvasClear() }
+        }
+
         // Drop any pending/resendable text wall so a stale caption can't
         // repaint the display after this clear.
         textWallLock.lock()
@@ -1625,6 +1988,16 @@ class MentraNexSGC: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate, SG
             emitBleCommandReceived(fullPacket, payloadDescription: String(describing: glassesToPhone.payload))
 
             switch glassesToPhone.payload {
+            case let .canvasResult(canvasResult):
+                // Ack for CanvasCreateComponent / CanvasClear (updates are
+                // unacked). Non-OK (INVALID / OVERSIZE / OOM) invalidates the
+                // registry entry so the next frame recreates the component —
+                // and a silent blank screen becomes a diagnosable log line.
+                if canvasResult.code != .ok {
+                    Bridge.log("NEX: CANVAS_RESULT id=\(canvasResult.id) code=\(canvasResult.code) — dropping registry entry for recreate")
+                    canvasElements.removeAll { $0.value.firmwareId == canvasResult.id }
+                }
+
             case let .batteryStatus(batteryStatus):
                 handleBatteryStatusProtobuf(batteryStatus)
 
@@ -2142,6 +2515,7 @@ class MentraNexSGC: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate, SG
         releaseServiceWaiters()
         Task { await commandQueue.clear() }
         resumePendingWrite()
+        resumePendingAck()
         stopReconnectionTimer()
         stopTextWallDrain()
     }
@@ -2192,6 +2566,7 @@ class MentraNexSGC: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate, SG
         releaseServiceWaiters()
         Task { await commandQueue.clear() }
         resumePendingWrite()
+        resumePendingAck()
 
         Bridge.log("NEX: ✅ MentraNexSGC destroyed successfully")
         // Reset initialization flags
@@ -2459,6 +2834,7 @@ class MentraNexSGC: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate, SG
         releaseServiceWaiters()
         Task { await commandQueue.clear() }
         resumePendingWrite()
+        resumePendingAck()
         self.peripheral = nil // Reset peripheral on failure to allow reconnection
         // Optionally, start reconnection attempts here
         if !isDisconnecting, !isKilled {
@@ -2478,6 +2854,13 @@ class MentraNexSGC: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate, SG
             Bridge.log("NEX-CONN: ⚠️ Disconnect error: \(error.localizedDescription)")
         }
 
+        // The glasses lose their canvas on disconnect — forget the component
+        // registry so post-reconnect frames take the CREATE path (firmware
+        // silently drops updates to dead component ids). The host replays the
+        // current scene after reconnect.
+        canvasElements.removeAll()
+        currentLayoutId = nil
+
         // Reset connection state
         // Save microphone state before disconnection (like Java implementation)
         saveMicrophoneStateBeforeDisconnection()
@@ -2485,6 +2868,7 @@ class MentraNexSGC: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate, SG
         releaseServiceWaiters()
         Task { await commandQueue.clear() }
         resumePendingWrite()
+        resumePendingAck()
 
         // Reset protobuf version posted flag for next connection (like Java implementation)
         protobufVersionPosted = false
@@ -2797,10 +3181,10 @@ class MentraNexSGC: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate, SG
             Bridge.log(
                 "NEX-CONN: ❌ Error writing value to \(characteristic.uuid): \(error.localizedDescription)"
             )
-            resumePendingWrite()
+            resumePendingAck()
             return
         }
-        resumePendingWrite()
+        resumePendingAck()
     }
 
     func peripheralIsReady(toSendWriteWithoutResponse _: CBPeripheral) {