@mentra/bluetooth-sdk 3.3.0-dev.317 → 3.3.0-dev.321

package/android/src/testDebug/java/com/mentra/bluetoothsdk/sgcs/NimoLifecycleTest.kt

@@ -0,0 +1,194 @@
+package com.mentra.bluetoothsdk.sgcs
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.ContextWrapper
+import android.content.SharedPreferences
+import android.os.Handler
+import android.os.Looper
+import androidx.test.core.app.ApplicationProvider
+import com.mentra.bluetoothsdk.Bridge
+import com.mentra.bluetoothsdk.DeviceManager
+import com.mentra.bluetoothsdk.DeviceStore
+import com.mentra.bluetoothsdk.utils.ConnTypes
+import java.io.File
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicReference
+import org.json.JSONObject
+import org.junit.After
+import org.junit.Assert.*
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.Shadows
+import org.robolectric.annotation.Config
+import org.robolectric.annotation.LooperMode
+
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [33])
+@LooperMode(LooperMode.Mode.PAUSED)
+class NimoLifecycleTest {
+  private class TrackingContext(base: Context) : ContextWrapper(base) {
+    val unregisterLoopers = mutableListOf<Looper?>()
+    val preferenceLoopers = mutableListOf<Looper?>()
+    override fun getApplicationContext(): Context = this
+    override fun getSharedPreferences(name: String, mode: Int): SharedPreferences {
+      if (name == "NimoPrefs") preferenceLoopers.add(Looper.myLooper())
+      return super.getSharedPreferences(name, mode)
+    }
+    override fun unregisterReceiver(receiver: BroadcastReceiver) {
+      unregisterLoopers.add(Looper.myLooper())
+      super.unregisterReceiver(receiver)
+    }
+  }
+
+  private lateinit var context: TrackingContext
+  private lateinit var nimo: Nimo
+  private lateinit var encoderThread: Thread
+  private lateinit var manager: DeviceManager
+  private var previousManager: DeviceManager? = null
+  private lateinit var diagnostics: NimoDiagnostics
+  private lateinit var captureDirectory: File
+  private lateinit var writeCompleted: () -> Unit
+  private var writes = 0
+  private val storeLoopers = mutableListOf<Looper?>()
+  private var listener: String? = null
+
+  @Before fun setup() {
+    context = TrackingContext(ApplicationProvider.getApplicationContext())
+    Bridge.initialize(context)
+    manager = DeviceManager(initializeHardware = false)
+    DeviceManager::class.java.getDeclaredField("_instance").apply { isAccessible = true }.let {
+      previousManager = it.get(null) as DeviceManager?
+      it.set(null, manager)
+    }
+    val threadsBefore = Thread.getAllStackTraces().keys
+    nimo = Nimo()
+    encoderThread = Thread.getAllStackTraces().keys.single {
+      it.name == "NimoCanvasEncoder" && it !in threadsBefore
+    }
+    context.getSharedPreferences("NimoPrefs", Context.MODE_PRIVATE).edit()
+      .putString("nimo_lastDeviceAddress", "00:11:22:33:44:55")
+      .putString("nimo_lastDeviceName", "Nimo-test")
+      .commit()
+    DeviceStore.set("glasses", "connected", true)
+    DeviceStore.set("glasses", "fullyBooted", true)
+    DeviceStore.set("glasses", "connectionState", ConnTypes.CONNECTED)
+    listener = DeviceStore.store.addListener { category, _ ->
+      if (category == "glasses") storeLoopers.add(Looper.myLooper())
+    }
+    diagnostics = NimoDiagnostics(context, Handler(Looper.getMainLooper()), send = { _, completed ->
+      writes += 1
+      writeCompleted = completed
+      true
+    })
+    diagnostics.connected(512)
+    // Install the real debug collaborator without requiring a Bluetooth radio handshake.
+    Nimo::class.java.getDeclaredField("diagnostics").apply { isAccessible = true }
+      .set(nimo, diagnostics)
+    val root = File(context.filesDir, "nimo-framebuffer")
+    val previous = root.listFiles()?.map { it.name }?.toSet() ?: emptySet()
+    // Receiver permission enforcement is a device test; this starts its real capture path.
+    NimoDiagnostics::class.java.getDeclaredMethod("start", String::class.java)
+      .apply { isAccessible = true }.invoke(diagnostics, "capture")
+    captureDirectory = root.listFiles()!!.single { it.name !in previous }
+    assertEquals(1, writes)
+  }
+
+  @After fun dispose() {
+    nimo.cleanup()
+    Shadows.shadowOf(Looper.getMainLooper()).idle()
+    encoderThread.join(1_000)
+    listener?.let { DeviceStore.store.removeListener(it) }
+    manager.cleanup()
+    DeviceManager::class.java.getDeclaredField("_instance").apply { isAccessible = true }
+      .set(null, previousManager)
+  }
+
+  @Test fun offMainDisconnectCompletesOnMainAndInterruptsActiveCapture() {
+    runOffMain { nimo.disconnect() }
+    assertDisconnectedOnMain()
+    assertRememberedDevice()
+  }
+
+  @Test fun offMainForgetClearsRememberedDeviceAfterMainThreadTeardown() {
+    runOffMain { nimo.forget() }
+    assertDisconnectedOnMain()
+    val prefs = context.getSharedPreferences("NimoPrefs", Context.MODE_PRIVATE)
+    assertFalse(prefs.contains("nimo_lastDeviceAddress"))
+    assertFalse(prefs.contains("nimo_lastDeviceName"))
+    assertTrue(context.preferenceLoopers.all { it === Looper.getMainLooper() })
+  }
+
+  @Test fun offMainCleanupClosesDiagnosticsAfterMainThreadTeardown() {
+    runOffMain { nimo.cleanup() }
+    assertDisconnectedOnMain()
+    assertRememberedDevice()
+    encoderThread.join(1_000)
+    assertFalse("Cleanup left its encoder thread alive", encoderThread.isAlive)
+    // A closed diagnostic cannot register another receiver or start a new capture.
+    diagnostics.connected(512)
+    NimoDiagnostics::class.java.getDeclaredMethod("start", String::class.java)
+      .apply { isAccessible = true }.invoke(diagnostics, "capture")
+    assertEquals(1, writes)
+  }
+
+  private fun runOffMain(operation: () -> Unit) {
+    val failure = AtomicReference<Throwable?>()
+    val caller = Thread({
+      try {
+        operation()
+        // The manager may replace this instance immediately after return. An asynchronous
+        // post is insufficient: the old connection must already be completely torn down.
+        assertEquals(false, DeviceStore.get("glasses", "connected"))
+        assertEquals(false, DeviceStore.get("glasses", "fullyBooted"))
+        assertTrue(File(captureDirectory, "session.json").exists())
+      } catch (error: Throwable) { failure.set(error) }
+    }, "Expo-AsyncFunctionQueue-test")
+    caller.start()
+    // The Main looper is paused, so no teardown may have run on the Expo worker.
+    assertEquals(true, DeviceStore.get("glasses", "connected"))
+    assertEquals(true, DeviceStore.get("glasses", "fullyBooted"))
+    assertRememberedDevice()
+    assertTrue(context.unregisterLoopers.isEmpty())
+    assertTrue(storeLoopers.isEmpty())
+    assertTrue("Encoder stopped before Main processed teardown", encoderThread.isAlive)
+    assertFalse(File(captureDirectory, "session.json").exists())
+    val deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(5)
+    while (caller.isAlive && System.nanoTime() < deadline) {
+      Shadows.shadowOf(Looper.getMainLooper()).idle()
+      caller.join(10)
+    }
+    if (caller.isAlive) {
+      caller.interrupt()
+      caller.join(1_000)
+      fail("Lifecycle did not return after Main processed teardown")
+    }
+    failure.get()?.let { throw AssertionError("Off-main lifecycle entrypoint failed", it) }
+  }
+
+  private fun assertDisconnectedOnMain() {
+    assertEquals(false, DeviceStore.get("glasses", "connected"))
+    assertEquals(false, DeviceStore.get("glasses", "fullyBooted"))
+    assertEquals(ConnTypes.DISCONNECTED, DeviceStore.get("glasses", "connectionState"))
+    assertEquals(listOf(Looper.getMainLooper()), context.unregisterLoopers)
+    assertTrue(storeLoopers.isNotEmpty())
+    assertTrue(storeLoopers.all { it === Looper.getMainLooper() })
+    val receiptFile = File(captureDirectory, "session.json")
+    val beforeLateCallback = receiptFile.readText()
+    val receipt = JSONObject(beforeLateCallback)
+    assertFalse(receipt.getBoolean("ok"))
+    assertTrue(receipt.getString("error").contains("disconnected"))
+    writeCompleted()
+    Shadows.shadowOf(Looper.getMainLooper()).idle()
+    assertEquals(beforeLateCallback, receiptFile.readText())
+    assertEquals(1, writes)
+  }
+
+  private fun assertRememberedDevice() {
+    val prefs = context.getSharedPreferences("NimoPrefs", Context.MODE_PRIVATE)
+    assertEquals("00:11:22:33:44:55", prefs.getString("nimo_lastDeviceAddress", null))
+    assertEquals("Nimo-test", prefs.getString("nimo_lastDeviceName", null))
+  }
+}

package/android/src/testDebug/java/com/mentra/bluetoothsdk/sgcs/NimoReadinessDriverTest.kt

@@ -0,0 +1,199 @@
+package com.mentra.bluetoothsdk.sgcs
+
+import android.bluetooth.BluetoothAdapter
+import android.bluetooth.BluetoothGatt
+import android.bluetooth.BluetoothGattCallback
+import android.bluetooth.BluetoothGattCharacteristic
+import android.bluetooth.BluetoothGattService
+import android.content.Context
+import android.os.Handler
+import android.os.Looper
+import androidx.test.core.app.ApplicationProvider
+import com.mentra.bluetoothsdk.Bridge
+import com.mentra.bluetoothsdk.DeviceManager
+import com.mentra.bluetoothsdk.DeviceStore
+import com.mentra.bluetoothsdk.utils.ConnTypes
+import java.util.UUID
+import org.junit.After
+import org.junit.Assert.*
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.Shadows
+import org.robolectric.annotation.Config
+import org.robolectric.annotation.LooperMode
+import org.robolectric.shadows.ShadowBluetoothGatt
+
+/** Exercise real receive dispatch, not just the already-tested canvas state machine. */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [33])
+@LooperMode(LooperMode.Mode.PAUSED)
+@Suppress("deprecation")
+class NimoReadinessDriverTest {
+  private lateinit var nimo: Nimo
+  private lateinit var encoderThread: Thread
+  private lateinit var manager: DeviceManager
+  private var previousManager: DeviceManager? = null
+  private lateinit var callback: BluetoothGattCallback
+  private lateinit var currentGatt: BluetoothGatt
+  private lateinit var rx: BluetoothGattCharacteristic
+  private lateinit var canvas: NimoCanvasCoordinator
+  private val frames = mutableListOf<ByteArray>()
+  private val failures = mutableListOf<String>()
+  private val rejections = mutableListOf<Int>()
+  private val savedStore = mutableMapOf<String, Any>()
+
+  @Before fun setup() {
+    Bridge.initialize(ApplicationProvider.getApplicationContext<Context>())
+    manager = DeviceManager(initializeHardware = false)
+    DeviceManager::class.java.getDeclaredField("_instance").apply { isAccessible = true }.let {
+      previousManager = it.get(null) as DeviceManager?
+      it.set(null, manager)
+    }
+    for (key in listOf("connected", "fullyBooted", "connectionState", "headUp", "voiceActivityDetectionEnabled")) {
+      DeviceStore.get("glasses", key)?.let { savedStore[key] = it }
+    }
+    // Suppress unrelated manager side effects when finishHandshake republishes these values.
+    DeviceStore.set("glasses", "connected", true)
+    DeviceStore.set("glasses", "fullyBooted", true)
+    DeviceStore.set("glasses", "connectionState", ConnTypes.CONNECTED)
+    val before = Thread.getAllStackTraces().keys
+    nimo = Nimo()
+    encoderThread = Thread.getAllStackTraces().keys.single {
+      it.name == "NimoCanvasEncoder" && it !in before
+    }
+    callback = field("gattCallback").get(nimo) as BluetoothGattCallback
+    currentGatt = newGatt()
+    field("gatt").set(nimo, currentGatt)
+    rx = characteristic(NimoBLE.SERVICE_UUID)
+    val handler = Handler(Looper.getMainLooper())
+    canvas = NimoCanvasCoordinator(NimoScheduler { delay, task ->
+      val runnable = Runnable(task)
+      handler.postDelayed(runnable, delay)
+      ({ handler.removeCallbacks(runnable) })
+    }, { 512 }, { chain, started, completed ->
+      frames.addAll(chain.map { it.copyOf() })
+      started()
+      completed()
+      true
+    }, { failures.add(it) }, { rejections.add(it) })
+    field("canvas").set(nimo, canvas)
+  }
+
+  @After fun dispose() {
+    try {
+      nimo.cleanup()
+      idle()
+      encoderThread.join(1_000)
+      assertFalse("Encoder thread leaked", encoderThread.isAlive)
+    } finally {
+      manager.cleanup()
+      savedStore.forEach { (key, value) -> DeviceStore.set("glasses", key, value) }
+      DeviceManager::class.java.getDeclaredField("_instance").apply { isAccessible = true }
+        .set(null, previousManager)
+    }
+  }
+
+  @Test fun onlyCompleteSuccessfulHeartbeatReleasesNotReadyAndSendsLatestScene() {
+    val latest = byteArrayOf(1, 0, 1)
+    canvas.offer(byteArrayOf(0, 0, 1), "first")
+    finishHandshake(peer = true)
+    assertKeys(1)
+    emit(packet(7, 1, byteArrayOf(7)))
+    assertEquals(listOf(7), rejections)
+    canvas.offer(latest, "latest")
+
+    emit(packet(6, 3, byteArrayOf(0, 1))) // TWS alone cannot refresh peer readiness.
+    emit(heartbeat(status = 7))
+    emit(packet(6, 4, byteArrayOf(0, 3) + ByteArray(9))) // Missing slaveGatt.
+    val corrupt = heartbeat().also { it[it.lastIndex] = 2 } // Invalid CRC.
+    emit(corrupt)
+    assertKeys(1)
+
+    emit(heartbeat())
+    assertKeys(1, 1)
+    emit(heartbeat()) // No overlapping Launch while awaiting its ACK.
+    assertKeys(1, 1)
+    emit(packet(7, 1, byteArrayOf(0, 0xFD.toByte())))
+    assertKeys(1, 1, 4)
+    assertArrayEquals(NimoCanvasCodec.frames(4, latest, 512).single(), frames.last())
+    assertTrue(failures.isEmpty())
+  }
+
+  @Test fun unknownPeerCannotLaunchFromHandshakeOrTwsOnlyReports() {
+    canvas.offer(byteArrayOf(0, 0, 1), "initial")
+    finishHandshake(peer = null)
+    assertKeys()
+    emit(packet(6, 3, byteArrayOf(0, 1)))
+    assertNull(field("peerCompanionReady").get(nimo))
+    assertKeys()
+    emit(heartbeat(peer = 0))
+    assertEquals(false, field("peerCompanionReady").get(nimo))
+    assertKeys()
+    emit(heartbeat())
+    assertEquals(true, field("peerCompanionReady").get(nimo))
+    assertKeys(1)
+    assertTrue(failures.isEmpty())
+  }
+
+  @Test fun queuedOldGattAndWrongServiceCannotEstablishReadiness() {
+    canvas.offer(byteArrayOf(0, 0, 1), "initial")
+    finishHandshake(peer = null)
+    val oldGatt = currentGatt
+    queue(heartbeat(), oldGatt)
+    currentGatt = newGatt()
+    field("gatt").set(nimo, currentGatt)
+    idle() // The generation check must occur when the queued callback executes.
+    emit(heartbeat(), oldGatt)
+    emit(heartbeat(), currentGatt, characteristic(UUID.fromString("00001234-0000-1000-8000-00805f9b34fb")))
+    assertNull(field("peerCompanionReady").get(nimo))
+    assertKeys()
+
+    emit(heartbeat()) // Positive control through the actual current RX callback.
+    assertKeys(1)
+    oldGatt.close()
+    assertTrue(failures.isEmpty())
+  }
+
+  private fun finishHandshake(peer: Boolean?) {
+    field("twsConnected").set(nimo, true)
+    field("peerCompanionReady").set(nimo, peer)
+    Nimo::class.java.getDeclaredMethod("finishHandshake").apply { isAccessible = true }.invoke(nimo)
+    idle()
+  }
+
+  private fun newGatt(): BluetoothGatt = ShadowBluetoothGatt.newInstance(
+    BluetoothAdapter.getDefaultAdapter().getRemoteDevice("00:11:22:33:44:55"),
+  )
+
+  private fun characteristic(serviceId: UUID): BluetoothGattCharacteristic {
+    val characteristic = BluetoothGattCharacteristic(NimoBLE.CHAR_RX,
+      BluetoothGattCharacteristic.PROPERTY_NOTIFY, BluetoothGattCharacteristic.PERMISSION_READ)
+    BluetoothGattService(serviceId, BluetoothGattService.SERVICE_TYPE_PRIMARY).addCharacteristic(characteristic)
+    return characteristic
+  }
+
+  private fun heartbeat(status: Int = 0, peer: Int = 1) = packet(6, 4,
+    byteArrayOf(status.toByte(), 3) + ByteArray(8) + byteArrayOf(1, peer.toByte()))
+
+  private fun packet(command: Int, key: Int, payload: ByteArray) =
+    NimoFrameCodec.encodeFrame(command, key, payload, needsAck = false)
+
+  private fun queue(packet: ByteArray, gatt: BluetoothGatt = currentGatt,
+                    characteristic: BluetoothGattCharacteristic = rx) {
+    characteristic.value = packet.copyOf()
+    callback.onCharacteristicChanged(gatt, characteristic)
+  }
+
+  private fun emit(packet: ByteArray, gatt: BluetoothGatt = currentGatt,
+                   characteristic: BluetoothGattCharacteristic = rx) {
+    queue(packet, gatt, characteristic)
+    idle()
+  }
+
+  private fun idle() = Shadows.shadowOf(Looper.getMainLooper()).idle()
+  private fun field(name: String) = Nimo::class.java.getDeclaredField(name).apply { isAccessible = true }
+  private fun assertKeys(vararg expected: Int) =
+    assertEquals(expected.toList(), frames.map { it[9].toInt() and 255 })
+}

package/build/generated/releaseMetadata.js

@@ -1,10 +1,10 @@
 export const BLUETOOTH_SDK_RELEASE_METADATA = Object.freeze({
     "schemaVersion": 1,
     "familyBaseVersion": "3.3.0",
-    "releaseIdentity": "3.3.0-dev.317",
-    "releaseSetId": "mentra-3.3.0-dev.317",
-    "sourceCommit": "f5be01b015898d019a200369c824eddba5f0f802",
-    "otaManifestUrl": "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.3.0/mentra-live-ota-3.3.0-dev.317.json",
-    "otaManifestSha256": "573b09239a97f0bbeb03a53b460e89a71ad62c7aad4f32dc93fd042cfb6d03d2"
+    "releaseIdentity": "3.3.0-dev.321",
+    "releaseSetId": "mentra-3.3.0-dev.321",
+    "sourceCommit": "75da48dec4a113644b96610acf0d92a2d1b5433c",
+    "otaManifestUrl": "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.3.0/mentra-live-ota-3.3.0-dev.321.json",
+    "otaManifestSha256": "bc7004312a321bc7e2218304ccbf754304ce27f98f2787d5affc6d79802b253e"
 });
 //# sourceMappingURL=releaseMetadata.js.map

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,sBAAsB;IACtC,cAAc,EAAE,0CAA0C;IAC1D,gBAAgB,EAAE,iIAAiI;IACnJ,mBAAmB,EAAE,kEAAkE;CACxF,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\": \"3.3.0\",\n  \"releaseIdentity\": \"3.3.0-dev.317\",\n  \"releaseSetId\": \"mentra-3.3.0-dev.317\",\n  \"sourceCommit\": \"f5be01b015898d019a200369c824eddba5f0f802\",\n  \"otaManifestUrl\": \"https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.3.0/mentra-live-ota-3.3.0-dev.317.json\",\n  \"otaManifestSha256\": \"573b09239a97f0bbeb03a53b460e89a71ad62c7aad4f32dc93fd042cfb6d03d2\"\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,sBAAsB;IACtC,cAAc,EAAE,0CAA0C;IAC1D,gBAAgB,EAAE,iIAAiI;IACnJ,mBAAmB,EAAE,kEAAkE;CACxF,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\": \"3.3.0\",\n  \"releaseIdentity\": \"3.3.0-dev.321\",\n  \"releaseSetId\": \"mentra-3.3.0-dev.321\",\n  \"sourceCommit\": \"75da48dec4a113644b96610acf0d92a2d1b5433c\",\n  \"otaManifestUrl\": \"https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.3.0/mentra-live-ota-3.3.0-dev.321.json\",\n  \"otaManifestSha256\": \"bc7004312a321bc7e2218304ccbf754304ce27f98f2787d5affc6d79802b253e\"\n})\n"]}

package/ios/MentraBluetoothSDK.podspec

@@ -38,13 +38,14 @@ Pod::Spec.new do |s|
   }
 
   # iOS frameworks required by Bluetooth SDK
-  ios_frameworks = ['AVFoundation', 'CoreBluetooth', 'UIKit', 'CoreGraphics']
+  ios_frameworks = ['AVFoundation', 'CoreBluetooth', 'UIKit', 'CoreGraphics', 'ImageIO']
   ios_frameworks << 'Network' if include_expo_adapter
   s.ios.frameworks = ios_frameworks
   s.osx.frameworks = ['AVFoundation', 'CoreBluetooth', 'CoreAudio', 'AudioToolbox', 'ImageIO', 'JavaScriptCore', 'Network']
 
   # System libraries required by MentraOS
-  s.ios.library = 'bz2'
+  s.ios.libraries = 'bz2', 'z'
+  s.osx.library = 'z'
 
   # Vendored frameworks
   s.ios.vendored_frameworks = 'Packages/SherpaOnnx/sherpa-onnx.xcframework'

package/ios/Source/BluetoothSdkDefaults.swift

@@ -11,7 +11,7 @@ enum BluetoothSdkDefaults {
     static let voiceActivityDetectionEnabled = false
     static let loudnessGateEnabled = false
     private static let infoSdkVersionKey = "MentraBluetoothSdkVersion"
-    private static let swiftPackageSdkVersion = "3.3.0-dev.317"
+    private static let swiftPackageSdkVersion = "3.3.0-dev.321"
     private static let swiftPackageSdkVersionPlaceholder = "__MENTRA" + "_BLUETOOTH_SDK_VERSION__"
 
     private static func normalizedSdkVersion(_ value: String?) -> String? {

package/ios/Source/DeviceManager.swift

@@ -1024,14 +1024,18 @@ struct ViewState {
             sgc.setDashboardPosition(h, d)
         }
 
-        // Show welcome message on first connect for all display glasses
+        // Preserve the connected-edge scene replay on full-frame adapters.
         if shouldSendBootingMessage {
-            Task {
-                await sgc.sendTextWall("// MentraOS Connected")
-                try? await Task.sleep(nanoseconds: 3_000_000_000) // 1 second
-                sgc.clearDisplay()
-            }
             shouldSendBootingMessage = false
+            if sgc.showConnectionConfirmation {
+                Task {
+                    guard (self.sgc as AnyObject?) === (sgc as AnyObject) else { return }
+                    await sgc.sendTextWall("// MentraOS Connected")
+                    try? await Task.sleep(nanoseconds: 3_000_000_000)
+                    guard (self.sgc as AnyObject?) === (sgc as AnyObject) else { return }
+                    sgc.clearDisplay()
+                }
+            }
         }
 
         // Call device-specific setup handlers
@@ -1214,7 +1218,9 @@ struct ViewState {
                 self.dashboardSceneCleanupPending = false
                 let elementIds = Array(self.pendingDashboardSceneElementIds)
                 self.pendingDashboardSceneElementIds.removeAll()
-                await self.sgc?.clearSceneElements(elementIds)
+                if self.sgc?.sceneHandoffRequiresClear == true {
+                    await self.sgc?.clearSceneElements(elementIds)
+                }
             }
             self.dashboardSceneCleanupTask = nil
         }
@@ -1261,7 +1267,7 @@ struct ViewState {
             if stateIndex == 1, dashboardSceneCleanupDeferred {
                 dashboardSceneCleanupPending = true
                 pendingDashboardSceneElementIds.formUnion(prevFrame.elements.map(\.id))
-            } else if layoutType != "clear_view" {
+            } else if layoutType != "clear_view", shouldClearSceneHandoff(stateIndex) {
                 let ids = prevFrame.elements.map(\.id)
                 Task { [weak self] in
                     await self?.sgc?.clearSceneElements(ids)
@@ -1355,7 +1361,7 @@ struct ViewState {
             // on G2 - no page rebuild).
             let prevLegacyType = viewStates[stateIndex].layoutType
             let cleanupDeferred = stateIndex == 1 && dashboardSceneCleanupDeferred
-            if !cleanupDeferred,
+            if !cleanupDeferred, shouldClearSceneHandoff(stateIndex),
                !prevLegacyType.isEmpty,
                prevLegacyType != "clear_view",
                prevLegacyType != "scene"
@@ -1371,7 +1377,7 @@ struct ViewState {
             if stateIndex == 1, dashboardSceneCleanupDeferred {
                 dashboardSceneCleanupPending = true
                 pendingDashboardSceneElementIds.formUnion(prevFrame.elements.map(\.id))
-            } else {
+            } else if shouldClearSceneHandoff(stateIndex) {
                 let ids = prevFrame.elements.map(\.id)
                 Task { [weak self] in
                     await self?.sgc?.clearSceneElements(ids)
@@ -1395,6 +1401,13 @@ struct ViewState {
         }
     }
 
+    private func shouldClearSceneHandoff(_ stateIndex: Int) -> Bool {
+        let visibleIndex = headUp && contextualDashboard ? 1 : 0
+        guard let sgc else { return false }
+        return stateIndex == visibleIndex && !screenDisabled && sgc.fullyBooted
+            && !sgc.type.contains(DeviceTypes.SIMULATED) && sgc.sceneHandoffRequiresClear
+    }
+
     /// Guarded scene dispatch - mirrors sendCurrentState's send conditions.
     private func dispatchSceneFrame(_ frame: SceneFrame, stateIndex: Int) {
         if screenDisabled { return }

package/ios/Source/DeviceStore.swift

@@ -191,14 +191,25 @@ class DeviceStore {
 
         // BLUETOOTH:
 
+        case ("bluetooth", "contextual_dashboard"):
+            if value is Bool {
+                Task { @MainActor in
+                    if self.store.get("glasses", "headUp") as? Bool == true {
+                        DeviceManager.shared.sendCurrentState()
+                    }
+                }
+            }
+
         case ("bluetooth", "brightness"):
             let b = value as? Int ?? 50
             let auto = store.get("bluetooth", "auto_brightness") as? Bool ?? true
             Task {
-                DeviceManager.shared.sgc?.setBrightness(b, autoMode: auto)
-                await DeviceManager.shared.sgc?.sendTextWall("Set brightness to \(b)%")
+                guard let device = DeviceManager.shared.sgc else { return }
+                device.setBrightness(b, autoMode: auto)
+                guard device.showBrightnessConfirmation else { return }
+                await device.sendTextWall("Set brightness to \(b)%")
                 try? await Task.sleep(nanoseconds: 800_000_000) // 0.8 seconds
-                DeviceManager.shared.sgc?.clearDisplay()
+                if (DeviceManager.shared.sgc as AnyObject?) === (device as AnyObject) { device.clearDisplay() }
             }
 
         case ("bluetooth", "auto_brightness"):
@@ -206,13 +217,14 @@ class DeviceStore {
             let auto = value as? Bool ?? true
             let autoBrightnessChanged = (oldValue as? Bool) != auto
             Task {
-                DeviceManager.shared.sgc?.setBrightness(b, autoMode: auto)
-                if autoBrightnessChanged {
-                    await DeviceManager.shared.sgc?.sendTextWall(
+                guard let device = DeviceManager.shared.sgc else { return }
+                device.setBrightness(b, autoMode: auto)
+                if autoBrightnessChanged, device.showBrightnessConfirmation {
+                    await device.sendTextWall(
                         auto ? "Enabled auto brightness" : "Disabled auto brightness"
                     )
                     try? await Task.sleep(nanoseconds: 800_000_000) // 0.8 seconds
-                    DeviceManager.shared.sgc?.clearDisplay()
+                    if (DeviceManager.shared.sgc as AnyObject?) === (device as AnyObject) { device.clearDisplay() }
                 }
             }
 

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 = "3.3.0"
-    static let releaseIdentity = "3.3.0-dev.317"
-    static let releaseSetId = "mentra-3.3.0-dev.317"
-    static let sourceCommit = "f5be01b015898d019a200369c824eddba5f0f802"
-    static let otaManifestUrl = "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.3.0/mentra-live-ota-3.3.0-dev.317.json"
-    static let otaManifestSha256 = "573b09239a97f0bbeb03a53b460e89a71ad62c7aad4f32dc93fd042cfb6d03d2"
+    static let releaseIdentity = "3.3.0-dev.321"
+    static let releaseSetId = "mentra-3.3.0-dev.321"
+    static let sourceCommit = "75da48dec4a113644b96610acf0d92a2d1b5433c"
+    static let otaManifestUrl = "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.3.0/mentra-live-ota-3.3.0-dev.321.json"
+    static let otaManifestSha256 = "bc7004312a321bc7e2218304ccbf754304ce27f98f2787d5affc6d79802b253e"
 }

package/ios/Source/sgcs/G2.swift

@@ -2230,7 +2230,7 @@ class G2: NSObject, SGCManager {
         let borderColor = borderColor ?? G2.defaultTextContainer.borderColor
         let borderRadius = borderRadius ?? G2.defaultTextContainer.borderRadius
         let paddingLength = paddingLength ?? G2.defaultTextContainer.paddingLength
-        let content = text.isEmpty ? " " : text
+        let content = G2Text.containerContent(text)
 
         // Pure state mutation: update the container's content and schedule its sends; the reconcile
         // loop (`displayReconcileTask`) does the actual updateText writes. Reuse an existing container
@@ -2391,7 +2391,7 @@ class G2: NSObject, SGCManager {
         // y is clamped first so the height term can't go negative.
         let y = min(max(y, 0), 288 - G2.minTextContainerHeight)
         let height = min(max(height, G2.minTextContainerHeight), 288 - y)
-        let content = text.isEmpty ? " " : text
+        let content = G2Text.containerContent(text)
         if let existingId = sceneTextByElement[elementId] {
             if let i = textContainers.firstIndex(where: { $0.id == existingId }) {
                 let c = textContainers[i]