@mentra/bluetooth-sdk 0.1.18 → 0.1.20

package/README.md

@@ -475,7 +475,7 @@ For bare native iOS apps, use the public SwiftPM repository:
 https://github.com/Mentra-Community/mentra-bluetooth-sdk-ios.git
 ```
 
-Select version `0.1.18`, then add the `MentraBluetoothSDK` product to your app target.
+Select version `0.1.20`, then add the `MentraBluetoothSDK` product to your app target.
 
 For local SDK development, add this package folder directly in Xcode:
 

package/android/src/main/java/com/mentra/bluetoothsdk/BluetoothSdkModule.kt

@@ -1,13 +1,92 @@
+@file:Suppress("FunctionName")
+
 package com.mentra.bluetoothsdk
 
 import com.mentra.bluetoothsdk.debug.BleTraceLogger
 import com.mentra.bluetoothsdk.utils.DeviceTypes
+import expo.modules.kotlin.exception.CodedException
 import expo.modules.kotlin.functions.Coroutine
 import expo.modules.kotlin.modules.Module
 import expo.modules.kotlin.modules.ModuleDefinition
+import expo.modules.kotlin.modules.ModuleDefinitionBuilder
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.withContext
 
+// Expo has no module-level error mapper, so SDK-backed registrations translate
+// core exceptions here while keeping Expo types out of the native SDK API.
+private inline fun <T> withExpoSdkError(block: () -> T): T =
+        try {
+            block()
+        } catch (error: BluetoothSdkException) {
+            throw CodedException(error.code, error.message ?: error.code, error)
+        }
+
+private suspend inline fun <T> withExpoSdkErrorSuspend(crossinline block: suspend () -> T): T =
+        try {
+            block()
+        } catch (error: BluetoothSdkException) {
+            throw CodedException(error.code, error.message ?: error.code, error)
+        }
+
+private inline fun <reified R> ModuleDefinitionBuilder.SdkAsyncFunction(
+    name: String,
+    crossinline body: () -> R,
+) = AsyncFunction<R>(name) { withExpoSdkError { body() } }
+
+private inline fun <reified R, reified P0> ModuleDefinitionBuilder.SdkAsyncFunction(
+    name: String,
+    crossinline body: (P0) -> R,
+) = AsyncFunction<R, P0>(name) { p0 -> withExpoSdkError { body(p0) } }
+
+private inline fun <reified R, reified P0, reified P1> ModuleDefinitionBuilder.SdkAsyncFunction(
+    name: String,
+    crossinline body: (P0, P1) -> R,
+) = AsyncFunction<R, P0, P1>(name) { p0, p1 -> withExpoSdkError { body(p0, p1) } }
+
+private inline fun <reified R, reified P0, reified P1, reified P2> ModuleDefinitionBuilder.SdkAsyncFunction(
+    name: String,
+    crossinline body: (P0, P1, P2) -> R,
+) = AsyncFunction<R, P0, P1, P2>(name) { p0, p1, p2 -> withExpoSdkError { body(p0, p1, p2) } }
+
+private inline fun <reified R, reified P0, reified P1, reified P2, reified P3>
+    ModuleDefinitionBuilder.SdkAsyncFunction(
+        name: String,
+        crossinline body: (P0, P1, P2, P3) -> R,
+    ) = AsyncFunction<R, P0, P1, P2, P3>(name) { p0, p1, p2, p3 ->
+        withExpoSdkError { body(p0, p1, p2, p3) }
+    }
+
+private inline fun <
+    reified R,
+    reified P0,
+    reified P1,
+    reified P2,
+    reified P3,
+    reified P4,
+    reified P5,
+    reified P6,
+> ModuleDefinitionBuilder.SdkAsyncFunction(
+    name: String,
+    crossinline body: (P0, P1, P2, P3, P4, P5, P6) -> R,
+) = AsyncFunction<R, P0, P1, P2, P3, P4, P5, P6>(name) { p0, p1, p2, p3, p4, p5, p6 ->
+    withExpoSdkError { body(p0, p1, p2, p3, p4, p5, p6) }
+}
+
+private inline fun <reified R> ModuleDefinitionBuilder.SdkFunction(
+    name: String,
+    crossinline body: () -> R,
+) = Function<R>(name) { withExpoSdkError { body() } }
+
+private inline fun <reified R, reified P0> ModuleDefinitionBuilder.SdkFunction(
+    name: String,
+    crossinline body: (P0) -> R,
+) = Function<R, P0>(name) { p0 -> withExpoSdkError { body(p0) } }
+
+private inline fun <reified R> ModuleDefinitionBuilder.SdkCoroutineFunction(
+    name: String,
+    crossinline body: suspend () -> R,
+) = AsyncFunction(name) Coroutine { -> withExpoSdkErrorSuspend { body() } }
+
 class BluetoothSdkModule : Module() {
     private var sdk: MentraBluetoothSdk? = null
     private var deviceManager: DeviceManager? = null
@@ -183,9 +262,10 @@ class BluetoothSdkModule : Module() {
 
     private fun requireSdk(): MentraBluetoothSdk =
             sdk
-                    ?: throw BluetoothSdkException(
+                    ?: throw CodedException(
                             "sdk_not_initialized",
                             "Bluetooth SDK is not initialized.",
+                            null,
                     )
 
     override fun definition() = ModuleDefinition {
@@ -335,11 +415,11 @@ class BluetoothSdkModule : Module() {
 
         // MARK: - Display Commands
 
-        AsyncFunction("displayEvent") { params: Map<String, Any> ->
+        SdkAsyncFunction("displayEvent") { params: Map<String, Any> ->
             sdk?.displayEvent(DisplayEventRequest(params))
         }
 
-        AsyncFunction("displayText") { text: String, x: Int?, y: Int?, size: Int? ->
+        SdkAsyncFunction("displayText") { text: String, x: Int?, y: Int?, size: Int? ->
             sdk?.displayText(
                     text = text,
                     x = x ?: 0,
@@ -348,34 +428,35 @@ class BluetoothSdkModule : Module() {
             )
         }
 
-        AsyncFunction("clearDisplay") { sdk?.clearDisplay() }
+        SdkAsyncFunction("clearDisplay") { -> sdk?.clearDisplay() }
 
         // MARK: - Connection Commands
 
-        AsyncFunction("connectDefault") { sdk?.connectDefault() }
+        SdkAsyncFunction("connectDefault") { -> sdk?.connectDefault() }
 
-        AsyncFunction("connectDefaultWithOptions") { options: Map<String, Any> ->
+        SdkAsyncFunction("connectDefaultWithOptions") { options: Map<String, Any> ->
             sdk?.connectDefault(options.toMentraConnectOptions())
         }
 
-        AsyncFunction("setDefaultDevice") { device: Map<String, Any>? ->
+        SdkAsyncFunction("setDefaultDevice") { device: Map<String, Any>? ->
             sdk?.setDefaultDevice(device.toMentraDevice())
         }
 
-        AsyncFunction("clearDefaultDevice") { sdk?.clearDefaultDevice() }
+        SdkAsyncFunction("clearDefaultDevice") { -> sdk?.clearDefaultDevice() }
 
-        AsyncFunction("connectWithOptions") { device: Map<String, Any>, options: Map<String, Any> ->
+        SdkAsyncFunction("connectWithOptions") { device: Map<String, Any>, options: Map<String, Any> ->
             sdk?.connect(
-                    device.toMentraDevice() ?: throw IllegalArgumentException("connect requires a Device with model and name."),
+                    device.toMentraDevice()
+                            ?: throw IllegalArgumentException("connect requires a Device with model and name."),
                     options.toMentraConnectOptions(),
             )
         }
 
-        AsyncFunction("connectSimulated") { sdk?.connectSimulated() }
+        SdkAsyncFunction("connectSimulated") { -> sdk?.connectSimulated() }
 
-        AsyncFunction("disconnect") { sdk?.disconnect() }
+        SdkAsyncFunction("disconnect") { -> sdk?.disconnect() }
 
-        AsyncFunction("forget") { sdk?.forget() }
+        SdkAsyncFunction("forget") { -> sdk?.forget() }
 
         AsyncFunction("connectDefaultController") { deviceManager?.connectDefaultController() }
 
@@ -383,15 +464,15 @@ class BluetoothSdkModule : Module() {
 
         AsyncFunction("forgetController") { deviceManager?.forgetController() }
 
-        AsyncFunction("startScan") { model: String ->
+        SdkAsyncFunction("startScan") { model: String ->
             sdk?.startScan(DeviceModel.fromDeviceType(model))
         }
 
-        AsyncFunction("stopScan") { sdk?.stopScan() }
+        SdkAsyncFunction("stopScan") { -> sdk?.stopScan() }
 
-        AsyncFunction("cancelConnectionAttempt") { sdk?.cancelConnectionAttempt() }
+        SdkAsyncFunction("cancelConnectionAttempt") { -> sdk?.cancelConnectionAttempt() }
 
-        AsyncFunction("showDashboard") { sdk?.showDashboard() }
+        SdkAsyncFunction("showDashboard") { -> sdk?.showDashboard() }
 
         AsyncFunction("ping") { deviceManager?.ping() }
 
@@ -409,51 +490,54 @@ class BluetoothSdkModule : Module() {
 
         // MARK: - Incident Reporting
 
-        AsyncFunction("sendIncidentId") { incidentId: String, apiBaseUrl: String? ->
+        SdkAsyncFunction("sendIncidentId") { incidentId: String, apiBaseUrl: String? ->
             sdk?.sendIncidentId(incidentId, apiBaseUrl)
         }
 
         // MARK: - WiFi Commands
 
-        AsyncFunction("requestWifiScan") { requireSdk().requestWifiScan().map { it.toMap() } }
+        SdkAsyncFunction("requestWifiScan") { -> requireSdk().requestWifiScan().map { it.toMap() } }
 
-        AsyncFunction("sendWifiCredentials") { ssid: String, password: String ->
+        SdkAsyncFunction("sendWifiCredentials") { ssid: String, password: String ->
             requireSdk().sendWifiCredentials(ssid, password).values
         }
 
-        AsyncFunction("forgetWifiNetwork") { ssid: String -> requireSdk().forgetWifiNetwork(ssid).values }
+        SdkAsyncFunction("forgetWifiNetwork") { ssid: String ->
+            requireSdk().forgetWifiNetwork(ssid).values
+        }
 
-        AsyncFunction("setHotspotState") { enabled: Boolean ->
+        SdkAsyncFunction("setHotspotState") { enabled: Boolean ->
             requireSdk().setHotspotState(enabled).values
         }
 
-        AsyncFunction("setSystemTime") { timestampMs: Double ->
+        SdkAsyncFunction("setSystemTime") { timestampMs: Double ->
             sdk?.setSystemTime(timestampMs.toLong())
         }
 
         // MARK: - Gallery Commands
 
-        AsyncFunction("setGalleryModeEnabled") { enabled: Boolean ->
+        SdkAsyncFunction("setGalleryModeEnabled") { enabled: Boolean ->
             requireSdk().setGalleryModeEnabled(enabled).values
         }
 
-        AsyncFunction("setVoiceActivityDetectionEnabled") { enabled: Boolean ->
+        SdkAsyncFunction("setVoiceActivityDetectionEnabled") { enabled: Boolean ->
             sdk?.setVoiceActivityDetectionEnabled(enabled)
         }
 
-        AsyncFunction("setPhotoCaptureDefaults") { params: Map<String, Any?> ->
+        @Suppress("DEPRECATION")
+        SdkAsyncFunction("setPhotoCaptureDefaults") { params: Map<String, Any?> ->
             requireSdk().setPhotoCaptureDefaults(params.toPhotoCaptureDefaults()).values
         }
 
-        AsyncFunction("setVideoRecordingDefaults") { width: Int, height: Int, fps: Int ->
+        SdkAsyncFunction("setVideoRecordingDefaults") { width: Int, height: Int, fps: Int ->
             requireSdk().setVideoRecordingDefaults(VideoRecordingDefaults(width, height, fps)).values
         }
 
-        AsyncFunction("setMaxVideoRecordingDuration") { minutes: Int ->
+        SdkAsyncFunction("setMaxVideoRecordingDuration") { minutes: Int ->
             requireSdk().setMaxVideoRecordingDuration(minutes).values
         }
 
-        AsyncFunction("setCameraFov") { fov: Map<String, Any> ->
+        SdkAsyncFunction("setCameraFov") { fov: Map<String, Any> ->
             val value = (fov["fov"] as? Number)?.toInt() ?: CameraFov.DEFAULT_FOV
             val roiPosition = CameraRoiPosition.fromValue(
                 (fov["roiPosition"] as? Number)?.toInt()
@@ -462,13 +546,13 @@ class BluetoothSdkModule : Module() {
             requireSdk().setCameraFov(CameraFov(value, roiPosition)).values
         }
 
-        AsyncFunction("setCameraTuningConfig") { anrOn: Boolean, gainOn: Boolean ->
+        SdkAsyncFunction("setCameraTuningConfig") { anrOn: Boolean, gainOn: Boolean ->
             requireSdk().setCameraTuningConfig(anrOn, gainOn).values
         }
 
-        AsyncFunction("queryGalleryStatus") { requireSdk().queryGalleryStatus().values }
+        SdkAsyncFunction("queryGalleryStatus") { -> requireSdk().queryGalleryStatus().values }
 
-        AsyncFunction("requestPhoto") { params: Map<String, Any?> ->
+        SdkAsyncFunction("requestPhoto") { params: Map<String, Any?> ->
             // JS may pass null for optional fields; Map<String, Any> rejects null values at the bridge.
             val sanitized =
                     params.mapNotNull { (key, value) ->
@@ -476,12 +560,12 @@ class BluetoothSdkModule : Module() {
                     }.toMap()
             val req = PhotoRequest.fromMap(sanitized)
             Bridge.log(
-                    "NATIVE: PHOTO PIPELINE [3/6] BluetoothSdk.requestPhoto requestId=${req.requestId} size=${req.size} compress=${req.compress} sound=${req.sound} exposureTimeNs=${req.exposureTimeNs} iso=${req.iso}"
+                    "NATIVE: PHOTO PIPELINE [3/6] BluetoothSdk.requestPhoto requestId=${req.requestId} size=${req.size} mode=${req.mode.value} compress=${req.compress} sound=${req.sound} exposureTimeNs=${req.exposureTimeNs} iso=${req.iso}"
             )
             requireSdk().requestPhoto(req).values
         }
 
-        AsyncFunction("warmUpCamera") { params: Map<String, Any?> ->
+        SdkAsyncFunction("warmUpCamera") { params: Map<String, Any?> ->
             val requestId = params["requestId"] as? String
             val size = PhotoSize.fromValue(params["size"] as? String)
             val exposureRaw = (params["exposureTimeNs"] as? Number)?.toDouble()
@@ -494,19 +578,19 @@ class BluetoothSdkModule : Module() {
 
         // MARK: - OTA Commands
 
-        Function("setOtaVersionUrl") { otaVersionUrl: String ->
+        SdkFunction("setOtaVersionUrl") { otaVersionUrl: String ->
             requireSdk().setOtaVersionUrl(otaVersionUrl)
         }
 
-        Function("getOtaVersionUrl") { requireSdk().getOtaVersionUrl() }
+        SdkFunction("getOtaVersionUrl") { -> requireSdk().getOtaVersionUrl() }
 
         // Runs on Dispatchers.IO, not the shared Expo AsyncFunctionQueue:
         // manifest fetches and version waits can block for several seconds.
-        AsyncFunction("checkForOtaUpdate") Coroutine { ->
+        SdkCoroutineFunction("checkForOtaUpdate") {
             withContext(Dispatchers.IO) { requireSdk().checkForOtaUpdate() }
         }
 
-        AsyncFunction("startOtaUpdate") { otaVersionUrl: String? ->
+        SdkAsyncFunction("startOtaUpdate") { otaVersionUrl: String? ->
             val sdk = requireSdk()
             if (otaVersionUrl.isNullOrBlank()) {
                 sdk.startOtaUpdate().values
@@ -515,21 +599,21 @@ class BluetoothSdkModule : Module() {
             }
         }
 
-        AsyncFunction("sendOtaQueryStatus") { requireSdk().sendOtaQueryStatus().values }
+        SdkAsyncFunction("sendOtaQueryStatus") { -> requireSdk().sendOtaQueryStatus().values }
 
         // MARK: - Version Info Commands
 
-        AsyncFunction("requestVersionInfo") { requireSdk().requestVersionInfo().toMap() }
+        SdkAsyncFunction("requestVersionInfo") { -> requireSdk().requestVersionInfo().toMap() }
 
         // MARK: - Power Control Commands
 
-        AsyncFunction("sendShutdown") { sdk?.sendShutdown() }
+        SdkAsyncFunction("sendShutdown") { -> sdk?.sendShutdown() }
 
-        AsyncFunction("sendReboot") { sdk?.sendReboot() }
+        SdkAsyncFunction("sendReboot") { -> sdk?.sendReboot() }
 
         // MARK: - Video Recording Commands
 
-        AsyncFunction("startVideoRecording") {
+        SdkAsyncFunction("startVideoRecording") {
                 requestId: String,
                 save: Boolean,
                 sound: Boolean,
@@ -553,7 +637,7 @@ class BluetoothSdkModule : Module() {
 
         // webhookUrl/authToken are supplied at stop (not start) so the token is
         // fresh when the upload runs. Empty/null webhook = keep on device.
-        AsyncFunction("stopVideoRecording") {
+        SdkAsyncFunction("stopVideoRecording") {
                 requestId: String,
                 webhookUrl: String?,
                 authToken: String? ->
@@ -562,23 +646,23 @@ class BluetoothSdkModule : Module() {
 
         // MARK: - Stream Commands
 
-        AsyncFunction("startStream") { params: Map<String, Any> ->
+        SdkAsyncFunction("startStream") { params: Map<String, Any> ->
             requireSdk().startStream(StreamRequest.fromMap(params)).values
         }
 
-        AsyncFunction("startExternallyManagedStream") { params: Map<String, Any> ->
+        SdkAsyncFunction("startExternallyManagedStream") { params: Map<String, Any> ->
             requireSdk().startExternallyManagedStream(StreamRequest.fromMap(params)).values
         }
 
-        AsyncFunction("stopStream") { requireSdk().stopStream().values }
+        SdkAsyncFunction("stopStream") { -> requireSdk().stopStream().values }
 
-        AsyncFunction("sendExternallyManagedStreamKeepAlive") { params: Map<String, Any> ->
+        SdkAsyncFunction("sendExternallyManagedStreamKeepAlive") { params: Map<String, Any> ->
             sdk?.sendExternallyManagedStreamKeepAlive(StreamKeepAliveRequest.fromMap(params))
         }
 
         // MARK: - Microphone Commands
 
-        AsyncFunction("setMicState") {
+        SdkAsyncFunction("setMicState") {
                 enabled: Boolean,
                 useGlassesMic: Boolean?,
                 sendTranscript: Boolean?,
@@ -600,7 +684,7 @@ class BluetoothSdkModule : Module() {
 
         // MARK: - Audio Playback Monitoring
 
-        AsyncFunction("setOwnAppAudioPlaying") { playing: Boolean ->
+        SdkAsyncFunction("setOwnAppAudioPlaying") { playing: Boolean ->
             sdk?.setOwnAppAudioPlaying(playing)
         }
 
@@ -619,7 +703,7 @@ class BluetoothSdkModule : Module() {
 
         // MARK: - RGB LED Control
 
-        AsyncFunction("rgbLedControl") {
+        SdkAsyncFunction("rgbLedControl") {
                 requestId: String,
                 packageName: String?,
                 action: String,

package/android/src/main/java/com/mentra/bluetoothsdk/DeviceManager.kt

@@ -16,6 +16,8 @@ import com.mentra.bluetoothsdk.services.ForegroundService
 import com.mentra.bluetoothsdk.services.PhoneMic
 import com.mentra.bluetoothsdk.sgcs.G1
 import com.mentra.bluetoothsdk.sgcs.G2
+import com.mentra.bluetoothsdk.sgcs.SceneElement
+import com.mentra.bluetoothsdk.sgcs.SceneFrame
 import com.mentra.bluetoothsdk.sgcs.Mach1
 import com.mentra.bluetoothsdk.sgcs.MentraLive
 import com.mentra.bluetoothsdk.sgcs.MentraNex
@@ -144,10 +146,6 @@ class DeviceManager {
         get() = DeviceStore.store.get("bluetooth", "bypass_vad") as? Boolean ?: false
         set(value) = DeviceStore.apply("bluetooth", "bypass_vad", value)
 
-    private var offlineCaptionsRunning: Boolean
-        get() = DeviceStore.store.get("bluetooth", "offline_captions_running") as? Boolean ?: false
-        set(value) = DeviceStore.apply("bluetooth", "offline_captions_running", value)
-
     private var localSttFallbackActive: Boolean
         get() = DeviceStore.store.get("bluetooth", "local_stt_fallback_active") as? Boolean ?: false
         set(value) = DeviceStore.apply("bluetooth", "local_stt_fallback_active", value)
@@ -660,6 +658,13 @@ class DeviceManager {
         var borderWidth: Int? = null,
         var borderRadius: Int? = null
     )
+
+    // Scene slots — one whole SceneFrame per view (main/dashboard), parallel to
+    // viewStates. When a slot holds a scene, viewStates carries a "scene"
+    // sentinel so sendCurrentState routes here. Holding the WHOLE frame keeps
+    // native re-dispatch coherent (dashboard exit re-applies a complete scene,
+    // not whatever element happened to arrive last).
+    private val sceneStates = arrayOfNulls<SceneFrame>(2)
     // MARK: - End Unique
 
     // MARK: - Voice Data Handling
@@ -740,7 +745,7 @@ class DeviceManager {
         // class to fire `vad_status` (a separate signal the cloud SDK
         // surfaces as `session.audio.isSpeaking`).
         handleSendingPcm(pcmData)
-        if (shouldSendTranscript || offlineCaptionsRunning || localSttFallbackActive) {
+        if (shouldSendTranscript || localSttFallbackActive) {
             if (ensureTranscriberInitialized()) {
                 transcriber?.acceptAudio(pcmData)
             }
@@ -877,16 +882,8 @@ class DeviceManager {
         }
 
         // executor.execute {
-        var currentViewState: ViewState
-        if (hUp) {
-            currentViewState = viewStates[1]
-        } else {
-            currentViewState = viewStates[0]
-        }
-
-        if (hUp && !contextualDashboard) {
-            currentViewState = viewStates[0]
-        }
+        val currentStateIndex = if (hUp && contextualDashboard) 1 else 0
+        val currentViewState: ViewState = viewStates[currentStateIndex]
 
         if (sgc?.type?.contains(DeviceTypes.SIMULATED) == true) {
             // dont send the event to glasses that aren't there:
@@ -944,6 +941,10 @@ class DeviceManager {
                 )
             }
 
+            "scene" -> {
+                sceneStates[currentStateIndex]?.let { sgc?.applySceneFrame(it) }
+            }
+
             "clear_view" -> sgc?.clearDisplay()
             else -> Bridge.log("MAN: UNHANDLED LAYOUT_TYPE ${currentViewState.layoutType}")
         }
@@ -1362,9 +1363,31 @@ class DeviceManager {
         val isDashboard = view == "dashboard"
         val stateIndex = if (isDashboard) 1 else 0
 
+        // Scene frames (display.render() pipeline) take their own path: the
+        // whole frame is the unit, not a layout, and the host's per-element
+        // annotations make redundant frames self-deduping (all-"unchanged"
+        // frames no-op in the SGC base handler).
+        @Suppress("UNCHECKED_CAST") val sceneMap = event["scene"] as? Map<String, Any>
+        if (sceneMap != null) {
+            handleSceneEvent(stateIndex, sceneMap)
+            return
+        }
+
         @Suppress("UNCHECKED_CAST") val layout = event["layout"] as? Map<String, Any> ?: return
 
         val layoutType = layout["layoutType"] as? String
+
+        // Scene→legacy handoff: a legacy layout is about to draw over a scene
+        // (e.g. a cloud app taking the view from a miniapp). Sweep the scene's
+        // elements first so they don't linger under the new content; clear_view
+        // wipes everything anyway.
+        sceneStates[stateIndex]?.let { prevFrame ->
+            sceneStates[stateIndex] = null
+            if (layoutType != "clear_view") {
+                sgc?.clearSceneElements(prevFrame.elements.map { it.id })
+            }
+        }
+
         val text = parsePlaceholders(layout.getString("text", " "))
         val topText = parsePlaceholders(layout.getString("topText", " "))
         val bottomText = parsePlaceholders(layout.getString("bottomText", " "))
@@ -1414,6 +1437,86 @@ class DeviceManager {
         }
     }
 
+    /** Parse + store a scene frame, then dispatch it if its view is visible. */
+    private fun handleSceneEvent(stateIndex: Int, sceneMap: Map<String, Any>) {
+        var frame = parseSceneFrame(sceneMap) ?: return
+        val prevFrame = sceneStates[stateIndex]
+
+        if (prevFrame == null) {
+            // Legacy→scene handoff: stale legacy content (e.g. a cloud app's
+            // text wall) must not linger under the scene's elements.
+            // clearDisplay is the per-device "wipe what's there" (blank-in-place
+            // on G2 — no page rebuild).
+            val prevLegacyType = viewStates[stateIndex].layoutType
+            if (prevLegacyType.isNotEmpty() && prevLegacyType != "clear_view" && prevLegacyType != "scene") {
+                sgc?.clearDisplay()
+            }
+        } else if (prevFrame.appId != frame.appId) {
+            // Cross-app switch: the host's diff baseline is per-app, so the new
+            // app's annotations don't know the old app's elements are on the
+            // glasses. Sweep the old app's elements (SGC registries still map
+            // them), then paint the new frame from scratch. In practice the
+            // boot message interposes between apps, so this isn't visible as a
+            // blank.
+            sgc?.clearSceneElements(prevFrame.elements.map { it.id })
+            frame = frame.copy(replay = true, elements = frame.elements.map { it.copy(change = "created") })
+        }
+
+        // Store the REDISPATCH form: any later sendCurrentState (dashboard
+        // exit, head-up return) must repaint the whole frame — the original
+        // annotations are only valid for the first dispatch right now.
+        sceneStates[stateIndex] =
+            frame.copy(replay = true, elements = frame.elements.map { it.copy(change = "created") })
+        viewStates[stateIndex] = ViewState(" ", " ", " ", "scene", " ", null, null)
+
+        val hUp = headUp && contextualDashboard
+        if ((stateIndex == 0 && !hUp) || (stateIndex == 1 && hUp)) {
+            dispatchSceneFrame(frame)
+        }
+    }
+
+    /** Guarded scene dispatch — mirrors sendCurrentState's send conditions. */
+    private fun dispatchSceneFrame(frame: SceneFrame) {
+        if (screenDisabled) return
+        if (sgc?.type?.contains(DeviceTypes.SIMULATED) == true) return
+        if (sgc?.fullyBooted != true) {
+            Bridge.log("MAN: dispatchSceneFrame(): sgc not ready")
+            return
+        }
+        sgc?.applySceneFrame(frame)
+    }
+
+    @Suppress("UNCHECKED_CAST")
+    private fun parseSceneFrame(sceneMap: Map<String, Any>): SceneFrame? {
+        val elementsRaw = sceneMap["elements"] as? List<Map<String, Any>> ?: return null
+        val elements =
+            elementsRaw.mapNotNull { el ->
+                val box = el["box"] as? Map<String, Any> ?: return@mapNotNull null
+                val style = el["style"] as? Map<String, Any>
+                SceneElement(
+                    id = el["id"] as? String ?: return@mapNotNull null,
+                    type = el["type"] as? String ?: return@mapNotNull null,
+                    x = (box["x"] as? Number)?.toInt() ?: 0,
+                    y = (box["y"] as? Number)?.toInt() ?: 0,
+                    w = (box["w"] as? Number)?.toInt() ?: 0,
+                    h = (box["h"] as? Number)?.toInt() ?: 0,
+                    text = (el["text"] as? String)?.let { parsePlaceholders(it) },
+                    data = el["data"] as? String,
+                    border = (style?.get("border") as? Number)?.toInt() ?: 0,
+                    radius = (style?.get("radius") as? Number)?.toInt() ?: 0,
+                    change = el["change"] as? String ?: "created",
+                    contentHash = el["contentHash"] as? String ?: ""
+                )
+            }
+        return SceneFrame(
+            appId = sceneMap["appId"] as? String ?: "",
+            epoch = (sceneMap["sceneEpoch"] as? Number)?.toInt() ?: 0,
+            replay = sceneMap["replay"] as? Boolean ?: false,
+            elements = elements,
+            removed = (sceneMap["removed"] as? List<*>)?.filterIsInstance<String>() ?: emptyList()
+        )
+    }
+
     fun showDashboard() {
         sgc?.showDashboard()
     }
@@ -1669,7 +1772,7 @@ class DeviceManager {
 
     fun setMicState() {
         val willSendPcm = shouldSendPcm || shouldSendLc3
-        val willSendTranscript = shouldSendTranscript || offlineCaptionsRunning || localSttFallbackActive
+        val willSendTranscript = shouldSendTranscript || localSttFallbackActive
         val nextEnabled = willSendPcm || willSendTranscript
         // Tell VAD when the mic is shutting down so it doesn't get stuck in
         // a stale "speaking" state and keep emitting vad_status=true after
@@ -1697,7 +1800,7 @@ class DeviceManager {
                 iso = manualIso,
             )
         Bridge.log(
-            "MAN: PHOTO PIPELINE [4/6] DeviceManager.requestPhoto requestId=${routed.requestId} size=${routed.size.value} compress=${routed.compress.value} save=${routed.save} sound=${routed.sound} exposureTimeNs=$exposureNs iso=${manualIso ?: "auto"} aeDivisor=${routed.aeExposureDivisor} isoCap=${routed.isoCap} sgc=${sgc?.javaClass?.simpleName ?: "null"}"
+            "MAN: PHOTO PIPELINE [4/6] DeviceManager.requestPhoto requestId=${routed.requestId} size=${routed.size.value} mode=${routed.mode.value} compress=${routed.compress.value} save=${routed.save} sound=${routed.sound} exposureTimeNs=$exposureNs iso=${manualIso ?: "auto"} aeDivisor=${routed.aeExposureDivisor} isoCap=${routed.isoCap} sgc=${sgc?.javaClass?.simpleName ?: "null"}"
         )
         val activeSgc = sgc
         if (activeSgc == null) {

package/android/src/main/java/com/mentra/bluetoothsdk/DeviceStore.kt

@@ -292,6 +292,11 @@ object DeviceStore {
             "bluetooth" to "camera_fov" -> {
                 DeviceManager.getInstance().sgc?.sendCameraFovSetting()
             }
+            "bluetooth" to "button_video_settings" -> {
+                DeviceManager.getInstance().sgc?.sendButtonVideoRecordingSettings()
+            }
+            // Legacy scalar keys remain supported for older hosts. New code should write the
+            // canonical button_video_settings object so width/height/fps update atomically.
             "bluetooth" to "button_video_width",
             "bluetooth" to "button_video_height",
             "bluetooth" to "button_video_fps" -> {
@@ -303,12 +308,6 @@ object DeviceStore {
                     DeviceManager.getInstance().setMicState()
                 }
             }
-            "bluetooth" to "offline_captions_running" -> {
-                (value as? Boolean)?.let { running ->
-                    Bridge.log("DeviceStore: offline_captions_running changed to $running")
-                    DeviceManager.getInstance().setMicState()
-                }
-            }
             "bluetooth" to "local_stt_fallback_active" -> {
                 (value as? Boolean)?.let { active ->
                     Bridge.log("DeviceStore: local_stt_fallback_active changed to $active")